approvepath

approvepath

A CODEOWNERS file says who is supposed to approve a change. Review history says who actually shows up. approvepath puts the two side by side for one pull request: you hand it the CODEOWNERS rules, the files the PR touches, and whatever past review activity you have, and it hands back, per file, the owners the rules assign and the people who have reviewed that exact file before.

Pattern matching follows a pinned subset of CODEOWNERS semantics, so the answer never depends on which CODEOWNERS dialect you had in mind. Any leading / is stripped from both the pattern and the file path before comparing. A pattern ending in / is a directory prefix: it matches every file under that directory. A pattern containing * is a glob that must match the whole path — ** matches any run of characters including /, while a single * matches any run except /. Any other pattern matches a file that equals it exactly, or a file underneath it (the pattern plus / as a prefix), so a bare directory name owns its whole subtree.

When several rules match the same file, the last matching rule in file order wins — the same override rule CODEOWNERS itself uses, and the reason a broad early rule can hand a subtree to a team while a later, narrower rule hands one corner of it back. A file no rule matches is unowned: its owners list is empty and its pattern is null, and it also appears in unowned_files, in input order.

Review history is counted plainly. For each changed file, frequent_reviewers counts, per reviewer, how many supplied review entries by that reviewer list the file exactly — no prefix credit, no directory credit. Reviewers are ranked by count descending, then by name ascending, and only the top three are reported. required_reviewers collects every owner from every winning rule across the PR, deduplicated and sorted, which is the shortest honest answer to "whose approval does this PR actually need?".

Everything is computed locally from the arguments alone: no repository is read, no hosting API is called, and nothing is guessed. Malformed input — a rule with an empty pattern, a changed file that is not a non-empty string, a review entry missing its reviewer — is a validation error naming the offending path, with no partial result.

CLI

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

args.json contains the full arguments object:

{
  "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 is optional and defaults to []. The result is printed as 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"]
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/approvepath mcp

MCP client config:

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

Tools

• map_approvals — Map the approval path for a pull request.

  • codeowners (array, required, may be empty) — CODEOWNERS rules in file order; each entry is {pattern, owners}, where pattern is a non-empty string and owners is an array of non-empty strings (may be empty)
  • changed_files (array of strings, required, non-empty) — paths of the files the PR changes
  • reviews (array, optional, default []) — past review activity; each entry is {reviewer, files}, where reviewer is a non-empty string and files is an array of strings (may be empty)

  Returns {files, unowned_files, required_reviewers}, where files holds one {file, owners, pattern, frequent_reviewers} entry per changed file, in input order.

Docker

docker run -i ghcr.io/cloudcorprecords/approvepath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/approvepath map --input /w/args.json

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios