@ankurhalder/codebase-snapshot 0.0.0-stage → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,364 @@
+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, e as SkipRecord } from './types-S-5eRuRc.cjs';
+export { A as ArtifactSelection, 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 ValidationDrift } from './types-S-5eRuRc.cjs';
+
+/**
+ * Strips `//` and block comments the way JSONC does, without touching anything
+ * inside a string literal. `JSON.parse` alone made every `.jsonc` file report
+ * `invalid-json`, losing its key shape entirely.
+ */
+declare function stripJsonComments(content: string): string;
+declare function summarizeJson(content: string): JsonSummary;
+declare function summarizeMarkdown(content: string): MarkdownSummary;
+
+/**
+ * Extracts a structural summary from a JS/TS source file.
+ *
+ * The traversal is an explicit stack, not recursion: a generated file with a
+ * long `a && b && …` chain used to overflow the call stack inside our own
+ * visitor and abort the entire snapshot. Callers should still treat a throw as
+ * possible (TypeScript's own parser recurses), so wrap the call.
+ */
+declare function summarizeTypeScriptSource(relativePath: string, content: string): SourceSummary;
+
+/**
+ * Brands a resolved config so consumers can distinguish it from a user
+ * `SnapshotConfig` structurally, instead of guessing from the presence of a
+ * single field (`"secretRules" in input`), which misfired for hand-built configs
+ * and for user configs that happened to carry an extra key.
+ */
+declare function markResolvedConfig<T extends ResolvedSnapshotConfig>(config: T): T;
+/**
+ * Detects a resolved config.
+ *
+ * The brand is a non-enumerable symbol, so it survives `structuredClone` but NOT
+ * `{ ...resolvedConfig, override }`. Relying on the brand alone caused a real
+ * regression: a spread config was re-resolved as a user config, which silently
+ * dropped custom `secretRules` and let matching secrets through in clear text.
+ * The structural fallback therefore accepts any object carrying the complete
+ * resolved-only shape.
+ */
+declare function isResolvedConfig(value: unknown): value is ResolvedSnapshotConfig;
+/**
+ * Re-validates a resolved config taken from an untrusted path (e.g. a spread
+ * copy), recompiling secret rules so string patterns and stray `g`/`y` flags are
+ * normalised even when the object did not come from `resolveConfig`.
+ */
+declare function normalizeResolvedConfig(config: ResolvedSnapshotConfig): ResolvedSnapshotConfig;
+/**
+ * Guards against a silently lossy config round-trip.
+ *
+ * A `RegExp` cannot survive `JSON.stringify`/`JSON.parse`: the pattern comes
+ * back as `{}`. Such an object no longer satisfies `isResolvedConfig`, so it
+ * would be re-resolved as a user config and its custom `secretRules` would be
+ * dropped without a word — a silent security regression. Fail loudly instead.
+ */
+declare function assertUsableConfigInput(value: unknown): void;
+interface ConfigLoadResult {
+    config: SnapshotConfig | null;
+    /** Absolute path of the file the config came from, if any. */
+    file: string | null;
+    /** Why a candidate config file was ignored. Never silently discarded. */
+    warnings: string[];
+}
+/** True when this Node can `import()` a `.ts` file natively (type stripping). */
+declare function supportsTypeScriptImports(): boolean;
+/**
+ * Loads the first usable config file from `cwd`.
+ *
+ * Every failure is reported through `warnings` instead of being swallowed by an
+ * empty `catch`: a syntax error in a user's config used to be indistinguishable
+ * from having no config at all.
+ */
+declare function loadConfigFileDetailed(cwd: string): Promise<ConfigLoadResult>;
+declare function loadConfigFile(cwd: string): Promise<SnapshotConfig | null>;
+/** Smallest usable part budget: a part header plus one section must fit. */
+declare const MIN_MAX_PART_BYTES = 4096;
+/** Every artifact this package can write, in the order it is written. */
+declare const ARTIFACT_NAMES: readonly ["readme", "manifest", "parts", "navigation", "projectTree", "audit", "monolith"];
+/**
+ * Parses a byte budget.
+ *
+ * Accepts a plain number (`122880`), a numeric string (`"122880"`), or a
+ * human-readable size (`"120k"`, `"1.5mb"`, `"2 GB"`). Returns `undefined` for
+ * anything it cannot read, so callers can decide whether that is an error or a
+ * fallback — a typo'd budget must not silently become the default.
+ */
+declare function parseByteSize(value: ByteSize | null | undefined): number | undefined;
+/**
+ * Merges user config, preset defaults and CLI overrides.
+ *
+ * `baseDir` is the directory the config was loaded from. Without it the natural
+ * library flow (`loadConfigFile(dir)` then `resolveConfig(config)`) silently
+ * fell back to `process.cwd()` and generated into the caller's directory.
+ */
+declare function resolveConfig(userConfig: SnapshotConfig | null, cliOptions?: Partial<CliOptions>, baseDir?: string): ResolvedSnapshotConfig;
+/**
+ * Matches a path against a layer/kind rule.
+ *
+ * `"src/app/**"` now means "exactly `src/app` or below": the previous
+ * implementation stripped `**` **and** the trailing slash, so the pattern also
+ * matched `src/apple/` and `src/application/`.
+ */
+declare function matchRule(filePath: string, matcher: string | RegExp | ((filePath: string) => boolean)): boolean;
+
+declare function defineConfig(config: SnapshotConfig): SnapshotConfig;
+
+declare function generateProjectTree(filePaths: string[]): string;
+
+interface PartitionedPart {
+    filename: string;
+    markdown: string;
+    metadata: PartMetadata;
+}
+/**
+ * Partitions rendered file sections into byte-bounded parts.
+ *
+ * The budget is a hard bound: a section that cannot fit into a part on its own
+ * is byte-truncated (and marked `isPreviewTruncated`) rather than emitted whole.
+ * The previous implementation skipped the flush check for an empty chunk, so one
+ * large file produced a part 13.5x over the configured budget.
+ */
+declare function partitionFiles(files: FileEntry[], maxPartBytes: number, contentFingerprint?: string): PartitionedPart[];
+/**
+ * Re-numbers a set of parts as one sequence and rewrites their headers.
+ *
+ * Needed when parts are produced by more than one partition pass (per-layer
+ * budgets): each pass numbers from `part-001`, so the merged set would otherwise
+ * contain duplicate filenames and every `Previous:`/`Next:` link would lie.
+ */
+declare function renumberParts(parts: PartitionedPart[], contentFingerprint?: string): PartitionedPart[];
+/**
+ * Chooses a fence longer than any backtick run in `content`, so a file that
+ * contains a fenced block cannot break out of its own code block.
+ */
+declare function fenceForContent(content: string): string;
+/**
+ * Stable, injective anchor for a file path.
+ *
+ * The previous slug was not injective (`src/a-b.ts` and `src/a/b.ts` produced the
+ * same anchor) and, more importantly, no part file ever emitted the anchors that
+ * `reports/navigation.md` linked to — every file link was dead.
+ */
+declare function anchorForPath(filePath: string): string;
+
+interface PreviewResult {
+    content: string;
+    isTruncated: boolean;
+    originalLines: number;
+    includedLines: number;
+}
+/**
+ * Line count with one consistent convention: a trailing newline does not start
+ * a new line, and an empty string has zero lines.
+ *
+ * Previously `index.ts` recorded 0 for an empty file while `preview.ts` recorded
+ * 1, and every newline-terminated file was over-counted by one.
+ */
+declare function countLines(content: string): number;
+/**
+ * Truncates to a UTF-8 byte budget without splitting a multi-byte character.
+ */
+declare function truncateToBytes(content: string, maxBytes: number): {
+    content: string;
+    isTruncated: boolean;
+};
+declare function truncatePreview(content: string, headLines: number, tailLines: number): PreviewResult;
+
+declare function detectPreset(cwd: string): {
+    presetName: string;
+    layers: LayerRule[];
+    kinds: KindRule[];
+};
+
+declare function isBinaryExtension(filePath: string): boolean;
+declare function isBinaryBuffer(buffer: Buffer): boolean;
+declare function isBinaryFile(absolutePath: string): boolean;
+
+declare function detectLanguage(filePath: string): string;
+
+/**
+ * Redacts secrets from `content`.
+ *
+ * - Replaces only the matched span, so unrelated code sharing the line survives
+ *   (the previous implementation discarded the whole line).
+ * - 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,
+ *   because that excerpt was being written verbatim into `reports/audit.md`.
+ */
+declare function scanAndRedactSecrets(content: string, rules: SecretRule[], filePath?: string): {
+    redacted: string;
+    findings: SecretFinding[];
+};
+
+/**
+ * Validates a generated snapshot against the working tree and against the
+ * recorded configuration.
+ *
+ * Beyond source-file hashes this now also:
+ * - refuses a manifest that does not have the expected shape (previously threw
+ *   an uncaught `TypeError`),
+ * - verifies every emitted `parts/*.md` against its recorded `byteSize`/`sha256`
+ *   (previously a deleted or corrupted part still reported `valid: true`),
+ * - re-checks the effective configuration and the part/file bookkeeping,
+ * - verifies monolith artefact digests when present.
+ */
+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 {
+    /** Path relative to the configured cwd, POSIX separators. */
+    path: string;
+    /** Whether the path exists on disk. */
+    exists: boolean;
+    /** Whether the scanner would include it in the next snapshot. */
+    included: boolean;
+    /** Why it is excluded, when it is. Mirrors `SkipRecord.reason`. */
+    reason?: string;
+    detail?: string;
+    layer?: string;
+    layerMatch?: string;
+    kind?: string;
+    kindMatch?: string;
+    language?: string;
+    /** Part filename from the last written manifest, when one is available. */
+    part?: string | null;
+    inclusionMode?: string;
+    lines?: number;
+    bytes?: number;
+    secretCount?: number;
+    secrets?: Array<{
+        rule: string;
+        line: number;
+    }>;
+}
+/**
+ * Explains what the scanner would do with one path.
+ *
+ * The whole point is that every decision is visible: which layer and kind rule
+ * matched, why a file was skipped, which part it landed in, and whether any
+ * secret rule fires. Re-running the real scanner is what keeps it honest.
+ */
+declare function explainPath(config: ResolvedSnapshotConfig, target: string): ExplainResult;
+/** Renders an explanation for a terminal. */
+declare function renderExplainText(result: ExplainResult): string;
+
+interface ManifestDiff {
+    before: DiffSide;
+    after: DiffSide;
+    added: string[];
+    removed: string[];
+    changed: string[];
+    unchanged: number;
+}
+interface DiffSide {
+    generatedAt: string;
+    fingerprint: string;
+    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".
+ */
+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;
+/** Renders a diff for a terminal. */
+declare function renderDiffText(diff: ManifestDiff): string;
+
+interface CollectOptions {
+    /**
+     * When non-empty, only files matching at least one pattern are candidates.
+     * Applied before `excludePatterns`, which then narrows the result further.
+     */
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    /**
+     * Emit credential-bearing files (`.env`, `*.pem`, `.npmrc`, `id_rsa`, …).
+     * Default `false`: they are skipped with `reason: "sensitive-file"`.
+     */
+    includeSensitiveFiles?: boolean;
+}
+interface CollectResult {
+    files: string[];
+    skipped: SkipRecord[];
+}
+declare function isSensitivePath(relativePath: string): boolean;
+/**
+ * Translates a glob (`**`, `*`, `?`, `{a,b}`, `[abc]`) into a RegExp. A pattern
+ * without a leading `/` matches at any depth, mirroring `.gitignore` semantics.
+ *
+ * Brace groups and character classes are supported because they are what people
+ * actually write: `*.{ts,tsx}` previously matched nothing at all, since `{` and
+ * `}` were escaped as literals.
+ */
+declare function globToRegExp(glob: string): RegExp;
+/**
+ * Path exclusion with proper segment semantics.
+ *
+ * A plain (non-glob) pattern matches a whole path segment sequence, so
+ * `"test"` matches `test/a.ts` and `src/test/b.ts` but **not** `contest/entry.ts`
+ * (the previous implementation was a raw `String.includes`).
+ */
+declare function matchesExclude(relativePath: string, pattern: string): boolean;
+/**
+ * Collects candidate file paths.
+ *
+ * Uses `git ls-files -z` when git is available: `-z` is required because the
+ * default output C-quotes paths containing non-ASCII characters, which silently
+ * mangled `src/café.ts` into a path that never existed and dropped the file.
+ */
+declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
+
+declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
+declare const GENERATOR_VERSION = "2.0.0";
+declare const SCHEMA_VERSION = "3.0.0";
+interface GenerateOptions {
+    /** Compute the full manifest but write nothing to disk. */
+    dryRun?: boolean;
+}
+/**
+ * Resolves and validates the output directories.
+ *
+ * `outDir` was previously deleted with `rmSync` before the replacement was
+ * renamed into place, so `outDir: "."` erased the whole repository and a
+ * nested `tmpDir` erased its own parent. These guards make that impossible.
+ */
+declare function resolveSafeOutputDirs(config: {
+    cwd: string;
+    outDir: string;
+    tmpDir: string;
+}): {
+    outDir: string;
+    tmpDir: string;
+};
+/**
+ * Generates the snapshot.
+ *
+ * Synchronous by design: it previously carried an `async` signature while doing
+ * only blocking I/O, which promised concurrency that did not exist. Existing
+ * `await generateSnapshot(...)` call sites continue to work.
+ */
+declare function generateSnapshot(configInput?: SnapshotConfig | ResolvedSnapshotConfig | null, options?: GenerateOptions): Manifest;
+/** 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, ByteSize, CliOptions, DEFAULT_SECRET_PATTERNS, type ExplainResult, FileEntry, GENERATOR_NAME, GENERATOR_VERSION, type GenerateOptions, JsonSummary, KindRule, LayerRule, MIN_MAX_PART_BYTES, Manifest, type ManifestDiff, MarkdownSummary, PartMetadata, ResolvedSnapshotConfig, SCHEMA_VERSION, SecretFinding, SecretRule, SkipRecord, SnapshotConfig, SourceSummary, ValidationResult, anchorForPath, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isResolvedConfig, isSensitivePath, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, renderDiffText, renderExplainText, renumberParts, resolveConfig, resolveSafeOutputDirs, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot };