skrypt-ai 0.6.1 → 0.8.0

package/dist/scanner/ruby.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'fs';
+import { splitParams, getLineNumber, getSourceContext } from './utils.js';
 /**
  * Scanner for Ruby source files
  * Extracts: classes, modules, methods (public only)
@@ -86,7 +87,7 @@ export class RubyScanner {
             if (!name)
                 continue;
             const superclass = match[2] ?? '';
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const docstring = this.getDocComment(lines, lineNumber - 1);
             const signature = superclass
                 ? `class ${name} < ${superclass}`
@@ -103,7 +104,7 @@ export class RubyScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber, 15)
+                sourceContext: getSourceContext(lines, lineNumber, 15)
             });
         }
     }
@@ -119,7 +120,7 @@ export class RubyScanner {
                 continue;
             // Only emit modules that contain constants (FOO = ...) and do NOT
             // contain class/def definitions — i.e. "leaf" modules.
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const body = this.getModuleBody(source, match.index);
             if (body === null)
                 continue;
@@ -140,7 +141,7 @@ export class RubyScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber, 15)
+                sourceContext: getSourceContext(lines, lineNumber, 15)
             });
         }
     }
@@ -190,7 +191,7 @@ export class RubyScanner {
             // Skip initialize (constructor internals)
             if (name === 'initialize')
                 continue;
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             // Check visibility — skip private / protected
             const visibility = visibilityMap.get(lineNumber);
             if (visibility === 'private' || visibility === 'protected')
@@ -223,7 +224,7 @@ export class RubyScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber)
+                sourceContext: getSourceContext(lines, lineNumber)
             });
         }
     }
@@ -305,7 +306,7 @@ export class RubyScanner {
         if (!paramsStr.trim())
             return [];
         const params = [];
-        const parts = this.splitParams(paramsStr);
+        const parts = splitParams(paramsStr);
         for (const part of parts) {
             const trimmed = part.trim();
             if (!trimmed)
@@ -348,26 +349,6 @@ export class RubyScanner {
         }
         return params;
     }
-    splitParams(str) {
-        const parts = [];
-        let depth = 0;
-        let current = '';
-        for (const char of str) {
-            if (char === '(' || char === '[' || char === '{')
-                depth++;
-            else if (char === ')' || char === ']' || char === '}')
-                depth--;
-            else if (char === ',' && depth === 0) {
-                parts.push(current);
-                current = '';
-                continue;
-            }
-            current += char;
-        }
-        if (current.trim())
-            parts.push(current);
-        return parts;
-    }
     // ---------------------------------------------------------------------------
     // Doc comments (YARD and plain #)
     // ---------------------------------------------------------------------------
@@ -417,15 +398,4 @@ export class RubyScanner {
         }
         return undefined;
     }
-    // ---------------------------------------------------------------------------
-    // Helpers
-    // ---------------------------------------------------------------------------
-    getLineNumber(source, index) {
-        return source.slice(0, index).split('\n').length;
-    }
-    getSourceContext(lines, lineNumber, context = 5) {
-        const start = Math.max(0, lineNumber - context - 1);
-        const end = Math.min(lines.length, lineNumber + context);
-        return lines.slice(start, end).join('\n');
-    }
 }

package/dist/scanner/rust.d.ts

@@ -16,8 +16,5 @@ export declare class RustScanner implements Scanner {
     private extractImplMethods;
     private extractBlock;
     private parseRustParams;
-    private splitParams;
-    private getLineNumber;
     private getDocComment;
-    private getSourceContext;
 }

package/dist/scanner/rust.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'fs';
+import { splitParams, getLineNumber, getSourceContext } from './utils.js';
 /**
  * Scanner for Rust source files
  * Extracts: pub functions, pub structs, pub enums, impl blocks, traits
@@ -72,7 +73,7 @@ export class RustScanner {
             const generics = match[4] || '';
             const paramsStr = match[5];
             const returnPart = match[6]?.trim() || '';
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const docstring = this.getDocComment(lines, lineNumber - 1);
             const parameters = this.parseRustParams(paramsStr);
             const returnType = returnPart ? returnPart.replace(/^->\s*/, '').trim() : undefined;
