@descent-vtt/spec-guard 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,131 @@ All notable changes to this project are documented here. Versions follow
 may change in a minor release — each such change is listed under **Changed**
 with the flag that restores the previous behaviour.
 
+## 0.5.0
+
+Import assertions covered one language, so a dependency rule pointed at a
+directory of Go files did not fail - it passed, having analysed nothing. That is
+the same defect 0.4.0 was written to remove, and this release closes the two
+remaining shapes of it: a rule that cannot read the language, and a rule whose
+scope holds no files at all.
+
+### Added
+
+- **Import assertions read Python, Go, Rust and C#**, alongside JavaScript and
+  TypeScript. `import a.b` / `from .rel import x`, `import ( ... )` groups,
+  `use a::{b, c}` with nested expansion, `using static` and `global using`, and
+  the dynamic forms (`importlib.import_module`) that can only be reported.
+  Not four new tokenizers: the comment and string lexer from ADR-0006 masks the
+  source and the readers work on what is left. Tree-sitter measured 94 MB
+  unpacked against this package's 0.33 MB. See
+  [ADR-0008](docs/adr/0008-polyglot-imports.md).
+- **`baseline` and `ratchet`** on the absence assertions, for adopting a strict
+  rule on a codebase that already breaks it. `baseline="src/legacy/a.ts:2"`
+  names the debt by file and count. The ratchet is two-sided: new violations
+  fail, and so does an entry the code no longer supports, because a baseline
+  that only grows is an `exclude` with extra steps. `ratchet="one-way"` relaxes
+  the second half. See [ADR-0009](docs/adr/0009-debt-baselines.md).
+- **`--print-baseline`** prints the attribute that would exempt today's
+  violations, for a human to paste. It prints; it does not edit. That is the
+  whole answer to `--fix`, and ADR-0009 argues it.
+- **`--format sarif`** writes SARIF 2.1.0, which GitHub turns into an annotation
+  on the offending line. One alert per broken rule, anchored on the code, with
+  the directive as a related location and a fingerprint that survives the code
+  moving. `--json` is unchanged and is now also `--format json`.
+- **`allow-empty` and `--allow-empty-scope`**, for the rules where covering
+  nothing is the honest state of the world.
+- **`baselinedMatches`, `staleBaseline` and `fileMatches`** on each result in
+  `--json`.
+
+### Changed
+
+- **An assertion that inspected no files now fails.** A rule whose scope holds
+  nothing passes every time and reads in the report exactly like a rule that
+  inspected a thousand files and found nothing. The usual causes are a `glob`
+  matching no extension in the tree, an `exclude` that swallowed the target, or
+  an emptied directory. **If a run starts failing this way, the rule was
+  covering nothing before it started failing;** `allow-empty="true"` on the
+  directive, or `--allow-empty-scope` for the run, restores the old behaviour.
+- **An import assertion fails when nothing in scope is in a language it can
+  read**, rather than reporting "analysed 0 of 12 files" in a warning and
+  passing.
+- **`.py`, `.pyi`, `.go`, `.rs`, `.cs` and `.csx` files are now analysed** by import
+  assertions rather than counted as skipped, so a rule over a polyglot tree
+  starts finding dependencies it previously reported as unanalysable.
+- **Mutation testing in CI runs in two tiers**: incremental on branches,
+  a full authoritative sweep on `main` and nightly. The gate stays at 85 in
+  both. See [ADR-0003](docs/adr/0003-mutation-testing.md).
+
+### Fixed
+
+- `excludeFiles` was applied after enumeration rather than during it, so an
+  excluded spec file counted towards a budgeted walk. Only reachable through the
+  adaptive engine's probe, where it could make a tree look larger than the file
+  set actually being searched.
+- The README described the safe-batching apparatus - containment and
+  dovetailing checks before merging literals into a ripgrep alternation - as
+  current behaviour. It was deleted in 0.4.0 when ripgrep became a pre-filter.
+
+## 0.4.0
+
+An audit found spec-guard reporting a clean pass on a repository that contained
+the forbidden symbol. On a tree with eight copies of one token, the scanner
+found two and ripgrep found four, and neither said anything about the rest.
+
+### Changed
+
+- **Hidden directories are searched.** `.github`, `.husky`, `.claude-rules` and
+  `.agents` hold CI, hooks and agent rules, and both engines skipped them
+  entirely - so an absence assertion passed while the forbidden thing sat in a
+  workflow file.
+- **The skip list is now four names**: `.git`, `.hg`, `.svn`, `node_modules`.
+  `dist`, `build`, `out`, `coverage`, `.next` and eight others are searched,
+  because spec-guard cannot tell build output from a directory of build scripts,
+  and guessing wrong means a rule silently covers nothing. **If a run starts
+  failing on your build output, that is this change, and the fix is to say so:**
+
+  ```md
+  <!-- @assert-absence target="." symbol="TODO" exclude="dist coverage" -->
+  ```
+
+- **`.gitignore` is no longer consulted.** It describes what git should carry,
+  not what a rule covers - and ripgrep applies it only inside a git repository,
+  so the same tree gave different answers depending on whether a `.git`
+  directory existed above it.
+- **Binary files are searched, and a match in one is reported** rather than
+  dropped. It is not counted as a violation, but it is no longer invisible.
+  "Binary" now means "contains a NUL byte" for both engines; the scanner used to
+  look only at the first 8KB, which disagreed with ripgrep on files whose first
+  NUL came later.
+- **`--strict` fails when a file could not be inspected**, which now has a
+  precise meaning: unreadable, or binary and containing the symbol.
+- **The engines are one implementation.** ripgrep now answers only *which files
+  contain this text*; the scanner does all counting, comment classification,
+  binary handling and reporting for both. `--engine` changes how long a run
+  takes, not what it concludes. See [ADR-0007](docs/adr/0007-search-scope.md).
+
+### Added
+
+- **`--no-default-skips`** to search even those four directories.
+- **`skipped`** on each result in `--json`: what was not inspected, and why.
+
+### Removed
+
+- `DEFAULT_IGNORED_DIRECTORIES`, `canBatchLiterals`, `shouldBatchPatterns`,
+  `createRipgrepSink` and `byteColumnToCharacter` from the public API. All of
+  them existed to make ripgrep's own counting trustworthy; as a pre-filter it
+  does not count, so pattern batching no longer has to be proved safe and
+  ripgrep's byte columns no longer need converting.
+
+### Fixed
+
+- ripgrep's per-file errors are no longer discarded. `--no-messages` meant a
+  file that could not be opened produced no match, no error, and no way to tell
+  it apart from one that was read and found clean.
+- `comments="include"` no longer changes whether binary files are searched. An
+  attribute about comments decided that, because it selected a different code
+  path through the engine.
+
 ## 0.3.0
 
 ### Added

