agent-roast 0.10.1 → 0.11.0

package/README.md

@@ -28,6 +28,7 @@ review AI-assisted changes, but it cannot tell who wrote a change, and the measu
 show these moves are not specific to AI.
 
 ```bash
+npx agent-roast replay                           # your last 50 commits, one at a time
 npx agent-roast review --base origin/main        # a pull request
 npx agent-roast --staged                         # what you are about to commit
 ```
@@ -42,7 +43,10 @@ npx agent-roast --staged                         # what you are about to commit
 | `test-skip`, `test-focus`, `trivial-assert`, `swallowed-error`, `type-escape`, `stub-abandonment` | the classic shortcuts, compared before/after so old debt does not block | skip, focus and trivial-assert block |
 
 Renames, moved tests, parametrization, assertions moved into a new helper, and formatter
-rewraps (prettier, black) are recognized and not reported. Intentional cases can be accepted
+rewraps (prettier, black) are recognized and not reported. So is a skip that depends on the
+environment: `test.skip(isMobile, 'reason')` and Playwright's other condition forms,
+`if not has_gpu(): pytest.skip(...)`, and a skip inside a fixture or helper. A skip that names a
+test, stands alone in a test body or depends on `CI` is still reported. Intentional cases can be accepted
 one by one with an expiring, reviewed exception (see below). Policy is read from the base
 branch, so a PR cannot switch the rules off for itself.
 
@@ -52,9 +56,9 @@ Measured, not promised; method, corpus and raw numbers are in
 [docs/benchmarks.md](docs/benchmarks.md). **Short version: weakened checks are rare, usually
 deliberate, and not specific to AI. The tool finds them; a person decides.**
 
-- **Labeled changes** (`benchmarks/cases.mjs`): 40 cheating edits across JS/TS, Python, Go and
-  CI/config files are caught and 33 harmless look-alikes (reformat, rename, move, parametrize,
-  helper extraction, raised thresholds, CI restructuring) stay silent. The cases were written
+- **Labeled changes** (`benchmarks/cases.mjs`): 43 cheating edits across JS/TS, Python, Go and
+  CI/config files are caught and 36 harmless look-alikes (reformat, rename, move, parametrize,
+  helper extraction, raised thresholds, CI restructuring, skips that depend on the environment) stay silent. The cases were written
   together with the detector, so they guard against regressions; they do not prove accuracy.
   Three known gaps are listed in the file and still open: mocking the module under test,
   hardcoding the tested value, and vacuous matchers such as `expect.anything()`.
@@ -99,8 +103,8 @@ It is a **review aid**: it cannot prove who wrote a change or that code is corre
 reads text, not program semantics. A green result is not a quality certificate.
 
 **Want to see what it says about your repository?** [docs/pilot.md](docs/pilot.md) has a
-five-minute look back, an advisory workflow that never fails a pull request, and a feedback form.
-Counts are enough; no code is needed.
+two-minute replay of your last commits, an advisory workflow that never fails a pull request, and a
+feedback form. Counts are enough; no code is needed.
 
 ### Quick start
 
@@ -122,6 +126,22 @@ A finding includes its file and line, the evidence, and a concrete next step.
 important findings (rules that block first, then the before/after rules, then the noisier
 line patterns).
 
+### Replay recent history
+
+```bash
+# Review each of the last 50 commits on its own, as a pull-request check would have seen it
+npx agent-roast replay
+npx agent-roast replay --last 200 --json     # more history, every finding
+npx agent-roast replay --all-rules           # also list line patterns such as `as any`
+```
+
+`replay` answers "what would this have said about our last 50 changes?" before you put it in CI.
+It follows the first-parent history, so a squash, a merge and a direct commit each count as one
+change, reviews each against its parent with the policy at that parent, and lists the commits
+that would have been blocked or drew a warning about a weakened check. It never fails because of a
+finding, and a commit too large to read is reported, not fatal. Line patterns (`type-escape`,
+`swallowed-error`, `stub-abandonment`) are counted and listed only with `--all-rules`.
+
 ### Context review for pull requests
 
 ```bash
@@ -153,7 +173,7 @@ severity but does not enable rules disabled by base policy.
 
 ```bash
 # Advisory pilot: inspect findings before deciding what should block the team
