skrypt-ai 0.8.0 → 0.8.1

package/dist/generator/organizer.js

@@ -123,28 +123,43 @@ function sortDocsWithinTopic(docs) {
     });
 }
 /**
- * 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 function detectCrossReferences(docs) {
     const refs = [];
     const elementNames = new Set(docs.map(d => d.element.name));
+    // Build a single regex matching any element name as a whole word.
+    // Escape regex special chars in names, join with alternation, wrap in word boundaries.
+    const namesArray = Array.from(elementNames);
+    if (namesArray.length === 0)
+        return refs;
+    const escaped = namesArray.map(n => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const combinedPattern = new RegExp(`\\b(?:${escaped.join('|')})\\b`, 'g');
     for (const doc of docs) {
         const { element } = doc;
-        // Check source context for references to other elements
-        const sourceContext = element.sourceContext || '';
-        const signature = element.signature || '';
-        for (const otherName of elementNames) {
-            if (otherName === element.name)
-                continue;
-            // Check if this element uses another element
-            if (sourceContext.includes(otherName) || signature.includes(otherName)) {
-                refs.push({
-                    fromElement: element.name,
-                    toElement: otherName,
-                    relationship: 'uses'
-                });
+        const text = (element.sourceContext || '') + '\n' + (element.signature || '');
+        // Single-pass regex scan to find all referenced element names
+        const referencedNames = new Set();
+        let match;
+        while ((match = combinedPattern.exec(text)) !== null) {
+            const name = match[0];
+            if (name !== element.name && elementNames.has(name)) {
+                referencedNames.add(name);
             }
         }
+        // Reset lastIndex for the next doc since the regex is global
+        combinedPattern.lastIndex = 0;
+        for (const otherName of referencedNames) {
+            refs.push({
+                fromElement: element.name,
+                toElement: otherName,
+                relationship: 'uses'
+            });
+        }
         // Methods reference their parent class
         if (element.parentClass && elementNames.has(element.parentClass)) {
             refs.push({

package/dist/generator/types.d.ts

@@ -36,6 +36,12 @@ export interface GenerationOptions {
     verify?: boolean;
     /** Error context from previous verification failures, keyed by element name */
     previousErrors?: Map<string, string>;
+    /** Max concurrent LLM calls (default: 5) */
+    concurrency?: number;
+    /** Skip generation cache and always call the LLM */
+    noCache?: boolean;
+    /** Directory to store cache files (default: project cwd) */
+    cacheDir?: string;
 }
 /**
  * Result of generating docs for a file

package/dist/generator/writer.js

@@ -5,6 +5,7 @@ import { formatAsMarkdown } from './generator.js';
 import { organizeByTopic, detectCrossReferences, getCrossRefsForElement } from './organizer.js';
 import { slugify } from '../utils/files.js';
 import { serializeMdxToMarkdown } from './mdx-serializer.js';
+import { stripResponseMarkers } from '../llm/index.js';
 /**
  * Generate llms.txt file (Answer Engine Optimization)
  * Format follows https://llmstxt.org convention
@@ -124,7 +125,9 @@ export async function writeDocsToDirectory(results, outputDir, sourceDir, option
         const title = basename(result.filePath).replace(/\.[^.]+$/, '')
             .replace(/^./, c => c.toUpperCase())
             .replace(/_/g, ' ');
-        const content = formatAsMarkdown(result.docs, title);
+        let content = formatAsMarkdown(result.docs, title);
+        // Defense-in-depth: strip any leaked LLM response markers before writing
+        content = stripResponseMarkers(content);
         // Write file
         await writeFile(outputPath, content, 'utf-8');
         filesWritten++;
@@ -212,7 +215,9 @@ export async function writeDocsByTopic(docs, outputDir) {
     // Write each topic as a separate file
     for (const topic of topics) {
         const topicPath = join(outputDir, `${topic.id}.md`);
-        const content = formatTopicMarkdown(topic, crossRefs);
+        let content = formatTopicMarkdown(topic, crossRefs);
+        // Defense-in-depth: strip any leaked LLM response markers before writing
+        content = stripResponseMarkers(content);
         await writeFile(topicPath, content, 'utf-8');
         filesWritten++;
     }

package/dist/github/org-discovery.js

@@ -89,5 +89,10 @@ export async function cloneRepoToTemp(repo, token) {
         const stderr = (result.stderr?.toString() || '').replace(/x-access-token:[^@]+@/g, 'x-access-token:***@');
         throw new Error(`Failed to clone ${repo.full_name}: ${stderr}`);
     }
+    // Scrub the token from .git/config so it doesn't persist on disk
+    try {
+        spawnSync('git', ['-C', tempDir, 'remote', 'set-url', 'origin', repo.clone_url], { stdio: 'pipe' });
+    }
+    catch { /* non-critical — temp dir will be deleted anyway */ }
     return tempDir;
 }

