@expo/code-review-cli 0.3.0 → 0.4.0

package/build/commands/ci.js

@@ -1,18 +1,21 @@
-import { readFile } from 'node:fs/promises';
-import { loadReviewConfig } from '../config/load.js';
-import { repoRoot, run } from '../core/exec.js';
-import { errorMessage } from '../core/util.js';
-import { runReview } from '../core/review.js';
-import { GitHubPRSource } from '../sources/github-pr.js';
-import { GitHubReporter } from '../reporters/github.js';
+import { readFile } from "node:fs/promises";
+import { loadAuthFromRoot, loadReviewConfig, loadScopeConfig } from "../config/load.js";
+import { loadRoutingManifest, resolveScopes, scopedCommentTag, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
+import { repoRoot, run } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+import { buildDiffLineIndex } from "../core/render.js";
+import { runReview } from "../core/review.js";
+import { GitHubPRSource } from "../sources/github-pr.js";
+import { memoizeSource } from "../sources/source.js";
+import { GitHubReporter } from "../reporters/github.js";
 /** Resolve the PR number from the Actions event payload or GITHUB_REF. */
 async function resolvePrNumber() {
     const eventPath = process.env.GITHUB_EVENT_PATH;
     if (eventPath) {
         try {
-            const event = JSON.parse(await readFile(eventPath, 'utf8'));
+            const event = JSON.parse(await readFile(eventPath, "utf8"));
             const number = event.pull_request?.number ?? event.issue?.number ?? event.number;
-            if (typeof number === 'number') {
+            if (typeof number === "number") {
                 return number;
             }
         }
@@ -20,7 +23,7 @@ async function resolvePrNumber() {
             // fall through
         }
     }
-    const match = (process.env.GITHUB_REF ?? '').match(/refs\/pull\/(\d+)\//);
+    const match = (process.env.GITHUB_REF ?? "").match(/refs\/pull\/(\d+)\//);
     return match ? Number(match[1]) : null;
 }
 const CI_USAGE = `ecr ci — review the current GitHub PR and post/update one comment.
@@ -29,54 +32,109 @@ For GitHub Actions: reads the PR number + repo from the event/env, gets the diff
 via \`gh pr diff\`, runs the reviewer, and upserts a single PR comment. Comment-only
 and non-blocking (a reviewer failure never fails the PR's checks).
 
+Monorepos: when .expo-code-review/routing.jsonc exists, ci fans out INTERNALLY —
+it assigns each changed file to exactly one scope (last-match-wins) and reviews
+each active scope over only its files, then renders one aggregated comment (or one
+per scope). With no manifest, behavior is unchanged.
+
 Options:
-  --agents <a,b>   Run only these agents (comma-separated ids); default: all
-  --route          Let the router pick relevant agents from the diff
-  -h, --help       Show this help
+  --agents <a,b>       Run only these agents (comma-separated ids); default: all
+  --route              Let the router pick relevant agents from the diff
+  --scopes <a,b>       Limit the fan-out to these named scopes (routing only)
+  --config-dir <dir>   Load the ROOT config.jsonc + routing.jsonc from <dir>
+                       instead of .expo-code-review/ (also ECR_CONFIG_DIR). Scope
+                       subtrees stay repo-root-relative.
+  --comment <mode>     Override manifest comment mode: single | per-scope
+  --force              Manual override: review even if the trigger policy (label
+                       trigger / ai-review:skip) would skip. Break-glass and the
+                       auth lock still apply. A /review comment command implies this.
+  -h, --help           Show this help
 
 Env: GITHUB_REPOSITORY, GITHUB_EVENT_PATH/GITHUB_REF (PR number), GH_TOKEN,
 and model credentials per .expo-code-review/config.jsonc (or REVIEWER_MODEL).
+GITHUB_EVENT_NAME=issue_comment implies --force (a /review comment command).
 `;
 export async function ciCommand(argv = []) {
-    if (argv.includes('-h') || argv.includes('--help')) {
+    if (argv.includes("-h") || argv.includes("--help")) {
         process.stdout.write(CI_USAGE);
         return;
     }
     const agents = parseAgents(argv);
-    const route = argv.includes('--route');
+    const route = argv.includes("--route");
+    const scopesFilter = parseListFlag(argv, "--scopes");
+    const commentOverride = parseCommentMode(argv);
+    // The ROOT config dir escape hatch (mirrors `ecr review`): an explicit
+    // --config-dir wins, else resolveConfigDir falls back to ECR_CONFIG_DIR, else
+    // the default .expo-code-review/. Applies to config.jsonc AND routing.jsonc.
+    let configDir;
+    try {
+        configDir = parseValueFlag(argv, "--config-dir");
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n\n${CI_USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    // A maintainer's explicit `/review` (comment command or --force) is a manual
+    // escape hatch that bypasses the trigger-policy gate only (see passesTriggerGate).
+    const bypassTriggerGate = shouldBypassTriggerGate(argv);
     const root = await repoRoot();
     if (root && root !== process.cwd()) {
         process.chdir(root);
     }
+    const cwd = process.cwd();
     const repo = process.env.GITHUB_REPOSITORY;
     const prNumber = await resolvePrNumber();
     if (!repo || prNumber == null) {
-        process.stderr.write('CI reviewer: could not determine repository or PR number from the environment. Skipping.\n');
+        process.stderr.write("CI reviewer: could not determine repository or PR number from the environment. Skipping.\n");
         return;
     }
-    let config;
+    // A malformed manifest is a loud, non-blocking error (never a silent fallback).
+    let manifest;
     try {
-        config = await loadReviewConfig(process.cwd());
+        manifest = await loadRoutingManifest(cwd, { configDir });
     }
     catch (error) {
-        process.stderr.write(`CI reviewer: ${errorMessage(error)}\n`);
+        process.stderr.write(`CI reviewer: invalid routing.jsonc: ${errorMessage(error)}\n`);
+        return;
+    }
+    if (manifest == null) {
+        await runLegacyCi(repo, prNumber, cwd, agents, route, bypassTriggerGate, configDir);
         return;
     }
-    // Config-driven trigger policy (.expo-code-review/config.jsonc → review): decide
-    // whether this PR should be reviewed at all. Fetch current labels via gh (more
-    // authoritative than the possibly-stale event payload); on failure, default to
-    // reviewing so a label-read hiccup never silently skips a PR.
-    let labels = [];
     try {
-        const { stdout } = await run('gh', ['pr', 'view', String(prNumber), '--repo', repo, '--json', 'labels', '--jq', '.labels[].name'], { cwd: process.cwd() });
-        labels = stdout.split('\n').map(name => name.trim()).filter(Boolean);
+        await runRoutedCi(manifest, repo, prNumber, cwd, agents, route, scopesFilter, commentOverride, bypassTriggerGate, configDir);
     }
     catch (error) {
-        process.stderr.write(`CI reviewer: could not read PR labels (continuing): ${errorMessage(error)}\n`);
+        // Fan-out failures stay non-blocking (single-writer property is the point).
+        process.stderr.write(`CI reviewer: routed run failed (non-blocking): ${errorMessage(error)}\n`);
     }
-    const gate = shouldReview(labels, config.review);
-    if (!gate.review) {
-        process.stderr.write(`CI reviewer: skipping — ${gate.reason}.\n`);
+}
+/**
+ * The pre-routing single-config path. Kept byte-for-byte equivalent so that with no
+ * routing.jsonc the CLI behaves exactly as before (backcompat invariant).
+ */
+async function runLegacyCi(repo, prNumber, cwd, agents, route, bypassTriggerGate, configDir) {
+    let config;
+    try {
+        config = await loadReviewConfig(cwd, { configDir });
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: ${errorMessage(error)}\n`);
+        return;
+    }
+    // Layer-1 auth lock (mirrors doctor): when the workflow pins the expected token
+    // env var name, refuse to run if the config names anything else. The workflow's
+    // bash guard is a text sweep (layer 2) and can't see through JSON escapes; this
+    // check compares the tokenEnv the loader actually honors.
+    const expectedTokenEnv = process.env.ECR_EXPECTED_TOKEN_ENV;
+    if (expectedTokenEnv && config.auth.tokenEnv !== expectedTokenEnv) {
+        process.stderr.write(`CI reviewer: auth.tokenEnv "${config.auth.tokenEnv ?? "(none)"}" != ECR_EXPECTED_TOKEN_ENV "${expectedTokenEnv}"; refusing to run.\n`);
+        return;
+    }
+    // Config-driven trigger policy (.expo-code-review/config.jsonc → review): decide
+    // whether this PR should be reviewed at all (bypassed by a manual /review).
+    if (!passesTriggerGate(await fetchPrLabels(repo, prNumber, cwd), config.review, bypassTriggerGate)) {
         return;
     }
     const reporter = new GitHubReporter({
@@ -84,7 +142,7 @@ export async function ciCommand(argv = []) {
         repo,
         commentTag: config.commentTag,
         breakGlassMarker: config.breakGlassMarker,
-        cwd: process.cwd(),
+        cwd,
     });
     try {
         if (await reporter.checkBreakGlass()) {
@@ -97,12 +155,12 @@ export async function ciCommand(argv = []) {
         process.stderr.write(`CI reviewer: break-glass check failed (continuing): ${errorMessage(error)}\n`);
     }
     try {
-        const review = await runReview(new GitHubPRSource({ prNumber, repo, cwd: process.cwd() }), {
+        const review = await runReview(new GitHubPRSource({ prNumber, repo, cwd }), {
             config,
-            mode: 'ci',
+            mode: "ci",
             agents,
             route,
-            onProgress: message => process.stderr.write(`${message}\n`),
+            onProgress: (message) => process.stderr.write(`${message}\n`),
         });
         await reporter.report(review);
         process.stderr.write(`CI reviewer: posted review (${review.decision}).\n`);
@@ -116,7 +174,7 @@ export async function ciCommand(argv = []) {
         process.stderr.write(`CI reviewer: run failed (non-blocking): ${reason}\n`);
         try {
             await reporter.report({
-                decision: 'approve_with_comments',
+                decision: "approve_with_comments",
                 findings: [],
                 summary: `⚠️ The AI reviewer failed to run, so this change was **not** reviewed:\n\n> ${reason}`,
                 incomplete: [],
@@ -127,6 +185,246 @@ export async function ciCommand(argv = []) {
         }
     }
 }
+/** A scope's non-blocking failure placeholder (same shape as the legacy failure notice). */
+function failureReview(scopeName, reason) {
+    return {
+        decision: "approve_with_comments",
+        findings: [],
+        summary: `⚠️ The AI reviewer failed to run for scope **${scopeName}**, so those changes were **not** reviewed:\n\n> ${reason}`,
+        incomplete: [],
+    };
+}
+/** The routing fan-out: one process, N scopes reviewed sequentially, one render. */
+async function runRoutedCi(manifest, repo, prNumber, cwd, agents, route, scopesFilter, commentOverride, bypassTriggerGate, configDir) {
+    // The root config + manifest follow the override; scope configs stay
+    // repo-root-relative (loadScopeConfig reads <root>/<scope.config>/.expo-code-review).
+    const rootConfig = await loadReviewConfig(cwd, { configDir });
+    // The root/aggregate marker is the ACTUAL root-owned comment tag so the
+    // pre-routing comment and its dismissal state upsert in place, not stranded
+    // under a new marker (risk 8/9). manifest.defaults.commentTag is the
+    // manifest-side default; when it diverges from the root config's tag (e.g. a
+    // repo with a custom root tag adopts routing.jsonc without setting
+    // defaults.commentTag, so Zod defaults it), keep the root config's tag and
+    // warn rather than silently posting under a fresh marker and losing history.
+    const rootTag = rootConfig.commentTag;
+    if (manifest.defaults.commentTag !== rootConfig.commentTag) {
+        process.stderr.write(`CI reviewer: routing.jsonc defaults.commentTag "${manifest.defaults.commentTag}" != root config.jsonc commentTag "${rootConfig.commentTag}"; using the root config's tag so the existing comment and its dismissals carry over. Set defaults.commentTag to match to silence this.\n`);
+    }
+    // Every enforced agent must exist in the ROOT roster (it is the source of truth).
+    const missing = manifest.defaults.enforceAgents.filter((id) => !rootConfig.agents.some((agent) => agent.id === id));
+    if (missing.length > 0) {
+        process.stderr.write(`CI reviewer: defaults.enforceAgents references unknown root agent(s): ${missing.join(", ")}. Skipping.\n`);
+        return;
+    }
+    // Layer-1 auth lock (mirrors doctor): when the workflow pins the expected token
+    // env var name, refuse to run if the HONORED auth (routing.jsonc defaults.auth
+    // when present, else the root config.jsonc) names anything else. The workflow's
+    // bash guard is a text sweep (layer 2) and can't see through JSON escapes; this
+    // check compares the tokenEnv the loader actually honors, so a PR-supplied
+    // defaults.auth can never repoint the forwarded credential.
+    const expectedTokenEnv = process.env.ECR_EXPECTED_TOKEN_ENV;
+    if (expectedTokenEnv) {
+        const honored = loadAuthFromRoot(rootConfig, manifest);
+        if (honored.tokenEnv !== expectedTokenEnv) {
+            process.stderr.write(`CI reviewer: honored auth.tokenEnv "${honored.tokenEnv ?? "(none)"}" != ECR_EXPECTED_TOKEN_ENV "${expectedTokenEnv}"; refusing to run.\n`);
+            return;
+        }
+    }
+    // Trigger policy is central (infra-owned): the ROOT config's `review` block
+    // gates the whole routed run — scope configs never widen or narrow the trigger.
+    // A manual /review bypasses this gate (break-glass + auth lock still apply).
+    if (!passesTriggerGate(await fetchPrLabels(repo, prNumber, cwd), rootConfig.review, bypassTriggerGate)) {
+        return;
+    }
+    const source = memoizeSource(new GitHubPRSource({ prNumber, repo, cwd }));
+    const changed = await source.getChangedFiles();
+    const resolution = resolveScopes(manifest, changed.map((file) => file.path));
+    process.stderr.write("CI reviewer: scope ownership —\n");
+    for (const line of formatOwnerTable(resolution)) {
+        process.stderr.write(`${line}\n`);
+    }
+    for (const overlap of resolution.overlaps) {
+        process.stderr.write(`CI reviewer: ⚠ ${overlap.file} matched ${overlap.matched.join(", ")} → ${overlap.winner} wins\n`);
+    }
+    if (resolution.unmatched.length > 0) {
+        process.stderr.write(`CI reviewer: ⚠ ${resolution.unmatched.length} changed file(s) matched no scope (add a **/* catch-all).\n`);
+    }
+    // Filter to named scopes AFTER resolution, so unmatched/overlaps stay honest.
+    let active = resolution.active;
+    if (scopesFilter) {
+        const known = new Set(manifest.scopes.map((scope) => scope.name));
+        const unknown = scopesFilter.filter((name) => !known.has(name));
+        if (unknown.length > 0) {
+            process.stderr.write(`CI reviewer: unknown scope(s) in --scopes: ${unknown.join(", ")}\n`);
+        }
+        active = active.filter((scope) => scopesFilter.includes(scope.name));
+    }
+    const mode = commentOverride ?? manifest.comment;
+    // Break-glass: ONE check via a reporter on the root marker, before fan-out.
+    const bgReporter = new GitHubReporter({
+        prNumber,
+        repo,
+        commentTag: rootTag,
+        breakGlassMarker: rootConfig.breakGlassMarker,
+        cwd,
+    });
+    try {
+        if (await bgReporter.checkBreakGlass()) {
+            process.stderr.write(`CI reviewer: ${rootConfig.breakGlassMarker} detected; skipping.\n`);
+            await bgReporter.postSkipNote();
+            await source.dispose();
+            return;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: break-glass check failed (continuing): ${errorMessage(error)}\n`);
+    }
+    // Build ONE link context for all scopes (rate-limit hygiene): diff lines from the
+    // already-fetched changed files, base SHA via a single `gh pr view`.
+    const link = {
+        repo,
+        prNumber,
+        diffLines: buildDiffLineIndex(changed.map((file) => ({ path: file.path, patch: file.patch }))),
+    };
+    try {
+        const { stdout } = await run("gh", ["pr", "view", String(prNumber), "--repo", repo, "--json", "baseRefOid"], { cwd });
+        const oid = JSON.parse(stdout).baseRefOid;
+        if (oid) {
+            link.baseSha = oid;
+        }
+    }
+    catch {
+        // leave baseSha unset → out-of-diff findings degrade to plain text
+    }
+    // Divide the passes budget across active scopes (risk 4), floored so a single
+    // scope still gets a workable window (see budget.* in routing.jsonc). Active
+    // scopes run sequentially, so N × perScope is the real wall-clock; when the
+    // floor forces that past the total, keep the floor but warn loudly.
+    const totalMs = manifest.budget.totalPassesMinutes * 60_000;
+    const minMs = manifest.budget.minScopeMinutes * 60_000;
+    const { perScopeMs: budget, overshoot } = scopePassesBudgetMs(totalMs, minMs, active.length);
+    if (overshoot) {
+        const expectedMinutes = Math.round((active.length * budget) / 60_000);
+        process.stderr.write(`CI reviewer: ⚠ ${active.length} scopes × floor = ${expectedMinutes}min exceeds budget.totalPassesMinutes (${manifest.budget.totalPassesMinutes}m); expect longer runs — raise the job timeout or trim scopes.\n`);
+    }
+    const results = [];
+    for (const scope of active) {
+        const scopeDef = manifest.scopes.find((entry) => entry.name === scope.name);
+        const isDefault = scope.configDir === ".";
+        let review;
+        try {
+            const config = await loadScopeConfig(cwd, scopeDef, manifest, rootConfig);
+            review = await runReview(source, {
+                config,
+                mode: "ci",
+                agents,
+                route,
+                includePaths: scope.files,
+                passesBudgetMs: budget,
+                onProgress: (message) => process.stderr.write(`[${scope.name}] ${message}\n`),
+            });
+        }
+        catch (error) {
+            const reason = errorMessage(error);
+            process.stderr.write(`CI reviewer: [${scope.name}] failed (non-blocking): ${reason}\n`);
+            review = failureReview(scope.name, reason);
+        }
+        results.push({ scope: scope.name, isDefault, review });
+    }
+    await source.dispose();
+    const reporterFor = (tag, withLink = false) => new GitHubReporter({
+        prNumber,
+        repo,
+        commentTag: tag,
+        breakGlassMarker: rootConfig.breakGlassMarker,
+        cwd,
+        linkContext: withLink ? link : undefined,
+    });
+    if (mode === "single") {
+        const aggregate = reporterFor(rootTag, true);
+        let finalResults = results;
+        if (scopesFilter) {
+            // A partial run (--scopes) is authoritative ONLY for the named scopes: merge
+            // the other scopes' previous results out of the existing aggregate comment's
+            // state so re-running one scope doesn't silently discard the rest.
+            const prior = (await aggregate.readState())?.scopes ?? [];
+            const byName = new Map(results.map((result) => [result.scope, result]));
+            for (const previous of prior) {
+                if (!scopesFilter.includes(previous.scope) && !byName.has(previous.scope)) {
+                    byName.set(previous.scope, previous);
+                }
+            }
+            // Manifest order; scopes no longer in the manifest drop out.
+            finalResults = manifest.scopes
+                .map((scope) => byName.get(scope.name))
+                .filter((entry) => entry != null);
+        }
+        await aggregate.reportAggregate(finalResults, resolution.unmatched);
+        // Clean up any per-scope comments from a previous per-scope run. A partial run
+        // only ever touches the named scopes' comments.
+        for (const scope of manifest.scopes) {
+            if (scopesFilter && !scopesFilter.includes(scope.name)) {
+                continue;
+            }
+            await reporterFor(scopedCommentTag(rootTag, scope.name)).clear();
+        }
+        process.stderr.write(`CI reviewer: posted aggregate review for ${finalResults.length} scope(s).\n`);
+    }
+    else {
+        for (const scope of manifest.scopes) {
+            // A partial run (--scopes) must never touch the other scopes' live comments
+            // (their reviews and dismissal state stay exactly as posted).
+            if (scopesFilter && !scopesFilter.includes(scope.name)) {
+                continue;
+            }
+            const reporter = reporterFor(scopedCommentTag(rootTag, scope.name), true);
+            const result = results.find((entry) => entry.scope === scope.name);
+            if (result) {
+                await reporter.report(result.review);
+            }
+            else {
+                // A reconciled scope with zero matched files gets its stale comment deleted.
+                await reporter.clear();
+            }
+        }
+        // The default scope posts under its scoped tag too, so clear the bare root-tag
+        // comment once so a single→per-scope switch doesn't strand it. A partial run
+        // (--scopes) skips this mode-switch cleanup: the root-tag comment may hold the
+        // other scopes' aggregate results.
+        if (!scopesFilter) {
+            await reporterFor(rootTag).clear();
+        }
+        process.stderr.write("CI reviewer: posted per-scope reviews.\n");
+    }
+}
+/**
+ * Current PR labels via gh (more authoritative than the possibly-stale event
+ * payload); on failure, returns [] so a label-read hiccup never silently skips a
+ * PR (shouldReview defaults toward reviewing).
+ */
+async function fetchPrLabels(repo, prNumber, cwd) {
+    try {
+        const { stdout } = await run("gh", [
+            "pr",
+            "view",
+            String(prNumber),
+            "--repo",
+            repo,
+            "--json",
+            "labels",
+            "--jq",
+            ".labels[].name",
+        ], { cwd });
+        return stdout
+            .split("\n")
+            .map((name) => name.trim())
+            .filter(Boolean);
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: could not read PR labels (continuing): ${errorMessage(error)}\n`);
+        return [];
+    }
+}
 /**
  * Decide whether a PR should be reviewed, given its labels and the repo's trigger
  * policy. `skipLabel` always wins (write-gated opt-out). In "label" mode a PR must
@@ -138,29 +436,94 @@ export function shouldReview(labels, review) {
     if (labels.includes(review.skipLabel)) {
         return { review: false, reason: `the ${review.skipLabel} label is set` };
     }
-    if (review.trigger === 'label') {
-        const optedIn = labels.some(name => name === review.label || name.startsWith(`${review.label}:`));
+    if (review.trigger === "label") {
+        const optedIn = labels.some((name) => name === review.label || name.startsWith(`${review.label}:`));
         return optedIn
             ? { review: true, reason: `the ${review.label} label is set` }
             : { review: false, reason: `trigger is "label" and no ${review.label} label is set` };
     }
     return { review: true, reason: 'trigger is "all"' };
 }
+/**
+ * Whether an explicit manual invocation should bypass the trigger/skip gate. A
+ * maintainer's `/review` is a manual escape hatch, so it must run even when the PR
+ * carries the skipLabel or the trigger policy would otherwise skip it. Detected via
+ * the `--force` flag OR the GitHub event being a comment command — `issue_comment`
+ * only reaches `ecr ci` through a /review command workflow, never the auto
+ * `pull_request` workflow. Pure (env injected) so it's unit-testable.
+ */
+export function shouldBypassTriggerGate(argv, env = process.env) {
+    return argv.includes("--force") || env.GITHUB_EVENT_NAME === "issue_comment";
+}
+/**
+ * Apply the trigger policy, honoring a manual-override bypass. Returns whether to
+ * proceed. When a bypass overrides a gate that would have skipped, emits a stderr
+ * notice so the override is visible in the job log; a normal (non-bypassed) skip
+ * emits the usual skip line. The bypass affects ONLY this trigger gate —
+ * break-glass and the auth lock are separate and still apply.
+ */
+function passesTriggerGate(labels, review, bypass) {
+    const gate = shouldReview(labels, review);
+    if (gate.review) {
+        return true;
+    }
+    if (bypass) {
+        process.stderr.write(`CI reviewer: manual /review — bypassing trigger policy (${gate.reason}).\n`);
+        return true;
+    }
+    process.stderr.write(`CI reviewer: skipping — ${gate.reason}.\n`);
+    return false;
+}
 /** Parse `--agents a,b,c` from argv (undefined = all agents). */
 function parseAgents(argv) {
-    const index = argv.indexOf('--agents');
+    return parseListFlag(argv, "--agents");
+}
+/** Parse a comma-separated list flag (`--flag a,b`); undefined when absent/empty. */
+function parseListFlag(argv, flag) {
+    const index = argv.indexOf(flag);
     if (index === -1) {
         return undefined;
     }
     const value = argv[index + 1];
     // A missing value, or the next token being another flag (e.g. `--agents --route`),
-    // means no agent list was given — treat as "all" rather than misparsing `--route`
-    // as an agent id. Mirrors review.ts's requireValue.
-    if (!value || value.startsWith('--')) {
+    // means no list was given — treat as "all"/absent rather than misparsing the next
+    // flag as a value. Mirrors review.ts's requireValue.
+    if (!value || value.startsWith("--")) {
         return undefined;
     }
     return value
-        .split(',')
-        .map(id => id.trim())
+        .split(",")
+        .map((id) => id.trim())
         .filter(Boolean);
 }
+/** Parse a single-value flag (`--flag value`); undefined when absent, throws when
+ * present without a value (matching review.ts's requireValue). */
+function parseValueFlag(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+/** Parse `--comment single|per-scope` (undefined = use the manifest's setting). */
+function parseCommentMode(argv) {
+    const index = argv.indexOf("--comment");
+    if (index === -1) {
+        return undefined;
+    }
+    const value = argv[index + 1];
+    if (value === "single" || value === "per-scope") {
+        return value;
+    }
+    // A present-but-invalid mode (e.g. `--comment foo`) would otherwise fall back to
+    // the manifest silently; warn like --scopes does for unknown scope names. A
+    // missing value or a following flag is treated as absent.
+    if (value && !value.startsWith("--")) {
+        process.stderr.write(`CI reviewer: ignoring invalid --comment mode "${value}" (expected single | per-scope)\n`);
+    }
+    return undefined;
+}

package/build/commands/dismiss.js

@@ -1,7 +1,7 @@
-import { loadReviewConfig } from '../config/load.js';
-import { repoRoot, resolveRepo } from '../core/exec.js';
-import { errorMessage } from '../core/util.js';
-import { GitHubReporter } from '../reporters/github.js';
+import { loadReviewConfig } from "../config/load.js";
+import { repoRoot, resolveRepo } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+import { GitHubReporter } from "../reporters/github.js";
 const USAGE = `ecr dismiss / undismiss — hide (or restore) a finding on a PR
 
 Usage:
@@ -17,31 +17,31 @@ function parseArgs(argv) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         switch (arg) {
-            case '--pr':
+            case "--pr":
                 args.pr = Number(argv[++i]);
                 break;
-            case '--repo':
+            case "--repo":
                 args.repo = argv[++i];
                 break;
-            case '--reason':
+            case "--reason":
                 args.reason = argv[++i];
                 break;
-            case '--by':
+            case "--by":
                 args.by = argv[++i];
                 break;
             default:
-                if (arg.startsWith('--')) {
+                if (arg.startsWith("--")) {
                     throw new Error(`Unknown argument: ${arg}`);
                 }
                 // Bare arg = a finding id. Sanitize to the fingerprint alphabet.
-                args.ids.push(arg.replace(/[^a-f0-9]/g, ''));
+                args.ids.push(arg.replace(/[^a-f0-9]/g, ""));
         }
     }
     args.ids = args.ids.filter(Boolean);
     return args;
 }
 export async function dismissCommand(argv, mode) {
-    if (argv.includes('-h') || argv.includes('--help')) {
+    if (argv.includes("-h") || argv.includes("--help")) {
         process.stdout.write(USAGE);
         return;
     }
@@ -55,12 +55,12 @@ export async function dismissCommand(argv, mode) {
         return;
     }
     if (args.pr == null || !Number.isInteger(args.pr) || args.pr <= 0) {
-        process.stderr.write('dismiss: --pr <number> is required.\n');
+        process.stderr.write("dismiss: --pr <number> is required.\n");
         process.exitCode = 2;
         return;
     }
     if (args.ids.length === 0) {
-        process.stderr.write('dismiss: provide at least one finding id.\n');
+        process.stderr.write("dismiss: provide at least one finding id.\n");
         process.exitCode = 2;
         return;
     }
@@ -79,15 +79,15 @@ export async function dismissCommand(argv, mode) {
             breakGlassMarker: config.breakGlassMarker,
             cwd,
         });
-        const result = await reporter.applyDismissal(mode === 'add' ? args.ids : [], mode === 'remove' ? args.ids : [], args.by, args.reason);
-        if (mode === 'add') {
+        const result = await reporter.applyDismissal(mode === "add" ? args.ids : [], mode === "remove" ? args.ids : [], args.by, args.reason);
+        if (mode === "add") {
             process.stderr.write(`Dismissed ${result.matched.length} finding(s) on ${repo}#${args.pr}.\n`);
         }
         else {
             process.stderr.write(`Restored finding(s) on ${repo}#${args.pr}.\n`);
         }
         if (result.unmatched.length > 0) {
-            process.stderr.write(`Unknown id(s) (no matching finding): ${result.unmatched.join(', ')}\n`);
+            process.stderr.write(`Unknown id(s) (no matching finding): ${result.unmatched.join(", ")}\n`);
         }
     }
     catch (error) {