codebase-doctor

Codebase Doctor

モデルが構築し、Codebase Doctorが検証します。

対象を見つけ、決して推測しません。

ほとんどのリポジトリスキャナーは、誤検知を大量に出すか、難しいケースをひそかに見落として「問題なし」と報告するかのどちらかです。Codebase Doctorはそのどちらもしません。すべての検出結果に証拠が伴い、すべての監査で分析できなかった内容が報告されます。また、問題なしという結果は、対象範囲が実際にチェックされたことを意味します。

npx -y codebase-doctor audit . --changed --format brief

codebase-doctor brief
scope=full findings=1 shown=1 coverage=incomplete score=80
[high] security/secrets/provider-token src/config.ts:12 —
  Have an authorized human or external coding agent remove the value and rotate it,
  then rerun the audit.
coverage-limitations: validation: skipped, database: skipped, security: partial

最後の一文が重要です。ほとんどのツールは検出結果を出して終わりです。このツールは、実行のたびに、チェックしなかった内容を知らせます。

---

これが必要な理由

コーディングエージェントは、レビューが追いつくよりも速くコードをリリースします。問題は、エージェントがコードを書けないことではなく、マージ前にそのコードを検証するものがないことです。

Codebase Doctorはその検証ステップを担います。ソースグラフを構築し、コミット済みのシークレット、依存関係のずれ、安全でないDockerfile、ワークフローインジェクション、RLSの誤り、アクセシビリティのリグレッションをスキャンし、検証できなかった内容を正確に知らせます。

感覚ではなく、ベンチマークで検証：欠陥を1つずつ埋め込んだ17個のフィクスチャで、ルールの再現率100％、中程度以上の誤検知ゼロを達成しています（結果、npm run benchmarkで再現可能）。

レッドチーム検証済み：敵対的な変更コーパスでは、各欠陥を異なる形で隠そうとします。11/11の変異を検出し、7/7のコントロールで問題なし。CIでゲートされています（コーパス、npm run red-teamで再現可能）。

相互検証済み：独立して作成された2つのオフラインアナライザー（このリポジトリのsql-rlsとrls-doctor）を同じSQLコーパスに対して実行し、10件の検出結果が一致、重大度の不一致は0件、文書化されたカバレッジの差異は1件。安全なスキーマは両方で問題なしとなりました（スコアボード、npm run differential）。

実地調査：エージェントの設定がある公開リポジトリ100件のうち、23％に少なくとも1件の重大度の高い検出結果がありました。10％には壊れたインポート、4％にはコミット済みのキー情報、11％にはリスクのあるエージェント設定があります（レポート、匿名化済みで再現可能）。

インストール

npx -y codebase-doctor audit .          # no install
npm install -g codebase-doctor         # global

クイックスタート

codebase-doctor demo                             # disposable fixture: secret, broken import, blast radius
codebase-doctor bisect security/secrets/provider-token .   # when did this enter history?
codebase-doctor audit . --json                   # full audit
codebase-doctor audit . --changed --json         # just my diff
codebase-doctor audit . --changed --base main --json    # PR review
codebase-doctor audit . --format sarif           # GitHub code scanning
codebase-doctor audit . --format html > report.html     # shareable standalone report
codebase-doctor verify . --baseline before.json  # confirm fixes landed

demoは設定もリポジトリも必要ありません。追跡対象のシークレットと壊れたインポートを含む一時的なgitフィクスチャを作成し、実際のパイプラインでシミュレートしたエージェントの編集を監査して、影響範囲を出力し、CIゲートを示すために終了コード1で終了します。テンポラリディレクトリの外には一切触れません。

オプション

--run-checks          Permit configured validation commands
--changed             Audit Git changes and their affected scope (implied by review)
--base <ref>          Compare changed scope from the merge base with this ref
--json                Emit schema-versioned JSON
--format <format>     Output format: text, json, sarif, brief, or html (review adds markdown, github)
--all-findings        Review only: include findings outside the changed lines
--output <file>       Review only: write the report to a file as well as stdout
--exclude <glob>      Exclude a repository-relative path glob; repeatable
--baseline <path>     Compare with a prior Codebase Doctor JSON report
--timeout <ms>        Per-command timeout (default: 120000)
--fail-on <severity>  info|low|medium|high|critical|none (default: high)
--require-complete    Exit 2 when audit coverage is incomplete
--max-findings <n>    Cap brief output (default: 100)
--score               Print only the Repo Health score
--badge               Print a shields.io badge URL for the Repo Health score
--receipt <path>      Write a portable coverage receipt (digest-verified)
--receipt-key <path>  Sign the receipt with an Ed25519 private key (PEM)
--pheromone <path>    Write a privacy-bounded signal (rules and counts only)
--with-database       Permit live PostgreSQL catalog access
--with-advisories     Opt-in OSV advisory lookup over lockfile packages
--database-schema     Schema to inspect; repeatable (default: public)
--database-timeout    Catalog statement timeout in ms (default: 10000)

コードレビュー

review はプルリクエスト用のコマンドです。常に変更範囲を監査し、追加された差分行に検出結果を絞り込み、判定結果（NO_CHANGES、APPROVE、COMMENT、REQUEST_CHANGES）を出力します。そのため、無関係な古い問題がプルリクエストを不合格にすることはなく、空のチェックアウトが承認として扱われることもありません。

codebase-doctor review . --base origin/main --format markdown > review.md
codebase-doctor review . --base origin/main --format github
codebase-doctor review . --format json  # includes a machine-readable review envelope
codebase-doctor review . --base origin/main --receipt review.json
codebase-doctor review . --base origin/main --receipt review.json --receipt-key key.pem

• --format markdown は、判定結果、検出結果、ソースへの影響、カバレッジの制限を含む、プルリクエストのコメントにそのまま使える本文を生成します。
• --format github は、Actions のログからプルリクエストの差分にインライン注釈を付ける ::error ／ ::warning ／ ::notice ワークフローコマンドを、ネットワークアクセスなしで出力します。
• 変更されていない行の検出結果は判定の対象外となり、省略件数に含まれます。通常の audit では、引き続きその検出結果も報告されます。--all-findings を指定すると絞り込みが無効になり、--output <file> を指定すると標準出力に加えてレポートをファイルにも書き込みます。
• --baseline を指定すると、差分に含まれる新しい検出結果のみが判定に影響します。
• 差分が空の場合は APPROVE ではなく NO_CHANGES を報告します。ベース参照が指定されていない場合に CI でフェイルクローズするには、--require-base を使用します。
• --receipt <path> を指定すると、判定結果、差分範囲の件数、カバレッジの制限、検出結果のフィンガープリントを含む、移植可能なレビュー証明書を書き込みます。--receipt-key を追加すると Ed25519 で署名できます。verify-receipt は整合性を検証し、レビューの判定結果を出力します。
• 終了コード 1 はレビューで変更が要求されたことを示します。終了コード 2 は運用上の失敗を示し、問題のない結果を意味するものではありません。レビュー済みの差分を検証済みまたは問題なしと判断する前に、カバレッジを確認してください。

GitHub Action

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v4
  - uses: subhajitlucky/[email protected]
    with:
      format: sarif
      upload: "true"
      fail-on: high

検出結果は Security タブに表示されます。docs/github-action.md を参照してください。

---

チェック項目

シークレット — 作業ツリーと履歴

精度を優先しており、すべてを網羅するものではありません。秘密鍵のデータ、プロバイダートークンの形式、ペアになった AWS 認証情報、認証情報を含む URL、確度の高い機密情報の代入を検出します。Git で無視される .env は通常の保存先であり、検出対象ではありません。ただし、実際の認証情報を含む追跡対象の .env は検出対象です。

security/secrets-history は、最も重要なケース、つまりシークレットがコミットされた後に作業ツリーから削除されたケースを検出します。これにより、ローテーション済みに見えるリポジトリでも、漏えいを見逃しません。リポジトリの内容をチェックアウト、書き換え、実行することなく、すべてのブランチを対象に直近 200 件のコミットを調べます。変更を監査する場合、履歴ログの対象は変更されたパスに絞られるため、漏えいしたファイルを削除しただけではレビューを問題なしにできません。

一致した値は、すべての検出結果、フィンガープリント、エラー、レポートから除外されます。 Codebase Doctor は、独自の SARIF 内も含め、シークレットを出力することはありません。共有可能な内容の修正と認証情報のローテーションまたは無効化は、権限を持つ外部の人間またはエージェントが行い、その後、同じ監査を再実行する必要があります。

依存関係

security/dependencies は読み取り専用で、オフラインで動作します。npm のロックファイルバージョン 2 と 3、pnpm（v5 以降）、Yarn（classic と Berry）、Bun、Python の poetry と uv のロックファイルを認識します。その他のエコシステムは、推測による検出結果を出すのではなく、明示的に未対応のままにします。

ルールファミリー：security/dependencies/missing-lockfile、security/dependencies/manifest-lock-drift、security/dependencies/insecure-source、security/dependencies/mutable-git-source、security/dependencies/missing-integrity、security/dependencies/workspace-registry-resolution、security/dependencies/competing-npm-lockfiles、security/dependencies/competing-lockfiles。

ロックファイルの内容が一致している場合、^5.0.0 のような通常の semver 範囲は検出結果になりません。生の依存関係指定と解決済み URL はレポートから除外され、フィンガープリントにも含まれません。外部の認可された人間またはエージェントがメタデータを修正し、同じスコープを再実行する必要があります。依存関係グラフがクリーンまたは検証済みと判断する前に、カバレッジを確認してください。

npm、その他のパッケージマネージャー、シェル、インストーラー、ライフサイクルスクリプトは実行せず、ネットワークリクエストも行いません。それ自体で CVE やアドバイザリに関する主張をすることはありません。Python のカバレッジでは、上限付きの行スキャナー（TOML 依存なし）を使って、poetry.lock と uv.lock のパッケージブロック、および pyproject.toml の Poetry と PEP 621 の宣言を解析します。安全でないトランスポート、ピン留めされていない git 参照、ハッシュ証拠の欠落、ロックファイルの欠落、競合するロックファイル、判定可能なマニフェストとロックファイルの不整合を報告します。一方、判定不能な指定子、マーカー、直接 URL の不整合、推移的なエントリーのみの構成、requirements のみのレイアウトは、部分的なカバレッジとして表示されたままになります。

--with-advisories は、解決済みパッケージを対象に、上限付きの OSV 検索を 1 回実行します。マシンの外部に送信されるのは、名前、バージョン、エコシステムのみです。

ソースの影響 — このファイルを変更すると何が壊れるか

repository/source-graph は実際の構文パーサーを使用し（コードは決して実行しません）、JS/TS、Python、Go、Java、Rust を対象に静的インポートグラフを構築します。変更モードでは逆方向のエッジをたどり、変更された各ファイルからの決定的な最短影響パスを報告します。

変更モードのスコープは Doctor ごとに異なり、すべてに共通するファイルフィルターではありません。Project Doctor の構造ルールは、マニフェスト、ロックファイル、ワークスペース、テストの可視性について、変更パス外の指摘も報告できるよう、リポジトリ全体のスナップショットで実行されます。ファイル単位の Doctor（backend、frontend、infrastructure、agent surface、performance）は、インベントリ内に存在する変更ファイルのみを調べるため、変更監査の規模は変更内容に応じたものになります。設定された検証チェック計画は、プロジェクトの全トポロジーから作成したうえで、affectedProjectIds に絞り込まれます。静的 SQL は、影響を受けるマイグレーションストリームを選択し、選択した各ストリームの現在の全履歴をリプレイします。ライブデータベースは、別途 --with-database が要求された場合に限り、観測されたスキーマセット全体の監査を実行します。変更に関する指摘がゼロでも、全体が問題なくクリーンであることを意味しません。

repository/source-graph は実際の構文パーサーを使用し（リポジトリのコードは決して実行しません）、JavaScript と TypeScript（さらに Python、Go、Java、Rust）を対象に、静的な import、再エクスポート、型のみのインポート、リテラルの require、リテラルの動的インポートのエッジを認識します。循環は有効なトポロジーであり、指摘ではありません。このモジュールは設計上、指摘を出しません。

独立した、高い精度を優先する repository/source-integrity Doctor は、source/import-target-missing ルールのみを出力することで、トポロジーの制限が推測によるバグ判定につながるのを防ぎます。この Doctor が診断するのは、次の4つの証明可能なケースのみです。サポート対象のソース拡張子を持つ明示的な相対ターゲット、設定されたターゲットがサポート対象のソースファイルを明示的に指定する単一の決定的なエイリアス、エントリがサポート対象のソースファイルを明示的に指定する一意のワークスペースパッケージ、そして replace ディレクティブのないモジュールパス配下の内部 Go パッケージです。

拡張子のない参照、JSON、カスタムローダー、条件付き参照、曖昧な参照、外部参照、動的参照、循環は指摘されません。また、名前付きエクスポートを調べたり、参照先のエクスポート名の存在を検証したりすることもありません。

全体モードでは条件に合うすべてのエッジを調べます。変更モードでは、変更されたインポーターと、逆方向の影響を完全に受けるインポーターを調べます。ターゲットが削除または名前変更された場合、そのターゲットをインポートする未変更のファイルも選択されます。

監査ごとの指摘数は最大1,000件で、この上限に達した場合、または上流のグラフ制限が適用された場合は、必ずカバレッジが不完全であることを報告します。カバレッジが不完全な場合、ソース整合性に問題がないとは言えません。生のインポート指定子とソーステキストは指摘に含めず、正規化されたパス、インポートの種類、証明クラス、安全な位置情報のみを提示します。

外部の権限を持つ人間またはエージェントが、意図したターゲットを修正または復元し、同じスコープで再実行する必要があります。

codebase-doctor audit . --changed --base main

src/db/schema.ts → src/repositories/user.ts → src/api/users/[id]/route.ts
→ src/app/dashboard/page.tsx → tests/integration/user.test.ts

循環は有効なトポロジーであり、指摘ではありません。グラフモジュールは意図的にバグの指摘を出しません。repository/source-graph は設計上、指摘を出さず、独立した高い精度を優先する repository/source-integrity Doctor は、証明可能な インポートターゲットの欠落のみを報告するため、トポロジー上の制限が推測によるバグ判定につながることはありません。

スキーマ1のレポートには、sourceImpact（スキーマ 1）が含まれる場合があります。変更モードでは内部エッジを逆方向にたどり、影響を受けるプロジェクトを affectedProjectIds に追加し、変更された各ソースルートについて決定的な最短影響パスを報告します。レポートには影響を受けるファイルの総数を保持しつつ、シリアライズする影響記録は上限を設けます。パスが証明するのは静的なエッジの連鎖のみであり、依存先のバグではありません。生のインポート指定子とソーステキストは含めません。このモジュールはプラグインもネットワークリクエストも書き込みも使用しません。

ローカルの tsconfig および jsconfig ファイルは、相対エイリアスの決定的なサブセットに反映されます。これは Node または TypeScript のモジュール解決を完全に再現するものではありません。リテラルでない動的インポート、曖昧なターゲット、サポートされない設定または構文、読み取れない入力、グラフの上限は、指摘ではなくカバレッジの制限です。

ワークフローとインフラストラクチャ

script-injection（run: ステップ内の攻撃者が制御する ${{ github.event.* }}）、pull-request-target-checkout、write-all-permissions、ピン留めされていないアクション参照、ピン留めされていない Docker ベースイメージ、pipe-to-shell、root-user、および全ユーザーが書き込み可能なファイルを検出します。ワークフローはディスパッチされず、イメージもビルドされません。

PostgreSQL と Supabase RLS

オフラインの database/sql-rls は、対応する PostgreSQL マイグレーションのストリームが見つかると自動的に実行されます。認証情報は不要で、ネットワークリクエストも発生せず、マイグレーション SQL も実行しません。対応するマイグレーションから、テーブル、ポリシー、RLS、権限の想定状態を再構築します。カバレッジが不完全な場合、静的 SQL の結果がクリーンであるとは見なされません。

ライブの database/rls は、ポリシー、権限、ロール、メンバーシップ、適用状態、バイパス経路の読み取り専用カタログを通じて、観測されたデータベースの状態を調査します。環境変数の認証情報と読み取り専用のリピータブルリードトランザクションを使用し、--with-database で個別に権限を付与します。

