npm - @descent-vtt/spec-guard - Versions diffs - 0.1.0 → 0.3.0 - Mend

@descent-vtt/spec-guard 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/CHANGELOG.md ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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
@@ -171,8 +315,9 @@ spec-guard [patterns...] [options]
 | `-v, --verbose` | Print passing assertions too |
 | `--fail-fast` | Stop at the first failing assertion |
 | `--json` | Machine-readable report on stdout |
-| `--engine <auto\|rg\|js>` | Search engine (default `auto`: ripgrep when available) |
-| `--strict` | Treat a `target` that does not exist as a failure, not a warning |
+| `--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 |
 | `--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) |
@@ -255,19 +400,37 @@ in one pass. Measured on Windows 11 / Node 24 / ripgrep 15 against a synthetic
 | ripgrep engine | ~280 ms | **~72 ms** |
 | JavaScript fallback | ~780 ms | **~283 ms** |
+`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.
+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.
 Two honest caveats:
-- **Process spawning is expensive on Windows** (~27 ms each). On a small tree
-  the JavaScript engine can beat ripgrep outright - spec-guard checks its own
-  repository in ~15 ms with `--engine js` versus ~170 ms with ripgrep. On Linux
-  and macOS, where spawning costs a few milliseconds, ripgrep wins at every
-  size. If your repository is small and you care about the last millisecond,
-  `--engine js` is a legitimate choice.
-- **ripgrep is the reference implementation.** The fallback matches it on
+- **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 fallback uses a fixed ignore list (`node_modules`, `dist`, `build`,
-  `coverage`, `.git`, dotfiles, and friends).
+  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`.
 ## Programmatic API
@@ -299,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
@@ -334,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)
@@ -345,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
@@ -354,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
 ```
@@ -368,20 +546,28 @@ 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: **83.16%** of
-2,060 mutants are killed, 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
+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
 almost all `toContain` against colourless output. A mutant could prepend a junk
-line to the output, drop a colour, or turn `remaining > 0` into `remaining >= 0`
-and every test still passed. Seventy-five tests later - exact whole-output
-comparison instead of substring matching - the reporter is at 87.30%.
-`npm run test:mutation` runs it. CI runs it weekly, on demand, and on pull
-requests that touch `src/` or `tests/`, with the score gated at 80%. The full
-story, including a run whose score turned out to be fiction, is in
-[ADR-0003](docs/adr/0003-mutation-testing.md).
+line, drop a colour, or turn `remaining > 0` into `remaining >= 0` and every
+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
+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.
 ## Requirements

package/dist/cli.d.ts CHANGED Viewed

@@ -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 - ripgrep when available)\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 CHANGED Viewed

	@@ -1 +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,~~o9CA8B8D~~,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~~"}
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"}

package/dist/cli.js CHANGED Viewed

@@ -40,8 +40,10 @@ Options
   -v, --verbose           Print passing assertions too
       --fail-fast         Stop at the first failing assertion
       --json              Emit a machine-readable JSON report
-      --engine <name>     auto | rg | js  (default: auto - ripgrep when available)
-      --strict            Treat a target path that does not exist as a failure
+      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)
+      --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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGtF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;~~AA2B5B~~,MAAM,OAAO,UAAW,SAAQ,KAAK;CAAG;AAExC,SAAS,OAAO;IACd,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAyB,CAAC;QAC/D,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG~~;;;;;;;;;;;;;;;;;qEAiBiD~~,oBAAoB;sEACnB,mBAAmB~~;;;;;;;;;;;;+EAYV~~,CAAC;AAEhF,MAAM,cAAc,GAAqC;IACvD,IAAI,EAAE,MAAM;IACZ,EAAE,EAAE,SAAS;IACb,OAAO,EAAE,SAAS;IAClB,EAAE,EAAE,YAAY;IAChB,UAAU,EAAE,YAAY;IACxB,IAAI,EAAE,YAAY;CACnB,CAAC;AAEF,SAAS,YAAY,CAAC,IAAY,EAAE,KAAyB;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,UAAU,CAAC,UAAU,IAAI,oBAAoB,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,KAAa;IAClD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,UAAU,IAAI,yCAAyC,KAAK,IAAI,CAAC,CAAC;IACjH,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,IAAuB,EAAE,GAAW;IAC5D,MAAM,OAAO,GAAe;QAC1B,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,GAAG;QACT,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,MAAM;QACd,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,oBAAoB;QACjC,WAAW,EAAE,mBAAmB;QAChC,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,KAAK;KACf,CAAC;IAEF,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAW,CAAC;QAEvC,IAAI,cAAc,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChC,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,cAAc,GAAG,IAAI,CAAC;YACtB,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAClE,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC3E,MAAM,SAAS,GAAG,GAAW,EAAE;YAC7B,IAAI,WAAW,KAAK,SAAS;gBAAE,OAAO,~~YAAY,CAAC,IAAI,EAAE,~~WAAW,CAAC~~,CAAC~~;~~YACtE~~,KAAK,IAAI,CAAC,CAAC;YACX,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC;QAEF,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,IAAI,CAAC;YACV,KAAK,QAAQ;gBACX,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;gBACpB,MAAM;YACR,KAAK,WAAW;gBACd,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;gBACvB,MAAM;YACR,KAAK,IAAI,CAAC;YACV,KAAK,WAAW;gBACd,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;gBACvB,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACxB,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;gBACpB,MAAM;YACR,KAAK,UAAU;gBACb,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;gBAC7B,MAAM;YACR,KAAK,iBAAiB;gBACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;gBAC5B,MAAM;YACR,KAAK,eAAe;gBAClB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC1B,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;gBACrB,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;gBACtB,MAAM;YACR,KAAK,IAAI,CAAC;YACV,KAAK,QAAQ;gBACX,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC9C,MAAM;YACR,KAAK,UAAU,EAAE,CAAC;gBAChB,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC,WAAW,EAAE,CAAC;gBACxC,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;gBACrC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,IAAI,UAAU,CAAC,mBAAmB,KAAK,6BAA6B,CAAC,CAAC;gBAC9E,CAAC;gBACD,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;gBACxB,MAAM;YACR,CAAC;YACD,KAAK,gBAAgB;gBACnB,OAAO,CAAC,WAAW,GAAG,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;gBACzD,MAAM;YACR,KAAK,eAAe;gBAClB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;gBACtE,MAAM;YACR;gBACE,MAAM,IAAI,UAAU,CAAC,mBAAmB,IAAI,2BAA2B,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,cAAc,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS;IAChB,OAAO;QACL,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;QACnD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;QACnD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAI,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,GAAU,SAAS,EAAE;IACjG,IAAI,OAAmB,CAAC;IACxB,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACd,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACrB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,YAAY,CAAC;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,eAAe,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnF,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,EAAE,CAAC,MAAM,CAAC,qCAAqC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrG,CAAC;QACD,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IACnD,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,MAAM,CACP,YAAY,CACV,MAAM,EACN;YACE,KAAK,EAAE,cAAc,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC;YACjE,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,KAAK,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC;SAC9B,EACD,OAAO,CAAC,WAAW,CACpB,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;AAC3C,CAAC"}
1	+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/comments.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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"}