codebase-snapshot 0.9.9 → 0.9.14

package/CHANGELOG.md

@@ -21,6 +21,879 @@ Two versions exist on the registry that are not releases, and both are deprecate
 Deleting them requires account-level rights that the release pipeline does not have, so they are
 deprecated with an explanatory message instead. `latest` has pointed at 0.9.0 since it existed.
 
+---
+
+## 0.9.14
+
+A fifth audit, of what the tool does to text it did not write. Three of the defects below were
+editing the user's code: a redaction rule erased 36 lines of source, a truncation left a code fence
+open, and a preview budget did not apply to a file with CR line endings. The rest are credentials
+left in clear text, two records that disagreed with the files beside them, and the performance work
+the previous audits kept deferring.
+
+Every item has a test that fails without it, with the exception of two performance changes that have
+no behavioural signal — both are named.
+
+### A redaction rule erased source code
+
+`PEM_BLOCK_PATTERN` is lazy over `[\s\S]`, which places no restriction on what may lie between a
+`BEGIN` and the next `END`. A file holding an *unterminated* header — a truncated key, a fixture, a
+half-written file — and, later, a properly terminated block had **everything between the two
+headers replaced with blank lines**, including the source code that happened to sit there.
+
+This repository did it to its own test suite: the security fixture's "unterminated key" test was
+followed by another test whose key was terminated, and the generator bridged the two — 36 lines of
+assertions, braces and the second test's declaration, replaced with 36 empty newlines.
+
+The body may no longer contain another `-----BEGIN`. A header with no `END` before the next `BEGIN`
+does not match as a block, and `PEM_UNTERMINATED_PATTERN` handles its header and its own base64 body,
+which is what that pattern is for. The newline after the header is deliberately still not required:
+a PEM inside a JSON or `.env` value is written with escaped `\n`, two characters rather than a line
+break, and a rule that insisted on one would mask the header alone and leave the base64 in clear.
+
+### A truncated section left its code fence open
+
+When the fixed metadata of a section would not fit the part budget, the *rendered* section was cut at
+a byte offset. The cut lands in the body or in the opening fence, and the closing fence it removes is
+the one that ends the block: every section after it was rendered inside this file's code block, and
+`parsePartSections` merged the next file into this one's body.
+
+The body now goes and the notice takes its place inside the block, with the file marked `preview`
+first so the re-rendered `- Meta:` line describes what the reader will actually find. A section that
+is a closed, empty, labelled block is readable; an unclosed fence corrupts the files after it, and no
+block at all is invisible to the part reader.
+
+### A file with CR line endings was never previewed
+
+`countLines` and `truncatePreview` split on `\n` alone, so a CR-only file — an old Mac file, anything
+written by a tool that predates LF on that platform — counted as **one line**. `largeFileBytes`
+therefore never fired: a 5 MB CR file went into a part whole, with its carriage returns intact, and
+`manifest.json` reported `lines: 1` for a 40 000-line file. The redaction pass counted terminators
+with `/\r\n|\n|\r/g`, so `reports/audit.md` reported line numbers the manifest disagreed with.
+
+All four places now normalise CR, LF and CRLF, and `countLines` counts by scanning rather than
+splitting — it runs on every file body and every part, and normalising first allocated a second copy
+of a multi-megabyte string to answer a question about its terminators.
+
+### Four credential shapes were left in clear text
+
+**`${VAR:-fallback}`, unquoted.** `POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-MyProdPassword123!}`
+defeated every rule, and each refusal was individually reasonable: the quoted rules need a quote
+after the separator, and the unquoted ones need the value to begin with a word character — a
+fallback begins with `$`. That idiom is the norm in `.env` files, docker-compose, GitHub Actions and
+shell scripts. A rule for the shape now masks the fallback and keeps the variable name.
+
+**`readonly` and `declare` in shell files.** Those words introduce a binding in TypeScript and an
+assignment in POSIX sh and `.envrc` — the same word, opposite meaning. The guard that suppresses
+redaction for declarations therefore suppressed it for exactly the files most likely to hold a
+credential. Bare `declare` is gone from the keyword list (the form that can initialise a binding in
+TS is `declare const`, matched through `const`), and the guard now knows which files are assignments.
+
+**A credential inside a string literal.** `startsInsideStringLiteral` rejected any match whose name
+began immediately after a quote, which is right for a list of key names and wrong for every
+connection string: `const dsn = "password=Secret;host=db"` and `curl -d "password=Secret"` were
+emitted in clear. The test now also asks whether the literal closes between the name and the value.
+
+**The MCP line cap.** `createLineReader` checked `MAX_LINE_BYTES` only on the buffer it had just
+appended to, so a chunk carrying a discarded line's terminator *and* the start of the next message
+left that remainder unmeasured until the stream ended — and `onEnd` delivered it whole to
+`JSON.parse`. It also compared `.length`, which is UTF-16 code units: a line of astral characters
+could be twice the ceiling in bytes and still pass. The cap is applied at every path that can
+deliver, and measured in bytes.
+
+### `--with-dependents` lost an importer, and three languages had no import graph
+
+The closure was computed from `file.summary.imports`, and a previewed or oversized file has no
+summary. An importer over `largeFileBytes` was therefore dropped as unchanged while `validate` and
+`explain`, which read the same file from disk, called it a dependent — generate and validate
+disagreed about the snapshot generate had just written. Import specifiers are cheap to extract from
+text already in hand, so they are now collected for files whose summary was refused, and the size
+ceiling lives in one place so all three commands refuse the same files.
+
+`resolveSpecifier` only understood JavaScript's `./x` shape, so the Python, Ruby, C/C++ and Dart
+imports the profiles have been recording for several releases resolved to nothing. Each language
+spells "this directory" differently — Python with dots, Ruby with `require_relative`, C with a
+quoted include, Dart with nothing at all — and each is now resolved on its own terms. Package-rooted
+languages (Go modules, Rust `crate::`, PHP PSR-4, JVM packages, Swift modules) stay unresolved on
+purpose: their specifiers go through a manifest, and guessing a path would fabricate edges that
+`validate` then has to disagree about.
+
+### `setup --format json` could corrupt its own output
+
+`setup` replaced `process.stdout.write` with a capture and restored the function it had captured on
+entry. A nested generate with an `async` hook installed the hook diversion inside that window, so
+`setup`'s restore ran first and removed it — the hook's `console.log`, after its first `await`, went
+straight to the real stdout — and the hook's restore then put back `setup`'s *finished* capture.
+Every later write in the process was appended to a dead string and silently discarded.
+
+Both borrow stdout and neither can own it, so there is now one router, installed at most once and
+released by reference counting, consulting two `AsyncLocalStorage` scopes.
+
+The same function also merged a failed nested generate in as `manifest`: `{ setup, manifest: { error } }`
+came out with exit code 1 and no top-level `error`. The failure is now at the top level.
+
+### A transient lock on the old snapshot could cost the new one
+
+`fs.rmSync(backupDir)` ran inside the `try` whose `catch` restores the previous snapshot. `rmSync`
+throws EPERM or EBUSY on Windows and on network filesystems when an indexer, an antivirus or an
+editor holds a handle in the old snapshot — and by then `outDir` already holds the new one. The catch
+deleted the new snapshot, restored the old one and rethrew; the retry then failed with ENOENT
+because the staging directory no longer existed. Removing the backup is no longer part of the
+transaction.
+
+### Two runs could take two different lock files
+
+`realpathSync(stagingRoot)` was used when the root existed and the unresolved path when it did not —
+and the run creates the root *after* taking the lock. On macOS, where `/var` is a symlink to
+`/private/var`, process 1 hashed `/var/folders/…/snapshot.tmp` and process 2, starting once the
+directory existed, hashed `/private/var/…`: two locks, no mutual exclusion, two concurrent writers.
+The key now resolves the nearest existing ancestor. Reclaiming a stale lock also re-checks the file's
+identity immediately before unlinking it, so two runs that both find the same dead lock cannot
+delete each other's.
+
+### The MCP worker ran the hook the docs say it does not
+
+`docs/mcp.md` tells the reader that `hooks.afterGenerate` does not run for a generation started from
+MCP. It did: the worker resolved the config file with its hooks intact, so an after-generate script
+ran from inside an MCP tool call, and a hook still running when the worker posted its result kept
+the thread alive for as long as the server did. The worker now empties `hooks` before resolving, and
+is terminated as soon as the result is settled.
+
+### A byte-order mark in `package.json` broke four readers
+
+`findConfigFile` reads `package.json` through `stripJsonComments`, which drops a BOM, so `generate`
+loaded a BOM'd project happily. Every other reader used bare `JSON.parse`, which throws on `\uFEFF`,
+and every one of them caught the throw and reported the ordinary, wrong answer: an existing
+`"snapshot"` block was invisible, `"type": "module"` was invisible, the scripts and devDependency
+were skipped with a note, and `nextStepHint` told the user to run `npx codebase-snapshot generate` —
+which resolves the *published* package instead of the one the run had just installed. The
+`npm create` shim had the same bug in `hasSnapshotScript`.
+
+A BOM is what a Windows editor writes when it saves UTF-8. All five readers now parse the same way
+the config loader does, and `init` writes the mark back rather than silently removing it.
+
+### `validate` could not name seven of the settings it compared
+
+`maxPartTokens`, `maxMonolithBytes`, `skeleton`, `sarif`, `changedSince`, `staged` and
+`withDependents` were recorded in the manifest and folded into the configuration digest, but never
+joined the field-by-field block. The digest can say *that* something changed; only the per-field
+comparisons say *what*. Toggling `--skeleton` produced the generic "the settings differ" line and
+nothing else.
+
+### A `.vue` or `.astro` script block was always parsed as `.ts`
+
+`<Button onClick={() => go()}>` is a type assertion followed by six parse errors to the TypeScript
+grammar, and no component at all, for a perfectly valid Vue `lang="tsx"` block. The script kind now
+follows the component: Astro frontmatter is JSX-capable by construction, and a Vue or Svelte block
+says so with `lang="tsx"`.
+
+### Performance
+
+- **The split loop re-rendered every part on every pass.** `partitionFilesForBuckets` renders all
+  groups, finds the first one over budget, splits it, and goes round again — up to 64 times. Each
+  pass re-assembled, re-token-estimated and SHA-256 hashed *every* part. A group's rendered size
+  depends on its sections, its index and the *width* of the numbering, and the width only changes
+  when the part count crosses 1 000, so sizes are now measured instead of rendered and cached per
+  group. Each part is hashed exactly once.
+- **The skeleton pass parsed with `setParentNodes: true`** and walked every node a second time to set
+  `.parent`, which nothing reads. It also expanded empty bodies from `{}` to `{ /* ... */ }`, making
+  small files larger, and rewrote the text once per span — 400 functions copied a 200 KB file 400
+  times.
+- **`fullContents` retained every file body on runs that wrote no monolith.** The map held a
+  reference to every pre-partition body and was read only inside `if (config.includeMonolith)`,
+  pinning the multi-megabyte originals that the partitioner had just replaced with previews.
+- **31 regexes were recompiled for every file.** `scanAndRedactSecrets` called `toGlobal` per rule
+  per call, and it is called once per file: a 20 000-file scan built 620 000 identical objects.
+- **`--watch` re-derived the whole repository for one changed file.** The derivation — redaction,
+  findings, skeleton, preview, summary — is a pure function of (bytes, settings, path), so it is now
+  cached and reused when the content hash and a settings digest both match. Validity is the **content
+  hash**, not `mtime`: a formatter or a `git checkout` can rewrite a file within the same timestamp
+  tick at the same length. Measured on a synthetic 250-file TypeScript repository: cold 520 ms, warm
+  196 ms of wall clock (2.65x) — the remainder is reading, hashing, partitioning and writing, which
+  a per-file cache cannot remove. The suite asserts the *work* instead, in CPU time on a denser
+  fixture: 1 046 ms against 48 ms, 21x, against a 3x floor.
+
+### What has no test, and why
+
+The last two are structural. The regex cache and the `fullContents` change have no behavioural
+signal — the output is byte-identical by construction — so they are covered by the existing suite
+and by the reasoning above rather than by a new test. The `--watch` cache is different: four of its
+five tests are correctness guards that pass on the previous build (that is the requirement — the
+cache must be invisible), and the fifth measures the CPU time the cache saves and fails without it.
+
+---
+
+## 0.9.13
+
+A fourth audit, this time of the seams: places where two code paths answer the same question with
+different rules, and places where a command accepts something it does not apply. Every item below
+has a test that fails without it, except one — the per-layer budget overflow, which I could not
+reproduce and which is called out honestly at the end.
+
+### A scoped snapshot could expire and still validate
+
+`validate` re-resolves the recorded changed-files scope and checks that every file it *skipped* as
+`unchanged` is still outside that scope. It never asked the mirror question. So:
+
+```bash
+git add src/a.ts
+codebase-snapshot generate --staged     # snapshot holds src/a.ts
+git reset HEAD src/a.ts                 # same bytes on disk, nothing staged
+codebase-snapshot validate --staged     # said: "Snapshot is valid and up to date"
+```
+
+The file on disk is byte-identical, so the hash comparison passed — and the scope the snapshot was
+taken over had silently become empty. A file that is in the snapshot and would not be if it were
+generated now is drift, and it is now reported, with `--with-dependents` still allowing for the
+one-hop importer exception.
+
+### A part name in `manifest.json` could reach any file on the host
+
+`validate` has confined part filenames since 0.9.9, but the **MCP server** resolved
+`parts[].filename` with a bare `path.resolve`, in `snapshot_read` and in the `snapshot://parts/{n}`
+resource. A repository under review could commit a manifest naming `../../../.env`, and a client
+would read it — resource reads are auto-approved as read-only. A part name is bare by construction,
+so `describeManifestShapeProblem` now requires one, which makes all five readers (`validate`,
+`report`, `diff`, `snapshot_read`, the resource) refuse the same manifest for the same stated
+reason.
+
+`snapshot_explain` had the mirror problem. `toRelativePath` resolved *after* its "is it absolute?"
+test and `normalizeTarget` returned anything starting with `..` unchanged, so `../other-repo/.env`
+was joined to the root and passed to `existsSync`: one read-only, auto-approved call per probe, for
+any path on the machine. Out-of-root targets now answer `outside-root` without touching the
+filesystem. A file named `..foo.ts` is no longer mistaken for a traversal.
+
+### Four credentials that looked like code
+
+- `password: "${DB_PASSWORD:-hunter2}"` — the shell and Compose idiom for a **default** — was
+  exempted as "an interpolation" because it starts with `${` and ends with `}`. So was
+  `${prefix}-real_secret-${suffix}` and any value with a `??` fallback. Only a value that is one
+  interpolation of a plain (optionally dotted) reference is exempt now; anything else in the braces
+  settles it the other way.
+- `export api_key=hunter2` — bare `export` was in `DECLARATION_KEYWORDS`, so a shell assignment was
+  read as a JavaScript binding whose initializer is an expression. `export` can never be followed by
+  a bare assignment in JS or TS (`export foo = 1` does not parse), so the word only ever suppressed
+  redaction for the files most likely to hold a secret.
+- An **indented, unterminated** private key — `privateKey: |` in YAML, or an indented template
+  literal — leaked every body line. The rule required base64 at column 0 and knew nothing about the
+  RFC 1421 header lines (`Proc-Type`, `DEK-Info`) that an encrypted key puts after the marker.
+- A masked key block in a **CR-only** file swallowed its line breaks, because pass 1 counted `\n`
+  only, so every reported line number after it was wrong.
+
+`.github/workflows/deprecate.yml` and `unpublish.yml` interpolated `${{ inputs.… }}` straight into
+`run:` in jobs that carry `NPM_TOKEN`. GitHub expands an expression into the script *before* bash
+parses it, so a dispatch input of `"; curl … $NODE_AUTH_TOKEN #` ran as a command. Inputs now arrive
+through `env:` and are referenced quoted.
+
+### Two enumerations, two answers
+
+The same repository produced different snapshots depending on `--discovery`, which is the one
+property a reproducible snapshot tool cannot have:
+
+- A tracked **file symlink** was dropped as `symlink` in `git` mode — the loop tested
+  `depth <= parts.length`, which includes the candidate itself — and emitted as a file by the walk.
+- A **broken** symlink was `symlink` in `git` mode, because `targetReal` started at the link's own
+  path and so always compared as "inside the root". It is `read-error`, or `outside-root` when its
+  written target leaves the tree, in both modes now.
+
+The output directory's crash leftovers had the same shape: the backup and partial-swap directories
+were recognised by the hardcoded prefix `snapshot.backup-`. With `outDir: ".context"` an interrupted
+run left `.context.backup-<pid>-<ts>` — a copy of the previous snapshot — to be scanned back in as
+user source. The names now come from the resolved output and staging directories. `--watch` also
+matched only `.backup-`, and only the directory itself, so an event for `part-001.md` *inside* a
+`.partial-` copy was treated as a source edit: on a cross-device swap that is an infinite
+regeneration loop.
+
+### The index described files that were not there
+
+- `summarizeMarkdown` called a leading `---` a front-matter block if *any* later line was `---`,
+  so a document opening with a horizontal rule and using another as a section divider lost every
+  heading between them. The block must now also *be* YAML — a heading, a fence or prose means the
+  `---` was a rule. `...` closes a YAML document as well as `---`.
+- The JSONC reader in `src/ast/structured.ts` ended a `//` comment only at `\n` and never removed a
+  trailing comma, so a `.jsonc` or an editor-reformatted `tsconfig.json` summarised as
+  `invalid-json` with no keys. Both are JSONC rather than extensions of it.
+- `summarizeTypeScriptSource` looked at `ImportDeclaration` and `ExportDeclaration` and nothing
+  else, so `require("./x")`, `import("./x")` and `import fs = require("fs")` produced no import
+  edge. A CommonJS project had no import graph at all, and `--with-dependents` had nothing to walk.
+  `export { a } from "./x"` was not recorded as a re-export either.
+
+### Flags that were accepted and not applied
+
+- `--only-artifacts audit` in a project whose config says `artifacts: { audit: false }` disabled the
+  other six and left audit off too: nothing written, exit 0. The flag was forwarded only as its
+  complement, and a suppression list cannot switch anything on.
+- `findConfigFile` parsed `package.json` with bare `JSON.parse` while the loader used the JSONC
+  reader, so a BOM or a trailing comma made the two disagree about whether the project was
+  configured. And `"snapshot": []` counted as this tool's configuration, which skipped the setup
+  question entirely.
+- `--skeleton` covered `.ts`, `.tsx`, `.mts` and `.cts` while `ts.createSourceFile` parses `.js`,
+  `.jsx`, `.mjs` and `.cjs` natively — so the files most repositories are made of were the ones it
+  could not compress, and `.d.ts` files, which have no bodies, were the ones it did parse.
+- Over MCP, `WorkspaceOverrides` accepted only `maxPartBytes` and `outDir`. `snapshot_validate`
+  re-derives the configuration and compares digests, so a `--skeleton` snapshot could not be
+  validated at all. `maxPartTokens`, `skeleton`, `sarif`, `changedSince`, `staged` and
+  `withDependents` are now accepted by `snapshot_plan`, `snapshot_generate`, `snapshot_validate`
+  and `snapshot_explain` — schema and application coming from one definition, so a tool cannot
+  advertise a flag it would ignore.
+- `npm create codebase-snapshot -- --preset=nextjs` ignored the preset: the shim parsed `argv` with
+  `indexOf`, which finds nothing for `--flag=value`, treats a missing value as "not given", and
+  ignores `--forse` entirely. `node:util.parseArgs` in strict mode now rejects all three by name.
+
+### Configuration answers that disagreed with each other
+
+- `loadConfigFileDetailed` did not attach `CONFIG_DIR_SYMBOL` — only `loadConfigFile` did — so
+  `resolveConfig((await loadConfigFileDetailed(dir)).config)` scanned `process.cwd()`.
+- `normalizeResolvedConfig` re-derived `artifacts` with `includeMonolith` as the default, so
+  `{ ...resolved, includeMonolith: true }` produced a config claiming `includeMonolith: true`
+  beside `artifacts.monolith: false`, and `generate` — which reads the map — wrote no monolith.
+- `configDigest` hashed `budgets` with `JSON.stringify`, which preserves insertion order, so
+  `{ docs, api }` and `{ api, docs }` produced different digests and `validate` reported drift for
+  a snapshot nobody changed.
+
+### Cost
+
+- `pathScanRules` returned `[...DEFAULT_SECRET_PATTERNS, ...extraRules]` although
+  `config.secretRules` already begins with those patterns: every file path, skip record and AST
+  summary string ran all 30 built-in rules twice. `disableDefaultPatterns` also had no effect on
+  paths while it worked on content.
+- `globToRegExp` and `matchGitignorePattern` compiled a fresh `RegExp` per call — over a million per
+  run on a 20 000-file repository with 55 patterns. Both are cached by pattern. A malformed
+  character class no longer escapes as a raw `SyntaxError`: a `.gitignore` range like `[z-a]`
+  matches nothing (which is what git's own `fnmatch` does), while the same range in a configured
+  glob is reported as the configuration mistake it is, naming the pattern.
+- `generateSnapshotAsync` resolved the configuration twice, and `validate` in the CLI re-read and
+  re-parsed `manifest.json` to re-run a shape check the validator had already run.
+- `pendingHooks` was drained only by `generateSnapshotAsync`, so a synchronous caller left one
+  settled promise per output directory for the life of the process.
+
+### Lifecycle
+
+- Each `hooks.afterGenerate` installed its own `process.stdout.write` wrapper and restored it only
+  if the current write was still its own. With two overlapping async hooks the first to finish never
+  restored, and the second put the first one's wrapper back — permanently. There is now one scope
+  and one wrapper, released by reference counting.
+- The update check used `request.setTimeout`, an *idle socket* timeout that resets on every chunk:
+  a trickling proxy kept the CLI alive indefinitely. It has a wall-clock deadline now, `.unref()`d
+  so a pending check never holds the process open. And `isNewer` stripped prerelease tags before
+  comparing, so `0.9.13-alpha.1` was recommended to everyone on a stable release and a stable
+  release was never announced to anyone on a beta.
+
+### Smaller
+
+- `wrapOneLine` measured `room` in terminal cells and cut with `String.prototype.slice`, which
+  counts UTF-16 code units. CJK text produced rows twice as wide as the frame believed, and a
+  surrogate pair could be cut in half. The cut advances by code point now.
+- Part numbering is decided **before** rendering, in one pass over every budget bucket, instead of
+  partitioning each budget and re-numbering the merged set afterwards.
+
+### What I could not reproduce
+
+The audit reported that per-layer budgets caused parts to overflow their budget by seven to twenty
+bytes when `renumberParts` rewrote their headers, and were then hard-clipped into a broken document.
+**I could not make that happen.** I swept file sizes against a two-budget configuration and again
+with six layers and eight kinds whose names are 180 characters long, and no part ever came out over
+its budget, with or without the clamp. The arithmetic explains why: `partitionFiles` reserves about
+2.2 kB of header room up front and shrinks sections to `budget - reserve`, so a rendered part sits
+roughly 1.4 kB below its ceiling, and the header growth being reported is fourteen bytes.
+
+The mechanism was removed anyway — the numbering pass now happens before rendering, so a fitted part
+cannot be rewritten — but the claim was not verified, and this changelog will not pretend it was.
+The four tests added with it pass on the previous build too; they pin the invariants the refactor
+must not break rather than reproducing a defect.
+
+## 0.9.12
+
+A third audit, this time of what the snapshot *costs* as well as what it gets wrong. Two of the
+defects were circular — `validate` demanded a flag it refused to accept — and one of them meant a
+config file could not turn a setting on at all. Every item below has a test that fails without it.
+
+### The parts were 32 000 tokens of duplicated metadata
+
+Each file section carried nine metadata bullets and, for a TS/JSON/Markdown file, a
+pretty-printed JSON summary of code that followed three lines later. On this repository — 234
+files — that was **195 619 bytes, about 32 600 tokens, 12 % of the snapshot**, spent on a
+`SHA-256:` line per file and on listing every variable and export immediately above the code that
+declares it.
+
+A section is now an anchor, a heading and one line:
+
+```text
+- Meta: src/other | typescript | full | 3 lines (63 B)
+```
+
+- The per-file `SHA-256` is **gone from the parts** and stays in `manifest.json`, which is the file
+  a machine reads. `snapshot_read` used to fall back to it when a path was too long for the
+  heading; it now matches the `<a id>` anchor, which is a digest of the exact `relativePath` and was
+  already there — exact even for the 300-character paths the heading caps.
+- The structural summary is **not printed for a `full` file**: `manifest.json` keeps it, and
+  `preview` and `signatures` sections keep it, because there the body is not the file. A one-line
+  string summary survives either way.
+- `- Content Fingerprint:` stays in the part header (~22 tokens per part), which anchors an answer
+  to a verifiable state of the repository.
+
+Nothing else about the format moved, so `snapshot_read` and both structural parsers still read it.
+
+### `validate` refused the flag its own comparison needed
+
+`manifest.config.digest` hashes `skeleton`, `sarif`, `maxPartTokens`, `changedSince`, `staged` and
+`withDependents`, and `validate` compared that digest — but `COMMAND_OPTION_SCOPE` allowed those six
+flags on `generate` only. So a snapshot generated with `--skeleton`:
+
+1. failed `validate` with "the settings differ from the ones this snapshot was generated with", and
+2. failed `validate --skeleton` with "`--skeleton` does not apply to validate".
+
+There was no way to validate it. `validate` now accepts all six, `explain` accepts the three that
+decide its answer, and `report` accepts none: it reads the manifest and prints what is there, so a
+generation setting would change nothing.
+
+### A config file could not turn these four settings on
+
+`parseArgs` returned `skeleton: values.skeleton === true`, so a run that did not pass the flag sent
+**`false`** — and `resolveConfig` reads these as `cliOptions.x ?? config.x`, where `false` is an
+explicit override. `skeleton: true` in `snapshot.config.ts` was silently turned off by every run
+that did not repeat the flag on the command line. The same applied to `staged`, `withDependents`
+and `sarif`. All four are now `undefined` when the flag is absent.
+
+### `explain` and `validate` ignored `--with-dependents`
+
+The generator widened a changed-files scope by one hop of importers; both readers compared the raw
+path set. A file that was **in** the snapshot because it imported something that changed was
+explained as `included: false, reason: "unchanged"`, and `validate` called the snapshot current
+while a file it should contain was missing from it. The import graph moved to
+`src/scanner/dependents.ts` so all three apply one rule, and `validate` now re-parses a recorded
+`unchanged` skip only when the manifest says the run used `--with-dependents`.
+
+### `setup` wrote a config its own snapshot did not match
+
+`setup --discovery walk --large-file-bytes 100000` forwarded both flags to the generation it runs
+and wrote the defaults into the config beside it, so a brand-new project's one-command setup
+finished with a snapshot that `validate` immediately called drifted — three configuration
+mismatches on the first run. `--max-part-tokens`, `--skeleton` and `--sarif` are now accepted by
+`setup` too, and every one of them is written into the generated config as well as forwarded.
+
+### Redaction that corrupted what it protected
+
+Three shapes were found in this repository's own snapshot, where the tool rewrote its own
+documentation and tests:
+
+- **Prose.** `credential-assignment-unquoted` masked any word after `secret: ` or `token: `, so
+  `indistinguishable from a secret: a` became `…from a secret: [REDACTED…]`. An unquoted value in a
+  line-oriented format never continues after a space (`PASSWORD: hunter2` ends the line; `secret: a
+  value` is a sentence), and a one-character bare value is not a credential. Quoted values keep
+  their one-character floor — quotes are evidence somebody meant to write a value.
+- **Template literals.** `` `… an empty token: "${appliesTo}"` `` had the interpolation masked,
+  because `startsInsideStringLiteral` only looks at the character before the identifier. A value
+  that is entirely `${…}` is an expression, so it is not masked.
+- **Doubly-escaped quotes.** `JSON.parse('{"password": "p@\\"ssw0rdINVENTED"}')` — how every
+  fixture that embeds JSON is written — emitted `"[REDACTED…]"ssw0rdINVENTED"`: a fragment of the
+  credential in clear and a line that no longer parses. A quote after `\\` that is followed by a
+  value character is an escaped quote in a deeper literal, and the value now runs to the real close.
+
+### An async `afterGenerate` hook's files were not recorded
+
+The hook is documented as the way to write your own artifact into the snapshot directory, and that
+directory is only replaceable while `.codebase-snapshot` accounts for every file in it. Only the
+*rejection* path re-shipped the marker, so an async hook that succeeded left its file unrecorded
+and the next `generate` refused the directory as foreign. The marker is now re-shipped when the
+hook settles either way, and only while it still records this run — the lock is released when
+`generateSnapshot` returns, so a slow hook can outlive the snapshot it belongs to.
+`generateSnapshotAsync` now awaits the hook, so a caller of the async API gets control back when
+the snapshot is actually finished.
+
+### Smaller fixes
+
+- **`getGitInfo` used Node's 1 MB `maxBuffer`** where every sibling call passed 32 or 50 MB. On a
+  repository with enough dirty entries, `git status` overflowed, threw, and the `catch` returned
+  `isDirty: false` — reporting the dirtiest possible tree as clean. The limit is raised and shared,
+  and an overflow now reports `isDirty: true`, because a buffer that large only fills when there is
+  a great deal to report. All three git invocations use `execFileSync` instead of a shell string.
+- **`.gitignore` character classes** were escaped as literals, so `*.[oa]`, `[Tt]humbs.db` and
+  `log[0-9].txt` matched nothing in `--discovery walk` while working in `git` mode.
+- **A layer or kind rule** was glob-translated only when it contained `*` or `?`, so
+  `src/{api,web}/index.ts` fell through to a substring search and classified nothing; and a plain
+  pattern like `test` used `String.includes`, so it matched `src/contest/a.ts`. Both now go through
+  `matchesExclude`, which is the single implementation of "does this pattern select this path".
+- **`export { handler as GET }`** and `export { GET } from "./handlers"` recorded the export but no
+  route method, so those App Router routes had no `methods` in `manifest.indexes.routes`.
+  `export default () => <div />` recorded no component for the same reason.
+- **The last-resort clip** reserved room for its own truncation marker but not for the token count
+  rewritten afterwards, so a part clipped to exactly its budget came back over it. `rehashPart` also
+  estimated tokens from text that still carried the *old* number, unlike every other part.
+- **Seven MCP tools ignored `outDir`**, so a snapshot generated into a custom directory could be
+  written by `snapshot_generate` and inspected by nothing.
+- **`snapshot_read`** replaced the line range with the preview note instead of adding to it, so a
+  window into a preview came back with no `Lines X–Y of Z` at all; `signatures` was treated as a
+  full file.
+- **Every published file ended with a `sourceMappingURL`** pointing at a `.map` that
+  `package.json#files` deliberately does not ship. The build no longer emits them.
+- **`--watch` crashed on Node 18 on Linux**, where `fs.watch(cwd, { recursive: true })` does not
+  exist before Node 20.13. The package declares `engines: >=18`, and the run wrote a snapshot,
+  printed "Watching for changes", and *then* threw `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. It is now
+  refused up front, with exit `2` and a message naming the version that works — and before anything
+  is written. A watcher that cannot start for any other reason (`ENOSPC`, the Linux inotify limit)
+  reports it as a message instead of a stack trace, and the snapshot it already wrote stays valid.
+  Found by the release's own Node 18 job: 0.9.10 and 0.9.11 never ran one.
+
+---
+
+## 0.9.11
+
+A second audit, run against 0.9.10's own output, found that several defects the previous release
+believed it had fixed were still reachable, that the changed-files scope was applied one layer too
+late, and that this repository's documentation had been quietly corrupted. Every item below is
+fixed with a test that fails without it.
+
+### The redactor was still editing the program
+
+`credential-assignment-unquoted` exists for `.env`, YAML and compose files, where everything after
+`NAME=` is a literal. In a source file the same shape is an **expression**. The bug is visible in
+the 0.9.10 snapshot itself, in `parts/part-005.md`:
+
+```
+const SINGLE_TOKEN = [REDACTED: potential secret-like value omitted from snapshot][^\sA-Za-z0-9_]/g;
+```
+
+The regex literal's opening `/` was a legal match for `UNQUOTED_LITERAL`, so the pattern was
+deleted and the line no longer parses — data loss in the artifact whose whole purpose is to
+describe the code. Three changes close the class rather than the instance:
+
+- an unquoted value must **begin** with a word character, so `/`, `+`, `-` and `%` can only
+  continue one;
+- a value followed by `[`, `{` or `(` is refused, because `const accessToken = tokens[0]` is a
+  reference;
+- a value that sits in a **declaration** is never a literal. `const`, `let`, `var`, `readonly`,
+  `private`, `protected`, `static`, `declare`, `export` and `using` are recognised, walking back to
+  the start of the identifier so the tail match (`TOKEN` inside `SINGLE_TOKEN`) is covered too.
+
+The guard is bounded to a 40-character window: an unbounded version made a 236 KB line with 4,000
+assignments cost 2.7 s, which the existing quadratic-scan test caught.
+
+### A changed-files scope was applied after the scan instead of before it
+
+`--changed-since` and `--staged` read, decoded, secret-scanned and TypeScript-parsed every file in
+the repository and then threw all but a handful away. Because every aggregate was bumped inside
+that scan, the snapshot inherited the repository's numbers:
+
+- **`validate` failed on every scoped snapshot.** Unchanged files are recorded in `skipped[]` with
+  reason `unchanged`, and `validate` then asked `wouldNowBeIncluded` about them — a question that
+  only answers "is this text?" — so every unchanged source file was reported as `new file:` and
+  the exit code was 1.
+- **`manifest.layers`, `manifest.kinds`, `counts.largeFileCount`, `totals.redactedLines`** and the
+  encoding/preview/parse warnings all described files the snapshot did not contain. A two-file
+  snapshot reported the layer distribution and the secret count of the whole repository.
+- **`explain` ignored the scope entirely** and answered `included: true` for exactly the files
+  `generate` was skipping.
+
+The scope is now resolved once, before the scan, and applied to the candidate list whenever
+`--with-dependents` is not in play. The dependents case still has to scan first — it needs every
+file's imports — so it narrows afterwards and recomputes the counts, the findings and the warnings
+from what survived.
+
+### `--with-dependents` walked the import graph transitively
+
+The closure tested `keep.has(resolved)` while adding to `keep`, so `a.ts` changed pulled in
+`b.ts` (which imports it) and then `c.ts` (which imports `b.ts`). Whether a two-hop file was
+included depended on whether its name sorted after `b.ts`: the same repository produced different
+snapshots depending on file names. The test is now made against the changed set, which makes the
+closure exactly one hop.
+
+### Root-anchored `.gitignore` rules never matched in `walk` mode
+
+`readGitignoreRules` keeps the leading `/`, and the matcher it was handed compares against a path
+with no leading slash — so `/build` could not equal `build`, could not prefix `build/x`, and could
+not appear between two slashes. `/secret-notes.txt` silently kept its file in the snapshot.
+
+The same delegation made the opposite mistake one segment down: gitignore(5) anchors a pattern
+containing a non-trailing `/` to the directory holding the `.gitignore`, so `doc/frotz` ignores the
+top-level one only, while `matchesExclude` matched `a/doc/frotz` as well. Both are fixed by using
+the gitignore matcher (which already implemented `anchored || body.includes("/")`) for every rule
+rather than only for rules containing a backslash. `matchesExclude` is left to configuration
+excludes, where "match at any depth" is the documented behaviour.
+
+### Spreading a resolved config with a new `maxPartBytes` changed nothing
+
+`{ ...resolved, maxPartBytes: 64 * 1024 }` still satisfies `isResolvedConfig`, and
+`normalizeResolvedConfig` kept the **old** `budgets` object. The partitioner reads
+`budgets.default`, so the run produced 300 KB parts and the manifest recorded the 64 KB that was
+ignored. `normalizeResolvedConfig` now normalises `budgets` against `maxPartBytes`, capping
+per-layer budgets rather than replacing them.
+
+A related inconsistency is fixed too: a config that sets only `budgets: { default: "100k" }`
+recorded `maxPartBytes: 300k`, so one snapshot described two different budgets.
+
+### Smaller fixes
+
+- **The MCP worker URL was built with string interpolation.** `file://${path}` turns a Windows path
+  into `file://C:/…` whose *host* is the drive letter, reads a `#` as a fragment and a `%` as an
+  escape. It uses `pathToFileURL` now, through an exported `workerEntry()`.
+- **`--sarif` and the monolith disagreed.** The log was rendered in the write phase, so
+  `full-codebase.json` embedded a manifest with no `artifacts.sarif` while `manifest.json` had one.
+  The log is rendered before the monolith is serialised.
+- **`validate` never checked `reports/audit.sarif`** against its recorded digest. It does now: a
+  security report uploaded to a third party is exactly the artifact that must be verified.
+- **`--sarif` was missing from `configDigest`**, so two runs that write different directories
+  compared equal.
+- **`--skip-artifacts … --sarif` claimed nothing was written** while writing `reports/audit.sarif`.
+- **SARIF rule ids were positional.** They were handed out by position in the sorted set of rule
+  names a run happened to use, so adding one custom rule that sorts before the built-ins
+  (`acme-key` does) shifted every built-in id by one and re-pointed every open alert. Built-in
+  rules now take a fixed id from their declaration order and custom rules get an id hashed from
+  their own name. This renumbers the built-ins once, relative to 0.9.10, and never again.
+- **`generate --watch` generated twice on startup** — `runCommand` generated, then the loop
+  generated again before any file changed.
+- **`--watch` froze `outDir`/`tmpDir` at startup.** After the config moved them, the watcher saw
+  its own output as user content and regenerated without end.
+- **The pre-commit hook hardcoded `snapshot/`**, so a project with `outDir: ".context"` got a hook
+  that printed "no snapshot found, skipping" and exited 0 on every commit — a gate that never ran.
+  The directory is baked in at install time, and the guard tests `manifest.json` rather than the
+  directory (a directory left by a failed run exists but holds no snapshot).
+- **`--max-part-tokens 200` was silently raised** to the 1024-token floor. It is a usage error
+  now, and the message talks about tokens rather than bytes.
+- **The MCP line cap was bypassed** by an oversized line that arrived complete with its terminator,
+  because the guard required the buffer to hold no `\n` at all. The cap now applies to every
+  complete line.
+- **`snapshot_locate` searched only half the summary.** `variables` (where a `const`, a Python
+  constant, a Go `var`, a Rust `mod`, a C `#define` and a Terraform `variable` all land),
+  `directives`, `frontmatterKeys` and JSON `keys` are searched too.
+- **`snapshot_read` printed `Lines 1–0 of 1` for an empty file** and returned the *last* line when
+  `fromLine` was past the end. Both are stated instead.
+- **`.TSX` was parsed as `ScriptKind.TS`** — `isSkeletonizable` lowered the name and
+  `skeletonizeTypeScript` did not.
+- **Markdown summaries:** an unclosed `---` at line 0 swallowed every heading, a shorter fence
+  inside a longer one closed it early, and a closing fence with an info string was accepted. All
+  three follow CommonMark now.
+- **Destructured exports were invisible.** `export const { a, b } = obj` and
+  `export const [first] = pair` declare real exports and were dropped by an
+  `isIdentifier` check.
+- **`rehashPart` left `estimatedTokens` at its pre-clip value** after `enforceBudget` cut a part,
+  and the part's own header kept stating the old number. Both are recomputed.
+- **`setup --preset <unknown>` exited 1** where `init` exits 2, because the parse-time check was
+  written for `init` only.
+- **`describe` omitted all seven 0.9.10 flags and six config keys.** `describe` is the contract an
+  agent reads instead of the docs, so this is the failure that matters most: the options simply did
+  not exist as far as a machine consumer was concerned. A test now compares `CLI_OPTIONS` and
+  `CONFIG_KEYS` against the contract in both directions.
+- **`--changed-since` was passed to git as a positional revision.** A ref beginning with `-` is now
+  refused before git sees it, and `--` separates revisions from paths.
+- **`--skeleton --include-monolith` labelled a body-stripped file `inclusionMode: "full"`.** The
+  monolith now keeps the full redacted body, so the label is true.
+
+### Documentation and repository hygiene
+
+- **Three sentences had letters eaten by interpreted escapes**: `\v` in "Validate", `\r` in
+  "reports/", `\a` in "audit.md". A test now fails on any control byte in any tracked text file.
+- **Four documents claimed the MCP server serves seven tools.** It serves eight. The count is now
+  compared against the live tool list.
+- **`publish:create` could not run.** `npm publish packages/create` is parsed by npm as the GitHub
+  shorthand `ssh://git@github.com/packages/create.git` and fails with exit 128; it names
+  `./packages/create`.
+- **`check-site-links` accepted a sibling directory.** `resolved.startsWith(SITE)` is true for
+  `../site-other`; the check requires the path separator.
+
+---
+
+## 0.9.10
+
+An audit of this codebase, run against its own snapshot, found twenty defects, six performance
+problems and seven missing capabilities. This release is all of them: every defect, every
+performance problem and every capability named in that audit is in the tree, with a test that
+fails without it.
+
+### Redaction was corrupting the code it exists to preserve
+
+The worst defects were in the secret scanner, and the evidence was in this repository's own
+snapshot. Four false-positive classes rewrote valid statements:
+
+- `[:=]` matched the first `=` of `===`, and the unquoted-value rules then read the remaining `==`
+  as a credential. `clause.token === ts.SyntaxKind…` shipped as `clause.token =[REDACTED…]`, and so
+  did `if (token === "--")`.
+- `env-secret-assignment` carried `/i`, so an indented reassignment matched: `key =
+  fs.realpathSync(stagingRoot)` was emitted with the call masked.
+- Credential names are matched as a *tail* — that is what catches `dbPassword` — so a name inside a
+  string literal matched, and the string's closing quote was taken as the value's opening quote.
+  `["awsSecret:", "apiKey:"]` came out with two list elements welded together.
+- `progressToken: "progressToken"` was masked as a credential. A camelCase value that spells its
+  own key is a symbol-table entry, not a secret.
+
+Reserved words are no longer credential literals either: `token = await refreshToken(client)` was
+emitted as `token = [REDACTED] refreshToken(client)`.
+
+### Scanning no longer depends on state outside the tree
+
+- A `.gitignore` rule naming a nested directory (`public/build/`) never matched in `walk` mode: the
+  candidate was reduced to its first path segment, which cannot equal a two-segment rule. The same
+  bug dropped a regular *file* named `build` for a `build/` rule.
+- How files are enumerated was held in a module-level variable written by `resolveConfig`, so two
+  scans in one process could disagree, and the second inherited the first one's mode.
+- `validate` did not exclude the tool's own output directory, so it counted `snapshot/` as files
+  missing from the snapshot and reported a correct snapshot as drifting.
+- `findSecretInPath` compiled thirty-plus `RegExp` objects per call, and it runs on every path and
+  every string in every summary.
+- `getGitInfo` spawns one `git status` instead of three `git` processes.
+
+### The config digest now covers what decides a snapshot
+
+Layer and kind *names* were hashed, not their matchers, so moving a layer from `src/api/**` to
+`src/v2/**` produced an identical digest and `validate` said "valid and up to date" for a snapshot
+whose files had all been reclassified. A rule's `flags` and `valueGroup` were missing too, and so
+was `discovery`. `package.json`'s `"snapshot"` object now gets the unknown-key guard every other
+config file already had, and `secretRules` is accepted in a config file as it already was in code.
+
+### `setup` stops dropping the flags it was given
+
+`setup` builds the inner `generate` command line by hand, and five settings were never copied into
+it, so the run reported one configuration and generated with another. It also refused
+`--discovery`, `--large-file-bytes`, `--max-monolith-bytes` and `--include-monolith` outright.
+`--only-artifacts monolith` enabled *nothing*: it turns the six default artifacts off and relied on
+the monolith switch to turn the seventh on, and neither `init` nor `setup` passed that switch along.
+
+### Part budgets say what they enforce
+
+- Every part records the budget it was built for. With per-layer budgets, verification compared
+  each part with the *largest* budget in the run, so a part twice over its own layer budget passed.
+- `renumberParts` rewrites headers, so the byte bound is re-applied after renumbering.
+- A body cut twice reported only the second cut: a 1,000-line file reduced to a preview and then to
+  ten lines said "11 lines omitted", because the count came from the preview instead of the file.
+- Every part states its size in **tokens**, and `--max-part-tokens 32k` sets a ceiling a context
+  window can be measured against. The estimate's method is documented, not hidden.
+
+### Crash-proof locks, byte-accurate reads
+
+- A run killed between creating its lock file and writing its pid leaves a zero-byte lock that
+  named nobody, so `lockOwnerIsGone` answered "not gone" forever and every later run refused to
+  start until the file was deleted by hand. Age is now the fallback evidence.
+- `snapshot_read` truncated to its byte limit by slicing UTF-16 code units, returning up to three
+  times the limit for multibyte text and able to split a surrogate pair.
+- `snapshot_locate` could not find a symbol a file does not export — most of the code in most files
+  — and could not find a Markdown heading at all. Layer and kind matched by exact equality while
+  every other category used a substring.
+- `findSection` compared a heading with the manifest's raw path, which differ once the heading has
+  been capped or escaped; such a file became unreadable whenever another file shared its content.
+- A watch loop had no `error` listener on `fs.watch`, so an `EPERM` or an inotify limit killed the
+  process instead of being reported.
+- The update check skipped itself when any argument contained "json", so `explain package.json`
+  never asked.
+
+### Fewer syscalls
+
+`generate` read every included file twice — a chunked NUL scan, then a full read and a second scan
+of the same bytes. Below the 8 MB scan cap the decode is the complete check on bytes that had to be
+read anyway, so the pre-scan is kept only above it. `explain` and `validate` had the same double
+read.
+
+### New structure for six more languages
+
+Swift, Dart, SQL, GraphQL, Protobuf and Terraform now have profiles. `src/scanner/language.ts`
+already knew four of those extensions by name and no profile claimed them, so a repository in one of
+those languages got a list of files and no idea what was inside them.
+
+### The site keeps its own links
+
+`README.md` writes absolute GitHub URLs so the same text works on npmjs.com; the site builder only
+rewrote *relative* links, so a reader on the docs site who clicked a guide link on the homepage was
+handed back to GitHub. In-repo links to published pages are rewritten now; other repositories and
+files the site does not publish are left alone.
+
+### Also
+
+- `configDigest`, `classifyLayer`, `classifyKind`, `displayPath`, `lockPathFor`, `estimateTokens`,
+  `findSecretInPath` and `getGitInfo` are exported.
+- `manifest.config` records `maxMonolithBytes` and `maxPartTokens`.
+- `scripts/sync-docs.mjs` propagates `package.json#version` to `src/version.ts` and
+  `packages/create/package.json`, so a release cannot drift by forgetting a file. `--check` covers
+  them.
+- `scripts/pack-check.mjs` requires the MCP build outputs, and the three wizard test files share one
+  fake-TTY harness.
+
+### `snapshot_dependents`: the import graph, in both directions
+
+`manifest.indexes.imports` already held enough to answer "what uses this file" —
+`byFile` records every specifier, `centralFiles` ranks the most-imported files — but nothing
+an agent could ask. So the one question that decides what to read next, *what breaks if I
+change this?*, was answered by reading parts until the picture appeared.
+
+The eighth MCP tool takes a path and a direction and returns both edge sets with the part each
+neighbour lives in, plus the specifiers that resolve to nothing inside the snapshot
+(`node:fs`, a package name) rather than silently dropping them. Resolution runs through the
+generator's own `buildImportResolver`, so the tool and `centralFiles` cannot describe different
+graphs — a test asserts the counts agree.
+
+### `--install-hook` gates commits on `validate`
+
+`docs/stale-context-is-your-bug.md` argues a snapshot is only trustworthy when something gates
+on it, and `validate` is that gate — but wiring it into `.git/hooks` was thirty seconds of
+manual work, which is the step a project skips. `init --install-hook` and `setup --install-hook`
+write `.git/hooks/pre-commit`, which refuses a commit whose snapshot is stale and never installs
+anything while doing it.
+
+A `pre-commit` this tool did not write is left byte-for-byte alone, and the output names the line
+to add instead: there is deliberately no flag to force the overwrite. A `.git` that is a *file*
+(a worktree or submodule) is followed to the real git directory rather than failing with
+`ENOTDIR`.
+
+### `--changed-since` and `--staged`: review packs the diff
+
+Reviewing a pull request with a model is the case this exists for: the diff is small, the
+repository is not, and packing all of it costs a context window to answer a question about four
+files.
+
+`--changed-since <ref>` is the working tree against that ref — committed, staged and unstaged
+changes all count, because all three are what a reviewer is looking at — **plus untracked
+files**, which `git diff` never lists and which are exactly what a new feature starts with.
+`--staged` is the index against `HEAD`, and `--with-dependents` adds the one-hop importers,
+which is the context needed to change a file safely rather than merely the file that moved.
+
+Files outside the scope are recorded in `skipped[]` with a new reason, `unchanged` —
+deliberately not `excluded`, which means the user's own glob rejected the path. Every failure is
+loud: an unknown ref, a directory that is not a git repository, and `--with-dependents` without
+a scope are all errors naming the way out, because a ref typo that produced an empty snapshot
+would read as "this change touched nothing".
+
+### `--skeleton`: signatures instead of bodies
+
+`docs/vs-repomix.md` concedes that a compression mode beats byte budgeting for a repository too
+large to fit at all. This is that mode, built on the compiler that is already the one runtime
+dependency: each function, method, constructor, accessor and arrow body becomes `{ /* ... */ }`
+in place.
+
+The rewrite is span-based rather than a `ts.createPrinter()` re-print, and that is the whole
+feature — a printer normalises quotes, blank lines and comment positions, so a skeleton would
+differ from its source everywhere instead of only where bodies were removed. Affected entries
+carry `inclusionMode: "signatures"`, and the structural summary still describes the whole file.
+
+### `--sarif`: the findings a CI gate can read
+
+`reports/audit.md` tells a human what was masked, and nothing could *gate* on it: a CI job that
+wanted to fail a build over a leaked key had to scrape markdown. `--sarif` writes
+`reports/audit.sarif` in SARIF 2.1.0, which is what GitHub Code Scanning reads.
+
+The artefact is deliberately austere: path, line, level and rule — and **never the value**,
+because it is meant to be uploaded to a third party and a second copy of a secret in someone
+else's retention policy is a new problem rather than a report on the old one. Rule ids are
+stable across runs so an alert is not orphaned, and each result carries a
+`partialFingerprint` so Code Scanning keeps an alert open instead of closing and reopening it
+on every run.
+
+### `snapshot_generate` runs off the JSON-RPC thread
+
+The 0.9.4 measurement stands: a synchronous generate blocks the stdio server for about 7.5
+seconds on a 3,000-file repository. In that window the process cannot answer `ping` or
+acknowledge `notifications/cancelled`, and a client with a socket timeout reports a working tool
+call as a dead server.
+
+The work moves to a worker thread. A resolved config cannot cross a thread boundary —
+`layers[].match` may be a function and `hooks.afterGenerate` always is — so the worker loads
+the config file and applies the same CLI options the calling thread did, rather than receiving
+values that would all look like explicit overrides. A worker that fails to start, exits without
+posting, or throws is reported as a tool failure naming the reason; there is no quiet retry on the
+calling thread, because that would hide exactly the condition this exists to avoid.
+
+One consequence is documented rather than discovered: `hooks.afterGenerate` does not run for a
+generation started from MCP, only for a CLI `generate`.
+
+---
+
 ## 0.9.9
 
 ### `snapshot -version` now answers the question it was asked