@doccov/sdk 0.15.1 → 0.19.0

package/dist/index.d.ts

@@ -1,3 +1,273 @@
+/**
+* Configuration types for DocCov.
+* These types are shared between CLI and API.
+*/
+/**
+* Documentation configuration options.
+*/
+interface DocsConfig {
+	/** Glob patterns for markdown docs to include */
+	include?: string[];
+	/** Glob patterns for markdown docs to exclude */
+	exclude?: string[];
+}
+/**
+* Example validation modes.
+*/
+type ExampleValidationMode = "presence" | "typecheck" | "run";
+/**
+* Schema extraction modes for validation libraries (Zod, Valibot, TypeBox, ArkType).
+*
+* - 'static': TypeScript Compiler API only (no runtime, always safe)
+* - 'runtime': Standard Schema runtime extraction (requires built package)
+* - 'hybrid': Try runtime first, fall back to static
+*/
+type SchemaExtractionMode = "static" | "runtime" | "hybrid";
+/**
+* Check command configuration options.
+*/
+interface CheckConfig {
+	/**
+	* Example validation modes to run.
+	* Can be a single mode, array of modes, or comma-separated string.
+	* - 'presence': Check that @example blocks exist on exports
+	* - 'typecheck': Compile examples with TypeScript
+	* - 'run': Execute examples and validate assertions
+	*/
+	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
+	/** Minimum coverage percentage required (0-100) */
+	minCoverage?: number;
+	/** Maximum drift percentage allowed (0-100) */
+	maxDrift?: number;
+}
+/**
+* Normalized DocCov configuration.
+* This is the parsed/normalized form used by commands.
+*/
+interface DocCovConfig {
+	/** Export include patterns */
+	include?: string[];
+	/** Export exclude patterns */
+	exclude?: string[];
+	/** Plugins (future) */
+	plugins?: unknown[];
+	/** Documentation configuration */
+	docs?: DocsConfig;
+	/** Check command configuration */
+	check?: CheckConfig;
+	/**
+	* Schema extraction mode for validation libraries.
+	*
+	* - 'static' (default): Safe, uses TypeScript Compiler API
+	* - 'runtime': Uses Standard Schema (requires built package)
+	* - 'hybrid': Tries runtime first, falls back to static
+	*
+	* Runtime extraction provides richer JSON Schema output (formats, patterns)
+	* but requires the package to be built first.
+	*/
+	schemaExtraction?: SchemaExtractionMode;
+}
+/**
+* Define a DocCov configuration.
+* Helper function for type-safe configuration in doccov.config.ts.
+*
+* @param config - Configuration object
+* @returns The configuration object (for type inference)
+*
+* @example
+* ```typescript
+* // doccov.config.ts
+* import { defineConfig } from '@doccov/sdk';
+*
+* defineConfig({
+*   include: ['MyClass', 'myFunction'],
+*   exclude: ['internal*'],
+*   check: {
+*     minCoverage: 80,
+*   },
+* });
+* ```
+*/
+declare function defineConfig(config: DocCovConfig): DocCovConfig;
+interface DocCovOptions {
+	includePrivate?: boolean;
+	followImports?: boolean;
+	maxDepth?: number;
+	resolveExternalTypes?: boolean;
+	/** Enable spec caching (default: true) */
+	useCache?: boolean;
+	/** Working directory for cache operations (default: process.cwd()) */
+	cwd?: string;
+	/**
+	* Schema extraction mode for validation libraries (Zod, Valibot, etc.)
+	*
+	* - 'static' (default): TypeScript Compiler API only (no runtime)
+	* - 'runtime': Standard Schema runtime extraction (requires built package)
+	* - 'hybrid': Try runtime first, fall back to static
+	*/
+	schemaExtraction?: SchemaExtractionMode;
+}
+/**
+* Pre-detected Standard Schema for a variable export.
+*/
+interface DetectedSchemaEntry {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
+/**
+* Runtime Schema Detection (Stubbed)
+*
+* Standard Schema extraction has been removed. This module provides
+* empty stubs to maintain API compatibility.
+*/
+interface SchemaDetectionContext {
+	baseDir: string;
+	entryFile: string;
+}
+interface SchemaDetectionResult {
+	schemas: Map<string, never>;
+	errors: string[];
+}
+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;
+}
+/**
+* Result of schema type extraction
+*/
+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;
+}
+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
+*/
+declare function extractSchemaOutputType(type: TS2.Type, checker: TS2.TypeChecker): TS2.Type | null;
+/**
+* Full extraction with adapter info.
+* Useful when you need to know which library was detected.
+*/
+declare function extractSchemaType(type: TS2.Type, checker: TS2.TypeChecker): SchemaExtractionResult | null;
+/**
+* Get all registered adapters.
+* Useful for logging/debugging.
+*/
+declare function getRegisteredAdapters(): readonly SchemaAdapter[];
+/**
+* Get supported library names.
+* Useful for documentation/help output.
+*/
+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>;
+		};
+	};
+}
+/**
+* Result of extracting Standard Schema from an export.
+*/
+interface StandardSchemaExtractionResult {
+	exportName: string;
+	vendor: string;
+	outputSchema: Record<string, unknown>;
+	inputSchema?: Record<string, unknown>;
+}
+/**
+* Options for runtime Standard Schema extraction.
+*/
+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";
+}
+/**
+* Result of Standard Schema extraction.
+*/
+interface StandardSchemaExtractionOutput {
+	schemas: Map<string, StandardSchemaExtractionResult>;
+	errors: string[];
+}
+/**
+* Check if an object implements StandardJSONSchemaV1.
+* This is a static type guard - doesn't require runtime.
+*/
+declare function isStandardJSONSchema(obj: unknown): obj is StandardJSONSchemaV1;
+/**
+* Resolve compiled JS path from TypeScript source.
+* Tries common output locations: dist/, build/, lib/, same dir.
+*/
+declare function resolveCompiledPath(tsPath: string, baseDir: string): string | null;
+/**
+* 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 extractStandardSchemas(compiledJsPath: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
+/**
+* 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
+*/
+declare function extractStandardSchemasFromProject(entryFile: string, baseDir: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
 import { DriftCategory, SpecDocDrift, SpecExport } from "@openpkg-ts/spec";
 interface ExampleRunResult {
 	success: boolean;
@@ -225,222 +495,18 @@ declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
 		coverageScore: number;
 	};
 };