package/README.md

@@ -199,6 +199,53 @@ an unknown extension, an unterminated literal — the text counts as code, and t
 report says which files it could not classify. A match wrongly kept is a visible
 failure you can argue with; a match wrongly dropped is a lie.
 
+## What gets searched
+
+An assertion is worth exactly as much as the set of files behind it, so
+spec-guard is explicit about that set and never quietly narrows it.
+
+**Four directory names are skipped**, and nothing else:
+
+| Skipped | Why |
+| --- | --- |
+| `.git`, `.hg`, `.svn` | version-control stores hold compressed copies of code you deleted on purpose |
+| `node_modules` | code you did not write, which your architecture rules are not about |
+
+Everything else is searched. That includes **hidden directories** - `.github`,
+`.husky`, `.claude-rules`, `.agents` - because that is where CI, hooks and agent
+rules live, and a rule that cannot see your workflow files is not enforcing much.
+It also includes `dist`, `build`, `out` and `coverage`, because spec-guard
+cannot tell build output from a directory of build scripts, and guessing wrong
+means a rule silently stops covering anything.
+
+`.gitignore` is not consulted. It describes what git should carry, not what a
+rule covers - and ripgrep applies it only inside a git repository, so honouring
+it made the same tree answer differently depending on whether a `.git` directory
+happened to exist above it.
+
+To narrow scope, say so in the assertion:
+
+```md
+<!-- @assert-absence target="src" symbol="TODO" exclude="dist coverage" -->
+```
+
+`--no-default-skips` removes even those four, for a run that has to be certain.
+
+### Nothing is skipped quietly
+
+A file spec-guard could not read, or one whose bytes are not text but which
+contained the symbol anyway, is a gap in the answer rather than a detail of it.
+Those are reported, and `--strict` fails on them:
+
+```text
+✖ docs/adr.md:3  @assert-absence
+    "ApiKey" must not appear in .
+    expected no matches, found 0, and 1 file could not be inspected
+    ⚠ 1 match in 1 binary file not counted: build/app.bin
+```
+
+The counts are in `--json` too, as `skipped` on each result.
+
 ### `@assert-count` - this symbol occurs exactly / at least / at most N times
 
 ```md
@@ -234,10 +281,33 @@ matches a mention in a comment, and it misses `export * from '../db'`.
 <!-- @assert-import-count target="src" module="axios" max="1" -->
 ```
 
