@pithyjs/codex 0.1.0-beta.0

package/README.md

@@ -0,0 +1,4401 @@
+# @pithyjs/codex
+
+AI-powered documentation generation and maintenance for PithyJS. Codex scans source files for structured annotations, extracts API metadata, syncs READMEs with auto-generated content, validates documentation integrity, and detects breaking API changes via snapshot diffing.
+
+## Installation
+
+<!-- @codex:auto install="@pithyjs/codex" -->
+```bash
+npm install @pithyjs/codex
+```
+
+```bash
+pnpm add @pithyjs/codex
+```
+
+```bash
+yarn add @pithyjs/codex
+```
+<!-- @codex:end -->
+
+```typescript
+import { runExtractionPipeline } from '@pithyjs/codex/extraction';
+```
+
+## Overview
+
+Codex is the documentation backbone of PithyJS. It works by:
+
+1. **Scanning** source files for `@codex`, `@codexApi`, and `@codex:example` annotations
+2. **Extracting** JSDoc comments, TypeScript type signatures, and test examples
+3. **Enriching** codex entries with linked API metadata, test coverage, and source locations
+4. **Syncing** README files using `@codex:auto` markers that auto-populate install commands, API tables, examples, and testing matrices
+5. **Validating** that all codex entries have consistent metadata, examples, and test references
+6. **Snapshotting** API surfaces to detect breaking changes between releases
+7. **Generating** changelogs and migration guides via LLM integration (OpenAI)
+
+## CLI Commands
+
+All commands are available as standalone binaries after building the package:
+
+| Command | Description |
+| --- | --- |
+| `pithy-codex` | Main CLI entry point for the sync workflow |
+| `pithy-codex-sync` | Run the full sync pipeline (scan → extract → enrich → validate) |
+| `pithy-codex-check` | Validate codex entry integrity and consistency |
+| `pithy-codex-index` | Regenerate codex index files |
+| `pithy-codex-extract` | Run the 7-phase extraction pipeline |
+| `pithy-codex-readme-sync` | Sync `@codex:auto` markers in README files |
+| `pithy-codex-validate` | Validate extraction results against schemas |
+| `pithy-codex-watch` | Watch mode for automatic re-sync on file changes |
+| `pithy-codex-snapshot` | Save, list, or diff API snapshots for breaking change detection |
+
+### Via pnpm scripts
+
+```bash
+pnpm --filter @pithyjs/codex build        # Build codex tools (required first)
+pnpm --filter @pithyjs/codex sync         # Smart sync (only changed entries)
+pnpm --filter @pithyjs/codex review       # Generate review.md
+pnpm --filter @pithyjs/codex apply        # Apply approved entries
+pnpm --filter @pithyjs/codex check        # Validate integrity
+pnpm --filter @pithyjs/codex index        # Regenerate indexes
+pnpm --filter @pithyjs/codex readme-sync  # Update READMEs with @codex:auto markers
+pnpm --filter @pithyjs/codex snapshot     # Save/list/diff API snapshots
+pnpm --filter @pithyjs/codex extract      # Run extraction pipeline
+pnpm --filter @pithyjs/codex validate     # Validate extraction results
+pnpm --filter @pithyjs/codex watch        # Watch mode for auto-sync
+```
+
+## Extraction Pipeline
+
+The extraction pipeline runs in 7 phases to transform source annotations into rich documentation entries:
+
+1. **Scan** — Discover source files matching configured glob patterns
+2. **Parse** — Extract `@codex` and `@codexApi` annotations from source files
+3. **JSDoc** — Link JSDoc comments to their corresponding declarations
+4. **Types** — Extract TypeScript type signatures and interfaces
+5. **Examples** — Collect `@codex:example` markers from test files
+6. **Tests** — Analyze test coverage and match tests to codex entries
+7. **Enrich** — Combine all extracted data into enriched codex entries with source links
+
+The pipeline is configurable via `ExtractionConfig` and outputs an `ExtractionResult` with stats, enriched components, API entries, test references, and README sections.
+
+## API Reference
+
+<!-- @codex:auto api="pithy.codex.**" format="table" -->
+| API | Component | Signature | Stability | Description |
+| --- | --- | --- | --- | --- |
+| parseCodexAnnotations | annotations | `(content: string) => CodexAnnotation[]` | stable | Parses @codex annotations from source code |
+| parseCodexApiAnnotations | annotations | `(content: string) => CodexApiAnnotation[]` | stable | Parses @codexApi annotations from source code |
+| createSourceDigest | annotations | `(content: string) => string` | stable | Creates a stable content hash for a source file |
+| createCanonicalFingerprint | annotations | `(component: DiscoveredComponent) => string` | stable | Creates a canonical fingerprint for a discovered component |
+| discoverComponentsFromFile | annotations | `(filePath: string, content?: string) => Promise<DiscoveredComponent[]>` | stable | Discovers components from a single source file using annotations |
+| validateAnnotation | annotations | `(annotation: unknown, type: 'codex' | 'codexApi') => boolean` | stable | Validates annotation format and logs issues in DEV mode |
+| CHANGED_ONLY_PATHSPEC | changed-scope | `readonly string[]` | stable | - |
+| loadEnv | env | `() => void` | stable | Loads environment variables from .env files using dotenv. |
+| askLLM | llm | `(messages: { role: 'system' | 'user'; content: string }[]) => Promise<string>` | stable | Sends a prompt to the OpenAI API and returns the response text. |
+| scan | scan | `(root: string, files?: string[]) => Promise<Candidate[]>` | stable | Scans source files for @codex annotations and returns discovered components/APIs. |
+| combineFingerprints | scan | `(fingerprints: string[]) => string` | internal | Fold the per-file fingerprints of one `@codex` id into a single stable one.  Sorts the COMPLETE list before hashing, which is what makes the result independent of scan order. Folding pairwise — `hash(sort([acc, next]))` — looks equivalent and is not: SHA-256 is not associative, so sorting at each step only commutes for two inputs. With three or more (and `pithy.doctor.rules` is declared by 22 files) a different scan order yields a different fingerprint for identical sources, which reports every entry as changed at random. |
+| ApiSig | schema | `z.ZodObject<{ name: string; stability: string; signature?: string }>` | stable | Zod schema for an API signature entry with name, stability, and optional signature. |
+| codexSchema | schema | `z.ZodObject<CodexEntry>` | stable | Zod schema defining the full structure of a codex entry. |
+| CodexEntry | schema | `z.infer<typeof codexSchema>` | stable | Inferred TypeScript type from the codex schema. |
+| consumeValue | snapshot-cli | `(args: string[], index: number, flag: string) => string` | stable | Consume the next argument as a value for an option flag. Throws if the value is missing or looks like another flag. |
+| parseArgs | snapshot-cli | `(args: string[]) => CliOptions` | stable | - |
+| validatePath | snapshot-cli | `(basePath: string, inputPath: string) => string` | stable | Validates and normalizes a path to prevent path traversal attacks |
+| validatePath | sync-pipeline | `(basePath: string, inputPath: string) => string` | stable | Validates and normalizes a path to prevent path traversal attacks |
+| runSyncPipeline | sync-pipeline | `(options: SyncPipelineOptions, logger?: CodexLogger) => Promise<SyncPipelineResult>` | stable | - |
+| validateExampleSyntax | validate | `(code: string, componentId?: string, apiName?: string, language?: string) => ExampleValidationResult` | stable | - |
+| validateExtractionResult | validate | `(result: ExtendedExtractionResult) => ValidationResult` | stable | - |
+| formatValidationReport | validate | `(result: ValidationResult) => string` | stable | - |
+| createApiSnapshot | breaking-changes | `(result: ExtendedExtractionResult, version: string, timestamp?: string) => ApiSnapshot` | stable | Create an API snapshot from extraction results at a given version. Captures all enriched API entries across all components. |
+| snapshotFromTypeDefinitions | breaking-changes | `(types: ExtractedTypeDefinition[], version: string, timestamp?: string) => ApiSnapshot` | stable | Create an API snapshot from extracted type definitions. Only includes exported types (public API surface). |
+| diffSnapshots | breaking-changes | `(before: ApiSnapshot, after: ApiSnapshot) => SnapshotDiff` | stable | Compare two API snapshots and produce a structured diff. Matches entries by qualifiedName (parent.name). |
+| classifyChange | breaking-changes | `(change: ApiChange) => ChangeClassification` | stable | 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 |
+| detectBreakingChanges | breaking-changes | `(diff: SnapshotDiff) => ApiChange[]` | stable | Filter a snapshot diff down to only breaking changes (those classified as "major"). |
+| generateMigrationGuide | breaking-changes | `(changes: ApiChange[]) => string` | stable | Generate a human-readable migration guide for a set of breaking changes. Groups changes by parent component and provides before/after comparisons. |
+| generateChangelog | breaking-changes | `(diff: SnapshotDiff) => string` | stable | Generate a changelog in Markdown from a snapshot diff. Sections: Breaking Changes, Added, Changed. Omits empty sections. |
+| extractExamples | example-extractor | `(content: string, baseLocation: SourceLocation) => ExtractedExample[]` | stable | Extracts all code examples from a markdown/documentation string |
+| validateExample | example-extractor | `(code: string, language: string) => { valid: boolean; errors: string[] }` | stable | Validates that a code example is syntactically valid |
+| wrapDoctestInHarness | example-extractor | `(example: ExtractedExample, entryId: string) => string` | stable | Wraps a doctest example in a test harness |
+| extractExamplesFromSource | example-extractor | `(content: string, filePath: string) => { functionName: string; examples: ExtractedExample[] }[]` | stable | Extracts examples from JSDoc @example tags in source code |
+| generateRunnableExampleFile | example-extractor | `(examples: ExtractedExample[], imports: string[]) => string` | stable | Generates a runnable example file from extracted examples |
+| parseJSDocComment | jsdoc-parser | `(comment: string, location: SourceLocation) => ParsedJSDoc` | stable | Parses a single JSDoc comment block |
+| extractJSDocBlocks | jsdoc-parser | `(content: string, filePath: string) => { jsdoc: ParsedJSDoc; followingCode: string }[]` | stable | Extracts all JSDoc blocks from a source file |
+| linkJSDocToDeclarations | jsdoc-parser | `(content: string, filePath: string) => Map<string, ParsedJSDoc>` | stable | Links JSDoc blocks to their associated function/class declarations |
+| extractSignature | jsdoc-parser | `(code: string) => string | undefined` | stable | Extracts function signature from source code |
+| runExtractionPipeline | pipeline | `(config?: Partial<ExtractionConfig>) => Promise<ExtendedExtractionResult>` | stable | - |
+| extractSingleFile | pipeline | `(filePath: string, content?: string) => Promise<EnrichedComponent | null>` | stable | - |
+| generateExtractionReport | pipeline | `(result: ExtractionResult) => string` | stable | - |
+| exportToCodexFormat | pipeline | `(result: ExtractionResult) => object` | stable | - |
+| parseMarkerAttributes | readme-sync | `(attrString: string) => Record<string, string>` | stable | Parses HTML-style attributes from a marker opening tag string. Only quoted attribute values are supported (double or single quotes). Unquoted values like `install=pkg` are ignored by design. |
+| resolveMarkerType | readme-sync | `(attributes: Record<string, string>) => ReadmeMarkerType | null` | stable | Determines marker type from its attributes. |
+| parseReadmeMarkers | readme-sync | `(content: string) => ReadmeMarker[]` | stable | Parses all @codex:auto markers from README content. |
+| matchIdPattern | readme-sync | `(pattern: string, entryId: string) => boolean` | stable | Matches codex entry IDs against a glob-style pattern. Supports: exact match, trailing `*` (one segment), trailing `**` (any depth). |
+| filterByPattern | readme-sync | `(components: EnrichedComponent[], pattern: string) => EnrichedComponent[]` | stable | Filters components by an ID pattern. |
+| stripTestBoilerplate | readme-sync | `(code: string) => string` | stable | Strips test framework boilerplate from example code extracted from tests. Removes it()/test() wrapper, dedents, converts expect() to value comments. |
+| generateInstallContent | readme-sync | `(packageName: string) => string` | stable | Generates install command content for a package. |
+| generateExamplesContent | readme-sync | `(components: EnrichedComponent[], limit?: number, testExamples?: TestExample[], pattern?: string) => string` | stable | Generates examples content from extraction data. Prefers API-level JSDoc examples; falls back to @codex:example test examples when no API examples are found (test examples are safe from feedback loops). |
+| escapeTableCell | readme-sync | `(str: string) => string` | stable | Escapes pipe characters and collapses newlines for use in markdown table cells. |
+| escapeMd | readme-sync | `(str: string) => string` | stable | Escapes markdown special characters in inline text (bold markers, brackets, pipes, backticks). |
+| sanitizeForInlineCode | readme-sync | `(str: string) => string` | stable | Strips backticks from a string so it can safely be wrapped in inline code. |
+| longestBacktickRun | readme-sync | `(str: string) => number` | stable | Returns the length of the longest consecutive run of backticks in a string. |
+| sanitizeLanguage | readme-sync | `(lang: string) => string` | stable | Sanitizes a language identifier for use in fenced code blocks. |
+| generateApiContent | readme-sync | `(components: EnrichedComponent[], format?: string) => string` | stable | Generates API reference table from extraction data. |
+| generateTestingContent | readme-sync | `(components: EnrichedComponent[]) => string` | stable | Generates testing pyramid table from extraction data. Includes a Status column showing coverage completeness based on test references and category-aware testing pyramid requirements. |
+| generateBundleContent | readme-sync | `(_packageName: string) => string` | stable | Placeholder for bundle content generation (not yet implemented). |
+| syncReadmeContent | readme-sync | `(content: string, filePath: string, components: EnrichedComponent[], testExamples?: TestExample[]) => ReadmeSyncResult` | stable | Syncs a single README's content: parses markers, generates content, replaces. |
+| syncAllReadmes | readme-sync | `(extractionResult: ExtendedExtractionResult, config?: ReadmeSyncConfig) => Promise<ReadmeSyncResult[]>` | stable | Syncs all README files matching configured patterns. |
+| getSnapshotPath | snapshot-store | `(dir: string, version: string) => string` | stable | Get the file path for a snapshot of a given version. |
+| saveSnapshot | snapshot-store | `(snapshot: ApiSnapshot, dir: string) => Promise<void>` | stable | Save an API snapshot to disk as a JSON file named `{version}.json`. Creates the target directory if it doesn't exist. |
+| loadSnapshot | snapshot-store | `(version: string, dir: string) => Promise<ApiSnapshot | null>` | stable | Load an API snapshot from disk by version. Returns `null` if the snapshot file does not exist. Throws if the file exists but cannot be parsed. |
+| listSnapshots | snapshot-store | `(dir: string) => Promise<string[]>` | stable | List all stored snapshot versions, sorted by semver (with lexicographic fallback). Returns an empty array if the directory does not exist. |
+| DeclarationLocation | source-linker | `interface DeclarationLocation { name: string; type: string; location: SourceLocation; signature?: string; exported: boolean }` | stable | Result of finding a declaration in source code |
+| findDeclarationLocation | source-linker | `(content: string, filePath: string, declarationName: string) => DeclarationLocation | undefined` | stable | Finds the source location of a declaration by name |
+| extractAllDeclarations | source-linker | `(content: string, filePath: string) => DeclarationLocation[]` | stable | Extracts all declarations from a source file |
+| parseReadmeSections | source-linker | `(content: string, filePath: string) => ReadmeSection[]` | stable | Parses README content into sections |
+| linkReadmeToEntries | source-linker | `(sections: ReadmeSection[], entryIds: string[]) => ReadmeSection[]` | stable | Links README sections to codex entry IDs based on heading matching |
+| generateSourceLink | source-linker | `(location: SourceLocation, repoUrl: string, branch?: string) => string` | stable | Generates source links for display (GitHub-style URLs) |
+| toRelativePath | source-linker | `(absolutePath: string, projectRoot: string) => string` | stable | Creates a relative path from project root |
+| enrichSourceLocation | source-linker | `(location: SourceLocation, content: string) => SourceLocation & { context?: string }` | stable | Enriches source locations with additional context |
+| extractTestExamples | test-example-extractor | `(content: string, filePath: string) => TestExample[]` | stable | - |
+| parseVitestOutput | test-example-extractor | `(output: string) => TestStatus[]` | stable | - |
+| matchExamplesToStatuses | test-example-extractor | `(examples: TestExample[], statuses: TestStatus[]) => TestExample[]` | stable | - |
+| generateExampleReport | test-example-extractor | `(examples: TestExample[]) => string` | stable | - |
+| validateTestExamples | test-example-extractor | `(examples: TestExample[]) => { valid: TestExample[]; invalid: TestExample[] }` | experimental | - |
+| extractTestCases | test-pattern-extractor | `(content: string, filePath: string) => ExtractedTestCase[]` | stable | Extracts test cases from a single test file |
+| extractTestImports | test-pattern-extractor | `(content: string) => string[]` | stable | Extracts imports from a test file to identify tested modules |
+| identifyCoveredApis | test-pattern-extractor | `(content: string, knownApis: string[]) => string[]` | stable | Identifies which APIs are likely covered by a test file |
+| analyzeTestFile | test-pattern-extractor | `(content: string, filePath: string, knownApis?: string[]) => TestFileAnalysis` | stable | Analyzes a test file and returns structured analysis |
+| testCasesToReferences | test-pattern-extractor | `(testCases: ExtractedTestCase[], filePath: string) => TestReference[]` | stable | Converts test cases to test references for linking to codex entries |
+| matchTestToEntry | test-pattern-extractor | `(testFilePath: string, entryIds: string[]) => string | undefined` | stable | Matches test files to codex entry IDs based on naming conventions |
+| generateCoverageSummary | test-pattern-extractor | `(analyses: TestFileAnalysis[]) => { totalTests: number; byType: Record<string, number>; coveredApis: string[] }` | stable | Generates a test coverage summary for display |
+| getTestingDefaults | testing-pyramid | `(category: string) => TestingRequirements` | stable | Get the default testing requirements for a given codex category. Returns feature defaults for unknown categories. Returns a fresh copy — callers may mutate freely. |
+| applyRiskModifiers | testing-pyramid | `(base: TestingRequirements, risk: RiskLevel | undefined) => TestingRequirements` | stable | Apply risk-level modifiers to testing requirements. Returns a new object — does not mutate the input. |
+| resolveTestingRequirements | testing-pyramid | `(category: string, risk?: RiskLevel, override?: TestingRequirements) => TestingRequirements` | stable | Resolve the final testing requirements for a codex entry. Merges annotation overrides with category defaults and applies risk modifiers. |
+| computeTestingStatus | testing-pyramid | `(reqs: TestingRequirements) => string` | stable | 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. |
+| extractTypesFromFile | type-extractor | `(filePath: string, content: string) => ExtractedTypeDefinition[]` | stable | - |
+| getTypeSignature | type-extractor | `(def: ExtractedTypeDefinition) => string` | stable | - |
+| generateMethodTable | type-extractor | `(def: ExtractedTypeDefinition) => string` | stable | - |
+<!-- @codex:end -->
+
+## Examples
+
+<!-- @codex:auto examples="pithy.codex.**" -->
+**parseCodexAnnotations**
+
+```typescript
+describe("parseCodexAnnotations", () => {
+  it("parses a simple flat annotation", () => {
+    const source = `/** ${CX}{ "id": "pithy.signals.signal", "title": "Signal", "category": "feature" } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].id; // → "pithy.signals.signal"
+    result[0].title; // → "Signal"
+    result[0].category; // → "feature"
+  });
+
+  it("parses annotation with risk field", () => {
+    const source = `/** ${CX}{ "id": "pithy.core.html", "title": "HTML", "category": "runtime", "risk": "high" } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].risk; // → "high"
+  });
+
+  it("parses annotation with nested testing field (2 levels of nesting)", () => {
+    const source = `/** ${CX}{ "id": "pithy.signals.signal", "title": "Signal", "category": "feature", "testing": { "unit": { "required": true, "covered": true, "file": "signal.test.ts" } } } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].testing; // → defined
+    result[0].testing!.unit; // → defined
+    result[0].testing!.unit!.required; // → true
+    result[0].testing!.unit!.covered; // → true
+    result[0].testing!.unit!.file; // → "signal.test.ts"
+  });
+
+  it("parses annotation with multiple nested testing levels", () => {
+    const source = `/** ${CX}{ "id": "x", "title": "X", "category": "feature", "testing": { "unit": { "required": true }, "integration": { "required": true }, "e2e": { "required": false } } } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].testing!.unit!.required; // → true
+    result[0].testing!.integration!.required; // → true
+    result[0].testing!.e2e!.required; // → false
+  });
+
+  it("parses multi-line annotation with nested testing", () => {
+    const source = `/**
+ * ${CX}
+ * { "id": "x", "title": "X", "category": "feature", "risk": "critical", "testing": { "unit": { "required": true, "covered": false } } }
+ */`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].risk; // → "critical"
+    result[0].testing!.unit!.required; // → true
+  });
+
+  it("returns empty array for invalid JSON", () => {
+    const source = `/** ${CX}{ not valid json } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → []
+  });
+
+  it("returns empty array for annotation missing required fields", () => {
+    const source = `/** ${CX}{ "id": "x" } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → []
+  });
+
+  it("rejects annotation with invalid risk via validateAnnotation", () => {
+    const source = `/** ${CX}{ "id": "x", "title": "X", "category": "feature", "risk": "extreme" } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → []
+  });
+
+  it("rejects annotation with invalid testing shape via validateAnnotation", () => {
+    const source = `/** ${CX}{ "id": "x", "title": "X", "category": "feature", "testing": { "unit": "yes" } } */`;
+    const result = parseCodexAnnotations(source);
+    result; // → []
+  });
+
+  it("parses multiple annotations in same file", () => {
+    const source = `
+/** ${CX}{ "id": "a", "title": "A", "category": "feature" } */
+export function a() {}
+
+/** ${CX}{ "id": "b", "title": "B", "category": "runtime" } */
+export function b() {}
+`;
+    const result = parseCodexAnnotations(source);
+    result; // → 2
+    result[0].id; // → "a"
+    result[1].id; // → "b"
+  });
+
+  it("parses annotation embedded in surrounding code", () => {
+    const source = `
+import { signal } from "./signal.js";
+
+/** ${CX}{ "id": "pithy.core.html", "title": "HTML", "category": "runtime" } */
+export function html(template: string) {
+  return document.createElement("div");
+}
+
+export function other() {}
+`;
+    const result = parseCodexAnnotations(source);
+    result; // → 1
+    result[0].id; // → "pithy.core.html"
+  });
+
+  it("returns empty array for empty content", () => {
+    parseCodexAnnotations(""); // → []
+  });
+});
+```
+
+**parseCodexApiAnnotations**
+
+```typescript
+describe("parseCodexApiAnnotations", () => {
+  it("parses a simple API annotation", () => {
+    const source = `/** ${CXA}{"parent":"pithy.signals","name":"signal","stability":"stable","signature":"<T>(v: T) => Signal<T>"} */`;
+    const result = parseCodexApiAnnotations(source);
+    result; // → 1
+    result[0].parent; // → "pithy.signals"
+    result[0].name; // → "signal"
+    result[0].stability; // → "stable"
+  });
+
+  it("defaults stability to stable", () => {
+    const source = `/** ${CXA}{"parent":"x","name":"fn"} */`;
+    const result = parseCodexApiAnnotations(source);
+    result[0].stability; // → "stable"
+  });
+
+  it("returns empty array for missing required fields", () => {
+    const source = `/** ${CXA}{"parent":"x"} */`;
+    const result = parseCodexApiAnnotations(source);
+    result; // → []
+  });
+
+  it("returns empty array for invalid JSON", () => {
+    const source = `/** ${CXA}{ bad json } */`;
+    const result = parseCodexApiAnnotations(source);
+    result; // → []
+  });
+
+  it("parses multiple API annotations in one file", () => {
+    const source = `
+/** ${CXA}{"parent":"pithy.signals","name":"signal","stability":"stable"} */
+export function signal() {}
+
+/** ${CXA}{"parent":"pithy.signals","name":"effect","stability":"stable"} */
+export function effect() {}
+
+/** ${CXA}{"parent":"pithy.signals","name":"computed","stability":"experimental"} */
+export function computed() {}
+`;
+    const result = parseCodexApiAnnotations(source);
+    result; // → 3
+    result[0].name; // → "signal"
+    result[1].name; // → "effect"
+    result[2].name; // → "computed"
+    result[2].stability; // → "experimental"
+  });
+
+  it("preserves deprecated stability", () => {
+    const source = `/** ${CXA}{"parent":"x","name":"old","stability":"deprecated"} */`;
+    const result = parseCodexApiAnnotations(source);
+    result[0].stability; // → "deprecated"
+  });
+
+  it("returns empty array for empty content", () => {
+    parseCodexApiAnnotations(""); // → []
+  });
+});
+```
+
+**validateAnnotation**
+
+```typescript
+describe("validateAnnotation", () => {
+  it("validates a correct codex annotation", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature" }, "codex"); // → true
+  });
+
+  it("rejects missing required fields", () => {
+    validateAnnotation({ id: "x" }, "codex"); // → false
+  });
+
+  it("rejects invalid category", () => {
+    validateAnnotation({ id: "x", title: "X", category: "invalid" }, "codex"); // → false
+  });
+
+  it("validates valid risk level", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", risk: "critical" }, "codex"); // → true
+    validateAnnotation({ id: "x", title: "X", category: "feature", risk: "low" }, "codex"); // → true
+  });
+
+  it("rejects invalid risk level", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", risk: "ultra" }, "codex"); // → false
+  });
+
+  it("validates valid testing field", () => {
+    const annotation = {
+      id: "x", title: "X", category: "feature",
+      testing: { unit: { required: true }, integration: { required: false } },
+    };
+    validateAnnotation(annotation, "codex"); // → true
+  });
+
+  it("rejects non-object testing field", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: "yes" }, "codex"); // → false
+  });
+
+  it("rejects unknown testing levels", () => {
+    const annotation = {
+      id: "x", title: "X", category: "feature",
+      testing: { performance: { required: true } },
+    };
+    validateAnnotation(annotation, "codex"); // → false
+  });
+
+  it("validates correct codexApi annotation", () => {
+    validateAnnotation({ parent: "x", name: "fn" }, "codexApi"); // → true
+  });
+
+  it("rejects codexApi missing parent", () => {
+    validateAnnotation({ name: "fn" }, "codexApi"); // → false
+  });
+
+  it("rejects codexApi missing name", () => {
+    validateAnnotation({ parent: "x" }, "codexApi"); // → false
+  });
+
+  it("validates all four risk levels", () => {
+    for (const risk of ["critical", "high", "medium", "low"]) {
+      validateAnnotation({ id: "x", title: "X", category: "feature", risk }, "codex"); // → true
+    }
+  });
+
+  it("rejects testing: null", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: null }, "codex"); // → false
+  });
+
+  it("accepts empty testing object", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: {} }, "codex"); // → true
+  });
+
+  it("rejects non-object testing level value (string)", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: "yes" } }, "codex"); // → false
+  });
+
+  it("rejects testing level with non-boolean required", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { required: "yes" } } }, "codex"); // → false
+  });
+
+  it("rejects testing level with coverage > 100", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { coverage: 150 } } }, "codex"); // → false
+  });
+
+  it("rejects testing level with negative coverage", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { coverage: -1 } } }, "codex"); // → false
+  });
+
+  it("accepts valid testing level with required and coverage", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { required: true, coverage: 80 } } }, "codex"); // → true
+  });
+
+  it("rejects testing level with non-boolean covered", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { covered: "yes" } } }, "codex"); // → false
+  });
+
+  it("accepts testing level with boolean covered", () => {
+    validateAnnotation({ id: "x", title: "X", category: "feature", testing: { unit: { required: true, covered: true } } }, "codex"); // → true
+  });
+});
+```
+
+**normalizeSourceContent**
+
+```typescript
+describe("normalizeSourceContent", () => {
+  it("removes block comments", () => {
+    const result = normalizeSourceContent("const a = 1; /* comment */ const b = 2;");
+    result; // → "comment"
+    result; // → "const a = 1;"
+    result; // → "const b = 2;"
+  });
+
+  it("removes line comments", () => {
+    const result = normalizeSourceContent("const a = 1; // line comment\nconst b = 2;");
+    result; // → "line comment"
+    result; // → "const a = 1;"
+    result; // → "const b = 2;"
+  });
+
+  it("preserves @codex annotations", () => {
+    const source = `/** ${CX}{ "id": "x" } */\nconst a = 1;`;
+    const result = normalizeSourceContent(source);
+    result; // → "ANNOTATION:"
+    result; // → "const a = 1;"
+  });
+
+  it("preserves @codexApi annotations", () => {
+    const source = `/** ${CXA}{"parent":"x","name":"fn"} */\nconst a = 1;`;
+    const result = normalizeSourceContent(source);
+    result; // → "ANNOTATION:"
+  });
+
+  it("normalizes whitespace to single spaces", () => {
+    const result = normalizeSourceContent("const   a  =  1;\n\n\n  const b = 2;");
+    result; // → "const a = 1; const b = 2;"
+  });
+
+  it("trims leading and trailing whitespace", () => {
+    const result = normalizeSourceContent("  \n  const a = 1;  \n  ");
+    result; // → "const a = 1;"
+  });
+
+  it("normalizes CRLF to LF", () => {
+    const lf = normalizeSourceContent("const a = 1;\nconst b = 2;");
+    const crlf = normalizeSourceContent("const a = 1;\r\nconst b = 2;");
+    crlf; // → lf
+  });
+
+  it("handles empty content", () => {
+    normalizeSourceContent(""); // → ""
+  });
+
+  it("handles content with only comments", () => {
+    const result = normalizeSourceContent("/* only a comment */\n// and a line comment");
+    result; // → ""
+  });
+});
+```
+
+**createSourceDigest**
+
+```typescript
+describe("createSourceDigest", () => {
+  it("returns a 64-character hex string (SHA-256)", () => {
+    const digest = createSourceDigest("const a = 1;");
+    digest; // → /^[0-9a-f]{64}$/
+  });
+
+  it("is deterministic (same content produces same digest)", () => {
+    const content = "const a = signal(0);";
+    createSourceDigest(content); // → createSourceDigest(content)
+  });
+
+  it("produces different digests for different content", () => {
+    const d1 = createSourceDigest("const a = 1;");
+    const d2 = createSourceDigest("const b = 2;");
+    d1; // → d2
+  });
+
+  it("produces same digest for CRLF vs LF", () => {
+    const lf = createSourceDigest("const a = 1;\nconst b = 2;");
+    const crlf = createSourceDigest("const a = 1;\r\nconst b = 2;");
+    crlf; // → lf
+  });
+
+  it("ignores comment differences", () => {
+    const withComment = createSourceDigest("const a = 1; /* hello */");
+    const withoutComment = createSourceDigest("const a = 1;");
+    withComment; // → withoutComment
+  });
+
+  it("handles empty content", () => {
+    const digest = createSourceDigest("");
+    digest; // → /^[0-9a-f]{64}$/
+  });
+});
+```
+
+**createCanonicalFingerprint**
+
+```typescript
+describe("createCanonicalFingerprint", () => {
+  const baseComponent: DiscoveredComponent = {
+    id: "pithy.signals.signal",
+    title: "Signal",
+    category: "feature",
+    apis: [
+      { parent: "pithy.signals", name: "signal", stability: "stable" },
+      { parent: "pithy.signals", name: "effect", stability: "stable" },
+    ],
+    files: ["signal.ts"],
+    sourceDigest: "abc123",
+  };
+
+  it("returns a 64-character hex string (SHA-256)", () => {
+    const fp = createCanonicalFingerprint(baseComponent);
+    fp; // → /^[0-9a-f]{64}$/
+  });
+
+  it("is deterministic", () => {
+    const fp1 = createCanonicalFingerprint(baseComponent);
+    const fp2 = createCanonicalFingerprint(baseComponent);
+    fp1; // → fp2
+  });
+
+  it("produces same fingerprint regardless of API order", () => {
+    const reversed: DiscoveredComponent = {
+      ...baseComponent,
+      apis: [
+        { parent: "pithy.signals", name: "effect", stability: "stable" },
+        { parent: "pithy.signals", name: "signal", stability: "stable" },
+      ],
+    };
+    createCanonicalFingerprint(baseComponent); // → createCanonicalFingerprint(reversed)
+  });
+
+  it("produces different fingerprints for different components", () => {
+    const other: DiscoveredComponent = {
+      ...baseComponent,
+      id: "pithy.signals.computed",
+      title: "Computed",
+    };
+    createCanonicalFingerprint(baseComponent); // → createCanonicalFingerprint(other)
+  });
+
+  it("produces different fingerprints when sourceDigest differs", () => {
+    const other: DiscoveredComponent = { ...baseComponent, sourceDigest: "different" };
+    createCanonicalFingerprint(baseComponent); // → createCanonicalFingerprint(other)
+  });
+
+  it("ignores files array (not part of canonical form)", () => {
+    const other: DiscoveredComponent = { ...baseComponent, files: ["other.ts", "extra.ts"] };
+    createCanonicalFingerprint(baseComponent); // → createCanonicalFingerprint(other)
+  });
+});
+```
+
+**discoverComponentsFromFile**
+
+```typescript
+describe("discoverComponentsFromFile", () => {
+  it("discovers a component with matching API annotations", async () => {
+    const source = `
+/** ${CX}{ "id": "pithy.signals", "title": "Signals", "category": "feature" } */
+
+/** ${CXA}{"parent":"pithy.signals","name":"signal","stability":"stable"} */
+export function signal() {}
+
+/** ${CXA}{"parent":"pithy.signals","name":"effect","stability":"stable"} */
+export function effect() {}
+`;
+    const result = await discoverComponentsFromFile("signals.ts", source);
+    result; // → 1
+    result[0].id; // → "pithy.signals"
+    result[0].title; // → "Signals"
+    result[0].category; // → "feature"
+    result[0].apis; // → 2
+    result[0].apis[0].name; // → "signal"
+    result[0].apis[1].name; // → "effect"
+    result[0].files; // → ["signals.ts"]
+    result[0].sourceDigest; // → /^[0-9a-f]{64}$/
+  });
+
+  it("discovers multiple components from one file", async () => {
+    const source = `
+/** ${CX}{ "id": "a", "title": "A", "category": "feature" } */
+/** ${CX}{ "id": "b", "title": "B", "category": "runtime" } */
+`;
+    const result = await discoverComponentsFromFile("multi.ts", source);
+    result; // → 2
+    result[0].id; // → "a"
+    result[1].id; // → "b"
+  });
+
+  it("assigns APIs only to their parent component", async () => {
+    const source = `
+/** ${CX}{ "id": "comp-a", "title": "A", "category": "feature" } */
+/** ${CX}{ "id": "comp-b", "title": "B", "category": "runtime" } */
+
+/** ${CXA}{"parent":"comp-a","name":"fn1"} */
+/** ${CXA}{"parent":"comp-b","name":"fn2"} */
+/** ${CXA}{"parent":"comp-b","name":"fn3"} */
+`;
+    const result = await discoverComponentsFromFile("multi.ts", source);
+    result[0].apis; // → 1
+    result[0].apis[0].name; // → "fn1"
+    result[1].apis; // → 2
+    result[1].apis[0].name; // → "fn2"
+  });
+
+  it("returns empty array for content with no annotations", async () => {
+    const result = await discoverComponentsFromFile("plain.ts", "const a = 1;");
+    result; // → []
+  });
+
+  it("returns empty array for empty content", async () => {
+    const result = await discoverComponentsFromFile("empty.ts", "");
+    result; // → []
+  });
+
+  it("returns empty APIs when no @codexApi matches component", async () => {
+    const source = `
+/** ${CX}{ "id": "lonely", "title": "Lonely", "category": "feature" } */
+/** ${CXA}{"parent":"other-component","name":"fn"} */
+`;
+    const result = await discoverComponentsFromFile("lonely.ts", source);
+    result; // → 1
+    result[0].apis; // → []
+  });
+
+  it("carries risk and testing fields from annotation to component", async () => {
+    const source = `
+/** ${CX}{ "id": "pithy.core.html", "title": "HTML", "category": "runtime", "risk": "high", "testing": { "unit": { "required": true } } } */
+`;
+    const result = await discoverComponentsFromFile("html.ts", source);
+    result; // → 1
+    result[0].risk; // → "high"
+    result[0].testing; // → { unit: { required: true } }
+  });
+
+  it("leaves risk and testing undefined when annotation omits them", async () => {
+    const source = `
+/** ${CX}{ "id": "pithy.core.simple", "title": "Simple", "category": "feature" } */
+`;
+    const result = await discoverComponentsFromFile("simple.ts", source);
+    result; // → 1
+    result[0].risk; // → undefined
+    result[0].testing; // → undefined
+  });
+});
+```
+
+**parseArgs**
+
+```typescript
+describe("parseArgs", () => {
+  it("defaults to help command with no args", () => {
+    const opts = parseArgs([]);
+    opts.command; // → "help"
+  });
+
+  it("parses save command with version", () => {
+    const opts = parseArgs(["save", "--version", "1.0.0"]);
+    opts.command; // → "save"
+    opts.version; // → "1.0.0"
+  });
+
+  it("parses diff command with from and to", () => {
+    const opts = parseArgs(["diff", "--from", "1.0.0", "--to", "2.0.0"]);
+    opts.command; // → "diff"
+    opts.fromVersion; // → "1.0.0"
+    opts.toVersion; // → "2.0.0"
+  });
+
+  it("parses list command", () => {
+    const opts = parseArgs(["list"]);
+    opts.command; // → "list"
+  });
+
+  it("parses verbose flag", () => {
+    const opts = parseArgs(["save", "-v", "--version", "1.0.0"]);
+    opts.verbose; // → true
+  });
+
+  it("parses --help flag overriding command", () => {
+    const opts = parseArgs(["save", "--help"]);
+    opts.command; // → "help"
+  });
+
+  it("parses custom root and dir", () => {
+    const opts = parseArgs(["list", "--root", "/my/project", "--dir", "versions"]);
+    opts.root; // → "/my/project"
+    opts.versionsDir; // → "versions"
+  });
+
+  it("throws when --root has no value", () => {
+    expect(() => parseArgs(["list", "--root"])).toThrow(/Missing value for --root/);
+  });
+
+  it("throws when --version value looks like a flag", () => {
+    expect(() => parseArgs(["save", "--version", "--from"])).toThrow(/Missing value for --version/);
+  });
+
+  it("throws when --from has no value", () => {
+    expect(() => parseArgs(["diff", "--from"])).toThrow(/Missing value for --from/);
+  });
+
+  it("throws when --dir value looks like a flag", () => {
+    expect(() => parseArgs(["list", "--dir", "--verbose"])).toThrow(/Missing value for --dir/);
+  });
+});
+```
+
+**validatePath**
+
+```typescript
+describe("validatePath", () => {
+  it("accepts a relative path within the base", () => {
+    const result = validatePath("/project", "codex.versions");
+    result; // → resolve("/project", "codex.versions")
+  });
+
+  it("accepts a nested relative path", () => {
+    const result = validatePath("/project", "data/versions");
+    result; // → resolve("/project", "data/versions")
+  });
+
+  it("rejects a path that escapes the base via ..", () => {
+    expect(() => validatePath("/project", "../../etc/passwd")).toThrow(/Security error/);
+  });
+
+  it("rejects an absolute path outside the base", () => {
+    expect(() => validatePath("/project", "/etc/passwd")).toThrow(/Security error/);
+  });
+
+  it("accepts an absolute path within the base", () => {
+    const result = validatePath("/project", resolve("/project", "codex.versions"));
+    result; // → resolve("/project", "codex.versions")
+  });
+
+  it("accepts a directory name starting with .. (e.g. ..foo)", () => {
+    const result = validatePath("/project", "..foo");
+    result; // → resolve("/project", "..foo")
+  });
+});
+```
+
+**consumeValue**
+
+```typescript
+describe("consumeValue", () => {
+  it("returns the value at the given index", () => {
+    consumeValue(["--root", "/foo"], 1, "--root"); // → "/foo"
+  });
+
+  it("throws for undefined value (past end of array)", () => {
+    expect(() => consumeValue(["--root"], 1, "--root")).toThrow(/Missing value/);
+  });
+
+  it("throws for flag-like value", () => {
+    expect(() => consumeValue(["--root", "--dir"], 1, "--root")).toThrow(/Missing value/);
+  });
+});
+```
+
+**allows paths within the base directory**
+
+```typescript
+const result = validatePath(base, 'src/file.ts');
+result; // → join(base, 'src/file.ts')
+```
+
+**rejects path traversal attempts**
+
+```typescript
+expect(() => validatePath(base, '../../../etc/passwd')).toThrow(
+  'Security error'
+);
+```
+
+**validateExampleSyntax**
+
+```typescript
+describe("validateExampleSyntax", () => {
+  it("accepts valid TypeScript code", () => {
+    const result = validateExampleSyntax(
+      'const x: number = 42;\nconsole.log(x);',
+      "test.component"
+    );
+    result.valid; // → true
+    result.diagnostics; // → 0
+  });
+
+  it("detects syntax errors in TypeScript", () => {
+    const result = validateExampleSyntax(
+      "const x: number = ;",
+      "test.component"
+    );
+    result.valid; // → false
+    expect(result.diagnostics.length).toBeGreaterThan(0);
+    result.diagnostics[0]; // → "Line"
+  });
+
+  it("accepts valid JavaScript code", () => {
+    const result = validateExampleSyntax(
+      'const x = 42;\nconsole.log(x);',
+      "test.component",
+      undefined,
+      "javascript"
+    );
+    result.valid; // → true
+  });
+
+  it("treats unknown languages as valid (skip)", () => {
+    const result = validateExampleSyntax(
+      "this is not code at all {}[]",
+      "test.component",
+      undefined,
+      "markdown"
+    );
+    result.valid; // → true
+    result.diagnostics; // → 0
+  });
+
+  it("preserves componentId and apiName in result", () => {
+    const result = validateExampleSyntax(
+      "const x = 1;",
+      "my.component",
+      "myApi"
+    );
+    result.componentId; // → "my.component"
+    result.apiName; // → "myApi"
+  });
+
+  it("handles empty code string", () => {
+    const result = validateExampleSyntax("", "test.component");
+    result.valid; // → true
+  });
+
+  it("handles multiline code with imports", () => {
+    const code = `
+import { signal } from '@pithyjs/signals';
+
+const count = signal(0);
+const doubled = computed(() => count() * 2);
+console.log(doubled());
+`;
+    const result = validateExampleSyntax(code, "test.component");
+    result.valid; // → true
+  });
+
+  it("detects multiple syntax errors", () => {
+    const code = "const x = ;\nconst y = ;";
+    const result = validateExampleSyntax(code, "test.component");
+    result.valid; // → false
+    expect(result.diagnostics.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("accepts async/await syntax", () => {
+    const code = `
+async function fetchData() {
+  const res = await fetch('/api');
+  return res.json();
+}
+`;
+    const result = validateExampleSyntax(code, "test.component");
+    result.valid; // → true
+  });
+
+  it("handles 'js' as a language alias", () => {
+    const result = validateExampleSyntax(
+      "const x = 1;",
+      "test.component",
+      undefined,
+      "js"
+    );
+    result.valid; // → true
+  });
+
+  it("handles 'ts' as a language alias", () => {
+    const result = validateExampleSyntax(
+      "const x: string = 'hello';",
+      "test.component",
+      undefined,
+      "ts"
+    );
+    result.valid; // → true
+  });
+
+  it("handles code with Unicode characters", () => {
+    const result = validateExampleSyntax(
+      'const msg = "Hello 😀 World";',
+      "test.component"
+    );
+    result.valid; // → true
+  });
+
+  it("accepts type-only errors as valid (only checks syntax)", () => {
+    // Type error: assigning string to number — but syntactically valid
+    const result = validateExampleSyntax(
+      'const x: number = "not a number";',
+      "test.component"
+    );
+    result.valid; // → true
+  });
+});
+```
+
+**validateExtractionResult**
+
+```typescript
+describe("validateExtractionResult", () => {
+  it("returns zero counts for empty extraction", () => {
+    const result = validateExtractionResult(makeExtractionResult());
+    result.totalExamples; // → 0
+    result.validCount; // → 0
+    result.invalidCount; // → 0
+    result.skippedCount; // → 0
+    result.invalidExamples; // → 0
+  });
+
+  it("validates component-level examples", () => {
+    const extraction = makeExtractionResult({
+      components: [
+        {
+          id: "test.comp",
+          title: "Test",
+          category: "feature",
+          apis: [],
+          examples: [
+            {
+              code: "const x = 42;",
+              language: "typescript",
+              runnable: true,
+              isDoctest: false,
+              location: { file: "test.ts", line: 1 },
+            },
+          ],
+          testRefs: [],
+          sourceFiles: [{ file: "test.ts", line: 1 }],
+        },
+      ],
+    });
+
+    const result = validateExtractionResult(extraction);
+    result.totalExamples; // → 1
+    result.validCount; // → 1
+    result.invalidCount; // → 0
+  });
+
+  it("validates API-level examples", () => {
+    const extraction = makeExtractionResult({
+      components: [
+        {
+          id: "test.comp",
+          title: "Test",
+          category: "feature",
+          apis: [
+            {
+              id: "test.comp.myFn",
+              name: "myFn",
+              parent: "test.comp",
+              stability: "stable",
+              examples: [
+                {
+                  code: "const x: number = ;",
+                  language: "typescript",
+                  runnable: true,
+                  isDoctest: false,
+                  location: { file: "test.ts", line: 1 },
+                },
+              ],
+              testRefs: [],
+              sourceLocation: { file: "test.ts", line: 1 },
+            },
+          ],
+          examples: [],
+          testRefs: [],
+          sourceFiles: [{ file: "test.ts", line: 1 }],
+        },
+      ],
+    });
+
+    const result = validateExtractionResult(extraction);
+    result.totalExamples; // → 1
+    result.invalidCount; // → 1
+    result.invalidExamples; // → 1
+    result.invalidExamples[0].apiName; // → "myFn"
+  });
+
+  it("skips non-validatable languages", () => {
+    const extraction = makeExtractionResult({
+      components: [
+        {
+          id: "test.comp",
+          title: "Test",
+          category: "feature",
+          apis: [],
+          examples: [
+            {
+              code: "npm install something",
+              language: "bash",
+              runnable: false,
+              isDoctest: false,
+              location: { file: "test.ts", line: 1 },
+            },
+          ],
+          testRefs: [],
+          sourceFiles: [{ file: "test.ts", line: 1 }],
+        },
+      ],
+    });
+
+    const result = validateExtractionResult(extraction);
+    result.totalExamples; // → 1
+    result.skippedCount; // → 1
+    result.validCount; // → 0
+    result.invalidCount; // → 0
+  });
+
+  it("handles mix of valid, invalid, and skipped", () => {
+    const extraction = makeExtractionResult({
+      components: [
+        {
+          id: "test.comp",
+          title: "Test",
+          category: "feature",
+          apis: [],
+          examples: [
+            {
+              code: "const x = 42;",
+              language: "typescript",
+              runnable: true,
+              isDoctest: false,
+              location: { file: "test.ts", line: 1 },
+            },
+            {
+              code: "const y = ;",
+              language: "typescript",
+              runnable: true,
+              isDoctest: false,
+              location: { file: "test.ts", line: 5 },
+            },
+            {
+              code: "echo hello",
+              language: "bash",
+              runnable: false,
+              isDoctest: false,
+              location: { file: "test.ts", line: 10 },
+            },
+          ],
+          testRefs: [],
+          sourceFiles: [{ file: "test.ts", line: 1 }],
+        },
+      ],
+    });
+
+    const result = validateExtractionResult(extraction);
+    result.totalExamples; // → 3
+    result.validCount; // → 1
+    result.invalidCount; // → 1
+    result.skippedCount; // → 1
+  });
+
+  it("records totalTimeMs", () => {
+    const result = validateExtractionResult(makeExtractionResult());
+    expect(result.totalTimeMs).toBeGreaterThanOrEqual(0);
+  });
+});
+```
+
+**formatValidationReport**
+
+```typescript
+describe("formatValidationReport", () => {
+  it("formats empty result", () => {
+    const report = formatValidationReport({
+      totalExamples: 0,
+      validCount: 0,
+      invalidCount: 0,
+      skippedCount: 0,
+      invalidExamples: [],
+      totalTimeMs: 5,
+    });
+    report; // → "Total examples: 0"
+    report; // → "✅ Valid: 0"
+    report; // → "❌ Invalid: 0"
+  });
+
+  it("formats result with invalid examples", () => {
+    const report = formatValidationReport({
+      totalExamples: 3,
+      validCount: 1,
+      invalidCount: 1,
+      skippedCount: 1,
+      invalidExamples: [
+        {
+          code: "const x = ;",
+          componentId: "test.comp",
+          apiName: "myFn",
+          valid: false,
+          diagnostics: ["Line 1: Expression expected"],
+        },
+      ],
+      totalTimeMs: 42,
+    });
+    report; // → "Total examples: 3"
+    report; // → "Invalid Examples:"
+    report; // → "test.comp.myFn"
+    report; // → "Expression expected"
+  });
+
+  it("shows component ID without apiName", () => {
+    const report = formatValidationReport({
+      totalExamples: 1,
+      validCount: 0,
+      invalidCount: 1,
+      skippedCount: 0,
+      invalidExamples: [
+        {
+          code: "bad code;",
+          componentId: "test.comp",
+          valid: false,
+          diagnostics: ["Line 1: Error"],
+        },
+      ],
+      totalTimeMs: 10,
+    });
+    report; // → "test.comp"
+    report; // → "test.comp."
+  });
+
+  it("includes timing information", () => {
+    const report = formatValidationReport({
+      totalExamples: 0,
+      validCount: 0,
+      invalidCount: 0,
+      skippedCount: 0,
+      invalidExamples: [],
+      totalTimeMs: 123,
+    });
+    report; // → "123ms"
+  });
+});
+```
+
+**createApiSnapshot**
+
+```typescript
+describe("createApiSnapshot", () => {
+  it("creates a snapshot from extraction results", () => {
+    const snap = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "<T>(initial: T) => Signal<T>" },
+      { name: "effect", signature: "(fn: () => void) => () => void" },
+    ]);
+
+    snap.version; // → "1.0.0"
+    snap.entries; // → 2
+    snap.entries[0].name; // → "signal"
+    snap.entries[0].signature; // → "<T>(initial: T) => Signal<T>"
+    snap.entries[1].name; // → "effect"
+    snap.timestamp; // → /^\d{4}-\d{2}-\d{2}/
+  });
+
+  it("captures stability for each API entry", () => {
+    const snap = makeSnapshot("1.0.0", [
+      { name: "oldFn", stability: "deprecated", signature: "() => void" },
+      { name: "newFn", stability: "experimental", signature: "() => void" },
+    ]);
+
+    snap.entries[0].stability; // → "deprecated"
+    snap.entries[1].stability; // → "experimental"
+  });
+
+  it("creates an empty snapshot when no APIs exist", () => {
+    const snap = makeSnapshot("0.0.1", []);
+    snap.entries; // → 0
+    snap.version; // → "0.0.1"
+  });
+
+  it("preserves parent component id for each entry", () => {
+    const snap = makeSnapshot("1.0.0", [{ name: "fn", signature: "()" }]);
+    snap.entries[0].parent; // → "test"
+  });
+});
+```
+
+**snapshotFromTypeDefinitions**
+
+```typescript
+describe("snapshotFromTypeDefinitions", () => {
+  it("creates entries from exported type definitions", () => {
+    const types: ExtractedTypeDefinition[] = [
+      {
+        name: "Signal",
+        kind: "interface",
+        exported: true,
+        members: [
+          { name: "set", type: "method", optional: false, readonly: false },
+          { name: "subscribe", type: "method", optional: false, readonly: false },
+        ],
+        location: loc,
+      },
+    ];
+
+    const snap = snapshotFromTypeDefinitions(types, "1.0.0");
+    snap.version; // → "1.0.0"
+    snap.entries; // → 1
+    snap.entries[0].name; // → "Signal"
+    snap.entries[0].kind; // → "interface"
+    snap.entries[0].signature; // → "export interface Signal"
+  });
+
+  it("skips non-exported type definitions", () => {
+    const types: ExtractedTypeDefinition[] = [
+      {
+        name: "Internal",
+        kind: "interface",
+        exported: false,
+        members: [],
+        location: loc,
+      },
+    ];
+
+    const snap = snapshotFromTypeDefinitions(types, "1.0.0");
+    snap.entries; // → 0
+  });
+
+  it("captures member signatures for interfaces", () => {
+    const types: ExtractedTypeDefinition[] = [
+      {
+        name: "Router",
+        kind: "interface",
+        exported: true,
+        members: [
+          {
+            name: "navigate",
+            type: "method",
+            optional: false,
+            readonly: false,
+            signature: "(path: string) => void",
+          },
+        ],
+        location: loc,
+      },
+    ];
+
+    const snap = snapshotFromTypeDefinitions(types, "1.0.0");
+    snap.entries[0].members; // → 1
+    snap.entries[0].members![0].name; // → "navigate"
+  });
+});
+```
+
+**diffSnapshots**
+
+```typescript
+describe("diffSnapshots", () => {
+  it("detects added APIs", () => {
+    const before = makeSnapshot("1.0.0", [{ name: "signal", signature: "()" }]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "(fn: () => void) => void" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    diff.added; // → 1
+    diff.added[0].name; // → "effect"
+    diff.removed; // → 0
+    diff.changed; // → 0
+  });
+
+  it("detects removed APIs", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "obsolete", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", [{ name: "signal", signature: "()" }]);
+
+    const diff = diffSnapshots(before, after);
+    diff.removed; // → 1
+    diff.removed[0].name; // → "obsolete"
+    diff.added; // → 0
+  });
+
+  it("detects signature changes", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "<T>(v: T) => Signal<T>" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "<T>(v: T, opts?: Options) => Signal<T>" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    diff.changed; // → 1
+    diff.changed[0].name; // → "signal"
+    diff.changed[0].changeKind; // → "signature-changed"
+    expect(diff.changed[0].before?.signature).toBe(
+      "<T>(v: T) => Signal<T>",
+    );
+    expect(diff.changed[0].after?.signature).toBe(
+      "<T>(v: T, opts?: Options) => Signal<T>",
+    );
+  });
+
+  it("detects stability changes", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "fn", stability: "stable", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "fn", stability: "deprecated", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    diff.changed; // → 1
+    diff.changed[0].changeKind; // → "stability-changed"
+  });
+
+  it("reports unchanged APIs count", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "(fn: () => void) => void" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "(fn: () => void) => void" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    diff.unchanged; // → 2
+    diff.added; // → 0
+    diff.removed; // → 0
+    diff.changed; // → 0
+  });
+
+  it("handles empty snapshots", () => {
+    const empty = makeSnapshot("0.0.0", []);
+    const filled = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(empty, filled);
+    diff.added; // → 1
+    diff.removed; // → 0
+  });
+
+  it("handles both snapshots empty", () => {
+    const diff = diffSnapshots(
+      makeSnapshot("0.0.0", []),
+      makeSnapshot("1.0.0", []),
+    );
+    diff.added; // → 0
+    diff.removed; // → 0
+    diff.changed; // → 0
+    diff.unchanged; // → 0
+  });
+
+  it("uses qualified name (parent.name) for matching", () => {
+    const before = createApiSnapshot(
+      {
+        components: [
+          makeComponent("signals", [
+            makeApi({ name: "signal", signature: "()" }),
+          ]),
+          makeComponent("router", [
+            makeApi({ name: "signal", signature: "(path: string) => void" }),
+          ]),
+        ],
+        testAnalysis: [],
+        readmeSections: [],
+        stats: {
+          filesScanned: 0,
+          componentsFound: 2,
+          apisExtracted: 2,
+          examplesExtracted: 0,
+          testsAnalyzed: 0,
+          readmeSectionsLinked: 0,
+          processingTimeMs: 0,
+        },
+        typeDefinitions: [],
+        testExamples: [],
+        testStatuses: [],
+      },
+      "1.0.0",
+    );
+
+    const after = createApiSnapshot(
+      {
+        components: [
+          makeComponent("signals", [
+            makeApi({ name: "signal", signature: "(changed: boolean) => void" }),
+          ]),
+          makeComponent("router", [
+            makeApi({ name: "signal", signature: "(path: string) => void" }),
+          ]),
+        ],
+        testAnalysis: [],
+        readmeSections: [],
+        stats: {
+          filesScanned: 0,
+          componentsFound: 2,
+          apisExtracted: 2,
+          examplesExtracted: 0,
+          testsAnalyzed: 0,
+          readmeSectionsLinked: 0,
+          processingTimeMs: 0,
+        },
+        typeDefinitions: [],
+        testExamples: [],
+        testStatuses: [],
+      },
+      "2.0.0",
+    );
+
+    const diff = diffSnapshots(before, after);
+    // Only the signals.signal changed, router.signal stayed
+    diff.changed; // → 1
+    diff.changed[0].name; // → "signal"
+    diff.changed[0].parent; // → "signals"
+    diff.unchanged; // → 1
+  });
+
+  it("detects combined signature and stability changes", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "fn", stability: "stable", signature: "(a: number) => void" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      {
+        name: "fn",
+        stability: "deprecated",
+        signature: "(a: number, b: string) => void",
+      },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    // Both changes detected; signature change takes priority
+    diff.changed; // → 1
+    diff.changed[0].changeKind; // → "signature-changed"
+  });
+});
+```
+
+**classifyChange**
+
+```typescript
+describe("classifyChange", () => {
+  it("classifies removal as major (breaking)", () => {
+    const change: ApiChange = {
+      name: "obsolete",
+      parent: "test",
+      qualifiedName: "test.obsolete",
+      changeKind: "removed",
+      before: { name: "obsolete", signature: "()", stability: "stable", parent: "test", qualifiedName: "test.obsolete" },
+    };
+    classifyChange(change); // → "major"
+  });
+
+  it("classifies signature change as major (breaking)", () => {
+    const change: ApiChange = {
+      name: "signal",
+      parent: "test",
+      qualifiedName: "test.signal",
+      changeKind: "signature-changed",
+      before: { name: "signal", signature: "(a: T) => S", stability: "stable", parent: "test", qualifiedName: "test.signal" },
+      after: { name: "signal", signature: "(a: T, b: U) => S", stability: "stable", parent: "test", qualifiedName: "test.signal" },
+    };
+    classifyChange(change); // → "major"
+  });
+
+  it("classifies addition as minor (non-breaking)", () => {
+    const change: ApiChange = {
+      name: "effect",
+      parent: "test",
+      qualifiedName: "test.effect",
+      changeKind: "added",
+      after: { name: "effect", signature: "(fn: () => void) => void", stability: "stable", parent: "test", qualifiedName: "test.effect" },
+    };
+    classifyChange(change); // → "minor"
+  });
+
+  it("classifies stable->deprecated as patch", () => {
+    const change: ApiChange = {
+      name: "fn",
+      parent: "test",
+      qualifiedName: "test.fn",
+      changeKind: "stability-changed",
+      before: { name: "fn", signature: "()", stability: "stable", parent: "test", qualifiedName: "test.fn" },
+      after: { name: "fn", signature: "()", stability: "deprecated", parent: "test", qualifiedName: "test.fn" },
+    };
+    classifyChange(change); // → "patch"
+  });
+
+  it("classifies experimental->stable as patch", () => {
+    const change: ApiChange = {
+      name: "fn",
+      parent: "test",
+      qualifiedName: "test.fn",
+      changeKind: "stability-changed",
+      before: { name: "fn", signature: "()", stability: "experimental", parent: "test", qualifiedName: "test.fn" },
+      after: { name: "fn", signature: "()", stability: "stable", parent: "test", qualifiedName: "test.fn" },
+    };
+    classifyChange(change); // → "patch"
+  });
+
+  it("classifies removal of experimental API as minor", () => {
+    const change: ApiChange = {
+      name: "beta",
+      parent: "test",
+      qualifiedName: "test.beta",
+      changeKind: "removed",
+      before: { name: "beta", signature: "()", stability: "experimental", parent: "test", qualifiedName: "test.beta" },
+    };
+    classifyChange(change); // → "minor"
+  });
+
+  it("classifies removal of deprecated API as minor", () => {
+    const change: ApiChange = {
+      name: "old",
+      parent: "test",
+      qualifiedName: "test.old",
+      changeKind: "removed",
+      before: { name: "old", signature: "()", stability: "deprecated", parent: "test", qualifiedName: "test.old" },
+    };
+    classifyChange(change); // → "minor"
+  });
+});
+```
+
+**detectBreakingChanges**
+
+```typescript
+describe("detectBreakingChanges", () => {
+  it("returns only breaking changes from a diff", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "removed", signature: "()" },
+      { name: "changed", signature: "(a: number) => void" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "added", signature: "()" },
+      { name: "changed", signature: "(a: string) => void" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const breaking = detectBreakingChanges(diff);
+
+    breaking; // → 2
+    const names = breaking.map((c) => c.name);
+    names; // → "removed"
+    names; // → "changed"
+  });
+
+  it("returns empty array when no breaking changes exist", () => {
+    const before = makeSnapshot("1.0.0", [{ name: "signal", signature: "()" }]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const breaking = detectBreakingChanges(diff);
+    breaking; // → 0
+  });
+
+  it("does not flag removal of experimental APIs as breaking", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "beta", stability: "experimental", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", []);
+
+    const diff = diffSnapshots(before, after);
+    const breaking = detectBreakingChanges(diff);
+    breaking; // → 0
+  });
+
+  it("does not flag removal of deprecated APIs as breaking", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "old", stability: "deprecated", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", []);
+
+    const diff = diffSnapshots(before, after);
+    const breaking = detectBreakingChanges(diff);
+    breaking; // → 0
+  });
+});
+```
+
+**generateMigrationGuide**
+
+```typescript
+describe("generateMigrationGuide", () => {
+  it("generates guide for removed APIs", () => {
+    const changes: ApiChange[] = [
+      {
+        name: "obsolete",
+        parent: "signals",
+        qualifiedName: "signals.obsolete",
+        changeKind: "removed",
+        before: { name: "obsolete", signature: "(val: T) => void", stability: "stable", parent: "signals", qualifiedName: "signals.obsolete" },
+      },
+    ];
+
+    const guide = generateMigrationGuide(changes);
+    guide; // → "obsolete"
+    guide; // → "removed"
+    guide; // → "Migration Guide"
+  });
+
+  it("generates guide for changed signatures", () => {
+    const changes: ApiChange[] = [
+      {
+        name: "signal",
+        parent: "signals",
+        qualifiedName: "signals.signal",
+        changeKind: "signature-changed",
+        before: { name: "signal", signature: "<T>(v: T) => Signal<T>", stability: "stable", parent: "signals", qualifiedName: "signals.signal" },
+        after: { name: "signal", signature: "<T>(v: T, opts?: Options) => Signal<T>", stability: "stable", parent: "signals", qualifiedName: "signals.signal" },
+      },
+    ];
+
+    const guide = generateMigrationGuide(changes);
+    guide; // → "signal"
+    guide; // → "signature"
+    guide; // → "<T>(v: T) => Signal<T>"
+    guide; // → "<T>(v: T, opts?: Options) => Signal<T>"
+  });
+
+  it("returns empty string for empty changes list", () => {
+    const guide = generateMigrationGuide([]);
+    guide; // → ""
+  });
+
+  it("groups changes by component/parent", () => {
+    const changes: ApiChange[] = [
+      {
+        name: "a",
+        parent: "signals",
+        qualifiedName: "signals.a",
+        changeKind: "removed",
+        before: { name: "a", signature: "()", stability: "stable", parent: "signals", qualifiedName: "signals.a" },
+      },
+      {
+        name: "b",
+        parent: "router",
+        qualifiedName: "router.b",
+        changeKind: "removed",
+        before: { name: "b", signature: "()", stability: "stable", parent: "router", qualifiedName: "router.b" },
+      },
+    ];
+
+    const guide = generateMigrationGuide(changes);
+    guide; // → "signals"
+    guide; // → "router"
+  });
+});
+```
+
+**generateChangelog**
+
+```typescript
+describe("generateChangelog", () => {
+  it("generates changelog with breaking changes section", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "removed", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "added", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+
+    log; // → "Breaking Changes"
+    log; // → "removed"
+    log; // → "added"
+  });
+
+  it("generates changelog with only additions (no breaking section)", () => {
+    const before = makeSnapshot("1.0.0", [{ name: "signal", signature: "()" }]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+
+    log; // → "Breaking Changes"
+    log; // → "Added"
+    log; // → "effect"
+  });
+
+  it("generates changelog for stability changes", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "fn", stability: "experimental", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "fn", stability: "stable", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+
+    log; // → "Changed"
+    log; // → "fn"
+  });
+
+  it("returns empty string for no changes", () => {
+    const before = makeSnapshot("1.0.0", [{ name: "signal", signature: "()" }]);
+    const after = makeSnapshot("2.0.0", [{ name: "signal", signature: "()" }]);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+    log; // → ""
+  });
+
+  it("includes version information in header", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "signal", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", [
+      { name: "signal", signature: "()" },
+      { name: "effect", signature: "()" },
+    ]);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+    log; // → "1.0.0"
+    log; // → "2.0.0"
+  });
+
+  it("generates changelog with mixed breaking and non-breaking removals", () => {
+    const before = makeSnapshot("1.0.0", [
+      { name: "stableRemoved", stability: "stable", signature: "()" },
+      { name: "deprecatedRemoved", stability: "deprecated", signature: "()" },
+    ]);
+    const after = makeSnapshot("2.0.0", []);
+
+    const diff = diffSnapshots(before, after);
+    const log = generateChangelog(diff);
+
+    log; // → "Breaking Changes"
+    log; // → "stableRemoved"
+    log; // → "Changed"
+    log; // → "deprecatedRemoved"
+    log; // → "was deprecated"
+  });
+});
+```
+
+**parseMarkerAttributes**
+
+```typescript
+describe("parseMarkerAttributes", () => {
+  it("parses single attribute with double quotes", () => {
+    const result = parseMarkerAttributes('install="@pithyjs/signals"');
+    result; // → { install: "@pithyjs/signals" }
+  });
+
+  it("parses multiple attributes", () => {
+    const result = parseMarkerAttributes('examples="pithy.signals.*" limit="3"');
+    result; // → { examples: "pithy.signals.*", limit: "3" }
+  });
+
+  it("parses attribute with single quotes", () => {
+    const result = parseMarkerAttributes("api='pithy.signals.*' format='table'");
+    result; // → { api: "pithy.signals.*", format: "table" }
+  });
+
+  it("returns empty object for empty string", () => {
+    parseMarkerAttributes(""); // → {}
+  });
+
+  it("handles whitespace between attributes", () => {
+    const result = parseMarkerAttributes('  install = "@pithyjs/core"  ');
+    result; // → { install: "@pithyjs/core" }
+  });
+});
+```
+
+**resolveMarkerType**
+
+```typescript
+describe("resolveMarkerType", () => {
+  it("resolves 'install' type", () => {
+    resolveMarkerType({ install: "@pithyjs/signals" }); // → "install"
+  });
+
+  it("resolves 'examples' type", () => {
+    resolveMarkerType({ examples: "pithy.signals.*" }); // → "examples"
+  });
+
+  it("resolves 'api' type", () => {
+    resolveMarkerType({ api: "pithy.signals.*" }); // → "api"
+  });
+
+  it("resolves 'bundle' type", () => {
+    resolveMarkerType({ bundle: "@pithyjs/signals" }); // → "bundle"
+  });
+
+  it("resolves 'testing' type", () => {
+    resolveMarkerType({ testing: "pithy.signals.*" }); // → "testing"
+  });
+
+  it("returns null for unknown attributes", () => {
+    resolveMarkerType({ foo: "bar" }); // → null
+  });
+});
+```
+
+**parseReadmeMarkers**
+
+```typescript
+describe("parseReadmeMarkers", () => {
+  it("parses a single install marker", () => {
+    const content = `# Package
+
+<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->
+
+## More`;
+
+    const markers = parseReadmeMarkers(content);
+    markers; // → 1
+    markers[0].type; // → "install"
+    markers[0].attributes; // → { install: "@pithyjs/signals" }
+    markers[0].innerContent; // → "\nold content\n"
+  });
+
+  it("parses multiple markers in one file", () => {
+    const content = `<!-- @codex:auto install="@pithyjs/core" -->
+```bash
+npm install @pithyjs/core
+```
+
+```bash
+pnpm add @pithyjs/core
+```
+
+```bash
+yarn add @pithyjs/core
+```
+<!-- @codex:end -->
+
+<!-- @codex:auto api="pithy.core.*" format="table" -->
+| API | Component | Signature | Stability | Description |
+| --- | --- | --- | --- | --- |
+| LazyState | lazy | `type LazyState = 'idle' | 'loading' | 'loaded' | 'error'` | stable | Possible states for a lazy component |
+| LazyOptions | lazy | `interface LazyOptions` | stable | Options for configuring lazy loading behavior |
+| LazyHandle | lazy | `interface LazyHandle<T>` | stable | Handle returned by lazy() for controlling lazy component loading |
+| lazy | lazy | `<T>(loader: () => Promise<T>, options?: LazyOptions) => LazyHandle<T>` | stable | - |
+| isLazyHandle | lazy | `(value: unknown) => value is LazyHandle<unknown>` | stable | - |
+| preloadLazy | lazy | `<T>(handle: LazyHandle<T>) => Promise<T>` | stable | - |
+| ModuleRecord | module-cache | `interface ModuleRecord<T>` | stable | - |
+| loadModule | module-cache | `<T>(key: string, loader: () => Promise<T>) => Promise<T>` | stable | - |
+| getModuleRecord | module-cache | `<T>(key: string) => ModuleRecord<T> | undefined` | stable | - |
+| invalidateModule | module-cache | `(key: string) => boolean` | stable | - |
+| getResolvedModuleKeys | module-cache | `() => string[]` | stable | - |
+| clearModuleCache | module-cache | `() => void` | stable | - |
+| bindDeferDirectives | bind-defer-directives | `(fragment: DocumentFragment, context: Record<string, unknown>, disposers: Array<() => void>) => void` | stable | - |
+| registerDirectiveBinder | directive-registry | `(binder: DirectiveBinder) => void` | stable | - |
+| unregisterDirectiveBinder | directive-registry | `(binder: DirectiveBinder) => void` | stable | - |
+| executeCustomDirectiveBinders | directive-registry | `(root: Element | DocumentFragment, context: Record<string, unknown>, disposers: Array<() => void>) => void` | stable | - |
+| createResource | resource | `<T, E = unknown>(fetcher: ResourceFetcher<T>, options?: ResourceOptions) => ResourceHandle<T, E>` | stable | - |
+<!-- @codex:end -->`;
+
+    const markers = parseReadmeMarkers(content);
+    markers; // → 2
+    markers[0].type; // → "install"
+    markers[1].type; // → "api"
+  });
+
+  it("handles markers with no inner content", () => {
+    const content = `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`;
+
+    const markers = parseReadmeMarkers(content);
+    markers; // → 1
+    markers[0].innerContent; // → "\n"
+  });
+
+  it("preserves content outside markers", () => {
+    const content = `# Title
+
+Some manual content.
+
+<!-- @codex:auto install="pkg" -->
+```bash
+npm install pkg
+```
+
+```bash
+pnpm add pkg
+```
+
+```bash
+yarn add pkg
+```
+<!-- @codex:end -->
+
+More manual content.`;
+
+    const markers = parseReadmeMarkers(content);
+    markers; // → 1
+    // Markers should have correct indices that don't span the whole file
+    expect(markers[0].startIndex).toBeGreaterThan(0);
+    expect(markers[0].endIndex).toBeLessThan(content.length);
+  });
+
+  it("returns empty array when no markers found", () => {
+    parseReadmeMarkers("# Just a regular README\n\nNo markers here."); // → []
+  });
+
+  it("handles malformed marker (missing @codex:end) gracefully", () => {
+    const content = `<!-- @codex:auto install="@pithyjs/signals" -->
+some content without closing tag`;
+
+    const markers = parseReadmeMarkers(content);
+    markers; // → 0
+  });
+
+  it("assigns correct startIndex and endIndex", () => {
+    const content = `before\n<!-- @codex:auto install="pkg" -->
+```bash
+npm install pkg
+```
+
+```bash
+pnpm add pkg
+```
+
+```bash
+yarn add pkg
+```
+<!-- @codex:end -->\nafter`;
+    const markers = parseReadmeMarkers(content);
+    markers; // → 1
+
+    const reconstructed =
+      content.slice(0, markers[0].startIndex) +
+      markers[0].originalContent +
+      content.slice(markers[0].endIndex);
+    reconstructed; // → content
+  });
+
+  it("stores the original open tag string", () => {
+    const content = `<!-- @codex:auto examples="pithy.signals.*" limit="3" -->
+**creates an effect**
+
+```typescript
+const count = signal(0);
+count(); // → 0
+```
+<!-- @codex:end -->`;
+    const markers = parseReadmeMarkers(content);
+    markers; // → 1
+    markers[0].openTag; // → `<!-- @codex:auto examples="pithy.signals.*" limit="3" -->`
+  });
+});
+```
+
+**generateInstallContent**
+
+````typescript
+describe("generateInstallContent", () => {
+  it("generates npm/pnpm/yarn commands", () => {
+    const content = generateInstallContent("@pithyjs/signals");
+    content; // → "npm install @pithyjs/signals"
+    content; // → "pnpm add @pithyjs/signals"
+    content; // → "yarn add @pithyjs/signals"
+  });
+
+  it("wraps in bash code blocks", () => {
+    const content = generateInstallContent("@pithyjs/signals");
+    content; // → "```bash"
+    content; // → "```"
+  });
+});
+````
+
+**generateExamplesContent**
+
+`````typescript
+describe("generateExamplesContent", () => {
+  it("generates markdown with code blocks from component examples", () => {
+    const comp = makeComponentWithApis();
+    const content = generateExamplesContent([comp]);
+    content; // → "```ts"
+    content; // → "const count = signal(0)"
+  });
+
+  it("respects limit parameter", () => {
+    const comp = makeComponentWithApis();
+    // Add multiple API-level examples (generateExamplesContent reads api.examples, not comp.examples)
+    comp.apis[0].examples = [
+      { code: "example1", language: "ts", runnable: true, isDoctest: false, location: { file: "f", line: 1 } },
+      { code: "example2", language: "ts", runnable: true, isDoctest: false, location: { file: "f", line: 2 } },
+      { code: "example3", language: "ts", runnable: true, isDoctest: false, location: { file: "f", line: 3 } },
+    ];
+    const content = generateExamplesContent([comp], 1);
+    // Should only show 1 example total
+    const codeBlockCount = (content.match(/```ts/g) || []).length;
+    codeBlockCount; // → 1
+  });
+
+  it("treats limit=0 as zero (not unlimited)", () => {
+    const comp = makeComponentWithApis();
+    const content = generateExamplesContent([comp], 0);
+    // limit=0 should select zero examples, not all of them
+    content; // → ""
+    // Verify without limit it would have returned examples
+    const unlimited = generateExamplesContent([comp]);
+    unlimited; // → "```ts"
+  });
+
+  it("uses dynamic fence length when code contains triple backticks", () => {
+    const comp = makeComponent({
+      apis: [{
+        id: "test.api",
+        name: "fn",
+        parent: "test",
+        stability: "stable",
+        examples: [{
+          code: 'const md = `\n```js\nconsole.log("hi");\n```\n`;',
+          language: "ts",
+          runnable: false,
+          isDoctest: false,
+          location: { file: "f.ts", line: 1 },
+        }],
+        testRefs: [],
+        sourceLocation: { file: "f.ts", line: 1 },
+      }],
+    });
+    const content = generateExamplesContent([comp]);
+    // Should use 4 backticks since content contains triple backticks
+    content; // → "````ts"
+    content; // → /````\s*$/m
+    // Should NOT contain a bare triple-backtick fence
+    content; // → /^```ts$/m
+  });
+
+  it("returns placeholder when no examples available", () => {
+    const comp = makeComponent({ apis: [] });
+    const content = generateExamplesContent([comp]);
+    content; // → "No examples"
+  });
+
+  it("includes example descriptions when available", () => {
+    const comp = makeComponentWithApis();
+    const content = generateExamplesContent([comp]);
+    content; // → "Basic usage"
+  });
+
+  it("falls back to test examples when no API examples exist", () => {
+    const comp = makeComponent({ id: "pithy.signals", apis: [] });
+    const testExamples: TestExample[] = [
+      {
+        entryId: "pithy.signals",
+        name: "creates a signal",
+        code: 'const count = signal(0);\nexpect(count()).toBe(0);',
+        location: { file: "signal.test.ts", line: 5 },
+        testFile: "signal.test.ts",
+        status: "passing",
+      },
+    ];
+    const content = generateExamplesContent([comp], undefined, testExamples, "pithy.signals");
+    content; // → "creates a signal"
+    content; // → "const count = signal(0)"
+    // Verify expect() was stripped by stripTestBoilerplate
+    content; // → "expect("
+    content; // → "count(); // → 0"
+  });
+
+  it("prefers API examples over test examples", () => {
+    const comp = makeComponentWithApis(); // has API-level example "Basic usage"
+    const testExamples: TestExample[] = [
+      {
+        entryId: "pithy.signals",
+        name: "test example",
+        code: 'test code',
+        location: { file: "signal.test.ts", line: 5 },
+        testFile: "signal.test.ts",
+        status: "passing",
+      },
+    ];
+    const content = generateExamplesContent([comp], undefined, testExamples, "pithy.signals.*");
+    // Should use API examples, not test examples
+    content; // → "Basic usage"
+    content; // → "test example"
+  });
+
+  it("filters test examples by pattern", () => {
+    const comp = makeComponent({ id: "pithy.signals", apis: [] });
+    const testExamples: TestExample[] = [
+      {
+        entryId: "pithy.signals",
+        name: "signal test",
+        code: 'signal code',
+        location: { file: "signal.test.ts", line: 5 },
+        testFile: "signal.test.ts",
+        status: "passing",
+      },
+      {
+        entryId: "pithy.router",
+        name: "router test",
+        code: 'router code',
+        location: { file: "router.test.ts", line: 5 },
+        testFile: "router.test.ts",
+        status: "passing",
+      },
+    ];
+    const content = generateExamplesContent([comp], undefined, testExamples, "pithy.signals");
+    content; // → "signal code"
+    content; // → "router code"
+  });
+});
+`````
+
+**generateApiContent**
+
+```typescript
+describe("generateApiContent", () => {
+  it("generates markdown table with correct columns", () => {
+    const comp = makeComponentWithApis();
+    const content = generateApiContent([comp]);
+    content; // → "| API |"
+    content; // → "| Signature |"
+    content; // → "| Stability |"
+  });
+
+  it("renders all APIs from matched components", () => {
+    const comp = makeComponentWithApis();
+    const content = generateApiContent([comp]);
+    content; // → "signal"
+    content; // → "effect"
+    content; // → "computed"
+  });
+
+  it("preserves pipe characters in signatures (inside backticks)", () => {
+    const comp = makeComponent({
+      apis: [{
+        id: "test.api",
+        name: "fn",
+        parent: "test",
+        signature: "(a: A | B) => C",
+        stability: "stable",
+        examples: [],
+        testRefs: [],
+        sourceLocation: { file: "f.ts", line: 1 },
+      }],
+    });
+    const content = generateApiContent([comp]);
+    // Signature is inside backticks — pipes don't need escaping in GFM inline code
+    content; // → "`(a: A | B) => C`"
+  });
+
+  it("renders list format when format='list'", () => {
+    const comp = makeComponentWithApis();
+    const content = generateApiContent([comp], "list");
+    content; // → "- **signal**"
+    content; // → "- **effect**"
+    content; // → "[stable]"
+    content; // → "[experimental]"
+    // Should NOT have table syntax
+    content; // → "| API |"
+  });
+
+  it("includes descriptions in list format", () => {
+    const comp = makeComponentWithApis();
+    const content = generateApiContent([comp], "list");
+    content; // → "Creates a reactive signal"
+  });
+
+  it("returns placeholder when no APIs found", () => {
+    const content = generateApiContent([]);
+    content; // → "No API"
+  });
+});
+```
+
+**syncReadmeContent**
+
+```typescript
+describe("syncReadmeContent", () => {
+  it("replaces install marker content", () => {
+    const readme = `# Package
+
+<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    result.changed; // → true
+    result.markersProcessed; // → 1
+    result.updatedContent; // → "npm install @pithyjs/signals"
+  });
+
+  it("replaces API marker content", () => {
+    const comp = makeComponentWithApis();
+    const readme = `# API
+
+<!-- @codex:auto api="pithy.signals.*" format="table" -->
+_No API entries found._
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.changed; // → true
+    result.updatedContent; // → "signal"
+    result.updatedContent; // → "effect"
+  });
+
+  it("handles multiple markers in one file", () => {
+    const comp = makeComponentWithApis();
+    const readme = `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->
+
+<!-- @codex:auto api="pithy.signals.*" -->
+_No API entries found._
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.markersProcessed; // → 2
+    result.markersUpdated; // → 2
+  });
+
+  it("preserves content outside markers", () => {
+    const readme = `# Title
+
+Manual content here.
+
+<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->
+
+More manual content.`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    result.updatedContent; // → "# Title"
+    result.updatedContent; // → "Manual content here."
+    result.updatedContent; // → "More manual content."
+  });
+
+  it("reports changed: false when content is identical after sync", () => {
+    // First sync to get the generated content
+    const readme = `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`;
+    const first = syncReadmeContent(readme, "README.md", []);
+
+    // Second sync with the already-synced content
+    const second = syncReadmeContent(first.updatedContent!, "README.md", []);
+    second.changed; // → false
+  });
+
+  it("reports warnings for unsupported marker types", () => {
+    const readme = `<!-- @codex:auto bundle="@pithyjs/signals" -->
+<!-- Bundle size tracking not yet available -->
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    result.warnings[0]; // → "bundle"
+  });
+
+  it("uses test examples for examples markers when no API examples exist", () => {
+    const comp = makeComponent({
+      id: "pithy.feature.signals",
+      apis: [
+        {
+          id: "pithy.feature.signals.signal",
+          name: "signal",
+          parent: "pithy.feature.signals",
+          stability: "stable",
+          examples: [],
+          testRefs: [],
+          sourceLocation: { file: "signal.ts", line: 1 },
+        },
+      ],
+    });
+    const testExamples: TestExample[] = [
+      {
+        entryId: "pithy.feature.signals",
+        name: "creates a reactive signal",
+        code: 'const count = signal(0);\nexpect(count()).toBe(0);',
+        location: { file: "signal.test.ts", line: 5 },
+        testFile: "signal.test.ts",
+        status: "passing",
+      },
+    ];
+    const readme = `<!-- @codex:auto examples="pithy.feature.signals" -->
+**creates a reactive signal with initial value**
+
+```typescript
+const count = signal(0);
+count(); // → 0
+count.set(1);
+count(); // → 1
+```
+
+**supports functional updates via .set()**
+
+```typescript
+const count = signal(0);
+count.set(n => n + 1);
+count(); // → 1
+count.set(n => n * 10);
+count(); // → 10
+```
+
+**tracks signal dependencies and re-runs**
+
+```typescript
+const count = signal(0);
+let observed = -1;
+effect(() => {
+  observed = count();
+});
+observed; // → 0
+count.set(5);
+observed; // → 5
+```
+
+**derives a value from other signals**
+
+```typescript
+const a = signal(2);
+const b = signal(3);
+const sum = computed(() => a() + b());
+sum(); // → 5
+a.set(10);
+sum(); // → 13
+```
+
+**defers effect execution until batch completes**
+
+```typescript
+const a = signal(1);
+const b = signal(2);
+let runCount = 0;
+effect(() => {
+  a();
+  b();
+  runCount++;
+});
+runCount; // → 1
+
+batch(() => {
+  a.set(10);
+  b.set(20);
+});
+// Effect should have run only once after batch, not twice
+runCount; // → 2
+```
+
+**runs cleanup on disposal**
+
+```typescript
+const count = signal(0);
+let cleaned = false;
+
+const dispose = effect(() => {
+  count();
+  onCleanup(() => {
+    cleaned = true;
+  });
+});
+
+cleaned; // → false
+dispose();
+cleaned; // → true
+```
+
+**detects signal values at runtime**
+
+```typescript
+const count = signal(0);
+isSignal(count); // → true
+isSignal(42); // → false
+isSignal(() => {}); // → false
+isSignal(null); // → false
+```
+
+**unsubscribes from a dependency it stopped reading**
+
+```typescript
+const useB = signal(true);
+const b = signal(2);
+
+let runs = 0;
+const dispose = effect(() => {
+  runs += 1;
+  if (useB()) b();
+});
+
+useB.set(false);
+const afterSwitch = runs;
+
+b.set(99);
+expect(runs, 'live effect re-ran for a dependency it stopped reading').toBe(
+  afterSwitch
+);
+
+dispose();
+```
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp], testExamples);
+    result.changed; // → true
+    result.updatedContent; // → "creates a reactive signal"
+    result.updatedContent; // → "const count = signal(0)"
+    // Verify test boilerplate was stripped
+    result.updatedContent; // → "expect("
+    result.updatedContent; // → "count(); // → 0"
+  });
+
+  it("skips outer marker when nested markers are detected", () => {
+    const readme = `<!-- @codex:auto install="@pithyjs/signals" -->
+<!-- @codex:auto api="pithy.signals.*" -->
+_No API entries found._
+<!-- @codex:end -->
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    // The parser skips the outer marker (its inner content contains another @codex:auto).
+    // Only the inner marker is processed — the outer is treated as malformed.
+    result.markersProcessed; // → 1
+    // The extra <!-- @codex:end --> remains in the file as-is (not corrupted)
+    result.updatedContent ?? readme; // → "<!-- @codex:end -->"
+  });
+
+  it("preserves original open tag attributes (no reordering)", () => {
+    const readme = `<!-- @codex:auto examples="pithy.signals.*" limit="3" -->
+**creates an effect**
+
+```typescript
+const count = signal(0);
+count(); // → 0
+```
+<!-- @codex:end -->`;
+
+    const first = syncReadmeContent(readme, "README.md", []);
+    // The open tag should be preserved exactly as written
+    first.updatedContent; // → `<!-- @codex:auto examples="pithy.signals.*" limit="3" -->`
+  });
+
+  it("warns on empty pattern value", () => {
+    const readme = `<!-- @codex:auto api="" -->
+_No API entries found._
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    result.warnings.some((w) => w.includes("Empty pattern")); // → true
+  });
+
+  it("warns on unknown api format", () => {
+    const comp = makeComponentWithApis();
+    const readme = `<!-- @codex:auto api="pithy.signals.*" format="csv" -->
+_No API entries found._
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.warnings.some((w) => w.includes('Unknown format "csv"')); // → true
+  });
+
+  it("warns on negative limit", () => {
+    const comp = makeComponentWithApis();
+    const readme = `<!-- @codex:auto examples="pithy.signals.*" limit="-1" -->
+
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.warnings.some((w) => w.includes("Negative")); // → true
+  });
+
+  it("returns correct markersProcessed and markersUpdated counts", () => {
+    const readme = `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->
+
+<!-- @codex:auto bundle="@pithyjs/signals" -->
+<!-- Bundle size tracking not yet available -->
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", []);
+    result.markersProcessed; // → 2
+    // Both markers generate content (bundle generates a placeholder)
+    result.markersUpdated; // → 2
+  });
+
+  it("replaces testing marker content", () => {
+    const comp = makeComponentWithApis();
+    const readme = `# Testing
+
+<!-- @codex:auto testing="pithy.signals.*" -->
+_No test data available._
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.changed; // → true
+    result.markersProcessed; // → 1
+    result.updatedContent; // → "signal"
+    result.updatedContent; // → "effect"
+    // Should contain a markdown table
+    result.updatedContent; // → "|"
+  });
+
+  it("warns on non-numeric limit value", () => {
+    const comp = makeComponentWithApis();
+    const readme = `<!-- @codex:auto examples="pithy.signals.*" limit="abc" -->
+**creates an effect**
+
+```typescript
+const count = signal(0);
+count(); // → 0
+```
+<!-- @codex:end -->`;
+
+    const result = syncReadmeContent(readme, "README.md", [comp]);
+    result.warnings.some((w) => w.toLowerCase().includes("limit")); // → true
+  });
+});
+```
+
+**syncAllReadmes**
+
+```typescript
+describe("syncAllReadmes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns empty results when no README files match", async () => {
+    const { globby } = await import("globby");
+    vi.mocked(globby).mockResolvedValue([]);
+
+    const extractionResult = makeExtractionResult();
+    const results = await syncAllReadmes(extractionResult, { root: "/project" });
+    results; // → []
+  });
+
+  it("processes matched README files and returns results", async () => {
+    const { globby } = await import("globby");
+    const { readFile } = await import("node:fs/promises");
+
+    vi.mocked(globby).mockResolvedValue(["/project/README.md"]);
+    vi.mocked(readFile).mockResolvedValue(
+      `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`
+    );
+
+    const extractionResult = makeExtractionResult();
+    const results = await syncAllReadmes(extractionResult, { root: "/project", dryRun: true });
+
+    results; // → 1
+    results[0].filePath; // → "/project/README.md"
+    results[0].changed; // → true
+    results[0].markersProcessed; // → 1
+  });
+
+  it("does not write files in dry-run mode", async () => {
+    const { globby } = await import("globby");
+    const { readFile, writeFile } = await import("node:fs/promises");
+
+    vi.mocked(globby).mockResolvedValue(["/project/README.md"]);
+    vi.mocked(readFile).mockResolvedValue(
+      `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`
+    );
+
+    const extractionResult = makeExtractionResult();
+    await syncAllReadmes(extractionResult, { root: "/project", dryRun: true });
+
+    expect(writeFile).not.toHaveBeenCalled();
+  });
+
+  it("writes files when not in dry-run mode", async () => {
+    const { globby } = await import("globby");
+    const { readFile, writeFile } = await import("node:fs/promises");
+
+    vi.mocked(globby).mockResolvedValue(["/project/README.md"]);
+    vi.mocked(readFile).mockResolvedValue(
+      `<!-- @codex:auto install="@pithyjs/signals" -->
+```bash
+npm install @pithyjs/signals
+```
+
+```bash
+pnpm add @pithyjs/signals
+```
+
+```bash
+yarn add @pithyjs/signals
+```
+<!-- @codex:end -->`
+    );
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const extractionResult = makeExtractionResult();
+    await syncAllReadmes(extractionResult, { root: "/project", dryRun: false });
+
+    expect(writeFile).toHaveBeenCalledWith(
+      "/project/README.md",
+      expect.stringContaining("npm install @pithyjs/signals"),
+      "utf-8"
+    );
+  });
+
+  it("passes test examples from extraction result to syncReadmeContent", async () => {
+    const { globby } = await import("globby");
+    const { readFile } = await import("node:fs/promises");
+
+    const comp = makeComponent({
+      id: "pithy.feature.signals",
+      apis: [{
+        id: "pithy.feature.signals.signal",
+        name: "signal",
+        parent: "pithy.feature.signals",
+        stability: "stable",
+        examples: [],
+        testRefs: [],
+        sourceLocation: { file: "signal.ts", line: 1 },
+      }],
+    });
+
+    vi.mocked(globby).mockResolvedValue(["/project/README.md"]);
+    vi.mocked(readFile).mockResolvedValue(
+      `<!-- @codex:auto examples="pithy.feature.signals" -->
+**creates a reactive signal with initial value**
+
+```typescript
+const count = signal(0);
+count(); // → 0
+count.set(1);
+count(); // → 1
+```
+
+**supports functional updates via .set()**
+
+```typescript
+const count = signal(0);
+count.set(n => n + 1);
+count(); // → 1
+count.set(n => n * 10);
+count(); // → 10
+```
+
+**tracks signal dependencies and re-runs**
+
+```typescript
+const count = signal(0);
+let observed = -1;
+effect(() => {
+  observed = count();
+});
+observed; // → 0
+count.set(5);
+observed; // → 5
+```
+
+**derives a value from other signals**
+
+```typescript
+const a = signal(2);
+const b = signal(3);
+const sum = computed(() => a() + b());
+sum(); // → 5
+a.set(10);
+sum(); // → 13
+```
+
+**defers effect execution until batch completes**
+
+```typescript
+const a = signal(1);
+const b = signal(2);
+let runCount = 0;
+effect(() => {
+  a();
+  b();
+  runCount++;
+});
+runCount; // → 1
+
+batch(() => {
+  a.set(10);
+  b.set(20);
+});
+// Effect should have run only once after batch, not twice
+runCount; // → 2
+```
+
+**runs cleanup on disposal**
+
+```typescript
+const count = signal(0);
+let cleaned = false;
+
+const dispose = effect(() => {
+  count();
+  onCleanup(() => {
+    cleaned = true;
+  });
+});
+
+cleaned; // → false
+dispose();
+cleaned; // → true
+```
+
+**detects signal values at runtime**
+
+```typescript
+const count = signal(0);
+isSignal(count); // → true
+isSignal(42); // → false
+isSignal(() => {}); // → false
+isSignal(null); // → false
+```
+
+**unsubscribes from a dependency it stopped reading**
+
+```typescript
+const useB = signal(true);
+const b = signal(2);
+
+let runs = 0;
+const dispose = effect(() => {
+  runs += 1;
+  if (useB()) b();
+});
+
+useB.set(false);
+const afterSwitch = runs;
+
+b.set(99);
+expect(runs, 'live effect re-ran for a dependency it stopped reading').toBe(
+  afterSwitch
+);
+
+dispose();
+```
+<!-- @codex:end -->`
+    );
+
+    const extractionResult = makeExtractionResult({
+      components: [comp],
+      testExamples: [{
+        entryId: "pithy.feature.signals",
+        name: "basic usage",
+        code: 'const s = signal(1);\nexpect(s()).toBe(1);',
+        location: { file: "signal.test.ts", line: 5 },
+        testFile: "signal.test.ts",
+        status: "passing",
+      }],
+    });
+
+    const results = await syncAllReadmes(extractionResult, { root: "/project", dryRun: true });
+    results[0].updatedContent; // → "basic usage"
+    results[0].updatedContent; // → "s(); // → 1"
+  });
+});
+```
+
+**should escape single quotes in entryId**
+
+```typescript
+const example = createExample('console.log("test")');
+const entryId = "test'injection";
+
+const result = wrapDoctestInHarness(example, entryId);
+
+// Should contain escaped single quote
+result; // → "test\\'injection"
+```
+
+**should escape regex metacharacters in API names**
+
+```typescript
+const content = 'import { set } from "./store"; set(value);';
+const apisWithMetachars = ['set(value)', 'get.*', 'test[0]', 'func$'];
+
+// Should not throw and should handle metacharacters safely
+expect(() => identifyCoveredApis(content, apisWithMetachars)).not.toThrow();
+```
+
+**getSnapshotPath**
+
+```typescript
+describe("getSnapshotPath", () => {
+  it("generates path for a simple version", () => {
+    const path = getSnapshotPath(TEST_DIR, "1.0.0");
+    path; // → join(TEST_DIR, "1.0.0.json")
+  });
+
+  it("generates path for a prerelease version", () => {
+    const path = getSnapshotPath(TEST_DIR, "2.0.0-beta.1");
+    path; // → join(TEST_DIR, "2.0.0-beta.1.json")
+  });
+
+  it("rejects version strings with path separators", () => {
+    expect(() => getSnapshotPath(TEST_DIR, "../../etc/passwd")).toThrow(/Invalid version/);
+  });
+
+  it("rejects version strings with slashes", () => {
+    expect(() => getSnapshotPath(TEST_DIR, "v1/exploit")).toThrow(/Invalid version/);
+  });
+
+  it("rejects version strings with backslashes", () => {
+    expect(() => getSnapshotPath(TEST_DIR, "v1\\exploit")).toThrow(/Invalid version/);
+  });
+
+  it("rejects empty version string", () => {
+    expect(() => getSnapshotPath(TEST_DIR, "")).toThrow(/Invalid version/);
+  });
+});
+```
+
+**saveSnapshot**
+
+```typescript
+describe("saveSnapshot", () => {
+  it("saves a snapshot to disk as JSON", async () => {
+    const snapshot = makeTestSnapshot("1.0.0");
+    await saveSnapshot(snapshot, TEST_DIR);
+
+    const filePath = join(TEST_DIR, "1.0.0.json");
+    const content = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(content);
+
+    parsed.version; // → "1.0.0"
+    parsed.entries; // → 2
+    parsed.timestamp; // → "2025-01-01T00:00:00.000Z"
+  });
+
+  it("creates the directory if it does not exist", async () => {
+    const nestedDir = join(TEST_DIR, "nested", "versions");
+    const snapshot = makeTestSnapshot("1.0.0");
+    await saveSnapshot(snapshot, nestedDir);
+
+    const filePath = join(nestedDir, "1.0.0.json");
+    const content = await readFile(filePath, "utf8");
+    JSON.parse(content).version; // → "1.0.0"
+  });
+
+  it("overwrites an existing snapshot for the same version", async () => {
+    const v1 = makeTestSnapshot("1.0.0");
+    await saveSnapshot(v1, TEST_DIR);
+
+    const v1Updated: ApiSnapshot = {
+      ...v1,
+      entries: [
+        ...v1.entries,
+        {
+          name: "computed",
+          parent: "pithy.signals",
+          qualifiedName: "pithy.signals.computed",
+          signature: "<T>(fn: () => T) => () => T",
+          stability: "stable",
+        },
+      ],
+    };
+    await saveSnapshot(v1Updated, TEST_DIR);
+
+    const content = await readFile(join(TEST_DIR, "1.0.0.json"), "utf8");
+    JSON.parse(content).entries; // → 3
+  });
+
+  it("handles prerelease version strings in filenames", async () => {
+    const snapshot = makeTestSnapshot("2.0.0-beta.1");
+    await saveSnapshot(snapshot, TEST_DIR);
+
+    const filePath = join(TEST_DIR, "2.0.0-beta.1.json");
+    const content = await readFile(filePath, "utf8");
+    JSON.parse(content).version; // → "2.0.0-beta.1"
+  });
+
+  it("produces valid JSON with 2-space indentation", async () => {
+    const snapshot = makeTestSnapshot("1.0.0");
+    await saveSnapshot(snapshot, TEST_DIR);
+
+    const content = await readFile(join(TEST_DIR, "1.0.0.json"), "utf8");
+    // Check indentation (2 spaces)
+    content; // → '  "version"'
+    // Should end with a newline
+    content.endsWith("\n"); // → true
+  });
+});
+```
+
+**loadSnapshot**
+
+```typescript
+describe("loadSnapshot", () => {
+  it("loads a saved snapshot by version", async () => {
+    const original = makeTestSnapshot("1.0.0");
+    await saveSnapshot(original, TEST_DIR);
+
+    const loaded = await loadSnapshot("1.0.0", TEST_DIR);
+    loaded; // → null
+    loaded!.version; // → "1.0.0"
+    loaded!.entries; // → 2
+    loaded!.entries[0].name; // → "signal"
+  });
+
+  it("returns null when snapshot does not exist", async () => {
+    const loaded = await loadSnapshot("99.99.99", TEST_DIR);
+    loaded; // → null
+  });
+
+  it("returns null when directory does not exist", async () => {
+    const loaded = await loadSnapshot("1.0.0", join(TEST_DIR, "nonexistent"));
+    loaded; // → null
+  });
+
+  it("preserves all snapshot fields through save/load cycle", async () => {
+    const original = makeTestSnapshot("1.0.0");
+    await saveSnapshot(original, TEST_DIR);
+    const loaded = await loadSnapshot("1.0.0", TEST_DIR);
+
+    loaded; // → original
+  });
+
+  it("loads snapshot with type members correctly", async () => {
+    const snapshot: ApiSnapshot = {
+      version: "1.0.0",
+      timestamp: "2025-01-01T00:00:00.000Z",
+      entries: [
+        {
+          name: "Signal",
+          parent: "pithy.signals",
+          qualifiedName: "pithy.signals.Signal",
+          stability: "stable",
+          kind: "interface",
+          members: [
+            { name: "set", type: "method", optional: false, readonly: false },
+            { name: "subscribe", type: "method", optional: false, readonly: false },
+          ],
+        },
+      ],
+    };
+    await saveSnapshot(snapshot, TEST_DIR);
+    const loaded = await loadSnapshot("1.0.0", TEST_DIR);
+
+    loaded!.entries[0].kind; // → "interface"
+    loaded!.entries[0].members; // → 2
+  });
+
+  it("throws on corrupted JSON file instead of returning null", async () => {
+    await mkdir(TEST_DIR, { recursive: true });
+    await writeFile(join(TEST_DIR, "corrupt.json"), "not valid json{{{", "utf8");
+    await expect(loadSnapshot("corrupt", TEST_DIR)).rejects.toThrow(/Failed to parse snapshot/);
+  });
+
+  it("throws on non-ENOENT filesystem errors instead of returning null", async () => {
+    // Trying to read a version that resolves to a directory path triggers a non-ENOENT error
+    const dirAsFile = join(TEST_DIR, "not-a-file");
+    await mkdir(join(dirAsFile + ".json"), { recursive: true }); // Create dir where file expected
+    await expect(loadSnapshot("not-a-file", TEST_DIR)).rejects.toThrow();
+  });
+});
+```
+
+**listSnapshots**
+
+```typescript
+describe("listSnapshots", () => {
+  it("lists all saved snapshot versions sorted by version", async () => {
+    await saveSnapshot(makeTestSnapshot("1.0.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("2.0.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.1.0"), TEST_DIR);
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → ["1.0.0", "1.1.0", "2.0.0"]
+  });
+
+  it("sorts by semver, not lexicographically (1.2.0 before 1.10.0)", async () => {
+    await saveSnapshot(makeTestSnapshot("1.10.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.2.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.1.0"), TEST_DIR);
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → ["1.1.0", "1.2.0", "1.10.0"]
+  });
+
+  it("returns empty array when no snapshots exist", async () => {
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → []
+  });
+
+  it("returns empty array when directory does not exist", async () => {
+    const versions = await listSnapshots(join(TEST_DIR, "nonexistent"));
+    versions; // → []
+  });
+
+  it("ignores non-JSON files", async () => {
+    await saveSnapshot(makeTestSnapshot("1.0.0"), TEST_DIR);
+    await writeFile(join(TEST_DIR, "README.md"), "# Versions\n");
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → ["1.0.0"]
+  });
+
+  it("handles prerelease versions", async () => {
+    await saveSnapshot(makeTestSnapshot("1.0.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("2.0.0-beta.1"), TEST_DIR);
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → "1.0.0"
+    versions; // → "2.0.0-beta.1"
+  });
+
+  it("sorts prereleases before their release (semver precedence)", async () => {
+    await saveSnapshot(makeTestSnapshot("1.0.0"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.0.0-beta.1"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.0.0-alpha.1"), TEST_DIR);
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → ["1.0.0-alpha.1", "1.0.0-beta.1", "1.0.0"]
+  });
+
+  it("sorts prerelease numeric identifiers numerically", async () => {
+    await saveSnapshot(makeTestSnapshot("1.0.0-beta.2"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.0.0-beta.10"), TEST_DIR);
+    await saveSnapshot(makeTestSnapshot("1.0.0-beta.1"), TEST_DIR);
+
+    const versions = await listSnapshots(TEST_DIR);
+    versions; // → ["1.0.0-beta.1", "1.0.0-beta.2", "1.0.0-beta.10"]
+  });
+});
+```
+
+**extractTestExamples**
+
+```typescript
+describe("extractTestExamples", () => {
+  it("extracts examples with plain marker format", () => {
+    const content = `
+// @codex:example pithy.signals.effect
+it("creates an effect", () => {
+  const count = signal(0);
+  count(); // → 0
+});
+`;
+    const examples = extractTestExamples(content, "/test/signal.test.ts");
+    examples; // → 1
+    examples[0].entryId; // → "pithy.signals.effect"
+    examples[0].name; // → "creates an effect"
+    examples[0].code; // → "signal(0)"
+    examples[0].testFile; // → "/test/signal.test.ts"
+    examples[0].status; // → "unknown"
+  });
+
+  it("extracts examples with parenthesized marker format", () => {
+    const content = `
+// @codex:example("pithy.core.compile")
+test("compiles template", () => {
+  compile("<div>hello</div>");
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].entryId; // → "pithy.core.compile"
+  });
+
+  it("extracts examples with object marker format", () => {
+    const content = `
+// @codex:example { entry: "pithy.router.navigate" }
+it("navigates to route", () => {
+  router.navigate("/home");
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].entryId; // → "pithy.router.navigate"
+  });
+
+  it("extracts multiple examples from one file", () => {
+    const content = `
+// @codex:example pithy.a
+it("first", () => { expect(1).toBe(1); });
+
+// @codex:example pithy.b
+it("second", () => { expect(2).toBe(2); });
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 2
+    examples[0].entryId; // → "pithy.a"
+    examples[1].entryId; // → "pithy.b"
+  });
+
+  it("skips markers not followed by a test block", () => {
+    const content = `
+// @codex:example pithy.orphan
+const helper = () => {};
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 0
+  });
+
+  it("handles braces inside strings correctly", () => {
+    const content = `
+// @codex:example pithy.strings
+it("handles object { with braces }", () => {
+  const obj = { key: "value with }" };
+  obj.key; // → defined
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    // Should capture the full test block including the closing });
+    examples[0].code; // → "expect(obj.key).toBeDefined()"
+  });
+
+  it("handles braces inside comments", () => {
+    const content = `
+// @codex:example pithy.comments
+it("works with comments", () => {
+  // This { brace should be ignored }
+  const x = 1;
+  x; // → 1
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].code; // → "expect(x).toBe(1)"
+  });
+
+  it("handles braces inside multi-line block comments", () => {
+    const content = `
+// @codex:example pithy.multiline
+it("multi-line comment", () => {
+  /*
+   * This { brace } should be ignored
+   * and this one too {
+   */
+  const x = 1;
+  x; // → 1
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].code; // → "expect(x).toBe(1)"
+    examples[0].code; // → "});"
+  });
+
+  it("provides correct 1-indexed line numbers", () => {
+    const content = `line1
+line2
+// @codex:example pithy.loc
+it("has location", () => {
+  true; // → true
+});`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples[0].location.line; // → 4); // it() is on line 4 (1-indexed
+  });
+
+  it("handles escaped quotes in test names", () => {
+    const content = `
+// @codex:example pithy.escape
+it("handles \\"quoted\\" text", () => {
+  true; // → true
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].name; // → 'handles \\"quoted\\" text'
+  });
+
+  it("handles describe blocks", () => {
+    const content = `
+// @codex:example pithy.describe
+describe("my suite", () => {
+  it("inner test", () => {
+    1; // → 1
+  });
+});
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 1
+    examples[0].name; // → "my suite"
+    examples[0].code; // → "inner test"
+  });
+
+  it("does not match marker-like text that isn't a dotted identifier", () => {
+    const content = `
+// This text mentions @codex:example but has no id after it
+it("test", () => { expect(1).toBe(1); });
+`;
+    const examples = extractTestExamples(content, "test.ts");
+    examples; // → 0
+  });
+});
+```
+
+**parseVitestOutput**
+
+```typescript
+describe("parseVitestOutput", () => {
+  it("parses testResults format (jest-like)", () => {
+    const output = JSON.stringify({
+      testResults: [
+        {
+          name: "packages/signals/src/signal.test.ts",
+          assertionResults: [
+            { fullName: "creates a signal", status: "passed", duration: 5 },
+            {
+              fullName: "updates signal",
+              status: "failed",
+              duration: 10,
+              failureMessages: ["Expected 1 to be 2"],
+            },
+          ],
+        },
+      ],
+    });
+
+    const statuses = parseVitestOutput(output);
+    statuses; // → 2
+    expect(statuses[0]).toMatchObject({
+      file: "packages/signals/src/signal.test.ts",
+      testName: "creates a signal",
+      status: "passed",
+    });
+    expect(statuses[1]).toMatchObject({
+      status: "failed",
+      error: "Expected 1 to be 2",
+    });
+  });
+
+  it("parses results/tasks format (vitest native)", () => {
+    const output = JSON.stringify({
+      success: true,
+      results: [
+        {
+          file: "src/foo.test.ts",
+          tasks: [
+            {
+              name: "suite",
+              type: "suite",
+              tasks: [
+                {
+                  name: "test one",
+                  type: "test",
+                  result: { state: "pass", duration: 3 },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    const statuses = parseVitestOutput(output);
+    statuses; // → 1
+    expect(statuses[0]).toMatchObject({
+      file: "src/foo.test.ts",
+      testName: "suite > test one",
+      status: "passed",
+    });
+  });
+
+  it("returns empty array for invalid JSON", () => {
+    parseVitestOutput("not json"); // → []
+  });
+
+  it("returns empty array for empty object", () => {
+    parseVitestOutput("{}"); // → []
+  });
+
+  it("maps pending/skipped/todo to skipped", () => {
+    const output = JSON.stringify({
+      testResults: [
+        {
+          name: "test.ts",
+          assertionResults: [
+            { title: "pending", status: "pending" },
+            { title: "skipped", status: "skipped" },
+            { title: "todo", status: "todo" },
+          ],
+        },
+      ],
+    });
+
+    const statuses = parseVitestOutput(output);
+    statuses.every((s) => s.status === "skipped"); // → true
+  });
+});
+```
+
+**matchExamplesToStatuses**
+
+```typescript
+describe("matchExamplesToStatuses", () => {
+  function makeExample(overrides: Partial<TestExample> = {}): TestExample {
+    return {
+      entryId: "pithy.test",
+      name: "my test",
+      code: 'it("my test", () => {})',
+      location: { file: "test.ts", line: 1 },
+      testFile: "packages/signals/src/signal.test.ts",
+      status: "unknown",
+      ...overrides,
+    };
+  }
+
+  it("matches by exact name and file path suffix", () => {
+    const examples = [makeExample()];
+    const statuses: TestStatus[] = [
+      {
+        file: "packages/signals/src/signal.test.ts",
+        testName: "my test",
+        status: "passed",
+      },
+    ];
+
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "passing"
+  });
+
+  it("matches when status testName includes describe prefix", () => {
+    const examples = [makeExample({ name: "creates signal" })];
+    const statuses: TestStatus[] = [
+      {
+        file: "packages/signals/src/signal.test.ts",
+        testName: "signal > creates signal",
+        status: "passed",
+      },
+    ];
+
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "passing"
+  });
+
+  it("does not false-match short names across different files", () => {
+    const examples = [
+      makeExample({
+        name: "works",
+        testFile: "packages/foo/src/utils.test.ts",
+      }),
+    ];
+    const statuses: TestStatus[] = [
+      {
+        file: "packages/bar/src/utils.test.ts",
+        testName: "works",
+        status: "passed",
+      },
+    ];
+
+    // Different packages — should NOT match
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "unknown"
+  });
+
+  it("maps failed status correctly", () => {
+    const examples = [makeExample()];
+    const statuses: TestStatus[] = [
+      {
+        file: "packages/signals/src/signal.test.ts",
+        testName: "my test",
+        status: "failed",
+        error: "Assertion failed",
+      },
+    ];
+
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "failing"
+    result[0].error; // → "Assertion failed"
+  });
+
+  it("maps skipped status correctly", () => {
+    const examples = [makeExample()];
+    const statuses: TestStatus[] = [
+      {
+        file: "packages/signals/src/signal.test.ts",
+        testName: "my test",
+        status: "skipped",
+      },
+    ];
+
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "skipped"
+  });
+
+  it("leaves unmatched examples as unknown", () => {
+    const examples = [makeExample({ name: "no match here" })];
+    const statuses: TestStatus[] = [];
+
+    const result = matchExamplesToStatuses(examples, statuses);
+    result[0].status; // → "unknown"
+  });
+});
+```
+
+**getTestingDefaults**
+
+```typescript
+describe("getTestingDefaults", () => {
+  it("returns directive defaults", () => {
+    const defaults = getTestingDefaults("directive");
+    defaults.unit; // → { required: true, coverage: 90 }
+    defaults.integration; // → { required: true, coverage: 80 }
+    defaults.e2e; // → { required: false }
+  });
+
+  it("returns feature defaults", () => {
+    const defaults = getTestingDefaults("feature");
+    defaults.unit; // → { required: true, coverage: 85 }
+    defaults.integration; // → { required: true, coverage: 70 }
+    defaults.e2e; // → { required: false }
+  });
+
+  it("returns runtime defaults", () => {
+    const defaults = getTestingDefaults("runtime");
+    defaults.unit; // → { required: true, coverage: 90 }
+    defaults.integration; // → { required: true, coverage: 80 }
+    defaults.e2e; // → { required: true }
+  });
+
+  it("returns compiler defaults", () => {
+    const defaults = getTestingDefaults("compiler");
+    defaults.unit; // → { required: true, coverage: 95 }
+    defaults.integration; // → { required: true, coverage: 70 }
+    defaults.e2e; // → { required: false }
+  });
+
+  it("returns plugin defaults", () => {
+    const defaults = getTestingDefaults("plugin");
+    defaults.unit; // → { required: true, coverage: 70 }
+    defaults.integration; // → { required: true, coverage: 85 }
+    defaults.e2e; // → { required: true }
+  });
+
+  it("returns empty requirements for types category", () => {
+    const defaults = getTestingDefaults("types");
+    defaults.unit; // → undefined
+    defaults.integration; // → undefined
+    defaults.e2e; // → undefined
+  });
+
+  it("returns feature defaults for unknown category", () => {
+    const defaults = getTestingDefaults("unknown-category");
+    defaults; // → getTestingDefaults("feature")
+  });
+
+  it("returns independent copies (mutations don't affect defaults)", () => {
+    const first = getTestingDefaults("feature");
+    first.unit!.coverage = 999;
+    const second = getTestingDefaults("feature");
+    second.unit!.coverage; // → 85
+  });
+});
+```
+
+**applyRiskModifiers**
+
+```typescript
+describe("applyRiskModifiers", () => {
+  it("applies critical risk modifiers", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+      integration: { required: true, coverage: 70 },
+      e2e: { required: false },
+    };
+
+    const result = applyRiskModifiers(base, "critical");
+    expect(result.unit!.coverage).toBe(90); // +5
+    expect(result.integration!.coverage).toBe(80); // +10
+    expect(result.e2e!.required).toBe(true); // Required
+  });
+
+  it("applies high risk modifiers", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+      integration: { required: true, coverage: 70 },
+      e2e: { required: false },
+    };
+
+    const result = applyRiskModifiers(base, "high");
+    expect(result.unit!.coverage).toBe(85); // +0
+    expect(result.integration!.coverage).toBe(75); // +5
+    expect(result.e2e!.required).toBe(false); // Unchanged
+  });
+
+  it("applies medium risk modifiers", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+      integration: { required: true, coverage: 70 },
+      e2e: { required: false },
+    };
+
+    const result = applyRiskModifiers(base, "medium");
+    expect(result.unit!.coverage).toBe(80); // -5
+    expect(result.integration!.coverage).toBe(70); // +0
+    result.e2e!.required; // → false
+  });
+
+  it("applies low risk modifiers", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+      integration: { required: true, coverage: 70 },
+      e2e: { required: false },
+    };
+
+    const result = applyRiskModifiers(base, "low");
+    expect(result.unit!.coverage).toBe(75); // -10
+    expect(result.integration!.coverage).toBe(60); // -10
+    result.e2e!.required; // → false
+  });
+
+  it("does not modify base object (returns new object)", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+      integration: { required: true, coverage: 70 },
+      e2e: { required: false },
+    };
+    const original = JSON.parse(JSON.stringify(base));
+
+    applyRiskModifiers(base, "critical");
+    base; // → original
+  });
+
+  it("handles undefined test levels gracefully", () => {
+    const base: TestingRequirements = {};
+    const result = applyRiskModifiers(base, "critical");
+    result; // → {}
+  });
+
+  it("clamps coverage to minimum 0", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 5 },
+    };
+    const result = applyRiskModifiers(base, "low");
+    result.unit!.coverage; // → 0
+  });
+
+  it("clamps coverage to maximum 100", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 98 },
+    };
+    const result = applyRiskModifiers(base, "critical");
+    result.unit!.coverage; // → 100
+  });
+
+  it("returns base unchanged when no risk level provided", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+    };
+    const result = applyRiskModifiers(base, undefined);
+    result; // → base
+  });
+
+  it("returns a deep copy when no risk level provided (no shared references)", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+    };
+    const result = applyRiskModifiers(base, undefined);
+    result.unit!.coverage = 999;
+    base.unit!.coverage; // → 85
+  });
+
+  it("returns clone for unknown risk string (fallback path)", () => {
+    const base: TestingRequirements = {
+      unit: { required: true, coverage: 85 },
+    };
+    const result = applyRiskModifiers(base, "unknown" as RiskLevel);
+    result; // → base
+    // Verify it's a clone, not the same object
+    result.unit!.coverage = 999;
+    base.unit!.coverage; // → 85
+  });
+
+  it("handles level with coverage undefined", () => {
+    const base: TestingRequirements = {
+      unit: { required: true },
+    };
+    const result = applyRiskModifiers(base, "critical");
+    result.unit!.required; // → true
+    result.unit!.coverage; // → undefined
+  });
+
+  it("handles e2e-only base with critical risk", () => {
+    const base: TestingRequirements = {
+      e2e: { required: false },
+    };
+    const result = applyRiskModifiers(base, "critical");
+    result.e2e!.required; // → true
+    result.unit; // → undefined
+    result.integration; // → undefined
+  });
+});
+```
+
+**resolveTestingRequirements**
+
+```typescript
+describe("resolveTestingRequirements", () => {
+  it("uses category defaults when no annotation testing exists", () => {
+    const result = resolveTestingRequirements("feature");
+    result.unit; // → defined
+    result.unit!.required; // → true
+    result.unit!.coverage; // → 85
+  });
+
+  it("applies risk modifier on top of category defaults", () => {
+    const result = resolveTestingRequirements("feature", "critical");
+    expect(result.unit!.coverage).toBe(90); // 85 + 5
+    expect(result.integration!.coverage).toBe(80); // 70 + 10
+    result.e2e!.required; // → true
+  });
+
+  it("annotation testing overrides defaults", () => {
+    const override: TestingRequirements = {
+      unit: { required: true, coverage: 100 },
+    };
+    const result = resolveTestingRequirements("feature", undefined, override);
+    result.unit!.coverage; // → 100
+    // Non-overridden levels use defaults
+    result.integration; // → defined
+    result.integration!.coverage; // → 70
+  });
+
+  it("annotation testing with risk modifier", () => {
+    const override: TestingRequirements = {
+      unit: { required: true, coverage: 80 },
+    };
+    const result = resolveTestingRequirements("feature", "high", override);
+    // Override unit is used as base, then risk applied: 80 + 0 = 80
+    result.unit!.coverage; // → 80
+    // Integration from defaults + risk: 70 + 5 = 75
+    result.integration!.coverage; // → 75
+  });
+
+  it("returns empty requirements for types category", () => {
+    const result = resolveTestingRequirements("types");
+    result.unit; // → undefined
+    result.integration; // → undefined
+    result.e2e; // → undefined
+  });
+
+  it("full override replaces all levels", () => {
+    const override: TestingRequirements = {
+      unit: { required: true, coverage: 100 },
+      integration: { required: false, coverage: 50 },
+      e2e: { required: true },
+    };
+    const result = resolveTestingRequirements("feature", undefined, override);
+    result.unit!.coverage; // → 100
+    result.integration!.coverage; // → 50
+    result.integration!.required; // → false
+    result.e2e!.required; // → true
+  });
+
+  it("unknown category with risk modifier uses feature fallback", () => {
+    const result = resolveTestingRequirements("unknown", "critical");
+    // feature defaults: unit 85, integration 70, e2e false
+    // critical: +5 unit, +10 integration, e2e required
+    result.unit!.coverage; // → 90
+    result.integration!.coverage; // → 80
+    result.e2e!.required; // → true
+  });
+
+  it("deep-merges partial override so defaults are preserved", () => {
+    // Override only sets covered/file, should retain required/coverage from defaults
+    const override: TestingRequirements = {
+      unit: { required: true, covered: true, file: "signal.test.ts" },
+    };
+    const result = resolveTestingRequirements("feature", undefined, override);
+    // Default feature unit: required=true, coverage=85
+    result.unit!.required; // → true
+    result.unit!.covered; // → true
+    result.unit!.file; // → "signal.test.ts"
+    expect(result.unit!.coverage).toBe(85); // retained from defaults
+    // Integration should still have defaults
+    result.integration!.required; // → true
+    result.integration!.coverage; // → 70
+  });
+});
+```
+
+**computeTestingStatus**
+
+```typescript
+describe("computeTestingStatus", () => {
+  it("returns 'Complete' when all required levels are covered", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: true },
+      integration: { required: true, covered: true },
+      e2e: { required: false },
+    };
+    computeTestingStatus(reqs); // → "Complete"
+  });
+
+  it("returns 'Missing unit' when unit is required but not covered", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: false },
+      integration: { required: true, covered: true },
+      e2e: { required: false },
+    };
+    computeTestingStatus(reqs); // → "Missing unit"
+  });
+
+  it("returns 'Missing integration' when integration is required but not covered", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: true },
+      integration: { required: true, covered: false },
+      e2e: { required: false },
+    };
+    computeTestingStatus(reqs); // → "Missing integration"
+  });
+
+  it("returns 'Missing e2e' when e2e is required but not covered", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: true },
+      integration: { required: true, covered: true },
+      e2e: { required: true, covered: false },
+    };
+    computeTestingStatus(reqs); // → "Missing e2e"
+  });
+
+  it("lists multiple missing levels", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: false },
+      integration: { required: true, covered: false },
+      e2e: { required: false },
+    };
+    const status = computeTestingStatus(reqs);
+    status; // → "unit"
+    status; // → "integration"
+  });
+
+  it("returns 'N/A' when no levels are defined", () => {
+    const reqs: TestingRequirements = {};
+    computeTestingStatus(reqs); // → "N/A"
+  });
+
+  it("returns 'Complete' when required levels are covered and e2e is optional", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: true },
+      e2e: { required: false, covered: false },
+    };
+    computeTestingStatus(reqs); // → "Complete"
+  });
+
+  it("lists all three levels when all missing", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: true, covered: false },
+      integration: { required: true, covered: false },
+      e2e: { required: true, covered: false },
+    };
+    computeTestingStatus(reqs); // → "Missing unit, integration, e2e"
+  });
+
+  it("ignores levels with required: false even when not covered", () => {
+    const reqs: TestingRequirements = {
+      unit: { required: false, covered: false },
+      integration: { required: false, covered: false },
+    };
+    computeTestingStatus(reqs); // → "Complete"
+  });
+});
+```
+
+**extractTypesFromFile**
+
+```typescript
+describe("extractTypesFromFile", () => {
+  it("extracts an exported interface", () => {
+    const code = `
+export interface Foo {
+  bar: string;
+  baz?: number;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types; // → 1
+    types[0].name; // → "Foo"
+    types[0].kind; // → "interface"
+    types[0].exported; // → true
+    types[0].members; // → 2
+    expect(types[0].members[0]).toMatchObject({
+      name: "bar",
+      type: "string",
+      optional: false,
+    });
+    expect(types[0].members[1]).toMatchObject({
+      name: "baz",
+      type: "number",
+      optional: true,
+    });
+  });
+
+  it("extracts a non-exported interface", () => {
+    const code = `interface Internal { x: number; }`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].exported; // → false
+  });
+
+  it("extracts interface with generics and extends", () => {
+    const code = `
+export interface Container<T extends Base> extends Parent {
+  value: T;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].generics; // → ["T extends Base"]
+    types[0].extends; // → ["Parent"]
+  });
+
+  it("extracts interface with method signatures", () => {
+    const code = `
+export interface Handler {
+  handle(req: Request): Response;
+  optional?(): void;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].members; // → 2
+    types[0].members[0].name; // → "handle"
+    types[0].members[0].type; // → "method"
+    types[0].members[1].optional; // → true
+  });
+
+  it("extracts interface with readonly and index signatures", () => {
+    const code = `
+export interface Config {
+  readonly name: string;
+  [key: string]: unknown;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].members[0].readonly; // → true
+    types[0].members[1].name; // → "[index]"
+  });
+
+  it("extracts a type alias with object literal", () => {
+    const code = `
+export type Options = {
+  verbose: boolean;
+  count?: number;
+};`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].kind; // → "type"
+    types[0].name; // → "Options"
+    types[0].members; // → 2
+  });
+
+  it("extracts a union type alias as __type member", () => {
+    const code = `export type Status = "active" | "inactive";`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].kind; // → "type"
+    types[0].members; // → 1
+    types[0].members[0].name; // → "__type"
+    types[0].members[0].type; // → "active"
+  });
+
+  it("extracts a type alias with generics", () => {
+    const code = `export type Wrapper<T> = { inner: T };`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].generics; // → ["T"]
+  });
+
+  it("extracts an enum", () => {
+    const code = `
+export enum Direction {
+  Up = "UP",
+  Down = "DOWN",
+  Left,
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].kind; // → "enum"
+    types[0].name; // → "Direction"
+    types[0].members; // → 3
+    expect(types[0].members[0]).toMatchObject({
+      name: "Up",
+      type: '"UP"',
+      readonly: true,
+    });
+    expect(types[0].members[2].type).toBe("auto"); // no initializer
+  });
+
+  it("extracts a class with public members only", () => {
+    const code = `
+export class MyService {
+  public name: string = "";
+  private secret: string = "";
+  protected internal: number = 0;
+
+  constructor() {}
+
+  public greet(): string { return this.name; }
+  private hash(): void {}
+  protected compute(): void {}
+
+  get value(): number { return 1; }
+  set value(v: number) {}
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].kind; // → "class"
+    types[0].exported; // → true
+
+    const memberNames = types[0].members.map((m) => m.name);
+    // Should include: name, greet, value (getter), value (setter)
+    memberNames; // → "name"
+    memberNames; // → "greet"
+    memberNames; // → "value"
+    // Should NOT include: secret, internal, hash, compute
+    memberNames; // → "secret"
+    memberNames; // → "internal"
+    memberNames; // → "hash"
+    memberNames; // → "compute"
+
+    // Method signatures should not include the body
+    const greet = types[0].members.find((m) => m.name === "greet");
+    greet?.signature; // → "greet(): string"
+    greet?.signature; // → "return"
+
+    // Getter/setter signatures should be declaration-only
+    const getter = types[0].members.find((m) => m.name === "value" && m.type === "getter");
+    getter?.signature; // → "get value(): number"
+    const setter = types[0].members.find((m) => m.name === "value" && m.type === "setter");
+    setter?.signature; // → "set value(v: number)"
+  });
+
+  it("skips ECMAScript #private fields", () => {
+    const code = `
+export class Vault {
+  #data: string = "";
+  public label: string = "";
+  #compute(): void {}
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    const memberNames = types[0].members.map((m) => m.name);
+    memberNames; // → ["label"]
+  });
+
+  it("extracts class with generics, extends, and implements", () => {
+    const code = `
+export class Store<T> extends BaseStore implements Disposable {
+  public items: T[] = [];
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].generics; // → ["T"]
+    types[0].extends; // → ["BaseStore"]
+    types[0].implements; // → ["Disposable"]
+  });
+
+  it("extracts JSDoc description from types", () => {
+    const code = `
+/** A documented interface */
+export interface Documented {
+  value: string;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].jsdoc; // → defined
+    types[0].jsdoc!.description; // → "A documented interface"
+  });
+
+  it("extracts JSDoc @param and @returns tags", () => {
+    const code = `
+/**
+ * A service class
+ * @param config - The configuration
+ * @returns The instance
+ * @since 1.0.0
+ * @deprecated Use NewService instead
+ */
+export interface Service {
+  run(): void;
+}`;
+    const types = extractTypesFromFile("test.ts", code);
+    const jsdoc = types[0].jsdoc!;
+    jsdoc.params; // → 1
+    jsdoc.params[0].name; // → "config"
+    jsdoc.returns?.description; // → "The instance"
+    jsdoc.since; // → "1.0.0"
+    jsdoc.deprecated; // → truthy
+  });
+
+  it("extracts multiple types from a single file", () => {
+    const code = `
+export interface A { x: number; }
+export type B = string;
+export enum C { X, Y }
+export class D { public z = 1; }`;
+    const types = extractTypesFromFile("test.ts", code);
+    types; // → 4
+    types.map((t) => t.name); // → ["A", "B", "C", "D"]
+    types.map((t) => t.kind); // → ["interface", "type", "enum", "class"]
+  });
+
+  it("returns empty array for files with no type definitions", () => {
+    const code = `const x = 5; function foo() { return x; }`;
+    const types = extractTypesFromFile("test.ts", code);
+    types; // → []
+  });
+
+  it("provides correct source locations", () => {
+    const code = `\nexport interface Foo {\n  bar: string;\n}\n`;
+    const types = extractTypesFromFile("test.ts", code);
+    types[0].location.file; // → "test.ts"
+    types[0].location.line; // → 2
+  });
+});
+```
+
+**getTypeSignature**
+
+```typescript
+describe("getTypeSignature", () => {
+  it("generates interface signature", () => {
+    const sig = getTypeSignature({
+      name: "Foo",
+      kind: "interface",
+      exported: true,
+      generics: ["T"],
+      extends: ["Bar"],
+      members: [],
+      location: { file: "test.ts", line: 1 },
+    });
+    sig; // → "export interface Foo<T> extends Bar"
+  });
+
+  it("generates type signature", () => {
+    const sig = getTypeSignature({
+      name: "Options",
+      kind: "type",
+      exported: true,
+      generics: ["K", "V"],
+      members: [],
+      location: { file: "test.ts", line: 1 },
+    });
+    sig; // → "export type Options<K, V>"
+  });
+
+  it("generates enum signature", () => {
+    const sig = getTypeSignature({
+      name: "Status",
+      kind: "enum",
+      exported: false,
+      members: [],
+      location: { file: "test.ts", line: 1 },
+    });
+    sig; // → "enum Status"
+  });
+
+  it("generates class signature with implements", () => {
+    const sig = getTypeSignature({
+      name: "Service",
+      kind: "class",
+      exported: true,
+      extends: ["Base"],
+      implements: ["Disposable", "Serializable"],
+      members: [],
+      location: { file: "test.ts", line: 1 },
+    });
+    expect(sig).toBe(
+      "export class Service extends Base implements Disposable, Serializable"
+    );
+  });
+});
+```
+
+**generateMethodTable**
+
+```typescript
+describe("generateMethodTable", () => {
+  it("returns empty string for no members", () => {
+    expect(
+      generateMethodTable({
+        name: "Empty",
+        kind: "interface",
+        exported: true,
+        members: [],
+        location: { file: "test.ts", line: 1 },
+      })
+    ).toBe("");
+  });
+
+  it("generates markdown table", () => {
+    const table = generateMethodTable({
+      name: "Foo",
+      kind: "interface",
+      exported: true,
+      members: [
+        { name: "bar", type: "string", optional: false, readonly: false, description: "The bar" },
+        { name: "baz", type: "number", optional: true, readonly: false },
+        { name: "id", type: "string", optional: false, readonly: true },
+      ],
+      location: { file: "test.ts", line: 1 },
+    });
+
+    table; // → "| Member | Type | Description |"
+    table; // → "| `bar` | `string` | The bar |"
+    table; // → "| `baz?` | `number` |  |"
+    table; // → "| `readonly id` | `string` |  |"
+  });
+
+  it("renders both readonly and optional when both are set", () => {
+    const table = generateMethodTable({
+      name: "Foo",
+      kind: "interface",
+      exported: true,
+      members: [
+        { name: "version", type: "string", optional: true, readonly: true },
+      ],
+      location: { file: "test.ts", line: 1 },
+    });
+
+    table; // → "| `readonly version?` | `string` |  |"
+  });
+
+  it("escapes pipes and newlines in descriptions", () => {
+    const table = generateMethodTable({
+      name: "Foo",
+      kind: "interface",
+      exported: true,
+      members: [
+        { name: "bar", type: "string", optional: false, readonly: false, description: "A | B choice" },
+        { name: "baz", type: "number", optional: false, readonly: false, description: "Line1\nLine2" },
+      ],
+      location: { file: "test.ts", line: 1 },
+    });
+
+    table; // → "A \\| B choice"
+    table; // → "Line1\n"
+    table; // → "Line1<br/>Line2"
+  });
+
+  it("uses signature over type when available", () => {
+    const table = generateMethodTable({
+      name: "Foo",
+      kind: "interface",
+      exported: true,
+      members: [
+        {
+          name: "handle",
+          type: "method",
+          optional: false,
+          readonly: false,
+          signature: "handle(req: Request): Response",
+        },
+      ],
+      location: { file: "test.ts", line: 1 },
+    });
+
+    table; // → "handle(req: Request): Response"
+  });
+});
+```
+<!-- @codex:end -->
+
+## Testing
+
+<!-- @codex:auto testing="pithy.codex.**" -->
+| Feature | Unit | Integration | E2E | Status |
+| --- | --- | --- | --- | --- |
+| parseCodexAnnotations | ✓ | - | - | Missing integration |
+| parseCodexApiAnnotations | ✓ | - | - | Missing integration |
+| createSourceDigest | ✓ | - | - | Missing integration |
+| createCanonicalFingerprint | ✓ | - | - | Missing integration |
+| discoverComponentsFromFile | ✓ | - | - | Missing integration |
+| validateAnnotation | ✓ | - | - | Missing integration |
+| CHANGED_ONLY_PATHSPEC | - | - | - | N/A |
+| loadEnv | - | - | - | Missing unit, integration |
+| askLLM | - | - | - | Missing unit, integration |
+| scan | - | - | - | Missing unit, integration |
+| combineFingerprints | - | - | - | Missing unit, integration |
+| ApiSig | - | - | - | Missing unit, integration |
+| codexSchema | - | - | - | Missing unit, integration |
+| CodexEntry | - | - | - | Missing unit, integration |
+| consumeValue | ✓ | - | - | Missing integration, e2e |
+| parseArgs | ✓ | - | - | Missing integration, e2e |
+| validatePath | ✓ | - | - | Missing integration, e2e |
+| validatePath | ✓ | - | - | Missing integration |
+| runSyncPipeline | - | - | - | Missing unit, integration |
+| validateExampleSyntax | - | - | - | Missing unit, integration |
+| validateExtractionResult | - | - | - | Missing unit, integration |
+| formatValidationReport | - | - | - | Missing unit, integration |
+| createApiSnapshot | ✓ | - | - | Missing integration |
+| snapshotFromTypeDefinitions | ✓ | - | - | Missing integration |
+| diffSnapshots | ✓ | - | - | Missing integration |
+| classifyChange | ✓ | - | - | Missing integration |
+| detectBreakingChanges | ✓ | - | - | Missing integration |
+| generateMigrationGuide | ✓ | - | - | Missing integration |
+| generateChangelog | ✓ | - | - | Missing integration |
+| extractExamples | - | - | - | Missing unit, integration |
+| validateExample | - | - | - | Missing unit, integration |
+| wrapDoctestInHarness | - | - | - | Missing unit, integration |
+| extractExamplesFromSource | - | - | - | Missing unit, integration |
+| generateRunnableExampleFile | - | - | - | Missing unit, integration |
+| parseJSDocComment | - | - | - | Missing unit, integration |
+| extractJSDocBlocks | - | - | - | Missing unit, integration |
+| linkJSDocToDeclarations | - | - | - | Missing unit, integration |
+| extractSignature | - | - | - | Missing unit, integration |
+| runExtractionPipeline | - | - | - | Missing unit, integration |
+| extractSingleFile | - | - | - | Missing unit, integration |
+| generateExtractionReport | - | - | - | Missing unit, integration |
+| exportToCodexFormat | - | - | - | Missing unit, integration |
+| parseMarkerAttributes | - | - | - | Missing unit, integration |
+| resolveMarkerType | - | - | - | Missing unit, integration |
+| parseReadmeMarkers | - | - | - | Missing unit, integration |
+| matchIdPattern | - | - | - | Missing unit, integration |
+| filterByPattern | - | - | - | Missing unit, integration |
+| stripTestBoilerplate | - | - | - | Missing unit, integration |
+| generateInstallContent | - | - | - | Missing unit, integration |
+| generateExamplesContent | - | - | - | Missing unit, integration |
+| escapeTableCell | - | - | - | Missing unit, integration |
+| escapeMd | - | - | - | Missing unit, integration |
+| sanitizeForInlineCode | - | - | - | Missing unit, integration |
+| longestBacktickRun | - | - | - | Missing unit, integration |
+| sanitizeLanguage | - | - | - | Missing unit, integration |
+| generateApiContent | - | - | - | Missing unit, integration |
+| generateTestingContent | - | - | - | Missing unit, integration |
+| generateBundleContent | - | - | - | Missing unit, integration |
+| syncReadmeContent | - | - | - | Missing unit, integration |
+| syncAllReadmes | - | - | - | Missing unit, integration |
+| getSnapshotPath | ✓ | - | - | Missing integration |
+| saveSnapshot | ✓ | - | - | Missing integration |
+| loadSnapshot | ✓ | - | - | Missing integration |
+| listSnapshots | ✓ | - | - | Missing integration |
+| DeclarationLocation | - | - | - | Missing unit, integration |
+| findDeclarationLocation | - | - | - | Missing unit, integration |
+| extractAllDeclarations | - | - | - | Missing unit, integration |
+| parseReadmeSections | - | - | - | Missing unit, integration |
+| linkReadmeToEntries | - | - | - | Missing unit, integration |
+| generateSourceLink | - | - | - | Missing unit, integration |
+| toRelativePath | - | - | - | Missing unit, integration |
+| enrichSourceLocation | - | - | - | Missing unit, integration |
+| extractTestExamples | ✓ | - | - | Missing integration |
+| parseVitestOutput | ✓ | - | - | Missing integration |
+| matchExamplesToStatuses | ✓ | - | - | Missing integration |
+| generateExampleReport | ✓ | - | - | Missing integration |
+| validateTestExamples | ✓ | - | - | Missing integration |
+| extractTestCases | - | - | - | Missing unit, integration |
+| extractTestImports | - | - | - | Missing unit, integration |
+| identifyCoveredApis | - | - | - | Missing unit, integration |
+| analyzeTestFile | - | - | - | Missing unit, integration |
+| testCasesToReferences | - | - | - | Missing unit, integration |
+| matchTestToEntry | - | - | - | Missing unit, integration |
+| generateCoverageSummary | - | - | - | Missing unit, integration |
+| getTestingDefaults | ✓ | - | - | Missing integration |
+| applyRiskModifiers | ✓ | - | - | Missing integration |
+| resolveTestingRequirements | ✓ | - | - | Missing integration |
+| computeTestingStatus | ✓ | - | - | Missing integration |
+| extractTypesFromFile | ✓ | - | - | Missing integration |
+| getTypeSignature | ✓ | - | - | Missing integration |
+| generateMethodTable | ✓ | - | - | Missing integration |
+<!-- @codex:end -->
+
+## License
+
+MIT