skrypt-ai 0.6.1 → 0.8.0

package/dist/commands/refresh.js

@@ -0,0 +1,158 @@
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { requirePro } from '../auth/index.js';
+import { scanDirectory } from '../scanner/index.js';
+import { createLLMClient } from '../llm/index.js';
+import { generateForElement } from '../generator/generator.js';
+import { loadConfig, checkApiKey } from '../config/index.js';
+import { readManifest, writeManifest, buildManifestEntries } from '../refresh/manifest.js';
+import { getChangedFiles, findStaleElements } from '../refresh/differ.js';
+import { spliceDocSection, removeDocSection } from '../refresh/splicer.js';
+export const refreshCommand = new Command('refresh')
+    .description('Refresh stale documentation based on code changes')
+    .argument('[source]', 'Source code directory', '.')
+    .option('--docs <dir>', 'Documentation directory', './docs')
+    .option('--since <ref>', 'Git ref to compare against (e.g. HEAD~3, 2026-03-01)', 'HEAD~1')
+    .option('-c, --config <file>', 'Config file path')
+    .option('--provider <name>', 'LLM provider')
+    .option('--model <name>', 'LLM model name')
+    .action(async (source, options) => {
+    try {
+        if (!await requirePro('refresh')) {
+            process.exit(1);
+        }
+        const sourcePath = resolve(source);
+        const docsPath = resolve(options.docs || './docs');
+        if (!existsSync(sourcePath)) {
+            console.error(`Error: Source directory not found: ${sourcePath}`);
+            process.exit(1);
+        }
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Docs directory not found: ${docsPath}`);
+            process.exit(1);
+        }
+        console.log('skrypt refresh');
+        console.log(`  source: ${sourcePath}`);
+        console.log(`  docs:   ${docsPath}`);
+        console.log(`  since:  ${options.since || 'HEAD~1'}`);
+        console.log('');
+        // Read existing manifest
+        const manifest = readManifest(docsPath);
+        if (!manifest) {
+            console.log('  No manifest found. Run `skrypt generate` first to create a manifest.');
+            console.log('  The manifest tracks which code elements map to which doc files.');
+            process.exit(1);
+        }
+        console.log(`  Manifest: generated ${manifest.generatedAt} (${manifest.commitSha})`);
+        console.log(`  Elements tracked: ${manifest.elements.length}`);
+        console.log('');
+        // Get changed files
+        console.log('Finding changed files...');
+        const since = options.since || 'HEAD~1';
+        let changedFiles;
+        try {
+            changedFiles = getChangedFiles(since);
+        }
+        catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
+            return;
+        }
+        if (changedFiles.length === 0) {
+            console.log('  No source files changed since ' + since);
+            console.log('\nAll documentation is up to date!');
+            return;
+        }
+        console.log(`  ${changedFiles.length} file(s) changed`);
+        // Find stale elements
+        console.log('\nChecking for stale documentation...');
+        const staleElements = await findStaleElements(manifest, changedFiles);
+        if (staleElements.length === 0) {
+            console.log('  No stale documentation found.');
+            console.log('\nAll documentation is up to date!');
+            return;
+        }
+        console.log(`  ${staleElements.length} element(s) need updating`);
+        console.log('');
+        // Set up LLM client for regeneration
+        const config = loadConfig(options.config);
+        if (options.provider)
+            config.llm.provider = options.provider;
+        if (options.model)
+            config.llm.model = options.model;
+        const { ok, envKey } = checkApiKey(config.llm.provider);
+        if (!ok && envKey) {
+            console.error(`Error: ${envKey} required for ${config.llm.provider}`);
+            process.exit(1);
+        }
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+        });
+        // Regenerate stale elements
+        let regenerated = 0;
+        let removed = 0;
+        for (const stale of staleElements) {
+            if (stale.newSignature === '[REMOVED]') {
+                // Element was deleted from code
+                console.log(`  \x1b[31m✗ removed\x1b[0m ${stale.entry.name}`);
+                removeDocSection(stale.entry.docFile, stale.entry.name);
+                removed++;
+                continue;
+            }
+            console.log(`  \x1b[33m↻ updating\x1b[0m ${stale.entry.name}`);
+            // Re-scan to get the full element context
+            try {
+                const scanResult = await scanDirectory(stale.entry.sourceFile);
+                const element = scanResult.files
+                    .flatMap(f => f.elements)
+                    .find(el => el.name === stale.entry.name && el.kind === stale.entry.kind);
+                if (!element) {
+                    console.log(`    Could not find element in source — skipping`);
+                    continue;
+                }
+                const doc = await generateForElement(element, client, {});
+                if (doc.error) {
+                    console.log(`    \x1b[31mGeneration failed: ${doc.error.slice(0, 60)}\x1b[0m`);
+                    continue;
+                }
+                // Build the new section content
+                const lang = doc.codeLanguage;
+                let section = `### \`${element.name}\`\n\n`;
+                section += `\`\`\`${lang}\n${element.signature}\n\`\`\`\n\n`;
+                if (doc.markdown)
+                    section += doc.markdown + '\n\n';
+                if (doc.codeExample) {
+                    section += '**Example:**\n\n';
+                    section += `\`\`\`${lang}\n${doc.codeExample}\n\`\`\`\n\n`;
+                }
+                spliceDocSection(stale.entry.docFile, stale.entry.name, section);
+                regenerated++;
+            }
+            catch (err) {
+                console.log(`    Error: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        const unchanged = manifest.elements.length - regenerated - removed;
+        // Update manifest
+        console.log('\nUpdating manifest...');
+        const scanResult = await scanDirectory(sourcePath);
+        const allElements = scanResult.files.flatMap(f => f.elements);
+        const newEntries = buildManifestEntries(allElements, docsPath);
+        writeManifest(docsPath, newEntries);
+        console.log('\n=== Refresh Summary ===');
+        console.log(`  Regenerated: ${regenerated}`);
+        console.log(`  Removed:     ${removed}`);
+        console.log(`  Unchanged:   ${unchanged}`);
+        console.log(`  Total:       ${manifest.elements.length}`);
+        const savings = manifest.elements.length > 0
+            ? Math.round((unchanged / manifest.elements.length) * 100)
+            : 0;
+        console.log(`\n  Saved ~${savings}% LLM cost vs full regeneration`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});

package/dist/commands/review.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const reviewCommand: Command;

package/dist/commands/review.js

@@ -0,0 +1,110 @@
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve, relative, isAbsolute } from 'path';
+import { requirePro } from '../auth/index.js';
+import { loadConfig, checkApiKey } from '../config/index.js';
+import { createLLMClient } from '../llm/index.js';
+import { parseFeedbackFile, parseInlineComments, applyFeedback } from '../review/index.js';
+export const reviewCommand = new Command('review')
+    .description('Incorporate feedback into documentation')
+    .argument('[docs]', 'Documentation directory', './docs')
+    .option('--feedback <file>', 'Feedback file (markdown format)')
+    .option('--inline', 'Process <!-- FIXME: --> and <!-- TODO: --> comments in docs')
+    .option('-c, --config <file>', 'Config file path')
+    .option('--provider <name>', 'LLM provider')
+    .option('--model <name>', 'LLM model name')
+    .action(async (docs, options) => {
+    try {
+        if (!await requirePro('review')) {
+            process.exit(1);
+        }
+        const docsPath = resolve(docs);
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Docs directory not found: ${docsPath}`);
+            process.exit(1);
+        }
+        if (!options.feedback && !options.inline) {
+            console.error('Error: Specify --feedback <file> or --inline');
+            process.exit(1);
+        }
+        console.log('skrypt review');
+        console.log(`  docs: ${docsPath}`);
+        if (options.feedback)
+            console.log(`  feedback: ${options.feedback}`);
+        if (options.inline)
+            console.log('  mode: inline (FIXME/TODO comments)');
+        console.log('');
+        // Collect feedback items
+        const feedbackItems = [];
+        if (options.feedback) {
+            const feedbackPath = resolve(options.feedback);
+            if (!existsSync(feedbackPath)) {
+                console.error(`Error: Feedback file not found: ${feedbackPath}`);
+                process.exit(1);
+            }
+            const rawItems = parseFeedbackFile(feedbackPath);
+            // Resolve relative filePaths from feedback to absolute paths
+            for (const item of rawItems) {
+                if (!isAbsolute(item.filePath)) {
+                    item.filePath = resolve(item.filePath);
+                }
+            }
+            feedbackItems.push(...rawItems);
+        }
+        if (options.inline) {
+            feedbackItems.push(...parseInlineComments(docsPath));
+        }
+        if (feedbackItems.length === 0) {
+            console.log('No feedback items found.');
+            return;
+        }
+        console.log(`Found ${feedbackItems.length} feedback item(s)\n`);
+        // Set up LLM client
+        const config = loadConfig(options.config);
+        if (options.provider)
+            config.llm.provider = options.provider;
+        if (options.model)
+            config.llm.model = options.model;
+        const { ok, envKey } = checkApiKey(config.llm.provider);
+        if (!ok && envKey) {
+            console.error(`Error: ${envKey} required for ${config.llm.provider}`);
+            process.exit(1);
+        }
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+        });
+        // Apply feedback
+        let applied = 0;
+        let failed = 0;
+        for (const item of feedbackItems) {
+            const location = item.lineNumber ? `:${item.lineNumber}` : '';
+            const element = item.elementName ? ` (${item.elementName})` : '';
+            const relPath = relative(docsPath, item.filePath);
+            const displayPath = relPath.startsWith('..') ? item.filePath : relPath;
+            process.stdout.write(`  Processing ${displayPath}${location}${element}...`);
+            const result = await applyFeedback(item, client);
+            if (result.applied) {
+                console.log(' \x1b[32m✓\x1b[0m');
+                applied++;
+            }
+            else {
+                console.log(` \x1b[31m✗\x1b[0m ${result.error?.slice(0, 60) || 'unknown error'}`);
+                failed++;
+            }
+        }
+        console.log('\n=== Review Summary ===');
+        console.log(`  Applied: ${applied}`);
+        if (failed > 0) {
+            console.log(`  Failed:  ${failed}`);
+        }
+        console.log(`  Total:   ${feedbackItems.length}`);
+        if (failed > 0) {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});