codebase-snapshot 0.9.9 → 0.9.12

package/dist/cli.d.cts

@@ -1,6 +1,229 @@
-import { O as OutputFormat, D as DiscoveryMode } from './types-Ca4PmkiQ.cjs';
+import { O as OutputFormat, D as DiscoveryMode, R as ResolvedSnapshotConfig } from './types-CTewen3J.cjs';
+
+/**
+ * The machine-readable description of this tool.
+ *
+ * Everything an agent needs to use the tool without prior knowledge lives here:
+ * the invocation that works, the ordered workflow, the full option table with
+ * defaults, the exit-code contract, the presets, the artifacts, the config file
+ * names and the output layout. It exists because `--help` is prose written for a
+ * human, and an agent with no context cannot reliably parse prose.
+ *
+ * `codebase-snapshot describe --format json` prints this. Keep it in sync with the CLI — the
+ * test suite asserts that the defaults here match `resolveConfig`'s defaults, so
+ * drift fails the build rather than misleading an agent.
+ */
+interface AgentContract {
+    generator: string;
+    package: string;
+    version: string;
+    schemaVersion: string;
+    contractVersion: string;
+    summary: string;
+    requires: {
+        node: string;
+        dependencies: string[];
+    };
+    invocation: {
+        oneShot: string;
+        installed: string;
+        bins: string[];
+        notes: string[];
+    };
+    workflow: Array<{
+        step: number;
+        id: string;
+        run: string;
+        expect: string;
+        notes?: string;
+    }>;
+    commands: Array<{
+        name: string;
+        aliases: string[];
+        summary: string;
+        positionals: string[];
+        exits: number[];
+    }>;
+    exitCodes: Record<string, string>;
+    options: Array<{
+        flag: string;
+        type: "string" | "boolean";
+        default?: string | number | boolean;
+        appliesTo: string;
+        summary: string;
+    }>;
+    presets: Array<{
+        name: string;
+        priority: number;
+        recommendedBudget: string | number;
+        excludes: string[];
+    }>;
+    artifacts: Array<{
+        name: string;
+        default: boolean;
+        summary: string;
+    }>;
+    config: {
+        fileNames: string[];
+        settings: Array<{
+            key: string;
+            type: string;
+            default: string | number | boolean | null;
+            summary: string;
+        }>;
+    };
+    output: {
+        layout: string[];
+        notes: string[];
+    };
+    safety: string[];
+    troubleshooting: Array<{
+        symptom: string;
+        cause: string;
+        fix: string;
+    }>;
+    /**
+     * The MCP server, described from the same objects the server serves.
+     *
+     * This block exists so an agent that has only ever run `describe` learns the server exists, and
+     * a test compares it against a live `tools/list` so the two cannot describe different tools.
+     */
+    mcp: {
+        command: string;
+        transport: "stdio";
+        protocolVersions: {
+            modern: string[];
+            legacy: string[];
+            default: string;
+        };
+        tools: Array<{
+            name: string;
+            title: string;
+            summary: string;
+            readOnly: boolean;
+            parameters: string[];
+            required: string[];
+        }>;
+        prompts: Array<{
+            name: string;
+            summary: string;
+            arguments: string[];
+        }>;
+        resources: string[];
+        resourceTemplates: string[];
+        notes: string[];
+    };
+}
+/** Builds the contract document. Cheap enough to call on every `describe`. */
+declare function buildAgentContract(): AgentContract;
 
 type Command = "generate" | "validate" | "report" | "init" | "setup" | "explain" | "diff" | "describe" | "skill" | "mcp";
+declare const CLI_OPTIONS: {
+    readonly cwd: {
+        readonly type: "string";
+    };
+    readonly "out-dir": {
+        readonly type: "string";
+    };
+    readonly "max-part-bytes": {
+        readonly type: "string";
+    };
+    readonly "large-file-bytes": {
+        readonly type: "string";
+    };
+    readonly "max-monolith-bytes": {
+        readonly type: "string";
+    };
+    readonly "include-monolith": {
+        readonly type: "boolean";
+    };
+    readonly "include-sensitive-files": {
+        readonly type: "boolean";
+    };
+    readonly "skip-artifacts": {
+        readonly type: "string";
+    };
+    readonly "only-artifacts": {
+        readonly type: "string";
+    };
+    readonly format: {
+        readonly type: "string";
+    };
+    readonly mode: {
+        readonly type: "string";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+    };
+    readonly watch: {
+        readonly type: "boolean";
+    };
+    readonly "no-config": {
+        readonly type: "boolean";
+    };
+    readonly discovery: {
+        readonly type: "string";
+    };
+    readonly "max-part-tokens": {
+        readonly type: "string";
+    };
+    readonly preset: {
+        readonly type: "string";
+    };
+    readonly include: {
+        readonly type: "string";
+    };
+    readonly exclude: {
+        readonly type: "string";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly type: "boolean";
+    };
+    readonly autopilot: {
+        readonly type: "boolean";
+    };
+    readonly install: {
+        readonly type: "boolean";
+    };
+    readonly "no-install": {
+        readonly type: "boolean";
+    };
+    readonly target: {
+        readonly type: "string";
+    };
+    readonly "no-update-check": {
+        readonly type: "boolean";
+    };
+    readonly "install-hook": {
+        readonly type: "boolean";
+    };
+    readonly "changed-since": {
+        readonly type: "string";
+    };
+    readonly "with-dependents": {
+        readonly type: "boolean";
+    };
+    readonly staged: {
+        readonly type: "boolean";
+    };
+    readonly skeleton: {
+        readonly type: "boolean";
+    };
+    readonly sarif: {
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+    };
+    readonly version: {
+        readonly type: "boolean";
+        readonly short: "v";
+    };
+};
 /** A user-input problem: printed without a stack trace, exits 2. */
 declare class UsageError extends Error {
 }
