skillhub/web/scripts/analytics-manifest.mjs
小妍儿 ✨ 6952629eed
feat(web): add passive semantic analytics attributes across frontend workflows (#1010)
* feat(web): expose passive semantic analytics attributes

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(web): omit disabled non-native analytics intents

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(web): keep docs integration test outside production build inputs

Move the collector example test alongside existing root-level web tests so the web-only Docker context does not require repository documentation. Preserve all assertions and default Vitest discovery; document the boundary.

Verified 1217 tests, focused 12 tests, typecheck, lint, build and a fresh web-only build without repository docs. Original snapshot reproduced TS2307. Independent review passed. Full local image build was blocked by an uncached pnpm download with network disabled; remote image CI remains authoritative.

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* docs(analytics): configure intent rules and add a manual Umami demo

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(analytics): accept product IDs and preserve concurrent intents

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(analytics): guard consent at Umami dispatch boundary

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(analytics): snapshot validated Umami payload primitives

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* docs(analytics): define configurable opt-in integration

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>

* chore(analytics): refresh manifest line numbers after main merge

The merge of latest main shifted source lines in router and pages. Only
line numbers change; routes, IDs and sites are identical.

Refs #989

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* fix(analytics): preserve release Web defaults in optional edge

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* docs(analytics): add Chinese guide and split delivery scope

Refs #989

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

* docs(analytics): keep upstream override and bypass module cache in guide

Export the upstream override so later compose commands keep it, and
tell operators to bypass the immutable module cache when re-checking
an edited local entry.

Refs #989

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>

---------

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Co-authored-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-29 14:56:58 +08:00

142 lines
9 KiB
JavaScript

// Development-only source inventory. Never imported by the application bundle.
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import ts from 'typescript'
const root = fileURLToPath(new URL('../../', import.meta.url))
const destination = path.join(root, 'docs/frontend-analytics-manifest.json')
const sourceRoot = path.join(root, 'web/src')
const markerProp = /^(data-analytics-id|analyticsId|[a-z]+AnalyticsId)$/
const idPattern = /^[a-z]+(?:\.[a-z]+){2,}$/
const passthrough = new Set(['analyticsId', 'confirmAnalyticsId', 'cancelAnalyticsId', 'closeAnalyticsId', 'copyAnalyticsId', 'downloadAnalyticsId', 'skillhubAnalyticsId', 'clawhubAnalyticsId', 'folderAnalyticsId', 'pickerAnalyticsId'])
const navigationFiles = new Set(['web/src/app/layout.tsx', 'web/src/pages/dashboard.tsx', 'web/src/features/namespace/namespace-management-nav.tsx'])
function walk(dir) {
return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en')).flatMap(entry => entry.isDirectory() ? walk(path.join(dir, entry.name)) : [path.join(dir, entry.name)])
}
function parse(file) {
return ts.createSourceFile(file, fs.readFileSync(path.join(root, file), 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
}
function visit(node, fn) {
fn(node)
ts.forEachChild(node, child => visit(child, fn))
}
function line(sf, node) {
return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1
}
function properties(node, sf) {
return Object.fromEntries(node.properties.filter(ts.isPropertyAssignment).map(prop => [prop.name.getText(sf), prop.initializer]))
}
function values(node, sf, file) {
if (!node) throw new Error(`Missing marker value in ${file}`)
if (ts.isStringLiteral(node)) {
if (!idPattern.test(node.text)) throw new Error(`Nonsemantic marker in ${file}:${line(sf, node)}`)
return { ids: [node.text] }
}
if (ts.isJsxExpression(node) || ts.isParenthesizedExpression(node)) return values(node.expression, sf, file)
if (ts.isConditionalExpression(node)) {
const yes = values(node.whenTrue, sf, file)
const no = values(node.whenFalse, sf, file)
return { ids: [...new Set([...(yes.ids ?? []), ...(no.ids ?? [])])].sort(), conditional: true, ...(yes.forward || no.forward ? { forward: yes.forward ?? no.forward } : {}) }
}
if (ts.isIdentifier(node) && node.text === 'undefined') return { ids: [] }
if (ts.isIdentifier(node) && passthrough.has(node.text)) return { forward: node.text }
if (ts.isPropertyAccessExpression(node) && node.name.text === 'analyticsId' && navigationFiles.has(file) && ['item', 'card', 'tab'].includes(node.expression.getText(sf))) return { forward: node.getText(sf) }
throw new Error(`Dynamic analytics value rejected in ${file}:${line(sf, node)}: ${node.getText(sf)}`)
}
function eventFor(tag, prop, attrs, ids) {
if (ids.includes('skill.detail.render')) return 'structural'
if (tag === 'SelectItem') return 'radix-item-intent'
if (tag === 'SelectTrigger') return 'click+keydown-intent'
if (tag === 'form' || tag === 'SearchBar') return 'submit'
if (tag === 'UploadZone') return prop === 'pickerAnalyticsId' ? 'click' : prop === 'folderAnalyticsId' ? 'change' : 'click+keydown+change+drop'
if (tag === 'SelectFilter') return 'change'
if (tag === 'FileTree' || tag === 'FileTreeNodeComponent') return 'click'
if (tag === 'SkillCard' || tag === 'ResourceCard' || (attrs.has('onKeyDown') && attrs.has('onClick') && tag !== 'TabsTrigger')) return 'click+keydown-enter-space'
if (tag === 'input' || tag === 'Input') return attrs.has('onKeyDown') ? 'keydown-enter' : 'change'
if (tag === 'select') return 'change'
if (tag === 'option') return 'change-selected-option'
if (ids.includes('skill.avatar.crop.adjust')) return 'pointerup+keydown-intent'
if (tag === 'div' && attrs.has('data-analytics-event')) return ids.includes('skill.avatar.file.drop') ? 'drop' : 'click+keydown+drop'
return 'click'
}
export function buildManifest() {
const sites = []
const definitions = []
for (const full of walk(sourceRoot).filter(file => file.endsWith('.tsx') && !/\.(test|spec)\.tsx$/.test(file))) {
const file = path.relative(root, full).split(path.sep).join('/')
const sf = parse(file)
visit(sf, node => {
if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
const attrs = node.attributes.properties.filter(ts.isJsxAttribute)
const names = new Set(attrs.map(attr => attr.name.getText(sf)))
for (const attr of attrs.filter(attr => markerProp.test(attr.name.getText(sf)))) {
const result = values(attr.initializer, sf, file)
const tag = node.tagName.getText(sf)
sites.push({ file, line: line(sf, node), host: tag, prop: attr.name.getText(sf), event: eventFor(tag, attr.name.getText(sf), names, result.ids ?? []), ...result })
}
}
if (ts.isPropertyAssignment(node) && node.name.getText(sf) === 'analyticsId') {
if (!navigationFiles.has(file)) throw new Error(`Unreviewed navigation metadata in ${file}`)
definitions.push({ file, line: line(sf, node), ...values(node.initializer, sf, file) })
}
})
}
const routeFile = 'web/src/app/router.tsx'
const sf = parse(routeFile)
const bindings = new Map()
const routes = []
let registered = []
visit(sf, node => {
if (!ts.isVariableDeclaration(node) || node.parent?.parent?.parent !== sf || !node.initializer || !ts.isCallExpression(node.initializer)) return
const call = node.initializer
const callee = call.expression.getText(sf)
if (['createLazyRouteComponent', 'createRoleProtectedRouteComponent'].includes(callee)) {
let modulePath
visit(call.arguments[0], child => {
if (ts.isCallExpression(child) && child.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteral(child.arguments[0])) modulePath = child.arguments[0].text
})
const exported = call.arguments[1]
if (!modulePath?.startsWith('@/') || !exported || !ts.isStringLiteral(exported)) throw new Error('Unresolved lazy route')
const file = 'web/src/' + modulePath.slice(2) + '.tsx'
const page = parse(file)
let implementation
visit(page, child => {
if ((ts.isFunctionDeclaration(child) || ts.isVariableDeclaration(child)) && child.name?.getText(page) === exported.text) implementation = { file, line: line(page, child), export: exported.text }
})
if (!implementation) throw new Error(`Missing route implementation: ${file} ${exported.text}`)
bindings.set(node.name.getText(sf), { implementation, roleProtected: callee === 'createRoleProtectedRouteComponent' })
}
if (callee === 'createRoute') {
const props = properties(call.arguments[0], sf)
if (!ts.isStringLiteral(props.path)) throw new Error('Nonliteral route path')
const component = props.component?.getText(sf)
const binding = bindings.get(component)
routes.push({ name: node.name.getText(sf), path: props.path.text, declaration: { file: routeFile, line: line(sf, node) }, implementation: binding?.implementation ?? null, guarded: !!props.beforeLoad, roleProtected: binding?.roleProtected ?? false })
}
if (callee === 'rootRoute.addChildren') registered = call.arguments[0].elements.map(element => element.getText(sf))
})
if (routes.length !== registered.length || routes.some(route => !registered.includes(route.name)) || new Set(registered).size !== registered.length) throw new Error('Route declaration/registration drift')
const ids = new Set([...sites, ...definitions].flatMap(site => site.ids ?? []))
return {
schema: 1,
description: 'Source declarations, not runtime DOM counts, pageviews, successful outcomes or a closed runtime enum. Forwarding sites require explicit callers. See frontend-analytics.md for gaps and event policy.',
counts: { routes: routes.length, uniqueIds: ids.size, literalJsxSites: sites.filter(site => site.ids?.length).length, literalJsxValues: sites.reduce((count, site) => count + (site.ids?.length ?? 0), 0), navigationDefinitions: definitions.length, forwardingSites: sites.filter(site => site.forward).length },
routes,
definitions,
sites,
}
}
function serialize(manifest) {
// Compact one-record-per-line projection; source and event stay reviewable together.
return '{\n "schema": 1,\n "description": ' + JSON.stringify(manifest.description) + ',\n "counts": ' + JSON.stringify(manifest.counts) + ',\n' + ['routes', 'definitions', 'sites'].map(key => ' "' + key + '": [\n' + manifest[key].map(row => ' ' + JSON.stringify(row)).join(',\n') + '\n ]').join(',\n') + '\n}\n'
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const manifest = buildManifest()
const text = serialize(manifest)
if (process.argv.includes('--write')) fs.writeFileSync(destination, text)
else if (fs.readFileSync(destination, 'utf8') !== text) throw new Error('Analytics manifest drift. Review source, then run node web/scripts/analytics-manifest.mjs --write from the repository root.')
console.log(JSON.stringify(manifest.counts))
}