@pithyjs/codex 0.1.0-beta.0

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

@@ -0,0 +1,261 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.test-pattern-extractor",
+ *   "title": "Test Pattern Extractor",
+ *   "category": "compiler"
+ * }
+ */
+import { basename } from 'node:path';
+/**
+ * Escapes special regex metacharacters in a string.
+ * This prevents regex injection when user-provided strings are used in RegExp.
+ */
+function escapeRegexMetachars(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Patterns for test framework detection
+ */
+const DESCRIBE_PATTERN = /(?:describe|suite)\s*\(\s*(['"`])([^'"`]+)\1\s*,\s*(?:async\s*)?\(\s*\)\s*=>\s*\{/g;
+const IT_PATTERN = /(?:it|test)\s*\(\s*(['"`])([^'"`]+)\1\s*,\s*(?:async\s*)?\(\s*\)\s*=>\s*\{/g;
+const IMPORT_PATTERN = /import\s+(?:\{[^}]+\}|\*\s+as\s+\w+|\w+)\s+from\s+(['"`])([^'"`]+)\1/g;
+const ASSERTION_PATTERN = /expect\([^)]+\)\.(?:toBe|toEqual|toMatch|toThrow|toHaveBeenCalled|toContain|toBeTruthy|toBeFalsy|toBeNull|toBeUndefined|toBeDefined|toBeGreaterThan|toBeLessThan|toHaveLength|toHaveProperty|toMatchObject|toMatchSnapshot|toMatchInlineSnapshot)\(/g;
+/**
+ * Determines the test type based on file path and patterns
+ */
+function determineTestType(filePath) {
+    const lowerPath = filePath.toLowerCase();
+    if (lowerPath.includes('e2e') || lowerPath.includes('end-to-end')) {
+        return 'e2e';
+    }
+    if (lowerPath.includes('integration') ||
+        lowerPath.includes('integ') ||
+        lowerPath.includes('.integration.')) {
+        return 'integration';
+    }
+    return 'unit';
+}
+/**
+ * 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 function extractTestCases(content, filePath) {
+    const testCases = [];
+    // Find all describe blocks for hierarchy tracking
+    const describes = [];
+    let match;
+    // Reset regex state
+    DESCRIBE_PATTERN.lastIndex = 0;
+    while ((match = DESCRIBE_PATTERN.exec(content)) !== null) {
+        const textBefore = content.slice(0, match.index);
+        const lineNumber = textBefore.split('\n').length;
+        describes.push({
+            name: match[2],
+            startIndex: match.index,
+            line: lineNumber,
+        });
+    }
+    // Find all test cases
+    IT_PATTERN.lastIndex = 0;
+    while ((match = IT_PATTERN.exec(content)) !== null) {
+        const testName = match[2];
+        const startIndex = match.index;
+        const textBefore = content.slice(0, startIndex);
+        const lineNumber = textBefore.split('\n').length;
+        // Find the parent describe block
+        let parentDescribe;
+        for (const desc of describes) {
+            if (desc.startIndex < startIndex) {
+                parentDescribe = desc.name;
+            }
+            else {
+                break;
+            }
+        }
+        // Extract the test body (simplified - just gets the next few lines)
+        const testBodyStart = content.indexOf('{', startIndex);
+        let braceCount = 1;
+        let testBodyEnd = testBodyStart + 1;
+        while (braceCount > 0 && testBodyEnd < content.length) {
+            const char = content[testBodyEnd];
+            if (char === '{')
+                braceCount++;
+            if (char === '}')
+                braceCount--;
+            testBodyEnd++;
+        }
+        const testCode = content.slice(testBodyStart, testBodyEnd);
+        // Find assertions in the test
+        const assertions = [];
+        ASSERTION_PATTERN.lastIndex = 0;
+        let assertMatch;
+        while ((assertMatch = ASSERTION_PATTERN.exec(testCode)) !== null) {
+            assertions.push(assertMatch[0]);
+        }
+        testCases.push({
+            name: testName,
+            type: match[0].startsWith('it') ? 'it' : 'test',
+            location: {
+                file: filePath,
+                line: lineNumber,
+            },
+            parentDescribe,
+            code: testCode,
+            assertions,
+        });
+    }
+    return testCases;
+}
+/**
+ * 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 function extractTestImports(content) {
+    const imports = [];
+    IMPORT_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = IMPORT_PATTERN.exec(content)) !== null) {
+        const importPath = match[2];
+        // Filter out test utilities and external packages
+        if (!importPath.startsWith('vitest') &&
+            !importPath.startsWith('@testing') &&
+            !importPath.startsWith('jest')) {
+            imports.push(importPath);
+        }
+    }
+    return imports;
+}
+/**
+ * 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 function identifyCoveredApis(content, knownApis) {
+    const covered = [];
+    for (const api of knownApis) {
+        // Escape regex metacharacters to prevent regex injection
+        const escapedApi = escapeRegexMetachars(api);
+        // Check if the API name appears in the test file
+        // Look for function calls, method calls, or imports
+        const patterns = [
+            new RegExp(`\\b${escapedApi}\\s*\\(`, 'g'), // Function call: api()
+            new RegExp(`\\.${escapedApi}\\s*\\(`, 'g'), // Method call: .api()
+            new RegExp(`import[^;]*\\b${escapedApi}\\b`, 'g'), // Import (limited scope)
+            new RegExp(`from\\s*['"][^'"]*${escapedApi}`, 'gi'), // From path containing api
+        ];
+        for (const pattern of patterns) {
+            if (pattern.test(content)) {
+                covered.push(api);
+                break;
+            }
+        }
+    }
+    return [...new Set(covered)];
+}
+/**
+ * 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 function analyzeTestFile(content, filePath, knownApis = []) {
+    const testCases = extractTestCases(content, filePath);
+    const imports = extractTestImports(content);
+    const coveredApis = identifyCoveredApis(content, knownApis);
+    return {
+        file: filePath,
+        testCases,
+        imports,
+        coveredApis,
+    };
+}
+/**
+ * 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 function testCasesToReferences(testCases, filePath) {
+    const testType = determineTestType(filePath);
+    return testCases.map(tc => ({
+        file: filePath,
+        line: tc.location.line,
+        name: tc.parentDescribe ? `${tc.parentDescribe} > ${tc.name}` : tc.name,
+        type: testType,
+    }));
+}
+/**
+ * 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 function matchTestToEntry(testFilePath, entryIds) {
+    // Extract the base name from the test file (cross-platform)
+    const fileName = basename(testFilePath);
+    const baseName = fileName
+        .replace(/\.test\.ts$/, '')
+        .replace(/\.spec\.ts$/, '')
+        .replace(/\.test\.js$/, '')
+        .replace(/\.spec\.js$/, '')
+        .toLowerCase();
+    // Try to find a matching entry ID
+    for (const entryId of entryIds) {
+        const entryParts = entryId.toLowerCase().split('.');
+        const lastPart = entryParts[entryParts.length - 1];
+        if (lastPart === baseName || entryId.toLowerCase().includes(baseName)) {
+            return entryId;
+        }
+    }
+    // Try matching by path segments (cross-platform: handle both / and \)
+    const normalizedPath = testFilePath.toLowerCase().replace(/\\/g, '/');
+    const pathSegments = normalizedPath.split('/');
+    for (const entryId of entryIds) {
+        const entryParts = entryId.toLowerCase().split('.');
+        // Check if any entry part matches a path segment
+        if (entryParts.some(part => pathSegments.includes(part))) {
+            return entryId;
+        }
+    }
+    return 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 function generateCoverageSummary(analyses) {
+    const byType = {
+        unit: 0,
+        integration: 0,
+        e2e: 0,
+    };
+    const allCoveredApis = new Set();
+    let totalTests = 0;
+    for (const analysis of analyses) {
+        const testType = determineTestType(analysis.file);
+        byType[testType] += analysis.testCases.length;
+        totalTests += analysis.testCases.length;
+        for (const api of analysis.coveredApis) {
+            allCoveredApis.add(api);
+        }
+    }
+    return {
+        totalTests,
+        byType,
+        coveredApis: Array.from(allCoveredApis),
+    };
+}

package/dist/extraction/testing-pyramid.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.testing-pyramid",
+ *   "title": "Testing Pyramid",
+ *   "category": "feature"
+ * }
+ *
+ * Provides category-based testing defaults and risk-level modifiers
+ * for the codex testing pyramid system. Resolves per-entry testing
+ * requirements by merging annotation overrides with category defaults
+ * and applying risk adjustments.
+ */
+import type { TestingRequirements, RiskLevel } from './types.js';
+/**
+ * Get the default testing requirements for a given codex category.
+ * Returns feature defaults for unknown categories.
+ * Returns a fresh copy — callers may mutate freely.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"getTestingDefaults","stability":"stable","signature":"(category: string) => TestingRequirements"}
+ */
+export declare function getTestingDefaults(category: string): TestingRequirements;
+/**
+ * Apply risk-level modifiers to testing requirements.
+ * Returns a new object — does not mutate the input.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"applyRiskModifiers","stability":"stable","signature":"(base: TestingRequirements, risk: RiskLevel | undefined) => TestingRequirements"}
+ */
+export declare function applyRiskModifiers(base: TestingRequirements, risk: RiskLevel | undefined): TestingRequirements;
+/**
+ * Resolve the final testing requirements for a codex entry.
+ * Merges annotation overrides with category defaults and applies risk modifiers.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"resolveTestingRequirements","stability":"stable","signature":"(category: string, risk?: RiskLevel, override?: TestingRequirements) => TestingRequirements"}
+ */
+export declare function resolveTestingRequirements(category: string, risk?: RiskLevel, override?: TestingRequirements): TestingRequirements;
+/**
+ * Compute human-readable testing status from requirements.
+ * Returns "Complete" if all required levels are covered,
+ * "N/A" if no levels are defined, or "Missing X, Y" listing uncovered levels.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"computeTestingStatus","stability":"stable","signature":"(reqs: TestingRequirements) => string"}
+ */
+export declare function computeTestingStatus(reqs: TestingRequirements): string;

package/dist/extraction/testing-pyramid.js

@@ -0,0 +1,163 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.testing-pyramid",
+ *   "title": "Testing Pyramid",
+ *   "category": "feature"
+ * }
+ *
+ * Provides category-based testing defaults and risk-level modifiers
+ * for the codex testing pyramid system. Resolves per-entry testing
+ * requirements by merging annotation overrides with category defaults
+ * and applying risk adjustments.
+ */
+// ── Category Defaults ───────────────────────────────────────────
+/** Category-based default testing requirements per the implementation plan. */
+const CATEGORY_DEFAULTS = {
+    directive: {
+        unit: { required: true, coverage: 90 },
+        integration: { required: true, coverage: 80 },
+        e2e: { required: false },
+    },
+    feature: {
+        unit: { required: true, coverage: 85 },
+        integration: { required: true, coverage: 70 },
+        e2e: { required: false },
+    },
+    runtime: {
+        unit: { required: true, coverage: 90 },
+        integration: { required: true, coverage: 80 },
+        e2e: { required: true },
+    },
+    compiler: {
+        unit: { required: true, coverage: 95 },
+        integration: { required: true, coverage: 70 },
+        e2e: { required: false },
+    },
+    plugin: {
+        unit: { required: true, coverage: 70 },
+        integration: { required: true, coverage: 85 },
+        e2e: { required: true },
+    },
+    // Type-only modules have no runtime behavior to test
+    types: {},
+};
+const RISK_MODIFIERS = {
+    critical: { unitDelta: 5, integrationDelta: 10, e2eRequired: true },
+    high: { unitDelta: 0, integrationDelta: 5, e2eRequired: false },
+    medium: { unitDelta: -5, integrationDelta: 0, e2eRequired: false },
+    low: { unitDelta: -10, integrationDelta: -10, e2eRequired: false },
+};
+// ── Public API ──────────────────────────────────────────────────
+/**
+ * Get the default testing requirements for a given codex category.
+ * Returns feature defaults for unknown categories.
+ * Returns a fresh copy — callers may mutate freely.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"getTestingDefaults","stability":"stable","signature":"(category: string) => TestingRequirements"}
+ */
+export function getTestingDefaults(category) {
+    const defaults = CATEGORY_DEFAULTS[category] ?? CATEGORY_DEFAULTS.feature;
+    return structuredClone(defaults);
+}
+/**
+ * Apply risk-level modifiers to testing requirements.
+ * Returns a new object — does not mutate the input.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"applyRiskModifiers","stability":"stable","signature":"(base: TestingRequirements, risk: RiskLevel | undefined) => TestingRequirements"}
+ */
+export function applyRiskModifiers(base, risk) {
+    if (!risk)
+        return structuredClone(base);
+    const modifier = RISK_MODIFIERS[risk];
+    if (!modifier)
+        return structuredClone(base);
+    const result = {};
+    if (base.unit) {
+        result.unit = {
+            ...base.unit,
+            coverage: base.unit.coverage !== undefined
+                ? clamp(base.unit.coverage + modifier.unitDelta, 0, 100)
+                : undefined,
+        };
+    }
+    if (base.integration) {
+        result.integration = {
+            ...base.integration,
+            coverage: base.integration.coverage !== undefined
+                ? clamp(base.integration.coverage + modifier.integrationDelta, 0, 100)
+                : undefined,
+        };
+    }
+    if (base.e2e) {
+        result.e2e = {
+            ...base.e2e,
+            required: modifier.e2eRequired || (base.e2e.required ?? false),
+        };
+    }
+    return result;
+}
+/**
+ * Resolve the final testing requirements for a codex entry.
+ * Merges annotation overrides with category defaults and applies risk modifiers.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"resolveTestingRequirements","stability":"stable","signature":"(category: string, risk?: RiskLevel, override?: TestingRequirements) => TestingRequirements"}
+ */
+export function resolveTestingRequirements(category, risk, override) {
+    const defaults = getTestingDefaults(category);
+    // Deep-merge: override fields take precedence per-level,
+    // but unspecified fields within a level retain category defaults
+    const merged = {
+        unit: mergeTestLevel(defaults.unit, override?.unit),
+        integration: mergeTestLevel(defaults.integration, override?.integration),
+        e2e: mergeTestLevel(defaults.e2e, override?.e2e),
+    };
+    // Clean up undefined levels (for "types" category)
+    if (merged.unit === undefined)
+        delete merged.unit;
+    if (merged.integration === undefined)
+        delete merged.integration;
+    if (merged.e2e === undefined)
+        delete merged.e2e;
+    return applyRiskModifiers(merged, risk);
+}
+/**
+ * Compute human-readable testing status from requirements.
+ * Returns "Complete" if all required levels are covered,
+ * "N/A" if no levels are defined, or "Missing X, Y" listing uncovered levels.
+ *
+ * @codexApi {"parent":"pithy.codex.testing-pyramid","name":"computeTestingStatus","stability":"stable","signature":"(reqs: TestingRequirements) => string"}
+ */
+export function computeTestingStatus(reqs) {
+    const levels = [
+        ['unit', reqs.unit],
+        ['integration', reqs.integration],
+        ['e2e', reqs.e2e],
+    ];
+    const defined = levels.filter(([, level]) => level !== undefined);
+    if (defined.length === 0)
+        return 'N/A';
+    const missing = defined
+        .filter(([, level]) => level.required && !level.covered)
+        .map(([name]) => name);
+    return missing.length === 0 ? 'Complete' : `Missing ${missing.join(', ')}`;
+}
+// ── Internal Helpers ────────────────────────────────────────────
+/**
+ * Deep-merge a test level override onto a default.
+ * Returns undefined if both are undefined (e.g. "types" category).
+ * Override fields win; unspecified fields retain defaults so that
+ * partial overrides (e.g. `{ covered: true }`) don't drop `required`.
+ */
+function mergeTestLevel(base, override) {
+    if (!base && !override)
+        return undefined;
+    if (!override)
+        return base;
+    if (!base)
+        return override;
+    return { ...base, ...override };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}

package/dist/extraction/type-extractor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.type-extractor",
+ *   "title": "TypeScript Type Extractor",
+ *   "category": "compiler"
+ * }
+ */
+import type { ExtractedTypeDefinition } from './types.js';
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"extractTypesFromFile","stability":"stable","signature":"(filePath: string, content: string) => ExtractedTypeDefinition[]"}
+ *
+ * Extracts type definitions from a TypeScript file using the TypeScript Compiler API
+ * @param filePath - Path to the TypeScript file
+ * @param content - Content of the file
+ * @returns Array of extracted type definitions
+ */
+export declare function extractTypesFromFile(filePath: string, content: string): ExtractedTypeDefinition[];
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"getTypeSignature","stability":"stable","signature":"(def: ExtractedTypeDefinition) => string"}
+ *
+ * Generates a human-readable signature for a type definition
+ * @param def - The extracted type definition
+ * @returns Formatted type signature
+ */
+export declare function getTypeSignature(def: ExtractedTypeDefinition): string;
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"generateMethodTable","stability":"stable","signature":"(def: ExtractedTypeDefinition) => string"}
+ *
+ * Generates a markdown table of members for documentation
+ * @param def - The extracted type definition
+ * @returns Markdown table string
+ */
+export declare function generateMethodTable(def: ExtractedTypeDefinition): string;