database/rls-drift は、マイグレーションから想定される状態と、実際に稼働中のデータベースで観測された状態を比較し、table-missing-live、rls-disabled-live、force-rls-disabled-live、policy-missing-live、grant-missing-live、rls-enabled-live-only、policy-unmanaged-live を報告します。

database/rls-probe は動作検証レイヤーです。--probe-db を指定すると、読み取り専用のロールバック対象トランザクション内で各 --app-roles ID を偽装し、必要に応じて各 --subjects UUID に対して Supabase の request.jwt.claims を設定して、所有者やテナントの境界を越えてロールが行を読み取れるかどうかを検証します。

codebase-doctor audit . --with-database --probe-db \
  --app-roles authenticated \
  --subjects 00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002 \
  --owner-columns owner_id,tenant_id \
  --database-schema public

サブジェクト間または所有者間の読み取りは重大度が高い問題です。プローブは一切書き込みを行わず、コミットもせず、常にロールバックします。

データベースと Drizzle の危険性

読み取り専用でオフラインの database/drizzle モジュールと、その database/drizzle/raw-sql-date-parameter ルールは、実行時の境界で発生する問題を検出します。JavaScript の Date を生の Drizzle sql テンプレートに埋め込むと、カラムのタイムスタンプエンコーダーを迂回する可能性があります。そのため postgres-js が ERR_INVALID_ARG_TYPE をスローする一方、同等の SQL が psql では動作することがあります。

// Before: raw interpolation can bypass the timestamp column encoder.
const rows = await db.execute(sql`select * from jobs where run_at <= ${date}`);

// After: guidance for a human or separately authorized external coding agent.
const rows = await db.select().from(jobs).where(lte(jobs.runAt, date));

適用対象となるには、drizzle-orm/postgres-js アダプターのインポートが完全一致するか、drizzle-orm と postgres の両方について、スコープ内の所有プロジェクトまたはワークスペースの証拠が必要です。静的に証明された Date のデータフローのみを報告し、変数名から推測することはありません。検出結果の重大度は中程度、信頼度は高です。

検出対象ではないもの：Date()、Date.now()、エンコード済みの toISOString() 文字列、lte(column, date) などの型付き比較、および新しく作成したインラインのエンコーダーオブジェクトを sql.param(value, encoder) に直接渡すケースです。エンコーダーの識別子とエイリアスは、const として宣言されていても、そのオブジェクトが別の場所で変更される可能性があるため、静的には安全と証明できません。こうした埋め込みや未解決のデータフローは、推測で検出結果を出すのではなく、カバレッジの部分的な制限として扱われます。カバレッジが不完全な場合、Drizzle 監査の結果がクリーンであるとは見なされません。生の SQL とパラメーター値は、検出結果、フィンガープリント、レポートに含めません。修正を行い、同じスコープで再実行する必要があります。修正は、権限を与えられた外部の人間またはエージェントが行ってください。

エージェントの攻撃対象領域 — 最新の攻撃対象

エージェント設定の攻撃対象領域を監査します。設定を実行したり、設定先に接続したりすることはありません。

• MCP クライアント設定：ピン留めされていないパッケージ実行ツール、シェルコマンド、インライン認証情報、広範なファイルシステム権限
• SKILL.md：スコープが設定されていない allowed-tools の権限付与（Bash(*)、単独の Write）
• 権限のバイパス：bypassPermissions、--dangerously-skip-permissions、--yolo、yes-always、広範な permissions.allow

フロントエンド

JSX/TSX と静的 HTML のアクセシビリティ（img-missing-alt、iframe-missing-title、html-missing-lang、positive-tabindex）および静的 SEO（missing-title、missing-meta-description）を検査します。ブラウザーもビルドも使用しません。

frontend/security は、JSX ソースを読み取り専用かつオフラインで検査します。動的に計算された値に、証明可能なサニタイザー呼び出し（DOMPurify.sanitize、sanitizeHtml）がない場合、dangerously-set-inner-html を検出します。静的リテラルは安全として扱われ、スプレッドプロパティがある場合は検査対象外となります。

バックエンドと認証

backend/auth は読み取り専用で、JavaScript と TypeScript のソース、および OAuth コールバックとセッションの紐付けルール用の Go ソースをオフラインで解析します。サーバーの起動、リクエストの送信、トークンの発行は一切行わず、ソーステキストのみを読み取ります。

ルール：cors-wildcard-origin-with-credentials（ワイルドカードの origin: "*"、反映された origin: true、または * を含む許可リストで、認証情報が有効になっている場合）、session-cookie-security-disabled（Cookie の secure または httpOnly が明示的に false に設定されている場合）、jwt-decode-without-verify（verify 呼び出しを含まないファイル内に decode 呼び出しがある場合）、jwt-verify-algorithm-unrestricted（algorithms の許可リストがない場合）、および oauth-callback-session-binding（コールバックルートがクエリ文字列からセッション識別子を読み取り、ブラウザーに紐付いた state Cookie がない状態で、そのセッションにトークンを割り当てる場合）。OAuth ルールは、JS/TS では Babel AST を解析し、Go ではファイル横断の関数インデックスを備えた限定的な Go トークナイザーを使用します。コールバックハンドラーを解決できない場合や Go のみの未対応箇所がある場合は、カバレッジ上の制約として報告し、検出事項として扱うことはありません。CORS、セッション Cookie、JWT のルールは引き続き JavaScript/TypeScript のみが対象です。

