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 は code ではなく docs です。

各ファイルには area を付けられます。これは、呼び出し元が使用するモジュール、パッケージ、その他のグループです。area のないファイルは、文字列の area 名 "(global)" の下に報告されます。レポートでは、該当する各 area についてコードとドキュメントの変更数を集計し、次のいずれかのステータスを割り当てます。

• code_without_docs — コードは変更されたが、ドキュメントは変更されていない
• docs_without_code — ドキュメントは変更されたが、コードは変更されていない
• in_sync — 両方が変更された
• no_relevant_changes — どちらも変更されていない（area に変更があったのは other ファイルのみ）

また、どちらかの乖離ステータスに該当する area をまとめた「乖離した area」の一覧が昇順で表示され、ファイル数、コード数、ドキュメント数、その他の全体数も表示されます。area はコードユニット順で昇順に並べられ、"(global)" は文字列そのものの文字で並べられます。

不正な入力 — changes リストがない、空である、または配列ではない場合、要素がオブジェクトではない場合、path がない、空である、または重複している場合、area が存在するものの空であるか文字列ではない場合 — は、問題のあるパスを示す検証エラーになります（例：changes[1].area must be a non-empty string）。部分的なレポートは生成されません。処理は純粋かつローカルで行われます。ネットワーク、設定、渡された入力以外のファイル読み込みはありません。

CLI

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 — 変更セットについて、area ごとのドキュメントの乖離をチェックします。
  • changes（配列、必須、1 件以上） — {path, area?} オブジェクトとして指定する変更ファイル。path はセット内で一意であり、area を指定すると、ファイルは "(global)" ではなく名前付きの area に分類されます。

{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