skrypt-ai 0.6.0 → 0.7.0

package/dist/audit/doc-parser.d.ts

@@ -0,0 +1,5 @@
+import { DocumentedElement } from './types.js';
+/**
+ * Extract documented elements from markdown files
+ */
+export declare function parseDocumentedElements(docsDir: string): DocumentedElement[];

package/dist/audit/doc-parser.js

@@ -0,0 +1,106 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+/**
+ * Find all markdown files in a docs directory
+ */
+function findMarkdownFiles(dir) {
+    const files = [];
+    function walk(currentDir) {
+        const entries = readdirSync(currentDir);
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules') {
+                walk(fullPath);
+            }
+            else if (stat.isFile() && (extname(entry) === '.md' || extname(entry) === '.mdx')) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+/**
+ * Extract documented elements from markdown files
+ */
+export function parseDocumentedElements(docsDir) {
+    const files = findMarkdownFiles(docsDir);
+    const elements = [];
+    for (const filePath of files) {
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        let hasCodeBlock = false;
+        let currentElement = null;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (hasCodeBlock) {
+                if (line.trim().startsWith('```')) {
+                    hasCodeBlock = false;
+                }
+                continue;
+            }
+            // Look for headings that indicate API elements
+            // Pattern: ### `functionName` or ## `ClassName`
+            const headingMatch = line.match(/^#{2,4}\s+`([^`]+)`/);
+            if (headingMatch) {
+                // Save previous element
+                if (currentElement?.name) {
+                    elements.push(currentElement);
+                }
+                const name = headingMatch[1];
+                currentElement = {
+                    name,
+                    kind: 'unknown',
+                    filePath,
+                    lineNumber: i + 1,
+                    hasExample: false,
+                };
+                continue;
+            }
+            // Look for signature code blocks right after element heading
+            // Must check before generic code block toggle
+            if (line.match(/^```\w+/)) {
+                hasCodeBlock = true;
+                if (currentElement) {
+                    currentElement.hasExample = true;
+                    if (!currentElement.signature && i + 1 < lines.length) {
+                        const sigLines = [];
+                        for (let j = i + 1; j < lines.length; j++) {
+                            if (lines[j].trim() === '```')
+                                break;
+                            sigLines.push(lines[j]);
+                        }
+                        currentElement.signature = sigLines.join('\n').trim();
+                    }
+                }
+                continue;
+            }
+            // Plain ``` (closing or code block without language)
+            if (line.trim().startsWith('```')) {
+                hasCodeBlock = true;
+                if (currentElement) {
+                    currentElement.hasExample = true;
+                }
+                continue;
+            }
+            // Detect kind from context
+            if (currentElement && currentElement.kind === 'unknown') {
+                if (/\bmethod\b/i.test(line)) {
+                    currentElement.kind = 'method';
+                }
+                else if (/\bclass\b/i.test(line)) {
+                    currentElement.kind = 'class';
+                }
+                else if (/\bfunction\b/i.test(line)) {
+                    currentElement.kind = 'function';
+                }
+            }
+        }
+        // Save last element
+        if (currentElement?.name) {
+            elements.push(currentElement);
+        }
+    }
+    return elements;
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './doc-parser.js';
+export * from './matcher.js';
+export * from './reporter.js';

package/dist/audit/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './doc-parser.js';
+export * from './matcher.js';
+export * from './reporter.js';

package/dist/audit/matcher.d.ts

@@ -0,0 +1,6 @@
+import { APIElement } from '../scanner/types.js';
+import { DocumentedElement, AuditReport } from './types.js';
+/**
+ * Cross-reference code elements with documented elements to produce an audit report
+ */
+export declare function crossReference(codeElements: APIElement[], docElements: DocumentedElement[]): AuditReport;

package/dist/audit/matcher.js

