@xulthekl/team-flow 0.64.0 → 0.67.0

package/scripts/lib/arch-scan-code.mjs

@@ -0,0 +1,518 @@
+// scripts/lib/arch-scan-code.mjs — tf arch scan-code：C4 代码注解扫描（v1.4 §5.4-4b）
+//
+// 定位：本机制**唯一的「A 级 · 真独立」锚**。
+//
+// 为什么必须是代码本体：C2 的锚（change 内手写 DDL）与 C3 的锚（api.md）**都产自
+// 同一条流水线**，与 registry 同源、受同一缺陷影响；对 emp-auth 的「56 表 → 1 表」
+// 崩溃**零检出**（§5.4-4 已实证）。唯一在被验证机制的**写路径之外**产生的制品是
+// **代码本体**——它由开发者提交，不经过 `arch-merge`，也不由本机制的 LLM 段产出。
+//
+// 本命令只读、**零运行时依赖**（不新增 npm 依赖——核心扫描只用 node:fs / node:path；
+// CLI 入口经 config-loader 复用既有配置读取）、纯文本正则（无需 AST）。
+// 实测依据：emp-auth 的 56 张表**全部为字面串 `@TableName("…")`**
+// （`service/infra-emp-auth` 51 处 + `service/adapter-emp-auth` 5 处 = 56，
+// 见 `docs/plan/ddd-purity-and-arch-merge-design.md` §5.4-4b 与附录 B 第 3 轮 R3-F4）。
+//
+// 用途：
+//   ① 独立命令 `tf arch scan-code`（opt-in，只读、退出码恒 0）
+//   ② 未来 `tf arch rebuild` 的**第 4 级取源**（§5.6 M1）
+//
+// ★ 诚实边界（四条，不得省略 —— 见 §5.4-4b）：
+//   1. 它不是「修复效果验证」，而是**新引入的一项扫描能力**（56 表只有靠它才可达）。
+//   2. 只能在**有代码**的仓库跑：纯设计阶段 / 无代码存量项目**拿不到** →
+//      `status='na'`（**不适用 ≠ 通过**，消费方须显式报 NA，不得当 PASS）；
+//      repos 部分缺失 / IO 失败 → `status='partial'`（**部分覆盖 ≠ ok**，count 为下界，
+//      P3 IMP-1——漏扫方向会使未来 A4-b 超集断言 vacuous pass）。
+//   3. 只覆盖 `tables[]` 一类：聚合 / BC / 子域 / 上下文映射 / 事件**仍无独立锚**
+//      → 这几类本轮只能靠人审。
+//   4. 覆盖率受代码形态影响：XML mapper、JPA、手写 SQL、动态表名**扫不到**
+//      → 报告须**列出 `uncovered` 清单，不静默**（同 A5 纪律）。
+//
+// ★ 扫描域与排除清单（v1.4 新增，处置 R3-8 —— 必须显式定义，否则会重复计数或漏扫）：
+//   - 扫描根 = 工作区根；多仓场景经 `arch.scan.repos[]` 显式配置
+//     （emp-auth 恰把两仓放在同一工作树 `service/infra-emp-auth` + `service/adapter-emp-auth`，
+//      故单根可跑；通用场景两仓分属不同 git 仓库时须配置）。
+//   - 排除清单（必配）：`.worktrees/`、`.git/`、`node_modules/`、`target/`、`build/`、`dist/`。
+//     **★ 实测风险已确认**：emp-auth 根下存在 4 个 `.worktrees/` 副本
+//     （v1-C2 / v2-C1 / v2-C2 / v3-C1），若不排除会**把同一批 `@TableName` 重复计入**
+//     （56 → 数百）。
+//   - fixture 须覆盖「副本目录去重」（见 tests/lib/arch-scan-code.test.mjs）。
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 默认排除目录（按 basename 精确匹配，任意层级生效）。 */
+export const DEFAULT_EXCLUDE_DIRS = Object.freeze([
+  '.worktrees', '.git', 'node_modules', 'target', 'build', 'dist',
+]);
+
+/** 默认注解名（MyBatis-Plus）。 */
+export const DEFAULT_ANNOTATION = 'TableName';
+
+/** 默认扫描的文件扩展名。 */
+export const DEFAULT_EXTENSIONS = Object.freeze(['.java']);
+
+/** 未覆盖形态探针（诚实边界 ④）——发现即登记，不静默。 */
+const UNCOVERED_PROBES = Object.freeze([
+  { id: 'jpa', label: 'JPA / Hibernate 注解', exts: ['.java', '.kt'],
+    re: /@(?:Entity|Table)\b|(?:javax|jakarta)\.persistence/ },
+  { id: 'mybatis-xml', label: 'MyBatis XML mapper', exts: ['.xml'],
+    re: /<(?:mapper|resultMap|select|insert|update|delete)\b/ },
+  { id: 'sql-ddl', label: '手写 SQL DDL', exts: ['.sql'],
+    re: /CREATE\s+TABLE/i },
+]);
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * 构造注解扫描正则。`pattern`（自定义正则源）优先于 `annotation`（注解名）。
+ *
+ * 匹配 `@TableName("x")` / `@TableName(value="x")` / `@TableName(value = "x")` /
+ * `@TableName(autoResultMap = true, value = "x")` —— 即括号内**任意位置**的首个字符串字面量，
+ * 但**仅当**未显式给出 `value=` 时接受裸串；给出 `value=` 时只认该字段。
+ *
+ * @param {string} annotation 注解名（可带或不带 `@` 前缀）
+ * @param {string|null} pattern 自定义正则源（覆盖 annotation）
+ * @returns {{ re: RegExp, source: string, mode: 'pattern'|'annotation' }}
+ */
+export function buildAnnotationMatcher(annotation, pattern) {
+  if (pattern) {
+    let re;
+    try {
+      re = new RegExp(pattern, 'g');
+    } catch (err) {
+      throw new Error(`Invalid arch.scan.pattern (${pattern}): ${err.message}`);
+    }
+    return { re, source: pattern, mode: 'pattern' };
+  }
+  const name = String(annotation || DEFAULT_ANNOTATION).replace(/^@/, '');
+  // 捕获括号内全部参数，再在参数内找字符串字面量。
+  const source = `@${escapeRe(name)}\\s*\\(([^)]*)\\)`;
+  return {
+    re: new RegExp(source, 'g'),
+    source,
+    mode: 'annotation',
+    // 参数体内取值：优先 `value = "x"`，否则首个裸串。
+    // 以回调形式暴露，避免调用方重复实现。
+    valueFromArgs: extractAnnotationValue,
+  };
+}
+
+/**
+ * 从注解参数体（`@X(...)` 的括号内容）中提取表名字面量。
+ * @param {string} argsBody
+ * @returns {string|null}
+ */
+export function extractAnnotationValue(argsBody) {
+  const explicit = /\bvalue\s*=\s*"([^"]+)"/.exec(argsBody);
+  if (explicit) return explicit[1];
+  const bare = /(?:^|,)\s*"([^"]+)"/.exec(argsBody);
+  return bare ? bare[1] : null;
+}
+
+/** 行是否为可忽略的注释行（行首 `//`、`*`、`/*`）。 */
+function isCommentLine(text, matchIndex) {
+  const lineStart = text.lastIndexOf('\n', matchIndex - 1) + 1;
+  const head = text.slice(lineStart, matchIndex).trimStart();
+  return head.startsWith('//') || head.startsWith('*') || head.startsWith('/*');
+}
+
+/**
+ * 从一段源码文本中提取注解表名，**并统计无法静态解出表名的注解数**。
+ *
+ * 为什么必须回报 `unresolved`（P2 审查修正，诚实边界 ④「不静默」）：
+ * `@TableName(MyTables.SYS_USER)`（常量）、`@TableName()`（空参，取类名策略）、
+ * SpEL 动态表名等形态**静态解不出字面量**。旧实现把它们**静默丢弃** → 计数偏低
+ * 却仍报 `status='ok'`，等于对覆盖率缺陷撒谎。emp-auth 全为字面串故不受影响，
+ * 但通用场景必须让这些形态进入 `uncovered` 清单，由人审兜底。
+ *
+ * @param {string} text
+ * @param {object} matcher buildAnnotationMatcher() 的返回值
+ * @returns {{ names: string[], unresolved: number }}
+ */
+export function extractAnnotationDetails(text, matcher) {
+  const names = [];
+  let unresolved = 0;
+  const { re, mode, valueFromArgs } = matcher;
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (isCommentLine(text, m.index)) continue;
+    let name = null;
+    if (mode === 'pattern') {
+      // 自定义正则：约定 group(1) 为表名；缺失则回退整段匹配。
+      name = m[1] ?? m[0];
+    } else {
+      name = valueFromArgs(m[1]);
+    }
+    if (name && typeof name === 'string') {
+      const trimmed = name.trim();
+      if (trimmed && !/\s/.test(trimmed)) names.push(trimmed);
+      else unresolved += 1;
+    } else {
+      unresolved += 1;
+    }
+  }
+  return { names, unresolved };
+}
+
+/**
+ * 从一段源码文本中提取注解表名（`extractAnnotationDetails` 的简写形式）。
+ * @param {string} text
+ * @param {object} matcher buildAnnotationMatcher() 的返回值
+ * @returns {string[]}
+ */
+export function extractTableNames(text, matcher) {
+  return extractAnnotationDetails(text, matcher).names;
+}
+
+/**
+ * 归一化配置：把 `arch.scan` 配置块折算为可直接使用的扫描参数。
+ * @param {object} scanConfig
+ * @returns {{ annotation: string, pattern: string|null, extensions: Set<string>,
+ *             exclude: Set<string>, repos: string[] }}
+ */
+export function normalizeScanOptions(scanConfig = {}) {
+  const cfg = scanConfig && typeof scanConfig === 'object' ? scanConfig : {};
+  // ★ 强制排除清单**恒生效**：配置项只能**追加**，不得覆盖（fail-closed）。
+  //
+  // 为什么不能让配置覆盖（P2 审查修正；★ P3 MIN-2 勘误归因方向）：若 `arch.scan.exclude`
+  // 被设为 `["vendor"]` 这类值，旧实现会**整体替换**默认清单 → `.worktrees/` 与分支副本
+  // 被重新扫入 → 锚的**正确性与可比性被污染**（副本/分支独有表名混入，emp-auth 多分支
+  // 场景下 count 可从 56 膨胀到数百）。C4 是 A4-b 断言（`registry.tables[]` ⊇ 代码扫描）
+  // 的**唯一锚**：膨胀方向使超集断言**更难成立**（误报方向）；真正使超集恒成立的
+  // fail-open 通道是**漏扫**（scan 偏小 → 超集 vacuous pass，由本文件的 partial 降级
+  // 登记堵截，见 P3 IMP-1）。故并集防线的正当理由 = 防污染锚 + 不静默，
+  // 与 §5.4-4b「排除清单（必配）」及 §8 红牌 9「A 级锚不得被架空」一致。
+  const exclude = [...new Set([
+    ...DEFAULT_EXCLUDE_DIRS,
+    ...(Array.isArray(cfg.exclude) ? cfg.exclude : []),
+  ])];
+  const extRaw = Array.isArray(cfg.extensions) && cfg.extensions.length > 0
+    ? cfg.extensions
+    : DEFAULT_EXTENSIONS;
+  return {
+    annotation: typeof cfg.annotation === 'string' && cfg.annotation.trim()
+      ? cfg.annotation.trim()
+      : DEFAULT_ANNOTATION,
+    pattern: typeof cfg.pattern === 'string' && cfg.pattern.trim() ? cfg.pattern.trim() : null,
+    extensions: new Set(extRaw.map(e => (e.startsWith('.') ? e : `.${e}`).toLowerCase())),
+    exclude: new Set(exclude.map(s => String(s).replace(/^\.\//, '').replace(/\/$/, ''))),
+    repos: Array.isArray(cfg.repos) ? cfg.repos.filter(r => typeof r === 'string' && r.trim()) : [],
+  };
+}
+
+/**
+ * 合并「配置文件 `arch.scan` + CLI 旗标」得到最终扫描配置。
+ *
+ * CLI 覆盖项：`--annotation`（注解名）、`--repos`（逗号分隔扫描根）、
+ * `--exclude`（逗号分隔，**只追加**，不得移除强制项）。
+ *
+ * 为什么必须有 CLI 入口（P2 实测驱动）：emp-auth 属**只读目标**（不可改其 config），
+ * 而其「扫全仓根」在本环境**未被实测通过**（见 §5.4-4b 修正），唯一可用姿势是
+ * 限定扫描根 → 若无 CLI 旗标就只能去改目标仓库的配置，与纪律冲突。
+ *
+ * 抽为独立函数以便单测（`run()` 会 `process.exit`，不便直接断言）。
+ * @param {object} scanConfig `arch.scan` 配置块
+ * @param {object} values parseArgs 结果
+ */
+export function resolveScanConfig(scanConfig = {}, values = {}) {
+  const cfg = scanConfig && typeof scanConfig === 'object' ? { ...scanConfig } : {};
+  if (values.annotation) cfg.annotation = values.annotation;
+  if (values.repos) {
+    cfg.repos = String(values.repos).split(',').map(s => s.trim()).filter(Boolean);
+  }
+  if (values.exclude) {
+    const extra = String(values.exclude).split(',').map(s => s.trim()).filter(Boolean);
+    cfg.exclude = [...(Array.isArray(cfg.exclude) ? cfg.exclude : []), ...extra];
+  }
+  return cfg;
+}
+
+/** 探针扩展名并集（用于收集"非主扩展名但需探测未覆盖形态"的文件）。 */
+const PROBE_EXTS = new Set(UNCOVERED_PROBES.flatMap(p => p.exts));
+
+/**
+ * 递归遍历目录，收集目标扩展名文件；按 basename 排除目录并登记命中项。
+ *
+ * 分两类收集：`files` = 主扫描扩展名内（跑注解扫描）；`probeFiles` = 仅探针扩展名内
+ * （如 `.xml` / `.sql`，只用于"未覆盖形态"报告，不参与表名计数）。
+ *
+ * @returns {{ files: object[], probeFiles: object[], excludedDirs: string[], dirs: number }}
+ */
+function walk(root, opts, relBase = '') {
+  const files = [];
+  const probeFiles = [];
+  const excludedDirs = [];
+  const readErrors = []; // ★ P3 IMP-1：目录读取失败不得静默——登记后 scanCode 降级 partial
+  let dirs = 0;
+
+  const stack = [{ abs: root, rel: relBase }];
+  while (stack.length > 0) {
+    const { abs, rel } = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch (e) {
+      readErrors.push(`${rel || '.'}: ${e.code || e.message}`);
+      continue;
+    }
+    dirs += 1;
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (opts.exclude.has(entry.name)) {
+          excludedDirs.push(childRel);
+          continue;
+        }
+        stack.push({ abs: path.join(abs, entry.name), rel: childRel });
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        const item = { abs: path.join(abs, entry.name), rel: childRel };
+        if (opts.extensions.has(ext)) files.push(item);
+        else if (PROBE_EXTS.has(ext)) probeFiles.push(item);
+      }
+    }
+  }
+  return { files, probeFiles, excludedDirs, readErrors, dirs };
+}
+
+/** 在给定文本上跑未覆盖形态探针，登记命中（去重累计）。 */
+function probeUncovered(text, rel, ext, uncoveredHits) {
+  for (const probe of UNCOVERED_PROBES) {
+    if (!probe.exts.includes(ext)) continue;
+    if (!probe.re.test(text)) continue;
+    if (!uncoveredHits.has(probe.id)) {
+      uncoveredHits.set(probe.id, { id: probe.id, label: probe.label, files: [] });
+    }
+    uncoveredHits.get(probe.id).files.push(rel);
+  }
+}
+
+/**
+ * 汇总 `uncovered` 清单：形态探针命中 + 「注解存在但表名非字面量」。
+ * **按 `id` 固定排序** —— 不依赖目录遍历顺序，满足红牌 10 的可重放要求
+ * （遍历用栈，`readdirSync` 顺序不保证跨平台一致）。
+ */
+function buildUncovered(uncoveredHits, unresolvedFiles, annotation, inputErrors = []) {
+  const list = [...uncoveredHits.values()].map(u => ({ ...u, files: u.files.sort() }));
+  if (unresolvedFiles.length > 0) {
+    list.push({
+      id: 'annotation-non-literal',
+      label: `@${annotation} 存在但表名非字面量（常量 / SpEL / 空参）`,
+      files: [...new Set(unresolvedFiles)].sort(),
+    });
+  }
+  // ★ P3 IMP-1：输入缺失/读取失败登记（结构化可见，驱动 status=partial）
+  if (inputErrors.length > 0) {
+    list.push({
+      id: 'scan-input-missing',
+      label: '扫描输入缺失或读取失败（漏扫方向：count 为下界，非完整覆盖）',
+      files: [...new Set(inputErrors)].sort(),
+    });
+  }
+  return list.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * ★ 核心：扫描代码仓库的持久化注解，产出表名集合（C4 的锚）。
+ *
+ * @param {string} root 工作区根（绝对路径）
+ * @param {object} [scanConfig] `arch.scan` 配置块
+ * @returns {{
+ *   status: 'ok'|'na'|'partial', reason: string|null, root: string, scanRoots: string[],
+ *   annotation: string, pattern: string|null, tables: string[], count: number,
+ *   sources: {file: string, table: string}[], excludedDirs: string[],
+ *   scanned: {files: number, probeFiles: number, dirs: number},
+ *   uncovered: {id: string, label: string, files: string[]}[]
+ * }}
+ */
+export function scanCode(root, scanConfig = {}) {
+  const absRoot = path.resolve(root);
+  const opts = normalizeScanOptions(scanConfig);
+  const matcher = buildAnnotationMatcher(opts.annotation, opts.pattern);
+
+  // 扫描根：显式 repos 优先，否则工作区根。
+  // ★ P3 IMP-1（fail-closed 输入维度）：缺失的 repos 条目**不得静默丢弃**——
+  // 部分缺失 = 只扫子集 = 漏扫方向，会让未来 A4-b 超集断言 vacuous pass，
+  // 故登记 missingRoots 并驱动 status 降级 partial（全部缺失仍走既有 na）。
+  const requestedRoots = opts.repos.length > 0 ? opts.repos : ['.'];
+  const scanRoots = [];
+  const missingRoots = [];
+  for (const r of requestedRoots) {
+    const abs = path.resolve(absRoot, r);
+    if (fs.existsSync(abs)) scanRoots.push(abs);
+    else missingRoots.push(r);
+  }
+
+  const files = [];
+  const probeFiles = [];
+  const excludedDirs = [];
+  const readErrors = []; // 文件级读取失败（同 P3 IMP-1，不静默）
+  let dirs = 0;
+  for (const sr of scanRoots) {
+    const rel = path.relative(absRoot, sr);
+    const w = walk(sr, opts, rel === '' ? '' : rel.split(path.sep).join('/'));
+    files.push(...w.files);
+    probeFiles.push(...w.probeFiles);
+    excludedDirs.push(...w.excludedDirs);
+    readErrors.push(...w.readErrors);
+    dirs += w.dirs;
+  }
+
+  const tables = new Set();
+  const sources = [];
+  const uncoveredHits = new Map();
+  // ★ 注解存在但表名非字面量（常量 / SpEL / 空参）——须进 uncovered，不静默（诚实边界 ④）。
+  const unresolvedFiles = [];
+
+  for (const { abs, rel } of files) {
+    let text;
+    try {
+      text = fs.readFileSync(abs, 'utf-8');
+    } catch (e) {
+      readErrors.push(`${rel}: ${e.code || e.message}`); // P3 IMP-1：不静默
+      continue;
+    }
+    const { names: hits, unresolved } = extractAnnotationDetails(text, matcher);
+    for (const name of hits) {
+      tables.add(name);
+      sources.push({ file: rel, table: name });
+    }
+    if (unresolved > 0) unresolvedFiles.push(rel);
+    // 未覆盖形态探针：仅在**未命中任何注解**的文件上探测，避免噪声。
+    if (hits.length === 0) {
+      probeUncovered(text, rel, path.extname(abs).toLowerCase(), uncoveredHits);
+    }
+  }
+  // 仅探针扩展名的文件（.xml / .sql 等）：不参与表名计数，只用于"未覆盖形态"报告。
+  for (const { abs, rel } of probeFiles) {
+    let text;
+    try {
+      text = fs.readFileSync(abs, 'utf-8');
+    } catch (e) {
+      readErrors.push(`${rel}: ${e.code || e.message}`); // P3 IMP-1：不静默
+      continue;
+    }
+    probeUncovered(text, rel, path.extname(abs).toLowerCase(), uncoveredHits);
+  }
+
+  sources.sort((a, b) => (a.file === b.file ? a.table.localeCompare(b.table) : a.file.localeCompare(b.file)));
+  const sortedTables = [...tables].sort((a, b) => a.localeCompare(b));
+  excludedDirs.sort();
+
+  let status = 'ok';
+  let reason = null;
+  if (scanRoots.length === 0) {
+    status = 'na';
+    reason = 'no scan root available (workspace root or arch.scan.repos[] paths do not exist)';
+  } else if (files.length === 0) {
+    status = 'na';
+    reason = `no scannable file (extensions: ${[...opts.extensions].join(', ')}) under the scan root`;
+  } else if (sortedTables.length === 0) {
+    status = 'na';
+    reason = `no @${opts.annotation} annotation found in ${files.length} scanned file(s)`
+      + ' — 若项目使用其他持久化框架，请配置 arch.scan.annotation / arch.scan.pattern';
+  }
+
+  // ★ P3 IMP-1：输入维度 fail-closed——repos 部分缺失 / IO 失败 = 漏扫方向，
+  // `status=ok` 不得照报（部分覆盖 ≠ ok）。na 已是显式不适用，优先级更高，不重复降级。
+  const inputErrors = [
+    ...missingRoots.map(r => `missing root: ${r}`),
+    ...readErrors,
+  ];
+  if (inputErrors.length > 0 && status === 'ok') {
+    status = 'partial';
+    reason = `partial scan: ${inputErrors.length} input error(s) — `
+      + inputErrors.slice(0, 5).join('; ')
+      + (inputErrors.length > 5 ? `; …(+${inputErrors.length - 5} more)` : '')
+      + '（漏扫方向：count 为下界，消费方不得当完整覆盖）';
+  }
+
+  return {
+    status,
+    reason,
+    root: absRoot,
+    scanRoots,
+    annotation: `@${opts.annotation}`,
+    pattern: opts.pattern,
+    tables: sortedTables,
+    count: sortedTables.length,
+    sources,
+    excludedDirs: [...new Set(excludedDirs)].sort(),
+    scanned: { files: files.length, probeFiles: probeFiles.length, dirs },
+    uncovered: buildUncovered(uncoveredHits, unresolvedFiles, opts.annotation, inputErrors),
+  };
+}
+
+/**
+ * 渲染人类可读输出。
+ * @param {object} result scanCode() 返回值
+ * @returns {string}
+ */
+export function renderReport(result) {
+  const lines = [];
+  lines.push(`arch scan-code — ${result.status.toUpperCase()}`
+    + (result.status === 'ok' ? `（${result.count} 张表）` : ''));
+  lines.push(`  scan root : ${result.root}`);
+  if (result.scanRoots.length > 1 || result.scanRoots[0] !== result.root) {
+    lines.push(`  scan roots: ${result.scanRoots.join(', ')}`);
+  }
+  lines.push(`  matcher   : ${result.annotation}${result.pattern ? ` (pattern: ${result.pattern})` : ''}`);
+  lines.push(`  scanned   : ${result.scanned.files} file(s) / ${result.scanned.dirs} dir(s)`
+    + `（另有 ${result.scanned.probeFiles} 个探针文件，仅计入未覆盖统计）`);
+  if (result.status === 'ok' || result.status === 'partial') {
+    lines.push(`  tables    : ${result.tables.join(', ')}`);
+  }
+  if (result.reason) {
+    lines.push(`  reason    : ${result.reason}`);
+  }
+  if (result.excludedDirs.length > 0) {
+    lines.push(`  excluded  : ${result.excludedDirs.join(', ')}  ← 副本去重生效`);
+  }
+  if (result.uncovered.length > 0) {
+    lines.push('  uncovered : 以下形态可能存在表定义，但未被本次注解扫描捕获（须人审）：');
+    for (const u of result.uncovered) {
+      lines.push(`    - ${u.label} (${u.files.length} file(s)): ${u.files.slice(0, 5).join(', ')}`
+        + (u.files.length > 5 ? ' …' : ''));
+    }
+  }
+  lines.push('  note: C4 是唯一 A 级锚（代码本体）；只覆盖 tables[] 一类；');
+  lines.push('        聚合 / BC / 子域 / 上下文映射 / 事件仍无独立锚，本轮只能靠人审。');
+  if (result.status === 'na') {
+    lines.push('        ★ status=na 表示「不适用」，不是「通过」——消费方须报 NA，不得当 PASS。');
+  }
+  if (result.status === 'partial') {
+    lines.push('        ★ status=partial 表示「部分覆盖」（输入缺失/读取失败，漏扫方向）——count 为下界，不得当完整覆盖。');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI 入口。`values` 由 `cmd-arch.run` 的 parseArgs 统一解析后传入。
+ * @param {{ root?: string, 'project-root'?: string, json?: boolean,
+ *           annotation?: string, repos?: string, exclude?: string }} values
+ */
+export async function run(values = {}) {
+  const root = path.resolve(values.root || values['project-root'] || process.cwd());
+
+  let scanConfig = {};
+  try {
+    const { loadConfig } = await import('./config-loader.mjs');
+    const config = loadConfig(root);
+    scanConfig = config?.arch?.scan ?? {};
+  } catch {
+    scanConfig = {};
+  }
+
+  const result = scanCode(root, resolveScanConfig(scanConfig, values));
+
+  if (values.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(renderReport(result));
+  }
+  // 证据工具：恒以 0 退出，不阻断流程（同 arch precheck 语义）。
+  process.exit(0);
+}

package/scripts/lib/cmd-arch.mjs

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import * as archPrecheck from './arch-precheck.mjs';
+import * as archScanCode from './arch-scan-code.mjs';
 import { scaffoldGlobalLedger } from './arch-merge.mjs';
 
 const ARCH_STATE_FILE = '.team-flow/arch-state.json';
@@ -16,6 +17,11 @@ export async function run(args) {
     args,
     options: {
       'project-root': { type: 'string' },
+      root: { type: 'string' },
+      // v1.4 §5.4-4b：scan-code 的 CLI 覆盖项（只读目标仓库无法改 config 时必需）
+      repos: { type: 'string' },
+      annotation: { type: 'string' },
+      exclude: { type: 'string' },
       mode: { type: 'string', default: 'reconstruction' },
       'baseline-ref': { type: 'string', default: 'prd/vN/' },
       json: { type: 'boolean', default: false },
@@ -30,7 +36,9 @@ export async function run(args) {
   if (sub === 'scaffold') return scaffold(values);
   // v0.22 §88.3.2：架构门判据的确定性证据工具（证据 only，退出码恒 0）
   if (sub === 'precheck') return archPrecheck.run(positionals.slice(1), values);
-  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch scaffold | tf arch precheck <change-dir> [--json]');
+  // v1.4 §5.4-4b：C4 代码注解扫描（唯一 A 级锚；只读、零依赖、证据 only，退出码恒 0）
+  if (sub === 'scan-code') return archScanCode.run(values);
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch scaffold | tf arch precheck <change-dir> [--json] | tf arch scan-code [--root <path>|--project-root <path>] [--repos <a,b>] [--annotation <name>] [--exclude <a,b>] [--json]');
   process.exit(2);
 }
 

package/scripts/lib/cmd-doctor.mjs

@@ -331,7 +331,7 @@ function checkArchState(root) {
   }
   if (existsSync(iterationsDir)) {
     for (const d of readdirSync(iterationsDir, { withFileTypes: true }).filter(x => x.isDirectory())) {
-      const hasSkip = existsSync(join(iterationsDir, d.name, 'SKIPPED'));
+      const hasSkip = existsSync(join(iterationsDir, d.name, 'SKIPPED.md')) || existsSync(join(iterationsDir, d.name, 'SKIPPED')); // P3 C-3 双形态
       const hasSnap = existsSync(join(iterationsDir, d.name, 'architecture.md'));
       if (hasSkip && hasSnap) warnings.push(`${d}: SKIPPED 与快照并存，语义矛盾`);
     }
@@ -382,9 +382,9 @@ function checkSolutions(root) {
     for (const line of readFileSync(indexPath, 'utf-8').split('\n')) {
       if (!line.startsWith('|') || line.startsWith('| date') || line.startsWith('|--')) continue;
       const cells = parseTableRow(line);
-      // v0.57.0 P4：`source` 列新增后列数为 7（存量 INDEX）或 8（本版重建）；
+      // v0.57.0 P4：`source` 列新增后列数为 7（存量）/ 8；P2-2 `flags` 列后 9（本版重建）；
       // 另校验 `file` 列形状——列数在界内仍可能因未转义的 `|` 而错位。
-      if (cells.length < 7 || cells.length > 8) continue;
+      if (cells.length < 7 || cells.length > 9) continue;
       if (!/^[a-z][a-z-]*\/.+\.md$/.test(cells[6])) continue;
       indexRows.set(cells[6], { date: cells[0], phase: cells[1], domain: cells[2], type: cells[3], severity: cells[4] });
     }