@ankurhalder/codebase-snapshot 4.0.6 → 4.1.0

package/dist/index.d.cts

@@ -1,5 +1,70 @@
-import { J as JsonSummary, M as MarkdownSummary, S as SourceSummary, R as ResolvedSnapshotConfig, a as SnapshotConfig, B as ByteSize, C as CliOptions, F as FileEntry, P as PartMetadata, L as LayerRule, K as KindRule, b as SecretRule, c as SecretFinding, V as ValidationResult, d as Manifest, A as ArtifactSelection, e as SkipRecord } from './types-x7aogSer.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-x7aogSer.cjs';
+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-BMP676ER.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-BMP676ER.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
@@ -190,6 +255,10 @@ declare function truncatePreview(content: string, headLines: number, tailLines:
  * 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;
@@ -197,10 +266,26 @@ interface PresetContext {
     files: ReadonlySet<string>;
     /** Top-level directory names. */
     dirs: ReadonlySet<string>;
-    /** `dependencies` + `devDependencies` + `peerDependencies` names. */
+    /** `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 {
@@ -239,6 +324,33 @@ 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;
@@ -296,6 +408,8 @@ interface ExplainResult {
     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<{
         rule: string;
@@ -320,6 +434,50 @@ interface ManifestDiff {
     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;
+    };
+    layers: {
+        before: Record<string, number>;
+        after: Record<string, number>;
+    };
+    /** Human-readable statements, rendered by the terminal form. */
+    reasons: string[];
 }
 interface DiffSide {
     generatedAt: string;
@@ -445,57 +603,8 @@ declare function profileForPath(path: string): LanguageProfile | null;
  */
 declare function summarizeWithProfile(path: string, content: string): HeuristicResult | null;
 
-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[];
-}
-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;
-
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "4.0.6";
+declare const GENERATOR_VERSION = "4.1.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */
@@ -537,4 +646,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, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, 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, ValidationResult, type WizardAnswers, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };
+export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };

package/dist/index.d.ts

@@ -1,5 +1,70 @@
-import { J as JsonSummary, M as MarkdownSummary, S as SourceSummary, R as ResolvedSnapshotConfig, a as SnapshotConfig, B as ByteSize, C as CliOptions, F as FileEntry, P as PartMetadata, L as LayerRule, K as KindRule, b as SecretRule, c as SecretFinding, V as ValidationResult, d as Manifest, A as ArtifactSelection, e as SkipRecord } from './types-x7aogSer.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-x7aogSer.js';
+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-BMP676ER.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-BMP676ER.js';
+
+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
@@ -190,6 +255,10 @@ declare function truncatePreview(content: string, headLines: number, tailLines:
  * 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;
@@ -197,10 +266,26 @@ interface PresetContext {
     files: ReadonlySet<string>;
     /** Top-level directory names. */
     dirs: ReadonlySet<string>;
-    /** `dependencies` + `devDependencies` + `peerDependencies` names. */
+    /** `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 {
@@ -239,6 +324,33 @@ 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;
@@ -296,6 +408,8 @@ interface ExplainResult {
     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<{
         rule: string;
@@ -320,6 +434,50 @@ interface ManifestDiff {
     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;
+    };
+    layers: {
+        before: Record<string, number>;
+        after: Record<string, number>;
+    };
+    /** Human-readable statements, rendered by the terminal form. */
+    reasons: string[];
 }
 interface DiffSide {
     generatedAt: string;
@@ -445,57 +603,8 @@ declare function profileForPath(path: string): LanguageProfile | null;
  */
 declare function summarizeWithProfile(path: string, content: string): HeuristicResult | null;
 
-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[];
-}
-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;
-
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "4.0.6";
+declare const GENERATOR_VERSION = "4.1.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */
@@ -537,4 +646,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, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, 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, ValidationResult, type WizardAnswers, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };
+export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, type HeuristicResult, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-GAY7W5MK.js';
+export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, 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, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-6SMZR5EM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{types-x7aogSer.d.cts → types-BMP676ER.d.cts}

@@ -1,5 +1,21 @@
 type Mode = "generate" | "validate" | "report";
 type OutputFormat = "text" | "json";