@@ -0,0 +1,94 @@
+/**
+ * Normalize a name for fuzzy matching (lowercase, strip common prefixes)
+ */
+function normalizeName(name) {
+    return name
+        .replace(/^(async\s+)?/, '')
+        .replace(/\(.*\)$/, '')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Normalize a signature for comparison
+ */
+function normalizeSignature(sig) {
+    return sig
+        .replace(/\s+/g, ' ')
+        .replace(/\s*:\s*/g, ': ')
+        .replace(/\s*=\s*/g, ' = ')
+        .trim();
+}
+/**
+ * Cross-reference code elements with documented elements to produce an audit report
+ */
+export function crossReference(codeElements, docElements) {
+    const docNames = new Map();
+    // Index documented elements by normalized name
+    for (const doc of docElements) {
+        const key = normalizeName(doc.name);
+        if (!docNames.has(key))
+            docNames.set(key, []);
+        docNames.get(key).push(doc);
+    }
+    const matchedCodeNames = new Set();
+    const matchedDocNames = new Set();
+    const undocumented = [];
+    const signatureMismatches = [];
+    const missingExamples = [];
+    // Find undocumented code elements and signature mismatches
+    for (const codeEl of codeElements) {
+        const key = normalizeName(codeEl.name);
+        const docMatches = docNames.get(key);
+        if (!docMatches || docMatches.length === 0) {
+            undocumented.push(codeEl);
+            continue;
+        }
+        matchedCodeNames.add(key);
+        for (const docEl of docMatches) {
+            matchedDocNames.add(normalizeName(docEl.name));
+            // Check for signature mismatch
+            if (docEl.signature && codeEl.signature) {
+                const normalizedDoc = normalizeSignature(docEl.signature);
+                const normalizedCode = normalizeSignature(codeEl.signature);
+                if (normalizedDoc !== normalizedCode) {
+                    signatureMismatches.push({
+                        element: codeEl,
+                        docsSignature: docEl.signature,
+                        codeSignature: codeEl.signature,
+                        docFile: docEl.filePath,
+                    });
+                }
+            }
+            // Check for missing examples
+            if (!docEl.hasExample) {
+                missingExamples.push(docEl);
+            }
+        }
+    }
+    // Find orphaned docs (documented but no matching code)
+    const orphaned = [];
+    for (const doc of docElements) {
+        const key = normalizeName(doc.name);
+        if (!matchedCodeNames.has(key)) {
+            orphaned.push({ name: doc.name, filePath: doc.filePath });
+        }
+    }
+    const documented = codeElements.length - undocumented.length;
+    const coveragePercent = codeElements.length > 0
+        ? Math.round((documented / codeElements.length) * 100)
+        : 100;
+    // Staleness score: ratio of signature mismatches to documented elements
+    const stalenessScore = documented > 0
+        ? Math.round((signatureMismatches.length / documented) * 100)
+        : 0;
+    return {
+        undocumented,
+        orphaned,
+        signatureMismatches,
+        missingExamples,
+        coveragePercent,
+        stalenessScore,
+        totalCodeElements: codeElements.length,
+        totalDocElements: docElements.length,
+    };
+}

package/dist/audit/reporter.d.ts

@@ -0,0 +1,9 @@
+import { AuditReport } from './types.js';
+/**
+ * Format audit report as human-readable text
+ */
+export declare function formatTextReport(report: AuditReport, basePath: string): string;
+/**
+ * Format audit report as JSON
+ */
+export declare function formatJsonReport(report: AuditReport): string;

package/dist/audit/reporter.js

@@ -0,0 +1,106 @@
+import { relative } from 'path';
+/**
+ * Format audit report as human-readable text
+ */
+export function formatTextReport(report, basePath) {
+    const lines = [];
+    lines.push('skrypt audit\n');
+    lines.push(`  Coverage: ${report.coveragePercent}% (${report.totalCodeElements - report.undocumented.length}/${report.totalCodeElements} elements documented)`);
+    if (report.stalenessScore > 0) {
+        lines.push(`  Staleness: ${report.stalenessScore}% of documented elements have signature mismatches`);
+    }
+    lines.push('');
+    // Undocumented
+    if (report.undocumented.length > 0) {
+        lines.push(`  UNDOCUMENTED (${report.undocumented.length})`);
+        // Group by file
+        const byFile = new Map();
+        for (const el of report.undocumented) {
+            const rel = relative(basePath, el.filePath);
+            if (!byFile.has(rel))
+                byFile.set(rel, []);
+            byFile.get(rel).push(`${el.name}()`);
+        }
+        for (const [file, names] of byFile) {
+            lines.push(`    ${file} → ${names.join(', ')}`);
+        }
+        lines.push('');
+    }
+    // Signature mismatches (stale)
+    if (report.signatureMismatches.length > 0) {
+        lines.push(`  STALE (${report.signatureMismatches.length})`);
+        for (const mismatch of report.signatureMismatches.slice(0, 20)) {
+            const docRel = relative(basePath, mismatch.docFile);
+            lines.push(`    ${docRel} → ${mismatch.element.name}`);
+            lines.push(`      docs:  ${mismatch.docsSignature.slice(0, 80)}`);
+            lines.push(`      code:  ${mismatch.codeSignature.slice(0, 80)}`);
+        }
+        if (report.signatureMismatches.length > 20) {
+            lines.push(`    ... and ${report.signatureMismatches.length - 20} more`);
+        }
+        lines.push('');
+    }
+    // Orphaned docs
+    if (report.orphaned.length > 0) {
+        lines.push(`  ORPHANED (${report.orphaned.length})`);
+        for (const orphan of report.orphaned.slice(0, 20)) {
+            const rel = relative(basePath, orphan.filePath);
+            lines.push(`    ${rel} — ${orphan.name} — no matching code`);
+        }
+        if (report.orphaned.length > 20) {
+            lines.push(`    ... and ${report.orphaned.length - 20} more`);
+        }
+        lines.push('');
+    }
+    // Missing examples
+    if (report.missingExamples.length > 0) {
+        lines.push(`  MISSING EXAMPLES (${report.missingExamples.length})`);
+        for (const el of report.missingExamples.slice(0, 20)) {
+            const rel = relative(basePath, el.filePath);
+            lines.push(`    ${rel}:${el.lineNumber} — ${el.name}`);
+        }
+        if (report.missingExamples.length > 20) {
+            lines.push(`    ... and ${report.missingExamples.length - 20} more`);
+        }
+        lines.push('');
+    }
+    if (report.undocumented.length === 0 && report.signatureMismatches.length === 0 &&
+        report.orphaned.length === 0 && report.missingExamples.length === 0) {
+        lines.push('  All elements documented with matching signatures and examples!');
+    }
+    return lines.join('\n');
+}
+/**
+ * Format audit report as JSON
+ */
+export function formatJsonReport(report) {
+    return JSON.stringify({
+        coverage: {
+            percent: report.coveragePercent,
+            documented: report.totalCodeElements - report.undocumented.length,
+            total: report.totalCodeElements,
+        },
+        staleness: {
+            score: report.stalenessScore,
+            mismatches: report.signatureMismatches.length,
+        },
+        undocumented: report.undocumented.map(el => ({
+            name: el.name,
+            kind: el.kind,
+            file: el.filePath,
+            line: el.lineNumber,
+        })),
+        orphaned: report.orphaned,
+        signatureMismatches: report.signatureMismatches.map(m => ({
+            name: m.element.name,
+            docFile: m.docFile,
+            docsSignature: m.docsSignature,
+            codeSignature: m.codeSignature,
+        })),
+        missingExamples: report.missingExamples.map(el => ({
+            name: el.name,
+            file: el.filePath,
+            line: el.lineNumber,
+        })),
+    }, null, 2);
+}

package/dist/audit/types.d.ts

@@ -0,0 +1,37 @@
+import { APIElement } from '../scanner/types.js';
+/**
+ * An element that has been documented (found in markdown)
+ */
+export interface DocumentedElement {
+    name: string;
+    kind: 'function' | 'class' | 'method' | 'unknown';
+    signature?: string;
+    filePath: string;
+    lineNumber: number;
+    hasExample: boolean;
+}
+/**
+ * A mismatch between code and docs signatures
+ */
+export interface SignatureMismatch {
+    element: APIElement;
+    docsSignature: string;
+    codeSignature: string;
+    docFile: string;
+}
+/**
+ * Full audit report
+ */
+export interface AuditReport {
+    undocumented: APIElement[];
+    orphaned: Array<{
+        name: string;
+        filePath: string;
+    }>;
+    signatureMismatches: SignatureMismatch[];
+    missingExamples: DocumentedElement[];
+    coveragePercent: number;
+    stalenessScore: number;
+    totalCodeElements: number;
+    totalDocElements: number;
+}

package/dist/audit/types.js

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

package/dist/auth/index.js

@@ -180,5 +180,7 @@ export const PRO_COMMANDS = [
     'sdk',
     'gh-action',
     'ci',
-    'mcp'
+    'mcp',
+    'refresh',
+    'review',
 ];

package/dist/cli.js

@@ -22,6 +22,11 @@ import { testCommand } from './commands/test.js';
 import { securityCommand } from './commands/security.js';
 import { importCommand } from './commands/import.js';
 import { healCommand } from './commands/heal.js';
+import { auditCommand } from './commands/audit.js';
+import { refreshCommand } from './commands/refresh.js';
+import { reviewCommand } from './commands/review.js';
+import { configCommand } from './commands/config.js';
+import { handlePostAction } from './next-actions/index.js';
 import { createRequire } from 'module';
 process.on('uncaughtException', (err) => {
     console.error('\x1b[31mFatal error:\x1b[0m', err.message);
@@ -70,7 +75,8 @@ program
     .name('skrypt')
     .description('AI-powered documentation generator with code examples')
     .version(VERSION)
-    .hook('postAction', async () => {
+    .hook('postAction', async (_thisCommand, actionCommand) => {
+    await handlePostAction(actionCommand.name());
     await checkForUpdates();
 });
 program.addCommand(initCommand);
@@ -97,4 +103,8 @@ program.addCommand(testCommand);
 program.addCommand(securityCommand);
 program.addCommand(importCommand);
 program.addCommand(healCommand);
+program.addCommand(auditCommand);
+program.addCommand(refreshCommand);
+program.addCommand(reviewCommand);
+program.addCommand(configCommand);
 program.parse();

package/dist/commands/audit.d.ts

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

package/dist/commands/audit.js

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { scanDirectory } from '../scanner/index.js';
+import { parseDocumentedElements, crossReference, formatTextReport, formatJsonReport } from '../audit/index.js';
+export const auditCommand = new Command('audit')
+    .description('Audit documentation coverage and staleness')
+    .argument('[source]', 'Source code directory to audit', '.')
+    .option('--docs <dir>', 'Documentation directory to compare against', './docs')
+    .option('--format <type>', 'Output format: text or json', 'text')
+    .option('--public-only', 'Only audit exported/public APIs')
+    .action(async (source, options) => {
+    try {
+        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}`);
+            console.error('  Specify with --docs <dir>');
+            process.exit(1);
+        }
+        // Step 1: Scan source code
+        console.log('Scanning source code...');
+        const scanResult = await scanDirectory(sourcePath, {
+            onProgress: (current, total, file) => {
+                process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+            }
+        });
+        console.log('');
+        let codeElements = scanResult.files.flatMap(f => f.elements);
+        if (options.publicOnly) {
+            codeElements = codeElements.filter(el => el.isExported === true || el.isPublic === true);
+        }
+        // Step 2: Parse documented elements
+        console.log('Parsing documentation...');
+        const docElements = parseDocumentedElements(docsPath);
+        console.log(`  Found ${docElements.length} documented elements\n`);
+        // Step 3: Cross-reference
+        const report = crossReference(codeElements, docElements);
+        // Step 4: Output
+        if (options.format === 'json') {
+            console.log(formatJsonReport(report));
+        }
+        else {
+            console.log(formatTextReport(report, sourcePath));
+        }
+        // Exit with error code if coverage is below threshold
+        if (report.undocumented.length > 0 || report.signatureMismatches.length > 0) {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});

package/dist/commands/config.d.ts

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

package/dist/commands/config.js

@@ -0,0 +1,73 @@
+import { Command } from 'commander';
+import { readPreferences, writePreferences, runFirstTimeSetup } from '../next-actions/index.js';
+export const configCommand = new Command('config')
+    .description('Configure Skrypt preferences')
+    .option('--suggestions', 'Configure next-step suggestions')
+    .option('--suggestions-on', 'Enable next-step suggestions')
+    .option('--suggestions-off', 'Disable next-step suggestions')
+    .action(async (options) => {
+    // Reject conflicting flags
+    const flagCount = [options.suggestions, options.suggestionsOn, options.suggestionsOff].filter(Boolean).length;
+    if (flagCount > 1) {
+        console.error('Error: Use only one of --suggestions, --suggestions-on, --suggestions-off');
+        process.exit(1);
+    }
+    if (options.suggestionsOn) {
+        const prefs = readPreferences();
+        if (prefs) {
+            prefs.enabled = true;
+            writePreferences(prefs);
+        }
+        else {
+            writePreferences({
+                enabled: true,
+                categories: { workflow: true, quality: true, cicd: true, advanced: true },
+            });
+        }
+        console.log('  Next-step suggestions enabled.');
+        return;
+    }
+    if (options.suggestionsOff) {
+        const prefs = readPreferences();
+        if (prefs) {
+            prefs.enabled = false;
+            writePreferences(prefs);
+        }
+        else {
+            writePreferences({
+                enabled: false,
+                categories: { workflow: false, quality: false, cicd: false, advanced: false },
+            });
+        }
+        console.log('  Next-step suggestions disabled.');
+        return;
+    }
+    if (options.suggestions) {
+        await runFirstTimeSetup();
+        return;
+    }
+    // No flags — show current config
+    const prefs = readPreferences();
+    console.log('skrypt config');
+    console.log('');
+    if (!prefs) {
+        console.log('  No preferences set yet. Run any command to configure.');
+        console.log('');
+        console.log('  Options:');
+    }
+    else {
+        console.log('  Suggestions: ' + (prefs.enabled ? '\x1b[32menabled\x1b[0m' : '\x1b[90mdisabled\x1b[0m'));
+        if (prefs.enabled) {
+            console.log('  Categories:');
+            console.log(`    workflow: ${prefs.categories.workflow ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+            console.log(`    quality:  ${prefs.categories.quality ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+            console.log(`    cicd:     ${prefs.categories.cicd ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+            console.log(`    advanced: ${prefs.categories.advanced ? '\x1b[32mon\x1b[0m' : '\x1b[90moff\x1b[0m'}`);
+        }
+        console.log('');
+        console.log('  Options:');
+    }
+    console.log('    --suggestions      Reconfigure suggestion categories');
+    console.log('    --suggestions-on   Enable suggestions');
+    console.log('    --suggestions-off  Disable suggestions');
+});

package/dist/commands/cron.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { existsSync, writeFileSync, mkdirSync } from 'fs';
 import { resolve, join } from 'path';
+import { requirePro } from '../auth/index.js';
 const CRON_WORKFLOW = `name: Skrypt Auto-Update Docs
 
 on:
@@ -54,6 +55,9 @@ export const cronCommand = new Command('cron')
     .option('-s, --schedule <cron>', 'Cron schedule (default: daily at 2am UTC)', '0 2 * * *')
     .option('-f, --force', 'Overwrite existing workflow')
     .action(async (repoPath, options) => {
+    if (!await requirePro('cron')) {
+        process.exit(1);
+    }
     try {
         const resolvedPath = resolve(repoPath);
         const workflowDir = join(resolvedPath, '.github', 'workflows');

package/dist/commands/generate.d.ts

@@ -1,2 +1,9 @@
 import { Command } from 'commander';
+import { SourceEntry } from '../config/types.js';
+/**
+ * Parse source arguments with optional labels.
+ * e.g. "./api:API" → { path: "./api", label: "API" }
+ * e.g. "./src" → { path: "./src" }
+ */
+export declare function parseSourceArgs(args: string[]): SourceEntry[];
 export declare const generateCommand: Command;