@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/snapshot-store.js

@@ -0,0 +1,153 @@
+/**
+ * @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 { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
+import { join, extname, basename } from 'node:path';
+/**
+ * Validate that a version string is safe for use in filenames.
+ * Rejects strings containing path separators or traversal patterns.
+ */
+function validateVersionString(version) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(version)) {
+        throw new Error(`Invalid version string "${version}": must contain only alphanumeric characters, dots, hyphens, and underscores`);
+    }
+}
+/**
+ * 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 function getSnapshotPath(dir, version) {
+    validateVersionString(version);
+    return join(dir, `${version}.json`);
+}
+/**
+ * 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 async function saveSnapshot(snapshot, dir) {
+    await mkdir(dir, { recursive: true });
+    const filePath = getSnapshotPath(dir, snapshot.version);
+    const content = JSON.stringify(snapshot, null, 2) + '\n';
+    await writeFile(filePath, content, 'utf8');
+}
+/**
+ * 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 async function loadSnapshot(version, dir) {
+    const filePath = getSnapshotPath(dir, version);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse snapshot for version "${version}" at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * 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 async function listSnapshots(dir) {
+    try {
+        const files = await readdir(dir);
+        return files
+            .filter(f => extname(f) === '.json')
+            .map(f => basename(f, '.json'))
+            .sort(compareSemver);
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+}
+/**
+ * Compare two version strings by semver numeric parts, falling back to
+ * lexicographic comparison for non-numeric segments (e.g. prerelease tags).
+ */
+function compareSemver(a, b) {
+    // Split into numeric core (e.g. ["1","0","0"]) and prerelease parts
+    const [coreA, preA] = splitSemver(a);
+    const [coreB, preB] = splitSemver(b);
+    // Compare numeric core segments first
+    const coreLen = Math.max(coreA.length, coreB.length);
+    for (let i = 0; i < coreLen; i++) {
+        const na = Number(coreA[i] ?? '0');
+        const nb = Number(coreB[i] ?? '0');
+        if (na !== nb)
+            return na - nb;
+    }
+    // Cores are equal — apply prerelease precedence:
+    // A version WITHOUT prerelease has higher precedence than one WITH prerelease
+    if (preA.length === 0 && preB.length > 0)
+        return 1;
+    if (preA.length > 0 && preB.length === 0)
+        return -1;
+    // Both have prerelease — compare segments
+    const preLen = Math.max(preA.length, preB.length);
+    for (let i = 0; i < preLen; i++) {
+        const sa = preA[i] ?? '';
+        const sb = preB[i] ?? '';
+        if (sa === '' && sb !== '')
+            return -1;
+        if (sa !== '' && sb === '')
+            return 1;
+        const na = Number(sa);
+        const nb = Number(sb);
+        if (!Number.isNaN(na) && !Number.isNaN(nb)) {
+            if (na !== nb)
+                return na - nb;
+        }
+        else {
+            const cmp = sa.localeCompare(sb);
+            if (cmp !== 0)
+                return cmp;
+        }
+    }
+    return 0;
+}
+/**
+ * Splits a version string into core numeric parts and prerelease parts.
+ * "1.2.3-beta.1" → [["1","2","3"], ["beta","1"]]
+ * "1.2.3" → [["1","2","3"], []]
+ */
+function splitSemver(version) {
+    const dashIndex = version.indexOf('-');
+    if (dashIndex === -1) {
+        return [version.split('.'), []];
+    }
+    const core = version.slice(0, dashIndex).split('.');
+    const pre = version.slice(dashIndex + 1).split('.');
+    return [core, pre];
+}