-These read the dependency rather than the text. A JavaScript/TypeScript
-tokenizer - comments, strings, template substitutions and regular expressions,
-no parser and no new dependency - extracts module references and counts the
-**files** that depend on the module. It understands:
+These read the dependency rather than the text, in **five languages**:
+
+| Language | Extensions | Reads |
+| --- | --- | --- |
+| JavaScript / TypeScript | `.js .mjs .cjs .jsx .ts .mts .cts .tsx` | `import`, `export ... from`, `require()`, `import()` |
+| Python | `.py .pyi` | `import a.b`, `from .rel import x`, `importlib.import_module("x")` |
+| Go | `.go` | `import "x"` and grouped `import ( ... )`, including aliases and `_` |
+| Rust | `.rs` | `use a::{b, c}` with nested groups, `pub use`, `extern crate` |
+| C# | `.cs .csx` | `using`, `using static`, `global using`, `using X = A.B` |
+
+No parser and no new dependency. JavaScript gets a full tokenizer because a
+module reference can appear anywhere in an expression; the other four are read
+by masking comments and string literals with the classifier from
+[ADR-0006](docs/adr/0006-comment-classification.md) and then reading statements
+off what is left. Tree-sitter would have cost 94 MB unpacked against this
+package's 0.33 MB - [ADR-0008](docs/adr/0008-polyglot-imports.md) has the
+measurements, and the list of things a real parser would genuinely see that
+this does not.
+
+Module patterns are matched against the resolved `/`-separated path *and*
+against the specifier as written, so `module="System.Text.Json"` and
+`module="System/Text/Json"` both work. Matching is case-sensitive, so a rule
+spanning C# and Go needs both conventions:
+`module="app/db/** App/Db/**"`.
+
+The unit counted is **files** that depend on the module. For JavaScript and
+TypeScript it understands:
 
 | Form | Counted |
 | --- | --- |
@@ -249,7 +319,8 @@ no parser and no new dependency - extracts module references and counts the
 | `import(name)`, `require(expr)` | **no - reported, see below** |
 
 Relative specifiers are resolved by path arithmetic, so `module="src/db"`
