docsdiff

docsdiff

Code and its documentation drift apart quietly. A pull request rewrites a module and leaves the guide that describes it untouched; a docs page is corrected for behaviour the code never had. Reviewers catch some of it, but the signal is buried in the file list. docsdiff makes that signal explicit: you hand it the changed files of a change set, and it reports, per area, whether code changed without docs, docs changed without code, the two moved together, or nothing relevant changed at all.

Every file is classified from its path alone — no contents are read, no repository is opened. The checks run in a fixed order and the first match wins:

• docs — the path starts with docs/ or contains a /docs/ segment, the basename (lowercased) starts with readme, or the extension is md, mdx, or rst.
• code — the extension is one of ts, tsx, js, jsx, mjs, cjs, py, go, rs, java, rb, php, c, h, cpp, hpp, or cs.
• other — everything else, including files with no extension and hidden files such as .gitignore.

The extension is the text after the last . in the basename, lowercased, so PAGE.MD is docs and App.TS is code just as their lowercase spellings are. Because the docs check runs first, a README inside a code directory is docs even when its name carries a code extension: src/readme.py is docs, not code.

Each file may carry an area — a module, package, or any other grouping the caller uses. Files without an area are reported under the literal area name "(global)". For every area that appears, the report counts its code and docs changes and assigns one status:

• code_without_docs — code changed, docs did not
• docs_without_code — docs changed, code did not
• in_sync — both changed
• no_relevant_changes — neither changed (only other files touched the area)

The result also lists the drifted areas — those in either drift status — sorted ascending, and overall counts of files, code, docs, and other. Areas are sorted ascending in code-unit order, with "(global)" sorting by its literal characters.

Malformed input — a missing, empty, or non-array changes list, an entry that is not an object, a missing, empty, or duplicated path, an area that is present but empty or not a string — is a validation error naming the offending path (for example changes[1].area must be a non-empty string), and no partial report is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

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

args.json contains the full arguments object:

{
  "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" }
  ]
}

The report is printed as 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 }
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/docsdiff mcp

MCP client config:

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

Tools

• check_docs_drift — Check a change set for documentation drift per area.

  • changes (array, required, at least one) — changed files as {path, area?} objects; path is unique across the set, and area groups the file under a named area instead of "(global)"

  Returns {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

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios