@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/pipeline.js

@@ -0,0 +1,526 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.pipeline",
+ *   "title": "Extraction Pipeline",
+ *   "category": "feature"
+ * }
+ */
+import { globby } from 'globby';
+import fs from 'node:fs/promises';
+import { basename, isAbsolute, join, relative } from 'node:path';
+import { DEFAULT_EXTRACTION_CONFIG, } from './types.js';
+import { linkJSDocToDeclarations } from './jsdoc-parser.js';
+import { extractExamplesFromSource } from './example-extractor.js';
+import { analyzeTestFile, matchTestToEntry, testCasesToReferences, } from './test-pattern-extractor.js';
+import { extractAllDeclarations, parseReadmeSections, linkReadmeToEntries, } from './source-linker.js';
+import { discoverComponentsFromFile } from '../annotations.js';
+import { extractTypesFromFile } from './type-extractor.js';
+import { extractTestExamples, parseVitestOutput, matchExamplesToStatuses, } from './test-example-extractor.js';
+/**
+ * Concurrency limit for parallel file processing
+ */
+const CONCURRENCY_LIMIT = 10;
+/**
+ * Processes items in parallel with a concurrency limit
+ * @param items - Items to process
+ * @param processor - Async function to process each item
+ * @param limit - Maximum concurrent operations
+ */
+async function processInParallel(items, processor, limit = CONCURRENCY_LIMIT) {
+    const results = [];
+    for (let i = 0; i < items.length; i += limit) {
+        const batch = items.slice(i, i + limit);
+        const batchResults = await Promise.all(batch.map(processor));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Gets the first description from a JSDoc map, if any exists
+ * @param jsdocMap - Map of declaration names to JSDoc
+ * @returns First description found, or undefined
+ */
+function getFirstDescription(jsdocMap) {
+    for (const jsdoc of jsdocMap.values()) {
+        if (jsdoc.description) {
+            return jsdoc.description;
+        }
+    }
+    return undefined;
+}
+/**
+ * Builds full config by merging defaults with provided options
+ */
+function buildFullConfig(config) {
+    return {
+        root: config?.root ?? process.cwd(),
+        sourcePatterns: config?.sourcePatterns ?? DEFAULT_EXTRACTION_CONFIG.sourcePatterns,
+        testPatterns: config?.testPatterns ?? DEFAULT_EXTRACTION_CONFIG.testPatterns,
+        readmePatterns: config?.readmePatterns ?? DEFAULT_EXTRACTION_CONFIG.readmePatterns,
+        extractRunnableExamples: config?.extractRunnableExamples ??
+            DEFAULT_EXTRACTION_CONFIG.extractRunnableExamples,
+        analyzeTests: config?.analyzeTests ?? DEFAULT_EXTRACTION_CONFIG.analyzeTests,
+        linkReadmes: config?.linkReadmes ?? DEFAULT_EXTRACTION_CONFIG.linkReadmes,
+        vitestOutputPath: config?.vitestOutputPath,
+    };
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.pipeline","name":"runExtractionPipeline","stability":"stable","signature":"(config?: Partial<ExtractionConfig>) => Promise<ExtendedExtractionResult>"}
+ *
+ * Runs the complete multi-source extraction pipeline
+ * @param config - Configuration options
+ * @returns Extraction result with all enriched data including types and test examples
+ *
+ * @example
+ * ```typescript
+ * const result = await runExtractionPipeline({
+ *   root: '/path/to/project',
+ *   extractRunnableExamples: true,
+ * });
+ *
+ * console.log(`Found ${result.stats.componentsFound} components`);
+ * console.log(`Extracted ${result.typeDefinitions.length} types`);
+ * console.log(`Found ${result.testExamples.length} test examples`);
+ * ```
+ */
+export async function runExtractionPipeline(config) {
+    const startTime = performance.now();
+    const fullConfig = buildFullConfig(config);
+    const stats = {
+        filesScanned: 0,
+        componentsFound: 0,
+        apisExtracted: 0,
+        examplesExtracted: 0,
+        testsAnalyzed: 0,
+        readmeSectionsLinked: 0,
+        processingTimeMs: 0,
+    };
+    // Phase 1: Discover source files
+    const sourceFiles = await globby(fullConfig.sourcePatterns, {
+        cwd: fullConfig.root,
+        absolute: true,
+        gitignore: true,
+    });
+    stats.filesScanned = sourceFiles.length;
+    // Phase 2: Extract components and APIs from source files (parallelized)
+    const components = [];
+    const allApiNames = [];
+    const extractionResults = await processInParallel(sourceFiles, async (filePath) => {
+        const content = await fs.readFile(filePath, 'utf8').catch(() => '');
+        if (!content)
+            return null;
+        // Get base component info from codex annotations
+        const discoveredComponents = await discoverComponentsFromFile(filePath, content);
+        if (discoveredComponents.length === 0)
+            return null;
+        const fileComponents = [];
+        const fileApiNames = [];
+        let fileExamplesCount = 0;
+        for (const discovered of discoveredComponents) {
+            // Enrich with JSDoc parsing
+            const jsdocMap = linkJSDocToDeclarations(content, filePath);
+            const declarations = extractAllDeclarations(content, filePath);
+            const sourceExamples = extractExamplesFromSource(content, filePath);
+            // Enrich APIs with JSDoc
+            const enrichedApis = [];
+            for (const api of discovered.apis) {
+                const jsdoc = jsdocMap.get(api.name);
+                const declaration = declarations.find(d => d.name === api.name);
+                // Collect examples for this API
+                const apiExamples = sourceExamples
+                    .filter(se => se.functionName === api.name)
+                    .flatMap(se => se.examples);
+                if (jsdoc) {
+                    apiExamples.push(...jsdoc.examples);
+                }
+                enrichedApis.push({
+                    id: `${discovered.id}.${api.name}`,
+                    name: api.name,
+                    parent: discovered.id,
+                    signature: api.signature || declaration?.signature,
+                    stability: api.stability || 'stable',
+                    jsdoc,
+                    examples: apiExamples,
+                    testRefs: [], // Will be populated in Phase 3
+                    sourceLocation: declaration?.location || {
+                        file: filePath,
+                        line: 1,
+                    },
+                });
+                fileApiNames.push(api.name);
+                fileExamplesCount += apiExamples.length;
+            }
+            // Collect component-level examples
+            const componentExamples = sourceExamples
+                .filter(se => !enrichedApis.some(a => a.name === se.functionName))
+                .flatMap(se => se.examples);
+            fileComponents.push({
+                id: discovered.id,
+                title: discovered.title,
+                category: discovered.category,
+                risk: discovered.risk,
+                testing: discovered.testing,
+                description: getFirstDescription(jsdocMap),
+                apis: enrichedApis,
+                examples: componentExamples,
+                testRefs: [], // Will be populated in Phase 3
+                sourceFiles: [{ file: filePath, line: 1 }],
+            });
+        }
+        return {
+            components: fileComponents,
+            apiNames: fileApiNames,
+            examplesCount: fileExamplesCount,
+        };
+    });
+    // Aggregate results from parallel processing
+    for (const result of extractionResults) {
+        if (result) {
+            components.push(...result.components);
+            allApiNames.push(...result.apiNames);
+            stats.examplesExtracted += result.examplesCount;
+            stats.apisExtracted += result.components.reduce((sum, c) => sum + c.apis.length, 0);
+            stats.componentsFound += result.components.length;
+        }
+    }
+    // Phase 3: Analyze test files and link to components (parallelized)
+    const testAnalyses = [];
+    // Discover test files once, reused by Phase 6
+    const testFiles = fullConfig.analyzeTests
+        ? await globby(fullConfig.testPatterns, {
+            cwd: fullConfig.root,
+            absolute: true,
+            gitignore: true,
+        })
+        : [];
+    if (fullConfig.analyzeTests) {
+        const entryIds = components.map(c => c.id);
+        // Build a reverse map from test filenames to entry IDs using
+        // the testing.unit.file / testing.integration.file hints in source
+        // annotations. Multiple entries may reference the same test file,
+        // so the map stores arrays of entry IDs.
+        //
+        // Keys are scoped by package directory (e.g. "packages/vitePlugins:scanner.test.ts")
+        // to prevent collisions when different packages share test filenames.
+        const testFileHints = new Map();
+        // Extract the package scope from an absolute path.
+        // Detects monorepo segments like "packages/<name>" or "apps/<name>" from
+        // the absolute path so hints work regardless of what `root` is set to.
+        // Falls back to the first two segments relative to root when no monorepo
+        // segment is found (single-package repos or non-standard layouts).
+        function packageDirOf(absPath) {
+            const normalized = absPath.replace(/\\/g, '/');
+            const monoMatch = normalized.match(/\/(packages|apps)\/([^/]+)\//);
+            if (monoMatch)
+                return `${monoMatch[1]}/${monoMatch[2]}`;
+            const rel = relative(fullConfig.root, absPath).replace(/\\/g, '/');
+            const parts = rel.split('/');
+            return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+        }
+        for (const comp of components) {
+            const srcFile = comp.sourceFiles[0]?.file;
+            if (!srcFile)
+                continue;
+            const pkgDir = packageDirOf(srcFile);
+            for (const level of ['unit', 'integration', 'e2e']) {
+                const hint = comp.testing?.[level]?.file;
+                if (hint) {
+                    const key = `${pkgDir}:${basename(hint).toLowerCase()}`;
+                    const existing = testFileHints.get(key) ?? [];
+                    if (!existing.includes(comp.id)) {
+                        existing.push(comp.id);
+                    }
+                    testFileHints.set(key, existing);
+                }
+            }
+        }
+        const analysisResults = await processInParallel(testFiles, async (testPath) => {
+            const content = await fs.readFile(testPath, 'utf8').catch(() => '');
+            if (!content)
+                return null;
+            const analysis = analyzeTestFile(content, testPath, allApiNames);
+            const hintKey = `${packageDirOf(testPath)}:${basename(testPath).toLowerCase()}`;
+            // Prefer explicit testing.*.file hints from source annotations
+            // (avoids heuristic mismatches when multiple entries share names).
+            // Keys are scoped by package directory so identically-named test
+            // files in different packages don't collide.
+            const hintEntryIds = testFileHints.get(hintKey);
+            const matchedEntryId = hintEntryIds?.[0] ?? matchTestToEntry(testPath, entryIds);
+            return { analysis, matchedEntryId, testPath, hintEntryIds };
+        });
+        // Helper: link test refs to a component and its APIs
+        function linkTestRefsToComponent(component, refs, analysis) {
+            component.testRefs.push(...refs);
+            for (const api of component.apis) {
+                const apiRefs = refs.filter(r => r.name.toLowerCase().includes(api.name.toLowerCase()) ||
+                    analysis.coveredApis.includes(api.name));
+                api.testRefs.push(...apiRefs);
+            }
+        }
+        // Build a lookup map for constant-time component access by ID
+        const componentById = new Map();
+        for (const comp of components) {
+            componentById.set(comp.id, comp);
+        }
+        // Apply results (must be sequential for component mutations)
+        for (const result of analysisResults) {
+            if (!result)
+                continue;
+            const { analysis, matchedEntryId, testPath, hintEntryIds } = result;
+            testAnalyses.push(analysis);
+            stats.testsAnalyzed += analysis.testCases.length;
+            const refs = testCasesToReferences(analysis.testCases, testPath);
+            // Link tests to ALL components that declare this test file
+            if (hintEntryIds && hintEntryIds.length > 0) {
+                for (const entryId of hintEntryIds) {
+                    const component = componentById.get(entryId);
+                    if (component) {
+                        linkTestRefsToComponent(component, refs, analysis);
+                    }
+                }
+            }
+            else if (matchedEntryId) {
+                const component = componentById.get(matchedEntryId);
+                if (component) {
+                    linkTestRefsToComponent(component, refs, analysis);
+                }
+            }
+        }
+    }
+    // Phase 4: Parse and link README files (parallelized)
+    const readmeSections = [];
+    if (fullConfig.linkReadmes) {
+        const readmeFiles = await globby(fullConfig.readmePatterns, {
+            cwd: fullConfig.root,
+            absolute: true,
+            gitignore: true,
+        });
+        const entryIds = components.map(c => c.id);
+        const readmeResults = await processInParallel(readmeFiles, async (readmePath) => {
+            const content = await fs.readFile(readmePath, 'utf8').catch(() => '');
+            if (!content)
+                return null;
+            const sections = parseReadmeSections(content, readmePath);
+            const linkedSections = linkReadmeToEntries(sections, entryIds);
+            return linkedSections;
+        });
+        // Apply results (must be sequential for component mutations)
+        for (const linkedSections of readmeResults) {
+            if (!linkedSections)
+                continue;
+            for (const section of linkedSections) {
+                if (section.linkedEntryId) {
+                    stats.readmeSectionsLinked++;
+                    // Add README examples to component
+                    const component = components.find(c => c.id === section.linkedEntryId);
+                    if (component) {
+                        component.readmeSections = component.readmeSections || [];
+                        component.readmeSections.push(section);
+                        component.examples.push(...section.codeBlocks);
+                        stats.examplesExtracted += section.codeBlocks.length;
+                    }
+                }
+            }
+            readmeSections.push(...linkedSections);
+        }
+    }
+    // Phase 5: Extract TypeScript type definitions
+    const typeDefinitions = [];
+    const typeResults = await processInParallel(sourceFiles.filter(f => f.endsWith('.ts')), async (filePath) => {
+        const content = await fs.readFile(filePath, 'utf8').catch(() => '');
+        if (!content)
+            return null;
+        return extractTypesFromFile(filePath, content);
+    });
+    for (const types of typeResults) {
+        if (types) {
+            typeDefinitions.push(...types);
+        }
+    }
+    // Phase 6: Extract test examples via @codex:example markers
+    // Reuses testFiles discovered in Phase 3
+    let testExamples = [];
+    if (fullConfig.analyzeTests && testFiles.length > 0) {
+        const exampleResults = await processInParallel(testFiles, async (testPath) => {
+            const content = await fs.readFile(testPath, 'utf8').catch(() => '');
+            if (!content)
+                return null;
+            return extractTestExamples(content, testPath);
+        });
+        for (const examples of exampleResults) {
+            if (examples) {
+                testExamples.push(...examples);
+            }
+        }
+    }
+    // Phase 7: Optionally parse vitest output and match to examples
+    let testStatuses = parseVitestOutput('{}'); // empty default
+    if (fullConfig.vitestOutputPath) {
+        const resolvedPath = isAbsolute(fullConfig.vitestOutputPath)
+            ? fullConfig.vitestOutputPath
+            : join(fullConfig.root, fullConfig.vitestOutputPath);
+        const vitestJson = await fs.readFile(resolvedPath, 'utf8').catch(err => {
+            console.warn(`[codex] Failed to read vitest output from ${resolvedPath}:`, err instanceof Error ? err.message : String(err));
+            return '';
+        });
+        if (vitestJson) {
+            testStatuses = parseVitestOutput(vitestJson);
+            testExamples = matchExamplesToStatuses(testExamples, testStatuses);
+        }
+    }
+    stats.processingTimeMs = performance.now() - startTime;
+    const result = {
+        components,
+        testAnalysis: testAnalyses,
+        readmeSections,
+        stats,
+        typeDefinitions,
+        testExamples,
+        testStatuses,
+    };
+    return result;
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.pipeline","name":"extractSingleFile","stability":"stable","signature":"(filePath: string, content?: string) => Promise<EnrichedComponent | null>"}
+ *
+ * Extracts documentation from a single source file
+ * @param filePath - Path to the source file
+ * @param content - Optional file content (will read if not provided)
+ * @returns Enriched component or null if no codex annotation found
+ */
+export async function extractSingleFile(filePath, content) {
+    const fileContent = content || (await fs.readFile(filePath, 'utf8').catch(() => ''));
+    if (!fileContent)
+        return null;
+    const discoveredComponents = await discoverComponentsFromFile(filePath, fileContent);
+    if (discoveredComponents.length === 0)
+        return null;
+    const discovered = discoveredComponents[0];
+    const jsdocMap = linkJSDocToDeclarations(fileContent, filePath);
+    const declarations = extractAllDeclarations(fileContent, filePath);
+    const sourceExamples = extractExamplesFromSource(fileContent, filePath);
+    const enrichedApis = [];
+    for (const api of discovered.apis) {
+        const jsdoc = jsdocMap.get(api.name);
+        const declaration = declarations.find(d => d.name === api.name);
+        const apiExamples = sourceExamples
+            .filter(se => se.functionName === api.name)
+            .flatMap(se => se.examples);
+        if (jsdoc) {
+            apiExamples.push(...jsdoc.examples);
+        }
+        enrichedApis.push({
+            id: `${discovered.id}.${api.name}`,
+            name: api.name,
+            parent: discovered.id,
+            signature: api.signature || declaration?.signature,
+            stability: api.stability || 'stable',
+            jsdoc,
+            examples: apiExamples,
+            testRefs: [],
+            sourceLocation: declaration?.location || { file: filePath, line: 1 },
+        });
+    }
+    return {
+        id: discovered.id,
+        title: discovered.title,
+        category: discovered.category,
+        description: getFirstDescription(jsdocMap),
+        apis: enrichedApis,
+        examples: sourceExamples.flatMap(se => se.examples),
+        testRefs: [],
+        sourceFiles: [{ file: filePath, line: 1 }],
+    };
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.pipeline","name":"generateExtractionReport","stability":"stable","signature":"(result: ExtractionResult) => string"}
+ *
+ * Generates a human-readable report from extraction results
+ * @param result - Extraction result
+ * @returns Formatted report string
+ */
+export function generateExtractionReport(result) {
+    const { stats, components, testAnalysis } = result;
+    const lines = [
+        '# Extraction Pipeline Report',
+        '',
+        '## Statistics',
+        `- Files scanned: ${stats.filesScanned}`,
+        `- Components found: ${stats.componentsFound}`,
+        `- APIs extracted: ${stats.apisExtracted}`,
+        `- Examples extracted: ${stats.examplesExtracted}`,
+        `- Tests analyzed: ${stats.testsAnalyzed}`,
+        `- README sections linked: ${stats.readmeSectionsLinked}`,
+        `- Processing time: ${stats.processingTimeMs.toFixed(2)}ms`,
+        '',
+        '## Components',
+    ];
+    for (const component of components) {
+        lines.push(`\n### ${component.title} (\`${component.id}\`)`);
+        lines.push(`Category: ${component.category}`);
+        if (component.description) {
+            lines.push(`\n${component.description}`);
+        }
+        lines.push(`\n**APIs (${component.apis.length}):**`);
+        for (const api of component.apis) {
+            const stability = api.stability === 'stable' ? '' : ` [${api.stability}]`;
+            lines.push(`- \`${api.name}\`${stability} - ${api.examples.length} examples, ${api.testRefs.length} tests`);
+        }
+        lines.push(`\n**Test coverage:** ${component.testRefs.length} test references`);
+    }
+    lines.push('\n## Test Analysis Summary');
+    const totalTests = testAnalysis.reduce((sum, a) => sum + a.testCases.length, 0);
+    lines.push(`Total test cases: ${totalTests}`);
+    return lines.join('\n');
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.pipeline","name":"exportToCodexFormat","stability":"stable","signature":"(result: ExtractionResult) => object"}
+ *
+ * Exports extraction results to codex-compatible JSON format
+ * @param result - Extraction result
+ * @returns Object suitable for codex.index.json
+ */
+export function exportToCodexFormat(result) {
+    return {
+        entries: result.components.map(c => ({
+            id: c.id,
+            title: c.title,
+            category: c.category,
+            description: c.description,
+            sourceFiles: c.sourceFiles.map(sf => ({
+                file: sf.file,
+                line: sf.line,
+            })),
+            apis: c.apis.map(api => ({
+                name: api.name,
+                signature: api.signature,
+                stability: api.stability,
+                examples: api.examples.map(ex => ({
+                    code: ex.code,
+                    language: ex.language,
+                    runnable: ex.runnable,
+                })),
+                testRefs: api.testRefs.map(tr => ({
+                    file: tr.file,
+                    line: tr.line,
+                    name: tr.name,
+                    type: tr.type,
+                })),
+            })),
+            examples: c.examples.map(ex => ({
+                code: ex.code,
+                language: ex.language,
+                runnable: ex.runnable,
+            })),
+            testRefs: c.testRefs.map(tr => ({
+                file: tr.file,
+                line: tr.line,
+                name: tr.name,
+                type: tr.type,
+            })),
+        })),
+        stats: result.stats,
+        generatedAt: new Date().toISOString(),
+    };
+}

package/dist/extraction/readme-sync.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @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 type { ReadmeMarker, ReadmeMarkerType, ReadmeSyncResult, ReadmeSyncConfig, EnrichedComponent, ExtendedExtractionResult, TestExample } from './types.js';
+/**
+ * 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 declare function parseMarkerAttributes(attrString: string): Record<string, string>;
+/**
+ * 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 declare function resolveMarkerType(attributes: Record<string, string>): ReadmeMarkerType | null;
+/**
+ * Parses all @codex:auto markers from README content.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"parseReadmeMarkers","stability":"stable","signature":"(content: string) => ReadmeMarker[]"}
+ */
+export declare function parseReadmeMarkers(content: string): ReadmeMarker[];
+/**
+ * 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 declare function matchIdPattern(pattern: string, entryId: string): boolean;
+/**
+ * Filters components by an ID pattern.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"filterByPattern","stability":"stable","signature":"(components: EnrichedComponent[], pattern: string) => EnrichedComponent[]"}
+ */
+export declare function filterByPattern(components: EnrichedComponent[], pattern: string): EnrichedComponent[];
+/**
+ * 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 declare function stripTestBoilerplate(code: string): string;
+/**
+ * Generates install command content for a package.
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateInstallContent","stability":"stable","signature":"(packageName: string) => string"}
+ */
+export declare function generateInstallContent(packageName: string): string;
+/**
+ * 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 declare function generateExamplesContent(components: EnrichedComponent[], limit?: number, testExamples?: TestExample[], pattern?: string): string;
+/**
+ * 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 declare function escapeTableCell(str: string): string;
+/**
+ * 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 declare function escapeMd(str: string): string;
+/**
+ * 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 declare function sanitizeForInlineCode(str: string): string;
+/** 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 declare function longestBacktickRun(str: string): number;
+/** 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 declare function sanitizeLanguage(lang: string): string;
+/**
+ * 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 declare function generateApiContent(components: EnrichedComponent[], format?: string): string;
+/**
+ * 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 declare function generateTestingContent(components: EnrichedComponent[]): string;
+/**
+ * Placeholder for bundle content generation (not yet implemented).
+ * @codexApi {"parent":"pithy.codex.extraction.readme-sync","name":"generateBundleContent","stability":"stable","signature":"(_packageName: string) => string"}
+ */
+export declare function generateBundleContent(_packageName: string): string;
+/**
+ * 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 declare function syncReadmeContent(content: string, filePath: string, components: EnrichedComponent[], testExamples?: TestExample[]): ReadmeSyncResult;
+/**
+ * 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 declare function syncAllReadmes(extractionResult: ExtendedExtractionResult, config?: ReadmeSyncConfig): Promise<ReadmeSyncResult[]>;