agent-roast 0.6.0 → 0.8.0

package/README.md

@@ -38,7 +38,7 @@ npx agent-roast check --baseline .agentroast-baseline.json
 npx agent-roast --staged
 
 # Audit pull request diffs (CI gate)
-npx agent-roast --base origin/main --head HEAD --format github
+npx agent-roast review --base origin/main --head HEAD --format github
 
 # Optional historical audit
 npx agent-roast --all --verbose
@@ -106,9 +106,65 @@ 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 with `npx agent-roast@0.6.0 review --base origin/main`. For local development,
+Install 0.8.0: `npx agent-roast@0.8.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.8.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
+one exact finding without switching off the rule or ignoring its whole file:
+
+1. Run `node dist/cli.js check --format json` and inspect the evidence. Findings
+   include a stable `fingerprint` (rule, relative filename and trimmed source snippet).
+2. Add a reviewed `exceptions` entry to the root `.agentroastrc.json`, with the
+   fingerprint, the **total** allowed occurrence count, a reason and an expiry date.
+3. Run the check again. Accepted findings remain visible with their reason/date;
+   additional duplicate occurrences still block. Expired exceptions stop applying.
+   Use a full `check` to revisit old findings; `review` continues gating newly
+   introduced debt, so expiration does not turn unchanged old debt into a new finding.
+
+```json
+{
+  "exceptions": [
+    {
+      "fingerprint": "f4d1212234f00381d0eaed359e3229fe4ff47388affc9eac0d0d89daffea13d6",
+      "count": 1,
+      "reason": "Integration sandbox unavailable; restore under ENG-42",
+      "expires": "2026-11-15"
+    }
+  ]
+}
+```
+
+The example fingerprint is for `it.skip('temporary');` in `auth.test.ts`; copy the
+fingerprint from **your** report. Expiry includes the specified day in UTC. Changing
+the rule, path or source snippet requires review again. Counts from an exception and
+baseline do not add together to accept extra identical occurrences.
+
+For committed/staged context reviews the allowance must already exist in the trusted
+base/HEAD policy. A candidate PR or unstaged config cannot approve itself; first
+commits use built-in defaults. `check` intentionally reads the current root policy.
+Use `--ignore-exceptions` with `check`, `review` or `--staged` to inspect accepted
+findings again. This flag does not disable a separately supplied baseline.
+Exceptions apply to these context/current-source workflows; historical and legacy
+added-line audits do not apply them. A full scan can use baseline adoption for old
+debt, while exceptions record temporary reviewed decisions about particular findings.
+
+JSON/Markdown/terminal reports separate accepted exceptions from actionable findings.
+SARIF retains accepted records with `suppressions` and their justification/expiry;
+JSON and SARIF include stable occurrence identities. SARIF omits code snippets but
+includes exception reasons, so review those before sharing reports.
+
+An offline editor schema is included as `schema.json` in the npm package. When using
+a local dev dependency, set `$schema` to `./node_modules/agent-roast/schema.json`.
+Ignore policies are bounded to 1,000 patterns of at most 1,024 characters each.
+Unknown settings, invalid severities and malformed exceptions fail with exit 2.
+Root policy must be a regular UTF-8 file no larger than 64 KiB. Simple ignore globs
+support `*`, `?`, `**` and directory prefixes; they are not full `.gitignore` syntax.
+
 ### Baseline adoption
 
 A baseline explicitly accepts the findings present at adoption time. It does not fix
@@ -175,7 +231,6 @@ Configure custom ignore paths, rule severities, and CI thresholds with a `.agent
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/Nari-Ab/agent-roast/main/schema.json",
   "ignorePaths": [
     "**/*.min.js",
     "**/vendor/**",
@@ -183,11 +238,10 @@ Configure custom ignore paths, rule severities, and CI thresholds with a `.agent
     "**/fixtures/**"
   ],
   "rules": {
-    "hallucinated-package": "error",
-    "empty-catch": "warn",
+    "test-focus": "error",
+    "swallowed-error": "warn",
     "trivial-assert": "warn",
-    "stub-abandonment": "warn",
-    "mock-leak": "warn"
+    "stub-abandonment": "warn"
   },
   "scoreThreshold": 70
 }
@@ -203,9 +257,25 @@ npx agent-roast --staged
 npx agent-roast init --hook
 ```
 
-`--staged` audits exactly the Git index, including an initial commit without HEAD.
-Unstaged edits and untracked files are excluded. The generated hook uses the locally
-installed CLI (`--no-install`) and blocks on configured error rules instead of scoring
+Since 0.7.0, `--staged` (also `review --staged`) compares the **full source**
+of changed files in HEAD and the Git index. It detects deletion-only empty handlers
+and retains comment context. Existing findings do not block; additional occurrences
+do. Unstaged edits, untracked files and `git add -N` intent-to-add entries are excluded.
+The older 0.6.0 `--staged` command checks only added index lines. Since
+0.8.0, it also reads Git's temporary candidate index during real `commit -a` / `--only`
+hooks. An alternate `GIT_INDEX_FILE` outside this checkout's Git metadata is refused
+with exit 2; it cannot silently redirect the check to a different commit.
+
+Policy comes from HEAD. Staged/unstaged config edits cannot weaken this check and
+are reported; adopt policy changes in a separately reviewed commit. With no HEAD,
+the first commit uses built-in defaults; use `--fail-on` for an explicit override.
+For example: `node dist/cli.js review --staged --fail-on test-skip,test-focus,swallowed-error`.
+Source is pinned by Git blob IDs. If HEAD or the staged inventory changes before the
+scan finishes, it exits 2 and asks for a rerun. The report's `source` is `index`;
+`headSha` is an `INDEX:` snapshot digest, not a commit SHA, and an unborn base is `EMPTY`.
+The JSON schema version for context reviews is now `1.1.0`.
+
+The generated hook uses the locally installed CLI (`--no-install`) and blocks on configured error rules instead of scoring
 old commits. It preserves an existing pre-commit hook.
 
 ### Configure what blocks a change
@@ -216,6 +286,7 @@ Create `.agentroastrc.json` (or run `npx agent-roast init`):
 {
   "rules": {
     "test-skip": "error",
+    "test-focus": "error",
     "trivial-assert": "error",
     "swallowed-error": "warn",
     "type-escape": "off"
@@ -227,7 +298,7 @@ Create `.agentroastrc.json` (or run `npx agent-roast init`):
 ```
 
 `off` removes findings and score penalties; `warn` reports without blocking a diff;
-`error` blocks PR/staged checks. An explicit `failOn` array overrides which enabled
+`error` blocks PR/staged checks, including `test-focus` by default in 0.7.0. An explicit `failOn` array overrides which enabled
 rules block (`[]` makes the audit advisory). CLI `--fail-on` takes precedence over
 that array. History and badge audits honor disabled rules and the panic-loop window.
 History exit status is controlled by `scoreThreshold` or `--fail-under`.
@@ -236,8 +307,10 @@ Configurations generated by older versions may contain unsupported rules such as
 `hallucinated-package`, `empty-catch` or `mock-leak`; remove these entries and use
 `swallowed-error` for empty catches.
 
-Exit codes: `0` passed, `1` blocking findings/score threshold, `2` invalid audit
-configuration or Git refs. `--format json` also works for history audits. A history
+Exit codes: `0` passed, `1` blocking findings/score threshold, `2` invalid configuration,
+Git refs or an incomplete scan. Since 0.8.0, legacy/history CLI audits also return 2
+when lines were skipped or supported source was marked binary by Git attributes,
+instead of treating missing coverage as a clean result. `--format json` also works for history audits. A history
 sample below 200 added lines has no score, but its findings are still shown.
 
 ### GitHub Actions Integration
@@ -264,18 +337,25 @@ jobs:
       - name: Run agent-roast audit
         uses: Nari-Ab/agent-roast@v1
         with:
-          fail-on: test-skip,trivial-assert,stub-abandonment
           format: github
 ```
 
+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.8.0. The CLI equivalent is `--fail-on ''`.
+
 > **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.
 
 ---
 
 ### What it checks
 
-Only **added lines** (`+`) in source code files are scanned — deleted lines, file moves, and comments never trigger false alarms.
+`check` scans current source. `review` scans both full versions of changed source;
+the 0.7.0 `--staged` command does the same for HEAD and index. Legacy
+`--base` and history audits inspect added lines. Comment/literal masking reduces
+noise; these are heuristic checks and can have false positives and missed findings.
 
+- **Focused tests (`test-focus`):** Exclusive `test.only`, `it.only`, `describe.only`, `suite.only`, Playwright `test.describe.only` and common modifier chains in JS/TS-family sources. `fit` / `fdescribe` aliases are recognized in conventional test paths. Supports contiguous multiline chains and ignores literal/comment examples. Default blocking rule; an existing explicit `failOn` list must include it to block. This does not resolve imports or custom aliases; configure your runner's native forbid-only option too when available ([Playwright](https://playwright.dev/docs/api/class-testconfig#test-config-forbid-only), [Jest API](https://jestjs.io/docs/api#testonlyname-fn-timeout)).
 - **Skipped tests (`test-skip`):** `it.skip`, `describe.skip`, `xit`, `pytest.skip`, `test.todo` added to silence failing tests. (Default blocking gate).
 - **Trivial assertions (`trivial-assert`):** Tautological or dummy assertions added to fabricate test green checks (`expect(true).toBe(true)`, `expect(1).toBe(1)`, `assert True`, `self.assertTrue(True)`).
 - **Stub abandonment (`stub-abandonment`):** Dummy stubs left unimplemented in committed code (`throw new Error("Not implemented")`, `raise NotImplementedError`, Rust `todo!()` / `unimplemented!()`).
@@ -308,14 +388,30 @@ Only **added lines** (`+`) in source code files are scanned — deleted lines, f
 Use this as a focused review aid for skipped tests, compiler suppressions and obvious
 stubs, alongside a compiler, test runner and language-aware linter. Findings identify
 patterns, not proof of AI authorship or developer intent. Deliberate skips and abstract
-methods can be legitimate. Contiguous block comments, Python docstrings and multi-line empty handlers are
-recognized. Template interpolation, complex language syntax and context outside
-the added diff are not fully parsed. Panic loops are an observational history heuristic.
+methods can be legitimate. Since 0.8.0, the analyzer improves language-specific checks, multiline skips/assertions,
+Rust raw strings/lifetimes and Java/Kotlin text blocks. Contiguous comments, Python
+docstrings and multiline empty handlers are recognized. Template interpolation, complex language syntax and context outside
+the added diff in legacy audit modes are not fully parsed. Custom test API aliases,
+computed property calls and type/import resolution are not handled. Panic loops are an observational history heuristic.
 The discipline score summarizes added history; it does not certify current code quality.
 `check` reports actionable findings without assigning a personality or quality score.
+History attribution is based on explicit text/identity heuristics; it does not prove
+AI authorship. Since 0.8.0, the analyzer avoids classifying ordinary people by name fragments
+or treating every automation bot as an AI author. Use `--all` for all commits.
+
+The website demos are synthetic illustrations, labeled as such. Older GIF/video
+assets are legacy demonstrations, not performance measurements or adoption evidence.
+See [related tools and design choices](docs/product/related-tools.md) for approaches
+reviewed in Semgrep, Ruff, Gitleaks, reviewdog and eslint-plugin-jest. No third-party
+implementation was copied.
 
 ### Development
 
+Develop/build/test with Node.js 20.19+ (or 22.12+). The distributed CLI still supports
+Node.js 18+. Patched Vitest 4 and build tooling are development dependencies only;
+CI runs the current test runner on Node 22 while CLI subprocesses and actual Git hooks
+are exercised on Node 18/20/22 using `AGENT_ROAST_TEST_NODE`.
+
 ```bash
 npm ci
 npm run typecheck
@@ -323,7 +419,11 @@ npm test
 ```
 
 `npm test` builds the distribution first so CLI integration and bundle checks run
-against current code. Regression tests use disposable Git repositories.
+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.8.0. For local development, use
+`node dist/cli.js --staged` after building.
 
 ### Author & Support