@@ -92,7 +93,7 @@ export class RustScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber)
+                sourceContext: getSourceContext(lines, lineNumber)
             });
         }
     }
@@ -110,7 +111,7 @@ export class RustScanner {
             const kind = match[1];
             const name = match[2];
             const generics = match[3] || '';
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const docstring = this.getDocComment(lines, lineNumber - 1);
             const signature = `pub ${kind} ${name}${generics}`;
             elements.push({
@@ -125,7 +126,7 @@ export class RustScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber, 20)
+                sourceContext: getSourceContext(lines, lineNumber, 20)
             });
         }
     }
@@ -136,7 +137,7 @@ export class RustScanner {
         while ((match = traitRegex.exec(source)) !== null) {
             const name = match[1];
             const generics = match[2] || '';
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const docstring = this.getDocComment(lines, lineNumber - 1);
             const signature = `pub trait ${name}${generics}`;
             elements.push({
@@ -151,7 +152,7 @@ export class RustScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber, 15)
+                sourceContext: getSourceContext(lines, lineNumber, 15)
             });
         }
     }
@@ -180,7 +181,7 @@ export class RustScanner {
                 const returnPart = methodMatch[5]?.trim() || '';
                 const bodyIndex = implBody.indexOf(methodMatch[0]);
                 const fullIndex = implStart + implMatch[0].length + bodyIndex;
-                const lineNumber = this.getLineNumber(source, fullIndex);
+                const lineNumber = getLineNumber(source, fullIndex);
                 const docstring = this.getDocComment(lines, lineNumber - 1);
                 const parameters = this.parseRustParams(paramsStr);
                 const returnType = returnPart ? returnPart.replace(/^->\s*/, '').trim() : undefined;
@@ -201,7 +202,7 @@ export class RustScanner {
                     isPublic: true,
                     imports,
                     packageName,
-                    sourceContext: this.getSourceContext(lines, lineNumber)
+                    sourceContext: getSourceContext(lines, lineNumber)
                 });
             }
         }
@@ -230,7 +231,7 @@ export class RustScanner {
         if (!paramsStr.trim())
             return [];
         const params = [];
-        const parts = this.splitParams(paramsStr);
+        const parts = splitParams(paramsStr);
         for (const part of parts) {
             const trimmed = part.trim();
             if (!trimmed)
@@ -250,29 +251,6 @@ export class RustScanner {
         }
         return params;
     }
-    splitParams(str) {
-        const parts = [];
-        let depth = 0;
-        let current = '';
-        for (const char of str) {
-            if (char === '<' || char === '(' || char === '[' || char === '{')
-                depth++;
-            else if (char === '>' || char === ')' || char === ']' || char === '}')
-                depth--;
-            else if (char === ',' && depth === 0) {
-                parts.push(current);
-                current = '';
-                continue;
-            }
-            current += char;
-        }
-        if (current.trim())
-            parts.push(current);
-        return parts;
-    }
-    getLineNumber(source, index) {
-        return source.slice(0, index).split('\n').length;
-    }
     getDocComment(lines, lineIndex) {
         const comments = [];
         let i = lineIndex - 1;
@@ -296,9 +274,4 @@ export class RustScanner {
         }
         return comments.length > 0 ? comments.join('\n') : undefined;
     }
-    getSourceContext(lines, lineNumber, context = 5) {
-        const start = Math.max(0, lineNumber - context - 1);
-        const end = Math.min(lines.length, lineNumber + context);
-        return lines.slice(start, end).join('\n');
-    }
 }

package/dist/scanner/swift.d.ts

@@ -18,8 +18,5 @@ export declare class SwiftScanner implements Scanner {
     private extractBlock;
     private parseSwiftParams;
     private findDefaultValueSplit;
-    private splitParams;
-    private getLineNumber;
     private getDocComment;
-    private getSourceContext;
 }

