codebase-snapshot 0.9.9 → 0.9.14

package/dist/index.d.ts

@@ -1,5 +1,12 @@
-import { S as SecretRule, D as DiscoveryMode, a as SkipRecord, J as JsonSummary, M as MarkdownSummary, b as SourceSummary, R as ResolvedSnapshotConfig, c as SnapshotConfig, B as ByteSize, C as CliOptions, F as FileEntry, P as PartMetadata, L as LayerRule, K as KindRule, T as TextEncoding, d as SecretFinding, V as ValidationResult, e as Manifest, A as ArtifactSelection } from './types-Ca4PmkiQ.js';
-export { f as BudgetConfig, H as HooksConfig, I as InclusionMode, g as ManifestArtifact, h as ManifestConfigSnapshot, i as ManifestIndexes, j as ManifestTotals, k as Mode, O as OutputFormat, l as PartFileEntry, m as ResolvedArtifacts, n as ResolvedBudgets, o as SecretRuleInput, p as SkipReason, q as SummaryQuality, r as ValidationDrift } from './types-Ca4PmkiQ.js';
+import { S as SecretRule, D as DiscoveryMode, a as SkipRecord, J as JsonSummary, M as MarkdownSummary, b as SourceSummary, K as KindRule, L as LayerRule, R as ResolvedSnapshotConfig, c as SnapshotConfig, B as ByteSize, C as CliOptions, P as PartMetadata, F as FileEntry, T as TextEncoding, d as SecretFinding, V as ValidationResult, e as Manifest, A as ArtifactSelection } from './types-DIX6zWSt.js';
+export { f as BudgetConfig, H as HooksConfig, I as InclusionMode, g as ManifestArtifact, h as ManifestConfigSnapshot, i as ManifestIndexes, j as ManifestTotals, k as Mode, O as OutputFormat, l as PartFileEntry, m as ResolvedArtifacts, n as ResolvedBudgets, o as SecretRuleInput, p as SkipReason, q as SummaryQuality, r as ValidationDrift } from './types-DIX6zWSt.js';
+export { w as workerEntry } from './generate-worker-D_mUjgXw.js';
+
+interface GitInfo {
+    branch: string;
+    commit: string;
+    isDirty: boolean;
+}
 
 interface CollectOptions {
     /**
@@ -39,7 +46,23 @@ interface CollectResult {
     files: string[];
     skipped: SkipRecord[];
 }
+declare function getGitInfo(cwd: string, fallbackBranch?: string): GitInfo;
 declare function isSensitivePath(relativePath: string): boolean;
+/**
+ * Reports a secret-shaped value in a *path*.
+ *
+ * File names are emitted verbatim into `project-tree.md`, `navigation.md`,
+ * `manifest.files[].relativePath`, the `## Skipped` table of the audit and
+ * `skipped[].path`, so a token in a name leaks exactly like a token in a body —
+ * and content redaction never sees it.
+ *
+ * `extraRules` are the caller's custom patterns. A `valueGroup` rule is masked
+ * whole here: a path has no `key: value` context to anchor on.
+ */
+declare function findSecretInPath(relativePath: string, extraRules?: readonly SecretRule[]): {
+    rules: string[];
+    masked: string;
+} | null;
 /**
  * Translates a glob (`**`, `*`, `?`, `{a,b}`, `[abc]`) into a RegExp. A pattern
  * without a leading `/` matches at any depth, mirroring `.gitignore` semantics.
@@ -47,6 +70,12 @@ declare function isSensitivePath(relativePath: string): boolean;
  * Brace groups and character classes are supported because they are what people
  * actually write: `*.{ts,tsx}` previously matched nothing at all, since `{` and
  * `}` were escaped as literals.
+ *
+ * Compiled once per distinct pattern. `matchesExclude` calls this for every
+ * (file, include), (file, exclude), (file, layer rule) and (file, kind rule)
+ * pair, so a 20 000-file repository with 55 patterns compiled over a million
+ * identical RegExp objects per run. The result is a pure function of the string,
+ * so the cache cannot change an answer.
  */
 declare function globToRegExp(glob: string): RegExp;
 /**
@@ -67,9 +96,19 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 /**
- * Strips `//` and block comments the way JSONC does, without touching anything
- * inside a string literal. `JSON.parse` alone made every `.jsonc` file report
- * `invalid-json`, losing its key shape entirely.
+ * Strips `//` and block comments the way JSONC does, plus trailing commas, without touching
+ * anything inside a string literal.
+ *
+ * `JSON.parse` alone made every `.jsonc` file — and every `tsconfig.json` an editor had
+ * reformatted — report `invalid-json`, losing its key shape entirely. Two things this file's
+ * matcher did that `src/config.ts`'s did not, and both are JSONC, not extensions of it:
+ *
+ * - **Trailing commas.** `{ "a": 1, }` is valid JSONC and invalid JSON.
+ * - **`\r`-only line endings.** A `//` comment ended only at `\n`, so on a CR-delimited file it
+ *   swallowed everything to the end of the document.
+ *
+ * A block comment keeps the line breaks it spans. Dropping them renumbered every line after it,
+ * and the only thing a reader has to place a summary key is the line number.
  */
 declare function stripJsonComments(content: string): string;
 declare function summarizeJson(content: string): JsonSummary;
@@ -138,16 +177,29 @@ interface ConfigLoadResult {
 /** True when this Node can `import()` a `.ts` file natively (type stripping). */
 declare function supportsTypeScriptImports(): boolean;
 /**
- * Loads the first usable config file from `cwd`.
+ * Every key a configuration file may carry.
  *
- * Every failure is reported through `warnings` instead of being swallowed by an
- * empty `catch`: a syntax error in a user's config used to be indistinguishable
- * from having no config at all.
+ * This is `SnapshotConfig` plus the spellings that are read through casts: `discovery`
+ * (validated separately), `exclude` (the flag spelling of `excludePatterns`) and
+ * `secretRules` (the library spelling of a rule list, accepted by `resolveConfig` and
+ * therefore needed here too — omitting it made a config file that used it fail with
+ * "unknown setting(s): secretRules" while the same key worked when passed in code).
  */
+declare const CONFIG_KEYS: ReadonlySet<string>;
 declare function loadConfigFileDetailed(cwd: string): Promise<ConfigLoadResult>;
 declare function loadConfigFile(cwd: string): Promise<SnapshotConfig | null>;
 /** Smallest usable part budget: a part header plus one section must fit. */
 declare const MIN_MAX_PART_BYTES = 4096;
+/**
+ * The same floor expressed in the unit `--max-part-tokens` is written in.
+ *
+ * `bytesForTokens` multiplies by four, so 1024 tokens and 4096 bytes are the same budget. A
+ * smaller token budget used to be raised to the floor without a word: `--max-part-tokens 200`
+ * was accepted, reported as 1024 tokens, and the setting the user wrote never applied. Rule 1
+ * says an impossible budget is an error, so this is the number the CLI and the config both
+ * refuse to go below.
+ */
+declare const MIN_MAX_PART_TOKENS: number;
 /** Every artifact this package can write, in the order it is written. */
 declare const ARTIFACT_NAMES: readonly ["readme", "manifest", "parts", "navigation", "projectTree", "audit", "monolith"];
 /**
@@ -173,8 +225,27 @@ declare function resolveConfig(userConfig: SnapshotConfig | null, cliOptions?: P
  * `"src/app/**"` now means "exactly `src/app` or below": the previous
  * implementation stripped `**` **and** the trailing slash, so the pattern also
  * matched `src/apple/` and `src/application/`.
+ *
+ * Everything else is answered by {@link matchesExclude}, which is the one implementation of
+ * "does this pattern select this path": glob metacharacters (including `{a,b}` and `[abc]`,
+ * which used to be tested for `*`/`?` only and then silently compared as literal text) go
+ * through the glob translator, and a plain pattern means a whole **path segment** sequence
+ * rather than a substring. `match: "test"` used to select `src/contest/a.ts`, and a layer rule
+ * that matched nothing classified every file under it as `other`.
  */
 declare function matchRule(filePath: string, matcher: string | RegExp | ((filePath: string) => boolean)): boolean;
+declare function classifyLayer(filePath: string, layers: LayerRule[]): string;
+declare function classifyKind(filePath: string, kinds: KindRule[]): string;
+/**
+ * Digest of every setting that changes what a snapshot contains.
+ *
+ * Masked config values cannot be compared directly: two different secrets both
+ * mask to the same placeholder, and `validate` would then report "current" for a
+ * snapshot generated with different rules. A digest of the raw effective settings
+ * answers "is this snapshot still configured the same way" without ever printing
+ * a value.
+ */
+declare function configDigest(config: ResolvedSnapshotConfig): string;
 
 declare function defineConfig(config: SnapshotConfig): SnapshotConfig;
 
@@ -194,6 +265,14 @@ interface PartitionedPart {
  * large file produced a part 13.5x over the configured budget.
  */
 declare function partitionFiles(files: FileEntry[], maxPartBytes: number, contentFingerprint?: string): PartitionedPart[];
+/**
+ * Hard-clips any part that is still above `budget`, re-hashing what it wrote.
+ *
+ * Exported so the clip path can be tested at all: the partitioner splits oversized sections
+ * rather than clipping them, so no ordinary fixture reaches this branch, and the stale token
+ * count it used to leave behind was therefore invisible to every end-to-end test.
+ */
+declare function enforceBudget(parts: PartitionedPart[], budget: number): PartitionedPart[];
 /**
  * Re-numbers a set of parts as one sequence and rewrites their headers.
  *
@@ -202,6 +281,22 @@ declare function partitionFiles(files: FileEntry[], maxPartBytes: number, conten
  * contain duplicate filenames and every `Previous:`/`Next:` link would lie.
  */
 declare function renumberParts(parts: PartitionedPart[], contentFingerprint?: string): PartitionedPart[];
+/**
+ * Paths reach the `## Files` list, the `### FILE:` heading and the navigation
+ * index, so a control character in a name is rendered as `\uXXXX` instead of
+ * being emitted raw: a bidi override visually reorders the line, a C1 CSI drives
+ * the terminal, and a newline would break the line-oriented layout. Escaping
+ * also keeps the `## Files` fence safe (see {@link fenceForText}). Paths are
+ * legal UTF-8, so this is reachable with an ordinary `git mv`.
+ */
+/**
+ * The form of a path that is written into a part.
+ *
+ * Exported because the reader has to compare against it: a section heading holds this
+ * form, not the manifest's `relativePath`, and the two differ for any path with a
+ * control character or one longer than {@link DISPLAY_PATH_MAX}.
+ */
+declare const displayPath: (value: string) => string;
 /**
  * Chooses a fence longer than any backtick run in `content`, so a file that
  * contains a fenced block cannot break out of its own code block.
@@ -238,6 +333,10 @@ interface PreviewResult {
  *
  * Previously `index.ts` recorded 0 for an empty file while `preview.ts` recorded
  * 1, and every newline-terminated file was over-counted by one.
+ *
+ * Counted by scanning rather than by `split`: this runs on every file body and on every part, and
+ * normalising first would allocate a second copy of a multi-megabyte string to answer a question
+ * about its terminator count.
  */
 declare function countLines(content: string): number;
 /**
@@ -379,18 +478,6 @@ declare function isBinaryFile(absolutePath: string): boolean;
 
 declare function detectLanguage(filePath: string): string;
 
-/**
- * Redacts secrets from `content`.
- *
- * - Replaces only the matched span, so unrelated code sharing the line survives
- *   (the previous implementation discarded the whole line).
- * - When a rule declares `valueGroup`, only that capture group is masked, so
- *   `dbPassword: "…"` keeps its key and stays parseable.
- * - Masks PEM private-key blocks as a unit; per-line rules can only see the
- *   `BEGIN` header, which left every body line of a real key in the output.
- * - Records `{ rule, line, path }` only. No excerpt of the source is retained,
- *   because that excerpt was being written verbatim into `reports/audit.md`.
- */
 declare function scanAndRedactSecrets(content: string, rules: SecretRule[], filePath?: string): {
     redacted: string;
     findings: SecretFinding[];
@@ -422,7 +509,7 @@ declare function validateSnapshot(configInput: ResolvedSnapshotConfig | Snapshot
  * `package.json` carries the same version; `npm run verify` compares the two.
  */
 declare const GENERATOR_NAME = "codebase-snapshot";
-declare const GENERATOR_VERSION = "0.9.9";
+declare const GENERATOR_VERSION = "0.9.14";
 
 /** The one endpoint this package will ever request. */
 declare const PACKAGE_LATEST_URL = "https://registry.npmjs.org/codebase-snapshot/latest";
@@ -467,7 +554,13 @@ interface UpdateCheckOptions {
     fetchLatest?: (url: string, timeoutMs: number) => Promise<string | null>;
     enabled?: boolean;
 }
-/** True when `candidate` is a strictly higher release than `current`. */
+/**
+ * True when `candidate` is a version worth telling somebody about.
+ *
+ * A prerelease is never announced — being offered `1.0.0-rc.1` while running `0.9.12` is not an
+ * upgrade, and a check that says so is wrong every time it fires. A stable release *is* newer than
+ * the prerelease of itself, so somebody on `0.9.12-beta.1` is told about `0.9.12`.
+ */
 declare function isNewer(candidate: string, current: string): boolean;
 /** The per-user cache directory, following each platform's convention. */
 declare function cacheDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
@@ -480,7 +573,18 @@ declare function cacheFilePath(env?: NodeJS.ProcessEnv): string;
  * spends a CI job's network and pollutes a machine-readable stream.
  */
 declare function shouldCheck(argv: readonly string[], env: NodeJS.ProcessEnv): boolean;
-/** One HTTPS GET with a hard timeout. Resolves null for every failure. */
+/**
+ * One GET with a hard deadline. Resolves null for every failure.
+ *
+ * The deadline is a **wall clock**, not an idle-socket timeout. `request.setTimeout` only fires
+ * when the socket goes quiet, so a slow or trickling proxy — one that sends a byte every second —
+ * kept the CLI process alive long past `REQUEST_TIMEOUT_MS`. The timer below is absolute: when it
+ * fires the request is destroyed and the answer is "could not determine", which is what the notice
+ * already treats as "say nothing".
+ *
+ * The scheme picks the transport so the deadline can be exercised against a local server; the
+ * default URL is https either way.
+ */
 declare function fetchLatestVersion(url?: string, timeoutMs?: number): Promise<string | null>;
 /**
  * Returns a notice when a newer version is published, or null.
@@ -651,10 +755,19 @@ interface InitOptions {
     /** Force a preset instead of detecting one. */
     preset?: string;
     maxPartBytes?: ByteSize;
+    /** Ceiling in tokens; narrows `maxPartBytes` rather than replacing it. */
+    maxPartTokens?: number;
+    largeFileBytes?: ByteSize;
+    maxMonolithBytes?: ByteSize;
+    discovery?: DiscoveryMode;
+    skeleton?: boolean;
+    sarif?: boolean;
     include?: string[];
     exclude?: string[];
     skipArtifacts?: string[];
     onlyArtifacts?: string[];
+    /** Turn the monolith on without disabling anything else (`--include-monolith`). */
+    includeMonolith?: boolean;
     includeSensitiveFiles?: boolean;
     /** Accept every default without prompting. */
     yes?: boolean;
@@ -698,6 +811,14 @@ interface InitResult {
     dependency: InitDependency;
     /** Human-readable notes about anything that was skipped or could not be done. */
     notes: string[];
+    /**
+     * The output directory the written config names.
+     *
+     * Returned so the caller can bake it into the pre-commit hook: the hook is a shell script and
+     * cannot read the config, and hardcoding `snapshot` there made a gate that never ran for any
+     * project that chose a different directory.
+     */
+    outDir: string;
 }
 /**
  * Runs the interactive setup, or writes a config from flags.
@@ -791,7 +912,12 @@ interface WizardAnswers {
     preset: string;
     branch: string;
     maxPartBytes: ByteSize;
+    maxPartTokens: number | null;
     largeFileBytes: ByteSize;
+    maxMonolithBytes: ByteSize | null;
+    discovery: DiscoveryMode;
+    skeleton: boolean;
+    sarif: boolean;
     include: string[];
     excludePatterns: string[];
     artifacts: Required<ArtifactSelection>;
@@ -853,6 +979,184 @@ declare function profileForPath(path: string): LanguageProfile | null;
  */
 declare function summarizeWithProfile(path: string, content: string): HeuristicResult | null;
 
+/**
+ * A deterministic token estimate for emitted text.
+ *
+ * Why a local estimate at all: the snapshot exists to be pasted into a model's context, and
+ * every budget in this tool is expressed in bytes. Bytes are the right unit for a filesystem
+ * and the wrong one for a context window — the arithmetic that converts them is in
+ * `docs/codebase-token-budget.md` and every reader has to repeat it by hand. A number in the
+ * manifest that says "this part is about 8,400 tokens" is the answer to the question an
+ * agent actually asks before reading it.
+ *
+ * Why not a real tokenizer: this package has exactly one runtime dependency (`typescript`)
+ * and that is a feature, not an oversight. A BPE vocabulary is a few megabytes of data that
+ * would have to ship, version and be kept current. This counts the structure that BPE
+ * tokenizers follow closely on source code:
+ *
+ *  - a run of word characters costs `round(length / 6)`, minimum one, because common words in
+ *    source (`export`, `const`, `return`, `value`) are a single token in every mainstream
+ *    vocabulary and long identifiers are two or three;
+ *  - every other non-space character costs one, because punctuation is almost always its own
+ *    token (`=`, `(`, `,` and `)` are separate);
+ *  - a *space* costs nothing, because BPE merges the leading space into the next token — the
+ *    sequence `" const"` is one token, not two;
+ *  - a newline costs one, which is what an indented block boundary actually is.
+ *
+ * It is an estimate and it says so. The constants were set against `cl100k_base` on this
+ * repository's own sources and land within about 10% either way; the method above is stated
+ * so a reader can judge the number rather than being asked to trust it.
+ */
+/**
+ * Estimates the token count of `text`.
+ *
+ * Deterministic: the same string always produces the same number, on every platform, with no
+ * vocabulary to load and no network. That is what makes it safe to record in a manifest and
+ * compare between runs.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Converts a token budget into the byte budget the partitioner understands.
+ *
+ * The partitioner is byte-bounded because bytes are what it measures and writes. A user who
+ * thinks in tokens gets a byte ceiling that corresponds to their number, using the same
+ * ratio the estimate is built on — and `maxPartBytes` still applies, so the smaller of the
+ * two wins and the manifest records both.
+ */
+declare function bytesForTokens(tokens: number): number;
+/** Renders a token count for a header or a report: `8400` → `8,400`. */
+declare function formatTokens(count: number): string;
+
+/** Marks a hook this tool wrote, so a re-run may replace it and a user can recognise it. */
+declare const HOOK_MARKER = "# codebase-snapshot: pre-commit snapshot check";
+interface HookInstallResult {
+    /** Absolute path of the hook file, or `null` when there was nowhere to write it. */
+    path: string | null;
+    /** True when this call wrote (or rewrote) the hook. */
+    written: boolean;
+    /** Human-readable outcomes, always at least one. */
+    notes: string[];
+}
+/**
+ * Installs (or refreshes) the pre-commit hook.
+ *
+ * Idempotent: a hook carrying {@link HOOK_MARKER} is replaced with the current body, so an
+ * upgrade of this package updates the check. Anyone else's hook is untouched.
+ */
+declare function installPreCommitHook(cwd: string, outDir?: string): HookInstallResult;
+
+interface ChangedScopeRequest {
+    /** A git ref to compare the working tree against (`main`, `HEAD~3`, a sha). */
+    changedSince?: string;
+    /** Only what is staged for the next commit. */
+    staged?: boolean;
+}
+interface ChangedScope {
+    /** Repository-relative paths, POSIX separators. */
+    paths: ReadonlySet<string>;
+    /** How the set was produced, for the manifest and the summary line. */
+    detail: string;
+}
+/**
+ * Resolves the request into a path set.
+ *
+ * `--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`. Both together are a union.
+ */
+declare function resolveChangedScope(cwd: string, request: ChangedScopeRequest): ChangedScope;
+
+/** One-pass lookup tables for relative-import resolution.
+ *
+ * `resolveSpecifier` used to fall back to scanning every known file for every
+ * unresolved import — 100k files × 100k imports — and built a RegExp from the
+ * candidate path, so a directory named `[unmatched` aborted the run and `[id]`
+ * matched unrelated files. Both are gone: every candidate is a map lookup, and
+ * no path is ever used as a pattern.
+ *
+ * Exported so a consumer can answer "what imports this file" from the snapshot's own
+ * index using the same rules the generator used. `manifest.indexes.imports.byFile`
+ * records the *raw* specifiers a file imports (`"./user.js"`), and a second
+ * implementation of the resolution would eventually disagree with this one — leaving
+ * two accounts of one graph.
+ */
+interface ImportResolver {
+    byPath: Map<string, string>;
+    byPathFolded: Map<string, string>;
+    byStem: Map<string, string>;
+    byStemFolded: Map<string, string>;
+}
+/** Anything that knows its own repository-relative path; `FileEntry` is the common case. */
+interface ImportCandidate {
+    relativePath: string;
+}
+declare function buildImportResolver(files: readonly ImportCandidate[]): ImportResolver;
+/** Best-effort resolution of a relative import to an included file. */
+declare function resolveSpecifier(fromFile: string, specifier: string, resolver: ImportResolver): string | null;
+/**
+ * True when `imports` — the specifiers one file imports — reach anything in `changedPaths`.
+ *
+ * One hop, and only one hop. The test is against the **changed set**, never against a set that
+ * is being extended while it is tested: doing that walked the graph transitively, so a changed
+ * `a.ts` pulled in `b.ts` (which imports it) and then `c.ts` (which imports `b.ts`), and whether
+ * the two-hop file was included depended on whether its name happened to sort after `b.ts`. The
+ * same repository produced different snapshots depending on file names.
+ */
+declare function importsChangedFile(importerPath: string, imports: readonly string[], changedPaths: ReadonlySet<string>, resolver: ImportResolver): boolean;
+
+/** Import specifiers from text already decoded, or `[]` when the language has no importer. */
+declare function importsOfText(relativePath: string, text: string): string[];
+/**
+ * Import specifiers of one file on disk.
+ *
+ * A file this cannot read, a binary file, an oversized file and a file the parser rejects all
+ * contribute `[]`, which is what the generator saw for them too — so the answer stays consistent
+ * with the snapshot rather than becoming a third opinion about it.
+ */
+declare function importsOfFile(relativePath: string, absolutePath: string): string[];
+
+interface SkeletonResult {
+    text: string;
+    /** How many bodies were replaced; zero means the file had none and was left alone. */
+    collapsed: number;
+}
+/**
+ * Replaces the body of every function-like node, innermost-first, by text span.
+ *
+ * Spans are collected and then applied from the end of the file backwards so that an earlier
+ * replacement never invalidates a later span's offsets.
+ */
+/**
+ * True when a filename is JavaScript-with-JSX, in any letter case.
+ *
+ * One function for one question, because two spellings of it is exactly how `.TSX` came to be
+ * eligible for a skeleton and then parsed as plain TypeScript, where JSX is a syntax error.
+ * Exported so the decision itself can be tested: collapsing a body is span-based and produces the
+ * same text under either script kind for simple files, so an output comparison cannot prove which
+ * parser ran.
+ */
+declare function isTsxFileName(fileName: string): boolean;
+declare function skeletonizeTypeScript(source: string, fileName?: string): SkeletonResult;
+/**
+ * True for a path this module can compress.
+ *
+ * `.d.ts` and friends are excluded first: they are declarations, so there is nothing to collapse,
+ * and parsing them was pure cost. Everything else the TypeScript parser can read is included —
+ * JavaScript and JSX included, which is most of the code in most repositories.
+ */
+declare function isSkeletonizable(filePath: string): boolean;
+
+/**
+ * Renders the findings as a SARIF log.
+ *
+ * Every result carries the file and line, a `level` of `note` — a redaction is the tool doing
+ * its job, not a build failure — and the rule that matched. `partialFingerprints` gives Code
+ * Scanning a stable identity for an alert across commits, built from the path, the rules and
+ * the line, so re-running `generate` does not close and reopen every alert.
+ */
+declare function generateSarifReport(manifest: Manifest, findings: readonly SecretFinding[], rules: readonly SecretRule[], toolVersion: string): string;
+
 declare const SCHEMA_VERSION = "3.0.0";
 
 interface GenerateOptions {
@@ -884,6 +1188,14 @@ declare function resolveSafeOutputDirs(config: {
  * directory per run rather than a single snapshot.
  */
 declare function assertReplaceable(target: string, label: "outDir" | "tmpDir", secretRules?: readonly SecretRule[]): void;
+/**
+ * Where the run lock for a staging root lives.
+ *
+ * Exported because the lock is the one piece of state that can outlive a crashed run and
+ * wedge the next one, and the error the user sees names this path — a diagnostic that
+ * has to be transcribed from a hash by hand is not a diagnostic.
+ */
+declare function lockPathFor(stagingRoot: string): string;
 /**
  * Generates the snapshot.
  *
@@ -895,4 +1207,4 @@ declare function generateSnapshot(configInput?: SnapshotConfig | ResolvedSnapsho
 /** Promise-returning wrapper for consumers that prefer an async call site. */
 declare function generateSnapshotAsync(configInput?: SnapshotConfig | ResolvedSnapshotConfig | null, options?: GenerateOptions): Promise<Manifest>;
 
-export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CHECK_INTERVAL_MS, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FAILURE_INTERVAL_MS, FileEntry, type FirstRunFacts, type FirstRunPlan, type FirstRunRefusal, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, type InitDependency, type InitOptions, type InitResult, type InstallKind, JsonSummary, KindRule, LANGUAGE_PROFILES, type LanguageProfile, LayerRule, MIN_MAX_PART_BYTES, Manifest, type ManifestDiff, MarkdownSummary, PACKAGE_LATEST_URL, PRESETS, PartMetadata, PromptBack, PromptCancelled, REQUEST_TIMEOUT_MS, ResolvedSnapshotConfig, SCHEMA_VERSION, SecretFinding, SecretRule, SkipRecord, SnapshotConfig, SourceSummary, TextEncoding, type UpdateCheckOptions, type UpdateNotice, ValidationResult, type WizardAnswers, anchorForPath, assertReplaceable, assertUsableConfigInput, cacheDirectory, cacheFilePath, checkForUpdate, collectFiles, compareManifests, countInvalidUtf8Bytes, countLines, decodeText, defineConfig, detectLanguage, detectPreset, displayWidth, explainPath, fenceForContent, fenceForText, fetchLatestVersion, firstRunMessage, formatUpdateNotice, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, hasPriorSnapshot, installKind, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isNewer, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, shouldCheck, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, updateCommand, validateSnapshot, wrapLines };
+export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CHECK_INTERVAL_MS, CONFIG_KEYS, type ChangedScope, type ChangedScopeRequest, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FAILURE_INTERVAL_MS, FileEntry, type FirstRunFacts, type FirstRunPlan, type FirstRunRefusal, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, HOOK_MARKER, type HeuristicResult, type HookInstallResult, type ImportCandidate, type ImportResolver, type InitDependency, type InitOptions, type InitResult, type InstallKind, JsonSummary, KindRule, LANGUAGE_PROFILES, type LanguageProfile, LayerRule, MIN_MAX_PART_BYTES, MIN_MAX_PART_TOKENS, Manifest, type ManifestDiff, MarkdownSummary, PACKAGE_LATEST_URL, PRESETS, PartMetadata, PromptBack, PromptCancelled, REQUEST_TIMEOUT_MS, ResolvedSnapshotConfig, SCHEMA_VERSION, SecretFinding, SecretRule, SkipRecord, SnapshotConfig, SourceSummary, TextEncoding, type UpdateCheckOptions, type UpdateNotice, ValidationResult, type WizardAnswers, anchorForPath, assertReplaceable, assertUsableConfigInput, buildImportResolver, bytesForTokens, cacheDirectory, cacheFilePath, checkForUpdate, classifyKind, classifyLayer, collectFiles, compareManifests, configDigest, countInvalidUtf8Bytes, countLines, decodeText, defineConfig, detectLanguage, detectPreset, displayPath, displayWidth, enforceBudget, estimateTokens, explainPath, fenceForContent, fenceForText, fetchLatestVersion, findSecretInPath, firstRunMessage, formatTokens, formatUpdateNotice, generateProjectTree, generateSarifReport, generateSnapshot, generateSnapshotAsync, getGitInfo, getPreset, globToRegExp, hasPriorSnapshot, importsChangedFile, importsOfFile, importsOfText, installKind, installPreCommitHook, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isNewer, isResolvedConfig, isSensitivePath, isSkeletonizable, isTsxFileName, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, lockPathFor, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveChangedScope, resolveConfig, resolveSafeOutputDirs, resolveSpecifier, runInit, scanAndRedactSecrets, shouldCheck, skeletonizeTypeScript, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, updateCommand, validateSnapshot, wrapLines };

package/dist/index.js

@@ -1,3 +1 @@
-export { ARTIFACT_NAMES, CHECK_INTERVAL_MS, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, FAILURE_INTERVAL_MS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PACKAGE_LATEST_URL, PRESETS, PromptBack, PromptCancelled, REQUEST_TIMEOUT_MS, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, cacheDirectory, cacheFilePath, checkForUpdate, collectFiles, compareManifests, countInvalidUtf8Bytes, countLines, decodeText, defineConfig, detectLanguage, detectPreset, displayWidth, explainPath, fenceForContent, fenceForText, fetchLatestVersion, firstRunMessage, formatUpdateNotice, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, hasPriorSnapshot, installKind, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isNewer, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, shouldCheck, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, updateCommand, validateSnapshot, wrapLines } from './chunk-KUVFTJHK.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+export { ARTIFACT_NAMES, CHECK_INTERVAL_MS, CONFIG_KEYS, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, FAILURE_INTERVAL_MS, GENERATOR_NAME, GENERATOR_VERSION, HOOK_MARKER, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, MIN_MAX_PART_TOKENS, PACKAGE_LATEST_URL, PRESETS, PromptBack, PromptCancelled, REQUEST_TIMEOUT_MS, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, buildImportResolver, bytesForTokens, cacheDirectory, cacheFilePath, checkForUpdate, classifyKind, classifyLayer, collectFiles, compareManifests, configDigest, countInvalidUtf8Bytes, countLines, decodeText, defineConfig, detectLanguage, detectPreset, displayPath, displayWidth, enforceBudget, estimateTokens, explainPath, fenceForContent, fenceForText, fetchLatestVersion, findSecretInPath, firstRunMessage, formatTokens, formatUpdateNotice, generateProjectTree, generateSarifReport, generateSnapshot, generateSnapshotAsync, getGitInfo, getPreset, globToRegExp, hasPriorSnapshot, importsChangedFile, importsOfFile, importsOfText, installKind, installPreCommitHook, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isNewer, isResolvedConfig, isSensitivePath, isSkeletonizable, isTsxFileName, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, lockPathFor, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveChangedScope, resolveConfig, resolveSafeOutputDirs, resolveSpecifier, runInit, scanAndRedactSecrets, shouldCheck, skeletonizeTypeScript, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, updateCommand, validateSnapshot, workerEntry, wrapLines } from './chunk-DUZK5VL2.js';