approvepath

approvepath

CODEOWNERS ファイルには、変更を承認することになっている人が記されています。 レビュー履歴には、実際に誰がレビューに参加したかが記されています。approvepath は、1 つのプルリクエストについてこの 2 つを並べて表示します。CODEOWNERS のルール、PR が変更するファイル、手元にある過去のレビュー活動を渡すと、ファイルごとに、ルールで割り当てられたオーナーと、そのファイルそのものを過去にレビューした人を返します。

パターンの照合には、固定された CODEOWNERS セマンティクスの一部を使用するため、どの CODEOWNERS 方言を想定していたかによって結果が変わることはありません。比較の前に、パターンとファイルパスの両方から先頭の / を取り除きます。末尾が / のパターンはディレクトリのプレフィックスで、そのディレクトリ以下のすべてのファイルに一致します。* を含むパターンはパス全体に一致するグロブです。** は / を含む任意の文字列に一致し、単一の * は / を除く任意の文字列に一致します。それ以外のパターンは、完全一致するファイル、またはそのパターンに / を付けたものをプレフィックスとする配下のファイルに一致するため、ディレクトリ名だけのパターンはそのディレクトリ以下全体のオーナーになります。

複数のルールが同じファイルに一致する場合は、ファイル内で最後に一致したルールが適用されます。これは CODEOWNERS 自体と同じ上書きルールであり、広い範囲に一致する先行ルールがサブツリーをチームに割り当てた後、より限定的な後続ルールがその一部を別のオーナーに戻せる理由です。どのルールにも一致しないファイルはオーナーなしとなり、owners リストは空、pattern は null になります。また、入力順で unowned_files にも表示されます。

レビュー履歴は単純に集計されます。変更されたファイルごとに、frequent_reviewers は、レビュー担当者ごとに、その担当者の提供されたレビューエントリーのうちファイルを正確に列挙している数を数えます。プレフィックス一致やディレクトリ一致はカウントされません。レビュー担当者は、件数の降順、次に名前の昇順で並べられ、上位 3 名のみが報告されます。required_reviewers には、PR 全体で適用されたすべてのルールのオーナーが重複なく集められ、ソートされます。これは「この PR に実際に承認が必要なのは誰か？」への、最も簡潔で正確な回答です。

すべての処理は引数だけを使ってローカルで行われます。リポジトリは読み込まず、ホスティング API も呼び出さず、推測もしません。パターンが空のルール、空でない文字列ではない変更ファイル、レビュー担当者が欠落しているレビューエントリーなど、不正な入力は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。

CLI

npx @reneturcios/approvepath map --input args.json
npx @reneturcios/approvepath --version

args.json には引数オブジェクト全体を格納します。

{
  "codeowners": [
    { "pattern": "src/", "owners": ["@core"] },
    { "pattern": "src/api/", "owners": ["@api-team", "sam"] }
  ],
  "changed_files": ["src/api/handler.ts", "README.md"],
  "reviews": [
    { "reviewer": "sam", "files": ["src/api/handler.ts"] },
    { "reviewer": "lee", "files": ["src/api/handler.ts"] }
  ]
}

reviews は省略可能で、省略時のデフォルトは [] です。結果は JSON として出力されます。

{
  "files": [
    {
      "file": "src/api/handler.ts",
      "owners": ["@api-team", "sam"],
      "pattern": "src/api/",
      "frequent_reviewers": [
        { "reviewer": "lee", "reviews": 1 },
        { "reviewer": "sam", "reviews": 1 }
      ]
    },
    {
      "file": "README.md",
      "owners": [],
      "pattern": null,
      "frequent_reviewers": []
    }
  ],
  "unowned_files": ["README.md"],
  "required_reviewers": ["@api-team", "sam"]
}

終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）時は 1、使用方法のエラー時は 2 です。

MCP server

npx -y @reneturcios/approvepath mcp

MCP クライアントの設定：

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

ツール

• map_approvals — プルリクエストの承認経路をマッピングします。

  • codeowners（配列、必須、空でも可）— ファイル順の CODEOWNERS ルール。各エントリーは {pattern, owners} で、pattern は空でない文字列、owners は空でない文字列の配列です（空でも可）。
  • changed_files（文字列の配列、必須、空でない）— PR が変更するファイルのパス
  • reviews（配列、省略可能、デフォルトは []）— 過去のレビュー活動。各エントリーは {reviewer, files} で、reviewer は空でない文字列、files は文字列の配列です（空でも可）。

  {files, unowned_files, required_reviewers} を返します。files には、入力順で変更されたファイルごとに 1 つの {file, owners, pattern, frequent_reviewers} エントリーが格納されます。

Docker

docker run -i ghcr.io/cloudcorprecords/approvepath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/approvepath map --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