@doccov/sdk 0.22.1 → 0.23.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { EntryPointDetectionMethod } from "@openpkg-ts/spec";
 /**
 * Configuration types for DocCov.
 * These types are shared between CLI and API.
@@ -114,209 +115,261 @@ interface DetectedSchemaEntry {
 	schema: Record<string, unknown>;
 	vendor: string;
 }
-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>;
-declare function clearSchemaCache(): void;
-import * as TS from "typescript";
-/**
-* A schema adapter can detect and extract output types from a specific
-* schema validation library.
-*/
-interface SchemaAdapter {
-	/** Unique identifier for this adapter */
-	readonly id: string;
-	/** npm package name(s) this adapter handles */
-	readonly packages: readonly string[];
-	/**
-	* Check if a type matches this adapter's schema library.
-	* Should be fast - called for every export.
-	*/
-	matches(type: TS.Type, checker: TS.TypeChecker): boolean;
-	/**
-	* Extract the output type from a schema type.
-	* Returns null if extraction fails.
-	*/
-	extractOutputType(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
-	/**
-	* Extract the input type from a schema type (optional).
-	* Useful for transforms where input differs from output.
-	*/
-	extractInputType?(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
-}
+import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+type OpenPkgSpec = OpenPkg2;
 /**
-* Result of schema type extraction
+* Input for generation metadata that comes from the caller (CLI, API, etc.)
 */
-interface SchemaExtractionResult {
-	/** The adapter that matched */
-	adapter: SchemaAdapter;
-	/** The extracted output type */
-	outputType: TS.Type;
-	/** The extracted input type (if different from output) */
-	inputType?: TS.Type;
+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;
 }
-import * as TS2 from "typescript";
-/**
-* Find an adapter that matches the given type.
-* Returns null if no adapter matches.
-*/
-declare function findAdapter(type: TS2.Type, checker: TS2.TypeChecker): SchemaAdapter | null;
-/**
-* Check if a type is from a recognized schema library.
-*/
-declare function isSchemaType(type: TS2.Type, checker: TS2.TypeChecker): boolean;
 /**
-* Extract the output type from a schema type.
-* Returns null if:
-* - The type is not from a recognized schema library
-* - The adapter fails to extract the output type
+* 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 function extractSchemaOutputType(type: TS2.Type, checker: TS2.TypeChecker): TS2.Type | null;
+declare function hashFile(filePath: string): string | null;
 /**
-* Full extraction with adapter info.
-* Useful when you need to know which library was detected.
+* Hash a string value.
+*
+* @param content - String to hash
+* @returns 16-character hex hash
 */
-declare function extractSchemaType(type: TS2.Type, checker: TS2.TypeChecker): SchemaExtractionResult | null;
+declare function hashString(content: string): string;
 /**
-* Get all registered adapters.
-* Useful for logging/debugging.
+* Hash multiple files and return a map of relative paths to hashes.
+*
+* @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 getRegisteredAdapters(): readonly SchemaAdapter[];
+declare function hashFiles(filePaths: string[], cwd: string): Record<string, string>;
 /**
-* Get supported library names.
-* Useful for documentation/help output.
+* Compare two hash maps and return changed files.
+*
+* @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 getSupportedLibraries(): readonly string[];
+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";
 /**
-* Standard JSON Schema v1 interface (minimal for detection).
+* Configuration that affects spec generation output.
 */
-interface StandardJSONSchemaV1 {
-	"~standard": {
-		version: number;
-		vendor: string;
-		jsonSchema?: {
-			output: (target?: string) => Record<string, unknown>;
-			input?: (target?: string) => Record<string, unknown>;
-		};
-	};
+interface SpecCacheConfig {
+	resolveExternalTypes: boolean;
 }
 /**
-* Result of extracting Standard Schema from an export.
+* Cached spec with validation metadata.
 */
-interface StandardSchemaExtractionResult {
-	exportName: string;
-	vendor: string;
-	outputSchema: Record<string, unknown>;
-	inputSchema?: Record<string, unknown>;
+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: OpenPkg3;
 }
 /**
-* Options for runtime Standard Schema extraction.
+* Result of cache validation.
 */
-interface ExtractStandardSchemasOptions {
-	/** Timeout in milliseconds (default: 10000) */
-	timeout?: number;
-	/** JSON Schema target version (default: 'draft-2020-12') */
-	target?: "draft-2020-12" | "draft-07" | "openapi-3.0";
+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[];
 }
 /**
-* Result of Standard Schema extraction.
+* Context needed for cache operations.
 */
-interface StandardSchemaExtractionOutput {
-	schemas: Map<string, StandardSchemaExtractionResult>;
-	errors: string[];
+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;
 }
 /**
-* Check if an object implements StandardJSONSchemaV1.
-* This is a static type guard - doesn't require runtime.
+* Load cached spec from disk.
+*
+* @param cwd - Working directory
+* @returns Cached spec, or null if not found or invalid JSON
 */
-declare function isStandardJSONSchema(obj: unknown): obj is StandardJSONSchemaV1;
+declare function loadSpecCache(cwd: string): SpecCache | null;
 /**
-* Resolve compiled JS path from TypeScript source.
-* Tries common output locations: dist/, build/, lib/, same dir.
+* Save spec to cache.
+*
+* @param spec - OpenPkg spec to cache
+* @param context - Cache context with file paths and config
 */
-declare function resolveCompiledPath(tsPath: string, baseDir: string): string | null;
+declare function saveSpecCache(spec: OpenPkg3, context: CacheContext): void;
 /**
-* Extract Standard Schema JSON Schemas from a compiled JS module.
+* Validate if cached spec is still valid.
 *
-* **Security Note**: This executes the module in a subprocess.
-* Only use with trusted code (user's own packages).
+* 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 compiledJsPath - Path to compiled .js file
-* @param options - Extraction options
-* @returns Extraction results with schemas and any errors
+* @param cache - Cached spec to validate
+* @param context - Current cache context
+* @returns Validation result
 */
-declare function extractStandardSchemas(compiledJsPath: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
+declare function validateSpecCache(cache: SpecCache, context: CacheContext): CacheValidationResult;
 /**
-* Extract Standard Schema from a TypeScript project.
+* Clear the spec cache.
 *
-* Convenience function that resolves compiled JS and extracts schemas.
+* @param cwd - Working directory
+* @returns True if cache was deleted, false if it didn't exist
+*/
+declare function clearSpecCache(cwd: string): boolean;
+/**
+* Get cache file path for a given working directory.
 *
-* @param entryFile - TypeScript entry file path
-* @param baseDir - Project base directory
-* @param options - Extraction options
+* @param cwd - Working directory
+* @returns Absolute path to cache file
 */
-declare function extractStandardSchemasFromProject(entryFile: string, baseDir: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
-import { DriftCategory, SpecDocDrift, SpecExport } from "@openpkg-ts/spec";
-interface ExampleRunResult {
-	success: boolean;
-	stdout: string;
-	stderr: string;
-	exitCode: number;
-	duration: number;
+declare function getSpecCachePath(cwd: string): string;
+/**
+* Release stage/visibility tags that can be used for filtering.
+* Based on TSDoc release tags.
+*/
+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 RunExampleOptions {
-	/** Timeout in milliseconds (default: 5000) */
-	timeout?: number;
-	/** Working directory for execution */
-	cwd?: string;
+interface Diagnostic2 {
+	message: string;
+	severity: "error" | "warning" | "info";
+	suggestion?: string;
+	location?: {
+		file: string;
+		line?: number;
+		column?: number;
+	};
 }
-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 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 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;
+interface AnalysisMetadata {
+	baseDir: string;
+	configPath?: string;
+	packageJsonPath?: string;
+	hasNodeModules: boolean;
+	resolveExternalTypes: boolean;
+	/** Source files included in analysis (for caching) */
+	sourceFiles?: string[];
 }
-/**
-* 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>;
-import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
-type OpenPkgSpec = OpenPkg2;
+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>;
+import { OpenPkg as OpenPkg4, SpecDocDrift as SpecDocDrift8, SpecDocsMetadata, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
+import { DriftCategory as DriftCategory2, SpecDocDrift as SpecDocDrift2 } from "@openpkg-ts/spec";
+import { DriftCategory, SpecDocDrift } from "@openpkg-ts/spec";
 /**
 * Result of computing drift for a single export.
 */
@@ -350,46 +403,6 @@ interface ExportRegistry {
 	all: Set<string>;
 }
 /**
-* Build a registry of all export/type names for cross-reference validation.
-*/
-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;
-/**
-* 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
-*/
-declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
-/**
-* Detect runtime errors in @example blocks.
-* Results are provided externally after running examples via runExamples().
-*/
-declare function detectExampleRuntimeErrors(entry: SpecExport, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
-/**
-* Parse assertion comments from example code.
-* Matches: // => expected_value
-*/
-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.
-*/
-declare function hasNonAssertionComments(code: string): boolean;
-/**
-* Detect assertion failures by comparing stdout to expected values.
-*/
-declare function detectExampleAssertionFailures(entry: SpecExport, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
-/**
 * Extended drift with category and fixability metadata.
 */
 interface CategorizedDrift extends SpecDocDrift {
@@ -397,6 +410,14 @@ interface CategorizedDrift extends SpecDocDrift {
 	fixable: boolean;
 }
 /**
+* Summary of drift issues by category.
+*/
+interface DriftSummary {
+	total: number;
+	byCategory: Record<DriftCategory, number>;
+	fixable: number;
+}
+/**
 * Categorize a single drift issue.
 *
 * @param drift - The drift to categorize
@@ -414,7 +435,7 @@ interface CategorizedDrift extends SpecDocDrift {
 * console.log(categorized.fixable);  // => true
 * ```
 */
-declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
+declare function categorizeDrift(drift: SpecDocDrift2): CategorizedDrift;
 /**
 * Group drifts by category.
 *
@@ -429,15 +450,7 @@ declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
 * console.log(grouped.example.length);    // Number of example issues
 * ```
 */
-declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
-/**
-* Summary of drift issues by category.
-*/
-interface DriftSummary {
-	total: number;
-	byCategory: Record<DriftCategory, number>;
-	fixable: number;
-}
+declare function groupDriftsByCategory(drifts: SpecDocDrift2[]): Record<DriftCategory2, CategorizedDrift[]>;
 /**
 * Get drift summary counts by category.
 *
@@ -451,7 +464,7 @@ interface DriftSummary {
 * // => "5 issues: 3 fixable"
 * ```
 */
-declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
+declare function getDriftSummary(drifts: SpecDocDrift2[]): DriftSummary;
 /**
 * Format drift summary for CLI output (single line).
 *
@@ -466,6 +479,25 @@ declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 * ```
 */
 declare function formatDriftSummaryLine(summary: DriftSummary): string;
+import { SpecDocDrift as SpecDocDrift3, SpecExport } from "@openpkg-ts/spec";
+/**
+* Build a registry of all export/type names for cross-reference validation.
+*/
+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;
+/**
+* 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
+*/
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift3[];
 /**
 * Calculate aggregate coverage score from a spec's exports.
 *
@@ -514,12 +546,80 @@ declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
 		coverageScore: number;
 	};
 };
-import { OpenPkg as OpenPkg3, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+import { SpecDocDrift as SpecDocDrift4, 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>): SpecDocDrift4[];
+/**
+* Parse assertion comments from example code.
+* Matches: // => expected_value
+*/
+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.
+*/
+declare function hasNonAssertionComments(code: string): boolean;
+/**
+* Detect assertion failures by comparing stdout to expected values.
+*/
+declare function detectExampleAssertionFailures(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift4[];
 /**
 * An enriched with computed documentation metadata.
 * Extends SpecExport with the `docs` field for coverage analysis.
 */
-type EnrichedExport = SpecExport2 & {
+type EnrichedExport = SpecExport7 & {
 	docs?: EnrichedDocsMetadata;
 };
 /**
@@ -530,7 +630,7 @@ type EnrichedDocsMetadata = SpecDocsMetadata;
 * An enriched OpenPkg spec with computed documentation metadata.
 * Extends OpenPkg with per-and aggregate coverage data.
 */
-type EnrichedOpenPkg = Omit<OpenPkg3, "exports"> & {
+type EnrichedOpenPkg = Omit<OpenPkg4, "exports"> & {
 	exports: EnrichedExport[];
 	docs?: EnrichedDocsMetadata;
 	/** Drift summary with category breakdown (if drift exists) */
@@ -541,7 +641,7 @@ interface EnrichOptions {
 	* Per-drift issues to include in enrichment.
 	* Map from ID to drift issues.
 	*/
-	driftByExport?: Map<string, SpecDocDrift2[]>;
+	driftByExport?: Map<string, SpecDocDrift8[]>;
 }
 /**
 * Enrich an OpenPkg spec with documentation coverage metadata.
@@ -563,9 +663,9 @@ interface EnrichOptions {
 * console.log(enriched.docs?.coverageScore); // e.g., 85
 * ```
 */
-declare function enrichSpec(spec: OpenPkg3, options?: EnrichOptions): EnrichedOpenPkg;
-import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
-import { DriftCategory as DriftCategory2, SpecDocDrift as SpecDocDrift3 } from "@openpkg-ts/spec";
+declare function enrichSpec(spec: OpenPkg4, options?: EnrichOptions): EnrichedOpenPkg;
+import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
+import { DriftCategory as DriftCategory3, SpecDocDrift as SpecDocDrift9 } from "@openpkg-ts/spec";
 /**
 * DocCov report schema version.
 */
@@ -625,7 +725,7 @@ interface DriftReportSummary {
 	/**
 	* Count of issues per category.
 	*/
-	byCategory: Record<DriftCategory2, number>;
+	byCategory: Record<DriftCategory3, number>;
 	/**
 	* Number of auto-fixable issues.
 	*/
@@ -647,7 +747,7 @@ interface DriftReport {
 	/**
 	* Issues grouped by category.
 	*/
-	byCategory: Record<DriftCategory2, CategorizedDrift[]>;
+	byCategory: Record<DriftCategory3, CategorizedDrift[]>;
 	/**
 	* Flat list of all drift issues (backward compatible).
 	*/
@@ -705,7 +805,7 @@ interface ExportCoverageData {
 	/**
 	* Drift issues for this export.
 	*/
-	drift?: SpecDocDrift3[];
+	drift?: SpecDocDrift9[];
 }
 /**
 * DocCov report - a persistable coverage analysis result.
@@ -759,7 +859,7 @@ interface DocCovReport {
 * console.log(`Coverage: ${report.coverage.score}%`);
 * ```
 */
-declare function generateReport(spec: OpenPkg4): DocCovReport;
+declare function generateReport(spec: OpenPkg5): DocCovReport;
 /**
 * Generate a DocCov report from an already-enriched spec.
 *
@@ -785,365 +885,8 @@ declare function loadCachedReport(reportPath?: string): DocCovReport | null;
 */
 declare function saveReport(report: DocCovReport, reportPath?: string): void;
 /**
-* Check if a cached report is still valid.
-*
-* A report is considered stale if:
-* - It doesn't exist
-* - The spec version has changed
-* - Source files have been modified since generation
-*
-* @param reportPath - Path to the report file
-* @param sourceFiles - Source files to check modification times against
-* @returns True if the cached report is still valid
-*/
-declare function isCachedReportValid(reportPath?: string, sourceFiles?: string[]): boolean;
-/**
-* 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);
-* ```
-*/
-declare function renderApiSurface(spec: OpenPkg4): string;
-import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
-/** Directory for storing history snapshots */
-declare const HISTORY_DIR = ".doccov/history";
-/**
-* A historical coverage snapshot.
-*/
-interface CoverageSnapshot {
-	/** ISO 8601 timestamp */
-	timestamp: string;
-	/** Package name */
-	package: string;
-	/** Package version (if available) */
-	version?: string;
-	/** Coverage score (0-100) */
-	coverageScore: number;
-	/** Total number of exports */
-	totalExports: number;
-	/** Number of documented exports */
-	documentedExports: number;
-	/** Number of drift issues */
-	driftCount: number;
-	/** Git commit hash (if available) */
-	commit?: string;
-	/** Git branch (if available) */
-	branch?: string;
-}
-/**
-* Coverage trend data.
-*/
-interface CoverageTrend {
-	/** Current snapshot */
-	current: CoverageSnapshot;
-	/** Previous snapshots (most recent first) */
-	history: CoverageSnapshot[];
-	/** Score delta from previous */
-	delta?: number;
-	/** Sparkline data (last N scores) */
-	sparkline: number[];
-}
-/**
-* Tier-based retention settings.
-*/
-type RetentionTier = "free" | "team" | "pro";
-/**
-* Retention days per tier.
-*/
-declare const RETENTION_DAYS: Record<RetentionTier, number>;
-/**
-* Weekly summary of coverage data.
-*/
-interface WeeklySummary {
-	/** Week start date (ISO string) */
-	weekStart: string;
-	/** Week end date (ISO string) */
-	weekEnd: string;
-	/** Average coverage for the week */
-	avgCoverage: number;
-	/** Coverage at start of week */
-	startCoverage: number;
-	/** Coverage at end of week */
-	endCoverage: number;
-	/** Change during the week */
-	delta: number;
-	/** Number of snapshots in the week */
-	snapshotCount: number;
-}
-/**
-* Extended trend analysis result.
-*/
-interface ExtendedTrendAnalysis {
-	/** Current trend data */
-	trend: CoverageTrend;
-	/** Weekly summaries (most recent first) */
-	weeklySummaries: WeeklySummary[];
-	/** 7-day velocity (average daily change) */
-	velocity7d: number;
-	/** 30-day velocity */
-	velocity30d: number;
-	/** 90-day velocity (Pro only) */
-	velocity90d?: number;
-	/** Projected coverage in 30 days (based on velocity) */
-	projected30d: number;
-	/** Best coverage ever recorded */
-	allTimeHigh: number;
-	/** Worst coverage ever recorded */
-	allTimeLow: number;
-	/** Date range of available data */
-	dataRange: {
-		start: string;
-		end: string;
-	} | null;
-}
-/**
-* Compute a coverage snapshot from an OpenPkg spec.
-*/
-declare function computeSnapshot(spec: OpenPkg5, options?: {
-	commit?: string;
-	branch?: string;
-}): CoverageSnapshot;
-/**
-* Save a coverage snapshot to history.
-*
-* @param snapshot - The snapshot to save
-* @param cwd - Working directory
-*/
-declare function saveSnapshot(snapshot: CoverageSnapshot, cwd: string): void;
-/**
-* Load all historical snapshots.
-*
-* @param cwd - Working directory
-* @returns Array of snapshots sorted by timestamp (most recent first)
-*/
-declare function loadSnapshots(cwd: string): CoverageSnapshot[];
-/**
-* Get coverage trend data.
-*
-* @param spec - Current OpenPkg spec
-* @param cwd - Working directory
-* @param options - Optional git metadata
-* @returns Trend data with history and delta
-*/
-declare function getTrend(spec: OpenPkg5, cwd: string, options?: {
-	commit?: string;
-	branch?: string;
-}): CoverageTrend;
-/**
-* Generate a sparkline character representation.
-*
-* @param values - Array of values (0-100 for coverage)
-* @returns Sparkline string using unicode characters
-*/
-declare function renderSparkline(values: number[]): string;
-/**
-* Format a delta value with arrow and color indicator.
-*
-* @param delta - Coverage delta (positive = improvement)
-* @returns Formatted delta string
-*/
-declare function formatDelta(delta: number): string;
-/**
-* Prune old snapshots to keep history manageable.
-*
-* @param cwd - Working directory
-* @param keepCount - Number of snapshots to keep (default: 100)
-* @returns Number of snapshots deleted
-*/
-declare function pruneHistory(cwd: string, keepCount?: number): number;
-/**
-* Prune snapshots based on tier retention policy.
-*
-* @param cwd - Working directory
-* @param tier - Retention tier (free: 7d, team: 30d, pro: 90d)
-* @returns Number of snapshots deleted
-*/
-declare function pruneByTier(cwd: string, tier: RetentionTier): number;
-/**
-* Load snapshots within a date range.
-*
-* @param cwd - Working directory
-* @param days - Number of days to include
-* @returns Filtered snapshots
-*/
-declare function loadSnapshotsForDays(cwd: string, days: number): CoverageSnapshot[];
-/**
-* Generate weekly summaries from snapshots.
-*
-* @param snapshots - Snapshots to summarize (most recent first)
-* @returns Weekly summaries (most recent first)
-*/
-declare function generateWeeklySummaries(snapshots: CoverageSnapshot[]): WeeklySummary[];
-/**
-* Get extended trend analysis with velocity and projections.
-*
-* @param spec - Current OpenPkg spec
-* @param cwd - Working directory
-* @param options - Analysis options
-* @returns Extended trend analysis
-*/
-declare function getExtendedTrend(spec: OpenPkg5, cwd: string, options?: {
-	commit?: string;
-	branch?: string;
-	tier?: RetentionTier;
-}): ExtendedTrendAnalysis;
-/**
-* 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 function hashFile(filePath: string): string | null;
-/**
-* Hash a string value.
-*
-* @param content - String to hash
-* @returns 16-character hex hash
-*/
-declare function hashString(content: string): string;
-/**
-* Hash multiple files and return a map of relative paths to hashes.
-*
-* @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 hashFiles(filePaths: string[], cwd: string): Record<string, string>;
-/**
-* Compare two hash maps and return changed files.
-*
-* @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 diffHashes(cached: Record<string, string>, current: Record<string, string>): string[];
-import { OpenPkg as OpenPkg6 } 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";
-/**
-* Configuration that affects spec generation output.
-*/
-interface SpecCacheConfig {
-	resolveExternalTypes: boolean;
-}
-/**
-* Cached spec with validation metadata.
-*/
-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: OpenPkg6;
-}
-/**
-* Result of cache validation.
-*/
-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[];
-}
-/**
-* Context needed for cache operations.
-*/
-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;
-}
-/**
-* Load cached spec from disk.
-*
-* @param cwd - Working directory
-* @returns Cached spec, or null if not found or invalid JSON
-*/
-declare function loadSpecCache(cwd: string): SpecCache | null;
-/**
-* Save spec to cache.
-*
-* @param spec - OpenPkg spec to cache
-* @param context - Cache context with file paths and config
-*/
-declare function saveSpecCache(spec: OpenPkg6, context: CacheContext): void;
-/**
-* 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
-*/
-declare function validateSpecCache(cache: SpecCache, context: CacheContext): CacheValidationResult;
-/**
-* Clear the spec cache.
-*
-* @param cwd - Working directory
-* @returns True if cache was deleted, false if it didn't exist
-*/
-declare function clearSpecCache(cwd: string): boolean;
-/**
-* Get cache file path for a given working directory.
-*
-* @param cwd - Working directory
-* @returns Absolute path to cache file
-*/
-declare function getSpecCachePath(cwd: string): string;
-/**
-* Project detection types for I/O-agnostic project analysis.
-* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
+* Project detection types for I/O-agnostic project analysis.
+* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
 */
 /**
 * Minimal filesystem interface for I/O-agnostic detection.
@@ -1238,6 +981,59 @@ 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
@@ -1430,7 +1226,7 @@ declare function parseExamplesFlag(value: boolean | string | undefined): Example
 * Check if a specific validation is enabled.
 */
 declare function shouldValidate(validations: ExampleValidation[], check: ExampleValidation): boolean;
-import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport8 } from "@openpkg-ts/spec";
 interface ExampleTypeError {
 	/** Index of the example in the examples array */
 	exampleIndex: number;
@@ -1527,103 +1323,35 @@ interface RunValidationResult {
 	passed: number;
 	failed: number;
 	drifts: RuntimeDrift[];
-	installSuccess: boolean;
-	installError?: string;
-}
-/**
-* Unified result from example validation.
-*/
-interface ExampleValidationResult {
-	/** Which validations were run */
-	validations: ExampleValidation[];
-	/** Presence validation results (if run) */
-	presence?: PresenceResult;
-	/** Typecheck validation results (if run) */
-	typecheck?: TypecheckValidationResult;
-	/** Runtime validation results (if run) */
-	run?: RunValidationResult;
-	/** Total number of issues found */
-	totalIssues: number;
-}
-/**
-* Validate examples across exports.
-*
-* Runs only the validations specified. Each validation is independent:
-* - `presence`: checks examples exist (doesn't require typecheck or run)
-* - `typecheck`: type-checks examples (doesn't require presence or run)
-* - `run`: executes examples (doesn't require presence or typecheck)
-*/
-declare function validateExamples(exports: SpecExport3[], options: ExampleValidationOptions): Promise<ExampleValidationResult>;
-declare function extractPackageSpec(entryFile: string, packageDir?: string, content?: string, options?: DocCovOptions): Promise<OpenPkgSpec>;
-/**
-* Release stage/visibility tags that can be used for filtering.
-* Based on TSDoc release tags.
-*/
-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[];
-}
-/**
-* 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
-* ```
+	installSuccess: boolean;
+	installError?: string;
+}
+/**
+* Unified result from example validation.
 */
-declare function parseListFlag(value?: string | string[]): string[] | undefined;
+interface ExampleValidationResult {
+	/** Which validations were run */
+	validations: ExampleValidation[];
+	/** Presence validation results (if run) */
+	presence?: PresenceResult;
+	/** Typecheck validation results (if run) */
+	typecheck?: TypecheckValidationResult;
+	/** Runtime validation results (if run) */
+	run?: RunValidationResult;
+	/** Total number of issues found */
+	totalIssues: number;
+}
 /**
-* 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'] };
+* Validate examples across exports.
 *
-* const resolved = mergeFilters(config, overrides);
-* // resolved.include = ['B', 'C'] (intersection)
-* ```
+* Runs only the validations specified. Each validation is independent:
+* - `presence`: checks examples exist (doesn't require typecheck or run)
+* - `typecheck`: type-checks examples (doesn't require presence or run)
+* - `run`: executes examples (doesn't require presence or typecheck)
 */
-declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
-import { SpecDocDrift as SpecDocDrift4, SpecExport as SpecExport4 } from "@openpkg-ts/spec";
-import * as TS3 from "typescript";
+declare function validateExamples(exports: SpecExport8[], options: ExampleValidationOptions): Promise<ExampleValidationResult>;
+import { SpecDocDrift as SpecDocDrift10, SpecExport as SpecExport9 } from "@openpkg-ts/spec";
+import * as TS2 from "typescript";
 /**
 * Represents a single parameter in a JSDoc patch
 */
@@ -1704,7 +1432,7 @@ declare function serializeJSDoc(patch: JSDocPatch, indent?: string): string;
 /**
 * Find the JSDoc location for a declaration in a source file
 */
-declare function findJSDocLocation(sourceFile: TS3.SourceFile, symbolName: string, approximateLine?: number): {
+declare function findJSDocLocation(sourceFile: TS2.SourceFile, symbolName: string, approximateLine?: number): {
 	startLine: number;
 	endLine: number;
 	declarationLine: number;
@@ -1719,7 +1447,7 @@ declare function applyEdits(edits: JSDocEdit[]): Promise<ApplyEditsResult>;
 /**
 * Create a TypeScript source file from a file path
 */
-declare function createSourceFile(filePath: string): TS3.SourceFile;
+declare function createSourceFile(filePath: string): TS2.SourceFile;
 /**
 * Types of fixes that can be generated
 */
@@ -1727,661 +1455,886 @@ type FixType = "add-param" | "remove-param" | "update-param-type" | "update-para
 /**
 * A fix suggestion with the patch to apply
 */
-interface FixSuggestion {
-	type: FixType;
-	driftType: SpecDocDrift4["type"];
-	target: string;
-	description: string;
-	patch: Partial<JSDocPatch>;
-}
+interface FixSuggestion {
+	type: FixType;
+	driftType: SpecDocDrift10["type"];
+	target: string;
+	description: string;
+	patch: Partial<JSDocPatch>;
+}
+/**
+* Check if a drift type can be fixed deterministically
+*/
+declare function isFixableDrift(drift: SpecDocDrift10): boolean;
+/**
+* Generate a fix for a single drift issue
+*/
+declare function generateFix(drift: SpecDocDrift10, exportEntry: SpecExport9, existingPatch?: JSDocPatch): FixSuggestion | null;
+/**
+* Generate all fixes for an export's drift issues
+*/
+declare function generateFixesForExport(exportEntry: SpecExport9, existingPatch?: JSDocPatch): FixSuggestion[];
+/**
+* Merge multiple fix patches into a single patch
+*/
+declare function mergeFixes(fixes: FixSuggestion[], basePatch?: JSDocPatch): JSDocPatch;
+/**
+* Get a summary of fixable vs non-fixable drifts
+*/
+declare function categorizeDrifts(drifts: SpecDocDrift10[]): {
+	fixable: SpecDocDrift10[];
+	nonFixable: SpecDocDrift10[];
+};
+import { SpecDiff } from "@openpkg-ts/spec";
+type MemberChangeType = "added" | "removed" | "signature-changed";
+interface MemberChange {
+	/** The class this member belongs to */
+	className: string;
+	/** The member name (e.g., "evaluateChainhook") */
+	memberName: string;
+	/** Kind of member */
+	memberKind: "method" | "property" | "accessor" | "constructor";
+	/** Type of change */
+	changeType: MemberChangeType;
+	/** Old signature string (for signature changes) */
+	oldSignature?: string;
+	/** New signature string (for signature changes) */
+	newSignature?: string;
+	/** Suggested replacement (e.g., "Use replayChainhook instead") */
+	suggestion?: string;
+}
+/**
+* Markdown/MDX documentation analysis types
+*/
+/**
+* A code block extracted from a markdown file
+*/
+interface MarkdownCodeBlock {
+	/** Language tag (ts, typescript, js, javascript, tsx, jsx) */
+	lang: string;
+	/** The code content */
+	code: string;
+	/** Raw meta string from code fence (e.g., "title=example.ts") */
+	meta?: string;
+	/** Starting line number in the markdown file */
+	lineStart: number;
+	/** Ending line number in the markdown file */
+	lineEnd: number;
+}
+/**
+* A parsed markdown documentation file
+*/
+interface MarkdownDocFile {
+	/** File path relative to project root */
+	path: string;
+	/** All executable code blocks found */
+	codeBlocks: MarkdownCodeBlock[];
+}
+/**
+* A reference to an found in markdown
+*/
+interface ExportReference {
+	/** The name of the being referenced */
+	exportName: string;
+	/** File path where the reference was found */
+	file: string;
+	/** Line number in the file */
+	line: number;
+	/** Surrounding code/text for context */
+	context: string;
+	/** Whether this reference is inside a code block */
+	inCodeBlock: boolean;
+	/** The code block index if inside a code block */
+	blockIndex?: number;
+}
+/**
+* Change type for an impacted reference
+*/
+type DocsChangeType = "signature-changed" | "removed" | "deprecated" | "method-removed" | "method-changed" | "method-deprecated";
+/**
+* Member-level change type
+*/
+type MemberChangeType2 = "added" | "removed" | "signature-changed";
+/**
+* An impacted reference in a documentation file
+*/
+interface DocsImpactReference {
+	/** The name that was changed */
+	exportName: string;
+	/** Line number in the file */
+	line: number;
+	/** Type of change affecting this reference */
+	changeType: DocsChangeType;
+	/** Suggested fix (AI-generated or deterministic) */
+	suggestion?: string;
+	/** Context around the reference */
+	context?: string;
+	/** Member/method name if this is a member-level change */
+	memberName?: string;
+	/** Type of member change (added, removed, signature-changed) */
+	memberChangeType?: MemberChangeType2;
+	/** Suggested replacement for removed/changed members */
+	replacementSuggestion?: string;
+	/** True if this is just a class instantiation (new ClassName()) */
+	isInstantiation?: boolean;
+}
+/**
+* Documentation file impact summary
+*/
+interface DocsImpact {
+	/** File path */
+	file: string;
+	/** All impacted references in this file */
+	references: DocsImpactReference[];
+}
+/**
+* Complete docs impact analysis result
+*/
+interface DocsImpactResult {
+	/** Files with impacted references */
+	impactedFiles: DocsImpact[];
+	/** New exports (from this diff) that have no documentation */
+	missingDocs: string[];
+	/** ALL exports from the spec that have no documentation in the scanned files */
+	allUndocumented: string[];
+	/** Statistics */
+	stats: {
+		/** Total markdown files scanned */
+		filesScanned: number;
+		/** Total code blocks found */
+		codeBlocksFound: number;
+		/** Total references found */
+		referencesFound: number;
+		/** References impacted by changes */
+		impactedReferences: number;
+		/** Total exports in the spec */
+		totalExports: number;
+		/** Exports found documented in markdown */
+		documentedExports: number;
+	};
+}
+/**
+* Analyze docs impact from a spec diff
+*
+* @param diff - The spec diff result
+* @param markdownFiles - Parsed markdown files
+* @param newExportNames - All names in the new spec (for missing docs detection)
+* @param memberChanges - Optional member-level changes for granular detection
+*/
+declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFile[], newExportNames?: string[], memberChanges?: MemberChange[]): DocsImpactResult;
+/**
+* Find references to deprecated exports
+*/
+declare function findDeprecatedReferences(markdownFiles: MarkdownDocFile[], deprecatedExports: string[]): ExportReference[];
+/**
+* Find references to removed exports
+*/
+declare function findRemovedReferences(markdownFiles: MarkdownDocFile[], removedExports: string[]): ExportReference[];
+/**
+* Check if any docs reference a specific */
+declare function hasDocsForExport(markdownFiles: MarkdownDocFile[], exportName: string): boolean;
+/**
+* Get all exports that have documentation
+*/
+declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+/**
+* Get all exports that lack documentation
+*/
+declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+import { CategorizedBreaking, OpenPkg as OpenPkg7, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
+/**
+* Extended spec diff result with docs impact
+*/
+interface SpecDiffWithDocs extends SpecDiff2 {
+	/** Docs impact analysis (only present if markdown files provided) */
+	docsImpact?: DocsImpactResult;
+	/** Member-level changes for classes (methods added/removed/changed) */
+	memberChanges?: MemberChange[];
+	/** Breaking changes categorized by severity (high/medium/low) */
+	categorizedBreaking?: CategorizedBreaking[];
+}
+/**
+* Options for diffSpecWithDocs
+*/
+interface DiffWithDocsOptions {
+	/** Parsed markdown documentation files */
+	markdownFiles?: MarkdownDocFile[];
+}
+/**
+* Compute spec diff with optional docs impact analysis
+*
+* @param oldSpec - Previous version of the spec
+* @param newSpec - Current version of the spec
+* @param options - Options including markdown files to analyze
+* @returns Extended diff result with docs impact
+*
+* @example
+* ```ts
+* import { diffSpecWithDocs, parseMarkdownFiles } from '@doccov/sdk';
+* import type { OpenPkg } from '@openpkg-ts/spec';
+*
+* const oldSpec: OpenPkg = { openpkg: '0.2.0', meta: { name: 'my-pkg' }, exports: [] };
+* const newSpec: OpenPkg = { openpkg: '0.2.1', meta: { name: 'my-pkg' }, exports: [] };
+*
+* const markdownFiles = parseMarkdownFiles([
+*   { path: 'docs/guide.md', content: '...' },
+* ]);
+*
+* const diff = diffSpecWithDocs(oldSpec, newSpec, { markdownFiles });
+*
+* if (diff.docsImpact?.impactedFiles.length) {
+*   console.log('Docs need updating!');
+* }
+* ```
+*/
+declare function diffSpecWithDocs(oldSpec: OpenPkg7, newSpec: OpenPkg7, options?: DiffWithDocsOptions): SpecDiffWithDocs;
 /**
-* Check if a drift type can be fixed deterministically
+* Check if a diff has any docs impact
 */
-declare function isFixableDrift(drift: SpecDocDrift4): boolean;
+declare function hasDocsImpact(diff: SpecDiffWithDocs): boolean;
 /**
-* Generate a fix for a single drift issue
+* Get summary of docs impact for display
 */
-declare function generateFix(drift: SpecDocDrift4, exportEntry: SpecExport4, existingPatch?: JSDocPatch): FixSuggestion | null;
+declare function getDocsImpactSummary(diff: SpecDiffWithDocs): {
+	impactedFileCount: number;
+	impactedReferenceCount: number;
+	missingDocsCount: number;
+	totalIssues: number;
+	memberChangesCount: number;
+};
 /**
-* Generate all fixes for an export's drift issues
+* Extract import statements from code (legacy interface).
+* @deprecated Use extractImportsAST for more detailed info.
 */
-declare function generateFixesForExport(exportEntry: SpecExport4, existingPatch?: JSDocPatch): FixSuggestion[];
+declare function extractImports(code: string): Array<{
+	name: string;
+	from: string;
+}>;
 /**
-* Merge multiple fix patches into a single patch
+* Extract function calls from code (legacy interface).
+* @deprecated Use extractCallsAST for more detailed info.
 */
-declare function mergeFixes(fixes: FixSuggestion[], basePatch?: JSDocPatch): JSDocPatch;
+declare function extractFunctionCalls(code: string): string[];
+/** Options for parsing markdown files */
+interface ParseOptions {
+	/** Custom set of executable language tags */
+	executableLangs?: string[];
+}
 /**
-* Get a summary of fixable vs non-fixable drifts
+* Check if a language tag represents executable code
 */
-declare function categorizeDrifts(drifts: SpecDocDrift4[]): {
-	fixable: SpecDocDrift4[];
-	nonFixable: SpecDocDrift4[];
-};
-import { OpenPkg as OpenPkg7 } from "@openpkg-ts/spec";
+declare function isExecutableLang(lang: string | null | undefined, customLangs?: Set<string>): boolean;
 /**
-* Parsed components of a GitHub URL.
+* Parse a markdown file and extract code blocks
 */
-interface ParsedGitHubUrl {
-	/** Repository owner (user or org) */
-	owner: string;
-	/** Repository name */
-	repo: string;
-	/** Git ref (branch or tag) */
-	ref: string;
-}
+declare function parseMarkdownFile(content: string, filePath: string, options?: ParseOptions): MarkdownDocFile;
 /**
-* Parse a GitHub URL or shorthand into components.
-*
-* Supported formats:
-* - https://github.com/owner/repo
-* - https://github.com/owner/repo/tree/branch
-* - https://github.com/owner/repo/tree/v1.0.0
-* - github.com/owner/repo
-* - owner/repo (shorthand)
-* - git@github.com:owner/repo.git
-*
-* @param input - GitHub URL or shorthand
-* @param defaultRef - Default ref if not specified in URL (default: 'main')
-* @returns Parsed components
-* @throws Error if the URL format is invalid
-*
-* @example
-* ```typescript
-* import { parseGitHubUrl } from '@doccov/sdk';
-*
-* const parsed = parseGitHubUrl('https://github.com/vercel/next.js/tree/canary');
-* // { owner: 'vercel', repo: 'next.js', ref: 'canary' }
-*
-* const shorthand = parseGitHubUrl('vercel/next.js');
-* // { owner: 'vercel', repo: 'next.js', ref: 'main' }
-* ```
+* Parse multiple markdown files
 */
-declare function parseGitHubUrl(input: string, defaultRef?: string): ParsedGitHubUrl;
+declare function parseMarkdownFiles(files: Array<{
+	path: string;
+	content: string;
+}>, options?: ParseOptions): MarkdownDocFile[];
 /**
-* Build a clone URL from parsed components.
-*
-* @param parsed - Parsed GitHub URL components
-* @returns HTTPS clone URL
-*
-* @example
-* ```typescript
-* const cloneUrl = buildCloneUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
-* // 'https://github.com/vercel/next.js.git'
-* ```
+* Find all references to given names in markdown files
 */
-declare function buildCloneUrl(parsed: ParsedGitHubUrl): string;
+declare function findExportReferences(files: MarkdownDocFile[], exportNames: string[]): ExportReference[];
 /**
-* Build a display-friendly URL (without protocol or .git suffix).
-*
-* @param parsed - Parsed GitHub URL components
-* @returns Display URL like 'github.com/owner/repo'
-*
-* @example
-* ```typescript
-* const displayUrl = buildDisplayUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
-* // 'github.com/vercel/next.js'
-* ```
+* Check if a code block references any of the given names
 */
-declare function buildDisplayUrl(parsed: ParsedGitHubUrl): string;
+declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
 /**
-* Build a raw.githubusercontent.com URL for a file.
-*
-* @param parsed - Parsed GitHub URL components
-* @param filePath - Path to the file in the repo
-* @returns Raw content URL
+* Type-check a single example
 */
-declare function buildRawUrl(parsed: ParsedGitHubUrl, filePath: string): string;
+declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
 /**
-* Fetch an OpenPkg spec from a GitHub repository.
-*
-* Tries the specified ref first, then falls back to 'master' if not found.
-*
-* @param parsed - Parsed GitHub URL components
-* @returns The OpenPkg spec, or null if not found
-*
-* @example
-* ```typescript
-* import { parseGitHubUrl, fetchSpecFromGitHub } from '@doccov/sdk';
-*
-* const parsed = parseGitHubUrl('vercel/next.js');
-* const spec = await fetchSpecFromGitHub(parsed);
-* if (spec) {
-*   console.log(`Coverage: ${spec.docs?.coverageScore}%`);
-* }
-* ```
+* Type-check multiple examples
 */
-declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg7 | null>;
+declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
+import { OpenPkg as OpenPkg8 } from "@openpkg-ts/spec";
+/** Directory for storing history snapshots */
+declare const HISTORY_DIR = ".doccov/history";
 /**
-* Options for fetching a spec from GitHub.
+* A historical coverage snapshot.
 */
-interface FetchSpecOptions {
-	/** Git ref (branch or tag). Default: 'main' */
-	ref?: string;
-	/** Path to openpkg.json (for monorepos). Default: 'openpkg.json' */
-	path?: string;
+interface CoverageSnapshot {
+	/** ISO 8601 timestamp */
+	timestamp: string;
+	/** Package name */
+	package: string;
+	/** Package version (if available) */
+	version?: string;
+	/** Coverage score (0-100) */
+	coverageScore: number;
+	/** Total number of exports */
+	totalExports: number;
+	/** Number of documented exports */
+	documentedExports: number;
+	/** Number of drift issues */
+	driftCount: number;
+	/** Git commit hash (if available) */
+	commit?: string;
+	/** Git branch (if available) */
+	branch?: string;
 }
 /**
-* Fetch an OpenPkg spec from a GitHub repository by owner/repo/branch.
-*
-* Convenience function that creates ParsedGitHubUrl internally.
-*
-* @param owner - Repository owner
-* @param repo - Repository name
-* @param branchOrOptions - Branch name (default: 'main') or options object
-* @returns The OpenPkg spec, or null if not found
-*/
-declare function fetchSpec(owner: string, repo: string, branchOrOptions?: string | FetchSpecOptions): Promise<OpenPkg7 | null>;
-/**
-* Progress event for installation status updates.
+* Coverage trend data.
 */
-interface InstallProgressEvent {
-	/** Current stage */
-	stage: "installing";
-	/** Human-readable message */
-	message: string;
-	/** Progress percentage (0-100), if known */
-	progress?: number;
+interface CoverageTrend {
+	/** Current snapshot */
+	current: CoverageSnapshot;
+	/** Previous snapshots (most recent first) */
+	history: CoverageSnapshot[];
+	/** Score delta from previous */
+	delta?: number;
+	/** Sparkline data (last N scores) */
+	sparkline: number[];
 }
 /**
-* Callback for receiving installation progress events.
+* Tier-based retention settings.
 */
-type InstallProgressCallback = (event: InstallProgressEvent) => void;
+type RetentionTier = "free" | "team" | "pro";
 /**
-* Result of running a command.
+* Retention days per tier.
 */
-interface CommandResult {
-	/** Exit code (0 = success) */
-	exitCode: number;
-	/** Standard output */
-	stdout: string;
-	/** Standard error */
-	stderr: string;
-}
+declare const RETENTION_DAYS: Record<RetentionTier, number>;
 /**
-* Function that runs a shell command.
-* Abstracts the difference between Node.js execSync and Sandbox runCommand.
+* Weekly summary of coverage data.
 */
-type CommandRunner = (cmd: string, args: string[], options: {
-	cwd: string;
-	timeout?: number;
-}) => Promise<CommandResult>;
+interface WeeklySummary {
+	/** Week start date (ISO string) */
+	weekStart: string;
+	/** Week end date (ISO string) */
+	weekEnd: string;
+	/** Average coverage for the week */
+	avgCoverage: number;
+	/** Coverage at start of week */
+	startCoverage: number;
+	/** Coverage at end of week */
+	endCoverage: number;
+	/** Change during the week */
+	delta: number;
+	/** Number of snapshots in the week */
+	snapshotCount: number;
+}
 /**
-* Result of dependency installation.
+* Extended trend analysis result.
 */
-interface InstallResult {
-	/** Whether installation succeeded */
-	success: boolean;
-	/** Package manager that was used */
-	packageManager: PackageManager;
-	/** If a fallback was used, which one */
-	fallbackUsed?: PackageManager;
-	/** Error message if installation failed */
-	error?: string;
-	/** Detailed error messages from each attempt */
-	errors?: string[];
+interface ExtendedTrendAnalysis {
+	/** Current trend data */
+	trend: CoverageTrend;
+	/** Weekly summaries (most recent first) */
+	weeklySummaries: WeeklySummary[];
+	/** 7-day velocity (average daily change) */
+	velocity7d: number;
+	/** 30-day velocity */
+	velocity30d: number;
+	/** 90-day velocity (Pro only) */
+	velocity90d?: number;
+	/** Projected coverage in 30 days (based on velocity) */
+	projected30d: number;
+	/** Best coverage ever recorded */
+	allTimeHigh: number;
+	/** Worst coverage ever recorded */
+	allTimeLow: number;
+	/** Date range of available data */
+	dataRange: {
+		start: string;
+		end: string;
+	} | null;
 }
 /**
-* Options for dependency installation.
+* Compute a coverage snapshot from an OpenPkg spec.
 */
-interface InstallOptions {
-	/** Timeout in milliseconds for install commands (default: 180000) */
-	timeout?: number;
-	/** Order of fallback package managers to try */
-	fallbackOrder?: PackageManager[];
-	/** Progress callback for status updates */
-	onProgress?: InstallProgressCallback;
-}
+declare function computeSnapshot(spec: OpenPkg8, options?: {
+	commit?: string;
+	branch?: string;
+}): CoverageSnapshot;
 /**
-* Install dependencies for a project.
-*
-* This consolidates the install logic from CLI scan.ts and API scan-stream.ts:
-* 1. Detect package manager from lockfile
-* 2. Try primary install command
-* 3. Fall back to other package managers if primary fails
+* Save a coverage snapshot to history.
 *
-* @param fs - FileSystem implementation for package manager detection
-* @param cwd - Working directory to install in
-* @param runCommand - Function to run shell commands
-* @param options - Installation options
-* @returns Result of the installation attempt
+* @param snapshot - The snapshot to save
+* @param cwd - Working directory
+*/
+declare function saveSnapshot(snapshot: CoverageSnapshot, cwd: string): void;
+/**
+* Load all historical snapshots.
 *
-* @example
-* ```typescript
-* import { NodeFileSystem, installDependencies, createNodeCommandRunner } from '@doccov/sdk';
+* @param cwd - Working directory
+* @returns Array of snapshots sorted by timestamp (most recent first)
+*/
+declare function loadSnapshots(cwd: string): CoverageSnapshot[];
+/**
+* Get coverage trend data.
 *
-* const fs = new NodeFileSystem('/path/to/repo');
-* const result = await installDependencies(fs, '/path/to/repo', createNodeCommandRunner());
+* @param spec - Current OpenPkg spec
+* @param cwd - Working directory
+* @param options - Optional git metadata
+* @returns Trend data with history and delta
+*/
+declare function getTrend(spec: OpenPkg8, cwd: string, options?: {
+	commit?: string;
+	branch?: string;
+}): CoverageTrend;
+/**
+* Generate a sparkline character representation.
 *
-* if (result.success) {
-*   console.log(`Installed using ${result.packageManager}`);
-* } else {
-*   console.error(`Install failed: ${result.error}`);
-* }
-* ```
+* @param values - Array of values (0-100 for coverage)
+* @returns Sparkline string using unicode characters
 */
-declare function installDependencies(fs: FileSystem, cwd: string, runCommand: CommandRunner, options?: InstallOptions): Promise<InstallResult>;
+declare function renderSparkline(values: number[]): string;
 /**
-* Create a command runner for Node.js environments using execSync.
-* This is used by the CLI for local dependency installation.
+* Format a delta value with arrow and color indicator.
 *
-* @returns CommandRunner that uses child_process.execSync
+* @param delta - Coverage delta (positive = improvement)
+* @returns Formatted delta string
+*/
+declare function formatDelta(delta: number): string;
+/**
+* Prune old snapshots to keep history manageable.
 *
-* @example
-* ```typescript
-* const runner = createNodeCommandRunner();
-* const result = await runner('npm', ['install'], { cwd: '/path/to/repo' });
-* ```
+* @param cwd - Working directory
+* @param keepCount - Number of snapshots to keep (default: 100)
+* @returns Number of snapshots deleted
 */
-declare function createNodeCommandRunner(): CommandRunner;
-import { SpecDiff } from "@openpkg-ts/spec";
-type MemberChangeType = "added" | "removed" | "signature-changed";
-interface MemberChange {
-	/** The class this member belongs to */
-	className: string;
-	/** The member name (e.g., "evaluateChainhook") */
-	memberName: string;
-	/** Kind of member */
-	memberKind: "method" | "property" | "accessor" | "constructor";
-	/** Type of change */
-	changeType: MemberChangeType;
-	/** Old signature string (for signature changes) */
-	oldSignature?: string;
-	/** New signature string (for signature changes) */
-	newSignature?: string;
-	/** Suggested replacement (e.g., "Use replayChainhook instead") */
-	suggestion?: string;
-}
+declare function pruneHistory(cwd: string, keepCount?: number): number;
 /**
-* Markdown/MDX documentation analysis types
+* Get extended trend analysis with velocity and projections.
+*
+* @param spec - Current OpenPkg spec
+* @param cwd - Working directory
+* @param options - Analysis options
+* @returns Extended trend analysis
 */
+declare function getExtendedTrend(spec: OpenPkg8, cwd: string, options?: {
+	commit?: string;
+	branch?: string;
+	tier?: RetentionTier;
+}): ExtendedTrendAnalysis;
+import * as TS3 from "typescript";
 /**
-* A code block extracted from a markdown file
+* A schema adapter can detect and extract output types from a specific
+* schema validation library.
 */
-interface MarkdownCodeBlock {
-	/** Language tag (ts, typescript, js, javascript, tsx, jsx) */
-	lang: string;
-	/** The code content */
-	code: string;
-	/** Raw meta string from code fence (e.g., "title=example.ts") */
-	meta?: string;
-	/** Starting line number in the markdown file */
-	lineStart: number;
-	/** Ending line number in the markdown file */
-	lineEnd: number;
+interface SchemaAdapter {
+	/** Unique identifier for this adapter */
+	readonly id: string;
+	/** npm package name(s) this adapter handles */
+	readonly packages: readonly string[];
+	/**
+	* Check if a type matches this adapter's schema library.
+	* Should be fast - called for every export.
+	*/
+	matches(type: TS3.Type, checker: TS3.TypeChecker): boolean;
+	/**
+	* Extract the output type from a schema type.
+	* Returns null if extraction fails.
+	*/
+	extractOutputType(type: TS3.Type, checker: TS3.TypeChecker): TS3.Type | null;
+	/**
+	* Extract the input type from a schema type (optional).
+	* Useful for transforms where input differs from output.
+	*/
+	extractInputType?(type: TS3.Type, checker: TS3.TypeChecker): TS3.Type | null;
 }
 /**
-* A parsed markdown documentation file
+* Result of schema type extraction
 */
-interface MarkdownDocFile {
-	/** File path relative to project root */
-	path: string;
-	/** All executable code blocks found */
-	codeBlocks: MarkdownCodeBlock[];
+interface SchemaExtractionResult {
+	/** The adapter that matched */
+	adapter: SchemaAdapter;
+	/** The extracted output type */
+	outputType: TS3.Type;
+	/** The extracted input type (if different from output) */
+	inputType?: TS3.Type;
 }
+import * as TS4 from "typescript";
 /**
-* A reference to an found in markdown
+* Find an adapter that matches the given type.
+* Returns null if no adapter matches.
 */
-interface ExportReference {
-	/** The name of the being referenced */
-	exportName: string;
-	/** File path where the reference was found */
-	file: string;
-	/** Line number in the file */
-	line: number;
-	/** Surrounding code/text for context */
-	context: string;
-	/** Whether this reference is inside a code block */
-	inCodeBlock: boolean;
-	/** The code block index if inside a code block */
-	blockIndex?: number;
-}
+declare function findAdapter(type: TS4.Type, checker: TS4.TypeChecker): SchemaAdapter | null;
 /**
-* Change type for an impacted reference
+* Check if a type is from a recognized schema library.
 */
-type DocsChangeType = "signature-changed" | "removed" | "deprecated" | "method-removed" | "method-changed" | "method-deprecated";
+declare function isSchemaType(type: TS4.Type, checker: TS4.TypeChecker): boolean;
 /**
-* Member-level change type
+* Extract the output type from a schema type.
+* Returns null if:
+* - The type is not from a recognized schema library
+* - The adapter fails to extract the output type
 */
-type MemberChangeType2 = "added" | "removed" | "signature-changed";
+declare function extractSchemaOutputType(type: TS4.Type, checker: TS4.TypeChecker): TS4.Type | null;
 /**
-* An impacted reference in a documentation file
+* Full extraction with adapter info.
+* Useful when you need to know which library was detected.
 */
-interface DocsImpactReference {
-	/** The name that was changed */
-	exportName: string;
-	/** Line number in the file */
-	line: number;
-	/** Type of change affecting this reference */
-	changeType: DocsChangeType;
-	/** Suggested fix (AI-generated or deterministic) */
-	suggestion?: string;
-	/** Context around the reference */
-	context?: string;
-	/** Member/method name if this is a member-level change */
-	memberName?: string;
-	/** Type of member change (added, removed, signature-changed) */
-	memberChangeType?: MemberChangeType2;
-	/** Suggested replacement for removed/changed members */
-	replacementSuggestion?: string;
-	/** True if this is just a class instantiation (new ClassName()) */
-	isInstantiation?: boolean;
-}
+declare function extractSchemaType(type: TS4.Type, checker: TS4.TypeChecker): SchemaExtractionResult | null;
 /**
-* Documentation file impact summary
+* Get all registered adapters.
+* Useful for logging/debugging.
 */
-interface DocsImpact {
-	/** File path */
-	file: string;
-	/** All impacted references in this file */
-	references: DocsImpactReference[];
-}
+declare function getRegisteredAdapters(): readonly SchemaAdapter[];
 /**
-* Complete docs impact analysis result
+* Get supported library names.
+* Useful for documentation/help output.
 */
-interface DocsImpactResult {
-	/** Files with impacted references */
-	impactedFiles: DocsImpact[];
-	/** New exports (from this diff) that have no documentation */
-	missingDocs: string[];
-	/** ALL exports from the spec that have no documentation in the scanned files */
-	allUndocumented: string[];
-	/** Statistics */
-	stats: {
-		/** Total markdown files scanned */
-		filesScanned: number;
-		/** Total code blocks found */
-		codeBlocksFound: number;
-		/** Total references found */
-		referencesFound: number;
-		/** References impacted by changes */
-		impactedReferences: number;
-		/** Total exports in the spec */
-		totalExports: number;
-		/** Exports found documented in markdown */
-		documentedExports: number;
+declare function getSupportedLibraries(): readonly string[];
+/**
+* Standard JSON Schema v1 interface (minimal for detection).
+*/
+interface StandardJSONSchemaV1 {
+	"~standard": {
+		version: number;
+		vendor: string;
+		jsonSchema?: {
+			output: (target?: string) => Record<string, unknown>;
+			input?: (target?: string) => Record<string, unknown>;
+		};
 	};
 }
 /**
-* Analyze docs impact from a spec diff
-*
-* @param diff - The spec diff result
-* @param markdownFiles - Parsed markdown files
-* @param newExportNames - All names in the new spec (for missing docs detection)
-* @param memberChanges - Optional member-level changes for granular detection
+* Result of extracting Standard Schema from an export.
 */
-declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFile[], newExportNames?: string[], memberChanges?: MemberChange[]): DocsImpactResult;
+interface StandardSchemaExtractionResult {
+	exportName: string;
+	vendor: string;
+	outputSchema: Record<string, unknown>;
+	inputSchema?: Record<string, unknown>;
+}
 /**
-* Find references to deprecated exports
+* Options for runtime Standard Schema extraction.
 */
-declare function findDeprecatedReferences(markdownFiles: MarkdownDocFile[], deprecatedExports: string[]): ExportReference[];
+interface ExtractStandardSchemasOptions {
+	/** Timeout in milliseconds (default: 10000) */
+	timeout?: number;
+	/** JSON Schema target version (default: 'draft-2020-12') */
+	target?: "draft-2020-12" | "draft-07" | "openapi-3.0";
+}
 /**
-* Find references to removed exports
+* Result of Standard Schema extraction.
 */
-declare function findRemovedReferences(markdownFiles: MarkdownDocFile[], removedExports: string[]): ExportReference[];
+interface StandardSchemaExtractionOutput {
+	schemas: Map<string, StandardSchemaExtractionResult>;
+	errors: string[];
+}
 /**
-* Check if any docs reference a specific */
-declare function hasDocsForExport(markdownFiles: MarkdownDocFile[], exportName: string): boolean;
+* Check if an object implements StandardJSONSchemaV1.
+* This is a static type guard - doesn't require runtime.
+*/
+declare function isStandardJSONSchema(obj: unknown): obj is StandardJSONSchemaV1;
 /**
-* Get all exports that have documentation
+* Resolve compiled JS path from TypeScript source.
+* Tries common output locations: dist/, build/, lib/, same dir.
 */
-declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+declare function resolveCompiledPath(tsPath: string, baseDir: string): string | null;
 /**
-* Get all exports that lack documentation
+* Extract Standard Schema JSON Schemas from a compiled JS module.
+*
+* **Security Note**: This executes the module in a subprocess.
+* Only use with trusted code (user's own packages).
+*
+* @param compiledJsPath - Path to compiled .js file
+* @param options - Extraction options
+* @returns Extraction results with schemas and any errors
 */
-declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
-import { CategorizedBreaking, OpenPkg as OpenPkg9, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
+declare function extractStandardSchemas(compiledJsPath: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
 /**
-* Extended spec diff result with docs impact
+* Extract Standard Schema from a TypeScript project.
+*
+* Convenience function that resolves compiled JS and extracts schemas.
+*
+* @param entryFile - TypeScript entry file path
+* @param baseDir - Project base directory
+* @param options - Extraction options
 */
-interface SpecDiffWithDocs extends SpecDiff2 {
-	/** Docs impact analysis (only present if markdown files provided) */
-	docsImpact?: DocsImpactResult;
-	/** Member-level changes for classes (methods added/removed/changed) */
-	memberChanges?: MemberChange[];
-	/** Breaking changes categorized by severity (high/medium/low) */
-	categorizedBreaking?: CategorizedBreaking[];
+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;
+}
+declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
+import { OpenPkg as OpenPkg9 } from "@openpkg-ts/spec";
 /**
-* Options for diffSpecWithDocs
+* Parsed components of a GitHub URL.
 */
-interface DiffWithDocsOptions {
-	/** Parsed markdown documentation files */
-	markdownFiles?: MarkdownDocFile[];
+interface ParsedGitHubUrl {
+	/** Repository owner (user or org) */
+	owner: string;
+	/** Repository name */
+	repo: string;
+	/** Git ref (branch or tag) */
+	ref: string;
 }
 /**
-* Compute spec diff with optional docs impact analysis
+* Parse a GitHub URL or shorthand into components.
 *
-* @param oldSpec - Previous version of the spec
-* @param newSpec - Current version of the spec
-* @param options - Options including markdown files to analyze
-* @returns Extended diff result with docs impact
+* Supported formats:
+* - https://github.com/owner/repo
+* - https://github.com/owner/repo/tree/branch
+* - https://github.com/owner/repo/tree/v1.0.0
+* - github.com/owner/repo
+* - owner/repo (shorthand)
+* - git@github.com:owner/repo.git
+*
+* @param input - GitHub URL or shorthand
+* @param defaultRef - Default ref if not specified in URL (default: 'main')
+* @returns Parsed components
+* @throws Error if the URL format is invalid
 *
 * @example
-* ```ts
-* import { diffSpecWithDocs, parseMarkdownFiles } from '@doccov/sdk';
-* import type { OpenPkg } from '@openpkg-ts/spec';
+* ```typescript
+* import { parseGitHubUrl } from '@doccov/sdk';
 *
-* const oldSpec: OpenPkg = { openpkg: '0.2.0', meta: { name: 'my-pkg' }, exports: [] };
-* const newSpec: OpenPkg = { openpkg: '0.2.1', meta: { name: 'my-pkg' }, exports: [] };
+* const parsed = parseGitHubUrl('https://github.com/vercel/next.js/tree/canary');
+* // { owner: 'vercel', repo: 'next.js', ref: 'canary' }
 *
-* const markdownFiles = parseMarkdownFiles([
-*   { path: 'docs/guide.md', content: '...' },
-* ]);
+* const shorthand = parseGitHubUrl('vercel/next.js');
+* // { owner: 'vercel', repo: 'next.js', ref: 'main' }
+* ```
+*/
+declare function parseGitHubUrl(input: string, defaultRef?: string): ParsedGitHubUrl;
+/**
+* Build a clone URL from parsed components.
 *
-* const diff = diffSpecWithDocs(oldSpec, newSpec, { markdownFiles });
+* @param parsed - Parsed GitHub URL components
+* @returns HTTPS clone URL
 *
-* if (diff.docsImpact?.impactedFiles.length) {
-*   console.log('Docs need updating!');
+* @example
+* ```typescript
+* const cloneUrl = buildCloneUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
+* // 'https://github.com/vercel/next.js.git'
+* ```
+*/
+declare function buildCloneUrl(parsed: ParsedGitHubUrl): string;
+/**
+* Build a display-friendly URL (without protocol or .git suffix).
+*
+* @param parsed - Parsed GitHub URL components
+* @returns Display URL like 'github.com/owner/repo'
+*
+* @example
+* ```typescript
+* const displayUrl = buildDisplayUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
+* // 'github.com/vercel/next.js'
+* ```
+*/
+declare function buildDisplayUrl(parsed: ParsedGitHubUrl): string;
+/**
+* Build a raw.githubusercontent.com URL for a file.
+*
+* @param parsed - Parsed GitHub URL components
+* @param filePath - Path to the file in the repo
+* @returns Raw content URL
+*/
+declare function buildRawUrl(parsed: ParsedGitHubUrl, filePath: string): string;
+/**
+* Fetch an OpenPkg spec from a GitHub repository.
+*
+* Tries the specified ref first, then falls back to 'master' if not found.
+*
+* @param parsed - Parsed GitHub URL components
+* @returns The OpenPkg spec, or null if not found
+*
+* @example
+* ```typescript
+* import { parseGitHubUrl, fetchSpecFromGitHub } from '@doccov/sdk';
+*
+* const parsed = parseGitHubUrl('vercel/next.js');
+* const spec = await fetchSpecFromGitHub(parsed);
+* if (spec) {
+*   console.log(`Coverage: ${spec.docs?.coverageScore}%`);
 * }
 * ```
 */
-declare function diffSpecWithDocs(oldSpec: OpenPkg9, newSpec: OpenPkg9, options?: DiffWithDocsOptions): SpecDiffWithDocs;
+declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg9 | null>;
 /**
-* Check if a diff has any docs impact
+* Options for fetching a spec from GitHub.
 */
-declare function hasDocsImpact(diff: SpecDiffWithDocs): boolean;
+interface FetchSpecOptions {
+	/** Git ref (branch or tag). Default: 'main' */
+	ref?: string;
+	/** Path to openpkg.json (for monorepos). Default: 'openpkg.json' */
+	path?: string;
+}
 /**
-* Get summary of docs impact for display
+* Fetch an OpenPkg spec from a GitHub repository by owner/repo/branch.
+*
+* Convenience function that creates ParsedGitHubUrl internally.
+*
+* @param owner - Repository owner
+* @param repo - Repository name
+* @param branchOrOptions - Branch name (default: 'main') or options object
+* @returns The OpenPkg spec, or null if not found
 */
-declare function getDocsImpactSummary(diff: SpecDiffWithDocs): {
-	impactedFileCount: number;
-	impactedReferenceCount: number;
-	missingDocsCount: number;
-	totalIssues: number;
-	memberChangesCount: number;
-};
+declare function fetchSpec(owner: string, repo: string, branchOrOptions?: string | FetchSpecOptions): Promise<OpenPkg9 | null>;
 /**
-* Extract import statements from code (legacy interface).
-* @deprecated Use extractImportsAST for more detailed info.
+* Progress event for installation status updates.
 */
-declare function extractImports(code: string): Array<{
-	name: string;
-	from: string;
-}>;
+interface InstallProgressEvent {
+	/** Current stage */
+	stage: "installing";
+	/** Human-readable message */
+	message: string;
+	/** Progress percentage (0-100), if known */
+	progress?: number;
+}
 /**
-* Extract function calls from code (legacy interface).
-* @deprecated Use extractCallsAST for more detailed info.
+* Callback for receiving installation progress events.
 */
-declare function extractFunctionCalls(code: string): string[];
-/** Options for parsing markdown files */
-interface ParseOptions {
-	/** Custom set of executable language tags */
-	executableLangs?: string[];
+type InstallProgressCallback = (event: InstallProgressEvent) => void;
+/**
+* Result of running a command.
+*/
+interface CommandResult {
+	/** Exit code (0 = success) */
+	exitCode: number;
+	/** Standard output */
+	stdout: string;
+	/** Standard error */
+	stderr: string;
 }
 /**
-* Check if a language tag represents executable code
+* Function that runs a shell command.
+* Abstracts the difference between Node.js execSync and Sandbox runCommand.
 */
-declare function isExecutableLang(lang: string | null | undefined, customLangs?: Set<string>): boolean;
+type CommandRunner = (cmd: string, args: string[], options: {
+	cwd: string;
+	timeout?: number;
+}) => Promise<CommandResult>;
 /**
-* Parse a markdown file and extract code blocks
+* Result of dependency installation.
 */
-declare function parseMarkdownFile(content: string, filePath: string, options?: ParseOptions): MarkdownDocFile;
+interface InstallResult {
+	/** Whether installation succeeded */
+	success: boolean;
+	/** Package manager that was used */
+	packageManager: PackageManager;
+	/** If a fallback was used, which one */
+	fallbackUsed?: PackageManager;
+	/** Error message if installation failed */
+	error?: string;
+	/** Detailed error messages from each attempt */
+	errors?: string[];
+}
 /**
-* Parse multiple markdown files
+* Options for dependency installation.
 */
-declare function parseMarkdownFiles(files: Array<{
-	path: string;
-	content: string;
-}>, options?: ParseOptions): MarkdownDocFile[];
+interface InstallOptions {
+	/** Timeout in milliseconds for install commands (default: 180000) */
+	timeout?: number;
+	/** Order of fallback package managers to try */
+	fallbackOrder?: PackageManager[];
+	/** Progress callback for status updates */
+	onProgress?: InstallProgressCallback;
+}
 /**
-* Find all references to given names in markdown files
+* Install dependencies for a project.
+*
+* This consolidates the install logic from CLI scan.ts and API scan-stream.ts:
+* 1. Detect package manager from lockfile
+* 2. Try primary install command
+* 3. Fall back to other package managers if primary fails
+*
+* @param fs - FileSystem implementation for package manager detection
+* @param cwd - Working directory to install in
+* @param runCommand - Function to run shell commands
+* @param options - Installation options
+* @returns Result of the installation attempt
+*
+* @example
+* ```typescript
+* import { NodeFileSystem, installDependencies, createNodeCommandRunner } from '@doccov/sdk';
+*
+* const fs = new NodeFileSystem('/path/to/repo');
+* const result = await installDependencies(fs, '/path/to/repo', createNodeCommandRunner());
+*
+* if (result.success) {
+*   console.log(`Installed using ${result.packageManager}`);
+* } else {
+*   console.error(`Install failed: ${result.error}`);
+* }
+* ```
 */
-declare function findExportReferences(files: MarkdownDocFile[], exportNames: string[]): ExportReference[];
+declare function installDependencies(fs: FileSystem, cwd: string, runCommand: CommandRunner, options?: InstallOptions): Promise<InstallResult>;
 /**
-* Check if a code block references any of the given names
+* Create a command runner for Node.js environments using execSync.
+* This is used by the CLI for local dependency installation.
+*
+* @returns CommandRunner that uses child_process.execSync
+*
+* @example
+* ```typescript
+* const runner = createNodeCommandRunner();
+* const result = await runner('npm', ['install'], { cwd: '/path/to/repo' });
+* ```
 */
-declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
-import { EntryPointDetectionMethod } from "@openpkg-ts/spec";
+declare function createNodeCommandRunner(): CommandRunner;
 /**
-* Input for generation metadata that comes from the caller (CLI, API, etc.)
+* Source of filter options.
 */
-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 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>;
+type FilterSource = "config" | "override" | "combined";
 /**
-* Options for resolving a target package/entry point.
+* Resolved filter options after merging config and overrides.
 */
-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;
+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;
 }
 /**
-* Result of resolving a target package/entry point.
+* 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
+* ```
 */
-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;
-}
+declare function parseListFlag(value?: string | string[]): string[] | undefined;
 /**
-* Resolve a target package and entry point.
+* Merge filter options from config and CLI/API overrides.
 *
-* 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
+* Merge behavior:
+* - Include: CLI values intersect with config values (narrowing)
+* - Exclude: CLI values are added to config values (expanding)
 *
-* @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
+* @param config - Configuration (from doccov.config.ts)
+* @param overrides - Override filters (from CLI flags or API params)
+* @returns Merged filter options
 *
 * @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() });
+* const config = { include: ['A', 'B', 'C'] };
+* const overrides = { include: ['B', 'C', 'D'] };
 *
-* // With monorepo package
-* const { targetDir, entryFile, packageInfo } = await resolveTarget(fs, {
-*   cwd: process.cwd(),
-*   package: '@myorg/core',
-* });
+* const resolved = mergeFilters(config, overrides);
+* // resolved.include = ['B', 'C'] (intersection)
 * ```
 */
-declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
+declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
 /**
 * Repository metadata from GitHub API.
 */
@@ -2623,12 +2576,4 @@ interface BuildPlanExecutionResult {
 	/** Overall error message if failed */
 	error?: string;
 }
-/**
-* Type-check a single example
-*/
-declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
-/**
-* Type-check multiple examples
-*/
-declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
-export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveSnapshot, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, resolveCompiledPath, renderSparkline, renderApiSurface, readPackageJson, pruneHistory, pruneByTier, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, loadSpecCache, loadSnapshotsForDays, loadSnapshots, loadCachedReport, listWorkspacePackages, isStandardJSONSchema, isSchemaType, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getTrend, getSupportedLibraries, getSpecCachePath, getRunCommand, getReportPath, getRegisteredAdapters, getPrimaryBuildScript, getInstallCommand, getExtendedTrend, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, generateWeeklySummaries, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, formatDelta, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, findAdapter, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractStandardSchemasFromProject, extractStandardSchemas, extractSpecSummary, extractSchemaType, extractSchemaOutputType, extractPackageSpec, extractImports, extractFunctionCalls, ensureSpecCoverage, enrichSpec, diffSpecWithDocs, diffHashes, detectRuntimeSchemas, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeSnapshot, computeExportDrift, computeDrift, clearSpecCache, clearSchemaCache, categorizeDrifts, categorizeDrift, calculateAggregateCoverage, buildRawUrl, buildExportRegistry, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, WorkspaceConfig, WeeklySummary, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SummaryDriftIssue, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, SchemaExtractionResult, SchemaExtractionMode, SchemaDetectionResult, SchemaDetectionContext, SchemaAdapter, SandboxFileSystem, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, RetentionTier, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, ReleaseTag, RETENTION_DAYS, REPORT_VERSION, REPORT_EXTENSIONS, ProjectInfo, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, HISTORY_DIR, GitHubRepoMetadata, GitHubProjectContext, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, FetchGitHubContextOptions, ExtractStandardSchemasOptions, ExtendedTrendAnalysis, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic2 as Diagnostic, DetectedSchemaEntry, DetectedPackageManager, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageTrend, CoverageSummary, CoverageSnapshot, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CACHE_VERSION, BuildPlanTarget, BuildPlanStepResult, BuildPlanStep, BuildPlanExecutionResult, BuildPlanEnvironment, BuildPlan, BuildInfo, BuildHints, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, ALL_VALIDATIONS };
+export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveSnapshot, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, resolveCompiledPath, renderSparkline, readPackageJson, pruneHistory, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, loadSpecCache, loadSnapshots, loadCachedReport, listWorkspacePackages, isStandardJSONSchema, isSchemaType, isFixableDrift, isExecutableLang, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getTrend, getSupportedLibraries, getSpecCachePath, getRunCommand, getReportPath, getRegisteredAdapters, getPrimaryBuildScript, getInstallCommand, getExtendedTrend, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, formatDelta, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, findAdapter, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractStandardSchemasFromProject, extractStandardSchemas, extractSpecSummary, extractSchemaType, extractSchemaOutputType, extractPackageSpec, extractImports, extractFunctionCalls, ensureSpecCoverage, enrichSpec, diffSpecWithDocs, diffHashes, detectRuntimeSchemas, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeSnapshot, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, calculateAggregateCoverage, buildRawUrl, buildExportRegistry, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, WorkspaceConfig, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SummaryDriftIssue, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, SchemaExtractionResult, SchemaExtractionMode, SchemaDetectionResult, SchemaDetectionContext, SchemaAdapter, SandboxFileSystem, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, ReleaseTag, RETENTION_DAYS, REPORT_VERSION, REPORT_EXTENSIONS, ProjectInfo, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, HISTORY_DIR, GitHubRepoMetadata, GitHubProjectContext, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, FetchGitHubContextOptions, ExtractStandardSchemasOptions, ExtendedTrendAnalysis, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic2 as Diagnostic, DetectedSchemaEntry, DetectedPackageManager, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageTrend, CoverageSummary, CoverageSnapshot, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CACHE_VERSION, BuildPlanTarget, BuildPlanStepResult, BuildPlanStep, BuildPlanExecutionResult, BuildPlanEnvironment, BuildPlan, BuildInfo, BuildHints, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, ALL_VALIDATIONS };