@@ -41,18 +264,44 @@ interface ParsedInvocation {
     includeMonolith?: boolean;
     includeSensitiveFiles?: boolean;
     maxPartBytes?: number;
+    /** A per-part ceiling in tokens; resolved into `maxPartBytes` by `resolveConfig`. */
+    maxPartTokens?: number;
     largeFileBytes?: number;
     maxMonolithBytes?: number | null;
     skipArtifacts?: string[];
+    /**
+     * The artifacts named by `--only-artifacts`, kept separately from the derived
+     * `skipArtifacts`.
+     *
+     * `--only-artifacts monolith` means "the six others off, the monolith on", which cannot
+     * be expressed by `skipArtifacts` alone: the monolith is off by default, so turning the
+     * others off left *everything* off and `init`/`setup` wrote a config that generated
+     * nothing. The wizard resolves this list itself.
+     */
+    onlyArtifacts?: string[];
     /** How candidates are discovered; `auto` when unset. */
     discovery?: DiscoveryMode;
+    /** The user asked not to be told about newer releases. */
+    noUpdateCheck?: boolean;
+    /** `init` and `setup` only: write a pre-commit hook that gates on `validate`. */
+    installHook?: boolean;
+    /** Only files changed since this git ref. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** With the two above: also include the files that import a changed one. */
+    withDependents?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX. */
+    skeleton?: boolean;
+    /** Also write reports/audit.sarif for a CI security gate. */
+    sarif?: boolean;
 }
 declare function parsePositiveInteger(raw: string | undefined, optionName: string, minimum: number): number | undefined;
 /**
  * Parses a byte-budget option, accepting human-readable units (`120k`, `1.5mb`)
  * as well as raw byte counts.
  */
-declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number, unit?: string): number | undefined;
 /**
  * Parses argv.
  *
@@ -136,5 +385,35 @@ declare function isGeneratedWatchPath(candidate: string, paths: WatchPaths): boo
  *   because Windows does not always name the path our own writes produced.
  */
 declare function decideWatchEvent(state: WatchState, event: WatchEvent, paths: WatchPaths): WatchDecision;
+/**
+ * Re-generates on every change under `cwd`.
+ *
+ * Events inside the resolved output and temporary directories are ignored, so
+ * writing a snapshot cannot feed the watcher. A source event that arrives while
+ * a run is in flight sets a pending flag and gets exactly one follow-up run;
+ * the settle window only suppresses unattributed events.
+ */
+/**
+ * The directories the watcher must ignore, derived from a resolved config.
+ *
+ * A function rather than an inline literal because the loop now recomputes it after every config
+ * reload: a watcher that keeps the `outDir` it started with treats the new one as user content,
+ * regenerates, writes, sees that write, and never settles.
+ */
+declare function watchPathsFor(config: ResolvedSnapshotConfig): WatchPaths;
+/**
+ * Why `--watch` cannot work here, or `null` when it can.
+ *
+ * `fs.watch(dir, { recursive: true })` is only available on Linux from Node 20.13: before that it
+ * throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. The package declares `engines: >=18`, so a user can
+ * legitimately be running a Node that cannot honour this flag — and what they got was an uncaught
+ * exception *after* the first snapshot had been written and "Watching for changes" printed, which
+ * reads as a broken tool rather than as a version requirement.
+ *
+ * The platform and version are parameters so the boundary is testable off the machine that happens
+ * to run the tests: this is the kind of check that is written on one OS and shipped broken to
+ * another, which is precisely how it went unnoticed.
+ */
+declare function watchSupportProblem(platform?: string, version?: string): string | null;
 
-export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };
+export { CLI_OPTIONS, UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, buildAgentContract, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger, watchPathsFor, watchSupportProblem };

