skrypt-ai 0.8.0 → 0.8.1

package/dist/commands/mutate.js

@@ -0,0 +1,177 @@
+import { Command } from 'commander';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join, extname } from 'path';
+import { requirePro } from '../auth/index.js';
+import { generateMutants } from '../mutation/mutator.js';
+import { runMutant } from '../mutation/runner.js';
+import { printMutationReport, formatMutationJson } from '../mutation/reporter.js';
+export const mutateCommand = new Command('mutate')
+    .description('Run mutation testing on documented code examples')
+    .argument('[source]', 'Source code directory', '.')
+    .option('--files <paths...>', 'Target specific source files')
+    .option('--max-mutants <n>', 'Maximum mutants to generate', '100')
+    .option('--min-score <percent>', 'Fail if mutation score is below threshold')
+    .option('--timeout <ms>', 'Timeout per example in milliseconds', '10000')
+    .option('--docs <dir>', 'Documentation directory', './docs')
+    .option('--json', 'Output as JSON')
+    .action(async (source, options) => {
+    try {
+        if (!await requirePro('mutate')) {
+            process.exit(1);
+        }
+        const sourcePath = resolve(source);
+        const docsPath = resolve(options.docs || './docs');
+        const maxMutants = parseInt(options.maxMutants || '100', 10);
+        const timeout = parseInt(options.timeout || '10000', 10);
+        if (!existsSync(sourcePath)) {
+            console.error(`Error: Source directory not found: ${sourcePath}`);
+            process.exit(1);
+        }
+        console.log('skrypt mutate');
+        console.log(`  source: ${sourcePath}`);
+        console.log(`  docs:   ${docsPath}`);
+        console.log(`  max:    ${maxMutants} mutants`);
+        console.log('');
+        // Step 1: Find source files to mutate
+        const sourceFiles = options.files
+            ? options.files.map(f => resolve(f))
+            : findSourceFiles(sourcePath);
+        console.log(`Found ${sourceFiles.length} source files`);
+        // Step 2: Extract doc examples
+        console.log('Extracting doc examples...');
+        const docExamples = extractDocExamples(docsPath);
+        console.log(`  Found ${docExamples.length} code examples in docs`);
+        if (docExamples.length === 0) {
+            console.log('\nNo code examples found in documentation. Nothing to test.');
+            return;
+        }
+        // Step 3: Generate mutants
+        console.log('\nGenerating mutants...');
+        let allMutants = sourceFiles.flatMap(f => generateMutants(f, maxMutants));
+        allMutants = allMutants.slice(0, maxMutants);
+        console.log(`  Generated ${allMutants.length} mutants`);
+        if (allMutants.length === 0) {
+            console.log('\nNo mutants generated. Source files may not contain mutable patterns.');
+            return;
+        }
+        // Step 4: Run mutations
+        console.log('\nRunning mutation tests...');
+        const results = [];
+        for (let i = 0; i < allMutants.length; i++) {
+            const mutant = allMutants[i];
+            process.stdout.write(`\r  [${i + 1}/${allMutants.length}] Testing mutant ${mutant.id}...`);
+            const result = runMutant(mutant, docExamples, timeout);
+            results.push(result);
+        }
+        console.log('');
+        // Step 5: Build report
+        const killed = results.filter(r => r.status === 'killed').length;
+        const survived = results.filter(r => r.status === 'survived').length;
+        const errors = results.filter(r => r.status === 'error').length;
+        const timeouts = results.filter(r => r.status === 'timeout').length;
+        const total = killed + survived;
+        // Per-file breakdown
+        const byFile = new Map();
+        for (const r of results) {
+            const key = r.mutant.filePath;
+            if (!byFile.has(key))
+                byFile.set(key, []);
+            byFile.get(key).push(r);
+        }
+        const report = {
+            totalMutants: results.length,
+            killed,
+            survived,
+            errors,
+            timeouts,
+            mutationScore: total > 0 ? (killed / total) * 100 : 100,
+            files: [...byFile.entries()].map(([filePath, fileResults]) => {
+                const fKilled = fileResults.filter(r => r.status === 'killed').length;
+                const fSurvived = fileResults.filter(r => r.status === 'survived').length;
+                const fTotal = fKilled + fSurvived;
+                return {
+                    filePath,
+                    mutants: fileResults.length,
+                    killed: fKilled,
+                    survived: fSurvived,
+                    score: fTotal > 0 ? (fKilled / fTotal) * 100 : 100,
+                };
+            }),
+            survivors: results.filter(r => r.status === 'survived'),
+        };
+        // Step 6: Output
+        if (options.json) {
+            console.log(formatMutationJson(report));
+        }
+        else {
+            printMutationReport(report);
+        }
+        // Step 7: Threshold check
+        if (options.minScore) {
+            const threshold = parseInt(options.minScore, 10);
+            if (!isNaN(threshold) && report.mutationScore < threshold) {
+                console.error(`\nMutation score ${report.mutationScore.toFixed(1)}% is below threshold ${threshold}%`);
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});
+function findSourceFiles(dir) {
+    const codeExts = new Set(['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs']);
+    const files = [];
+    function walk(d) {
+        const entries = readdirSync(d);
+        for (const entry of entries) {
+            const fullPath = join(d, entry);
+            const s = statSync(fullPath);
+            if (s.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules' && entry !== 'dist') {
+                walk(fullPath);
+            }
+            else if (s.isFile() && codeExts.has(extname(entry))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+function extractDocExamples(docsDir) {
+    const examples = [];
+    if (!existsSync(docsDir))
+        return examples;
+    function walk(d) {
+        const entries = readdirSync(d);
+        for (const entry of entries) {
+            const fullPath = join(d, entry);
+            const s = statSync(fullPath);
+            if (s.isDirectory() && !entry.startsWith('.')) {
+                walk(fullPath);
+            }
+            else if (s.isFile() && (extname(entry) === '.md' || extname(entry) === '.mdx')) {
+                const content = readFileSync(fullPath, 'utf-8');
+                const blocks = content.matchAll(/```(\w+)\n([\s\S]*?)```/g);
+                for (const block of blocks) {
+                    const lang = block[1].toLowerCase();
+                    if (['typescript', 'javascript', 'python', 'ts', 'js', 'py'].includes(lang)) {
+                        examples.push({ code: block[2], language: normalizeLang(lang), filePath: fullPath });
+                    }
+                }
+            }
+        }
+    }
+    walk(docsDir);
+    return examples;
+}
+function normalizeLang(lang) {
+    if (lang === 'ts' || lang === 'typescript')
+        return 'typescript';
+    if (lang === 'js' || lang === 'javascript')
+        return 'javascript';
+    if (lang === 'py' || lang === 'python')
+        return 'python';
+    return lang;
+}

package/dist/config/types.js

@@ -28,7 +28,7 @@ export const DEFAULT_CONFIG = {
         format: 'markdown'
     },
     llm: {
-        provider: 'deepseek',
-        model: 'deepseek-v3'
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-6'
     }
 };

package/dist/coverage/calculator.d.ts

@@ -0,0 +1,7 @@
+import { APIElement } from '../scanner/types.js';
+import { DocumentedElement } from '../audit/types.js';
+import { CoverageReport } from './types.js';
+/**
+ * Calculate documentation coverage by cross-referencing code symbols with docs
+ */
+export declare function calculateCoverage(codeElements: APIElement[], docElements: DocumentedElement[], includeInternal?: boolean): CoverageReport;

package/dist/coverage/calculator.js

@@ -0,0 +1,86 @@
+/**
+ * Calculate documentation coverage by cross-referencing code symbols with docs
+ */
+export function calculateCoverage(codeElements, docElements, includeInternal = false) {
+    // Filter to exported/public unless includeInternal
+    const symbols = includeInternal
+        ? codeElements
+        : codeElements.filter(el => el.isExported || el.isPublic);
+    // Build a set of documented names (normalized, lowercased for matching).
+    // Note: matching is by name only because DocumentedElement tracks the doc file,
+    // not the source file. If two source files export the same name (e.g. `parse`),
+    // documenting either one counts both as covered. This is intentional: docs
+    // reference symbols by name, not by file path.
+    const documentedNames = new Set();
+    const exampleNames = new Set();
+    for (const doc of docElements) {
+        // Use just name for matching (docs don't track filePath)
+        documentedNames.add(doc.name.toLowerCase());
+        if (doc.hasExample) {
+            exampleNames.add(doc.name.toLowerCase());
+        }
+    }
+    // Group symbols by file
+    const byFile = new Map();
+    for (const el of symbols) {
+        if (!byFile.has(el.filePath))
+            byFile.set(el.filePath, []);
+        byFile.get(el.filePath).push(el);
+    }
+    // Calculate per-file coverage
+    const files = [];
+    const undocumented = [];
+    for (const [filePath, fileElements] of byFile) {
+        let documented = 0;
+        let withExamples = 0;
+        const undocNames = [];
+        for (const el of fileElements) {
+            const normalizedName = el.name.toLowerCase();
+            if (documentedNames.has(normalizedName)) {
+                documented++;
+                if (exampleNames.has(normalizedName)) {
+                    withExamples++;
+                }
+            }
+            else {
+                undocNames.push(el.name);
+                undocumented.push({
+                    name: el.name,
+                    kind: el.kind,
+                    filePath: el.filePath,
+                    isExported: el.isExported ?? false,
+                });
+            }
+        }
+        files.push({
+            filePath,
+            totalSymbols: fileElements.length,
+            documentedSymbols: documented,
+            exampleSymbols: withExamples,
+            coveragePercent: fileElements.length > 0
+                ? Math.round((documented / fileElements.length) * 100)
+                : 100,
+            undocumentedNames: undocNames,
+        });
+    }
+    // Sort files by coverage (lowest first)
+    files.sort((a, b) => a.coveragePercent - b.coveragePercent);
+    // Sort undocumented: exported first, then by name
+    undocumented.sort((a, b) => {
+        if (a.isExported !== b.isExported)
+            return a.isExported ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    const totalSymbols = symbols.length;
+    const documentedSymbols = symbols.filter(el => documentedNames.has(el.name.toLowerCase())).length;
+    const exampleSymbols = symbols.filter(el => exampleNames.has(el.name.toLowerCase())).length;
+    return {
+        totalSymbols,
+        documentedSymbols,
+        exampleSymbols,
+        coveragePercent: totalSymbols > 0 ? Math.round((documentedSymbols / totalSymbols) * 100) : 100,
+        examplePercent: totalSymbols > 0 ? Math.round((exampleSymbols / totalSymbols) * 100) : 100,
+        files,
+        undocumented,
+    };
+}

package/dist/coverage/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './calculator.js';
+export * from './reporter.js';

package/dist/coverage/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './calculator.js';
+export * from './reporter.js';

package/dist/coverage/reporter.d.ts

@@ -0,0 +1,9 @@
+import { CoverageReport } from './types.js';
+/**
+ * Print coverage report to terminal
+ */
+export declare function printCoverageReport(report: CoverageReport): void;
+/**
+ * Format report as JSON
+ */
+export declare function formatCoverageJson(report: CoverageReport): string;

package/dist/coverage/reporter.js

@@ -0,0 +1,65 @@
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+/**
+ * Format a coverage bar: [████████░░] 80%
+ */
+function coverageBar(percent, width = 30) {
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    const color = percent >= 80 ? GREEN : percent >= 50 ? YELLOW : RED;
+    return `${color}[${'█'.repeat(filled)}${'░'.repeat(empty)}]${RESET} ${percent}%`;
+}
+/**
+ * Print coverage report to terminal
+ */
+export function printCoverageReport(report) {
+    console.log(`\n${BOLD}Documentation Coverage Report${RESET}\n`);
+    // Overall bar
+    console.log(`  Coverage:  ${coverageBar(report.coveragePercent)}`);
+    console.log(`  Examples:  ${coverageBar(report.examplePercent)}`);
+    console.log(`  Symbols:   ${report.documentedSymbols}/${report.totalSymbols} documented, ${report.exampleSymbols} with examples`);
+    console.log('');
+    // Per-file table
+    if (report.files.length > 0) {
+        console.log(`${BOLD}  Per-file Breakdown${RESET}`);
+        console.log(`  ${'File'.padEnd(45)} ${'Symbols'.padStart(8)} ${'Docs'.padStart(6)} ${'Ex'.padStart(4)} ${'Coverage'.padStart(10)}`);
+        console.log(`  ${'─'.repeat(45)} ${'─'.repeat(8)} ${'─'.repeat(6)} ${'─'.repeat(4)} ${'─'.repeat(10)}`);
+        for (const file of report.files) {
+            const shortPath = shortenPath(file.filePath, 44);
+            const color = file.coveragePercent >= 80 ? GREEN : file.coveragePercent >= 50 ? YELLOW : RED;
+            console.log(`  ${shortPath.padEnd(45)} ${String(file.totalSymbols).padStart(8)} ${String(file.documentedSymbols).padStart(6)} ${String(file.exampleSymbols).padStart(4)} ${color}${String(file.coveragePercent + '%').padStart(10)}${RESET}`);
+        }
+        console.log('');
+    }
+    // Undocumented symbols (top 20)
+    if (report.undocumented.length > 0) {
+        const shown = report.undocumented.slice(0, 20);
+        console.log(`${BOLD}  Undocumented Symbols${RESET} (${report.undocumented.length} total)`);
+        for (const sym of shown) {
+            const exported = sym.isExported ? `${RED}exported${RESET}` : `${DIM}internal${RESET}`;
+            console.log(`    ${sym.kind.padEnd(10)} ${sym.name.padEnd(35)} ${exported}`);
+        }
+        if (report.undocumented.length > 20) {
+            console.log(`    ${DIM}... and ${report.undocumented.length - 20} more${RESET}`);
+        }
+        console.log('');
+    }
+    // Summary line
+    const color = report.coveragePercent >= 80 ? GREEN : report.coveragePercent >= 50 ? YELLOW : RED;
+    console.log(`${color}${BOLD}  Coverage: ${report.coveragePercent}% (${report.documentedSymbols}/${report.totalSymbols}) | Examples: ${report.examplePercent}% (${report.exampleSymbols}/${report.totalSymbols})${RESET}\n`);
+}
+/**
+ * Format report as JSON
+ */
+export function formatCoverageJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+function shortenPath(filePath, maxLen) {
+    if (filePath.length <= maxLen)
+        return filePath;
+    return '...' + filePath.slice(filePath.length - maxLen + 3);
+}

package/dist/coverage/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Coverage report for a single file
+ */
+export interface FileCoverage {
+    filePath: string;
+    totalSymbols: number;
+    documentedSymbols: number;
+    exampleSymbols: number;
+    coveragePercent: number;
+    undocumentedNames: string[];
+}
+/**
+ * Overall coverage report
+ */
+export interface CoverageReport {
+    totalSymbols: number;
+    documentedSymbols: number;
+    exampleSymbols: number;
+    coveragePercent: number;
+    examplePercent: number;
+    files: FileCoverage[];
+    undocumented: Array<{
+        name: string;
+        kind: string;
+        filePath: string;
+        isExported: boolean;
+    }>;
+}
+/**
+ * Options for coverage calculation
+ */
+export interface CoverageOptions {
+    includeInternal?: boolean;
+    minCoverage?: number;
+    json?: boolean;
+}

package/dist/coverage/types.js

@@ -0,0 +1 @@
+export {};

package/dist/generator/generator.d.ts

@@ -2,7 +2,9 @@ import { APIElement } from '../scanner/types.js';
 import { LLMClient } from '../llm/index.js';
 import { GeneratedDoc, GenerationOptions, GenerationProgress } from './types.js';
 /**
- * Generate documentation for an API element (no testing)
+ * Generate documentation for an API element (no testing).
+ * Supports hash-based caching: if the element's inputs haven't changed,
+ * the cached result is returned without calling the LLM.
  */
 export declare function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>;
 /**

package/dist/generator/generator.js

@@ -1,5 +1,10 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
 import { generateDocumentation } from '../llm/index.js';
 import { matchImportsToContext } from '../context-hub/index.js';
+/** Directory name for generation cache (project-local) */
+const CACHE_DIR = '.skrypt-cache';
 /**
  * Build enhanced context for LLM from API element
  */
@@ -23,6 +28,50 @@ function buildElementContext(element, externalContext, projectContext) {
     }
     return ctx;
 }
+/**
+ * Compute a deterministic hash for an element's generation inputs.
+ * Covers: element name, source context, and the system prompt template (via multiLanguage flag).
+ */
+function computeCacheKey(element, multiLanguage) {
+    const h = createHash('sha256');
+    h.update(element.name);
+    h.update(element.signature || '');
+    h.update(element.sourceContext || '');
+    h.update(element.docstring || '');
+    h.update(element.filePath || '');
+    h.update(multiLanguage ? 'multi' : 'single');
+    return h.digest('hex');
+}
+/**
+ * Attempt to read a cached generation result.
+ * Returns undefined on miss.
+ */
+function readCache(cacheDir, key) {
+    const filePath = join(cacheDir, `${key}.json`);
+    try {
+        if (!existsSync(filePath))
+            return undefined;
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write a generation result to the cache directory (created lazily).
+ */
+function writeCache(cacheDir, key, doc) {
+    try {
+        if (!existsSync(cacheDir)) {
+            mkdirSync(cacheDir, { recursive: true });
+        }
+        writeFileSync(join(cacheDir, `${key}.json`), JSON.stringify(doc), 'utf-8');
+    }
+    catch {
+        // Cache write failure is non-fatal
+    }
+}
 /**
  * Detect code language from file path
  */
@@ -52,7 +101,9 @@ function detectLanguageFromFile(filePath) {
     return 'typescript';
 }
 /**
- * Generate documentation for an API element (no testing)
+ * Generate documentation for an API element (no testing).
+ * Supports hash-based caching: if the element's inputs haven't changed,
+ * the cached result is returned without calling the LLM.
  */
 export async function generateForElement(element, client, options, onProgress) {
     const report = (status) => {
@@ -65,13 +116,24 @@ export async function generateForElement(element, client, options, onProgress) {
     };
     const codeLanguage = detectLanguageFromFile(element.filePath);
     const useMultiLang = options.multiLanguage ?? false;
+    // --- Cache check ---
+    const useCache = !options.noCache;
+    const cacheDir = join(options.cacheDir || process.cwd(), CACHE_DIR);
+    if (useCache) {
+        const cacheKey = computeCacheKey(element, useMultiLang);
+        const cached = readCache(cacheDir, cacheKey);
+        if (cached) {
+            report('done');
+            return cached;
+        }
+    }
     report('generating');
     try {
         const elementContext = buildElementContext(element, options.externalContext, options.projectContext);
         const errorContext = options.previousErrors?.get(element.name);
         const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang, verify: options.verify, previousError: errorContext });
         report('done');
-        return {
+        const doc = {
             element,
             markdown: result.markdown,
             codeExample: result.codeExample,
@@ -80,6 +142,12 @@ export async function generateForElement(element, client, options, onProgress) {
             pythonExample: result.pythonExample,
             usage: result.usage
         };
+        // --- Cache write ---
+        if (useCache) {
+            const cacheKey = computeCacheKey(element, useMultiLang);
+            writeCache(cacheDir, cacheKey, doc);
+        }
+        return doc;
     }
     catch (err) {
         report('failed');
@@ -92,35 +160,81 @@ export async function generateForElement(element, client, options, onProgress) {
         };
     }
 }
+/**
+ * Simple concurrency limiter (pLimit-style). Limits the number of
+ * concurrently executing async functions without adding a dependency.
+ */
+function createConcurrencyLimiter(concurrency) {
+    let active = 0;
+    const queue = [];
+    function next() {
+        if (queue.length > 0 && active < concurrency) {
+            active++;
+            const resolve = queue.shift();
+            resolve();
+        }
+    }
+    return async function limit(fn) {
+        // Wait for a slot to open
+        if (active >= concurrency) {
+            await new Promise((resolve) => {
+                queue.push(resolve);
+            });
+        }
+        else {
+            active++;
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            active--;
+            next();
+        }
+    };
+}
 /**
  * Generate documentation for multiple elements
  */
 export async function generateForElements(elements, client, options) {
-    const results = [];
-    let totalTokens = 0;
     const MAX_TOKENS = options.maxTokens ?? 1_000_000; // default 1M tokens (~$10-20)
-    for (let i = 0; i < elements.length; i++) {
-        const element = elements[i];
+    const concurrency = options.concurrency ?? 5;
+    const limit = createConcurrencyLimiter(concurrency);
+    // Shared mutable state — safe because JS is single-threaded;
+    // mutations happen synchronously between await points.
+    let totalTokens = 0;
+    let budgetExceeded = false;
+    // Pre-allocate results array to preserve original ordering
+    const results = new Array(elements.length);
+    const promises = elements.map((element, i) => {
         if (!element)
-            continue;
-        const doc = await generateForElement(element, client, options, (progress) => {
-            options.onProgress?.({
-                ...progress,
-                current: i + 1,
-                total: elements.length
+            return Promise.resolve();
+        return limit(async () => {
+            // Check budget before starting — another concurrent task may have exceeded it
+            if (budgetExceeded)
+                return;
+            const doc = await generateForElement(element, client, options, (progress) => {
+                options.onProgress?.({
+                    ...progress,
+                    current: i + 1,
+                    total: elements.length
+                });
             });
+            // Store result at original index to preserve ordering
+            results[i] = doc;
+            if (doc.usage) {
+                totalTokens += (doc.usage.inputTokens ?? 0) + (doc.usage.outputTokens ?? 0);
+            }
+            if (totalTokens > MAX_TOKENS) {
+                budgetExceeded = true;
+                console.warn(`\nToken budget exceeded (${totalTokens.toLocaleString()} tokens used). Stopping generation.`);
+                console.warn('Use --max-tokens to increase the limit.');
+            }
         });
-        results.push(doc);
-        if (doc.usage) {
-            totalTokens += (doc.usage.inputTokens ?? 0) + (doc.usage.outputTokens ?? 0);
-        }
-        if (totalTokens > MAX_TOKENS) {
-            console.warn(`\nToken budget exceeded (${totalTokens.toLocaleString()} tokens used). Stopping generation.`);
-            console.warn('Use --max-tokens to increase the limit.');
-            break;
-        }
-    }
-    return results;
+    });
+    await Promise.all(promises);
+    // Filter out undefined slots (skipped elements or budget-exceeded gaps)
+    return results.filter((r) => r !== undefined);
 }
 /**
  * Format generated docs as markdown file content

package/dist/generator/mdx-serializer.js

@@ -130,6 +130,7 @@ export function serializeMdxToMarkdown(mdx) {
 }
 function formatBlockquote(label, content) {
     const lines = content.split('\n');
-    const quoted = lines.map(line => `> ${line}`).join('\n');
-    return `> **${label}:** ${quoted.replace(/^> /, '')}\n`;
+    const first = `> **${label}:** ${lines[0]}`;
+    const rest = lines.slice(1).map(line => `> ${line}`);
+    return [first, ...rest].join('\n') + '\n';
 }

package/dist/generator/organizer.d.ts

@@ -8,7 +8,11 @@ export declare const DEFAULT_TOPIC_CONFIG: TopicConfig;
  */
 export declare function organizeByTopic(docs: GeneratedDoc[], config?: TopicConfig): Topic[];
 /**
- * Detect cross-references between elements
+ * Detect cross-references between elements.
+ *
+ * Instead of checking every element name against every doc's source text (O(n^2) with
+ * string.includes), we build a single regex alternation of all element names and scan
+ * each doc's text once. This reduces the inner loop to a single regex pass per doc.
  */
 export declare function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[];
 /**