package/dist/scanner/swift.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'fs';
+import { splitParams, getLineNumber, getSourceContext } from './utils.js';
 /**
  * Scanner for Swift source files
  * Extracts: public/open classes, structs, enums, protocols, actors, functions, methods
@@ -72,7 +73,7 @@ export class SwiftScanner {
             const name = match[3];
             if (!access || !kind || !name)
                 continue;
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const docstring = this.getDocComment(lines, lineNumber - 1);
             const signature = `${access} ${kind} ${name}`;
             elements.push({
@@ -87,7 +88,7 @@ export class SwiftScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber, 15)
+                sourceContext: getSourceContext(lines, lineNumber, 15)
             });
         }
     }
@@ -143,7 +144,7 @@ export class SwiftScanner {
             if (!access || !name)
                 continue;
             // Check if this is at the top level (not indented)
-            const lineNumber = this.getLineNumber(source, match.index);
+            const lineNumber = getLineNumber(source, match.index);
             const lineContent = lines[lineNumber - 1];
             if (!lineContent || /^\s+/.test(lineContent))
                 continue;
@@ -169,7 +170,7 @@ export class SwiftScanner {
                 isPublic: true,
                 imports,
                 packageName,
-                sourceContext: this.getSourceContext(lines, lineNumber)
+                sourceContext: getSourceContext(lines, lineNumber)
             });
         }
     }
@@ -202,7 +203,7 @@ export class SwiftScanner {
                 // Calculate line number relative to the full source
                 const bodyOffset = blockStart + 1;
                 const fullIndex = bodyOffset + methodMatch.index;
-                const lineNumber = this.getLineNumber(source, fullIndex);
+                const lineNumber = getLineNumber(source, fullIndex);
                 const docstring = this.getDocComment(lines, lineNumber - 1);
                 const parameters = this.parseSwiftParams(paramsStr);
                 const signature = this.buildSignature(access, name, paramsStr, isAsync, isThrows, isRethrows, returnType);
@@ -221,7 +222,7 @@ export class SwiftScanner {
                     isPublic: true,
                     imports,
                     packageName,
-                    sourceContext: this.getSourceContext(lines, lineNumber)
+                    sourceContext: getSourceContext(lines, lineNumber)
                 });
             }
         }
@@ -262,7 +263,7 @@ export class SwiftScanner {
         if (!paramsStr.trim())
             return [];
         const params = [];
-        const parts = this.splitParams(paramsStr);
+        const parts = splitParams(paramsStr);
         for (const part of parts) {
             const trimmed = part.trim();
             if (!trimmed)
@@ -316,29 +317,6 @@ export class SwiftScanner {
         }
         return -1;
     }
-    splitParams(str) {
-        const parts = [];
-        let depth = 0;
-        let current = '';
-        for (const char of str) {
-            if (char === '<' || char === '(' || char === '[' || char === '{')
-                depth++;
-            else if (char === '>' || char === ')' || char === ']' || char === '}')
-                depth--;
-            else if (char === ',' && depth === 0) {
-                parts.push(current);
-                current = '';
-                continue;
-            }
-            current += char;
-        }
-        if (current.trim())
-            parts.push(current);
-        return parts;
-    }
-    getLineNumber(source, index) {
-        return source.slice(0, index).split('\n').length;
-    }
     getDocComment(lines, lineIndex) {
         const comments = [];
         let i = lineIndex - 1;
@@ -384,9 +362,4 @@ export class SwiftScanner {
         }
         return comments.length > 0 ? comments.join('\n') : undefined;
     }
-    getSourceContext(lines, lineNumber, context = 5) {
-        const start = Math.max(0, lineNumber - context - 1);
-        const end = Math.min(lines.length, lineNumber + context);
-        return lines.slice(start, end).join('\n');
-    }
 }

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/scanner/utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared utility functions for language scanners.
+ *
+ * These helpers are used identically (or near-identically) across
+ * multiple scanner implementations. Centralising them here avoids
+ * duplicated code and makes future fixes apply everywhere at once.
+ */
+/**
+ * Split a parameter string by commas while respecting nested brackets.
+ * Handles: `<>`, `()`, `[]`, `{}`
+ *
+ * Used by: Java, C#, Swift, Kotlin, PHP, Rust, Ruby scanners.
+ */
+export declare function splitParams(str: string): string[];
+/**
+ * Split a parameter string by commas, respecting `()`, `[]`, `{}`
+ * but NOT `<>`.  Go is the only scanner that uses this variant because
+ * Go has no angle-bracket generics in parameter lists.
+ */
+export declare function splitParamsNoAngleBrackets(str: string): string[];
+/**
+ * Convert a character-index in `source` to a 1-based line number.
+ *
+ * Used by every regex-based scanner.
+ */
+export declare function getLineNumber(source: string, index: number): number;
+/**
+ * Return a few lines of source context around `lineNumber` (1-based).
+ *
+ * @param lines   - Pre-split source lines (`source.split('\n')`)
+ * @param lineNumber - 1-based line number of the declaration
+ * @param context - Number of lines to include before and after (default 5)
+ */
+export declare function getSourceContext(lines: string[], lineNumber: number, context?: number): string;
+/**
+ * Starting at the opening `{` at `openIndex`, find its matching `}`.
+ * Returns the index of the closing brace, or -1 if not found.
+ *
+ * Used by: Java, C#, PHP scanners (for class-range detection).
+ */
+export declare function findMatchingBrace(source: string, openIndex: number): number;

