@doccov/sdk 0.15.0 → 0.18.0

package/dist/index.d.ts

@@ -1,3 +1,191 @@
+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;
+}
+/**
+* Pre-detected Standard Schema for a variable export.
+*/
+interface DetectedSchemaEntry {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
+/**
+* Standard JSON Schema Integration
+*
+* Provides runtime detection and extraction of Standard JSON Schema v1 compliant libraries.
+* This enables support for Zod v4.2+, ArkType, Valibot, and other Standard Schema compliant libraries.
+*
+* @see https://github.com/standard-schema/standard-schema
+*/
+/**
+* Standard JSON Schema V1 interface (minimal subset for detection).
+* Full spec: https://github.com/standard-schema/standard-schema
+*/
+interface StandardJSONSchemaV1 {
+	readonly "~standard": {
+		readonly version: 1;
+		readonly vendor: string;
+		readonly jsonSchema: {
+			readonly output: (options?: StandardSchemaOutputOptions) => Record<string, unknown>;
+		};
+	};
+}
+/**
+* Options for Standard Schema JSON output.
+*/
+interface StandardSchemaOutputOptions {
+	/**
+	* Target JSON Schema dialect.
+	* - 'draft-07': JSON Schema Draft 07 (widest compatibility)
+	* - 'draft-2020-12': Latest JSON Schema (best features)
+	* - 'openapi-3.0': OpenAPI 3.0 compatible schema
+	*/
+	target?: "draft-07" | "draft-2020-12" | "openapi-3.0";
+}
+/**
+* Result of Standard Schema extraction.
+*/
+interface StandardSchemaResult {
+	/** The extracted JSON Schema */
+	schema: Record<string, unknown>;
+	/** The vendor library (e.g., 'zod', 'arktype', 'valibot') */
+	vendor: string;
+	/** Standard Schema version */
+	version: number;
+}
+/**
+* Check if a value implements the Standard JSON Schema v1 interface.
+*
+* This enables runtime detection of schema libraries that implement the standard,
+* including Zod v4.2+, ArkType, Valibot, and others.
+*
+* @param value - Value to check
+* @returns True if the value implements StandardJSONSchemaV1
+*
+* @example
+* ```typescript
+* import { isStandardJSONSchema, extractViaStandardSchema } from '@doccov/sdk';
+* import { z } from 'zod';
+*
+* const UserSchema = z.object({
+*   name: z.string(),
+*   age: z.number().min(0),
+* });
+*
+* if (isStandardJSONSchema(UserSchema)) {
+*   const jsonSchema = extractViaStandardSchema(UserSchema);
+*   console.log(jsonSchema);
+*   // { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number', minimum: 0 } } }
+* }
+* ```
+*/
+declare function isStandardJSONSchema(value: unknown): value is StandardJSONSchemaV1;
+/**
+* Extract JSON Schema from a Standard Schema v1 compliant value.
+*
+* @param schema - A value implementing StandardJSONSchemaV1
+* @param options - Extraction options
+* @returns Extracted JSON Schema result with vendor info
+* @throws Error if the value doesn't implement Standard Schema
+*
+* @example
+* ```typescript
+* import { extractViaStandardSchema } from '@doccov/sdk';
+*
+* // Works with any Standard Schema v1 compliant library
+* const result = extractViaStandardSchema(mySchema, { target: 'draft-2020-12' });
+* console.log(result.vendor); // 'zod', 'arktype', 'valibot', etc.
+* console.log(result.schema); // The extracted JSON Schema
+* ```
+*/
+declare function extractViaStandardSchema(schema: StandardJSONSchemaV1, options?: StandardSchemaOutputOptions): StandardSchemaResult;
+/**
+* Try to extract JSON Schema from a value that may or may not implement Standard Schema.
+*
+* @param value - Any value that might be a Standard Schema
+* @param options - Extraction options
+* @returns Extraction result, or null if value doesn't implement Standard Schema
+*
+* @example
+* ```typescript
+* import { tryExtractStandardSchema } from '@doccov/sdk';
+*
+* const result = tryExtractStandardSchema(unknownSchema);
+* if (result) {
+*   console.log(`Extracted ${result.vendor} schema:`, result.schema);
+* }
+* ```
+*/
+declare function tryExtractStandardSchema(value: unknown, options?: StandardSchemaOutputOptions): StandardSchemaResult | null;
+/**
+* Supported Standard Schema vendors and their minimum versions.
+*/
+declare const KNOWN_VENDORS: {
+	readonly zod: {
+		readonly minVersion: "4.2.0";
+		readonly homepage: "https://zod.dev";
+	};
+	readonly arktype: {
+		readonly minVersion: "2.0.0";
+		readonly homepage: "https://arktype.io";
+	};
+	readonly valibot: {
+		readonly minVersion: "1.0.0";
+		readonly homepage: "https://valibot.dev";
+	};
+};
+type KnownVendor = keyof typeof KNOWN_VENDORS;
+/**
+* Context for schema detection.
+*/
+interface SchemaDetectionContext {
+	/** Base directory for resolving modules */
+	baseDir: string;
+	/** Entry file being analyzed */
+	entryFile: string;
+}
+/**
+* Result of runtime schema detection for a module.
+*/
+interface SchemaDetectionResult {
+	/** Map of name to detected Standard Schema */
+	schemas: Map<string, StandardSchemaResult>;
+	/** Errors encountered during detection (non-fatal) */
+	errors: string[];
+}
+/**
+* Detect Standard Schema exports from a compiled module.
+*
+* This function attempts to load the compiled/transpiled version of the entry file
+* and checks each for Standard Schema compliance.
+*
+* @param context - Detection context with paths
+* @returns Detection result with found schemas and any errors
+*
+* @example
+* ```typescript
+* const result = await detectRuntimeSchemas({
+*   baseDir: '/path/to/project',
+*   entryFile: '/path/to/project/dist/index.js',
+* });
+*
+* for (const [name, schema] of result.schemas) {
+*   console.log(`Found ${schema.vendor} schema: ${name}`);
+* }
+* ```
+*/
+declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
+/**
+* Clear the module cache.
+* Useful for testing or when modules may have changed.
+*/
+declare function clearSchemaCache(): void;
 import { DriftCategory, SpecDocDrift, SpecExport } from "@openpkg-ts/spec";
 interface ExampleRunResult {
 	success: boolean;
@@ -334,6 +522,11 @@ type QualitySeverity = "error" | "warn" | "off";
 interface RuleContext {
 	export: SpecExport2;
 	rawJSDoc?: string;
+	/**
+	* Registry of all exported names/IDs for spec-level rules.
+	* Used by rules like no-forgotten-to check if referenced types are exported.
+	*/
+	exportRegistry?: Set<string>;
 }
 /**
 * A violation reported by a quality rule.
@@ -725,6 +918,210 @@ declare function saveReport(report: DocCovReport, reportPath?: string): void;
 */
 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.
 *
@@ -755,7 +1152,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 +1187,7 @@ interface SpecCache {
 	/** Analysis configuration that affects output */
 	config: SpecCacheConfig;
 	/** The cached OpenPkg spec */
-	spec: OpenPkg5;
+	spec: OpenPkg6;
 }
 /**
 * Result of cache validation.
@@ -833,7 +1230,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,6 +1262,160 @@ declare function clearSpecCache(cwd: string): boolean;
 */
 declare function getSpecCachePath(cwd: string): string;
 /**
+* A single CODEOWNERS rule.
+*/
+interface CodeOwnerRule {
+	/** Line number in the CODEOWNERS file (1-indexed) */
+	line: number;
+	/** The glob pattern for matching files */
+	pattern: string;
+	/** List of owners (e.g., @user, @org/team, email) */
+	owners: string[];
+}
+/**
+* Parsed CODEOWNERS file.
+*/
+interface CodeOwnersFile {
+	/** Path to the CODEOWNERS file */
+	filePath: string;
+	/** All parsed rules (in order, later rules take precedence) */
+	rules: CodeOwnerRule[];
+}
+/**
+* Coverage stats for a single owner.
+*/
+interface OwnerCoverageStats {
+	/** The owner identifier */
+	owner: string;
+	/** Total exports owned */
+	totalExports: number;
+	/** Documented exports (has description) */
+	documentedExports: number;
+	/** Coverage percentage */
+	coverageScore: number;
+	/** Exports with drift issues */
+	exportsWithDrift: number;
+	/** Drift percentage */
+	driftScore: number;
+	/** Exports missing @example */
+	missingExamples: number;
+	/** List of undocumented names */
+	undocumentedExports: string[];
+}
+/**
+* Result of ownership analysis.
+*/
+interface OwnershipAnalysisResult {
+	/** Path to the CODEOWNERS file used */
+	codeownersPath: string;
+	/** Stats per owner */
+	byOwner: Map<string, OwnerCoverageStats>;
+	/** Exports with no matching owner */
+	unowned: EnrichedExport[];
+	/** Total exports analyzed */
+	totalExports: number;
+}
+/**
+* Parse a CODEOWNERS file content into rules.
+*/
+declare function parseCodeOwners(content: string): CodeOwnerRule[];
+/**
+* Find and load CODEOWNERS file from a directory.
+*/
+declare function loadCodeOwners(baseDir: string): CodeOwnersFile | null;
+/**
+* Find owners for a file path based on CODEOWNERS rules.
+* Returns the owners from the last matching rule (CODEOWNERS precedence).
+*/
+declare function findOwners(filePath: string, rules: CodeOwnerRule[]): string[];
+/**
+* Attribute owners to exports based on their source file paths.
+*/
+declare function attributeOwners(exports: EnrichedExport[], rules: CodeOwnerRule[], baseDir: string): Map<EnrichedExport, string[]>;
+/**
+* Analyze ownership and coverage breakdown by owner.
+*/
+declare function analyzeOwnership(spec: EnrichedOpenPkg, codeowners: CodeOwnersFile, baseDir: string): OwnershipAnalysisResult;
+/**
+* Options for ownership analysis.
+*/
+interface AnalyzeOwnershipOptions {
+	/** Base directory for the project */
+	baseDir: string;
+}
+/**
+* Load CODEOWNERS and analyze ownership for a spec.
+* Returns null if no CODEOWNERS file is found.
+*/
+declare function analyzeSpecOwnership(spec: EnrichedOpenPkg, options: AnalyzeOwnershipOptions): OwnershipAnalysisResult | null;
+/**
+* Git blame info for a single line.
+*/
+interface BlameInfo {
+	/** Commit hash */
+	commit: string;
+	/** Author name */
+	author: string;
+	/** Author email */
+	email: string;
+	/** Line number (1-indexed) */
+	line: number;
+	/** Timestamp */
+	timestamp: number;
+}
+/**
+* Stats for a single contributor.
+*/
+interface ContributorStats {
+	/** Contributor name */
+	name: string;
+	/** Contributor email */
+	email: string;
+	/** Number of exports this contributor documented */
+	documentedExports: number;
+	/** Names of exports documented by this contributor */
+	exports: string[];
+	/** Number of JSDoc lines authored */
+	linesAuthored: number;
+	/** Most recent documentation contribution */
+	lastContribution: Date | null;
+}
+/**
+* Result of contributor analysis.
+*/
+interface ContributorAnalysisResult {
+	/** Stats per contributor */
+	byContributor: Map<string, ContributorStats>;
+	/** Total documented exports analyzed */
+	totalDocumented: number;
+	/** Exports that couldn't be attributed (no git history) */
+	unattributed: string[];
+}
+/**
+* Get git blame for a file.
+*/
+declare function getFileBlame(filePath: string, cwd: string): BlameInfo[] | null;
+/**
+* Get blame info for specific line range.
+*/
+declare function getBlameForLines(filePath: string, startLine: number, endLine: number, cwd: string): BlameInfo[] | null;
+/**
+* Analyze contributors for documented exports.
+*/
+declare function analyzeContributors(spec: EnrichedOpenPkg, baseDir: string): ContributorAnalysisResult;
+/**
+* Options for contributor analysis.
+*/
+interface AnalyzeContributorsOptions {
+	/** Base directory for the project (must be a git repo) */
+	baseDir: string;
+}
+/**
+* Analyze spec contributors.
+* Returns null if not in a git repository.
+*/
+declare function analyzeSpecContributors(spec: EnrichedOpenPkg, options: AnalyzeContributorsOptions): ContributorAnalysisResult | null;
+/**
 * Configuration types for DocCov.
 * These types are shared between CLI and API.
 */
@@ -910,6 +1461,20 @@ interface QualityRulesConfig {
 	rules?: Record<string, QualitySeverity2>;
 }
 /**
+* Per-path policy configuration.
+* Allows setting different coverage requirements for different parts of the codebase.
+*/
+interface PolicyConfig {
+	/** Glob pattern to match file paths (e.g., "packages/public-api/**") */
+	path: string;
+	/** Minimum coverage percentage required for matched paths (0-100) */
+	minCoverage?: number;
+	/** Maximum drift percentage allowed for matched paths (0-100) */
+	maxDrift?: number;
+	/** Require @example blocks on all matched exports */
+	requireExamples?: boolean;
+}
+/**
 * Normalized DocCov configuration.
 * This is the parsed/normalized form used by commands.
 */
@@ -926,6 +1491,8 @@ interface DocCovConfig {
 	check?: CheckConfig;
 	/** Quality rules configuration */
 	quality?: QualityRulesConfig;
+	/** Per-path coverage policies (Pro tier) */
+	policies?: PolicyConfig[];
 }
 /**
 * Define a DocCov configuration.
@@ -1368,20 +1935,19 @@ interface ExampleValidationResult {
 * - `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 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.
@@ -1475,7 +2041,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 +2134,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 +2151,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 +2413,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 +2459,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 +2584,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 +2600,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,6 +2612,64 @@ declare class DocCov {
 }
 declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
+/**
+* Result of evaluating a single policy.
+*/
+interface PolicyResult {
+	/** The policy that was evaluated */
+	policy: PolicyConfig;
+	/** Exports that matched this policy's path pattern */
+	matchedExports: EnrichedExport[];
+	/** Coverage score for matched exports (0-100) */
+	coverageScore: number;
+	/** Drift score for matched exports (0-100, percentage of exports with drift) */
+	driftScore: number;
+	/** Number of matched exports missing @example */
+	missingExamples: number;
+	/** Whether the policy passed all configured thresholds */
+	passed: boolean;
+	/** Specific failures for this policy */
+	failures: PolicyFailure[];
+}
+/**
+* A specific policy failure.
+*/
+interface PolicyFailure {
+	type: "coverage" | "drift" | "examples";
+	message: string;
+	actual: number;
+	threshold: number;
+}
+/**
+* Result of evaluating all policies.
+*/
+interface PolicyEvaluationResult {
+	/** Results for each policy */
+	results: PolicyResult[];
+	/** Whether all policies passed */
+	allPassed: boolean;
+	/** Total number of policies */
+	totalPolicies: number;
+	/** Number of policies that passed */
+	passedCount: number;
+	/** Number of policies that failed */
+	failedCount: number;
+}
+/**
+* Evaluate a single policy against a set of exports.
+*/
+declare function evaluatePolicy(policy: PolicyConfig, allExports: EnrichedExport[], baseDir?: string): PolicyResult;
+/**
+* Options for evaluating policies.
+*/
+interface EvaluatePoliciesOptions {
+	/** Base directory for resolving relative paths in policies */
+	baseDir?: string;
+}
+/**
+* Evaluate all policies against a spec's exports.
+*/
+declare function evaluatePolicies(policies: PolicyConfig[], spec: EnrichedOpenPkg, options?: EvaluatePoliciesOptions): PolicyEvaluationResult;
 import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
 import { SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
 /**
@@ -2034,6 +2677,11 @@ import { SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
 */
 declare const CORE_RULES: QualityRule[];
 /**
+* TSDoc Strictness rules - match API Extractor's TSDoc compliance.
+* These help maintain consistent, high-quality documentation.
+*/
+declare const TSDOC_RULES: QualityRule[];
+/**
 * Style rules - these don't affect coverage, only lint.
 */
 declare const STYLE_RULES: QualityRule[];
@@ -2063,9 +2711,10 @@ declare function getDefaultConfig(): Record<string, QualitySeverity>;
 * @param exp - The to evaluate
 * @param rawJSDoc - Optional raw JSDoc text for regex-based checks
 * @param config - Quality configuration with rule severities
+* @param exportRegistry - Optional registry of all exported names for spec-level rules
 * @returns Quality result with coverage score and violations
 */
-declare function evaluateExportQuality(exp: SpecExport6, rawJSDoc?: string, config?: QualityConfig): QualityResult;
+declare function evaluateExportQuality(exp: SpecExport6, rawJSDoc?: string, config?: QualityConfig, exportRegistry?: Set<string>): QualityResult;
 /**
 * Evaluate quality for multiple exports.
 *
@@ -2138,6 +2787,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 +3028,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 +3035,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, tryExtractStandardSchema, shouldValidate, serializeJSDoc, saveSpecCache, saveSnapshot, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, renderSparkline, renderApiSurface, readPackageJson, pruneHistory, pruneByTier, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseCodeOwners, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadSnapshotsForDays, loadSnapshots, loadCodeOwners, loadCachedReport, listWorkspacePackages, isStandardJSONSchema, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getTrend, getSpecCachePath, getRunCommand, getRulesForKind, getRule, getReportPath, getPrimaryBuildScript, getInstallCommand, getFileBlame, getExtendedTrend, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, getDefaultConfig, getCoverageRules, getBlameForLines, generateWeeklySummaries, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, formatDelta, findRemovedReferences, findPackageByName, findOwners, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractViaStandardSchema, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, evaluateQuality, evaluatePolicy, evaluatePolicies, evaluateExportQuality, 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, attributeOwners, applyPatchToJSDoc, applyEdits, analyzeSpecOwnership, analyzeSpecContributors, analyzeProject2 as analyzeProject, analyzeOwnership, analyzeFile, analyzeDocsImpact, analyzeContributors, analyze, WorkspacePackage, WorkspaceConfig, WeeklySummary, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, TSDOC_RULES, SummaryDriftIssue, StandardSchemaResult, StandardSchemaOutputOptions, StandardJSONSchemaV1, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, SchemaDetectionResult, SchemaDetectionContext, SandboxFileSystem, STYLE_RULES, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, RuleContext, RetentionTier, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, ReleaseTag, RETENTION_DAYS, REPORT_VERSION, REPORT_EXTENSIONS, QualityViolation, QualitySeverity2 as QualitySeverity, QualityRulesConfig, QualityRule, QualityResult, QualityConfig, ProjectInfo, PresenceResult, PolicyResult, PolicyFailure, PolicyEvaluationResult, PolicyConfig, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OwnershipAnalysisResult, OwnerCoverageStats, OpenPkgSpec, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, KnownVendor, KNOWN_VENDORS, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, HISTORY_DIR, GitHubRepoMetadata, GitHubProjectContext, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, FetchGitHubContextOptions, ExtendedTrendAnalysis, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EvaluatePoliciesOptions, 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, ContributorStats, ContributorAnalysisResult, CommandRunner, CommandResult, CodeOwnersFile, CodeOwnerRule, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildPlanTarget, BuildPlanStepResult, BuildPlanStep, BuildPlanExecutionResult, BuildPlanEnvironment, BuildPlan, BuildInfo, BuildHints, BlameInfo, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOwnershipOptions, AnalyzeOptions, AnalyzeContributorsOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };