@descent-vtt/spec-guard 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project are documented here. Versions follow
+[semantic versioning](https://semver.org), with the 0.x caveat that behaviour
+may change in a minor release — each such change is listed under **Changed**
+with the flag that restores the previous behaviour.
+
+## 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
+
+- **`exclude` attribute.** Most real rules are "nowhere except one place", not
+  "not here": `exclude="src/config/**"` expresses that in one assertion instead
+  of a hand-maintained list of every directory that is not `src/config`. Follows
+  gitignore semantics — deliberately different from `glob`'s basename matching —
+  and a parity matrix asserts both engines agree.
+- **Import assertions:** `@assert-import-absence` and `@assert-import-count`.
+  "The UI layer must not depend on the database layer" is a dependency claim,
+  not a text claim, and approximating it with a string search fails in both
+  directions. A zero-dependency tokenizer resolves `import`, `export … from`,
+  `import type`, dynamic `import()` with a literal, and `require()`. Module
+  references it cannot resolve statically are reported, never counted as clean.
+  See [ADR-0005](docs/adr/0005-import-assertions.md).
+- **`comments` attribute.** See Changed, below.
+- **`--allow-missing-targets`** to restore the previous handling of a `target`
+  path that does not exist.
+- **`commentMatches` and `unclassifiedFiles`** on every result in `--json`.
+
+### Changed
+
+- **Matches inside comments no longer count**, so the note recording that a
+  symbol was deleted is no longer read as an occurrence of that symbol. This is
+  the defect where documenting a decision defeated the assertion enforcing it.
+  Comment syntax is known for 59 extensions across 9 families; strings are
+  tracked too, since `//` inside a URL is not a comment. Where classification is
+  uncertain the text counts as code, and every run reports how many matches it
+  excluded — a pass caused by comment exclusion is never silent.
+  `comments="include"` restores counting per assertion.
+  See [ADR-0006](docs/adr/0006-comment-classification.md).
+- **A `target` path that does not exist now fails the run** instead of warning
+  and searching what remained. An assertion pointed at a renamed directory used
+  to search nothing, find nothing, and report success. `--allow-missing-targets`
+  restores the old behaviour.
+- **`--strict`** now means "treat analysis that could not be completed as a
+  failure" — it no longer carries the missing-target meaning, which is now the
+  default.
+
+### Fixed
+
+- `search()` on the ripgrep engine was not comment-aware while `searchBatch()`
+  was, so a spec containing exactly one assertion kept its comment matches.
+- The two engines reported different columns for the same match on a line
+  containing non-ASCII text: ripgrep counts bytes, the scanner counts
+  characters, and editors count characters. ripgrep's column is now converted,
+  so a reported location points at the match in both engines.
+- Leftover `*.test.ts` files in scratch fixture directories were collected by
+  Vitest, breaking a run with "no test suite found" because of debris from a
+  previous one.
+
+### Notes
+
+The version in `package.json` was bumped to 0.3.0 during development but never
+published; npm went 0.1.0 -> 0.2.0. Everything above ships together as the
+first published 0.3.0.
+
+## 0.2.0
+
+### Added
+
+- **Adaptive engine selection.** `--engine auto` now measures rather than
+  guesses: a budgeted, stat-only enumeration decides whether a tree is small
+  enough for the JavaScript scanner to beat a ripgrep process spawn. The probe
+  is the work — the enumeration it performs is reused by the scanner, so
+  choosing costs nothing when the scanner wins.
+  See [ADR-0004](docs/adr/0004-adaptive-engine.md).
+- **Mutation testing** with Stryker, wired into CI on every push, plus the tests
+  that closed the gaps it exposed. See [ADR-0003](docs/adr/0003-mutation-testing.md).
+
+### Changed
+
+- Published as `@descent-vtt/spec-guard`. The binary is still plain
+  `spec-guard`.
+
+## 0.1.0
+
+Initial release: `@assert-absence`, `@assert-count` and `@assert-present`,
+written as HTML comments that are invisible in every Markdown renderer. ripgrep
+primary with a pure-JavaScript fallback of identical semantics, safe assertion
+batching, `--json`, and exit code 2 for "spec-guard could not run" as distinct
+from "your specs failed".

package/README.md

@@ -120,6 +120,132 @@ may use double or single quotes, and a bare attribute means `="true"`.
 Fails when the symbol occurs more than `expected` times (default `0`).
 `max="..."` is accepted as a synonym for `expected`.
 
+### `exclude` - everywhere except
+
+Most real rules are "nowhere except one place", not "not here":
+
+```md
+<!-- @assert-absence target="src" symbol="process.env" exclude="src/config/**" -->
+```
+
+That is the rule this README opens with - *no secret is ever read from
+`process.env` outside `src/config`* - written as one assertion instead of a
+hand-maintained list of every directory that is not `src/config`.
+
+`exclude` follows gitignore rules, which are **not** the same as `glob`'s:
+
+| Pattern | Excludes |
+| --- | --- |
+| `tests` | any directory or file named `tests`, at any depth, and everything under it |
+| `src/config` | that directory and everything under it |
+| `src/config/**` | the same, written explicitly |
+| `*.test.ts` | any file with that name shape, at any depth |
+
+The difference is deliberate. `glob="*.ts"` filters files, so basename matching
+is what you want; `exclude="tests"` means the directory, because that is what
+people mean when they write it - and it is what `rg -g '!tests'` does. Both
+engines implement the same rule, and a parity matrix asserts they agree on it.
+
+List attributes accept commas or whitespace, so both of these work:
+
+```md
+<!-- @assert-absence target="src" symbol="TODO" exclude="src/legacy/** tests" -->
+<!-- @assert-absence target="src" symbol="TODO" exclude="src/legacy/**,tests" -->
+```
+
+(A path containing a space therefore cannot be written; there is no quoting
+inside an attribute value.)
+
+### `comments` - the note about a deletion is not the deletion
+
+You delete a symbol and leave the explanation where the next person will look:
+
+```ts
+// LegacyThing was removed in ADR-398; do not reintroduce it.
+```
+
+A plain text search reads that comment as an occurrence, so the assertion that
+keeps the symbol deleted fails on the sentence proving it was deleted. Both
+fixes are bad: delete the note and lose the reason, or delete the rule.
+
+So matches inside comments do not count:
+
+```md
+<!-- comments are ignored by default -->
+<!-- @assert-absence target="src" symbol="LegacyThing" -->
+
+<!-- ...unless you ask for them -->
+<!-- @assert-absence target="src" symbol="Copyright" comments="include" -->
+```
+
+`comments="include"` is right for assertions that really are about text — a
+licence header, or a name that must appear nowhere in the repository at all.
+
+Because this is the one thing that can turn a failing run green without anyone
+touching code, a run that passed this way says so:
+
+```
+⚠ 1 match inside comments was not counted; add comments="include" to count it
+
+1 passed · 7ms
+✔ every spec assertion holds
+```
+
+Comment syntax is known for around 59 extensions across 9 families (JS/TS, C,
+C#, Rust, Go, Python-style `#`, SQL-style `--`, markup, and formats with no
+comments at all). Strings are tracked too, because `//` inside a URL is not a
+comment and reading it as one would hide real code. Where spec-guard is unsure —
+an unknown extension, an unterminated literal — the text counts as code, and the
+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
@@ -132,6 +258,67 @@ Fails when the symbol occurs more than `expected` times (default `0`).
 Requires `expected`, or `min` and/or `max`. `expected` cannot be combined with
 `min`/`max`.
 
+An exact count is the most brittle assertion in the set: a test that merely
+mentions the symbol will break it. spec-guard does not silently skip test files
+for you - an assertion that quietly ignores part of the tree is the failure mode
+this tool exists to prevent - so say what you mean:
+
+```md
+<!-- @assert-count target="src" symbol="UserSessionManager" expected="1" exclude="*.test.ts *.spec.ts" -->
+```
+
+`min="1"` is often the better rule anyway: it says "this exists" without
+breaking every time someone writes a second test.
+
+### `@assert-import-absence` / `@assert-import-count` - dependencies, not text
+
+The rules architecture documents actually contain are usually about
+dependencies, and a text search answers those badly in both directions - it
+matches a mention in a comment, and it misses `export * from '../db'`.
+
+```md
+<!-- @assert-import-absence target="src/ui" module="src/db" reason="the UI talks to services, not storage" -->
+<!-- @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:
+
+| Form | Counted |
+| --- | --- |
+| `import { A } from 'x'`, `import 'x'`, `import * as ns from 'x'` | yes |
+| `import type { A } from 'x'` | yes, unless `types="ignore"` |
+| `export * from 'x'`, `export { A } from 'x'` | yes - a re-export is a dependency, and a barrel file is how layering rules usually get broken |
+| `require('x')` | yes, with a literal argument |
+| `import('x')` | yes, with a literal argument |
+| `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
+filesystem resolution: tsconfig `paths` aliases and package `exports` maps are
+not followed, so an alias is written out as itself (`module="@app/db"`).
+
+**It tells you what it could not see.** Roughly 1% of module references in real
+code are dynamic, and about 0.09% of files defeat the tokenizer outright. Both
+are reported rather than counted as clean:
+
+```text
+✔ docs/adr.md:1  @assert-import-absence "src/db" (0 matches) in src/core
+⚠ 1 module reference could not be resolved statically
+⚠   src/core/plugin.ts:1 import(name)
+```
+
+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.
+
+[ADR-0005](docs/adr/0005-import-assertions.md) has the measurements and the
+reasoning behind each boundary.
+
 ### `@assert-present` - this file exists
 
 ```md
@@ -150,10 +337,14 @@ Passes when every listed path exists relative to `--root`. Directories count.
 | `file` | present | Comma-separated paths that must exist |
 | `expected` | absence, count | Upper bound for absence; exact count for count |
 | `min` / `max` | count (`max` also on absence) | Inclusive bounds |
-| `glob` | absence, count | Comma-separated file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
+| `glob` | absence, count | Include-only file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
+| `exclude` | absence, count | Paths to leave out, gitignore-style: `src/config/**`, `tests`, `*.test.ts` |
 | `regex` | absence, count | Treat `symbol` as a regular expression |
 | `word` | absence, count | Require word boundaries, so `Primary` does not match `PrimaryButton` |
 | `ignore-case` | absence, count | Case-insensitive matching |
+| `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` |
 | `reason` | all | Human-readable justification, printed on failure |
 
 Unknown attributes are an error, not a shrug: `expct="1"` fails the run instead
@@ -172,7 +363,9 @@ spec-guard [patterns...] [options]
 | `--fail-fast` | Stop at the first failing assertion |
 | `--json` | Machine-readable report on stdout |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
-| `--strict` | Treat a `target` that does not exist as a failure, not a warning |
+| `--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 |
+| `--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) |
@@ -247,45 +440,54 @@ 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 |
-| --- | --- | --- |
-| `--engine rg` | 793.7 ms | 195.8 ms |
-| `--engine js` | 19.5 ms | 330.6 ms |
-| `--engine auto` | **19.1 ms** | **171.9 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.
+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.
 
 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
 
@@ -317,7 +519,10 @@ implementation departs from the obvious reading of the brief, here is why.
 "`LegacyGateway` must not appear" contains the string `LegacyGateway`. Without
 this rule, absence assertions would fail on the document asserting them - the
 single most confusing possible first-run experience. `--include-specs` restores
-the naive behaviour.
+the naive behaviour, and counts the prose of your specs; the directives
+themselves stay uncounted, because a directive is an HTML comment and a rule
+whose own text trips it can never be satisfied. `comments="include"` counts even
+those.
 
 **Fenced code and inline code are masked before parsing.** A README documenting
 the syntax must not execute it. Masking preserves byte offsets, so reported line
@@ -352,6 +557,26 @@ count.
 **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.
 
+**A missing `target` fails the run.** It used to warn and search what was left,
+which meant an assertion pointed at a renamed directory searched nothing, found
+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.
+
 ## spec-guard checks itself
 
 The invariants in [`docs/adr/0001-invariants.md`](docs/adr/0001-invariants.md)
@@ -363,7 +588,7 @@ build fails if they stop being true.
 
 This README is executable too:
 
-<!-- @assert-present file="src/parser.ts,src/engine.ts,src/reporter.ts,src/runner.ts,src/cli.ts" -->
+<!-- @assert-present file="src/parser.ts,src/engine.ts,src/reporter.ts,src/runner.ts,src/cli.ts,src/comments.ts" -->
 
 ## Development
 
@@ -372,7 +597,7 @@ npm install
 npm run build      # tsc -> dist/
 npm test           # vitest
 npm run test:coverage
-npm run test:mutation  # stryker (~20 minutes)
+npm run test:mutation  # stryker (~16 min in CI; much slower locally)
 npm run lint       # tsc --noEmit
 npm run selfcheck  # run spec-guard on its own docs
 ```
@@ -386,8 +611,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: **86.40%** of
-2,118 mutants are killed in CI, against 98.98% line coverage.
+behaved differently. This repository measures the difference: **84.63%** of
+2,949 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
@@ -397,16 +622,17 @@ 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 half an hour; CI runs it
-on **every push** in under seven minutes, gated at 85%. The CI figure is the one
+`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.
 
-Three cautionary tales are in [ADR-0003](docs/adr/0003-mutation-testing.md): a
+Four 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, and the
-platform gap above.
+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.
 
 ## Requirements
 

package/dist/cli.d.ts

@@ -24,6 +24,8 @@ export interface CliOptions {
     failFast: boolean;
     json: boolean;
     engine: EnginePreference;
+    allowMissingTargets: boolean;
+    defaultSkips: boolean;
     strictTargets: boolean;
     includeSpecs: boolean;
     allowEmpty: boolean;
@@ -35,7 +37,7 @@ 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 a target path that does not exist as a failure\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\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
+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      --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\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";
 /** 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,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,2+CA8B8D,CAAC;AAuBhF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAmG1E;AAYD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DpH"}
+{"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,YAAY,EAAE,OAAO,CAAC;IACtB,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,2xDAmC8D,CAAC;AAgChF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CA2G1E;AAYD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiEpH"}

package/dist/cli.js

@@ -41,7 +41,10 @@ Options
       --fail-fast         Stop at the first failing assertion
       --json              Emit a machine-readable JSON report
       --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)
-      --strict            Treat a target path that does not exist as a failure
+      --strict            Treat analysis that could not be completed as a failure
+      --allow-missing-targets
+                          Tolerate target paths that do not exist (they fail by default)
+      --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: ${DEFAULT_MAX_SNIPPETS})
       --concurrency <n>   Assertions executed in parallel (default: ${DEFAULT_CONCURRENCY})
@@ -51,10 +54,12 @@ Options
       --version           Print the version
 
 Directives
-  <!-- @assert-absence target="src/" symbol="LegacyGateway" -->
+  <!-- @assert-absence target="src/" symbol="LegacyGateway" exclude="src/legacy/**" -->
   <!-- @assert-count   target="src/" symbol="SessionManager" expected="1" -->
   <!-- @assert-present file="SECURITY.md" -->
 
+  Matches inside comments do not count; add comments="include" to count them.
+
 Exit codes
   0 all assertions passed   1 an assertion failed   2 spec-guard could not run`;
 const ENGINE_ALIASES = {
@@ -65,6 +70,15 @@ const ENGINE_ALIASES = {
     javascript: 'javascript',
     node: 'javascript',
 };
+/**
+ * Takes the next argv element as a value.
+ *
+ * A leading dash means the value was omitted and the next option got swallowed
+ * ("--root --verbose"). That heuristic only applies here: in the `--opt=value`
+ * form there is nothing ambiguous about a leading dash, so "--max-snippets=-1"
+ * should be told it wants a non-negative integer rather than that it is missing
+ * a value.
+ */
 function requireValue(name, value) {
     if (value === undefined || value.startsWith('-')) {
         throw new UsageError(`Option ${name} requires a value.`);
@@ -85,6 +99,8 @@ export function parseArgs(argv, cwd) {
         failFast: false,
         json: false,
         engine: 'auto',
+        allowMissingTargets: false,
+        defaultSkips: true,
         strictTargets: false,
         includeSpecs: false,
         allowEmpty: false,
@@ -109,7 +125,7 @@ export function parseArgs(argv, cwd) {
         const inlineValue = equals === -1 ? undefined : argument.slice(equals + 1);
         const nextValue = () => {
             if (inlineValue !== undefined)
-                return requireValue(name, inlineValue);
+                return inlineValue;
             index += 1;
             return requireValue(name, argv[index]);
         };
@@ -134,6 +150,12 @@ export function parseArgs(argv, cwd) {
             case '--strict':
                 options.strictTargets = true;
                 break;
+            case '--allow-missing-targets':
+                options.allowMissingTargets = true;
+                break;
+            case '--no-default-skips':
+                options.defaultSkips = false;
+                break;
             case '--include-specs':
                 options.includeSpecs = true;
                 break;
@@ -209,6 +231,8 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
             root: options.root,
             engine: options.engine,
             failFast: options.failFast,
+            allowMissingTargets: options.allowMissingTargets,
+            defaultSkips: options.defaultSkips,
             strictTargets: options.strictTargets,
             includeSpecs: options.includeSpecs,
             concurrency: options.concurrency,