skrypt-ai 0.1.0

package/dist/config/loader.js

@@ -0,0 +1,82 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+import { DEFAULT_CONFIG, PROVIDER_ENV_KEYS } from './types.js';
+const VALID_PROVIDERS = ['deepseek', 'openai', 'anthropic', 'google', 'ollama', 'openrouter'];
+const CONFIG_FILENAMES = ['.skrypt.yaml', '.skrypt.yml', 'skrypt.yaml', 'skrypt.yml'];
+export function findConfigFile(dir) {
+    for (const filename of CONFIG_FILENAMES) {
+        const filepath = join(dir, filename);
+        if (existsSync(filepath)) {
+            return filepath;
+        }
+    }
+    return null;
+}
+export function loadConfig(configPath) {
+    // If explicit path provided, use it
+    if (configPath) {
+        if (!existsSync(configPath)) {
+            throw new Error(`Config file not found: ${configPath}`);
+        }
+        return parseConfigFile(configPath);
+    }
+    // Otherwise look for config in current directory
+    const foundPath = findConfigFile(process.cwd());
+    if (foundPath) {
+        return parseConfigFile(foundPath);
+    }
+    // No config file, use defaults
+    return DEFAULT_CONFIG;
+}
+function parseConfigFile(filepath) {
+    const content = readFileSync(filepath, 'utf-8');
+    const parsed = yaml.load(content);
+    // Merge with defaults
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+}
+function mergeConfig(defaults, overrides) {
+    return {
+        version: overrides.version ?? defaults.version,
+        source: {
+            ...defaults.source,
+            ...overrides.source
+        },
+        output: {
+            ...defaults.output,
+            ...overrides.output
+        },
+        llm: {
+            ...defaults.llm,
+            ...overrides.llm
+        },
+        license: overrides.license ?? defaults.license
+    };
+}
+export function validateConfig(config) {
+    const errors = [];
+    if (config.version !== 1) {
+        errors.push(`Unsupported config version: ${config.version}`);
+    }
+    if (!config.source.path) {
+        errors.push('source.path is required');
+    }
+    if (!config.output.path) {
+        errors.push('output.path is required');
+    }
+    if (!VALID_PROVIDERS.includes(config.llm.provider)) {
+        errors.push(`Invalid LLM provider: ${config.llm.provider}. Valid: ${VALID_PROVIDERS.join(', ')}`);
+    }
+    return errors;
+}
+export function getRequiredEnvKey(provider) {
+    return PROVIDER_ENV_KEYS[provider] || null;
+}
+export function checkApiKey(provider) {
+    const envKey = PROVIDER_ENV_KEYS[provider];
+    // Ollama doesn't need an API key
+    if (!envKey) {
+        return { ok: true, envKey: null };
+    }
+    return { ok: !!process.env[envKey], envKey };
+}

package/dist/config/types.d.ts

@@ -0,0 +1,24 @@
+export interface SourceConfig {
+    path: string;
+    include?: string[];
+    exclude?: string[];
+}
+export type LLMProvider = 'deepseek' | 'openai' | 'anthropic' | 'google' | 'ollama' | 'openrouter';
+export interface LLMConfig {
+    provider: LLMProvider;
+    model: string;
+    baseUrl?: string;
+}
+export declare const PROVIDER_ENV_KEYS: Record<LLMProvider, string>;
+export declare const DEFAULT_MODELS: Record<LLMProvider, string>;
+export interface Config {
+    version: number;
+    source: SourceConfig;
+    output: {
+        path: string;
+        format: 'markdown' | 'mdx';
+    };
+    llm: LLMConfig;
+    license?: string;
+}
+export declare const DEFAULT_CONFIG: Config;

package/dist/config/types.js

@@ -0,0 +1,34 @@
+// Provider -> env var mapping
+export const PROVIDER_ENV_KEYS = {
+    deepseek: 'DEEPSEEK_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    anthropic: 'ANTHROPIC_API_KEY',
+    google: 'GOOGLE_API_KEY',
+    ollama: '', // No key needed for local
+    openrouter: 'OPENROUTER_API_KEY'
+};
+// Default models per provider
+export const DEFAULT_MODELS = {
+    deepseek: 'deepseek-v3',
+    openai: 'gpt-4.1',
+    anthropic: 'claude-sonnet-4-6',
+    google: 'gemini-2.5-flash',
+    ollama: 'qwen2.5-coder:32b',
+    openrouter: 'deepseek/deepseek-v3'
+};
+export const DEFAULT_CONFIG = {
+    version: 1,
+    source: {
+        path: './src',
+        include: ['**/*.py', '**/*.js', '**/*.ts', '**/*.go', '**/*.rs'],
+        exclude: ['**/node_modules/**', '**/__pycache__/**', '**/dist/**', '**/target/**']
+    },
+    output: {
+        path: './docs',
+        format: 'markdown'
+    },
+    llm: {
+        provider: 'deepseek',
+        model: 'deepseek-v3'
+    }
+};

