gapproof

gapproof

gapproof 是一个用于代码仓库的本地测试缺口分析工具。它会遍历源文件，提取找到的函数，检查其中哪些函数在测试中被提及，并报告缺口：没有测试似乎覆盖的函数。记录的测试运行会提供第二种、更有力的信号——通过的运行中提到的函数（直接提及，或通过关联它的测试提及）会被视为已验证，而不只是已关联——这两种信号会合并为一个覆盖率分数。

这个软件包是从零开始重建的干净室版本，也是一个标注过的核心子集：它涵盖了原 Orangepro MCP 服务（orangepro_*）所记录的 18 个工具中的 12 个。省略的工具列在下文的“范围”部分。

工作原理——如实说明

这里没有 AST，没有解析器，也没有任何网络调用。引擎由一组有文档说明的启发式规则构成：

• 遍历。 从给定根目录开始，跳过 node_modules、.git、dist 和以点开头的目录。以 .ts、.tsx、.js、.jsx 或 .py 结尾的文件，如果位于 test/、tests/ 或 __tests__/ 目录下，或命名为 *.test.*、*.spec.*、test_*.py 或 *_test.py，则归类为测试；其余文件均为源文件。
• 提取（正则表达式）。 TypeScript/JavaScript：function name(、export function name( 和 const name = (...) =>（也支持 let/var、function 关键字形式，以及可选的 async）。Python：def name(。名称不以下划线 _ 开头的 Python 函数视为已导出；使用 export 声明的 TS/JS 函数视为已导出。
• 关联。 如果某个函数名作为一个单词出现在某个测试文件的内容中，则该函数视为已关联。
• 验证。 orangepro_record_run 会将一次运行（test、outcome: "pass" | "fail"、可选的 functions）追加到持久化图谱中。如果某次通过的运行提到了某个函数，或提到了一个会关联到该函数的测试文件／测试用例，则该函数视为已验证。
• 分数。 60% × 已关联比例 + 40% × 已验证比例，以 0–100 的范围报告，保留一位小数。
• RTM。 从源文件注释中（仅 //、/* … */、#）读取符合 [A-Z]+-\d+ 的需求 ID，并与同一文件中定义的函数关联。

状态保存在一个文件中：<root>/.gapproof/graph.json，由 orangepro_start 和 orangepro_record_run 写入。其他所有操作只读取仓库（以及在需要考虑运行记录时读取该图谱），不会写入。

安装

npx @reneturcios/gapproof orangepro_start '{"root":"/path/to/repo"}'

也可以运行容器映像：

docker run -i ghcr.io/cloudcorprecords/gapproof

容器默认启动 MCP 服务。传入 CLI 参数即可将其用作 CLI。无需 API 密钥——原版中可选的模型密钥仅用于其 AI 测试生成工具，而此子集不包含这些工具。

CLI

CLI 与各工具对应：每个工具对应一个子命令，参数以单个 JSON 对象的形式传入。

gapproof orangepro_start '{"root":"/path/to/repo"}'
gapproof orangepro_analyze_sources '{"root":"/path/to/repo"}'
gapproof orangepro_find_test_gaps '{"root":"/path/to/repo","limit":10}'
gapproof orangepro_status '{"root":"/path/to/repo"}'
gapproof orangepro_record_run '{"root":"/path/to/repo","test":"math.test","outcome":"pass"}'
gapproof orangepro_export_evidence_pack '{"root":"/path/to/repo"}'
gapproof --version

退出代码：成功时为 0，分析或验证错误时为 1，用法错误时为 2。

MCP 服务

一个二进制文件同时提供两种接口。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/gapproof mcp

MCP 客户端配置：

{
  "mcpServers": {
    "gapproof": {
      "command": "npx",
      "args": ["-y", "@reneturcios/gapproof", "mcp"]
    }
  }
}

工具

除非另有说明，所有工具都接受 root（仓库路径）。

工具	额外输入	返回内容
orangepro_start	—	分析仓库，持久化 .gapproof/graph.json（保留已记录的运行），并返回 {root, sources, functions, tests, linked, unlinked} 计数。
orangepro_analyze_sources	—	执行相同的遍历，但不持久化：返回每个文件的函数列表以及函数总数。
orangepro_find_test_gaps	limit（可选）	返回未关联的函数，格式为 [{function, file, exported}]，先列出导出的函数，再按文件顺序排列。
orangepro_status	—	有持久化图时返回 {exists: true, generated_at, counts}。没有图时返回 {exists: false}，以及一份新生成但未存储的快照。
orangepro_doctor	—	返回 {root_exists, has_manifest, source_files, test_files, issues}；清单文件指根目录中的 package.json 或 pyproject.toml。
orangepro_graph_score	—	返回 {score, linked_ratio, proven_ratio, functions}：关联度占 60%，验证度占 40%。
orangepro_stats	—	返回 {files, functions, tests, test_files, linked, unlinked, proven, runs}。tests 统计单个测试用例；test_files 统计文件。
orangepro_rtm	—	返回源代码注释中找到的需求 ID 对应的 [{id, functions, covered}]；covered 表示所有关联函数均已关联。没有 ID 时返回空列表。
orangepro_changed_impact	files（必需数组）	根据给定的仓库相对路径文件，返回 {changed_functions, affected_tests, unlinked_changed}。
orangepro_record_run	test、outcome（必需），functions（可选）	向图中追加一次运行记录（若尚无图，则先执行一次全新分析），并返回 {recorded: true, runs_total}。
orangepro_explain_test	test（必需）	根据名称子字符串查找测试文件，并返回 {test, file, linked_functions, proven_functions, content_excerpt}（摘录不超过 400 个字符）。
orangepro_export_evidence_pack	—	返回给调用方 {generated_at, root, score, stats, gaps, runs}，不会写入任何内容。

范围

此核心子集省略了 orangepro_prove_loop、 orangepro_prove、orangepro_generate_tests、 orangepro_update_graph、orangepro_ai_links 和 orangepro_ai_flows。这些是原版中用于执行证明和 AI 辅助的工具；原版中的 AI 工作流需要模型密钥。 此子集仅复现本地分析功能，并受上述启发式方法的限制：基于名称的关联可能会遗漏间接覆盖，也可能因巧合提及而误判为覆盖；基于注释的 RTM 提取只能识别注释中写明的 ID。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, in-memory fixture repo, no network, no disk
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。