gapproof

gapproof

gapproof は、コードリポジトリのテスト不足を分析するローカルツールです。ソースを走査して関数を抽出し、そのうちテストで言及されているものを確認して、テストでカバーされていないように見える関数を不足分として報告します。記録されたテスト実行は、もう一つのより強いシグナルになります。成功した実行で名前が挙げられた関数は、直接、またはその関数に関連付けられたテストを通じて、単に関連付けられているだけではなく、実証済みとみなされます。この2つのシグナルを組み合わせて、単一のカバレッジスコアを算出します。

このパッケージはクリーンルーム方式で再構築されたもので、ラベル付きのコアサブセットです。元の Orangepro MCP サーバー（orangepro_*）で説明されている18個のツールのうち、12個に対応しています。含まれないツールは、以下の「範囲」に記載しています。

仕組み — 正直に説明すると

AST もパーサーもなく、ネットワーク呼び出しも一切ありません。エンジンは、文書化されたヒューリスティックの集合です。

• 走査。 指定されたルートから開始し、node_modules、.git、dist、ドットで始まるディレクトリをスキップします。.ts、.tsx、.js、.jsx、.py で終わるファイルは、test/、tests/、__tests__/ の下にある場合、または *.test.*、*.spec.*、test_*.py、*_test.py という名前の場合にテストとして分類され、それ以外はソースとして分類されます。
• 抽出（正規表現）。 TypeScript/JavaScript：function name(、export function name(、const name = (...) =>（let／var、function キーワード形式、任意の async にも対応）。Python：def name(。_ で始まらない Python の名前はエクスポート済みとみなされ、TS/JS の名前は export を付けて宣言されている場合にエクスポート済みとみなされます。
• 関連付け。 テストファイルのコンテンツ内に関数名が単語として登場すると、その関数はテストに関連付けられているとみなされます。
• 実証。 orangepro_record_run は、実行記録（test、outcome: "pass" | "fail"、任意の functions）を永続化されたグラフに追加します。成功した実行で関数名、またはその関数に関連付けられたテストファイル／テストケースの名前が挙げられている場合、その関数は実証済みとみなされます。
• スコア。 60% × 関連付け率 + 40% × 実証率。0〜100の尺度で、小数点以下1桁まで報告されます。
• RTM。 [A-Z]+-\d+ に一致する要件 ID は、ソースのコメントのみ（//、/* … */、#）から読み取られ、同じファイルで定義された関数に関連付けられます。

状態は1つのファイル <root>/.gapproof/graph.json に保存されます。このファイルは orangepro_start と orangepro_record_run が書き込みます。それ以外は、リポジトリ（および実行記録が必要な場合はそのグラフ）を読み取るだけで、書き込みは行いません。

インストール

npx @reneturcios/gapproof orangepro_start '{"root":"/path/to/repo"}'

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/gapproof

コンテナはデフォルトで MCP サーバーとして起動します。CLI として使うには、CLI 引数を渡してください。API キーは不要です。元のツールの任意のモデルキーは、AI テスト生成ツールでのみ使用されますが、このサブセットには含まれていません。

CLI

CLI はツールに対応しており、各ツールにつき1つのサブコマンドがあり、引数を1つの JSON オブジェクトとして受け取ります。

gapproof orangepro_start '{"root":"/path/to/repo"}'
gapproof orangepro_analyze_sources '{"root":"/path/to/repo"}'
gapproof orangepro_find_test_gaps '{"root":"/path/to/repo","limit":10}'
gapproof orangepro_status '{"root":"/path/to/repo"}'
gapproof orangepro_record_run '{"root":"/path/to/repo","test":"math.test","outcome":"pass"}'
gapproof orangepro_export_evidence_pack '{"root":"/path/to/repo"}'
gapproof --version

終了コード：成功時は 0、分析または検証エラー時は 1、使用方法のエラー時は 2 です。

MCP サーバー

1つの実行ファイルで、どちらの使い方にも対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/gapproof mcp

MCP クライアントの設定：

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

ツール

特に記載がない限り、すべてのツールで root（リポジトリのパス）を指定します。

ツール	追加の入力	返される内容
orangepro_start	—	リポジトリを分析し、記録済みの実行結果を保持したまま .gapproof/graph.json に保存し、{root, sources, functions, tests, linked, unlinked} の件数を返します。
orangepro_analyze_sources	—	保存は行わず同じ走査を実行し、ファイルごとの関数一覧と関数の合計数を返します。
orangepro_find_test_gaps	limit（任意）	未リンク関数を [{function, file, exported}] として返します。エクスポート済み関数が先で、その後はファイル内の順序です。
orangepro_status	—	グラフが保存されている場合は {exists: true, generated_at, counts} を返します。保存されていない場合は {exists: false} と、新たに生成した未保存のスナップショットを返します。
orangepro_doctor	—	{root_exists, has_manifest, source_files, test_files, issues} を返します。マニフェストはルートにある package.json または pyproject.toml です。
orangepro_graph_score	—	{score, linked_ratio, proven_ratio, functions} を返します。リンク済みの割合が 60％、実証済みの割合が 40％です。
orangepro_stats	—	{files, functions, tests, test_files, linked, unlinked, proven, runs} を返します。tests は個々のテストケース数、test_files はファイル数です。
orangepro_rtm	—	ソースコメントにある要件 ID を [{id, functions, covered}] として返します。covered は、関連するすべての関数がリンク済みであることを示します。ID がない場合は空です。
orangepro_changed_impact	files（必須の配列）	指定されたリポジトリ相対パスの変更ファイルについて、{changed_functions, affected_tests, unlinked_changed} を返します。
orangepro_record_run	test、outcome（必須）、functions（任意）	グラフに実行結果を追加します（グラフがない場合は先に新たな分析を実行）。{recorded: true, runs_total} を返します。
orangepro_explain_test	test（必須）	名前の部分一致でテストファイルを検索し、{test, file, linked_functions, proven_functions, content_excerpt} を返します（抜粋は 400 文字以下です）。
orangepro_export_evidence_pack	—	{generated_at, root, score, stats, gaps, runs} を呼び出し元に返します。ファイルへの書き込みは行いません。

対象範囲

このコアサブセットには、orangepro_prove_loop、 orangepro_prove、orangepro_generate_tests、 orangepro_update_graph、orangepro_ai_links、および orangepro_ai_flows は含まれません。これらはオリジナルに含まれる証明実行ツールと AI 支援ツールです。オリジナルでは、AI フローの実行にモデルキーが必要です。 このサブセットが再現するのはローカル分析機能のみです。前述のヒューリスティックには 限界があり、名前に基づくリンクでは間接的なカバレッジを見逃すことや、 偶然の言及をカバレッジとして扱うことがあります。また、コメントに基づく RTM の抽出では、 コメント内に記載された ID のみが対象になります。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, in-memory fixture repo, no network, no disk
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。