-matches `../db/client.js` seen from `src/ui/`. There is deliberately no
+matches `../db/client.js` seen from `src/ui/`, and Python's `from ..core import
+x` resolves against the importing file the same way. There is deliberately no
 filesystem resolution: tsconfig `paths` aliases and package `exports` maps are
 not followed, so an alias is written out as itself (`module="@app/db"`).
 
@@ -266,8 +337,9 @@ are reported rather than counted as clean:
 The count is still true of everything that could be seen; the warning is what
 stops it being mistaken for a complete answer. `--strict` turns those warnings
 into failures. Files in scope that are not JavaScript or TypeScript are counted
-and reported too, so a rule pointed at the wrong tree says "analysed 1 of 3
-files" rather than quietly passing.
+and reported too, so a rule pointed at the wrong tree says "analysed 2 of 3
+files" rather than quietly passing - and if *none* of them can be read, the
+assertion fails rather than passing on an empty analysis.
 
 [ADR-0005](docs/adr/0005-import-assertions.md) has the measurements and the
 reasoning behind each boundary.
@@ -298,11 +370,77 @@ Passes when every listed path exists relative to `--root`. Directories count.
 | `comments` | absence, count | `ignore` (default) or `include` for matches inside comments |
 | `module` | import assertions | Which dependency, matched like `exclude` |
 | `types` | import assertions | `include` (default) or `ignore` for `import type` |
+| `allow-empty` | absence, count, import assertions | Tolerate a scope that holds no files. Off by default - see below |
+| `baseline` | absence, import-absence | Known violations that do not count: `path` or `path:count` |
+| `ratchet` | absence, import-absence | `two-sided` (default) or `one-way` - see below |
 | `reason` | all | Human-readable justification, printed on failure |
 
 Unknown attributes are an error, not a shrug: `expct="1"` fails the run instead
 of silently asserting nothing.
 
+### `allow-empty` - an assertion that covers nothing is a failure
+
+```md
+<!-- @assert-absence target="services" symbol="Legacy" glob="*.ts" -->
+```
+
+If `services/` holds no `.ts` file, that rule passes every time, forever,
+without inspecting anything - and in the report it is indistinguishable from a
+rule that inspected a thousand files and found nothing. So it fails instead:
+
+```text
+✖ docs/adr.md:3  @assert-absence
+    "Legacy" must not appear in services
+    no files were inspected, so this assertion verified nothing
+    (add allow-empty="true" if that is expected)
+```
+
+The usual causes are a `glob` matching no extension in the tree, an `exclude`
+that swallowed the target, or a directory somebody emptied. Where covering
+nothing yet is the honest state of the world - a rule written before the code
+it guards - `allow-empty="true"` says so, and `--allow-empty-scope` says it for
+a whole run.
+
+### `baseline` - adopting a rule the codebase already breaks
+
+A strict rule introduced into a mature codebase lands on violations that already
+exist. `exclude` turns those into a permanent blind spot, and `expected="5"`
+cannot tell "one fixed, one added" from "nothing happened". A baseline names
+them:
+
+```md
+<!-- @assert-absence target="src" symbol="LegacyGateway"
+     baseline="src/legacy/gateway.ts:2
+               src/legacy/adapter.ts" -->
+```
+
+The rule now holds when no file outside the list matches and no file inside it
+matches more than it declares. A bare path means one match.
+
+**It ratchets in both directions.** New debt fails, obviously. So does debt that
+has been *paid* and left on the list, because an entry the code no longer
+supports is a spec asserting something untrue:
+
+```text
+    expected no matches, found 0; the baseline is out of date and must be
+    pruned: src/legacy/adapter.ts (no longer matches)
+```
+
+The fix is deleting the line the message names. `ratchet="one-way"` relaxes that
+half to a report-only note. Every run says how many matches the baseline
+excluded, because a pass bought by an exemption is never silent.
+
+To adopt a rule on a codebase that already violates it:
+
+```bash
+spec-guard docs/adr.md --print-baseline
+```
+
+prints the attribute that would exempt exactly today's violations, for you to
+paste in. It prints; it does not edit. [ADR-0009](docs/adr/0009-debt-baselines.md)
+explains why that distinction is the whole design, and why there is no `--fix`
+for architecture rules.
+
 ## CLI
 
 ```bash
@@ -314,14 +452,18 @@ spec-guard [patterns...] [options]
 | `-r, --root <path>` | Codebase root that assertions resolve against (default: cwd) |
 | `-v, --verbose` | Print passing assertions too |
 | `--fail-fast` | Stop at the first failing assertion |
-| `--json` | Machine-readable report on stdout |
+| `--json` | Machine-readable report on stdout (same as `--format json`) |
+| `--format <human\|json\|sarif>` | Output format. `sarif` uploads to GitHub code scanning |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
 | `--strict` | Treat analysis that could not be completed as a failure |
 | `--allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
+| `--allow-empty-scope` | Warn instead of failing when an assertion inspects no files |
+| `--print-baseline` | Print the `baseline="..."` that would exempt today's violations, and exit |
+| `--no-default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
 | `--include-specs` | Also count matches inside the spec files themselves |
 | `--max-snippets <n>` | Failure snippets per assertion (default 5) |
 | `--concurrency <n>` | Search passes in flight at once (default 8) |
-| `--allow-empty` | Exit 0 when no spec file matched the patterns |
+| `--allow-empty` | Exit 0 when no spec file matched the patterns (about the run, not an assertion) |
 | `--color` / `--no-color` | Force colour on or off (`NO_COLOR` honoured) |
 
 Patterns are expanded by spec-guard itself, so quoted globs behave identically
@@ -370,6 +512,35 @@ As a pre-commit hook (assuming a local install, so the bare command resolves):
 npx spec-guard "docs/**/*.md" --fail-fast
 ```
 
+### Annotations on the pull request
+
+`--format sarif` writes a SARIF 2.1.0 document, which GitHub turns into a
+comment on the offending line:
+
+```yaml
+      - run: npx @descent-vtt/spec-guard "docs/**/*.md" --format sarif > spec-guard.sarif || true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: spec-guard.sarif
+          category: spec-guard
+```
+
+That job needs `permissions: security-events: write`. One alert per broken rule
+rather than per match - the thing that broke is the rule - anchored on the first
+offending line, with the directive as a related location because that is often
+where the fix goes. Alerts carry a fingerprint derived from what the assertion
+is about rather than where its matches landed, so inserting a line above a
+violation does not close the alert and open a new one.
+
+**There is no language server, and that is a decision rather than a gap.**
+spec-guard's claims are about a whole repository - "this symbol appears nowhere
+in `src`" - and a language server is handed one buffer at a time. Answering a
+repository-wide question on every keystroke means rescanning the tree on every
+keystroke; the alternative is answering a smaller question and calling it the
+same one. The CLI does a full run of this repository in about 130 ms, so a
+pre-commit hook or a watch loop already closes the feedback gap without a
+daemon, an extension per editor, or a protocol version matrix.
+
 ## How it works
 
 ```text
@@ -392,45 +563,69 @@ parser  ──▶ Directive[] ──▶ runner ──▶ Assertion[] ──▶ e
 
 Scanning a tree costs about the same whether you look for one symbol or twenty,
 so spec-guard groups assertions by target set and flags and answers each group
-in one pass. Measured on Windows 11 / Node 24 / ripgrep 15 against a synthetic
-2,000-file, 5.1 MB tree with 8 assertions:
-
-| | one pass per assertion | batched (current) |
-| --- | --- | --- |
-| ripgrep engine | ~280 ms | **~72 ms** |
-| JavaScript fallback | ~780 ms | **~283 ms** |
+in one pass.
 
 `auto` then picks between the two engines **per search group**, because they
 have different shapes of cost: ripgrep is dominated by process startup and
 barely notices tree size, while the built-in scanner has no startup cost and
 grows linearly. Starting a process to search a handful of files is a bad trade.
+Re-measured for 0.4.0 on Windows 11 / Node 24, median of three, one symbol over
+a synthetic tree:
+
+| files | scanner | ripgrep | |
+| --- | --- | --- | --- |
+| 100 | **17 ms** | 214 ms | scanner, 12.9x |
+| 500 | **70 ms** | 263 ms | scanner, 3.8x |
+| 1,000 | 216 ms | **181 ms** | ripgrep, 1.2x |
+| 3,000 | 735 ms | **222 ms** | ripgrep, 3.3x |
+| 5,000 | 1,046 ms | **241 ms** | ripgrep, 4.3x |
 
 The decision uses a bounded enumeration as its probe: spec-guard walks the
 target set until it either finishes - in which case the file list is already in
 hand and the scanner runs against it, with no process and no second walk - or