package/dist/cli.d.ts

@@ -1,6 +1,229 @@
-import { O as OutputFormat, D as DiscoveryMode } from './types-Ca4PmkiQ.js';
+import { O as OutputFormat, D as DiscoveryMode, R as ResolvedSnapshotConfig } from './types-CTewen3J.js';
+
+/**
+ * The machine-readable description of this tool.
+ *
+ * Everything an agent needs to use the tool without prior knowledge lives here:
+ * the invocation that works, the ordered workflow, the full option table with
+ * defaults, the exit-code contract, the presets, the artifacts, the config file
+ * names and the output layout. It exists because `--help` is prose written for a
+ * human, and an agent with no context cannot reliably parse prose.
+ *
+ * `codebase-snapshot describe --format json` prints this. Keep it in sync with the CLI — the
+ * test suite asserts that the defaults here match `resolveConfig`'s defaults, so
+ * drift fails the build rather than misleading an agent.
+ */
+interface AgentContract {
+    generator: string;
+    package: string;
+    version: string;
+    schemaVersion: string;
+    contractVersion: string;
+    summary: string;
+    requires: {
+        node: string;
+        dependencies: string[];
+    };
+    invocation: {
+        oneShot: string;
+        installed: string;
+        bins: string[];
+        notes: string[];
+    };
+    workflow: Array<{
+        step: number;
+        id: string;
+        run: string;
+        expect: string;
+        notes?: string;
+    }>;
+    commands: Array<{
+        name: string;
+        aliases: string[];
+        summary: string;
+        positionals: string[];
+        exits: number[];
+    }>;
+    exitCodes: Record<string, string>;
+    options: Array<{
+        flag: string;
+        type: "string" | "boolean";
+        default?: string | number | boolean;
+        appliesTo: string;
+        summary: string;
+    }>;
+    presets: Array<{
+        name: string;
+        priority: number;
+        recommendedBudget: string | number;
+        excludes: string[];
+    }>;
+    artifacts: Array<{
+        name: string;
+        default: boolean;
+        summary: string;
+    }>;
+    config: {
+        fileNames: string[];
+        settings: Array<{
+            key: string;
+            type: string;
+            default: string | number | boolean | null;
+            summary: string;
+        }>;
+    };
+    output: {
+        layout: string[];
+        notes: string[];
+    };
+    safety: string[];
+    troubleshooting: Array<{
+        symptom: string;
+        cause: string;
+        fix: string;
+    }>;
+    /**
+     * The MCP server, described from the same objects the server serves.
+     *
+     * This block exists so an agent that has only ever run `describe` learns the server exists, and
+     * a test compares it against a live `tools/list` so the two cannot describe different tools.
+     */
+    mcp: {
+        command: string;
+        transport: "stdio";
+        protocolVersions: {
+            modern: string[];
+            legacy: string[];
+            default: string;
+        };
+        tools: Array<{
+            name: string;
+            title: string;
+            summary: string;
+            readOnly: boolean;
+            parameters: string[];
+            required: string[];
+        }>;
+        prompts: Array<{
+            name: string;
+            summary: string;
+            arguments: string[];
+        }>;
+        resources: string[];
+        resourceTemplates: string[];
+        notes: string[];
+    };
+}
+/** Builds the contract document. Cheap enough to call on every `describe`. */
+declare function buildAgentContract(): AgentContract;
 
 type Command = "generate" | "validate" | "report" | "init" | "setup" | "explain" | "diff" | "describe" | "skill" | "mcp";
+declare const CLI_OPTIONS: {
+    readonly cwd: {
+        readonly type: "string";
+    };
+    readonly "out-dir": {
+        readonly type: "string";
+    };
+    readonly "max-part-bytes": {
+        readonly type: "string";
+    };
+    readonly "large-file-bytes": {
+        readonly type: "string";
+    };
+    readonly "max-monolith-bytes": {
+        readonly type: "string";
+    };
+    readonly "include-monolith": {
+        readonly type: "boolean";
+    };
+    readonly "include-sensitive-files": {
+        readonly type: "boolean";
+    };
+    readonly "skip-artifacts": {
+        readonly type: "string";
+    };
+    readonly "only-artifacts": {
+        readonly type: "string";
+    };
+    readonly format: {
+        readonly type: "string";
+    };
+    readonly mode: {
+        readonly type: "string";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+    };
+    readonly watch: {
+        readonly type: "boolean";
+    };
+    readonly "no-config": {
+        readonly type: "boolean";
+    };
+    readonly discovery: {
+        readonly type: "string";
+    };
+    readonly "max-part-tokens": {
+        readonly type: "string";
+    };
+    readonly preset: {
+        readonly type: "string";
+    };
+    readonly include: {
+        readonly type: "string";
+    };
+    readonly exclude: {
+        readonly type: "string";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly type: "boolean";
+    };
+    readonly autopilot: {
+        readonly type: "boolean";
+    };
+    readonly install: {
+        readonly type: "boolean";
+    };
+    readonly "no-install": {
+        readonly type: "boolean";
+    };
+    readonly target: {
+        readonly type: "string";
+    };
+    readonly "no-update-check": {
+        readonly type: "boolean";
+    };
+    readonly "install-hook": {
+        readonly type: "boolean";
+    };
+    readonly "changed-since": {
+        readonly type: "string";
+    };
+    readonly "with-dependents": {
+        readonly type: "boolean";
+    };
+    readonly staged: {
+        readonly type: "boolean";
+    };
+    readonly skeleton: {
+        readonly type: "boolean";
+    };
+    readonly sarif: {
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+    };
+    readonly version: {
+        readonly type: "boolean";
+        readonly short: "v";
+    };
+};
 /** A user-input problem: printed without a stack trace, exits 2. */
 declare class UsageError extends Error {
 }
