wehub-resource-sync
1309 lines
48 KiB
JavaScript
1309 lines
48 KiB
JavaScript
#!/usr/bin/env node
|
|
/**
|
|
* Static consistency checker between navigation declaration and source code triggers.
|
|
*
|
|
* What it detects (v0.1):
|
|
* 1) Used transitionId in code but missing in navigation.declaration.ts transitions[].
|
|
* 2) Usage occurs inside a page component whose route path is NOT included in transition.from (path match only).
|
|
*
|
|
* Notes:
|
|
* - This is a best-effort static checker. It does not execute code.
|
|
* - For "from" checks, we only validate route path presence (string '/x' or object {path:'/x', ...}).
|
|
* We do NOT attempt to prove search constraints correctness (e.g. tab='shelf' vs '*').
|
|
*/
|
|
import fs from 'fs';
|
|
import path from 'path';
|
|
import process from 'process';
|
|
import ts from 'typescript';
|
|
|
|
const WORKSPACE_ROOT = process.cwd();
|
|
|
|
function usage() {
|
|
console.log(`
|
|
Usage:
|
|
node scripts/check_navigation_declaration_consistency.mjs WechatReading
|
|
|
|
Options:
|
|
--json Output JSON only
|
|
--actions Also validate Actions (data-action) consistency
|
|
--actions-only Only run Actions checks
|
|
--fail-on-warn Exit non-zero on warnings too
|
|
`);
|
|
}
|
|
|
|
function parseArgs(argv) {
|
|
const args = argv.slice(2);
|
|
const appName = args.find(a => !a.startsWith('--'));
|
|
const jsonOnly = args.includes('--json');
|
|
const failOnWarn = args.includes('--fail-on-warn');
|
|
const actions = args.includes('--actions');
|
|
const actionsOnly = args.includes('--actions-only');
|
|
return { appName, jsonOnly, failOnWarn, actions, actionsOnly };
|
|
}
|
|
|
|
function readText(filePath) {
|
|
return fs.readFileSync(filePath, 'utf8');
|
|
}
|
|
|
|
function listFilesRecursive(dir, { exts, ignoreDirs }) {
|
|
const out = [];
|
|
const entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
for (const entry of entries) {
|
|
const full = path.join(dir, entry.name);
|
|
if (entry.isDirectory()) {
|
|
if (ignoreDirs.has(entry.name)) continue;
|
|
out.push(...listFilesRecursive(full, { exts, ignoreDirs }));
|
|
} else {
|
|
const ext = path.extname(entry.name);
|
|
if (exts.has(ext)) out.push(full);
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
function createSourceFile(filePath) {
|
|
const text = readText(filePath);
|
|
const ext = path.extname(filePath);
|
|
const kind = ext === '.tsx' ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
|
|
return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, kind);
|
|
}
|
|
|
|
function isObjectLiteral(node) {
|
|
return node && node.kind === ts.SyntaxKind.ObjectLiteralExpression;
|
|
}
|
|
|
|
function getProp(objLit, name) {
|
|
if (!objLit || !objLit.properties) return null;
|
|
for (const prop of objLit.properties) {
|
|
if (!ts.isPropertyAssignment(prop)) continue;
|
|
const key = prop.name;
|
|
if (ts.isIdentifier(key) && key.text === name) return prop.initializer;
|
|
if (ts.isStringLiteral(key) && key.text === name) return prop.initializer;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function getStringLiteralValue(node) {
|
|
if (!node) return null;
|
|
// Unwrap common TS wrappers like `'x' as TransitionId` or `('x')`
|
|
let cur = node;
|
|
while (cur) {
|
|
if (ts.isAsExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isSatisfiesExpression && ts.isSatisfiesExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isParenthesizedExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
break;
|
|
}
|
|
if (ts.isStringLiteral(cur) || ts.isNoSubstitutionTemplateLiteral(cur)) return cur.text;
|
|
return null;
|
|
}
|
|
|
|
function extractNavDeclaration(navDeclPath) {
|
|
const sf = createSourceFile(navDeclPath);
|
|
|
|
/** @type {null | ts.ObjectLiteralExpression} */
|
|
let declObj = null;
|
|
|
|
function unwrapExpr(expr) {
|
|
let cur = expr;
|
|
// Unwrap common TS wrappers: `as const`, `satisfies`, parentheses
|
|
// - AsExpression: `{...} as const`
|
|
// - SatisfiesExpression: `({...}) satisfies T`
|
|
// - ParenthesizedExpression: `({...})`
|
|
while (cur) {
|
|
if (ts.isAsExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isSatisfiesExpression && ts.isSatisfiesExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isParenthesizedExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
break;
|
|
}
|
|
return cur;
|
|
}
|
|
|
|
function visit(node) {
|
|
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'NAVIGATION_DECLARATION') {
|
|
const init = node.initializer ? unwrapExpr(node.initializer) : null;
|
|
if (init && ts.isObjectLiteralExpression(init)) declObj = init;
|
|
}
|
|
ts.forEachChild(node, visit);
|
|
}
|
|
visit(sf);
|
|
|
|
if (!declObj) {
|
|
throw new Error(`Cannot find NAVIGATION_DECLARATION object in ${navDeclPath}`);
|
|
}
|
|
|
|
const routesInit = getProp(declObj, 'routes');
|
|
const transitionsInit = getProp(declObj, 'transitions');
|
|
|
|
/** @type {Array<{path:string, component:string, queryParamKeys:Set<string>, uiStates:Array<{id:string, discreteKeys:Set<string>}> , uiStateDiscreteKeySets:Set<string>[], hasBaseDiscreteState:boolean}>} */
|
|
const routes = [];
|
|
/** @type {Map<string, {id:string, fromPaths:Set<string>, fromEntries:Array<{path:string, search?:Record<string,string>}>, uiPlacement:null|string, uiGesture:null|string, rawFrom:any}>} */
|
|
const transitions = new Map();
|
|
|
|
if (routesInit && ts.isArrayLiteralExpression(routesInit)) {
|
|
for (const el of routesInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(el)) continue;
|
|
const p = getStringLiteralValue(getProp(el, 'path'));
|
|
const c = getStringLiteralValue(getProp(el, 'component'));
|
|
if (!p || !c) continue;
|
|
|
|
const queryParamKeys = new Set();
|
|
const queryParamsInit = getProp(el, 'queryParams');
|
|
if (queryParamsInit && ts.isObjectLiteralExpression(queryParamsInit)) {
|
|
for (const prop of queryParamsInit.properties) {
|
|
if (!ts.isPropertyAssignment(prop)) continue;
|
|
const key =
|
|
ts.isIdentifier(prop.name) ? prop.name.text :
|
|
ts.isStringLiteral(prop.name) ? prop.name.text :
|
|
null;
|
|
if (!key) continue;
|
|
queryParamKeys.add(key);
|
|
}
|
|
}
|
|
|
|
const uiStateDiscreteKeySets = [];
|
|
const uiStates = [];
|
|
let hasBaseDiscreteState = false;
|
|
const uiStatesInit = getProp(el, 'uiStates');
|
|
if (uiStatesInit && ts.isArrayLiteralExpression(uiStatesInit)) {
|
|
for (const stateEl of uiStatesInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(stateEl)) continue;
|
|
const uiStateId = getStringLiteralValue(getProp(stateEl, 'id')) ?? '<unknown>';
|
|
const searchInit = getProp(stateEl, 'search');
|
|
const searchObj = searchInit && ts.isObjectLiteralExpression(searchInit) ? searchInit : null;
|
|
const discreteKeys = new Set();
|
|
if (searchObj) {
|
|
for (const prop of searchObj.properties) {
|
|
if (!ts.isPropertyAssignment(prop)) continue;
|
|
const key =
|
|
ts.isIdentifier(prop.name) ? prop.name.text :
|
|
ts.isStringLiteral(prop.name) ? prop.name.text :
|
|
null;
|
|
if (!key) continue;
|
|
// queryParams are dynamic; don't count them as discrete keys
|
|
if (queryParamKeys.has(key)) continue;
|
|
discreteKeys.add(key);
|
|
}
|
|
}
|
|
uiStateDiscreteKeySets.push(discreteKeys);
|
|
uiStates.push({ id: uiStateId, discreteKeys });
|
|
if (discreteKeys.size === 0) hasBaseDiscreteState = true;
|
|
}
|
|
}
|
|
|
|
routes.push({
|
|
path: p,
|
|
component: c,
|
|
queryParamKeys,
|
|
uiStates,
|
|
uiStateDiscreteKeySets,
|
|
hasBaseDiscreteState,
|
|
});
|
|
}
|
|
}
|
|
|
|
if (transitionsInit && ts.isArrayLiteralExpression(transitionsInit)) {
|
|
for (const el of transitionsInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(el)) continue;
|
|
const id = getStringLiteralValue(getProp(el, 'id'));
|
|
if (!id) continue;
|
|
|
|
const fromInit = getProp(el, 'from');
|
|
const fromPaths = new Set();
|
|
const fromEntries = [];
|
|
const uiInit = getProp(el, 'ui');
|
|
let uiPlacement = null;
|
|
let uiGesture = null;
|
|
if (uiInit && ts.isObjectLiteralExpression(uiInit)) {
|
|
uiPlacement = getStringLiteralValue(getProp(uiInit, 'placement'));
|
|
uiGesture = getStringLiteralValue(getProp(uiInit, 'gesture'));
|
|
}
|
|
|
|
const parseSearchObj = (searchInit) => {
|
|
if (!searchInit || !ts.isObjectLiteralExpression(searchInit)) return undefined;
|
|
const out = {};
|
|
for (const prop of searchInit.properties) {
|
|
if (!ts.isPropertyAssignment(prop)) continue;
|
|
const key =
|
|
ts.isIdentifier(prop.name) ? prop.name.text :
|
|
ts.isStringLiteral(prop.name) ? prop.name.text :
|
|
null;
|
|
if (!key) continue;
|
|
const val = getStringLiteralValue(prop.initializer);
|
|
if (val !== null) out[key] = val;
|
|
}
|
|
return out;
|
|
};
|
|
|
|
const addFromNode = node => {
|
|
const str = getStringLiteralValue(node);
|
|
if (str) {
|
|
fromPaths.add(str);
|
|
fromEntries.push({ path: str });
|
|
return;
|
|
}
|
|
if (node && ts.isObjectLiteralExpression(node)) {
|
|
const p = getStringLiteralValue(getProp(node, 'path'));
|
|
if (p) {
|
|
fromPaths.add(p);
|
|
const search = parseSearchObj(getProp(node, 'search'));
|
|
fromEntries.push({ path: p, ...(search ? { search } : {}) });
|
|
}
|
|
}
|
|
};
|
|
|
|
if (fromInit) {
|
|
if (ts.isArrayLiteralExpression(fromInit)) {
|
|
for (const item of fromInit.elements) addFromNode(item);
|
|
} else {
|
|
addFromNode(fromInit);
|
|
}
|
|
}
|
|
|
|
transitions.set(id, {
|
|
id,
|
|
fromPaths,
|
|
fromEntries,
|
|
uiPlacement,
|
|
uiGesture,
|
|
rawFrom: fromInit ? sf.text.slice(fromInit.pos, fromInit.end) : null,
|
|
});
|
|
}
|
|
}
|
|
|
|
const componentToPaths = new Map();
|
|
for (const r of routes) {
|
|
const list = componentToPaths.get(r.component) ?? [];
|
|
list.push(r.path);
|
|
componentToPaths.set(r.component, list);
|
|
}
|
|
|
|
return { routes, transitions, componentToPaths };
|
|
}
|
|
|
|
function extractTransitionUsages(appDir, declaredTransitionIdSet) {
|
|
const ignoreDirs = new Set(['node_modules', 'dist', 'build', 'data', 'context']);
|
|
const exts = new Set(['.ts', '.tsx']);
|
|
const files = listFilesRecursive(appDir, { exts, ignoreDirs });
|
|
|
|
/** @type {Array<{id:string, kind:string, file:string, line:number, col:number, componentGuess?:string, inferredSearch?:Record<string,string>}>} */
|
|
const usages = [];
|
|
|
|
for (const filePath of files) {
|
|
// Never treat the declaration itself as a "usage" source.
|
|
if (filePath.endsWith(`${path.sep}navigation.declaration.ts`)) continue;
|
|
|
|
const sf = createSourceFile(filePath);
|
|
const rel = path.relative(WORKSPACE_ROOT, filePath);
|
|
const base = path.basename(filePath).replace(/\.(ts|tsx)$/, '');
|
|
const isPage = rel.includes(`${path.sep}pages${path.sep}`);
|
|
const componentGuess = isPage ? base : undefined;
|
|
|
|
// Heuristic: collect transition ids from object literals like:
|
|
// - `{ transition: 'tab.reading' }` (TabBar in WechatReading)
|
|
// - `{ transitionId: 'readingList.open.finished' as TransitionId }` (MyReadingPage)
|
|
// - `{ triggerId: 'tab.home' as TransitionId }` (TabBar in TencentMeeting)
|
|
// This lets us count indirect usage patterns like `bindTap(tab.transition)` in TabBar.
|
|
//
|
|
// Supported property names (common naming patterns for transition IDs):
|
|
const TRANSITION_KEYS = [
|
|
'transition', // e.g. { transition: 'tab.reading' }
|
|
'transitionId', // e.g. { transitionId: 'home.open' }
|
|
'triggerId', // e.g. { triggerId: 'tab.home' } - from useTriggerGestures
|
|
'navId', // e.g. { navId: 'page.open' }
|
|
'navigationId', // e.g. { navigationId: 'route.go' }
|
|
];
|
|
const fileTransitionIdPool = new Set();
|
|
const isLikelyTransitionId = (v) =>
|
|
typeof v === 'string' &&
|
|
v.includes('.') &&
|
|
!/\s/.test(v) &&
|
|
/^[A-Za-z][A-Za-z0-9_.-]*$/.test(v);
|
|
(function collectTransitionPool() {
|
|
function visitPool(node) {
|
|
if (ts.isObjectLiteralExpression(node)) {
|
|
for (const key of TRANSITION_KEYS) {
|
|
const t = getProp(node, key);
|
|
const v = getStringLiteralValue(t);
|
|
if (isLikelyTransitionId(v)) fileTransitionIdPool.add(v);
|
|
}
|
|
}
|
|
ts.forEachChild(node, visitPool);
|
|
}
|
|
visitPool(sf);
|
|
})();
|
|
|
|
function record(kind, id, node) {
|
|
const lc = sf.getLineAndCharacterOfPosition(node.getStart(sf));
|
|
const inferredSearch = inferSearchFromContext(node, sf);
|
|
usages.push({
|
|
id,
|
|
kind,
|
|
file: rel,
|
|
line: lc.line + 1,
|
|
col: lc.character + 1,
|
|
componentGuess,
|
|
inferredSearch,
|
|
});
|
|
}
|
|
|
|
function inferSearchFromContext(node, sourceFile) {
|
|
const out = {};
|
|
|
|
const addFromExpr = (expr) => {
|
|
for (const { ident, value } of extractStringEqualityConstraints(expr)) {
|
|
const key = mapIdentToSearchKey(ident);
|
|
if (!key) continue;
|
|
out[key] = value;
|
|
}
|
|
};
|
|
|
|
// Walk up a few parents to find if/ternary conditions guarding this usage.
|
|
let cur = node;
|
|
let steps = 0;
|
|
while (cur && cur.parent && steps < 10) {
|
|
const p = cur.parent;
|
|
if (ts.isIfStatement(p)) addFromExpr(p.expression);
|
|
if (ts.isConditionalExpression(p)) addFromExpr(p.condition);
|
|
if (ts.isBinaryExpression(p) || ts.isPrefixUnaryExpression(p) || ts.isParenthesizedExpression(p)) {
|
|
// no-op, covered by extract on higher-level conditions
|
|
}
|
|
cur = p;
|
|
steps++;
|
|
if (ts.isSourceFile(cur)) break;
|
|
}
|
|
|
|
return Object.keys(out).length ? out : undefined;
|
|
}
|
|
|
|
function mapIdentToSearchKey(ident) {
|
|
const s = String(ident || '').toLowerCase();
|
|
if (s.includes('tab')) return 'tab';
|
|
if (s.includes('sub')) return 'sub';
|
|
if (s.includes('category')) return 'category';
|
|
if (s.includes('modal')) return 'modal';
|
|
if (s.includes('select')) return 'select';
|
|
return null;
|
|
}
|
|
|
|
function extractStringEqualityConstraints(expr) {
|
|
/** @type {Array<{ident:string,value:string}>} */
|
|
const res = [];
|
|
|
|
const visit = (e) => {
|
|
if (!e) return;
|
|
if (ts.isParenthesizedExpression(e)) return visit(e.expression);
|
|
if (ts.isBinaryExpression(e)) {
|
|
// Handle `a === 'x'` and `'x' === a`
|
|
if (
|
|
e.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
|
|
e.operatorToken.kind === ts.SyntaxKind.EqualsEqualsToken
|
|
) {
|
|
const leftIdent = ts.isIdentifier(e.left) ? e.left.text : null;
|
|
const rightIdent = ts.isIdentifier(e.right) ? e.right.text : null;
|
|
const leftStr = getStringLiteralValue(e.left);
|
|
const rightStr = getStringLiteralValue(e.right);
|
|
if (leftIdent && rightStr) res.push({ ident: leftIdent, value: rightStr });
|
|
if (rightIdent && leftStr) res.push({ ident: rightIdent, value: leftStr });
|
|
}
|
|
// Recurse through && / || trees etc.
|
|
visit(e.left);
|
|
visit(e.right);
|
|
return;
|
|
}
|
|
if (ts.isPrefixUnaryExpression(e)) return visit(e.operand);
|
|
};
|
|
|
|
visit(expr);
|
|
return res;
|
|
}
|
|
|
|
function visit(node) {
|
|
if (ts.isCallExpression(node)) {
|
|
// go('transition.id', ...)
|
|
if (ts.isIdentifier(node.expression) && node.expression.text === 'go') {
|
|
const first = node.arguments[0];
|
|
const id = getStringLiteralValue(first);
|
|
if (id) record('go', id, first);
|
|
}
|
|
// bindTap('transition.id', ...)
|
|
if (ts.isIdentifier(node.expression) && node.expression.text === 'bindTap') {
|
|
const first = node.arguments[0];
|
|
const id = getStringLiteralValue(first);
|
|
if (id) {
|
|
record('bindTap', id, first);
|
|
} else if (fileTransitionIdPool.size > 0) {
|
|
// Indirect bindTap usage (e.g., bindTap(tab.transition))
|
|
// Record all transition ids seen in the local pool as "used".
|
|
for (const pooled of fileTransitionIdPool) {
|
|
record('bindTap', pooled, node);
|
|
}
|
|
}
|
|
}
|
|
// bindLongPress('transition.id', ...)
|
|
if (ts.isIdentifier(node.expression) && node.expression.text === 'bindLongPress') {
|
|
const first = node.arguments[0];
|
|
const id = getStringLiteralValue(first);
|
|
if (id) record('bindLongPress', id, first);
|
|
}
|
|
// bindDoubleTap('transition.id', ...)
|
|
if (ts.isIdentifier(node.expression) && node.expression.text === 'bindDoubleTap') {
|
|
const first = node.arguments[0];
|
|
const id = getStringLiteralValue(first);
|
|
if (id) record('bindDoubleTap', id, first);
|
|
}
|
|
// Best-effort: indirect bindings via shared components (e.g., header/topbar config APIs).
|
|
// We detect any call that passes an object with `id: '<transitionId>'` and only count it
|
|
// when it matches a declared TransitionId (prevents ActionId strings from being mis-counted).
|
|
const expr = node.expression;
|
|
const calleeName =
|
|
ts.isIdentifier(expr) ? expr.text :
|
|
ts.isPropertyAccessExpression(expr) ? expr.name.text :
|
|
'call';
|
|
for (const arg of node.arguments ?? []) {
|
|
if (!arg || !ts.isObjectLiteralExpression(arg)) continue;
|
|
const idInit = getProp(arg, 'id');
|
|
const id = getStringLiteralValue(idInit);
|
|
if (id && (!declaredTransitionIdSet || declaredTransitionIdSet.has(id))) {
|
|
record(`call:${calleeName}`, id, idInit ?? arg);
|
|
}
|
|
}
|
|
}
|
|
ts.forEachChild(node, visit);
|
|
}
|
|
visit(sf);
|
|
}
|
|
|
|
return usages;
|
|
}
|
|
|
|
function buildReport({ nav, usages }) {
|
|
const declaredIds = new Set(nav.transitions.keys());
|
|
|
|
// Built-in/system triggers are not part of navigation.declaration.ts transitions[].
|
|
// Example: `system.back` is used by bindBack() across apps.
|
|
const isSystemId = (id) => typeof id === 'string' && id.startsWith('system.');
|
|
const usedIds = new Set(usages.map(u => u.id).filter(id => !isSystemId(id)));
|
|
|
|
const missingInDeclaration = [...usedIds].filter(id => !declaredIds.has(id)).sort();
|
|
const unusedInCode = [...declaredIds].filter(id => !usedIds.has(id)).sort();
|
|
|
|
/** @type {Record<string, Array<{id:string, kind:string, file:string, line:number, col:number, component?:string}>>} */
|
|
const missingUsageSites = {};
|
|
for (const u of usages) {
|
|
if (isSystemId(u.id)) continue;
|
|
if (declaredIds.has(u.id)) continue;
|
|
const arr = missingUsageSites[u.id] ?? (missingUsageSites[u.id] = []);
|
|
arr.push({
|
|
id: u.id,
|
|
kind: u.kind,
|
|
file: u.file,
|
|
line: u.line,
|
|
col: u.col,
|
|
...(u.componentGuess ? { component: u.componentGuess } : {}),
|
|
});
|
|
}
|
|
for (const id of Object.keys(missingUsageSites)) {
|
|
const seen = new Set();
|
|
missingUsageSites[id] = missingUsageSites[id]
|
|
.filter(x => {
|
|
const key = `${x.file}:${x.line}:${x.col}:${x.kind}:${x.component ?? ''}`;
|
|
if (seen.has(key)) return false;
|
|
seen.add(key);
|
|
return true;
|
|
})
|
|
.sort((a, b) =>
|
|
`${a.file}:${a.line}:${a.col}`.localeCompare(`${b.file}:${b.line}:${b.col}`),
|
|
);
|
|
}
|
|
|
|
/** @type {Array<{id:string, file:string, line:number, col:number, component?:string, expectedFromPaths:string[], declaredFromPaths:string[]}>} */
|
|
const fromMismatches = [];
|
|
|
|
// Build expected from paths per transitionId based on page-local usage sites we can map.
|
|
/** @type {Map<string, Set<string>>} */
|
|
const expectedFromById = new Map();
|
|
for (const u of usages) {
|
|
if (!u.componentGuess) continue;
|
|
const pathsForComponent = nav.componentToPaths.get(u.componentGuess) ?? [];
|
|
if (pathsForComponent.length === 0) continue;
|
|
const set = expectedFromById.get(u.id) ?? new Set();
|
|
for (const p of pathsForComponent) set.add(p);
|
|
expectedFromById.set(u.id, set);
|
|
}
|
|
|
|
for (const u of usages) {
|
|
const t = nav.transitions.get(u.id);
|
|
if (!t) continue; // already covered by missingInDeclaration
|
|
if (!u.componentGuess) continue; // we only validate within page components for now
|
|
const pathsForComponent = nav.componentToPaths.get(u.componentGuess) ?? [];
|
|
if (pathsForComponent.length === 0) continue; // unknown mapping
|
|
const ok = pathsForComponent.some(p => t.fromPaths.has(p));
|
|
if (!ok) {
|
|
fromMismatches.push({
|
|
id: u.id,
|
|
file: u.file,
|
|
line: u.line,
|
|
col: u.col,
|
|
component: u.componentGuess,
|
|
expectedFromPaths: pathsForComponent,
|
|
declaredFromPaths: [...t.fromPaths].sort(),
|
|
});
|
|
}
|
|
}
|
|
|
|
// Gesture mismatches: compare declared ui.gesture with observed bind* usage.
|
|
/** @type {Array<{id:string, declaredGesture:string|null, observedGestures:string[], examples:Array<{file:string,line:number,col:number,kind:string}>}>} */
|
|
const gestureMismatches = [];
|
|
const observedById = new Map();
|
|
for (const u of usages) {
|
|
if (u.kind === 'bindTap') {
|
|
const entry = observedById.get(u.id) ?? { gestures: new Set(), examples: [] };
|
|
entry.gestures.add('tap');
|
|
entry.examples.push({ file: u.file, line: u.line, col: u.col, kind: u.kind });
|
|
observedById.set(u.id, entry);
|
|
}
|
|
if (u.kind === 'bindLongPress') {
|
|
const entry = observedById.get(u.id) ?? { gestures: new Set(), examples: [] };
|
|
entry.gestures.add('longPress');
|
|
entry.examples.push({ file: u.file, line: u.line, col: u.col, kind: u.kind });
|
|
observedById.set(u.id, entry);
|
|
}
|
|
if (u.kind === 'bindDoubleTap') {
|
|
const entry = observedById.get(u.id) ?? { gestures: new Set(), examples: [] };
|
|
entry.gestures.add('doubleTap');
|
|
entry.examples.push({ file: u.file, line: u.line, col: u.col, kind: u.kind });
|
|
observedById.set(u.id, entry);
|
|
}
|
|
}
|
|
for (const [id, obs] of observedById.entries()) {
|
|
const t = nav.transitions.get(id);
|
|
if (!t) continue;
|
|
const declared = t.uiGesture ?? null;
|
|
const observedGestures = [...obs.gestures].sort();
|
|
if (declared && observedGestures.length === 1 && declared !== observedGestures[0]) {
|
|
gestureMismatches.push({
|
|
id,
|
|
declaredGesture: declared,
|
|
observedGestures,
|
|
examples: obs.examples.slice(0, 3),
|
|
});
|
|
}
|
|
}
|
|
|
|
// from.search over-broad heuristics (best-effort):
|
|
// If a usage site is guarded by a specific tab/sub/etc, but the transition.from for that route path
|
|
// is missing search or uses wildcard '*', warn/suggest narrowing.
|
|
/** @type {Array<{id:string, sourcePath:string, key:string, expectedValue:string, declaredValue:string|null, example:{file:string,line:number,col:number}}>} */
|
|
const fromSearchTooBroad = [];
|
|
for (const u of usages) {
|
|
if (!u.componentGuess) continue;
|
|
if (!u.inferredSearch) continue;
|
|
const t = nav.transitions.get(u.id);
|
|
if (!t) continue;
|
|
const pathsForComponent = nav.componentToPaths.get(u.componentGuess) ?? [];
|
|
if (pathsForComponent.length === 0) continue;
|
|
// only handle single-path components to avoid ambiguity
|
|
if (pathsForComponent.length !== 1) continue;
|
|
const sourcePath = pathsForComponent[0];
|
|
// Find from entries in declaration that match this source path
|
|
const relevant = t.fromEntries.filter(e => e.path === sourcePath);
|
|
if (relevant.length === 0) continue;
|
|
|
|
for (const [key, expectedValue] of Object.entries(u.inferredSearch)) {
|
|
for (const entry of relevant) {
|
|
const declaredValue = entry.search?.[key] ?? null;
|
|
if (declaredValue === '*') {
|
|
fromSearchTooBroad.push({
|
|
id: u.id,
|
|
sourcePath,
|
|
key,
|
|
expectedValue,
|
|
declaredValue,
|
|
example: { file: u.file, line: u.line, col: u.col },
|
|
});
|
|
}
|
|
if (declaredValue === null && expectedValue) {
|
|
fromSearchTooBroad.push({
|
|
id: u.id,
|
|
sourcePath,
|
|
key,
|
|
expectedValue,
|
|
declaredValue: null,
|
|
example: { file: u.file, line: u.line, col: u.col },
|
|
});
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Warn about declared "from" paths that are route paths but have no mapped usage site.
|
|
/** @type {Array<{id:string, extraFromPaths:string[], declaredFromPaths:string[], hasAnyUsage:boolean}>} */
|
|
const extraFromWarnings = [];
|
|
const allRoutePaths = new Set(nav.routes.map(r => r.path));
|
|
for (const [id, t] of nav.transitions.entries()) {
|
|
const expected = expectedFromById.get(id) ?? new Set();
|
|
// Only run this heuristic when we have at least one mapped usage site (page -> route).
|
|
// Otherwise (e.g., triggers inside shared components like TabBar), we can't infer expected-from.
|
|
if (expected.size === 0) continue;
|
|
// Tabbar transitions are global entry points; page-local inference will under-estimate.
|
|
if (t.uiPlacement === 'tabbar') continue;
|
|
const extra = [...t.fromPaths].filter(p => allRoutePaths.has(p) && !expected.has(p)).sort();
|
|
// Only warn if we have at least one usage of this id anywhere (otherwise it might be truly unused/placeholder).
|
|
const hasAnyUsage = usedIds.has(id);
|
|
if (hasAnyUsage && extra.length > 0) {
|
|
extraFromWarnings.push({
|
|
id,
|
|
extraFromPaths: extra,
|
|
declaredFromPaths: [...t.fromPaths].sort(),
|
|
hasAnyUsage,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Warn about "from" using bare route path when that route has NO base discrete uiState.
|
|
// This commonly creates an extra placeholder node (e.g. "/ranking" or "/profile/following") with indegree=0.
|
|
/** @type {Array<{id:string, fromPath:string, reason:string}>} */
|
|
const fromBarePathWithoutBaseState = [];
|
|
const routeMetaByPath = new Map(nav.routes.map(r => [r.path, r]));
|
|
for (const [id, t] of nav.transitions.entries()) {
|
|
for (const entry of t.fromEntries) {
|
|
const routeMeta = routeMetaByPath.get(entry.path);
|
|
if (!routeMeta) continue;
|
|
// bare path (no search constraint) only
|
|
if (entry.search && Object.keys(entry.search).length > 0) continue;
|
|
if (routeMeta.hasBaseDiscreteState) continue;
|
|
|
|
const keySets = routeMeta.uiStateDiscreteKeySets || [];
|
|
const uniqueKeySetStr = Array.from(
|
|
new Set(
|
|
keySets
|
|
.filter(s => s && s.size > 0)
|
|
.map(s => Array.from(s).sort().join(',')),
|
|
),
|
|
)
|
|
.filter(Boolean)
|
|
.slice(0, 5);
|
|
|
|
const hint =
|
|
uniqueKeySetStr.length > 0
|
|
? `该路由没有离散基础态（uiStates 不包含 search:{}）。可达状态的离散键集合示例：${uniqueKeySetStr
|
|
.map(s => `[${s}]`)
|
|
.join('、')}`
|
|
: '该路由没有离散基础态（uiStates 不包含 search:{}）。';
|
|
|
|
fromBarePathWithoutBaseState.push({
|
|
id,
|
|
fromPath: entry.path,
|
|
reason: hint,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Base uiState naming: if uiState.search is {} (no discrete keys), id must end with ".base"
|
|
// Ref: docs/platform/declarative-navigation.md ("Routes" / "Actions" sections)
|
|
/** @type {Array<{routePath:string, uiStateId:string, message:string}>} */
|
|
const invalidBaseStateIds = [];
|
|
/** @type {Array<{routePath:string, baseStateIds:string[]}>} */
|
|
const multipleBaseStates = [];
|
|
|
|
for (const r of nav.routes) {
|
|
const baseStates = (r.uiStates ?? []).filter(s => (s?.discreteKeys?.size ?? 0) === 0);
|
|
if (baseStates.length > 1) {
|
|
multipleBaseStates.push({
|
|
routePath: r.path,
|
|
baseStateIds: baseStates.map(s => s.id).filter(Boolean),
|
|
});
|
|
}
|
|
for (const s of baseStates) {
|
|
const id = s.id ?? '<unknown>';
|
|
if (!id.endsWith('.base')) {
|
|
invalidBaseStateIds.push({
|
|
routePath: r.path,
|
|
uiStateId: id,
|
|
message: `Invalid base uiState id "${id}" for route "${r.path}". If uiState.search is {}, id must end with ".base".`,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
return {
|
|
summary: {
|
|
routes: nav.routes.length,
|
|
transitionsDeclared: declaredIds.size,
|
|
transitionsUsedInCode: usedIds.size,
|
|
missingInDeclaration: missingInDeclaration.length,
|
|
unusedInCode: unusedInCode.length,
|
|
fromMismatches: fromMismatches.length,
|
|
extraFromWarnings: extraFromWarnings.length,
|
|
gestureMismatches: gestureMismatches.length,
|
|
fromSearchTooBroad: fromSearchTooBroad.length,
|
|
fromBarePathWithoutBaseState: fromBarePathWithoutBaseState.length,
|
|
invalidBaseStateIds: invalidBaseStateIds.length,
|
|
multipleBaseStates: multipleBaseStates.length,
|
|
},
|
|
missingInDeclaration,
|
|
missingUsageSites,
|
|
unusedInCode,
|
|
fromMismatches,
|
|
extraFromWarnings,
|
|
gestureMismatches,
|
|
fromSearchTooBroad,
|
|
fromBarePathWithoutBaseState,
|
|
invalidBaseStateIds,
|
|
multipleBaseStates,
|
|
};
|
|
}
|
|
|
|
function printHuman(report) {
|
|
const s = report.summary;
|
|
console.log('=== Navigation Declaration Consistency Report ===');
|
|
console.log(`routes=${s.routes} transitionsDeclared=${s.transitionsDeclared} transitionsUsedInCode=${s.transitionsUsedInCode}`);
|
|
console.log(`missingInDeclaration=${s.missingInDeclaration} fromMismatches=${s.fromMismatches} unusedInCode=${s.unusedInCode}`);
|
|
console.log('');
|
|
|
|
if (report.missingInDeclaration.length) {
|
|
console.log('--- ERROR: Used in code but missing in declaration ---');
|
|
for (const id of report.missingInDeclaration) {
|
|
console.log(`- ${id}`);
|
|
const sites = report.missingUsageSites?.[id] ?? [];
|
|
for (const ex of sites.slice(0, 8)) {
|
|
console.log(` @ ${ex.file}:${ex.line}:${ex.col} (${ex.kind}${ex.component ? `, component=${ex.component}` : ''})`);
|
|
}
|
|
if (sites.length > 8) console.log(` ... (${sites.length - 8} more)`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.fromMismatches.length) {
|
|
console.log('--- ERROR: Usage file route not included in transition.from (path-only check) ---');
|
|
for (const m of report.fromMismatches) {
|
|
console.log(`- ${m.id} @ ${m.file}:${m.line}:${m.col} (component=${m.component})`);
|
|
console.log(` expected from includes one of: ${m.expectedFromPaths.join(', ')}`);
|
|
console.log(` declared from paths: ${m.declaredFromPaths.join(', ') || '(none parsed)'}`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.unusedInCode.length) {
|
|
console.log('--- WARN: Declared but not found in code (may be OK: implicit/entry/back/placeholder) ---');
|
|
for (const id of report.unusedInCode.slice(0, 50)) console.log(`- ${id}`);
|
|
if (report.unusedInCode.length > 50) console.log(`... (${report.unusedInCode.length - 50} more)`);
|
|
console.log('');
|
|
}
|
|
|
|
if (report.extraFromWarnings?.length) {
|
|
console.log('--- WARN: Declared transition.from includes route paths with no mapped trigger site in code ---');
|
|
for (const w of report.extraFromWarnings) {
|
|
console.log(`- ${w.id}: extra from paths = ${w.extraFromPaths.join(', ')}`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.gestureMismatches?.length) {
|
|
console.log('--- WARN: Declared ui.gesture mismatch vs bind* usage ---');
|
|
for (const m of report.gestureMismatches) {
|
|
console.log(`- ${m.id}: declared=${m.declaredGesture} observed=${m.observedGestures.join(', ')}`);
|
|
for (const ex of m.examples) {
|
|
console.log(` @ ${ex.file}:${ex.line}:${ex.col} (${ex.kind})`);
|
|
}
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.fromSearchTooBroad?.length) {
|
|
console.log('--- WARN: transition.from.search might be too broad (best-effort inference from guarded usage sites) ---');
|
|
for (const w of report.fromSearchTooBroad.slice(0, 30)) {
|
|
console.log(`- ${w.id} from ${w.sourcePath}: expected ${w.key}=${w.expectedValue}, declared ${w.key}=${w.declaredValue ?? '(missing)'}`);
|
|
console.log(` @ ${w.example.file}:${w.example.line}:${w.example.col}`);
|
|
}
|
|
if (report.fromSearchTooBroad.length > 30) console.log(`... (${report.fromSearchTooBroad.length - 30} more)`);
|
|
console.log('');
|
|
}
|
|
|
|
if (report.fromBarePathWithoutBaseState?.length) {
|
|
console.log('--- WARN: transition.from uses bare route path but route has no base discrete uiState (may create indegree=0 placeholder node) ---');
|
|
for (const w of report.fromBarePathWithoutBaseState.slice(0, 50)) {
|
|
console.log(`- ${w.id}: from "${w.fromPath}" (no search constraint)`);
|
|
console.log(` ${w.reason}`);
|
|
console.log(` fix: replace with FromConstraint(s), e.g. { path: "${w.fromPath}", search: { <key>: '*' } } or enumerate concrete uiStates.`);
|
|
}
|
|
if (report.fromBarePathWithoutBaseState.length > 50) {
|
|
console.log(`... (${report.fromBarePathWithoutBaseState.length - 50} more)`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.invalidBaseStateIds?.length) {
|
|
console.log('--- ERROR: invalid base uiState ids (uiState.search is {} but id does not end with .base) ---');
|
|
for (const e of report.invalidBaseStateIds.slice(0, 50)) {
|
|
console.log(`- ${e.message}`);
|
|
}
|
|
if (report.invalidBaseStateIds.length > 50) {
|
|
console.log(`... (${report.invalidBaseStateIds.length - 50} more)`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.multipleBaseStates?.length) {
|
|
console.log('--- WARN: route has multiple base uiStates (search:{}). Consider keeping only one. ---');
|
|
for (const w of report.multipleBaseStates.slice(0, 50)) {
|
|
console.log(`- ${w.routePath}: base uiStates = ${w.baseStateIds.join(', ')}`);
|
|
}
|
|
if (report.multipleBaseStates.length > 50) {
|
|
console.log(`... (${report.multipleBaseStates.length - 50} more)`);
|
|
}
|
|
console.log('');
|
|
}
|
|
}
|
|
|
|
// ============================================================================
|
|
// Actions consistency (data-action / bindTap({kind:'action'}))
|
|
// ============================================================================
|
|
|
|
function extractActionsFromNavDeclaration(navDeclPath) {
|
|
const sf = createSourceFile(navDeclPath);
|
|
|
|
/** @type {null | ts.ObjectLiteralExpression} */
|
|
let declObj = null;
|
|
|
|
function unwrapExpr(expr) {
|
|
let cur = expr;
|
|
while (cur) {
|
|
if (ts.isAsExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isSatisfiesExpression && ts.isSatisfiesExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
if (ts.isParenthesizedExpression(cur)) {
|
|
cur = cur.expression;
|
|
continue;
|
|
}
|
|
break;
|
|
}
|
|
return cur;
|
|
}
|
|
|
|
function visit(node) {
|
|
if (
|
|
ts.isVariableDeclaration(node) &&
|
|
ts.isIdentifier(node.name) &&
|
|
node.name.text === 'NAVIGATION_DECLARATION'
|
|
) {
|
|
const init = node.initializer ? unwrapExpr(node.initializer) : null;
|
|
if (init && ts.isObjectLiteralExpression(init)) declObj = init;
|
|
}
|
|
ts.forEachChild(node, visit);
|
|
}
|
|
visit(sf);
|
|
|
|
if (!declObj) {
|
|
throw new Error(`Cannot find NAVIGATION_DECLARATION object in ${navDeclPath}`);
|
|
}
|
|
|
|
const routesInit = getProp(declObj, 'routes');
|
|
/** @type {Array<{id:string,label?:string,behavior?:string,scope?:string,paramsSchema?:Record<string,string>,routePath:string,uiStateId:string}>} */
|
|
const actions = [];
|
|
|
|
if (routesInit && ts.isArrayLiteralExpression(routesInit)) {
|
|
for (const routeEl of routesInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(routeEl)) continue;
|
|
const routePath = getStringLiteralValue(getProp(routeEl, 'path')) ?? '<unknown>';
|
|
const uiStatesInit = getProp(routeEl, 'uiStates');
|
|
if (!uiStatesInit || !ts.isArrayLiteralExpression(uiStatesInit)) continue;
|
|
|
|
for (const uiStateEl of uiStatesInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(uiStateEl)) continue;
|
|
const uiStateId = getStringLiteralValue(getProp(uiStateEl, 'id')) ?? '<unknown>';
|
|
const actionsInit = getProp(uiStateEl, 'actions');
|
|
if (!actionsInit || !ts.isArrayLiteralExpression(actionsInit)) continue;
|
|
|
|
for (const actEl of actionsInit.elements) {
|
|
if (!ts.isObjectLiteralExpression(actEl)) continue;
|
|
const id = getStringLiteralValue(getProp(actEl, 'id'));
|
|
if (!id) continue;
|
|
const label = getStringLiteralValue(getProp(actEl, 'label')) ?? undefined;
|
|
const behavior = getStringLiteralValue(getProp(actEl, 'behavior')) ?? undefined;
|
|
const scope = getStringLiteralValue(getProp(actEl, 'scope')) ?? undefined;
|
|
|
|
const paramsSchemaInit = getProp(actEl, 'paramsSchema');
|
|
let paramsSchema = undefined;
|
|
if (paramsSchemaInit && ts.isObjectLiteralExpression(paramsSchemaInit)) {
|
|
paramsSchema = {};
|
|
for (const prop of paramsSchemaInit.properties) {
|
|
if (!ts.isPropertyAssignment(prop)) continue;
|
|
const key =
|
|
ts.isIdentifier(prop.name) ? prop.name.text :
|
|
ts.isStringLiteral(prop.name) ? prop.name.text :
|
|
null;
|
|
if (!key) continue;
|
|
const val = getStringLiteralValue(prop.initializer);
|
|
if (val) paramsSchema[key] = val;
|
|
}
|
|
}
|
|
|
|
actions.push({ id, label, behavior, scope, paramsSchema, routePath, uiStateId });
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
return actions;
|
|
}
|
|
|
|
function extractActionUsages(appDir, declaredIdSet) {
|
|
const ignoreDirs = new Set(['node_modules', 'dist', 'build']);
|
|
const exts = new Set(['.ts', '.tsx']);
|
|
const files = listFilesRecursive(appDir, { exts, ignoreDirs });
|
|
|
|
/** @type {Array<{id:string, kind:'bindTap'|'bindLongPress'|'bindDoubleTap'|'data-action'|'stringLiteral', file:string, line:number, col:number}>} */
|
|
const usages = [];
|
|
|
|
for (const filePath of files) {
|
|
// Never treat the declaration itself as a "usage" source.
|
|
if (filePath.endsWith(`${path.sep}navigation.declaration.ts`)) continue;
|
|
|
|
const sf = createSourceFile(filePath);
|
|
const rel = path.relative(WORKSPACE_ROOT, filePath);
|
|
|
|
function record(kind, id, node) {
|
|
const lc = sf.getLineAndCharacterOfPosition(node.getStart(sf));
|
|
usages.push({
|
|
id,
|
|
kind,
|
|
file: rel,
|
|
line: lc.line + 1,
|
|
col: lc.character + 1,
|
|
});
|
|
}
|
|
|
|
function extractActionSpecId(objLit) {
|
|
if (!isObjectLiteral(objLit)) return null;
|
|
const kindInit = getProp(objLit, 'kind');
|
|
const kindVal = getStringLiteralValue(kindInit);
|
|
if (kindVal !== 'action') return null;
|
|
return getStringLiteralValue(getProp(objLit, 'id'));
|
|
}
|
|
|
|
function visit(node) {
|
|
// bindTap({kind:'action',id:'x'})
|
|
if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
|
|
const callee = node.expression.text;
|
|
if (callee === 'bindTap' || callee === 'bindLongPress' || callee === 'bindDoubleTap') {
|
|
const first = node.arguments[0];
|
|
if (first && ts.isObjectLiteralExpression(first)) {
|
|
const id = extractActionSpecId(first);
|
|
if (id) record(callee, id, first);
|
|
}
|
|
}
|
|
}
|
|
|
|
// JSX: data-action="x"
|
|
if (ts.isJsxAttribute(node)) {
|
|
const name = node.name?.text;
|
|
if (name === 'data-action') {
|
|
const init = node.initializer;
|
|
if (init && ts.isStringLiteral(init)) {
|
|
record('data-action', init.text, init);
|
|
}
|
|
if (init && ts.isJsxExpression(init) && init.expression) {
|
|
const v = getStringLiteralValue(init.expression);
|
|
if (v) record('data-action', v, init.expression);
|
|
}
|
|
}
|
|
}
|
|
|
|
// Best-effort: any string literal that exactly matches a declared actionId
|
|
// (covers passing actionId via props / lookup tables).
|
|
if (declaredIdSet && ts.isStringLiteral(node)) {
|
|
if (declaredIdSet.has(node.text)) record('stringLiteral', node.text, node);
|
|
}
|
|
if (declaredIdSet && ts.isNoSubstitutionTemplateLiteral(node)) {
|
|
if (declaredIdSet.has(node.text)) record('stringLiteral', node.text, node);
|
|
}
|
|
|
|
ts.forEachChild(node, visit);
|
|
}
|
|
|
|
visit(sf);
|
|
}
|
|
|
|
return usages;
|
|
}
|
|
|
|
function validateActionDeclarations(actions) {
|
|
/** @type {Array<{level:'error'|'warn', code:string, message:string, actionId?:string, routePath?:string, uiStateId?:string}>} */
|
|
const issues = [];
|
|
|
|
const idToDecls = new Map();
|
|
for (const a of actions) {
|
|
const list = idToDecls.get(a.id) ?? [];
|
|
list.push(a);
|
|
idToDecls.set(a.id, list);
|
|
}
|
|
|
|
for (const [id, list] of idToDecls.entries()) {
|
|
if (list.length > 1) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'duplicate_action_id',
|
|
message: `Duplicate action id "${id}" declared in multiple uiStates (${list.length}).`,
|
|
actionId: id,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Allow camelCase / PascalCase segments; still require dot-separated segments.
|
|
const idRe = /^[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)+$/;
|
|
|
|
for (const a of actions) {
|
|
const { id, behavior, scope, paramsSchema } = a;
|
|
const segments = id.split('.');
|
|
|
|
if (!idRe.test(id) || segments.length < 3) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'invalid_action_id',
|
|
message: `Invalid actionId "${id}". Must match ${idRe} and have at least 3 segments.`,
|
|
actionId: id,
|
|
routePath: a.routePath,
|
|
uiStateId: a.uiStateId,
|
|
});
|
|
}
|
|
|
|
if (behavior === 'select') {
|
|
if (!/\.select\.[a-zA-Z0-9]+$/.test(id)) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'select_id_format',
|
|
message: `behavior='select' actionId must match "<prefix>.select.<option>": "${id}"`,
|
|
actionId: id,
|
|
routePath: a.routePath,
|
|
uiStateId: a.uiStateId,
|
|
});
|
|
}
|
|
}
|
|
|
|
if (behavior === 'input') {
|
|
if (!paramsSchema || (paramsSchema.value !== 'string' && paramsSchema.value !== 'number')) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'input_requires_value',
|
|
message: `behavior='input' must declare paramsSchema.value as 'string'|'number': "${id}"`,
|
|
actionId: id,
|
|
routePath: a.routePath,
|
|
uiStateId: a.uiStateId,
|
|
});
|
|
}
|
|
}
|
|
|
|
if (scope === 'item') {
|
|
if (!paramsSchema || Object.keys(paramsSchema).length === 0) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'item_scope_requires_params_schema',
|
|
message: `scope='item' must declare paramsSchema with at least one object identifier field: "${id}"`,
|
|
actionId: id,
|
|
routePath: a.routePath,
|
|
uiStateId: a.uiStateId,
|
|
});
|
|
} else {
|
|
const objectIdKeys = Object.entries(paramsSchema).filter(
|
|
([k, v]) => (v === 'string' || v === 'number') && k !== 'value' && k !== 'to',
|
|
);
|
|
if (objectIdKeys.length === 0) {
|
|
issues.push({
|
|
level: 'error',
|
|
code: 'item_scope_missing_object_identifier',
|
|
message: `scope='item' paramsSchema must include at least one identifier field (string|number), e.g. bookId/userId: "${id}"`,
|
|
actionId: id,
|
|
routePath: a.routePath,
|
|
uiStateId: a.uiStateId,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
return issues;
|
|
}
|
|
|
|
function buildActionsReport({ declaredActions, usages }) {
|
|
const declaredIds = new Set(declaredActions.map(a => a.id));
|
|
const usedIds = new Set(usages.map(u => u.id));
|
|
|
|
const missingInDeclaration = [...usedIds].filter(id => !declaredIds.has(id)).sort();
|
|
const unusedInCode = [...declaredIds].filter(id => !usedIds.has(id)).sort();
|
|
const schemaIssues = validateActionDeclarations(declaredActions);
|
|
|
|
/** @type {Record<string, Array<{id:string, kind:string, file:string, line:number, col:number}>>} */
|
|
const missingUsageSites = {};
|
|
for (const u of usages) {
|
|
if (declaredIds.has(u.id)) continue;
|
|
const arr = missingUsageSites[u.id] ?? (missingUsageSites[u.id] = []);
|
|
arr.push({ id: u.id, kind: u.kind, file: u.file, line: u.line, col: u.col });
|
|
}
|
|
for (const id of Object.keys(missingUsageSites)) {
|
|
const seen = new Set();
|
|
missingUsageSites[id] = missingUsageSites[id]
|
|
.filter(x => {
|
|
const key = `${x.file}:${x.line}:${x.col}:${x.kind}`;
|
|
if (seen.has(key)) return false;
|
|
seen.add(key);
|
|
return true;
|
|
})
|
|
.sort((a, b) =>
|
|
`${a.file}:${a.line}:${a.col}`.localeCompare(`${b.file}:${b.line}:${b.col}`),
|
|
);
|
|
}
|
|
|
|
return {
|
|
summary: {
|
|
actionsDeclared: declaredIds.size,
|
|
actionsUsedInCode: usedIds.size,
|
|
missingInDeclaration: missingInDeclaration.length,
|
|
unusedInCode: unusedInCode.length,
|
|
schemaErrors: schemaIssues.filter(x => x.level === 'error').length,
|
|
schemaWarnings: schemaIssues.filter(x => x.level === 'warn').length,
|
|
},
|
|
missingInDeclaration,
|
|
missingUsageSites,
|
|
unusedInCode,
|
|
schemaIssues,
|
|
};
|
|
}
|
|
|
|
function printHumanActions(report) {
|
|
const s = report.summary;
|
|
console.log('=== Actions Declaration Consistency Report ===');
|
|
console.log(`actionsDeclared=${s.actionsDeclared} actionsUsedInCode=${s.actionsUsedInCode}`);
|
|
console.log(`missingInDeclaration=${s.missingInDeclaration} unusedInCode=${s.unusedInCode}`);
|
|
console.log(`schemaErrors=${s.schemaErrors} schemaWarnings=${s.schemaWarnings}`);
|
|
console.log('');
|
|
|
|
const errors = report.schemaIssues.filter(x => x.level === 'error');
|
|
const warns = report.schemaIssues.filter(x => x.level === 'warn');
|
|
|
|
if (errors.length) {
|
|
console.log('--- ERROR: Action declaration schema issues ---');
|
|
for (const e of errors) {
|
|
console.log(`- [${e.code}] ${e.message}`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (report.missingInDeclaration.length) {
|
|
console.log('--- ERROR: Used in code but missing in declaration ---');
|
|
for (const id of report.missingInDeclaration) {
|
|
console.log(`- ${id}`);
|
|
const sites = report.missingUsageSites?.[id] ?? [];
|
|
for (const ex of sites.slice(0, 8)) {
|
|
console.log(` @ ${ex.file}:${ex.line}:${ex.col} (${ex.kind})`);
|
|
}
|
|
if (sites.length > 8) console.log(` ... (${sites.length - 8} more)`);
|
|
}
|
|
console.log('');
|
|
}
|
|
|
|
if (warns.length) {
|
|
console.log('--- WARN: Action declaration schema warnings ---');
|
|
for (const w of warns) console.log(`- [${w.code}] ${w.message}`);
|
|
console.log('');
|
|
}
|
|
|
|
if (report.unusedInCode.length) {
|
|
console.log('--- WARN: Declared but not found in code ---');
|
|
for (const id of report.unusedInCode.slice(0, 50)) console.log(`- ${id}`);
|
|
if (report.unusedInCode.length > 50) console.log(`... (${report.unusedInCode.length - 50} more)`);
|
|
console.log('');
|
|
}
|
|
}
|
|
|
|
async function main() {
|
|
const { appName, jsonOnly, failOnWarn, actions, actionsOnly } = parseArgs(process.argv);
|
|
if (!appName) {
|
|
usage();
|
|
process.exit(2);
|
|
}
|
|
|
|
const appDir = path.join(WORKSPACE_ROOT, 'apps', appName);
|
|
const navDeclPath = path.join(appDir, 'navigation.declaration.ts');
|
|
if (!fs.existsSync(navDeclPath)) {
|
|
throw new Error(`navigation.declaration.ts not found: ${navDeclPath}`);
|
|
}
|
|
|
|
const nav = extractNavDeclaration(navDeclPath);
|
|
const navUsages = extractTransitionUsages(appDir, new Set(nav.transitions.keys()));
|
|
const navReport = buildReport({ nav, usages: navUsages });
|
|
|
|
let actionsReport = null;
|
|
if (actions || actionsOnly) {
|
|
const declaredActions = extractActionsFromNavDeclaration(navDeclPath);
|
|
const declaredIdSet = new Set(declaredActions.map(a => a.id));
|
|
const actionUsages = extractActionUsages(appDir, declaredIdSet);
|
|
actionsReport = buildActionsReport({ declaredActions, usages: actionUsages });
|
|
}
|
|
|
|
if (jsonOnly) {
|
|
if (actions || actionsOnly) {
|
|
console.log(JSON.stringify({ navigation: navReport, actions: actionsReport }, null, 2));
|
|
} else {
|
|
console.log(JSON.stringify(navReport, null, 2));
|
|
}
|
|
} else {
|
|
if (!actionsOnly) {
|
|
printHuman(navReport);
|
|
console.log(`JSON summary: ${JSON.stringify(navReport.summary)}`);
|
|
console.log('');
|
|
}
|
|
if (actions || actionsOnly) {
|
|
printHumanActions(actionsReport);
|
|
console.log(`JSON summary: ${JSON.stringify(actionsReport.summary)}`);
|
|
}
|
|
}
|
|
|
|
const hasNavError = navReport.missingInDeclaration.length > 0 || navReport.fromMismatches.length > 0;
|
|
const hasNavWarn = navReport.unusedInCode.length > 0;
|
|
|
|
const hasActionsError = actionsReport
|
|
? actionsReport.missingInDeclaration.length > 0 ||
|
|
actionsReport.schemaIssues.some(x => x.level === 'error')
|
|
: false;
|
|
const hasActionsWarn = actionsReport
|
|
? actionsReport.unusedInCode.length > 0 ||
|
|
actionsReport.schemaIssues.some(x => x.level === 'warn')
|
|
: false;
|
|
|
|
const hasError = (actionsOnly ? hasActionsError : hasNavError || hasActionsError);
|
|
const hasWarn = (actionsOnly ? hasActionsWarn : hasNavWarn || hasActionsWarn);
|
|
if (hasError || (failOnWarn && hasWarn)) {
|
|
process.exit(1);
|
|
}
|
|
}
|
|
|
|
main().catch(err => {
|
|
console.error(err?.stack || String(err));
|
|
process.exit(1);
|
|
});
|
|
|