@ankurhalder/codebase-snapshot 0.0.0-stage → 2.0.0

package/dist/cli.d.cts

@@ -0,0 +1,40 @@
+import { O as OutputFormat } from './types-S-5eRuRc.cjs';
+
+type Command = "generate" | "validate" | "report" | "init" | "explain" | "diff";
+/** A user-input problem: printed without a stack trace, exits 2. */
+declare class UsageError extends Error {
+}
+interface ParsedInvocation {
+    command: Command;
+    /** Positional arguments that follow the command name. */
+    args: string[];
+    format: OutputFormat;
+    dryRun: boolean;
+    watch: boolean;
+    cwd: string;
+    outDir?: string;
+    includeMonolith?: boolean;
+    includeSensitiveFiles?: boolean;
+    maxPartBytes?: number;
+    largeFileBytes?: number;
+    maxMonolithBytes?: number | null;
+    skipArtifacts?: string[];
+}
+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;
+/**
+ * Parses argv.
+ *
+ * Uses `node:util.parseArgs` in strict mode, so `--option=value` works, unknown
+ * flags are rejected instead of silently ignored, and a typo can no longer fall
+ * through to the writable `generate` command.
+ */
+declare function parseCliArgs(argv: string[]): ParsedInvocation;
+/** Runs the CLI and returns the process exit code. */
+declare function main(argv?: string[]): Promise<number>;
+
+export { UsageError, main, parseByteOption, parseCliArgs, parsePositiveInteger };

package/dist/cli.d.ts

@@ -0,0 +1,40 @@
+import { O as OutputFormat } from './types-S-5eRuRc.js';
+
+type Command = "generate" | "validate" | "report" | "init" | "explain" | "diff";
+/** A user-input problem: printed without a stack trace, exits 2. */
+declare class UsageError extends Error {
+}
+interface ParsedInvocation {
+    command: Command;
+    /** Positional arguments that follow the command name. */
+    args: string[];
+    format: OutputFormat;
+    dryRun: boolean;
+    watch: boolean;
+    cwd: string;
+    outDir?: string;
+    includeMonolith?: boolean;
+    includeSensitiveFiles?: boolean;
+    maxPartBytes?: number;
+    largeFileBytes?: number;
+    maxMonolithBytes?: number | null;
+    skipArtifacts?: string[];
+}
+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;
+/**
+ * Parses argv.
+ *
+ * Uses `node:util.parseArgs` in strict mode, so `--option=value` works, unknown
+ * flags are rejected instead of silently ignored, and a typo can no longer fall
+ * through to the writable `generate` command.
+ */
+declare function parseCliArgs(argv: string[]): ParsedInvocation;
+/** Runs the CLI and returns the process exit code. */
+declare function main(argv?: string[]): Promise<number>;
+
+export { UsageError, main, parseByteOption, parseCliArgs, parsePositiveInteger };

package/dist/cli.js

