docsdiff

docsdiff

代码及其文档会悄然脱节。一个拉取请求重写了某个模块，却没有更新介绍它的指南；某个文档页面修正了代码从未有过的行为。审阅者能发现其中一些问题，但这些信号淹没在文件列表中。docsdiff 会明确指出这些信号：你将一组变更中的文件交给它，它就会按区域报告代码变更但文档未变、文档变更但代码未变、两者同步变更，或完全没有相关变更。

每个文件仅根据其路径进行分类——不会读取文件内容，也不会打开代码库。检查按固定顺序执行，匹配第一项后即停止：

• docs — 路径以 docs/ 开头或包含 /docs/ 路径段，文件名（转换为小写后）以 readme 开头，或扩展名为 md、mdx 或 rst。
• code — 扩展名为 ts、tsx、js、jsx、mjs、cjs、py、go、rs、java、rb、php、c、h、cpp、hpp 或 cs。
• other — 其他所有文件，包括没有扩展名的文件和 .gitignore 之类的隐藏文件。

扩展名是文件名中最后一个 . 之后的文本，转换为小写后判断，因此 PAGE.MD 属于 docs，App.TS 属于 code，与它们的小写形式相同。由于 docs 检查优先执行，因此代码目录中的 README 即使名称带有代码扩展名，也属于 docs：src/readme.py 属于 docs，而非 code。

每个文件都可以带有一个 area——模块、包或调用方使用的任意其他分组。没有区域的文件会归入字面区域名 "(global)"。对于每个出现的区域，报告都会统计其代码和文档变更，并指定一种状态：

• code_without_docs — 代码有变更，文档没有变更
• docs_without_code — 文档有变更，代码没有变更
• in_sync — 代码和文档都有变更
• no_relevant_changes — 两者都没有变更（只有 other 文件影响了该区域）

结果还会列出发生漂移的区域——即处于任一漂移状态的区域——并按升序排列，同时给出文件总数以及 code、docs 和 other 的数量。区域按代码单元顺序升序排列，"(global)" 按其字面字符排序。

无效输入——缺失、为空或非数组的 changes 列表；非对象条目；缺失、为空或重复的 path；存在但为空或非字符串的 area——会导致验证错误，并指出出错路径（例如 changes[1].area must be a non-empty string），且不会生成部分报告。计算纯粹在本地进行：不访问网络，不使用配置，也不读取你传入输入以外的任何文件。

命令行界面

npx @reneturcios/docsdiff check --input args.json
npx @reneturcios/docsdiff --version

args.json 包含完整的参数对象：

{
  "changes": [
    { "path": "src/api/handler.ts", "area": "api" },
    { "path": "src/api/auth.ts", "area": "api" },
    { "path": "docs/guide.md" },
    { "path": "assets/logo.png", "area": "api" }
  ]
}

报告以 JSON 格式打印：

{
  "areas": [
    { "area": "(global)", "code_changed": 0, "docs_changed": 1, "status": "docs_without_code" },
    { "area": "api", "code_changed": 2, "docs_changed": 0, "status": "code_without_docs" }
  ],
  "drifted": ["(global)", "api"],
  "counts": { "files": 4, "code": 2, "docs": 1, "other": 1 }
}

退出代码：成功时为 0；发生运行时错误（包括输入文件无法读取或无效，或输入无效）时为 1；用法错误时为 2。

MCP 服务

npx -y @reneturcios/docsdiff mcp

MCP 客户端配置：

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

工具

• check_docs_drift — 按区域检查一组变更是否存在文档漂移。

  • changes（数组，必需，至少一项）— 变更文件，采用 {path, area?} 对象；path 在整个集合中必须唯一，area 用于将文件归入指定区域，而不是 "(global)"

  返回 {areas, drifted, counts}。

Docker

docker run -i ghcr.io/cloudcorprecords/docsdiff
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/docsdiff check --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios