@descent-vtt/spec-guard 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# 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.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,85 @@ 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.
+
 ### `@assert-count` - this symbol occurs exactly / at least / at most N times
 
 ```md
@@ -132,6 +211,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 +290,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 +316,8 @@ 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 |
 | `--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) |
@@ -317,7 +462,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 +500,18 @@ 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.
+
+**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 +523,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 +532,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 +546,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 +557,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,7 @@ export interface CliOptions {
     failFast: boolean;
     json: boolean;
     engine: EnginePreference;
+    allowMissingTargets: boolean;
     strictTargets: boolean;
     includeSpecs: boolean;
     allowEmpty: boolean;
@@ -35,7 +36,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      --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,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"}

package/dist/cli.js

@@ -41,7 +41,9 @@ 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)
       --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 +53,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 +69,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 +98,7 @@ export function parseArgs(argv, cwd) {
         failFast: false,
         json: false,
         engine: 'auto',
+        allowMissingTargets: false,
         strictTargets: false,
         includeSpecs: false,
         allowEmpty: false,
@@ -109,7 +123,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 +148,9 @@ export function parseArgs(argv, cwd) {
             case '--strict':
                 options.strictTargets = true;
                 break;
+            case '--allow-missing-targets':
+                options.allowMissingTargets = true;
+                break;
             case '--include-specs':
                 options.includeSpecs = true;
                 break;
@@ -209,6 +226,7 @@ export async function main(argv = process.argv.slice(2), io = defaultIO()) {
             root: options.root,
             engine: options.engine,
             failFast: options.failFast,
+            allowMissingTargets: options.allowMissingTargets,
             strictTargets: options.strictTargets,
             includeSpecs: options.includeSpecs,
             concurrency: options.concurrency,

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/comments.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Comment classification.
+ *
+ * A documented codebase defeats a plain text search in the most ironic way
+ * available: the comment recording that a symbol was deleted is itself a match
+ * for that symbol. `@assert-absence symbol="LegacyThing"` then fails on
+ *
+ *   // LegacyThing was removed in ADR-398
+ *
+ * which is the sentence proving the assertion true. So matches are classified
+ * and, by default, those inside comments do not count.
+ *
+ * The scanner tracks strings as well as comments, and it has to: a `//` inside
+ * a string literal is not a comment, and misreading one is the dangerous
+ * direction. Consider
+ *
+ *   const url = "http://example.com"; const x = LegacyThing;
+ *
+ * Treating `//` in that URL as a comment start would hide a real use of
+ * LegacyThing and turn a violation into a silent pass. Every uncertainty here
+ * therefore resolves the same way: **when in doubt, it is code**. A match
+ * wrongly kept is a visible failure someone can argue with; a match wrongly
+ * dropped is a lie.
+ *
+ * Languages it does not recognise get no comment ranges at all, so their
+ * matches all count - and the result says so rather than implying the file was
+ * understood.
+ */
+interface StringRule {
+    open: string;
+    close: string;
+    /** Backslash escapes apply inside. */
+    escape: boolean;
+}
+export interface CommentSyntax {
+    name: string;
+    /** Prefixes that comment out the rest of the line. */
+    line: readonly string[];
+    /** Delimiter pairs for block comments. */
+    block: ReadonlyArray<readonly [string, string]>;
+    /** Block comments nest, as in Rust. */
+    nested: boolean;
+    /** Literal forms that may contain comment-looking text. */
+    strings: readonly StringRule[];
+}
+/** The comment syntax for a path, or null when the language is unknown. */
+export declare function syntaxFor(filePath: string): CommentSyntax | null;
+/** Half-open [start, end) offsets that are comment text. */
+export type CommentRange = readonly [number, number];
+/**
+ * Finds every comment in the source.
+ *
+ * One pass, tracking strings so that comment markers inside them are ignored.
+ * An unterminated comment or string runs to the end of the file, which matches
+ * how a compiler would read it.
+ *
+ * The scan is written so that it cannot stand still: whatever the branches
+ * below decide, the loop advances by at least one character. That guarantee is
+ * the difference between a wrong answer and a hang, and this loop appends as it
+ * goes - standing still here would not spin, it would eat memory until the
+ * process died, on somebody's file, in somebody's CI.
+ */
+export declare function commentRanges(source: string, syntax: CommentSyntax): CommentRange[];
+/**
+ * Decides whether a byte offset falls inside a comment.
+ *
+ * `classified` is false when the language is unknown, in which case nothing is
+ * treated as a comment. Callers report that rather than implying the file was
+ * understood.
+ */
+export interface CommentMask {
+    readonly classified: boolean;
+    readonly syntax: string | null;
+    isComment(offset: number): boolean;
+}
+export declare function createCommentMask(source: string, filePath: string): CommentMask;
+export {};
+//# sourceMappingURL=comments.d.ts.map

package/dist/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,0CAA0C;IAC1C,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CAChC;AAuHD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEhE;AAED,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAqCrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,YAAY,EAAE,CAkCnF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAqB/E"}