backend/api は同じソースを読み取り専用でオフライン解析します。連結または補間された SQL テキストが、バインドされていることを確実に判定できる pg、postgres、mysql、mysql2、better-sqlite3、または sqlite3 のクエリ呼び出しに渡されると、sql-string-concat-query が検出されます（値の配列を使ったパラメーター化クエリは安全です）。静的でないコマンドが、バインドされていることを確実に判定できる child_process の exec/execSync（shell: true を指定した spawn を含む）に渡されると、child-process-exec-dynamic が検出されます。一方、execFile と通常の spawn は検出対象になりません。new Pool() のような構築を介したインスタンス呼び出しも、直接インポートと同様に解決されます。クエリテキストを解決できない場合は、カバレッジ上の制約として扱われます。

ルールが検出されるのは、呼び出し先がインポート宣言または CommonJS の require を通じて監査対象パッケージに解決されると確実に判定できる場合のみです。そのため、無関係なローカルヘルパー関数の名前が cors や decode であっても、検出されることはありません。静的に解決できない設定（リテラルではないオプション式、計算された Cookie フラグ、値を指定する可能性があるスプレッドプロパティなど）は、推測による検出事項ではなく、カバレッジ上の制約です。そのため、コードベースに問題がないと判断する前に、backend のカバレッジを確認してください。decode とアルゴリズムのルールはファイル単位で適用されます。別のファイルにあるミドルウェア内の verify 呼び出しによって、これらのルールが抑制されることはありません。設定されたオリジンやシークレットのリテラルはレポートに含まれず、フィンガープリントにも記録されません。

対象外：API 形状の検証、ワーカー、Webhook、cron、レート制限の解析。外部の権限を持つ人またはエージェントが設定を修正した後、同じ範囲を再実行します。

---

現在のカバレッジと目指す姿

ここが、ほとんどのスキャナーが見落とす部分です。

コードベース全体を診断するのは、統合された単一の監査ツールです。複数の独立した製品を寄せ集めたものではありません。フレームワークやドメイン固有の知識は、組み込みの内部監査モジュールとして備わっています。

フル監査では、適用可能な実装済みモジュールを対象に、指定されたリポジトリの範囲全体を調査します。すべてを網羅するものでも、普遍的なものでもありません。あらゆるドメインを解析できるわけではありません。コードベースが検証済み、または問題なしと判断する前に、coverage を確認してください。

すべてのレポートには domainCoverage が含まれます。これは、適用可能性とステータスを分けた9つのドメインのチェックリストです。これにより、未検出と、検出されたものの未対応、スキップ、失敗、未選択の状態を区別できます。モジュールレベルのステータスの詳細、エビデンス、制限事項も含まれます。coverageComplete は、バグがない、または正しいことを意味するものではありません。

つまり、次のとおりです。

• 問題なしという実行結果は、対象範囲が実際にチェックされたことを意味します。
• --require-complete を指定すると、スキップされた領域が問題なしとして報告されるのではなく、終了コード 2 で終了します。
• スキャンが切り詰められた場合や範囲に上限がある場合は、正確な total ／ emitted ／ omitted 件数と、決定論的なサンプルパスとともに、その旨が coverageSummary に示されます。

ドメイン	現在のソースカバレッジ	目指す姿
リポジトリ構造	インベントリ、フレームワーク検出、マニフェスト、ワークスペース、ロックファイル、テストの可視性、JS/TS + Python + Go + Java + Rust の影響グラフ	言語をまたぐ依存関係と動作のトポロジー
設定済みの検証	JS/TS および Python のコマンド計画。実行は --run-checks を指定した場合のみ	各エコシステムにまたがるサンドボックス化された検証
データベース	オフラインでのマイグレーション RLS、Drizzle の Date に関する危険性、ライブ RLS、静的解析とライブ環境の不一致	スキーマ、クエリ、権限、より多くのエンジン
フロントエンド	JSX/HTML の a11y、静的 HTML の SEO、生の HTML のシンク	React、Next.js、バンドル解析、より幅広い a11y
バックエンドと認可	読み取り専用のオフライン backend/auth（CORS、セッション Cookie、JWT、OAuth コールバックのバインド。JS/TS と Go の OAuth）および JS/TS の backend/api（SQL の連結、シェル実行）の解析。NestJS の検出	ワーカー、Webhook、cron、レート制限の解析
セキュリティ	シークレット（ツリーと履歴）、依存関係ルール、オプトインの OSV	シークレット、権限、脆弱性、サプライチェーン
インフラストラクチャ	Dockerfile と GitHub Actions	ホスティングとデプロイの解析
パフォーマンス	静的ファイルの衛生状態：コミット済みのビルド成果物、サイズの大きすぎるソース	キャッシュ、クエリ、メモリ、プロファイリング
AI システム	エージェントのサーフェス監査：MCP 設定、SKILL.md の権限付与、権限設定	プロンプト、トークン、グラウンディングの解析

目指す姿に記載された項目は計画中のモジュールであり、リリース済みの機能ではありません。組み込みのソース影響グラフ、シークレット解析、依存関係解析は 0.1.4 でまとめてリリースされており、過去の 0.1.3 パッケージには含まれていません。

精度とレポート上限の契約

