12 模块多 agent 并行开发(dev+test+fix 每,两层 + barrier):
- T06 PbaSession 事件溯源 + deriveMessages + logged 不变量
- T07 PbaEventBus typed event bus + waterfall + ScopeKey 隔离
- T08 能力接缝三角色(board-link + flash Provider/Registry/consumer)
- T09 compaction 完整工程(token-meter/pruner/summarizer/spill)
- T10 CI 质量门 + snapshot + doc-sync
- T11 类型镜像漂移检测(tsconfig.realpi + type-drift-check)
- T12 子代理 + 工作流编排(parallel/pipeline/InlineSubagentProvider)
- T13 上下文注入三段(inject/steer/followup)
- T14 plan/goal/todo checkpoint logged state(look-ahead 状态机)
- T15 profile/bundle 分层(维修诊断 vs 嵌入式开发,共享 base)
- T16 多 LLM provider 适配(ProviderRegistry + glm-5.2/deepseek)
- T17 审批接缝(fail-closed auto-deny)+ credentials/settings/lsp
集成(串行):
- src/index.ts 公共 re-export(board-link/flash 具名避 shared/types 重名)
- tests/system-integration.test.ts 跨模块 10 闭环(事件溯源→compaction→bus→
接缝→checkpoint→inject→workflow→approval→provider→profile)
- 全量 tsc=0;vitest 39 文件 2449 passed/5 skipped(1044 baseline +~1400 模块 + 10 系统)
- 密钥铁律:\${DROBOTICS_LLM_KEY} 占位,grep sk- 明文 0
68 workflow agent / 0 error / ~3M token;mutation 测试每模块 3-9 seeded bug 全杀。
Co-Authored-By: Claude <noreply@anthropic.com>
252 lines
9.3 KiB
TypeScript
252 lines
9.3 KiB
TypeScript
/**
|
||
* @module doc-sync
|
||
*
|
||
* 文档锚点同步校验(T10)—— 校验架构文档的 file:line 锚点与代码对齐。
|
||
*
|
||
* 为什么需要:架构设计文档_v3.md 通篇用 `src/foo.ts:NN` 锚点引用真实代码
|
||
* (如「`src/core/tool-pipeline.ts`:实现 `ToolPipeline` 调度器」)。代码重构后
|
||
* 文档锚点易漂移——文件路径搬走、符号改名、整段删除——而文档仍指旧位置,
|
||
* 误导后续维护者。本模块把「文档声称的锚点 ⟺ 代码真实存在」做成可注入的纯校验,
|
||
* CI 跑之,锚点与代码不符即红。
|
||
*
|
||
* 双侧校验(一个 DocAnchor 同时钉住文档侧与代码侧):
|
||
* - 文档侧:docFile 的第 docLine 行必须确实引用 codeFile(锚点位置没飘)。
|
||
* - 代码侧:codeSymbol 必须在 codeFile 中存在(grepSymbol 返回 >0 行号)。
|
||
* 任一侧不符即记一条 mismatch,附可读 reason。两侧皆过才 ok。
|
||
*
|
||
* fail-closed(安全不变式):
|
||
* - docFile 不可读 / docLine 越界 → mismatch(无法确认锚点对齐,安全默认红)。
|
||
* - codeFile 不可读 → mismatch(同上)。
|
||
* - grepSymbol 返回 ≤0(约定 -1 表未命中;0 表非法行号)→ mismatch。
|
||
*
|
||
* 正交阶段(单一职责,确定性可测):
|
||
* checkDocSync(纯校验,readFile/grepSymbol 注入)为唯一主入口;
|
||
* defaultReadFile / defaultGrepSymbol 是真 IO 适配器(CI 装配,单测注入 mock);
|
||
* DEFAULT_DOC_ANCHORS 是已人工核对落地的锚点清单(CI 默认跑)。
|
||
*
|
||
* 纯逻辑 + readFile/grepSymbol 可注入,零 pi 运行时依赖,可离线单测。
|
||
* 见架构设计文档_v3.md §5.9(CI 质量门:doc-sync 文档门)。
|
||
*/
|
||
|
||
import { readFileSync } from "node:fs";
|
||
|
||
// ============================================================================
|
||
// 命名常量 —— 消灭魔法值
|
||
// ============================================================================
|
||
|
||
/**
|
||
* grepSymbol「未命中」哨兵。行号 1-indexed,故 ≤0 一律视为未命中(兼容 -1 与 0
|
||
* 两种约定,fail-closed:歧义即红)。
|
||
*/
|
||
const GREP_NOT_FOUND_MAX = 0;
|
||
|
||
/** 默认架构文档文件(doc-sync 校验对象)。 */
|
||
const DEFAULT_DOC_FILE = "架构设计文档_v3.md";
|
||
|
||
// ============================================================================
|
||
// 类型契约
|
||
// ============================================================================
|
||
|
||
/**
|
||
* 一条文档锚点:声明「docFile 的第 docLine 行引用了 codeFile 中的 codeSymbol」。
|
||
*
|
||
* docFile / codeFile 均为仓库相对路径。docLine 1-indexed。
|
||
*/
|
||
export interface DocAnchor {
|
||
/** 文档文件(仓库相对路径,如 "架构设计文档_v3.md")。 */
|
||
readonly docFile: string;
|
||
/** 文档内锚点行号(1-indexed)。 */
|
||
readonly docLine: number;
|
||
/** 锚点引用的代码文件(仓库相对路径,如 "src/core/tool-pipeline.ts")。 */
|
||
readonly codeFile: string;
|
||
/** 锚点声称在 codeFile 中存在的符号(子串匹配,如 "ToolPipeline")。 */
|
||
readonly codeSymbol: string;
|
||
}
|
||
|
||
/** 单条锚点校验不符。 */
|
||
export interface DocSyncMismatch {
|
||
/** 触发不符的锚点。 */
|
||
readonly anchor: DocAnchor;
|
||
/** 人类可读的不符原因。 */
|
||
readonly reason: string;
|
||
}
|
||
|
||
/** checkDocSync 返回值。 */
|
||
export interface DocSyncResult {
|
||
/** 全部锚点两侧皆过即 true。 */
|
||
readonly ok: boolean;
|
||
/** 不符清单(保持锚点输入序,稳定可测)。 */
|
||
readonly mismatches: readonly DocSyncMismatch[];
|
||
}
|
||
|
||
/** readFile 抽象(注入以便单测 mock,避免真 fs)。 */
|
||
export type ReadFile = (path: string) => string;
|
||
|
||
/** grepSymbol 抽象(注入以便单测 mock)。返回 1-indexed 行号,未命中返回 -1。 */
|
||
export type GrepSymbol = (file: string, symbol: string) => number;
|
||
|
||
// ============================================================================
|
||
// 真 IO 适配器 —— CI 装配用(单测注入 mock 替代)
|
||
// ============================================================================
|
||
|
||
/**
|
||
* 默认 readFile:同步读 UTF-8 文本。
|
||
*
|
||
* 抛错(文件不存在等)由调用方 {@link checkDocSync} 的 try/catch 兜成 mismatch。
|
||
*
|
||
* @param path 仓库相对路径。
|
||
* @returns 文件 UTF-8 文本。
|
||
*/
|
||
export const defaultReadFile: ReadFile = (path) => readFileSync(path, "utf8");
|
||
|
||
/**
|
||
* 默认 grepSymbol:在 file 中按行子串查找 symbol,返回首个命中行号(1-indexed)。
|
||
*
|
||
* 子串匹配即可(注释/实现皆算)——doc-sync 只关心「符号概念仍在该文件」,
|
||
* 不要求精确到定义行。未命中返回 -1。
|
||
*
|
||
* @param file 代码文件路径。
|
||
* @param symbol 要查的符号子串。
|
||
* @returns 首个命中行号(1-indexed),未命中 -1。
|
||
*/
|
||
export const defaultGrepSymbol: GrepSymbol = (file, symbol) => {
|
||
const text = readFileSync(file, "utf8");
|
||
const lines = text.split("\n");
|
||
for (let i = 0; i < lines.length; i++) {
|
||
if (lines[i].includes(symbol)) return i + 1;
|
||
}
|
||
return -1;
|
||
};
|
||
|
||
// ============================================================================
|
||
// DEFAULT_DOC_ANCHORS —— 已人工核对落地的锚点(CI 默认跑)
|
||
// ============================================================================
|
||
|
||
/**
|
||
* 深冻结 DocAnchor 数组:外层数组 + 逐元素对象均 Object.freeze。
|
||
*
|
||
* Object.freeze(arr) 仅浅冻结——元素 DocAnchor 对象的 docFile/docLine 等属性
|
||
* 仍可写、可被运行时静默篡改(如 `DEFAULT_DOC_ANCHORS[0].docFile = 'x'` 不抛错)。
|
||
* 逐元素 Object.freeze 方达「深冻结」语义,兑现下方注释的安全不变式承诺。
|
||
*
|
||
* @param anchors 待冻结锚点(元素须为纯对象)。
|
||
* @returns 深冻结后的同一引用(外层 + 元素皆 Object.isFrozen===true)。
|
||
*/
|
||
function deepFreezeAnchors(anchors: readonly DocAnchor[]): readonly DocAnchor[] {
|
||
for (const anchor of anchors) {
|
||
Object.freeze(anchor);
|
||
}
|
||
return Object.freeze(anchors) as readonly DocAnchor[];
|
||
}
|
||
|
||
/**
|
||
* 默认锚点清单。每条均经人工核对:docLine 行确实引用 codeFile,codeSymbol 确在
|
||
* codeFile 中存在。新增锚点须先核对再追加,勿盲填。
|
||
*
|
||
* 深冻结(deepFreezeAnchors):外层数组 + 逐元素对象均 Object.freeze,
|
||
* 防运行时意外篡改 docFile/docLine 等字段(与 sandbox-policy 的
|
||
* DEFAULT_BOARD_SANDBOX_POLICY 同范式)。
|
||
*/
|
||
export const DEFAULT_DOC_ANCHORS: readonly DocAnchor[] = deepFreezeAnchors([
|
||
{
|
||
docFile: DEFAULT_DOC_FILE,
|
||
docLine: 274,
|
||
codeFile: "src/extensions/hardware-state.ts",
|
||
codeSymbol: "replayFromEntries",
|
||
},
|
||
{
|
||
docFile: DEFAULT_DOC_FILE,
|
||
docLine: 582,
|
||
codeFile: "src/core/tool-pipeline.ts",
|
||
codeSymbol: "ToolPipeline",
|
||
},
|
||
{
|
||
docFile: DEFAULT_DOC_FILE,
|
||
docLine: 749,
|
||
codeFile: "src/core/sandbox-policy.ts",
|
||
codeSymbol: "probeSandbox",
|
||
},
|
||
]);
|
||
|
||
// ============================================================================
|
||
// checkDocSync —— 主入口(纯逻辑,readFile/grepSymbol 注入)
|
||
// ============================================================================
|
||
|
||
/**
|
||
* 校验文档锚点 file:line 与代码对齐。
|
||
*
|
||
* 对每个 anchor 做双侧校验:
|
||
* 1. 文档侧——读 docFile,取第 docLine 行,确认其确实引用 codeFile
|
||
* (字符串包含 codeFile 路径)。docFile 不可读 / 行越界 → mismatch(fail-closed)。
|
||
* 2. 代码侧——grepSymbol(codeFile, codeSymbol) 返回 >0 行号表存在;
|
||
* ≤0 或抛错 → mismatch(fail-closed:无法确认存在即视为漂移)。
|
||
*
|
||
* mismatches 保持锚点输入序(稳定、可测);ok 当且仅当 mismatches 为空。
|
||
*
|
||
* 纯逻辑、readFile/grepSymbol 可注入、无 pi 运行时依赖、确定性可测。
|
||
*
|
||
* @param opts.readFile 文件读取器(默认 fs.readFileSync;单测注入 mock)。
|
||
* @param opts.anchors 待校验锚点清单。
|
||
* @param opts.grepSymbol 符号查找器(默认按行子串;单测注入 mock)。
|
||
* @returns 校验结果(ok + mismatches)。
|
||
*/
|
||
export function checkDocSync(opts: {
|
||
readFile: ReadFile;
|
||
anchors: readonly DocAnchor[];
|
||
grepSymbol: GrepSymbol;
|
||
}): DocSyncResult {
|
||
const { readFile, anchors, grepSymbol } = opts;
|
||
const mismatches: DocSyncMismatch[] = [];
|
||
|
||
for (const anchor of anchors) {
|
||
// ---- 文档侧 ----
|
||
let docText: string;
|
||
try {
|
||
docText = readFile(anchor.docFile);
|
||
} catch {
|
||
mismatches.push({
|
||
anchor,
|
||
reason: `doc file not readable: ${anchor.docFile}`,
|
||
});
|
||
continue;
|
||
}
|
||
|
||
const docLines = docText.split("\n");
|
||
const docLine = docLines[anchor.docLine - 1];
|
||
if (docLine === undefined) {
|
||
mismatches.push({
|
||
anchor,
|
||
reason: `doc line ${anchor.docLine} out of range (file has ${docLines.length} lines)`,
|
||
});
|
||
continue;
|
||
}
|
||
if (!docLine.includes(anchor.codeFile)) {
|
||
mismatches.push({
|
||
anchor,
|
||
reason: `doc line ${anchor.docLine} does not reference "${anchor.codeFile}"`,
|
||
});
|
||
continue;
|
||
}
|
||
|
||
// ---- 代码侧 ----
|
||
let codeLine: number;
|
||
try {
|
||
codeLine = grepSymbol(anchor.codeFile, anchor.codeSymbol);
|
||
} catch {
|
||
mismatches.push({
|
||
anchor,
|
||
reason: `code file not readable: ${anchor.codeFile}`,
|
||
});
|
||
continue;
|
||
}
|
||
if (codeLine <= GREP_NOT_FOUND_MAX) {
|
||
mismatches.push({
|
||
anchor,
|
||
reason: `symbol "${anchor.codeSymbol}" not found in ${anchor.codeFile}`,
|
||
});
|
||
}
|
||
}
|
||
|
||
return { ok: mismatches.length === 0, mismatches };
|
||
}
|