@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/test-example-extractor.js

@@ -0,0 +1,400 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.test-example-extractor",
+ *   "title": "Test Example Extractor",
+ *   "category": "compiler"
+ * }
+ *
+ * Extracts examples from test files marked with @codex:example
+ * and tracks test status from vitest/jest output.
+ */
+import { normalize } from 'node:path';
+/**
+ * Marker pattern for identifying codex examples in test files
+ *
+ * Supports formats:
+ * - @codex:example pithy.signals.effect
+ * - @codex:example("pithy.signals.effect")
+ * - @codex:example { entry: "pithy.signals.effect" }
+ */
+const CODEX_EXAMPLE_MARKER = /@codex:example\s*(?:\(\s*["']([^"']+)["']\s*\)|{[^}]*entry:\s*["']([^"']+)["'][^}]*}|([\w-]+(?:\.[\w-]+)+))/g;
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"extractTestExamples","stability":"stable","signature":"(content: string, filePath: string) => TestExample[]"}
+ *
+ * Extracts examples marked with @codex:example from a test file
+ * @param content - Test file content
+ * @param filePath - Path to the test file
+ * @returns Array of extracted test examples
+ *
+ * @example
+ * ```typescript
+ * // In a test file:
+ * // @codex:example pithy.signals.effect
+ * it("creates an effect that tracks dependencies", () => {
+ *   const count = signal(0);
+ *   let runCount = 0;
+ *   effect(() => { count(); runCount++; });
+ *   expect(runCount).toBe(1);
+ * });
+ * ```
+ */
+export function extractTestExamples(content, filePath) {
+    const examples = [];
+    const lines = content.split('\n');
+    // Find all @codex:example markers
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        CODEX_EXAMPLE_MARKER.lastIndex = 0;
+        const match = CODEX_EXAMPLE_MARKER.exec(line);
+        if (match) {
+            // Extract entry ID from any of the capture groups
+            const entryId = match[1] || match[2] || match[3];
+            if (!entryId)
+                continue;
+            // Look for the next it/test/describe block
+            const testBlock = findNextTestBlock(lines, i + 1);
+            if (!testBlock)
+                continue;
+            examples.push({
+                entryId: entryId.trim(),
+                name: testBlock.name,
+                code: testBlock.code,
+                location: {
+                    file: filePath,
+                    line: testBlock.startLine + 1, // 1-indexed
+                    endLine: testBlock.endLine + 1,
+                },
+                testFile: filePath,
+                status: 'unknown',
+            });
+        }
+    }
+    return examples;
+}
+/**
+ * Counts brace depth change for a line, skipping braces inside strings,
+ * template literals, and comments (including multi-line block comments).
+ *
+ * @param line - The line to scan
+ * @param inBlockComment - Whether we are currently inside a multi-line block comment
+ * @returns Brace counts and updated block comment state
+ */
+function countBraces(line, inBlockComment = false) {
+    let open = 0;
+    let close = 0;
+    let i = 0;
+    while (i < line.length) {
+        // If inside a multi-line block comment, scan for closing */
+        if (inBlockComment) {
+            const end = line.indexOf('*/', i);
+            if (end === -1) {
+                // Entire remaining line is still inside the comment
+                return { open, close, inBlockComment: true };
+            }
+            inBlockComment = false;
+            i = end + 2;
+            continue;
+        }
+        const ch = line[i];
+        // Skip single-line comments
+        if (ch === '/' && line[i + 1] === '/')
+            break;
+        // Block comment opening
+        if (ch === '/' && line[i + 1] === '*') {
+            const end = line.indexOf('*/', i + 2);
+            if (end === -1) {
+                // Block comment spans to subsequent lines
+                return { open, close, inBlockComment: true };
+            }
+            i = end + 2;
+            continue;
+        }
+        // Skip string/template literals
+        if (ch === '"' || ch === "'" || ch === '`') {
+            const quote = ch;
+            i++;
+            while (i < line.length) {
+                if (line[i] === '\\') {
+                    i += 2; // skip escaped character
+                    continue;
+                }
+                if (line[i] === quote) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === '{')
+            open++;
+        else if (ch === '}')
+            close++;
+        i++;
+    }
+    return { open, close, inBlockComment };
+}
+/**
+ * Finds the next test block (it/test/describe) starting from a given line
+ */
+function findNextTestBlock(lines, startLine) {
+    for (let i = startLine; i < lines.length; i++) {
+        const line = lines[i];
+        // Match it/test/describe patterns (handles escaped quotes in test names)
+        const testMatch = line.match(/(?:it|test|describe)\s*\(\s*(['"`])((?:\\.|(?!\1).)+)\1/);
+        if (testMatch) {
+            const name = testMatch[2];
+            const blockStart = i;
+            // Find the closing of this block using context-aware brace counting
+            let depth = 0;
+            let foundFirstBrace = false;
+            let blockEnd = i;
+            let commentState = false;
+            for (let j = i; j < lines.length; j++) {
+                const result = countBraces(lines[j], commentState);
+                commentState = result.inBlockComment;
+                if (result.open > 0)
+                    foundFirstBrace = true;
+                depth += result.open - result.close;
+                if (foundFirstBrace && depth <= 0) {
+                    blockEnd = j;
+                    break;
+                }
+            }
+            const code = lines.slice(blockStart, blockEnd + 1).join('\n');
+            return {
+                name,
+                code,
+                startLine: blockStart,
+                endLine: blockEnd,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"parseVitestOutput","stability":"stable","signature":"(output: string) => TestStatus[]"}
+ *
+ * Parses vitest JSON output to extract test statuses
+ * @param output - JSON string from vitest --reporter=json
+ * @returns Array of test statuses
+ */
+export function parseVitestOutput(output) {
+    const statuses = [];
+    try {
+        const json = JSON.parse(output);
+        // Handle vitest JSON output format
+        if (json.testResults) {
+            for (const fileResult of json.testResults) {
+                const file = fileResult.name || fileResult.file;
+                if (!file)
+                    continue;
+                for (const testResult of fileResult.assertionResults || []) {
+                    const testName = testResult.fullName || testResult.title;
+                    if (!testName)
+                        continue;
+                    statuses.push({
+                        file,
+                        testName,
+                        status: mapVitestStatus(testResult.status),
+                        duration: testResult.duration,
+                        error: testResult.failureMessages?.join('\n'),
+                    });
+                }
+            }
+        }
+        // Also handle the top-level format
+        if (json.success !== undefined && json.results) {
+            for (const result of json.results) {
+                const file = result.file;
+                if (!file)
+                    continue;
+                for (const task of flattenTasks(result.tasks || [])) {
+                    if (!task?.name)
+                        continue;
+                    statuses.push({
+                        file,
+                        testName: task.name,
+                        status: mapTaskResult(task.result?.state),
+                        duration: task.result?.duration,
+                        error: task.result?.error?.message,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (output.trim().length > 0 && process.env.NODE_ENV === 'development') {
+            console.warn('[codex] Failed to parse vitest output:', err instanceof Error ? err.message : String(err));
+        }
+    }
+    return statuses;
+}
+/**
+ * Flattens nested task structure from vitest
+ */
+function flattenTasks(tasks, parentName = '') {
+    const flat = [];
+    for (const task of tasks) {
+        const fullName = parentName ? `${parentName} > ${task.name}` : task.name;
+        if (task.type === 'test') {
+            flat.push({
+                name: fullName,
+                result: task.result,
+            });
+        }
+        if (task.tasks && Array.isArray(task.tasks)) {
+            flat.push(...flattenTasks(task.tasks, fullName));
+        }
+    }
+    return flat;
+}
+/**
+ * Maps vitest status to our status format
+ */
+function mapVitestStatus(status) {
+    switch (status?.toLowerCase()) {
+        case 'passed':
+            return 'passed';
+        case 'failed':
+            return 'failed';
+        case 'pending':
+        case 'skipped':
+        case 'todo':
+            return 'skipped';
+        default:
+            return 'skipped';
+    }
+}
+/**
+ * Maps vitest task result state to our status format
+ */
+function mapTaskResult(state) {
+    switch (state?.toLowerCase()) {
+        case 'pass':
+            return 'passed';
+        case 'fail':
+            return 'failed';
+        case 'skip':
+        case 'todo':
+            return 'skipped';
+        default:
+            return 'skipped';
+    }
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"matchExamplesToStatuses","stability":"stable","signature":"(examples: TestExample[], statuses: TestStatus[]) => TestExample[]"}
+ *
+ * Matches extracted examples to test statuses by test name
+ * @param examples - Extracted test examples
+ * @param statuses - Test statuses from vitest output
+ * @returns Examples with updated status information
+ */
+export function matchExamplesToStatuses(examples, statuses) {
+    return examples.map(example => {
+        // Find matching status by normalized file path and test name
+        const normalizedExample = normalize(example.testFile);
+        const matchingStatus = statuses.find(status => {
+            const normalizedStatus = normalize(status.file);
+            // Prefer normalized path suffix matching to avoid cross-package collisions.
+            // Both paths are normalized so separator differences are handled.
+            const fileMatch = normalizedStatus.endsWith(normalizedExample) ||
+                normalizedExample.endsWith(normalizedStatus);
+            // Prefer exact name match; fall back to substring only if one
+            // is a full "describe > test" path containing the other.
+            const nameMatch = status.testName === example.name ||
+                status.testName.endsWith(` > ${example.name}`) ||
+                status.testName.startsWith(`${example.name} > `);
+            return fileMatch && nameMatch;
+        });
+        if (matchingStatus) {
+            return {
+                ...example,
+                status: matchingStatus.status === 'passed'
+                    ? 'passing'
+                    : matchingStatus.status === 'failed'
+                        ? 'failing'
+                        : 'skipped',
+                error: matchingStatus.error,
+            };
+        }
+        return example;
+    });
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"generateExampleReport","stability":"stable","signature":"(examples: TestExample[]) => string"}
+ *
+ * Generates a markdown report of test examples with their statuses
+ * @param examples - Test examples to report
+ * @returns Markdown formatted report
+ */
+export function generateExampleReport(examples) {
+    const byEntry = new Map();
+    // Group by entry ID
+    for (const example of examples) {
+        const existing = byEntry.get(example.entryId) || [];
+        existing.push(example);
+        byEntry.set(example.entryId, existing);
+    }
+    const lines = ['# Test Examples Report', ''];
+    for (const [entryId, entryExamples] of byEntry) {
+        lines.push(`## ${entryId}`);
+        lines.push('');
+        for (const example of entryExamples) {
+            const statusIcon = example.status === 'passing'
+                ? '✅'
+                : example.status === 'failing'
+                    ? '❌'
+                    : example.status === 'skipped'
+                        ? '⏭️'
+                        : '❓';
+            lines.push(`### ${statusIcon} ${example.name}`);
+            lines.push('');
+            lines.push(`Location: \`${example.testFile}:${example.location.line}\``);
+            lines.push('');
+            lines.push('```typescript');
+            lines.push(example.code);
+            lines.push('```');
+            lines.push('');
+            if (example.error) {
+                lines.push('**Error:**');
+                lines.push('```');
+                lines.push(example.error);
+                lines.push('```');
+                lines.push('');
+            }
+        }
+    }
+    // Summary
+    const passing = examples.filter(e => e.status === 'passing').length;
+    const failing = examples.filter(e => e.status === 'failing').length;
+    const unknown = examples.filter(e => e.status === 'unknown' || e.status === 'skipped').length;
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- ✅ Passing: ${passing}`);
+    lines.push(`- ❌ Failing: ${failing}`);
+    lines.push(`- ❓ Unknown/Skipped: ${unknown}`);
+    return lines.join('\n');
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.test-example-extractor","name":"validateTestExamples","stability":"experimental","signature":"(examples: TestExample[]) => { valid: TestExample[]; invalid: TestExample[] }"}
+ *
+ * Validates that test examples are working by checking their status
+ * @param examples - Test examples to validate
+ * @returns Object with valid and invalid examples
+ */
+export function validateTestExamples(examples) {
+    const valid = [];
+    const invalid = [];
+    for (const example of examples) {
+        if (example.status === 'passing') {
+            valid.push(example);
+        }
+        else if (example.status === 'failing') {
+            invalid.push(example);
+        }
+        // Unknown/skipped are neither valid nor invalid
+    }
+    return { valid, invalid };
+}

package/dist/extraction/test-pattern-extractor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.test-pattern-extractor",
+ *   "title": "Test Pattern Extractor",
+ *   "category": "compiler"
+ * }
+ */
+import type { ExtractedTestCase, TestFileAnalysis, TestReference } from './types.js';
+/**
+ * Extracts test cases from a single test file
+ * @param content - Test file content
+ * @param filePath - Path to the test file
+ * @returns Array of extracted test cases
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"extractTestCases","stability":"stable","signature":"(content: string, filePath: string) => ExtractedTestCase[]"}
+ */
+export declare function extractTestCases(content: string, filePath: string): ExtractedTestCase[];
+/**
+ * Extracts imports from a test file to identify tested modules
+ * @param content - Test file content
+ * @returns Array of import paths
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"extractTestImports","stability":"stable","signature":"(content: string) => string[]"}
+ */
+export declare function extractTestImports(content: string): string[];
+/**
+ * Identifies which APIs are likely covered by a test file
+ * @param content - Test file content
+ * @param knownApis - List of known API names to look for
+ * @returns Array of covered API identifiers
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"identifyCoveredApis","stability":"stable","signature":"(content: string, knownApis: string[]) => string[]"}
+ */
+export declare function identifyCoveredApis(content: string, knownApis: string[]): string[];
+/**
+ * Analyzes a test file and returns structured analysis
+ * @param content - Test file content
+ * @param filePath - Path to the test file
+ * @param knownApis - Optional list of known API names
+ * @returns Test file analysis
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"analyzeTestFile","stability":"stable","signature":"(content: string, filePath: string, knownApis?: string[]) => TestFileAnalysis"}
+ */
+export declare function analyzeTestFile(content: string, filePath: string, knownApis?: string[]): TestFileAnalysis;
+/**
+ * Converts test cases to test references for linking to codex entries
+ * @param testCases - Extracted test cases
+ * @param filePath - Path to the test file
+ * @returns Array of test references
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"testCasesToReferences","stability":"stable","signature":"(testCases: ExtractedTestCase[], filePath: string) => TestReference[]"}
+ */
+export declare function testCasesToReferences(testCases: ExtractedTestCase[], filePath: string): TestReference[];
+/**
+ * Matches test files to codex entry IDs based on naming conventions
+ * @param testFilePath - Path to the test file
+ * @param entryIds - List of codex entry IDs
+ * @returns Matched entry ID or undefined
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"matchTestToEntry","stability":"stable","signature":"(testFilePath: string, entryIds: string[]) => string | undefined"}
+ */
+export declare function matchTestToEntry(testFilePath: string, entryIds: string[]): string | undefined;
+/**
+ * Generates a test coverage summary for display
+ * @param analyses - Array of test file analyses
+ * @returns Formatted coverage summary
+ * @codexApi {"parent":"pithy.codex.extraction.test-pattern-extractor","name":"generateCoverageSummary","stability":"stable","signature":"(analyses: TestFileAnalysis[]) => { totalTests: number; byType: Record<string, number>; coveredApis: string[] }"}
+ */
+export declare function generateCoverageSummary(analyses: TestFileAnalysis[]): {
+    totalTests: number;
+    byType: Record<string, number>;
+    coveredApis: string[];
+};