codebase-snapshot 0.9.0 → 0.9.4

package/dist/index.d.cts

@@ -292,7 +292,17 @@ interface PresetDefinition {
     readonly name: string;
     /** Higher wins. Framework presets outrank repository shapes. */
     readonly priority: number;
-    detect(context: PresetContext): boolean;
+    /**
+     * Why this preset matches, or null. Absent on the fallback preset only.
+     *
+     * Returning the reason rather than `true` is what lets the wizard print
+     * `Because next.config.ts` instead of asking the developer to trust a verdict they
+     * cannot check — and it is what makes an `--autopilot` decision auditable after
+     * the fact. See `evidence.ts` for the helpers the detectors are built from.
+     */
+    detect?(context: PresetContext): string | null;
+    /** Matches everything, and is only reached when no detector reported evidence. */
+    readonly fallback?: boolean;
     readonly layers: LayerRule[];
     readonly kinds: KindRule[];
     /** Ecosystem-specific ignores, merged with the user's `excludePatterns`. */
@@ -307,12 +317,26 @@ interface DetectedPreset {
     /** Ecosystem ignores the scanner should apply in addition to the user's. */
     exclude: string[];
     recommendedBudget: ByteSize | null;
+    /**
+     * The signal that matched, e.g. `next.config.ts`.
+     *
+     * Null when the preset was forced by name — nothing was detected, so there is
+     * nothing to report — and null for the fallback preset.
+     */
+    reason: string | null;
+    /**
+     * True only when nothing matched and the fallback preset was used.
+     *
+     * A forced preset is never a fallback: the developer asked for it. The first-run
+     * wizard keys its "could not tell what this is, please choose" prompt off this.
+     */
+    fallback: boolean;
 }
 /**
  * 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
+ * Ordering is the whole detection model: the first definition whose detector reports
+ * evidence wins, so the list is sorted once at module load rather than being
  * hand-maintained in the right order.
  */
 declare const PRESETS: readonly PresetDefinition[];
@@ -398,7 +422,7 @@ declare function validateSnapshot(configInput: ResolvedSnapshotConfig | Snapshot
  * `package.json` carries the same version; `npm run verify` compares the two.
  */
 declare const GENERATOR_NAME = "codebase-snapshot";
-declare const GENERATOR_VERSION = "0.9.0";
+declare const GENERATOR_VERSION = "0.9.4";
 
 declare const DEFAULT_SECRET_PATTERNS: SecretRule[];
 
@@ -584,6 +608,10 @@ interface InitResult {
     /** True when an existing config was kept instead of being written. */
     reused: boolean;
     preset: string;
+    /** The signal the detector matched, e.g. `next.config.ts`; null when nothing detected it. */
+    reason: string | null;
+    /** True when no preset matched and the fallback was used. */
+    fallback: boolean;
     scripts: string[];
     gitignoreEntries: string[];
     dependency: InitDependency;
@@ -596,9 +624,87 @@ interface InitResult {
  * 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.
+ *
+ * Every question starts on its answer, so pressing enter through the whole wizard
+ * produces the recommended configuration — and the first question is a single
+ * "use the recommended setup" for a project that was recognised, which is what makes
+ * `snapshot` alone a complete command.
  */
 declare function runInit(options: InitOptions): Promise<InitResult>;
 
+/**
+ * What "just type `snapshot`" does.
+ *
+ * The decision lives here, away from the CLI's input and output, so it can be tested as
+ * a table rather than by driving a terminal. The rule it encodes is the repository's own:
+ * a first run either asks, or refuses out loud — it never silently falls back to the
+ * built-in defaults, because a snapshot shaped by settings the developer never saw is
+ * indistinguishable from a broken one.
+ */
+interface FirstRunFacts {
+    /** A config file, or a `"snapshot"` key in package.json, exists. */
+    hasConfig: boolean;
+    /** A snapshot this tool wrote is already on disk. */
+    hasPriorSnapshot: boolean;
+    /** stdin and stdout are both TTYs, and the output format is text. */
+    interactive: boolean;
+    /** `--autopilot`: never ask, set everything up. */
+    autopilot: boolean;
+    /** The target directory holds no files at all. */
+    emptyTarget: boolean;
+}
+type FirstRunRefusal = "empty" | "undecided";
+type FirstRunPlan = 
+/** Nothing to set up: run the generate that was asked for. */
+{
+    action: "generate";
+}
+/** Set the repository up first, asking the developer about the detected choices. */
+ | {
+    action: "setup";
+    interactive: true;
+}
+/** Set the repository up first, deciding everything — `--autopilot`. */
+ | {
+    action: "setup";
+    interactive: false;
+}
+/** Stop, with a message that says what to run instead. */
+ | {
+    action: "refuse";
+    exitCode: number;
+    reason: FirstRunRefusal;
+};
+/** The message a non-interactive first run gets. It has to name the way out. */
+declare function firstRunMessage(reason: FirstRunRefusal, cwd: string): string;
+/**
+ * The first-run decision table.
+ *
+ * `--autopilot` is checked first because it is an explicit instruction: with an existing
+ * config, setup still adds the npm script, the devDependency and the install the
+ * repository may be missing. Everything else defers to an existing config or an existing
+ * snapshot, so a repository that has been generated before never sees a wizard twice.
+ *
+ * An empty directory is refused before anything else: setting it up would install a
+ * devDependency for a repository nobody has started yet.
+ */
+declare function planFirstRun(facts: FirstRunFacts): FirstRunPlan;
+/**
+ * True when there is nothing in `cwd` but version-control or operating-system metadata.
+ *
+ * Setting up a project that has no files produces an empty snapshot and a devDependency
+ * for a repository nobody has started yet, so the answer is "not yet", not "done".
+ */
+declare function isEffectivelyEmpty(cwd: string): boolean;
+/**
+ * True when `outDir` holds a snapshot this tool wrote.
+ *
+ * The ownership marker is the same evidence the output-directory guard uses, so a
+ * directory that merely happens to be named `snapshot` does not count as "we have been
+ * here before" and cannot silence the first-run question.
+ */
+declare function hasPriorSnapshot(cwd: string, outDir: string): boolean;
+
 /** What the wizard decided, after prompts or flags. */
 interface WizardAnswers {
     preset: string;
@@ -707,4 +813,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, 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 };
+export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FileEntry, type FirstRunFacts, type FirstRunPlan, type FirstRunRefusal, 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, firstRunMessage, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, hasPriorSnapshot, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };

package/dist/index.d.ts

@@ -292,7 +292,17 @@ interface PresetDefinition {
     readonly name: string;
     /** Higher wins. Framework presets outrank repository shapes. */
     readonly priority: number;
-    detect(context: PresetContext): boolean;
+    /**
+     * Why this preset matches, or null. Absent on the fallback preset only.
+     *
+     * Returning the reason rather than `true` is what lets the wizard print
+     * `Because next.config.ts` instead of asking the developer to trust a verdict they
+     * cannot check — and it is what makes an `--autopilot` decision auditable after
+     * the fact. See `evidence.ts` for the helpers the detectors are built from.
+     */
+    detect?(context: PresetContext): string | null;
+    /** Matches everything, and is only reached when no detector reported evidence. */
+    readonly fallback?: boolean;
     readonly layers: LayerRule[];
     readonly kinds: KindRule[];
     /** Ecosystem-specific ignores, merged with the user's `excludePatterns`. */
@@ -307,12 +317,26 @@ interface DetectedPreset {
     /** Ecosystem ignores the scanner should apply in addition to the user's. */
     exclude: string[];
     recommendedBudget: ByteSize | null;
+    /**
+     * The signal that matched, e.g. `next.config.ts`.
+     *
+     * Null when the preset was forced by name — nothing was detected, so there is
+     * nothing to report — and null for the fallback preset.
+     */
+    reason: string | null;
+    /**
+     * True only when nothing matched and the fallback preset was used.
+     *
+     * A forced preset is never a fallback: the developer asked for it. The first-run
+     * wizard keys its "could not tell what this is, please choose" prompt off this.
+     */
+    fallback: boolean;
 }
 /**
  * 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
+ * Ordering is the whole detection model: the first definition whose detector reports
+ * evidence wins, so the list is sorted once at module load rather than being
  * hand-maintained in the right order.
  */
 declare const PRESETS: readonly PresetDefinition[];
@@ -398,7 +422,7 @@ declare function validateSnapshot(configInput: ResolvedSnapshotConfig | Snapshot
  * `package.json` carries the same version; `npm run verify` compares the two.
  */
 declare const GENERATOR_NAME = "codebase-snapshot";
-declare const GENERATOR_VERSION = "0.9.0";
+declare const GENERATOR_VERSION = "0.9.4";
 
 declare const DEFAULT_SECRET_PATTERNS: SecretRule[];
 
@@ -584,6 +608,10 @@ interface InitResult {
     /** True when an existing config was kept instead of being written. */
     reused: boolean;
     preset: string;
+    /** The signal the detector matched, e.g. `next.config.ts`; null when nothing detected it. */
+    reason: string | null;
+    /** True when no preset matched and the fallback was used. */
+    fallback: boolean;
     scripts: string[];
     gitignoreEntries: string[];
     dependency: InitDependency;
@@ -596,9 +624,87 @@ interface InitResult {
  * 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.
+ *
+ * Every question starts on its answer, so pressing enter through the whole wizard
+ * produces the recommended configuration — and the first question is a single
+ * "use the recommended setup" for a project that was recognised, which is what makes
+ * `snapshot` alone a complete command.
  */
 declare function runInit(options: InitOptions): Promise<InitResult>;
 
+/**
+ * What "just type `snapshot`" does.
+ *
+ * The decision lives here, away from the CLI's input and output, so it can be tested as
+ * a table rather than by driving a terminal. The rule it encodes is the repository's own:
+ * a first run either asks, or refuses out loud — it never silently falls back to the
+ * built-in defaults, because a snapshot shaped by settings the developer never saw is
+ * indistinguishable from a broken one.
+ */
+interface FirstRunFacts {
+    /** A config file, or a `"snapshot"` key in package.json, exists. */
+    hasConfig: boolean;
+    /** A snapshot this tool wrote is already on disk. */
+    hasPriorSnapshot: boolean;
+    /** stdin and stdout are both TTYs, and the output format is text. */
+    interactive: boolean;
+    /** `--autopilot`: never ask, set everything up. */
+    autopilot: boolean;
+    /** The target directory holds no files at all. */
+    emptyTarget: boolean;
+}
+type FirstRunRefusal = "empty" | "undecided";
+type FirstRunPlan = 
+/** Nothing to set up: run the generate that was asked for. */
+{
+    action: "generate";
+}
+/** Set the repository up first, asking the developer about the detected choices. */
+ | {
+    action: "setup";
+    interactive: true;
+}
+/** Set the repository up first, deciding everything — `--autopilot`. */
+ | {
+    action: "setup";
+    interactive: false;
+}
+/** Stop, with a message that says what to run instead. */
+ | {
+    action: "refuse";
+    exitCode: number;
+    reason: FirstRunRefusal;
+};
+/** The message a non-interactive first run gets. It has to name the way out. */
+declare function firstRunMessage(reason: FirstRunRefusal, cwd: string): string;
+/**
+ * The first-run decision table.
+ *
+ * `--autopilot` is checked first because it is an explicit instruction: with an existing
+ * config, setup still adds the npm script, the devDependency and the install the
+ * repository may be missing. Everything else defers to an existing config or an existing
+ * snapshot, so a repository that has been generated before never sees a wizard twice.
+ *
+ * An empty directory is refused before anything else: setting it up would install a
+ * devDependency for a repository nobody has started yet.
+ */
+declare function planFirstRun(facts: FirstRunFacts): FirstRunPlan;
+/**
+ * True when there is nothing in `cwd` but version-control or operating-system metadata.
+ *
+ * Setting up a project that has no files produces an empty snapshot and a devDependency
+ * for a repository nobody has started yet, so the answer is "not yet", not "done".
+ */
+declare function isEffectivelyEmpty(cwd: string): boolean;
+/**
+ * True when `outDir` holds a snapshot this tool wrote.
+ *
+ * The ownership marker is the same evidence the output-directory guard uses, so a
+ * directory that merely happens to be named `snapshot` does not count as "we have been
+ * here before" and cannot silence the first-run question.
+ */
+declare function hasPriorSnapshot(cwd: string, outDir: string): boolean;
+
 /** What the wizard decided, after prompts or flags. */
 interface WizardAnswers {
     preset: string;
@@ -707,4 +813,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, 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 };
+export { ARTIFACT_NAMES, ArtifactSelection, ByteSize, CliOptions, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, DiscoveryMode, type ExplainResult, FileEntry, type FirstRunFacts, type FirstRunPlan, type FirstRunRefusal, 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, firstRunMessage, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, hasPriorSnapshot, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, 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, 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 } from './chunk-FJ4RQYY2.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, firstRunMessage, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, hasPriorSnapshot, isBinaryBuffer, isBinaryExtension, isBinaryFile, isEffectivelyEmpty, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, planFirstRun, profileForPath, renderConfig, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-FCWD4LY7.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map