@pithyjs/codex 0.1.0-beta.0

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.cli",
+ *   "title": "CLI Entry Point",
+ *   "category": "feature"
+ * }
+ *
+ * Main CLI dispatcher for codex commands. Provides an interactive readline
+ * prompt to create new codex entries with id, title, category, tags, and
+ * related fields, then writes the validated JSON to codex/.proposals/.
+ */
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { join } from 'node:path';
+import fs from 'node:fs/promises';
+import { codexSchema } from './schema.js'; // NodeNext-friendly
+const parseCSV = (s) => s
+    .split(',')
+    .map(t => t.trim())
+    .filter(Boolean);
+const sanitizeId = (s) => s.trim().replace(/\s+/g, '-');
+const isSafeId = (s) => /^[A-Za-z0-9._-]+$/.test(s);
+async function main() {
+    const rl = createInterface({ input, output });
+    const idRaw = await rl.question('id: ');
+    const id = sanitizeId(idRaw);
+    if (!isSafeId(id)) {
+        console.error('Invalid id. Use letters, numbers, ".", "_" or "-". No spaces.');
+        rl.close();
+        process.exit(1);
+    }
+    const title = (await rl.question('title: ')).trim();
+    const category = (await rl.question('category: ')).trim();
+    const tags = await rl.question('tags (comma separated): ');
+    const updatedIn = (await rl.question('updated (ISO date, blank = now): ')).trim();
+    const updated = updatedIn || new Date().toISOString();
+    const related = await rl.question('related (comma separated): ');
+    rl.close();
+    const data = {
+        id,
+        title,
+        category,
+        tags: parseCSV(tags),
+        updated,
+        related: parseCSV(related),
+    };
+    const entry = codexSchema.parse(data); // throws on invalid
+    const outDir = join(process.cwd(), 'codex');
+    const filePath = join(outDir, `${entry.id}.json`);
+    try {
+        // prevent accidental overwrite
+        await fs.access(filePath);
+        console.error(`Entry already exists: ${filePath}`);
+        process.exit(1);
+    }
+    catch {
+        // OK, file doesn't exist
+    }
+    await fs.writeFile(filePath, JSON.stringify(entry, null, 2));
+    console.log(`✅ Wrote ${filePath}`);
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Loads environment variables from .env files using dotenv.
+ * @codexApi {"parent":"pithy.codex.env","name":"loadEnv","stability":"stable","signature":"() => void"}
+ */
+export declare function loadEnv(): void;

package/dist/env.js

@@ -0,0 +1,35 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.env",
+ *   "title": "Environment Configuration",
+ *   "category": "feature"
+ * }
+ *
+ * Loads environment variables for LLM API access.
+ */
+import { config } from 'dotenv';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '../../..');
+// Load order: team defaults → .env → .env.local (later files win)
+const files = [
+    join(repoRoot, '.env.team'),
+    join(repoRoot, '.env'),
+    join(repoRoot, '.env.local'),
+];
+/**
+ * Loads environment variables from .env files using dotenv.
+ * @codexApi {"parent":"pithy.codex.env","name":"loadEnv","stability":"stable","signature":"() => void"}
+ */
+export function loadEnv() {
+    for (const f of files) {
+        try {
+            config({ path: f, override: false });
+        }
+        catch {
+            void 0;
+        }
+    }
+}