-exceeds a budget, in which case ripgrep takes over. Measured end to end:
-
-| | this repo's own specs | 2,000 files |
+exceeds a budget, in which case ripgrep takes over. The crossover above sits
+between 500 and 1,000 files, which is what the Windows budget of 512 encodes;
+on Linux it is far lower, because what is really being measured is process
+spawn cost. `scripts/bench-engines.mjs` reproduces this, and
+[ADR-0004](docs/adr/0004-adaptive-engine.md) has the full tables.
+
+Treat single measurements from one machine with suspicion. On the development
+machine used here, an absence assertion over 2,000 files measures 303 ms with
+the scanner and 399 ms with ripgrep, but ripgrep's own spread across five runs
+was 379-1039 ms - wide enough that the two are not really distinguishable at
+that size. The order-of-magnitude differences at the ends of the table are the
+part worth trusting.
+
+0.5.0 added four language analysers, a scope probe on every assertion and a
+baseline pass, so the obvious question is what that cost. Both versions were run
+against the same synthetic 1,000-file tree, alternating rounds inside one
+process so that this machine's load - which varies by a factor of two over a
+session - falls on both equally:
+
+| | median | min |
 | --- | --- | --- |
-| `--engine rg` | 793.7 ms | 195.8 ms |
-| `--engine js` | 19.5 ms | 330.6 ms |
-| `--engine auto` | **19.1 ms** | **171.9 ms** |
+| 0.4.0 | 908.8 ms | 493.7 ms |
+| 0.5.0 | 913.4 ms | 496.6 ms |
 
-The crossover is ~575 files on Windows and ~25 on Linux, because what is really
-being measured is process spawn cost. `scripts/bench-engines.mjs` reproduces
-both; [ADR-0004](docs/adr/0004-adaptive-engine.md) has the full tables.
+0.5% apart, against a run-to-run spread far wider than that. The two versions
+also returned identical counts for all five assertions, which is the more
+useful half of the result.
 
 Two honest caveats:
 
 - **The reported engine is the one that ran, not the one available.** On a small
   repository `--json` reports `"engine": "javascript"` even with ripgrep
   installed. That is the optimisation working, not a failure to find `rg`.
-- **ripgrep is the reference implementation.** The scanner matches it on
-  everything the test suite covers - counts, snippets, word boundaries, globs,
-  binary skipping, file-size limits - but ripgrep also honours `.gitignore`,
-  while the scanner uses a fixed ignore list (`node_modules`, `dist`, `build`,
-  `coverage`, `.git`, dotfiles, and friends). On a repository where those differ
-  materially, pin the engine with `--engine rg`.
+- **The engines are one implementation, not two that agree.** This used to say
+  that ripgrep was the reference and the scanner merely matched it "on
+  everything the test suite covers", with a note that the two treated
+  `.gitignore` and ignored directories differently and that you should pin an
+  engine if it mattered. It did matter: on a tree with eight copies of a symbol
+  the scanner found two and ripgrep found four. Since 0.4.0 ripgrep answers only
+  *which files contain this text*, and the scanner does all the counting,
+  classification and reporting for both. `--engine` now changes how long a run
+  takes and nothing about its verdict, and the suite asserts that on trees built
+  from every case that used to split them.
 
 ## Programmatic API
 
@@ -490,12 +685,14 @@ process spawn (~27 ms on Windows) on the critical path of every run, including
 runs where ripgrep is missing. Discovering its absence from the first real
 search is free.
 
-**Assertions are batched, but only when provably safe.** Merging literals into
-one ripgrep alternation can lose matches two ways: containment (`Primary` /
-`PrimaryButton`) and dovetailing (`abc` / `cd` in `abcd`). spec-guard checks for
-both and falls back to separate passes when either is possible, and never
-batches regexes or case-insensitive searches. Speed is never traded for a wrong
-count.
+**Assertions that share a target list share one pass over the tree.** This used
+to need a proof: merging literals into a ripgrep alternation can lose matches
+through containment (`Primary` / `PrimaryButton`) and dovetailing (`abc` / `cd`
+in `abcd`), so spec-guard checked for both and fell back to separate passes.
+Since 0.4.0 it does not need the proof, because ripgrep no longer counts
+anything - it answers only *which files contain this text*, and the scanner
+counts each pattern separately over the shared file contents. The batching
+checks were deleted along with the risk they guarded.
 
 **Exit code 2 exists.** "Your specs failed" and "spec-guard could not run" are
 different facts, and CI should be able to tell them apart.