-agent-roast review --base origin/main --fail-on ''
+agent-roast review --base origin/main --advisory
 # Gate the shortcuts the team agrees matter
 agent-roast review --base origin/main --fail-on test-skip,trivial-assert,swallowed-error
 ```
@@ -180,12 +200,12 @@ regressions) may appear in the report/summary rather than as an inline PR annota
 Use a separate SARIF category for introduced-findings review; it does not represent
 a full scan of all outstanding alerts.
 
-Install 0.10.1: `npx agent-roast@0.10.1 review --base origin/main`. For local development,
+Install 0.11.0: `npx agent-roast@0.11.0 review --base origin/main`. For local development,
 run `npm run build` and use `node dist/cli.js`.
 
 ### Precise exceptions (since 0.8.0)
 
-Use `npx agent-roast@0.10.1 check --format json`, or build this checkout with
+Use `npx agent-roast@0.11.0 check --format json`, or build this checkout with
 `npm run build` and run `node dist/cli.js`.
 
 Some skipped integrations or abstract stubs are intentional. In 0.8.0 you can accept
@@ -421,7 +441,9 @@ jobs:
 
 To pilot the Action without blocking on findings, set `advisory: true`. It passes
 an explicit empty fail-on list; invalid configuration, Git errors and incomplete
-scans still fail. The `v1` Action installs 0.10.1. The CLI equivalent is `--fail-on ''`.
+scans still fail. The `v1` Action installs 0.11.0. The CLI equivalent is `--advisory`
+(`--fail-on ''` does the same in POSIX shells, but cmd.exe and Windows PowerShell 5.1 do not pass
+an empty argument through).
 
 > **Security Note:** `agent-roast` runs in an isolated runner directory (`$RUNNER_TEMP`) with `--ignore-scripts` to neutralize malicious `.npmrc` files in untrusted pull requests. `pull_request_target` is not supported.
 
@@ -474,7 +496,10 @@ the added diff in legacy audit modes are not fully parsed. Custom test API alias
 computed property calls and type/import resolution are not handled. Panic loops are an observational history heuristic.
 Test registration options such as Node's `test('name', { skip: true }, fn)` and
 `{ only: true }` are currently not inspected; use explicit `.skip`/`.only` APIs and
-the runner's CI safeguards. Regexp masking is contextual, not a full JavaScript
+the runner's CI safeguards. A skip that depends on the environment (`test.skip(isMobile, 'reason')`,
+`pytest.skip` under an `if`, or in a fixture) is not reported, because such skips are overwhelmingly
+platform or service gates; one that hides a failing test behind a condition is therefore missed unless
+the condition mentions `CI`. Regexp masking is contextual, not a full JavaScript
 parser. Formatting across contiguous lines is supported for casts, empty catches
 and placeholder errors, but legacy added-line audits cannot recover missing hunks.
 The discipline score summarizes added history; it does not certify current code quality.
@@ -509,7 +534,7 @@ node scripts/verify-user-workflows.mjs dist/cli.js
 against current code. Regression tests use disposable Git repositories. The programmatic
 `auditPullRequest({ staged: true })` API retains the legacy added-lines contract;
 use `reviewStagedChanges()` for the new context comparison and `ReviewResult`.
-The composite Action installs exactly 0.10.1. For local development, use
+The composite Action installs exactly 0.11.0. For local development, use
 `node dist/cli.js --staged` after building.
 
 ### Author & Support

package/dist/{chunk-FFKEBW6D.js → chunk-WMHB65AL.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/git.ts
 import { spawn, spawnSync } from "child_process";
@@ -1161,11 +1161,57 @@ function matchIgnorePath(filePath, ignorePatterns) {
 // src/metrics.ts
 var PYTHON_TEST_SKIP_PATTERNS = [
   { regex: /@pytest\s*\.\s*mark\s*\.\s*skip\b/, name: "skipped pytest (@pytest.mark.skip)" },
-  { regex: /(?<![\w.])pytest\s*\.\s*skip\s*\(/, name: "imperative pytest skip (pytest.skip)" },
-  { regex: /@unittest\s*\.\s*skip\s*\(/, name: "skipped unittest (@unittest.skip)" },
-  { regex: /\bself\s*\.\s*skipTest\s*\(/, name: "imperative unittest skip (self.skipTest)" }
+  { regex: /(?<![\w.])pytest\s*\.\s*skip\s*\(/, name: "imperative pytest skip (pytest.skip)", imperative: true },
+  { regex: /@unittest\s*\.\s*skip\s*\(/, name: "skipped unittest (@unittest.skip)", imperative: false },
+  { regex: /\bself\s*\.\s*skipTest\s*\(/, name: "imperative unittest skip (self.skipTest)", imperative: true }
 ];
+function isGuardedSkip(lines) {
+  const indentOf = (text) => text.length - text.trimStart().length;
+  const mentionsCi = (raw) => /\bCI\b|\bGITHUB_ACTIONS\b/.test(raw);
+  const own = lines[lines.length - 1];
+  if (/^\s*(?:if|elif|else)\b.*:\s*\S/.test(own.code)) return !mentionsCi(own.raw);
+  let limit = indentOf(own.code);
+  for (let i = lines.length - 2; i >= 0 && lines.length - 1 - i <= 200; i--) {
+    if (lines[i].number !== lines[i + 1].number - 1) return false;
+    const { code, raw } = lines[i];
+    if (!code.trim() || indentOf(code) >= limit) continue;
+    const keyword = /^\s*(async\s+def|def|class|if|elif|else|try|except|finally|with|for|while)\b/.exec(code)?.[1];
+    if (keyword === "def" || keyword === "async def") return !/^\s*(?:async\s+)?def\s+test/.test(code);
+    if (keyword === "class") return false;
+    if (keyword === "if" || keyword === "elif" || keyword === "else" || keyword === "try" || keyword === "except" || keyword === "finally") return !mentionsCi(raw);
+    limit = indentOf(code) + (keyword ? 0 : 1);
+  }
+  return false;
+}
 var JS_TEST_API = /(?<![\w$.])(?:(?:it|test|describe|suite)(?:\s*\.\s*(?:concurrent|serial|parallel|describe|failing|sequential))*\s*\.\s*(skip|todo|only)|((?:xit|xtest|xdescribe|fit|fdescribe)))\b((?:\s*\.\s*(?:each|failing|concurrent|serial|parallel|sequential))*)\s*(?=\(|\u0001)/g;
+function isConditionalSkip(source, raw, open2) {
+  if (source[open2] !== "(") return false;
+  const args = [];
+  let depth = 0;
+  let start = open2 + 1;
+  for (let i = start; i < source.length && i - open2 <= 2e3; i++) {
+    const char = source[i];
+    if (char === "\0") return false;
+    if ("([{".includes(char)) depth++;
+    else if (")]}".includes(char)) {
+      if (depth) {
+        depth--;
+        continue;
+      }
+      if (char !== ")") return false;
+      args.push(raw.slice(start, i).trim());
+      while (args.length && !args.at(-1)) args.pop();
+      const isString = (arg) => /^(['"`])[\s\S]*\1$/.test(arg);
+      if (!args.length || isString(args[0]) || args[0] === "true") return false;
+      if (args.length > 1 && !isString(args.at(-1))) return false;
+      return !/\bCI\b|\bisCI\b|GITHUB_ACTIONS/.test(args[0]);
+    } else if (char === "," && !depth) {
+      args.push(raw.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  return false;
+}
 var JS_COMMENT_DIRECTIVE_PATTERNS = [
   { regex: /^\s*\/\/\s*@ts-ignore\b/, name: "compiler ignore (@ts-ignore)" },
   { regex: /^\s*\/\/\s*@ts-expect-error\b/, name: "compiler suppression (@ts-expect-error)" },
@@ -1271,6 +1317,7 @@ function auditFileDiffs(files, commitHash = "HEAD", commitDate = (/* @__PURE__ *
       if (python && !isComment) {
         for (const rule of PYTHON_TEST_SKIP_PATTERNS) {
           if (rule.regex.test(cleanedLine)) {
+            if (rule.imperative && isGuardedSkip(maskedLines)) break;
             infractions.push({
               type: "test-skip",
               file: file.path,
@@ -1376,6 +1423,7 @@ function auditFileDiffs(files, commitHash = "HEAD", commitDate = (/* @__PURE__ *
         if (match[2] && !isTestFile(file.path)) continue;
         if (/\bfunction$/.test(source.slice(Math.max(0, previous - 8), previous + 1))) continue;
         if (source[match.index + match[0].length] === "
" && !/\.\s*each\s*$/.test(match[3])) continue;
+        if (match[1] === "skip" && !match[3] && isConditionalSkip(source, raw, match.index + match[0].length)) continue;
         const focus = match[1] === "only" || match[2] === "fit" || match[2] === "fdescribe";
         infractions.push({
           type: focus ? "test-focus" : "test-skip",
@@ -1887,6 +1935,9 @@ var RULE_PRIORITY = {
   "expectation-rewritten": 1,
   "test-removed": 1
 };
+function isCheckRule(type) {
+  return RULE_PRIORITY[type] !== void 0;
+}
 function findingRank(type, failedRules) {
   return failedRules.includes(type) ? -1 : RULE_PRIORITY[type] ?? 2;
 }
@@ -2530,6 +2581,20 @@ async function requireLocalObjects2(cwd, signal) {
     if (!(error instanceof GitError && error.code === 1)) throw error;
   }
 }
+async function unresolvedRefHint(cwd, ref, signal) {
+  try {
+    const count = async (...args) => Number((await readGit(cwd, ["rev-list", "--count", ...args, "HEAD"], signal, 64)).toString().trim());
+    if ((await readGit(cwd, ["rev-parse", "--is-shallow-repository"], signal, 64)).toString().trim() === "true") {
+      return `This clone is shallow (commits available: ${await count()}), so the ref may lie outside it. Run 'git fetch --unshallow' (in GitHub Actions: actions/checkout with fetch-depth: 0) or check the name.`;
+    }
+    const back = /^HEAD~(\d+)$/.exec(ref);
+    const depth = back ? await count("--first-parent") : 0;
+    if (back && Number(back[1]) >= depth) return `HEAD has only ${depth} commit${depth === 1 ? "" : "s"} on its main line${depth > 1 ? `; try HEAD~${depth - 1}` : ""}.`;
+  } catch {
+    assertNotAborted(signal);
+  }
+  return "Check that it names a commit, branch or tag of this repository.";
+}
 async function reviewRefs(cwd, base, head, signal) {
   const resolve2 = async (ref) => {
     if (!ref.trim()) throw new ConfigError("Review refs must not be empty.");
@@ -2537,7 +2602,7 @@ async function reviewRefs(cwd, base, head, signal) {
       return (await readGit(cwd, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`], signal, 1024)).toString().trim();
     } catch (error) {
       assertNotAborted(signal);
-      throw new ConfigError(`Cannot resolve review ref '${ref}'. Use valid commits and fetch complete history (actions/checkout fetch-depth: 0). ${error instanceof Error ? error.message : String(error)}`);
+      throw new ConfigError(`Cannot resolve review ref '${ref}'. ${await unresolvedRefHint(cwd, ref, signal)} ${error instanceof Error ? error.message : String(error)}`);
     }
   };
   await requireLocalObjects2(cwd, signal);
@@ -3374,6 +3439,125 @@ async function compareSourceChanges(options) {
   return result;
 }
 
+// src/replay.ts
+import path7 from "path";
+var MAX_COMMITS = 1e3;
+var CONCURRENCY = 4;
+var LISTED_COMMITS = 15;
+var LISTED_PER_RULE = 2;
+var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function clipEvidence(text, limit = 200) {
+  if (text.length <= limit) return text;
+  const arrow = text.indexOf(" \u2192 ");
+  const clip = (part, size) => part.length > size ? `${part.slice(0, size - 1)}\u2026` : part;
+  if (arrow < 0) return clip(text, limit);
+  const side = Math.floor((limit - 3) / 2);
+  return `${clip(text.slice(0, arrow), side)} \u2192 ${clip(text.slice(arrow + 3), side)}`;
+}
+async function replayHistory(options = {}) {
+  assertNotAborted(options.signal);
+  const cwd = path7.resolve(options.cwd || process.cwd());
+  const last = options.last ?? 50;
+  if (!Number.isInteger(last) || last < 1 || last > MAX_COMMITS) throw new ConfigError(`Replay needs a whole number of commits between 1 and ${MAX_COMMITS}.`);
+  const format = options.format ?? "terminal";
+  if (format !== "terminal" && format !== "json") throw new ConfigError("Replay supports the terminal and json formats.");
+  let log;
+  try {
+    log = (await readGit(cwd, ["log", "--first-parent", "-n", String(last), "--format=%H%x1f%P%x1f%cI%x1f%s"], options.signal)).toString("utf8");
+  } catch (error) {
+    assertNotAborted(options.signal);
+    throw new ConfigError(`Cannot read the commit history. ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const entries = log.split("\n").filter(Boolean).map((line) => {
+    const [sha, parents, date, ...subject] = line.split("");
+    return { sha, base: parents.split(" ")[0], date, subject: subject.join(" ") };
+  });
+  if (!entries.length) throw new ConfigError("The repository has no commits to replay.");
+  const reviewable = entries.filter((entry) => entry.base);
+  const commits = new Array(reviewable.length);
+  let next = 0;
+  let done = 0;
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, reviewable.length) }, async () => {
+    while (next < reviewable.length) {
+      const index = next++;
+      commits[index] = await replayCommit(cwd, reviewable[index], options.signal);
+      options.onProgress?.(++done, reviewable.length);
+    }
+  }));
+  if (commits.length && commits.every((commit) => commit.status === "failed")) throw new ConfigError(`No commit could be reviewed. ${commits[0].error}`);
+  const summary = { commits: commits.length, blocked: 0, warned: 0, noted: 0, clean: 0, untouched: 0, incomplete: 0, failed: 0, findingsByRule: {} };
+  for (const commit of commits) {
+    summary[commit.status]++;
+    for (const finding2 of commit.findings) summary.findingsByRule[finding2.type] = (summary.findingsByRule[finding2.type] ?? 0) + 1;
+  }
+  const shallow = (await readGit(cwd, ["rev-parse", "--is-shallow-repository"], options.signal, 64).catch(() => Buffer.from(""))).toString().trim() === "true";
+  const result = { schemaVersion: "1.0.0", mode: "replay", head: entries[0].sha, requested: last, commitsWithoutParent: entries.length - reviewable.length, shallow, summary, commits, exitCode: 0, output: "" };
+  result.output = format === "json" ? JSON.stringify({ ...result, output: void 0 }, null, 2) : formatReplayTerminal(result, options.allRules);
+  return result;
+}
+async function replayCommit(cwd, entry, signal) {
+  const identity = { sha: entry.sha, date: entry.date, subject: entry.subject };
+  try {
+    const review = await reviewChanges({ cwd, base: entry.base, head: entry.sha, format: "json", signal });
+    const status = review.failedRules.length ? "blocked" : !review.complete ? "incomplete" : review.infractions.some((finding2) => isCheckRule(finding2.type)) ? "warned" : review.infractions.length ? "noted" : review.filesInspected ? "clean" : "untouched";
+    return { ...identity, status, failedRules: review.failedRules, findings: mostImportantFirst(review.infractions, review.failedRules), filesInspected: review.filesInspected, skipped: review.skippedFiles };
+  } catch (error) {
+    assertNotAborted(signal);
+    return { ...identity, status: "failed", failedRules: [], findings: [], filesInspected: 0, skipped: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function formatReplayTerminal(result, allRules = false) {
+  const { summary } = result;
+  const lines = [
+    "",
+    `agent-roast \u2014 replay of the last ${plural(summary.commits, "commit")} (up to ${result.head.slice(0, 7)})`,
+    "  Each commit is reviewed on its own against its parent, as a pull-request check would have seen it."
+  ];
+  const shallowHint = result.shallow ? ["  This clone is shallow, so only the commits it holds were replayed. Run 'git fetch --unshallow' to replay more."] : [];
+  if (!summary.commits) return [...lines, "  There is no earlier commit to compare with, so nothing was reviewed.", ...shallowHint, ""].join("\n");
+  lines.push(...shallowHint);
+  lines.push(
+    `  ${plural(summary.commits - summary.untouched - summary.failed, "commit")} changed source, tests or CI config \xB7 ${summary.untouched} did not`,
+    `  Would have blocked: ${plural(summary.blocked, "commit")} \xB7 warnings on ${summary.warned} \xB7 line patterns only on ${summary.noted} \xB7 nothing to report on ${summary.clean}`
+  );
+  if (summary.incomplete + summary.failed) lines.push(`  Not reviewed in full: ${plural(summary.incomplete + summary.failed, "commit")}`);
+  const listed = result.commits.filter((commit) => commit.status === "blocked" || commit.status === "warned" || allRules && commit.status === "noted");
+  const ordered = [...listed.filter((commit) => commit.status === "blocked"), ...listed.filter((commit) => commit.status !== "blocked")];
+  for (const commit of ordered.slice(0, LISTED_COMMITS)) {
+    lines.push("", `  ${commit.status === "blocked" ? "BLOCK" : "WARN "} ${commit.sha.slice(0, 7)} ${commit.date.slice(0, 10)} ${terminalText(commit.subject).slice(0, 80)}`);
+    const shown = commit.findings.filter((finding2) => allRules || isCheckRule(finding2.type));
+    for (const rule of new Set(shown.map((finding2) => finding2.type))) {
+      const group = shown.filter((finding2) => finding2.type === rule);
+      for (const finding2 of group.slice(0, LISTED_PER_RULE)) {
+        lines.push(
+          `    ${commit.failedRules.includes(rule) ? "FAIL" : "WARN"} [${rule}] ${terminalText(finding2.file || "unknown")}:${finding2.lineNumber}`,
+          `      ${clipEvidence(terminalText(finding2.lineSnippet || finding2.reason))}`
+        );
+      }
+      if (group.length > LISTED_PER_RULE) lines.push(`    \u2026 and ${group.length - LISTED_PER_RULE} more [${rule}] in this commit`);
+    }
+  }
+  if (ordered.length > LISTED_COMMITS) lines.push("", `  \u2026 ${plural(ordered.length - LISTED_COMMITS, "more commit")} with findings; use --json for all of them.`);
+  if (!ordered.length) lines.push("", "  Nothing to report on these commits.");
+  if (!allRules) {
+    const hidden = result.commits.flatMap((commit) => commit.findings.filter((finding2) => !isCheckRule(finding2.type)));
+    if (hidden.length) {
+      const byRule = Object.entries(hidden.reduce((counts, finding2) => ({ ...counts, [finding2.type]: (counts[finding2.type] ?? 0) + 1 }), {})).sort((a, b) => b[1] - a[1]);
+      lines.push("", `  Line patterns not listed: ${plural(hidden.length, "finding")} (${byRule.slice(0, 3).map(([rule, count]) => `${rule} ${count}`).join(", ")}). Add --all-rules to list them.`);
+    }
+  }
+  for (const commit of result.commits.filter((commit2) => commit2.status === "incomplete" || commit2.status === "failed").slice(0, 5)) {
+    lines.push(`  Not reviewed in full: ${commit.sha.slice(0, 7)} ${terminalText(commit.subject).slice(0, 60)} \u2014 ${terminalText(commit.error ?? `${plural(commit.skipped.length, "changed file")} could not be compared`)}`);
+  }
+  lines.push(
+    "",
+    "  Findings are review candidates, not verdicts: `agent-roast explain <rule>` says what a rule means.",
+    "  To run this on every pull request: `agent-roast init --ci`.",
+    ""
+  );
+  return lines.join("\n");
+}
+
 // src/index.ts
 var InvalidDetectorError = class extends Error {
   constructor(message) {
@@ -3382,9 +3566,9 @@ var InvalidDetectorError = class extends Error {
   }
 };
 async function roastRepository(options = {}) {
-  const cwd = path7.resolve(options.cwd || process.cwd());
+  const cwd = path8.resolve(options.cwd || process.cwd());
   const since = options.since || "90 days ago";
-  const repoName = path7.basename(cwd);
+  const repoName = path8.basename(cwd);
   const collector = new MetricsCollector({ all: options.all, ignorePaths: options.ignorePaths, rules: options.rules, panicLoopWindowMinutes: options.panicLoopWindowMinutes });
   const gitStream = streamGitLog(cwd, since);
   await parseGitLogStream(gitStream, (commit, stats) => {
@@ -3399,7 +3583,7 @@ async function roastRepository(options = {}) {
   return { summary, output };
 }
 async function auditPullRequest(options) {
-  const cwd = path7.resolve(options.cwd || process.cwd());
+  const cwd = path8.resolve(options.cwd || process.cwd());
   const format = options.format || "terminal";
   const failOn = (options.failOn || ["test-skip"]).map((s) => s.trim()).filter(Boolean);
   for (const det of failOn) {
@@ -3522,6 +3706,8 @@ export {
   generateShareUrl,
   formatTerminalCard,
   formatPrTerminalCard,
+  isCheckRule,
+  mostImportantFirst,
   formatGithubAnnotations,
   formatGithubStepSummary,
   formatPrMarkdownComment,
@@ -3543,6 +3729,8 @@ export {
   compareFindings,
   reviewChanges,
   reviewStagedChanges,
+  replayHistory,
+  formatReplayTerminal,
   InvalidDetectorError,
   roastRepository,
   auditPullRequest

package/dist/cli.js

@@ -17,12 +17,13 @@ import {
   initProject,
   loadConfig,
   readGit,
+  replayHistory,
   reviewChanges,
   reviewStagedChanges,
   roastRepository,
   terminalText,
   writeBaseline
-} from "./chunk-FFKEBW6D.js";
+} from "./chunk-WMHB65AL.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -32,6 +33,13 @@ import * as path from "path";
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
 var errorMessage = (error) => terminalText(error instanceof Error ? error.message : String(error));
+function failOnOption(options) {
+  if (options.advisory) {
+    if (options.failOn !== void 0) throw new ConfigError("--advisory cannot be combined with --fail-on.");
+    return [];
+  }
+  return options.failOn?.split(",").map((rule) => rule.trim()).filter(Boolean);
+}
 async function runContextReview(repoPath, options, staged) {
   const controller = new AbortController();
   const abort = () => controller.abort();
@@ -40,7 +48,7 @@ async function runContextReview(repoPath, options, staged) {
   try {
     const common = {
       cwd: repoPath,
-      failOn: options.failOn !== void 0 ? options.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
+      failOn: failOnOption(options),
       ignoreExceptions: options.ignoreExceptions,
       format: options.json ? "json" : options.format,
       signal: controller.signal
@@ -71,7 +79,7 @@ removed-count=${result.removedFindings.length}
   }
 }
 var program = new Command();
-program.name("agent-roast").description("Check current code, review changes and audit Git history for coding shortcuts").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Compare full HEAD/index source and gate new staged findings (including the first commit)", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--ignore-exceptions", "Report findings even when accepted by reviewed, unexpired exceptions", false).option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action(async (repoPath, options) => {
+program.name("agent-roast").description("Check current code, review changes and audit Git history for coding shortcuts").version(pkg.version || "0.4.0").argument("[path]", "Path to git repository (default: current directory)", ".").option("-a, --all", "Audit ALL commits regardless of AI attribution tags", false).option("-s, --since <time>", "Time window for git analysis", "90 days ago").option("-v, --verbose", "Show commit SHAs and line snippets for all infractions", false).option("--json", "Output results as raw JSON", false).option("--staged", "Compare full HEAD/index source and gate new staged findings (including the first commit)", false).option("--base <ref>", "Base git ref/branch for PR mode audit (e.g. origin/main)").option("--head <ref>", "Head git ref/SHA for PR mode audit (default: HEAD)", "HEAD").option("--ignore-exceptions", "Report findings even when accepted by reviewed, unexpired exceptions", false).option("--fail-on <rules>", "Comma-separated detectors that trigger CI failure").option("--advisory", "Report findings without failing the run, the same as an empty --fail-on (setup errors and incomplete scans still fail)", false).option("--fail-under <score>", "Fail CI if agent score is below threshold (0-100)").option("--format <format>", "Output format: terminal, json, github, markdown (check/review also support sarif)", "terminal").option("--authors", "Display author names and emails in report", false).action(async (repoPath, options) => {
   try {
     if (process.env.GITHUB_EVENT_NAME === "pull_request_target") {
       console.warn(
@@ -93,8 +101,8 @@ program.name("agent-roast").description("Check current code, review changes and
     if (options.failUnder !== void 0 && (options.failUnder.trim() === "" || !Number.isFinite(Number(options.failUnder)) || Number(options.failUnder) < 0 || Number(options.failUnder) > 100)) {
       throw new ConfigError("--fail-under must be a number between 0 and 100.");
     }
-    if (!options.base && !options.staged && options.failOn !== void 0) {
-      throw new ConfigError("--fail-on requires --base or --staged.");
+    if (!options.base && !options.staged && (options.failOn !== void 0 || options.advisory)) {
+      throw new ConfigError(`${options.advisory ? "--advisory" : "--fail-on"} requires --base or --staged.`);
     }
     if (!options.base && !options.staged && !options.json && !["terminal", "json"].includes(options.format)) {
       throw new ConfigError("Repository audits support terminal or json format; use --base or --staged for github/markdown.");
@@ -102,7 +110,7 @@ program.name("agent-roast").description("Check current code, review changes and
     const configRoot = gitOutputPath((await readGit(path.resolve(repoPath), ["rev-parse", "--show-toplevel"])).toString("utf8"));
     const config = loadConfig(configRoot);
     if (options.base || options.staged) {
-      const failOnRules = options.failOn !== void 0 ? options.failOn.split(",").map((s) => s.trim()).filter(Boolean) : config.failOn;
+      const failOnRules = failOnOption(options) ?? config.failOn;
       const chosenFormat = options.json ? "json" : options.format || "terminal";
       const prResult = await auditPullRequest({
         cwd: repoPath,
@@ -176,7 +184,7 @@ has-supported-changes=${prResult.hasSupportedChanges}
     }
   }
 });
-program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD), or use --staged for HEAD/index\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExample: agent-roast review --base origin/main --format markdown").action(async (repoPath) => {
+program.command("review").description("Compare full changed source at merge-base and head; gate only new findings").argument("[path]", "Path to the Git repository", ".").addHelpText("after", "\nRequired: --base <trusted-ref>  Optional: --head <ref> (default HEAD), or use --staged for HEAD/index\nOutput: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>, --advisory\nExamples:\n  agent-roast review --base origin/main --format markdown\n  agent-roast review --base HEAD~50 --advisory").action(async (repoPath) => {
   try {
     const options = program.opts();
     if (options.staged ? options.base || program.getOptionValueSource("head") === "cli" : !options.base) {
@@ -191,7 +199,41 @@ program.command("review").description("Compare full changed source at merge-base
     process.exitCode = 2;
   }
 });
-program.command("check").description("Check current tracked and non-ignored untracked source files").argument("[path]", "Path to a git repository", ".").option("--baseline <file>", "Report only findings not accepted in this baseline").option("--write-baseline <file>", "Save current findings for adoption (refuses to overwrite)").addHelpText("after", "\nOutput options: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>\nExamples:\n  agent-roast check\n  agent-roast check --write-baseline .agentroast-baseline.json\n  agent-roast check --baseline .agentroast-baseline.json --format json").action(async (repoPath, opts) => {
+program.command("replay").description("Review each of the newest commits on its own, to see what a pull-request check would have said").argument("[path]", "Path to the Git repository", ".").option("--last <n>", "How many of the newest commits to review (default 50, at most 1000)").option("--all-rules", "List line-pattern warnings (type-escape, swallowed-error, stub-abandonment) as well", false).addHelpText("after", "\nOutput: --format terminal|json, --json\nExamples:\n  agent-roast replay\n  agent-roast replay --last 200 --json").action(async (repoPath, opts) => {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    const global = program.opts();
+    if (global.base || global.staged || global.failOn !== void 0 || global.advisory || global.failUnder !== void 0 || global.all || global.ignoreExceptions || program.getOptionValueSource("head") === "cli" || program.getOptionValueSource("since") === "cli") {
+      throw new ConfigError("replay reviews each commit on its own; --base, --head, --staged, --fail-on, --advisory, --fail-under, --all, --since and --ignore-exceptions do not apply.");
+    }
+    const format = global.json ? "json" : global.format;
+    if (format !== "terminal" && format !== "json") throw new ConfigError("replay supports --format terminal or json.");
+    const last = opts.last === void 0 ? 50 : Number(opts.last);
+    if (!/^\d+$/.test(opts.last ?? "50") || last < 1 || last > 1e3) throw new ConfigError("--last must be a whole number between 1 and 1000.");
+    const progress = process.stderr.isTTY && format === "terminal";
+    const result = await replayHistory({
+      cwd: repoPath,
+      last,
+      allRules: opts.allRules,
+      format,
+      signal: controller.signal,
+      onProgress: progress ? (done, total) => process.stderr.write(`\r  reviewed ${done}/${total} commits`) : void 0
+    });
+    if (progress) process.stderr.write("\r\x1B[K");
+    console.log(result.output);
+    process.exitCode = result.exitCode;
+  } catch (error) {
+    console.error(`agent-roast replay error: ${errorMessage(error)}`);
+    process.exitCode = 2;
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+});
+program.command("check").description("Check current tracked and non-ignored untracked source files").argument("[path]", "Path to a git repository", ".").option("--baseline <file>", "Report only findings not accepted in this baseline").option("--write-baseline <file>", "Save current findings for adoption (refuses to overwrite)").addHelpText("after", "\nOutput options: --format terminal|json|github|markdown|sarif, --json, --fail-on <rules>, --advisory\nExamples:\n  agent-roast check\n  agent-roast check --write-baseline .agentroast-baseline.json\n  agent-roast check --baseline .agentroast-baseline.json --format json").action(async (repoPath, opts) => {
   try {
     const global = program.opts();
     if (global.base || global.staged || global.failUnder !== void 0 || global.all || program.getOptionValueSource("head") === "cli" || program.getOptionValueSource("since") === "cli") {
@@ -202,7 +244,7 @@ program.command("check").description("Check current tracked and non-ignored untr
       cwd: repoPath,
       baseline: opts.baseline,
       ignoreExceptions: global.ignoreExceptions,
-      failOn: global.failOn !== void 0 ? global.failOn.split(",").map((rule) => rule.trim()).filter(Boolean) : void 0,
+      failOn: failOnOption(global),
       format: global.json ? "json" : global.format
     });
     if (opts.writeBaseline) {

package/dist/index.d.ts

@@ -317,6 +317,15 @@ declare function formatTerminalCard(summary: MetricSummary, options: {
     verbose?: boolean;
 }): string;
 declare function formatPrTerminalCard(result: PrAuditResult): string;
+/** Rules about the checks themselves (tests, assertions, quality gates), as opposed to line patterns such as `as any`. */
+declare function isCheckRule(type: string): boolean;
+/**
+ * Puts the findings that matter first, so a long list of warnings cannot push them below a
+ * display cap. The order inside each rank is unchanged.
+ */
+declare function mostImportantFirst<T extends {
+    type: string;
+}>(findings: readonly T[], failedRules: readonly string[]): T[];
 declare function formatGithubAnnotations(result: Pick<PrAuditResult, "infractions" | "failedRules">): string;
 /**
  * Generates GitHub Step Summary Markdown
@@ -410,6 +419,55 @@ declare function compareFindings(before: Infraction[], after: Infraction[], newP
 declare function reviewChanges(options: ReviewOptions): Promise<ReviewResult>;
 declare function reviewStagedChanges(options?: StagedReviewOptions): Promise<ReviewResult>;
 
+type ReplayStatus = "blocked" | "warned" | "noted" | "clean" | "untouched" | "incomplete" | "failed";
+interface ReplayCommit {
+    sha: string;
+    date: string;
+    subject: string;
+    /** blocked: a rule that blocks by default fired; warned: a check rule fired without blocking; noted: only line patterns. */
+    status: ReplayStatus;
+    failedRules: string[];
+    findings: Infraction[];
+    filesInspected: number;
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+    error?: string;
+}
+interface ReplayOptions {
+    cwd?: string;
+    /** How many of the newest commits to review (default 50). */
+    last?: number;
+    /** List the line-pattern findings (type-escape, swallowed-error, ...) as well as the check rules. */
+    allRules?: boolean;
+    format?: "terminal" | "json";
+    signal?: AbortSignal;
+    onProgress?: (done: number, total: number) => void;
+}
+interface ReplayResult {
+    schemaVersion: string;
+    mode: "replay";
+    head: string;
+    requested: number;
+    /** Commits without a parent (the first commit, or the edge of a shallow clone) have nothing to compare with. */
+    commitsWithoutParent: number;
+    /** A shallow clone holds only part of the history, so fewer commits than requested may have been replayed. */
+    shallow: boolean;
+    summary: Record<ReplayStatus | "commits", number> & {
+        findingsByRule: Record<string, number>;
+    };
+    commits: ReplayCommit[];
+    exitCode: number;
+    output: string;
+}
+/**
+ * Reviews each of the newest commits of the first-parent history on its own against its parent, which is what a
+ * pull-request check would have seen: one change per squash, merge or direct commit. Reads Git objects only.
+ */
+declare function replayHistory(options?: ReplayOptions): Promise<ReplayResult>;
+declare function formatReplayTerminal(result: ReplayResult, allRules?: boolean): string;
+
 /** Offline SARIF 2.1.0, with relative URIs and explicit incomplete-run status.
  * Snippets are omitted to avoid embedding source code in integration artifacts. */
 declare function formatSarif(report: CheckResult | ReviewResult): string;
@@ -452,4 +510,4 @@ declare function roastRepository(options?: RoastOptions): Promise<{
 }>;
 declare function auditPullRequest(options: PrAuditOptions): Promise<PrAuditResult>;
 
-export { type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, type FindingException, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, MAX_CONFIG_BYTES, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, type StagedReviewOptions, type SuppressedFinding, VALID_DETECTORS, applyBaseline, applyExceptions, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, gitOutputPath, initProject, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, parseDiff, parseGitLogStream, resolveCommitSha, reviewChanges, reviewStagedChanges, roastRepository, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, terminalText, unquoteGitPath, validateExceptions, writeBaseline };
+export { type AgentRoastConfig, type AiAttributionResult, CONFIG_FILENAMES, type CheckOptions, type CheckResult, type CommitInfo, ConfigError, DEFAULT_CONFIG, DEFAULT_CONFIG_TEMPLATE, type DetectorType, FIELD_SEPARATOR, type FindingBaseline, type FindingException, GITHUB_WORKFLOW_TEMPLATE, GitError, GitResolutionError, HERMETIC_GIT_FLAGS, type Infraction, type InitOptions, type InitResult, InvalidDetectorError, MAX_CONFIG_BYTES, type MetricSummary, MetricsCollector, PRE_COMMIT_HOOK_TEMPLATE, type ParseDiffResult, type ParsedCommit, type ParsedDiffLine, type ParsedFileDiff, type PrAuditOptions, type PrAuditResult, RECORD_SEPARATOR, RULE_GUIDES, type ReplayCommit, type ReplayOptions, type ReplayResult, type ReplayStatus, type ReviewFormat, type ReviewOptions, type ReviewResult, type RoastOptions, type RuleGuide, type ShieldsEndpointResponse, type StagedReviewOptions, type SuppressedFinding, VALID_DETECTORS, applyBaseline, applyExceptions, auditFileDiffs, auditPullRequest, checkProject, compareFindings, configFromText, createBaseline, detectAiAttribution, findMergeBase, findingFingerprint, formatCheckMarkdown, formatCheckTerminal, formatGithubAnnotations, formatGithubStepSummary, formatPrMarkdownComment, formatPrTerminalCard, formatReplayTerminal, formatReviewMarkdown, formatReviewTerminal, formatSarif, formatTerminalCard, generateShareUrl, generateShieldsJson, generateShieldsMarkdown, generateSvgBadge, getHermeticGitEnv, getScoreColor, gitOutputPath, initProject, isCheckRule, isCodeFile, isTestFile, loadBaseline, loadConfig, matchIgnorePath, mostImportantFirst, parseDiff, parseGitLogStream, replayHistory, resolveCommitSha, reviewChanges, reviewStagedChanges, roastRepository, streamGitDiff, streamGitLog, stripStringAndRegexLiterals, terminalText, unquoteGitPath, validateExceptions, writeBaseline };

package/dist/index.js

@@ -33,6 +33,7 @@ import {
   formatGithubStepSummary,
   formatPrMarkdownComment,
   formatPrTerminalCard,
+  formatReplayTerminal,
   formatReviewMarkdown,
   formatReviewTerminal,
   formatSarif,
@@ -45,13 +46,16 @@ import {
   getScoreColor,
   gitOutputPath,
   initProject,
+  isCheckRule,
   isCodeFile,
   isTestFile,
   loadBaseline,
   loadConfig,
   matchIgnorePath,
+  mostImportantFirst,
   parseDiff,
   parseGitLogStream,
+  replayHistory,
   resolveCommitSha,
   reviewChanges,
   reviewStagedChanges,
@@ -63,7 +67,7 @@ import {
   unquoteGitPath,
   validateExceptions,
   writeBaseline
-} from "./chunk-FFKEBW6D.js";
+} from "./chunk-WMHB65AL.js";
 export {
   CONFIG_FILENAMES,
   ConfigError,
@@ -98,6 +102,7 @@ export {
   formatGithubStepSummary,
   formatPrMarkdownComment,
   formatPrTerminalCard,
+  formatReplayTerminal,
   formatReviewMarkdown,
   formatReviewTerminal,
   formatSarif,
@@ -110,13 +115,16 @@ export {
   getScoreColor,
   gitOutputPath,
   initProject,
+  isCheckRule,
   isCodeFile,
   isTestFile,
   loadBaseline,
   loadConfig,
   matchIgnorePath,
+  mostImportantFirst,
   parseDiff,
   parseGitLogStream,
+  replayHistory,
   resolveCommitSha,
   reviewChanges,
   reviewStagedChanges,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-roast",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Offline review for AI-assisted changes: catches weakened tests, lowered quality gates, skipped tests and swallowed errors",
   "type": "module",
   "main": "./dist/index.js",