@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/breaking-changes.js

@@ -0,0 +1,352 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.breaking-changes",
+ *   "title": "Breaking Change Detection",
+ *   "category": "feature"
+ * }
+ *
+ * Detects breaking changes between API snapshots by comparing
+ * extracted API signatures, stability levels, and type definitions.
+ * Generates migration guides and changelogs for version transitions.
+ */
+import { getTypeSignature } from './type-extractor.js';
+import { basename } from 'node:path';
+// ── Helpers ──────────────────────────────────────────────────────
+/** Normalize a signature string for comparison (collapse whitespace, trim). */
+function normalizeSignature(sig) {
+    if (sig === undefined)
+        return undefined;
+    return sig.replace(/\s+/g, ' ').trim();
+}
+/** Serialize members for deep comparison (order-independent). */
+function membersKey(members) {
+    if (!members || members.length === 0)
+        return '';
+    return members
+        .map(m => {
+        const sig = normalizeSignature(m.signature) ?? m.type;
+        const ro = m.readonly ? 'readonly ' : '';
+        const opt = m.optional ? '?' : '';
+        return `${m.name}|${ro}${opt}|${sig}`;
+    })
+        .sort()
+        .join(';');
+}
+// ── createApiSnapshot ────────────────────────────────────────────
+/**
+ * Create an API snapshot from extraction results at a given version.
+ * Captures all enriched API entries across all components.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"createApiSnapshot","stability":"stable","signature":"(result: ExtendedExtractionResult, version: string, timestamp?: string) => ApiSnapshot"}
+ */
+export function createApiSnapshot(result, version, timestamp) {
+    const entries = [];
+    for (const component of result.components) {
+        for (const api of component.apis) {
+            entries.push({
+                name: api.name,
+                parent: component.id,
+                qualifiedName: `${component.id}.${api.name}`,
+                signature: api.signature,
+                stability: api.stability,
+            });
+        }
+    }
+    return {
+        version,
+        timestamp: timestamp ?? new Date().toISOString(),
+        entries,
+    };
+}
+// ── snapshotFromTypeDefinitions ──────────────────────────────────
+/**
+ * Create an API snapshot from extracted type definitions.
+ * Only includes exported types (public API surface).
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"snapshotFromTypeDefinitions","stability":"stable","signature":"(types: ExtractedTypeDefinition[], version: string, timestamp?: string) => ApiSnapshot"}
+ */
+export function snapshotFromTypeDefinitions(types, version, timestamp) {
+    const entries = [];
+    for (const type of types) {
+        if (!type.exported)
+            continue;
+        const stability = type.jsdoc?.deprecated
+            ? 'deprecated'
+            : 'stable';
+        const parent = basename(type.location.file);
+        entries.push({
+            name: type.name,
+            parent,
+            qualifiedName: `${parent}.${type.name}`,
+            stability,
+            signature: getTypeSignature(type),
+            kind: type.kind,
+            members: type.members,
+        });
+    }
+    return {
+        version,
+        timestamp: timestamp ?? new Date().toISOString(),
+        entries,
+    };
+}
+// ── diffSnapshots ────────────────────────────────────────────────
+/**
+ * Compare two API snapshots and produce a structured diff.
+ * Matches entries by qualifiedName (parent.name).
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"diffSnapshots","stability":"stable","signature":"(before: ApiSnapshot, after: ApiSnapshot) => SnapshotDiff"}
+ */
+export function diffSnapshots(before, after) {
+    const beforeMap = new Map();
+    for (const entry of before.entries) {
+        beforeMap.set(entry.qualifiedName, entry);
+    }
+    const afterMap = new Map();
+    for (const entry of after.entries) {
+        afterMap.set(entry.qualifiedName, entry);
+    }
+    const added = [];
+    const removed = [];
+    const changed = [];
+    let unchanged = 0;
+    // Find removed and changed entries
+    for (const [qn, beforeEntry] of beforeMap) {
+        const afterEntry = afterMap.get(qn);
+        if (!afterEntry) {
+            removed.push({
+                name: beforeEntry.name,
+                parent: beforeEntry.parent,
+                qualifiedName: qn,
+                changeKind: 'removed',
+                before: beforeEntry,
+            });
+            continue;
+        }
+        // Check for changes — priority: signature > members > stability
+        // When multiple aspects change, the highest-priority changeKind is used.
+        // The full before/after entries are always preserved so consumers can
+        // detect secondary changes (e.g. stability shift alongside signature change).
+        const beforeSig = normalizeSignature(beforeEntry.signature);
+        const afterSig = normalizeSignature(afterEntry.signature);
+        if (beforeSig !== afterSig) {
+            changed.push({
+                name: beforeEntry.name,
+                parent: beforeEntry.parent,
+                qualifiedName: qn,
+                changeKind: 'signature-changed',
+                before: beforeEntry,
+                after: afterEntry,
+            });
+        }
+        else if (membersKey(beforeEntry.members) !== membersKey(afterEntry.members)) {
+            changed.push({
+                name: beforeEntry.name,
+                parent: beforeEntry.parent,
+                qualifiedName: qn,
+                changeKind: 'members-changed',
+                before: beforeEntry,
+                after: afterEntry,
+            });
+        }
+        else if (beforeEntry.stability !== afterEntry.stability) {
+            changed.push({
+                name: beforeEntry.name,
+                parent: beforeEntry.parent,
+                qualifiedName: qn,
+                changeKind: 'stability-changed',
+                before: beforeEntry,
+                after: afterEntry,
+            });
+        }
+        else {
+            unchanged++;
+        }
+    }
+    // Find added entries
+    for (const [qn, afterEntry] of afterMap) {
+        if (!beforeMap.has(qn)) {
+            added.push({
+                name: afterEntry.name,
+                parent: afterEntry.parent,
+                qualifiedName: qn,
+                changeKind: 'added',
+                after: afterEntry,
+            });
+        }
+    }
+    return {
+        fromVersion: before.version,
+        toVersion: after.version,
+        added,
+        removed,
+        changed,
+        unchanged,
+    };
+}
+// ── classifyChange ───────────────────────────────────────────────
+/**
+ * Classify a single API change as major, minor, or patch
+ * according to semver conventions.
+ *
+ * - **major**: removal or signature/member change of a stable API
+ * - **minor**: addition, removal of experimental/deprecated, or changes to experimental APIs
+ * - **patch**: stability level changes
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"classifyChange","stability":"stable","signature":"(change: ApiChange) => ChangeClassification"}
+ */
+export function classifyChange(change) {
+    switch (change.changeKind) {
+        case 'added':
+            return 'minor';
+        case 'removed': {
+            const stability = change.before?.stability;
+            // Removing internal (non-public), experimental, or deprecated APIs is
+            // non-breaking — only stable public APIs count as breaking removals.
+            if (stability === 'internal' ||
+                stability === 'experimental' ||
+                stability === 'deprecated') {
+                return 'minor';
+            }
+            return 'major';
+        }
+        case 'signature-changed':
+        case 'members-changed': {
+            // Changing internal (non-public), experimental, or deprecated APIs is
+            // non-breaking — only stable public APIs count as breaking changes.
+            const stability = change.before?.stability;
+            if (stability === 'internal' ||
+                stability === 'experimental' ||
+                stability === 'deprecated') {
+                return 'minor';
+            }
+            return 'major';
+        }
+        case 'stability-changed':
+            return 'patch';
+        default: {
+            const _exhaustive = change.changeKind;
+            throw new Error(`Unknown change kind: ${_exhaustive}`);
+        }
+    }
+}
+// ── detectBreakingChanges ────────────────────────────────────────
+/**
+ * Filter a snapshot diff down to only breaking changes
+ * (those classified as "major").
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"detectBreakingChanges","stability":"stable","signature":"(diff: SnapshotDiff) => ApiChange[]"}
+ */
+export function detectBreakingChanges(diff) {
+    const allChanges = [...diff.removed, ...diff.changed];
+    return allChanges.filter(c => classifyChange(c) === 'major');
+}
+// ── generateMigrationGuide ───────────────────────────────────────
+/**
+ * Generate a human-readable migration guide for a set of breaking changes.
+ * Groups changes by parent component and provides before/after comparisons.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"generateMigrationGuide","stability":"stable","signature":"(changes: ApiChange[]) => string"}
+ */
+export function generateMigrationGuide(changes) {
+    if (changes.length === 0)
+        return '';
+    const lines = ['# Migration Guide', ''];
+    // Group changes by parent
+    const grouped = new Map();
+    for (const change of changes) {
+        const group = grouped.get(change.parent) ?? [];
+        group.push(change);
+        grouped.set(change.parent, group);
+    }
+    for (const [parent, groupChanges] of grouped) {
+        lines.push(`## ${parent}`, '');
+        for (const change of groupChanges) {
+            switch (change.changeKind) {
+                case 'removed':
+                    lines.push(`### \`${change.name}\` — removed`, '', `The \`${change.name}\` API has been removed.`);
+                    if (change.before?.signature) {
+                        lines.push('', '**Previous signature:**', '```typescript', change.before.signature, '```');
+                    }
+                    lines.push('');
+                    break;
+                case 'signature-changed':
+                    lines.push(`### \`${change.name}\` — signature changed`, '', `The signature of \`${change.name}\` has changed.`, '', '**Before:**', '```typescript', change.before?.signature ?? '(unknown)', '```', '', '**After:**', '```typescript', change.after?.signature ?? '(unknown)', '```', '');
+                    break;
+                case 'members-changed':
+                    lines.push(`### \`${change.name}\` — members changed`, '', `The members of the \`${change.name}\` type have changed.`, '');
+                    break;
+                case 'stability-changed':
+                    lines.push(`### \`${change.name}\` — stability changed`, '', `Stability changed from \`${change.before?.stability}\` to \`${change.after?.stability}\`.`, '');
+                    break;
+                // "added" is not typically in a migration guide, skip
+                default:
+                    break;
+            }
+        }
+    }
+    return lines.join('\n');
+}
+// ── generateChangelog ────────────────────────────────────────────
+/**
+ * Generate a changelog in Markdown from a snapshot diff.
+ * Sections: Breaking Changes, Added, Changed. Omits empty sections.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"generateChangelog","stability":"stable","signature":"(diff: SnapshotDiff) => string"}
+ */
+export function generateChangelog(diff) {
+    const breaking = detectBreakingChanges(diff);
+    const hasBreaking = breaking.length > 0;
+    const hasAdded = diff.added.length > 0;
+    const hasChanged = diff.changed.length > 0;
+    const hasRemoved = diff.removed.length > 0;
+    if (!hasBreaking && !hasAdded && !hasChanged && !hasRemoved) {
+        return '';
+    }
+    const lines = [`## ${diff.fromVersion} → ${diff.toVersion}`, ''];
+    if (hasBreaking) {
+        lines.push('### ⚠️ Breaking Changes', '');
+        for (const change of breaking) {
+            if (change.changeKind === 'removed') {
+                lines.push(`- **Removed** \`${change.qualifiedName}\``);
+            }
+            else if (change.changeKind === 'signature-changed') {
+                lines.push(`- **Changed** \`${change.qualifiedName}\` signature`);
+            }
+            else if (change.changeKind === 'members-changed') {
+                lines.push(`- **Changed** \`${change.qualifiedName}\` members`);
+            }
+        }
+        lines.push('');
+    }
+    if (hasAdded) {
+        lines.push('### Added', '');
+        for (const change of diff.added) {
+            lines.push(`- \`${change.qualifiedName}\``);
+        }
+        lines.push('');
+    }
+    // Non-breaking changes (stability, non-breaking signature changes)
+    const nonBreakingChanges = diff.changed.filter(c => classifyChange(c) !== 'major');
+    const nonBreakingRemovals = diff.removed.filter(c => classifyChange(c) !== 'major');
+    if (nonBreakingChanges.length > 0 || nonBreakingRemovals.length > 0) {
+        lines.push('### Changed', '');
+        for (const change of nonBreakingChanges) {
+            if (change.changeKind === 'stability-changed') {
+                lines.push(`- \`${change.qualifiedName}\` stability: ${change.before?.stability} → ${change.after?.stability}`);
+            }
+            else if (change.changeKind === 'signature-changed') {
+                lines.push(`- \`${change.qualifiedName}\` signature changed (non-breaking)`);
+            }
+            else if (change.changeKind === 'members-changed') {
+                lines.push(`- \`${change.qualifiedName}\` members changed (non-breaking)`);
+            }
+        }
+        for (const change of nonBreakingRemovals) {
+            lines.push(`- **Removed** \`${change.qualifiedName}\` (was ${change.before?.stability})`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.example-extractor",
+ *   "title": "Example Extractor",
+ *   "category": "compiler"
+ * }
+ */
+import type { ExtractedExample, SourceLocation } from './types.js';
+/**
+ * Extracts all code examples from a markdown/documentation string
+ * @param content - Content to extract examples from
+ * @param baseLocation - Base source location for the content
+ * @returns Array of extracted examples
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"extractExamples","stability":"stable","signature":"(content: string, baseLocation: SourceLocation) => ExtractedExample[]"}
+ */
+export declare function extractExamples(content: string, baseLocation: SourceLocation): ExtractedExample[];
+/**
+ * Validates that a code example is syntactically valid
+ * @param code - Code to validate
+ * @param language - Language of the code
+ * @returns Validation result with any errors
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"validateExample","stability":"stable","signature":"(code: string, language: string) => { valid: boolean; errors: string[] }"}
+ */
+export declare function validateExample(code: string, _language: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Wraps a doctest example in a test harness
+ * @param example - The extracted example
+ * @param entryId - ID of the codex entry this example belongs to
+ * @returns Test code ready to run with vitest
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"wrapDoctestInHarness","stability":"stable","signature":"(example: ExtractedExample, entryId: string) => string"}
+ */
+export declare function wrapDoctestInHarness(example: ExtractedExample, entryId: string): string;
+/**
+ * Extracts examples from JSDoc @example tags in source code
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @returns Array of extracted examples with their context
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"extractExamplesFromSource","stability":"stable","signature":"(content: string, filePath: string) => { functionName: string; examples: ExtractedExample[] }[]"}
+ */
+export declare function extractExamplesFromSource(content: string, filePath: string): {
+    functionName: string;
+    examples: ExtractedExample[];
+}[];
+/**
+ * Generates a runnable example file from extracted examples
+ * @param examples - Examples to include
+ * @param imports - Required imports
+ * @returns Complete TypeScript file content
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"generateRunnableExampleFile","stability":"stable","signature":"(examples: ExtractedExample[], imports: string[]) => string"}
+ */
+export declare function generateRunnableExampleFile(examples: ExtractedExample[], imports: string[]): string;

package/dist/extraction/example-extractor.js

@@ -0,0 +1,272 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.example-extractor",
+ *   "title": "Example Extractor",
+ *   "category": "compiler"
+ * }
+ */
+/**
+ * Regex patterns for code block extraction
+ */
+const CODE_BLOCK_REGEX = /```(\w*(?:\s+doctest)?)\s*\n([\s\S]*?)\n\s*```/g;
+/**
+ * Escapes a string for use in a JavaScript single-quoted string.
+ * Prevents code injection by escaping backslashes, quotes, and newlines.
+ */
+function escapeForSingleQuotedString(str) {
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+/**
+ * Languages that are considered runnable
+ */
+const RUNNABLE_LANGUAGES = new Set([
+    'typescript',
+    'ts',
+    'javascript',
+    'js',
+    'tsx',
+    'jsx',
+]);
+/**
+ * Extracts all code examples from a markdown/documentation string
+ * @param content - Content to extract examples from
+ * @param baseLocation - Base source location for the content
+ * @returns Array of extracted examples
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"extractExamples","stability":"stable","signature":"(content: string, baseLocation: SourceLocation) => ExtractedExample[]"}
+ */
+export function extractExamples(content, baseLocation) {
+    const examples = [];
+    // Reset regex state
+    CODE_BLOCK_REGEX.lastIndex = 0;
+    let match;
+    while ((match = CODE_BLOCK_REGEX.exec(content)) !== null) {
+        const [, languageSpec, code] = match;
+        const startIndex = match.index;
+        // Calculate relative line number
+        const textBefore = content.slice(0, startIndex);
+        const relativeLine = textBefore.split('\n').length;
+        // Parse language and doctest flag
+        const isDoctest = languageSpec.includes('doctest');
+        const language = languageSpec.replace(/\s*doctest\s*/, '').trim() || 'typescript';
+        // Determine if runnable
+        const isRunnable = isDoctest || RUNNABLE_LANGUAGES.has(language.toLowerCase());
+        // Extract description from preceding text
+        const precedingLines = textBefore.split('\n').slice(-3);
+        const description = extractExampleDescription(precedingLines);
+        examples.push({
+            code: code.trim(),
+            language,
+            description,
+            runnable: isRunnable,
+            isDoctest,
+            location: {
+                ...baseLocation,
+                line: baseLocation.line + relativeLine - 1,
+            },
+        });
+    }
+    return examples;
+}
+/**
+ * Extracts description from lines preceding a code block
+ */
+function extractExampleDescription(precedingLines) {
+    // Look for a description in the last non-empty line before the code block
+    for (let i = precedingLines.length - 1; i >= 0; i--) {
+        const line = precedingLines[i].trim();
+        // Skip empty lines and headers
+        if (!line || line.startsWith('#') || line.startsWith('```')) {
+            continue;
+        }
+        // Return the description if it's meaningful
+        if (line.length > 5 && !line.startsWith('@')) {
+            return line;
+        }
+    }
+    return undefined;
+}
+/**
+ * Validates that a code example is syntactically valid
+ * @param code - Code to validate
+ * @param language - Language of the code
+ * @returns Validation result with any errors
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"validateExample","stability":"stable","signature":"(code: string, language: string) => { valid: boolean; errors: string[] }"}
+ */
+export function validateExample(code, _language) {
+    const errors = [];
+    // Basic syntax checks
+    if (!code.trim()) {
+        errors.push('Empty code block');
+        return { valid: false, errors };
+    }
+    // Check for balanced brackets
+    const brackets = {
+        '(': ')',
+        '[': ']',
+        '{': '}',
+    };
+    const stack = [];
+    let inString = false;
+    let stringChar = '';
+    for (let i = 0; i < code.length; i++) {
+        const char = code[i];
+        const prevChar = i > 0 ? code[i - 1] : '';
+        // Handle strings
+        if ((char === '"' || char === "'" || char === '`') && prevChar !== '\\') {
+            if (!inString) {
+                inString = true;
+                stringChar = char;
+            }
+            else if (char === stringChar) {
+                inString = false;
+                stringChar = '';
+            }
+            continue;
+        }
+        if (inString)
+            continue;
+        // Handle brackets
+        if (brackets[char]) {
+            stack.push(brackets[char]);
+        }
+        else if (Object.values(brackets).includes(char)) {
+            if (stack.length === 0 || stack.pop() !== char) {
+                errors.push(`Unbalanced brackets: unexpected '${char}'`);
+            }
+        }
+    }
+    if (stack.length > 0) {
+        errors.push(`Unbalanced brackets: missing ${stack.join(', ')}`);
+    }
+    if (inString) {
+        errors.push(`Unterminated string starting with ${stringChar}`);
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Wraps a doctest example in a test harness
+ * @param example - The extracted example
+ * @param entryId - ID of the codex entry this example belongs to
+ * @returns Test code ready to run with vitest
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"wrapDoctestInHarness","stability":"stable","signature":"(example: ExtractedExample, entryId: string) => string"}
+ */
+export function wrapDoctestInHarness(example, entryId) {
+    const testName = example.description || `doctest from ${entryId}`;
+    // Properly escape for single-quoted strings in generated code
+    const safeEntryId = escapeForSingleQuotedString(entryId);
+    const safeTestName = escapeForSingleQuotedString(testName);
+    // Indent the example code
+    const indentedCode = example.code
+        .split('\n')
+        .map(line => `    ${line}`)
+        .join('\n');
+    return `import { describe, it, expect } from 'vitest';
+
+describe('${safeEntryId}', () => {
+  it('${safeTestName}', async () => {
+${indentedCode}
+  });
+});`;
+}
+/**
+ * Extracts examples from JSDoc @example tags in source code
+ * @param content - Source file content
+ * @param filePath - Path to the source file
+ * @returns Array of extracted examples with their context
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"extractExamplesFromSource","stability":"stable","signature":"(content: string, filePath: string) => { functionName: string; examples: ExtractedExample[] }[]"}
+ */
+export function extractExamplesFromSource(content, filePath) {
+    const results = [];
+    // Match a single JSDoc block followed by a function declaration.
+    // Uses ((?:[^*]|\*(?!\/))*) instead of ([\s\S]*?) to prevent the regex
+    // from backtracking across two adjacent /** */ blocks (e.g., a JSDoc
+    // comment immediately followed by a @codexApi comment).
+    const jsdocFunctionPattern = /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:\/\*\*(?:[^*]|\*(?!\/))*\*\/\s*)*(?:export\s+)?(?:async\s+)?(?:function|const|let|var)\s+(\w+)/g;
+    let match;
+    while ((match = jsdocFunctionPattern.exec(content)) !== null) {
+        const [, jsdocContent, functionName] = match;
+        const startIndex = match.index;
+        // Calculate line number
+        const textBefore = content.slice(0, startIndex);
+        const lineNumber = textBefore.split('\n').length;
+        // Clean JSDoc asterisk prefixes from the captured content so that:
+        // 1. Code block regexes (``` ... ```) can match correctly
+        // 2. @example end-detection doesn't false-positive on @word inside code
+        //    (e.g., '@pithyjs/shared' in an import statement)
+        const cleanedJsdoc = jsdocContent
+            .split('\n')
+            .map(l => l.replace(/^\s*\*\s?/, ''))
+            .join('\n');
+        // Match @example at the start of a line only — not mid-sentence
+        // mentions like "from JSDoc @example tags". Terminates at the next
+        // @tag at the start of a line, or end of string.
+        const examplePattern = /(?:^|\n)@example[ \t]*\n?([\s\S]*?)(?=\n@\w+|$)/g;
+        const examples = [];
+        let exampleMatch;
+        while ((exampleMatch = examplePattern.exec(cleanedJsdoc)) !== null) {
+            const exampleContent = exampleMatch[1].trim();
+            const baseLocation = {
+                file: filePath,
+                line: lineNumber,
+            };
+            // Extract code blocks from the example content
+            const extractedExamples = extractExamples(exampleContent, baseLocation);
+            // If no code blocks found, treat the content as inline code
+            if (extractedExamples.length === 0 && exampleContent) {
+                // Strip JSDoc comment delimiter artifacts that leak in when
+                // two adjacent /** */ blocks are captured as one
+                const cleanedCode = exampleContent
+                    .split('\n')
+                    .filter(l => !/^\s*\*?\/?$/.test(l) && !/^\s*\/\*\*?\s*$/.test(l))
+                    .join('\n')
+                    .trim();
+                if (cleanedCode) {
+                    examples.push({
+                        code: cleanedCode,
+                        language: 'typescript',
+                        runnable: true,
+                        isDoctest: false,
+                        location: baseLocation,
+                    });
+                }
+            }
+            else {
+                examples.push(...extractedExamples);
+            }
+        }
+        if (examples.length > 0) {
+            results.push({ functionName, examples });
+        }
+    }
+    return results;
+}
+/**
+ * Generates a runnable example file from extracted examples
+ * @param examples - Examples to include
+ * @param imports - Required imports
+ * @returns Complete TypeScript file content
+ * @codexApi {"parent":"pithy.codex.extraction.example-extractor","name":"generateRunnableExampleFile","stability":"stable","signature":"(examples: ExtractedExample[], imports: string[]) => string"}
+ */
+export function generateRunnableExampleFile(examples, imports) {
+    const importStatements = imports.map(imp => `import ${imp};`).join('\n');
+    const exampleBlocks = examples
+        .filter(ex => ex.runnable)
+        .map((ex, i) => `
+// Example ${i + 1}
+// From: ${ex.location.file}:${ex.location.line}
+${ex.description ? `// ${ex.description}` : ''}
+${ex.code}
+`)
+        .join('\n');
+    return `${importStatements}
+
+${exampleBlocks}
+`.trim();
+}