package/dist/extraction/source-linker.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.source-linker",
+ *   "title": "Source Linker",
+ *   "category": "compiler"
+ * }
+ */
+import type { SourceLocation, ReadmeSection } from './types.js';
+/**
+ * Result of finding a declaration in source code
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"DeclarationLocation","stability":"stable","signature":"interface DeclarationLocation { name: string; type: string; location: SourceLocation; signature?: string; exported: boolean }"}
+ */
+export interface DeclarationLocation {
+    name: string;
+    type: 'function' | 'class' | 'interface' | 'type' | 'const';
+    location: SourceLocation;
+    signature?: string;
+    exported: boolean;
+}
+/**
+ * Finds the source location of a declaration by name
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @param declarationName - Name of the declaration to find
+ * @returns Source location or undefined if not found
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"findDeclarationLocation","stability":"stable","signature":"(content: string, filePath: string, declarationName: string) => DeclarationLocation | undefined"}
+ */
+export declare function findDeclarationLocation(content: string, filePath: string, declarationName: string): DeclarationLocation | undefined;
+/**
+ * Extracts all declarations from a source file
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @returns Array of declaration locations
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"extractAllDeclarations","stability":"stable","signature":"(content: string, filePath: string) => DeclarationLocation[]"}
+ */
+export declare function extractAllDeclarations(content: string, filePath: string): DeclarationLocation[];
+/**
+ * Parses README content into sections
+ * @param content - README file content
+ * @param filePath - Path to the README file
+ * @returns Array of parsed sections
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"parseReadmeSections","stability":"stable","signature":"(content: string, filePath: string) => ReadmeSection[]"}
+ */
+export declare function parseReadmeSections(content: string, filePath: string): ReadmeSection[];
+/**
+ * Links README sections to codex entry IDs based on heading matching
+ * @param sections - Parsed README sections
+ * @param entryIds - List of codex entry IDs
+ * @returns Sections with linked entry IDs
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"linkReadmeToEntries","stability":"stable","signature":"(sections: ReadmeSection[], entryIds: string[]) => ReadmeSection[]"}
+ */
+export declare function linkReadmeToEntries(sections: ReadmeSection[], entryIds: string[]): ReadmeSection[];
+/**
+ * Generates source links for display (GitHub-style URLs)
+ * @param location - Source location
+ * @param repoUrl - Base repository URL
+ * @param branch - Branch name (default: main)
+ * @returns URL string for the source location
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"generateSourceLink","stability":"stable","signature":"(location: SourceLocation, repoUrl: string, branch?: string) => string"}
+ */
+export declare function generateSourceLink(location: SourceLocation, repoUrl: string, branch?: string): string;
+/**
+ * Creates a relative path from project root
+ * @param absolutePath - Absolute file path
+ * @param projectRoot - Project root path
+ * @returns Relative path
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"toRelativePath","stability":"stable","signature":"(absolutePath: string, projectRoot: string) => string"}
+ */
+export declare function toRelativePath(absolutePath: string, projectRoot: string): string;
+/**
+ * Enriches source locations with additional context
+ * @param location - Basic source location
+ * @param content - File content
+ * @returns Enriched location with context
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"enrichSourceLocation","stability":"stable","signature":"(location: SourceLocation, content: string) => SourceLocation & { context?: string }"}
+ */
+export declare function enrichSourceLocation(location: SourceLocation, content: string): SourceLocation & {
+    context?: string;
+};

package/dist/extraction/source-linker.js