ワークスペースの公開エントリ、生成されたターゲット、フィクスチャによって制御されたパスは、独立して問題があると確認されない限り、カバレッジの制限事項です。それ自体をターゲット欠落の検出結果とはしません。検出された pnpm、Yarn、Bun のスコープに、npm 固有の検出結果が適用されることはありません。秘密鍵を意図的なローカルテスト鍵と分類できるのは、インベントリに登録された localhost 専用証明書と暗号学的に一致する場合のみです。それ以外の一致した秘密鍵は、すべて高い重大度のまま扱われます。

スキーマ 1 のレポートでは、繰り返し発生するエビデンスを、規模を隠すことなく上限付きで出力します。coverageSummary には正確な total、emitted、omitted 件数が保持され、limitationGroups には各理由、決定論的なサンプルパス、省略されたパスの件数が保持されます。

コードベースが検証済み、または問題なしと判断する前に、coverage を確認してください。契約の詳細については、docs/architecture.md をお読みください。

読み取り専用の設計

Codebase Doctor はレポートを作成します。対象ファイルに直接書き込む API は公開しておらず、ファイルシステムへの直接書き込み機能もなく、修正実行機能も備えていません。対象への直接書き込みや修正を行う権限を付与されることはなく、対象ファイルを変更、修正、修復することもありません。人間または別途認可されたエージェントが変更を行い、その後、同じ範囲を再実行して検証します。

別途認可された --run-checks は、リポジトリが所有する検証用サブプロセスを起動します。これらはファイルシステムやネットワークから隔離されておらず、副作用が生じる可能性があります。これは検証の実行であり、Doctor に修復権限を与えるものではありません。

• --changed を指定しても、コマンド実行、ネットワーク、データベースへのアクセス権限は付与されません
• 検証コマンドには --run-checks、ライブデータベースには --with-database、OSV の照会には --with-advisories が必要です
• データベースの認証情報は DATABASE_URL または SUPABASE_DB_URL から取得し、接続文字列のフラグは使用しません
• ソース解析では構文を解析するだけで、ソースを実行することはありません。ロックファイル解析でパッケージマネージャーを起動することもありません
• 明示的に要求された OSV の照会を除き、外部ネットワークへの呼び出しは行いません

シャドー監査

shadow は、ステージ済み、未ステージ、削除済み、名前変更済み、未追跡のファイルを含む、作業ツリーの破棄可能なコピーを監査します。検証コマンド（--run-checks）はコピー内で実行されるため、リポジトリが所有する副作用（ファイルへの書き込み、キャッシュ、フック）が作業ツリーに影響することはありません。

codebase-doctor shadow . --run-checks --fail-on high --receipt shadow.json

コピーは必ず削除され、元のファイルが変更されることはありません。また、レシートには environment: shadow (disposable copy) と記録されます。信頼できない検証コマンドを実行する場合は、この方法が安全です。

検証スウォーム

swarm は、並列の読み取り専用ワーカーを使って複数のリポジトリを検証し、全体の判定をまとめます。判定は、その仕組み上、正確です。

• findings — ゲーティング対象の指摘事項（--fail-on 以上）が存在します
• unknown — 証拠が失われています。カバレッジが不完全または部分的であるか、ワーカーが失敗しています
• gaps — ゲーティング対象の指摘事項はありませんが、設計上、試行されなかったドメインがあります
• verified — 該当するすべてのドメインの処理が完了したか、該当しませんでした

codebase-doctor swarm ../api ../web ../worker --workers 4 --receipt-dir receipts/
codebase-doctor swarm ../api ../web --require-complete   # exit 2 on unknown or gaps

全体の判定は、構成要素のうち最も悪い判定になります。証拠が失われている場合に、クリーンな判定を主張することはありません。各ワーカーはカバレッジレシートを出力できます。

時系列二分探索

bisect は、破棄可能な git ワークツリーで履歴を古い順に監査し、ルールまたはフィンガープリントが最初に現れたコミットを特定します。

codebase-doctor bisect security/secrets/provider-token .
codebase-doctor bisect <fingerprint> . --max-commits 500 --json

出力には、コミット、作成者、メッセージ、場所、フィンガープリント、および親コミットに存在しないことを示す証拠が含まれます。親コミットはその直前にスキャンされ、対象が含まれていないことが確認されています。各コミットは破棄可能なワークツリーで監査され、作業ツリーが変更されることはありません。--all-history はマージコミットもスキャンします。デフォルトは first-parent です。

リポジトリの健全性スコア

すべてのレポートには、決定論的なスコアが含まれます。スコアは 100 から重大度ごとのペナルティ（critical は 25、high は 10、medium は 4、low は 1、info は 0）を差し引き、該当するカバレッジが完了していない場合はさらに 10 を差し引いた値で、0～100 の範囲に収まるよう調整されます。区分は、緑が 80 以上、黄が 50 以上、赤が 50 未満です。承認済み（抑制済み）の指摘事項はカウントされません。また、スコアがレポートに取って代わることはありません。コードベースが検証済みであると判断する前に、coverage を確認してください。

codebase-doctor audit . --score    # Repo Health: 71/100
codebase-doctor audit . --badge    # https://img.shields.io/badge/Repo%20Health-71%2F100-yellow

--score と --badge はスコアまたはバッジのみを出力します。終了コードは引き続き --fail-on に従います。JSON レポートには常に findingPenalty と coveragePenalty の内訳を含む score オブジェクトが含まれ、簡易出力のヘッダーには score= が表示されます。

終了コード

コード	意味
0	要求された監査が完了し、しきい値以上の指摘事項はありませんでした
1	要求された監査が完了し、しきい値以上の指摘事項が少なくとも 1 件ありました
2	監査を完了できなかったか、--require-complete の指定下でカバレッジが不完全でした

