@expo/code-review-cli 0.3.0 → 0.4.0

package/README.md

@@ -74,7 +74,7 @@ Options (most to least common):
 | --- | --- |
 | `--pr <n>` | Review GitHub PR #n by number (diff fetched via `gh`, no checkout); not combinable with `--base`/`--head`/`--staged`. |
 | `--post` | With `--pr`, also post the result as the PR comment (needs `gh` auth). Omit to preview only; re-run with `--post` to publish. |
-| `--staged` | Review only staged changes. |
+| `--staged` | Review only staged changes (index vs HEAD; not combinable with `--base`/`--head`). |
 | `--base <ref>` | Base ref to diff against (default: merge-base with the default branch). |
 | `--head <ref>` | Head ref to diff (default: working tree, incl. uncommitted changes). |
 | `--agents <a,b>` | Run only these agents (comma-separated ids); default: all. |
@@ -101,14 +101,132 @@ is a ready example to adapt.
 | Command | What it does |
 | --- | --- |
 | `ecr init [--no-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) + a CI workflow. |
+| `ecr init --monorepo` | …and add a `routing.jsonc` routing manifest (one default scope). |
+| `ecr init --scope <dir>` | Scaffold a per-team scope under `<dir>` and register it in the manifest. |
 | `ecr review [options]` | Review local changes and print an advisory review (default command). |
+| `ecr review --scope <name>` | Review only one routing scope over just that scope's changed files. |
 | `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
-| `ecr doctor` | Check environment, config, and model credentials. |
+| `ecr doctor [--list-scopes]` | Check environment, config, credentials, and (with a manifest) scopes. |
+
+Extra flags for monorepos: `review`/`ci` `--config-dir <dir>` (load config from an
+alternate dir; also `ECR_CONFIG_DIR`), `ci --scopes a,b` (limit the fan-out to
+named scopes), `ci --comment single|per-scope` (override the manifest).
 
 (When developing this repo itself, use `bun run src/cli.ts <command>`.)
 
 ---
 