@@ -0,0 +1,316 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.source-linker",
+ *   "title": "Source Linker",
+ *   "category": "compiler"
+ * }
+ */
+/**
+ * Patterns for declaration extraction
+ *
+ * Note: These patterns are designed to reduce ReDoS risk by:
+ * - Bounding matches and avoiding unbounded wildcards where practical
+ * - Avoiding nested quantifiers with overlapping character classes
+ * - Using (?:=>|[^=])+ to match type annotations including arrow types while stopping at assignment =
+ */
+const FUNCTION_DECLARATION_PATTERN = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*(?:<[^>]*>)?\s*\([^)]*\)/g;
+// Pattern that matches const/let/var arrow functions with complex type annotations
+// Uses (?:=>|[^=])+ to allow arrow types like (a: T) => U and object types like {a: string}
+// while stopping at the assignment = (since standalone = is not matched, only =>)
+const CONST_FUNCTION_PATTERN = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*(?::\s*(?:=>|[^=])+)?\s*=\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/g;
+const CLASS_DECLARATION_PATTERN = /(?:export\s+)?(?:abstract\s+)?class\s+(\w+)(?:\s+extends\s+\w+)?(?:\s+implements\s+[\w,\s]+)?/g;
+const INTERFACE_PATTERN = /(?:export\s+)?interface\s+(\w+)(?:\s+extends\s+[\w,\s]+)?/g;
+const TYPE_ALIAS_PATTERN = /(?:export\s+)?type\s+(\w+)\s*(?:<[^>]*>)?\s*=/g;
+/**
+ * Finds the source location of a declaration by name
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @param declarationName - Name of the declaration to find
+ * @returns Source location or undefined if not found
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"findDeclarationLocation","stability":"stable","signature":"(content: string, filePath: string, declarationName: string) => DeclarationLocation | undefined"}
+ */
+export function findDeclarationLocation(content, filePath, declarationName) {
+    const declarations = extractAllDeclarations(content, filePath);
+    return declarations.find(d => d.name === declarationName);
+}
+/**
+ * Extracts all declarations from a source file
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @returns Array of declaration locations
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"extractAllDeclarations","stability":"stable","signature":"(content: string, filePath: string) => DeclarationLocation[]"}
+ */
+export function extractAllDeclarations(content, filePath) {
+    const declarations = [];
+    // Extract functions
+    FUNCTION_DECLARATION_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = FUNCTION_DECLARATION_PATTERN.exec(content)) !== null) {
+        const lineNumber = getLineNumber(content, match.index);
+        const isExported = content
+            .slice(Math.max(0, match.index - 10), match.index)
+            .includes('export');
+        declarations.push({
+            name: match[1],
+            type: 'function',
+            location: { file: filePath, line: lineNumber },
+            signature: match[0],
+            exported: isExported,
+        });
+    }
+    // Extract const/arrow functions
+    CONST_FUNCTION_PATTERN.lastIndex = 0;
+    while ((match = CONST_FUNCTION_PATTERN.exec(content)) !== null) {
+        const lineNumber = getLineNumber(content, match.index);
+        const isExported = content
+            .slice(Math.max(0, match.index - 10), match.index)
+            .includes('export');
+        declarations.push({
+            name: match[1],
+            type: 'const',
+            location: { file: filePath, line: lineNumber },
+            signature: match[0],
+            exported: isExported,
+        });
+    }
+    // Extract classes
+    CLASS_DECLARATION_PATTERN.lastIndex = 0;
+    while ((match = CLASS_DECLARATION_PATTERN.exec(content)) !== null) {
+        const lineNumber = getLineNumber(content, match.index);
+        const isExported = content
+            .slice(Math.max(0, match.index - 10), match.index)
+            .includes('export');
+        declarations.push({
+            name: match[1],
+            type: 'class',
+            location: { file: filePath, line: lineNumber },
+            signature: match[0],
+            exported: isExported,
+        });
+    }
+    // Extract interfaces
+    INTERFACE_PATTERN.lastIndex = 0;
+    while ((match = INTERFACE_PATTERN.exec(content)) !== null) {
+        const lineNumber = getLineNumber(content, match.index);
+        const isExported = content
+            .slice(Math.max(0, match.index - 10), match.index)
+            .includes('export');
+        declarations.push({
+            name: match[1],
+            type: 'interface',
+            location: { file: filePath, line: lineNumber },
+            signature: match[0],
+            exported: isExported,
+        });
+    }
+    // Extract type aliases
+    TYPE_ALIAS_PATTERN.lastIndex = 0;
+    while ((match = TYPE_ALIAS_PATTERN.exec(content)) !== null) {
+        const lineNumber = getLineNumber(content, match.index);
+        const isExported = content
+            .slice(Math.max(0, match.index - 10), match.index)
+            .includes('export');
+        declarations.push({
+            name: match[1],
+            type: 'type',
+            location: { file: filePath, line: lineNumber },
+            signature: match[0],
+            exported: isExported,
+        });
+    }
+    return declarations;
+}
+/**
+ * Gets the line number for a character index
+ */
+function getLineNumber(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+/**
+ * Parses README content into sections
+ * @param content - README file content
+ * @param filePath - Path to the README file
+ * @returns Array of parsed sections
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"parseReadmeSections","stability":"stable","signature":"(content: string, filePath: string) => ReadmeSection[]"}
+ */
+export function parseReadmeSections(content, filePath) {
+    const sections = [];
+    const lines = content.split('\n');
+    let currentSection = null;
+    let contentBuffer = [];
+    let lineNumber = 0;
+    let sectionContentStart = 0;
+    let fenceChar = null;
+    let fenceLen = 0;
+    for (const line of lines) {
+        lineNumber++;
+        // Track fenced code blocks (``` or ~~~, 3+ chars) so we skip
+        // heading-like lines inside them (e.g. "## More" in a template literal).
+        // CommonMark allows up to 3 leading spaces before a fence.
+        // Closing fences must have only trailing whitespace (no info string).
+        const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})(.*)/);
+        if (fenceMatch) {
+            const ch = fenceMatch[1][0];
+            const len = fenceMatch[1].length;
+            const trailing = fenceMatch[2];
+            if (!fenceChar) {
+                // Opening fence (info string allowed)
+                fenceChar = ch;
+                fenceLen = len;
+            }
+            else if (ch === fenceChar &&
+                len >= fenceLen &&
+                /^\s*$/.test(trailing)) {
+                // Closing fence (same char, at least as many, no info string)
+                fenceChar = null;
+                fenceLen = 0;
+            }
+        }
+        // Check for heading (only outside code fences)
+        const headingMatch = !fenceChar && line.match(/^(#{1,6})\s+(.+)/);
+        if (headingMatch) {
+            // Save previous section
+            if (currentSection) {
+                currentSection.content = contentBuffer.join('\n').trim();
+                currentSection.codeBlocks = extractCodeBlocks(currentSection.content, {
+                    file: filePath,
+                    line: sectionContentStart,
+                });
+                sections.push(currentSection);
+            }
+            // Start new section; content begins on the line after the heading
+            currentSection = {
+                heading: headingMatch[2],
+                level: headingMatch[1].length,
+                content: '',
+                codeBlocks: [],
+            };
+            contentBuffer = [];
+            sectionContentStart = lineNumber + 1;
+        }
+        else if (currentSection) {
+            contentBuffer.push(line);
+        }
+    }
+    // Save final section
+    if (currentSection) {
+        currentSection.content = contentBuffer.join('\n').trim();
+        currentSection.codeBlocks = extractCodeBlocks(currentSection.content, {
+            file: filePath,
+            line: sectionContentStart,
+        });
+        sections.push(currentSection);
+    }
+    return sections;
+}
+/**
+ * Extracts code blocks from markdown content
+ */
+function extractCodeBlocks(content, baseLocation) {
+    const examples = [];
+    // Anchored to line start to prevent matching inline sequences like foo```.
+    // Backreference \1 ensures closing fence uses the same char as opening.
+    // [^\S\n] = horizontal whitespace only (prevents consuming newlines between blocks).
+    // Allows up to 3 leading spaces per CommonMark.
+    const codeBlockPattern = /(?:^|\n)[^\S\n]{0,3}(`{3,}|~{3,})(\w*)[^\S\n]*\n([\s\S]*?)\n[^\S\n]{0,3}\1[^\S\n]*(?:\n|$)/g;
+    let match;
+    while ((match = codeBlockPattern.exec(content)) !== null) {
+        const language = match[2] || 'text';
+        const code = match[3];
+        const textBefore = content.slice(0, match.index);
+        const relativeLine = textBefore.split('\n').length;
+        examples.push({
+            code: code.trim(),
+            language,
+            runnable: ['typescript', 'ts', 'javascript', 'js'].includes(language.toLowerCase()),
+            isDoctest: false,
+            location: {
+                file: baseLocation.file,
+                line: baseLocation.line + relativeLine - 1,
+            },
+        });
+    }
+    return examples;
+}
+/**
+ * Links README sections to codex entry IDs based on heading matching
+ * @param sections - Parsed README sections
+ * @param entryIds - List of codex entry IDs
+ * @returns Sections with linked entry IDs
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"linkReadmeToEntries","stability":"stable","signature":"(sections: ReadmeSection[], entryIds: string[]) => ReadmeSection[]"}
+ */
+export function linkReadmeToEntries(sections, entryIds) {
+    return sections.map(section => {
+        // Try to match section heading to an entry ID.
+        // We intentionally only match by heading — content-based matching
+        // is too loose for large sections (e.g. "## Examples" spanning thousands
+        // of lines) and causes false-positive attribution. Explicit linking
+        // should use @codex:auto markers instead.
+        const normalizedHeading = section.heading
+            .toLowerCase()
+            .replace(/\s+/g, '-');
+        for (const entryId of entryIds) {
+            const entryParts = entryId.toLowerCase().split('.');
+            const lastPart = entryParts[entryParts.length - 1];
+            // Check if heading matches entry name
+            if (normalizedHeading.includes(lastPart) ||
+                lastPart.includes(normalizedHeading)) {
+                return { ...section, linkedEntryId: entryId };
+            }
+        }
+        return section;
+    });
+}
+/**
+ * Generates source links for display (GitHub-style URLs)
+ * @param location - Source location
+ * @param repoUrl - Base repository URL
+ * @param branch - Branch name (default: main)
+ * @returns URL string for the source location
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"generateSourceLink","stability":"stable","signature":"(location: SourceLocation, repoUrl: string, branch?: string) => string"}
+ */
+export function generateSourceLink(location, repoUrl, branch = 'main') {
+    // Normalize the file path (remove leading slashes, project root)
+    const normalizedPath = location.file.replace(/^.*?(packages|apps|src)/, '$1');
+    const lineFragment = location.endLine
+        ? `#L${location.line}-L${location.endLine}`
+        : `#L${location.line}`;
+    return `${repoUrl}/blob/${branch}/${normalizedPath}${lineFragment}`;
+}
+/**
+ * Creates a relative path from project root
+ * @param absolutePath - Absolute file path
+ * @param projectRoot - Project root path
+ * @returns Relative path
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"toRelativePath","stability":"stable","signature":"(absolutePath: string, projectRoot: string) => string"}
+ */
+export function toRelativePath(absolutePath, projectRoot) {
+    if (absolutePath.startsWith(projectRoot)) {
+        return absolutePath.slice(projectRoot.length).replace(/^\//, '');
+    }
+    return absolutePath;
+}
+/**
+ * Enriches source locations with additional context
+ * @param location - Basic source location
+ * @param content - File content
+ * @returns Enriched location with context
+ * @codexApi {"parent":"pithy.codex.extraction.source-linker","name":"enrichSourceLocation","stability":"stable","signature":"(location: SourceLocation, content: string) => SourceLocation & { context?: string }"}
+ */
+export function enrichSourceLocation(location, content) {
+    const lines = content.split('\n');
+    const lineIndex = location.line - 1;
+    if (lineIndex >= 0 && lineIndex < lines.length) {
+        // Get 2 lines of context before and after
+        const start = Math.max(0, lineIndex - 2);
+        const end = Math.min(lines.length, lineIndex + 3);
+        const context = lines.slice(start, end).join('\n');
+        return {
+            ...location,
+            endLine: location.endLine || location.line,
+            context,
+        };
+    }
+    return location;
+}

package/dist/extraction/test-example-extractor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.test-example-extractor",
+ *   "title": "Test Example Extractor",
+ *   "category": "compiler"
+ * }
+ *
+ * Extracts examples from test files marked with @codex:example
+ * and tracks test status from vitest/jest output.
+ */
+import type { TestExample, TestStatus } from './types.js';
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"extractTestExamples","stability":"stable","signature":"(content: string, filePath: string) => TestExample[]"}
+ *
+ * Extracts examples marked with @codex:example from a test file
+ * @param content - Test file content
+ * @param filePath - Path to the test file
+ * @returns Array of extracted test examples
+ *
+ * @example
+ * ```typescript
+ * // In a test file:
+ * // @codex:example pithy.signals.effect
+ * it("creates an effect that tracks dependencies", () => {
+ *   const count = signal(0);
+ *   let runCount = 0;
+ *   effect(() => { count(); runCount++; });
+ *   expect(runCount).toBe(1);
+ * });
+ * ```
+ */
+export declare function extractTestExamples(content: string, filePath: string): TestExample[];
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"parseVitestOutput","stability":"stable","signature":"(output: string) => TestStatus[]"}
+ *
+ * Parses vitest JSON output to extract test statuses
+ * @param output - JSON string from vitest --reporter=json
+ * @returns Array of test statuses
+ */
+export declare function parseVitestOutput(output: string): TestStatus[];
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"matchExamplesToStatuses","stability":"stable","signature":"(examples: TestExample[], statuses: TestStatus[]) => TestExample[]"}
+ *
+ * Matches extracted examples to test statuses by test name
+ * @param examples - Extracted test examples
+ * @param statuses - Test statuses from vitest output
+ * @returns Examples with updated status information
+ */
+export declare function matchExamplesToStatuses(examples: TestExample[], statuses: TestStatus[]): TestExample[];
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"generateExampleReport","stability":"stable","signature":"(examples: TestExample[]) => string"}
+ *
+ * Generates a markdown report of test examples with their statuses
+ * @param examples - Test examples to report
+ * @returns Markdown formatted report
+ */
+export declare function generateExampleReport(examples: TestExample[]): string;
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"validateTestExamples","stability":"experimental","signature":"(examples: TestExample[]) => { valid: TestExample[]; invalid: TestExample[] }"}
+ *
+ * Validates that test examples are working by checking their status
+ * @param examples - Test examples to validate
+ * @returns Object with valid and invalid examples
+ */
+export declare function validateTestExamples(examples: TestExample[]): {
+    valid: TestExample[];
+    invalid: TestExample[];
+};