@pithyjs/codex 0.1.0-beta.0

package/dist/schema.js

@@ -0,0 +1,70 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.schema",
+ *   "title": "Entry Schema",
+ *   "category": "feature"
+ * }
+ *
+ * Zod validation schemas for codex entries.
+ */
+import { z } from 'zod';
+/** Zod schema for a requirement ID (RID) with text and criticality flag. */
+const Rid = z.object({
+    id: z.string().min(1), // e.g. RID-FOR-001
+    text: z.string().min(1), // human readable requirement
+    critical: z.boolean().default(false), // CI may require coverage for critical ones
+});
+/** Zod schema for expected test coverage across testing levels. */
+const TestsExpected = z.object({
+    unit: z.array(z.string()).default([]), // list of RID ids
+    integration: z.array(z.string()).default([]),
+    e2e: z.array(z.string()).default([]),
+    property: z.array(z.string()).default([]),
+    contract: z.array(z.string()).default([]),
+});
+/** Zod schema for an API signature entry with name, stability, and optional signature.
+ * @codexApi {"parent":"pithy.codex.schema","name":"ApiSig","stability":"stable","signature":"z.ZodObject<{ name: string; stability: string; signature?: string }>"} */
+export const ApiSig = z.object({
+    name: z.string(),
+    // 'internal' marks exported-but-not-public APIs (e.g. helpers not in the
+    // package barrel). Without it here, the indexer's schema validation silently
+    // drops any atom whose API uses stability:"internal" from codex.index.json.
+    stability: z
+        .enum(['internal', 'experimental', 'stable', 'deprecated'])
+        .default('stable'),
+    signature: z.string().optional(),
+});
+/** Zod schema defining the full structure of a codex entry.
+ * @codexApi {"parent":"pithy.codex.schema","name":"codexSchema","stability":"stable","signature":"z.ZodObject<CodexEntry>"} */
+export const codexSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    category: z.string().min(1), // e.g. "feature", "directive", "runtime"
+    tags: z.array(z.string()).default([]),
+    updated: z.string().datetime(), // keep your field
+    // additions for docs/testing
+    public: z.boolean().default(true),
+    status: z
+        .enum(['draft', 'experimental', 'stable', 'deprecated'])
+        .default('draft'),
+    version: z.string().default('1.0'),
+    owner: z.string().optional(), // e.g. "core@pithy"
+    related: z.array(z.string()).default([]), // other entry ids
+    dependsOn: z.array(z.string()).default([]), // stronger relation for impact analysis
+    apis: z.array(ApiSig).default([]),
+    // testing & traceability
+    rids: z.array(Rid).default([]),
+    acceptance: z.array(z.string()).default([]),
+    tests_expected: TestsExpected.default({}),
+    // optional free-form description (if you don't store content in md yet)
+    summary: z.string().optional(),
+    // future: point to .md body (front-matter) if you switch to md
+    bodyPath: z.string().optional(),
+    // change detection metadata
+    meta: z
+        .object({
+        hash: z.string().optional(), // content hash for change detection
+    })
+        .optional(),
+});

package/dist/snapshot-cli.d.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.snapshot-cli",
+ *   "title": "Snapshot CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * CLI for managing API version snapshots.
+ *
+ * Usage:
+ *   pithy-codex-snapshot <command> [options]
+ *
+ * Commands:
+ *   save   Create and save a snapshot for the current version
+ *   list   List all stored snapshot versions
+ *   diff   Diff two snapshot versions
+ */
+export interface CliOptions {
+    command: 'save' | 'list' | 'diff' | 'help';
+    root: string;
+    versionsDir: string;
+    version?: string;
+    fromVersion?: string;
+    toVersion?: string;
+    verbose: boolean;
+}
+/**
+ * Consume the next argument as a value for an option flag.
+ * Throws if the value is missing or looks like another flag.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"consumeValue","stability":"stable","signature":"(args: string[], index: number, flag: string) => string"}
+ */
+export declare function consumeValue(args: string[], index: number, flag: string): string;
+/**
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"parseArgs","stability":"stable","signature":"(args: string[]) => CliOptions"}
+ */
+export declare function parseArgs(args: string[]): CliOptions;
+/**
+ * Validates and normalizes a path to prevent path traversal attacks
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"validatePath","stability":"stable","signature":"(basePath: string, inputPath: string) => string"}
+ */
+export declare function validatePath(basePath: string, inputPath: string): string;

