@pithyjs/codex 0.1.0-beta.0

package/dist/validate.js

@@ -0,0 +1,183 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.validate",
+ *   "title": "Documentation Validator",
+ *   "category": "feature"
+ * }
+ *
+ * Validates extracted documentation examples by checking they are
+ * syntactically valid TypeScript. Used by `pnpm codex validate` and CI drift checks.
+ */
+import ts from 'typescript';
+/**
+ * Languages we can validate syntactically
+ */
+const VALIDATABLE_LANGUAGES = new Set(['typescript', 'ts', 'javascript', 'js']);
+/**
+ * @codexApi {"parent":"pithy.codex.validate","name":"validateExampleSyntax","stability":"stable","signature":"(code: string, componentId?: string, apiName?: string, language?: string) => ExampleValidationResult"}
+ *
+ * Validates a single code example for syntactic correctness using TypeScript compiler.
+ * Does NOT type-check — only parses for syntax errors.
+ *
+ * @param code - The example code to validate
+ * @param componentId - The ID of the component the example belongs to (default: "")
+ * @param apiName - The name of the API the example belongs to
+ * @param language - The language of the example (default: "typescript")
+ * @returns Validation result with diagnostics if invalid
+ */
+export function validateExampleSyntax(code, componentId = '', apiName, language = 'typescript') {
+    const lang = language.toLowerCase();
+    if (!VALIDATABLE_LANGUAGES.has(lang)) {
+        return {
+            code,
+            componentId,
+            apiName,
+            valid: true,
+            diagnostics: [],
+        };
+    }
+    const isJs = lang === 'javascript' || lang === 'js';
+    const fileName = isJs ? 'example.js' : 'example.ts';
+    const scriptKind = isJs ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+    const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, scriptKind);
+    // Collect parse diagnostics (syntax errors only)
+    const diagnostics = [];
+    // TypeScript's createSourceFile doesn't expose parseDiagnostics directly,
+    // so we use a minimal compiler host for syntax-only check
+    const compilerOptions = {
+        noEmit: true,
+        allowJs: true,
+        target: ts.ScriptTarget.Latest,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        // Loose settings — we only care about syntax, not type errors
+        strict: false,
+        noImplicitAny: false,
+        skipLibCheck: true,
+    };
+    const host = ts.createCompilerHost(compilerOptions);
+    const originalGetSourceFile = host.getSourceFile;
+    host.getSourceFile = (fileName, languageVersion) => {
+        if (fileName === sourceFile.fileName) {
+            return sourceFile;
+        }
+        return originalGetSourceFile.call(host, fileName, languageVersion);
+    };
+    host.fileExists = fileName => fileName === sourceFile.fileName || ts.sys.fileExists(fileName);
+    host.readFile = fileName => fileName === sourceFile.fileName ? code : ts.sys.readFile(fileName);
+    const program = ts.createProgram([sourceFile.fileName], compilerOptions, host);
+    // Only get syntactic diagnostics (parse errors), not semantic
+    const syntacticDiags = program.getSyntacticDiagnostics(sourceFile);
+    for (const diag of syntacticDiags) {
+        const message = ts.flattenDiagnosticMessageText(diag.messageText, '\n');
+        const line = diag.file && diag.start !== undefined
+            ? diag.file.getLineAndCharacterOfPosition(diag.start).line + 1
+            : 0;
+        diagnostics.push(`Line ${line}: ${message}`);
+    }
+    return {
+        code,
+        componentId,
+        apiName,
+        valid: diagnostics.length === 0,
+        diagnostics,
+    };
+}
+/**
+ * @codexApi {"parent":"pithy.codex.validate","name":"validateExtractionResult","stability":"stable","signature":"(result: ExtendedExtractionResult) => ValidationResult"}
+ *
+ * Validates all extracted examples from an extraction pipeline result.
+ * Checks that TypeScript/JavaScript examples are syntactically valid.
+ *
+ * @param result - The extraction result to validate
+ * @returns Aggregate validation result
+ */
+export function validateExtractionResult(result) {
+    const startTime = performance.now();
+    const invalidExamples = [];
+    let totalExamples = 0;
+    let validCount = 0;
+    let invalidCount = 0;
+    let skippedCount = 0;
+    for (const component of result.components) {
+        // Validate component-level examples
+        for (const example of component.examples) {
+            totalExamples++;
+            if (!VALIDATABLE_LANGUAGES.has(example.language.toLowerCase())) {
+                skippedCount++;
+                continue;
+            }
+            const validation = validateExampleSyntax(example.code, component.id, undefined, example.language);
+            if (validation.valid) {
+                validCount++;
+            }
+            else {
+                invalidCount++;
+                invalidExamples.push(validation);
+            }
+        }
+        // Validate API-level examples
+        for (const api of component.apis) {
+            for (const example of api.examples) {
+                totalExamples++;
+                if (!VALIDATABLE_LANGUAGES.has(example.language.toLowerCase())) {
+                    skippedCount++;
+                    continue;
+                }
+                const validation = validateExampleSyntax(example.code, component.id, api.name, example.language);
+                if (validation.valid) {
+                    validCount++;
+                }
+                else {
+                    invalidCount++;
+                    invalidExamples.push(validation);
+                }
+            }
+        }
+    }
+    return {
+        totalExamples,
+        validCount,
+        invalidCount,
+        skippedCount,
+        invalidExamples,
+        totalTimeMs: performance.now() - startTime,
+    };
+}
+/**
+ * @codexApi {"parent":"pithy.codex.validate","name":"formatValidationReport","stability":"stable","signature":"(result: ValidationResult) => string"}
+ *
+ * Formats a human-readable validation report.
+ *
+ * @param result - Validation result to format
+ * @returns Formatted report string
+ */
+export function formatValidationReport(result) {
+    const lines = [
+        '📋 Example Validation Report',
+        '',
+        `Total examples: ${result.totalExamples}`,
+        `  ✅ Valid: ${result.validCount}`,
+        `  ❌ Invalid: ${result.invalidCount}`,
+        `  ⏭  Skipped: ${result.skippedCount}`,
+        `  ⏱  Time: ${result.totalTimeMs.toFixed(0)}ms`,
+    ];
+    if (result.invalidExamples.length > 0) {
+        lines.push('');
+        lines.push('Invalid Examples:');
+        for (const ex of result.invalidExamples) {
+            const location = ex.apiName
+                ? `${ex.componentId}.${ex.apiName}`
+                : ex.componentId;
+            lines.push(`\n  ── ${location} ──`);
+            const firstLine = ex.code.split('\n')[0] || '';
+            const preview = firstLine.length > 80 ? firstLine.slice(0, 77) + '...' : firstLine;
+            lines.push(`  Code: ${preview}`);
+            for (const diag of ex.diagnostics) {
+                lines.push(`  ${diag}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}

package/dist/watch-cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.watch-cli",
+ *   "title": "Watch CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * Watch mode for codex sync. Monitors source files for changes and
+ * re-runs the sync pipeline automatically.
+ *
+ * Usage:
+ *   pnpm codex watch [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --debounce <ms>     Debounce interval in milliseconds (default: 300)
+ *   --verbose           Show detailed progress
+ */
+export {};

package/dist/watch-cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.watch-cli",
+ *   "title": "Watch CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * Watch mode for codex sync. Monitors source files for changes and
+ * re-runs the sync pipeline automatically.
+ *
+ * Usage:
+ *   pnpm codex watch [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --debounce <ms>     Debounce interval in milliseconds (default: 300)
+ *   --verbose           Show detailed progress
+ */
+import { resolve, relative } from 'node:path';
+import fs from 'node:fs/promises';
+import { watch } from 'node:fs';
+import { runSyncPipeline } from './sync-pipeline.js';
+function parseArgs(args) {
+    const options = {
+        root: process.cwd(),
+        debounceMs: 300,
+        verbose: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--root=')) {
+            options.root = arg.slice('--root='.length);
+            continue;
+        }
+        switch (arg) {
+            case '--root': {
+                const next = args[i + 1];
+                if (!next || next.startsWith('-')) {
+                    console.error('Error: --root option requires a path argument.');
+                    process.exit(1);
+                }
+                options.root = next;
+                i++;
+                break;
+            }
+            case '--debounce': {
+                const next = args[i + 1];
+                if (!next || isNaN(Number(next))) {
+                    console.error('Error: --debounce option requires a number in milliseconds.');
+                    process.exit(1);
+                }
+                options.debounceMs = Number(next);
+                i++;
+                break;
+            }
+            case '--verbose':
+            case '-v':
+                options.verbose = true;
+                break;
+            case '--help':
+            case '-h':
+                printHelp();
+                process.exit(0);
+                break;
+            default:
+                if (arg.startsWith('-')) {
+                    console.warn(`Warning: unknown option "${arg}" (ignored)`);
+                }
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`
+Codex Watch
+
+Watches for source file changes and re-runs the sync pipeline automatically.
+Monitors TypeScript (.ts), JavaScript (.js), and README files in the packages/ directory.
+
+Usage:
+  pithy-codex-watch [options]
+  pnpm --filter @pithyjs/codex watch [-- options]
+
+Options:
+  --root <path>       Project root directory (default: current directory)
+  --debounce <ms>     Debounce interval in milliseconds (default: 300)
+  --verbose, -v       Show detailed progress
+  --help, -h          Show this help message
+
+Examples:
+  # Watch from project root
+  pithy-codex-watch --root ../..
+
+  # Watch with longer debounce
+  pithy-codex-watch --root ../.. --debounce 1000 --verbose
+`);
+}
+/** Directories to watch within the root */
+const WATCH_DIRS = ['packages'];
+/** File patterns to trigger re-sync */
+function shouldTriggerSync(filename) {
+    if (!filename)
+        return false;
+    return (filename.endsWith('.ts') ||
+        filename.endsWith('.js') ||
+        /README(?:\.md)?$/i.test(filename));
+}
+/**
+ * Creates a debounced function that delays invoking func until after
+ * wait milliseconds have elapsed since the last time it was invoked.
+ */
+function debounce(func, wait) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            timeoutId = null;
+            func(...args);
+        }, wait);
+    };
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const options = parseArgs(args);
+    options.root = resolve(options.root);
+    // Verify root 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);
+    }
+    const logger = {
+        log: msg => console.log(msg),
+        warn: msg => console.warn(msg),
+        error: msg => console.error(msg),
+    };
+    let running = false;
+    const runSync = async () => {
+        if (running)
+            return;
+        running = true;
+        console.log('\n🔄 Change detected — re-syncing...\n');
+        try {
+            await runSyncPipeline({
+                root: options.root,
+                verbose: options.verbose,
+            }, logger);
+        }
+        catch (error) {
+            console.error('❌ Sync failed:', error instanceof Error ? error.message : error);
+        }
+        running = false;
+    };
+    const debouncedSync = debounce(runSync, options.debounceMs);
+    // Initial sync
+    console.log('👁  Codex Watch Mode');
+    console.log(`   Root: ${options.root}`);
+    console.log(`   Debounce: ${options.debounceMs}ms`);
+    console.log('');
+    console.log('Running initial sync...');
+    await runSync();
+    // Set up file watchers
+    const activeWatchers = [];
+    const watchDirs = [];
+    for (const dir of WATCH_DIRS) {
+        const fullDir = resolve(options.root, dir);
+        try {
+            await fs.stat(fullDir);
+            watchDirs.push(fullDir);
+        }
+        catch {
+            // Directory doesn't exist, skip
+        }
+    }
+    if (watchDirs.length === 0) {
+        console.error('❌ No watch directories found');
+        process.exit(1);
+    }
+    for (const dir of watchDirs) {
+        // Note: { recursive: true } is supported on Windows and macOS.
+        // On Linux, consider using chokidar for recursive watching.
+        const watcher = watch(dir, { recursive: true }, (_event, filename) => {
+            if (filename && shouldTriggerSync(filename)) {
+                if (options.verbose) {
+                    console.log(`   📄 ${relative(options.root, resolve(dir, filename))}`);
+                }
+                debouncedSync();
+            }
+        });
+        watcher.on('error', err => {
+            console.error(`Watch error on ${dir}:`, err.message);
+        });
+        activeWatchers.push(watcher);
+        console.log(`   Watching: ${relative(options.root, dir)}/`);
+    }
+    // Cleanup on exit
+    process.on('SIGINT', () => {
+        for (const w of activeWatchers) {
+            w.close();
+        }
+        console.log('\n👋 Watch stopped');
+        process.exit(0);
+    });
+    console.log('');
+    console.log('Waiting for changes... (Ctrl+C to stop)');
+}
+main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pithyjs/codex",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "main": "dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./extraction": "./dist/extraction/index.js"
+  },
+  "bin": {
+    "pithy-codex": "dist/cli.js",
+    "pithy-codex-check": "dist/check.js",
+    "pithy-codex-index": "dist/indexer.js",
+    "pithy-codex-extract": "dist/extract-cli.js",
+    "pithy-codex-readme-sync": "dist/readme-sync-cli.js",
+    "pithy-codex-sync": "dist/sync-cli.js",
+    "pithy-codex-validate": "dist/validate-cli.js",
+    "pithy-codex-watch": "dist/watch-cli.js",
+    "pithy-codex-snapshot": "dist/snapshot-cli.js"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.1",
+    "execa": "^9.6.0",
+    "globby": "^14.1.0",
+    "openai": "^5.12.2",
+    "simple-git": "^3.28.0",
+    "typescript": "^5.8.3",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vitest": "3.2.4"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "sync": "node dist/sync.js --root ../../..",
+    "sync:direct": "node dist/sync.js --root ../../.. --no-llm --direct",
+    "sync:debug": "node dist/sync.js --root ../../.. --debug",
+    "sync:prompts": "node dist/sync.js --root ../../.. --emit-prompts --debug",
+    "sync-pipeline": "node dist/sync-cli.js",
+    "validate": "node dist/validate-cli.js",
+    "watch": "node dist/watch-cli.js",
+    "review": "node dist/review.js --root ../../..",
+    "apply": "node dist/apply.js --root ../../..",
+    "check": "node dist/check.js",
+    "index": "node dist/indexer.js",
+    "extract": "node dist/extract-cli.js --root ../..",
+    "readme-sync": "node dist/readme-sync-cli.js --root ../..",
+    "readme-sync:dry": "node dist/readme-sync-cli.js --root ../.. --dry-run --verbose",
+    "snapshot": "node dist/snapshot-cli.js --root ../..",
+    "gen": "pnpm -w --filter @pithyjs/codex sync && pnpm -w --filter @pithyjs/codex review && pnpm -w --filter @pithyjs/codex apply"
+  }
+}