package/dist/generator/generator.d.ts

@@ -0,0 +1,15 @@
+import { APIElement } from '../scanner/types.js';
+import { LLMClient } from '../llm/index.js';
+import { GeneratedDoc, GenerationOptions, GenerationProgress } from './types.js';
+/**
+ * Generate documentation for an API element (no testing)
+ */
+export declare function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>;
+/**
+ * Generate documentation for multiple elements
+ */
+export declare function generateForElements(elements: APIElement[], client: LLMClient, options: GenerationOptions): Promise<GeneratedDoc[]>;
+/**
+ * Format generated docs as markdown file content
+ */
+export declare function formatAsMarkdown(docs: GeneratedDoc[], title: string): string;

package/dist/generator/generator.js

@@ -0,0 +1,144 @@
+import { generateDocumentation } from '../llm/index.js';
+/**
+ * Build enhanced context for LLM from API element
+ */
+function buildElementContext(element) {
+    return {
+        kind: element.kind,
+        name: element.name,
+        signature: element.signature,
+        parameters: element.parameters,
+        returnType: element.returnType,
+        docstring: element.docstring,
+        parentClass: element.parentClass,
+        imports: element.imports,
+        packageName: element.packageName,
+        sourceContext: element.sourceContext,
+        filePath: element.filePath
+    };
+}
+/**
+ * Detect code language from file path
+ */
+function detectLanguageFromFile(filePath) {
+    if (filePath.endsWith('.py'))
+        return 'python';
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx'))
+        return 'typescript';
+    if (filePath.endsWith('.js') || filePath.endsWith('.jsx'))
+        return 'javascript';
+    if (filePath.endsWith('.go'))
+        return 'go';
+    if (filePath.endsWith('.rs'))
+        return 'rust';
+    return 'typescript';
+}
+/**
+ * Generate documentation for an API element (no testing)
+ */
+export async function generateForElement(element, client, options, onProgress) {
+    const report = (status) => {
+        onProgress?.({
+            current: 0,
+            total: 0,
+            element: element.name,
+            status
+        });
+    };
+    const codeLanguage = detectLanguageFromFile(element.filePath);
+    const useMultiLang = options.multiLanguage ?? false;
+    report('generating');
+    try {
+        const elementContext = buildElementContext(element);
+        const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang });
+        report('done');
+        return {
+            element,
+            markdown: result.markdown,
+            codeExample: result.codeExample,
+            codeLanguage,
+            typescriptExample: result.typescriptExample,
+            pythonExample: result.pythonExample
+        };
+    }
+    catch (err) {
+        report('failed');
+        return {
+            element,
+            markdown: '',
+            codeExample: '',
+            codeLanguage,
+            error: `Failed to generate: ${err}`
+        };
+    }
+}
+/**
+ * Generate documentation for multiple elements
+ */
+export async function generateForElements(elements, client, options) {
+    const results = [];
+    for (let i = 0; i < elements.length; i++) {
+        const element = elements[i];
+        if (!element)
+            continue;
+        const doc = await generateForElement(element, client, options, (progress) => {
+            options.onProgress?.({
+                ...progress,
+                current: i + 1,
+                total: elements.length
+            });
+        });
+        results.push(doc);
+    }
+    return results;
+}
+/**
+ * Format generated docs as markdown file content
+ */
+export function formatAsMarkdown(docs, title) {
+    let content = `# ${title}\n\n`;
+    const functions = docs.filter(d => d.element.kind === 'function');
+    const classes = docs.filter(d => d.element.kind === 'class');
+    const methods = docs.filter(d => d.element.kind === 'method');
+    if (functions.length > 0) {
+        content += '## Functions\n\n';
+        for (const doc of functions) {
+            content += formatDocSection(doc);
+        }
+    }
+    if (classes.length > 0) {
+        content += '## Classes\n\n';
+        for (const doc of classes) {
+            content += formatDocSection(doc);
+            const classMethods = methods.filter(m => m.element.parentClass === doc.element.name);
+            if (classMethods.length > 0) {
+                content += '### Methods\n\n';
+                for (const method of classMethods) {
+                    content += formatDocSection(method, '####');
+                }
+            }
+        }
+    }
+    return content;
+}
+function formatDocSection(doc, headingLevel = '###') {
+    let section = `${headingLevel} \`${doc.element.name}\`\n\n`;
+    section += `\`\`\`${doc.codeLanguage}\n${doc.element.signature}\n\`\`\`\n\n`;
+    if (doc.markdown) {
+        section += doc.markdown + '\n\n';
+    }
+    const hasMultiLang = doc.typescriptExample && doc.pythonExample;
+    if (hasMultiLang) {
+        section += '**Examples:**\n\n';
+        section += '<CodeGroup>\n\n';
+        section += `\`\`\`typescript example.ts\n${doc.typescriptExample}\n\`\`\`\n\n`;
+        section += `\`\`\`python example.py\n${doc.pythonExample}\n\`\`\`\n\n`;
+        section += '</CodeGroup>\n\n';
+    }
+    else if (doc.codeExample) {
+        section += '**Example:**\n\n';
+        const ext = doc.codeLanguage === 'typescript' ? 'ts' : doc.codeLanguage === 'python' ? 'py' : 'js';
+        section += `\`\`\`${doc.codeLanguage} example.${ext}\n${doc.codeExample}\n\`\`\`\n\n`;
+    }
+    return section;
+}

package/dist/generator/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './generator.js';
+export * from './writer.js';
+export * from './organizer.js';

package/dist/generator/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './generator.js';
+export * from './writer.js';
+export * from './organizer.js';

package/dist/generator/organizer.d.ts

@@ -0,0 +1,29 @@
+import { GeneratedDoc, Topic, TopicConfig, CrossReference, NavigationItem } from './types.js';
+/**
+ * Default topic configuration with common patterns
+ */
+export declare const DEFAULT_TOPIC_CONFIG: TopicConfig;
+/**
+ * Organize generated docs into topics
+ */
+export declare function organizeByTopic(docs: GeneratedDoc[], config?: TopicConfig): Topic[];
+/**
+ * Detect cross-references between elements
+ */
+export declare function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[];
+/**
+ * Get cross-references for a specific element
+ */
+export declare function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[];
+/**
+ * Build navigation structure from topics
+ */
+export declare function buildNavigation(topics: Topic[]): NavigationItem[];
+/**
+ * Generate a sidebar configuration (works with multiple doc platforms)
+ */
+export declare function generateSidebarConfig(topics: Topic[]): object;
+/**
+ * Merge user config with defaults
+ */
+export declare function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults?: TopicConfig): TopicConfig;

package/dist/generator/organizer.js