@@ -506,12 +703,42 @@ nothing, and reported success — the exact shape of a green check that verified
 nothing. `--allow-missing-targets` restores the old behaviour for repositories
 where a path is legitimately optional.
 
+**Hidden directories are searched, and `.gitignore` is not consulted.** An
+audit of 0.3.0 found the tool reporting a clean pass on a repository whose
+forbidden symbol sat in `.github/workflows/ci.yml`; the scanner and ripgrep also
+disagreed with each other, finding two matches and four on the same tree. Scope
+is now one policy that both engines are driven by, the skip list is four names
+long, and anything spec-guard could not inspect is reported rather than assumed
+clean ([ADR-0007](docs/adr/0007-search-scope.md)).
+
 **Comments are excluded by default, and the exclusion is reported.** Counting
 the note that records a deletion as an occurrence of the thing deleted punishes
 the documentation this tool exists to keep honest ([ADR-0006](docs/adr/0006-comment-classification.md)).
 The reverse risk — a rule that quietly stops checking anything because every
 match now sits in a comment — is why every run says how many matches it dropped.
 
+**An assertion that inspected no files fails.** It is the same defect as a
+missing `target` seen from a different angle: a rule whose scope is empty passes
+forever and reads exactly like a rule that found nothing. Turning this on found
+a vacuous assertion inside this repository's own test suite on the first run.
+`allow-empty="true"` covers the honest case of a rule written before the code it
+guards.
+
+**Four more languages, and no parser.** Import assertions read Python, Go, Rust
+and C# as well as JavaScript. Not by adding four tokenizers - by reusing the
+comment and string lexer that already existed, masking the source with it, and
+reading statements off what is left. Tree-sitter would have been the modern
+answer and costs 94 MB unpacked against this package's 0.33 MB; the four things
+a real parser would genuinely see that this cannot are listed in
+[ADR-0008](docs/adr/0008-polyglot-imports.md) rather than glossed over.
+
+**There is no `--fix`.** Every edit a machine can make to a failing boundary
+assertion is an edit that records the rule no longer holding: widen the bound,
+add an exclusion, append to the baseline, insert an ignore comment. A one-flag
+path from red to green is a bad button for a person and a much worse one for an
+agent whose loop terminates on a green build. `--print-baseline` prints what you
+could paste; it does not paste it ([ADR-0009](docs/adr/0009-debt-baselines.md)).
+
 ## spec-guard checks itself
 
 The invariants in [`docs/adr/0001-invariants.md`](docs/adr/0001-invariants.md)
@@ -532,7 +759,7 @@ npm install
 npm run build      # tsc -> dist/
 npm test           # vitest
 npm run test:coverage
