@doccov/sdk 0.24.0 → 0.24.1

package/dist/index.d.ts

@@ -1,951 +1,951 @@
-import { EntryPointDetectionMethod } from "@openpkg-ts/spec";
+import { DocCovSpec } from "@doccov/spec";
+import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+type OpenPkgSpec = OpenPkg2;
+interface BuildDocCovOptions {
+	openpkgPath: string;
+	openpkg: OpenPkgSpec;
+	packagePath?: string;
+}
 /**
-* Configuration types for DocCov.
-* These types are shared between CLI and API.
+* Build a DocCov spec from an OpenPkg spec.
+*
+* @param options - Build options
+* @returns DocCov specification with coverage analysis
 */
+declare function buildDocCovSpec(options: BuildDocCovOptions): DocCovSpec;
 /**
-* Documentation configuration options.
+* All possible drift type identifiers.
 */
-interface DocsConfig {
-	/** Glob patterns for markdown docs to include */
-	include?: string[];
-	/** Glob patterns for markdown docs to exclude */
-	exclude?: string[];
-}
+type DriftType = "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "async-mismatch" | "property-type-drift" | "example-drift" | "example-syntax-error" | "example-runtime-error" | "example-assertion-failed" | "broken-link";
+type SpecDocDrift = {
+	type: DriftType;
+	target?: string;
+	issue: string;
+	suggestion?: string;
+};
 /**
-* Example validation modes.
+* Drift categories group related drift types for progressive disclosure.
 */
-type ExampleValidationMode = "presence" | "typecheck" | "run";
+type DriftCategory = "structural" | "semantic" | "example";
 /**
-* Schema extraction modes for validation libraries (Zod, Valibot, TypeBox, ArkType).
-*
-* - 'static': TypeScript Compiler API only (no runtime, always safe)
-* - 'runtime': Standard Schema runtime extraction (requires built package)
-* - 'hybrid': Try runtime first, fall back to static
+* Maps each drift type to its category.
 */
-type SchemaExtractionMode = "static" | "runtime" | "hybrid";
+declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
 /**
-* Check command configuration options.
+* Human-readable category labels.
 */
-interface CheckConfig {
-	/**
-	* Example validation modes to run.
-	* Can be a single mode, array of modes, or comma-separated string.
-	* - 'presence': Check that @example blocks exist on exports
-	* - 'typecheck': Compile examples with TypeScript
-	* - 'run': Execute examples and validate assertions
-	*/
-	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
-	/** Minimum coverage percentage required (0-100) */
-	minCoverage?: number;
-	/** Maximum drift percentage allowed (0-100) */
-	maxDrift?: number;
-}
+declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
 /**
-* Normalized DocCov configuration.
-* This is the parsed/normalized form used by commands.
+* Category descriptions for help text.
 */