終了コード 2 は運用上の失敗を示し、クリーンな結果ではありません。

ベースラインと SARIF

--baseline はフィンガープリントを新規、変更なし、または解決済みに分類し、--fail-on を新規の検出結果にのみ適用します。外部で修正を行った後は、次のように確認してください。

codebase-doctor audit . --json > before.json
# ... fix happens elsewhere ...
codebase-doctor verify . --baseline before.json

verify は各フィンガープリントを resolved、unchanged、unresolved、または new として報告し、すべてが検証可能な形で解決済みでない限り、終了コード 1 を返します。unresolved は、網羅性が不完全な状態で見つからなかったことを意味し、修復を意味するものではありません。新しい verify スキャンでは、audit と同じオフライン監査範囲が実行されるため、セキュリティとデータベースの検出結果を比較できます。ライブデータベースへのアクセス権は引き続き付与されません。

カバレッジレシート

各監査では、何を確認したか、何を確認しなかったか、決定論的スコア、検出結果のフィンガープリントを記録した、ポータブルなカバレッジレシートを出力できます。正規化された本文に対する SHA-256 ダイジェストと、オプションの Ed25519 署名も含まれます。

codebase-doctor audit . --receipt receipt.json
codebase-doctor audit . --receipt receipt.json --receipt-key key.pem
codebase-doctor verify-receipt receipt.json   # exit 0 valid, 2 tampered

レシートには、対象ルート、範囲、HEAD コミット、ベースコミット、変更パス数、変更パスセットのダイジェストが記録されます。レシートに秘密の値やソーステキストが含まれることはありません。ダイジェストは改ざんの検知を可能にし、署名は鍵の保有者が発行したことを証明します。詳細はdocs/receipts.mdを参照してください。

フェロモンシグナル

監査では、ルール、重大度、件数のみを含むフェロモンシグナルを出力できます。パス、フィンガープリント、ソーステキスト、リポジトリ名は含まれません。

