codebase-snapshot 0.0.0-stage → 4.5.0

package/dist/index.d.cts

@@ -0,0 +1,710 @@
+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.cjs';
+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.cjs';
+
+interface CollectOptions {
+    /**
+     * When non-empty, only files matching at least one pattern are candidates.
+     * Applied before `excludePatterns`, which then narrows the result further.
+     */
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    /**
+     * Emit credential-bearing files (`.env`, `*.pem`, `.npmrc`, `id_rsa`, …).
+     * Default `false`: they are skipped with `reason: "sensitive-file"`.
+     */
+    includeSensitiveFiles?: boolean;
+    /**
+     * Secret rules used to scan *paths* (defaults are always applied). Pass
+     * `config.secretRules` so `customPatterns` also protect file names.
+     */
+    secretRules?: readonly SecretRule[];
+    /**
+     * Top-level directory names this run is about to write — `outDir` and `tmpDir`.
+     *
+     * They are excluded from the scan without a `skipped[]` record because that is this tool's own
+     * bookkeeping and a first run cannot have written a marker into them yet. A directory with one
+     * of these *names* that carries no marker is still excluded when it is one of these paths, but
+     * is an ordinary directory when it is not: dropping it silently was the bug.
+     */
+    toolOwnedPaths?: readonly string[];
+    /**
+     * How candidates are discovered: `auto` (git when usable, refusal when the
+     * directory claims to be a repository but git cannot list it), `git` (require
+     * git), or `walk` (walk the tree, reading the root `.gitignore` directly).
+     * Defaults to the configured mode, then `auto`.
+     */
+    discovery?: DiscoveryMode;
+}
+interface CollectResult {
+    files: string[];
+    skipped: SkipRecord[];
+}
+declare function isSensitivePath(relativePath: string): boolean;
+/**
+ * Translates a glob (`**`, `*`, `?`, `{a,b}`, `[abc]`) into a RegExp. A pattern
+ * without a leading `/` matches at any depth, mirroring `.gitignore` semantics.
+ *
+ * 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.
+ */
+declare function globToRegExp(glob: string): RegExp;
+/**
+ * Path exclusion with proper segment semantics.
+ *
+ * A plain (non-glob) pattern matches a whole path segment sequence, so
+ * `"test"` matches `test/a.ts` and `src/test/b.ts` but **not** `contest/entry.ts`
+ * (the previous implementation was a raw `String.includes`).
+ */
+declare function matchesExclude(relativePath: string, pattern: string): boolean;
+/**
+ * Collects candidate file paths.
+ *
+ * Uses `git ls-files -z` when git is available: `-z` is required because the
+ * default output C-quotes paths containing non-ASCII characters, which silently
+ * mangled `src/café.ts` into a path that never existed and dropped the file.
+ */
+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.
+ */
+declare function stripJsonComments(content: string): string;
+declare function summarizeJson(content: string): JsonSummary;
+declare function summarizeMarkdown(content: string): MarkdownSummary;
+
+/**
+ * Extracts a structural summary from a JS/TS source file.
+ *
+ * The traversal is an explicit stack, not recursion: a generated file with a
+ * long `a && b && …` chain used to overflow the call stack inside our own
+ * visitor and abort the entire snapshot. Callers should still treat a throw as
+ * possible (TypeScript's own parser recurses), so wrap the call.
+ */
+declare function summarizeTypeScriptSource(relativePath: string, content: string): SourceSummary;
+
+/**
+ * Brands a resolved config so consumers can distinguish it from a user
+ * `SnapshotConfig` structurally, instead of guessing from the presence of a
+ * single field (`"secretRules" in input`), which misfired for hand-built configs
+ * and for user configs that happened to carry an extra key.
+ */
+declare function markResolvedConfig<T extends ResolvedSnapshotConfig>(config: T): T;
+/**
+ * Detects a resolved config.
+ *
+ * The brand is a non-enumerable symbol, so it survives `structuredClone` but NOT
+ * `{ ...resolvedConfig, override }`. Relying on the brand alone caused a real
+ * regression: a spread config was re-resolved as a user config, which silently
+ * dropped custom `secretRules` and let matching secrets through in clear text.
+ * The structural fallback therefore accepts any object carrying the complete
+ * resolved-only shape.
+ */
+declare function isResolvedConfig(value: unknown): value is ResolvedSnapshotConfig;
+/**
+ * Re-validates a resolved config taken from an untrusted path (e.g. a spread
+ * copy), recompiling secret rules so string patterns and stray `g`/`y` flags are
+ * normalised even when the object did not come from `resolveConfig`.
+ */
+declare function normalizeResolvedConfig(config: ResolvedSnapshotConfig): ResolvedSnapshotConfig;
+/**
+ * Guards against a silently lossy config round-trip.
+ *
+ * A `RegExp` cannot survive `JSON.stringify`/`JSON.parse`: the pattern comes
+ * back as `{}`. Such an object no longer satisfies `isResolvedConfig`, so it
+ * would be re-resolved as a user config and its custom `secretRules` would be
+ * dropped without a word — a silent security regression. Fail loudly instead.
+ */
+declare function assertUsableConfigInput(value: unknown): void;
+interface ConfigLoadResult {
+    config: SnapshotConfig | null;
+    /** Absolute path of the file the config came from, if any. */
+    file: string | null;
+    /** Why a candidate config file was ignored. Never silently discarded. */
+    warnings: string[];
+    /**
+     * Config files that exist but could not be read.
+     *
+     * These are fatal: a config that fails to parse used to be skipped in favour of
+     * the defaults, which meant a typo silently produced a snapshot with none of the
+     * developer's settings applied. A config that is merely unsupported on this Node
+     * version (a `.ts` file below Node 22.6) stays a warning — nothing is wrong with
+     * the file, and the message already says what to do.
+     */
+    errors: string[];
+}
+/** 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 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.
+ */
+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;
+/** Every artifact this package can write, in the order it is written. */
+declare const ARTIFACT_NAMES: readonly ["readme", "manifest", "parts", "navigation", "projectTree", "audit", "monolith"];
+/**
+ * Parses a byte budget.
+ *
+ * Accepts a plain number (`122880`), a numeric string (`"122880"`), or a
+ * human-readable size (`"120k"`, `"1.5mb"`, `"2 GB"`). Returns `undefined` for
+ * anything it cannot read, so callers can decide whether that is an error or a
+ * fallback — a typo'd budget must not silently become the default.
+ */
+declare function parseByteSize(value: ByteSize | null | undefined): number | undefined;
+/**
+ * Merges user config, preset defaults and CLI overrides.
+ *
+ * `baseDir` is the directory the config was loaded from. Without it the natural
+ * library flow (`loadConfigFile(dir)` then `resolveConfig(config)`) silently
+ * fell back to `process.cwd()` and generated into the caller's directory.
+ */
+declare function resolveConfig(userConfig: SnapshotConfig | null, cliOptions?: Partial<CliOptions>, baseDir?: string): ResolvedSnapshotConfig;
+/**
+ * Matches a path against a layer/kind rule.
+ *
+ * `"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/`.
+ */
+declare function matchRule(filePath: string, matcher: string | RegExp | ((filePath: string) => boolean)): boolean;
+
+declare function defineConfig(config: SnapshotConfig): SnapshotConfig;
+
+declare function generateProjectTree(filePaths: string[]): string;
+
+interface PartitionedPart {
+    filename: string;
+    markdown: string;
+    metadata: PartMetadata;
+}
+/**
+ * Partitions rendered file sections into byte-bounded parts.
+ *
+ * The budget is a hard bound: a section that cannot fit into a part on its own
+ * is byte-truncated (and marked `isPreviewTruncated`) rather than emitted whole.
+ * The previous implementation skipped the flush check for an empty chunk, so one
+ * large file produced a part 13.5x over the configured budget.
+ */
+declare function partitionFiles(files: FileEntry[], maxPartBytes: number, contentFingerprint?: string): PartitionedPart[];
+/**
+ * Re-numbers a set of parts as one sequence and rewrites their headers.
+ *
+ * Needed when parts are produced by more than one partition pass (per-layer
+ * budgets): each pass numbers from `part-001`, so the merged set would otherwise
+ * contain duplicate filenames and every `Previous:`/`Next:` link would lie.
+ */
+declare function renumberParts(parts: PartitionedPart[], contentFingerprint?: string): PartitionedPart[];
+/**
+ * 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.
+ */
+declare function fenceForContent(content: string): string;
+/**
+ * A fence longer than any backtick run in `content`, never shorter than
+ * `minimum`.
+ *
+ * Every fenced block the generator writes goes through this, not just file
+ * bodies: a *filename* may contain a backtick run (it is a legal name), and a
+ * fixed three-backtick fence around the `## Files` list let such a name close
+ * the block and turn the following filenames into live document text.
+ */
+declare function fenceForText(content: string, minimum: number): string;
+/**
+ * Stable, injective anchor for a file path.
+ *
+ * The previous slug was not injective (`src/a-b.ts` and `src/a/b.ts` produced the
+ * same anchor) and, more importantly, no part file ever emitted the anchors that
+ * `reports/navigation.md` linked to — every file link was dead.
+ */
+declare function anchorForPath(filePath: string): string;
+
+interface PreviewResult {
+    content: string;
+    isTruncated: boolean;
+    originalLines: number;
+    includedLines: number;
+}
+/**
+ * Line count with one consistent convention: a trailing newline does not start
+ * a new line, and an empty string has zero lines.
+ *
+ * Previously `index.ts` recorded 0 for an empty file while `preview.ts` recorded
+ * 1, and every newline-terminated file was over-counted by one.
+ */
+declare function countLines(content: string): number;
+/**
+ * Truncates to a UTF-8 byte budget without splitting a multi-byte character.
+ */
+declare function truncateToBytes(content: string, maxBytes: number): {
+    content: string;
+    isTruncated: boolean;
+};
+declare function truncatePreview(content: string, headLines: number, tailLines: number): PreviewResult;
+
+/**
+ * Everything preset detection is allowed to look at.
+ *
+ * Built once per run: the previous implementation re-read `package.json` inside
+ * every detector, which was both slow and incapable of seeing anything outside
+ * the JavaScript ecosystem.
+ *
+ * Detection stays bounded: the root is read once, and a workspace root (and only
+ * a workspace root) additionally looks one level into its packages so a Next.js
+ * app in `apps/web` is still a Next.js repository — see {@link isWorkspace}.
+ */
+interface PresetContext {
+    cwd: string;
+    /** Top-level file names, e.g. `next.config.ts`. */
+    files: ReadonlySet<string>;
+    /** Top-level directory names. */
+    dirs: ReadonlySet<string>;
+    /** `dependencies` + `devDependencies` + `peerDependencies` names, root and workspace. */
+    dependencies: ReadonlySet<string>;
+    /** Small snapshots of well-known manifests, for keyword detection. */
+    manifests: Readonly<Record<string, string>>;
+    /** True when the root declares a workspace (`pnpm-workspace.yaml`, `workspaces`, nx/turbo/lerna). */
+    isWorkspace: boolean;
+    /**
+     * Top-level entry names of the workspace's packages, deduplicated.
+     *
+     * Flattened on purpose: a detector only needs "does some package carry a
+     * `next.config.*`/`vite.config.*` marker", not which package it was.
+     */
+    workspaceFiles: ReadonlySet<string>;
+    /**
+     * `.md`/`.mdx` files at the root and up to two directories down.
+     *
+     * Only counted when the root has no `package.json` (the `docs` preset's other
+     * condition), so ordinary repositories pay nothing for it.
+     */
+    markdownCount: number;
+}
+
+interface PresetDefinition {
+    readonly name: string;
+    /** Higher wins. Framework presets outrank repository shapes. */
+    readonly priority: number;
+    detect(context: PresetContext): boolean;
+    readonly layers: LayerRule[];
+    readonly kinds: KindRule[];
+    /** Ecosystem-specific ignores, merged with the user's `excludePatterns`. */
+    readonly exclude?: string[];
+    /** Advice for the setup wizard. Never applied automatically. */
+    readonly recommendedBudget?: ByteSize;
+}
+interface DetectedPreset {
+    presetName: string;
+    layers: LayerRule[];
+    kinds: KindRule[];
+    /** Ecosystem ignores the scanner should apply in addition to the user's. */
+    exclude: string[];
+    recommendedBudget: ByteSize | null;
+}
+/**
+ * Every preset, ordered by priority.
+ *
+ * Ordering is the whole detection model: the first definition whose `detect`
+ * returns true wins, so the list is sorted once at module load rather than being
+ * hand-maintained in the right order.
+ */
+declare const PRESETS: readonly PresetDefinition[];
+/** Every preset name, in priority order — used by the CLI and the wizard. */
+declare function listPresetNames(): string[];
+declare function getPreset(name: string): PresetDefinition | undefined;
+/** Detects the preset for `cwd`, reading the repository once. */
+declare function detectPreset(cwd: string, forced?: string): DetectedPreset;
+
+declare function isBinaryExtension(filePath: string): boolean;
+declare function isBinaryBuffer(buffer: Buffer): boolean;
+interface DecodedText {
+    /** Decoded body. Empty when `binary` is true. */
+    text: string;
+    encoding: TextEncoding;
+    /** Byte count that could not be decoded as UTF-8. Zero for well-formed input. */
+    invalidBytes: number;
+    /** True when the bytes are not text: a NUL, or a payload full of control characters. */
+    binary: boolean;
+    /** Human-readable reason the bytes were rejected, when `binary` is true. */
+    binaryReason?: string;
+}
+/**
+ * Counts the bytes that are not part of a well-formed UTF-8 sequence.
+ *
+ * `buffer.toString("utf8")` silently substitutes U+FFFD for every bad sequence, which is how a
+ * Latin-1 source file used to reach the snapshot as `caf\uFFFD` with no warning anywhere. This
+ * gives the caller the number it needs to say so.
+ */
+declare function countInvalidUtf8Bytes(buffer: Buffer): number;
+/**
+ * Decodes a file buffer to text without guessing silently.
+ *
+ * Order matters. A UTF-16 file is mostly NUL bytes, and NUL is perfectly valid UTF-8, so asking
+ * "is this valid UTF-8?" first would answer yes and hand the caller a string full of NULs. The
+ * BOM check and the UTF-16 shape test therefore run before the UTF-8 validity test.
+ */
+declare function decodeText(buffer: Buffer): DecodedText;
+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[];
+};
+
+/**
+ * Validates a generated snapshot against the working tree and against the
+ * recorded configuration.
+ *
+ * Beyond source-file hashes this now also:
+ * - refuses a manifest that does not have the expected shape (previously threw
+ *   an uncaught `TypeError`),
+ * - verifies every emitted `parts/*.md` against its recorded `byteSize`/`sha256`
+ *   (previously a deleted or corrupted part still reported `valid: true`),
+ * - re-checks the effective configuration and the part/file bookkeeping,
+ * - verifies monolith artefact digests when present.
+ */
+declare function validateSnapshot(configInput: ResolvedSnapshotConfig | SnapshotConfig): ValidationResult;
+
+/**
+ * The published identity of this package: its name and its version.
+ *
+ * Both live here rather than in `index.ts` because the wizard needs them and
+ * `index.ts` re-exports the wizard. Importing the barrel from the wizard closes a
+ * cycle, and a cycle over a `const` is read at call time — fine under ESM, a trap
+ * under CJS, where the first access can land before the assignment runs. `index.ts`
+ * re-exports these two names, so the public API keeps them at the same place.
+ *
+ * `package.json` carries the same version; `npm run verify` compares the two.
+ */
+declare const GENERATOR_NAME = "codebase-snapshot";
+declare const GENERATOR_VERSION = "4.5.0";
+
+declare const DEFAULT_SECRET_PATTERNS: SecretRule[];
+
+interface ExplainResult {
+    /** Path relative to the configured cwd, POSIX separators. */
+    path: string;
+    /** Whether the path exists on disk. */
+    exists: boolean;
+    /** Whether the scanner would include it in the next snapshot. */
+    included: boolean;
+    /** Why it is excluded, when it is. Mirrors `SkipRecord.reason`. */
+    reason?: string;
+    detail?: string;
+    layer?: string;
+    layerMatch?: string;
+    kind?: string;
+    kindMatch?: string;
+    language?: string;
+    /** Part filename from the last written manifest, when one is available. */
+    part?: string | null;
+    inclusionMode?: string;
+    lines?: number;
+    bytes?: number;
+    /** Present when the file is not plain UTF-8, so an explanation cannot quietly lie about it. */
+    encoding?: TextEncoding;
+    secretCount?: number;
+    secrets?: Array<{
+        rules: string[];
+        line: number;
+    }>;
+}
+/**
+ * Explains what the scanner would do with one path.
+ *
+ * The whole point is that every decision is visible: which layer and kind rule
+ * matched, why a file was skipped, which part it landed in, and whether any
+ * secret rule fires. Re-running the real scanner is what keeps it honest.
+ */
+declare function explainPath(config: ResolvedSnapshotConfig, target: string): ExplainResult;
+/** Renders an explanation for a terminal. */
+declare function renderExplainText(result: ExplainResult): string;
+
+interface ManifestDiff {
+    before: DiffSide;
+    after: DiffSide;
+    added: string[];
+    removed: string[];
+    changed: string[];
+    unchanged: number;
+    /** What differs beyond the per-file list: the configuration and the emitted payload. */
+    payload: PayloadDiff;
+}
+/**
+ * A difference the per-file list cannot express.
+ *
+ * Per-file comparison is `relativePath + hashSha256`, so a run that changes only
+ * the *emitted* payload — `--large-file-bytes` turning a large preview into its
+ * full body, different preview head/tail counts, different redaction rules,
+ * different artifact selection — used to report "0 changed, N unchanged" and
+ * nothing else. The manifests already record the effective-settings digest, the
+ * content fingerprint and the part count, so this block says plainly when the
+ * source files are identical but the snapshot handed to the model is not.
+ */
+interface PayloadDiff {
+    /** No source file was added, removed or changed. */
+    sourceFilesIdentical: boolean;
+    /** The emitted payload, or the configuration that produced it, differs. */
+    differs: boolean;
+    /** The generator or the effective settings differ, independent of any source edit. */
+    configurationDiffers: boolean;
+    generator: {
+        before: string;
+        after: string;
+    };
+    /** `null` when the manifest predates the digest (written before 4.0.5). */
+    configDigest: {
+        before: string | null;
+        after: string | null;
+    };
+    fingerprint: {
+        before: string;
+        after: string;
+    };
+    partsCount: {
+        before: number;
+        after: number;
+    };
+    /**
+     * The `schemaVersion` of both manifests.
+     *
+     * Two snapshots written under different schema versions can carry the same file
+     * hashes and still mean different things, so a mismatch is reported as a
+     * difference (never as a crash) and turns the payload block on.
+     */
+    schemaVersion: {
+        before: string;
+        after: string;
+    };
+    /**
+     * The `parts` array compared entry by entry: a part added, removed, or
+     * re-rendered (different `byteSize`, `sha256`, `lines` or `fileCount`).
+     *
+     * The per-file list compares `relativePath + hashSha256` only, so a hand-edited
+     * or older manifest whose parts were repacked, renamed or deleted used to produce
+     * "+0 -0 ~0 =N unchanged" and exit 0. This block is rendered independently of
+     * `differs`, because a source edit already legitimately turns the file lists on.
+     */
+    partsManifest: {
+        differs: boolean;
+        changes: string[];
+    };
+    layers: {
+        before: Record<string, number>;
+        after: Record<string, number>;
+    };
+    /** Human-readable statements, rendered by the terminal form. */
+    reasons: string[];
+}
+interface DiffSide {
+    generatedAt: string;
+    fingerprint: string;
+    fileCount: number;
+    partsCount: number;
+}
+/** Compares two manifests file by file. */
+declare function compareManifests(before: Manifest, after: Manifest): ManifestDiff;
+/** Loads a manifest from a snapshot directory or a `manifest.json` path. */
+declare function loadManifest(target: string): Manifest;
+/** Renders a diff for a terminal. */
+declare function renderDiffText(diff: ManifestDiff): string;
+
+interface PromptIO {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+}
+/** Thrown when the developer presses Ctrl+C or Ctrl+D mid-prompt. */
+declare class PromptCancelled extends Error {
+    constructor();
+}
+/** Both ends must be a TTY before anything interactive is attempted. */
+declare function isInteractive(io: PromptIO): boolean;
+
+interface InitOptions {
+    cwd: string;
+    /** Force a preset instead of detecting one. */
+    preset?: string;
+    maxPartBytes?: ByteSize;
+    include?: string[];
+    exclude?: string[];
+    skipArtifacts?: string[];
+    onlyArtifacts?: string[];
+    includeSensitiveFiles?: boolean;
+    /** Accept every default without prompting. */
+    yes?: boolean;
+    /** Overwrite an existing config. */
+    force?: boolean;
+    /**
+     * Keep an existing config instead of refusing.
+     *
+     * `setup` writes a config only when the repository has none; when it has one, the rest of the
+     * setup work (scripts, devDependency, `.gitignore`) still happens and the file is left exactly as
+     * it is. `init` on its own keeps refusing — a user who typed `init` expects to be told the file
+     * already exists.
+     */
+    reuseConfig?: boolean;
+    /** Render the config without writing anything. */
+    dryRun?: boolean;
+    outDir?: string;
+    io?: PromptIO;
+}
+/** What happened to the `devDependencies` entry that makes the npm scripts self-contained. */
+interface InitDependency {
+    name: string;
+    /** The range now present in package.json, or a pre-existing declaration. */
+    range: string | null;
+    /** True when this run wrote the entry. */
+    added: boolean;
+}
+interface InitResult {
+    configPath: string;
+    configText: string;
+    written: boolean;
+    /** True when an existing config was kept instead of being written. */
+    reused: boolean;
+    preset: string;
+    scripts: string[];
+    gitignoreEntries: string[];
+    dependency: InitDependency;
+    /** Human-readable notes about anything that was skipped or could not be done. */
+    notes: string[];
+}
+/**
+ * Runs the interactive setup, or writes a config from flags.
+ *
+ * Interactive only when both ends are a TTY and `--yes` was not passed; every
+ * other path uses the flag values and the detected preset, and prints what it
+ * decided rather than prompting.
+ */
+declare function runInit(options: InitOptions): Promise<InitResult>;
+
+/** What the wizard decided, after prompts or flags. */
+interface WizardAnswers {
+    preset: string;
+    branch: string;
+    maxPartBytes: ByteSize;
+    largeFileBytes: ByteSize;
+    include: string[];
+    excludePatterns: string[];
+    artifacts: Required<ArtifactSelection>;
+    includeSensitiveFiles: boolean;
+    outDir: string;
+}
+declare const DEFAULT_ANSWERS: WizardAnswers;
+/**
+ * Renders the full, self-documenting config — the only shape `init` writes.
+ *
+ * Every setting appears at its current value, commented and grouped, because
+ * most developers never open the documentation — a file that lists only their
+ * changes cannot tell them what else exists. Deleting any line is safe: the
+ * defaults are real.
+ *
+ * There used to be a `--minimal` variant that wrote only the settings that
+ * differed from the defaults. It produced a seven-line file for a Next.js
+ * project — `export default { preset: "nextjs" }` — which is the one file the
+ * user is supposed to open to change things, holding none of the things. The
+ * flag is gone: one canonical config, always complete.
+ *
+ * The object is assigned to `config` and exported by name. An anonymous
+ * `export default { … }` is what every lint preset derived from
+ * `eslint-config-next` reports as `import/no-anonymous-default-export`, so the
+ * generated file was a lint error on the first save in a Next.js project — the
+ * preset this tool detects most often.
+ */
+declare function renderConfig(answers: WizardAnswers): string;
+
+interface HeuristicResult {
+    summary: SourceSummary;
+    /**
+     * `ast` only when a real parser produced this (TypeScript, and the script
+     * block of a Vue/Svelte/Astro component). Everything else is `heuristic`, and
+     * the manifest says so — a line-scan is not a parse.
+     */
+    quality: "ast" | "heuristic";
+}
+interface LanguageProfile {
+    readonly id: string;
+    readonly extensions: readonly string[];
+    summarize(path: string, content: string): HeuristicResult;
+}
+
+/**
+ * Every heuristic profile, in no particular order — lookup is by extension.
+ *
+ * Adding a language is one file exporting a `LanguageProfile` plus one line
+ * here; nothing else in the pipeline changes.
+ */
+declare const LANGUAGE_PROFILES: readonly LanguageProfile[];
+/** The profile that owns `path`, or `null` when no profile claims it. */
+declare function profileForPath(path: string): LanguageProfile | null;
+/**
+ * Summarizes `path` with whichever profile claims it.
+ *
+ * Returns `null` for files no profile handles — those still enter the snapshot,
+ * they just carry no structural summary.
+ */
+declare function summarizeWithProfile(path: string, content: string): HeuristicResult | null;
+
+declare const SCHEMA_VERSION = "3.0.0";
+interface GenerateOptions {
+    /** Compute the full manifest but write nothing to disk. */
+    dryRun?: boolean;
+}
+/**
+ * Resolves and validates the output directories.
+ *
+ * `outDir` was previously deleted with `rmSync` before the replacement was
+ * renamed into place, so `outDir: "."` erased the whole repository and a
+ * nested `tmpDir` erased its own parent. These guards make that impossible.
+ */
+declare function resolveSafeOutputDirs(config: {
+    cwd: string;
+    outDir: string;
+    tmpDir: string;
+}): {
+    outDir: string;
+    tmpDir: string;
+};
+/**
+ * Refuses to replace a directory that this generator did not write.
+ *
+ * Path checks alone cannot make the swap safe: `outDir: "src"` is a plausible
+ * typo, and a user directory that happens to contain a `.codebase-snapshot` file
+ * or a manifest-shaped JSON document is not a snapshot. The staging root is
+ * checked separately by {@link assertStagingRootUsable}, because it holds one
+ * directory per run rather than a single snapshot.
+ */
+declare function assertReplaceable(target: string, label: "outDir" | "tmpDir", secretRules?: readonly SecretRule[]): void;
+/**
+ * Generates the snapshot.
+ *
+ * Synchronous by design: it previously carried an `async` signature while doing
+ * only blocking I/O, which promised concurrency that did not exist. Existing
+ * `await generateSnapshot(...)` call sites continue to work.
+ */
+declare function generateSnapshot(configInput?: SnapshotConfig | ResolvedSnapshotConfig | null, options?: GenerateOptions): Manifest;
+/** 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, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, type InitDependency, type InitOptions, type InitResult, JsonSummary, KindRule, LANGUAGE_PROFILES, type LanguageProfile, LayerRule, MIN_MAX_PART_BYTES, Manifest, type ManifestDiff, MarkdownSummary, PRESETS, PartMetadata, PromptCancelled, ResolvedSnapshotConfig, SCHEMA_VERSION, SecretFinding, SecretRule, SkipRecord, SnapshotConfig, SourceSummary, TextEncoding, ValidationResult, type WizardAnswers, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countInvalidUtf8Bytes, countLines, decodeText, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, fenceForText, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };