readmeaudit

readmeaudit

README は次第に実態とずれていきます。インストールコマンドでは名前が変更されたパッケージを指定し、使用方法のセクションには 2 リリース前に CLI から削除されたフラグが記載されていても、ユーザーが存在しないコマンドをコピーするまで誰も気付きません。

readmeaudit は、パッケージの README と、その隣にある 2 つの信頼できる情報源、package.json および src/ 配下の CLI ソースを比較します。インストールコマンドで使われているパッケージ名が package.json の name と一致すること、README に記載されたすべての長いフラグがソースに実際に存在すること、ソースにあるすべての長いフラグが README に記載されていること、そして MCP サーバーを宣言しているパッケージが README にその旨を記載していることをチェックします。結果は判定付きの決定論的なレポートとして出力され、食い違いごとに根拠（ルール、重大度、ファイル、行）が示されます。判定は IN-SYNC または DRIFT です。

オフラインで動作し、静的なテキストのみを読み取り、対象パッケージ内のものを実行することはありません。CLI から、または MCP サーバーとして呼び出せるため、手動で実行するだけでなく、リリースワークフローやエージェントセッションでもチェックを実行できます。

インストール

npx @reneturcios/readmeaudit

このコマンドを 1 つ実行するだけで、グローバルにインストールせずにツールを実行できます。下記の audit コマンドで、対象のパッケージディレクトリを指定してください。

CLI の使い方

readmeaudit audit [path] [--json]
readmeaudit mcp
readmeaudit --version

• audit は、指定したパス（既定値：カレントディレクトリ）のパッケージをチェックし、人間が読みやすいレポートを出力します。JSON オプションを追加すると、同じレポートが JSON として出力されます。
• mcp は、stdio で MCP サーバーを起動します。
• version オプションはツールのバージョンを出力して終了します。

終了コード：判定が IN-SYNC の場合は 0、DRIFT の場合は 1、使い方に誤りがある場合や対象を読み取れない場合は 2 です。読み手が出力パイプを早期に閉じた場合、プロセスの終了コードは 0 ではなく 141 になります。

ドキュメントが実態と一致しているパッケージの出力例：

readmeaudit 0.1.0
Target: .
Verdict: IN-SYNC
Counts: flagsDocumented=3, flagsInSource=3, phantom=0, undocumented=0, nameDrift=0
Findings: none
IN-SYNC: no high or medium findings; 0 low or info finding(s) noted.

各レポートの件数には、README に記載された --flags とソースで見つかった --flags の数に加えて、記載されているものの実在しないフラグの数、ソースにあるもののドキュメントに記載されていないフラグの数、誤ったパッケージ名を指定したインストールコマンドの数が集計されます。

チェック内容

rule	severity	what it means
NAME-DRIFT	high	README のインストールコマンドで、package.json の name フィールドとは異なるパッケージ名が指定されています。検出結果には、根拠として行番号と該当行が含まれます。
NO-INSTALL	medium	README にインストールコマンドがまったく含まれていないため、新規ユーザーがパッケージ名を含むコマンドをコピーできません。
FLAG-PHANTOM	medium	長いフラグが README に記載されていますが、src/ 配下のどのソースファイルにも存在しません。
FLAG-UNDOCUMENTED	low	長いフラグが src/ 配下のソースにありますが、README には記載されていません。
MCP-UNDOCUMENTED	low	package.json で mcpName が宣言されているため、パッケージには MCP サーバーが含まれていますが、README では mcp に一度も触れていません。
CMD-UNKNOWN	info	フェンス付きコードブロック内の行が、パッケージで宣言された bin 名ではない単独のコマンド語で始まり、その行に長いフラグまたは mcp という語も含まれています。

各チェックの仕組み

名前。 名前チェックの対象は、インストール行に限られます。つまり、パッケージランナーのコマンド、または標準の JavaScript パッケージマネージャーのインストールコマンドを含む行です。これらの行では、コマンド語の後にある最初のオプション以外のトークンが、呼び出されたパッケージ名です。バージョンのサフィックスは取り除かれます。スコープ付きの名前と通常の名前の両方に対応しています。呼び出された名前が package.json の名前と異なる場合は、NAME-DRIFT になります。このチェックをインストール行に限定しているのは意図的です。本文や比較表では、正当に別のツール名に言及することがあり、そうした記述はインストールコマンドではないためです。

フラグ。 フラグチェックでは、README と src/ 以下のすべての TypeScript ファイル（再帰的に検索）から、長いフラグのトークン（ハイフン 2 つ、英字 1 つ、その後に英字、数字、またはハイフンが続くもの）を収集します。両方に同じ収集処理を使います。テキストとして記述された --flags のようなトークンを拾うのも、この収集処理です。その後、2 つの集合を両方向に差分比較し、フラグごとに 1 件の指摘を出します。

MCP。 package.json に mcpName フィールドがある場合、そのパッケージはその名前で MCP クライアントに提示されるため、README では少なくともプロトコルに言及する必要があります。このチェックでは、README 内の mcp という単語を大文字・小文字を区別せずに検索します。

コマンド。 コマンドチェックは、このツールの中で最も保守的なチェックです。これは意図的な設計です。フェンス付きコードブロック内のみを対象にし、行の最初のトークンのみを調べ、そのトークンが宣言済みの bin 名でも、よく知られたシェルやプログラムの語（パッケージマネージャー、ランタイム、コンテナツール、バージョン管理、基本的なシェルの語はすべて除外）でもない、単独の単語の場合に限ります。それでも重大度は info で、ほかのすべての指摘と同様に件数には含まれますが、判定結果は決して変わりません。使用例のブロックにある未知のコマンド語は、補助コマンド、エイリアス、または以前のリリースで名前が変更されたバイナリであることがよくあります。この指摘は、人が目を通すためのものであり、ゲートを失敗させるためのものではありません。

判定ルール

• IN-SYNC：重大度が high または medium の指摘がありません。low と info の指摘は報告されますが、判定結果には影響しません。終了コードは 0 です。
• DRIFT：重大度が high または medium の指摘が 1 件以上あります。終了コードは 1 です。
• 指摘はルール順、次に対象のフラグまたは名前順、さらに行順に並びます。レポートにはタイムスタンプが含まれないため、同じツリーで 2 回実行すると、バイト単位で同一の出力になります。

MCP サーバー

MCP クライアントの設定に次を追加します。

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

ツール：audit_readme(path) は、CLI が JSON オプションで出力するものと同じオブジェクトである、完全な監査レポートを JSON 形式で返します。

制限事項

• これは静的なテキスト比較です。readmeaudit は、package.json と src/ に信頼できる情報源がある名前、フラグ、コマンドをチェックできます。一方、本文の説明が正しいかどうかは判断できません。コードにない動作を、誤った名前やフラグを含めずに流暢な文章で説明する README は、チェックを通過します。
• フラグはテキストトークンです。ソース内のコメントや文字列リテラルにフラグがあれば、ソースに存在するものとして扱われます。また、実行時に動的に組み立てられるフラグ（複数の要素から構成されるものや、設定から読み込まれるもの）は検出されません。
• ソースの対象範囲は src/ 以下の TypeScript ファイルのみです。別の言語で実装された CLI や、ツリー内の別の場所にあるファイルはフラグチェックから見えないため、そのフラグは実際には存在していても検出されません。
• 名前チェックの対象はインストール行のみです。本文、バッジの URL、見出しにある古いパッケージ名は指摘されません。
• bin 名は package.json の bin フィールドから取得されます。bin フィールドのないパッケージでは、既知の語の除外以外にコマンドチェックの保護機能がありません。また、CMD-UNKNOWN の重大度が info に留まるのは、まさにこの理由によります。このツールは、推測に基づいて README を誤って非難するよりも、コマンドの報告漏れを許容します。
• 入力の欠落は指摘ではなくエラーです。対象に package.json がない場合、または README.md と README のどちらもない場合は、明確なメッセージと終了コード 2 を返して失敗します。