skrypt-ai 0.5.0 → 0.6.1

package/dist/commands/watch.js

@@ -7,6 +7,7 @@ import { DEFAULT_MODELS } from '../config/types.js';
 import { scanDirectory } from '../scanner/index.js';
 import { createLLMClient } from '../llm/index.js';
 import { generateForElements, groupDocsByFile, writeDocsToDirectory } from '../generator/index.js';
+import { runQA, printQAReport, fixQAIssues, printFixReport } from '../qa/index.js';
 export const watchCommand = new Command('watch')
     .description('Watch source files and regenerate docs on changes')
     .argument('<source>', 'Source directory to watch')
@@ -16,127 +17,142 @@ export const watchCommand = new Command('watch')
     .option('--model <name>', 'LLM model name')
     .option('--debounce <ms>', 'Debounce time in milliseconds', '1000')
     .action(async (source, options) => {
-    const config = loadConfig(options.config);
-    if (source)
-        config.source.path = source;
-    if (options.output)
-        config.output.path = options.output;
-    if (options.provider) {
-        config.llm.provider = options.provider;
-        if (!options.model) {
-            config.llm.model = DEFAULT_MODELS[config.llm.provider];
+    try {
+        const config = loadConfig(options.config);
+        if (source)
+            config.source.path = source;
+        if (options.output)
+            config.output.path = options.output;
+        if (options.provider) {
+            config.llm.provider = options.provider;
+            if (!options.model) {
+                config.llm.model = DEFAULT_MODELS[config.llm.provider];
+            }
         }
-    }
-    if (options.model)
-        config.llm.model = options.model;
-    const errors = validateConfig(config);
-    if (errors.length > 0) {
-        console.error('Config errors:', errors);
-        process.exit(1);
-    }
-    const { ok, envKey } = checkApiKey(config.llm.provider);
-    if (!ok && envKey) {
-        console.error(`Error: ${envKey} required`);
-        process.exit(1);
-    }
-    const sourcePath = resolve(config.source.path);
-    const outputPath = resolve(config.output.path);
-    if (!existsSync(sourcePath)) {
-        console.error(`Source not found: ${sourcePath}`);
-        process.exit(1);
-    }
-    console.log('skrypt watch');
-    console.log(`  source: ${sourcePath}`);
-    console.log(`  output: ${outputPath}`);
-    console.log(`  provider: ${config.llm.provider}`);
-    console.log('');
-    const client = createLLMClient({
-        provider: config.llm.provider,
-        model: config.llm.model,
-        baseUrl: config.llm.baseUrl
-    });
-    let generating = false;
-    let pendingGenerate = false;
-    const debounceMs = parseInt(options.debounce);
-    async function generate() {
-        if (generating) {
-            pendingGenerate = true;
-            return;
+        if (options.model)
+            config.llm.model = options.model;
+        const errors = validateConfig(config);
+        if (errors.length > 0) {
+            console.error('Config errors:', errors);
+            process.exit(1);
+        }
+        const { ok, envKey } = checkApiKey(config.llm.provider);
+        if (!ok && envKey) {
+            console.error(`Error: ${envKey} required`);
+            process.exit(1);
         }
-        generating = true;
-        const startTime = Date.now();
-        try {
-            console.log('\n[' + new Date().toLocaleTimeString() + '] Regenerating docs...');
-            const scanResult = await scanDirectory(sourcePath, {
-                include: config.source.include,
-                exclude: config.source.exclude,
-            });
-            if (scanResult.totalElements === 0) {
-                console.log('  No elements found');
+        const sourcePath = resolve(config.source.path);
+        const outputPath = resolve(config.output.path);
+        if (!existsSync(sourcePath)) {
+            console.error(`Source not found: ${sourcePath}`);
+            process.exit(1);
+        }
+        console.log('skrypt watch');
+        console.log(`  source: ${sourcePath}`);
+        console.log(`  output: ${outputPath}`);
+        console.log(`  provider: ${config.llm.provider}`);
+        console.log('');
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+            baseUrl: config.llm.baseUrl
+        });
+        let generating = false;
+        let pendingGenerate = false;
+        const debounceMs = parseInt(options.debounce, 10);
+        if (isNaN(debounceMs) || debounceMs < 1) {
+            console.error('Error: --debounce must be a positive number');
+            process.exit(1);
+        }
+        async function generate() {
+            if (generating) {
+                pendingGenerate = true;
                 return;
             }
-            const allElements = [];
-            for (const file of scanResult.files) {
-                allElements.push(...file.elements);
+            generating = true;
+            const startTime = Date.now();
+            try {
+                console.log('\n[' + new Date().toLocaleTimeString() + '] Regenerating docs...');
+                const scanResult = await scanDirectory(sourcePath, {
+                    include: config.source.include,
+                    exclude: config.source.exclude,
+                });
+                if (scanResult.totalElements === 0) {
+                    console.log('  No elements found');
+                    return;
+                }
+                const allElements = [];
+                for (const file of scanResult.files) {
+                    allElements.push(...file.elements);
+                }
+                const docs = await generateForElements(allElements, client, {
+                    onProgress: (p) => {
+                        process.stdout.write(`\r  [${p.current}/${p.total}] ${p.element}`.padEnd(60));
+                    }
+                });
+                const fileResults = groupDocsByFile(docs);
+                await writeDocsToDirectory(fileResults, outputPath, sourcePath);
+                // Auto-fix then run QA on generated output
+                const fixReport = fixQAIssues(outputPath);
+                printFixReport(fixReport);
+                const qaReport = runQA(outputPath);
+                printQAReport(qaReport);
+                const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+                console.log(`\n  Done in ${duration}s`);
+            }
+            catch (err) {
+                console.error('\n  Error:', err);
             }
-            const docs = await generateForElements(allElements, client, {
-                onProgress: (p) => {
-                    process.stdout.write(`\r  [${p.current}/${p.total}] ${p.element}`.padEnd(60));
+            finally {
+                generating = false;
+                if (pendingGenerate) {
+                    pendingGenerate = false;
+                    setTimeout(generate, debounceMs);
                 }
-            });
-            const fileResults = groupDocsByFile(docs);
-            await writeDocsToDirectory(fileResults, outputPath, sourcePath);
-            const duration = ((Date.now() - startTime) / 1000).toFixed(1);
-            console.log(`\n  Done in ${duration}s`);
-        }
-        catch (err) {
-            console.error('\n  Error:', err);
-        }
-        finally {
-            generating = false;
-            if (pendingGenerate) {
-                pendingGenerate = false;
-                setTimeout(generate, debounceMs);
             }
         }
+        // Initial generation
+        await generate();
+        // Watch for changes
+        console.log('\nWatching for changes... (Ctrl+C to stop)');
+        let debounceTimer = null;
+        const watcher = watch(sourcePath, {
+            ignored: [
+                '**/node_modules/**',
+                '**/.git/**',
+                '**/dist/**',
+                '**/__pycache__/**',
+            ],
+            persistent: true,
+            ignoreInitial: true,
+        });
+        watcher.on('change', (path) => {
+            console.log(`  Changed: ${path}`);
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(generate, debounceMs);
+        });
+        watcher.on('add', (path) => {
+            console.log(`  Added: ${path}`);
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(generate, debounceMs);
+        });
+        watcher.on('unlink', (path) => {
+            console.log(`  Removed: ${path}`);
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(generate, debounceMs);
+        });
+        // Keep process alive
+        process.on('SIGINT', () => {
+            console.log('\nStopping watch...');
+            watcher.close();
+            process.exit(0);
+        });
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
     }
-    // Initial generation
-    await generate();
-    // Watch for changes
-    console.log('\nWatching for changes... (Ctrl+C to stop)');
-    let debounceTimer = null;
-    const watcher = watch(sourcePath, {
-        ignored: [
-            '**/node_modules/**',
-            '**/.git/**',
-            '**/dist/**',
-            '**/__pycache__/**',
-        ],
-        persistent: true,
-        ignoreInitial: true,
-    });
-    watcher.on('change', (path) => {
-        console.log(`  Changed: ${path}`);
-        if (debounceTimer)
-            clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(generate, debounceMs);
-    });
-    watcher.on('add', (path) => {
-        console.log(`  Added: ${path}`);
-        if (debounceTimer)
-            clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(generate, debounceMs);
-    });
-    watcher.on('unlink', (path) => {
-        console.log(`  Removed: ${path}`);
-        if (debounceTimer)
-            clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(generate, debounceMs);
-    });
-    // Keep process alive
-    process.on('SIGINT', () => {
-        console.log('\nStopping watch...');
-        watcher.close();
-        process.exit(0);
-    });
 });

package/dist/config/types.js

@@ -20,8 +20,8 @@ export const DEFAULT_CONFIG = {
     version: 1,
     source: {
         path: './src',
-        include: ['**/*.py', '**/*.js', '**/*.ts', '**/*.go', '**/*.rs'],
-        exclude: ['**/node_modules/**', '**/__pycache__/**', '**/dist/**', '**/target/**']
+        include: ['**/*.py', '**/*.js', '**/*.ts', '**/*.go', '**/*.rs', '**/*.java', '**/*.cs', '**/*.php', '**/*.kt', '**/*.kts', '**/*.swift', '**/*.rb'],
+        exclude: ['**/node_modules/**', '**/__pycache__/**', '**/dist/**', '**/target/**', '**/vendor/**', '**/build/**', '**/bin/**', '**/obj/**', '**/.build/**']
     },
     output: {
         path: './docs',

package/dist/context-hub/index.d.ts

@@ -0,0 +1,23 @@
+import type { ContextHubExportOptions, ContextHubExportResult, ContextHubContext } from './types.js';
+import type { GeneratedDoc } from '../generator/types.js';
+export type { ContextHubExportOptions, ContextHubExportResult, ContextHubContext };
+/**
+ * Check if the `chub` CLI is installed
+ */
+export declare function isChubInstalled(): boolean;
+/**
+ * Extract Context Hub IDs from import lines by matching against known mappings
+ */
+export declare function extractDependencyIds(imports: string[]): string[];
+/**
+ * Fetch docs from Context Hub for the given IDs
+ */
+export declare function fetchContextHubDocs(chubIds: string[], language?: string): Map<string, string>;
+/**
+ * Given an element's imports, return relevant fetched docs as a single string
+ */
+export declare function matchImportsToContext(imports: string[], contextMap: Map<string, string>): string | undefined;
+/**
+ * Export generated docs to Context Hub format
+ */
+export declare function exportToContextHub(docs: GeneratedDoc[], outputDir: string, options: ContextHubExportOptions): ContextHubExportResult;

package/dist/context-hub/index.js

@@ -0,0 +1,179 @@
+import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { IMPORT_MAPPINGS } from './mappings.js';
+/**
+ * Check if the `chub` CLI is installed
+ */
+export function isChubInstalled() {
+    try {
+        const result = spawnSync('chub', ['--version'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract Context Hub IDs from import lines by matching against known mappings
+ */
+export function extractDependencyIds(imports) {
+    const hits = new Map();
+    for (const line of imports) {
+        for (const mapping of IMPORT_MAPPINGS) {
+            if (mapping.pattern.test(line)) {
+                hits.set(mapping.chubId, (hits.get(mapping.chubId) || 0) + 1);
+            }
+        }
+    }
+    // Sort by frequency (most imported first), cap at 10
+    return [...hits.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([id]) => id);
+}
+/**
+ * Fetch docs from Context Hub for the given IDs
+ */
+export function fetchContextHubDocs(chubIds, language) {
+    const results = new Map();
+    for (const id of chubIds) {
+        try {
+            const args = ['get', id];
+            if (language) {
+                args.push('--lang', language);
+            }
+            const result = spawnSync('chub', args, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 15000,
+            });
+            if (result.status === 0 && result.stdout?.trim()) {
+                results.set(id, result.stdout.trim());
+            }
+        }
+        catch {
+            // Skip failures silently
+        }
+    }
+    return results;
+}
+/**
+ * Given an element's imports, return relevant fetched docs as a single string
+ */
+export function matchImportsToContext(imports, contextMap) {
+    if (!imports.length || !contextMap.size)
+        return undefined;
+    const ids = extractDependencyIds(imports);
+    const matched = [];
+    for (const id of ids) {
+        const content = contextMap.get(id);
+        if (content) {
+            matched.push(`## ${id}\n${content}`);
+        }
+    }
+    if (!matched.length)
+        return undefined;
+    return matched.join('\n\n');
+}
+/**
+ * Export generated docs to Context Hub format
+ */
+export function exportToContextHub(docs, outputDir, options) {
+    const { projectName, languages, version, description } = options;
+    const isMultiLang = languages.length > 1;
+    // Create directory structure
+    const baseDir = join(outputDir, 'context-hub', projectName, 'docs', 'api');
+    let filesWritten = 0;
+    // Group docs by element kind for organized output
+    const byKind = new Map();
+    for (const doc of docs) {
+        if (doc.error)
+            continue;
+        const kind = doc.element.kind;
+        if (!byKind.has(kind))
+            byKind.set(kind, []);
+        byKind.get(kind).push(doc);
+    }
+    const buildContent = (lang) => {
+        const today = new Date().toISOString().split('T')[0];
+        let content = '---\n';
+        content += `name: "api"\n`;
+        content += `description: "${description || `API documentation for ${projectName}`}"\n`;
+        content += `metadata:\n`;
+        content += `  languages: "${lang || languages.join(', ')}"\n`;
+        content += `  versions: "${version || '1.0.0'}"\n`;
+        content += `  revision: 1\n`;
+        content += `  updated-on: "${today}"\n`;
+        content += `  source: community\n`;
+        content += `  tags: "${projectName},api,documentation"\n`;
+        content += '---\n\n';
+        content += `# ${projectName} API Documentation\n\n`;
+        for (const [kind, kindDocs] of byKind) {
+            const heading = kind.charAt(0).toUpperCase() + kind.slice(1) + 's';
+            content += `## ${heading}\n\n`;
+            for (const doc of kindDocs) {
+                content += `### ${doc.element.name}\n\n`;
+                if (doc.markdown) {
+                    content += doc.markdown + '\n\n';
+                }
+                // Pick the right code example for this language
+                if (lang === 'python' && doc.pythonExample) {
+                    content += `\`\`\`python\n${doc.pythonExample}\n\`\`\`\n\n`;
+                }
+                else if (lang === 'javascript' || lang === 'typescript') {
+                    const code = doc.typescriptExample || doc.codeExample;
+                    if (code) {
+                        content += `\`\`\`typescript\n${code}\n\`\`\`\n\n`;
+                    }
+                }
+                else if (doc.codeExample) {
+                    content += `\`\`\`${doc.codeLanguage}\n${doc.codeExample}\n\`\`\`\n\n`;
+                }
+            }
+        }
+        return content;
+    };
+    if (isMultiLang) {
+        // Write per-language files
+        for (const lang of languages) {
+            const langDir = join(baseDir, lang);
+            mkdirSync(langDir, { recursive: true });
+            writeFileSync(join(langDir, 'DOC.md'), buildContent(lang));
+            filesWritten++;
+        }
+    }
+    else {
+        // Single-language file
+        mkdirSync(baseDir, { recursive: true });
+        writeFileSync(join(baseDir, 'DOC.md'), buildContent(languages[0]));
+        filesWritten++;
+    }
+    // Write submission instructions README
+    const readmeDir = join(outputDir, 'context-hub');
+    const readme = `# Context Hub Submission
+
+Your documentation has been exported in Context Hub format.
+
+## How to submit
+
+1. Fork https://github.com/andrewyng/context-hub
+2. Copy the \`${projectName}/\` directory into the \`contexts/\` folder of your fork
+3. Open a pull request with a brief description of your project
+
+## What is Context Hub?
+
+Context Hub is a curated registry of machine-readable API docs for AI coding agents.
+Once submitted, any developer using \`chub\` will be able to pull your docs directly
+into their AI coding workflow.
+
+Learn more: https://github.com/andrewyng/context-hub
+`;
+    writeFileSync(join(readmeDir, 'README.md'), readme);
+    filesWritten++;
+    return { outputDir: readmeDir, filesWritten, languages };
+}

package/dist/context-hub/mappings.d.ts

@@ -0,0 +1,8 @@
+import { ImportMapping } from './types.js';
+/**
+ * Static registry mapping import patterns to Context Hub IDs.
+ *
+ * Covers ES6 imports, CommonJS require(), and Python imports.
+ * Sorted roughly by ecosystem popularity.
+ */
+export declare const IMPORT_MAPPINGS: ImportMapping[];

package/dist/context-hub/mappings.js

@@ -0,0 +1,55 @@
+/**
+ * Static registry mapping import patterns to Context Hub IDs.
+ *
+ * Covers ES6 imports, CommonJS require(), and Python imports.
+ * Sorted roughly by ecosystem popularity.
+ */
+export const IMPORT_MAPPINGS = [
+    // --- JavaScript / TypeScript ---
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]stripe['"]/, chubId: 'stripe/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]openai['"]/, chubId: 'openai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@anthropic-ai\/sdk['"]/, chubId: 'anthropic/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@google-cloud\//, chubId: 'google-cloud/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]firebase['"]/, chubId: 'firebase/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@supabase\/supabase-js['"]/, chubId: 'supabase/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@prisma\/client['"]/, chubId: 'prisma/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]drizzle-orm['"]/, chubId: 'drizzle/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]next['"]/, chubId: 'nextjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]next\//, chubId: 'nextjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]express['"]/, chubId: 'express/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]hono['"]/, chubId: 'hono/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@aws-sdk\//, chubId: 'aws/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]axios['"]/, chubId: 'axios/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]zod['"]/, chubId: 'zod/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@trpc\//, chubId: 'trpc/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@tanstack\/react-query['"]/, chubId: 'tanstack-query/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@clerk\//, chubId: 'clerk/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@auth\//, chubId: 'authjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]mongoose['"]/, chubId: 'mongoose/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]typeorm['"]/, chubId: 'typeorm/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@langchain\//, chubId: 'langchain/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]llamaindex['"]/, chubId: 'llamaindex/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@pinecone-database\/pinecone['"]/, chubId: 'pinecone/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@vercel\/ai['"]/, chubId: 'vercel-ai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]ai['"]/, chubId: 'vercel-ai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@sentry\//, chubId: 'sentry/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@reduxjs\/toolkit['"]/, chubId: 'redux-toolkit/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]graphql['"]/, chubId: 'graphql/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@apollo\//, chubId: 'apollo/api' },
+    // --- Python ---
+    { pattern: /^(?:from|import)\s+fastapi/, chubId: 'fastapi/api' },
+    { pattern: /^(?:from|import)\s+django/, chubId: 'django/api' },
+    { pattern: /^(?:from|import)\s+flask/, chubId: 'flask/api' },
+    { pattern: /^(?:from|import)\s+sqlalchemy/, chubId: 'sqlalchemy/api' },
+    { pattern: /^(?:from|import)\s+pydantic/, chubId: 'pydantic/api' },
+    { pattern: /^(?:from|import)\s+pandas/, chubId: 'pandas/api' },
+    { pattern: /^(?:from|import)\s+numpy/, chubId: 'numpy/api' },
+    { pattern: /^(?:from|import)\s+torch/, chubId: 'pytorch/api' },
+    { pattern: /^(?:from|import)\s+tensorflow/, chubId: 'tensorflow/api' },
+    { pattern: /^(?:from|import)\s+langchain/, chubId: 'langchain/api' },
+    { pattern: /^(?:from|import)\s+anthropic/, chubId: 'anthropic/api' },
+    { pattern: /^(?:from|import)\s+openai/, chubId: 'openai/api' },
+    { pattern: /^(?:from|import)\s+stripe/, chubId: 'stripe/api' },
+    { pattern: /^(?:from|import)\s+boto3/, chubId: 'aws/api' },
+    { pattern: /^(?:from|import)\s+celery/, chubId: 'celery/api' },
+];

package/dist/context-hub/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Options for exporting docs to Context Hub format
+ */
+export interface ContextHubExportOptions {
+    projectName: string;
+    languages: string[];
+    version?: string;
+    description?: string;
+}
+/**
+ * Result of a Context Hub export
+ */
+export interface ContextHubExportResult {
+    outputDir: string;
+    filesWritten: number;
+    languages: string[];
+}
+/**
+ * Fetched context from Context Hub for a dependency
+ */
+export interface ContextHubContext {
+    id: string;
+    content: string;
+}
+/**
+ * Maps an import pattern to a Context Hub ID
+ */
+export interface ImportMapping {
+    /** Regex pattern to match against import lines */
+    pattern: RegExp;
+    /** Context Hub ID (e.g., "stripe/api") */
+    chubId: string;
+}

package/dist/context-hub/types.js

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