package/dist/snapshot-cli.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.snapshot-cli",
+ *   "title": "Snapshot CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * CLI for managing API version snapshots.
+ *
+ * Usage:
+ *   pithy-codex-snapshot <command> [options]
+ *
+ * Commands:
+ *   save   Create and save a snapshot for the current version
+ *   list   List all stored snapshot versions
+ *   diff   Diff two snapshot versions
+ */
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runExtractionPipeline, createApiSnapshot, diffSnapshots, detectBreakingChanges, generateChangelog, generateMigrationGuide, } from './extraction/index.js';
+import { saveSnapshot, loadSnapshot, listSnapshots, } from './extraction/snapshot-store.js';
+const DEFAULT_VERSIONS_DIR = 'codex.versions';
+/**
+ * Consume the next argument as a value for an option flag.
+ * Throws if the value is missing or looks like another flag.
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"consumeValue","stability":"stable","signature":"(args: string[], index: number, flag: string) => string"}
+ */
+export function consumeValue(args, index, flag) {
+    const value = args[index];
+    if (value === undefined || value.startsWith('-')) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+/**
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"parseArgs","stability":"stable","signature":"(args: string[]) => CliOptions"}
+ */
+export function parseArgs(args) {
+    const options = {
+        command: 'help',
+        root: process.cwd(),
+        versionsDir: DEFAULT_VERSIONS_DIR,
+        verbose: false,
+    };
+    const VALID_COMMANDS = new Set(['save', 'list', 'diff', 'help']);
+    if (args.length > 0 && !args[0].startsWith('-')) {
+        if (VALID_COMMANDS.has(args[0])) {
+            options.command = args[0];
+        }
+    }
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--root':
+                options.root = consumeValue(args, ++i, '--root');
+                break;
+            case '--dir':
+                options.versionsDir = consumeValue(args, ++i, '--dir');
+                break;
+            case '--version':
+                options.version = consumeValue(args, ++i, '--version');
+                break;
+            case '--from':
+                options.fromVersion = consumeValue(args, ++i, '--from');
+                break;
+            case '--to':
+                options.toVersion = consumeValue(args, ++i, '--to');
+                break;
+            case '--verbose':
+            case '-v':
+                options.verbose = true;
+                break;
+            case '--help':
+            case '-h':
+                options.command = 'help';
+                break;
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`
+Codex API Snapshot Manager
+
+Usage:
+  pithy-codex-snapshot <command> [options]
+
+Commands:
+  save    Save a snapshot for the current version
+  list    List all stored snapshots
+  diff    Compare two snapshot versions
+
+Options:
+  --root <path>       Project root directory (default: current working directory)
+  --dir <path>        Versions directory (default: codex.versions)
+  --version <ver>     Version to save (required for 'save')
+  --from <ver>        From version for diff
+  --to <ver>          To version for diff
+  --verbose, -v       Show detailed progress
+  --help, -h          Show this help message
+
+Examples:
+  # Save a snapshot
+  pithy-codex-snapshot save --version 1.0.0
+
+  # List all snapshots
+  pithy-codex-snapshot list
+
+  # Diff two versions
+  pithy-codex-snapshot diff --from 1.0.0 --to 2.0.0
+`);
+}
+/**
+ * Validates and normalizes a path to prevent path traversal attacks
+ *
+ * @codexApi {"parent":"pithy.codex.snapshot-cli","name":"validatePath","stability":"stable","signature":"(basePath: string, inputPath: string) => string"}
+ */
+export function validatePath(basePath, inputPath) {
+    const resolvedBase = resolve(basePath);
+    const resolvedPath = isAbsolute(inputPath)
+        ? resolve(inputPath)
+        : resolve(basePath, inputPath);
+    const relativePath = relative(resolvedBase, resolvedPath);
+    if (relativePath.startsWith('..' + sep) ||
+        relativePath === '..' ||
+        isAbsolute(relativePath)) {
+        throw new Error(`Security error: Path "${inputPath}" escapes the project root directory`);
+    }
+    return resolvedPath;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const options = parseArgs(args);
+    if (options.command === 'help') {
+        printHelp();
+        return;
+    }
+    options.root = resolve(options.root);
+    const versionsDir = validatePath(options.root, options.versionsDir);
+    switch (options.command) {
+        case 'save': {
+            if (!options.version) {
+                console.error("❌ Error: --version is required for 'save' command");
+                process.exit(1);
+            }
+            if (options.verbose) {
+                console.log(`📸 Creating API snapshot for version ${options.version}...`);
+            }
+            const result = await runExtractionPipeline({ root: options.root });
+            const snapshot = createApiSnapshot(result, options.version);
+            await saveSnapshot(snapshot, versionsDir);
+            console.log(`✅ Snapshot saved: ${versionsDir}/${options.version}.json (${snapshot.entries.length} entries)`);
+            break;
+        }
+        case 'list': {
+            const versions = await listSnapshots(versionsDir);
+            if (versions.length === 0) {
+                console.log('No snapshots found.');
+            }
+            else {
+                console.log(`📦 ${versions.length} snapshot(s):`);
+                for (const v of versions) {
+                    const snap = await loadSnapshot(v, versionsDir);
+                    const entryCount = snap?.entries.length ?? '?';
+                    console.log(`  - ${v} (${entryCount} entries)`);
+                }
+            }
+            break;
+        }
+        case 'diff': {
+            if (!options.fromVersion || !options.toVersion) {
+                console.error("❌ Error: --from and --to are required for 'diff' command");
+                process.exit(1);
+            }
+            const fromSnap = await loadSnapshot(options.fromVersion, versionsDir);
+            const toSnap = await loadSnapshot(options.toVersion, versionsDir);
+            if (!fromSnap) {
+                console.error(`❌ Snapshot not found: ${options.fromVersion}`);
+                process.exit(1);
+            }
+            if (!toSnap) {
+                console.error(`❌ Snapshot not found: ${options.toVersion}`);
+                process.exit(1);
+            }
+            const diff = diffSnapshots(fromSnap, toSnap);
+            const breaking = detectBreakingChanges(diff);
+            if (diff.added.length === 0 &&
+                diff.removed.length === 0 &&
+                diff.changed.length === 0) {
+                console.log('No API changes detected.');
+                return;
+            }
+            const changelog = generateChangelog(diff);
+            console.log(changelog);
+            if (breaking.length > 0) {
+                console.log('');
+                const guide = generateMigrationGuide(breaking);
+                console.log(guide);
+            }
+            break;
+        }
+        default:
+            console.error(`❌ Unknown command: ${options.command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+if (process.argv[1] &&
+    resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+    main().catch(err => {
+        console.error('Fatal error:', err);
+        process.exit(1);
+    });
+}

package/dist/sync-cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.sync-cli",
+ *   "title": "Sync CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * Unified CLI for running the codex sync pipeline (extraction + README sync).
+ *
+ * Usage:
+ *   pnpm codex sync [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --dry-run           Report changes without writing files
+ *   --skip-readme       Skip README marker sync
+ *   --skip-tests        Skip test file analysis
+ *   --verbose           Show detailed progress
+ */
+export {};

package/dist/sync-cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.sync-cli",
+ *   "title": "Sync CLI",
+ *   "category": "plugin"
+ * }
+ *
+ * Unified CLI for running the codex sync pipeline (extraction + README sync).
+ *
+ * Usage:
+ *   pnpm codex sync [options]
+ *
+ * Options:
+ *   --root <path>       Project root directory (default: cwd)
+ *   --dry-run           Report changes without writing files
+ *   --skip-readme       Skip README marker sync
+ *   --skip-tests        Skip test file analysis
+ *   --verbose           Show detailed progress
+ */
+import { resolve } from 'node:path';
+import fs from 'node:fs/promises';
+import { runSyncPipeline } from './sync-pipeline.js';
+function parseArgs(args) {
+    const options = {
+        root: process.cwd(),
+        dryRun: false,
+        skipReadmeSync: false,
+        skipTests: false,
+        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 '--dry-run':
+                options.dryRun = true;
+                break;
+            case '--skip-readme':
+                options.skipReadmeSync = true;
+                break;
+            case '--skip-tests':
+                options.skipTests = true;
+                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 Sync Pipeline
+
+Runs the full codex sync: extraction pipeline → README marker sync.
+Equivalent to running 'codex extract' followed by 'codex readme-sync'.
+
+Usage:
+  pithy-codex-sync [options]
+  pnpm --filter @pithyjs/codex sync-pipeline [-- options]
+
+Options:
+  --root <path>       Project root directory (default: current directory)
+  --dry-run           Report changes without writing files
+  --skip-readme       Skip README marker sync step
+  --skip-tests        Skip test file analysis (faster)
+  --verbose, -v       Show detailed progress
+  --help, -h          Show this help message
+
+Examples:
+  # Full sync from project root
+  pithy-codex-sync --root ../..
+
+  # Preview changes without writing
+  pithy-codex-sync --root ../.. --dry-run --verbose
+
+  # Extract only (no README sync)
+  pithy-codex-sync --root ../.. --skip-readme
+`);
+}
+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),
+    };
+    try {
+        const result = await runSyncPipeline({
+            root: options.root,
+            dryRun: options.dryRun,
+            skipReadmeSync: options.skipReadmeSync,
+            skipTests: options.skipTests,
+            verbose: options.verbose,
+        }, logger);
+        // Always show summary
+        console.log('');
+        console.log(`✨ Extracted ${result.extraction.stats.componentsFound} components with ${result.extraction.stats.apisExtracted} APIs`);
+        if (!options.skipReadmeSync) {
+            const changed = result.readmeSync.filter(r => r.changed);
+            if (changed.length > 0 && options.dryRun) {
+                console.log('');
+                console.log('(dry-run mode — no files were written)');
+            }
+        }
+    }
+    catch (error) {
+        console.error('❌ Sync failed:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+main().catch(err => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/sync-pipeline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.sync-pipeline",
+ *   "title": "Sync Pipeline",
+ *   "category": "feature"
+ * }
+ *
+ * Unified sync pipeline that orchestrates extraction, README sync, and validation.
+ * Used by the `codex sync` CLI command and CI integration.
+ */
+import type { ExtendedExtractionResult, ReadmeSyncResult, CodexLogger } from './extraction/types.js';
+/**
+ * Options for the unified sync pipeline
+ */
+export interface SyncPipelineOptions {
+    /** Project root directory */
+    root: string;
+    /** Whether to perform a dry run (no file writes) */
+    dryRun?: boolean;
+    /** Whether to show verbose output */
+    verbose?: boolean;
+    /** Skip README sync step */
+    skipReadmeSync?: boolean;
+    /** Skip test analysis */
+    skipTests?: boolean;
+}
+/**
+ * Result of the unified sync pipeline
+ */
+export interface SyncPipelineResult {
+    /** Extraction pipeline result */
+    extraction: ExtendedExtractionResult;
+    /** README sync results (empty if skipped) */
+    readmeSync: ReadmeSyncResult[];
+    /** Total time in milliseconds */
+    totalTimeMs: number;
+}
+/**
+ * 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
+ * @codexApi {"parent":"pithy.codex.sync-pipeline","name":"validatePath","stability":"stable","signature":"(basePath: string, inputPath: string) => string"}
+ */
+export declare function validatePath(basePath: string, inputPath: string): string;
+/**
+ * @codexApi {"parent":"pithy.codex.sync-pipeline","name":"runSyncPipeline","stability":"stable","signature":"(options: SyncPipelineOptions, logger?: CodexLogger) => Promise<SyncPipelineResult>"}
+ *
+ * Runs the unified sync pipeline: extraction → README sync.
+ * This is the main entry point used by `pnpm codex sync` and CI.
+ *
+ * @param options - Pipeline configuration
+ * @param logger - Optional logger for output (silent by default)
+ * @returns Pipeline result with extraction data and sync results
+ */
+export declare function runSyncPipeline(options: SyncPipelineOptions, logger?: CodexLogger): Promise<SyncPipelineResult>;

package/dist/sync-pipeline.js

@@ -0,0 +1,104 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.sync-pipeline",
+ *   "title": "Sync Pipeline",
+ *   "category": "feature"
+ * }
+ *
+ * Unified sync pipeline that orchestrates extraction, README sync, and validation.
+ * Used by the `codex sync` CLI command and CI integration.
+ */
+import { resolve, isAbsolute, relative, sep } from 'node:path';
+import fs from 'node:fs/promises';
+import { runExtractionPipeline } from './extraction/pipeline.js';
+import { syncAllReadmes } from './extraction/readme-sync.js';
+const silentLogger = {
+    log: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * 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
+ * @codexApi {"parent":"pithy.codex.sync-pipeline","name":"validatePath","stability":"stable","signature":"(basePath: string, inputPath: string) => string"}
+ */
+export function validatePath(basePath, inputPath) {
+    const resolvedBase = resolve(basePath);
+    const resolvedPath = isAbsolute(inputPath)
+        ? resolve(inputPath)
+        : resolve(basePath, inputPath);
+    const relativePath = relative(resolvedBase, resolvedPath);
+    if (relativePath === '..' ||
+        relativePath.startsWith('..' + sep) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`Security error: Path "${inputPath}" escapes the project root directory`);
+    }
+    return resolvedPath;
+}
+/**
+ * @codexApi {"parent":"pithy.codex.sync-pipeline","name":"runSyncPipeline","stability":"stable","signature":"(options: SyncPipelineOptions, logger?: CodexLogger) => Promise<SyncPipelineResult>"}
+ *
+ * Runs the unified sync pipeline: extraction → README sync.
+ * This is the main entry point used by `pnpm codex sync` and CI.
+ *
+ * @param options - Pipeline configuration
+ * @param logger - Optional logger for output (silent by default)
+ * @returns Pipeline result with extraction data and sync results
+ */
+export async function runSyncPipeline(options, logger = silentLogger) {
+    const startTime = performance.now();
+    const root = resolve(options.root);
+    // Verify root directory exists
+    const stat = await fs.stat(root).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        throw new Error(`Root directory "${root}" does not exist or is not a directory`);
+    }
+    // Step 1: Extraction pipeline
+    logger.log('📂 Running extraction pipeline...');
+    const extraction = await runExtractionPipeline({
+        root,
+        analyzeTests: !options.skipTests,
+        linkReadmes: true,
+        extractRunnableExamples: true,
+    });
+    logger.log(`   Found ${extraction.stats.componentsFound} components with ${extraction.stats.apisExtracted} APIs`);
+    // Step 2: README sync
+    let readmeSync = [];
+    if (!options.skipReadmeSync) {
+        logger.log('📝 Syncing README files...');
+        const syncConfig = {
+            root,
+            dryRun: options.dryRun,
+            verbose: options.verbose,
+        };
+        readmeSync = await syncAllReadmes(extraction, syncConfig);
+        const changed = readmeSync.filter(r => r.changed);
+        const totalMarkers = readmeSync.reduce((sum, r) => sum + r.markersProcessed, 0);
+        const totalUpdated = readmeSync.reduce((sum, r) => sum + r.markersUpdated, 0);
+        logger.log(`   Files scanned: ${readmeSync.length}`);
+        logger.log(`   Files changed: ${changed.length}`);
+        logger.log(`   Markers processed: ${totalMarkers}`);
+        logger.log(`   Markers updated: ${totalUpdated}`);
+        // Report warnings
+        const allWarnings = readmeSync.flatMap(r => r.warnings);
+        if (allWarnings.length > 0) {
+            for (const w of allWarnings) {
+                logger.warn(`   ⚠ ${w}`);
+            }
+        }
+    }
+    else {
+        logger.log('⏭  Skipping README sync');
+    }
+    const totalTimeMs = performance.now() - startTime;
+    logger.log(`\n✅ Sync complete in ${(totalTimeMs / 1000).toFixed(2)}s`);
+    return {
+        extraction,
+        readmeSync,
+        totalTimeMs,
+    };
+}

package/dist/sync.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};