@descent-vtt/spec-guard 0.10.3 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,416 @@ All notable changes to this project are documented here. Versions follow
 may change in a minor release — each such change is listed under **Changed**
 with the flag that restores the previous behaviour.
 
+## 0.12.0
+
+The family's core, and three commands. Patterns and Markdown are read through
+spec-core, copied in and checked by hash: a pattern that cannot be read is
+refused rather than matched as a literal, a glob no longer backtracks, and
+directives are found as CommonMark finds code, comments and front matter.
+`prove` shows every rule in force catching a violation, `cites` holds code
+comments to the specs they cite, and `impact` names who depends on a path.
+`archived` withholds a document.
+
+### Upgrading
+
+Run this release beside the one it replaces, each with `--json`, and compare
+`summary.total` before trusting a green run - and, if the totals differ, each
+result's `spec` file and line, which say which rule moved. A rule that stops
+running reads exactly like one that passes. On a consumer of 114 specs and 301
+assertions, both releases ran the same 301 at the same places with the same
+counts. What can differ, and where this changelog says why:
+
+- **A run that exits 2**, or a directive that is invalid, where one ran: a
+  pattern that cannot be read - `**` inside a name (`docs/**.md`), an
+  extended glob, an unclosed `[` or `{` - in `specs`, `exclude`, `--spec`,
+  `--exclude` or a directive's attributes.
+- **`summary.total` moving** because a directive moved between prose and code:
+  the shapes under Fixed. Every directive-shaped comment left in code, raw
+  HTML or front matter is on one line of the report and in `maskedDirectives`.
+- **`summary.inactive` moving**: `archived` withholds a document; a
+  front-matter `status` the reader cannot read - text after a closing quote,
+  `: ` in a plain value - keeps its document in force with a warning, where
+  0.11.0 took its first word, and nothing below the front matter is read in
+  its place; and an invalid directive in a draft is counted once, as invalid.
+- **Warnings that fail nothing**, in `specWarnings`: a front-matter status
+  that cannot be read, a block never closed.
+- **`impact` exits 2** when no spec matched, as `query` does.
+
+### Added
+
+- **`spec-guard impact <paths...>`: who depends on this?** For each path, the
+  files that import it, transitively, each with its distance and the import
+  that takes it one step closer, and the rules in force that govern the path or
+  any of them, by `query`'s arithmetic. The import graph is ADR-0011's, read
+  backwards over the whole tree: relative JavaScript and TypeScript imports by
+  its resolution table, and relative Python imports, which name a module
+  beside the importing file. Go, Rust, C# and absolute Python references name
+  modules and are counted rather than followed; a path in one of those
+  languages says its dependents are not computed. An import naming no file, an
+  alias or a dynamic `import(name)` is listed, never guessed. `--depth <n>`,
+  `--ignore-status`, and `--json` with `formatVersion`. A path that does not
+  exist is exit 2, and so is a run in which no spec matched, as for `query`:
+  the dependents are written, and `--allow-empty` exits 0 with them. `impactOf`
+  is the API. [ADR-0018](docs/adr/0018-impact.md).
+- **`get_dependents` on the MCP server**, a third tool beside
+  `get_architectural_rules` and `check_architecture`: `impact` for a list of
+  paths, with `depth` and `include_inactive`. Its structured content is the
+  document `impact --json` writes and its text the command's report, and it is
+  annotated read-only, as the other two are. Its description, and the server's
+  instructions, tell an agent to call it before changing a file others import.
+  A path that does not exist is a tool error the model can read. A client
+  that pinned the tool list sees three. `impactDocument` is the API for the
+  document both answer with. ADR-0018's amendment.
+- **`spec-guard cites`: do the comments cite decisions in force?** A comment
+  such as `// ADR-0011: the domain imports no infrastructure` is a claim, and it
+  goes stale when the document is never written or is superseded. `cites` reads
+  the comment text of every source file - by the classifier's reading, so never
+  a string - for the ids of the families a project names in a new `cites`
+  option, `[{ "id": "ADR-{n}", "files": "docs/adr/{n}-*.md" }]`, where `{n}` is
+  a number (`ADR-7`, `ADR-007` and `0007-x.md` are one document). Without it, a
+  directory of numbered specs whose titles all begin with one id and their own
+  number is read as a family; anything less is a note and exit 0, not a guess.
+  A **ghost** citation, of no document, is an error with the nearest ids as its
+  hint. A **stale** one, of a document superseded, deprecated, rejected or
+  archived, is a warning (an error under `--strict`) that names the successor
+  the document's status line gives, followed to the one in force. Ids another
+  project qualifies - `spec-core's ADR-0005` - are counted and not checked,
+  and so are ids in a link: after a `/`, `#`, `=` or `?`, or past a `://`,
+  as in `https://github.com/org/repo/blob/main/docs/adr/ADR-0042.md`.
+  Markdown, spec files, excluded paths and files in no known language are not
+  read, and are counted. Human, `--json` (with `formatVersion`), SARIF, GitHub
+  and GitLab output; exit 1 on a ghost, 2 for a family whose files match no
+  document. `findCitations` is the API.
+  [ADR-0017](docs/adr/0017-citations-in-comments.md).
+- **`spec-guard prove`: can each rule actually fail?** A passing rule cannot
+  say whether the code holds or the rule cannot see the code. `prove` shows
+  each rule in force a violation of itself - a file holding the forbidden text,
+  a file importing the forbidden module, a cycle, an import across layers, a
+  misnamed file, a required entry or a partner taken away, a required file
+  removed - and runs the rule over it, in memory, through the door every read
+  goes through: nothing is written to disk and nothing touches git. Each rule
+  is `killed`, `survived` (the finding, with the violation shown) or
+  `unprovable` (with the reason). Exit 1 when a rule survived, and under
+  `--strict` when one is unprovable; `--json` is versioned by `formatVersion`,
+  and `--format sarif` puts a survivor on its directive.
+  `proveSpecGuard` is the same for a caller of the API. The first proof of
+  this repository's own rules found one that could not fail as written, and
+  CI now proves every rule the repository states on each change.
+  [ADR-0016](docs/adr/0016-rules-seen-to-fail.md).
+- **`RunOptions.io`: a run over a tree that is not on disk.** `runSpecGuard`
+  reads through the `Io` it is given - finding and reading the specs, checking
+  targets exist, walking them, scanning files, reading imports and listing
+  directories - and through `nodeIo` when it is given none, as before. The run
+  had the door all along and handed the filesystem to every reader itself.
+  ripgrep reads the disk in a process of its own, where no door reaches, so
+  `engine: 'ripgrep'` with an `io` is refused with a message that says so, and
+  `auto` with one searches with the built-in scanner. A search that fails
+  outright through the door fails the run, rather than falling back to the
+  scanner that reads the disk. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
+- **`--format gitlab` and `--format github`**, for the run, `prove` and
+  `cites`. `gitlab` writes a GitLab Code Quality report - `description`,
+  `check_name`, a `fingerprint`, a `severity` and a `location` - which a
+  merge request shows beside its changes. The fingerprint is the SHA-256 of
+  what a finding is about - a rule's document, kind, subject and targets, as
+  SARIF's is; a citation's file, family and id; a document's path - and never
+  of its message, which holds the count of matches and the directive's line:
+  one more match, or a line added above a directive, would otherwise have
+  closed every open issue and opened a new one. Findings that share an
+  identity, one ghost cited on two lines, are numbered in order. `github` writes one workflow command per finding, which a job's log
+  turns into an annotation on the pull request with no upload step. Both place
+  the findings SARIF places: a failing assertion or a surviving rule is
+  `critical`, a directive that could not be read `major`, a rule `prove` could
+  make no violation for `minor`, and a document not in force is named, as
+  `info`, on its first line. `formatGitlab`, `formatGithub`, `runAnnotations`,
+  `proveAnnotations` and `citesAnnotations` are the API.
+- **What was not run is counted.** A comment shaped like a directive in code,
+  raw HTML or front matter is not run, and a report now says how many and
+  where: one dim line in the human report - "7 directive-shaped comments in
+  code, raw HTML or front matter were not run: README.md:120, ..." - naming
+  the first five, or every one under `--verbose`, and `maskedDirectives` in
+  the `--json` of a run and of `prove`, each with what hid it. Most are
+  examples; the ones that are not are rules 0.11.0 ran that this release does
+  not, such as a directive in an indented line or under a leading `---` read
+  as front matter. Warnings about how a document was read - a front-matter
+  status that cannot be read, a block never closed - are `specWarnings`.
+  Both fields are added, so no `formatVersion` moves.
+  [ADR-0002](docs/adr/0002-directive-format.md)'s amendment.
+- **`formatVersion: 1` on the run's `--json` and on `query --json`**, as
+  `prove --json` has had from the start: a field removed or renamed moves it,
+  a field added does not. Both documents are otherwise unchanged; this is one
+  field more, first in each.
+- **`io` on `loadRuleSet` and `queryRules`, too.** A query found and read the
+  specs, and asked whether each path exists, through the filesystem whatever
+  the caller had; it now goes through the door it is given, as a run does, so
+  a query over a tree in memory sees that tree.
+
+### Fixed
+
+- **An invalid directive in a document not in force was counted twice**, as
+  invalid and again as a rule not in force, so one bad directive in a draft
+  read "1 invalid · 1 not in force". It is counted once, as invalid, in the
+  summary, in the document's own line, and in the `inactive` of every JSON
+  report: it is no rule the document would run in force.
+- **A glob could take a minute to fail one file name.** Every pattern was
+  compiled to a `RegExp`, and `*-*-*-*-*-*x` against a name of 121 dashes made
+  V8 try every way of dividing the name between six `[^/]*` groups: 55 seconds,
+  measured. Patterns are now read by the glob engine the spec-* tools share,
+  spec-core's, whose automaton keeps a set of live states and cannot backtrack:
+  the same match takes under a millisecond. spec-core is copied into
+  `src/vendor/spec-core` and verified by hash, so `dependencies` stays empty,
+  and its MIT notice ships in the package at `src/vendor/spec-core/LICENSE`.
+  [ADR-0015](docs/adr/0015-globs-from-spec-core.md).
+- **ripgrep and the scanner still read some patterns differently**, so the same
+  rule could count differently on either side of the tree size at which `auto`
+  changes engine. ripgrep anchored every alternative of `{src/*.ts,*.md}`
+  because one held a `/`, dropped the empty one in `{,src/}a.ts`, matched
+  nothing for `src/./a.ts`, and failed on a `}` that closes nothing. It is now
+  handed each alternative as a glob of its own, spelled as the scanner reads
+  it. And ripgrep applies no glob to a path named on its command line, so a
+  rule whose target is a file its `glob` does not match, or a directory its
+  `exclude` does, counted under ripgrep what the scanner left out; its list of
+  files is now held to the same filters. ADR-0015.
+- **What is code in a spec is what CommonMark says it is.** Directives inside
+  code never execute, and what counted as code was decided by `maskCode`'s own
+  rules. It is now decided by spec-core's Markdown scanner, which every spec-*
+  tool reads documents with, copied into `src/vendor/spec-core` from `cbe2223`
+  and verified by hash; `maskCode` is still exported, and is the scanner's
+  mask. [ADR-0002](docs/adr/0002-directive-format.md)'s amendment.
+
+  Directives that were hidden, and now execute:
+  - **A backtick fence's info string may not hold a backtick.** A line that
+    reads ```` ```js`x ```` is prose that opens with a code span. Read as a
+    fence, it hid every line under it, a real directive included, until
+    something closed it - and nothing said a rule had gone quiet.
+  - **A code span ends with its paragraph.** A backtick that closes nothing
+    there, as in ``press ` to open the console``, paired with the next
+    backtick anywhere in the document and hid every directive between the
+    two. An escaped backtick opens nothing.
+  - **A fence shown inside a comment opens nothing.** A template that showed
+    one hid every directive after it.
+  - **A fence line shown as code in a list item opens nothing.** Four columns
+    past an item's text is indented code, so a fence line written there - six
+    spaces under a `-` item, seven under `1.`, deeper in a nested item - is a
+    line of code. The first copy of the scanner read no indented code inside a
+    list, took the line for an opener that nothing closed, and hid every
+    directive after it.
+
+  And a code fence or a `<pre>`, `<script>`, `<style>` or `<textarea>`
+  block that is never closed, and runs to the end of the document, is a
+  warning on its opening line (`specWarnings`), since no directive after it
+  runs. It fails nothing: it is read as every renderer shows it, as code.
+
+  Directives that executed, and are now code:
+  - **A closing fence has no info string.** Inside a block opened by three
+    backticks, a line of three backticks followed by `js` is a line of the
+    block. It used to close it, and a directive shown after it executed.
+  - **A fence may be indented with the list item it sits in.** CommonMark
+    counts its three spaces from the item, so a fence in a `1.` item nested in
+    a `-` item is five or more spaces from the margin. It was not recognised,
+    and a directive shown inside it executed: always behind `~~~`, and behind
+    backticks whenever the prose above mentioned one, since the two fence lines
+    otherwise paired as a code span by accident. An opener may sit at any
+    indentation outside indented code, and a closer at most three columns
+    deeper than its opener.
+  - **Indented code, raw-text HTML and front matter are not read.** Four
+    columns past the margin, or past the text of the list item a line sits
+    in, after a blank line, are code in every renderer;
+    `<script>`, `<pre>`, `<style>` and `<textarea>` hold no Markdown; front
+    matter is metadata. `<details>` and `<div>` hold Markdown, and are read.
+
+  And a backtick inside a comment is a character, so a directive holding one
+  keeps it: ``symbol="`eval`"`` is searched for as written, where the two
+  backticks paired and the rule searched for six spaces.
+
+  This repository's own specs execute the same assertions, at the same lines,
+  and every directive in the 143 Markdown files of the five spec-* repositories
+  is read as before. A test holds the scanner to 0.11.0's masking on every
+  Markdown file here, and on random documents built from lines both read alike,
+  and shows it parting from 0.11.0 on each shape above.
+
+### Changed
+
+- **Mutation testing in CI runs in eight shards**, not four. Three of the four
+  took 23 to 28 minutes on the sweep that merged this release's code, and the
+  fourth was cancelled at the 30-minute job limit. ADR-0003 has the per-file
+  minutes and the split; the longest of the eight took 16m16s.
+- **A pattern that cannot be read is refused.** An unclosed `[` or `{`, an
+  extended glob such as `+(a|b)` (a group holding a `|`: `C++(notes).md` and
+  `*(2017).md` are names with parentheses), a `..`, or a range that runs
+  backwards, in `glob`, `exclude`, `module`, `order`, `pattern`, `dirs` or
+  `required`, makes the directive invalid; in `exclude` in the configuration or `--exclude`, or in
+  a spec pattern, it is exit 2. Each used to be read as a literal or as whatever
+  its `RegExp` happened to mean, which is a filter that matches nothing and
+  passes. So is an alternative that names no path, as in `{dist/**,}`, whose
+  empty alternative matched the empty string. A brace group with a comma in it
+  in a directive is one more case: a list attribute splits on commas, so
+  `glob="*.{ts,tsx}"` was always the two patterns `*.{ts` and `tsx}`, and the
+  message now says so. A configuration's `exclude` is a JSON array, where braces
+  keep their commas. Nothing restores the old readings.
+  [ADR-0015](docs/adr/0015-globs-from-spec-core.md).
+- **`**` inside a name is refused**: `docs/**.md`, `src/**.ts`, `**.ts`,
+  `a**b`. The message says what `**` means and gives the two ways to write
+  what was meant, `docs/**/*.md` for any depth and `*.md` for one level. It
+  used to cross directories under the scanner and not under ripgrep, so a rule
+  counted differently by engine; read as `*`, as `.gitignore` reads it,
+  `"specs": ["docs/**.md"]` would quietly have stopped finding every nested
+  document. In a directive the directive is invalid, in a draft as in a
+  document in force. A spec pattern is refused before any command starts: in
+  the configuration's `specs`, naming the file, and on the command line or in
+  `--spec`, for `query`, `impact`, `cites`, `prove` and `mcp` as for a run -
+  exit 2, as `exclude` in the configuration and `--exclude` are.
+  `specPatternError` is the check, for a caller of the API.
+- **A `.` or empty segment is no segment** (`src/./a.ts` is `src/a.ts`), and
+  **a leading `/` anchors a `glob`** at the root, as it anchors an `exclude`.
+  Both matched nothing in the scanner before; ripgrep already anchored.
+- **`archived` withholds a document**, a sixth word beside `draft`,
+  `proposed`, `rejected`, `deprecated` and `superseded`. `spec-brief` closes a
+  task brief's round by setting `status: archived` and moving the brief to an
+  archive directory. Its directives stated the round's premises and goals,
+  which are history once the round is closed, and executed anyway they failed.
+  An archived document is still parsed, validated and named in every output
+  format. `--ignore-status` executes it as before. The list stays closed:
+  `done`, `closed`, `archive` and every other near word stay in force, and
+  [ADR-0010](docs/adr/0010-spec-status.md)'s amendment says why this word and
+  no other.
+- **A status is found by the scanner's headings and front-matter reader.**
+  The three spellings, their order and the words are unchanged, and every
+  status in the five spec-* repositories reads as it did. Where the scanner
+  reads a document differently, the status follows it:
+  - A `## Status` kept in a comment - a template not yet filled in - no longer
+    withholds the document, and a `##` in a comment or in code no longer ends
+    the preamble where the `**Status:**` label is read.
+  - An underlined heading is a heading. An underlined `Status` is the section,
+    and an underlined section ends the preamble, so a `status: draft` line with
+    `---` directly under it is a heading, as every renderer shows it, and not a
+    label.
+  - Front matter is read by spec-core's reader, the family's: a quoted value
+    to its closing quote and a plain one to a comment, as before. A value it
+    refuses declares nothing - a `: ` in a plain value, text after a closing
+    quote, a value continued on the next line, `*Draft*`, which YAML reads as
+    an alias - and a `status` nested under another key is that key's. Front
+    matter behind a byte-order mark, or closed by `...`, is read as front
+    matter.
+  - A front-matter `status` decides even when it cannot be read. A value the
+    reader refuses, an empty one, one with no word or a list leaves the
+    status unrecognised and the document in force, and the `## Status`
+    section and the `Status:` label are not read in its place: under 0.11.0
+    `status: "accepted" (2024-05-01)` was accepted, and falling through to a
+    section still saying `Proposed` would have withheld its rules. Every
+    format says so, on the key's line: a warning in the human report, a
+    `specWarnings` entry in `--json` (run and `prove`), a SARIF notification
+    and a `spec-warning` annotation for GitHub and GitLab.
+
+  [ADR-0010](docs/adr/0010-spec-status.md)'s second amendment.
+- **A title is the first level-one heading as the scanner reads it.** An
+  underlined one (`===`) is a title and one kept in a comment is not; a code
+  span in it is kept as written, where it was blanked, and a comment in it is
+  dropped. A first level-one heading with no text leaves the document
+  untitled rather than promoting the next. In this repository one title
+  changed: ADR-0009's keeps its `` `--fix` ``.
+- **`maskCode` keeps a carriage return inside code**, where it blanked one:
+  every line terminator stays where it was, a lone `\r` included.
+- **Reading a spec costs about four times what it did**: 17 ms against 4 ms
+  over this repository's 18 ADRs, and 23 ms against 9 ms for a warm query of
+  one path, past the 20 ms ADR-0012 set out to meet. The scanner finds list
+  items, links and tables that nothing here reads.
+  [ADR-0002](docs/adr/0002-directive-format.md)'s amendment says where the
+  remedy lies.
+- **The MCP server speaks the protocol through spec-core.** Classifying each
+  request, the two eras, dispatch, result shapes and the stdio framing are
+  spec-core's `jsonrpc` module, copied from `f085f29` and verified by hash;
+  `src/mcp.ts` keeps the instructions, the tools and the resources. What a
+  client sees is unchanged, and every test of the server passes as it was
+  written. One edge moved: a last line cut inside a UTF-8 character when stdin
+  closes is read as far as it goes rather than dropped. The protocol's names
+  are still exported from the package. [ADR-0015](docs/adr/0015-globs-from-spec-core.md).
+- **API:**
+  - `createGlobMatcher`, `createExcludeMatcher` and `expandSpecPatterns` throw
+    for a pattern spec-core refuses - an unclosed `[` or `{`, an extended
+    glob, a `..`, `**` inside a name - naming the pattern, where they read it
+    as a literal or as whatever its `RegExp` meant. `globPatternError` and the
+    new `specPatternError` say why without throwing.
+  - `Annotation` has a required `identity`, which the GitLab fingerprint is
+    made of. `SpecSet` and `RunPlan` have required `warnings` and `masked`;
+    `RunReport` and `ProveReport` have optional `specWarnings` and
+    `maskedDirectives`, and `ParseResult` optional `warnings` and `masked`.
+    An `InactiveSpec`'s `directives` counts only those that resolve.
+  - New: `proveSpecGuard`, `PROVE_NAME`, `overlayIo` and `readOnce`;
+    `findCitations`, `findDocuments`, `deriveFamilies`, `scanCitations`,
+    `inComments`, `qualified`, `isStale`, `numberKey`, `documentNumber`,
+    `parseIdTemplate`, `parseFilesTemplate`, `citeIdError`, `citeFilesError`,
+    `CitesError` and `NUMBER`; `impactOf`, `impactDocument`, `dependentsOf`,
+    `buildReverseGraph`, `resolvePython`, `formatImpact`, `formatImpactJson`
+    and `ImpactError`; `formatProve`, `formatProveJson`, `formatProveSarif`,
+    `formatCites`, `formatCitesJson`, `formatCitesSarif`, `formatGitlab`,
+    `formatGithub`, `runAnnotations`, `proveAnnotations` and
+    `citesAnnotations`; `RUN_FORMAT_VERSION`, `QUERY_FORMAT_VERSION`,
+    `PROVE_FORMAT_VERSION`, `CITES_FORMAT_VERSION` and
+    `IMPACT_FORMAT_VERSION`; `globPatternError` and `specPatternError`; and
+    the types that go with them, `SpecWarning`, `MaskedDirective` and
+    `MaskedContext` among them.
+
+## 0.11.0
+
+The literal this lexer never read. A JavaScript or TypeScript regular
+expression can hold a quote — `/'/`, `/["']/`, `replace(/\/\//g, '')` — and
+without a rule for `/`, that quote opened a string that closed somewhere else
+entirely. Every text rule over a TypeScript project reads through this
+classifier, and this repository's own `src/parser.ts` was one of the files it
+lost its place in. [ADR-0006](docs/adr/0006-comment-classification.md).
+
+### Fixed
+
+- **A regular expression holding a quote desynchronised the scan.** The quote
+  opened a string that ran to the next quote in the file, so the comments it
+  covered were counted as code — and, once it closed, the scan was half a
+  literal out of step, where a `//` inside a real string opened a comment that
+  **hid real code**. `/` now opens a literal in `.js`, `.mjs`, `.cjs`, `.jsx`,
+  `.ts`, `.mts`, `.cts` and `.tsx`, decided by the token before it with the
+  same two tables the import tokenizer has used since 0.2.0 — which now live in
+  one place and are read by both, so the two scanners cannot disagree. A
+  character class holds an unescaped `/`, `\/` does not close, and a `/` that
+  closes nothing before the end of its line was a division.
+- **`/*` in JSX text opened a comment**, so `<div>/*</div>` hid every line up
+  to the next `*/` in the file. After a tag's `>` it is text.
+- **An apostrophe in a YAML value opened a string.** Most YAML scalars are
+  unquoted and may hold one — `- name: Build the decoder's artefact` — and read
+  with the shell's quoting that apostrophe closed on the next one, lines away,
+  with every `#` between them no longer a comment. `.yaml` and `.yml` have a
+  profile of their own, `yaml`, which keeps the shell's `#` rule and takes a
+  quote as opening a scalar only where a word could start. `'it''s'` is one
+  scalar, YAML's own escape. A shell's quotes still open mid-word, because
+  `dir='C:\'` needs them to.
+
+### Changed
+
+- **A JavaScript string ends at its line.** Only a template may hold a line
+  break, so a quoted string that reaches one was never a string and is read as
+  code from there. It used to run to the end of the file. This is what JSX text
+  costs as well: `<p>Don't click</p>` opens a literal nothing closes, and it
+  now costs that line rather than everything after it.
+- **The `shell-like` profile split in two.** `.sh`, `.bash` and `.zsh` are
+  read as `shell`, `.yaml` and `.yml` as `yaml`, because their quoting
+  differs: a shell's quotes open mid-word and YAML's open only where a value
+  starts. The names themselves are internal — no output reports them — so what
+  changed for a caller is the reading, described above.
+
+Counts may move on a project that has any of these. A text rule over `.ts`,
+`.tsx`, `.yaml` or `.yml` can now see code it could not see before, and can
+stop counting comment text it was counting: on 7,953 files here, 119 phantom
+comments in 63 files disappeared and 1,948 real comments in 53 files came back.
+44 JavaScript files reported a lost scan before; 4 do now, every one of them a
+template nested inside a `${…}` substitution, which ADR-0006 records as the
+open item this release does not close.
+
+The scan is also **faster than it has ever been** — 5.1× for TypeScript, 5.2×
+for C#, 3.4× for C, 2.8× for shell scripts and 1.3× for Rust, whose raw strings
+open with the letter `r` and so reach the slow path often. A character that
+opens nothing in a language now costs one array lookup rather than four
+searches that were always going to fail. That was not a bonus: adding the
+regular-expression branch made C, which never enters it, 16% slower, and a
+question asked per character has to be paid for per character.
+
 ## 0.10.3
 
 Fixes from running 0.10.2 over a Rust and .NET monorepo, where an import rule