@@ -0,0 +1,487 @@
+import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, supportsTypeScriptImports, renderExplainText } from './chunk-RGDVLQTT.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseArgs } from 'util';
+
+var VERSION = GENERATOR_VERSION;
+var COMMAND_ALIASES = /* @__PURE__ */ new Map([
+  ["generate", "generate"],
+  ["validate", "validate"],
+  ["check", "validate"],
+  ["report", "report"],
+  ["init", "init"],
+  ["explain", "explain"],
+  ["diff", "diff"]
+]);
+var COMMAND_ARITY = {
+  generate: 0,
+  validate: 0,
+  report: 0,
+  init: 0,
+  explain: 1,
+  diff: 2
+};
+var CLI_OPTIONS = {
+  cwd: { type: "string" },
+  "out-dir": { type: "string" },
+  "max-part-bytes": { type: "string" },
+  "large-file-bytes": { type: "string" },
+  "max-monolith-bytes": { type: "string" },
+  "include-monolith": { type: "boolean" },
+  "include-sensitive-files": { type: "boolean" },
+  "skip-artifacts": { type: "string" },
+  "only-artifacts": { type: "string" },
+  format: { type: "string" },
+  mode: { type: "string" },
+  "dry-run": { type: "boolean" },
+  watch: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" }
+};
+var UsageError = class extends Error {
+};
+var USAGE = `
+${GENERATOR_NAME} v${VERSION}
+Production-grade LLM codebase snapshot generator, auditor, and AST partitioner
+
+Usage:
+  codebase-snapshot [command] [options]
+  snap [command] [options]
+
+Commands:
+  generate (default)   Generate a complete partitioned codebase snapshot
+  validate, check      Validate snapshot integrity and check for drift
+  init                 Generate a starter snapshot.config file
+  report               Print codebase health, layer metrics, and secret audit
+  explain <path>       Show how one path would be treated: layer, kind, part, skips
+  diff <a> <b>         Compare two snapshots (directories or manifest.json files)
+
+Options:
+  --cwd <path>                  Target repository directory (default: current directory)
+  --out-dir <path>              Snapshot output directory (default: snapshot)
+  --include-monolith            Also generate full-codebase.json and full-codebase.md
+  --max-monolith-bytes <n>      Skip monolith artefacts larger than n bytes
+  --max-part-bytes <n>          Maximum byte budget per markdown part (default: 307200).
+                                Accepts units: 120k, 1.5mb
+  --large-file-bytes <n>        Threshold for head/tail truncation (default: 204800)
+  --include-sensitive-files     Emit .env / *.pem / .npmrc / credential files
+  --skip-artifacts <names>      Comma-separated artifacts to omit
+                                (readme, manifest, parts, navigation,
+                                 projectTree, audit, monolith)
+  --only-artifacts <names>      Write *only* these artifacts
+  --format <text|json>          CLI output format (default: text)
+  --dry-run                     Compute the snapshot without writing anything
+  --watch                       Re-generate whenever the repository changes
+  -h, --help                    Display this help message
+  -v, --version                 Display version
+
+All options also accept the --option=value form.
+Human-readable progress is written to stderr; payloads (--format json) go to stdout.
+`.trim();
+function parsePositiveInteger(raw, optionName, minimum) {
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new UsageError(`--${optionName} expects a whole number, received "${raw}".`);
+  }
+  const value = Number(trimmed);
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new UsageError(`--${optionName} must be at least ${minimum}, received "${raw}".`);
+  }
+  return value;
+}
+function parseByteOption(raw, optionName, minimum) {
+  if (raw === void 0) return void 0;
+  const value = parseByteSize(raw);
+  if (value === void 0 || !Number.isSafeInteger(value)) {
+    throw new UsageError(
+      `--${optionName} expects a byte count such as 120000 or "120k", received "${raw}".`
+    );
+  }
+  if (value < minimum) {
+    throw new UsageError(`--${optionName} must be at least ${minimum}, received "${raw}".`);
+  }
+  return value;
+}
+function parseArtifactList(raw, flag) {
+  const names = raw.split(",").map((name) => name.trim()).filter(Boolean);
+  if (names.length === 0) {
+    throw new UsageError(
+      `${flag} expects at least one artifact name (${ARTIFACT_NAMES.join(", ")}).`
+    );
+  }
+  const unknown = names.filter((name) => !ARTIFACT_NAMES.includes(name));
+  if (unknown.length > 0) {
+    throw new UsageError(
+      `Unknown artifact(s): ${unknown.join(", ")}. Expected one of: ${ARTIFACT_NAMES.join(", ")}.`
+    );
+  }
+  return names;
+}
+function parseCliArgs(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: CLI_OPTIONS,
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (err) {
+    throw new UsageError(err.message);
+  }
+  const values = parsed.values;
+  if (values.help) {
+    process.stdout.write(`${USAGE}
+`);
+    throw new HelpRequested();
+  }
+  if (values.version) {
+    process.stdout.write(`v${VERSION}
+`);
+    throw new HelpRequested();
+  }
+  const positionals = parsed.positionals;
+  let command = "generate";
+  let args = [];
+  const explicitMode = values.mode ? String(values.mode) : void 0;
+  const firstPositional = positionals[0];
+  if (firstPositional !== void 0) {
+    const resolved = COMMAND_ALIASES.get(firstPositional);
+    if (!resolved) {
+      throw new UsageError(
+        `Unknown command "${firstPositional}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    command = resolved;
+    args = positionals.slice(1);
+  } else if (explicitMode !== void 0) {
+    const resolved = COMMAND_ALIASES.get(explicitMode);
+    if (!resolved) {
+      throw new UsageError(
+        `Unknown --mode "${explicitMode}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    command = resolved;
+  }
+  const expectedArgs = COMMAND_ARITY[command];
+  if (args.length !== expectedArgs) {
+    if (command === "explain") {
+      throw new UsageError("explain expects exactly one path.");
+    }
+    if (command === "diff") {
+      throw new UsageError(
+        "diff expects exactly two arguments: two snapshot directories or manifest.json files."
+      );
+    }
+    throw new UsageError(
+      `Unexpected argument(s): ${args.join(" ")}. ${command} takes no positional arguments.`
+    );
+  }
+  const rawFormat = values.format === void 0 ? "text" : String(values.format);
+  if (rawFormat !== "text" && rawFormat !== "json") {
+    throw new UsageError(`--format must be "text" or "json", received "${rawFormat}".`);
+  }
+  const rawSkip = values["skip-artifacts"];
+  const rawOnly = values["only-artifacts"];
+  if (rawSkip !== void 0 && rawOnly !== void 0) {
+    throw new UsageError("--skip-artifacts and --only-artifacts cannot be combined.");
+  }
+  let skipArtifacts;
+  if (rawOnly !== void 0) {
+    const keep = parseArtifactList(String(rawOnly), "--only-artifacts");
+    skipArtifacts = ARTIFACT_NAMES.filter(
+      (name) => !keep.includes(name)
+    );
+  } else if (rawSkip !== void 0) {
+    skipArtifacts = parseArtifactList(String(rawSkip), "--skip-artifacts");
+  }
+  return {
+    command,
+    args,
+    format: rawFormat,
+    dryRun: values["dry-run"] === true,
+    watch: values.watch === true,
+    cwd: values.cwd === void 0 ? process.cwd() : path.resolve(String(values.cwd)),
+    outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
+    includeMonolith: values["include-monolith"] === true ? true : void 0,
+    includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
+    maxPartBytes: parseByteOption(
+      values["max-part-bytes"],
+      "max-part-bytes",
+      MIN_MAX_PART_BYTES
+    ),
+    largeFileBytes: parseByteOption(
+      values["large-file-bytes"],
+      "large-file-bytes",
+      1
+    ),
+    maxMonolithBytes: parseByteOption(
+      values["max-monolith-bytes"],
+      "max-monolith-bytes",
+      1
+    ),
+    skipArtifacts
+  };
+}
+var HelpRequested = class extends Error {
+};
+function info(message) {
+  process.stderr.write(`${message}
+`);
+}
+function warn(message) {
+  process.stderr.write(`${message}
+`);
+}
+function emit(format, payload, textRenderer) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+    return;
+  }
+  textRenderer();
+}
+function runInit(cwd) {
+  const targetName = supportsTypeScriptImports() ? "snapshot.config.ts" : "snapshot.config.mjs";
+  const targetPath = path.join(cwd, targetName);
+  if (fs.existsSync(targetPath)) {
+    warn(`\u274C ${targetName} already exists in ${cwd}.`);
+    return 1;
+  }
+  const importPath = JSON.stringify(GENERATOR_NAME);
+  const starter = `import { defineConfig } from ${importPath};
+
+export default defineConfig({
+  branch: "main",
+  outDir: "snapshot",
+  maxPartBytes: 300 * 1024,
+  largeFileBytes: 200 * 1024,
+  excludePatterns: [],
+});
+`;
+  fs.writeFileSync(targetPath, starter, "utf8");
+  info(`\u2705 Created ${targetName} in ${cwd}`);
+  if (targetName.endsWith(".mjs")) {
+    info(
+      "   (a .ts config needs Node >= 22.6 to import natively; this Node writes a .mjs instead)"
+    );
+  }
+  return 0;
+}
+function renderValidateText(result) {
+  if (result.valid) {
+    info("\u2705 Snapshot is valid and up to date with disk.");
+  } else {
+    warn("\u274C Snapshot validation failed:");
+    for (const error of result.errors) warn(`  - ${error}`);
+    for (const drift of result.drift.hashMismatches.slice(0, 20)) {
+      warn(`  - modified: ${drift.path}`);
+    }
+    for (const issue of result.drift.partIssues.slice(0, 20)) {
+      warn(`  - part: ${issue.part} (${issue.issue})`);
+    }
+    for (const mismatch of result.drift.configMismatches.slice(0, 20)) {
+      warn(`  - config: ${mismatch}`);
+    }
+    for (const missing of result.drift.missingInSnapshot.slice(0, 20)) {
+      warn(`  - new file: ${missing}`);
+    }
+    for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
+      warn(`  - deleted: ${missing}`);
+    }
+  }
+  for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
+}
+async function main(argv = process.argv.slice(2)) {
+  let invocation;
+  try {
+    invocation = parseCliArgs(argv);
+  } catch (err) {
+    if (err instanceof HelpRequested) return 0;
+    if (err instanceof UsageError) {
+      process.stderr.write(`\u274C ${err.message}
+
+${USAGE}
+`);
+      return 2;
+    }
+    throw err;
+  }
+  if (invocation.command === "init") {
+    return runInit(invocation.cwd);
+  }
+  const loaded = await loadConfigFileDetailed(invocation.cwd);
+  for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
+  if (loaded.file) info(`\u2699  Using config ${path.relative(process.cwd(), loaded.file) || loaded.file}`);
+  const resolved = resolveConfig(
+    loaded.config,
+    {
+      mode: invocation.command,
+      format: invocation.format,
+      dryRun: invocation.dryRun,
+      cwd: invocation.cwd,
+      outDir: invocation.outDir,
+      includeMonolith: invocation.includeMonolith,
+      includeSensitiveFiles: invocation.includeSensitiveFiles,
+      maxPartBytes: invocation.maxPartBytes,
+      largeFileBytes: invocation.largeFileBytes,
+      maxMonolithBytes: invocation.maxMonolithBytes,
+      skipArtifacts: invocation.skipArtifacts
+    },
+    invocation.cwd
+  );
+  if (invocation.command === "validate") {
+    const result = validateSnapshot(resolved);
+    emit(invocation.format, result, () => renderValidateText(result));
+    return result.valid ? 0 : 1;
+  }
+  if (invocation.command === "report") {
+    const manifestPath = path.join(resolved.cwd, resolved.outDir, "manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+      warn(`\u274C Manifest not found at ${manifestPath}. Run generate first.`);
+      return 1;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch (err) {
+      warn(`\u274C Could not read ${manifestPath}: ${err.message}`);
+      return 1;
+    }
+    const validation = validateSnapshot(resolved);
+    emit(invocation.format, { manifest, validation }, () => {
+      info(`
+\u{1F4CA} Codebase Snapshot Report (${resolved.cwd})`);
+      info(`   - Generated at:   ${manifest.generatedAt}`);
+      info(`   - Schema:         ${manifest.schemaVersion}`);
+      info(`   - Fingerprint:    ${manifest.fingerprint}`);
+      info(`   - Files included: ${manifest.counts.totalFiles}`);
+      info(`   - Total lines:    ${manifest.counts.totalLines.toLocaleString()}`);
+      info(
+        `   - Total size:     ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
+      );
+      info(`   - Total parts:    ${manifest.counts.partsCount}`);
+      info(`   - Integrity:      ${validation.valid ? "\u2705 Clean (no drift)" : "\u274C Drift detected"}`);
+      info(`   - Warnings:       ${manifest.warnings?.length ?? 0}`);
+      info("\n   Layers:");
+      for (const [layer, count] of Object.entries(manifest.layers)) {
+        info(`     - ${layer.padEnd(16)}: ${count} files`);
+      }
+    });
+    return validation.valid ? 0 : 1;
+  }
+  if (invocation.command === "explain") {
+    const result = explainPath(resolved, invocation.args[0]);
+    emit(invocation.format, result, () => info(renderExplainText(result)));
+    return result.included ? 0 : 1;
+  }
+  if (invocation.command === "diff") {
+    try {
+      const [beforePath, afterPath] = invocation.args;
+      const diff = compareManifests(loadManifest(beforePath), loadManifest(afterPath));
+      emit(invocation.format, diff, () => info(renderDiffText(diff)));
+      return 0;
+    } catch (err) {
+      warn(`\u274C ${err.message}`);
+      return 1;
+    }
+  }
+  const started = performance.now();
+  info(`\u{1F4F8} ${invocation.dryRun ? "Planning snapshot (dry run)" : "Generating snapshot"} for: ${resolved.cwd}`);
+  info(
+    `   Branch: ${resolved.branch} | Part budget: ${(resolved.maxPartBytes / 1024).toFixed(0)} KB`
+  );
+  try {
+    const manifest = generateSnapshot(resolved, { dryRun: invocation.dryRun });
+    const elapsed = ((performance.now() - started) / 1e3).toFixed(2);
+    if (invocation.dryRun) {
+      info("\n\u{1F9EA} Dry run \u2014 nothing was written:");
+      info(`   - Would track:  ${manifest.counts.totalFiles} files`);
+      info(`   - Would write:  ${manifest.counts.partsCount} part(s) under ${resolved.outDir}/parts/`);
+      info(`   - Skipped:      ${manifest.counts.skippedCount} file(s)`);
+      info(`   - Warnings:     ${manifest.warnings.length}`);
+      info(`   - Integrity:    ${manifest.validation.status}`);
+      for (const error of manifest.validation.errors.slice(0, 10)) info(`     - ${error}`);
+    } else {
+      info(`
+\u2705 Snapshot generated in ${elapsed}s:`);
+      info(`   - Tracked files: ${manifest.counts.totalFiles}`);
+      info(`   - Total lines:   ${manifest.counts.totalLines.toLocaleString()}`);
+      info(
+        `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
+      );
+      info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+      info(`   - Reports:       ${resolved.outDir}/reports/ (project-tree, navigation, audit)`);
+      info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      info(`   - Fingerprint:   ${manifest.fingerprint}`);
+      info(`   - Integrity:     ${manifest.validation.status}`);
+      if (manifest.warnings.length > 0) {
+        info(`   - Warnings:      ${manifest.warnings.length}`);
+        for (const warning of manifest.warnings.slice(0, 10)) info(`     - ${warning}`);
+      }
+    }
+    if (invocation.format === "json") {
+      process.stdout.write(`${JSON.stringify(manifest, null, 2)}
+`);
+    }
+    if (invocation.watch) {
+      return await runWatchLoop(invocation, resolved);
+    }
+    return manifest.validation.status === "passed" ? 0 : 1;
+  } catch (err) {
+    warn(`\u274C Failed to generate snapshot: ${err.message}`);
+    return 1;
+  }
+}
+async function runWatchLoop(invocation, resolved) {
+  const outDir = path.resolve(resolved.cwd, resolved.outDir);
+  const tmpDir = path.resolve(resolved.cwd, resolved.tmpDir);
+  const outName = path.basename(outDir).toLowerCase();
+  const tmpName = path.basename(tmpDir).toLowerCase();
+  const isGenerated = (candidate) => candidate.toLowerCase().split(/[\\/]/).some(
+    (segment) => segment === outName || segment === tmpName || segment.startsWith(`${outName}.backup-`)
+  );
+  let running = false;
+  const regenerate = () => {
+    if (running) return;
+    running = true;
+    const started = performance.now();
+    try {
+      const manifest = generateSnapshot(resolved, { dryRun: invocation.dryRun });
+      const elapsed = ((performance.now() - started) / 1e3).toFixed(2);
+      info(
+        `\u267B\uFE0F  ${(/* @__PURE__ */ new Date()).toISOString()}  ${manifest.counts.totalFiles} file(s), ${manifest.counts.partsCount} part(s), ${manifest.validation.status} (${elapsed}s)`
+      );
+    } catch (err) {
+      warn(`\u274C ${err.message}`);
+    } finally {
+      running = false;
+    }
+  };
+  info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
+  regenerate();
+  let timer = null;
+  const watcher = fs.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
+    if (filename) {
+      const changed = path.resolve(resolved.cwd, filename.toString());
+      if (isGenerated(changed)) return;
+    }
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(regenerate, 250);
+  });
+  await new Promise((resolve2) => {
+    const stop = () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+      resolve2();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  return 0;
+}
+
+export { UsageError, main, parseByteOption, parseCliArgs, parsePositiveInteger };
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map