-interface DocCovConfig {
-	/** Export include patterns */
-	include?: string[];
-	/** Export exclude patterns */
-	exclude?: string[];
-	/** Plugins (future) */
-	plugins?: unknown[];
-	/** Documentation configuration */
-	docs?: DocsConfig;
-	/** Check command configuration */
-	check?: CheckConfig;
-	/**
-	* Schema extraction mode for validation libraries.
-	*
-	* - 'static' (default): Safe, uses TypeScript Compiler API
-	* - 'runtime': Uses Standard Schema (requires built package)
-	* - 'hybrid': Tries runtime first, falls back to static
-	*
-	* Runtime extraction provides richer JSON Schema output (formats, patterns)
-	* but requires the package to be built first.
-	*/
-	schemaExtraction?: SchemaExtractionMode;
+declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
+type SpecDocsMetadata = {
+	coverageScore?: number;
+	missing?: string[];
+	drift?: SpecDocDrift[];
+};
+/**
+* Result of computing drift for a single export.
+*/
+type ExportDriftResult = {
+	id: string;
+	drift: SpecDocDrift[];
+};
+/**
+* Result of computing drift for all exports.
+*/
+type DriftResult = {
+	exports: Map<string, SpecDocDrift[]>;
+};
+/**
+* Information about an for context-aware suggestions.
+*/
+interface ExportInfo {
+	name: string;
+	kind: string;
+	isCallable: boolean;
 }
 /**
-* Define a DocCov configuration.
-* Helper function for type-safe configuration in doccov.config.ts.
-*
-* @param config - Configuration object
-* @returns The configuration object (for type inference)
-*
-* @example
-* ```typescript
-* // doccov.config.ts
-* import { defineConfig } from '@doccov/sdk';
-*
-* defineConfig({
-*   include: ['MyClass', 'myFunction'],
-*   exclude: ['internal*'],
-*   check: {
-*     minCoverage: 80,
-*   },
-* });
-* ```
+* Registry of exports and types for cross-reference validation.
 */
-declare function defineConfig(config: DocCovConfig): DocCovConfig;
-interface DocCovOptions {
-	includePrivate?: boolean;
-	followImports?: boolean;
-	maxDepth?: number;
-	resolveExternalTypes?: boolean;
-	/** Enable spec caching (default: true) */
-	useCache?: boolean;
-	/** Working directory for cache operations (default: process.cwd()) */
-	cwd?: string;
-	/**
-	* Schema extraction mode for validation libraries (Zod, Valibot, etc.)
-	*
-	* - 'static' (default): TypeScript Compiler API only (no runtime)
-	* - 'runtime': Standard Schema runtime extraction (requires built package)
-	* - 'hybrid': Try runtime first, fall back to static
-	*/
-	schemaExtraction?: SchemaExtractionMode;
+interface ExportRegistry {
+	/** Map of names to their info (for context-aware suggestions) */
+	exports: Map<string, ExportInfo>;
+	/** Set of type names (interfaces, type aliases, etc.) */
+	types: Set<string>;
+	/** Combined set of all names (for backward compatibility) */
+	all: Set<string>;
 }
 /**
-* Pre-detected Standard Schema for a variable export.
+* Extended drift with category and fixability metadata.
 */
-interface DetectedSchemaEntry {
-	schema: Record<string, unknown>;
-	vendor: string;
+interface CategorizedDrift extends SpecDocDrift {
+	category: DriftCategory;
+	fixable: boolean;
 }
-import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
-type OpenPkgSpec = OpenPkg2;
 /**
-* Input for generation metadata that comes from the caller (CLI, API, etc.)
+* Summary of drift issues by category.
 */
-interface GenerationInput {
-	/** Entry point file path (relative to package root) */
-	entryPoint: string;
-	/** How the entry point was detected */
-	entryPointSource: EntryPointDetectionMethod;
-	/** Whether this is a declaration-only analysis (.d.ts file) */
-	isDeclarationOnly?: boolean;
-	/** Generator tool name */
-	generatorName: string;
-	/** Generator tool version */
-	generatorVersion: string;
-	/** Detected package manager */
-	packageManager?: string;
-	/** Whether this is a monorepo */
-	isMonorepo?: boolean;
-	/** Target package name (for monorepos) */
-	targetPackage?: string;
+interface DriftSummary {
+	total: number;
+	byCategory: Record<DriftCategory, number>;
+	fixable: number;
 }
 /**
-* Compute a hash of file contents.
-* Uses truncated SHA-256 for balance of speed and collision resistance.
+* Categorize a single drift issue.
 *
-* @param filePath - Absolute path to the file
-* @returns 16-character hex hash, or null if file doesn't exist
+* @param drift - The drift to categorize
+* @returns The drift with category and fixable metadata
+*
+* @example
+* ```ts
+* const drift: SpecDocDrift = {
+*   type: 'param-type-mismatch',
+*   target: 'userId',
+*   issue: 'Type mismatch'
+* };
+* const categorized = categorizeDrift(drift);
+* console.log(categorized.category); // => 'structural'
+* console.log(categorized.fixable);  // => true
+* ```
 */
-declare function hashFile(filePath: string): string | null;
+declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
 /**
-* Hash a string value.
+* Group drifts by category.
 *
-* @param content - String to hash
-* @returns 16-character hex hash
+* @param drifts - Array of drift issues to group
+* @returns Drifts organized by category
+*
+* @example
+* ```ts
+* const grouped = groupDriftsByCategory(spec.docs.drift ?? []);
+* console.log(grouped.structural.length); // Number of structural issues
+* console.log(grouped.semantic.length);   // Number of semantic issues
+* console.log(grouped.example.length);    // Number of example issues
+* ```
 */
-declare function hashString(content: string): string;
+declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
 /**
-* Hash multiple files and return a map of relative paths to hashes.
+* Get drift summary counts by category.
 *
-* @param filePaths - Array of absolute file paths
-* @param cwd - Base directory for relative path calculation
-* @returns Map of relative paths to their content hashes
+* @param drifts - Array of drift issues
+* @returns Summary with totals, category breakdown, and fixable count
+*
+* @example
+* ```ts
+* const summary = getDriftSummary(exportEntry.docs?.drift ?? []);
+* console.log(`${summary.total} issues: ${summary.fixable} fixable`);
+* // => "5 issues: 3 fixable"
+* ```
 */
-declare function hashFiles(filePaths: string[], cwd: string): Record<string, string>;
+declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 /**
-* Compare two hash maps and return changed files.
+* Format drift summary for CLI output (single line).
 *
-* @param cached - Hash map from cache
-* @param current - Current hash map
-* @returns Array of file paths that changed, were added, or were removed
+* @param summary - Drift summary to format
+* @returns Human-readable summary string
+*
+* @example
+* ```ts
+* const summary = getDriftSummary(drifts);
+* console.log(formatDriftSummaryLine(summary));
+* // => "5 issues (3 structural, 1 semantic, 1 example)"
+* ```
 */
-declare function diffHashes(cached: Record<string, string>, current: Record<string, string>): string[];
-import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
-/** Current cache format version */
-declare const CACHE_VERSION = "1.0.0";
-/** Default cache file path */
-declare const SPEC_CACHE_FILE = ".doccov/spec.cache.json";
+declare function formatDriftSummaryLine(summary: DriftSummary): string;
+import { SpecExport } from "@openpkg-ts/spec";
 /**
-* Configuration that affects spec generation output.
+* Build a registry of all export/type names for cross-reference validation.
 */
-interface SpecCacheConfig {
-	resolveExternalTypes: boolean;
-}
+declare function buildExportRegistry(spec: OpenPkgSpec): ExportRegistry;
 /**
-* Cached spec with validation metadata.
+* Compute drift for all exports in a spec.
+*
+* @param spec - The OpenPkg spec to analyze
+* @returns Drift results per */
+declare function computeDrift(spec: OpenPkgSpec): DriftResult;
+/**
+* Compute drift for a single export.
+*
+* @param entry - The to analyze
+* @param registry - Registry of known exports and types for validation
+* @returns Array of drift issues detected
 */
-interface SpecCache {
-	/** Cache format version for migrations */
-	cacheVersion: string;
-	/** When cache was generated (ISO timestamp) */
-	generatedAt: string;
-	/** OpenPkg spec version (e.g., "0.3.0") */
-	specVersion: string;
-	/** Entry file that was analyzed (relative path) */
-	entryFile: string;
-	/** Hash validation data */
-	hashes: {
-		/** Hash of tsconfig.json content (null if not found) */
-		tsconfig: string | null;
-		/** Hash of package.json content */
-		packageJson: string;
-		/** Source file hashes: relative filepath → content hash */
-		sourceFiles: Record<string, string>;
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
+/**
+* Calculate aggregate coverage score from a spec's exports.
+*
+* This is a lightweight function that calculates coverage without
+* requiring full quality evaluation. It handles three cases:
+* 1. Exports with `docs.coverageScore` - uses that value
+* 2. Exports without score but with description - counts as 100%
+* 3. Exports without score and no description - counts as 0%
+*
+* @param spec - The OpenPkg spec to calculate coverage for
+* @returns The aggregate coverage score (0-100)
+*
+* @example
+* ```ts
+* import { calculateAggregateCoverage } from '@doccov/sdk';
+*
+* const coverage = calculateAggregateCoverage(spec);
+* console.log(`Coverage: ${coverage}%`);
+* ```
+*/
+declare function calculateAggregateCoverage(spec: OpenPkgSpec): number;
+/**
+* Ensure a spec has a top-level docs.coverageScore.
+*
+* If the spec already has `docs.coverageScore`, returns the spec unchanged.
+* Otherwise, calculates aggregate coverage from exports and returns a
+* new spec with the coverage score added.
+*
+* This is useful for commands like `diff` that need coverage scores
+* but may receive raw specs that haven't been enriched.
+*
+* @param spec - The OpenPkg spec to ensure coverage for
+* @returns The spec with guaranteed top-level coverage score
+*
+* @example
+* ```ts
+* import { ensureSpecCoverage } from '@doccov/sdk';
+*
+* // Works with raw or enriched specs
+* const specWithCoverage = ensureSpecCoverage(rawSpec);
+* console.log(specWithCoverage.docs?.coverageScore); // e.g., 85
+* ```
+*/
+declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
+	docs: {
+		coverageScore: number;
 	};
-	/** Analysis configuration that affects output */
-	config: SpecCacheConfig;
-	/** The cached OpenPkg spec */
-	spec: OpenPkg3;
+};
+import { SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+interface ExampleRunResult {
+	success: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+	duration: number;
+}
+interface RunExampleOptions {
+	/** Timeout in milliseconds (default: 5000) */
+	timeout?: number;
+	/** Working directory for execution */
+	cwd?: string;
+}
+interface RunExamplesWithPackageOptions extends RunExampleOptions {
+	/** Path to the local package to install */
+	packagePath: string;
+	/** Package manager to use (auto-detected if not specified) */
+	packageManager?: "npm" | "pnpm" | "bun";
+	/** Timeout for package installation in ms (default: 60000) */
+	installTimeout?: number;
+}
+interface RunExamplesWithPackageResult {
+	/** Results for each example by index */
+	results: Map<number, ExampleRunResult>;
+	/** Whether package installation succeeded */
+	installSuccess: boolean;
+	/** Error message if installation failed */
+	installError?: string;
+	/** Total duration including install */
+	totalDuration: number;
 }
 /**
-* Result of cache validation.
+* Run an example code snippet in an isolated Node process.
+* Uses Node 22+ --experimental-strip-types for direct TS execution.
 */
-interface CacheValidationResult {
-	/** Whether the cache is valid */
-	valid: boolean;
-	/** Reason for invalidation (if invalid) */
-	reason?: "cache-version-mismatch" | "entry-file-changed" | "config-changed" | "tsconfig-changed" | "package-json-changed" | "source-files-changed";
-	/** Files that changed (if reason is source-files-changed) */
-	changedFiles?: string[];
-}
+declare function runExample(code: string, options?: RunExampleOptions): Promise<ExampleRunResult>;
 /**
-* Context needed for cache operations.
+* Run multiple examples and collect results
 */
-interface CacheContext {
-	/** Entry file being analyzed (absolute path) */
-	entryFile: string;
-	/** Source files included in analysis (absolute paths) */
-	sourceFiles: string[];
-	/** Path to tsconfig.json (absolute, or null if not found) */
-	tsconfigPath: string | null;
-	/** Path to package.json (absolute) */
-	packageJsonPath: string;
-	/** Configuration that affects output */
-	config: SpecCacheConfig;
-	/** Working directory */
-	cwd: string;
-}
+declare function runExamples(examples: string[], options?: RunExampleOptions): Promise<Map<number, ExampleRunResult>>;
 /**
-* Load cached spec from disk.
-*
-* @param cwd - Working directory
-* @returns Cached spec, or null if not found or invalid JSON
+* Run multiple examples with a pre-installed local package.
+* Creates a single temp directory, installs the package once,
+* runs all examples, then cleans up.
 */
-declare function loadSpecCache(cwd: string): SpecCache | null;
+declare function runExamplesWithPackage(examples: string[], options: RunExamplesWithPackageOptions): Promise<RunExamplesWithPackageResult>;
 /**
-* Save spec to cache.
-*
-* @param spec - OpenPkg spec to cache
-* @param context - Cache context with file paths and config
+* Detect runtime errors in @example blocks.
+* Results are provided externally after running examples via runExamples().
 */
-declare function saveSpecCache(spec: OpenPkg3, context: CacheContext): void;
+declare function detectExampleRuntimeErrors(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 /**
-* Validate if cached spec is still valid.
-*
-* Checks:
-* 1. Cache version matches
-* 2. Entry file matches
-* 3. Config matches
-* 4. tsconfig.json hash matches
-* 5. package.json hash matches
-* 6. All source file hashes match
-*
-* @param cache - Cached spec to validate
-* @param context - Current cache context
-* @returns Validation result
+* Parse assertion comments from example code.
+* Matches: // => expected_value
 */
-declare function validateSpecCache(cache: SpecCache, context: CacheContext): CacheValidationResult;
+declare function parseAssertions(code: string): Array<{
+	lineNumber: number;
+	expected: string;
+}>;
 /**
-* Clear the spec cache.
-*
-* @param cwd - Working directory
-* @returns True if cache was deleted, false if it didn't exist
+* Check if code contains comments that are not assertion syntax.
+* Used to determine if LLM fallback should be attempted.
 */
-declare function clearSpecCache(cwd: string): boolean;
+declare function hasNonAssertionComments(code: string): boolean;
 /**
-* Get cache file path for a given working directory.
-*
-* @param cwd - Working directory
-* @returns Absolute path to cache file
+* Detect assertion failures by comparing stdout to expected values.
 */
-declare function getSpecCachePath(cwd: string): string;
+declare function detectExampleAssertionFailures(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
+import { OpenPkg as OpenPkg3, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 /**
-* Release stage/visibility tags that can be used for filtering.
-* Based on TSDoc release tags.
+* An enriched with computed documentation metadata.
+* Extends SpecExport with the `docs` field for coverage analysis.
 */
-type ReleaseTag = "public" | "beta" | "alpha" | "internal";
-interface FilterOptions {
-	/** Include exports matching these patterns */
-	include?: string[];
-	/** Exclude exports matching these patterns */
-	exclude?: string[];
-	/** Filter by visibility/release stage (e.g., ['public', 'beta']) */
-	visibility?: ReleaseTag[];
-}
-interface Diagnostic2 {
-	message: string;
-	severity: "error" | "warning" | "info";
-	suggestion?: string;
-	location?: {
-		file: string;
-		line?: number;
-		column?: number;
-	};
-}
-interface AnalysisResult {
-	spec: OpenPkgSpec;
-	diagnostics: Diagnostic2[];
-	metadata: AnalysisMetadata;
-	/** True if result came from cache (no fresh analysis) */
-	fromCache?: boolean;
-	/** Cache validation details (if cache was checked) */
-	cacheStatus?: CacheValidationResult;
-}
-interface AnalysisMetadata {
-	baseDir: string;
-	configPath?: string;
-	packageJsonPath?: string;
-	hasNodeModules: boolean;
-	resolveExternalTypes: boolean;
-	/** Source files included in analysis (for caching) */
-	sourceFiles?: string[];
-}
-interface AnalyzeOptions {
-	filters?: FilterOptions;
-	/** Generation metadata input (entry point info, tool version, etc.) */
-	generationInput?: GenerationInput;
-}
-declare class DocCov {
-	private readonly options;
-	constructor(options?: DocCovOptions);
-	analyze(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
-	analyzeFile(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
-	analyzeProject(entryPath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
-	analyzeWithDiagnostics(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
-	analyzeFileWithDiagnostics(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
-	/**
-	* Try to load spec from cache.
-	* Returns null if cache is invalid or doesn't exist.
-	*/
-	private tryLoadFromCache;
-	/**
-	* Get current source files from a fresh TypeScript program.
-	* Used for cache validation to detect new files.
-	*/
-	private getCurrentSourceFiles;
-	/**
-	* Save analysis result to cache.
-	*/
-	private saveToCache;
-	/**
-	* Find tsconfig.json starting from a directory.
-	*/
-	private findTsConfig;
-	/**
-	* Find package.json starting from a directory.
-	*/
-	private findPackageJson;
+type EnrichedExport = SpecExport7 & {
+	docs?: EnrichedDocsMetadata;
+};
+/**
+* Extended docs metadata.
+*/
+type EnrichedDocsMetadata = SpecDocsMetadata;
+/**
+* An enriched OpenPkg spec with computed documentation metadata.
+* Extends OpenPkg with per-and aggregate coverage data.
+*/
+type EnrichedOpenPkg = Omit<OpenPkg3, "exports"> & {
+	exports: EnrichedExport[];
+	docs?: EnrichedDocsMetadata;
+	/** Drift summary with category breakdown (if drift exists) */
+	driftSummary?: DriftSummary;
+};
+interface EnrichOptions {
 	/**
-	* Detect Standard Schema exports from compiled modules.
-	* Only runs when schemaExtraction is 'runtime' or 'hybrid'.
-	* Returns undefined if detection is disabled, fails, or no schemas found.
+	* Per-drift issues to include in enrichment.
+	* Map from ID to drift issues.
 	*/
-	private detectSchemas;
-	private normalizeDiagnostic;
-	private mapSeverity;
-	private normalizeMetadata;
-	private applySpecFilters;
+	driftByExport?: Map<string, SpecDocDrift[]>;
 }
-declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
-declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
-import { OpenPkg as OpenPkg4, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 /**
-* All possible drift type identifiers.
+* Enrich an OpenPkg spec with documentation coverage metadata.
+*
+* Computes coverage scores and detects drift issues.
+*
+* @param spec - The pure OpenPkg spec to enrich
+* @param options - Optional enrichment configuration
+* @returns An enriched spec with documentation metadata
+*
+* @example
+* ```ts
+* import { DocCov, enrichSpec } from '@doccov/sdk';
+*
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+*
+* const enriched = enrichSpec(spec);
+* console.log(enriched.docs?.coverageScore); // e.g., 85
+* ```
 */
-type DriftType = "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "async-mismatch" | "property-type-drift" | "example-drift" | "example-syntax-error" | "example-runtime-error" | "example-assertion-failed" | "broken-link";
-type SpecDocDrift = {
-	type: DriftType;
-	target?: string;
-	issue: string;
-	suggestion?: string;
-};
+declare function enrichSpec(spec: OpenPkg3, options?: EnrichOptions): EnrichedOpenPkg;
+import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
 /**
-* Drift categories group related drift types for progressive disclosure.
+* DocCov report schema version.
 */
-type DriftCategory = "structural" | "semantic" | "example";
+declare const REPORT_VERSION = "1.0.0";
 /**
-* Maps each drift type to its category.
+* Default directory for DocCov outputs.
 */
-declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
+declare const DEFAULT_REPORT_DIR = ".doccov";
 /**
-* Human-readable category labels.
+* Default path for cached DocCov reports.
 */
-declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
+declare const DEFAULT_REPORT_PATH = ".doccov/report.json";
 /**
-* Category descriptions for help text.
+* File extensions for each report format.
 */
-declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
-type SpecDocsMetadata = {
-	coverageScore?: number;
-	missing?: string[];
-	drift?: SpecDocDrift[];
-};
+declare const REPORT_EXTENSIONS: Record<string, string>;
 /**
-* Result of computing drift for a single export.
+* Get the default report path for a given format.
+*
+* @param format - The report format (json, markdown, html, github)
+* @param dir - The output directory (defaults to .doccov)
+* @returns The full path to the report file
+*
+* @example
+* ```ts
+* getReportPath('markdown'); // '.doccov/report.md'
+* getReportPath('html', 'reports'); // 'reports/report.html'
+* ```
 */
-type ExportDriftResult = {
-	id: string;
-	drift: SpecDocDrift[];
-};
+declare function getReportPath(format: string, dir?: string): string;
 /**
-* Result of computing drift for all exports.
+* Get the report path for a diff comparison.
+*
+* Uses truncated hashes from both specs to create a unique, deterministic filename.
+*
+* @param baseHash - Hash of the base (before) spec
+* @param headHash - Hash of the head (after) spec
+* @param format - The report format (json, markdown, html, github)
+* @param dir - The output directory (defaults to .doccov)
+* @returns The full path to the diff report file
+*
+* @example
+* ```ts
+* getDiffReportPath('abc123def456', 'xyz789uvw012', 'markdown');
+* // '.doccov/diff-abc123de-xyz789uv.md'
+* ```
 */
-type DriftResult = {
-	exports: Map<string, SpecDocDrift[]>;
-};
+declare function getDiffReportPath(baseHash: string, headHash: string, format: string, dir?: string): string;
 /**
-* Information about an for context-aware suggestions.
+* Drift summary with category breakdown.
 */
-interface ExportInfo {
-	name: string;
-	kind: string;
-	isCallable: boolean;
+interface DriftReportSummary {
+	/**
+	* Total number of drift issues.
+	*/
+	total: number;
+	/**
+	* Count of issues per category.
+	*/
+	byCategory: Record<DriftCategory, number>;
+	/**
+	* Number of auto-fixable issues.
+	*/
+	fixable: number;
 }
 /**
-* Registry of exports and types for cross-reference validation.
+* Drift report with progressive disclosure structure.
+*
+* Provides three levels of detail:
+* 1. Summary - total counts by category
+* 2. By category - grouped drift issues
+* 3. All - flat list for backward compatibility
 */
-interface ExportRegistry {
-	/** Map of names to their info (for context-aware suggestions) */
-	exports: Map<string, ExportInfo>;
-	/** Set of type names (interfaces, type aliases, etc.) */
-	types: Set<string>;
-	/** Combined set of all names (for backward compatibility) */
-	all: Set<string>;
+interface DriftReport {
+	/**
+	* High-level summary counts.
+	*/
+	summary: DriftReportSummary;
+	/**
+	* Issues grouped by category.
+	*/
+	byCategory: Record<DriftCategory, CategorizedDrift[]>;
+	/**
+	* Flat list of all drift issues (backward compatible).
+	*/
+	all: CategorizedDrift[];
 }
 /**
-* Extended drift with category and fixability metadata.
+* Coverage summary for an entire package or project.
 */
-interface CategorizedDrift extends SpecDocDrift {
-	category: DriftCategory;
-	fixable: boolean;
+interface CoverageSummary {
+	/**
+	* Overall coverage score (0-100).
+	*/
+	score: number;
+	/**
+	* Total number of exports analyzed.
+	*/
+	totalExports: number;
+	/**
+	* Number of fully documented exports.
+	*/
+	documentedExports: number;
+	/**
+	* Breakdown of missing documentation by rule ID.
+	*/
+	missingByRule: Record<string, number>;
+	/**
+	* Total number of drift issues detected.
+	*/
+	driftCount: number;
+	/**
+	* Drift summary with category breakdown.
+	*/
+	driftSummary?: DriftReportSummary;
+}
+/**
+* Coverage data for a single export.
+*/
+interface ExportCoverageData {
+	/**
+	* Export name.
+	*/
+	name: string;
+	/**
+	* Export kind (function, class, etc.).
+	*/
+	kind: string;
+	/**
+	* Coverage score for this (0-100).
+	*/
+	coverageScore: number;
+	/**
+	* Missing documentation rule IDs.
+	*/
+	missing?: string[];
+	/**
+	* Drift issues for this export.
+	*/
+	drift?: SpecDocDrift[];
 }
 /**
-* Summary of drift issues by category.
+* DocCov report - a persistable coverage analysis result.
+*
+* This is the format saved to `.doccov/report.json` and returned
+* by the `check` command with `--format json`.
 */
-interface DriftSummary {
-	total: number;
-	byCategory: Record<DriftCategory, number>;
-	fixable: number;
+interface DocCovReport {
+	/**
+	* JSON Schema reference for validation.
+	*/
+	$schema: string;
+	/**
+	* Report format version.
+	*/
+	version: string;
+	/**
+	* ISO 8601 timestamp when report was generated.
+	*/
+	generatedAt: string;
+	/**
+	* Package/project metadata.
+	*/
+	spec: {
+		name: string;
+		version?: string;
+	};
+	/**
+	* Aggregate coverage summary.
+	*/
+	coverage: CoverageSummary;
+	/**
+	* Per-coverage data, keyed by ID.
+	*/
+	exports: Record<string, ExportCoverageData>;
 }
 /**
-* Categorize a single drift issue.
+* Generate a DocCov report from an OpenPkg spec.
 *
-* @param drift - The drift to categorize
-* @returns The drift with category and fixable metadata
+* @param spec - The pure OpenPkg spec to analyze
+* @returns A DocCov report with coverage analysis
 *
 * @example
 * ```ts
-* const drift: SpecDocDrift = {
-*   type: 'param-type-mismatch',
-*   target: 'userId',
-*   issue: 'Type mismatch'
-* };
-* const categorized = categorizeDrift(drift);
-* console.log(categorized.category); // => 'structural'
-* console.log(categorized.fixable);  // => true
-* ```
-*/
-declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
-/**
-* Group drifts by category.
+* import { DocCov, generateReport } from '@doccov/sdk';
 *
-* @param drifts - Array of drift issues to group
-* @returns Drifts organized by category
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* const report = generateReport(spec);
 *
-* @example
-* ```ts
-* const grouped = groupDriftsByCategory(spec.docs.drift ?? []);
-* console.log(grouped.structural.length); // Number of structural issues
-* console.log(grouped.semantic.length);   // Number of semantic issues
-* console.log(grouped.example.length);    // Number of example issues
+* console.log(`Coverage: ${report.coverage.score}%`);
 * ```
 */
-declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
+declare function generateReport(spec: OpenPkg4): DocCovReport;
 /**
-* Get drift summary counts by category.
+* Generate a DocCov report from an already-enriched spec.
 *
-* @param drifts - Array of drift issues
-* @returns Summary with totals, category breakdown, and fixable count
+* Use this when you've already called enrichSpec() and want to avoid
+* recomputing coverage data.
 *
-* @example
-* ```ts
-* const summary = getDriftSummary(exportEntry.docs?.drift ?? []);
-* console.log(`${summary.total} issues: ${summary.fixable} fixable`);
-* // => "5 issues: 3 fixable"
-* ```
+* @param enriched - The enriched OpenPkg spec
+* @returns A DocCov report with coverage analysis
 */
-declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
+declare function generateReportFromEnriched(enriched: EnrichedOpenPkg): DocCovReport;
 /**
-* Format drift summary for CLI output (single line).
-*
-* @param summary - Drift summary to format
-* @returns Human-readable summary string
+* Load a cached DocCov report from disk.
 *
-* @example
-* ```ts
-* const summary = getDriftSummary(drifts);
-* console.log(formatDriftSummaryLine(summary));
-* // => "5 issues (3 structural, 1 semantic, 1 example)"
-* ```
-*/
-declare function formatDriftSummaryLine(summary: DriftSummary): string;
-import { SpecExport } from "@openpkg-ts/spec";
-/**
-* Build a registry of all export/type names for cross-reference validation.
+* @param reportPath - Path to the report file (defaults to .doccov/report.json)
+* @returns The cached report, or null if not found
 */
-declare function buildExportRegistry(spec: OpenPkgSpec): ExportRegistry;
-/**
-* Compute drift for all exports in a spec.
-*
-* @param spec - The OpenPkg spec to analyze
-* @returns Drift results per */
-declare function computeDrift(spec: OpenPkgSpec): DriftResult;
+declare function loadCachedReport(reportPath?: string): DocCovReport | null;
 /**
-* Compute drift for a single export.
+* Save a DocCov report to disk.
 *
-* @param entry - The to analyze
-* @param registry - Registry of known exports and types for validation
-* @returns Array of drift issues detected
+* @param report - The report to save
+* @param reportPath - Path to save the report (defaults to .doccov/report.json)
 */
-declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
+declare function saveReport(report: DocCovReport, reportPath?: string): void;
 /**
-* Calculate aggregate coverage score from a spec's exports.
+* Generate a git-trackable API surface markdown file from an OpenPkg spec.
 *
-* This is a lightweight function that calculates coverage without
-* requiring full quality evaluation. It handles three cases:
-* 1. Exports with `docs.coverageScore` - uses that value
-* 2. Exports without score but with description - counts as 100%
-* 3. Exports without score and no description - counts as 0%
+* This produces a deterministic, sorted output suitable for version control.
+* Changes to the API will show up as diffs in this file.
 *
-* @param spec - The OpenPkg spec to calculate coverage for
-* @returns The aggregate coverage score (0-100)
+* @param spec - The OpenPkg spec to render
+* @returns Markdown string representing the API surface
 *
 * @example
 * ```ts
-* import { calculateAggregateCoverage } from '@doccov/sdk';
-*
-* const coverage = calculateAggregateCoverage(spec);
-* console.log(`Coverage: ${coverage}%`);
-* ```
-*/
-declare function calculateAggregateCoverage(spec: OpenPkgSpec): number;
-/**
-* Ensure a spec has a top-level docs.coverageScore.
-*
-* If the spec already has `docs.coverageScore`, returns the spec unchanged.
-* Otherwise, calculates aggregate coverage from exports and returns a
-* new spec with the coverage score added.
-*
-* This is useful for commands like `diff` that need coverage scores
-* but may receive raw specs that haven't been enriched.
-*
-* @param spec - The OpenPkg spec to ensure coverage for
-* @returns The spec with guaranteed top-level coverage score
+* import { DocCov, renderApiSurface } from '@doccov/sdk';
 *
-* @example
-* ```ts
-* import { ensureSpecCoverage } from '@doccov/sdk';
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* const apiSurface = renderApiSurface(spec);
 *
-* // Works with raw or enriched specs
-* const specWithCoverage = ensureSpecCoverage(rawSpec);
-* console.log(specWithCoverage.docs?.coverageScore); // e.g., 85
+* fs.writeFileSync('api-surface.md', apiSurface);
 * ```
 */
-declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
-	docs: {
-		coverageScore: number;
-	};
-};
-import { SpecExport as SpecExport2 } from "@openpkg-ts/spec";
-interface ExampleRunResult {
-	success: boolean;
-	stdout: string;
-	stderr: string;
-	exitCode: number;
-	duration: number;
-}
-interface RunExampleOptions {
-	/** Timeout in milliseconds (default: 5000) */
-	timeout?: number;
-	/** Working directory for execution */
-	cwd?: string;
-}
-interface RunExamplesWithPackageOptions extends RunExampleOptions {
-	/** Path to the local package to install */
-	packagePath: string;
-	/** Package manager to use (auto-detected if not specified) */
-	packageManager?: "npm" | "pnpm" | "bun";
-	/** Timeout for package installation in ms (default: 60000) */
-	installTimeout?: number;
-}
-interface RunExamplesWithPackageResult {
-	/** Results for each example by index */
-	results: Map<number, ExampleRunResult>;
-	/** Whether package installation succeeded */
-	installSuccess: boolean;
-	/** Error message if installation failed */
-	installError?: string;
-	/** Total duration including install */
-	totalDuration: number;
-}
-/**
-* Run an example code snippet in an isolated Node process.
-* Uses Node 22+ --experimental-strip-types for direct TS execution.
-*/
-declare function runExample(code: string, options?: RunExampleOptions): Promise<ExampleRunResult>;
-/**
-* Run multiple examples and collect results
-*/
-declare function runExamples(examples: string[], options?: RunExampleOptions): Promise<Map<number, ExampleRunResult>>;
-/**
-* Run multiple examples with a pre-installed local package.
-* Creates a single temp directory, installs the package once,
-* runs all examples, then cleans up.
-*/
-declare function runExamplesWithPackage(examples: string[], options: RunExamplesWithPackageOptions): Promise<RunExamplesWithPackageResult>;
-/**
-* Detect runtime errors in @example blocks.
-* Results are provided externally after running examples via runExamples().
-*/
-declare function detectExampleRuntimeErrors(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
+declare function renderApiSurface(spec: OpenPkg4): string;
+import { EntryPointDetectionMethod } from "@openpkg-ts/spec";
 /**
-* Parse assertion comments from example code.
-* Matches: // => expected_value
+* Configuration types for DocCov.
+* These types are shared between CLI and API.
 */
-declare function parseAssertions(code: string): Array<{
-	lineNumber: number;
-	expected: string;
-}>;
 /**
-* Check if code contains comments that are not assertion syntax.
-* Used to determine if LLM fallback should be attempted.
+* Documentation configuration options.
 */
-declare function hasNonAssertionComments(code: string): boolean;
+interface DocsConfig {
+	/** Glob patterns for markdown docs to include */
+	include?: string[];
+	/** Glob patterns for markdown docs to exclude */
+	exclude?: string[];
+}
 /**
-* Detect assertion failures by comparing stdout to expected values.
+* Example validation modes.
 */
-declare function detectExampleAssertionFailures(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
+type ExampleValidationMode = "presence" | "typecheck" | "run";
 /**
-* An enriched with computed documentation metadata.
-* Extends SpecExport with the `docs` field for coverage analysis.
+* Schema extraction modes for validation libraries (Zod, Valibot, TypeBox, ArkType).
+*
+* - 'static': TypeScript Compiler API only (no runtime, always safe)
+* - 'runtime': Standard Schema runtime extraction (requires built package)
+* - 'hybrid': Try runtime first, fall back to static
 */
-type EnrichedExport = SpecExport7 & {
-	docs?: EnrichedDocsMetadata;
-};
+type SchemaExtractionMode = "static" | "runtime" | "hybrid";
 /**
-* Extended docs metadata.
+* Check command configuration options.
 */
-type EnrichedDocsMetadata = SpecDocsMetadata;
+interface CheckConfig {
+	/**
+	* Example validation modes to run.
+	* Can be a single mode, array of modes, or comma-separated string.
+	* - 'presence': Check that @example blocks exist on exports
+	* - 'typecheck': Compile examples with TypeScript
+	* - 'run': Execute examples and validate assertions
+	*/
+	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
+	/** Minimum coverage percentage required (0-100) */
+	minCoverage?: number;
+	/** Maximum drift percentage allowed (0-100) */
+	maxDrift?: number;
+}
 /**
-* An enriched OpenPkg spec with computed documentation metadata.
-* Extends OpenPkg with per-and aggregate coverage data.
+* Normalized DocCov configuration.
+* This is the parsed/normalized form used by commands.
 */
-type EnrichedOpenPkg = Omit<OpenPkg4, "exports"> & {
-	exports: EnrichedExport[];
-	docs?: EnrichedDocsMetadata;
-	/** Drift summary with category breakdown (if drift exists) */
-	driftSummary?: DriftSummary;
-};
-interface EnrichOptions {
+interface DocCovConfig {
+	/** Export include patterns */
+	include?: string[];
+	/** Export exclude patterns */
+	exclude?: string[];
+	/** Plugins (future) */
+	plugins?: unknown[];
+	/** Documentation configuration */
+	docs?: DocsConfig;
+	/** Check command configuration */
+	check?: CheckConfig;
 	/**
-	* Per-drift issues to include in enrichment.
-	* Map from ID to drift issues.
+	* Schema extraction mode for validation libraries.
+	*
+	* - 'static' (default): Safe, uses TypeScript Compiler API
+	* - 'runtime': Uses Standard Schema (requires built package)
+	* - 'hybrid': Tries runtime first, falls back to static
+	*
+	* Runtime extraction provides richer JSON Schema output (formats, patterns)
+	* but requires the package to be built first.
 	*/
-	driftByExport?: Map<string, SpecDocDrift[]>;
+	schemaExtraction?: SchemaExtractionMode;
 }
 /**
-* Enrich an OpenPkg spec with documentation coverage metadata.
-*
-* Computes coverage scores and detects drift issues.
+* Define a DocCov configuration.
+* Helper function for type-safe configuration in doccov.config.ts.
 *
-* @param spec - The pure OpenPkg spec to enrich
-* @param options - Optional enrichment configuration
-* @returns An enriched spec with documentation metadata
+* @param config - Configuration object
+* @returns The configuration object (for type inference)
 *
 * @example
-* ```ts
-* import { DocCov, enrichSpec } from '@doccov/sdk';
-*
-* const doccov = new DocCov();
-* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* ```typescript
+* // doccov.config.ts
+* import { defineConfig } from '@doccov/sdk';
 *
-* const enriched = enrichSpec(spec);
-* console.log(enriched.docs?.coverageScore); // e.g., 85
+* defineConfig({
+*   include: ['MyClass', 'myFunction'],
+*   exclude: ['internal*'],
+*   check: {
+*     minCoverage: 80,
+*   },
+* });
 * ```
 */
-declare function enrichSpec(spec: OpenPkg4, options?: EnrichOptions): EnrichedOpenPkg;
-import { DocCovSpec } from "@doccov/spec";
-interface BuildDocCovOptions {
-	openpkgPath: string;
-	openpkg: OpenPkgSpec;
-	packagePath?: string;
+declare function defineConfig(config: DocCovConfig): DocCovConfig;
+interface DocCovOptions {
+	includePrivate?: boolean;
+	followImports?: boolean;
+	maxDepth?: number;
+	resolveExternalTypes?: boolean;
+	/** Enable spec caching (default: true) */
+	useCache?: boolean;
+	/** Working directory for cache operations (default: process.cwd()) */
+	cwd?: string;
+	/**
+	* Schema extraction mode for validation libraries (Zod, Valibot, etc.)
+	*
+	* - 'static' (default): TypeScript Compiler API only (no runtime)
+	* - 'runtime': Standard Schema runtime extraction (requires built package)
+	* - 'hybrid': Try runtime first, fall back to static
+	*/
+	schemaExtraction?: SchemaExtractionMode;
 }
 /**
-* Build a DocCov spec from an OpenPkg spec.
-*
-* @param options - Build options
-* @returns DocCov specification with coverage analysis
-*/
-declare function buildDocCovSpec(options: BuildDocCovOptions): DocCovSpec;
-import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
-/**
-* DocCov report schema version.
+* Pre-detected Standard Schema for a variable export.
 */
-declare const REPORT_VERSION = "1.0.0";
+interface DetectedSchemaEntry {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
 /**
-* Default directory for DocCov outputs.
+* Input for generation metadata that comes from the caller (CLI, API, etc.)
 */
-declare const DEFAULT_REPORT_DIR = ".doccov";
+interface GenerationInput {
+	/** Entry point file path (relative to package root) */
+	entryPoint: string;
+	/** How the entry point was detected */
+	entryPointSource: EntryPointDetectionMethod;
+	/** Whether this is a declaration-only analysis (.d.ts file) */
+	isDeclarationOnly?: boolean;
+	/** Generator tool name */
+	generatorName: string;
+	/** Generator tool version */
+	generatorVersion: string;
+	/** Detected package manager */
+	packageManager?: string;
+	/** Whether this is a monorepo */
+	isMonorepo?: boolean;
+	/** Target package name (for monorepos) */
+	targetPackage?: string;
+}
 /**
-* Default path for cached DocCov reports.
+* Compute a hash of file contents.
+* Uses truncated SHA-256 for balance of speed and collision resistance.
+*
+* @param filePath - Absolute path to the file
+* @returns 16-character hex hash, or null if file doesn't exist
 */
-declare const DEFAULT_REPORT_PATH = ".doccov/report.json";
+declare function hashFile(filePath: string): string | null;
 /**
-* File extensions for each report format.
+* Hash a string value.
+*
+* @param content - String to hash
+* @returns 16-character hex hash
 */
-declare const REPORT_EXTENSIONS: Record<string, string>;
+declare function hashString(content: string): string;
 /**
-* Get the default report path for a given format.
-*
-* @param format - The report format (json, markdown, html, github)
-* @param dir - The output directory (defaults to .doccov)
-* @returns The full path to the report file
+* Hash multiple files and return a map of relative paths to hashes.
 *
-* @example
-* ```ts
-* getReportPath('markdown'); // '.doccov/report.md'
-* getReportPath('html', 'reports'); // 'reports/report.html'
-* ```
+* @param filePaths - Array of absolute file paths
+* @param cwd - Base directory for relative path calculation
+* @returns Map of relative paths to their content hashes
 */
-declare function getReportPath(format: string, dir?: string): string;
+declare function hashFiles(filePaths: string[], cwd: string): Record<string, string>;
 /**
-* Get the report path for a diff comparison.
-*
-* Uses truncated hashes from both specs to create a unique, deterministic filename.
-*
-* @param baseHash - Hash of the base (before) spec
-* @param headHash - Hash of the head (after) spec
-* @param format - The report format (json, markdown, html, github)
-* @param dir - The output directory (defaults to .doccov)
-* @returns The full path to the diff report file
+* Compare two hash maps and return changed files.
 *
-* @example
-* ```ts
-* getDiffReportPath('abc123def456', 'xyz789uvw012', 'markdown');
-* // '.doccov/diff-abc123de-xyz789uv.md'
-* ```
+* @param cached - Hash map from cache
+* @param current - Current hash map
+* @returns Array of file paths that changed, were added, or were removed
 */
-declare function getDiffReportPath(baseHash: string, headHash: string, format: string, dir?: string): string;
+declare function diffHashes(cached: Record<string, string>, current: Record<string, string>): string[];
+import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
+/** Current cache format version */
+declare const CACHE_VERSION = "1.0.0";
+/** Default cache file path */
+declare const SPEC_CACHE_FILE = ".doccov/spec.cache.json";
 /**
-* Drift summary with category breakdown.
+* Configuration that affects spec generation output.
 */
-interface DriftReportSummary {
-	/**
-	* Total number of drift issues.
-	*/
-	total: number;
-	/**
-	* Count of issues per category.
-	*/
-	byCategory: Record<DriftCategory, number>;
-	/**
-	* Number of auto-fixable issues.
-	*/
-	fixable: number;
+interface SpecCacheConfig {
+	resolveExternalTypes: boolean;
 }
 /**
-* Drift report with progressive disclosure structure.
-*
-* Provides three levels of detail:
-* 1. Summary - total counts by category
-* 2. By category - grouped drift issues
-* 3. All - flat list for backward compatibility
+* Cached spec with validation metadata.
 */
-interface DriftReport {
-	/**
-	* High-level summary counts.
-	*/
-	summary: DriftReportSummary;
-	/**
-	* Issues grouped by category.
-	*/
-	byCategory: Record<DriftCategory, CategorizedDrift[]>;
-	/**
-	* Flat list of all drift issues (backward compatible).
-	*/
-	all: CategorizedDrift[];
+interface SpecCache {
+	/** Cache format version for migrations */
+	cacheVersion: string;
+	/** When cache was generated (ISO timestamp) */
+	generatedAt: string;
+	/** OpenPkg spec version (e.g., "0.3.0") */
+	specVersion: string;
+	/** Entry file that was analyzed (relative path) */
+	entryFile: string;
+	/** Hash validation data */
+	hashes: {
+		/** Hash of tsconfig.json content (null if not found) */
+		tsconfig: string | null;
+		/** Hash of package.json content */
+		packageJson: string;
+		/** Source file hashes: relative filepath → content hash */
+		sourceFiles: Record<string, string>;
+	};
+	/** Analysis configuration that affects output */
+	config: SpecCacheConfig;
+	/** The cached OpenPkg spec */
+	spec: OpenPkg5;
 }
 /**
-* Coverage summary for an entire package or project.
+* Result of cache validation.
 */
-interface CoverageSummary {
-	/**
-	* Overall coverage score (0-100).
-	*/
-	score: number;
-	/**
-	* Total number of exports analyzed.
-	*/
-	totalExports: number;
-	/**
-	* Number of fully documented exports.
-	*/
-	documentedExports: number;
-	/**
-	* Breakdown of missing documentation by rule ID.
-	*/
-	missingByRule: Record<string, number>;
-	/**
-	* Total number of drift issues detected.
-	*/
-	driftCount: number;
-	/**
-	* Drift summary with category breakdown.
-	*/
-	driftSummary?: DriftReportSummary;
+interface CacheValidationResult {
+	/** Whether the cache is valid */
+	valid: boolean;
+	/** Reason for invalidation (if invalid) */
+	reason?: "cache-version-mismatch" | "entry-file-changed" | "config-changed" | "tsconfig-changed" | "package-json-changed" | "source-files-changed";
+	/** Files that changed (if reason is source-files-changed) */
+	changedFiles?: string[];
 }
 /**
-* Coverage data for a single export.
+* Context needed for cache operations.
 */
-interface ExportCoverageData {
-	/**
-	* Export name.
-	*/
-	name: string;
-	/**
-	* Export kind (function, class, etc.).
-	*/
-	kind: string;
-	/**
-	* Coverage score for this (0-100).
-	*/
-	coverageScore: number;
-	/**
-	* Missing documentation rule IDs.
-	*/
-	missing?: string[];
-	/**
-	* Drift issues for this export.
-	*/
-	drift?: SpecDocDrift[];
+interface CacheContext {
+	/** Entry file being analyzed (absolute path) */
+	entryFile: string;
+	/** Source files included in analysis (absolute paths) */
+	sourceFiles: string[];
+	/** Path to tsconfig.json (absolute, or null if not found) */
+	tsconfigPath: string | null;
+	/** Path to package.json (absolute) */
+	packageJsonPath: string;
+	/** Configuration that affects output */
+	config: SpecCacheConfig;
+	/** Working directory */
+	cwd: string;
 }
 /**
-* DocCov report - a persistable coverage analysis result.
+* Load cached spec from disk.
 *
-* This is the format saved to `.doccov/report.json` and returned
-* by the `check` command with `--format json`.
+* @param cwd - Working directory
+* @returns Cached spec, or null if not found or invalid JSON
 */
-interface DocCovReport {
-	/**
-	* JSON Schema reference for validation.
-	*/
-	$schema: string;
-	/**
-	* Report format version.
-	*/
-	version: string;
-	/**
-	* ISO 8601 timestamp when report was generated.
-	*/
-	generatedAt: string;
-	/**
-	* Package/project metadata.
-	*/
-	spec: {
-		name: string;
-		version?: string;
-	};
-	/**
-	* Aggregate coverage summary.
-	*/
-	coverage: CoverageSummary;
-	/**
-	* Per-coverage data, keyed by ID.
-	*/
-	exports: Record<string, ExportCoverageData>;
-}
+declare function loadSpecCache(cwd: string): SpecCache | null;
 /**
-* Generate a DocCov report from an OpenPkg spec.
-*
-* @param spec - The pure OpenPkg spec to analyze
-* @returns A DocCov report with coverage analysis
-*
-* @example
-* ```ts
-* import { DocCov, generateReport } from '@doccov/sdk';
-*
-* const doccov = new DocCov();
-* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
-* const report = generateReport(spec);
+* Save spec to cache.
 *
-* console.log(`Coverage: ${report.coverage.score}%`);
-* ```
+* @param spec - OpenPkg spec to cache
+* @param context - Cache context with file paths and config
 */
-declare function generateReport(spec: OpenPkg5): DocCovReport;
+declare function saveSpecCache(spec: OpenPkg5, context: CacheContext): void;
 /**
-* Generate a DocCov report from an already-enriched spec.
+* Validate if cached spec is still valid.
 *
-* Use this when you've already called enrichSpec() and want to avoid
-* recomputing coverage data.
+* Checks:
+* 1. Cache version matches
+* 2. Entry file matches
+* 3. Config matches
+* 4. tsconfig.json hash matches
+* 5. package.json hash matches
+* 6. All source file hashes match
 *
-* @param enriched - The enriched OpenPkg spec
-* @returns A DocCov report with coverage analysis
+* @param cache - Cached spec to validate
+* @param context - Current cache context
+* @returns Validation result
 */
-declare function generateReportFromEnriched(enriched: EnrichedOpenPkg): DocCovReport;
+declare function validateSpecCache(cache: SpecCache, context: CacheContext): CacheValidationResult;
 /**
-* Load a cached DocCov report from disk.
+* Clear the spec cache.
 *
-* @param reportPath - Path to the report file (defaults to .doccov/report.json)
-* @returns The cached report, or null if not found
+* @param cwd - Working directory
+* @returns True if cache was deleted, false if it didn't exist
 */
-declare function loadCachedReport(reportPath?: string): DocCovReport | null;
+declare function clearSpecCache(cwd: string): boolean;
 /**
-* Save a DocCov report to disk.
+* Get cache file path for a given working directory.
 *
-* @param report - The report to save
-* @param reportPath - Path to save the report (defaults to .doccov/report.json)
+* @param cwd - Working directory
+* @returns Absolute path to cache file
 */
-declare function saveReport(report: DocCovReport, reportPath?: string): void;
+declare function getSpecCachePath(cwd: string): string;
 /**
-* Generate a git-trackable API surface markdown file from an OpenPkg spec.
-*
-* This produces a deterministic, sorted output suitable for version control.
-* Changes to the API will show up as diffs in this file.
-*
-* @param spec - The OpenPkg spec to render
-* @returns Markdown string representing the API surface
-*
-* @example
-* ```ts
-* import { DocCov, renderApiSurface } from '@doccov/sdk';
-*
-* const doccov = new DocCov();
-* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
-* const apiSurface = renderApiSurface(spec);
-*
-* fs.writeFileSync('api-surface.md', apiSurface);
-* ```
+* Release stage/visibility tags that can be used for filtering.
+* Based on TSDoc release tags.
 */
-declare function renderApiSurface(spec: OpenPkg5): string;
+type ReleaseTag = "public" | "beta" | "alpha" | "internal";
+interface FilterOptions {
+	/** Include exports matching these patterns */
+	include?: string[];
+	/** Exclude exports matching these patterns */
+	exclude?: string[];
+	/** Filter by visibility/release stage (e.g., ['public', 'beta']) */
+	visibility?: ReleaseTag[];
+}
+interface Diagnostic2 {
+	message: string;
+	severity: "error" | "warning" | "info";
+	suggestion?: string;
+	location?: {
+		file: string;
+		line?: number;
+		column?: number;
+	};
+}
+interface AnalysisResult {
+	spec: OpenPkgSpec;
+	diagnostics: Diagnostic2[];
+	metadata: AnalysisMetadata;
+	/** True if result came from cache (no fresh analysis) */
+	fromCache?: boolean;
+	/** Cache validation details (if cache was checked) */
+	cacheStatus?: CacheValidationResult;
+}
+interface AnalysisMetadata {
+	baseDir: string;
+	configPath?: string;
+	packageJsonPath?: string;
+	hasNodeModules: boolean;
+	resolveExternalTypes: boolean;
+	/** Source files included in analysis (for caching) */
+	sourceFiles?: string[];
+}
+interface AnalyzeOptions {
+	filters?: FilterOptions;
+	/** Generation metadata input (entry point info, tool version, etc.) */
+	generationInput?: GenerationInput;
+}
+declare class DocCov {
+	private readonly options;
+	constructor(options?: DocCovOptions);
+	analyze(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeFile(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeProject(entryPath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeWithDiagnostics(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	analyzeFileWithDiagnostics(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	/**
+	* Try to load spec from cache.
+	* Returns null if cache is invalid or doesn't exist.
+	*/
+	private tryLoadFromCache;
+	/**
+	* Get current source files from a fresh TypeScript program.
+	* Used for cache validation to detect new files.
+	*/
+	private getCurrentSourceFiles;
+	/**
+	* Save analysis result to cache.
+	*/
+	private saveToCache;
+	/**
+	* Find tsconfig.json starting from a directory.
+	*/
+	private findTsConfig;
+	/**
+	* Find package.json starting from a directory.
+	*/
+	private findPackageJson;
+	/**
+	* Detect Standard Schema exports from compiled modules.
+	* Only runs when schemaExtraction is 'runtime' or 'hybrid'.
+	* Returns undefined if detection is disabled, fails, or no schemas found.
+	*/
+	private detectSchemas;
+	private normalizeDiagnostic;
+	private mapSeverity;
+	private normalizeMetadata;
+	private applySpecFilters;
+}
+declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
+declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 /**
 * Project detection types for I/O-agnostic project analysis.
 * Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
@@ -1043,59 +1043,6 @@ interface AnalyzeProjectOptions {
 	targetPackage?: string;
 }
 /**
-* Options for resolving a target package/entry point.
-*/
-interface ResolveTargetOptions {
-	/** Working directory (usually process.cwd()) */
-	cwd: string;
-	/** Target package name for monorepos */
-	package?: string;
-	/** Explicit entry point path (relative to cwd or package dir) */
-	entry?: string;
-}
-/**
-* Result of resolving a target package/entry point.
-*/
-interface ResolvedTarget {
-	/** Resolved directory containing the package */
-	targetDir: string;
-	/** Resolved entry point file path (absolute) */
-	entryFile: string;
-	/** Package info if this is a monorepo package */
-	packageInfo?: WorkspacePackage;
-	/** Entry point detection info */
-	entryPointInfo: EntryPointInfo;
-}
-/**
-* Resolve a target package and entry point.
-*
-* This consolidates the repeated pattern from CLI commands:
-* 1. If --package specified, detect monorepo and find the package
-* 2. If no entry specified, auto-detect entry point
-* 3. If entry is a directory, detect entry point within it
-*
-* @param fs - FileSystem implementation (NodeFileSystem or SandboxFileSystem)
-* @param options - Resolution options
-* @returns Resolved target info
-* @throws Error if monorepo package not found, or entry point detection fails
-*
-* @example
-* ```typescript
-* import { NodeFileSystem, resolveTarget } from '@doccov/sdk';
-*
-* // Simple usage
-* const fs = new NodeFileSystem(process.cwd());
-* const { targetDir, entryFile } = await resolveTarget(fs, { cwd: process.cwd() });
-*
-* // With monorepo package
-* const { targetDir, entryFile, packageInfo } = await resolveTarget(fs, {
-*   cwd: process.cwd(),
-*   package: '@myorg/core',
-* });
-* ```
-*/
-declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
-/**
 * Detect build configuration and exotic project indicators.
 *
 * @param fs - FileSystem implementation
@@ -1257,6 +1204,59 @@ declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJs
 */
 declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
 /**
+* Options for resolving a target package/entry point.
+*/
+interface ResolveTargetOptions {
+	/** Working directory (usually process.cwd()) */
+	cwd: string;
+	/** Target package name for monorepos */
+	package?: string;
+	/** Explicit entry point path (relative to cwd or package dir) */
+	entry?: string;
+}
+/**
+* Result of resolving a target package/entry point.
+*/
+interface ResolvedTarget {
+	/** Resolved directory containing the package */
+	targetDir: string;
+	/** Resolved entry point file path (absolute) */
+	entryFile: string;
+	/** Package info if this is a monorepo package */
+	packageInfo?: WorkspacePackage;
+	/** Entry point detection info */
+	entryPointInfo: EntryPointInfo;
+}
+/**
+* Resolve a target package and entry point.
+*
+* This consolidates the repeated pattern from CLI commands:
+* 1. If --package specified, detect monorepo and find the package
+* 2. If no entry specified, auto-detect entry point
+* 3. If entry is a directory, detect entry point within it
+*
+* @param fs - FileSystem implementation (NodeFileSystem or SandboxFileSystem)
+* @param options - Resolution options
+* @returns Resolved target info
+* @throws Error if monorepo package not found, or entry point detection fails
+*
+* @example
+* ```typescript
+* import { NodeFileSystem, resolveTarget } from '@doccov/sdk';
+*
+* // Simple usage
+* const fs = new NodeFileSystem(process.cwd());
+* const { targetDir, entryFile } = await resolveTarget(fs, { cwd: process.cwd() });
+*
+* // With monorepo package
+* const { targetDir, entryFile, packageInfo } = await resolveTarget(fs, {
+*   cwd: process.cwd(),
+*   package: '@myorg/core',
+* });
+* ```
+*/
+declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
+/**
 * Example validation types and utilities.
 */
 /**
@@ -1981,6 +1981,21 @@ declare function getExtendedTrend(spec: OpenPkg8, cwd: string, options?: {
 	branch?: string;
 	tier?: RetentionTier;
 }): ExtendedTrendAnalysis;
+interface SchemaDetectionContext {
+	baseDir: string;
+	entryFile: string;
+}
+interface DetectedSchema {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
+interface SchemaDetectionResult {
+	schemas: Map<string, DetectedSchema>;
+	errors: string[];
+	/** Warning when runtime was requested but compiled JS not found */
+	noCompiledJsWarning?: boolean;
+}
+declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
 import * as TS3 from "typescript";
 /**
 * A schema adapter can detect and extract output types from a specific
@@ -2120,21 +2135,60 @@ declare function extractStandardSchemas(compiledJsPath: string, options?: Extrac
 */
 declare function extractStandardSchemasFromProject(entryFile: string, baseDir: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
 declare function extractPackageSpec(entryFile: string, packageDir?: string, content?: string, options?: DocCovOptions): Promise<OpenPkgSpec>;
-interface SchemaDetectionContext {
-	baseDir: string;
-	entryFile: string;
-}
-interface DetectedSchema {
-	schema: Record<string, unknown>;
-	vendor: string;
-}
-interface SchemaDetectionResult {
-	schemas: Map<string, DetectedSchema>;
-	errors: string[];
-	/** Warning when runtime was requested but compiled JS not found */
-	noCompiledJsWarning?: boolean;
+/**
+* Source of filter options.
+*/
+type FilterSource = "config" | "override" | "combined";
+/**
+* Resolved filter options after merging config and overrides.
+*/
+interface ResolvedFilters {
+	/** Include patterns */
+	include?: string[];
+	/** Exclude patterns */
+	exclude?: string[];
+	/** Source of the filters */
+	source?: FilterSource;
+	/** Whether filters were applied from config */
+	fromConfig: boolean;
+	/** Whether filters were applied from overrides */
+	fromOverride: boolean;
 }
-declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
+/**
+* Parse a comma-separated list flag into an array.
+*
+* @param value - String or string array from CLI flag
+* @returns Parsed array, or undefined if empty
+*
+* @example
+* ```typescript
+* parseListFlag('a,b,c'); // ['a', 'b', 'c']
+* parseListFlag(['a,b', 'c']); // ['a', 'b', 'c']
+* parseListFlag(undefined); // undefined
+* ```
+*/
+declare function parseListFlag(value?: string | string[]): string[] | undefined;
+/**
+* Merge filter options from config and CLI/API overrides.
+*
+* Merge behavior:
+* - Include: CLI values intersect with config values (narrowing)
+* - Exclude: CLI values are added to config values (expanding)
+*
+* @param config - Configuration (from doccov.config.ts)
+* @param overrides - Override filters (from CLI flags or API params)
+* @returns Merged filter options
+*
+* @example
+* ```typescript
+* const config = { include: ['A', 'B', 'C'] };
+* const overrides = { include: ['B', 'C', 'D'] };
+*
+* const resolved = mergeFilters(config, overrides);
+* // resolved.include = ['B', 'C'] (intersection)
+* ```
+*/
+declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
 import { OpenPkg as OpenPkg9 } from "@openpkg-ts/spec";
 /**
 * Parsed components of a GitHub URL.
@@ -2352,60 +2406,6 @@ declare function installDependencies(fs: FileSystem, cwd: string, runCommand: Co
 */
 declare function createNodeCommandRunner(): CommandRunner;
 /**
-* Source of filter options.
-*/
-type FilterSource = "config" | "override" | "combined";
-/**
-* Resolved filter options after merging config and overrides.
-*/
-interface ResolvedFilters {
-	/** Include patterns */
-	include?: string[];
-	/** Exclude patterns */
-	exclude?: string[];
-	/** Source of the filters */
-	source?: FilterSource;
-	/** Whether filters were applied from config */
-	fromConfig: boolean;
-	/** Whether filters were applied from overrides */
-	fromOverride: boolean;
-}
-/**
-* Parse a comma-separated list flag into an array.
-*
-* @param value - String or string array from CLI flag
-* @returns Parsed array, or undefined if empty
-*
-* @example
-* ```typescript
-* parseListFlag('a,b,c'); // ['a', 'b', 'c']
-* parseListFlag(['a,b', 'c']); // ['a', 'b', 'c']
-* parseListFlag(undefined); // undefined
-* ```
-*/
-declare function parseListFlag(value?: string | string[]): string[] | undefined;
-/**
-* Merge filter options from config and CLI/API overrides.
-*
-* Merge behavior:
-* - Include: CLI values intersect with config values (narrowing)
-* - Exclude: CLI values are added to config values (expanding)
-*
-* @param config - Configuration (from doccov.config.ts)
-* @param overrides - Override filters (from CLI flags or API params)
-* @returns Merged filter options
-*
-* @example
-* ```typescript
-* const config = { include: ['A', 'B', 'C'] };
-* const overrides = { include: ['B', 'C', 'D'] };
-*
-* const resolved = mergeFilters(config, overrides);
-* // resolved.include = ['B', 'C'] (intersection)
-* ```
-*/
-declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
-/**
 * Repository metadata from GitHub API.
 */
 interface GitHubRepoMetadata {