skrypt-ai 0.6.0 → 0.7.0

package/dist/review/parser.js

@@ -0,0 +1,95 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+/**
+ * Parse a feedback markdown file.
+ *
+ * Format:
+ * ## docs/api/users.md
+ * - Line 42: Use the SDK client.get() method, not raw fetch()
+ * - General: Too formal, make it conversational
+ */
+export function parseFeedbackFile(feedbackPath) {
+    const content = readFileSync(feedbackPath, 'utf-8');
+    const lines = content.split('\n');
+    const feedback = [];
+    let currentFile = null;
+    for (const line of lines) {
+        // ## path/to/file.md
+        const fileMatch = line.match(/^##\s+(.+\.(?:md|mdx))\s*$/);
+        if (fileMatch) {
+            currentFile = fileMatch[1].trim();
+            continue;
+        }
+        if (!currentFile)
+            continue;
+        // - Line 42: feedback text
+        const lineMatch = line.match(/^-\s+Line\s+(\d+)\s*:\s*(.+)$/);
+        if (lineMatch) {
+            feedback.push({
+                filePath: currentFile,
+                lineNumber: parseInt(lineMatch[1], 10),
+                feedback: lineMatch[2].trim(),
+                source: 'file',
+            });
+            continue;
+        }
+        // - "elementName": feedback text
+        const elementMatch = line.match(/^-\s+"([^"]+)"\s*:\s*(.+)$/);
+        if (elementMatch) {
+            feedback.push({
+                filePath: currentFile,
+                elementName: elementMatch[1].trim(),
+                feedback: elementMatch[2].trim(),
+                source: 'file',
+            });
+            continue;
+        }
+        // - General: feedback text  or  - feedback text
+        const generalMatch = line.match(/^-\s+(?:General\s*:\s*)?(.+)$/);
+        if (generalMatch) {
+            feedback.push({
+                filePath: currentFile,
+                feedback: generalMatch[1].trim(),
+                source: 'file',
+            });
+        }
+    }
+    return feedback;
+}
+/**
+ * Scan markdown files for inline FIXME/TODO comments.
+ *
+ * Looks for: <!-- FIXME: ... --> or <!-- TODO: ... -->
+ */
+export function parseInlineComments(docsDir) {
+    const feedback = [];
+    function walk(dir) {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            const fullPath = join(dir, 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')) {
+                const content = readFileSync(fullPath, 'utf-8');
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    // <!-- FIXME: ... --> or <!-- TODO: ... -->
+                    const commentMatch = line.match(/<!--\s*(?:FIXME|TODO)\s*:\s*(.*?)\s*-->/);
+                    if (commentMatch) {
+                        feedback.push({
+                            filePath: fullPath,
+                            lineNumber: i + 1,
+                            feedback: commentMatch[1].trim(),
+                            source: 'inline',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    walk(docsDir);
+    return feedback;
+}

package/dist/review/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A piece of feedback targeting a specific doc file or element
+ */
+export interface ReviewFeedback {
+    filePath: string;
+    lineNumber?: number;
+    elementName?: string;
+    feedback: string;
+    source: 'file' | 'inline';
+}
+/**
+ * Result of processing a single feedback item
+ */
+export interface ReviewResult {
+    feedback: ReviewFeedback;
+    applied: boolean;
+    error?: string;
+}

package/dist/review/types.js

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

package/dist/scanner/types.d.ts

@@ -27,6 +27,8 @@ export interface APIElement {
     sourceContext?: string;
     packageName?: string;
     relatedTypes?: string[];
+    sourceLabel?: string;
+    sourceRoot?: string;
 }
 /**
  * Result of scanning a file

package/dist/structure/index.d.ts

@@ -0,0 +1,19 @@
+import { APIElement } from '../scanner/types.js';
+import { LLMClient } from '../llm/types.js';
+import { GenerationOptions, GeneratedDoc } from '../generator/types.js';
+import { DocStructure } from './types.js';
+export * from './types.js';
+export { analyzeTopology } from './topology.js';
+export { planStructure } from './planner.js';
+/**
+ * Plan a smart documentation structure using LLM analysis
+ */
+export declare function planSmartStructure(elements: APIElement[], client: LLMClient): Promise<DocStructure>;
+/**
+ * Generate documentation following a smart structure plan
+ */
+export declare function generateWithStructure(structure: DocStructure, client: LLMClient, outputPath: string, options: GenerationOptions): Promise<{
+    filesWritten: number;
+    totalDocs: number;
+    docs: GeneratedDoc[];
+}>;

package/dist/structure/index.js

@@ -0,0 +1,92 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { generateForElements } from '../generator/generator.js';
+import { analyzeTopology } from './topology.js';
+import { planStructure } from './planner.js';
+export * from './types.js';
+export { analyzeTopology } from './topology.js';
+export { planStructure } from './planner.js';
+/**
+ * Plan a smart documentation structure using LLM analysis
+ */
+export async function planSmartStructure(elements, client) {
+    const topology = analyzeTopology(elements);
+    return planStructure(elements, topology, client);
+}
+/**
+ * Generate documentation following a smart structure plan
+ */
+export async function generateWithStructure(structure, client, outputPath, options) {
+    let filesWritten = 0;
+    let totalDocs = 0;
+    const allDocs = [];
+    // Create category directories
+    const categoryDirs = {
+        quickstart: outputPath,
+        concepts: join(outputPath, 'concepts'),
+        guides: join(outputPath, 'guides'),
+        api: join(outputPath, 'api'),
+    };
+    for (const dir of Object.values(categoryDirs)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Generate docs page by page
+    for (const page of structure.pages) {
+        if (page.elements.length === 0)
+            continue;
+        const dir = categoryDirs[page.category] || outputPath;
+        const filePath = join(dir, `${page.slug}.md`);
+        // Generate docs for all elements on this page
+        const docs = await generateForElements(page.elements, client, {
+            ...options,
+            onProgress: (progress) => {
+                options.onProgress?.({
+                    ...progress,
+                    element: `${page.title}: ${progress.element}`,
+                });
+            },
+        });
+        // Write the page
+        const content = buildPageContent(page, docs);
+        writeFileSync(filePath, content);
+        filesWritten++;
+        totalDocs += docs.length;
+        allDocs.push(...docs);
+    }
+    // Write navigation file
+    mkdirSync(join(outputPath, '.skrypt'), { recursive: true });
+    const navContent = JSON.stringify(structure.navigation, null, 2);
+    writeFileSync(join(outputPath, '.skrypt', 'navigation.json'), navContent);
+    return { filesWritten, totalDocs, docs: allDocs };
+}
+/**
+ * Build markdown content for a smart-structured page
+ */
+function buildPageContent(page, docs) {
+    let content = `---\ntitle: ${page.title}\ndescription: ${page.description}\n---\n\n`;
+    content += `# ${page.title}\n\n`;
+    content += `${page.description}\n\n`;
+    for (const doc of docs) {
+        if (doc.error)
+            continue;
+        content += `## \`${doc.element.name}\`\n\n`;
+        content += `\`\`\`${doc.codeLanguage}\n${doc.element.signature}\n\`\`\`\n\n`;
+        if (doc.markdown) {
+            content += doc.markdown + '\n\n';
+        }
+        const hasMultiLang = doc.typescriptExample && doc.pythonExample;
+        if (hasMultiLang) {
+            content += '**Examples:**\n\n';
+            content += '<CodeGroup>\n\n';
+            content += `\`\`\`typescript example.ts\n${doc.typescriptExample}\n\`\`\`\n\n`;
+            content += `\`\`\`python example.py\n${doc.pythonExample}\n\`\`\`\n\n`;
+            content += '</CodeGroup>\n\n';
+        }
+        else if (doc.codeExample) {
+            content += '**Example:**\n\n';
+            content += `\`\`\`${doc.codeLanguage}\n${doc.codeExample}\n\`\`\`\n\n`;
+        }
+        content += '---\n\n';
+    }
+    return content;
+}

package/dist/structure/planner.d.ts

@@ -0,0 +1,8 @@
+import { APIElement } from '../scanner/types.js';
+import { LLMClient } from '../llm/types.js';
+import { DocStructure } from './types.js';
+import { TopologyAnalysis } from './topology.js';
+/**
+ * Use LLM to plan a smart documentation structure
+ */
+export declare function planStructure(elements: APIElement[], topology: TopologyAnalysis, client: LLMClient): Promise<DocStructure>;

package/dist/structure/planner.js

@@ -0,0 +1,180 @@
+/**
+ * Use LLM to plan a smart documentation structure
+ */
+export async function planStructure(elements, topology, client) {
+    // Build a summary of the API surface for the LLM
+    const summary = buildAPISummary(elements, topology);
+    const response = await client.complete({
+        messages: [
+            {
+                role: 'system',
+                content: STRUCTURE_PLANNER_PROMPT,
+            },
+            {
+                role: 'user',
+                content: summary,
+            },
+        ],
+        temperature: 0,
+        maxTokens: 4096,
+    });
+    return parseStructurePlan(response.content, elements);
+}
+const STRUCTURE_PLANNER_PROMPT = `You are an expert documentation architect. Given a list of API elements, plan a documentation structure organized by user journey — NOT by file.
+
+## Output Structure
+
+Return a JSON object with this shape:
+\`\`\`json
+{
+  "pages": [
+    {
+      "slug": "quickstart",
+      "title": "Quickstart",
+      "category": "quickstart",
+      "description": "Get from zero to first API call in 5 minutes",
+      "elementNames": ["createClient", "configure"]
+    },
+    {
+      "slug": "authentication",
+      "title": "Authentication",
+      "category": "concepts",
+      "description": "How auth works — API keys, OAuth, sessions",
+      "elementNames": ["authenticate", "refreshToken", "SessionManager"]
+    }
+  ]
+}
+\`\`\`
+
+## Rules
+1. ALWAYS start with a "quickstart" page covering entry points
+2. Group by CONCEPT (auth, data model, errors), not by file
+3. Put classes and their methods together on one page
+4. "api" category pages are per-class or per-module API reference
+5. "guides" are task-oriented: "Setting up webhooks", "Testing your integration"
+6. Keep slugs lowercase-kebab-case
+7. Every element must appear in exactly one page
+8. Return ONLY the JSON, no markdown fences, no explanation`;
+function buildAPISummary(elements, topology) {
+    let summary = `## API Surface (${elements.length} elements)\n\n`;
+    if (topology.entryPoints.length > 0) {
+        summary += `### Entry Points\n`;
+        for (const ep of topology.entryPoints) {
+            summary += `- ${ep.kind} \`${ep.name}\` (${ep.filePath})\n`;
+        }
+        summary += '\n';
+    }
+    summary += `### Public API (${topology.publicAPI.length} elements)\n`;
+    for (const el of topology.publicAPI.slice(0, 100)) {
+        const parent = el.parentClass ? ` (${el.parentClass})` : '';
+        summary += `- ${el.kind} \`${el.name}\`${parent}: ${el.signature.slice(0, 80)}\n`;
+    }
+    if (topology.publicAPI.length > 100) {
+        summary += `... and ${topology.publicAPI.length - 100} more\n`;
+    }
+    if (topology.classClusters.size > 0) {
+        summary += `\n### Classes (${topology.classClusters.size})\n`;
+        for (const [className, methods] of topology.classClusters) {
+            summary += `- \`${className}\` with methods: ${methods.map(m => m.name).join(', ')}\n`;
+        }
+    }
+    return summary;
+}
+/**
+ * Parse LLM response into DocStructure
+ */
+function parseStructurePlan(content, elements) {
+    // Extract JSON from response
+    let jsonStr = content.trim();
+    // Remove markdown fences if present
+    jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        // Fallback: create a simple structure
+        return createFallbackStructure(elements);
+    }
+    // Map element names to actual elements (case-insensitive for LLM tolerance)
+    const elementByName = new Map();
+    const elementByNameLower = new Map();
+    for (const el of elements) {
+        elementByName.set(el.name, el);
+        elementByNameLower.set(el.name.toLowerCase(), el);
+    }
+    const pages = [];
+    const assignedElements = new Set();
+    for (const page of parsed.pages) {
+        const pageElements = [];
+        for (const name of page.elementNames || []) {
+            // Try exact match first, then case-insensitive
+            let el = elementByName.get(name);
+            if (!el) {
+                el = elementByNameLower.get(name.toLowerCase());
+                if (el) {
+                    console.log(`  Note: LLM returned "${name}", matched to "${el.name}" (case-insensitive)`);
+                }
+            }
+            if (el) {
+                pageElements.push(el);
+                assignedElements.add(el.name);
+            }
+            else {
+                console.log(`  Warning: LLM referenced unknown element "${name}" — skipping`);
+            }
+        }
+        const category = (['quickstart', 'concepts', 'guides', 'api'].includes(page.category)
+            ? page.category
+            : 'api');
+        pages.push({
+            slug: page.slug,
+            title: page.title,
+            category,
+            description: page.description,
+            elements: pageElements,
+        });
+    }
+    // Add unassigned elements to an "API Reference" catch-all
+    const unassigned = elements.filter(el => !assignedElements.has(el.name));
+    if (unassigned.length > 0) {
+        pages.push({
+            slug: 'api-reference',
+            title: 'API Reference',
+            category: 'api',
+            description: 'Complete API reference',
+            elements: unassigned,
+        });
+    }
+    // Build navigation
+    const navigation = buildNavigation(pages);
+    return { pages, navigation };
+}
+function createFallbackStructure(elements) {
+    const pages = [{
+            slug: 'api-reference',
+            title: 'API Reference',
+            category: 'api',
+            description: 'Complete API reference',
+            elements,
+        }];
+    return {
+        pages,
+        navigation: [{ title: 'API Reference', slug: 'api-reference' }],
+    };
+}
+function buildNavigation(pages) {
+    const categories = {
+        quickstart: { title: 'Getting Started', slug: '', children: [] },
+        concepts: { title: 'Concepts', slug: '', children: [] },
+        guides: { title: 'Guides', slug: '', children: [] },
+        api: { title: 'API Reference', slug: '', children: [] },
+    };
+    for (const page of pages) {
+        const cat = categories[page.category];
+        if (cat) {
+            cat.children.push({ title: page.title, slug: page.slug });
+        }
+    }
+    return Object.values(categories).filter(c => c.children.length > 0);
+}

package/dist/structure/topology.d.ts

@@ -0,0 +1,16 @@
+import { APIElement } from '../scanner/types.js';
+/**
+ * Analysis of a codebase's API surface
+ */
+export interface TopologyAnalysis {
+    entryPoints: APIElement[];
+    publicAPI: APIElement[];
+    internalElements: APIElement[];
+    classClusters: Map<string, APIElement[]>;
+    fileClusters: Map<string, APIElement[]>;
+}
+/**
+ * Analyze the topology of a set of API elements.
+ * Identifies entry points, public surface, class groupings, and file clusters.
+ */
+export declare function analyzeTopology(elements: APIElement[]): TopologyAnalysis;

package/dist/structure/topology.js

@@ -0,0 +1,49 @@
+/**
+ * Analyze the topology of a set of API elements.
+ * Identifies entry points, public surface, class groupings, and file clusters.
+ */
+export function analyzeTopology(elements) {
+    const entryPoints = [];
+    const publicAPI = [];
+    const internalElements = [];
+    const classClusters = new Map();
+    const fileClusters = new Map();
+    for (const el of elements) {
+        // Classify by visibility
+        if (el.isExported || el.isPublic) {
+            publicAPI.push(el);
+        }
+        else {
+            internalElements.push(el);
+        }
+        // Identify likely entry points (exported top-level functions/classes)
+        if ((el.isExported || el.isPublic) && !el.parentClass && (el.kind === 'function' || el.kind === 'class')) {
+            // Heuristic: entry points are often in index.ts, main.ts, or have names like init, create, setup
+            const isEntryFile = /(?:index|main|app|server|client)\.\w+$/.test(el.filePath);
+            const isEntryName = /^(?:create|init|setup|configure|connect|start|build)/i.test(el.name);
+            if (isEntryFile || isEntryName) {
+                entryPoints.push(el);
+            }
+        }
+        // Group by parent class
+        if (el.parentClass) {
+            if (!classClusters.has(el.parentClass)) {
+                classClusters.set(el.parentClass, []);
+            }
+            classClusters.get(el.parentClass).push(el);
+        }
+        // Group by source file
+        const fileKey = el.filePath.replace(/\.(ts|js|py|go|rs|java|cs|php|kt|swift|rb)x?$/, '');
+        if (!fileClusters.has(fileKey)) {
+            fileClusters.set(fileKey, []);
+        }
+        fileClusters.get(fileKey).push(el);
+    }
+    return {
+        entryPoints,
+        publicAPI,
+        internalElements,
+        classClusters,
+        fileClusters,
+    };
+}

package/dist/structure/types.d.ts

@@ -0,0 +1,26 @@
+import { APIElement } from '../scanner/types.js';
+/**
+ * A planned page in the smart-structured docs
+ */
+export interface PagePlan {
+    slug: string;
+    title: string;
+    category: 'quickstart' | 'concepts' | 'guides' | 'api';
+    description: string;
+    elements: APIElement[];
+}
+/**
+ * Full documentation structure plan
+ */
+export interface DocStructure {
+    pages: PagePlan[];
+    navigation: NavigationNode[];
+}
+/**
+ * Navigation tree node
+ */
+export interface NavigationNode {
+    title: string;
+    slug: string;
+    children?: NavigationNode[];
+}

package/dist/structure/types.js

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

package/dist/testing/comparator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compare actual output against expected output
+ */
+export declare function compareOutput(actual: string, expected: string, mode?: 'exact' | 'contains'): {
+    match: boolean;
+    diff: string;
+};

package/dist/testing/comparator.js

@@ -0,0 +1,77 @@
+/**
+ * Compare actual output against expected output
+ */
+export function compareOutput(actual, expected, mode = 'exact') {
+    const normalizedActual = normalize(actual);
+    const normalizedExpected = normalize(expected);
+    if (mode === 'contains') {
+        const match = normalizedActual.includes(normalizedExpected);
+        if (match) {
+            return { match: true, diff: '' };
+        }
+        return {
+            match: false,
+            diff: buildDiff(normalizedExpected, normalizedActual, 'contains'),
+        };
+    }
+    // Exact mode
+    if (normalizedActual === normalizedExpected) {
+        return { match: true, diff: '' };
+    }
+    return {
+        match: false,
+        diff: buildDiff(normalizedExpected, normalizedActual, 'exact'),
+    };
+}
+/**
+ * Normalize output for comparison: trim whitespace, normalize line endings
+ */
+function normalize(s) {
+    return s
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .trim();
+}
+/**
+ * Build a unified-style diff for display
+ */
+function buildDiff(expected, actual, mode) {
+    const expectedLines = expected.split('\n');
+    const actualLines = actual.split('\n');
+    const lines = [];
+    if (mode === 'contains') {
+        lines.push('--- expected (contains) ---');
+        lines.push('+++ actual +++');
+        lines.push('');
+        for (const line of expectedLines) {
+            lines.push(`- ${line}`);
+        }
+        lines.push('---');
+        for (const line of actualLines) {
+            lines.push(`+ ${line}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push('--- expected ---');
+    lines.push('+++ actual +++');
+    lines.push('');
+    const maxLen = Math.max(expectedLines.length, actualLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        const exp = expectedLines[i];
+        const act = actualLines[i];
+        if (exp === undefined) {
+            lines.push(`+ ${act}`);
+        }
+        else if (act === undefined) {
+            lines.push(`- ${exp}`);
+        }
+        else if (exp !== act) {
+            lines.push(`- ${exp}`);
+            lines.push(`+ ${act}`);
+        }
+        else {
+            lines.push(`  ${exp}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/testing/docker.d.ts

@@ -0,0 +1,21 @@
+import { ExtractedSnippet, TestResult, DockerEnvironment, RunnerConfig } from './types.js';
+/**
+ * Available Docker environments for multi-env testing
+ */
+export declare const DOCKER_ENVIRONMENTS: DockerEnvironment[];
+/**
+ * Check if Docker is available on this machine
+ */
+export declare function isDockerAvailable(): boolean;
+/**
+ * Parse a comma-separated environments string into DockerEnvironment objects
+ */
+export declare function parseEnvironments(envString: string): DockerEnvironment[];
+/**
+ * Get compatible Docker environments for a given language
+ */
+export declare function getCompatibleEnvironments(language: string, environments: DockerEnvironment[]): DockerEnvironment[];
+/**
+ * Run a snippet in a Docker container
+ */
+export declare function runInDocker(snippet: ExtractedSnippet, environment: DockerEnvironment, config: RunnerConfig): Promise<TestResult>;