package/dist/extract-cli.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.cli",
+ *   "title": "Extraction CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * CLI for running the multi-source extraction pipeline.
+ *
+ * Usage:
+ *   pnpm codex:extract [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --output <path>     Output file for results (default: codex/extracted.json)
+ *   --report            Generate human-readable report
+ *   --no-tests          Skip test file analysis
+ *   --no-readme         Skip README linking
+ *   --verbose           Show detailed progress
+ */
+export {};

package/dist/extract-cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.cli",
+ *   "title": "Extraction CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * CLI for running the multi-source extraction pipeline.
+ *
+ * Usage:
+ *   pnpm codex:extract [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --output <path>     Output file for results (default: codex/extracted.json)
+ *   --report            Generate human-readable report
+ *   --no-tests          Skip test file analysis
+ *   --no-readme         Skip README linking
+ *   --verbose           Show detailed progress
+ */
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import fs from 'node:fs/promises';
+import { runExtractionPipeline, generateExtractionReport, exportToCodexFormat, } from './extraction/index.js';
+/**
+ * Validates and normalizes a path to prevent path traversal attacks
+ * @param basePath - The base directory that paths must stay within
+ * @param inputPath - The user-provided path to validate
+ * @returns Normalized absolute path
+ * @throws Error if path escapes the base directory
+ */
+function validatePath(basePath, inputPath) {
+    const resolvedBase = resolve(basePath);
+    const resolvedPath = isAbsolute(inputPath)
+        ? resolve(inputPath)
+        : resolve(basePath, inputPath);
+    // Ensure the resolved path is within the base directory
+    const relativePath = relative(resolvedBase, resolvedPath);
+    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        throw new Error(`Security error: Path "${inputPath}" escapes the project root directory`);
+    }
+    return resolvedPath;
+}
+function parseArgs(args) {
+    const options = {
+        root: process.cwd(),
+        output: 'codex/extracted.json',
+        report: false,
+        analyzeTests: true,
+        linkReadmes: true,
+        verbose: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--root':
+                options.root = args[++i] || process.cwd();
+                break;
+            case '--output':
+                options.output = args[++i] || options.output;
+                break;
+            case '--report':
+                options.report = true;
+                break;
+            case '--no-tests':
+                options.analyzeTests = false;
+                break;
+            case '--no-readme':
+                options.linkReadmes = false;
+                break;
+            case '--verbose':
+            case '-v':
+                options.verbose = true;
+                break;
+            case '--help':
+            case '-h':
+                printHelp();
+                process.exit(0);
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`
+Codex Extraction Pipeline
+
+Usage:
+  codex-extract [options]
+
+Options:
+  --root <path>       Project root directory (default: current directory)
+  --output <path>     Output file for results (default: codex/extracted.json)
+  --report            Generate human-readable report (stdout)
+  --no-tests          Skip test file analysis
+  --no-readme         Skip README linking
+  --verbose, -v       Show detailed progress
+  --help, -h          Show this help message
+
+Examples:
+  # Extract from current directory
+  codex-extract
+
+  # Extract with custom output
+  codex-extract --output docs/api-data.json
+
+  # Generate report only
+  codex-extract --report
+
+  # Extract without test analysis (faster)
+  codex-extract --no-tests --no-readme
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const options = parseArgs(args);
+    // Validate and normalize the root path
+    options.root = resolve(options.root);
+    // Verify root directory exists
+    try {
+        const stat = await fs.stat(options.root);
+        if (!stat.isDirectory()) {
+            console.error(`❌ Error: "${options.root}" is not a directory`);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(`❌ Error: Root directory "${options.root}" does not exist`);
+        process.exit(1);
+    }
+    if (options.verbose) {
+        console.log('🔍 Codex Extraction Pipeline');
+        console.log(`   Root: ${options.root}`);
+        console.log(`   Output: ${options.output}`);
+        console.log(`   Analyze tests: ${options.analyzeTests}`);
+        console.log(`   Link READMEs: ${options.linkReadmes}`);
+        console.log('');
+    }
+    const startTime = performance.now();
+    try {
+        if (options.verbose) {
+            console.log('📂 Scanning source files...');
+        }
+        const result = await runExtractionPipeline({
+            root: options.root,
+            analyzeTests: options.analyzeTests,
+            linkReadmes: options.linkReadmes,
+            extractRunnableExamples: true,
+        });
+        const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);
+        if (options.verbose) {
+            console.log(`\n✅ Extraction complete in ${elapsed}s`);
+            console.log('');
+            console.log('📊 Statistics:');
+            console.log(`   Files scanned: ${result.stats.filesScanned}`);
+            console.log(`   Components found: ${result.stats.componentsFound}`);
+            console.log(`   APIs extracted: ${result.stats.apisExtracted}`);
+            console.log(`   Examples extracted: ${result.stats.examplesExtracted}`);
+            console.log(`   Tests analyzed: ${result.stats.testsAnalyzed}`);
+            console.log(`   README sections linked: ${result.stats.readmeSectionsLinked}`);
+            console.log('');
+        }
+        // Generate report if requested
+        if (options.report) {
+            const report = generateExtractionReport(result);
+            console.log(report);
+        }
+        // Write output file (with path validation)
+        const validatedRoot = resolve(options.root);
+        const outputPath = validatePath(validatedRoot, options.output);
+        const outputDir = join(outputPath, '..');
+        await fs.mkdir(outputDir, { recursive: true });
+        const exportData = exportToCodexFormat(result);
+        await fs.writeFile(outputPath, JSON.stringify(exportData, null, 2));
+        if (options.verbose || !options.report) {
+            console.log(`📝 Wrote extraction data to: ${outputPath}`);
+        }
+        // Summary (always shown unless report mode)
+        if (!options.report) {
+            console.log('');
+            console.log(`✨ Extracted ${result.stats.componentsFound} components with ${result.stats.apisExtracted} APIs`);
+        }
+    }
+    catch (error) {
+        console.error('❌ Extraction failed:', error);
+        process.exit(1);
+    }
+}
+main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/extraction/breaking-changes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.breaking-changes",
+ *   "title": "Breaking Change Detection",
+ *   "category": "feature"
+ * }
+ *
+ * Detects breaking changes between API snapshots by comparing
+ * extracted API signatures, stability levels, and type definitions.
+ * Generates migration guides and changelogs for version transitions.
+ */
+import type { ExtendedExtractionResult, ExtractedTypeDefinition, ApiSnapshot, ApiChange, SnapshotDiff, ChangeClassification } from './types.js';
+/**
+ * Create an API snapshot from extraction results at a given version.
+ * Captures all enriched API entries across all components.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"createApiSnapshot","stability":"stable","signature":"(result: ExtendedExtractionResult, version: string, timestamp?: string) => ApiSnapshot"}
+ */
+export declare function createApiSnapshot(result: ExtendedExtractionResult, version: string, timestamp?: string): ApiSnapshot;
+/**
+ * Create an API snapshot from extracted type definitions.
+ * Only includes exported types (public API surface).
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"snapshotFromTypeDefinitions","stability":"stable","signature":"(types: ExtractedTypeDefinition[], version: string, timestamp?: string) => ApiSnapshot"}
+ */
+export declare function snapshotFromTypeDefinitions(types: ExtractedTypeDefinition[], version: string, timestamp?: string): ApiSnapshot;
+/**
+ * Compare two API snapshots and produce a structured diff.
+ * Matches entries by qualifiedName (parent.name).
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"diffSnapshots","stability":"stable","signature":"(before: ApiSnapshot, after: ApiSnapshot) => SnapshotDiff"}
+ */
+export declare function diffSnapshots(before: ApiSnapshot, after: ApiSnapshot): SnapshotDiff;
+/**
+ * Classify a single API change as major, minor, or patch
+ * according to semver conventions.
+ *
+ * - **major**: removal or signature/member change of a stable API
+ * - **minor**: addition, removal of experimental/deprecated, or changes to experimental APIs
+ * - **patch**: stability level changes
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"classifyChange","stability":"stable","signature":"(change: ApiChange) => ChangeClassification"}
+ */
+export declare function classifyChange(change: ApiChange): ChangeClassification;
+/**
+ * Filter a snapshot diff down to only breaking changes
+ * (those classified as "major").
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"detectBreakingChanges","stability":"stable","signature":"(diff: SnapshotDiff) => ApiChange[]"}
+ */
+export declare function detectBreakingChanges(diff: SnapshotDiff): ApiChange[];
+/**
+ * Generate a human-readable migration guide for a set of breaking changes.
+ * Groups changes by parent component and provides before/after comparisons.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"generateMigrationGuide","stability":"stable","signature":"(changes: ApiChange[]) => string"}
+ */
+export declare function generateMigrationGuide(changes: ApiChange[]): string;
+/**
+ * Generate a changelog in Markdown from a snapshot diff.
+ * Sections: Breaking Changes, Added, Changed. Omits empty sections.
+ *
+ * @codexApi {"parent":"pithy.codex.breaking-changes","name":"generateChangelog","stability":"stable","signature":"(diff: SnapshotDiff) => string"}
+ */
+export declare function generateChangelog(diff: SnapshotDiff): string;