package/dist/importers/mintlify.js

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync } from 'fs';
-import { join, relative, basename, extname } from 'path';
+import { join, relative, basename, extname, resolve, sep } from 'path';
 import { findMdxFiles } from '../utils/files.js';
 import { transformMintlifyCallouts, transformMintlifyTabs, normalizeFrontmatter, rewriteImagePaths } from './transform.js';
 /**
@@ -78,9 +78,10 @@ function processPage(dir, pageRef, stats, result) {
     let content = readFileSync(filePath, 'utf-8');
     // Handle <Snippet file="x.mdx" /> — inline referenced files
     content = content.replace(/<Snippet\s+file="([^"]+)"\s*\/>/g, (_match, snippetPath) => {
-        const snippetFile = join(dir, snippetPath);
+        const snippetFile = resolve(join(dir, snippetPath));
+        const resolvedDir = resolve(dir) + sep;
         // Guard: prevent path traversal outside source directory
-        if (!snippetFile.startsWith(dir)) {
+        if (!snippetFile.startsWith(resolvedDir) && snippetFile !== resolve(dir)) {
             result.warnings.push(`Snippet path traversal blocked: ${snippetPath}`);
             return `<!-- Snippet blocked: ${snippetPath} -->`;
         }

package/dist/llm/anthropic-client.js

@@ -61,6 +61,7 @@ export class AnthropicClient {
         switch (reason) {
             case 'end_turn':
             case 'stop_sequence':
+            case null:
                 return 'stop';
             case 'max_tokens':
                 return 'length';

package/dist/llm/index.d.ts

@@ -55,3 +55,18 @@ export declare function generateDocumentation(client: LLMClient, element: Elemen
     verify?: boolean;
     previousError?: string;
 }): Promise<GeneratedDocResult>;
+/**
+ * Normalize delimiter variations that LLMs (especially GPT-4o) produce.
+ * Models may return delimiters with extra dashes, spaces, backticks, bold markers, or different casing.
+ * Examples that should all normalize to ---MARKDOWN---:
+ *   "--- MARKDOWN ---", "----MARKDOWN----", "**---MARKDOWN---**",
+ *   "`---MARKDOWN---`", "---Markdown---", "--- markdown ---"
+ */
+export declare function normalizeDelimiters(content: string): string;
+/**
+ * Strip all LLM response markers from content.
+ * This is a safety net — if parsing fails or partially succeeds, we must never
+ * write raw ---CODE---/---END---/---MARKDOWN--- markers to .md files because
+ * curly braces inside unfenced code blocks cause MDX compilation errors.
+ */
+export declare function stripResponseMarkers(content: string): string;

package/dist/llm/index.js

@@ -182,40 +182,159 @@ function buildDocPrompt(element, multiLanguage = false, verify = false) {
     }
     return prompt;
 }
