@expo/code-review-cli 0.6.0 → 0.8.0

package/README.md

@@ -70,9 +70,9 @@ excludes) — see [the mixed setup](#other-providers) below. Prefer
 # Review working-tree changes; prints here, posts nothing
 ecr review
 # Review a GitHub PR by number (preview only)
-ecr review --pr 4057
+ecr review --pr 123
 # …and post it as the PR comment
-ecr review --pr 4057 --post
+ecr review --pr 123 --post
 ```
 
 Options (most to least common):
@@ -110,15 +110,18 @@ is a ready example to adapt.
 | `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 setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT sign-in and/or API keys), printing the `export` lines for your shell config. |
+| `ecr setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT/Claude sign-in and/or API keys), printing the `export` lines for your shell config. |
 | `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 [--list-scopes]` | Check environment, config, credentials, and (with a manifest) scopes. |
+| `ecr feedback [--repo <owner/repo>]` | Report which findings PR authors pushed back on, across history. See below. |
 
 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).
+named scopes), `ci --comment single|per-scope` (override the manifest). Both
+`review` and `ci` also take `--context-file <path>` (inject a file's text as
+untrusted external context; see below).
 
 (When developing this repo itself, use `bun run src/cli.ts <command>`.)
 
@@ -138,9 +141,9 @@ your-monorepo/
     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
+  apps/
+    api/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # api team
+    web/.expo-code-review/{config.jsonc(NO auth),coordinator.md,agents/}   # web team
   .github/workflows/expo-code-review.yml   # unchanged shape: one workflow, one `ecr ci`
 ```
 
@@ -157,21 +160,21 @@ your-monorepo/
   "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" }
+    { "name": "default",  "paths": ["**/*"],        "config": "." },
+    { "name": "apps-api", "paths": ["apps/api/**"], "config": "apps/api" },
+    { "name": "apps-web", "paths": ["apps/web/**"], "config": "apps/web" }
   ]
 }
 ```
 
 ```jsonc
-// server/www/.expo-code-review/config.jsonc  (the www team owns this)
+// apps/api/.expo-code-review/config.jsonc  (the api team owns this)
 {
   // NO "auth" block — locked centrally; a tokenEnv here is rejected by loader + CI guard.
   "model": "openai/gpt-5.5",
   "policy": { "includeSuggestions": false },
-  "noise":  { "additionalIgnores": ["server/www/**/__generated__/**"] }
-  // shared.md, coordinator.md, agents/*.md live beside this file — the www team's roster.
+  "noise":  { "additionalIgnores": ["apps/api/**/__generated__/**"] }
+  // shared.md, coordinator.md, agents/*.md live beside this file — the api team's roster.
 }
 ```
 
@@ -245,7 +248,7 @@ your-monorepo/
   security warning and will be removed on a minor boundary.
 
 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`
+(the single authoritative router) and `/apps/api/.expo-code-review/ @your-api-team`
 (each team owns only its own scope dir). Rerouting globs is gated behind infra review.
 
 ---
@@ -486,6 +489,108 @@ as the published package via `npx`, so no PR-controlled code is built.
 
 </details>
 
