codebase-snapshot 0.9.8 → 0.9.12

package/CHANGELOG.md

@@ -21,6 +21,542 @@ 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.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
+
+Reported from a real terminal, by someone trying to find out which version they had:
+
+```
+> snapshot -version
+❌ Unknown option '-e'. To specify a positional argument starting with a '-', place it at the
+   end of the command after '--', as in '-- "-e"'
+```
+
+That message came from `node:util.parseArgs`, which reads `-version` as the short-flag cluster
+`-v -e -r -s -i -o -n` and objects to the third character. It names something the caller never
+typed, and it buries the actual mistake — one dash where two belong — which is exactly the
+information a usage error exists to give.
+
+Every token of that shape is now caught before the parser sees it and answered as a spelling
+problem:
+
+```
+❌ Unknown option '-version'. Options start with two dashes — did you mean '--version'?
+```
+
+`-cwd`, `-help`, `-format` and `-dry-run` get the same treatment with their own long form
+suggested. A token that is not an option at all (`-frobnicate`) is told to go after `--` instead of
+being pointed at a `--frobnicate` that does not exist, and a cluster of short flags that *are* real
+(`-vh`) still works.
+
+### The update notice suggests the command that fits this copy
+
+It said `npm install -g codebase-snapshot` to everybody, which is wrong for two of the three ways
+people run this. `setup` deliberately adds the package as a **devDependency**, where `-g` installs a
+second global copy that shadows the pinned one; an `npx` invocation is a cache entry that the next
+`@latest` run replaces by itself.
+
+The suggested command is now derived from the path Node is running: `-g` for a global install,
+`npm install codebase-snapshot@latest` for a dependency of the project being worked in (npm rewrites
+the entry where it already is, so a devDependency stays one), and `npx -y codebase-snapshot@latest`
+for npx. The classification is `_npx` in the path for the cache, and `node_modules` under the
+working directory for a local dependency — evidence rather than a guess.
+
 ## 0.9.8
 
 ### A wrapped menu no longer changes height under the cursor

package/README.md

@@ -200,13 +200,13 @@ Everything an agent needs is available as data, and the tool can install its own
 ```bash
 npx codebase-snapshot describe --format json   # contract: workflow, options, exit codes
 npx codebase-snapshot skill --install          # into .claude/skills + .cursor/rules
-npx -y codebase-snapshot@0.9.8 mcp             # or serve it over MCP
+npx -y codebase-snapshot@0.9.12 mcp             # or serve it over MCP
 ```
 
 An agent told only "use `npx codebase-snapshot`" can read the contract, follow its ordered
 workflow, and produce a validated snapshot unaided — that path is covered by a test.
 
-The MCP server exposes seven tools — status, plan, generate, validate, locate, read, explain — plus
+The MCP server exposes eight tools — status, plan, generate, validate, locate, dependents, read, explain — plus
 `snapshot://` resources and two prompts. Its reads come from the snapshot rather than the working
 tree, so an excluded file stays excluded and a redacted value stays redacted, and
 `snapshot_validate` answers the question an agent otherwise cannot ask: is the context I was given
@@ -260,7 +260,7 @@ others.
 | [Configuration](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/configuration.md) | Every setting, all 25 presets, budgets, hooks, secrets |
 | [Snapshot output](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/output.md) | Directory layout and the full manifest schema |
 | [AI agents](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/agent.md) | The contract, the skill, what an agent should avoid |
-| [MCP server](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/mcp.md) | Seven tools, resources, both protocol eras |
+| [MCP server](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/mcp.md) | Eight tools, resources, both protocol eras |
 | [Troubleshooting](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/troubleshooting.md) | Every message and what to do about it |
 | [Changelog](https://github.com/ankurhalder/codebase-snapshot/blob/main/CHANGELOG.md) | Release history and breaking changes |