+/**
+ * Normalize delimiter variations that LLMs (especially GPT-4o) produce.
+ * Models may return delimiters with extra dashes, spaces, backticks, bold markers, or different casing.
+ * Examples that should all normalize to ---MARKDOWN---:
+ *   "--- MARKDOWN ---", "----MARKDOWN----", "**---MARKDOWN---**",
+ *   "`---MARKDOWN---`", "---Markdown---", "--- markdown ---"
+ */
+export function normalizeDelimiters(content) {
+    // Match delimiter patterns: optional formatting chars, 2+ dashes, optional spaces,
+    // a known keyword, optional spaces, 2+ dashes, optional formatting chars
+    // Covers: ---MARKDOWN---, --- MARKDOWN ---, ----MARKDOWN----, **---MARKDOWN---**, `---MARKDOWN---`
+    const delimiterPattern = /^[`*]*-{2,}\s*(MARKDOWN|TYPESCRIPT|PYTHON|CODE|END)\s*-{2,}[`*]*$/gim;
+    return content.replace(delimiterPattern, (_match, keyword) => `---${keyword.toUpperCase()}---`);
+}
+/**
+ * Strip all LLM response markers from content.
+ * This is a safety net — if parsing fails or partially succeeds, we must never
+ * write raw ---CODE---/---END---/---MARKDOWN--- markers to .md files because
+ * curly braces inside unfenced code blocks cause MDX compilation errors.
+ */
+export function stripResponseMarkers(content) {
+    // Strip both exact markers and common LLM variations (extra dashes, spaces, formatting)
+    return content.replace(/^[`*]*-{2,}\s*(?:MARKDOWN|TYPESCRIPT|PYTHON|CODE|END)\s*-{2,}[`*]*$/gim, '').trim();
+}
+/**
+ * Strip markdown code fences from a code block.
+ * Handles ```language\n...\n```, including nested fences.
+ */
+function stripCodeFences(code) {
+    let result = code;
+    // Remove repeated opening fences (```typescript, ```python, etc.)
+    while (/^```[\w]*\n?/.test(result)) {
+        result = result.replace(/^```[\w]*\n?/, '');
+    }
+    // Remove repeated closing fences
+    while (/\n?```\s*$/.test(result)) {
+        result = result.replace(/\n?```\s*$/, '');
+    }
+    return result;
+}
+/**
+ * Fallback parser: extract documentation and code from a response that has no delimiters.
+ * Looks for markdown prose followed by code fences.
+ */
+function parseFallbackResponse(content) {
+    // Try to split on the first code fence
+    const codeFenceMatch = content.match(/([\s\S]*?)```(\w*)\n([\s\S]*?)```([\s\S]*)/);
+    if (codeFenceMatch) {
+        const markdown = codeFenceMatch[1]?.trim() || content;
+        const firstLang = codeFenceMatch[2]?.toLowerCase() || '';
+        const firstCode = codeFenceMatch[3]?.trim() || '';
+        const rest = codeFenceMatch[4] || '';
+        // Check if there's a second code fence (multi-lang)
+        const secondFenceMatch = rest.match(/```(\w*)\n([\s\S]*?)```/);
+        const secondLang = secondFenceMatch?.[1]?.toLowerCase() || '';
+        const secondCode = secondFenceMatch?.[2]?.trim() || '';
+        // Assign code blocks by detected language
+        const isPythonFirst = firstLang === 'python' || firstLang === 'py';
+        const isPythonSecond = secondLang === 'python' || secondLang === 'py';
+        const typescriptExample = isPythonFirst ? secondCode : firstCode;
+        const pythonExample = isPythonFirst ? firstCode : (isPythonSecond ? secondCode : secondCode);
+        return {
+            markdown,
+            codeExample: typescriptExample || firstCode,
+            typescriptExample: typescriptExample || firstCode,
+            pythonExample
+        };
+    }
+    // No code fences found at all — return everything as markdown
+    return { markdown: content, codeExample: '', typescriptExample: '' };
+}
 function parseDocResponse(content, elementName) {
-    if (!content.includes('---MARKDOWN---')) {
+    const normalized = normalizeDelimiters(content);
+    // Try to extract with delimiters first
+    const markdownMatch = normalized.match(/---MARKDOWN---\s*([\s\S]*?)\s*---CODE---/);
+    const codeMatch = normalized.match(/---CODE---\s*([\s\S]*?)\s*---END---/);
+    if (markdownMatch && codeMatch) {
+        const markdown = markdownMatch[1]?.trim() || '';
+        let codeExample = codeMatch[1]?.trim() || '';
+        codeExample = stripCodeFences(codeExample);
+        return { markdown, codeExample, typescriptExample: codeExample };
+    }
+    // Delimiter-based parsing failed — try fallback
+    const fallback = parseFallbackResponse(content);
+    if (!fallback.markdown && !fallback.codeExample) {
         console.warn(`  Warning: LLM response missing expected format for ${elementName ?? 'unknown'}`);
     }
-    // Extract markdown section
-    const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---CODE---/);
-    const markdown = markdownMatch?.[1]?.trim() || content;
-    // Extract code section
-    const codeMatch = content.match(/---CODE---\s*([\s\S]*?)\s*---END---/);
-    let codeExample = codeMatch?.[1]?.trim() || '';
-    // Clean up code fences if present
-    codeExample = codeExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
-    return { markdown, codeExample, typescriptExample: codeExample };
+    const result = fallback.markdown ? fallback : { markdown: content, codeExample: '', typescriptExample: '' };
+    // Safety net: strip any leaked markers from the final result
+    result.markdown = stripResponseMarkers(result.markdown);
+    if (result.codeExample)
+        result.codeExample = stripResponseMarkers(result.codeExample);
+    if (result.typescriptExample)
+        result.typescriptExample = stripResponseMarkers(result.typescriptExample);
+    return result;
 }
 function parseMultiLangResponse(content, elementName) {
-    if (!content.includes('---MARKDOWN---')) {
+    const normalized = normalizeDelimiters(content);
+    // Try to extract with delimiters first
+    const markdownMatch = normalized.match(/---MARKDOWN---\s*([\s\S]*?)\s*---TYPESCRIPT---/);
+    const tsMatch = normalized.match(/---TYPESCRIPT---\s*([\s\S]*?)\s*---PYTHON---/);
+    const pyMatch = normalized.match(/---PYTHON---\s*([\s\S]*?)\s*---END---/);
+    if (markdownMatch && tsMatch && pyMatch) {
+        const markdown = markdownMatch[1]?.trim() || '';
+        const typescriptExample = stripCodeFences(tsMatch[1]?.trim() || '');
+        const pythonExample = stripCodeFences(pyMatch[1]?.trim() || '');
+        return {
+            markdown,
+            codeExample: typescriptExample,
+            typescriptExample,
+            pythonExample
+        };
+    }
+    // Partial delimiter match — try extracting what we can
+    if (markdownMatch || normalized.includes('---MARKDOWN---')) {
+        let markdown = markdownMatch?.[1]?.trim() || '';
+        let typescriptExample = tsMatch?.[1]?.trim() || '';
+        typescriptExample = stripCodeFences(typescriptExample);
+        let pythonExample = pyMatch?.[1]?.trim() || '';
+        pythonExample = stripCodeFences(pythonExample);
+        // If we have markdown but no code sections, try extracting code from remaining content
+        if (!typescriptExample && !pythonExample) {
+            const afterMarkdown = normalized.split(/---MARKDOWN---/)[1] || '';
+            const fallbackFromRest = parseFallbackResponse(afterMarkdown);
+            typescriptExample = fallbackFromRest.typescriptExample || '';
+            pythonExample = fallbackFromRest.pythonExample || '';
+        }
+        // Safety net: strip any leaked markers
+        markdown = stripResponseMarkers(markdown || content);
+        typescriptExample = stripResponseMarkers(typescriptExample);
+        pythonExample = stripResponseMarkers(pythonExample);
+        return {
+            markdown,
+            codeExample: typescriptExample,
+            typescriptExample,
+            pythonExample
+        };
+    }
+    // No delimiters at all — use fallback parser
+    const fallback = parseFallbackResponse(content);
+    if (!fallback.markdown && !fallback.codeExample) {
         console.warn(`  Warning: LLM response missing expected format for ${elementName ?? 'unknown'}`);
     }
-    // Extract markdown section
-    const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---TYPESCRIPT---/);
-    const markdown = markdownMatch?.[1]?.trim() || '';
-    // Extract TypeScript section
-    const tsMatch = content.match(/---TYPESCRIPT---\s*([\s\S]*?)\s*---PYTHON---/);
-    let typescriptExample = tsMatch?.[1]?.trim() || '';
-    typescriptExample = typescriptExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
-    // Extract Python section
-    const pyMatch = content.match(/---PYTHON---\s*([\s\S]*?)\s*---END---/);
-    let pythonExample = pyMatch?.[1]?.trim() || '';
-    pythonExample = pythonExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
-    // Primary code example is TypeScript (for backwards compat)
-    return {
-        markdown,
-        codeExample: typescriptExample,
-        typescriptExample,
-        pythonExample
-    };
+    const result = fallback.markdown
+        ? fallback
+        : { markdown: content, codeExample: '', typescriptExample: '', pythonExample: '' };
+    // Safety net: strip any leaked markers from the final result
+    result.markdown = stripResponseMarkers(result.markdown);
+    if (result.codeExample)
+        result.codeExample = stripResponseMarkers(result.codeExample);
+    if (result.typescriptExample)
+        result.typescriptExample = stripResponseMarkers(result.typescriptExample);
+    if (result.pythonExample)
+        result.pythonExample = stripResponseMarkers(result.pythonExample);
+    return result;
 }