-import { OpenPkg as OpenPkg3, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
-import { SpecExport as SpecExport2, SpecExportKind } from "@openpkg-ts/spec";
-import * as TS from "typescript";
-/**
-* Represents a single parameter in a JSDoc patch
-*/
-interface JSDocParam {
-	name: string;
-	type?: string;
-	description?: string;
-	optional?: boolean;
-}
-/**
-* Represents a return type in a JSDoc patch
-*/
-interface JSDocReturn {
-	type?: string;
-	description?: string;
-}
-/**
-* Represents a generic tag in a JSDoc patch
-*/
-interface JSDocTag {
-	name: string;
-	text: string;
-}
-/**
-* A patchable representation of a JSDoc comment
-*/
-interface JSDocPatch {
-	description?: string;
-	params?: JSDocParam[];
-	returns?: JSDocReturn;
-	examples?: string[];
-	deprecated?: string | false;
-	async?: boolean;
-	type?: string;
-	typeParams?: Array<{
-		name: string;
-		constraint?: string;
-		description?: string;
-	}>;
-	otherTags?: JSDocTag[];
-}
-/**
-* Represents an edit to be applied to a source file
-*/
-interface JSDocEdit {
-	filePath: string;
-	symbolName: string;
-	startLine: number;
-	endLine: number;
-	hasExisting: boolean;
-	existingJSDoc?: string;
-	newJSDoc: string;
-	indent: string;
-}
-/**
-* Result of applying edits to source files
-*/
-interface ApplyEditsResult {
-	filesModified: number;
-	editsApplied: number;
-	errors: Array<{
-		file: string;
-		error: string;
-	}>;
-}
-/**
-* Parse a JSDoc comment string into a patchable structure
-*/
-declare function parseJSDocToPatch(jsDocText: string): JSDocPatch;
-/**
-* Apply a partial patch to an existing JSDoc patch, preserving unmodified content
-*/
-declare function applyPatchToJSDoc(existing: JSDocPatch, updates: Partial<JSDocPatch>): JSDocPatch;
-/**
-* Serialize a JSDocPatch back to a formatted comment string
-*/
-declare function serializeJSDoc(patch: JSDocPatch, indent?: string): string;
-/**
-* Find the JSDoc location for a declaration in a source file
-*/
-declare function findJSDocLocation(sourceFile: TS.SourceFile, symbolName: string, approximateLine?: number): {
-	startLine: number;
-	endLine: number;
-	declarationLine: number;
-	hasExisting: boolean;
-	existingJSDoc?: string;
-	indent: string;
-} | null;
-/**
-* Apply a batch of edits to source files
-*/
-declare function applyEdits(edits: JSDocEdit[]): Promise<ApplyEditsResult>;
-/**
-* Create a TypeScript source file from a file path
-*/
-declare function createSourceFile(filePath: string): TS.SourceFile;
-/**
-* Quality rule severity levels.
-*/
-type QualitySeverity = "error" | "warn" | "off";
-/**
-* Context passed to quality rule checks.
-*/
-interface RuleContext {
-	export: SpecExport2;
-	rawJSDoc?: string;
-}
-/**
-* A violation reported by a quality rule.
-*/
-interface QualityViolation {
-	ruleId: string;
-	severity: "error" | "warn";
-	message: string;
-	line?: number;
-	fixable: boolean;
-}
-/**
-* A quality rule checks one aspect of documentation quality.
-* Rules can contribute to coverage score, lint violations, or both.
-*/
-interface QualityRule {
-	/** Unique rule identifier */
-	id: string;
-	/** Human-readable name */
-	name: string;
-	/** What this rule checks */
-	description: string;
-	/**
-	* Which kinds this rule applies to.
-	* If undefined, applies to all kinds.
-	*/
-	appliesTo?: SpecExportKind[];
-	/**
-	* Does this rule contribute to coverage score?
-	* If true, the rule is counted as a "signal" for coverage calculation.
-	*/
-	affectsCoverage: boolean;
-	/**
-	* Default lint severity. Set to 'off' if rule is coverage-only.
-	*/
-	defaultSeverity: QualitySeverity;
-	/**
-	* Check if the satisfies this rule.
-	* Returns true if satisfied, false if not.
-	*/
-	check(ctx: RuleContext): boolean;
-	/**
-	* Get detailed violation info when check returns false.
-	* Only called if check() returns false and severity !== 'off'.
-	*/
-	getViolation?(ctx: RuleContext): QualityViolation;
-	/**
-	* Generate a fix for the violation.
-	* Only called if check() returns false and fix is requested.
-	*/
-	fix?(ctx: RuleContext): JSDocPatch | null;
-}
-/**
-* User configuration for quality rules.
-*/
-interface QualityConfig {
-	rules: Record<string, QualitySeverity>;
-}
-/**
-* Result of evaluating quality for a single export.
-*/
-interface QualityResult {
-	/** Coverage score (0-100) */
-	coverageScore: number;
-	/** Coverage details */
-	coverage: {
-		/** Rule IDs that passed */
-		satisfied: string[];
-		/** Rule IDs that failed */
-		missing: string[];
-		/** All applicable rule IDs */
-		applicable: string[];
-	};
-	/** Lint violations (only for rules with severity !== 'off') */
-	violations: QualityViolation[];
-	/** Summary counts */
-	summary: {
-		errorCount: number;
-		warningCount: number;
-		fixableCount: number;
-	};
-}
-/**
-* Aggregate result for multiple exports.
-*/
-interface AggregateQualityResult {
-	byExport: Map<string, QualityResult>;
-	overall: {
-		coverageScore: number;
-		totalViolations: number;
-		errorCount: number;
-		warningCount: number;
-	};
-}
+import { OpenPkg as OpenPkg3, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 /**
 * An enriched with computed documentation metadata.
 * Extends SpecExport with the `docs` field for coverage analysis.
 */
-type EnrichedExport = SpecExport3 & {
+type EnrichedExport = SpecExport2 & {
 	docs?: EnrichedDocsMetadata;
 };
 /**
-* Extended docs metadata with quality violations.
+* Extended docs metadata.
 */
-type EnrichedDocsMetadata = SpecDocsMetadata & {
-	violations?: QualityViolation[];
-};
+type EnrichedDocsMetadata = SpecDocsMetadata;
 /**
 * An enriched OpenPkg spec with computed documentation metadata.
 * Extends OpenPkg with per-and aggregate coverage data.
@@ -457,21 +523,11 @@ interface EnrichOptions {
 	* Map from ID to drift issues.
 	*/
 	driftByExport?: Map<string, SpecDocDrift2[]>;
-	/**
-	* Quality configuration with rule severities.
-	*/
-	qualityConfig?: QualityConfig;
-	/**
-	* Per-raw JSDoc text for style rule checks.
-	* Map from ID to raw JSDoc string.
-	*/
-	rawJSDocByExport?: Map<string, string>;
 }
 /**
 * Enrich an OpenPkg spec with documentation coverage metadata.
 *
-* This function computes coverage scores using quality rules,
-* detects drift issues, and produces an EnrichedOpenPkg.
+* Computes coverage scores and detects drift issues.
 *
 * @param spec - The pure OpenPkg spec to enrich
 * @param options - Optional enrichment configuration
@@ -484,10 +540,8 @@ interface EnrichOptions {
 * const doccov = new DocCov();
 * const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
 *
-* // Enrich with coverage data
 * const enriched = enrichSpec(spec);
 * console.log(enriched.docs?.coverageScore); // e.g., 85
-* console.log(enriched.docs?.missing); // e.g., ['has-examples']
 * ```
 */
 declare function enrichSpec(spec: OpenPkg3, options?: EnrichOptions): EnrichedOpenPkg;
@@ -670,60 +724,264 @@ interface DocCovReport {
 	exports: Record<string, ExportCoverageData>;
 }
 /**
-* Generate a DocCov report from an OpenPkg spec.
-*
-* @param spec - The pure OpenPkg spec to analyze
-* @returns A DocCov report with coverage analysis
+* Generate a DocCov report from an OpenPkg spec.
+*
+* @param spec - The pure OpenPkg spec to analyze
+* @returns A DocCov report with coverage analysis
+*
+* @example
+* ```ts
+* import { DocCov, generateReport } from '@doccov/sdk';
+*
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* const report = generateReport(spec);
+*
+* console.log(`Coverage: ${report.coverage.score}%`);
+* ```
+*/
+declare function generateReport(spec: OpenPkg4): DocCovReport;
+/**
+* Generate a DocCov report from an already-enriched spec.
+*
+* Use this when you've already called enrichSpec() and want to avoid
+* recomputing coverage data.
+*
+* @param enriched - The enriched OpenPkg spec
+* @returns A DocCov report with coverage analysis
+*/
+declare function generateReportFromEnriched(enriched: EnrichedOpenPkg): DocCovReport;
+/**
+* Load a cached DocCov report from disk.
+*
+* @param reportPath - Path to the report file (defaults to .doccov/report.json)
+* @returns The cached report, or null if not found
+*/
+declare function loadCachedReport(reportPath?: string): DocCovReport | null;
+/**
+* Save a DocCov report to disk.
+*
+* @param report - The report to save
+* @param reportPath - Path to save the report (defaults to .doccov/report.json)
+*/
+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.
 *
-* @example
-* ```ts
-* import { DocCov, generateReport } 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 doccov = new DocCov();
-* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
-* const report = generateReport(spec);
+* @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.
 *
-* console.log(`Coverage: ${report.coverage.score}%`);
-* ```
+* @param values - Array of values (0-100 for coverage)
+* @returns Sparkline string using unicode characters
 */
-declare function generateReport(spec: OpenPkg4): DocCovReport;
+declare function renderSparkline(values: number[]): string;
 /**
-* Generate a DocCov report from an already-enriched spec.
+* Format a delta value with arrow and color indicator.
 *
-* Use this when you've already called enrichSpec() and want to avoid
-* recomputing coverage data.
+* @param delta - Coverage delta (positive = improvement)
+* @returns Formatted delta string
+*/
+declare function formatDelta(delta: number): string;
+/**
+* Prune old snapshots to keep history manageable.
 *
-* @param enriched - The enriched OpenPkg spec
-* @returns A DocCov report with coverage analysis
+* @param cwd - Working directory
+* @param keepCount - Number of snapshots to keep (default: 100)
+* @returns Number of snapshots deleted
 */
-declare function generateReportFromEnriched(enriched: EnrichedOpenPkg): DocCovReport;
+declare function pruneHistory(cwd: string, keepCount?: number): number;
 /**
-* Load a cached DocCov report from disk.
+* Prune snapshots based on tier retention policy.
 *
-* @param reportPath - Path to the report file (defaults to .doccov/report.json)
-* @returns The cached report, or null if not found
+* @param cwd - Working directory
+* @param tier - Retention tier (free: 7d, team: 30d, pro: 90d)
+* @returns Number of snapshots deleted
 */
-declare function loadCachedReport(reportPath?: string): DocCovReport | null;
+declare function pruneByTier(cwd: string, tier: RetentionTier): number;
 /**
-* Save a DocCov report to disk.
+* Load snapshots within a date range.
 *
-* @param report - The report to save
-* @param reportPath - Path to save the report (defaults to .doccov/report.json)
+* @param cwd - Working directory
+* @param days - Number of days to include
+* @returns Filtered snapshots
 */
-declare function saveReport(report: DocCovReport, reportPath?: string): void;
+declare function loadSnapshotsForDays(cwd: string, days: number): CoverageSnapshot[];
 /**
-* Check if a cached report is still valid.
+* Generate weekly summaries from snapshots.
 *
-* A report is considered stale if:
-* - It doesn't exist
-* - The spec version has changed
-* - Source files have been modified since generation
+* @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 reportPath - Path to the report file
-* @param sourceFiles - Source files to check modification times against
-* @returns True if the cached report is still valid
+* @param spec - Current OpenPkg spec
+* @param cwd - Working directory
+* @param options - Analysis options
+* @returns Extended trend analysis
 */
-declare function isCachedReportValid(reportPath?: string, sourceFiles?: string[]): boolean;
+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.
@@ -755,7 +1013,7 @@ declare function hashFiles(filePaths: string[], cwd: string): Record<string, str
 * @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 OpenPkg5 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg6 } from "@openpkg-ts/spec";
 /** Current cache format version */
 declare const CACHE_VERSION = "1.0.0";
 /** Default cache file path */
@@ -790,7 +1048,7 @@ interface SpecCache {
 	/** Analysis configuration that affects output */
 	config: SpecCacheConfig;
 	/** The cached OpenPkg spec */
-	spec: OpenPkg5;
+	spec: OpenPkg6;
 }
 /**
 * Result of cache validation.
@@ -833,7 +1091,7 @@ declare function loadSpecCache(cwd: string): SpecCache | null;
 * @param spec - OpenPkg spec to cache
 * @param context - Cache context with file paths and config
 */
-declare function saveSpecCache(spec: OpenPkg5, context: CacheContext): void;
+declare function saveSpecCache(spec: OpenPkg6, context: CacheContext): void;
 /**
 * Validate if cached spec is still valid.
 *
@@ -865,97 +1123,6 @@ declare function clearSpecCache(cwd: string): boolean;
 */
 declare function getSpecCachePath(cwd: string): string;
 /**
-* Configuration types for DocCov.
-* These types are shared between CLI and API.
-*/
-/**
-* Documentation configuration options.
-*/
-interface DocsConfig {
-	/** Glob patterns for markdown docs to include */
-	include?: string[];
-	/** Glob patterns for markdown docs to exclude */
-	exclude?: string[];
-}
-/**
-* Example validation modes.
-*/
-type ExampleValidationMode = "presence" | "typecheck" | "run";
-/**
-* Check command configuration options.
-*/
-interface CheckConfig {
-	/**
-	* Example validation modes to run.
-	* Can be a single mode, array of modes, or comma-separated string.
-	* - 'presence': Check that @example blocks exist on exports
-	* - 'typecheck': Compile examples with TypeScript
-	* - 'run': Execute examples and validate assertions
-	*/
-	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
-	/** Minimum coverage percentage required (0-100) */
-	minCoverage?: number;
-	/** Maximum drift percentage allowed (0-100) */
-	maxDrift?: number;
-}
-/**
-* Quality rule severity level.
-*/
-type QualitySeverity2 = "error" | "warn" | "off";
-/**
-* Quality rules configuration.
-*/
-interface QualityRulesConfig {
-	/** Rule severity overrides */
-	rules?: Record<string, QualitySeverity2>;
-}
-/**
-* Normalized DocCov configuration.
-* This is the parsed/normalized form used by commands.
-*/
-interface DocCovConfig {
-	/** Export include patterns */
-	include?: string[];
-	/** Export exclude patterns */
-	exclude?: string[];
-	/** Plugins (future) */
-	plugins?: unknown[];
-	/** Documentation configuration */
-	docs?: DocsConfig;
-	/** Check command configuration */
-	check?: CheckConfig;
-	/** Quality rules configuration */
-	quality?: QualityRulesConfig;
-}
-/**
-* Define a DocCov configuration.
-* Helper function for type-safe configuration in doccov.config.ts.
-*
-* @param config - Configuration object
-* @returns The configuration object (for type inference)
-*
-* @example
-* ```typescript
-* // doccov.config.ts
-* import { defineConfig } from '@doccov/sdk';
-*
-* defineConfig({
-*   include: ['MyClass', 'myFunction'],
-*   exclude: ['internal*'],
-*   docs: {
-*     include: ['docs/**\/*.md'],
-*   },
-*   quality: {
-*     rules: {
-*       'has-description': 'error',
-*       'has-examples': 'warn',
-*     },
-*   },
-* });
-* ```
-*/
-declare function defineConfig(config: DocCovConfig): DocCovConfig;
-/**
 * Project detection types for I/O-agnostic project analysis.
 * Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
 */
@@ -1244,7 +1411,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 SpecExport4 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
 interface ExampleTypeError {
 	/** Index of the example in the examples array */
 	exampleIndex: number;
@@ -1367,77 +1534,173 @@ interface ExampleValidationResult {
 * - `typecheck`: type-checks examples (doesn't require presence or run)
 * - `run`: executes examples (doesn't require presence or typecheck)
 */
-declare function validateExamples(exports: SpecExport4[], options: ExampleValidationOptions): Promise<ExampleValidationResult>;
-interface DocCovOptions {
-	includePrivate?: boolean;
-	followImports?: boolean;
-	maxDepth?: number;
-	resolveExternalTypes?: boolean;
-	/** Enable spec caching (default: true) */
-	useCache?: boolean;
-	/** Working directory for cache operations (default: process.cwd()) */
-	cwd?: string;
-}
+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
+* ```
+*/
+declare function parseListFlag(value?: string | string[]): string[] | undefined;
+/**
+* Merge filter options from config and CLI/API overrides.
+*
+* Merge behavior:
+* - Include: CLI values intersect with config values (narrowing)
+* - Exclude: CLI values are added to config values (expanding)
+*
+* @param config - Configuration (from doccov.config.ts)
+* @param overrides - Override filters (from CLI flags or API params)
+* @returns Merged filter options
+*
+* @example
+* ```typescript
+* const config = { include: ['A', 'B', 'C'] };
+* const overrides = { include: ['B', 'C', 'D'] };
+*
+* const resolved = mergeFilters(config, overrides);
+* // resolved.include = ['B', 'C'] (intersection)
+* ```
+*/
+declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
+import { SpecDocDrift as SpecDocDrift4, SpecExport as SpecExport4 } from "@openpkg-ts/spec";
+import * as TS3 from "typescript";
+/**
+* Represents a single parameter in a JSDoc patch
+*/
+interface JSDocParam {
+	name: string;
+	type?: string;
+	description?: string;
+	optional?: boolean;
+}
+/**
+* Represents a return type in a JSDoc patch
+*/
+interface JSDocReturn {
+	type?: string;
+	description?: string;
+}
+/**
+* Represents a generic tag in a JSDoc patch
+*/
+interface JSDocTag {
+	name: string;
+	text: string;
+}
+/**
+* A patchable representation of a JSDoc comment
+*/
+interface JSDocPatch {
+	description?: string;
+	params?: JSDocParam[];
+	returns?: JSDocReturn;
+	examples?: string[];
+	deprecated?: string | false;
+	async?: boolean;
+	type?: string;
+	typeParams?: Array<{
+		name: string;
+		constraint?: string;
+		description?: string;
+	}>;
+	otherTags?: JSDocTag[];
+}
+/**
+* Represents an edit to be applied to a source file
+*/
+interface JSDocEdit {
+	filePath: string;
+	symbolName: string;
+	startLine: number;
+	endLine: number;
+	hasExisting: boolean;
+	existingJSDoc?: string;
+	newJSDoc: string;
+	indent: string;
+}
+/**
+* Result of applying edits to source files
+*/
+interface ApplyEditsResult {
+	filesModified: number;
+	editsApplied: number;
+	errors: Array<{
+		file: string;
+		error: string;
+	}>;
 }
 /**
-* Source of filter options.
+* Parse a JSDoc comment string into a patchable structure
 */
-type FilterSource = "config" | "override" | "combined";
+declare function parseJSDocToPatch(jsDocText: string): JSDocPatch;
 /**
-* Resolved filter options after merging config and overrides.
+* Apply a partial patch to an existing JSDoc patch, preserving unmodified content
 */
-interface ResolvedFilters {
-	/** Include patterns */
-	include?: string[];
-	/** Exclude patterns */
-	exclude?: string[];
-	/** Source of the filters */
-	source?: FilterSource;
-	/** Whether filters were applied from config */
-	fromConfig: boolean;
-	/** Whether filters were applied from overrides */
-	fromOverride: boolean;
-}
+declare function applyPatchToJSDoc(existing: JSDocPatch, updates: Partial<JSDocPatch>): JSDocPatch;
 /**
-* 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
-* ```
+* Serialize a JSDocPatch back to a formatted comment string
 */
-declare function parseListFlag(value?: string | string[]): string[] | undefined;
+declare function serializeJSDoc(patch: JSDocPatch, indent?: string): string;
 /**
-* Merge filter options from config and CLI/API overrides.
-*
-* Merge behavior:
-* - Include: CLI values intersect with config values (narrowing)
-* - Exclude: CLI values are added to config values (expanding)
-*
-* @param config - Configuration (from doccov.config.ts)
-* @param overrides - Override filters (from CLI flags or API params)
-* @returns Merged filter options
-*
-* @example
-* ```typescript
-* const config = { include: ['A', 'B', 'C'] };
-* const overrides = { include: ['B', 'C', 'D'] };
-*
-* const resolved = mergeFilters(config, overrides);
-* // resolved.include = ['B', 'C'] (intersection)
-* ```
+* Find the JSDoc location for a declaration in a source file
 */
-declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
-import { SpecDocDrift as SpecDocDrift4, SpecExport as SpecExport5 } from "@openpkg-ts/spec";
+declare function findJSDocLocation(sourceFile: TS3.SourceFile, symbolName: string, approximateLine?: number): {
+	startLine: number;
+	endLine: number;
+	declarationLine: number;
+	hasExisting: boolean;
+	existingJSDoc?: string;
+	indent: string;
+} | null;
+/**
+* Apply a batch of edits to source files
+*/
+declare function applyEdits(edits: JSDocEdit[]): Promise<ApplyEditsResult>;
+/**
+* Create a TypeScript source file from a file path
+*/
+declare function createSourceFile(filePath: string): TS3.SourceFile;
 /**
 * Types of fixes that can be generated
 */
@@ -1459,11 +1722,11 @@ declare function isFixableDrift(drift: SpecDocDrift4): boolean;
 /**
 * Generate a fix for a single drift issue
 */
-declare function generateFix(drift: SpecDocDrift4, exportEntry: SpecExport5, existingPatch?: JSDocPatch): FixSuggestion | null;
+declare function generateFix(drift: SpecDocDrift4, exportEntry: SpecExport4, existingPatch?: JSDocPatch): FixSuggestion | null;
 /**
 * Generate all fixes for an export's drift issues
 */
-declare function generateFixesForExport(exportEntry: SpecExport5, existingPatch?: JSDocPatch): FixSuggestion[];
+declare function generateFixesForExport(exportEntry: SpecExport4, existingPatch?: JSDocPatch): FixSuggestion[];
 /**
 * Merge multiple fix patches into a single patch
 */
@@ -1475,7 +1738,7 @@ declare function categorizeDrifts(drifts: SpecDocDrift4[]): {
 	fixable: SpecDocDrift4[];
 	nonFixable: SpecDocDrift4[];
 };
-import { OpenPkg as OpenPkg6 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg7 } from "@openpkg-ts/spec";
 /**
 * Parsed components of a GitHub URL.
 */
@@ -1568,7 +1831,16 @@ declare function buildRawUrl(parsed: ParsedGitHubUrl, filePath: string): string;
 * }
 * ```
 */
-declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg6 | null>;
+declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg7 | null>;
+/**
+* Options for fetching a spec from GitHub.
+*/
+interface FetchSpecOptions {
+	/** Git ref (branch or tag). Default: 'main' */
+	ref?: string;
+	/** Path to openpkg.json (for monorepos). Default: 'openpkg.json' */
+	path?: string;
+}
 /**
 * Fetch an OpenPkg spec from a GitHub repository by owner/repo/branch.
 *
@@ -1576,10 +1848,10 @@ declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg6
 *
 * @param owner - Repository owner
 * @param repo - Repository name
-* @param branch - Branch name (default: 'main')
+* @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, branch?: string): Promise<OpenPkg6 | null>;
+declare function fetchSpec(owner: string, repo: string, branchOrOptions?: string | FetchSpecOptions): Promise<OpenPkg7 | null>;
 /**
 * Progress event for installation status updates.
 */
@@ -1838,7 +2110,7 @@ declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNa
 * Get all exports that lack documentation
 */
 declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
-import { CategorizedBreaking, OpenPkg as OpenPkg8, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
+import { CategorizedBreaking, OpenPkg as OpenPkg9, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
 /**
 * Extended spec diff result with docs impact
 */
@@ -1884,7 +2156,7 @@ interface DiffWithDocsOptions {
 * }
 * ```
 */
-declare function diffSpecWithDocs(oldSpec: OpenPkg8, newSpec: OpenPkg8, options?: DiffWithDocsOptions): SpecDiffWithDocs;
+declare function diffSpecWithDocs(oldSpec: OpenPkg9, newSpec: OpenPkg9, options?: DiffWithDocsOptions): SpecDiffWithDocs;
 /**
 * Check if a diff has any docs impact
 */
@@ -2009,6 +2281,11 @@ declare class DocCov {
 	*/
 	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;
@@ -2020,6 +2297,11 @@ declare class DocCov {
 	* Find package.json starting from a directory.
 	*/
 	private findPackageJson;
+	/**
+	* Opportunistically detect Standard Schema exports from compiled modules.
+	* Returns undefined if detection fails or no schemas found (fallback to AST).
+	*/
+	private detectSchemas;
 	private normalizeDiagnostic;
 	private mapSeverity;
 	private normalizeMetadata;
@@ -2027,63 +2309,6 @@ declare class DocCov {
 }
 declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
-import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
-import { SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
-/**
-* Core quality rules - these affect coverage score.
-*/
-declare const CORE_RULES: QualityRule[];
-/**
-* Style rules - these don't affect coverage, only lint.
-*/
-declare const STYLE_RULES: QualityRule[];
-/**
-* All built-in quality rules.
-*/
-declare const BUILTIN_RULES: QualityRule[];
-/**
-* Get rules that affect coverage calculation.
-*/
-declare function getCoverageRules(): QualityRule[];
-/**
-* Get rules applicable to a specific kind.
-*/
-declare function getRulesForKind(kind: SpecExportKind2): QualityRule[];
-/**
-* Get a rule by ID.
-*/
-declare function getRule(id: string): QualityRule | undefined;
-/**
-* Get default configuration with all rule defaults.
-*/
-declare function getDefaultConfig(): Record<string, QualitySeverity>;
-/**
-* Evaluate quality for a single export.
-*
-* @param exp - The to evaluate
-* @param rawJSDoc - Optional raw JSDoc text for regex-based checks
-* @param config - Quality configuration with rule severities
-* @returns Quality result with coverage score and violations
-*/
-declare function evaluateExportQuality(exp: SpecExport6, rawJSDoc?: string, config?: QualityConfig): QualityResult;
-/**
-* Evaluate quality for multiple exports.
-*
-* @param exports - Array of exports with optional raw JSDoc
-* @param config - Quality configuration with rule severities
-* @returns Aggregate result with per-and overall scores
-*/
-declare function evaluateQuality(exports: Array<{
-	export: SpecExport6;
-	rawJSDoc?: string;
-}>, config?: QualityConfig): AggregateQualityResult;
-/**
-* Merge user configuration with defaults.
-*
-* @param userConfig - Partial user configuration
-* @returns Complete configuration with defaults filled in
-*/
-declare function mergeConfig(userConfig: Partial<QualityConfig>): QualityConfig;
 /**
 * Options for resolving a target package/entry point.
 */
@@ -2138,6 +2363,90 @@ interface ResolvedTarget {
 */
 declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
 /**
+* Repository metadata from GitHub API.
+*/
+interface GitHubRepoMetadata {
+	owner: string;
+	repo: string;
+	defaultBranch: string;
+	description: string | null;
+	language: string | null;
+	topics: string[];
+	isPrivate: boolean;
+}
+/**
+* Detected package manager from lockfile.
+*/
+type DetectedPackageManager = "npm" | "yarn" | "pnpm" | "bun" | "unknown";
+/**
+* Workspace/monorepo configuration.
+*/
+interface WorkspaceConfig {
+	isMonorepo: boolean;
+	tool?: "npm" | "yarn" | "pnpm" | "lerna" | "turborepo" | "nx";
+	packages?: string[];
+}
+/**
+* Build hints detected from project files.
+*/
+interface BuildHints {
+	hasTypeScript: boolean;
+	hasWasm: boolean;
+	hasNativeModules: boolean;
+	hasBuildScript: boolean;
+	buildScript?: string;
+	frameworks: string[];
+}
+/**
+* Complete project context for build plan generation.
+*/
+interface GitHubProjectContext {
+	/** Repository metadata */
+	metadata: GitHubRepoMetadata;
+	/** Git ref being analyzed */
+	ref: string;
+	/** Detected package manager */
+	packageManager: DetectedPackageManager;
+	/** Workspace/monorepo configuration */
+	workspace: WorkspaceConfig;
+	/** Build hints from project files */
+	buildHints: BuildHints;
+	/** Raw file contents for AI analysis */
+	files: {
+		packageJson?: string;
+		tsconfigJson?: string;
+		lockfile?: {
+			name: string;
+			content: string;
+		};
+	};
+}
+/**
+* Parse GitHub URL into owner and repo.
+* Uses the richer parseGitHubUrl from github/index.ts, returning null on error.
+*/
+declare function parseGitHubUrl2(url: string): {
+	owner: string;
+	repo: string;
+} | null;
+/**
+* Options for fetching GitHub project context.
+*/
+interface FetchGitHubContextOptions {
+	/** Git ref (branch, tag, or SHA). Defaults to default branch. */
+	ref?: string;
+	/** Auth token for private repos (GitHub App installation token or PAT). */
+	authToken?: string;
+}
+/**
+* Fetch complete project context from GitHub.
+*/
+declare function fetchGitHubContext(repoUrl: string, refOrOptions?: string | FetchGitHubContextOptions): Promise<GitHubProjectContext>;
+/**
+* List packages in a monorepo workspace.
+*/
+declare function listWorkspacePackages(owner: string, repo: string, ref: string, patterns: string[], authToken?: string): Promise<string[]>;
+/**
 * A documentation drift issue in a spec summary.
 */
 interface SummaryDriftIssue {
@@ -2295,81 +2604,6 @@ interface BuildPlanExecutionResult {
 	error?: string;
 }
 /**
-* Repository metadata from GitHub API.
-*/
-interface GitHubRepoMetadata {
-	owner: string;
-	repo: string;
-	defaultBranch: string;
-	description: string | null;
-	language: string | null;
-	topics: string[];
-	isPrivate: boolean;
-}
-/**
-* Detected package manager from lockfile.
-*/
-type DetectedPackageManager = "npm" | "yarn" | "pnpm" | "bun" | "unknown";
-/**
-* Workspace/monorepo configuration.
-*/
-interface WorkspaceConfig {
-	isMonorepo: boolean;
-	tool?: "npm" | "yarn" | "pnpm" | "lerna" | "turborepo" | "nx";
-	packages?: string[];
-}
-/**
-* Build hints detected from project files.
-*/
-interface BuildHints {
-	hasTypeScript: boolean;
-	hasWasm: boolean;
-	hasNativeModules: boolean;
-	hasBuildScript: boolean;
-	buildScript?: string;
-	frameworks: string[];
-}
-/**
-* Complete project context for build plan generation.
-*/
-interface GitHubProjectContext {
-	/** Repository metadata */
-	metadata: GitHubRepoMetadata;
-	/** Git ref being analyzed */
-	ref: string;
-	/** Detected package manager */
-	packageManager: DetectedPackageManager;
-	/** Workspace/monorepo configuration */
-	workspace: WorkspaceConfig;
-	/** Build hints from project files */
-	buildHints: BuildHints;
-	/** Raw file contents for AI analysis */
-	files: {
-		packageJson?: string;
-		tsconfigJson?: string;
-		lockfile?: {
-			name: string;
-			content: string;
-		};
-	};
-}
-/**
-* Parse GitHub URL into owner and repo.
-* Uses the richer parseGitHubUrl from github/index.ts, returning null on error.
-*/
-declare function parseGitHubUrl2(url: string): {
-	owner: string;
-	repo: string;
-} | null;
-/**
-* Fetch complete project context from GitHub.
-*/
-declare function fetchGitHubContext(repoUrl: string, ref?: string): Promise<GitHubProjectContext>;
-/**
-* List packages in a monorepo workspace.
-*/
-declare function listWorkspacePackages(owner: string, repo: string, ref: string, patterns: string[]): Promise<string[]>;
-/**
 * Type-check a single example
 */
 declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
@@ -2377,4 +2611,4 @@ declare function typecheckExample(example: string, packagePath: string, options?
 * Type-check multiple examples
 */
 declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
-export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, readPackageJson, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadCachedReport, listWorkspacePackages, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getSpecCachePath, getRunCommand, getRulesForKind, getRule, getReportPath, getPrimaryBuildScript, getInstallCommand, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, getDefaultConfig, getCoverageRules, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, evaluateQuality, evaluateExportQuality, ensureSpecCoverage, enrichSpec, diffSpecWithDocs, diffHashes, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, 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, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, SandboxFileSystem, STYLE_RULES, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, RuleContext, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, REPORT_VERSION, REPORT_EXTENSIONS, QualityViolation, QualitySeverity2 as QualitySeverity, QualityRulesConfig, QualityRule, QualityResult, QualityConfig, ProjectInfo, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, GitHubRepoMetadata, GitHubProjectContext, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, 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, DetectedPackageManager, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildPlanTarget, BuildPlanStepResult, BuildPlanStep, BuildPlanExecutionResult, BuildPlanEnvironment, BuildPlan, BuildInfo, BuildHints, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };
+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 };