deveco_hmigbot 0.21.5

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * check-anchors.mjs — 字面锚点与 PRD 覆盖记账（不做语义判断，只对格式和行号记账）。
+ * 实证：0.14.1 基准 13 条失败用例 11 条是 PRD 明写的 id/文本没落地（resumeInput、recordStart、"工作通知"…），且逐轮随机。
+ * 语义理解归 2b 的模型（读 PRD/源码产断言卡）；本脚本只核两件事：
+ *   ① 字面量真有：台账 features[].literals（parse-cards 从断言卡机械抽的反引号/「」/“” 与 "id 为 X"）在产物源码/资源里必须出现
+ *      → literal_missing（case）。探针："前缀：值"复合文本只探前缀（值多为动态数据）；对账两边都做 NFKC+小写归一化
+ *      （全半角标点/大小写写法差异不算缺），颜色 #RRGGBB 只比十六进制位（产物常写 0xFFRRGGBB）。
+ *      严宽只看来源，不看措辞：锚点指向 PRD 或断言用 "id 为 X" 句式的字面量是契约，缺失立 case（实证基准失败 11/13 属此类）；
+ *      锚点指向源码的字面量是描述（调用签名/注解/API 名/源资源名混在其中，实证一轮 111 条 literal_missing 109 条属此），
+ *      缺失只记 info `literal_unmatched`，不进闭合立案，报告里可看。
+ *   ② PRD 逐行覆盖（有 PRD 时）：PRD 的每条需求行（列表项）须被至少一条断言的锚点 `PRD.md:行` 指向，
+ *      或该行标记的字面量（反引号/「」/“”）全部出现在台账断言的字面量里（模型原样转写了、只是锚点指向别处）；
+ *      指向的行连同其缩进子项算覆盖，指向标题算覆盖整节；锚点行号越界=PRD 可能已变更
+ *      → prd_uncovered / prd_anchor_stale（case）。PRD 不是每次都有：--prd 未给时从断言锚点里找 basename 含 prd 的文件，找不到即跳过。
+ * 全部为软立案（final 阶段修或带理由豁免），绝不设硬违规——字面匹配与行号记账都有天然误差。
+ * 用法：check-anchors.mjs --project <root> [--ledger <ledger.json>] [--prd <PRD 文件>] [--json out]
+ *       缺省自动找 <project>/spec/ledger/ledger.json；2b 装账后可直接跑本命令看 PRD 覆盖差集，按差集补卡。
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, relative, basename, dirname, isAbsolute } from 'node:path';
+import { probeOf, MARK_RE, isPlaceholder, ID_RE, normText, hexForms } from '../lib/literals.mjs';
+
+const argv = process.argv.slice(2);
+if (argv.includes('--help')) { console.log(readFileSync(new URL(import.meta.url), 'utf8').split('\n').filter(l => /^ \* /.test(l)).map(l => l.slice(3)).join('\n')); process.exit(0); }
+const argOf = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const PROJECT = argOf('--project', null);
+if (!PROJECT || !existsSync(PROJECT)) { console.error('usage: check-anchors.mjs --project <root> [--ledger <ledger.json>] [--prd <file>] [--json out]'); process.exit(3); }
+const LEDGER = argOf('--ledger', join(PROJECT, 'spec', 'ledger', 'ledger.json'));
+const OUT = argOf('--json', null);
+const rel = (p) => relative(process.cwd(), p) || '.';   // 落盘产物不写机器绝对路径（工作区须可搬运）
+
+// 语料：所有模块 src/main + AppScope 下的 ets/ts/json/json5（跳过构建产物、依赖与 spec）
+function corpusFiles(root) {
+  const acc = [];
+  (function walk(d, depth) {
+    let ents; try { ents = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) { if (/^(build|oh_modules|node_modules|\.hvigor|\.git|\.idea|spec)$/.test(e.name)) continue; if (depth < 8) walk(p, depth + 1); }
+      else if (/(^|[\\/])(src[\\/]main|AppScope)([\\/]|$)/.test(relative(root, p) + '/')) {
+        // 源码与资源：resources/ 下任何文本文件都算语料（rawfile 里的 RSS/CSV/JSON fixture 是字面量的真正落点——实证一张票就是它），大文件跳过
+        const inRes = /[\\/]resources[\\/]/.test(p);
+        if (/\.(ets|ts|json|json5)$/.test(e.name) || (inRes && /\.(xml|txt|csv|md|html|htm|properties|yaml|yml)$/i.test(e.name))) { try { if (statSync(p).size <= 4 * 1024 * 1024) acc.push(p); } catch { /* 读不到不入语料 */ } }
+      }
+    }
+  })(root, 0);
+  return acc;
+}
+
+// PRD 需求行 = 代码围栏外的列表项（- * + 或 "1."），带缩进；标题带级别。纯结构，不理解内容。
+function prdLines(md) {
+  const lines = String(md).split(/\r?\n/); if (lines.length && lines[lines.length - 1] === '') lines.pop();   // 末尾换行不算一行
+  const req = new Map(); const heads = new Map(); let fence = false;
+  lines.forEach((raw, i) => {
+    if (/^\s*(```|~~~)/.test(raw)) { fence = !fence; return; }
+    if (fence) return;
+    const h = raw.match(/^(#{1,6})\s+\S/); if (h) { heads.set(i + 1, h[1].length); return; }
+    const m = raw.match(/^(\s*)(?:[-*+]|(\d+)[.)])\s+(\S.*)$/); if (m) req.set(i + 1, { indent: m[1].length, text: m[3].trim(), ordered: m[2] !== undefined, no: m[2] !== undefined ? Number(m[2]) : null });
+  });
+  return { total: lines.length, req, heads, lines };
+}
+// 锚点 "path:58" / "path:58-60" / "path:58,61" → { file, lines[] }
+function parseAnchor(a) {
+  const m = String(a || '').match(/^(.*?)[:：](\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$/); if (!m) return null;   // 全角冒号也认（卡片里常见）
+  const nums = [];
+  for (const part of m[2].split(',')) { const r = part.split('-').map(Number); if (r.length === 2) { for (let k = r[0]; k <= Math.min(r[1], r[0] + 50); k++) nums.push(k); } else nums.push(r[0]); }
+  return { file: m[1], lines: nums };
+}
+// 覆盖两种算法都是结构记账：① 锚点行号（含缩进子项、标题整节）；② 需求行里用反引号/「」/“”标记的字面量（去占位符，口径同 parse-cards）
+//   全部出现在台账断言的字面量里（模型把 id/文本原样转写进了断言，只是锚点指向了别的文件，如 semantic.json——实证 bikepacking 卡片如此）。
+// refLines: Map<行号, 断言 id[]>。返回逐行对照表（mode: anchor|child|section|step|literal|uncovered，by: 断言 id）供报告直接投影
+//   step：有序列表里被锚定的末项（结果位）之前的连续步骤（锚定结果行即覆盖其前置动作步骤；锚在中间项不外扩）
+function coverage(md, refLines, ledgerLits = new Set(), litOwners = new Map()) {
+  const { total, req, heads, lines } = prdLines(md);
+  const reqKeys = [...req.keys()].sort((a, b) => a - b);
+  const covered = new Map(); const stale = [];
+  const mark = (k, mode, ids) => { const c = covered.get(k); if (!c) covered.set(k, { mode, by: new Set(ids) }); else for (const i of ids) c.by.add(i); };
+  for (const [L, ids] of refLines) {
+    if (L < 1 || L > total) { stale.push(L); continue; }
+    if (req.has(L)) {
+      mark(L, 'anchor', ids);
+      const ind = req.get(L).indent;
+      for (const k of reqKeys) { if (k <= L) continue; if (req.get(k).indent > ind) mark(k, 'child', ids); else break; }
+    } else if (heads.has(L)) {
+      const lvl = heads.get(L);
+      for (let k = L + 1; k <= total; k++) { if (heads.has(k) && heads.get(k) <= lvl) break; if (req.has(k)) mark(k, 'section', ids); }
+    } // 指向散文行：不算错也不扩散
+  }
+  let byLiteral = 0;
+  for (const k of reqKeys) {
+    if (covered.has(k)) continue;
+    const marks = [...req.get(k).text.matchAll(MARK_RE)].map(m => (m[1] ?? m[2] ?? m[3] ?? '').trim()).filter(v => v && !isPlaceholder(v));
+    if (marks.length && marks.every(x => ledgerLits.has(x) || ledgerLits.has(probeOf(x)))) {
+      const ids = new Set(); for (const x of marks) for (const id of (litOwners.get(x) || litOwners.get(probeOf(x)) || [])) ids.add(id);
+      mark(k, 'literal', [...ids]); byLiteral++;
+    }
+  }
+  // 有序列表 = 步骤序列：锚定第 k 项即断言了 1..k 步之后的状态——同一列表里（同缩进、连续编号项）它之前的步骤行随之覆盖；之后的项不覆盖（可能是另一结果）
+  for (const k of reqKeys) {
+    const c = covered.get(k); if (!c || c.mode === 'step' || !req.get(k).ordered) continue;
+    const ind = req.get(k).indent; let prevNo = req.get(k).no;
+    // 只有锚定"列表末项"（结果位）才回溯覆盖前置步骤；锚在中间项不外扩——功能清单式有序列表不会因锚了一条而整段算覆盖
+    { let last = true; for (let L = k + 1; L <= total; L++) { if (heads.has(L)) break; const r = req.get(L); if (!r) { if (/\S/.test(lines[L - 1] || '')) continue; break; } if (r.indent > ind) continue; if (r.indent < ind || !r.ordered) break; if (r.no === prevNo + 1) last = false; break; } if (!last) continue; }
+    for (let L = k - 1; L >= 1; L--) {
+      if (heads.has(L)) break;
+      const r = req.get(L); if (!r) { if (/\S/.test(lines[L - 1] || '')) continue; break; } // 散文行不断链；空行断链
+      if (r.indent > ind) continue;                                     // 更深的子项属于上一步，跳过
+      if (r.indent < ind || !r.ordered || r.no !== prevNo - 1) break;    // 出列表 / 非有序 / 编号不连续 → 到头
+      prevNo = r.no;
+      if (!covered.has(L)) mark(L, 'step', [...c.by]);
+    }
+  }
+  const table = reqKeys.map(k => { const c = covered.get(k); return { line: k, text: req.get(k).text, mode: c ? c.mode : 'uncovered', by: c ? [...c.by] : [] }; });
+  const uncovered = table.filter(r => r.mode === 'uncovered').map(r => ({ line: r.line, text: r.text }));
+  return { total, requirementLines: reqKeys.length, covered: reqKeys.length - uncovered.length, byLiteral, uncovered, stale, table };
+}
+
+// PRD 文件名先定下来（① 的严宽判据用；② 的覆盖记账也用同一个）：--prd 显式 > 按断言锚点自动定位（工程→工作区根→启动目录）
+let PRD = argOf('--prd', null);
+let PRD_BASE = PRD ? basename(PRD).toLowerCase() : null;
+const files = corpusFiles(PROJECT);
+const corpus = normText(files.map(f => { try { return readFileSync(f, 'utf8'); } catch { return ''; } }).join('\n'));
+const has = (probe) => { const p = normText(probe).trim(); return p.length > 0 && corpus.includes(p); };
+const findings = []; let prdCoverage = null;
+const stats = { corpusFiles: files.length, ledger: null, literalsChecked: 0, literalMissing: 0, literalUnmatched: 0, prd: null, prdRequirementLines: 0, prdCovered: 0, prdUncovered: 0, prdStaleAnchors: 0 };
+
+let feats = [];
+if (existsSync(LEDGER)) {
+  let ledger = null; try { ledger = JSON.parse(readFileSync(LEDGER, 'utf8')); } catch { /* 坏 JSON 由 ledger verify 报 */ }
+  feats = ledger && Array.isArray(ledger.features) ? ledger.features : [];
+  stats.ledger = relative(PROJECT, LEDGER);
+}
+
+if (!PRD) {
+  // 自动定位：先工程、再工作区根（工程的上级）、最后启动目录——避免启动目录里恰好有个同名 PRD 抢先
+  const cand = [...new Set(feats.map(f => parseAnchor(f.anchor)).filter(Boolean).map(a => a.file).filter(p => /prd/i.test(basename(p))))];
+  for (const c of cand) { for (const base of [PROJECT, dirname(PROJECT), process.cwd()]) { const p = isAbsolute(c) ? c : resolve(base, c); if (existsSync(p)) { PRD = p; break; } } if (PRD) break; }
+  if (PRD) PRD_BASE = basename(PRD).toLowerCase();
+}
+// ① 字面量真有（探针与严宽口径见文件头）
+// PRD 归属：--prd 已给（或按锚点自动定位到）时按该文件名判，PRD 不叫 *prd* 也不漏；只有 PRD 未知时才退回名字含 prd
+const anchorFile = (f) => basename(String(f.anchor || '').replace(/\\/g, '/').replace(/[:：]\d.*$/, ''));   // Windows 反斜杠锚点也认
+const isPrdAnchored = (f) => PRD_BASE ? anchorFile(f).toLowerCase() === PRD_BASE : /prd/i.test(anchorFile(f));
+const idLiterals = (f) => new Set([...String(f.note || '').matchAll(ID_RE)].map(m => m[1].replace(/[-_]+$/, '')));
+for (const f of feats) {
+  if (!Array.isArray(f.literals) || !f.literals.length || f.status === 'waived') continue;
+  for (const lit of f.literals) {
+    stats.literalsChecked++;
+    const probes = [...new Set([String(lit), probeOf(lit), ...hexForms(lit)].filter(Boolean))];
+    if (probes.some(has)) continue;
+    const where = `断言 ${f.id}（${f.card || f.domain || '?'}）引用「${lit}」在工程源码/资源中未出现${probes.length > 1 ? `（探针 ${probes.map(p => `「${p}」`).join(' ')}）` : ''}`;
+    if (isPrdAnchored(f) || idLiterals(f).has(String(lit))) {
+      stats.literalMissing++;
+      findings.push({ severity: 'case', type: 'literal_missing', name: `${f.id}:${lit}`, file: '', evidence: where });
+    } else {
+      stats.literalUnmatched++;
+      findings.push({ severity: 'info', type: 'literal_unmatched', name: `${f.id}:${lit}`, file: '', evidence: `${where}；锚点指向源码，字面量是描述不是契约，不立案` });
+    }
+  }
+}
+
+// ② PRD 逐行覆盖
+const anchors = feats.map(f => ({ id: f.id, a: parseAnchor(f.anchor) })).filter(x => x.a);
+if (PRD && existsSync(PRD)) {
+  stats.prd = rel(resolve(PRD));
+  const md = readFileSync(PRD, 'utf8');
+  const pb = basename(PRD).toLowerCase();
+  const refs = new Set(); const byLine = new Map();
+  for (const { id, a } of anchors) { if (basename(a.file).toLowerCase() !== pb) continue; for (const L of a.lines) { refs.add(L); if (!byLine.has(L)) byLine.set(L, []); byLine.get(L).push(id); } }
+  const ledgerLits = new Set(); const litOwners = new Map();
+  for (const f of feats) for (const l of f.literals || []) { for (const k of [String(l), probeOf(l)]) { ledgerLits.add(k); if (!litOwners.has(k)) litOwners.set(k, []); litOwners.get(k).push(f.id); } }
+  const cov = coverage(md, byLine, ledgerLits, litOwners);
+  stats.prdRequirementLines = cov.requirementLines; stats.prdCovered = cov.covered; stats.prdCoveredByLiteral = cov.byLiteral; stats.prdUncovered = cov.uncovered.length; stats.prdStaleAnchors = cov.stale.length;
+  prdCoverage = { prd: stats.prd, table: cov.table };   // 逐行对照表：ledger render --anchors 直接投影成 PRD 覆盖对照，不再由模型手写
+  for (const u of cov.uncovered) findings.push({ severity: 'case', type: 'prd_uncovered', name: `PRD:${u.line}`, file: relative(dirname(PROJECT), PRD), evidence: `PRD 第 ${u.line} 行需求无断言锚点指向（转写漏项或应并入邻行）：${u.text.slice(0, 90)}` });
+  for (const L of cov.stale) findings.push({ severity: 'case', type: 'prd_anchor_stale', name: (byLine.get(L) || []).join(','), file: relative(dirname(PROJECT), PRD), evidence: `断言 ${(byLine.get(L) || []).join(',')} 的 PRD 锚点第 ${L} 行越界（PRD 共 ${cov.total} 行，PRD 可能已变更，需重对行号）` });
+} else if (PRD) {
+  findings.push({ severity: 'case', type: 'prd_anchor_stale', name: 'prd', file: '', evidence: `--prd 指定的文件不存在：${PRD}` });
+}
+
+const report = { project: rel(resolve(PROJECT)), findings, stats, ...(prdCoverage ? { prdCoverage } : {}) };
+if (OUT) writeFileSync(OUT, JSON.stringify(report, null, 2));
+console.log(`[check-anchors] 语料 ${stats.corpusFiles} 文件 · 断言字面量 ${stats.literalsChecked} 缺 ${stats.literalMissing}${stats.literalUnmatched ? `（另 ${stats.literalUnmatched} 个源码锚点字面量未对上，info 不立案）` : ''}` + (stats.prd ? ` · PRD 需求行 ${stats.prdRequirementLines} 已覆盖 ${stats.prdCovered}（其中字面量对上 ${stats.prdCoveredByLiteral || 0}）未覆盖 ${stats.prdUncovered}${stats.prdStaleAnchors ? ` 锚点越界 ${stats.prdStaleAnchors}` : ''}` : ' · 无 PRD（锚点里没有 prd 文件或 --prd 未给）'));
+for (const f of findings.filter(x => x.severity !== 'info').slice(0, 12)) console.log(`  ▲ ${f.type} [${f.name}] ${f.evidence}`.slice(0, 180));
+process.exit(0);

package/skills/migrate-core/scripts/closure/check-api-guards.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * check-api-guards.mjs — 崩溃防护门（补门禁盲区：同步会抛的平台 API 未 try/catch → 未捕获异常杀进程）。
+ *
+ * 病根：安卓"尽力而为"能力（触感/传感器）设备不支持时静默 no-op；鸿蒙对应**同步 API 会抛**
+ * （如 vibrator.isSupportEffectSync 无振动器时抛 "Device operation failed"）。`.catch()` 只接异步拒绝，
+ * 接不住同步抛。迁移照搬调用不 try/catch → 崩（实测应用长按闪退即此）。详见 methodology/platform-api-guards.md。
+ *
+ * 判据（确定性）：调用了已知同步会抛的 API，但该调用**不在任何 try 块体内** → 硬违规。
+ * 用 brace 追踪精确判断"是否在 try{} 内"，避免注释/字符串误配。
+ * 分档（按所在栈，模拟器实测）：事件回调/定时器/生命周期等同步栈上裸调 → 违规（未捕获即杀进程）；
+ * async 函数体或 .then/.catch/.finally 回调内裸调 → 立案（同步抛转为未处理拒绝，不杀进程、不进 faultlog，静默失败）。
+ * 规则③：accessSync 返回值弃置——它返回布尔且不存在时不抛，弃置即被当成"不存在则抛"的检查，属确定性语义误用。
+ *
+ * 用法：check-api-guards.mjs --project <鸿蒙工程根> [--json out]　退出码：0 都防护 / 10 有裸调 / 3 用法错
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve, dirname } from 'node:path';
+import { walkFiles, stripComments, blankStrings, moduleSrcRoots, tryCatchRanges, enclosingTry, functionContexts, innermostContext } 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-api-guards.mjs --project <root> [--json out]'); process.exit(3); }
+
+// 已知"同步会抛"的平台 API（保守清单：确认同步抛、.catch 接不住的；异步 API 走 .catch 不在此列）
+const SYNC_THROW = [
+  { re: /\bvibrator\s*\.\s*(isSupportEffectSync|isHdHapticSupported)/g, api: 'vibrator 同步触感查询', why: '无振动器(模拟器)同步抛 Device operation failed' },
+  { re: /\.\s*beginTransaction\s*\(/g, api: 'RDB beginTransaction', why: '并发/锁冲突同步抛 801' },
+  { re: /\bsensor\s*\.\s*getSingleSensorSync\b/g, api: 'sensor 同步查询', why: '无传感器同步抛' },
+  { re: /\bdisplay\s*\.\s*getDefaultDisplaySync\b/g, api: 'display 同步查询', why: '早期调用可同步抛' },
+  // 文件同步 API：路径无权限/不存在/只读同步抛 BusinessError（13900002/13900012 等）；实测下载回调里裸调 openSync 直接杀进程。
+  // accessSync/存在性判断类返回布尔不抛，不在此列。
+  { re: /\b(?:fileIo|fs)\s*\.\s*(?:openSync|readSync|writeSync|readTextSync|writeTextSync|unlinkSync|mkdirSync|rmdirSync|copyFileSync|moveFileSync|renameSync|statSync|listFileSync|truncateSync)\s*\(/g, api: '文件同步读写', why: '路径无权限/不存在/只读时同步抛 BusinessError' },
+];
+
+const rel = f => relative(resolve(PROJECT), f).replace(/\\/g, '/');
+// 全模块扫描 + try/catch 追踪走共享层 scan.mjs（反手拷；原本地 tryRanges 已并入 tryCatchRanges）
+const ROOTS = moduleSrcRoots(resolve(PROJECT));
+
+const findings = [];
+let scanned = 0, naked = 0, nakedDeferred = 0;
+for (const ROOT of ROOTS) for (const f of walkFiles(ROOT, { match: (_p, e) => e.endsWith('.ets') || e.endsWith('.ts') })) {
+  const raw = readFileSync(f, 'utf8');
+  const code = blankStrings(stripComments(raw)); // 中和字符串+注释，保留偏移
+  let hit = false;
+  for (const rule of SYNC_THROW) { rule.re.lastIndex = 0; if (rule.re.test(code)) { hit = true; break; } }
+  if (!hit) continue;
+  scanned++;
+  const tries = tryCatchRanges(code);
+  const ctxs = functionContexts(code);
+  const inTry = (off) => !!enclosingTry(tries, off);
+  const upto = (off) => raw.slice(0, off).split('\n').length; // 偏移→行号
+  for (const rule of SYNC_THROW) {
+    rule.re.lastIndex = 0; let m;
+    while ((m = rule.re.exec(code)) !== null) {
+      if (inTry(m.index)) continue;
+      naked++;
+      const ctx = innermostContext(ctxs, m.index);
+      if (ctx && ctx.kind !== 'sync') {
+        // async 体 / Promise 回调：同步抛=未处理拒绝——不杀进程也不进 faultlog（实测），静默失败，立案不定罪
+        nakedDeferred++;
+        findings.push({ severity: 'case', type: 'unguarded_throwing_api_async', name: rule.api,
+          file: rel(f), line: upto(m.index),
+          basis: `判据：裸调位于${ctx.kind === 'async' ? ' async 函数体' : ' Promise 回调'}——同步抛转为未处理拒绝，不杀进程但也无错误出口（静默失败），除非调用链有 catch`,
+          evidence: `${rel(f)}:${upto(m.index)} ${rule.api} 未包 try/catch——${rule.why}；此处不崩但会静默失败，须 try/catch 转成明确错误出口，或确认调用链已 catch` });
+        continue;
+      }
+      findings.push({ severity: 'violation', type: 'unguarded_throwing_api', name: rule.api,
+        file: rel(f), line: upto(m.index),
+        evidence: `${rel(f)}:${upto(m.index)} ${rule.api} 未包 try/catch——${rule.why}；未捕获异常会杀进程，须 try/catch 降级 no-op` });
+    }
+  }
+}
+
+// ---- 规则③：accessSync 返回值弃置（确定性语义误用）----
+// accessSync 返回布尔、不存在时返回 false 且不抛，唯一用途就是它的返回值。语句位弃置说明被当成
+// "不存在则抛"的检查：不存在分支永远不执行（目录/文件永远建不出来），只在下游 openSync 以 13900002 露头。
+// 判据：调用前一个非空白字符是 ; { } 或文件开头（语句位）；有接收者（= ( ! , ? : && || return =>）即返回值被使用。
+let discardedAccess = 0;
+for (const ROOT of ROOTS) for (const f of walkFiles(ROOT, { match: (_p, e) => e.endsWith('.ets') || e.endsWith('.ts') })) {
+  const raw = readFileSync(f, 'utf8');
+  if (!/accessSync/.test(raw)) continue;
+  const code = blankStrings(stripComments(raw));
+  for (const m of code.matchAll(/\b(?:fileIo|fs)\s*\.\s*accessSync\s*\(/g)) {
+    let k = m.index - 1; while (k >= 0 && /\s/.test(code[k])) k--;
+    const prev = k >= 0 ? code[k] : '';
+    if (prev !== '' && !';{}'.includes(prev)) continue;
+    discardedAccess++;
+    const line = raw.slice(0, m.index).split('\n').length;
+    findings.push({ severity: 'violation', type: 'discarded_boolean_check', name: 'accessSync 返回值弃置',
+      file: rel(f), line,
+      evidence: `${rel(f)}:${line} accessSync 的返回值被弃置——它返回布尔且不存在时不抛，弃置即被当成"不存在则抛"的检查，不存在分支永远不执行。改法：if (!fileIo.accessSync(p)) { 建目录/文件 }` });
+  }
+}
+
+// ---- 规则②：@BuilderParam 传参的三种形态（官方 arkts-builderparam 指南 + FAQ faqs-arkui-229，真机复核 2026-09-21）----
+//  ① 裸引用 `键: this.xxxBuilder`：builder 体内 this 指向**接收方**子组件——体内一旦用 this.成员/方法，
+//     真机 TypeError（"xxx is not callable"/"Cannot read property"，coolmall 4 份 jscrash 同型）；体内无 this 碰巧安全。
+//  ② 箭头包裹 `键: () => { this.xxxBuilder() }`：this 指向宿主，**官方推荐写法**，真机复核正常渲染。
+//  ③ `键: this.xxxBuilder.bind(this)`：可用但触 ArkTS 约束 arkts-no-func-apply-bind-call（lint 告警，可构建），不推荐。
+//  真正必崩的只有一种：键值 lambda 体内**直接构造组件**（`键: () => { Comp({...}) }`，非 @Builder 语境构造 struct）。
+//  分级：①体内有 this → violation（不可豁免，改法=②）；①无 this → case；lambda 直构组件 → violation；③ → info。
+//  合法形态不误伤：ForEach/Repeat 的 itemGenerator 是位置参数 lambda（无键前缀）；lambda 体内调普通方法不算。
+const BUILDER_DECL = /@Builder\s+(?:(?:private|public|protected|static)\s+)*([\w$]+)\s*\(/g;   // 声明容忍修饰符（语料 45 工程 560 个带 private/public 的 @Builder）
+function builderBody(code, name) {
+  const m = new RegExp(`@Builder\\s+(?:(?:private|public|protected|static)\\s+)*${name}\\s*\\(`).exec(code);
+  if (!m) return null;
+  let i = m.index + m[0].length - 1, d = 0;
+  for (; i < code.length; i++) { if (code[i] === '(') d++; else if (code[i] === ')') { d--; if (!d) break; } }   // 跳过参数表
+  const open = code.indexOf('{', i); if (open < 0) return null;
+  d = 0;
+  for (let j = open; j < code.length; j++) { if (code[j] === '{') d++; else if (code[j] === '}') { d--; if (!d) return code.slice(open + 1, j); } }
+  return null;
+}
+let builderLambda = 0;
+for (const ROOT of ROOTS) for (const f of walkFiles(ROOT, { match: (_p, e) => e.endsWith('.ets') })) {
+  const raw = readFileSync(f, 'utf8');
+  const code = blankStrings(stripComments(raw));
+  const builderMethods = new Set([...code.matchAll(BUILDER_DECL)].map(m => m[1]));
+  for (const m of code.matchAll(/[\w$]+\s*:\s*(?:\(\s*\)|\([^)]*\))(?:\s*:\s*[\w$<>\[\], .|]+?)?\s*=>\s*\{/g)) {
+    const open = code.indexOf('{', m.index + m[0].length - 1);
+    let d = 0, end = -1;
+    for (let j = open; j < code.length; j++) {
+      if (code[j] === '{') d++;
+      else if (code[j] === '}') { d--; if (!d) { end = j; break; } }
+    }
+    if (end < 0) continue;
+    const body = code.slice(open + 1, end);
+    const line = raw.slice(0, m.index).split('\n').length;
+    const hit = body.match(/(?<![.\w])([A-Z][\w$]*)\s*\(\s*\{/);
+    if (hit) {
+      builderLambda++;
+      findings.push({ severity: 'violation', type: 'builder_lambda_component', name: hit[1],
+        file: rel(f), line,
+        evidence: `${rel(f)}:${line} 组件参数以普通 lambda 传入且体内直接构造组件 ${hit[1]}({...})——非 @Builder 语境构造 struct 必崩。改法：把该 lambda 提升为本类 @Builder 方法，再以箭头包裹传入（键: () => { this.xxxBuilder() }，官方推荐）` });
+    }
+  }
+  // ① 裸引用：`键: this.xxxBuilder`（无 .bind、无箭头）——按 builder 体内是否用 this 分级
+  for (const m of code.matchAll(/[\w$]+\s*:\s*this\.([\w$]+)\s*(?=[,}\n])/g)) {
+    if (!builderMethods.has(m[1])) continue;
+    builderLambda++;
+    const line = raw.slice(0, m.index).split('\n').length;
+    const body = builderBody(code, m[1]) || '';
+    const deps = [...new Set([...body.matchAll(/\bthis\s*\.\s*([\w$]+)/g)].map(x => x[1]))];
+    if (deps.length) {
+      findings.push({ severity: 'violation', type: 'builder_ref_unbound', name: m[1],
+        file: rel(f), line,
+        evidence: `${rel(f)}:${line} 裸引用 this.${m[1]} 传给子组件，而该 @Builder 体内用了 this.${deps.slice(0, 4).join('/this.')}${deps.length > 4 ? '…' : ''}——执行时 this 指向接收方子组件，这些成员不存在即 TypeError（官方 FAQ faqs-arkui-229 同题）。改法（官方）：键: () => { this.${m[1]}() }` });
+    } else {
+      findings.push({ severity: 'case', type: 'builder_ref_unbound', name: m[1],
+        file: rel(f), line,
+        basis: '判据：@Builder 方法以裸引用传参且体内无 this 依赖——this 指向接收方但未被使用，碰巧安全；改成箭头包裹恒安全',
+        evidence: `${rel(f)}:${line} 键值裸引用 this.${m[1]}（体内无 this）——建议改 键: () => { this.${m[1]}() }；确认无需宿主状态可豁免` });
+    }
+  }
+  // ③ bind：可用但违 ArkTS 约束，只提示
+  for (const m of code.matchAll(/[\w$]+\s*:\s*this\.([\w$]+)\.bind\(\s*this\s*\)/g)) {
+    if (!builderMethods.has(m[1])) continue;
+    const line = raw.slice(0, m.index).split('\n').length;
+    findings.push({ severity: 'info', type: 'builder_bind_call', name: m[1], file: rel(f), line,
+      evidence: `${rel(f)}:${line} this.${m[1]}.bind(this)——可用，但触 ArkTS 约束 arkts-no-func-apply-bind-call（lint 告警）；官方推荐 键: () => { this.${m[1]}() }` });
+  }
+}
+
+const report = { project: relative(process.cwd(), resolve(PROJECT)) || '.', stats: { scannedFiles: scanned, nakedCalls: naked, nakedDeferred, discardedAccess, builderLambda }, findings };
+const out = argOf('--json', null);
+if (out) { mkdirSync(dirname(resolve(out)), { recursive: true }); writeFileSync(out, JSON.stringify(report, null, 2)); }
+const vio = findings.filter(f => f.severity === 'violation');
+console.log(`[check-api-guards] 涉险文件 ${scanned} · 裸调(未防护) ${naked}（其中 async/Promise 回调内静默失败档 ${nakedDeferred}）· accessSync 弃置 ${discardedAccess}`);
+for (const v of vio.slice(0, 12)) console.log(`  ✗ ${v.evidence}`);
+const cas = findings.filter(f => f.severity === 'case');
+for (const c of cas.slice(0, 8)) console.log(`  ▲ CASE ${c.type} — ${c.evidence}`);
+if (!vio.length && !cas.length) console.log('  ✓ 会抛平台 API 均已 try/catch 防护');
+process.exit(vio.length ? 10 : 0);