-npm run test:mutation  # stryker (~16 min in CI; much slower locally)
+npm run test:mutation  # stryker (~16 min in CI; over two hours locally)
 npm run lint       # tsc --noEmit
 npm run selfcheck  # run spec-guard on its own docs
 ```
@@ -546,8 +773,8 @@ prebuilt binary and is never a runtime dependency.
 ### Mutation testing
 
 Coverage says a line ran. It does not say an assertion would notice if the line
-behaved differently. This repository measures the difference: **84.63%** of
-2,949 mutants are killed in CI, against high line coverage.
+behaved differently. This repository measures the difference: **87.21%** of
+4,512 mutants are killed in CI, against high line coverage.
 
 That gap is the point. The first run scored 77.23%, and the weakest file was the
 reporter at 65.48% - not because it lacked tests, but because its tests were
@@ -557,17 +784,33 @@ test still passed. Exact whole-output comparison took it to 87.30%. The engine
 and the walker were then rewritten for testability rather than papered over with
 more tests, which is what moved them from 75%/78% to 83%/93%.
 
-`npm run test:mutation` runs it locally and takes about an hour; CI runs it on
-**every push**, gated at 84%. The CI figure is the one
-quoted above, and it is the lower of the two: the same commit scores 88.76% on
-Windows, where three times as many mutants hang and Stryker counts a hang as a
-kill.
-
-Four cautionary tales are in [ADR-0003](docs/adr/0003-mutation-testing.md): a
+CI runs it in **two tiers**, both gated at 85%. Branches and pull requests run
+Stryker incrementally, reusing the verdict for any mutant whose source and
+covering tests are both unchanged. Pushes to `main`, the weekly schedule and
+manual runs do the full sweep, which is the authoritative number and the one
+quoted above; a full sweep is also what publishes the cache the branches start
+from, so an incremental verdict can never be built on another incremental
+verdict.
+
+The full sweep was 6m54s at 2,118 mutants, 15m51s at 3,493, and is 22m11s at
+4,512. That growth is why the tiers exist: a check that gets quietly more
+expensive every release is a check somebody eventually proposes lowering.
+
+Run it locally with `npm run test:mutation` if you like, but do not calibrate
+anything on the result: on the Windows machine this was developed on the same
+suite takes over two hours against 22 minutes hosted, and it scores *higher*,
+because far more mutants hang there and Stryker counts a hang as a kill. Linux
+CI is the measurement.
+
+Six cautionary tales are in [ADR-0003](docs/adr/0003-mutation-testing.md): a
 run whose score was pure fiction because the mutants were never activated, a
 tuning knob that lifted the score six points without adding a test, the platform
-gap above, and the baseline being re-anchored when a tokenizer arrived - along
-with the real bug that chasing the gate uncovered.
+gap above, the baseline being re-anchored when a tokenizer arrived, and a score
+that rose partly because code carrying hard-to-kill mutants was deleted rather
+than because tests improved, and the 0.5.0 sweep that failed the build at 83.77%
+because a suite can be thorough about the thing it was written to test and
+silent about the machinery underneath it - along with the real bug that chasing
+the gate uncovered.
 
 ## Requirements
 

package/dist/cli.d.ts

@@ -17,15 +17,22 @@ export interface CliIO {
     cwd: string;
     isTTY: boolean;
 }
+/** How a finished run is written out. */
+export type OutputFormat = 'human' | 'json' | 'sarif';
 export interface CliOptions {
     patterns: string[];
     root: string;
     verbose: boolean;
     failFast: boolean;
+    format: OutputFormat;
+    /** Kept as its own field so `--json` remains exactly what it always was. */
     json: boolean;
     engine: EnginePreference;
     allowMissingTargets: boolean;
+    defaultSkips: boolean;
     strictTargets: boolean;
+    allowEmptyScope: boolean;
+    printBaseline: boolean;
     includeSpecs: boolean;
     allowEmpty: boolean;
     maxSnippets: number;
@@ -36,7 +43,8 @@ export interface CliOptions {
 }
 export declare class UsageError extends Error {
 }
-export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)\n  -v, --verbose           Print passing assertions too\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n      --strict            Treat analysis that could not be completed as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel (default: 8)\n      --allow-empty       Exit 0 when no spec files matched\n      --color/--no-color  Force colour on or off (NO_COLOR is honoured)\n  -h, --help              Show this help\n      --version           Print the version\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
+export declare function version(): string;
+export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)\n  -v, --verbose           Print passing assertions too\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report (same as --format json)\n      --format <name>     human | json | sarif  (sarif uploads to GitHub code scanning)\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n      --strict            Treat analysis that could not be completed as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --allow-empty-scope Tolerate assertions whose scope holds no files (they fail by default)\n      --print-baseline    Print the baseline=\"...\" that would exempt today's violations, and exit\n      --no-default-skips  Search .git, .hg, .svn and node_modules too\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel (default: 8)\n      --allow-empty       Exit 0 when no spec files matched (about the run, not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR is honoured)\n  -h, --help              Show this help\n      --version           Print the version\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n  An assertion whose scope holds no files fails; add allow-empty=\"true\" to allow it.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
 /** Runs the CLI and resolves to the process exit code. */

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAaxC,eAAO,MAAM,IAAI,otDAkC8D,CAAC;AAgChF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAuG1E;AAYD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,OAAO,IAAI,MAAM,CAShC;AAED,eAAO,MAAM,IAAI,4sEAuC8D,CAAC;AAgChF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CA8H1E;AAYD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2EpH"}