android2harmony 0.1.4 → 0.1.6

package/skills/a2h-ui-transfer/scripts/arkts_static_check.js

@@ -0,0 +1,1624 @@
+/**
+ * arkts_static_check — 转换后 ArkTS 代码的静态缺陷检查器。
+ *
+ * 定位:补上「编译期发现不了、但纯词法即可判定」的那一类缺陷。
+ * 纯 JavaScript(ESM),直接 node 运行,无需构建、无依赖:
+ *
+ *   node arkts_static_check.js --ets <harmony_project>/<ui_module>/src/main/ets \
+ *                             [--resources <harmony_project>/<ui_module>/src/main/resources]
+ *   <ui_module> 不一定是 entry;分层工程如 products/phone。
+ *
+ * 输出分两段,语义完全不同:
+ *
+ *   [GATE]       零歧义缺陷。**必须清零**,否则 exit code 1。
+ *   [CANDIDATES] 仅缩小人工核对范围,**不判定对错**、不影响 exit code。
+ *                这些位置合法与否取决于 Android 源侧的意图(锚定方向、层叠次序),
+ *                词法分析无法判断 —— 由 Phase 5 对应检查项逐条标注来源。
+ *
+ * 设计要点:先把注释替换成等长空白再匹配。否则「解释某个坑」的文档注释
+ * 本身就会被当成那个坑命中 —— 检查器被自己要防的说明骗了。
+ *
+ * 注:R7/R8/R9 需要 --resources,因为它们要读 SVG 文件内容(而非只看代码);
+ * 未传 --resources 时这些规则整条跳过,与 string.json 检查一致。
+ *
+ * R7/R8/R9 共同针对同一个失效模式:**「资源存在」不等于「资源能渲染对」**。
+ * 页面转换时惯于用 `ls media/` 确认名字存在就通过,从不打开文件,于是
+ * 「引用名正确 + 文件存在 + 编译通过」三项全过,图标却是黑块/白框/灰框。
+ *
+ * R11(entry-route-not-converted)针对另一个同源模式:
+ * **「注册过」不等于「会被加载」**。main_pages.json 里有某页只说明它可被路由到,
+ * 真正决定启动画面的是 UIAbility 的 loadContent()。二者不一致时编译与静态引用
+ * 检查全过,唯一症状是启动后停在脚手架的 Hello World,转换成果一次也没显示过 ——
+ * 只有真机启动能看见,但判据完全是词法的,故定为 GATE。
+ * 它以「工程内已有转换产出页」为前提:空工程加载脚手架页是正确状态,不报。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const BACKTICK = String.fromCharCode(96);
+
+// type Severity = 'GATE' | 'CAND';
+
+// interface Finding {
+  // sev: Severity;
+  // rule: string;
+  // file: string;
+  // line: number;
+  // msg: string;
+// }
+
+const findings = [];
+
+function report(sev, rule, file, line, msg) {
+  findings.push({ sev, rule, file, line, msg });
+}
+
+// ---------------------------------------------------------------- 预处理
+
+/**
+ * 把注释替换成等长空白,保持行号与列号不变。
+ * 字符串与模板字符串内的 // 和 /* 不算注释。
+ */
+function stripComments(src) {
+  let out = '';
+  let i = 0;
+  let state = 0; // 0 code, 1 line-comment, 2 block-comment, 3 string, 4 template
+  let quote = '';
+
+  while (i < src.length) {
+    const c = src[i];
+    const n = src[i + 1];
+
+    if (state === 0) {
+      if (c === '/' && n === '/') { state = 1; i += 2; out += '  '; continue; }
+      if (c === '/' && n === '*') { state = 2; i += 2; out += '  '; continue; }
+      if (c === '"' || c === "'") { state = 3; quote = c; out += c; i++; continue; }
+      if (c === BACKTICK) { state = 4; out += c; i++; continue; }
+      out += c; i++; continue;
+    }
+    if (state === 1) {
+      if (c === '\n') { state = 0; out += '\n'; } else { out += ' '; }
+      i++; continue;
+    }
+    if (state === 2) {
+      if (c === '*' && n === '/') { state = 0; i += 2; out += '  '; continue; }
+      out += (c === '\n' ? '\n' : ' '); i++; continue;
+    }
+    if (state === 3) {
+      out += c;
+      if (c === '\\') { out += (src[i + 1] || ''); i += 2; continue; }
+      if (c === quote) { state = 0; }
+      i++; continue;
+    }
+    // state === 4
+    out += c;
+    if (c === '\\') { out += (src[i + 1] || ''); i += 2; continue; }
+    if (c === BACKTICK) { state = 0; }
+    i++;
+  }
+  return out;
+}
+
+/** 标记哪些行处于 /* ... *\/ 块注释内部(用于「注释提前闭合」检查)。 */
+function blockCommentLines(src) {
+  const inside = new Set();
+  let depth = 0;
+  const lines = src.split('\n');
+
+  for (let idx = 0; idx < lines.length; idx++) {
+    if (depth > 0) { inside.add(idx + 1); }
+    const line = lines[idx];
+    let i = 0;
+    while (i < line.length) {
+      if (line[i] === '/' && line[i + 1] === '*') { depth++; inside.add(idx + 1); i += 2; continue; }
+      if (line[i] === '*' && line[i + 1] === '/') { if (depth > 0) { depth--; } i += 2; continue; }
+      if (line[i] === '/' && line[i + 1] === '/' && depth === 0) { break; }
+      i++;
+    }
+  }
+  return inside;
+}
+
+/**
+ * 把代码切成「属性链块」:组件行 + 其后连续的 .xxx() 行。
+ * 同一元素的属性共现判定必须在链内进行,否则会跨元素误判。
+ */
+// interface Chain {
+  // start: number;      // 1-based 行号
+  // lines: string[];
+// }
+
+function attributeChains(codeLines) {
+  const chains = [];
+  let cur = null;
+
+  for (let i = 0; i < codeLines.length; i++) {
+    const line = codeLines[i];
+    if (/^\s*\./.test(line)) {
+      if (cur === null) {
+        // 链首行取上一行(组件调用行)
+        cur = { start: i, lines: [codeLines[i - 1] || ''] };
+      }
+      cur.lines.push(line);
+    } else if (cur !== null) {
+      chains.push(cur);
+      cur = null;
+    }
+  }
+  if (cur !== null) { chains.push(cur); }
+  return chains;
+}
+
+// ---------------------------------------------------------------- 逐文件规则
+
+const RE_PCT_WIDTH = /\.width\((['"])100%\1\)/;
+const RE_PCT_HEIGHT = /\.height\((['"])100%\1\)/;
+const RE_H_MARGIN = /\.margin\(\s*\{[^}]*(left|right|start|end)\s*:/;
+// interface GetterHit {
+  // name: string;
+  // line: number;
+// }
+
+// interface ObservedTrackClass {
+  // name: string;
+  // getters: GetterHit[];
+// }
+
+/**
+ * 找出所有「带 @Observed 且类体内至少有一个 @Track」的类,并列出该类体内声明的 getter。
+ *
+ * 为什么按类体而不是整文件:一个 .ets 里常常同时有 @Observed 的 VM/Model 和普通
+ * class / interface(如纯数据的 DTO、工具类),整文件判定会把后者的 getter 也算进来。
+ * 类体范围用花括号配对求得(注释已在 stripComments 阶段被替换成等长空白,
+ * 因此不会有注释里的花括号干扰配对)。
+ */
+function observedTrackClassBodies(code, codeLines) {
+  const out = [];
+  // @Observed 之后允许有若干行(export / 注释留下的空行)再到 class 声明
+  const reClass = /@Observed[\s\S]{0,200}?\bclass\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = reClass.exec(code)) !== null) {
+    const clsName = m[1];
+    // 从 class 声明之后的第一个 { 开始做花括号配对,求出类体范围
+    const open = code.indexOf('{', m.index + m[0].length);
+    if (open < 0) {
+      continue;
+    }
+    let depth = 0;
+    let end = -1;
+    for (let i = open; i < code.length; i++) {
+      const c = code[i];
+      if (c === '{') {
+        depth++;
+      } else if (c === '}') {
+        depth--;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    if (end < 0) {
+      continue;
+    }
+    const body = code.slice(open, end);
+    // 只有类体内真的用了 @Track 才受本约束(全无 @Track 的类走的是整类观测,不报)
+    if (!/@Track\b/.test(body)) {
+      continue;
+    }
+    const bodyStartLine = code.slice(0, open).split('\n').length;
+    const getters = [];
+    const bodyLines = body.split('\n');
+    for (let i = 0; i < bodyLines.length; i++) {
+      // `get name()` —— 必须排除 `getXxx()` 普通方法,故 get 后要求空白
+      const g = /^\s*(?:public\s+|private\s+|protected\s+)?get\s+([A-Za-z_$][\w$]*)\s*\(\s*\)/.exec(bodyLines[i]);
+      if (g) {
+        getters.push({ name: g[1], line: bodyStartLine + i });
+      }
+    }
+    if (getters.length > 0) {
+      out.push({ name: clsName, getters });
+    }
+  }
+  void codeLines;
+  return out;
+}
+
+const RE_V1_DECO = /^\s*@(State|Prop|Link|Observed|Track|Provide|Consume|Watch|CustomDialog)\b/gm;
+const RE_V2_DECO = /^\s*@(Local|Param|Once|Event|ObservedV2|Trace|Monitor|Computed|Provider|Consumer)\b/gm;
+
+/**
+ * ArkUI 通用属性方法名 —— CustomComponent 基类已把它们定义为方法,
+ * 自定义组件里再声明同名**状态字段**会冲突(编译期 10505001)。
+ * 取自 SDK common.d.ts 的 CommonMethod,只收最容易被当成字段名的那些。
+ */
+const RESERVED_ATTR_NAMES = new Set([
+  'size', 'width', 'height', 'margin', 'padding', 'position', 'scale', 'opacity',
+  'border', 'clip', 'visibility', 'direction', 'align', 'offset', 'rotate',
+  'translate', 'zIndex', 'enabled', 'id', 'key'
+]);
+
+// interface TintedMedia {
+  // name: string;
+  // line: number;
+// }
+
+// interface FileScan {
+  // rel: string;
+  // hasExpandSafeArea: boolean;
+  // isPage: boolean;
+  // hasWindowFullScreen: boolean;
+  // tinted: TintedMedia[];
+  // /** 本文件引用的**全部** app.media.X(不限于被染色的),供媒体内容体检使用。 */
+  // mediaRefs: TintedMedia[];
+  // text: string; // 去注释后的代码文本,供 checkWindowMode 使用
+// }
+
+function checkFile(file, rel) {
+  const src = fs.readFileSync(file, 'utf8');
+  const code = stripComments(src);
+  const rawLines = src.split('\n');
+  const codeLines = code.split('\n');
+  const inBlock = blockCommentLines(src);
+
+  // ---- GATE R1:块注释被 */ 序列提前闭合
+  // 典型来源:把含通配符的证据路径(如 foo_*/view.xml)写进 JSDoc。
+  // 后果:其后正文被当作代码解析,编译器报出大量指向注释正文的假坐标错误。
+  for (let i = 0; i < rawLines.length; i++) {
+    if (!inBlock.has(i + 1)) { continue; }
+    // 判据:块内任何位置出现 */ 都会闭合外层注释,**与它后面跟什么无关**。
+    // 早期版本用 /\*\/[^\s]/(要求 */ 后紧跟非空白),只抓到 foo_*(斜杠)view.xml 这类,
+    // 漏掉了行尾形态 —— 把示例代码贴进 JSDoc 时最常见的那种(内层 /* … */ 收在行尾),
+    // 因为它后面是行尾空白。实测漏检:ListPreferenceDialogHost.ets 由此产生 126 个
+    // 坐标指向注释正文的假错误,而 GATE 报 0 条。
+    // 注意 JS 块注释**不可嵌套**,故内层的 /* 本身无害,危险的只有 */ 。
+    if (/^\s*\/\*/.test(rawLines[i])) { continue; }   // 自身即开块(含单行 /** … */)
+    if (/^\s*\*\/\s*$/.test(rawLines[i])) { continue; } // 正常终止行:*/ 独占一行
+    if (rawLines[i].includes('*/')) {
+      report('GATE', 'block-comment-break', rel, i + 1,
+        'JSDoc 块内出现 */ 序列,注释在此提前闭合,其后正文将被当作代码解析' +
+        '(内层示例里的 /* … */ 请改成 // 行注释形式)');
+    }
+  }
+
+  // ---- GATE R2:$r() 传模板字符串($r 要求字面量)
+  for (let i = 0; i < codeLines.length; i++) {
+    if (codeLines[i].indexOf('$r(' + BACKTICK) >= 0) {
+      report('GATE', 'r-template-string', rel, i + 1,
+        '$r() 要求字面量,模板字符串拼接在运行时不可靠 —— 改为显式映射表');
+    }
+  }
+
+  const chains = attributeChains(codeLines);
+
+  for (const ch of chains) {
+    const blob = ch.lines.join('\n');
+
+    // ---- GATE R3:同一元素上 width('100%') 与左右 margin 叠加
+    if (RE_PCT_WIDTH.test(blob) && RE_H_MARGIN.test(blob)) {
+      report('GATE', 'pct-width-with-hmargin', rel, ch.start,
+        "width('100%') 与左右 margin 叠加 → 100% 不扣除自身 margin,实际宽度超出父容器,右侧溢出");
+    }
+
+    // ---- CAND R7:撑满容器且未声明 hitTestBehavior
+    // 只有「同时是层叠末位子节点」且「其下有可点击元素」才真正构成缺陷,
+    // 词法分析判不了这两点 —— 故仅列为候选。
+    if (RE_PCT_WIDTH.test(blob) && RE_PCT_HEIGHT.test(blob) && blob.indexOf('hitTestBehavior') < 0) {
+      report('CAND', 'fullsize-container', rel, ch.start,
+        '撑满容器未声明 hitTestBehavior:若它是层叠末位子节点,会吞掉其下元素的点击');
+    }
+  }
+
+  // ---- CAND R8:常量坐标
+  // 合法与否取决于 Android 侧锚定方向:起始边固定 margin 合法,右/下锚定则是缺陷。
+  for (let i = 0; i < codeLines.length; i++) {
+    const m = codeLines[i].match(/\.(position|offset)\(\s*\{([^}]*)\}/);
+    if (m !== null && /[xy]\s*:\s*-?\d/.test(m[2])) {
+      report('CAND', 'constant-coordinate', rel, i + 1,
+        '坐标含常量:需回读 Android 源确认是「固定偏移」还是「由父尺寸推导」');
+    }
+  }
+
+  // ---- GATE R3b:状态变量名与 ArkUI 通用属性同名
+  //
+  // 自定义组件继承 CustomComponent,后者已把 width/height/size/margin/... 定义为
+  // **方法**。用同名字段(如 `@Prop size: number`)会与基类成员冲突,编译器报
+  // 10505001「Property 'size' in type 'X' is not assignable to the same property in
+  // base type 'CustomComponent'」—— 报错信息指向类型不兼容,读起来像泛型/赋值问题,
+  // 与"换个名字就好"毫无字面关联,实测要靠猜。
+  //
+  // 值得单列一条:`size` 对一个图标组件是**最自然的**命名,四个图标组件会一次性
+  // 全部命中(实测首轮 8 个编译错误里有 4 个是这一条),而且它跨页复现 ——
+  // 任何新写的图标/头像/徽标组件都会再踩一次。
+  for (let i = 0; i < codeLines.length; i++) {
+    const dm = codeLines[i].match(
+      /@(?:Prop|State|Link|Local|Param|Provide|Consume|ObjectLink)\s+([A-Za-z_$][\w$]*)\s*[:?]/);
+    if (dm !== null && RESERVED_ATTR_NAMES.has(dm[1])) {
+      report('GATE', 'state-name-shadows-attribute', rel, i + 1,
+        `状态变量名 \`${dm[1]}\` 与 ArkUI 通用属性方法同名 —— CustomComponent 基类已定义 ` +
+        `${dm[1]}() 方法,同名字段会冲突,编译器报 10505001「not assignable to the same ` +
+        `property in base type 'CustomComponent'」(报错文本不会提示改名,极难反查)。` +
+        `改成带前缀的名字,如 \`icon${dm[1].charAt(0).toUpperCase() + dm[1].slice(1)}\``);
+    }
+  }
+
+  // ---- GATE R3c:@Builder 形参声明为 () => void 并被裸调用
+  //
+  // 把"子内容"作为回调传进 @Builder 是命令式思维下最顺手的写法,但 ArkUI 的
+  // @Builder 体必须是**声明式 UI 语句**,裸 `icon();` 不是,编译器报 10905204
+  // 「'icon();' does not meet UI component syntax」。正确做法是传 @Builder 引用
+  // (@BuilderParam),或直接把子内容内联展开。
+  //
+  // 与上一条同源:两者都是**编译期**才暴露、且报错信息不指向真正原因,
+  // 于是每次都要付一整轮构建(实测单轮 44s~70s)才能发现。
+  for (let i = 0; i < codeLines.length; i++) {
+    if (!/@Builder/.test(codeLines[i])) { continue; }
+    const sig = codeLines[i + 1] || '';
+    // 形参表必须按括号配平截取:`() => void` 里的 `)` 会让 `[^)]*` 提前收尾,
+    // 把 `tap: () => void, icon: () => void` 截断成 `tap: (` —— 回调形参恰好
+    // 因此全部漏掉,规则静默失效(本条自身就踩过一次)。
+    const nm = sig.match(/\b([A-Za-z_$][\w$]*)\s*\(/);
+    if (nm === null || nm.index === undefined) { continue; }
+    let depth = 0;
+    let open = sig.indexOf('(', nm.index);
+    let close = -1;
+    for (let c = open; c < sig.length; c++) {
+      if (sig[c] === '(') { depth++; }
+      else if (sig[c] === ')') { depth--; if (depth === 0) { close = c; break; } }
+    }
+    if (close < 0) { continue; }
+    const params = sig.slice(open + 1, close);
+    const sm = [nm[0], nm[1], params];
+    const cbs = [...params.matchAll(/([A-Za-z_$][\w$]*)\s*:\s*\(\s*\)\s*=>\s*void/g)]
+      .map((x) => x[1]);
+    if (cbs.length === 0) { continue; }
+    const body = codeLines.slice(i + 1, i + 40).join('\n');
+    for (const c of cbs) {
+      if (new RegExp('(^|[^.\\w$])' + c + '\\s*\\(\\s*\\)\\s*;').test(body)) {
+        report('GATE', 'builder-invokes-callback-param', rel, i + 2,
+          `@Builder ${sm[1]} 的形参 \`${c}: () => void\` 在体内被裸调用 \`${c}();\` —— ` +
+          `@Builder 体只能是声明式 UI 语句,编译器报 10905204「does not meet UI component ` +
+          `syntax」。改用 @BuilderParam 传入 @Builder 引用,或把该子内容内联展开`);
+      }
+    }
+  }
+
+  // ---- GATE R4:V1/V2 状态管理范式混用
+  const v1 = (code.match(RE_V1_DECO) || []).length;
+  const v2 = (code.match(RE_V2_DECO) || []).length;
+  if (v1 > 0 && v2 > 0) {
+    report('GATE', 'paradigm-mix', rel, 1,
+      `同文件内 V1(${v1} 处) 与 V2(${v2} 处) 装饰器混用 —— 两套范式不得在同一工程混用`);
+  }
+
+  // ---- GATE R5:@ObservedV2 类无任何 @Trace(不配合则完全不生效)
+  if (/@ObservedV2/.test(code) && (code.match(/@Trace/g) || []).length === 0) {
+    report('GATE', 'observedv2-without-trace', rel, 1,
+      '@ObservedV2 类中没有任何 @Trace 属性,状态变更不会触发 UI 刷新');
+  }
+  // 反向:有 @Trace 但类上没有 @ObservedV2
+  if (/@Trace/.test(code) && !/@ObservedV2/.test(code)) {
+    report('GATE', 'trace-without-observedv2', rel, 1,
+      '出现 @Trace 但类上缺少 @ObservedV2,二者必须配合,单独使用不生效');
+  }
+
+  // ---- GATE R5b:@Observed + @Track 的类里用 getter 暴露派生值(V1 专有陷阱)
+  //
+  // 判据来自 references/mvvm/@Track装饰器：class对象属性级更新.md:15 与 :198 ——
+  // 「如果 class 类中使用了 @Track 装饰器,则未被 @Track 装饰的属性不能在 UI 中使用,
+  //   如果使用,会发生运行时报错」。
+  //
+  // getter **不是数据属性,无法被 @Track 装饰**,于是 @Track 的属性级代理会把它判为
+  // 「未被 @Track 的属性」,在 build() 里首次读取即抛
+  //   BusinessError 140110: Illegal usage of not @Track'ed property 'x' on UI!
+  //
+  // 为什么这一条必须是 GATE 而不是 CAND:
+  //   * 字段侧完备性检查会**全部通过** —— 15 个字段都规规矩矩带了 @Track;
+  //   * 编译通过、零告警,GATE 其余各条也全部为 0;
+  //   * V1 没有 @Computed(那是 V2 的能力),所以「派生值该怎么暴露」在 V1 文档里
+  //     没有正面答案,极易被推理成「普通 TS getter 就行,反正读取会重新求值」——
+  //     该推理关于**响应性**是对的,关于**合法性**是错的,两者极易混为一谈。
+  //   * 只有真机首帧崩溃能发现它,而判据完全是词法的(同文件内即可判定)。
+  //
+  // 修法:把 getter 改成**普通方法**(`title(): string` + UI 侧 `vm.title()`)。
+  // 原型方法不是数据属性,不经过 @Track 代理,故不受本约束限制。
+  // 也可把派生值提升为真正的 @Track 字段,在赋值处同步维护。
+  //
+  // 精度说明:按**类体**逐个判定,而不是整文件 —— 同一文件里可能既有 @Observed
+  // 类也有普通 class/interface,整文件判定会误报后者的 getter。
+  for (const cls of observedTrackClassBodies(code, codeLines)) {
+    for (const g of cls.getters) {
+      report('GATE', 'track-class-getter-in-ui', rel, g.line,
+        `@Observed 类 ${cls.name} 同时使用了 @Track,其 getter '${g.name}' 无法被 @Track 装饰;` +
+        '一旦在 build()/@Builder 中读取,首帧即抛 BusinessError 140110 ' +
+        `(Illegal usage of not @Track'ed property '${g.name}' on UI)。` +
+        '改成普通方法(原型方法不受 @Track 代理约束),或提升为真正的 @Track 字段');
+    }
+  }
+
+  // ---- 收集 .fillColor() 染色的 media 名(GATE R7 在跨文件阶段核对 SVG 内容)
+  //
+  // 不能用 attributeChains():注释已被替换成空白行,而空白行会**打断**链,
+  // 于是 Image( 与它的 .fillColor( 常常落在不同的"链"里(本项目实测两者相隔 23 行,
+  // 中间全是解释性注释)。改为直接按行回溯:从每个 .fillColor( 向上找最近的 Image(,
+  // 把该区间内出现的所有 app.media.<NAME> 视为被这次染色作用的候选
+  // (Image() 里常是三元选图,两个分支都要算)。
+  const tinted = [];
+  for (let i = 0; i < codeLines.length; i++) {
+    if (!codeLines[i].includes('.fillColor(')) { continue; }
+
+    // 向上找最近的 Image(。窗口给足:属性链之间夹大段注释是常态。
+    let from = -1;
+    for (let k = i; k >= 0 && k >= i - 80; k--) {
+      if (codeLines[k].includes('Image(')) { from = k; break; }
+    }
+    if (from < 0) { continue; }
+
+    // 区间 = Image( 那行 .. .fillColor( 之后的若干行(染色参数本身可能跨行,
+    // 但 media 名只会出现在 Image() 的实参里,取到 i 即可)
+    const span = codeLines.slice(from, i + 1).join('\n');
+
+    const re = /app\.media\.([A-Za-z0-9_]+)/g;
+    let m = re.exec(span);
+    while (m !== null) {
+      tinted.push({ name: m[1], line: i + 1 });
+      m = re.exec(span);
+    }
+  }
+
+  // ---- 收集本文件引用的全部 app.media.X(与染色无关),供跨文件的媒体内容体检使用
+  const mediaRefs = [];
+  for (let i = 0; i < codeLines.length; i++) {
+    const re = /app\.media\.([A-Za-z0-9_]+)/g;
+    let m = re.exec(codeLines[i]);
+    while (m !== null) {
+      mediaRefs.push({ name: m[1], line: i + 1 });
+      m = re.exec(codeLines[i]);
+    }
+  }
+
+  // ---- 预扫:哪些 @Builder 方法在自己的顶层直接渲染 Text
+  //
+  // 必需,否则 R8 会漏掉最常见的写法:容器的直接子节点是 `this.SectionTitle(title)`
+  // 而不是字面的 `Text(...)`。实测 mihon-statistics 的居中缺陷正是这种形状 ——
+  // 只认字面 Text 时该页零命中。
+  const textBuilders = new Set();
+  for (let i = 0; i < codeLines.length; i++) {
+    if (!/^\s*@Builder\b/.test(codeLines[i])) { continue; }
+    // 方法签名可能在 @Builder 的下一行或再下一行
+    let sig = -1;
+    for (let k = i + 1; k < Math.min(i + 4, codeLines.length); k++) {
+      if (/^\s*(?:private\s+|public\s+)?[A-Za-z_$][A-Za-z0-9_$]*\s*\(/.test(codeLines[k])) { sig = k; break; }
+    }
+    if (sig < 0) { continue; }
+    const nm =
+      codeLines[sig].match(/(?:private\s+|public\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/);
+    if (nm === null) { continue; }
+
+    // 从签名行的 { 起做大括号配平,取方法体;判断体内 depth===1 处是否有 Text(
+    let depth = 0;
+    let started = false;
+    let direct = false;
+    for (let k = sig; k < codeLines.length; k++) {
+      const ln = codeLines[k];
+      for (let c = 0; c < ln.length; c++) {
+        if (ln[c] === '{') { depth++; started = true; continue; }
+        if (ln[c] === '}') { depth--; continue; }
+        if (started && depth === 1 && ln.startsWith('Text(', c)) {
+          const prev = c > 0 ? ln[c - 1] : ' ';
+          if (!/[A-Za-z0-9_.$]/.test(prev)) { direct = true; }
+        }
+      }
+      if (started && depth <= 0) { break; }
+    }
+    if (direct) { textBuilders.add(nm[1]); }
+  }
+
+  // ---- CAND R8:Column/Row 含收缩宽度子节点但未显式设 alignItems
+  //
+  // ArkUI Column 默认 HorizontalAlign.Center、Row 默认 VerticalAlign.Center;
+  // Android LinearLayout / Compose Column 默认 **start**。两侧都不写对齐属性时
+  // 字面完全一致,逐属性对照会把它确认成「翻译正确」,而渲染结果一个居中一个齐左。
+  //
+  // 放 CAND 不放 GATE:居中有时正是对的(空态插图、按钮内图标、卡片内数值列)。
+  // 只在容器直接含 Text( 时才报,避免把纯布局容器全部列出来。
+  for (const ch of attributeChains(codeLines)) {
+    // attributeChains 的链首只回溯一行,对**带子节点**的容器而言那行是 `}` 而不是
+    // `Column() {`。这里从链首行往上做大括号配平,找到真正的容器声明行,
+    // 并把 { ... } 之间的子节点内容一并取出(判断容器是否直接含 Text 要用它)。
+    let head = ch.lines[0] || '';
+    let bodyLines = [];
+    if (/^\s*\}/.test(head)) {
+      let depth = 0;
+      let open = -1;
+      for (let k = ch.start; k >= 0; k--) {
+        const ln = codeLines[k];
+        for (let c = ln.length - 1; c >= 0; c--) {
+          if (ln[c] === '}') { depth++; }
+          else if (ln[c] === '{') {
+            depth--;
+            if (depth === 0) { open = k; break; }
+          }
+        }
+        if (open >= 0) { break; }
+      }
+      if (open < 0) { continue; }
+      head = codeLines[open];
+      bodyLines = codeLines.slice(open, ch.start + 1);
+    }
+
+    const m = head.match(/\b(Column|Row)\s*\(/);
+    if (m === null) { continue; }
+    const attrs = ch.lines.join('\n');
+    // 必须检查**决定水平位置的那个轴**,而两种容器的该轴属性不同名:
+    //   Column -> 水平是交叉轴 -> alignItems(HorizontalAlign)
+    //   Row    -> 水平是主轴   -> justifyContent(FlexAlign)
+    // 若一律只看 alignItems,则 Row 上一个**完全正确的**
+    // .alignItems(VerticalAlign.Center)(纵向居中,通常正是 Android 的
+    // verticalAlignment=CenterVertically)会把本条静默放行 —— 而它管的是纵轴,
+    // 跟"文字齐左还是居中"无关。实测漏检:日期分隔行因此居中,而该容器
+    // "已写 alignItems",检查器不报、编译通过、逐属性对照亦"忠实"。
+    const axisAttr = m[1] === 'Column' ? 'alignItems' : 'justifyContent';
+    if (new RegExp('\\.' + axisAttr + '\\(').test(attrs)) { continue; }
+    // 只在容器**直接**含 Text 时才报。必须按大括号深度筛:否则最外层容器
+    // 会因为某个深层嵌套的子容器里有 Text 而被命中(该 Text 的对齐由那个
+    // 子容器决定,与本容器无关),典型如 build() 里包住整页的那个 Column。
+    if (bodyLines.length > 0) {
+      let depth = 0;
+      let directText = false;
+      for (let k = 0; k < bodyLines.length && !directText; k++) {
+        const ln = bodyLines[k];
+        for (let c = 0; c < ln.length; c++) {
+          if (ln[c] === '{') { depth++; continue; }
+          if (ln[c] === '}') { depth--; continue; }
+          // depth === 1 即本容器大括号内的顶层位置
+          if (depth !== 1) { continue; }
+          // (a) 字面 Text(
+          if (ln.startsWith('Text(', c)) {
+            const prev = c > 0 ? ln[c - 1] : ' ';
+            if (!/[A-Za-z0-9_.$]/.test(prev)) { directText = true; break; }
+          }
+          // (b) this.SomeBuilder(...) 且该 @Builder 顶层直接渲染 Text
+          if (ln.startsWith('this.', c)) {
+            const bm =
+              ln.slice(c).match(/^this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/);
+            if (bm !== null && textBuilders.has(bm[1])) { directText = true; break; }
+          }
+        }
+      }
+      if (!directText) { continue; }
+    } else if (!/\bText\s*\(/.test(attrs)) {
+      continue;
+    }
+    const kind = m[1];
+    const want = kind === 'Column'
+      ? 'alignItems(HorizontalAlign.Start)'
+      : 'justifyContent(FlexAlign.Start)';
+    report('CAND', 'container-align-unset', rel, ch.start,
+      `${kind} 直接含 Text 子节点但未显式 .${axisAttr}() —— 它是本容器**水平方向**的` +
+      `对齐属性(Column 的水平是交叉轴 alignItems,Row 的水平是主轴 justifyContent)。` +
+      `Android LinearLayout / Compose Column 默认 start。若 Android 侧未写水平 gravity,` +
+      `应显式译成 .${want};若该处本就该居中(空态插图、按钮内图标),忽略本条。` +
+      `注意:Row 上已有的 .alignItems(VerticalAlign.*) 管的是纵轴,不满足本条`);
+  }
+
+  return {
+    rel,
+    hasExpandSafeArea: /expandSafeArea/.test(code),
+    isPage: /[\\/]pages[\\/]/.test(file),
+    hasWindowFullScreen: /setWindowLayoutFullScreen/.test(code),
+    tinted,
+    mediaRefs,
+    text: code
+  };
+}
+
+// ---------------------------------------------------------------- 跨文件规则
+
+/**
+ * GATE R7:用 .fillColor() 给 stroke 着色的 SVG 染色 —— 颜色完全不生效。
+ *
+ * fillColor 只叠加 fill 通道(SDK image.d.ts: "Sets the fill color to be superimposed
+ * on the image"),对 stroke 无效。而保真规则**要求**描边图形写成 fill="none",
+ * 于是两条各自正确的规则组合出一个静默缺陷:文件内容对、引用名对、代码看起来也对,
+ * 图形却保持原始色(通常是黑)。
+ *
+ * 判据(纯文件内容,零歧义):某个被 fillColor 染色的 SVG 里,存在带具体 stroke 颜色
+ * 且自身没有具体 fill 颜色的元素 —— 该元素的颜色染不上。
+ */
+function checkSvgTintChannel(scans, resDir) {
+  const mediaDir = path.join(resDir, 'base', 'media');
+  if (!fs.existsSync(mediaDir)) { return; }
+
+  for (const s of scans) {
+    const seen = new Set();
+    for (const t of s.tinted) {
+      if (seen.has(t.name)) { continue; }
+      seen.add(t.name);
+
+      const svg = path.join(mediaDir, `${t.name}.svg`);
+      if (!fs.existsSync(svg)) { continue; }
+
+      let src;
+      try {
+        src = fs.readFileSync(svg, 'utf8');
+      } catch {
+        continue;
+      }
+
+      // 逐个元素看:有具体 stroke 颜色、且同元素内无具体 fill 颜色 => 染不上
+      const els = src.match(/<(?:path|circle|rect|ellipse|line|polyline|polygon)\b[^>]*>/g) || [];
+      const bad = [];
+      for (const el of els) {
+        const stroke = el.match(/stroke\s*=\s*"([^"]*)"/);
+        if (stroke === null) { continue; }
+        const sv = stroke[1].trim().toLowerCase();
+        if (sv === '' || sv === 'none' || sv === 'currentcolor') { continue; }
+        const fill = el.match(/fill\s*=\s*"([^"]*)"/);
+        const fv = fill === null ? '' : fill[1].trim().toLowerCase();
+        if (fv === '' || fv === 'none') { bad.push(sv); }
+      }
+
+      if (bad.length > 0) {
+        report('GATE', 'fillcolor-on-stroke-svg', s.rel, t.line,
+          `对 app.media.${t.name} 使用了 .fillColor(),但该 SVG 有 ${bad.length} 个 stroke 着色` +
+          `(${bad.slice(0, 3).join(', ')})且无 fill —— fillColor 只作用于 fill 通道,` +
+          '这些几何的颜色不会改变(保持原色,通常为黑)。' +
+          '改法:把描边几何改写成等价 fill 几何(等宽圆环 = 外圆 + 内圆同 path + fill-rule="evenodd")、' +
+          '改用原生组件、或按状态备两份已着色素材');
+      }
+    }
+  }
+}
+
+/**
+ * GATE R8:用 .fillColor() 染色的 SVG 里存在**铺满 viewBox 的 fill="none" 包围盒 path**
+ * —— 整个图标会被染成实心色块。
+ *
+ * 与 R7 同族但方向相反:R7 查「stroke 几何染不上」,本条查「fill="none" 的包围盒被染上」。
+ * fillColor 是叠加到**全部**几何上的,fill="none" 并不能豁免它。
+ *
+ * 成因:Material 图标的 web SVG 标准写法带一条 `<path d="M0 0h24v24H0z" fill="none"/>`
+ * 包围盒(占位/对齐用)。Android 的 `<vector>` 源里**没有**这条 path —— 实测 10 个安卓仓
+ * 零命中 —— 所以它只会出现在「凭记忆手写 SVG」的产物里。因此本规则同时是
+ * 「图标不得凭记忆手写」这条禁令的机械抓手:命中即证明该 SVG 不是从 Android 源转换而来。
+ *
+ * 判据(纯文件内容,零歧义):某个被 fillColor 染色的 SVG 里,存在 fill="none" 且其 d
+ * 恰好是 viewBox 全矩形的 path。
+ */
+function isFullViewportRect(d, w, h) {
+  // 归一化:去空白、统一逗号
+  const s = d.replace(/\s+/g, '').replace(/,/g, ' ').trim();
+  // 允许 M0 0 / m0 0 起手,H/h + V/v + H/h 回 0 + Z/z 的各种大小写与相对/绝对混写。
+  // 只匹配最常见的三种等价写法,宁可漏报也不误报。
+  const nw = String(w);
+  const nh = String(h);
+  const variants = [
+    `M0 0h${nw}v${nh}H0z`,
+    `M0 0h${nw}v${nh}h-${nw}z`,
+    `M0 0H${nw}V${nh}H0Z`,
+    `M0 0l${nw} 0 0 ${nh} -${nw} 0z`
+  ];
+  const norm = (x) => x.replace(/\s+/g, '').toLowerCase();
+  return variants.some((v) => norm(v) === norm(s));
+}
+
+function checkFullViewportTint(scans, resDir) {
+  const mediaDir = path.join(resDir, 'base', 'media');
+  if (!fs.existsSync(mediaDir)) { return; }
+
+  // 对**全部**被引用的 media 检查,不限于 tinted。
+  //
+  // 原因有两层:
+  // (1) tinted 靠「从 .fillColor( 向上找最近的 Image(」配对,跨不过方法边界 ——
+  //     实测 readyou-accounts 的 ic_rss_feed 由 iconFor() 返回、在另一个 @Builder 里
+  //     被染色,只查 tinted 时漏检,而它恰是列表项里最显眼的那个黑框。
+  // (2) 更根本的:这条包围盒 path 是 Material web SVG 的写法,Android <vector> 源
+  //     不会产生它(实测 10 个安卓仓零命中)。所以它的出现本身就证明该文件是
+  //     凭记忆手写而非从 Android 源转换 —— 无论当前有没有染色,都该修。
+  const reportedFvp = new Set();
+  for (const s of scans) {
+    const tintedNames = new Set(s.tinted.map((x) => x.name));
+    for (const t of s.mediaRefs) {
+      if (reportedFvp.has(t.name)) { continue; }
+
+      const svg = path.join(mediaDir, `${t.name}.svg`);
+      if (!fs.existsSync(svg)) { continue; }
+
+      let src;
+      try { src = fs.readFileSync(svg, 'utf8'); } catch { continue; }
+
+      // 取 viewBox 尺寸(缺失时退回 width/height)
+      const vb = src.match(/viewBox\s*=\s*"([^"]+)"/);
+      let w = 0;
+      let h = 0;
+      if (vb !== null) {
+        const p = vb[1].trim().split(/[\s,]+/);
+        if (p.length === 4) { w = parseFloat(p[2]); h = parseFloat(p[3]); }
+      }
+      if (!(w > 0 && h > 0)) { continue; }
+
+      const els = src.match(/<path\b[^>]*>/g) || [];
+      for (const el of els) {
+        const fill = el.match(/fill\s*=\s*"([^"]*)"/);
+        if (fill === null || fill[1].trim().toLowerCase() !== 'none') { continue; }
+        const dm = el.match(/\bd\s*=\s*"([^"]*)"/);
+        if (dm === null) { continue; }
+        if (isFullViewportRect(dm[1], w, h)) {
+          reportedFvp.add(t.name);
+          const tintNote = tintedNames.has(t.name)
+            ? `本文件对它用了 .fillColor(),fillColor 会把这条包围盒一并染上(fill="none" 拦不住),` +
+              '整个图标渲染为**实心色块**'
+            : '本文件未直接对它染色,但只要任何位置用 .fillColor() 染它,整个图标就会变成实心色块' +
+              '(注:跨方法返回资源时染色点可能在别的 @Builder 里)';
+          report('GATE', 'fillcolor-on-full-viewport-path', s.rel, t.line,
+            `app.media.${t.name} 的 SVG 含一条铺满 viewBox(${w}x${h})的 fill="none" ` +
+            `包围盒 path。${tintNote}。` +
+            '根因:这条 path 是 Material **web SVG** 的写法,Android <vector> 源不会产生它 —— ' +
+            '该文件是凭记忆手写而非从 Android 源转换。' +
+            '修法:从 res/drawable 的 <vector> 重新转换;确实无对应 drawable 时,' +
+            '按 Phase 4.3 的图标来源分级登记为「已降级」,不要手写');
+          break;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * GATE R9:引用了内容无法渲染的 media —— 文件存在、引用名正确,却画不出图形。
+ *
+ * 起因:页面 agent 惯于用 `ls media/` 确认资源"存在"就通过,从不打开文件。
+ * 两类都能编译、都能过引用存在性检查:
+ *   (a) 转换器留下的未解析 Android 主题属性(`?attr/...`、`?colorPrimary`)进了 fill/stroke
+ *       —— SVG 不认识这种值,该几何不着色;
+ *   (b) 占位 SVG(a2h-resource-convert 在缺资源时生成的灰底 + 资源名文本)被当真图标用。
+ *
+ * 判据均为纯文件内容,零歧义。不依赖读 resource_mapping.md —— 那份文档很长,
+ * 且 (a) 类根本不在它的 Placeholder 章节里(它来自真实 drawable 的转换失败)。
+ */
+function checkMediaContentUsable(scans, resDir) {
+  const mediaDir = path.join(resDir, 'base', 'media');
+  if (!fs.existsSync(mediaDir)) { return; }
+
+  // 同一资源在整个工程里只报一次,附带首个引用位置
+  const reported = new Set();
+
+  for (const s of scans) {
+    for (const t of s.mediaRefs) {
+      if (reported.has(t.name)) { continue; }
+
+      const svg = path.join(mediaDir, `${t.name}.svg`);
+      if (!fs.existsSync(svg)) { continue; }
+
+      let src;
+      try { src = fs.readFileSync(svg, 'utf8'); } catch { continue; }
+
+      // (0) 同一元素上出现重复属性 —— XML 规范下这是 **fatal error**,
+      // 整份文档会被解析器拒绝,于是**整个图标一个像素都画不出来**(表现为
+      // 空白/看不见,而不是画错)。
+      //
+      // 为什么必须单列一条:其余所有检查(包括本函数的 a/b 两项、
+      // fillcolor-on-* 两项、以及资源侧的 svg_fidelity_check)都是**先当作
+      // 有效 SVG 再检查语义**,没有任何一条验证过"这份文件解析得开"。
+      // 引用名对、文件存在、`ls media/` 通过、语义层也挑不出错 —— 只是文件
+      // 根本不合法。实测来源:转换器给每个 path 先写死 fill-opacity="1",
+      // 再把 Android 的 fillAlpha 作为**第二个** fill-opacity 追加,命中率
+      // 11/93。修法是保留后者(即 Android 源里的真实 alpha)、删掉前者。
+      const dupHit = (() => {
+        for (const el of src.matchAll(/<([a-zA-Z][\w:-]*)\b([^>]*?)\/?>/g)) {
+          const seen = new Set();
+          for (const a of el[2].matchAll(/([a-zA-Z_][\w:.-]*)\s*=\s*"/g)) {
+            if (seen.has(a[1])) { return `<${el[1]}> 上的 ${a[1]}`; }
+            seen.add(a[1]);
+          }
+        }
+        return null;
+      })();
+      if (dupHit !== null) {
+        reported.add(t.name);
+        report('GATE', 'media-duplicate-attribute', s.rel, t.line,
+          `app.media.${t.name} 的 SVG 不是合法 XML:${dupHit} 出现了两次。` +
+          '重复属性在 XML 规范下是致命错误,解析器会拒绝整份文档 —— ' +
+          '**该图标会完全不显示**(空白),而不是显示得不对。' +
+          '注意「文件存在 + 引用名正确 + 语义检查通过」全都拦不住这一条。' +
+          '修法:回到 Android <vector> 源核对该属性(如 fillAlpha/strokeAlpha),' +
+          '只保留一个正确取值;转换器常见 bug 是先写默认 "1" 再追加真实值,此时应保留后者');
+        continue;
+      }
+
+      // (a) 未解析的 Android 主题属性残留在颜色通道里
+      const attrHit =
+        src.match(/(?:fill|stroke)\s*=\s*"(\?[A-Za-z0-9_./:]+)"/);
+      if (attrHit !== null) {
+        reported.add(t.name);
+        report('GATE', 'media-unresolved-theme-attr', s.rel, t.line,
+          `app.media.${t.name} 的 SVG 里 fill/stroke 仍是未解析的 Android 主题属性 ` +
+          `"${attrHit[1]}" —— SVG 不认识该值,这部分几何不会着色(常表现为白框/透明块)。` +
+          '需回到 Android <vector> 源,把 ?attr/ 主题属性解析成 theme 里对应的具体颜色后重新转换');
+        continue;
+      }
+
+      // (b) 占位 SVG:灰底矩形 + 资源名文本(见 a2h-resource-convert 的 placeholder 模板)
+      const isPlaceholder =
+        /<rect\b[^>]*fill\s*=\s*"#CCCCCC"/i.test(src) && /<text\b/i.test(src);
+      if (isPlaceholder) {
+        reported.add(t.name);
+        report('GATE', 'media-placeholder-in-use', s.rel, t.line,
+          `app.media.${t.name} 是资源转换阶段生成的**占位 SVG**(灰底矩形 + 资源名文本),` +
+          '不是真实图标 —— 界面上会渲染成一个灰框。' +
+          '需补齐真实素材(从 Android res/drawable 转换,或按 Phase 4.3 的图标来源分级处理),' +
+          '拿不到时必须在报告中登记为「已降级」,不得直接消费占位图');
+      }
+    }
+  }
+}
+
+/**
+ * GATE R8/R9: SVG 内容自动验证 + 图标语义形状比对。
+ *
+ * R8 检查 SVG 文件内容是否可用（空文件、重复属性、主题属性残留、占位 SVG）。
+ * R9 比对图标的**几何元素计数**这一粗粒度拓扑特征：当 measure_pack.json 里记录了
+ * 该图标的参考签名时，数当前 SVG 的 <path>/<circle>/<rect>/<ellipse> 个数并与之比对。
+ *
+ * **能力边界（勿按"形状比对"理解）**：本规则不栅格化 SVG、不比对轮廓，只数元素个数。
+ * 它能抓到「三点 overflow 译成单个圆」这类元素数量级差异，抓不到元素数相同而轮廓不同
+ * （下载箭头 vs 上传箭头、圆角矩形 vs 圆）的情形。`measure_pack.js --probe` 只接受
+ * PNG，无法对 SVG 取 runs —— 轮廓一致性仍须人工打开 SVG 与参考截图比对。
+ *
+ * **前提**：--resources 必须提供，且页面目录下 measure_pack.json 的 regions
+ * 里有 shape_sig 字段（`{ resource_name, runs, coverage }`，其中 runs 按元素计数口径填写）。
+ * 该字段目前**没有任何随包脚本产出**，须人工写入；无 --resources 或无 shape_sig 时本规则整条跳过。
+ */
+function checkSvgSemantics(scans, resDir, uiInfoDir) {
+  // 1. 收集所有被引用的 SVG（从代码中的 $r('app.media.xxx') 提取）
+  const mediaRefs = new Set();
+  for (const s of scans) {
+    for (const t of s.mediaRefs) {
+      if (t.line > 0) {
+        mediaRefs.add(t.name);
+      }
+    }
+  }
+
+  if (mediaRefs.size === 0) {
+    return;
+  }
+
+  const mediaDir = path.join(resDir, 'base', 'media');
+  if (!fs.existsSync(mediaDir)) {
+    return;
+  }
+
+  // 2. 读取 ui_info 下所有 measure_pack.json，提取图标形状签名
+  // interface IconShapeSig {
+    // name: string;       // 资源名（不含扩展名）
+    // runs: number;       // 连续段数
+    // coverage: number;   // 覆盖率
+    // pageName: string;   // 来源页面（用于报错时定位）
+  // }
+
+  const refShapes = new Map();
+  let pagedirs = [];
+  try {
+    const entries = fs.readdirSync(uiInfoDir, { withFileTypes: true });
+    pagedirs = entries
+      .filter((e) => e.isDirectory() && /^(page|manual)_\d{4}_/.test(e.name))
+      .map((e) => path.join(uiInfoDir, e.name));
+  } catch {
+    // ui_info 不存在时整条跳过
+    return;
+  }
+
+  for (const pageDir of pagedirs) {
+    const measurePackPath = path.join(pageDir, 'measure_pack.json');
+    if (!fs.existsSync(measurePackPath)) {
+      continue;
+    }
+
+    let measureData;
+    try {
+      measureData = JSON.parse(fs.readFileSync(measurePackPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    const pageName = path.basename(pageDir);
+    if (Array.isArray(measureData.regions)) {
+      for (const r of measureData.regions) {
+        // 只处理标记为图标的节点（role=ImageView/Image 且尺寸 < 96dp）
+        if (!r.shape_sig || typeof r.shape_sig !== 'object') {
+          continue;
+        }
+        // shape_sig: { resource_name, runs, coverage }
+        const resName = r.shape_sig.resource_name;
+        if (typeof resName === 'string' && resName.length > 0) {
+          refShapes.set(resName, {
+            name: resName,
+            runs: r.shape_sig.runs || 0,
+            coverage: r.shape_sig.coverage || 0,
+            pageName
+          });
+        }
+      }
+    }
+  }
+
+  // 3. 逐个检查被引用的 SVG
+  for (const mediaName of mediaRefs) {
+    const svgPath = path.join(mediaDir, mediaName + '.svg');
+    if (!fs.existsSync(svgPath)) {
+      continue; // 可能是其他格式（png/jpg），跳过
+    }
+
+    let svgContent;
+    try {
+      svgContent = fs.readFileSync(svgPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    // 找到第一个引用该资源的文件（用于报错定位）
+    let refFile = '';
+    let refLine = 1;
+    for (const s of scans) {
+      const hit = s.mediaRefs.find((t) => t.name === mediaName);
+      if (hit && hit.line > 0) {
+        refFile = s.rel;
+        refLine = hit.line;
+        break;
+      }
+    }
+    if (refFile === '') {
+      continue; // 理论上不会到这里
+    }
+
+    // R8a: 空 SVG 文件
+    if (svgContent.trim().length === 0 || /<svg[^>]*>\s*<\/svg>/.test(svgContent)) {
+      report('GATE', 'media-empty-svg', refFile, refLine,
+        `app.media.${mediaName} 是空 SVG 文件（无任何几何内容），界面上该位置为空白。` +
+        '需补齐真实图标素材或按 L3 规则用等尺寸空 Row/Column 占位 + 降级登记');
+      continue;
+    }
+
+    // R8b: 重复属性（已在 checkMediaContentUsable 的 media-duplicate-attribute 里检查，此处不重复）
+    // R8c: 主题属性残留（已在 checkMediaContentUsable 的 media-unresolved-theme-attr 里检查）
+    // R8d: 占位 SVG（已在 checkMediaContentUsable 的 media-placeholder-in-use 里检查）
+
+    // R9: 形状语义比对（当 refShapes 里有该资源的参考签名时）
+    const refSig = refShapes.get(mediaName);
+    if (!refSig) {
+      continue; // 无参考签名，跳过形状比对
+    }
+
+    // 几何元素计数作为粗粒度拓扑特征。
+    // 不用 measure_pack.js --probe：它只解码 PNG，对 SVG 取不到 runs。
+    // 因此本规则的判据是「元素个数」而非「轮廓」，见函数头的能力边界说明。
+    const actualElems = (() => {
+      const pathCount = (svgContent.match(/<path\b/g) || []).length;
+      const circleCount = (svgContent.match(/<circle\b/g) || []).length;
+      const rectCount = (svgContent.match(/<rect\b/g) || []).length;
+      const ellipseCount = (svgContent.match(/<ellipse\b/g) || []).length;
+      return pathCount + circleCount + rectCount + ellipseCount;
+    })();
+
+    // 判据：几何元素数量差异 > 50% 且绝对差 >= 2 即判定拓扑不符
+    const diff = Math.abs(actualElems - refSig.runs);
+    const ratio = refSig.runs > 0 ? diff / refSig.runs : (actualElems > 0 ? 1 : 0);
+
+    if (ratio > 0.5 && diff >= 2) {
+      report('GATE', 'media-element-count-mismatch', refFile, refLine,
+        `app.media.${mediaName} 的几何元素个数与参考签名不符：` +
+        `参考签名记录 ${refSig.runs} 个（来自 ${refSig.pageName}），` +
+        `当前 SVG 有 ${actualElems} 个（偏差 ${Math.round(ratio * 100)}%）。` +
+        '文件名选对但像素内容错 —— 需回溯资源转换阶段修正，或换用 L3 等尺寸空 Row 占位 + 降级登记。' +
+        '禁止只抽查部分文件后对未检查文件下全称断言');
+    }
+  }
+}
+
+/**
+ * CAND R10:Android 侧有 edge-to-edge 调用,但鸿蒙工程里两层都没声明。
+ *
+ * 为什么必须查源码而不能看截图:edge-to-edge 的页面会自行对 insets 做 padding,
+ * 其截图形态与「避让系统栏」**完全同形** —— 状态栏可见、内容起点在其下方。
+ * 于是「依据截图判断是否沉浸式」在沉浸式场景下必然误判成非沉浸式,
+ * 再叠加「与基线保持一致」(基线全是非沉浸式)就形成一条两步都"有据"、
+ * 结论却错的通过路径。实测:10 个安卓仓全部调用了 edge-to-edge,
+ * 而 15 个转换页面的 expandSafeArea / setWindowLayoutFullScreen 出现次数全为 0。
+ *
+ * 为什么是 CAND 而不是 GATE:命中的调用点可能属于别的 Activity
+ * (如 CrashActivity / ReaderActivity —— Mihon 实测 3 处命中),
+ * 而本检查器不知道 page → Activity 的映射,做成 GATE 会误报。
+ * 作为 CAND 已经足够:它把①的证据从「可选」变成「必须逐条回应的清单」。
+ */
+const E2E_KEYS = [
+  'enableEdgeToEdge',
+  'EdgeToEdge.enable',
+  'setDecorFitsSystemWindows',
+  'statusBarColor',
+  'colorPrimaryDark',
+  'setStatusBarColor'
+];
+
+function grepAndroidEdgeToEdge(dir) {
+  const hits = [];
+  const SKIP = new Set([
+    'build', '.git', '.gradle', 'node_modules', 'oh_modules', '.idea',
+    'test', 'androidTest', 'debug', 'benchmark', 'fastlane', 'docs', 'metadata'
+  ]);
+  const MAX_HITS = 12;
+  const MAX_FILES = 6000;
+  let scanned = 0;
+
+  const walk = (d, depth) => {
+    if (depth > 10 || hits.length >= MAX_HITS || scanned >= MAX_FILES) { return; }
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (hits.length >= MAX_HITS || scanned >= MAX_FILES) { return; }
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (SKIP.has(e.name)) { continue; }
+        walk(p, depth + 1);
+        continue;
+      }
+      // 只看 Kotlin/Java 源:XML 主题里的 windowTranslucentStatus 常来自
+      // 三方库或 dialog 主题,单独出现时判别力太低,交给 Phase 5 人工核对
+      if (!/\.(kt|java)$/.test(e.name)) { continue; }
+      scanned++;
+      let src;
+      try { src = fs.readFileSync(p, 'utf8'); } catch { continue; }
+      // 先整体判一次,绝大多数文件在这里就被排除,避免逐行扫
+      let touched = false;
+      for (const k of E2E_KEYS) {
+        if (src.includes(k)) { touched = true; break; }
+      }
+      if (!touched) { continue; }
+
+      const lines = src.split('\n');
+      for (let i = 0; i < lines.length && hits.length < MAX_HITS; i++) {
+        if (/^\s*import\b/.test(lines[i])) { continue; }
+        for (const k of E2E_KEYS) {
+          if (lines[i].includes(k)) {
+            hits.push(`${path.relative(dir, p).replace(/\\/g, '/')}:${i + 1} (${k})`);
+            break;
+          }
+        }
+      }
+    }
+  };
+  walk(dir, 0);
+  return hits;
+}
+
+function checkAndroidImmersive(scans, androidDir) {
+  const pages = scans.filter((s) => s.isPage);
+  if (pages.length === 0) { return; }
+  const anyComponentLayer = pages.some((s) => s.hasExpandSafeArea);
+  const anyWindowLayer = scans.some((s) => s.hasWindowFullScreen);
+  if (anyComponentLayer && anyWindowLayer) { return; }
+
+  const hits = grepAndroidEdgeToEdge(androidDir);
+  if (hits.length === 0) { return; }
+
+  const shown = hits.slice(0, 6).join('; ');
+  const more = hits.length > 6 ? ` 等 ${hits.length} 处` : '';
+  const missing = [];
+  if (!anyWindowLayer) { missing.push('窗口层 setWindowLayoutFullScreen'); }
+  if (!anyComponentLayer) { missing.push('组件层 expandSafeArea'); }
+
+  report('CAND', 'android-immersive-not-mirrored', pages[0].rel, 1,
+    `Android 侧存在 edge-to-edge 调用(${shown}${more}),但鸿蒙工程缺少:${missing.join(' + ')}。` +
+    '请按 Phase 5「窗口模式证据」①逐项核对:命中的调用点是否属于本页宿主 Activity ' +
+    '(属于 CrashActivity/ReaderActivity 等其他 Activity 的不算本页证据)。' +
+    '**注意不要用截图判断** —— edge-to-edge 页面自行对 insets 做 padding,' +
+    '截图形态与避让系统栏完全同形;「与基线一致」也不构成依据,基线只说明现状。' +
+    '若确认本页宿主沉浸,需补齐窗口层 + 组件层(含改 EntryAbility)');
+}
+
+function checkWindowMode(scans) {
+  const pages = scans.filter((s) => s.isPage);
+  const withExpand = pages.filter((s) => s.hasExpandSafeArea);
+  const anyWindowLayer = scans.some((s) => s.hasWindowFullScreen);
+
+  // GATE R6:声明了组件层却完全没有窗口层 —— 沉浸式必须两层配合。
+  // 只设组件层时全批页面会「一致地错」,跨页一致性检查照样满分通过。
+  if (withExpand.length > 0 && !anyWindowLayer) {
+    report('GATE', 'window-layer-missing', withExpand[0].rel, 1,
+      `${withExpand.length} 个页面声明了 expandSafeArea,但工程内无 setWindowLayoutFullScreen —— ` +
+      '系统仍为状态栏保留空间,页面顶部出现空白带');
+  }
+
+  // GATE R7:全屏模式下缺内容层 inset 避让 —— 两层开关已设,但内容从 y=0 起绘与状态栏重合
+  if (anyWindowLayer && withExpand.length > 0) {
+    const noAvoid = pages.filter((s) =>
+      s.hasExpandSafeArea && !s.text.includes('getWindowAvoidArea') &&
+      !s.text.includes('avoidAreaChange') && !s.text.includes('statusBarHeight')
+    );
+    if (noAvoid.length > 0) {
+      report('CAND', 'immersive-missing-inset-padding', noAvoid[0].rel, 1,
+        `${noAvoid.length} 个页面已设全屏模式(setWindowLayoutFullScreen) + expandSafeArea,` +
+        '但页面内未见 getWindowAvoidArea/statusBarHeight 等内容避让实现 —— ' +
+        '若内容顶部未自加状态栏高度 padding,会与系统状态栏文字/图标重合。' +
+        '仅背景层 expandSafeArea 而内容层不延伸的设计(Stack 分层)无需此项。' +
+        '请按 Phase 5 窗口模式证据⑤核对内容避让实现 file:line');
+    }
+  }
+
+  // CAND:页间策略不一致(可能有据可依,例如该页本身不沉浸)
+  if (withExpand.length > 0 && withExpand.length < pages.length) {
+    const missing = pages.filter((s) => !s.hasExpandSafeArea).map((s) => s.rel);
+    report('CAND', 'window-mode-inconsistent', missing[0], 1,
+      `expandSafeArea 在页面间不一致,未声明的页面:${missing.join(', ')} —— ` +
+      '需在报告中给出理由,或补齐');
+  }
+}
+
+/** 字符串资源残留 Android 转义引号:"…" 是转义语法,不是文本内容。 */
+function checkStringResources(resourcesDir) {
+  const files = [];
+  const walkRes = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { walkRes(p); } else if (e.name === 'string.json') { files.push(p); }
+    }
+  };
+  walkRes(resourcesDir);
+
+  for (const f of files) {
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(f, 'utf8'));
+    } catch {
+      continue;
+    }
+    const arr = parsed['string'];
+    if (!Array.isArray(arr)) { continue; }
+    for (const item of arr) {
+      const v = item['value'];
+      if (typeof v === 'string' && v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+        report('GATE', 'string-quote-leak', path.basename(f), 1,
+          `资源 ${item['name']} 的值首尾残留字面引号,UI 上会显示出引号`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------- 主流程
+
+/**
+ * GATE R11:转换后的页面从未成为启动路由。
+ *
+ * 「注册过」不等于「会被加载」:main_pages.json 里有 pages/X,只说明它可被路由到;
+ * 真正决定启动画面的是 UIAbility 里的 loadContent('pages/Y')。二者不一致时:
+ *   - 编译永远通过(两个文件都合法、资源都存在);
+ *   - 静态引用检查全过;
+ *   - 唯一症状是启动后看到脚手架的 Hello World,而转换成果一次也没被显示。
+ * 该缺陷只有真机启动能发现,但它的判据完全是词法的 —— 所以定为 GATE。
+ *
+ * 判据(三支,命中任一即报):
+ *   (1) loadContent 的目标 .ets 不存在;
+ *   (2) 目标是 DevEco 脚手架残留页(@Entry + 'Hello World' 字面量 + 不引用任何 app 资源);
+ *   (3) 工程内有多个 @Entry 页,但没有任何一个非脚手架页被任何 loadContent 加载。
+ * 判据 (2) 判的是脚手架模板的特征,对所有 DevEco 新工程一致,不含任何 app 专属知识。
+ */
+function checkEntryRoute(scans, etsDir) {
+  const abilityFiles = scans.filter((s) => /ability/i.test(s.rel));
+  if (abilityFiles.length === 0) {
+    return;
+  }
+
+  // FileScan 只带相对路径(无 abs 字段),故由 etsDir + rel 复原绝对路径,
+  // 不改动共享的 FileScan 接口。
+  const root = etsDir.replace(/[\\/]+$/, '');
+  const absOfRel = (rel) => root + '/' + rel;
+
+  // 收集全部 loadContent 目标
+  const targets = [];
+  for (const a of abilityFiles) {
+    const lines = fs.readFileSync(absOfRel(a.rel), 'utf8').split('\n');
+    lines.forEach((l, i) => {
+      const m = /loadContent\(\s*['"]([^'"]+)['"]/.exec(l);
+      if (m !== null) {
+        targets.push({ rel: a.rel, line: i + 1, target: m[1] });
+      }
+    });
+  }
+  if (targets.length === 0) {
+    return;
+  }
+
+  /**
+   * 是否为 DevEco 脚手架残留页 —— **按特征打分,不按「缺少某物」判定**。
+   *
+   * 曾经的写法要求「零 app 资源引用」,结果漏报:真实脚手架页**确实**引用了
+   * 一个 app 资源(`$r('app.float.page_text_font_size')`),于是它被当成已转换页,
+   * 规则在真工程上静默失效 —— 而简化过的测试夹具里没有那句引用,测试照样全绿。
+   * 教训:判据一旦依赖「不存在某物」,就会被夹具与真实产物的细微差异掩盖。
+   *
+   * 改为对 DevEco 默认模板的固有特征打分,命中 >= 3 项即认定为脚手架。
+   * 这些特征是模板自带的,与被转换的 app 无关;逐项都可能随 DevEco 版本微调,
+   * 但不会同时消失 3 项以上。
+   */
+  const isScaffold = (abs) => {
+    if (!fs.existsSync(abs)) {
+      return false;
+    }
+    const t = fs.readFileSync(abs, 'utf8');
+    if (!/@Entry/.test(t)) {
+      return false;
+    }
+    let score = 0;
+    if (/Hello\s+World/.test(t)) { score++; }
+    if (/@State\s+message\s*:\s*string/.test(t)) { score++; }
+    if (/\.id\(\s*['"]HelloWorld['"]\s*\)/.test(t)) { score++; }
+    if (/struct\s+Index\b/.test(t)) { score++; }
+    if (/RelativeContainer\s*\(/.test(t) && /__container__/.test(t)) { score++; }
+    if (/['"]Welcome['"]/.test(t)) { score++; }
+    return score >= 3;
+  };
+
+  const absOf = (target) => root + '/' + target.replace(/^\/+/, '') + '.ets';
+
+  // **前置条件:工程内必须至少存在一个已转换页面。**
+  // 尚未转换任何页面的空工程里,loadContent 指向脚手架页是**正确**状态 ——
+  // 此时无「转换成果」可要求,报错纯属噪声,而 GATE 的噪声会训练使用者忽略它。
+  // 因此三支判据全部以「已有转换产出」为前提。
+  const convertedPages = scans.filter((s) => s.isPage && !isScaffold(absOfRel(s.rel)));
+  if (convertedPages.length === 0) {
+    return;
+  }
+
+  let loadsAConvertedPage = false;
+
+  for (const t of targets) {
+    const abs = absOf(t.target);
+    if (!fs.existsSync(abs)) {
+      report('GATE', 'entry-route-not-converted', t.rel, t.line,
+        `loadContent 的目标页不存在:'${t.target}' —— 期望文件 ${abs.replace(/\\/g, '/')}`);
+      continue;
+    }
+    if (isScaffold(abs)) {
+      report('GATE', 'entry-route-not-converted', t.rel, t.line,
+        `loadContent 加载的是 DevEco 脚手架残留页 '${t.target}'(命中模板特征 >= 3 项),` +
+        `而工程内已有 ${convertedPages.length} 个转换产出页(${convertedPages.map((s) => s.rel).join(', ')})` +
+        ' —— 转换后的页面从未成为启动路由。改为本批产出的入口页' +
+        '(通常对应 Android 侧持 MAIN/LAUNCHER 的那个 Activity)');
+      continue;
+    }
+    loadsAConvertedPage = true;
+  }
+
+  // 判据 (3):有已转换页,但没有任何一个被加载(目标既非脚手架、也不在转换产出里,
+  // 例如指向了一个中间页或占位页)
+  if (!loadsAConvertedPage) {
+    report('GATE', 'entry-route-not-converted', targets[0].rel, targets[0].line,
+      `工程内有 ${convertedPages.length} 个已转换页面(${convertedPages.map((s) => s.rel).join(', ')}),` +
+      '但没有任何一个被 loadContent 加载 —— 至少一个非脚手架页必须成为启动路由');
+  }
+}
+
+/**
+ * GATE R12: 代码字面尺寸与 measure_pack.json 实测值偏差超阈值。
+ *
+ * 针对「测归测、写归写」的失效模式：agent 跑了 measure_pack 并在轨迹里写出正确换算
+ * （如「84px = 32dp」），但代码里写的是另一套数字（84vp / Material 记忆值 24vp）。
+ *
+ * 判据：
+ * 1. 页面目录下存在 measure_pack.json（有实测值）
+ * 2. 代码中出现字面数字尺寸（.width(N) / .height(N) / .size({width:N,height:N})）
+ * 3. 该数字与 measure_pack 中任一关键节点的实测尺寸（vp 换算后）偏差 > 30%
+ *
+ * 排除：
+ * - 百分比字符串 width('100%')
+ * - 资源引用 $r('app.float.xxx')
+ * - layoutWeight(1) 等弹性布局
+ * - 小于 8vp 的数字（padding/间距等，不属于"关键区域尺寸"）
+ *
+ * **密度置信度决定本规则的档位**：measure_pack.json 的所有 vp 都由密度换算而来，
+ * 密度错一次，全页 vp 整体差 2~3 倍，此时本规则会对几乎每个字面尺寸报错 —— 一批
+ * 假阳性比没有门禁更糟（会把 agent 推去"修"正确的代码）。因此：
+ *   - `density.confident === true`（设备真值，或反解命中 >= 2 个 dp 档且优势明确）→ `[GATE]`
+ *   - `confident === false` 或字段缺失（旧版 measure_pack.json）→ 降级为 `[CANDIDATES]`
+ * 降级不是放过：CANDIDATES 仍进 Phase 5 待核清单，只是不再当零歧义缺陷卡构建。
+ * 重跑 measure_pack.js（最好是重采一次带 device 字段的 meta.json）即可恢复 GATE 档。
+ *
+ * 报告时附带最接近的实测节点信息，供快速定位。
+ */
+function checkSizeMismatch(scans, uiInfoDir) {
+  // 遍历 ui_info/page_NNNN_ActivityName/ 目录
+  let pagedirs = [];
+  try {
+    const entries = fs.readdirSync(uiInfoDir, { withFileTypes: true });
+    pagedirs = entries
+      .filter((e) => e.isDirectory() && /^(page|manual)_\d{4}_/.test(e.name))
+      .map((e) => path.join(uiInfoDir, e.name));
+  } catch {
+    return;
+  }
+
+  // interface MeasuredNode {
+    // id: string;
+    // widthVp: number;
+    // heightVp: number;
+  // }
+
+  for (const pageDir of pagedirs) {
+    const measurePackPath = path.join(pageDir, 'measure_pack.json');
+    if (!fs.existsSync(measurePackPath)) {
+      continue;
+    }
+
+    let measureData;
+    try {
+      measureData = JSON.parse(fs.readFileSync(measurePackPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    // measure_pack.js 的 schema:density 是对象 { value, source, evidence },
+    // 节点在 `regions` 数组里且 wVp/hVp 已换算好(density 无法反解时为 null)。
+    // 勿改回 measureData.density / measureData.nodes —— 那两个键不存在,
+    // 读到 undefined 后本规则会静默跳过每一页,等于没有门禁。
+    const density = measureData.density && typeof measureData.density.value === 'number'
+      ? measureData.density.value
+      : 0;
+    if (density <= 0) {
+      continue; // density 反解失败时 wVp/hVp 全为 null,无实测值可比
+    }
+    // 密度置信度 → 本规则档位。字段缺失(旧版 measure_pack.json)按**不可信**处理:
+    // 那些包正是用有偏的反解算法产出的,拿它们卡 GATE 会造成成批假阳性。
+    const densityConfident = measureData.density.confident === true;
+    const densitySource = typeof measureData.density.source === 'string'
+      ? measureData.density.source
+      : 'unknown';
+    const sev = densityConfident ? 'GATE' : 'CAND';
+    const densityNote = densityConfident
+      ? ''
+      : `【降级为 CANDIDATES:该页 density=${density} 来源 ${densitySource} 且未通过置信判据` +
+        (measureData.density.confident === undefined ? '(旧版 measure_pack.json 无 confident 字段)' : '') +
+        (measureData.density.rival
+          ? `,次优候选 ${measureData.density.rival.density}` : '') +
+        ';请先用 `adb shell wm density` 核实密度或重跑 measure_pack.js,再判断本条是否成立】'
+      ;
+
+    // 提取关键节点尺寸(wVp/hVp 已由 measure_pack 换算,>= 8vp 才算"关键区域")
+    const nodes = [];
+    if (Array.isArray(measureData.regions)) {
+      for (const r of measureData.regions) {
+        if (typeof r.wVp !== 'number' || typeof r.hVp !== 'number') {
+          continue;
+        }
+        if (r.wVp < 8 || r.hVp < 8) {
+          continue; // 跳过过小节点
+        }
+        const label = r.text || r.desc || r.role || `node_${r.node}`;
+        nodes.push({
+          id: `${r.role || 'node'}#${r.node}${label !== r.role ? ` (${label})` : ''}`,
+          widthVp: r.wVp,
+          heightVp: r.hVp
+        });
+      }
+    }
+
+    if (nodes.length === 0) {
+      continue;
+    }
+
+    // 推测对应的页面文件（page_NNNN_ActivityName → ActivityNamePage.ets 或 ActivityName.ets）
+    const pageName = path.basename(pageDir).replace(/^(page|manual)_\d{4}_/, '');
+    const candidates = [
+      `${pageName}Page.ets`,
+      `${pageName}.ets`,
+      `${pageName.replace(/Activity$/, '')}Page.ets`
+    ];
+
+    let targetScan = null;
+    for (const c of candidates) {
+      const s = scans.find((x) => x.rel.endsWith('/' + c));
+      if (s) {
+        targetScan = s;
+        break;
+      }
+    }
+
+    if (!targetScan) {
+      continue;
+    }
+    // 绑定为非空 const:下面的 checkDim 是闭包,捕获 targetScan 时会丢掉上面这次收窄。
+    const scan = targetScan;
+
+    // 在代码中匹配 .width(N) / .height(N) / .size({width:N,height:N})
+    const code = scan.text;
+    const lines = code.split('\n');
+
+    // 正则：捕获数字字面量尺寸
+    const reWidth = /\.width\((\d+(?:\.\d+)?)\)/g;
+    const reHeight = /\.height\((\d+(?:\.\d+)?)\)/g;
+    const reSize = /\.size\(\s*\{\s*width\s*:\s*(\d+(?:\.\d+)?)\s*,\s*height\s*:\s*(\d+(?:\.\d+)?)\s*\}\s*\)/g;
+
+    const checkDim = (val, lineIdx, axis) => {
+      if (val < 8) {
+        return; // 跳过小尺寸
+      }
+
+      // 找最接近的实测节点
+      let closest = null;
+      let minDiff = Infinity;
+
+      for (const n of nodes) {
+        const measured = axis === 'width' ? n.widthVp : n.heightVp;
+        const diff = Math.abs(measured - val);
+        if (diff < minDiff) {
+          minDiff = diff;
+          closest = n;
+        }
+      }
+
+      if (!closest) {
+        return;
+      }
+
+      const measured = axis === 'width' ? closest.widthVp : closest.heightVp;
+      const ratio = minDiff / measured;
+
+      // 阈值：偏差 > 30%
+      if (ratio > 0.3 && minDiff > 8) {
+        report(
+          sev,
+          'size-mismatch-vs-measure',
+          scan.rel,
+          lineIdx + 1,
+          `代码写 .${axis}(${val}),但 measure_pack.json 中最接近节点 ${closest.id} 的实测值为 ${measured}vp ` +
+          `(偏差 ${minDiff}vp,${Math.round(ratio * 100)}%)。` +
+          `measure_pack 已产出实测值时必须采用,不得用 Material 规范记忆值或"与兄弟页保持一致"等惯例覆盖 ` +
+          `—— 参见 conversion-procedure.md Phase 4.2 硬性要求（尺寸）` + densityNote
+        );
+      }
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      let m;
+
+      reWidth.lastIndex = 0;
+      while ((m = reWidth.exec(line)) !== null) {
+        checkDim(parseFloat(m[1]), i, 'width');
+      }
+
+      reHeight.lastIndex = 0;
+      while ((m = reHeight.exec(line)) !== null) {
+        checkDim(parseFloat(m[1]), i, 'height');
+      }
+
+      reSize.lastIndex = 0;
+      while ((m = reSize.exec(line)) !== null) {
+        checkDim(parseFloat(m[1]), i, 'width');
+        checkDim(parseFloat(m[2]), i, 'height');
+      }
+    }
+  }
+}
+
+function walkEts(dir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === 'build' || e.name === 'oh_modules' || e.name === 'node_modules') { continue; }
+      walkEts(p, acc);
+    } else if (e.name.endsWith('.ets')) {
+      acc.push(p);
+    }
+  }
+  return acc;
+}
+
+function argOf(flag) {
+  const argv = process.argv;
+  const i = argv.indexOf(flag);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+}
+
+function main() {
+  const etsDir = argOf('--ets');
+  const resDir = argOf('--resources');
+  const androidDir = argOf('--android');
+  const uiInfoArg = argOf('--ui-info');
+
+  if (etsDir === '') {
+    console.error('用法: node arkts_static_check.js --ets <.../<ui_module>/src/main/ets> [--resources <.../<ui_module>/src/main/resources>] [--android <android_project_dir>] [--ui-info <ui_info_root>]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(etsDir)) {
+    console.error(`ets 目录不存在: ${etsDir}`);
+    process.exit(2);
+  }
+
+  const files = walkEts(etsDir, []);
+  const scans = [];
+  for (const f of files) {
+    scans.push(checkFile(f, path.relative(etsDir, f).replace(/\\/g, '/')));
+  }
+  checkWindowMode(scans);
+  if (resDir !== '') {
+    checkStringResources(resDir);
+    checkSvgTintChannel(scans, resDir);
+    checkFullViewportTint(scans, resDir);
+    checkMediaContentUsable(scans, resDir);
+  }
+  if (androidDir !== '' && fs.existsSync(androidDir)) {
+    checkAndroidImmersive(scans, androidDir);
+  }
+  checkEntryRoute(scans, etsDir);
+
+  // GATE R12: 代码字面尺寸与 measure_pack 实测偏差超阈值。
+  // --ui-info 显式指定 ui_info_root;不给时按 SKILL.md 的默认位置
+  // ${harmony_project_dir}/.hometrans/ui_info 推导。UI 模块名不一定是 entry
+  // (分层工程如 products/phone,层数也不固定),所以不能剥固定前缀:先剥 src/main/ets
+  // 得模块目录,再逐层向上找真实存在的 .hometrans/ui_info。都找不到就退回模块目录的
+  // 上一层候选(单模块工程的原行为),由下方 existsSync 判 false。
+  const defaultUiInfoDir = (dir) => {
+    const moduleDir = dir.replace(/[\\/]+$/, '').replace(/[\\/]src[\\/]main[\\/]ets$/, '');
+    let cur = moduleDir;
+    for (let depth = 0; depth < 8; depth++) {
+      const cand = path.join(cur, '.hometrans', 'ui_info');
+      if (fs.existsSync(cand)) return cand;
+      const up = path.dirname(cur);
+      if (up === cur) break;
+      cur = up;
+    }
+    return path.join(path.dirname(moduleDir), '.hometrans', 'ui_info');
+  };
+  const uiInfoDir = uiInfoArg !== '' ? uiInfoArg : defaultUiInfoDir(etsDir);
+  if (fs.existsSync(uiInfoDir)) {
+    checkSizeMismatch(scans, uiInfoDir);
+  }
+
+  // GATE R8/R9: SVG 内容验证 + 形状语义比对（需要 --resources 和 ui_info）
+  if (resDir !== '' && fs.existsSync(uiInfoDir)) {
+    checkSvgSemantics(scans, resDir, uiInfoDir);
+  }
+
+  const gate = findings.filter((f) => f.sev === 'GATE');
+  const cand = findings.filter((f) => f.sev === 'CAND');
+
+  console.log(`arkts_static_check — 扫描 ${files.length} 个 .ets 文件\n`);
+
+  console.log(`[GATE] 零歧义缺陷,必须清零 —— ${gate.length} 条`);
+  if (gate.length === 0) {
+    console.log('  (无)');
+  } else {
+    for (const f of gate) {
+      console.log(`  ${f.rule.padEnd(26)} ${f.file}:${f.line}`);
+      console.log(`  ${' '.repeat(26)} ${f.msg}`);
+    }
+  }
+
+  console.log(`\n[CANDIDATES] 仅供人工核对,不判定对错 —— ${cand.length} 条`);
+  if (cand.length === 0) {
+    console.log('  (无)');
+  } else {
+    for (const f of cand) {
+      console.log(`  ${f.rule.padEnd(26)} ${f.file}:${f.line}`);
+      console.log(`  ${' '.repeat(26)} ${f.msg}`);
+    }
+    console.log('\n  ↑ 这些位置是否正确取决于 Android 源侧意图(锚定方向、层叠次序、是否沉浸),');
+    console.log('    词法分析无法判定。请在 Phase 5 的「位置锚点证据」「交互可达性证据」');
+    console.log('    「窗口模式证据」中逐条标注来源,不要因为本段有输出就直接改代码。');
+  }
+
+  process.exit(gate.length > 0 ? 1 : 0);
+}
+
+main();