@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/readme-sync.js

@@ -0,0 +1,592 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.readme-sync",
+ *   "title": "README Marker Sync",
+ *   "category": "feature"
+ * }
+ *
+ * Parses README files for @codex:auto markers and replaces their content
+ * with generated documentation from extraction pipeline data.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { globby } from 'globby';
+import { resolveTestingRequirements, computeTestingStatus, } from './testing-pyramid.js';
+// ── Marker Parsing ──────────────────────────────────────────────
+/**
+ * Parses HTML-style attributes from a marker opening tag string.
+ * Only quoted attribute values are supported (double or single quotes).
+ * Unquoted values like `install=pkg` are ignored by design.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"parseMarkerAttributes","stability":"stable","signature":"(attrString: string) => Record<string, string>"}
+ */
+export function parseMarkerAttributes(attrString) {
+    const attrs = {};
+    const regex = /(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    let match;
+    while ((match = regex.exec(attrString)) !== null) {
+        attrs[match[1]] = match[2] ?? match[3];
+    }
+    return attrs;
+}
+const MARKER_TYPES = [
+    'install',
+    'examples',
+    'api',
+    'bundle',
+    'testing',
+];
+/**
+ * Determines marker type from its attributes.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"resolveMarkerType","stability":"stable","signature":"(attributes: Record<string, string>) => ReadmeMarkerType | null"}
+ */
+export function resolveMarkerType(attributes) {
+    for (const type of MARKER_TYPES) {
+        if (type in attributes)
+            return type;
+    }
+    return null;
+}
+const MARKER_OPEN_REGEX = /<!--\s*@codex:auto\s+(.*?)\s*-->/g;
+const MARKER_CLOSE = '<!-- @codex:end -->';
+/**
+ * Parses all @codex:auto markers from README content.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"parseReadmeMarkers","stability":"stable","signature":"(content: string) => ReadmeMarker[]"}
+ */
+export function parseReadmeMarkers(content) {
+    const markers = [];
+    MARKER_OPEN_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_OPEN_REGEX.exec(content)) !== null) {
+        const openTag = match[0];
+        const attrString = match[1];
+        const startIndex = match.index;
+        const afterOpen = startIndex + openTag.length;
+        // Find closing tag
+        const closeIndex = content.indexOf(MARKER_CLOSE, afterOpen);
+        if (closeIndex === -1) {
+            // Malformed marker — skip
+            continue;
+        }
+        const endIndex = closeIndex + MARKER_CLOSE.length;
+        const innerContent = content.slice(afterOpen, closeIndex);
+        // If the inner content contains another @codex:auto tag, the close tag we found
+        // likely belongs to the nested marker — skip this outer match as malformed.
+        if (/<!--\s*@codex:auto\s/.test(innerContent)) {
+            continue;
+        }
+        const attributes = parseMarkerAttributes(attrString);
+        const type = resolveMarkerType(attributes);
+        if (type === null)
+            continue;
+        const originalContent = content.slice(startIndex, endIndex);
+        markers.push({
+            type,
+            attributes,
+            openTag,
+            startIndex,
+            endIndex,
+            originalContent,
+            innerContent,
+        });
+    }
+    return markers;
+}
+// ── ID Pattern Matching ─────────────────────────────────────────
+/**
+ * Matches codex entry IDs against a glob-style pattern.
+ * Supports: exact match, trailing `*` (one segment), trailing `**` (any depth).
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"matchIdPattern","stability":"stable","signature":"(pattern: string, entryId: string) => boolean"}
+ */
+export function matchIdPattern(pattern, entryId) {
+    if (pattern === entryId)
+        return true;
+    // pithy.signals.** → match anything under pithy.signals
+    if (pattern.endsWith('.**')) {
+        const prefix = pattern.slice(0, -3); // remove .**
+        return (entryId.startsWith(prefix + '.') && entryId.length > prefix.length + 1);
+    }
+    // pithy.signals.* → match exactly one segment after pithy.signals.
+    if (pattern.endsWith('.*')) {
+        const prefix = pattern.slice(0, -2); // remove .*
+        if (!entryId.startsWith(prefix + '.'))
+            return false;
+        const remainder = entryId.slice(prefix.length + 1);
+        return remainder.length > 0 && !remainder.includes('.');
+    }
+    return false;
+}
+/**
+ * Filters components by an ID pattern.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"filterByPattern","stability":"stable","signature":"(components: EnrichedComponent[], pattern: string) => EnrichedComponent[]"}
+ */
+export function filterByPattern(components, pattern) {
+    return components.filter(c => {
+        if (matchIdPattern(pattern, c.id))
+            return true;
+        if (c.apis.some(api => matchIdPattern(pattern, api.id)))
+            return true;
+        // Match parent component when pattern uses wildcards
+        // e.g., component "pithy.signals" matches pattern "pithy.signals.*"
+        if (pattern.endsWith('.*') || pattern.endsWith('.**')) {
+            const prefix = pattern.replace(/\.\*+$/, '');
+            if (c.id === prefix)
+                return true;
+        }
+        return false;
+    });
+}
+// ── Test Boilerplate Stripping ──────────────────────────────────
+/**
+ * Strips test framework boilerplate from example code extracted from tests.
+ * Removes it()/test() wrapper, dedents, converts expect() to value comments.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"stripTestBoilerplate","stability":"stable","signature":"(code: string) => string"}
+ */
+export function stripTestBoilerplate(code) {
+    let lines = code.split('\n');
+    // Strip it('...', () => { ... }); or test('...', () => { ... }); wrapper
+    if (lines.length > 1 && /^\s*(it|test)\s*\(/.test(lines[0])) {
+        lines = lines.slice(1);
+        // Remove trailing });
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (/^\s*\}\s*\);?\s*$/.test(lines[i])) {
+                lines = lines.slice(0, i);
+                break;
+            }
+        }
+    }
+    // Dedent by common leading whitespace
+    const nonEmpty = lines.filter(l => l.trim().length > 0);
+    if (nonEmpty.length > 0) {
+        const minIndent = Math.min(...nonEmpty.map(l => (l.match(/^(\s*)/) || [''])[1].length));
+        if (minIndent > 0) {
+            lines = lines.map(l => (l.length >= minIndent ? l.slice(minIndent) : l));
+        }
+    }
+    // Convert expect(expr).toBe(val) / .toEqual(val) → expr; // → val
+    lines = lines.map(line => {
+        const trimmed = line.trimStart();
+        const indent = line.slice(0, line.length - trimmed.length);
+        if (!trimmed.startsWith('expect('))
+            return line;
+        // Find the closing paren of expect() by counting parens (handles nested calls)
+        let depth = 0;
+        let expectCloseIndex = -1;
+        for (let j = 7; j < trimmed.length; j++) {
+            if (trimmed[j] === '(')
+                depth++;
+            else if (trimmed[j] === ')') {
+                if (depth === 0) {
+                    expectCloseIndex = j;
+                    break;
+                }
+                depth--;
+            }
+        }
+        if (expectCloseIndex === -1)
+            return line;
+        const expr = trimmed.slice(7, expectCloseIndex); // between expect( and )
+        const rest = trimmed.slice(expectCloseIndex + 1); // after the closing )
+        // Matchers with a value argument
+        const valueMatch = rest.match(/\.(toBe|toEqual|toStrictEqual|toContain|toMatch|toHaveLength)\((.+)\);?\s*$/);
+        if (valueMatch) {
+            const value = valueMatch[2];
+            return `${indent}${expr}; // → ${value}`;
+        }
+        // No-argument matchers
+        const noArgMatch = rest.match(/\.(toBeTruthy|toBeFalsy|toBeNull|toBeUndefined|toBeDefined)\(\);?\s*$/);
+        if (noArgMatch) {
+            const labels = {
+                toBeTruthy: 'truthy',
+                toBeFalsy: 'falsy',
+                toBeNull: 'null',
+                toBeUndefined: 'undefined',
+                toBeDefined: 'defined',
+            };
+            return `${indent}${expr}; // → ${labels[noArgMatch[1]]}`;
+        }
+        return line;
+    });
+    return lines.join('\n').trim();
+}
+// ── Content Generators ──────────────────────────────────────────
+/**
+ * Generates install command content for a package.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateInstallContent","stability":"stable","signature":"(packageName: string) => string"}
+ */
+export function generateInstallContent(packageName) {
+    if (!NPM_NAME_RE.test(packageName)) {
+        return `_Invalid package name: \`${sanitizeForInlineCode(packageName)}\`_`;
+    }
+    return [
+        '```bash',
+        `npm install ${packageName}`,
+        '```',
+        '',
+        '```bash',
+        `pnpm add ${packageName}`,
+        '```',
+        '',
+        '```bash',
+        `yarn add ${packageName}`,
+        '```',
+    ].join('\n');
+}
+/**
+ * Generates examples content from extraction data.
+ * Prefers API-level JSDoc examples; falls back to @codex:example test examples
+ * when no API examples are found (test examples are safe from feedback loops).
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateExamplesContent","stability":"stable","signature":"(components: EnrichedComponent[], limit?: number, testExamples?: TestExample[], pattern?: string) => string"}
+ */
+export function generateExamplesContent(components, limit, testExamples, pattern) {
+    // Only collect examples from API-level JSDoc (not component-level, which may
+    // include README-sourced examples that would create a feedback loop)
+    const allExamples = [];
+    for (const comp of components) {
+        for (const api of comp.apis) {
+            for (const ex of api.examples) {
+                allExamples.push(ex);
+            }
+        }
+    }
+    // Fall back to test examples when no API JSDoc examples exist
+    if (allExamples.length === 0 && testExamples && pattern) {
+        const matchingTests = testExamples.filter(te => te.entryId === pattern || matchIdPattern(pattern, te.entryId));
+        for (const te of matchingTests) {
+            allExamples.push({
+                description: te.name,
+                code: stripTestBoilerplate(te.code),
+                language: 'typescript',
+            });
+        }
+    }
+    // Deduplicate by normalized code + language (collapse whitespace differences
+    // but keep distinct examples that share code with different languages)
+    const seen = new Set();
+    const uniqueExamples = allExamples.filter(ex => {
+        const key = `${ex.language}:${ex.code.replace(/\s+/g, ' ').trim()}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    if (uniqueExamples.length === 0) {
+        return '_No examples found._';
+    }
+    const selected = limit !== undefined
+        ? uniqueExamples.slice(0, Math.max(0, limit))
+        : uniqueExamples;
+    const lines = [];
+    for (const ex of selected) {
+        if (ex.description) {
+            lines.push(`**${escapeMd(ex.description)}**`);
+            lines.push('');
+        }
+        // Use enough backticks to avoid collision if content contains triple backticks
+        const fenceLen = Math.max(3, longestBacktickRun(ex.code) + 1);
+        const fence = '`'.repeat(fenceLen);
+        lines.push(`${fence}${sanitizeLanguage(ex.language)}`);
+        lines.push(ex.code);
+        lines.push(fence);
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+/**
+ * Escapes pipe characters and collapses newlines for use in markdown table cells.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"escapeTableCell","stability":"stable","signature":"(str: string) => string"}
+ */
+export function escapeTableCell(str) {
+    return str.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
+}
+/**
+ * Escapes markdown special characters in inline text (bold markers, brackets, pipes, backticks).
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"escapeMd","stability":"stable","signature":"(str: string) => string"}
+ */
+export function escapeMd(str) {
+    return str.replace(/([*[\]|\\`_~<>])/g, '\\$1');
+}
+/**
+ * Strips backticks from a string so it can safely be wrapped in inline code.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"sanitizeForInlineCode","stability":"stable","signature":"(str: string) => string"}
+ */
+export function sanitizeForInlineCode(str) {
+    return str.replace(/`/g, "'");
+}
+/** Returns the length of the longest consecutive run of backticks in a string.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"longestBacktickRun","stability":"stable","signature":"(str: string) => number"} */
+export function longestBacktickRun(str) {
+    let max = 0;
+    let current = 0;
+    for (const ch of str) {
+        if (ch === '`') {
+            current++;
+            if (current > max)
+                max = current;
+        }
+        else {
+            current = 0;
+        }
+    }
+    return max;
+}
+/** Sanitizes a language identifier for use in fenced code blocks.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"sanitizeLanguage","stability":"stable","signature":"(lang: string) => string"} */
+export function sanitizeLanguage(lang) {
+    return lang.replace(/[^a-zA-Z0-9_+-]/g, '');
+}
+/** Matches valid npm package names (scoped and unscoped, lowercase-only per npm rules). */
+const NPM_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/**
+ * Generates API reference table from extraction data.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateApiContent","stability":"stable","signature":"(components: EnrichedComponent[], format?: string) => string"}
+ */
+export function generateApiContent(components, format) {
+    const allApis = components.flatMap(c => c.apis);
+    if (allApis.length === 0) {
+        return '_No API entries found._';
+    }
+    if (format === 'list') {
+        return allApis
+            .map(api => {
+            const name = escapeMd(api.name);
+            const sig = api.signature
+                ? ` - \`${sanitizeForInlineCode(api.signature)}\``
+                : '';
+            const desc = api.jsdoc?.description
+                ? ` — ${escapeMd(api.jsdoc.description)}`
+                : '';
+            return `- **${name}**${sig}${desc} [${api.stability}]`;
+        })
+            .join('\n');
+    }
+    // Default: table format
+    // Include a Component column when APIs come from multiple components
+    // to disambiguate entries with the same name (e.g. validatePath)
+    const parentIds = new Set(components.map(c => c.id));
+    const multiComponent = parentIds.size > 1;
+    const lines = multiComponent
+        ? [
+            '| API | Component | Signature | Stability | Description |',
+            '| --- | --- | --- | --- | --- |',
+        ]
+        : [
+            '| API | Signature | Stability | Description |',
+            '| --- | --- | --- | --- |',
+        ];
+    for (const comp of components) {
+        for (const api of comp.apis) {
+            const name = escapeTableCell(api.name);
+            const sig = api.signature ? sanitizeForInlineCode(api.signature) : '-';
+            const stability = escapeTableCell(api.stability);
+            const desc = api.jsdoc?.description
+                ? escapeTableCell(api.jsdoc.description)
+                : '-';
+            // Signature is wrapped in backticks — pipes inside inline code don't need escaping in GFM
+            if (multiComponent) {
+                const shortParent = escapeTableCell(comp.id.split('.').slice(-1)[0]);
+                lines.push(`| ${name} | ${shortParent} | \`${sig}\` | ${stability} | ${desc} |`);
+            }
+            else {
+                lines.push(`| ${name} | \`${sig}\` | ${stability} | ${desc} |`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Generates testing pyramid table from extraction data.
+ * Includes a Status column showing coverage completeness based on
+ * test references and category-aware testing pyramid requirements.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateTestingContent","stability":"stable","signature":"(components: EnrichedComponent[]) => string"}
+ */
+export function generateTestingContent(components) {
+    const allApis = components.flatMap(c => c.apis);
+    if (allApis.length === 0) {
+        return '_No test data available._';
+    }
+    // Build lookups from API parent id → component metadata
+    const componentByParent = new Map();
+    for (const comp of components) {
+        componentByParent.set(comp.id, comp);
+    }
+    const lines = [
+        '| Feature | Unit | Integration | E2E | Status |',
+        '| --- | --- | --- | --- | --- |',
+    ];
+    for (const api of allApis) {
+        const hasUnit = api.testRefs.some(r => r.type === 'unit');
+        const hasIntegration = api.testRefs.some(r => r.type === 'integration');
+        const hasE2e = api.testRefs.some(r => r.type === 'e2e');
+        const name = escapeTableCell(api.name);
+        // Resolve requirements using the shared testing pyramid API
+        // with risk and per-entry testing overrides from annotations
+        const comp = componentByParent.get(api.parent);
+        const category = comp?.category ?? 'feature';
+        const reqs = resolveTestingRequirements(category, comp?.risk, comp?.testing);
+        if (reqs.unit)
+            reqs.unit = { ...reqs.unit, covered: hasUnit };
+        if (reqs.integration)
+            reqs.integration = { ...reqs.integration, covered: hasIntegration };
+        if (reqs.e2e)
+            reqs.e2e = { ...reqs.e2e, covered: hasE2e };
+        const status = computeTestingStatus(reqs);
+        lines.push(`| ${name} | ${hasUnit ? '✓' : '-'} | ${hasIntegration ? '✓' : '-'} | ${hasE2e ? '✓' : '-'} | ${status} |`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Placeholder for bundle content generation (not yet implemented).
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateBundleContent","stability":"stable","signature":"(_packageName: string) => string"}
+ */
+export function generateBundleContent(_packageName) {
+    return '<!-- Bundle size tracking not yet available -->';
+}
+// ── Sync Engine ─────────────────────────────────────────────────
+/**
+ * Generates replacement content for a single marker.
+ */
+function generateMarkerContent(marker, components, testExamples) {
+    const pattern = marker.attributes[marker.type] || '';
+    const warnings = [];
+    // Warn when pattern value is empty (likely a typo in the marker)
+    if (!pattern && marker.type !== 'install') {
+        warnings.push(`Empty pattern value for "${marker.type}" marker; no components will match.`);
+    }
+    switch (marker.type) {
+        case 'install':
+            return { content: generateInstallContent(pattern), warning: warnings[0] };
+        case 'examples': {
+            let limit;
+            if (marker.attributes.limit) {
+                const parsed = parseInt(marker.attributes.limit, 10);
+                if (Number.isNaN(parsed)) {
+                    warnings.push(`Invalid "limit" value "${marker.attributes.limit}" for examples marker; ignoring limit.`);
+                }
+                else if (parsed < 0) {
+                    warnings.push(`Negative "limit" value "${marker.attributes.limit}" for examples marker; clamping to 0.`);
+                    limit = 0;
+                }
+                else {
+                    limit = parsed;
+                }
+            }
+            const matched = filterByPattern(components, pattern);
+            return {
+                content: generateExamplesContent(matched, limit, testExamples, pattern),
+                warning: warnings.join(' ') || undefined,
+            };
+        }
+        case 'api': {
+            const format = marker.attributes.format;
+            if (format && format !== 'table' && format !== 'list') {
+                warnings.push(`Unknown format "${format}" for api marker; falling back to table format.`);
+            }
+            const matched = filterByPattern(components, pattern);
+            return {
+                content: generateApiContent(matched, format),
+                warning: warnings.join(' ') || undefined,
+            };
+        }
+        case 'testing': {
+            const matched = filterByPattern(components, pattern);
+            return {
+                content: generateTestingContent(matched),
+                warning: warnings.join(' ') || undefined,
+            };
+        }
+        case 'bundle': {
+            warnings.push(`bundle marker not yet fully supported for "${pattern}", generated placeholder content instead`);
+            return {
+                content: generateBundleContent(pattern),
+                warning: warnings.join(' ') || undefined,
+            };
+        }
+        default:
+            return { content: '', warning: `Unknown marker type: ${marker.type}` };
+    }
+}
+/**
+ * Syncs a single README's content: parses markers, generates content, replaces.
+ *
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"syncReadmeContent","stability":"stable","signature":"(content: string, filePath: string, components: EnrichedComponent[], testExamples?: TestExample[]) => ReadmeSyncResult"}
+ */
+export function syncReadmeContent(content, filePath, components, testExamples) {
+    const allMarkers = parseReadmeMarkers(content);
+    const warnings = [];
+    let markersUpdated = 0;
+    let result = content;
+    // Detect overlapping/nested markers and skip inner ones to avoid corruption
+    const markers = [];
+    for (const marker of allMarkers) {
+        const prev = markers[markers.length - 1];
+        if (prev && marker.startIndex < prev.endIndex) {
+            warnings.push(`Nested @codex:auto marker detected at offset ${marker.startIndex}; skipping to avoid output corruption.`);
+            continue;
+        }
+        markers.push(marker);
+    }
+    // Process markers back-to-front to preserve indices
+    for (let i = markers.length - 1; i >= 0; i--) {
+        const marker = markers[i];
+        const generated = generateMarkerContent(marker, components, testExamples);
+        if (generated.warning) {
+            warnings.push(generated.warning);
+        }
+        // Preserve original open tag to avoid reordering attributes
+        const replacement = `${marker.openTag}\n${generated.content}\n${MARKER_CLOSE}`;
+        if (replacement !== marker.originalContent) {
+            result =
+                result.slice(0, marker.startIndex) +
+                    replacement +
+                    result.slice(marker.endIndex);
+            markersUpdated++;
+        }
+    }
+    const changed = result !== content;
+    return {
+        filePath,
+        changed,
+        markersProcessed: markers.length,
+        markersUpdated,
+        warnings,
+        updatedContent: changed ? result : undefined,
+    };
+}
+/**
+ * Syncs all README files matching configured patterns.
+ *
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"syncAllReadmes","stability":"stable","signature":"(extractionResult: ExtendedExtractionResult, config?: ReadmeSyncConfig) => Promise<ReadmeSyncResult[]>"}
+ */
+export async function syncAllReadmes(extractionResult, config = {}) {
+    const root = config.root || process.cwd();
+    const readmePatterns = config.readmePatterns || [
+        'packages/*/README.md',
+        'README.md',
+    ];
+    const dryRun = config.dryRun ?? false;
+    const verbose = config.verbose ?? false;
+    const readmePaths = await globby(readmePatterns, {
+        cwd: root,
+        absolute: true,
+        gitignore: true,
+    });
+    const results = [];
+    for (const readmePath of readmePaths) {
+        const content = await readFile(readmePath, 'utf-8');
+        const result = syncReadmeContent(content, readmePath, extractionResult.components, extractionResult.testExamples);
+        if (verbose) {
+            const status = result.changed
+                ? `updated (${result.markersUpdated}/${result.markersProcessed} markers)`
+                : `unchanged (${result.markersProcessed} markers)`;
+            console.log(`  ${readmePath}: ${status}`);
+            for (const w of result.warnings) {
+                console.log(`    ⚠ ${w}`);
+            }
+        }
+        if (result.changed && !dryRun && result.updatedContent) {
+            await writeFile(readmePath, result.updatedContent, 'utf-8');
+        }
+        results.push(result);
+    }
+    return results;
+}

package/dist/extraction/snapshot-store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.snapshot-store",
+ *   "title": "API Snapshot Store",
+ *   "category": "feature"
+ * }
+ *
+ * Persists and retrieves API snapshots per version in `codex.versions/`.
+ * Enables historical API tracking and versioned breaking-change detection.
+ */
+import type { ApiSnapshot } from './types.js';
+/**
+ * Get the file path for a snapshot of a given version.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-store","name":"getSnapshotPath","stability":"stable","signature":"(dir: string, version: string) => string"}
+ */
+export declare function getSnapshotPath(dir: string, version: string): string;
+/**
+ * Save an API snapshot to disk as a JSON file named `{version}.json`.
+ * Creates the target directory if it doesn't exist.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-store","name":"saveSnapshot","stability":"stable","signature":"(snapshot: ApiSnapshot, dir: string) => Promise<void>"}
+ */
+export declare function saveSnapshot(snapshot: ApiSnapshot, dir: string): Promise<void>;
+/**
+ * Load an API snapshot from disk by version.
+ * Returns `null` if the snapshot file does not exist.
+ * Throws if the file exists but cannot be parsed.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-store","name":"loadSnapshot","stability":"stable","signature":"(version: string, dir: string) => Promise<ApiSnapshot | null>"}
+ */
+export declare function loadSnapshot(version: string, dir: string): Promise<ApiSnapshot | null>;
+/**
+ * List all stored snapshot versions, sorted by semver (with lexicographic fallback).
+ * Returns an empty array if the directory does not exist.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-store","name":"listSnapshots","stability":"stable","signature":"(dir: string) => Promise<string[]>"}
+ */
+export declare function listSnapshots(dir: string): Promise<string[]>;