codebase-doctor audit . --pheromone signal.json
codebase-doctor pheromone merge signals/*.json --min-signals 3 --out index.json

merge は各シグナルのダイジェスト（存在する場合は署名も）を検証し、改ざんされた入力を拒否します。また、--min-signals 未満のシグナルでしか観測されていないパターンを除外します（k-匿名性）。その結果、誰のコードも公開することなく、実際に発生しているパターンをまとめた公開インデックスが生成されます。詳細はdocs/pheromones.mdを参照してください。

意図の検証

intent verify は、監査証拠に照らして宣言された意図を確認します。散文を解釈することはありません。主張は JSON、または PR 本文内のフェンス付き intent ブロックに記述します。

```intent
{ "intentVersion": "1", "claims": [
  { "id": "no-secrets", "kind": "rule-absent", "ruleId": "security/secrets/provider-token" },
  { "id": "score", "kind": "score-at-least", "value": 90 }
] }
```

codebase-doctor intent verify pr.md . --require-verified

各主張は検証済み、証拠の場所を伴う違反、または未確定のいずれかになります。未確定とは、主張の判定に必要なカバレッジが完了していないことを意味し、検証済みとして数えられることはありません。違反がある場合は終了コード 1 を返し、未確定の判定がある場合は --require-verified により終了コード 2 を返します。詳細はdocs/intent.mdを参照してください。

経済的検証

economy verify は、使い捨てのシャドウ台帳でトランザクションジャーナルを再生します。何も送信されず、何も移動しません。実際の価値が動く前に、経済的な不変条件を証明するか、その証拠を提示します。

codebase-doctor economy verify journal.json --policy policy.json

• non-negative-balances — 超過引き出し／二重支払いと、該当する正確な操作
• per-operation-limit と window-volume-limit — サイズと処理速度の上限
• allowlist — 送金先の取引相手
• declared-balances — ジャーナルに報告された残高が、再生結果と一致している必要があります

違反には証拠（操作 ID、インデックス、残高スナップショット）が付随します。違反がある場合は終了コード 1 を返し、未確定の判定がある場合は --require-proved により終了コード 2 を返します。詳細はdocs/economy.mdを参照してください。

証明付き修復

fix は検出結果に対する修復を生成し、何も書き込む前に使い捨てコピーで検証します。

codebase-doctor fix <fingerprint> . --patch fix.patch --receipt fix.json

source/import-target-missing の場合は、曖昧さのない既存の候補（まず完全一致するステムを探し、同じディレクトリを優先）を見つけて、シャドウコピーに1行の変更を適用し、再監査します。検出結果のフィンガープリントが消え、新たな中以上の重大度の検出結果が発生しない場合に限り、パッチを書き込みます。パッチは実際の git diff であり、レシートにはフィンガープリント、パッチの SHA-256、修正前後の判定が記録されます。元のリポジトリは変更されません。詳細はdocs/repairs.mdを参照してください。

エクスプロイトの証拠

witness は、リスクのあるパターンの検出結果を具体的なエクスプロイトに変換します。ペイロード、ペイロードによって生成される変換後のシンクテキスト、境界に違反する理由を示します。

codebase-doctor witness <fingerprint> .
# Payload:     ' OR '1'='1' --
# Transformed: select * from users where id = '' OR '1'='1' --'

サポート対象のルール：backend/api/sql-string-concat-query、 backend/api/child-process-exec-dynamic、および frontend/security/dangerously-set-inner-html。小規模な連結評価器が、リテラル、テンプレートリテラル、+、括弧、TS キャストを処理します。それ以外は未判定とし、決して推測しません。アーティファクトはダイジェストによって検出結果のフィンガープリントに紐付けられ、実行されることはありません。docs/witness.md を参照してください。

確認済みの検出結果（抑制）

人がレビューして受け入れた検出結果は、どのレポートからも隠すことなく、行内で確認済みにできます。

const API_KEY = "..."; // codebase-doctor-ignore: security/secrets/provider-token -- rotated test credential

• ディレクティブでは、ルール ID、doctor ID、または doctor/* のプレフィックスを指定でき、検出結果の該当行、またはその直前の行に適用されます。場所のない検出結果は行内で確認済みにできません。また、何にも一致しないディレクティブは無視されます。
• 確認済みの検出結果は findings から除外されるため、失敗ゲートを通過しますが、理由とディレクティブの場所を含めて suppressed に引き続きすべて表示されます。これらは存在する検出結果として扱われるため、ベースライン比較では unchanged と報告され、verify が resolved と報告することはありません。ディレクティブを削除すると、検出結果は新規として再び表示されます。
• 抑制された検出結果は、設計上 SARIF のアップロード対象から除外されます。代わりに、JSON、テキスト、または brief 出力で suppressed を確認してください。

MCP サーバーとエージェント

claude mcp add codebase-doctor --scope user -- npx -y [email protected] mcp

読み取り専用ツールにはそれぞれ、readOnlyHint: true、destructiveHint: false、idempotentHint: true が付与されています。audit_codebase、review_changes、verify_changes、explain_finding、verify_intent、build_receipt、describe_capabilities が対象です。レスポンスはおよそ 50 KB に制限されます。サーバーが --run-checks やライブデータベースアクセスを有効にすることはありません。失敗時には、{ error: { code, message, nextAction } } 形式の構造化 JSON が返されます。Codex CLI、Gemini CLI、汎用の stdio クライアントのセットアップ方法は docs/agents.md を参照してください。

レジストリのメタデータは server.json（io.github.subhajitlucky/codebase-doctor）に含まれています。公式 MCP レジストリ、Smithery、Glama への公開手順は docs/mcp-registries.md を参照してください。

公開中のリスティング：Glama · 公式 MCP レジストリ（io.github.subhajitlucky/codebase-doctor）。

Claude Code プラグインがこのリポジトリに含まれています（.claude-plugin/ + skills/）。

/plugin marketplace add subhajitlucky/codebase-doctor
/plugin install codebase-doctor

codebase-doctor instructions は、AGENTS.md、CLAUDE.md、.cursor/rules/、.windsurfrules/、.clinerules/、copilot instructions 用の、すぐに貼り付けられるスニペットを出力します。出力のみを行い、ファイルを書き込むことはありません。

ワークフロー：編集後に audit . --changed --format brief を実行し、PR の判定には review . --base main --format brief を実行します。信頼境界では audit . を全件実行し、外部で修正した後に verify を実行します。

ロードマップ

• バックエンド、パフォーマンス、AI の意味的監査を標準搭載
• グローバルな --require-complete ゲートに加え、ドメインごとのカバレッジ保証
• 同一のレポートスキーマに基づくプルリクエストへの注釈、フック、エージェントプラグイン
• 読み取り専用のマウントまたは使い捨てコピーでの承認済み検証
• 決定論的な doctor ベンチマーク（npm run benchmark、docs/benchmark.md を参照）：再現率、中程度以上の誤検知率、レビュー判定、シード済みフィクスチャでの抑制の適切さ
• モデル横断ベンチマーク：検出した欠陥、検証の成功率、トークンコスト

自己適用

CI は Codebase Doctor 自身を使って、このリポジトリを監査します。

node dist/cli.js audit . --baseline .codebase-doctor-baseline.json --format brief --fail-on high

ベースラインには、このリポジトリで受け入れ済みの検出結果が記録されています。現在は 0 件で、自己監査はクリーンです。新たな検出結果があると、CI は失敗します。すべてのフィクスチャのソースは分割されており、トークンが作業ツリー内や履歴内で連続して現れることはありません。生成されたフィクスチャにはトークンが含まれるため、demo では引き続き実際のシークレットの検出例を確認できます。

競合スキャナーのスコアボード

ほとんどのベンチマークは、独自に作成したテスト用データで自分たちだけで実施されています。これも同様ですが、そのことを明示したうえで、同じコーパスを独立してインストールした競合スキャナーにも適用します。

npm run rival-differential -- --markdown docs/rival-scoreboard.md

同じ17個の決定論的なケースに、アドバイザリー行と対照行を加えたものを使って、破棄可能なリポジトリを作成し、それぞれに対して codebase-doctor と、バージョンを固定した Semgrep CE、gitleaks、Trivy、osv-scanner を実行します。そして、検出した項目、見逃した項目、クリーンな対照データに対するノイズ、対象範囲外の項目を含む、日付付きのスナップショットを公開します。codebase-doctor が劣る項目も含まれます。競合ツールの結果は CI のゲートではありません。レジストリやアドバイザリデータベースは変化するためです。

• スナップショットと方法論：docs/rival-scoreboard.md
• 週次ワークフローで、最新の実行結果を Actions のジョブサマリーに公開します（.github/workflows/rival-scoreboard.yml）。

開発

npm install && npm run build && npm run typecheck && npm test

リリース時には npm pack でパッケージを作成し、クリーンな一時プロジェクトにインストールして、生成されたバイナリを実行して確認します。

ライセンス

MIT