agent-roast 0.7.0 → 0.8.1

package/README.md

@@ -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 0.7.0: `npx agent-roast@0.7.0 review --base origin/main`. For local development,
+Install 0.8.1: `npx agent-roast@0.8.1 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.1 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
@@ -205,7 +261,10 @@ 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 previous released 0.6.0 `--staged` command checks only added index lines.
+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,
@@ -219,6 +278,11 @@ 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.
 
+`init` resolves the repository root even when run from a package/subdirectory, so
+its policy is used by `check` and its workflow can be discovered by GitHub. Outside
+a Git repository, initialization uses the supplied directory. Its output shows the
+actual destination and existing policy/hooks are preserved.
+
 ### Configure what blocks a change
 
 Create `.agentroastrc.json` (or run `npx agent-roast init`):
@@ -248,8 +312,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
@@ -279,6 +345,10 @@ jobs:
           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.1. 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.
 
 ---
@@ -323,26 +393,49 @@ noise; these are heuristic checks and can have false positives and missed findin
 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
+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.
+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
+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.
 `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
 npm test
+
+# Optional end-to-end CLI checks in disposable Git repositories
+node scripts/verify-user-workflows.mjs dist/cli.js
 ```
 
 `npm test` builds the distribution first so CLI integration and bundle checks run
 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.7.0. For local development, use
+The composite Action installs exactly 0.8.1. For local development, use
 `node dist/cli.js --staged` after building.
 
 ### Author & Support