+/**
+ * How files are discovered.
+ *
+ * `auto` lists files through git when git can do it and walks the tree otherwise; `git` and `walk`
+ * force one path. It is part of the manifest's recorded settings because it decides which files a
+ * snapshot contains — the same repository scanned both ways is two different snapshots.
+ */
+type DiscoveryMode = "auto" | "git" | "walk";
+/**
+ * How a file's bytes became text.
+ *
+ * Absent from a `FileEntry` means plain UTF-8, which is the overwhelmingly common case. The other
+ * values are recorded because they change what the artifact actually contains: `utf-16le`/`utf-16be`
+ * files were transcoded, and `utf-8-lossy` files carry U+FFFD where their undecodable bytes were.
+ */
+type TextEncoding = "utf-8" | "utf-8-lossy" | "utf-16le" | "utf-16be";
 /**
  * How much of a file made it into the snapshot.
  * `full`    – the complete file body was emitted.
@@ -64,7 +80,15 @@ type SkipReason = "binary" | "read-error" | "not-file"
 /** Excluded by a built-in rule: the ignore list, a preset, or an output dir. */
  | "default-ignore"
 /** Excluded by the user's own `excludePatterns` or `include` allow-list. */
- | "excluded";
+ | "excluded"
+/**
+ * A directory that belongs to another repository: a nested checkout or a submodule.
+ *
+ * A submodule is a single gitlink entry, so `stat` reports a directory where a file was
+ * expected — which used to be recorded as the generic `not-file`, implying the path was a
+ * socket or a FIFO rather than a repository whose contents are simply somebody else's.
+ */
+ | "nested-repository";
 interface SkipRecord {
     /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
@@ -99,6 +123,11 @@ interface FileEntry {
     summaryQuality?: SummaryQuality;
     /** True when the summary alone was too large for the part budget and was dropped. */
     summaryOmitted?: boolean;
+    /**
+     * How the file's bytes were decoded. Absent means plain UTF-8. Present when the file was
+     * transcoded from UTF-16, or when it was not valid UTF-8 and lost bytes to U+FFFD.
+     */
+    encoding?: TextEncoding;
     /** Emitted body after redaction/truncation. Never serialized into the manifest. */
     content?: string;
 }
@@ -215,6 +244,8 @@ interface ManifestConfigSnapshot {
     previewTailLines: number;
     includeMonolith: boolean;
     includeSensitiveFiles: boolean;
+    /** How files were discovered; `undefined` on manifests written before this was recorded. */
+    discovery?: DiscoveryMode;
     artifacts: ResolvedArtifacts;
     include: string[];
     preset: string;
@@ -368,6 +399,12 @@ interface ResolvedSnapshotConfig {
     includeMonolith: boolean;
     maxMonolithBytes: number | null;
     includeSensitiveFiles: boolean;
+    /**
+     * How files are discovered; `auto` picks git when it can list files and walks the tree otherwise.
+     * Optional because a resolved config can arrive from an older caller that never named it — every
+     * reader treats `undefined` as `auto`, so the effective mode is never guessed twice.
+     */
+    discovery?: DiscoveryMode;
     /** Empty means "no allow-list"; every discovered file is a candidate. */
     include: string[];
     /** The preset that was resolved (detected or forced). */
@@ -400,6 +437,8 @@ interface CliOptions {
 interface ValidationDrift {
     missingInSnapshot: string[];
     missingOnDisk: string[];
+    /** Files that exist but could not be read, so their content could not be verified. */
+    unreadable: string[];
     hashMismatches: Array<{
         path: string;
         diskHash: string;
@@ -424,4 +463,4 @@ interface ValidationResult {
     warnings: string[];
 }
 
-export type { ArtifactSelection as A, ByteSize as B, CliOptions as C, FileEntry as F, HooksConfig as H, InclusionMode as I, JsonSummary as J, KindRule as K, LayerRule as L, MarkdownSummary as M, OutputFormat as O, PartMetadata as P, ResolvedSnapshotConfig as R, SourceSummary as S, ValidationResult as V, SnapshotConfig as a, SecretRule as b, SecretFinding as c, Manifest as d, SkipRecord as e, BudgetConfig as f, ManifestArtifact as g, ManifestConfigSnapshot as h, ManifestIndexes as i, ManifestTotals as j, Mode as k, PartFileEntry as l, ResolvedArtifacts as m, ResolvedBudgets as n, SecretRuleInput as o, SkipReason as p, SummaryQuality as q, ValidationDrift as r };
+export type { ArtifactSelection as A, ByteSize as B, CliOptions as C, DiscoveryMode as D, FileEntry as F, HooksConfig as H, InclusionMode as I, JsonSummary as J, KindRule as K, LayerRule as L, MarkdownSummary as M, OutputFormat as O, PartMetadata as P, ResolvedSnapshotConfig as R, SecretRule as S, TextEncoding as T, ValidationResult as V, SkipRecord as a, SourceSummary as b, SnapshotConfig as c, SecretFinding as d, Manifest as e, BudgetConfig as f, ManifestArtifact as g, ManifestConfigSnapshot as h, ManifestIndexes as i, ManifestTotals as j, Mode as k, PartFileEntry as l, ResolvedArtifacts as m, ResolvedBudgets as n, SecretRuleInput as o, SkipReason as p, SummaryQuality as q, ValidationDrift as r };