@customize-agent/server 4.58.0 → 4.59.1

package/scripts/half-built-scan.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * 半成品扫描器（2026-09-28）。
+ *
+ * ## 为什么要有它
+ * 用户口径：「每次问你都会遗漏很多东西，都会有很多都是半成品」。
+ * 结构性原因不是"不够仔细"，而是：**仓库里已有九份缺口账本，散在九个文件里，没有一处汇总**——
+ * 所以任何一次凭记忆回答都必然只覆盖一两份（见 `docs/half-built-inventory-2026-09-28.md` 第零节）。
+ *
+ * 本脚本负责的是**账本记不住的那一类**：**声明了、实现了，但生产代码里零调用点**。
+ *
+ * ## 判定口径（刻意保守）
+ * 对每个导出符号分别统计：
+ * - `inFile`：**本文件内**引用次数（扣掉声明行本身）——>0 说明它是模块内部实现的一部分（正常）；
+ * - `otherProd`：**其它生产文件**引用次数——**这是唯一判定"接线与否"的量**；
+ * - `tests`：测试目录引用次数——>0 且 otherProd=0 = **典型的"只在测试里活着"**。
+ *
+ * 三种分类：
+ * | 分类 | 判据 | 含义 |
+ * |---|---|---|
+ * | 半成品嫌疑 | otherProd=0 且 tests>0 | 写好了、测过了，生产里没人用 |
+ * | 谁都不用 | inFile=0 且 otherProd=0 且 tests=0 | 真死代码，或被取代的旧 API |
+ * | 封装暴露 | otherProd=0 但 inFile>0 | 只是导出给测试用，**不是**半成品 |
+ *
+ * ## 已知局限（写在这里，免得被当成结论用）
+ * - **动态引用识别不了**：`await import('...')`、字符串派发、计算属性访问都会漏判 ⇒ 会误报；
+ * - 因此本脚本的输出是**候选清单**，逐条必须 grep 复核后才能写进账本；
+ *   实测教训：本轮用它测"画布标签表"，头两版都测错（表其实是完整的），最后以读文件逐键核对为准。
+ *
+ * ## 用法
+ *   node apps/server/scripts/half-built-scan.mjs                       # 全仓
+ *   node apps/server/scripts/half-built-scan.mjs apps/server/src/services  # 指定目录
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '../../..');           // 仓库根
+const DEFAULT_DIRS = ['apps/server/src', 'packages'];
+const DIRS = process.argv.slice(2).length > 0 ? process.argv.slice(2) : DEFAULT_DIRS;
+
+const TEST_HINT = /(^|\/)(test|tests|__tests__|__mocks__)\//;
+const isSource = file => /\.(ts|tsx)$/.test(file) && !/\.d\.ts$/.test(file);
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.next', 'coverage']);
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walk(full, out);
+    } else if (isSource(full)) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * ★ **引用池永远是全仓，报告范围才是参数**（2026-09-28 实测修正）。
+ *
+ * 第一版把"其它生产文件"也限定在扫描目录内 ⇒ 扫 `services/agent` 时，调用点落在
+ * `document-workflow` 的 `closePhaseNode` / `closeDanglingConnections` 被误报成"谁都不用"。
+ * **工具撒谎比没有工具更糟**：这会让人去删正在用的代码。
+ */
+const ALL_DIRS = DEFAULT_DIRS;
+const allFiles = ALL_DIRS.flatMap(dir => walk(path.resolve(ROOT, dir)));
+const texts = new Map(allFiles.map(f => [f, fs.readFileSync(f, 'utf8')]));
+const prod = allFiles.filter(f => !TEST_HINT.test(f));
+const tests = allFiles.filter(f => TEST_HINT.test(f));
+const scopeRoots = DIRS.map(dir => path.resolve(ROOT, dir));
+const inScope = file => scopeRoots.some(root => file.startsWith(root + path.sep) || file === root);
+
+const EXPORT_PATTERNS = [
+  [/^export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm, 'fn'],
+  [/^export\s+class\s+([A-Za-z_$][\w$]*)/gm, 'class'],
+  [/^export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm, 'const'],
+];
+
+function countRefs(name, pool, selfFile, subtractDeclaration) {
+  const re = new RegExp(`\\b${name.replace(/\$/g, '\\$')}\\b`, 'g');
+  let total = 0;
+  for (const file of pool) {
+    let hits = (texts.get(file).match(re) || []).length;
+    if (subtractDeclaration && file === selfFile) {
+      const decl = new RegExp(`^export\\s+(async\\s+)?(function|class|const|let|var)\\s+${name.replace(/\$/g, '\\$')}\\b`, 'gm');
+      hits -= (texts.get(file).match(decl) || []).length;
+    }
+    total += Math.max(0, hits);
+  }
+  return total;
+}
+
+const rows = [];
+for (const file of prod) {
+  if (!inScope(file)) continue;                          // 报告范围 = 参数；引用池 = 全仓
+  const rel = path.relative(ROOT, file);
+  const text = texts.get(file);
+  for (const [pattern, kind] of EXPORT_PATTERNS) {
+    for (const match of text.matchAll(pattern)) {
+      const name = match[1];
+      if (name.length < 4) continue;
+      const inFile = countRefs(name, [file], file, true);
+      const otherProd = countRefs(name, prod.filter(f => f !== file), file, false);
+      const testRefs = countRefs(name, tests, file, false);
+      if (otherProd > 0) continue;
+      rows.push({
+        rel, name, kind, inFile, testRefs,
+        verdict: inFile === 0 && testRefs === 0 ? '谁都不用'
+          : inFile === 0 && testRefs > 0 ? '半成品嫌疑'
+            : '封装暴露（只导出给测试）',
+      });
+    }
+  }
+}
+
+const byVerdict = verdict => rows.filter(r => r.verdict === verdict);
+const suspect = byVerdict('半成品嫌疑');
+const unused = byVerdict('谁都不用');
+
+console.log('════════ 半成品扫描 ════════');
+console.log(`扫描范围：${DIRS.join(', ')}（引用池 = 全仓 ${prod.length} 个生产文件 / ${tests.length} 个测试文件）`);
+console.log(`导出符号在他处生产零引用：${rows.length}`);
+console.log(`  · 半成品嫌疑（仅测试引用）    ${suspect.length}`);
+console.log(`  · 谁都不用（含自身文件）      ${unused.length}`);
+console.log(`  · 封装暴露（本文件内自用）    ${byVerdict('封装暴露（只导出给测试）').length}`);
+
+const print = (title, list, limit = 40) => {
+  if (list.length === 0) return;
+  console.log(`\n── ${title}（${list.length} 条，列前 ${Math.min(limit, list.length)}）`);
+  for (const row of list.slice(0, limit)) {
+    console.log(`   ${row.rel}  ::  ${row.name}${row.testRefs ? `  (测试引用 ${row.testRefs})` : ''}`);
+  }
+};
+print('半成品嫌疑', suspect);
+print('谁都不用', unused, 30);
+
+console.log('\n════════ 另外九份账本（本脚本扫不到，必须一起看）════════');
+for (const line of [
+  'L1 A/B 接线缺口          test/services/agent/detailLayerWiring.test.ts 的 WIRING_GAPS',
+  'L2 N 类判据处置表        document-workflow/nClassJudges.ts 的 N_CLASS_JUDGE_DISPOSITIONS',
+  'L3 写作期处置欠账        detectorFixerRegistry.ts 的 PENDING_WRITING_TIME_DISPOSITION',
+  'L4 未锚定修复轮          agent/tools/repairRounds.ts 的 unanchoredRepairRounds()',
+  'L5 manual 检测器         detectorFixerRegistry 的 fixerDisposition==="manual"（54 条）',
+  'L6 工具面空壳（已删）    services/agent/toolRegistry.ts 的删除记录',
+  'L7 91 条对照表缺口       docs/closure-checklist-mapping-2026-09-28.md',
+  'L8 机制级缺口            docs/judgment-completeness-2026-09-28.md',
+  'L9 零生产者节点类型      docs/half-built-inventory-2026-09-28.md 第一节',
+]) console.log(`   ${line}`);
+console.log('\n完整口径与不确定性见 docs/half-built-inventory-2026-09-28.md。');