deveco_hmigbot 0.21.5

package/skills/migrate-core/scripts/closure/check-routes.mjs

@@ -0,0 +1,527 @@
+#!/usr/bin/env node
+/**
+ * check-routes.mjs — 路由可达性闭合检查（三态：violation / case / pass）
+ *
+ * 对账三本账：注册表（Navigation pageMap 比较分支 + 路由常量 + main_pages.json）
+ *            × 跳转调用（pushPathByName 族 / router.pushUrl 族，含工具类包装器链式解析）
+ *            × 入口连通（@Entry / loadContent 起点的 import 闭包 BFS）
+ *
+ * 裁决纪律：
+ *  - violation（硬，exit 10）：仅"两本账自相矛盾"——跳转了一个任何地方都没注册的路由名。
+ *  - case（软，exit 0，--strict 时 exit 2）：注册了但找不到静态入口 / 唯一入口在无人调用的
+ *    包装器里 / 从入口连通图不可达。立案待裁决，不是定罪。
+ *  - 动态名（模板串/变量）一律进 unresolved 不定罪；模板串按注册表的 {param} 前缀匹配；
+ *    含动态跳转的文件对其引用的路由常量给予 soft-credit（inferred），防"循环跳转表"误伤。
+ *  - 包装器机制只作用于非组件文件（工具类）；组件方法内的跳转按文件归属直接计。
+ *
+ *  - 注册页骨架残留（scaffold_page_residue）：route_map 注册的页文件仍含 wire 占位标记——slice 阶段不立案、
+ *    integration 立案、final 硬违规（--stage 由 closure-suite 透传）；pageSourceFile 缺失恒为硬违规。
+ *
+ * 用法：node check-routes.mjs --project <鸿蒙工程根> [--json out.json] [--strict] [--profile p.json] [--stage slice|integration|final]
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve, sep, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { stripComments, blankStrings, functionBodies, walkFiles, moduleSrcRoots } from '../lib/scan.mjs';
+
+const argv = process.argv.slice(2);
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const PROJECT = argOf('--project', null);
+const OUT = argOf('--json', null);
+const STRICT = argv.includes('--strict');
+// 阶段（closure-suite 透传）：只影响"注册页骨架残留"的立案级别——slice 不立案 / integration case / final violation
+const STAGE = ['slice', 'integration', 'final'].includes(argOf('--stage', 'integration')) ? argOf('--stage', 'integration') : 'integration';
+const PROFILE = argOf('--profile', null) ? JSON.parse(readFileSync(argOf('--profile', null), 'utf8')) : {};
+// 写法知识表：数据不硬编码。默认随包 idioms.json，可 --idioms 覆盖（顶层键浅合并）。
+const HERE = dirname(fileURLToPath(import.meta.url));
+const IDIOMS = { ...JSON.parse(readFileSync(join(HERE, 'idioms.json'), 'utf8')) };
+const idiomsOverride = argOf('--idioms', null);
+if (idiomsOverride) { const o = JSON.parse(readFileSync(idiomsOverride, 'utf8')); for (const k of Object.keys(o)) IDIOMS[k] = { ...IDIOMS[k], ...o[k] }; }
+if (!PROJECT) { console.error('usage: check-routes.mjs --project <root> [--json out] [--strict] [--profile p.json]'); process.exit(3); }
+
+const allFiles = walkFiles(resolve(PROJECT), { match: (p, e) => e.endsWith('.ets') || (e === 'main_pages.json' && p.includes(`${sep}profile${sep}`)) });
+const etsFiles = allFiles.filter(f => f.endsWith('.ets'));
+const pageProfiles = allFiles.filter(f => f.endsWith('main_pages.json'));
+// 注释脱敏（共享库：整文本状态机，模板串/正则字面量安全，同长度保偏移）
+const src = new Map(etsFiles.map(f => [f, stripComments(readFileSync(f, 'utf8'))]));
+// 字符串脱敏视图（调用点扫描用：字符串里的调用样例不算调用；偏移与 src 一致，取参回 src）
+const blankCache = new Map();
+const bl = f => { if (!blankCache.has(f)) blankCache.set(f, blankStrings(src.get(f))); return blankCache.get(f); };
+const rel = f => String(f).replace(resolve(PROJECT) + sep, '');
+const COMPONENT_RE = new RegExp(IDIOMS.wrappers.componentDecorators);
+const isComponentFile = f => COMPONENT_RE.test(src.get(f) || '');
+const lineOf = (code, idx) => code.slice(0, idx).split('\n').length;
+
+// ---------- 0) 常量 / 枚举成员表 ----------
+// 裸名跨文件同名不同值 = ambiguous（进 unresolved 不定罪）；static 成员按 类名.成员 限定存。
+const AMBIG = Symbol('ambiguous');
+const constMap = new Map();
+function setConst(key, val) {
+  if (!constMap.has(key)) { constMap.set(key, val); return; }
+  if (constMap.get(key) !== val) constMap.set(key, AMBIG);
+}
+for (const [, code] of src) {
+  for (const m of code.matchAll(/(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::\s*string)?\s*=\s*(['"])((?:(?!\2).)*)\2/g)) setConst(m[1], m[3]);
+  for (const m of code.matchAll(/static\s+(?:readonly\s+)?([A-Za-z_$][\w$]*)\s*(?::\s*string)?\s*=\s*(['"])((?:(?!\2).)*)\2/g)) {
+    const cls = [...code.slice(0, m.index).matchAll(/class\s+([A-Za-z_$][\w$]*)/g)].pop();
+    if (cls) setConst(`${cls[1]}.${m[1]}`, m[3]);
+    setConst(m[1], m[3]); // 裸名仍可查，冲突自动降 ambiguous
+  }
+  for (const em of code.matchAll(/(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)\s*\{([\s\S]*?)\}/g)) {
+    for (const mm of em[2].matchAll(/([A-Za-z_$][\w$]*)\s*=\s*(['"])((?:(?!\2).)*)\2/g)) {
+      setConst(`${em[1]}.${mm[1]}`, mm[3]);
+      if (!constMap.has(mm[1])) constMap.set(mm[1], mm[3]);
+    }
+  }
+}
+function resolveExpr(exprRaw) {
+  const e = (exprRaw || '').trim();
+  if (!e) return { name: null, kind: 'dynamic', via: '' };
+  const lit = e.match(/^(['"])((?:(?!\1).)*)\1$/);
+  if (lit) return { name: lit[2], kind: 'literal' };
+  if (e.startsWith('`')) {
+    const plain = e.match(/^`([^`$\\]*)`$/); // 无插值模板串=字面量
+    if (plain) return { name: plain[1], kind: 'literal' };
+    const m = e.match(/^`([^`$]*)\$\{/);
+    return { name: null, kind: 'template', prefix: m ? m[1] : '', via: e.slice(0, 40) };
+  }
+  const hit = (k) => constMap.get(k) === AMBIG
+    ? { name: null, kind: 'ambiguous', via: `${k}（跨文件同名不同值，进 unresolved）` }
+    : { name: constMap.get(k), kind: k.includes('.') ? 'enum' : 'const', via: k };
+  if (constMap.has(e)) return hit(e);
+  const q = e.match(/^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/);
+  if (q && constMap.has(`${q[1]}.${q[2]}`)) return hit(`${q[1]}.${q[2]}`);
+  return { name: null, kind: 'dynamic', via: e.slice(0, 40) };
+}
+function firstArg(code, idx) {
+  let depth = 0, out = '';
+  for (let i = idx; i < code.length && out.length < 200; i++) {
+    const c = code[i];
+    if ('({['.includes(c)) depth++;
+    else if (')}]'.includes(c)) { if (depth === 0) break; depth--; }
+    else if (c === ',' && depth === 0) break;
+    out += c;
+  }
+  return out.trim();
+}
+
+// ---------- 1) 注册表 ----------
+const registered = new Map();
+function addReg(name, kind, file, line, via) {
+  if (!name || registered.has(name)) return;
+  registered.set(name, { name, kind, file: rel(file), line, via, pattern: name.includes('{') ? name.slice(0, name.indexOf('{')) : null });
+}
+const entryRootPages = [];
+for (const pf of pageProfiles) {
+  try {
+    const j = JSON.parse(readFileSync(pf, 'utf8'));
+    (j.src || []).forEach((p, i) => { addReg(p, 'page', pf, 0, 'main_pages.json'); if (i === 0) entryRootPages.push(p); });
+  } catch { /* ignore */ }
+}
+// 第四本账：systemRouterMap（官方配置化路由）——route_map.json 直读，与 wire-routes 生成器
+// 同源（数据文件秒解析，无自研注册表形态漂移问题）。计入 kind:'nav' → 保险丝认账。
+// 同时记 name → pageSourceFile（模块根相对）：单一注册下 Index 不再 import 页面文件，
+// 路由→文件映射与骨架残留判定都靠它。
+const rmPageFile = new Map();
+for (const rmp of moduleSrcRoots(resolve(PROJECT)).map(r => join(r, '..', 'resources', 'base', 'profile', 'route_map.json')).filter(existsSync)) {
+  try {
+    const rm = JSON.parse(readFileSync(rmp, 'utf8'));
+    const modRoot = resolve(dirname(rmp), '..', '..', '..', '..', '..'); // profile/base/resources/main/src → 模块根
+    for (const e of (rm.routerMap || [])) {
+      addReg(e.name, 'nav', rmp, 0, 'route_map(systemRouterMap)');
+      if (e.pageSourceFile && !rmPageFile.has(e.name)) rmPageFile.set(e.name, resolve(modRoot, String(e.pageSourceFile)));
+    }
+  } catch { /* 坏 JSON 由构建自身报错 */ }
+}
+const REG_VARS = IDIOMS.nav.registrationVars.map(v => `\\b${v}\\b`).join('|');
+const navFiles = etsFiles.filter(f => src.get(f).includes(IDIOMS.nav.registrationMarker));
+const regFiles = new Set(navFiles);
+// 邻接扩展收紧：被 navFile import 的文件必须自身含 NavDestination( 组件（如集中式路由表文件）
+// 才算注册文件——否则普通工具文件里的 `name === 枚举` 解析函数会被误收（实测误伤）。
+for (const f of navFiles) {
+  for (const im of src.get(f).matchAll(/import\s+[^;]*?from\s+['"](\.[^'"]+)['"]/g)) {
+    const t = resolve(dirname(f), im[1]) + '.ets';
+    if (src.has(t) && /\bNavDestination\s*\(/.test(src.get(t))) regFiles.add(t);
+  }
+}
+for (const f of regFiles) {
+  const code = src.get(f);
+  for (const m of code.matchAll(new RegExp(`(?:${REG_VARS})\\s*===?\\s*([A-Za-z_$][\\w$.]*|['"][^'"]+['"])`, 'g'))) {
+    const r = resolveExpr(m[1]);
+    if (r.name) addReg(r.name, 'nav', f, lineOf(code, m.index), r.via || 'compare');
+  }
+  for (const m of code.matchAll(/case\s+(['"])((?:(?!\1).)*)\1\s*:/g)) addReg(m[2], 'nav', f, lineOf(code, m.index), 'case');
+  for (const m of code.matchAll(/\.startsWith\s*\(\s*([A-Za-z_$][\w$.]*|['"][^'"]+['"])\s*\)/g)) {
+    const r = resolveExpr(m[1]);
+    // 前缀最短长度门（idioms.nav.patternPrefixMinLen）：单字符前缀（如 '/'）注册成模式会匹配一切名字
+    if (r.name && r.name.endsWith('/') && r.name.length >= (IDIOMS.nav.patternPrefixMinLen ?? 2)) addReg(r.name + '{*}', 'nav-pattern', f, lineOf(code, m.index), r.via || 'startsWith');
+  }
+}
+// 注册账可解析性保险丝：工程明显在用 Navigation（有 NavDestination(）却一条 nav 注册都没解析出来
+// —— 说明注册写法不在知识表内（Map 路由表/装饰器路由等）。此时 ghost 全量降级立案，不定罪。
+const usesNavDest = etsFiles.some(f => /\bNavDestination\s*\(/.test(src.get(f)));
+const navRegUnparseable = usesNavDest && ![...registered.values()].some(r => r.kind === 'nav' || r.kind === 'nav-pattern');
+function matchRegistered(name, tplPrefix) {
+  if (typeof name !== 'string') name = null; // AMBIG 哨兵等非串值一律当不可解析
+  if (name && registered.has(name)) return registered.get(name);
+  for (const r of registered.values()) {
+    if (!r.pattern) continue;
+    if (name && name.startsWith(r.pattern)) return r;
+    if (tplPrefix && (tplPrefix.startsWith(r.pattern) || r.pattern.startsWith(tplPrefix))) return r;
+  }
+  return null;
+}
+
+// ---------- 2) 原始跳转点采集 ----------
+const NAV_PUSH_RE = new RegExp(`\\.\\s*(${IDIOMS.nav.pushApis.join('|')})\\s*\\(`, 'g');
+const NAV_PUSHOBJ_RE = new RegExp(`\\.\\s*(?:${IDIOMS.nav.pushObjApis.join('|')})\\s*\\(\\s*\\{[\\s\\S]{0,120}?\\bname\\s*:\\s*([A-Za-z_$][\\w$.]*|['"][^'"]+['"])`, 'g');
+// 官方常见写法 pushPath(new NavPathInfo(name, …))——漏采会造成真 ghost 漏检 + orphan 假立案
+const NAV_PUSHNPI_RE = new RegExp(`\\.\\s*(?:${IDIOMS.nav.pushObjApis.join('|')})\\s*\\(\\s*new\\s+NavPathInfo\\s*\\(\\s*([A-Za-z_$][\\w$.]*|['"][^'"]+['"])`, 'g');
+const URL_PUSH_RE = new RegExp(`\\.\\s*(${IDIOMS.pageRouter.pushApis.join('|')})\\s*\\(`, 'g');
+// 匹配跑在字符串脱敏视图（blanked）上；取参回真实文本（real）——偏移两者一致
+function rawPushesIn(real, blanked, base) {
+  const out = [];
+  let m;
+  NAV_PUSH_RE.lastIndex = 0;
+  while ((m = NAV_PUSH_RE.exec(blanked)) !== null) out.push({ system: 'nav', argExpr: firstArg(real, NAV_PUSH_RE.lastIndex), idx: base + m.index });
+  NAV_PUSHOBJ_RE.lastIndex = 0;
+  while ((m = NAV_PUSHOBJ_RE.exec(real)) !== null) {
+    if (isBlankedAt(blanked, m.index)) continue;
+    out.push({ system: 'nav', argExpr: m[1], idx: base + m.index });
+  }
+  NAV_PUSHNPI_RE.lastIndex = 0;
+  while ((m = NAV_PUSHNPI_RE.exec(real)) !== null) {
+    if (isBlankedAt(blanked, m.index)) continue;
+    out.push({ system: 'nav', argExpr: m[1], idx: base + m.index });
+  }
+  URL_PUSH_RE.lastIndex = 0;
+  while ((m = URL_PUSH_RE.exec(blanked)) !== null) {
+    const a = firstArg(real, URL_PUSH_RE.lastIndex);
+    let expr = a;
+    if (a.startsWith('{')) { const u = a.match(/\burl\s*:\s*([A-Za-z_$][\w$.]*|['"][^'"]+['"]|`[^`]*`)/); expr = u ? u[1] : a; }
+    out.push({ system: 'page', argExpr: expr, idx: base + m.index, urlIndirect: !a.startsWith('{') && !/^['"`]/.test(a) ? a : null });
+  }
+  return out;
+}
+// 该偏移是否落在被脱敏的字符串内（脱敏视图该处为空格而真实文本非空格）
+function isBlankedAt(blanked, idx) { return blanked[idx] === ' '; }
+// 函数体抽取：共享库版（字符串感知括号平衡；大写开头名不当函数——ArkUI 组件/@Builder 防污染）
+// 变量→表达式 局部回溯（options.url = x / { url: x } / const v = 'lit'）
+function resolveLocalVar(body, varName, params) {
+  if (params.includes(varName)) return { param: params.indexOf(varName) };
+  let m = body.match(new RegExp(`(?:const|let)\\s+${varName}[^=\\n]*=\\s*([^;\\n]+)`));
+  if (m) {
+    const objUrl = m[1].match(/\burl\s*:\s*([A-Za-z_$][\w$.]*|['"][^'"]+['"])/);
+    const expr = objUrl ? objUrl[1] : m[1].trim();
+    if (params.includes(expr)) return { param: params.indexOf(expr) };
+    return { expr };
+  }
+  m = body.match(new RegExp(`${varName}\\.url\\s*=\\s*([^;\\n]+)`));
+  if (m) { const e = m[1].trim(); return params.includes(e) ? { param: params.indexOf(e) } : { expr: e }; }
+  return null;
+}
+
+// ---------- 3) 包装器机制（仅非组件文件），链式解析 ×3 轮 ----------
+const utilFns = new Map(); // key file::fn
+for (const [f, code] of src) {
+  if (isComponentFile(f)) continue;
+  for (const fn of functionBodies(code)) {
+    const before = code.slice(0, fn.start);
+    const cm = [...before.matchAll(/class\s+([A-Za-z_$][\w$]*)/g)].pop();
+    utilFns.set(`${f}::${fn.name}`, { ...fn, file: f, cls: cm ? cm[1] : null, routeNames: new Set(), paramSlot: -1, isWrapper: false });
+  }
+}
+// 种子：体内含原始 push 的工具函数
+for (const w of utilFns.values()) {
+  for (const p of rawPushesIn(w.body, blankStrings(w.body), 0)) {
+    let r = resolveExpr(p.argExpr);
+    if (r.kind === 'dynamic') {
+      const lv = resolveLocalVar(w.body, p.argExpr.trim(), w.params);
+      if (lv && lv.param !== undefined) { w.paramSlot = lv.param; w.isWrapper = true; continue; }
+      if (lv && lv.expr) r = resolveExpr(lv.expr);
+    }
+    if (w.params.includes(p.argExpr.trim())) { w.paramSlot = w.params.indexOf(p.argExpr.trim()); w.isWrapper = true; continue; }
+    if (r.name) { w.routeNames.add(r.name); w.isWrapper = true; }
+    else if (r.kind === 'template' && r.prefix) { w.routeNames.add(r.prefix + '{*}'); w.isWrapper = true; }
+  }
+}
+// 每文件命名导入表：裸函数跨文件调用要求 import 关联（防跨文件同名裸函数互相串账）
+const namedImports = new Map(); // f -> Map(localName -> targetFile)
+for (const [f, code] of src) {
+  const im = new Map();
+  for (const m of code.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"](\.[^'"]+)['"]/g)) {
+    const t = resolve(dirname(f), m[2]) + '.ets';
+    if (!src.has(t)) continue;
+    for (const nm of m[1].split(',').map(s => s.trim().split(/\s+as\s+/).pop())) if (nm) im.set(nm, t);
+  }
+  namedImports.set(f, im);
+}
+const bareCallLinked = (callerFile, fn) => fn.cls ? true
+  : (callerFile === fn.file || namedImports.get(callerFile)?.get(fn.name) === fn.file);
+
+// 链式：调用已知包装器的工具函数也成为包装器
+for (let round = 0; round < 3; round++) {
+  let changed = false;
+  for (const w of utilFns.values()) {
+    const wBodyBlank = blankStrings(w.body);
+    for (const t of utilFns.values()) {
+      if (!t.isWrapper || t === w) continue;
+      if (!bareCallLinked(w.file, t)) continue;
+      const callRe = t.cls ? new RegExp(`\\b(?:${t.cls}|this)\\.${t.name}\\s*\\(`, 'g') : new RegExp(`(?<![.\\w])${t.name}\\s*\\(`, 'g');
+      let m;
+      while ((m = callRe.exec(wBodyBlank)) !== null) {
+        if (t.paramSlot >= 0) {
+          const arg = firstArg(w.body, callRe.lastIndex);
+          if (w.params.includes(arg)) { if (w.paramSlot < 0) { w.paramSlot = w.params.indexOf(arg); w.isWrapper = true; changed = true; } }
+          else {
+            const r = resolveExpr(arg);
+            if (r.name && !w.routeNames.has(r.name)) { w.routeNames.add(r.name); w.isWrapper = true; changed = true; }
+          }
+        }
+        for (const n of t.routeNames) if (!w.routeNames.has(n)) { w.routeNames.add(n); w.isWrapper = true; changed = true; }
+      }
+    }
+  }
+  if (!changed) break;
+}
+const wrappers = [...utilFns.values()].filter(w => w.isWrapper);
+// 包装器体范围（同文件内互调不算外部调用者）
+const wrapperRanges = new Map();
+for (const w of wrappers) {
+  if (!wrapperRanges.has(w.file)) wrapperRanges.set(w.file, []);
+  wrapperRanges.get(w.file).push([w.start, w.end]);
+}
+const inWrapperBody = (f, idx) => (wrapperRanges.get(f) || []).some(([s, e]) => idx >= s && idx < e);
+
+// ---------- 4) 全量跳转账本 ----------
+const pushes = []; // {system,name,kind,prefix,file,line,via}
+for (const [f, code] of src) {
+  const componentFile = isComponentFile(f);
+  for (const p of rawPushesIn(code, bl(f), 0)) {
+    if (!componentFile && inWrapperBody(f, p.idx)) continue; // 包装器体内的原始 push 由调用点计
+    const r = resolveExpr(p.argExpr);
+    pushes.push({ system: p.system, name: r.name, kind: r.kind, prefix: r.prefix, file: f, line: lineOf(code, p.idx), via: r.via || p.argExpr.slice(0, 50) });
+  }
+  for (const w of wrappers) {
+    if (!bareCallLinked(f, w)) continue; // 裸函数：无 import 关联的同名调用不记账
+    const callRe = w.cls ? new RegExp(`\\b${w.cls}\\.${w.name}\\s*\\(`, 'g') : new RegExp(`(?<![.\\w])${w.name}\\s*\\(`, 'g');
+    let m;
+    const blanked = bl(f);
+    while ((m = callRe.exec(blanked)) !== null) {
+      if (f === w.file) continue; // 定义文件内（含链式互调）不算外部调用
+      w.externalCallers = (w.externalCallers || 0) + 1;
+      const label = `${w.cls ? w.cls + '.' : ''}${w.name}`;
+      if (w.paramSlot >= 0) {
+        const r = resolveExpr(firstArg(code, callRe.lastIndex));
+        pushes.push({ system: 'nav', name: r.name, kind: r.name ? 'wrapper-arg' : r.kind, prefix: r.prefix, file: f, line: lineOf(code, m.index), via: `${label}(${(r.via || r.name || '')})` });
+      }
+      for (const n of w.routeNames) {
+        pushes.push({ system: 'nav', name: n.replace('{*}', ''), kind: 'wrapper-fixed', prefix: n.endsWith('{*}') ? n.replace('{*}', '') : undefined, file: f, line: lineOf(code, m.index), via: `${label}()→'${n}'` });
+      }
+    }
+  }
+}
+// 死包装器（固定路由名但外部零调用）
+const deadEntries = new Map();
+for (const w of wrappers) {
+  if ((w.externalCallers || 0) > 0) continue;
+  for (const n of w.routeNames) {
+    deadEntries.set(n.replace('{*}', ''), `${w.cls ? w.cls + '.' : ''}${w.name}() @${rel(w.file)} 内含该跳转，但全工程零调用方`);
+  }
+}
+// soft-credit
+const constByLiteral = new Map();
+for (const [k, v] of constMap) if (typeof v === 'string' && matchRegistered(v, null)) constByLiteral.set(k, v);
+const inferred = [];
+for (const [f, code] of src) {
+  if (!pushes.some(p => p.file === f && p.kind === 'dynamic')) continue;
+  for (const [ident, lit] of constByLiteral) {
+    if (new RegExp(`\\b${ident.replace('.', '\\.')}\\b`).test(code)) inferred.push({ system: 'nav', name: lit, kind: 'inferred', file: f, line: 0, via: `动态跳转文件引用常量 ${ident}` });
+  }
+}
+
+// ---------- 5) 入口连通 ----------
+const importGraph = new Map();
+for (const [f, code] of src) {
+  const outs = [];
+  for (const m of code.matchAll(/import\s+[^;]*?from\s+['"](\.[^'"]+)['"]/g)) {
+    const t = resolve(dirname(f), m[1]) + '.ets';
+    if (src.has(t)) outs.push(t);
+  }
+  importGraph.set(f, outs);
+}
+function closureOf(starts) {
+  const seen = new Set(starts); const q = [...starts];
+  while (q.length) for (const t of importGraph.get(q.pop()) || []) if (!seen.has(t)) { seen.add(t); q.push(t); }
+  return seen;
+}
+const routeFile = new Map();
+for (const r of registered.values()) {
+  if (r.kind === 'page') {
+    const cand = etsFiles.find(f => rel(f).replace(/\\/g, '/').endsWith(`ets/${r.name}.ets`));
+    if (cand) routeFile.set(r.name, cand);
+  }
+}
+// systemRouterMap 的 pageSourceFile 是权威映射（Index 无 pageMap 时唯一来源）
+for (const [name, file] of rmPageFile) if (src.has(file) && !routeFile.has(name)) routeFile.set(name, file);
+for (const f of regFiles) {
+  const code = src.get(f);
+  const imports = new Map();
+  for (const m of code.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"](\.[^'"]+)['"]/g)) {
+    for (const nm of m[1].split(',').map(s => s.trim().split(/\s+as\s+/).pop())) {
+      const t = resolve(dirname(f), m[2]) + '.ets';
+      if (src.has(t)) imports.set(nm, t);
+    }
+  }
+  for (const m of code.matchAll(/(?:\bname\b|\brouteName\b)\s*===?\s*([A-Za-z_$][\w$.]*|['"][^'"]+['"])[\s\S]{0,80}?([A-Za-z_$][\w$]*)\s*\(/g)) {
+    const r = resolveExpr(m[1]);
+    const target = imports.get(m[2]) || imports.get(m[2].replace(/Builder$/, ''));
+    if (r.name && target && !routeFile.has(r.name)) routeFile.set(r.name, target);
+  }
+}
+const entryFiles = etsFiles.filter(f => /@Entry\b/.test(src.get(f)));
+const abilityLoads = [];
+for (const [, code] of src) for (const m of code.matchAll(/loadContent\s*\(\s*(['"])((?:(?!\1).)*)\1/g)) abilityLoads.push(m[2]);
+let roots = entryFiles.filter(f => abilityLoads.some(l => rel(f).replace(/\\/g, '/').endsWith(`ets/${l}.ets`)));
+if (roots.length === 0) roots = entryFiles;
+if (PROFILE.entryFiles) roots.push(...PROFILE.entryFiles.map(p => resolve(PROJECT, p)).filter(p => src.has(p)));
+const rootRouteNames = new Set(entryRootPages.concat(abilityLoads));
+// 注：死包装器不会产生调用点 push，故无需按名过滤——按名过滤会误杀同名路由的其他真实入口
+const livePushes = [...pushes, ...inferred].filter(p => p.name || p.prefix);
+
+const reachable = new Set();
+for (const r of registered.values()) {
+  const bare = r.name.replace('{*}', '');
+  if (rootRouteNames.has(bare) || roots.some(f => routeFile.get(bare) === f)) reachable.add(r.name);
+}
+let frontier = closureOf(roots);
+let changed = true;
+while (changed) {
+  changed = false;
+  for (const p of livePushes) {
+    if (!frontier.has(p.file)) continue;
+    const reg = matchRegistered(p.name, p.prefix);
+    if (reg && !reachable.has(reg.name)) {
+      reachable.add(reg.name);
+      changed = true;
+      const rf = routeFile.get(reg.name.replace('{*}', ''));
+      if (rf) for (const x of closureOf([rf])) frontier.add(x);
+    }
+  }
+}
+
+// ---------- 5b) 首屏链路（冷启第一跳逐跳走到首个实义页）----------
+// 静态门管两件确定性事实：①链上每跳可注册解析 ②链尾不是 wire 骨架占位页
+// （骨架判定用 wire-routes 生成物的固定占位标记——TODO(切片) 页面内容行）。
+// 转发页近似：页内含 replace 调用即视为转发页，取其行号最小跳转继续走；≤3 跳防环。
+const SCAFFOLD_MARK = /TODO\(切片\): 页面内容/;
+const DBG_CHAIN = !!process.env.DEBUG_CHAIN;
+const entryChainFindings = [];
+if (DBG_CHAIN) console.error(`[chain] roots=${roots.map(rel).join(',')}`);
+for (const root of roots) {
+  let cur = livePushes.filter(p => p.file === root && p.name).sort((a, b) => a.line - b.line)[0];
+  if (DBG_CHAIN) console.error(`[chain] root=${rel(root)} first=${cur ? cur.name : '(无)'}`);
+  const chain = [rel(root)];
+  const seenHop = new Set();
+  for (let hop = 0; cur && hop < 3; hop++) {
+    const reg = matchRegistered(cur.name, cur.prefix);
+    if (!reg || seenHop.has(reg.name)) break; // 未注册由 ghost 门定罪，此处不重复立案
+    seenHop.add(reg.name);
+    chain.push(reg.name);
+    const pf = routeFile.get(reg.name.replace('{*}', ''));
+    if (DBG_CHAIN) console.error(`[chain] hop${hop} ${reg.name} → file=${pf ? rel(pf) : '(未映射)'}`);
+    if (!pf) break;
+    const pcode = src.get(pf);
+    // 骨架标记在注释里——src 是去注释视图，须读原文判定
+    if (SCAFFOLD_MARK.test(readFileSync(pf, 'utf8'))) {
+      entryChainFindings.push({ type: 'entry_chain_scaffold', severity: 'case', name: reg.name,
+        basis: '判据：冷启链路静态走查落在 wire 骨架占位页——首屏是占位模板不是实义页',
+        evidence: `${chain.join(' → ')} 止于骨架页 ${rel(pf)}（占位标记仍在）。修复=实现该页，或校正上游转发目标（转发语义：splash/launcher 应转发到源 app 主 NavHost 首 destination 的等价页）` });
+      break;
+    }
+    if (!/\.\s*replace\s*\(/.test(pcode)) break; // 非转发页 = 实义首页，链闭合
+    cur = livePushes.filter(p => p.file === pf && p.name).sort((a, b) => a.line - b.line)[0];
+  }
+}
+
+// ---------- 6) 裁决 ----------
+const findings = [];
+const IGNORE = new Set(PROFILE.ignoreRoutes || []);
+findings.push(...entryChainFindings);
+for (const p of pushes) {
+  if (['literal', 'const', 'enum', 'wrapper-arg', 'wrapper-fixed'].includes(p.kind) && p.name && !matchRegistered(p.name, null)) {
+    if (p.system === 'nav' && navRegUnparseable) {
+      findings.push({ type: 'ghost_route_unverifiable', severity: 'case', name: p.name, basis: '判据：跳转名未见于注册账，但注册账不可解析（工程在用 Navigation 而未解析出任何 nav 注册——写法不在知识表内），不定罪待裁决', evidence: `${rel(p.file)}:${p.line} 经 ${p.via} 跳转；注册写法请回源码裁决，普适写法请修订 idioms.json` });
+    } else {
+      findings.push({ type: 'ghost_route', severity: 'violation', name: p.name, basis: '判据：可解析跳转名未出现在任何注册账（pageMap比较/main_pages/模式前缀）——运行时必失败', evidence: `${rel(p.file)}:${p.line} 经 ${p.via} 跳转，但该名未在任何注册表出现（运行时必失败）` });
+    }
+  }
+}
+const pushedKeys = new Map();
+for (const p of [...pushes, ...inferred]) {
+  const reg = matchRegistered(p.name, p.prefix);
+  if (!reg) continue;
+  if (!pushedKeys.has(reg.name)) pushedKeys.set(reg.name, []);
+  pushedKeys.get(reg.name).push(p);
+}
+// ---------- 6a) 注册页骨架残留（全部注册路由，不只冷启链）----------
+// 三道防线同漏的实证：5 个注册路由页到收尾仍是 wire 骨架（实现写在别的目录、壳从未挂载），
+// 静态门只查首屏链、smoke 假绿、verify 只读实现文件。判据确定性：注册页文件仍含占位标记。
+// 阶段语义：slice 阶段其他片未实现属正常，不立案；integration 立案（case）；final 硬违规（实现或删注册，不许豁免）。
+if (STAGE !== 'slice') {
+  for (const [name, file] of rmPageFile) {
+    if (IGNORE.has(name)) continue;
+    if (!existsSync(file)) {
+      findings.push({ type: 'route_page_missing', severity: 'violation', name, basis: '判据：route_map 注册的 pageSourceFile 不存在——hvigor ProcessRouterMap 必失败', evidence: `${rel(file)} 缺失（删注册或补页面）` });
+      continue;
+    }
+    if (!SCAFFOLD_MARK.test(readFileSync(file, 'utf8'))) continue;
+    const ps = pushedKeys.get(name) || [];
+    findings.push({ type: 'scaffold_page_residue', severity: STAGE === 'final' ? 'violation' : 'case', name,
+      basis: '判据：注册路由页仍是 wire 骨架占位（TODO(切片) 页面内容标记在）——用户可达的是占位模板，不是实义页',
+      evidence: `${rel(file)} 占位标记仍在${ps.length ? `，且有 ${ps.length} 处跳转可达（${ps.slice(0, 2).map(p => rel(p.file) + ':' + p.line).join(', ')}）` : '，无静态跳转（确属不迁移的页：从 route_map 删注册并删骨架文件）'}。修复=实现该页（拥有它的切片 targetPath 必须含此文件；用 only 续跑该片）` });
+  }
+}
+// 可靠性规则：只要工程里存在**无法静态解析的跳转点**（变量/函数返回值/对象字段/模板拼名——实证 45 工程里每家形态都不同：
+// 类字段承载、SettingsRouter 返回字符串、DrawerItem 数据表、`${x}Page` 拼名），就不能证明任何一条注册路由是孤儿——
+// 此时 orphan 只记 info（附动态跳转点清单），不立案；全部跳转都解析得开时才立案。实证：coolmall 31/35、antennapod-ds 53/85、
+// quillpad 6/16 的 orphan 立案抽样全是误报，模型一张 .* 票整体豁免，门形同虚设。
+const dynamicPushes = pushes.filter(p => !p.name && !p.prefix);
+for (const r of registered.values()) {
+  if (IGNORE.has(r.name) || reachable.has(r.name) && (pushedKeys.get(r.name) || []).length) continue;
+  const bare = r.name.replace('{*}', '');
+  if (rootRouteNames.has(bare)) continue;
+  const ps = pushedKeys.get(r.name) || [];
+  if (ps.length === 0) {
+    if (deadEntries.has(bare)) findings.push({ type: 'dead_entry_route', severity: 'case', name: r.name, basis: '判据：该路由的全部跳转都在零外部调用的包装器方法体内', evidence: `唯一入口 ${deadEntries.get(bare)}` });
+    else if (dynamicPushes.length) findings.push({ type: 'orphan_route', severity: 'info', name: r.name, basis: '判据：无可解析跳转，但工程有无法静态解析的跳转点——不能证明孤儿，不立案', evidence: `已注册（${r.file}:${r.line}）但静态未见跳转；工程另有 ${dynamicPushes.length} 处动态跳转（${dynamicPushes.slice(0, 3).map(p => rel(p.file) + ':' + p.line).join(', ')}）可能指向它——4b 走查核可达性` });
+    else findings.push({ type: 'orphan_route', severity: 'case', name: r.name, basis: '判据：已注册但全工程无可静态解析的跳转，且工程无任何动态跳转点（深链/通知/卡片入口属合法豁免）', evidence: `已注册（${r.file}:${r.line}）但全工程未发现可解析跳转；若为深链/通知/卡片入口请在 profile.ignoreRoutes 豁免` });
+  } else if (!reachable.has(r.name)) {
+    findings.push({ type: 'unreachable_route', severity: 'case', name: r.name, basis: '判据：存在跳转但发起文件不在入口 import 闭包内', evidence: `存在跳转（${ps.slice(0, 2).map(p => rel(p.file) + ':' + p.line).join(', ')}）但从入口连通图不可达` });
+  }
+}
+const unresolved = pushes.filter(p => !p.name && !p.prefix).map(p => ({ file: rel(p.file), line: p.line, via: p.via, kind: p.kind }));
+if (navRegUnparseable) findings.push({ type: 'nav_registry_unparseable', severity: 'case', name: '(registry)', basis: '判据：存在 NavDestination( 但未解析出任何 nav 注册条目', evidence: '注册写法不在知识表（idioms.json nav.*）内——人工回源码确认注册机制，普适写法回写知识表' });
+
+const report = {
+  project: relative(process.cwd(), resolve(PROJECT)) || '.',
+  stats: {
+    etsFiles: etsFiles.length, registered: registered.size,
+    pushSites: pushes.length, resolved: pushes.filter(p => p.name || p.prefix).length,
+    inferred: inferred.length, dynamic: unresolved.length,
+    wrappers: wrappers.map(w => ({ fn: (w.cls ? w.cls + '.' : '') + w.name, file: rel(w.file), names: [...w.routeNames], paramSlot: w.paramSlot, externalCallers: w.externalCallers || 0 })),
+    entryRoots: roots.map(rel), reachable: [...reachable],
+  },
+  registered: [...registered.values()],
+  findings, unresolved,
+};
+if (OUT) writeFileSync(OUT, JSON.stringify(report, null, 2));
+const vio = findings.filter(f => f.severity === 'violation');
+const cases = findings.filter(f => f.severity === 'case');
+console.log(`[check-routes] ${resolve(PROJECT)}`);
+console.log(`  注册 ${registered.size} · 跳转点 ${pushes.length}（解析 ${report.stats.resolved} 推断 ${inferred.length} 动态 ${unresolved.length}） · 可达 ${reachable.size} · 包装器 ${wrappers.length}`);
+for (const f of vio) console.log(`  ✗ VIOLATION ${f.type} [${f.name}] — ${f.evidence}`);
+for (const f of cases) console.log(`  ▲ CASE      ${f.type} [${f.name}] — ${f.evidence}`);
+if (!vio.length && !cases.length) console.log('  ✓ 三本账闭合，无立案');
+process.exit(vio.length ? 10 : (STRICT && cases.length ? 2 : 0));

package/skills/migrate-core/scripts/closure/check-safearea.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * check-safearea.mjs — 安全区/布局保真度门（补门禁盲区：edge-to-edge 页顶部避让脆弱→内容压系统状态栏下）。
+ *
+ * 病根：迁移把安卓沉浸式（setWindowLayoutFullScreen(true)）映射到鸿蒙后，需给顶部内容叠加系统避让
+ * （statusBar 高度）。三类脆弱（均为真机实证）：
+ *   ① 竞态门控：inset 赋值被 `if(!isLayoutFullScreen) return` 早退挡住——与全屏设置竞态，回调早于生效则 inset=0；
+ *   ② 取一次不订阅：getWindowAvoidArea 只算一次、全工程无 avoidAreaChange 重挂——初值/旋转/多窗后 inset 卡 0；
+ *   ③ 页面根本不消费：壳层建好了避让基建（全局 insets 服务），但某些导航页既不引用它也不自取避让——
+ *      "每页手动消费"模式必然漏页（两轮真机重合实证，且漏的页每轮不同——系统病）。
+ *
+ * 判定全为**软立案**（case）——竞态/消费与否静态无法定罪（全屏页、对话框、时序确稳皆属合法），
+ * 绝不设硬违规、恒退 0：由 closure-suite final 阶段汇总，模型逐条回源裁决（真重合→修；合法→带理由豁免）。
+ * 报告措辞不许造成"零违规=安全区没问题"的误导——立案数与检查覆盖数都必须打出来。
+ *
+ * 用法：check-safearea.mjs --project <鸿蒙工程根> [--json out]　退出码：0（软立案不失败）/ 3 用法错
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve, dirname } from 'node:path';
+import { walkFiles, stripComments, moduleSrcRoots } from '../lib/scan.mjs';
+
+const argv = process.argv.slice(2);
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const PROJECT = argOf('--project', null);
+if (!PROJECT) { console.error('usage: check-safearea.mjs --project <root> [--json out]'); process.exit(3); }
+
+const rel = f => relative(resolve(PROJECT), f).replace(/\\/g, '/');
+const escRe = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// 全模块扫描（entry + 任意 HSP/HAR 模块）
+const files = moduleSrcRoots(resolve(PROJECT)).flatMap(r => [...walkFiles(r, { match: (_p, e) => e.endsWith('.ets') })]);
+const texts = new Map(files.map(f => [f, stripComments(readFileSync(f, 'utf8'))]));
+const edgeToEdge = [...texts.values()].some(c => /setWindowLayoutFullScreen\s*\(\s*true\s*\)/.test(c));
+const projHasAvoidChange = [...texts.values()].some(c => /avoidAreaChange/.test(c));
+
+// 全局 insets 提供者识别（全部为显式语义链，无黑名单）：调 getWindowAvoidArea 的文件里——
+//   a) 该文件导出的声明（provider 与存储同文件的形态）；
+//   b) 写入的 AppStorage 键（键名即消费凭据）；
+//   c) 该文件 **import 进来且在文件内被赋值** 的标识符（provider 写外部存储的形态——
+//      import+赋值双条件是显式跨文件链，杜绝把内置全局名误当提供者）。
+// 页面凡引用其一（或自取避让/expandSafeArea）即视为"消费了避让"。
+const providerNames = new Set();
+for (const code of texts.values()) {
+  if (!/getWindowAvoidArea/.test(code)) continue;
+  for (const m of code.matchAll(/export\s+(?:default\s+)?(?:@\w+\s+)*(?:class|struct|const|let|function|enum)\s+([A-Za-z_$][\w$]*)/g)) providerNames.add(m[1]);
+  for (const m of code.matchAll(/AppStorage\.setOrCreate\(\s*['"]([^'"]+)['"]/g)) providerNames.add(m[1]);
+  const imported = [];
+  // 四形态：命名 { a, b as c } / 默认 x / 混合 x, { y } / 命名空间 * as ns
+  for (const m of code.matchAll(/import\s+(?:([A-Za-z_$][\w$]*)\s*,\s*)?(?:\{([^}]*)\}|\*\s+as\s+([A-Za-z_$][\w$]*)|([A-Za-z_$][\w$]*))\s*from/g)) {
+    if (m[1]) imported.push(m[1]);
+    if (m[2]) imported.push(...m[2].split(',').map(s => s.trim().split(/\s+as\s+/).pop()).filter(Boolean));
+    if (m[3]) imported.push(m[3]);
+    if (m[4]) imported.push(m[4]);
+  }
+  for (const n of imported) if (new RegExp(`\\b${escRe(n)}\\b\\s*[.\\[][^=\n]*=(?!=)`).test(code)) providerNames.add(n);
+}
+
+// import 链传播（结构判据：相对 import 解析到工程文件，链长不限，memo 兼作环守卫；不看组件名）
+const avoidMemo = new Map();
+function resolveRel(from, spec) { const base = resolve(dirname(from), spec); for (const c of [base, base + '.ets', base + '.ts', join(base, 'index.ets'), join(base, 'index.ts')]) if (texts.has(c)) return c; return null; }
+function avoidsViaImport(file) {
+  if (avoidMemo.has(file)) return avoidMemo.get(file);
+  avoidMemo.set(file, false);
+  const code = texts.get(file) || '';
+  let ok = false;
+  for (const m of code.matchAll(/from\s+['"](\.[^'"]+)['"]/g)) {
+    const t = resolveRel(file, m[1]); if (!t) continue;
+    const c2 = texts.get(t) || '';
+    if (/expandSafeArea|getWindowAvoidArea|avoidAreaChange/.test(c2) || [...providerNames].some(n => n && new RegExp(`\\b${escRe(n)}\\b`).test(c2)) || avoidsViaImport(t)) { ok = true; break; }
+  }
+  avoidMemo.set(file, ok);
+  return ok;
+}
+
+const findings = [];
+let insetFiles = 0, pagesChecked = 0;
+if (edgeToEdge) {
+  for (const f of files) {
+    const code = texts.get(f);
+    const line = (re) => { const m = code.match(re); return m ? code.slice(0, m.index).split('\n').length : 0; };
+    const takesTopInset = /getWindowAvoidArea/.test(code) && /topRect|TYPE_SYSTEM/.test(code);
+    if (takesTopInset) {
+      insetFiles++;
+      // ① 竞态门控（概率性脆弱）
+      if (/isLayoutFullScreen[\s\S]{0,80}?\breturn\b/.test(code)) {
+        findings.push({ severity: 'case', type: 'racy_safearea_gate', name: rel(f), file: rel(f),
+          line: line(/isLayoutFullScreen/),
+          evidence: `${rel(f)}:${line(/isLayoutFullScreen/)} 顶部避让 inset 被 isLayoutFullScreen 早退门控——与 setWindowLayoutFullScreen 竞态，回调早于全屏生效则 inset=0（裁决：去早退+avoidAreaChange 重挂，或时序确稳则豁免）` });
+      }
+      // ② 取一次不订阅（全工程无 avoidAreaChange 才立案——有中央重挂经全局态分发即合法）
+      if (!/avoidAreaChange/.test(code) && !projHasAvoidChange) {
+        findings.push({ severity: 'case', type: 'stale_inset_no_subscription', name: rel(f), file: rel(f),
+          line: line(/getWindowAvoidArea/),
+          evidence: `${rel(f)}:${line(/getWindowAvoidArea/)} 取顶部避让但全工程无 avoidAreaChange 订阅——初值/旋转/多窗变化后 inset 卡死（裁决：中央订阅重算入全局态，或证明场景不变则豁免）` });
+      }
+    }
+    // ③ 导航页不消费避让（页判定纯语义：含 NavDestination/@Entry 即页，不靠目录名约定）
+    const isPage = /NavDestination\s*\(|@Entry\b/.test(code);
+    if (isPage) {
+      pagesChecked++;
+      const selfAvoids = /expandSafeArea|getWindowAvoidArea|avoidAreaChange/.test(code);
+      const consumesProvider = [...providerNames].some(n => n && new RegExp(`\\b${escRe(n)}\\b`).test(code));
+      // 页面把避让委托给它 import 的组件（AppScaffold/TopBar 之类）也算消费：沿相对 import 走 ≤3 跳，被引文件自取避让或引用提供者即可
+      if (!selfAvoids && !consumesProvider && avoidsViaImport(f)) { continue; }
+      if (!selfAvoids && !consumesProvider) {
+        findings.push({ severity: 'case', type: 'page_top_unavoided', name: rel(f), file: rel(f), line: 1,
+          evidence: `${rel(f)} 导航页在 edge-to-edge 工程中未见任何顶部避让（不引用全局 insets 提供者${providerNames.size ? `[${[...providerNames].slice(0, 4).join('/')}…]` : ''}、无 expandSafeArea/自取避让）——顶部内容可能压状态栏（裁决：接全局 insets 顶部 padding，或该页确属全出血/无顶置内容则豁免）` });
+      }
+    }
+  }
+}
+
+const cases = findings.filter(f => f.severity === 'case');
+const byType = (t) => cases.filter(c => c.type === t).length;
+const report = { project: relative(process.cwd(), resolve(PROJECT)) || '.', edgeToEdge, stats: { insetFiles, pagesChecked, providers: [...providerNames] }, findings };
+const out = argOf('--json', null);
+if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(out, JSON.stringify(report, null, 2)); }
+console.log(`[check-safearea] edge-to-edge:${edgeToEdge ? '是' : '否'} · 取顶部avoid文件 ${insetFiles} · 页面消费检查 ${pagesChecked} 页 · 软立案 ${cases.length}（竞态${byType('racy_safearea_gate')}/失订${byType('stale_inset_no_subscription')}/页未避让${byType('page_top_unavoided')}）`);
+for (const c of cases.slice(0, 12)) console.log(`  ▲ ${c.evidence}`);
+if (!cases.length) console.log(edgeToEdge ? `  ✓ 未发现脆弱写法（软证据：本门非确定性，真机走查仍须逐页顺检顶部重合）` : '  ✓ 非 edge-to-edge，系统自动避让');
+// 软立案不让 checker 失败（恒退 0）——closure-suite final 阶段汇总裁决，绝不逼修
+process.exit(0);