package/dist/scanner/utils.js

@@ -0,0 +1,97 @@
+/**
+ * Shared utility functions for language scanners.
+ *
+ * These helpers are used identically (or near-identically) across
+ * multiple scanner implementations. Centralising them here avoids
+ * duplicated code and makes future fixes apply everywhere at once.
+ */
+/**
+ * Split a parameter string by commas while respecting nested brackets.
+ * Handles: `<>`, `()`, `[]`, `{}`
+ *
+ * Used by: Java, C#, Swift, Kotlin, PHP, Rust, Ruby scanners.
+ */
+export function splitParams(str) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of str) {
+        if (char === '<' || char === '(' || char === '[' || char === '{')
+            depth++;
+        else if (char === '>' || char === ')' || char === ']' || char === '}')
+            depth--;
+        else if (char === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim())
+        parts.push(current);
+    return parts;
+}
+/**
+ * Split a parameter string by commas, respecting `()`, `[]`, `{}`
+ * but NOT `<>`.  Go is the only scanner that uses this variant because
+ * Go has no angle-bracket generics in parameter lists.
+ */
+export function splitParamsNoAngleBrackets(str) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of str) {
+        if (char === '(' || char === '[' || char === '{')
+            depth++;
+        else if (char === ')' || char === ']' || char === '}')
+            depth--;
+        else if (char === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim())
+        parts.push(current);
+    return parts;
+}
+/**
+ * Convert a character-index in `source` to a 1-based line number.
+ *
+ * Used by every regex-based scanner.
+ */
+export function getLineNumber(source, index) {
+    return source.slice(0, index).split('\n').length;
+}
+/**
+ * Return a few lines of source context around `lineNumber` (1-based).
+ *
+ * @param lines   - Pre-split source lines (`source.split('\n')`)
+ * @param lineNumber - 1-based line number of the declaration
+ * @param context - Number of lines to include before and after (default 5)
+ */
+export function getSourceContext(lines, lineNumber, context = 5) {
+    const start = Math.max(0, lineNumber - context - 1);
+    const end = Math.min(lines.length, lineNumber + context);
+    return lines.slice(start, end).join('\n');
+}
+/**
+ * Starting at the opening `{` at `openIndex`, find its matching `}`.
+ * Returns the index of the closing brace, or -1 if not found.
+ *
+ * Used by: Java, C#, PHP scanners (for class-range detection).
+ */
+export function findMatchingBrace(source, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < source.length; i++) {
+        if (source[i] === '{')
+            depth++;
+        else if (source[i] === '}') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}

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>;