@@ -0,0 +1,222 @@
+/**
+ * Default topic configuration with common patterns
+ */
+export const DEFAULT_TOPIC_CONFIG = {
+    topics: {
+        'getting-started': { name: 'Getting Started', description: 'Quick start and setup guides', order: 0 },
+        'core': { name: 'Core API', description: 'Core functionality and main exports', order: 1 },
+        'middleware': { name: 'Middleware', description: 'Request/response middleware and handlers', order: 2 },
+        'memory': { name: 'Memory & Storage', description: 'Memory management and persistence', order: 3 },
+        'tools': { name: 'Tools & Utilities', description: 'Helper functions and utilities', order: 4 },
+        'types': { name: 'Types & Interfaces', description: 'Type definitions and interfaces', order: 5 },
+        'integrations': { name: 'Integrations', description: 'Third-party integrations', order: 6 },
+        'advanced': { name: 'Advanced', description: 'Advanced usage and configuration', order: 7 },
+        'other': { name: 'Other', description: 'Miscellaneous utilities', order: 99 }
+    },
+    rules: [
+        // File path patterns
+        { topic: 'middleware', patterns: ['**/middleware*', '**/handler*'] },
+        { topic: 'memory', patterns: ['**/memory*', '**/store*', '**/persist*', '**/cache*'] },
+        { topic: 'tools', patterns: ['**/tool*', '**/util*', '**/helper*', '**/shared*'] },
+        { topic: 'types', patterns: ['**/types*', '**/interface*', '**/schema*'] },
+        { topic: 'core', patterns: ['**/index*', '**/main*', '**/core*', '**/client*'] },
+        { topic: 'integrations', patterns: ['**/openai*', '**/anthropic*', '**/vercel*', '**/mastra*'] },
+        // Function name patterns
+        { topic: 'middleware', namePatterns: ['^create.*Handler$', '^.*Middleware$', '^wrap.*$'] },
+        { topic: 'memory', namePatterns: ['^save.*Memory', '^get.*Memory', '^.*Memory$', '^store.*$', '^persist.*$'] },
+        { topic: 'tools', namePatterns: ['^create.*Tool$', '^.*Tool$', '^use.*$'] },
+        // Element kinds
+        { topic: 'types', kinds: ['interface', 'type'] }
+    ],
+    defaultTopic: 'other'
+};
+/**
+ * Organize generated docs into topics
+ */
+export function organizeByTopic(docs, config = DEFAULT_TOPIC_CONFIG) {
+    const topicDocs = new Map();
+    // Initialize all topics
+    for (const topicId of Object.keys(config.topics)) {
+        topicDocs.set(topicId, []);
+    }
+    // Categorize each doc
+    for (const doc of docs) {
+        const topicId = inferTopic(doc, config);
+        if (!topicDocs.has(topicId)) {
+            topicDocs.set(topicId, []);
+        }
+        topicDocs.get(topicId).push(doc);
+    }
+    // Build topic objects
+    const topics = [];
+    for (const [topicId, topicDocList] of topicDocs.entries()) {
+        if (topicDocList.length === 0)
+            continue;
+        const topicConfig = config.topics[topicId] || { name: titleCase(topicId), order: 50 };
+        topics.push({
+            id: topicId,
+            name: topicConfig.name,
+            description: topicConfig.description,
+            order: topicConfig.order ?? 50,
+            docs: sortDocsWithinTopic(topicDocList)
+        });
+    }
+    // Sort topics by order
+    return topics.sort((a, b) => a.order - b.order);
+}
+/**
+ * Infer the topic for a doc based on rules
+ */
+function inferTopic(doc, config) {
+    const { element } = doc;
+    for (const rule of config.rules) {
+        // Check file path patterns
+        if (rule.patterns) {
+            for (const pattern of rule.patterns) {
+                if (matchGlobPattern(element.filePath, pattern)) {
+                    return rule.topic;
+                }
+            }
+        }
+        // Check name patterns
+        if (rule.namePatterns) {
+            for (const pattern of rule.namePatterns) {
+                if (new RegExp(pattern, 'i').test(element.name)) {
+                    return rule.topic;
+                }
+            }
+        }
+        // Check element kinds
+        if (rule.kinds && rule.kinds.includes(element.kind)) {
+            return rule.topic;
+        }
+    }
+    return config.defaultTopic || 'other';
+}
+/**
+ * Simple glob pattern matching
+ */
+function matchGlobPattern(path, pattern) {
+    // Convert glob to regex
+    const regex = pattern
+        .replace(/\*\*/g, '___DOUBLESTAR___')
+        .replace(/\*/g, '[^/]*')
+        .replace(/___DOUBLESTAR___/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(regex, 'i').test(path);
+}
+/**
+ * Sort docs within a topic by importance
+ */
+function sortDocsWithinTopic(docs) {
+    return docs.sort((a, b) => {
+        // Classes first, then functions, then methods
+        const kindOrder = { class: 0, function: 1, method: 2 };
+        const aKind = kindOrder[a.element.kind] ?? 3;
+        const bKind = kindOrder[b.element.kind] ?? 3;
+        if (aKind !== bKind)
+            return aKind - bKind;
+        // Then by name
+        return a.element.name.localeCompare(b.element.name);
+    });
+}
+/**
+ * Detect cross-references between elements
+ */
+export function detectCrossReferences(docs) {
+    const refs = [];
+    const elementNames = new Set(docs.map(d => d.element.name));
+    for (const doc of docs) {
+        const { element } = doc;
+        // Check source context for references to other elements
+        const sourceContext = element.sourceContext || '';
+        const signature = element.signature || '';
+        for (const otherName of elementNames) {
+            if (otherName === element.name)
+                continue;
+            // Check if this element uses another element
+            if (sourceContext.includes(otherName) || signature.includes(otherName)) {
+                refs.push({
+                    fromElement: element.name,
+                    toElement: otherName,
+                    relationship: 'uses'
+                });
+            }
+        }
+        // Methods reference their parent class
+        if (element.parentClass && elementNames.has(element.parentClass)) {
+            refs.push({
+                fromElement: element.name,
+                toElement: element.parentClass,
+                relationship: 'related'
+            });
+        }
+    }
+    // Add reverse references (used-by)
+    const usesRefs = refs.filter(r => r.relationship === 'uses');
+    for (const ref of usesRefs) {
+        refs.push({
+            fromElement: ref.toElement,
+            toElement: ref.fromElement,
+            relationship: 'used-by'
+        });
+    }
+    return refs;
+}
+/**
+ * Get cross-references for a specific element
+ */
+export function getCrossRefsForElement(elementName, allRefs) {
+    return allRefs.filter(r => r.fromElement === elementName);
+}
+/**
+ * Build navigation structure from topics
+ */
+export function buildNavigation(topics) {
+    return topics.map(topic => ({
+        title: topic.name,
+        path: `/${topic.id}`,
+        children: topic.docs.map(doc => ({
+            title: doc.element.name,
+            path: `/${topic.id}#${slugify(doc.element.name)}`
+        }))
+    }));
+}
+/**
+ * Generate a sidebar configuration (works with multiple doc platforms)
+ */
+export function generateSidebarConfig(topics) {
+    return {
+        navigation: topics.map(topic => ({
+            group: topic.name,
+            pages: topic.docs.map(doc => `${topic.id}/${slugify(doc.element.name)}`)
+        }))
+    };
+}
+/**
+ * Convert string to title case
+ */
+function titleCase(str) {
+    return str
+        .replace(/-/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+/**
+ * Convert string to URL-safe slug
+ */
+function slugify(str) {
+    return str
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Merge user config with defaults
+ */
+export function mergeTopicConfig(userConfig, defaults = DEFAULT_TOPIC_CONFIG) {
+    return {
+        topics: { ...defaults.topics, ...userConfig.topics },
+        rules: [...defaults.rules, ...(userConfig.rules || [])],
+        defaultTopic: userConfig.defaultTopic ?? defaults.defaultTopic
+    };
+}

package/dist/generator/types.d.ts

@@ -0,0 +1,83 @@
+import { APIElement } from '../scanner/types.js';
+/**
+ * Generated documentation for an API element
+ */
+export interface GeneratedDoc {
+    element: APIElement;
+    markdown: string;
+    codeExample: string;
+    codeLanguage: string;
+    error?: string;
+    typescriptExample?: string;
+    pythonExample?: string;
+}
+/**
+ * Progress callback for generation
+ */
+export interface GenerationProgress {
+    current: number;
+    total: number;
+    element: string;
+    status: 'generating' | 'done' | 'failed';
+}
+/**
+ * Options for generation
+ */
+export interface GenerationOptions {
+    onProgress?: (progress: GenerationProgress) => void;
+    multiLanguage?: boolean;
+}
+/**
+ * Result of generating docs for a file
+ */
+export interface FileGenerationResult {
+    filePath: string;
+    docs: GeneratedDoc[];
+}
+/**
+ * A topic groups related API elements by concept
+ */
+export interface Topic {
+    id: string;
+    name: string;
+    description?: string;
+    order: number;
+    docs: GeneratedDoc[];
+}
+/**
+ * Topic mapping rule for auto-categorization
+ */
+export interface TopicRule {
+    topic: string;
+    patterns?: string[];
+    namePatterns?: string[];
+    kinds?: string[];
+}
+/**
+ * Topic configuration
+ */
+export interface TopicConfig {
+    topics: Record<string, {
+        name: string;
+        description?: string;
+        order?: number;
+    }>;
+    rules: TopicRule[];
+    defaultTopic?: string;
+}
+/**
+ * Navigation structure for generated docs
+ */
+export interface NavigationItem {
+    title: string;
+    path: string;
+    children?: NavigationItem[];
+}
+/**
+ * Cross-reference between elements
+ */
+export interface CrossReference {
+    fromElement: string;
+    toElement: string;
+    relationship: 'uses' | 'used-by' | 'see-also' | 'related';
+}

package/dist/generator/types.js

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

package/dist/generator/writer.d.ts

@@ -0,0 +1,28 @@
+import { GeneratedDoc, FileGenerationResult, Topic } from './types.js';
+/**
+ * Generate llms.txt file (Answer Engine Optimization)
+ * Format follows https://llmstxt.org convention
+ */
+export declare function writeLlmsTxt(docs: GeneratedDoc[], outputDir: string, options?: {
+    projectName?: string;
+    description?: string;
+}): Promise<void>;
+/**
+ * Write generated docs to output directory
+ */
+export declare function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string): Promise<{
+    filesWritten: number;
+    totalDocs: number;
+}>;
+/**
+ * Group generated docs by file
+ */
+export declare function groupDocsByFile(docs: GeneratedDoc[]): FileGenerationResult[];
+/**
+ * Write docs organized by topic
+ */
+export declare function writeDocsByTopic(docs: GeneratedDoc[], outputDir: string): Promise<{
+    filesWritten: number;
+    totalDocs: number;
+    topics: Topic[];
+}>;