package/dist/llm/openai-client.js

@@ -64,6 +64,8 @@ export class OpenAICompatibleClient {
         switch (reason) {
             case 'stop':
             case 'end_turn':
+            case null:
+            case undefined:
                 return 'stop';
             case 'length':
             case 'max_tokens':

package/dist/mutation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './mutator.js';
+export * from './runner.js';
+export * from './reporter.js';

package/dist/mutation/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './mutator.js';
+export * from './runner.js';
+export * from './reporter.js';

package/dist/mutation/mutator.d.ts

@@ -0,0 +1,5 @@
+import { Mutant } from './types.js';
+/**
+ * Generate mutations for a source file
+ */
+export declare function generateMutants(filePath: string, maxMutants?: number): Mutant[];

package/dist/mutation/mutator.js

@@ -0,0 +1,101 @@
+import { readFileSync } from 'fs';
+import { createHash } from 'crypto';
+/**
+ * Generate mutations for a source file
+ */
+export function generateMutants(filePath, maxMutants = 100) {
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    const mutants = [];
+    for (let i = 0; i < lines.length && mutants.length < maxMutants; i++) {
+        const line = lines[i];
+        const lineMutants = mutateLine(line, i, filePath);
+        mutants.push(...lineMutants);
+    }
+    return mutants.slice(0, maxMutants);
+}
+/**
+ * Generate mutations for a single line
+ */
+function mutateLine(line, lineNumber, filePath) {
+    const mutants = [];
+    // Return value mutations
+    const returnTrue = line.match(/return\s+true\b/);
+    if (returnTrue) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+true\b/, 'return false'), lineNumber, 'return_value', 'Changed return true to return false'));
+    }
+    const returnFalse = line.match(/return\s+false\b/);
+    if (returnFalse) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+false\b/, 'return true'), lineNumber, 'return_value', 'Changed return false to return true'));
+    }
+    const returnZero = line.match(/return\s+0\b/);
+    if (returnZero) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+0\b/, 'return 1'), lineNumber, 'return_value', 'Changed return 0 to return 1'));
+    }
+    const returnOne = line.match(/return\s+1\b/);
+    if (returnOne) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+1\b/, 'return 0'), lineNumber, 'return_value', 'Changed return 1 to return 0'));
+    }
+    const returnNull = line.match(/return\s+null\b/);
+    if (returnNull) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+null\b/, 'return undefined'), lineNumber, 'return_value', 'Changed return null to return undefined'));
+    }
+    const returnEmptyArr = line.match(/return\s+\[\]/);
+    if (returnEmptyArr) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+\[\]/, 'return [null]'), lineNumber, 'return_value', 'Changed return [] to return [null]'));
+    }
+    const returnEmptyStr = line.match(/return\s+''|return\s+""/);
+    if (returnEmptyStr) {
+        mutants.push(makeMutant(filePath, line, line.replace(/return\s+(?:''|"")/, 'return "mutated"'), lineNumber, 'return_value', 'Changed return empty string to "mutated"'));
+    }
+    // Conditional mutations (avoid JSX, generics, HTML, shift operators)
+    if (line.includes(' > ') && !line.includes('=>') && !/<\w/.test(line) && !/\w>/.test(line)) {
+        mutants.push(makeMutant(filePath, line, line.replace(' > ', ' <= '), lineNumber, 'conditional', 'Flipped > to <='));
+    }
+    if (line.includes(' < ') && !line.includes('=>') && !line.includes('<<') && !/<\w/.test(line)) {
+        mutants.push(makeMutant(filePath, line, line.replace(' < ', ' >= '), lineNumber, 'conditional', 'Flipped < to >='));
+    }
+    if (line.includes(' === ')) {
+        mutants.push(makeMutant(filePath, line, line.replace(' === ', ' !== '), lineNumber, 'conditional', 'Flipped === to !=='));
+    }
+    if (line.includes(' !== ')) {
+        mutants.push(makeMutant(filePath, line, line.replace(' !== ', ' === '), lineNumber, 'conditional', 'Flipped !== to ==='));
+    }
+    // Match == but not === (use regex with negative lookahead/lookbehind)
+    if (/[^=!] == [^=]/.test(` ${line} `)) {
+        mutants.push(makeMutant(filePath, line, line.replace(/ == (?!=)/, ' != '), lineNumber, 'conditional', 'Flipped == to !='));
+    }
+    // Logical operator mutations
+    if (line.includes(' && ')) {
+        mutants.push(makeMutant(filePath, line, line.replace(' && ', ' || '), lineNumber, 'logical_operator', 'Changed && to ||'));
+    }
+    if (line.includes(' || ')) {
+        mutants.push(makeMutant(filePath, line, line.replace(' || ', ' && '), lineNumber, 'logical_operator', 'Changed || to &&'));
+    }
+    // String literal mutations (only for simple cases)
+    const stringMatch = line.match(/'([^']{2,20})'|"([^"]{2,20})"/);
+    if (stringMatch && !line.includes('import') && !line.includes('require')) {
+        const original = stringMatch[0];
+        const mutated = original === `'${stringMatch[1]}'`
+            ? `'MUTATED_${stringMatch[1]}'`
+            : `"MUTATED_${stringMatch[2]}"`;
+        mutants.push(makeMutant(filePath, line, line.replace(original, mutated), lineNumber, 'string_literal', `Changed string literal ${original}`));
+    }
+    return mutants;
+}
+function makeMutant(filePath, originalCode, mutatedCode, lineNumber, type, description) {
+    const id = createHash('sha256')
+        .update(`${filePath}:${lineNumber}:${type}:${description}`)
+        .digest('hex')
+        .slice(0, 12);
+    return {
+        id,
+        filePath,
+        originalCode,
+        mutatedCode,
+        startLine: lineNumber,
+        endLine: lineNumber,
+        type,
+        description,
+    };
+}

