skrypt-ai 0.5.0 → 0.6.0

package/dist/llm/openai-client.js

@@ -9,14 +9,19 @@ export class OpenAICompatibleClient {
     client;
     model;
     maxRetries;
+    apiKey;
     constructor(config) {
         this.provider = config.provider;
         this.model = config.model;
         this.maxRetries = config.maxRetries ?? 3;
         const baseURL = config.baseUrl || PROVIDER_BASE_URLS[config.provider];
         const extraHeaders = PROVIDER_EXTRA_HEADERS[config.provider] || {};
+        // Ollama doesn't need a real key; other providers get empty string
+        // (SDK validates on first request, not construction)
+        const effectiveKey = config.apiKey || (config.provider === 'ollama' ? 'ollama' : 'not-set');
+        this.apiKey = effectiveKey;
         this.client = new OpenAI({
-            apiKey: config.apiKey || 'ollama', // Ollama doesn't need a real key
+            apiKey: effectiveKey,
             baseURL,
             timeout: config.timeout ?? 60000,
             maxRetries: this.maxRetries,
@@ -24,7 +29,7 @@ export class OpenAICompatibleClient {
         });
     }
     isConfigured() {
-        return true; // OpenAI SDK handles validation
+        return this.apiKey !== '' && this.apiKey !== 'not-set';
     }
     async complete(request) {
         const model = request.model || this.model;

package/dist/qa/checks.d.ts

@@ -0,0 +1,10 @@
+import type { QAIssue } from './types.js';
+export declare function checkFrontmatter(filePath: string, content: string, relPath: string): QAIssue[];
+export declare function checkHeadings(content: string, relPath: string): QAIssue[];
+export declare function checkCodeBlocks(content: string, relPath: string): QAIssue[];
+export declare function checkComponents(content: string, relPath: string): QAIssue[];
+export declare function checkLinks(content: string, relPath: string, _allFiles: Set<string>): QAIssue[];
+export declare function checkSecurity(content: string, relPath: string): QAIssue[];
+export declare function checkContentQuality(content: string, relPath: string): QAIssue[];
+export declare function checkScreenshots(content: string, relPath: string, outputDir: string): QAIssue[];
+export declare function checkMdxSyntax(content: string, relPath: string): QAIssue[];

package/dist/qa/checks.js

@@ -0,0 +1,492 @@
+import { existsSync, statSync } from 'fs';
+import { join } from 'path';
+// ── Registered MDX components (must match template/src/components/mdx/index.tsx) ──
+const KNOWN_COMPONENTS = new Set([
+    'Card', 'CardGroup', 'Tabs', 'TabList', 'Tab', 'TabPanel',
+    'CodeGroup', 'CodeBlock', 'HighlightedCode',
+    'Callout', 'Info', 'Warning', 'Success', 'Error', 'Tip', 'Note',
+    'Accordion', 'AccordionGroup', 'Steps', 'Step',
+    'H1', 'H2', 'H3', 'H4',
+    'ParamTable', 'Schema', 'Mermaid',
+    'LinkPreview', 'Changelog', 'ChangelogEntry', 'Change',
+    'Tooltip', 'Frame', 'DarkImage',
+    'MethodBadge', 'StatusBadge', 'Endpoint',
+    'CodePlayground', 'PythonPlayground', 'GoPlayground',
+    'Screenshot',
+    // Passthrough components (handled but rendered as fragments)
+    'TabItem', 'Details',
+]);
+// ── Check: Frontmatter ──
+export function checkFrontmatter(filePath, content, relPath) {
+    const issues = [];
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!fmMatch) {
+        issues.push({
+            file: relPath,
+            line: 1,
+            severity: 'warning',
+            check: 'frontmatter',
+            message: 'Missing frontmatter (title and description recommended)',
+        });
+        return issues;
+    }
+    const fm = fmMatch[1];
+    if (!/^title\s*:/m.test(fm)) {
+        issues.push({
+            file: relPath,
+            line: 1,
+            severity: 'warning',
+            check: 'frontmatter',
+            message: 'Missing "title" in frontmatter',
+        });
+    }
+    return issues;
+}
+// ── Check: Heading structure ──
+export function checkHeadings(content, relPath) {
+    const issues = [];
+    const lines = content.split('\n');
+    let h1Count = 0;
+    let lastLevel = 0;
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        const headingMatch = line.match(/^(#{1,6})\s+/);
+        if (!headingMatch)
+            continue;
+        const level = headingMatch[1].length;
+        const lineNum = i + 1;
+        if (level === 1) {
+            h1Count++;
+            if (h1Count > 1) {
+                issues.push({
+                    file: relPath,
+                    line: lineNum,
+                    severity: 'warning',
+                    check: 'headings',
+                    message: 'Multiple h1 headings found (only one recommended)',
+                });
+            }
+        }
+        if (lastLevel > 0 && level > lastLevel + 1) {
+            issues.push({
+                file: relPath,
+                line: lineNum,
+                severity: 'warning',
+                check: 'headings',
+                message: `Heading level skipped: h${lastLevel} → h${level} (should increment by 1)`,
+            });
+        }
+        lastLevel = level;
+    }
+    return issues;
+}
+// ── Check: Code blocks ──
+export function checkCodeBlocks(content, relPath) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    let codeBlockStart = 0;
+    let codeBlockLines = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            if (!inCodeBlock) {
+                inCodeBlock = true;
+                codeBlockStart = i + 1;
+                const codeBlockLang = line.slice(3).trim().split(/\s/)[0] || '';
+                codeBlockLines = 0;
+                if (!codeBlockLang) {
+                    issues.push({
+                        file: relPath,
+                        line: codeBlockStart,
+                        severity: 'info',
+                        check: 'code-blocks',
+                        message: 'Code block missing language specifier',
+                    });
+                }
+            }
+            else {
+                inCodeBlock = false;
+                if (codeBlockLines === 0) {
+                    issues.push({
+                        file: relPath,
+                        line: codeBlockStart,
+                        severity: 'warning',
+                        check: 'code-blocks',
+                        message: 'Empty code block',
+                    });
+                }
+            }
+        }
+        else if (inCodeBlock) {
+            codeBlockLines++;
+        }
+    }
+    if (inCodeBlock) {
+        issues.push({
+            file: relPath,
+            line: codeBlockStart,
+            severity: 'error',
+            check: 'code-blocks',
+            message: 'Unclosed code block (missing closing ```)',
+        });
+    }
+    return issues;
+}
+// TypeScript/generic types that look like JSX components but aren't
+const TYPE_NAMES = new Set([
+    'T', 'K', 'V', 'U', 'R', 'P', 'S', 'E', // Single-letter generics
+    'Map', 'Set', 'Array', 'Record', 'Promise', 'Partial', 'Required',
+    'Readonly', 'Pick', 'Omit', 'Extract', 'Exclude', 'NonNullable',
+    'ReturnType', 'InstanceType', 'Parameters', 'ConstructorParameters',
+    'Function', 'Object', 'String', 'Number', 'Boolean', 'Symbol', 'RegExp',
+    'Date', 'Error', 'TypeError', 'RangeError', 'Buffer', 'Uint8Array',
+]);
+// ── Check: Components ──
+export function checkComponents(content, relPath) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Find JSX component tags (PascalCase) that look like MDX usage
+        // Only flag tags that appear at the start of a line or as standalone JSX
+        // Skip tags that look like TypeScript generics (inside backticks, followed by >)
+        const componentMatches = line.matchAll(/<([A-Z][A-Za-z0-9]*)\s*/g);
+        for (const match of componentMatches) {
+            const component = match[1];
+            // Skip known components
+            if (KNOWN_COMPONENTS.has(component))
+                continue;
+            // Skip TypeScript type names (generics, built-in types)
+            if (TYPE_NAMES.has(component))
+                continue;
+            // Skip if it looks like a TypeScript generic (e.g., "Promise<FixResult>" or "`Map<string>`")
+            // Check if the tag is inside backticks or follows a type-like pattern
+            const beforeTag = line.slice(0, match.index);
+            if (beforeTag.includes('`') || /\w$/.test(beforeTag))
+                continue;
+            // Skip if preceded by common TypeScript patterns
+            if (/:\s*$|=>\s*$|\|\s*$|&\s*$/.test(beforeTag))
+                continue;
+            // Skip if it ends with > immediately (like "Result>" part of "SomeType<Result>")
+            const afterTag = line.slice((match.index || 0) + match[0].length);
+            if (/^[A-Za-z0-9_,\s]*>/.test(afterTag) && !afterTag.startsWith('>'))
+                continue;
+            issues.push({
+                file: relPath,
+                line: i + 1,
+                severity: 'error',
+                check: 'components',
+                message: `Unknown component <${component}> — not registered in MDX component map`,
+            });
+        }
+    }
+    return issues;
+}
+// ── Check: Internal links ──
+export function checkLinks(content, relPath, _allFiles) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Markdown links
+        const linkMatches = line.matchAll(/\[([^\]]*)\]\(([^)]+)\)/g);
+        for (const match of linkMatches) {
+            const linkText = match[1];
+            const href = match[2];
+            // Skip external links
+            if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('mailto:'))
+                continue;
+            // Skip hash-only links (same-page anchors)
+            if (href.startsWith('#'))
+                continue;
+            // Empty link text
+            if (!linkText.trim()) {
+                issues.push({
+                    file: relPath,
+                    line: i + 1,
+                    severity: 'warning',
+                    check: 'links',
+                    message: `Empty link text for href="${href}"`,
+                });
+            }
+        }
+        // Image alt text
+        const imgMatches = line.matchAll(/!\[([^\]]*)\]\(/g);
+        for (const match of imgMatches) {
+            if (!match[1].trim()) {
+                issues.push({
+                    file: relPath,
+                    line: i + 1,
+                    severity: 'warning',
+                    check: 'links',
+                    message: 'Image missing alt text',
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ── Check: Security ──
+export function checkSecurity(content, relPath) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Raw <script> tags (outside code blocks)
+        if (/<script[\s>]/i.test(line)) {
+            issues.push({
+                file: relPath,
+                line: i + 1,
+                severity: 'error',
+                check: 'security',
+                message: 'Raw <script> tag found — potential XSS risk',
+            });
+        }
+        // javascript: URLs
+        if (/href\s*=\s*["']javascript:/i.test(line)) {
+            issues.push({
+                file: relPath,
+                line: i + 1,
+                severity: 'error',
+                check: 'security',
+                message: 'javascript: URL found — XSS risk',
+            });
+        }
+        // onclick and other event handlers
+        if (/\s+on\w+\s*=\s*["']/i.test(line) && !inCodeBlock) {
+            issues.push({
+                file: relPath,
+                line: i + 1,
+                severity: 'error',
+                check: 'security',
+                message: 'Inline event handler found — potential XSS risk',
+            });
+        }
+        // Iframe without sandbox
+        if (/<iframe\s/i.test(line) && !/sandbox/i.test(line)) {
+            issues.push({
+                file: relPath,
+                line: i + 1,
+                severity: 'warning',
+                check: 'security',
+                message: '<iframe> without sandbox attribute',
+            });
+        }
+    }
+    return issues;
+}
+// ── Check: Content quality ──
+export function checkContentQuality(content, relPath) {
+    const issues = [];
+    // Strip frontmatter and code blocks for word count
+    const stripped = content
+        .replace(/^---[\s\S]*?---/, '')
+        .replace(/```[\s\S]*?```/g, '')
+        .replace(/<[^>]+>/g, '')
+        .trim();
+    // File is basically empty
+    if (stripped.length < 50) {
+        issues.push({
+            file: relPath,
+            severity: 'warning',
+            check: 'content',
+            message: 'File has very little content (< 50 chars after stripping code/frontmatter)',
+        });
+    }
+    // Check for broken MDX — unclosed JSX tags
+    const openTags = [];
+    const tagRegex = /<\/?([A-Z][A-Za-z0-9]*)\s*[^>]*\/?>/g;
+    let inCodeBlock = false;
+    for (const line of content.split('\n')) {
+        tagRegex.lastIndex = 0;
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        let match;
+        while ((match = tagRegex.exec(line)) !== null) {
+            const fullMatch = match[0];
+            const tag = match[1];
+            if (fullMatch.endsWith('/>'))
+                continue; // self-closing
+            if (fullMatch.startsWith('</')) {
+                // Closing tag
+                if (openTags.length > 0 && openTags[openTags.length - 1] === tag) {
+                    openTags.pop();
+                }
+            }
+            else {
+                openTags.push(tag);
+            }
+        }
+    }
+    // Don't flag unclosed tags for components that can wrap large content blocks
+    const wrapperComponents = new Set(['CardGroup', 'CodeGroup', 'Steps', 'AccordionGroup', 'Tabs']);
+    const unclosed = openTags.filter(t => !wrapperComponents.has(t));
+    if (unclosed.length > 5) {
+        issues.push({
+            file: relPath,
+            severity: 'info',
+            check: 'content',
+            message: `${unclosed.length} potentially unclosed JSX tags: ${unclosed.slice(0, 3).join(', ')}...`,
+        });
+    }
+    return issues;
+}
+// ── Check: Screenshot files ──
+export function checkScreenshots(content, relPath, outputDir) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        const tagMatches = line.matchAll(/<Screenshot\s+([^>]*?)\/?>/g);
+        for (const match of tagMatches) {
+            const propsStr = match[1];
+            if (!propsStr)
+                continue;
+            // Extract url and selector props
+            const urlMatch = propsStr.match(/url\s*=\s*["']([^"']*?)["']/);
+            const selectorMatch = propsStr.match(/selector\s*=\s*["']([^"']*?)["']/);
+            if (!urlMatch?.[1])
+                continue;
+            const url = urlMatch[1];
+            const selector = selectorMatch?.[1];
+            // Compute expected filename (same logic as capture/naming.ts)
+            let pathname;
+            try {
+                pathname = new URL(url).pathname;
+            }
+            catch {
+                pathname = url;
+            }
+            let slug = pathname.replace(/^\/+/, '').replace(/\//g, '-');
+            if (!slug)
+                slug = 'index';
+            slug = slug.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+            if (selector) {
+                let selSlug = selector.replace(/^[.#]/, '');
+                selSlug = selSlug.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+                slug = `${slug}--${selSlug}`;
+            }
+            const expectedFile = `${slug}.png`;
+            // Check if screenshot file exists in common locations
+            const screenshotDirs = [
+                join(outputDir, 'public', 'screenshots'),
+                join(outputDir, 'screenshots'),
+            ];
+            let found = false;
+            let stale = false;
+            for (const dir of screenshotDirs) {
+                const filePath = join(dir, expectedFile);
+                if (existsSync(filePath)) {
+                    found = true;
+                    // Check if stale (older than 7 days)
+                    try {
+                        const stat = statSync(filePath);
+                        const age = Date.now() - stat.mtimeMs;
+                        if (age > 7 * 24 * 60 * 60 * 1000) {
+                            stale = true;
+                        }
+                    }
+                    catch {
+                        // stat failed, skip staleness check
+                    }
+                    break;
+                }
+            }
+            if (!found) {
+                issues.push({
+                    file: relPath,
+                    line: i + 1,
+                    severity: 'warning',
+                    check: 'screenshots',
+                    message: `Screenshot file missing: ${expectedFile} — run \`skrypt heal --screenshots\``,
+                });
+            }
+            else if (stale) {
+                issues.push({
+                    file: relPath,
+                    line: i + 1,
+                    severity: 'info',
+                    check: 'screenshots',
+                    message: `Screenshot may be stale (> 7 days old): ${expectedFile}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ── Check: MDX compilation (lightweight syntax check) ──
+export function checkMdxSyntax(content, relPath) {
+    const issues = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // import statements (MDX treats these as JS imports)
+        if (/^import\s+/.test(line)) {
+            // Check if it's importing from a theme (Docusaurus pattern that breaks MDX)
+            if (/@theme\//.test(line)) {
+                issues.push({
+                    file: relPath,
+                    line: i + 1,
+                    severity: 'error',
+                    check: 'mdx-syntax',
+                    message: 'Docusaurus @theme import found — not compatible with this template',
+                });
+            }
+        }
+        // Curly braces outside JSX expressions can break MDX
+        // Check for lone { or } that aren't in JSX attributes
+        if (/^\s*\{[^}]*$/.test(line) && !/<\w/.test(line) && !/^\s*\{\/\*/.test(line)) {
+            // Potential issue but too many false positives, skip
+        }
+    }
+    return issues;
+}

package/dist/qa/fixes.d.ts

@@ -0,0 +1,30 @@
+export interface FixResult {
+    content: string;
+    fixes: string[];
+}
+/**
+ * Fix frontmatter issues:
+ * - Add frontmatter with title if none exists
+ * - Add title field if frontmatter exists but has no title
+ */
+export declare function fixFrontmatter(content: string, filePath: string): FixResult;
+/**
+ * Fix MDX syntax issues:
+ * - Strip Docusaurus @theme imports
+ * - Strip empty <a id="..."></a> anchor tags
+ */
+export declare function fixMdxSyntax(content: string): FixResult;
+/**
+ * Fix code block issues:
+ * - Infer language for code blocks missing a language specifier
+ * - Close unclosed code blocks at end of file
+ */
+export declare function fixCodeBlocks(content: string): FixResult;
+/**
+ * Fix security issues:
+ * - Strip <script>...</script> tags (outside code blocks)
+ * - Replace javascript: URLs with #
+ * - Strip inline on* event handlers from HTML tags
+ * - Add sandbox attribute to unsandboxed <iframe> tags
+ */
+export declare function fixSecurity(content: string): FixResult;