+## Monorepos (routing manifest)
+
+A monorepo can route different subtrees to different reviewer rosters from a single
+infra-owned manifest. There is still **one workflow, one `ecr ci` process** per PR:
+it reads the changed files once, assigns each to exactly one scope, reviews each
+active scope over only its files, and renders one comment. Because it is a single
+writer in a single process there is no comment/check race and no locking.
+
+```
+your-monorepo/
+  .expo-code-review/
+    routing.jsonc          # the manifest — infra-owned, ordered scope list + locked defaults
+    config.jsonc           # the default/root scope; the ONLY place auth/tokenEnv lives
+    shared.md coordinator.md agents/
+  server/
+    www/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}       # www team
+    website/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # website team
+  .github/workflows/expo-code-review.yml   # unchanged shape: one workflow, one `ecr ci`
+```
+
+```jsonc
+// .expo-code-review/routing.jsonc
+{
+  // Central guardrails every scope inherits and CANNOT override.
+  "defaults": {
+    // The ONLY place auth/tokenEnv is honored (besides the root config.jsonc).
+    "auth": { "mode": "oauth", "provider": "anthropic", "tokenEnv": "ANTHROPIC_OAUTH_API_KEY" },
+    "enforceAgents": ["security"],            // always runs on every scope, roster or not
+    "commentTag": "expo-ai-code-reviewer"     // per-scope markers derive from this
+  },
+  "comment": "single",   // "single" = one aggregated comment (default) | "per-scope"
+  // Ordered; the LAST matching scope wins per changed file (CODEOWNERS discipline).
+  "scopes": [
+    { "name": "default",        "paths": ["**/*"],              "config": "." },
+    { "name": "server-www",     "paths": ["server/www/**"],     "config": "server/www" },
+    { "name": "server-website", "paths": ["server/website/**"], "config": "server/website" }
+  ]
+}
+```
+
+```jsonc
+// server/www/.expo-code-review/config.jsonc  (the www team owns this)
+{
+  // NO "auth" block — locked centrally; a tokenEnv here is rejected by loader + CI guard.
+  "model": "anthropic/claude-sonnet-5",
+  "policy": { "includeSuggestions": false },
+  "noise":  { "additionalIgnores": ["server/www/**/__generated__/**"] }
+  // shared.md, coordinator.md, agents/*.md live beside this file — the www team's roster.
+}
+```
+
+- **Path glob dialect** — `**` crosses `/`, `*` matches within a segment. Keep a
+  `**/*` catch-all scope so no changed file goes unreviewed (`ecr doctor` flags a
+  coverage gap otherwise). Scopes are ordered and the **last** match wins, so put
+  broad scopes first and specific ones after (CODEOWNERS/Renovate discipline).
+- **Comment modes** — `single` posts one aggregated comment (a scope summary table
+  + a collapsed `<details>` per scope) under the existing marker; `per-scope` posts
+  one cleanly-namespaced comment per scope. A scope with zero matched files gets its
+  stale comment deleted.
+- **Scoped flags** — `ecr ci --scopes a,b` limits the fan-out; `ecr ci --comment
+  single|per-scope` overrides the manifest; `ecr review --scope <name>` runs one
+  scope locally; `ecr review`/`ecr ci --config-dir <dir>` (or `ECR_CONFIG_DIR`)
+  load config from an alternate directory; `ecr doctor --list-scopes` prints the
+  scope table. **`--config-dir` designates an alternate ROOT config dir: both
+  `config.jsonc` and `routing.jsonc` are read from it, so the root config and its
+  manifest always travel together. Scope `config` paths stay repo-root-relative —
+  the override swaps the root config/manifest against the *real* scope tree, it
+  does not relocate the scopes themselves.**
+- **Passes budget** — `defaults`-level `budget` bounds total review time:
+  `totalPassesMinutes` (default 32) is split across active scopes (which run
+  sequentially in one `ecr ci`), clamped up to `minScopeMinutes` (default 5) so a
+  single scope still gets a workable window. When enough scopes are active that the
+  floor would overshoot the total, `ecr ci` keeps the floor but warns, and `ecr
+  doctor` flags the worst case (`scopes × floor` vs total) — raise the workflow
+  `timeout-minutes` or trim scopes.
+- **Adoption is incremental** — with no `routing.jsonc`, behavior is exactly as
+  before (single config). Add the manifest with just a default scope → still one
+  comment, identical behavior. Land per-team scope dirs one at a time; everything
+  else keeps hitting the default scope.
+
+### Security
+
+- **auth is locked to the root.** `tokenEnv` (which env var becomes the model
+  credential) is honored in exactly one place: the root `config.jsonc` or
+  `routing.jsonc` `defaults.auth`. A scope config declaring `auth`/`breakGlass`
+  **fails to parse** (Zod-level rejection), and the CI guard step independently
+  sweeps every `.expo-code-review/config.jsonc`/`routing.jsonc` repo-wide and refuses
+  to run unless `tokenEnv` appears exactly once, in a root-owned file, equal to
+  `ECR_EXPECTED_TOKEN_ENV`. A routing manifest can never widen exposure — globs only
+  choose *which roster* reviews a file, never *which secret* is sent.
+- **enforceAgents can't be weakened.** Agents listed in `defaults.enforceAgents`
+  (e.g. `security`) are injected into every scope with `alwaysRun`, taken from the
+  root roster — a scope defining a same-id agent gets the root one, so a team can't
+  shadow the enforced reviewer with a weaker version on its own subtree.
+- **Config comes from the checked-out ref (documented tradeoff).** The scaffolded
+  auto workflow checks out the PR **merge ref**, so a PR *can* edit rosters, prompts,
+  and routing globs for its own advisory review — that only steers what the
+  comment-only reviewer says about that PR. What a PR can **never** do is touch
+  credentials: `auth` is locked by the scope-schema rejection, the CLI's runtime
+  `ECR_EXPECTED_TOKEN_ENV` check, and the guard step above, all three of which run
+  against whatever ref is checked out. A `/review`-command workflow that checks out
+  only the trusted base ref (see eas-cli's) closes the prompt-tampering vector too;
+  resolving config from the base ref on the auto path as well is on the
+  [roadmap](./ROADMAP.md).
+
+Ownership is enforced with CODEOWNERS: `/.expo-code-review/routing.jsonc @your-infra`
+(the single authoritative router) and `/server/www/.expo-code-review/ @your-www-team`
+(each team owns only its own scope dir). Rerouting globs is gated behind infra review.
+
+---
+
 <details>
 <summary><b>How it works</b></summary>
 
@@ -135,6 +253,49 @@ and applies Anthropic prompt caching automatically.
 
 </details>
 
+<details>
+<summary><b>Tokens, cost &amp; prompt caching</b></summary>
+
+Every run reports what it spent and how much of it was served from the prompt
+cache, in three places:
+
+- **Job log (stderr)** — one line at the end of the run:
+  `Token usage — input …, output …, cache read …, cache write … (cost $…)`.
+- **GitHub Actions step summary** — a per-pass table (one row per agent, plus the
+  cross-cutting pass, coordinator, and verifier), the run's cache hit rate, and
+  the exact comment that was posted. The PR comment is updated in place on every
+  run, so the step summary is where past runs' comments remain readable.
+- **`.expo-code-review/.runs/reviews.jsonl`** — one JSON line per run (uploaded as
+  a CI artifact) with the same totals plus per-pass `agentTokens`, the raw
+  per-agent findings, coverage notes, and what the verifier dropped.
+
+**How the caching works.** Anthropic prompt caching is a *prefix match*: the
+provider caches the rendered prompt up to a marker, and any byte change anywhere
+in that prefix invalidates everything after it. The reviewer is laid out so the
+prefix is stable — the system prompt (`shared.md` + the agent's own `.md`) is
+byte-identical for every chunk an agent reviews, while the volatile parts (the
+diff, file lists, PR metadata) travel in the user message *after* the prefix and
+never touch it. The first call per agent **writes** the cache (`cache write`,
+billed ~1.25× the input price); every later chunk in the run **reads** it
+(`cache read`, ~0.1× the input price). Cache entries live ~5 minutes and are
+refreshed on use, which comfortably covers a run's concurrent calls.
+
+**Reading the numbers.** Hit rate = `cache read / (cache read + input)` — the
+share of prompt tokens served from cache instead of being reprocessed at full
+price. Multi-chunk reviews should show a high rate; single-chunk reviews mostly
+show writes (there is nothing to re-read within the run).
+
+**Keeping hits high:**
+
+- Keep `shared.md` and `agents/*.md` stable. Any edit writes a new prefix — one
+  extra cache write per agent on the next run, then it is warm again. Never put
+  varying text (dates, PR numbers) into prompt files.
+- Very short prompts may show `cache read 0`: prompts below the model's minimum
+  cacheable size (~1–4K tokens depending on the model) are silently not cached.
+  That is expected, not a bug.
+
+</details>
+
 <details>
 <summary><b>Configuration — <code>.expo-code-review/</code></b></summary>
 
@@ -176,6 +337,9 @@ per-repo `noise.additionalIgnores`.
   "policy": { "includeSuggestions": false },  // suppress suggestion-severity findings
   "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 6 },
   "noise": { "additionalIgnores": ["packages/*/build/**"] },
+  "review": { "trigger": "all",               // which PRs `ecr ci` reviews: "all"
+              "label": "ai-review",            // (default, except ai-review:skip) or
+              "skipLabel": "ai-review:skip" }, // "label" (only labeled PRs)
   "breakGlass": { "marker": "/skip-review" }, // PR body marker that skips the review
   "commentTag": "expo-ai-code-reviewer",      // hidden tag used to find/update the comment
   "auth": { "mode": "oauth", "provider": "anthropic",
@@ -223,6 +387,14 @@ change which model reviewed your code. Use an explicit override instead.
   un-reducible pass reports a coverage gap — and it is always reported, never silent.
 - **Parse failures are retried** (same session, then once in a bounded fresh
   session) — separate from the timeout path.
+- **Transient API errors are retried** (bounded backoff on 429/5xx/network) —
+  distinct from both the timeout path (abandon) and the parse path; a one-off blip
+  no longer drops an entire pass.
+- **Auth failures surface once, and fail fast** — `ecr` checks the configured
+  provider's credential at startup and stops with one clear message if it's missing
+  (rather than failing every pass); a credential rejected mid-run (401/403)
+  collapses into a single actionable coverage note pointing at
+  `auth.tokenEnv`/`REVIEWER_MODEL`.
 - **A failed run never reads as "Approve"** — all passes fail → "could not
   complete"; some fail → never a clean approve, and coverage-reduced.
 - **The coordinator can't sink the run** — if consolidation fails, findings are
@@ -243,9 +415,12 @@ line: **comments = one-shot actions, labels = persistent configuration.**
 - **command workflow** — one-shot `/review` comments (maintainers): `/review`
   (router picks agents), `/review all`, `/review correctness security`. Never
   changes configuration.
-- **auto workflow** — continuous review, configured by **labels**: `ai-review`
-  (router), `ai-review:all`, `ai-review:<agent>` (e.g. `ai-review:security`;
-  combine to widen), `ai-review:skip` (opt-out).
+- **auto workflow** — continuous review. **Which PRs get reviewed is set in
+  `config.jsonc` → `review.trigger`**: `"all"` (default) reviews every PR except
+  those labeled `ai-review:skip`; `"label"` reviews only PRs labeled `ai-review`
+  (or `ai-review:<agent>` to scope agents). `ecr ci` self-gates on this policy;
+  the workflow's `if:` is an optional coarse gate layered on top. `ai-review:skip`
+  always wins and is write-gated, so a contributor can't opt their own PR out.
 - **dismiss workflow** — `/dismiss <id> [… -- reason]` / `/undismiss <id>`
   (maintainers). Each finding shows a short `` `id:…` ``. Dismissal is a **display
   filter only** — the reviewer still analyzes everything, and a `critical`/`secrets`
@@ -263,7 +438,9 @@ as the published package via `npx`, so no PR-controlled code is built.
 Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
 inputs, decision, finding count, duration, per-agent cost, and aggregate token
 usage (incl. prompt-cache read/write counts) — for auditing and measuring
-cost/latency/cache reuse over time.
+cost/latency/cache reuse over time. The same totals are printed as a one-line
+summary to the terminal / CI job log at the end of each run, so cache reuse is
+visible even in CI (where the run log is ephemeral).
 
 </details>
 

package/build/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { ciCommand } from './commands/ci.js';
-import { dismissCommand } from './commands/dismiss.js';
-import { doctorCommand } from './commands/doctor.js';
-import { initCommand } from './commands/init.js';
-import { reviewCommand } from './commands/review.js';
+import { ciCommand } from "./commands/ci.js";
+import { dismissCommand } from "./commands/dismiss.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { initCommand } from "./commands/init.js";
+import { reviewCommand } from "./commands/review.js";
+import { verifyConfigCommand } from "./commands/verify-config.js";
 const USAGE = `expo-code-review (ecr) — config-driven AI code reviewer
 
 Usage:
@@ -11,41 +12,47 @@ Usage:
   ecr ci                 Review the current PR and post a comment (GitHub Actions).
   ecr dismiss --pr <n> <id...>     Hide a finding on a PR (see \`ecr dismiss --help\`).
   ecr undismiss --pr <n> <id...>   Restore a dismissed finding.
-  ecr init [--with-workflow] [--force]   Scaffold .expo-code-review/ in this repo.
-  ecr doctor             Check environment, config, and credentials.
+  ecr init [--monorepo] [--scope <dir>]   Scaffold .expo-code-review/ in this repo.
+  ecr doctor [--list-scopes]   Check environment, config, credentials, and scopes.
+  ecr verify-config [--expected <env>] [--json]   Refuse to run if a config could redirect the credential (CI guard).
 
 Agents live in each repo under .expo-code-review/. This CLI is the engine.
+
+Monorepos: .expo-code-review/routing.jsonc routes paths to per-team scopes (see README).
 `;
 async function main() {
     const [, , sub, ...rest] = process.argv;
-    if (sub === '-h' || sub === '--help' || sub === 'help') {
+    if (sub === "-h" || sub === "--help" || sub === "help") {
         process.stdout.write(USAGE);
         return;
     }
     // No subcommand (or a leading flag) defaults to `review`.
-    if (!sub || sub.startsWith('-')) {
+    if (!sub || sub.startsWith("-")) {
         await reviewCommand(process.argv.slice(2));
         return;
     }
     switch (sub) {
-        case 'review':
+        case "review":
             await reviewCommand(rest);
             break;
-        case 'ci':
+        case "ci":
             await ciCommand(rest);
             break;
-        case 'dismiss':
-            await dismissCommand(rest, 'add');
+        case "dismiss":
+            await dismissCommand(rest, "add");
             break;
-        case 'undismiss':
-            await dismissCommand(rest, 'remove');
+        case "undismiss":
+            await dismissCommand(rest, "remove");
             break;
-        case 'init':
+        case "init":
             await initCommand(rest);
             break;
-        case 'doctor':
+        case "doctor":
             await doctorCommand(rest);
             break;
+        case "verify-config":
+            await verifyConfigCommand(rest);
+            break;
         default:
             process.stderr.write(`Unknown command: ${sub}\n\n${USAGE}`);
             process.exitCode = 2;