@ankurhalder/codebase-snapshot 3.0.0 → 4.0.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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-CJqkePM4.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-CJqkePM4.cjs';
+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-LSfwsKE-.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-LSfwsKE-.cjs';
 
 /**
  * Strips `//` and block comments the way JSONC does, without touching anything
@@ -142,6 +142,16 @@ declare function renumberParts(parts: PartitionedPart[], contentFingerprint?: st
  * 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.
  *
@@ -238,6 +248,8 @@ declare function detectLanguage(filePath: string): string;
  *
  * - 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,
@@ -262,20 +274,6 @@ declare function scanAndRedactSecrets(content: string, rules: SecretRule[], file
  */
 declare function validateSnapshot(configInput: ResolvedSnapshotConfig | SnapshotConfig): ValidationResult;
 
-/**
- * Default secret rules.
- *
- * Design notes:
- * - Every quantifier is bounded. An unbounded `[A-Za-z0-9_-]{10,}` followed by
- *   `\.` backtracks to the end of the line at every start position, which made
- *   `jwt-token` quadratic (measured: 1.22 s for a 200 KB line). JWT segments are
- *   never longer than a few KB, so bounding at 1024 keeps the match linear in
- *   practice while still matching every realistic token.
- * - Rules are line-oriented; the whole-block private-key scan lives in
- *   `redact.ts` because it spans lines.
- * - Names are matched case-insensitively only where a value is anchored by
- *   quotes or a length, to keep false positives at zero on ordinary source.
- */
 declare const DEFAULT_SECRET_PATTERNS: SecretRule[];
 
 interface ExplainResult {
@@ -329,12 +327,7 @@ interface DiffSide {
     fileCount: number;
     partsCount: number;
 }
-/**
- * Compares two manifests file by file.
- *
- * The per-file hashes and the content fingerprint already make this exact, so
- * nothing is inferred: a path is added, removed or changed, never "maybe".
- */
+/** 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;
@@ -464,6 +457,11 @@ interface CollectOptions {
      * 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[];
@@ -497,7 +495,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "3.0.0";
+declare const GENERATOR_VERSION = "4.0.1";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */
@@ -521,12 +519,13 @@ declare function resolveSafeOutputDirs(config: {
 /**
  * Refuses to replace a directory that this generator did not write.
  *
- * `swapIntoPlace` renames the previous output aside and deletes it, and the
- * scratch directory is deleted outright before every run. Path checks alone
- * cannot make that safe: `outDir: "src"` is a plausible typo, and it used to
- * delete the developer's entire source tree and exit 0.
+ * 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"): void;
+declare function assertReplaceable(target: string, label: "outDir" | "tmpDir", secretRules?: readonly SecretRule[]): void;
 /**
  * Generates the snapshot.
  *
@@ -538,4 +537,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, 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, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-CJqkePM4.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-CJqkePM4.js';
+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-LSfwsKE-.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-LSfwsKE-.js';
 
 /**
  * Strips `//` and block comments the way JSONC does, without touching anything
@@ -142,6 +142,16 @@ declare function renumberParts(parts: PartitionedPart[], contentFingerprint?: st
  * 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.
  *
@@ -238,6 +248,8 @@ declare function detectLanguage(filePath: string): string;
  *
  * - 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,
@@ -262,20 +274,6 @@ declare function scanAndRedactSecrets(content: string, rules: SecretRule[], file
  */
 declare function validateSnapshot(configInput: ResolvedSnapshotConfig | SnapshotConfig): ValidationResult;
 
-/**
- * Default secret rules.
- *
- * Design notes:
- * - Every quantifier is bounded. An unbounded `[A-Za-z0-9_-]{10,}` followed by
- *   `\.` backtracks to the end of the line at every start position, which made
- *   `jwt-token` quadratic (measured: 1.22 s for a 200 KB line). JWT segments are
- *   never longer than a few KB, so bounding at 1024 keeps the match linear in
- *   practice while still matching every realistic token.
- * - Rules are line-oriented; the whole-block private-key scan lives in
- *   `redact.ts` because it spans lines.
- * - Names are matched case-insensitively only where a value is anchored by
- *   quotes or a length, to keep false positives at zero on ordinary source.
- */
 declare const DEFAULT_SECRET_PATTERNS: SecretRule[];
 
 interface ExplainResult {
@@ -329,12 +327,7 @@ interface DiffSide {
     fileCount: number;
     partsCount: number;
 }
-/**
- * Compares two manifests file by file.
- *
- * The per-file hashes and the content fingerprint already make this exact, so
- * nothing is inferred: a path is added, removed or changed, never "maybe".
- */
+/** 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;
@@ -464,6 +457,11 @@ interface CollectOptions {
      * 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[];
@@ -497,7 +495,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "3.0.0";
+declare const GENERATOR_VERSION = "4.0.1";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */
@@ -521,12 +519,13 @@ declare function resolveSafeOutputDirs(config: {
 /**
  * Refuses to replace a directory that this generator did not write.
  *
- * `swapIntoPlace` renames the previous output aside and deletes it, and the
- * scratch directory is deleted outright before every run. Path checks alone
- * cannot make that safe: `outDir: "src"` is a plausible typo, and it used to
- * delete the developer's entire source tree and exit 0.
+ * 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"): void;
+declare function assertReplaceable(target: string, label: "outDir" | "tmpDir", secretRules?: readonly SecretRule[]): void;
 /**
  * Generates the snapshot.
  *
@@ -538,4 +537,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, 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, 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 };

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, 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-5B4UVQLR.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, 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-RGIMMEAW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{types-CJqkePM4.d.cts → types-LSfwsKE-.d.cts}

@@ -44,8 +44,29 @@ interface MarkdownSummary {
  *                as one.
  */
 type SummaryQuality = "ast" | "structural" | "heuristic";
-type SkipReason = "asset" | "binary" | "read-error" | "not-file" | "sensitive-file" | "symlink" | "default-ignore" | "excluded";
+/**
+ * Why a discovered path was not emitted.
+ *
+ * Every reason below is produced by the scanner; nothing in the type is
+ * aspirational. `asset` was removed because no code path ever emitted it.
+ */
+type SkipReason = "binary" | "read-error" | "not-file"
+/** A credential-bearing name (`.env`, `*.pem`, `.npmrc`, …). */
+ | "sensitive-file"
+/** The path itself matched a secret rule; the emitted path is span-masked. */
+ | "sensitive-path"
+/** A directory link (never followed), or a link to neither file nor directory. */
+ | "symlink"
+/** A file link whose target resolves outside the scanned root. */
+ | "outside-root"
+/** Excluded by a `.gitignore` in a scan without git. */
+ | "gitignore"
+/** 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";
 interface SkipRecord {
+    /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
     reason: SkipReason;
     detail?: string;
@@ -103,12 +124,25 @@ interface PartMetadata {
 interface SecretRule {
     rule: string;
     pattern: RegExp;
+    /**
+     * Index of the capture group that holds the secret, when the rule has to match
+     * its surrounding context to identify one (`password: "…"`). Redaction then
+     * masks only that group, so the key and the rest of the line survive.
+     */
+    valueGroup?: number;
 }
-/** Shape accepted from JSON config files, where `pattern` can only be a string. */
-interface SecretRuleInput {
+/**
+ * Shape accepted for `secrets.customPatterns`.
+ *
+ * A bare `RegExp` or string is accepted because it is the documented form; the
+ * object form exists to name a rule. `valueGroup` is only useful with the object
+ * form, since a bare pattern has no group to name.
+ */
+type SecretRuleInput = {
     rule: string;
     pattern: RegExp | string;
-}
+    valueGroup?: number;
+} | RegExp | string;
 /**
  * A detected secret. Deliberately carries no excerpt of the matched source:
  * the previous `snippet` field was the vector by which raw credentials were

package/dist/{types-CJqkePM4.d.ts → types-LSfwsKE-.d.ts}

@@ -44,8 +44,29 @@ interface MarkdownSummary {
  *                as one.
  */
 type SummaryQuality = "ast" | "structural" | "heuristic";
-type SkipReason = "asset" | "binary" | "read-error" | "not-file" | "sensitive-file" | "symlink" | "default-ignore" | "excluded";
+/**
+ * Why a discovered path was not emitted.
+ *
+ * Every reason below is produced by the scanner; nothing in the type is
+ * aspirational. `asset` was removed because no code path ever emitted it.
+ */
+type SkipReason = "binary" | "read-error" | "not-file"
+/** A credential-bearing name (`.env`, `*.pem`, `.npmrc`, …). */
+ | "sensitive-file"
+/** The path itself matched a secret rule; the emitted path is span-masked. */
+ | "sensitive-path"
+/** A directory link (never followed), or a link to neither file nor directory. */
+ | "symlink"
+/** A file link whose target resolves outside the scanned root. */
+ | "outside-root"
+/** Excluded by a `.gitignore` in a scan without git. */
+ | "gitignore"
+/** 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";
 interface SkipRecord {
+    /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
     reason: SkipReason;
     detail?: string;
@@ -103,12 +124,25 @@ interface PartMetadata {
 interface SecretRule {
     rule: string;
     pattern: RegExp;
+    /**
+     * Index of the capture group that holds the secret, when the rule has to match
+     * its surrounding context to identify one (`password: "…"`). Redaction then
+     * masks only that group, so the key and the rest of the line survive.
+     */
+    valueGroup?: number;
 }
-/** Shape accepted from JSON config files, where `pattern` can only be a string. */
-interface SecretRuleInput {
+/**
+ * Shape accepted for `secrets.customPatterns`.
+ *
+ * A bare `RegExp` or string is accepted because it is the documented form; the
+ * object form exists to name a rule. `valueGroup` is only useful with the object
+ * form, since a bare pattern has no group to name.
+ */
+type SecretRuleInput = {
     rule: string;
     pattern: RegExp | string;
-}
+    valueGroup?: number;
+} | RegExp | string;
 /**
  * A detected secret. Deliberately carries no excerpt of the matched source:
  * the previous `snippet` field was the vector by which raw credentials were

package/docs/agent.md

@@ -1,45 +1,63 @@
 # Using this with an AI agent
 
-The package ships two things that make it usable by an agent that has never heard of it:
-a **machine-readable contract** and a **bundled skill**.
+The package ships two things that make it usable by an agent that has never heard of it: a
+**machine-readable contract** and a **bundled skill**.
 
-Nothing here needs to be installed globally, and no prior knowledge of the tool is
-required.
+Nothing needs to be installed globally and no prior knowledge of the tool is required.
 
 ## The three commands an agent needs
 
 ```bash
 # 1. Read the contract. This is the machine-readable replacement for --help.
-npx @ankurhalder/codebase-snapshot@latest describe --format json
+npx @ankurhalder/codebase-snapshot describe --format json
 
 # 2. Write a commented config that lists every setting (non-interactive).
-npx @ankurhalder/codebase-snapshot@latest init --yes
+npx @ankurhalder/codebase-snapshot init --yes
 
 # 3. Generate and verify.
-npx @ankurhalder/codebase-snapshot@latest generate
-npx @ankurhalder/codebase-snapshot@latest validate
+npx @ankurhalder/codebase-snapshot generate
+npx @ankurhalder/codebase-snapshot validate
 ```
 
-`describe` returns the invocation that works, an ordered `workflow` array, every command,
-every option with its default, the exit-code contract, all 25 presets, the artifact list,
-the config file names, the output layout, safety rules and a troubleshooting table — all
-as JSON on stdout.
+The bare package name works; pin `@latest` or `@4` when the same version must run on every
+machine.
 
-**Always pin the tag** (`@latest` or `@2`). A bare scoped spec can resolve to a bin-less
-placeholder manifest on some npm builds and exit 0 printing nothing; the pinned form
-cannot.
+## The contract
+
+`describe --format json` returns the whole tool as data on stdout:
+
+| Field | Contents |
+| :--- | :--- |
+| `invocation` | The supported one-shot and installed commands, and the bin names. |
+| `workflow` | An ordered six-step procedure: verify → understand → configure → generate → verify output → consume. |
+| `commands` | Every command with what it does, its positionals and its exit codes. |
+| `options` | Every option with its type, default, which commands it applies to, and a summary. |
+| `exitCodes` | `0` success, `1` drift or refused generation, `2` usage error. |
+| `presets` | All 25, with priority, recommended budget and ecosystem ignores. |
+| `artifacts` | Each artifact with its on/off default and what it contains. |
+| `config` | Every config filename and every setting with its default. |
+| `output` | The directory layout and how to read `manifest.json`. |
+| `safety` | What is excluded or redacted, and which directories are refused. |
+| `troubleshooting` | Symptom → cause → fix. |
+
+It is generated from the same code the CLI runs — presets, artifact names and versions are
+read directly — and a test compares its documented defaults against a real
+`generate --dry-run` manifest. If a default changes, the test fails rather than the contract
+silently misleading an agent.
+
+`describe` with no `--format` renders the same content for a human.
 
 ## The skill
 
 ```bash
-npx @ankurhalder/codebase-snapshot@latest skill            # print it (stdout)
-npx @ankurhalder/codebase-snapshot@latest skill --install  # write it into the repo
+npx @ankurhalder/codebase-snapshot skill            # print it (stdout)
+npx @ankurhalder/codebase-snapshot skill --install  # write it into the repository
 ```
 
 Printing goes to stdout deliberately, so it can be redirected:
 
 ```bash
-npx @ankurhalder/codebase-snapshot@latest skill > SKILL.md
+npx @ankurhalder/codebase-snapshot skill > SKILL.md
 ```
 
 `--install` writes the same skill to every location agents look at by default:
@@ -51,30 +69,52 @@ npx @ankurhalder/codebase-snapshot@latest skill > SKILL.md
 | `cursor` | `.cursor/rules/codebase-snapshot.mdc` | Cursor rules |
 
 ```bash
-skill --install --target claude    # one location
-skill --install                    # all three (default)
+npx @ankurhalder/codebase-snapshot skill --install --target claude   # one location
+npx @ankurhalder/codebase-snapshot skill --install                   # all three (default)
 ```
 
-The install is **idempotent and non-destructive**: re-running replaces only the block
-between `<!-- codebase-snapshot:skill:start -->` and
-`<!-- codebase-snapshot:skill:end -->`, so an `AGENTS.md` that already documents your
-conventions keeps them. `--format json` reports what was created, updated or unchanged.
+The install is **idempotent and non-destructive**: re-running replaces only the block between
+`<!-- codebase-snapshot:skill:start -->` and `<!-- codebase-snapshot:skill:end -->`, so an
+`AGENTS.md` that already documents your conventions keeps them. `--format json` reports what
+was created, updated or unchanged.
 
 `codebase-snapshot init` prints a reminder about this; it never installs the skill on its own.
 
 ## Why both a contract and a skill
 
-The contract is for **doing** — it is the data an agent needs to pick correct commands and
-options, and it is asserted against the real defaults in the test suite so it cannot drift
-into lying.
-
+The contract is for **doing** — the data an agent needs to pick correct commands and options.
 The skill is for **knowing when to act** — it carries the trigger conditions, the ordered
-workflow, and the surprises (sensitive files excluded by default, secrets redacted, the
-output directory being tool-owned) that an agent cannot infer from a schema.
-
-## Keeping the contract honest
-
-`describe` is generated from the same code the CLI runs — the preset list, artifact names,
-schema version and generator version are read directly, and a test compares its documented
-defaults against a real `generate --dry-run` manifest. If a default changes, the test fails
-rather than the contract silently misleading an agent.
+workflow, and the surprises an agent cannot infer from a schema: sensitive files excluded by
+default, secrets redacted, the output directory being tool-owned.
+
+## What an agent should avoid
+
+- **Do not point `--out-dir` at source code.** It is refused, and the refusal is deliberate.
+- **Do not add `--include-sensitive-files`** unless the user explicitly asked for credential
+  files; by default they are excluded and recorded as `sensitive-file` in `manifest.skipped[]`.
+- **Do not work around redaction.** If a value is masked, ask the user rather than reading the
+  original file.
+- **Do not assume exit 2 means the repository is broken.** It means the command was wrong.
+  Re-read the contract.
+- **Do not treat a bare `npx` that prints nothing as a repository problem.** A stale global
+  install shadows `npx`; see [Troubleshooting](troubleshooting.md#the-command-does-nothing).
+
+## Verifying an agent can drive it
+
+`tests/agent-simulation.test.js` runs the published instructions as an agent would: read
+`--help`, discover `describe`, then execute the six workflow steps in order against an 8-file
+Django fixture.
+
+It asserts what the contract promises at each step: `--version` prints a version, every
+published option states where it applies, `init --yes` writes a config naming **every**
+setting the contract lists, `generate --format json` exits `0` with
+`validation.status: "passed"` and the preset `python-django`, every fixture file is either in
+`manifest.files[]` or explained in `manifest.skipped[]`, each `files[]` entry carries its
+classification and hash, and `validate` then exits `0`. If an agent following the published
+words would fail, that test fails.
+
+When you parse the manifest, remember what is conditional: `manifest.files[]` carries
+`relativePath`, `layer`, `kind`, `language`, `part`, `inclusionMode` and `hashSha256` for
+every included file, but `summary` and `summaryQuality` only for a language the tool can
+analyse. A `.gitignore` or plain-text entry has neither key, and a file whose summary was too
+large for its part carries `summaryOmitted: true` instead of a `summary`.