d-robotics 6d6a805d46
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run
feat(v3): P1+P2 全落地 — T06–T17 + 系统集成测试
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>
2026-08-14 15:35:49 +08:00

252 lines
9.3 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* @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 };
}