+<details>
+<summary><b>Author feedback (replies to findings)</b></summary>
+
+A PR author's reply to a finding is matched to it deterministically — by quoting
+the finding's title back, or by citing its short `` `id:…` `` token (only the id can
+clear a finding, see below) — and recorded
+in the comment's embedded state, no model involved in the matching itself. A
+matched finding shows `💬 @login replied` (linked to the comment) and a visible
+count above the fold; the reply's own text is never stored or rendered, only the
+login, the comment link, and (optionally) an enum-valued verdict. Controlled by
+the root-only `feedback` block in `config.jsonc`:
+
+```jsonc
+"feedback": {
+  "mode": "annotate",       // "off" | "annotate" | "adjudicate"
+  "match": "both",          // "quote" | "id" | "both"
+  "dismiss": "never",       // "never" | "maintainers" | "adjudicated"
+  "protectedCategories": ["secrets", "security"],
+  "maxAdjudications": 10    // cap on model calls per run, when mode is "adjudicate"
+}
+```
+
+- **`annotate`** (the default) matches and shows "author replied" with zero effect
+  on the decision — safe and useful even if you never touch this block.
+- **Clearing a finding always needs the `` `id:…` `` token**, in the replier's own words
+  (an id inside a `>` quote does not count). Quoting the title is enough to *annotate*,
+  never to clear: GitHub's "Quote reply" copies the PR author's text verbatim, so a
+  maintainer clicking it would otherwise dismiss a finding on words the author wrote —
+  by accident, or because they were led to.
+- **`adjudicate`** additionally has a model re-check the reply against the actual
+  source (distrust-by-default, like the finding verifier) and record a verdict.
+  Whether that verdict can actually clear a finding is a separate, still-off-by-
+  default choice — `mode` and `dismiss` are independent axes: `dismiss:
+  "maintainers"` lets a maintainer's own reply dismiss with no model involved
+  (it works under plain `annotate` too); `dismiss: "adjudicated"` additionally
+  accepts an author reply the model confirmed (which does need `mode:
+  "adjudicate"` for verdicts to exist). Either way the reply has to cite the finding's
+  `` `id:…` ``. A `critical` finding, or one categorized `secrets`/
+  `security`, can never be cleared this way, whatever the config — that floor is
+  enforced in code, not the prompt.
+- **`/undismiss <id>` wins over a reply.** Running it on a finding a reply cleared
+  puts the finding back in the active list and keeps it there: another reply from
+  the PR author can't clear it again. The restore is recorded against the FINDING
+  in the comment state, not against the reply, so editing or deleting the reply
+  doesn't drop it either. Only a maintainer lifts that — either `/dismiss <id>` on
+  the same finding, or a maintainer's own reply to it.
+
+`ecr feedback` mines this substrate retroactively, with no model call and no
+re-review: it crawls a repo's PRs, reads each one's existing reviewer comment
+(which already embeds its findings), matches non-bot replies against it, and
+reports totals, a reply-rate, breakdowns by category/severity/agent, and — the
+highest-value part — "repeat offenders": findings whose title recurred across 2+
+PRs and drew a reply every single time.
+
+```bash
+ecr feedback --repo your-org/your-repo --limit 100 --since 2026-06-01
+ecr feedback --as my-review-bot   # if CI posts under a PAT/app identity
+ecr feedback --json               # for scripting
+```
+
+The crawl matches the reviewer's comments by author. CI posts them as
+`github-actions[bot]` (the default), so a locally-run crawl uses that identity —
+pass `--as <login>` when your workflow posts under something else.
+
+`ecr feedback` always reads `.expo-code-review/config.jsonc` from the LOCAL
+checkout, even with `--repo`. If `--repo` points at a different repo, it warns
+that `commentTag` may not match, so a zero-findings result there is not read as
+zero pushback. It also warns when every scanned PR had no bot comment at all,
+instead of leaving that as an easy-to-miss "0 with a bot comment" in the totals.
+
+See [LLP 0011](./llp/0011-author-feedback.explainer.md) for why matching is
+deterministic, why reply text is never echoed into the comment, and why the
+defaults are asymmetric.
+
+</details>
+
+<details>
+<summary><b>External context (--context-file)</b></summary>
+
+`ecr review --context-file <path>` and `ecr ci --context-file <path>` inject the
+file's UTF-8 text into the reviewer prompts as an explicitly UNTRUSTED external
+block (the reviewer is told to use it but never follow instructions in it). The
+main use is a CI-provided terraform plan. The text is sanitized like any untrusted
+prose and capped at 24k chars (head 16k + tail 8k, so a big plan keeps both its
+resource list and its `Plan: N to add…` summary); the read itself is bounded at
+1 MiB.
+
+Read errors differ by command on purpose. `ecr review` fails loud (exits 2) on a
+missing or oversized file, since you typed the path. `ecr ci` warns and continues
+with no context, because a CI run must never fail the PR's checks.
+
+### Atlantis terraform plans
+
+`templates/atlantis.yml` is an opt-in workflow (not scaffolded by `ecr init`) that
+runs the reviewer when Atlantis posts a `terraform plan` comment on a PR and feeds
+the plan into the review as `--context-file`. The plan comment body is treated as
+untrusted data throughout. Copy it into `.github/workflows/` and set two repo
+variables: `ATLANTIS_BOT_LOGIN` (the Atlantis bot's comment login, e.g.
+`atlantis-app[bot]`) and optionally `ATLANTIS_PLAN_MARKER`.
+
+</details>
+
 <details>
 <summary><b>Run logs</b></summary>
 
@@ -545,18 +650,36 @@ set in `config.auth` (credentials come from OpenCode):
     One caveat: OpenCode can't price alias models (they're config-declared), so
     pro passes report `$0` in the run log's cost column — token counts are
     correct, and the OpenAI project dashboard is the source of truth for spend.
