skrypt-ai 0.7.0 → 0.8.0

package/dist/commands/generate.js

@@ -1,739 +0,0 @@
-import { Command } from 'commander';
-import { existsSync, copyFileSync, mkdirSync, readFileSync, rmSync } from 'fs';
-import { resolve, basename, dirname, join } from 'path';
-import { loadConfig, validateConfig, checkApiKey, resolveSourceEntries } from '../config/index.js';
-import { DEFAULT_MODELS } from '../config/types.js';
-import { scanDirectory } from '../scanner/index.js';
-import { createLLMClient } from '../llm/index.js';
-import { generateForElements, groupDocsByFile, writeDocsToDirectory, writeDocsByTopic, writeLlmsTxt } from '../generator/index.js';
-import { showSecurityNotice } from '../auth/notices.js';
-import { requirePro } from '../auth/index.js';
-import { runQA, printQAReport, fixQAIssues, printFixReport } from '../qa/index.js';
-import { extractDependencyIds, isChubInstalled, fetchContextHubDocs, exportToContextHub } from '../context-hub/index.js';
-import { discoverOrgRepos, cloneRepoToTemp } from '../github/org-discovery.js';
-import { extractSnippets, findDocFiles, runLocally, loadEnvFile } from '../testing/index.js';
-import { writeManifest, buildManifestEntries } from '../refresh/manifest.js';
-import { planSmartStructure, generateWithStructure } from '../structure/index.js';
-import * as readline from 'readline';
-/**
- * Parse source arguments with optional labels.
- * e.g. "./api:API" → { path: "./api", label: "API" }
- * e.g. "./src" → { path: "./src" }
- */
-export function parseSourceArgs(args) {
-    return args.map(arg => {
-        const colonIdx = arg.lastIndexOf(':');
-        // Only treat as label separator if colon is not part of a path (e.g. C:\)
-        if (colonIdx > 1 && !arg.substring(0, colonIdx).endsWith('\\')) {
-            return {
-                path: arg.substring(0, colonIdx),
-                label: arg.substring(colonIdx + 1),
-            };
-        }
-        return { path: arg };
-    });
-}
-/**
- * Read .skryptignore patterns from source directory
- */
-function readIgnorePatterns(sourcePath) {
-    const ignorePath = join(sourcePath, '.skryptignore');
-    if (!existsSync(ignorePath))
-        return [];
-    const content = readFileSync(ignorePath, 'utf-8');
-    return content
-        .split('\n')
-        .map(line => line.trim())
-        .filter(line => line && !line.startsWith('#'));
-}
-/**
- * Auto-detect OpenAPI spec file in source directory
- */
-function findOpenAPISpec(sourcePath) {
-    const candidates = [
-        'openapi.json',
-        'openapi.yaml',
-        'openapi.yml',
-        'swagger.json',
-        'swagger.yaml',
-        'swagger.yml',
-        'api.json',
-        'api.yaml',
-        'api.yml',
-    ];
-    for (const name of candidates) {
-        const specPath = join(sourcePath, name);
-        if (existsSync(specPath)) {
-            return specPath;
-        }
-    }
-    // Check common subdirectories
-    const subdirs = ['docs', 'api', 'spec', '.'];
-    for (const subdir of subdirs) {
-        for (const name of candidates) {
-            const specPath = join(sourcePath, subdir, name);
-            if (existsSync(specPath)) {
-                return specPath;
-            }
-        }
-    }
-    return null;
-}
-/**
- * Check if element should be excluded based on patterns
- */
-function shouldExcludeElement(element, patterns) {
-    for (const pattern of patterns) {
-        // Match by name
-        if (pattern.startsWith('name:')) {
-            const namePattern = pattern.slice(5);
-            if (element.name === namePattern) {
-                return true;
-            }
-            // Only use regex if the pattern contains regex metacharacters
-            // Reject patterns with nested quantifiers to prevent catastrophic backtracking (ReDoS)
-            if (/[*+?{}()|[\]\\^$.]/.test(namePattern)) {
-                if (/(\+|\*|\?)\{|\(\?[^:)]|\(\.[*+].*\)\+|\([^)]*[+*][^)]*\)[+*]/.test(namePattern)) {
-                    continue; // Skip patterns prone to catastrophic backtracking
-                }
-                try {
-                    if (new RegExp(namePattern).test(element.name))
-                        return true;
-                }
-                catch {
-                    // Invalid regex — treat as literal match (already checked above)
-                }
-            }
-        }
-        // Match by file path
-        else if (pattern.includes('/') || pattern.includes('*')) {
-            const filePath = element.filePath;
-            if (pattern.includes('**')) {
-                const parts = pattern.split('**');
-                const prefixMatch = !parts[0] || filePath.includes(parts[0].replace(/^\//, ''));
-                const suffixMatch = !parts[1] || filePath.includes(parts[1].replace(/^\//, ''));
-                if (prefixMatch && suffixMatch)
-                    return true;
-            }
-            else if (filePath.includes(pattern.replace(/\*/g, ''))) {
-                return true;
-            }
-        }
-        // Match by exact name
-        else if (element.name === pattern) {
-            return true;
-        }
-    }
-    return false;
-}
-export const generateCommand = new Command('generate')
-    .description('Generate documentation with code examples')
-    .argument('[sources...]', 'Source directories to scan (use dir:Label for labels)')
-    .option('-o, --output <dir>', 'Output directory')
-    .option('-c, --config <file>', 'Config file path')
-    .option('--provider <name>', 'LLM provider (deepseek, openai, anthropic, google, ollama, openrouter)')
-    .option('--model <name>', 'LLM model name')
-    .option('--base-url <url>', 'Custom API base URL (for Ollama or proxies)')
-    .option('--dry-run', 'Scan only, do not generate docs')
-    .option('--multi-lang', 'Generate TypeScript + Python examples')
-    .option('--by-topic', 'Organize output by topic instead of file')
-    .option('--openapi <file>', 'Include OpenAPI spec file for API Playground')
-    .option('--public-only', 'Only document exported/public APIs')
-    .option('--exclude <patterns...>', 'Exclude patterns (files, names, or name:pattern)')
-    .option('--llms-txt', 'Generate llms.txt for Answer Engine Optimization (AEO)')
-    .option('--project-name <name>', 'Project name for llms.txt header')
-    .option('--org <name>', 'GitHub organization to discover repos from')
-    .option('--repos <list>', 'Comma-separated list of repos to include (with --org)')
-    .option('--exclude-repos <list>', 'Comma-separated list of repos to exclude (with --org)')
-    .option('--verify', 'Verify generated code examples by running them (Pro)')
-    .option('--env-file <file>', 'Load environment variables for code verification')
-    .option('--smart-structure', 'Organize docs by user journey instead of file structure (Pro)')
-    .option('--max-verify-iterations <n>', 'Max re-generation attempts for failing snippets', '2')
-    .action(async (sources = [], options) => {
-    try {
-        const startTime = Date.now();
-        // Require at least one source or --org
-        if (sources.length === 0 && !options.org) {
-            console.error('Error: At least one source directory is required (or use --org)');
-            process.exit(1);
-        }
-        // Load config (file or defaults)
-        const config = loadConfig(options.config);
-        // CLI flags override config — first source is used for single-source compat
-        if (sources.length > 0)
-            config.source.path = sources[0];
-        if (options.output)
-            config.output.path = options.output;
-        if (options.provider) {
-            const validProviders = ['deepseek', 'openai', 'anthropic', 'google', 'ollama', 'openrouter'];
-            if (!validProviders.includes(options.provider)) {
-                console.error(`Error: Unknown provider "${options.provider}". Valid: ${validProviders.join(', ')}`);
-                process.exit(1);
-            }
-            config.llm.provider = options.provider;
-            // Use provider's default model unless explicitly specified
-            if (!options.model) {
-                config.llm.model = DEFAULT_MODELS[config.llm.provider];
-            }
-        }
-        if (options.model)
-            config.llm.model = options.model;
-        if (options.baseUrl)
-            config.llm.baseUrl = options.baseUrl;
-        // Validate
-        const errors = validateConfig(config);
-        if (errors.length > 0) {
-            console.error('Config errors:');
-            errors.forEach(e => console.error(`  - ${e}`));
-            process.exit(1);
-        }
-        // Check for API key (not needed for Ollama or dry-run)
-        if (!options.dryRun) {
-            const { ok, envKey } = checkApiKey(config.llm.provider);
-            if (!ok && envKey) {
-                console.error(`Error: ${envKey} environment variable required for ${config.llm.provider}`);
-                process.exit(1);
-            }
-        }
-        // Pro-gated flags
-        if (options.verify) {
-            if (!await requirePro('generate --verify')) {
-                process.exit(1);
-            }
-        }
-        if (options.smartStructure) {
-            if (!await requirePro('generate --smart-structure')) {
-                process.exit(1);
-            }
-        }
-        // First-run security notice
-        showSecurityNotice();
-        console.log('skrypt generate');
-        if (options.org) {
-            console.log(`  source:   org:${options.org}`);
-        }
-        else if (sources.length > 1) {
-            console.log(`  sources:  ${sources.join(', ')}`);
-        }
-        else {
-            console.log(`  source:   ${config.source.path}`);
-        }
-        console.log(`  output:   ${config.output.path}`);
-        console.log(`  provider: ${config.llm.provider}`);
-        console.log(`  model:    ${config.llm.model}`);
-        if (config.llm.baseUrl) {
-            console.log(`  base url: ${config.llm.baseUrl}`);
-        }
-        // Routing transparency
-        const providerEnvKeys = {
-            openai: 'OPENAI_API_KEY',
-            anthropic: 'ANTHROPIC_API_KEY',
-            google: 'GOOGLE_API_KEY',
-            deepseek: 'DEEPSEEK_API_KEY',
-        };
-        const providerKey = providerEnvKeys[config.llm.provider];
-        if (providerKey && process.env[providerKey]) {
-            console.log(`  routing:  direct to ${config.llm.provider} (BYOK — your key never touches Skrypt)`);
-        }
-        else if (config.llm.provider !== 'ollama') {
-            console.log('  routing:  via Skrypt API proxy');
-        }
-        console.log('');
-        // Resolve source entries: CLI args, --org, or config file
-        let sourceEntries;
-        const tempDirs = [];
-        if (options.org) {
-            // GitHub org discovery mode
-            const token = process.env.GITHUB_TOKEN;
-            if (!token) {
-                console.error('Error: GITHUB_TOKEN environment variable required for --org');
-                process.exit(1);
-            }
-            console.log(`Discovering repos in org "${options.org}"...`);
-            const repoWhitelist = options.repos ? options.repos.split(',').map(r => r.trim()) : undefined;
-            const repoBlacklist = options.excludeRepos ? options.excludeRepos.split(',').map(r => r.trim()) : undefined;
-            let discoveredRepos = await discoverOrgRepos(options.org, token);
-            if (repoWhitelist) {
-                discoveredRepos = discoveredRepos.filter(r => repoWhitelist.includes(r.name));
-            }
-            if (repoBlacklist) {
-                discoveredRepos = discoveredRepos.filter(r => !repoBlacklist.includes(r.name));
-            }
-            console.log(`  Found ${discoveredRepos.length} repos`);
-            sourceEntries = [];
-            for (const repo of discoveredRepos) {
-                console.log(`  Cloning ${repo.full_name}...`);
-                const tempDir = await cloneRepoToTemp(repo, token);
-                tempDirs.push(tempDir);
-                sourceEntries.push({
-                    path: tempDir,
-                    label: repo.name,
-                    include: config.source.include,
-                    exclude: config.source.exclude,
-                });
-            }
-        }
-        else if (sources.length > 1) {
-            // Multiple CLI args
-            sourceEntries = parseSourceArgs(sources);
-        }
-        else {
-            // Single source or config file sources
-            sourceEntries = resolveSourceEntries(config);
-        }
-        const isMultiSource = sourceEntries.length > 1 || sourceEntries.some(s => s.label);
-        // Check all source paths exist
-        for (const entry of sourceEntries) {
-            const sourcePath = resolve(entry.path);
-            if (!existsSync(sourcePath)) {
-                console.error(`Error: Source directory not found: ${sourcePath}`);
-                process.exit(1);
-            }
-        }
-        // Step 1: Scan source code from all sources
-        console.log('Step 1: Scanning source code...');
-        let allElements = [];
-        let totalFiles = 0;
-        const allScanErrors = [];
-        try {
-            for (const entry of sourceEntries) {
-                const sourcePath = resolve(entry.path);
-                if (isMultiSource) {
-                    console.log(`\n  Scanning ${entry.label || entry.path}...`);
-                }
-                const scanResult = await scanDirectory(sourcePath, {
-                    include: entry.include || config.source.include,
-                    exclude: entry.exclude || config.source.exclude,
-                    onProgress: (current, total, file) => {
-                        process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
-                    }
-                });
-                console.log('');
-                if (scanResult.errors.length > 0) {
-                    allScanErrors.push(...scanResult.errors);
-                }
-                totalFiles += scanResult.files.length;
-                // Tag elements with source metadata
-                for (const file of scanResult.files) {
-                    for (const el of file.elements) {
-                        if (entry.label) {
-                            el.sourceLabel = entry.label;
-                        }
-                        el.sourceRoot = sourcePath;
-                        allElements.push(el);
-                    }
-                }
-            }
-            if (allScanErrors.length > 0) {
-                console.log('\n  Scan warnings:');
-                allScanErrors.slice(0, 5).forEach(e => console.log(`    - ${e}`));
-                if (allScanErrors.length > 5) {
-                    console.log(`    ... and ${allScanErrors.length - 5} more`);
-                }
-            }
-            console.log(`\n  Found ${allElements.length} API elements in ${totalFiles} files`);
-            if (allElements.length === 0) {
-                console.log('  No API elements found. Nothing to generate.');
-                return;
-            }
-            // Apply privacy filters
-            const initialCount = allElements.length;
-            // 1. --public-only: filter to exported/public APIs only
-            if (options.publicOnly) {
-                allElements = allElements.filter(el => el.isExported === true || el.isPublic === true);
-                console.log(`  --public-only: filtered to ${allElements.length} exported APIs`);
-            }
-            // 2. Load .skryptignore patterns from all source dirs
-            const ignorePatterns = [];
-            for (const entry of sourceEntries) {
-                ignorePatterns.push(...readIgnorePatterns(resolve(entry.path)));
-            }
-            if (ignorePatterns.length > 0) {
-                console.log(`  .skryptignore: loaded ${ignorePatterns.length} patterns`);
-            }
-            // 3. Combine with --exclude patterns
-            const excludePatterns = [...ignorePatterns, ...(options.exclude || [])];
-            if (excludePatterns.length > 0) {
-                allElements = allElements.filter(el => !shouldExcludeElement(el, excludePatterns));
-                if (options.exclude?.length) {
-                    console.log(`  --exclude: applied ${options.exclude.length} additional patterns`);
-                }
-            }
-            if (initialCount !== allElements.length) {
-                console.log(`  Filtered: ${initialCount} -> ${allElements.length} elements`);
-            }
-            // Show summary by kind
-            const byKind = {};
-            for (const el of allElements) {
-                byKind[el.kind] = (byKind[el.kind] || 0) + 1;
-            }
-            const pluralize = (word, count) => {
-                if (count === 1)
-                    return word;
-                if (word === 'class')
-                    return 'classes';
-                return word + 's';
-            };
-            console.log('  ' + Object.entries(byKind).map(([k, v]) => `${v} ${pluralize(k, v)}`).join(', '));
-            // Dry run - stop here
-            if (options.dryRun) {
-                console.log('\n[dry run - stopping before generation]');
-                return;
-            }
-            // Use first source path as the primary source for context/compat
-            const primarySourcePath = resolve(sourceEntries[0].path);
-            // Auto-read project context from README for richer doc generation
-            let projectContext;
-            const readmeCandidates = ['README.md', 'README.mdx', 'readme.md', 'README.rst', 'README.txt'];
-            for (const candidate of readmeCandidates) {
-                const readmePath = join(primarySourcePath, candidate);
-                if (existsSync(readmePath)) {
-                    try {
-                        const raw = readFileSync(readmePath, 'utf-8');
-                        // Take the first ~1500 chars (intro/description section, not the whole file)
-                        projectContext = raw.slice(0, 1500);
-                        console.log(`  Project context: loaded from ${candidate}`);
-                    }
-                    catch {
-                        // Skip if unreadable
-                    }
-                    break;
-                }
-            }
-            // Also check parent directory (common for monorepos where source is a subdirectory)
-            if (!projectContext) {
-                const parentReadme = join(primarySourcePath, '..', 'README.md');
-                if (existsSync(parentReadme)) {
-                    try {
-                        projectContext = readFileSync(parentReadme, 'utf-8').slice(0, 1500);
-                        console.log('  Project context: loaded from parent README.md');
-                    }
-                    catch {
-                        // Skip
-                    }
-                }
-            }
-            // Context Hub enrichment: fetch third-party API docs if chub is installed
-            let externalContext;
-            const allImports = [];
-            for (const el of allElements) {
-                if (el.imports?.length) {
-                    allImports.push(...el.imports);
-                }
-            }
-            const chubIds = extractDependencyIds(allImports);
-            if (chubIds.length > 0 && isChubInstalled()) {
-                console.log(`\n  Context Hub: fetching docs for ${chubIds.length} dependencies...`);
-                externalContext = fetchContextHubDocs(chubIds);
-                if (externalContext.size > 0) {
-                    console.log(`  Context Hub: enriching with ${externalContext.size} API references`);
-                }
-            }
-            // Step 2: Generate docs
-            console.log('\nStep 2: Generating documentation...');
-            const client = createLLMClient({
-                provider: config.llm.provider,
-                model: config.llm.model,
-                baseUrl: config.llm.baseUrl
-            });
-            let lastElement = '';
-            const multiLanguage = options.multiLang ?? false;
-            if (multiLanguage) {
-                console.log('  mode: multi-language (TypeScript + Python)');
-            }
-            const genOptions = {
-                multiLanguage,
-                externalContext,
-                projectContext,
-                onProgress: (progress) => {
-                    if (progress.element !== lastElement) {
-                        if (lastElement)
-                            console.log('');
-                        lastElement = progress.element;
-                    }
-                    process.stdout.write(`\r  [${progress.current}/${progress.total}] ${progress.element}: ${progress.status}`.padEnd(80));
-                }
-            };
-            // Step 3: Write output
-            const outputPath = resolve(config.output.path);
-            let filesWritten;
-            let totalDocs;
-            let docs;
-            let errorCount;
-            if (options.smartStructure) {
-                // Smart structure: LLM-planned page organization
-                console.log('  mode: smart-structure (user-journey organization)');
-                console.log('\n  Planning documentation structure...');
-                const structure = await planSmartStructure(allElements, client);
-                console.log(`  Planned ${structure.pages.length} page(s)`);
-                for (const page of structure.pages) {
-                    console.log(`    ${page.category}/${page.slug}: ${page.elements.length} elements`);
-                }
-                console.log('\nStep 3: Generating & writing structured documentation...');
-                const result = await generateWithStructure(structure, client, outputPath, genOptions);
-                filesWritten = result.filesWritten;
-                totalDocs = result.totalDocs;
-                docs = result.docs;
-                errorCount = docs.filter(d => d.error).length;
-            }
-            else {
-                docs = await generateForElements(allElements, client, genOptions);
-                console.log('\n');
-                console.log('Step 3: Writing documentation...');
-                if (options.byTopic) {
-                    console.log('  mode: by-topic (grouped by concept)');
-                    const result = await writeDocsByTopic(docs, outputPath);
-                    filesWritten = result.filesWritten;
-                    totalDocs = result.totalDocs;
-                    console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
-                }
-                else if (isMultiSource) {
-                    // Multi-source: write docs namespaced by source label
-                    filesWritten = 0;
-                    totalDocs = 0;
-                    // Group docs by source label
-                    const bySource = new Map();
-                    for (const doc of docs) {
-                        const label = doc.element.sourceLabel || '_default';
-                        if (!bySource.has(label))
-                            bySource.set(label, []);
-                        bySource.get(label).push(doc);
-                    }
-                    for (const [label, sourceDocs] of bySource) {
-                        const fileResults = groupDocsByFile(sourceDocs);
-                        const sourceOutputDir = label === '_default' ? outputPath : join(outputPath, label.toLowerCase());
-                        const sourceRoot = sourceDocs[0]?.element.sourceRoot || primarySourcePath;
-                        const result = await writeDocsToDirectory(fileResults, sourceOutputDir, sourceRoot);
-                        filesWritten += result.filesWritten;
-                        totalDocs += result.totalDocs;
-                        if (label !== '_default') {
-                            console.log(`  ${label}: ${result.filesWritten} files`);
-                        }
-                    }
-                }
-                else {
-                    // Default: file-based output (single source)
-                    const fileResults = groupDocsByFile(docs);
-                    const result = await writeDocsToDirectory(fileResults, outputPath, primarySourcePath);
-                    filesWritten = result.filesWritten;
-                    totalDocs = result.totalDocs;
-                }
-                errorCount = docs.filter(d => d.error).length;
-            }
-            const duration = Math.round((Date.now() - startTime) / 1000);
-            console.log(`\n  Wrote ${filesWritten} documentation files to ${outputPath}`);
-            // Copy OpenAPI spec (provided or auto-detected)
-            let specPath = options.openapi ? resolve(options.openapi) : null;
-            // Auto-detect if not provided
-            if (!specPath) {
-                const detected = findOpenAPISpec(primarySourcePath);
-                if (detected) {
-                    specPath = detected;
-                    console.log(`\n  Auto-detected OpenAPI spec: ${basename(detected)}`);
-                }
-            }
-            if (specPath) {
-                if (existsSync(specPath)) {
-                    const specFilename = basename(specPath);
-                    const contentDir = dirname(outputPath);
-                    const destPath = resolve(contentDir, specFilename);
-                    mkdirSync(dirname(destPath), { recursive: true });
-                    copyFileSync(specPath, destPath);
-                    console.log(`  Copied OpenAPI spec: ${specFilename} -> ${destPath}`);
-                    console.log('  API Playground will be available at /reference');
-                }
-                else if (options.openapi) {
-                    console.log(`\n  Warning: OpenAPI spec not found: ${specPath}`);
-                }
-            }
-            // Always generate llms.txt for AEO (Answer Engine Optimization)
-            await writeLlmsTxt(docs, outputPath, {
-                projectName: options.projectName,
-                description: `API documentation for ${options.projectName || basename(primarySourcePath)}`
-            });
-            console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
-            // Step 4: Verify code examples (if --verify)
-            if (options.verify) {
-                console.log('\nStep 4: Verifying code examples...');
-                let verifyEnvVars = {};
-                if (options.envFile) {
-                    try {
-                        verifyEnvVars = loadEnvFile(resolve(options.envFile));
-                        console.log(`  Loaded ${Object.keys(verifyEnvVars).length} env var(s) from ${options.envFile}`);
-                    }
-                    catch {
-                        console.log(`  Warning: Could not load env file: ${options.envFile}`);
-                    }
-                }
-                const verifyConfig = {
-                    timeout: 15000,
-                    envVars: verifyEnvVars,
-                    installDeps: true,
-                };
-                const maxIterations = Math.max(1, parseInt(options.maxVerifyIterations ?? '2', 10) || 2);
-                let failedCount = 0;
-                let passedCount = 0;
-                let skippedCount = 0;
-                for (let iteration = 1; iteration <= maxIterations; iteration++) {
-                    const docFiles = findDocFiles(outputPath);
-                    const allSnippets = docFiles.flatMap(f => extractSnippets(f));
-                    if (allSnippets.length === 0) {
-                        console.log('  No code snippets found to verify');
-                        break;
-                    }
-                    if (iteration === 1) {
-                        console.log(`  Found ${allSnippets.length} code snippet(s) to verify`);
-                    }
-                    else {
-                        console.log(`\n  Retry ${iteration}/${maxIterations}: re-verifying ${allSnippets.length} snippet(s)...`);
-                    }
-                    failedCount = 0;
-                    passedCount = 0;
-                    skippedCount = 0;
-                    const failedSnippets = [];
-                    const snippetErrors = new Map();
-                    for (const snippet of allSnippets) {
-                        const result = await runLocally(snippet, verifyConfig);
-                        if (result.status === 'pass') {
-                            passedCount++;
-                        }
-                        else if (result.status === 'skip') {
-                            skippedCount++;
-                        }
-                        else {
-                            failedCount++;
-                            failedSnippets.push(snippet);
-                            const errorMsg = result.stderr?.trim().split('\n').slice(0, 5).join('\n') || `Exit code: ${result.exitCode}`;
-                            snippetErrors.set(snippet.filePath + ':' + snippet.lineNumber, errorMsg);
-                            console.log(`  \x1b[31m✗\x1b[0m ${snippet.filePath}:${snippet.lineNumber} [${snippet.language}]`);
-                            if (result.stderr) {
-                                console.log(`    ${result.stderr.trim().split('\n')[0]?.slice(0, 80)}`);
-                            }
-                        }
-                    }
-                    // If all passed or last iteration, stop
-                    if (failedCount === 0 || iteration === maxIterations) {
-                        break;
-                    }
-                    // Re-generate failing docs by re-running generation for elements whose docs had failing snippets
-                    console.log(`\n  Re-generating ${failedSnippets.length} failing snippet(s)...`);
-                    const failedFiles = [...new Set(failedSnippets.map(s => s.filePath))];
-                    for (const failedFile of failedFiles) {
-                        // Find elements that map to this doc file
-                        const fileSnippets = failedSnippets.filter(s => s.filePath === failedFile);
-                        const matchingElements = allElements.filter(el => fileSnippets.some(s => {
-                            // Match element name in the snippet's surrounding code or filename
-                            const elNameLower = el.name.toLowerCase();
-                            return s.code.toLowerCase().includes(elNameLower) ||
-                                failedFile.toLowerCase().includes(elNameLower);
-                        }));
-                        if (matchingElements.length > 0) {
-                            // Build error context map: element name → error message
-                            const previousErrors = new Map();
-                            for (const snippet of fileSnippets) {
-                                const errKey = snippet.filePath + ':' + snippet.lineNumber;
-                                const errMsg = snippetErrors.get(errKey);
-                                if (errMsg) {
-                                    // Map snippet back to element name
-                                    const matchedEl = matchingElements.find(el => snippet.code.toLowerCase().includes(el.name.toLowerCase()));
-                                    if (matchedEl) {
-                                        previousErrors.set(matchedEl.name, errMsg);
-                                    }
-                                }
-                            }
-                            const reDocs = await generateForElements(matchingElements, client, {
-                                ...genOptions,
-                                verify: true,
-                                previousErrors,
-                                onProgress: (p) => {
-                                    process.stdout.write(`\r  Re-generating: ${p.element} ${p.status}`.padEnd(80));
-                                },
-                            });
-                            console.log('');
-                            // Re-write the doc file with updated content
-                            const fileResults = groupDocsByFile(reDocs);
-                            await writeDocsToDirectory(fileResults, dirname(failedFile), primarySourcePath);
-                        }
-                    }
-                }
-                if (failedCount + passedCount + skippedCount > 0) {
-                    console.log(`\n  Verification: ${passedCount} passed, ${failedCount} failed, ${skippedCount} skipped`);
-                }
-            }
-            // Write manifest for staleness detection
-            try {
-                const manifestEntries = buildManifestEntries(allElements, outputPath);
-                writeManifest(outputPath, manifestEntries);
-            }
-            catch {
-                // Non-fatal — manifest is optional
-            }
-            // Step 5: Embedded QA (auto-fix then check)
-            console.log(`\nStep ${options.verify ? '5' : '4'}: Running QA checks...`);
-            const fixReport = fixQAIssues(outputPath);
-            printFixReport(fixReport);
-            const qaReport = runQA(outputPath);
-            printQAReport(qaReport);
-            // Context Hub export prompt (TTY only — skip in CI/piped mode)
-            if (process.stdin.isTTY) {
-                console.log('');
-                console.log('  Context Hub: Make your docs discoverable by AI coding agents.');
-                console.log('  Context Hub is a curated registry by Andrew Ng (7K+ stars)');
-                console.log('  https://github.com/andrewyng/context-hub');
-                console.log('');
-                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-                const answer = await new Promise((resolve) => {
-                    rl.question('  Export for Context Hub? (y/N) ', (ans) => {
-                        rl.close();
-                        resolve(ans.trim().toLowerCase());
-                    });
-                });
-                if (answer === 'y' || answer === 'yes') {
-                    const languages = multiLanguage ? ['typescript', 'python'] : ['typescript'];
-                    const projName = options.projectName || basename(primarySourcePath);
-                    const result = exportToContextHub(docs, outputPath, {
-                        projectName: projName,
-                        languages,
-                        description: `API documentation for ${projName}`,
-                    });
-                    console.log(`\n  Exported ${result.filesWritten} files to ${result.outputDir}`);
-                    console.log('  See context-hub/README.md for submission instructions');
-                }
-            }
-            console.log('\n=== Summary ===');
-            console.log(`  Total elements: ${totalDocs}`);
-            console.log(`  Generated:      ${totalDocs - errorCount}`);
-            if (errorCount > 0) {
-                console.log(`  Errors:         ${errorCount}`);
-            }
-            console.log(`  Duration:       ${duration}s`);
-            console.log(`  Output:         ${outputPath}`);
-            if (errorCount > 0) {
-                console.log('\n  Elements with errors:');
-                docs.filter(d => d.error).slice(0, 10).forEach(d => {
-                    console.log(`    - ${d.element.name}: ${d.error?.slice(0, 50)}`);
-                });
-                if (errorCount > 10) {
-                    console.log(`    ... and ${errorCount - 10} more`);
-                }
-            }
-            console.log('\nDone!');
-        }
-        finally {
-            // Clean up temp directories from --org clones
-            for (const dir of tempDirs) {
-                try {
-                    rmSync(dir, { recursive: true, force: true });
-                }
-                catch {
-                    // Ignore cleanup errors
-                }
-            }
-        }
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`Error: ${message}`);
-        process.exit(1);
-    }
-});