package/dist/mutation/reporter.d.ts

@@ -0,0 +1,14 @@
+import { MutantResult, MutationReport } from './types.js';
+/**
+ * Print mutation testing report to terminal
+ */
+export declare function printMutationReport(report: MutationReport): void;
+/**
+ * Format report as JSON
+ */
+export declare function formatMutationJson(report: MutationReport): string;
+/**
+ * Compute mutation score from a list of mutant results.
+ * Score = killed / total * 100. Returns 0 when there are no mutants.
+ */
+export declare function computeMutationScore(results: MutantResult[]): number;

package/dist/mutation/reporter.js

@@ -0,0 +1,66 @@
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+/**
+ * Print mutation testing report to terminal
+ */
+export function printMutationReport(report) {
+    console.log(`\n${BOLD}Documentation Mutation Testing Report${RESET}\n`);
+    // Score bar
+    const color = report.mutationScore >= 70 ? GREEN : report.mutationScore >= 40 ? YELLOW : RED;
+    const barWidth = 30;
+    const filled = Math.round((report.mutationScore / 100) * barWidth);
+    const empty = barWidth - filled;
+    console.log(`  Mutation Score: ${color}[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${report.mutationScore.toFixed(1)}%${RESET}`);
+    console.log(`  Killed: ${GREEN}${report.killed}${RESET} | Survived: ${RED}${report.survived}${RESET} | Errors: ${DIM}${report.errors}${RESET} | Timeouts: ${DIM}${report.timeouts}${RESET}`);
+    console.log(`  Total mutants: ${report.totalMutants}`);
+    console.log('');
+    // Per-file breakdown
+    if (report.files.length > 0) {
+        console.log(`${BOLD}  Per-file Breakdown${RESET}`);
+        console.log(`  ${'File'.padEnd(45)} ${'Mutants'.padStart(8)} ${'Killed'.padStart(8)} ${'Survived'.padStart(10)} ${'Score'.padStart(8)}`);
+        console.log(`  ${'─'.repeat(45)} ${'─'.repeat(8)} ${'─'.repeat(8)} ${'─'.repeat(10)} ${'─'.repeat(8)}`);
+        for (const file of report.files) {
+            const shortPath = file.filePath.length > 44
+                ? '...' + file.filePath.slice(-41)
+                : file.filePath;
+            const fileColor = file.score >= 70 ? GREEN : file.score >= 40 ? YELLOW : RED;
+            console.log(`  ${shortPath.padEnd(45)} ${String(file.mutants).padStart(8)} ${String(file.killed).padStart(8)} ${String(file.survived).padStart(10)} ${fileColor}${(file.score.toFixed(0) + '%').padStart(8)}${RESET}`);
+        }
+        console.log('');
+    }
+    // Dangerous survivors
+    if (report.survivors.length > 0) {
+        const shown = report.survivors.slice(0, 10);
+        console.log(`${RED}${BOLD}  Dangerous Survivors${RESET} (${report.survivors.length} total)`);
+        console.log(`  These mutations changed behavior but no doc example caught them:\n`);
+        for (const s of shown) {
+            console.log(`    ${RED}SURVIVED${RESET} ${s.mutant.filePath}:${s.mutant.startLine + 1}`);
+            console.log(`      ${DIM}${s.mutant.description}${RESET}`);
+            console.log(`      ${DIM}${s.mutant.originalCode.trim()} → ${s.mutant.mutatedCode.trim()}${RESET}`);
+            console.log('');
+        }
+        if (report.survivors.length > 10) {
+            console.log(`    ${DIM}... and ${report.survivors.length - 10} more${RESET}`);
+        }
+    }
+}
+/**
+ * Format report as JSON
+ */
+export function formatMutationJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+/**
+ * Compute mutation score from a list of mutant results.
+ * Score = killed / total * 100. Returns 0 when there are no mutants.
+ */
+export function computeMutationScore(results) {
+    if (results.length === 0)
+        return 0;
+    const killed = results.filter(r => r.status === 'killed').length;
+    return (killed / results.length) * 100;
+}

package/dist/mutation/runner.d.ts

@@ -0,0 +1,9 @@
+import { Mutant, MutantResult } from './types.js';
+/**
+ * Run doc examples against a mutated source file and check if the mutation is caught
+ */
+export declare function runMutant(mutant: Mutant, docExamples: Array<{
+    code: string;
+    language: string;
+    filePath: string;
+}>, timeout?: number): MutantResult;

package/dist/mutation/runner.js

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, basename, dirname } from 'path';
+import { tmpdir } from 'os';
+import { spawnSync } from 'child_process';
+/**
+ * Run doc examples against a mutated source file and check if the mutation is caught
+ */
+export function runMutant(mutant, docExamples, timeout = 10000) {
+    // Create temp directory with mutated file
+    const tmpDir = join(tmpdir(), `skrypt-mutant-${mutant.id}`);
+    try {
+        mkdirSync(tmpDir, { recursive: true });
+        // Read original file, apply mutation, write to temp
+        const originalContent = readFileSync(mutant.filePath, 'utf-8');
+        const lines = originalContent.split('\n');
+        lines[mutant.startLine] = mutant.mutatedCode;
+        const mutatedContent = lines.join('\n');
+        const tempFile = join(tmpDir, basename(mutant.filePath));
+        writeFileSync(tempFile, mutatedContent);
+        // Run each doc example that references symbols in the mutated file
+        for (const example of docExamples) {
+            const exampleFile = join(tmpDir, `example_${basename(example.filePath)}`);
+            writeFileSync(exampleFile, example.code);
+            const isTS = example.language === 'typescript' || example.language === 'javascript';
+            const isPy = example.language === 'python';
+            let result;
+            if (isTS) {
+                result = spawnSync('node', ['--input-type=module', '-e', example.code], {
+                    cwd: tmpDir,
+                    timeout,
+                    encoding: 'utf-8',
+                    env: { ...process.env, NODE_PATH: dirname(mutant.filePath) },
+                });
+            }
+            else if (isPy) {
+                result = spawnSync('python3', ['-c', example.code], {
+                    cwd: tmpDir,
+                    timeout,
+                    encoding: 'utf-8',
+                });
+            }
+            else {
+                continue;
+            }
+            // If example fails, mutation was caught (killed)
+            if (result.status !== 0) {
+                return {
+                    mutant,
+                    status: 'killed',
+                    failedExample: example.filePath,
+                };
+            }
+        }
+        // All examples still pass = mutation survived (bad)
+        return { mutant, status: 'survived' };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('TIMEOUT') || message.includes('timed out')) {
+            return { mutant, status: 'timeout' };
+        }
+        return { mutant, status: 'error', error: message };
+    }
+    finally {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { /* ignore cleanup errors */ }
+    }
+}