-- **Anthropic / Claude (API key)** — set `auth.provider` to `"anthropic"`, point
-  `tokenEnv` at the env var holding a Console API key (e.g. `ANTHROPIC_API_KEY`),
-  and use `anthropic/...` model ids; the key is sent as `x-api-key`. Note that
-  Claude Pro/Max **subscription** tokens cannot be used here: Anthropic prohibits
-  them in third-party tools, and OpenCode has no Anthropic OAuth support — only an
-  API key works.
+- **Anthropic / Claude** — use `anthropic/...` model ids and every anthropic pass
+  runs through the **Claude Code CLI** (`claude -p --output-format json`), inferred
+  from the model. The credential is (in order) a `tokenEnv` you name, an ambient
+  `CLAUDE_CODE_OAUTH_TOKEN`, or your local `claude` login — an `auth` entry is
+  entirely optional. Run `claude setup-token` for a Max/Team subscription token
+  (forwarded as `CLAUDE_CODE_OAUTH_TOKEN`) or point `tokenEnv` at an Anthropic
+  Console API key (`sk-ant-api…`, forwarded as `ANTHROPIC_API_KEY`); the CLI reads
+  either. `ecr setup-auth` walks you through it. Each pass is trust-isolated and
+  read-only: it runs with `--safe-mode` (no `CLAUDE.md`/hooks/MCP/plugins),
+  `--strict-mcp-config`, `--permission-mode dontAsk`, and only the
+  `Read`/`Grep`/`Glob` tools — never `Bash`/`Edit`/`Write`/`WebFetch`/`WebSearch`.
+  The child env is an allowlist that omits ambient `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`
+  (only the configured credential is re-injected).
+  ```jsonc
+  // Optional — no anthropic entry at all falls back to your `claude` login.
+  "auth": { "providers": {
+    "anthropic": { "tokenEnv": "CLAUDE_CODE_OAUTH_TOKEN" }
+  } }
+  ```
 - **Another provider** — the current path is the `REVIEWER_MODEL`
   env override: `opencode auth login` once (pick the provider), then run with
   e.g. `REVIEWER_MODEL=google/gemini-3-pro`. It overrides every agent's model
-  and uses your OpenCode login, so no `auth` block is needed. *(Per-agent
-  provider mixing beyond the alias mechanism above is on the
-  [roadmap](./ROADMAP.md).)*
+  and uses your OpenCode login, so no `auth` block is needed.
+
+Engines are inferred **per agent** from that agent's resolved model alone: an
+`anthropic/…` agent runs through the Claude Code CLI while other agents run through
+OpenCode — in the SAME run. So an anthropic model may coexist with an `openai` (or
+any other) OpenCode provider, and each agent's `model` selects its engine.
+`REVIEWER_MODEL` still overrides every agent's model (and therefore every agent's
+engine), converging the whole run onto one engine.
 
 There is no shared fallback key; if a run fails for lack of credentials, authenticate
 a provider in OpenCode. `ecr doctor` diagnoses setup.
@@ -570,8 +693,11 @@ rediscovering one fixable thing, then reports N coverage gaps. So before any pas
   model, with nothing pointing at the credential. A truncated value, surrounding
   whitespace, or a token that can't work for the configured `auth.mode` is rejected
   by name.
-- **Configured model ids are checked against the running server**, so a typo or an id
-  the provider doesn't have is reported once, up front, with the close matches.
+- **Configured model ids for OpenCode-routed providers are checked against the running
+  server**, so a typo or an id the provider doesn't have is reported once, up front,
+  with the close matches. `anthropic/…` (Claude Code) model ids aren't checked up
+  front — Claude validates them per-request, so a typo there surfaces as a per-pass
+  error instead.
 - **`ecr doctor` reports the `opencode` version actually in use** and warns when a
   different one is first on your `PATH` — runs use the version this package pins.
 

package/build/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+// @ref LLP 0007#command-dispatch-and-conventions — argv dispatch only; no execution logic lives here
 import { ciCommand } from "./commands/ci.js";
 import { dismissCommand } from "./commands/dismiss.js";
 import { doctorCommand } from "./commands/doctor.js";
+import { feedbackCommand } from "./commands/feedback.js";
 import { initCommand } from "./commands/init.js";
 import { reviewCommand } from "./commands/review.js";
 import { setupAuthCommand } from "./commands/setup-auth.js";
@@ -13,6 +15,7 @@ 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 feedback [--repo <owner/repo>] [--limit <n>]   Report what humans pushed back on (see \`ecr feedback --help\`).
   ecr init [--monorepo] [--scope <dir>]   Scaffold .expo-code-review/ in this repo.
   ecr setup-auth [--yes]   Walk through getting model credentials for local runs.
   ecr doctor [--list-scopes]   Check environment, config, credentials, and scopes.
@@ -28,6 +31,7 @@ async function main() {
         process.stdout.write(USAGE);
         return;
     }
+    // @ref LLP 0007#command-dispatch-and-conventions [implements] — default-to-review also swallows leading-flag typos; new global flags must not collide with review flags
     // No subcommand (or a leading flag) defaults to `review`.
     if (!sub || sub.startsWith("-")) {
         await reviewCommand(process.argv.slice(2));
@@ -46,6 +50,9 @@ async function main() {
         case "undismiss":
             await dismissCommand(rest, "remove");
             break;
+        case "feedback":
+            await feedbackCommand(rest);
+            break;
         case "init":
             await initCommand(rest);
             break;