@@ -41,18 +264,44 @@ interface ParsedInvocation {
     includeMonolith?: boolean;
     includeSensitiveFiles?: boolean;
     maxPartBytes?: number;
+    /** A per-part ceiling in tokens; resolved into `maxPartBytes` by `resolveConfig`. */
+    maxPartTokens?: number;
     largeFileBytes?: number;
     maxMonolithBytes?: number | null;
     skipArtifacts?: string[];
+    /**
+     * The artifacts named by `--only-artifacts`, kept separately from the derived
+     * `skipArtifacts`.
+     *
+     * `--only-artifacts monolith` means "the six others off, the monolith on", which cannot
+     * be expressed by `skipArtifacts` alone: the monolith is off by default, so turning the
+     * others off left *everything* off and `init`/`setup` wrote a config that generated
+     * nothing. The wizard resolves this list itself.
+     */
+    onlyArtifacts?: string[];
     /** How candidates are discovered; `auto` when unset. */
     discovery?: DiscoveryMode;
+    /** The user asked not to be told about newer releases. */
+    noUpdateCheck?: boolean;
+    /** `init` and `setup` only: write a pre-commit hook that gates on `validate`. */
+    installHook?: boolean;
+    /** Only files changed since this git ref. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** With the two above: also include the files that import a changed one. */
+    withDependents?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX. */
+    skeleton?: boolean;
+    /** Also write reports/audit.sarif for a CI security gate. */
+    sarif?: boolean;
 }
 declare function parsePositiveInteger(raw: string | undefined, optionName: string, minimum: number): number | undefined;
 /**
  * Parses a byte-budget option, accepting human-readable units (`120k`, `1.5mb`)
  * as well as raw byte counts.
  */
-declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number, unit?: string): number | undefined;
 /**
  * Parses argv.
  *
@@ -136,5 +385,35 @@ declare function isGeneratedWatchPath(candidate: string, paths: WatchPaths): boo
  *   because Windows does not always name the path our own writes produced.
  */
 declare function decideWatchEvent(state: WatchState, event: WatchEvent, paths: WatchPaths): WatchDecision;
+/**
+ * Re-generates on every change under `cwd`.
+ *
+ * Events inside the resolved output and temporary directories are ignored, so
+ * writing a snapshot cannot feed the watcher. A source event that arrives while
+ * a run is in flight sets a pending flag and gets exactly one follow-up run;
+ * the settle window only suppresses unattributed events.
+ */
+/**
+ * The directories the watcher must ignore, derived from a resolved config.
+ *
+ * A function rather than an inline literal because the loop now recomputes it after every config
+ * reload: a watcher that keeps the `outDir` it started with treats the new one as user content,
+ * regenerates, writes, sees that write, and never settles.
+ */
+declare function watchPathsFor(config: ResolvedSnapshotConfig): WatchPaths;
+/**
+ * Why `--watch` cannot work here, or `null` when it can.
+ *
+ * `fs.watch(dir, { recursive: true })` is only available on Linux from Node 20.13: before that it
+ * throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. The package declares `engines: >=18`, so a user can
+ * legitimately be running a Node that cannot honour this flag — and what they got was an uncaught
+ * exception *after* the first snapshot had been written and "Watching for changes" printed, which
+ * reads as a broken tool rather than as a version requirement.
+ *
+ * The platform and version are parameters so the boundary is testable off the machine that happens
+ * to run the tests: this is the kind of check that is written on one OS and shipped broken to
+ * another, which is precisely how it went unnoticed.
+ */
+declare function watchSupportProblem(platform?: string, version?: string): string | null;
 
-export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };
+export { CLI_OPTIONS, UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, buildAgentContract, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger, watchPathsFor, watchSupportProblem };