@ankurhalder/codebase-snapshot 0.0.0-stage → 2.0.0

package/dist/types-S-5eRuRc.d.ts

@@ -0,0 +1,372 @@
+type Mode = "generate" | "validate" | "report";
+type OutputFormat = "text" | "json";
+/**
+ * How much of a file made it into the snapshot.
+ * `full`    – the complete file body was emitted.
+ * `preview` – the body was truncated (by lines and/or bytes) before emission.
+ */
+type InclusionMode = "full" | "preview";
+interface SourceSummary {
+    directives: string[];
+    imports: string[];
+    exports: string[];
+    /** Module specifiers re-exported wholesale via `export * from "..."`. */
+    reExports: string[];
+    functions: string[];
+    classes: string[];
+    interfaces: string[];
+    types: string[];
+    enums: string[];
+    variables: string[];
+    reactComponents: string[];
+    hooks: string[];
+    routeHandlers: string[];
+    /** Number of parser diagnostics, present only when the file has syntax errors. */
+    parseErrors?: number;
+}
+interface JsonSummary {
+    shape: string;
+    itemCount: number | null;
+    keys: string[];
+    sampleKeys: string[];
+}
+interface MarkdownSummary {
+    headings: string[];
+    frontmatterKeys: string[];
+}
+type SkipReason = "asset" | "binary" | "read-error" | "not-file" | "sensitive-file" | "symlink" | "default-ignore" | "excluded";
+interface SkipRecord {
+    path: string;
+    reason: SkipReason;
+    detail?: string;
+}
+/**
+ * One scanned file. Field names are canonical and unique by design:
+ * earlier releases carried `path`/`relativePath`, `sizeBytes`/`bytes` and
+ * `hashSha256`/`sha256` aliases that could only ever agree.
+ */
+interface FileEntry {
+    relativePath: string;
+    sizeBytes: number;
+    lines: number;
+    hashSha256: string;
+    part: string;
+    layer: string;
+    kind: string;
+    language: string;
+    inclusionMode: InclusionMode;
+    isLarge: boolean;
+    isPreviewTruncated: boolean;
+    /** Line count of the file on disk. */
+    originalLines: number;
+    /** Lines actually emitted into the snapshot. */
+    includedLines: number;
+    /** UTF-8 bytes of file content actually emitted into the snapshot. */
+    includedBytes: number;
+    summary?: SourceSummary | JsonSummary | MarkdownSummary;
+    /** True when the summary alone was too large for the part budget and was dropped. */
+    summaryOmitted?: boolean;
+    /** Emitted body after redaction/truncation. Never serialized into the manifest. */
+    content?: string;
+}
+interface PartFileEntry {
+    relativePath: string;
+    sourceBytes: number;
+    includedBytes: number;
+    lines: number;
+    layer: string;
+    kind: string;
+}
+interface PartMetadata {
+    index: number;
+    filename: string;
+    /** Exact UTF-8 byte length of the emitted part file. */
+    byteSize: number;
+    sha256: string;
+    lines: number;
+    fileCount: number;
+    layersCovered: string[];
+    includedFiles: PartFileEntry[];
+}
+interface SecretRule {
+    rule: string;
+    pattern: RegExp;
+}
+/** Shape accepted from JSON config files, where `pattern` can only be a string. */
+interface SecretRuleInput {
+    rule: string;
+    pattern: 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
+ * written into `reports/audit.md`.
+ */
+interface SecretFinding {
+    rule: string;
+    line: number;
+    path?: string;
+}
+interface ManifestTotals {
+    candidateFiles: number;
+    includedFiles: number;
+    fullFiles: number;
+    previewFiles: number;
+    skippedFiles: number;
+    totalSourceBytes: number;
+    totalContentBytes: number;
+    partCount: number;
+    warningCount: number;
+}
+interface ManifestArtifact {
+    byteSize: number;
+    sha256: string;
+}
+interface ManifestIndexes {
+    routes: Array<{
+        path: string;
+        methods: string[];
+        part: string;
+    }>;
+    components: Array<{
+        path: string;
+        symbols: string[];
+        part: string;
+        layer: string;
+    }>;
+    handlers: Array<{
+        path: string;
+        exports: string[];
+        part: string;
+    }>;
+    features: Array<{
+        name: string;
+        files: number;
+    }>;
+    imports: {
+        byFile: Array<{
+            path: string;
+            imports: string[];
+            exports: string[];
+        }>;
+        centralFiles: Array<{
+            path: string;
+            importedByCount: number;
+        }>;
+    };
+    directives: Array<{
+        path: string;
+        directives: string[];
+    }>;
+}
+/** Effective configuration recorded so `validate` can detect config drift. */
+interface ManifestConfigSnapshot {
+    maxPartBytes: number;
+    largeFileBytes: number;
+    previewHeadLines: number;
+    previewTailLines: number;
+    includeMonolith: boolean;
+    includeSensitiveFiles: boolean;
+    artifacts: ResolvedArtifacts;
+    include: string[];
+    layersMode: "merge" | "replace";
+    budgets: ResolvedBudgets;
+    excludePatterns: string[];
+    layers: string[];
+    kinds: string[];
+}
+interface Manifest {
+    schemaVersion: string;
+    generatedAt: string;
+    generator: {
+        name: string;
+        version: string;
+    };
+    git: {
+        branch: string;
+        commit: string;
+        isDirty: boolean;
+    };
+    budgets: {
+        maxPartBytes: number;
+        largeFileBytes: number;
+    };
+    config: ManifestConfigSnapshot;
+    counts: {
+        totalFiles: number;
+        totalSizeBytes: number;
+        totalLines: number;
+        partsCount: number;
+        skippedCount: number;
+        largeFileCount: number;
+        truncatedPreviewCount: number;
+    };
+    totals: ManifestTotals;
+    fingerprint: string;
+    validation: {
+        status: "passed" | "failed";
+        errors: string[];
+    };
+    artifacts: {
+        fullJson: ManifestArtifact | null;
+        fullMarkdown: ManifestArtifact | null;
+    };
+    layers: Record<string, number>;
+    kinds: Record<string, number>;
+    indexes: ManifestIndexes;
+    parts: PartMetadata[];
+    files: FileEntry[];
+    skipped: SkipRecord[];
+    warnings: string[];
+}
+interface LayerRule {
+    name: string;
+    match: string | RegExp | ((filePath: string) => boolean);
+}
+/**
+ * Which snapshot artifacts get written.
+ *
+ * Everything a developer opens is produced by default; each entry exists only so
+ * a single artifact can be switched off without disabling the rest. `monolith`
+ * is the one exception, because it duplicates the entire payload: it follows
+ * `includeMonolith` (off by default) unless set here explicitly.
+ */
+interface ArtifactSelection {
+    /** `README.md` — the orientation page for humans and models. */
+    readme?: boolean;
+    /** `manifest.json` — the registry `validate` and `report` read. */
+    manifest?: boolean;
+    /** `parts/part-XXX.md` — the partitioned code payload. */
+    parts?: boolean;
+    /** `reports/navigation.md` — file-to-part lookup index. */
+    navigation?: boolean;
+    /** `reports/project-tree.md` — ASCII repository tree. */
+    projectTree?: boolean;
+    /** `reports/audit.md` — security, layer, kind and skip findings. */
+    audit?: boolean;
+    /** `full-codebase.{json,md}` — one file per format, the whole payload again. */
+    monolith?: boolean;
+}
+/** Every artifact decision made concrete. */
+type ResolvedArtifacts = Required<ArtifactSelection>;
+interface KindRule {
+    kind: string;
+    match: string | RegExp | ((filePath: string) => boolean);
+}
+/** A byte budget: either raw bytes or a human-readable size such as `"120k"`. */
+type ByteSize = number | string;
+/** Per-layer part budgets. Unlisted layers fall back to `default`. */
+interface BudgetConfig {
+    default?: ByteSize;
+    byLayer?: Record<string, ByteSize>;
+}
+/** Every budget resolved to concrete byte counts. */
+interface ResolvedBudgets {
+    default: number;
+    byLayer: Record<string, number>;
+}
+/** Lifecycle hooks. Not serialized into the manifest (functions are not data). */
+interface HooksConfig {
+    /** Runs once after a successful generate, with the manifest that was written. */
+    afterGenerate?: (manifest: Manifest) => void;
+}
+interface SnapshotConfig {
+    cwd?: string;
+    branch?: string;
+    outDir?: string;
+    tmpDir?: string;
+    /** Raw bytes, or a human-readable size (`"120k"`, `"1.5mb"`). */
+    maxPartBytes?: ByteSize;
+    largeFileBytes?: ByteSize;
+    previewHeadLines?: number;
+    previewTailLines?: number;
+    includeMonolith?: boolean;
+    maxMonolithBytes?: ByteSize | null;
+    /** Opt in to emitting `.env`/`*.pem`/`.npmrc`/credential files. Default false. */
+    includeSensitiveFiles?: boolean;
+    /** Allow-list of globs. When non-empty, only matching files are included. */
+    include?: string[];
+    /** Switch individual snapshot artifacts off. Everything is on by default. */
+    artifacts?: ArtifactSelection;
+    /**
+     * How user `layers`/`kinds` interact with the detected preset (default
+     * `"merge"`): user rules are evaluated first, then the preset fills the gaps.
+     * `"replace"` discards the preset entirely.
+     */
+    layersMode?: "merge" | "replace";
+    /** Per-layer part budgets. */
+    budgets?: BudgetConfig;
+    hooks?: HooksConfig;
+    layers?: LayerRule[];
+    kinds?: KindRule[];
+    excludePatterns?: string[];
+    secrets?: {
+        customPatterns?: SecretRuleInput[];
+        disableDefaultPatterns?: boolean;
+    };
+}
+interface ResolvedSnapshotConfig {
+    cwd: string;
+    branch: string;
+    outDir: string;
+    tmpDir: string;
+    maxPartBytes: number;
+    largeFileBytes: number;
+    previewHeadLines: number;
+    previewTailLines: number;
+    includeMonolith: boolean;
+    maxMonolithBytes: number | null;
+    includeSensitiveFiles: boolean;
+    /** Empty means "no allow-list"; every discovered file is a candidate. */
+    include: string[];
+    artifacts: ResolvedArtifacts;
+    layersMode: "merge" | "replace";
+    budgets: ResolvedBudgets;
+    hooks: HooksConfig;
+    layers: LayerRule[];
+    kinds: KindRule[];
+    excludePatterns: string[];
+    secretRules: SecretRule[];
+}
+interface CliOptions {
+    mode: Mode;
+    format: OutputFormat;
+    dryRun: boolean;
+    cwd?: string;
+    outDir?: string;
+    includeMonolith?: boolean;
+    includeSensitiveFiles?: boolean;
+    maxMonolithBytes?: number | null;
+    maxPartBytes?: number;
+    largeFileBytes?: number;
+    /** Artifact names to suppress for this invocation (`--skip-artifacts`). */
+    skipArtifacts?: string[];
+}
+interface ValidationDrift {
+    missingInSnapshot: string[];
+    missingOnDisk: string[];
+    hashMismatches: Array<{
+        path: string;
+        diskHash: string;
+        snapshotHash: string;
+    }>;
+    /** Emitted `parts/*.md` that are missing or no longer match their recorded hash. */
+    partIssues: Array<{
+        part: string;
+        issue: string;
+    }>;
+    /** `counts`/`totals`/`budgets` that disagree with the rest of the manifest. */
+    totalsMismatches: string[];
+    /** Effective-configuration differences between the manifest and the current run. */
+    configMismatches: string[];
+}
+interface ValidationResult {
+    valid: boolean;
+    manifestPresent: boolean;
+    drift: ValidationDrift;
+    errors: string[];
+    /** Non-fatal observations (e.g. branch moved on). */
+    warnings: string[];
+}
+
+export type { ArtifactSelection as A, ByteSize as B, CliOptions as C, FileEntry as F, HooksConfig as H, InclusionMode as I, JsonSummary as J, KindRule as K, LayerRule as L, MarkdownSummary as M, OutputFormat as O, PartMetadata as P, ResolvedSnapshotConfig as R, SourceSummary as S, ValidationResult as V, SnapshotConfig as a, SecretRule as b, SecretFinding as c, Manifest as d, SkipRecord as e, BudgetConfig as f, ManifestArtifact as g, ManifestConfigSnapshot as h, ManifestIndexes as i, ManifestTotals as j, Mode as k, PartFileEntry as l, ResolvedArtifacts as m, ResolvedBudgets as n, SecretRuleInput as o, SkipReason as p, ValidationDrift as q };

package/docs/configuration.md

@@ -0,0 +1,244 @@
+# Configuration reference
+
+Everything `@ankurhalder/codebase-snapshot` can be told to do, in one place.
+
+```bash
+npx @ankurhalder/codebase-snapshot init     # writes a starter config
+```
+
+Config files are resolved in this order, first match wins:
+
+`snapshot.config.ts` → `.js` → `.mjs` → `.cjs` → `.json` → `.snapshotrc.json` → `.snapshotrc` → `"snapshot"` in `package.json`.
+
+> A `.ts` config is only importable natively from Node **22.6+**. `init` writes `.mjs` on older Node, and an unloadable config is reported on stderr rather than ignored.
+
+---
+
+## Scoping: which files get in
+
+```javascript
+export default {
+  include: ["src/**", "packages/*/src/**"],   // allow-list, empty = everything
+  excludePatterns: ["**/*.test.ts", "docs"],  // narrows what include let through
+};
+```
+
+`include` runs first, `excludePatterns` narrows the survivors. Both accept globs
+(`**`, `*`, `?`, `{a,b}`, `[abc]`) or plain strings; a plain string matches a
+whole path segment sequence, so `"docs"` matches `docs/a.md` and `src/docs/b.md`
+but not `docsite/c.md`.
+
+Every dropped file is recorded in `manifest.skipped` with `reason` and the exact
+pattern responsible (`excluded`, `default-ignore`, `sensitive-file`, `binary`,
+`symlink`, `read-error`, `not-file`).
+
+```javascript
+export default {
+  includeSensitiveFiles: false,   // .env, *.pem, .npmrc, .ssh/, .tfstate …
+};
+```
+
+## Classification: layers and kinds
+
+```javascript
+export default {
+  layersMode: "merge",   // default: your rules first, then the preset's
+  layers: [
+    { name: "billing", match: "src/features/billing/**" },
+    { name: "legacy", match: (p) => p.includes(".legacy.") },
+  ],
+  kinds: [
+    { kind: "route", match: /(^|\/)route\.tsx?$/ },
+    { kind: "hook", match: "src/hooks/**" },
+  ],
+};
+```
+
+Rules are evaluated in order, **first match wins**, with an `other` fallback.
+`match` may be a string, a `RegExp`, or a predicate function.
+
+`layersMode: "merge"` (the default) keeps the detected preset's rules and lets
+yours win by being evaluated first. `"replace"` discards the preset entirely.
+
+Presets are auto-detected: **nextjs** → **vite** → **node** → **default**.
+
+## Sizing: byte budgets
+
+```javascript
+export default {
+  maxPartBytes: "120k",      // hard ceiling per part; default 300 KB, min 4096 B
+  largeFileBytes: "200k",    // above this a file gets a head/tail preview
+  previewHeadLines: 80,
+  previewTailLines: 40,
+
+  budgets: {                 // optional per-layer overrides
+    default: "120k",
+    byLayer: { docs: 40_000, core: 300_000 },
+  },
+};
+```
+
+Budgets accept raw bytes (`122880`) or human sizes (`"120k"`, `"1.5mb"`, `"2 GB"`).
+Anything unparseable is an error rather than a silent fallback to the default.
+
+Files under different budgets are partitioned separately and the resulting parts
+are re-numbered, so filenames and `Previous:`/`Next:` links stay correct.
+
+## Artifacts: what gets written
+
+Everything is on by default. Each artifact can be switched off independently —
+`artifacts` in config, or `--skip-artifacts` / `--only-artifacts` on the CLI.
+
+| Artifact | Default | File |
+| :--- | :--- | :--- |
+| `readme` | on | `README.md` |
+| `manifest` | on | `manifest.json` — **off breaks `validate` and `report`** |
+| `parts` | on | `parts/part-XXX.md` |
+| `navigation` | on | `reports/navigation.md` — dangles if `parts` is off |
+| `projectTree` | on | `reports/project-tree.md` |
+| `audit` | on | `reports/audit.md` |
+| `monolith` | off | `full-codebase.{json,md}` |
+
+```javascript
+export default {
+  artifacts: { parts: false, navigation: false },   // reports-only pass
+  includeMonolith: false,
+  maxMonolithBytes: null,
+};
+```
+
+Unknown artifact names are rejected, not ignored. The selection is recorded in
+`manifest.config.artifacts`, so changing it later shows up as config drift.
+
+The monolith is built from the **pre-partition** contents, so it holds the whole
+file even when a part had to truncate it.
+
+## Secrets: redaction rules
+
+21 built-in rules cover PEM keys, JWT, AWS, GitHub, Slack, Stripe, Google,
+OpenAI/Anthropic, npm, PyPI, SendGrid, Twilio, DigitalOcean, Azure, database
+URIs, basic-auth URLs and `.env`-style assignments.
+
+```javascript
+export default {
+  secrets: {
+    customPatterns: [
+      { rule: "internal-token", pattern: /CORP-[A-Z0-9]{32}/ },
+      { rule: "from-json", pattern: "ACME_[a-z0-9]{10}" },   // strings allowed
+    ],
+    disableDefaultPatterns: false,
+  },
+};
+```
+
+Only the matched span is replaced; the rest of the line survives. Multi-line PEM
+blocks are masked as a block, including ones cut off before their `END` marker.
+No excerpt of a matched line is ever written to any artifact.
+
+## Output layout
+
+```javascript
+export default {
+  outDir: "snapshot",
+  tmpDir: "snapshot.tmp",
+  branch: "main",   // fallback when git cannot report one
+};
+```
+
+`outDir` may not be the working directory, an ancestor, or the filesystem root,
+and `outDir`/`tmpDir` may not contain each other. Writes are atomic: the previous
+snapshot survives until the new one is fully in place.
+
+## Hooks
+
+```javascript
+export default {
+  hooks: {
+    afterGenerate: (manifest) => {
+      // runs after a successful generate (and after a dry run)
+    },
+  },
+};
+```
+
+A throwing hook becomes a warning on the manifest — it never loses a snapshot
+that was already written.
+
+---
+
+# Commands
+
+| Command | Purpose |
+| :--- | :--- |
+| `generate` *(default)* | Write the snapshot |
+| `validate`, `check` | Re-hash sources and parts, compare config, detect drift |
+| `report` | Print metrics, layer distribution and drift status |
+| `explain <path>` | Show how one path would be treated |
+| `diff <a> <b>` | Compare two snapshots |
+| `init` | Write a starter config |
+
+## `explain`
+
+```
+$ snap explain src/app/page.tsx
+
+src/app/page.tsx
+
+  included   yes
+  layer      app   (rule (p) => p.startsWith("src/app/") || ...)
+  kind       component   (rule (p) => { const base = p.split("/").pop() ...)
+  language   tsx
+  size       48 B, 1 line(s)
+  part       part-001.md
+  inclusion  full
+  secrets    none
+```
+
+Excluded paths say why:
+
+```
+$ snap explain .env
+
+.env
+
+  included   no
+  reason     sensitive-file
+  detail     credential-bearing file; enable includeSensitiveFiles to emit it
+```
+
+Exits `0` when the path is included, `1` when it is not. `--format json` emits the
+same data as an object.
+
+## `diff`
+
+```
+$ snap diff old-snapshot new-snapshot
+
+before  2026-11-03T10:00:00.000Z  812 file(s), 4 part(s)
+after   2026-11-03T11:30:00.000Z  820 file(s), 4 part(s)
+
+  + 9 added
+  - 1 removed
+  ~ 3 changed
+  = 808 unchanged
+```
+
+Both arguments may be snapshot directories or paths to a `manifest.json`.
+
+## `--watch`
+
+```bash
+npx @ankurhalder/codebase-snapshot generate --watch
+```
+
+Re-generates on every change, ignoring writes into the output and temporary
+directories (including the atomic-swap backup) so it cannot trigger itself.
+
+---
+
+# Drift
+
+`validate` compares five things: source hashes on disk, the emitted parts (size
+and SHA-256), the manifest's own bookkeeping, the recorded configuration
+(budgets, includes, excludes, artifacts, layers mode), and git state. Changing a
+config value without re-generating is reported as drift, not silently accepted.

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
+  "keywords": [
+    "codebase",
+    "snapshot",
+    "llm",
+    "ai",
+    "context",
+    "ast",
+    "audit",
+    "codebase-snapshot",
+    "code-analysis"
+  ],
+  "author": "Ankur Halder <ankur.halder12345@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ankurhalder/codebase-snapshot.git"
+  },
+  "homepage": "https://github.com/ankurhalder/codebase-snapshot#readme",
+  "bugs": {
+    "url": "https://github.com/ankurhalder/codebase-snapshot/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "bin": {
+    "codebase-snapshot": "./dist/bin.js",
+    "snap": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./cli": {
+      "import": {
+        "types": "./dist/cli.d.ts",
+        "default": "./dist/cli.js"
+      },
+      "require": {
+        "types": "./dist/cli.d.cts",
+        "default": "./dist/cli.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.cjs",
+    "dist/*.d.ts",
+    "dist/*.d.cts",
+    "docs/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "node scripts/lint.mjs",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "pretest": "npm run build",
+    "test": "node --test tests/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage tests/*.test.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "typescript": "^5.0.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}