@doccov/sdk 0.25.12 → 0.27.0

package/dist/analysis/index.d.ts

@@ -5,13 +5,30 @@ interface DetectedSchemaEntry {
 	schema: Record<string, unknown>;
 	vendor: string;
 }
-import { DocCovSpec } from "@doccov/spec";
+import { DocCovSpec, TypeReferenceLocation } from "@doccov/spec";
 import { OpenPkg } from "@openpkg-ts/spec";
 type OpenPkgSpec = OpenPkg;
+/** Forgotten from extract package (different shape than spec type) */
+interface ExtractForgottenExport {
+	name: string;
+	definedIn?: string;
+	referencedBy: Array<{
+		typeName: string;
+		exportName: string;
+		location: TypeReferenceLocation;
+		path?: string;
+	}>;
+	isExternal: boolean;
+	fix?: string;
+}
 interface BuildDocCovOptions {
 	openpkgPath: string;
 	openpkg: OpenPkgSpec;
 	packagePath?: string;
+	/** Forgotten exports from extraction (for API surface calculation) */
+	forgottenExports?: ExtractForgottenExport[];
+	/** Type names to ignore in API surface calculation */
+	apiSurfaceIgnore?: string[];
 }
 /**
 * Build a DocCov spec from an OpenPkg spec.
@@ -467,6 +484,7 @@ declare function getExportMissing(exp: SpecExport7, doccov: DocCovSpec2): Missin
 declare function isExportFullyDocumented(exp: SpecExport7, doccov: DocCovSpec2): boolean;
 import { DocCovSpec as DocCovSpec3 } from "@doccov/spec";
 import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
+import { ApiSurfaceResult, DocumentationHealth } from "@doccov/spec";
 /**
 * Drift summary with category breakdown.
 */
@@ -572,6 +590,14 @@ interface DocCovReport {
 	* Per-coverage data, keyed by ID.
 	*/
 	exports: Record<string, ExportCoverageData>;
+	/**
+	* API surface analysis (forgotten exports).
+	*/
+	apiSurface?: ApiSurfaceResult;
+	/**
+	* Unified documentation health score.
+	*/
+	health?: DocumentationHealth;
 }
 /**
 * Generate a DocCov report from an OpenPkg spec.
@@ -666,4 +692,4 @@ interface SchemaDetectionResult {
 	noCompiledJsWarning?: boolean;
 }
 declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
-export { saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, pruneByTier, parseAssertions, loadSnapshotsForDays, loadSnapshots, loadCachedReport, isExportFullyDocumented, isCachedReportValid, hasNonAssertionComments, groupDriftsByCategory, getTrend, getExtendedTrend, getExportScore, getExportMissing, getExportDrift, getExportAnalysis, getDriftSummary, generateWeeklySummaries, generateReportFromDocCov, generateReport, formatDriftSummaryLine, formatDelta, ensureSpecCoverage, detectRuntimeSchemas, detectExampleRuntimeErrors, detectExampleAssertionFailures, computeSnapshot, computeExportDrift, computeDrift, categorizeDrift, calculateAggregateCoverage, buildExportRegistry, buildDocCovSpec, WeeklySummary, SchemaDetectionResult, SchemaDetectionContext, RetentionTier, RETENTION_DAYS, OpenPkgSpec, HISTORY_DIR, ExtendedTrendAnalysis, ExportDriftResult, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift, BuildDocCovOptions };
+export { saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, pruneByTier, parseAssertions, loadSnapshotsForDays, loadSnapshots, loadCachedReport, isExportFullyDocumented, isCachedReportValid, hasNonAssertionComments, groupDriftsByCategory, getTrend, getExtendedTrend, getExportScore, getExportMissing, getExportDrift, getExportAnalysis, getDriftSummary, generateWeeklySummaries, generateReportFromDocCov, generateReport, formatDriftSummaryLine, formatDelta, ensureSpecCoverage, detectRuntimeSchemas, detectExampleRuntimeErrors, detectExampleAssertionFailures, computeSnapshot, computeExportDrift, computeDrift, categorizeDrift, calculateAggregateCoverage, buildExportRegistry, buildDocCovSpec, WeeklySummary, SchemaDetectionResult, SchemaDetectionContext, RetentionTier, RETENTION_DAYS, OpenPkgSpec, HISTORY_DIR, ExtractForgottenExport, ExtendedTrendAnalysis, ExportDriftResult, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift, BuildDocCovOptions };

package/dist/analysis/index.js

@@ -38,7 +38,7 @@ import {
   renderSparkline,
   saveReport,
   saveSnapshot
-} from "../shared/chunk-cbe8089a.js";
+} from "../shared/chunk-v62zsv8j.js";
 import"../shared/chunk-esptwrfq.js";
 export {
   saveSnapshot,

package/dist/index.d.ts

@@ -1,10 +1,63 @@
-import { DocCovSpec } from "@doccov/spec";
+import { DocumentationHealth, DriftCategory, MissingDocRule } from "@doccov/spec";
+/**
+* Input data for computing documentation health score.
+*/
+interface HealthInput {
+	/** Coverage score (0-100) */
+	coverageScore: number;
+	/** Number of documented exports */
+	documentedExports: number;
+	/** Total exports analyzed */
+	totalExports: number;
+	/** Missing docs by rule */
+	missingByRule: Record<MissingDocRule, number>;
+	/** Total drift issues */
+	driftIssues: number;
+	/** Fixable drift issues */
+	fixableDrift: number;
+	/** Drift by category */
+	driftByCategory: Record<DriftCategory, number>;
+	/** Example validation results (optional) */
+	examples?: {
+		passed: number;
+		failed: number;
+		total: number;
+	};
+}
+/**
+* Compute unified documentation health score.
+*
+* Formula: health = completeness × (1 - drift_ratio × 0.5)
+* - Max 50% drift penalty
+* - Optional 30% example penalty if examples validated
+*
+* Score thresholds: green 80+, yellow 60-79, red <60
+*/
+declare function computeHealth(input: HealthInput): DocumentationHealth;
+import { DocCovSpec, TypeReferenceLocation } from "@doccov/spec";
 import { OpenPkg } from "@openpkg-ts/spec";
 type OpenPkgSpec = OpenPkg;
+/** Forgotten from extract package (different shape than spec type) */
+interface ExtractForgottenExport {
+	name: string;
+	definedIn?: string;
+	referencedBy: Array<{
+		typeName: string;
+		exportName: string;
+		location: TypeReferenceLocation;
+		path?: string;
+	}>;
+	isExternal: boolean;
+	fix?: string;
+}
 interface BuildDocCovOptions {
 	openpkgPath: string;
 	openpkg: OpenPkgSpec;
 	packagePath?: string;
+	/** Forgotten exports from extraction (for API surface calculation) */
+	forgottenExports?: ExtractForgottenExport[];
+	/** Type names to ignore in API surface calculation */
+	apiSurfaceIgnore?: string[];
 }
 /**
 * Build a DocCov spec from an OpenPkg spec.
@@ -26,19 +79,19 @@ type SpecDocDrift = {
 /**
 * Drift categories group related drift types for progressive disclosure.
 */
-type DriftCategory = "structural" | "semantic" | "example";
+type DriftCategory2 = "structural" | "semantic" | "example";
 /**
 * Maps each drift type to its category.
 */
-declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
+declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory2>;
 /**
 * Human-readable category labels.
 */
-declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
+declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory2, string>;
 /**
 * Category descriptions for help text.
 */
-declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
+declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory2, string>;
 /**
 * Result of computing drift for a single export.
 */
@@ -75,7 +128,7 @@ interface ExportRegistry {
 * Extended drift with category and fixability metadata.
 */
 interface CategorizedDrift extends SpecDocDrift {
-	category: DriftCategory;
+	category: DriftCategory2;
 	fixable: boolean;
 }
 /**
@@ -83,7 +136,7 @@ interface CategorizedDrift extends SpecDocDrift {
 */
 interface DriftSummary {
 	total: number;
-	byCategory: Record<DriftCategory, number>;
+	byCategory: Record<DriftCategory2, number>;
 	fixable: number;
 }
 /**
@@ -119,7 +172,7 @@ declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
 * console.log(grouped.example.length);    // Number of example issues
 * ```
 */
-declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
+declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory2, CategorizedDrift[]>;
 /**
 * Get drift summary counts by category.
 *
@@ -284,7 +337,7 @@ declare function hasNonAssertionComments(code: string): boolean;
 * Detect assertion failures by comparing stdout to expected values.
 */
 declare function detectExampleAssertionFailures(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
-import { DocCovDrift, DocCovSpec as DocCovSpec2, ExportAnalysis, MissingDocRule } from "@doccov/spec";
+import { DocCovDrift, DocCovSpec as DocCovSpec2, ExportAnalysis, MissingDocRule as MissingDocRule2 } from "@doccov/spec";
 import { SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 /**
 * Get the full analysis data for an export.
@@ -317,7 +370,7 @@ declare function getExportDrift(exp: SpecExport7, doccov: DocCovSpec2): DocCovDr
 * @param doccov - The DocCov spec containing analysis data
 * @returns Array of missing rule IDs or empty array if none
 */
-declare function getExportMissing(exp: SpecExport7, doccov: DocCovSpec2): MissingDocRule[];
+declare function getExportMissing(exp: SpecExport7, doccov: DocCovSpec2): MissingDocRule2[];
 /**
 * Check if an has complete documentation.
 *
@@ -328,6 +381,7 @@ declare function getExportMissing(exp: SpecExport7, doccov: DocCovSpec2): Missin
 declare function isExportFullyDocumented(exp: SpecExport7, doccov: DocCovSpec2): boolean;
 import { DocCovSpec as DocCovSpec3 } from "@doccov/spec";
 import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+import { ApiSurfaceResult, DocumentationHealth as DocumentationHealth2 } from "@doccov/spec";
 /**
 * DocCov report schema version.
 */
@@ -387,7 +441,7 @@ interface DriftReportSummary {
 	/**
 	* Count of issues per category.
 	*/
-	byCategory: Record<DriftCategory, number>;
+	byCategory: Record<DriftCategory2, number>;
 	/**
 	* Number of auto-fixable issues.
 	*/
@@ -409,7 +463,7 @@ interface DriftReport {
 	/**
 	* Issues grouped by category.
 	*/
-	byCategory: Record<DriftCategory, CategorizedDrift[]>;
+	byCategory: Record<DriftCategory2, CategorizedDrift[]>;
 	/**
 	* Flat list of all drift issues (backward compatible).
 	*/
@@ -503,6 +557,14 @@ interface DocCovReport {
 	* Per-coverage data, keyed by ID.
 	*/
 	exports: Record<string, ExportCoverageData>;
+	/**
+	* API surface analysis (forgotten exports).
+	*/
+	apiSurface?: ApiSurfaceResult;
+	/**
+	* Unified documentation health score.
+	*/
+	health?: DocumentationHealth2;
 }
 /**
 * Generate a DocCov report from an OpenPkg spec.
@@ -748,6 +810,17 @@ type ExampleValidationMode = "presence" | "typecheck" | "run";
 */
 type SchemaExtractionMode = "static" | "runtime" | "hybrid";
 /**
+* API surface configuration options.
+*/
+interface ApiSurfaceConfig {
+	/** Minimum completeness percentage to pass (0-100) */
+	minCompleteness?: number;
+	/** Warning threshold - warn when below this (0-100) */
+	warnBelow?: number;
+	/** Type names to ignore (won't be flagged as forgotten exports) */
+	ignore?: string[];
+}
+/**
 * Check command configuration options.
 */
 interface CheckConfig {
@@ -759,10 +832,22 @@ interface CheckConfig {
 	* - 'run': Execute examples and validate assertions
 	*/
 	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
-	/** Minimum coverage percentage required (0-100) */
+	/** Minimum health score required (0-100). Unified metric combining coverage + accuracy. */
+	minHealth?: number;
+	/**
+	* Minimum coverage percentage required (0-100)
+	* @deprecated Use `minHealth` instead. Will be removed in next major.
+	*/
 	minCoverage?: number;
-	/** Maximum drift percentage allowed (0-100) */
+	/**
+	* Maximum drift percentage allowed (0-100)
+	* @deprecated Use `minHealth` instead. Drift is now factored into health score.
+	*/
 	maxDrift?: number;
+	/** Minimum API surface completeness percentage (0-100) - deprecated, use apiSurface.minCompleteness */
+	minApiSurface?: number;
+	/** API surface configuration */
+	apiSurface?: ApiSurfaceConfig;
 }
 /**
 * Normalized DocCov configuration.
@@ -849,6 +934,20 @@ interface AnalysisResult {
 	fromCache?: boolean;
 	/** Cache validation details (if cache was checked) */
 	cacheStatus?: CacheValidationResult;
+	/** Forgotten exports (types referenced but not exported) */
+	forgottenExports?: ForgottenExportResult[];
+}
+interface ForgottenExportResult {
+	name: string;
+	definedIn?: string;
+	referencedBy: Array<{
+		typeName: string;
+		exportName: string;
+		location: "return" | "parameter" | "property" | "extends" | "type-parameter";
+		path?: string;
+	}>;
+	isExternal: boolean;
+	fix?: string;
 }
 interface AnalysisMetadata {
 	baseDir: string;
@@ -959,7 +1058,7 @@ interface WorkspacePackage {
 	private: boolean;
 }
 /** Entry point source - where the entry was detected from */
-type EntryPointSource = "types" | "exports" | "main" | "module" | "fallback";
+type EntryPointSource = "types" | "exports" | "main" | "module" | "fallback" | "explicit";
 /** Entry point detection result */
 interface EntryPointInfo {
 	/** Path to entry file (relative to package root) */
@@ -1510,6 +1609,55 @@ declare function categorizeDrifts(drifts: SpecDocDrift[]): {
 	fixable: SpecDocDrift[];
 	nonFixable: SpecDocDrift[];
 };
+import { ApiSurfaceResult as ApiSurfaceResult2 } from "@doccov/spec";
+/** Fix for a forgotten */
+interface ForgottenExportFix {
+	type: "forgotten-export";
+	typeName: string;
+	targetFile: string;
+	exportStatement: string;
+	insertPosition: "append" | {
+		afterLine: number;
+	};
+}
+/** Result of applying forgotten fixes */
+interface ApplyForgottenExportResult {
+	filesModified: number;
+	fixesApplied: number;
+	errors: Array<{
+		file: string;
+		error: string;
+	}>;
+}
+/** Options for generating fixes */
+interface GenerateForgottenExportFixesOptions {
+	/** Base directory for resolving paths */
+	baseDir: string;
+	/** Entry file for the package */
+	entryFile: string;
+}
+/**
+* Generate fixes for forgotten exports.
+* Groups fixes by target file and generates minimal statements.
+*/
+declare function generateForgottenExportFixes(apiSurface: ApiSurfaceResult2, options: GenerateForgottenExportFixesOptions): ForgottenExportFix[];
+/**
+* Group fixes by target file for efficient application.
+*/
+declare function groupFixesByFile(fixes: ForgottenExportFix[]): Map<string, ForgottenExportFix[]>;
+/**
+* Apply forgotten fixes to files.
+* Reads files, finds best insertion points, and applies edits.
+*/
+declare function applyForgottenExportFixes(fixes: ForgottenExportFix[]): Promise<ApplyForgottenExportResult>;
+/**
+* Preview forgotten fixes without applying them.
+* Returns a map of file paths to the changes that would be made.
+*/
+declare function previewForgottenExportFixes(fixes: ForgottenExportFix[]): Map<string, {
+	insertLine: number;
+	statements: string[];
+}>;
 import { SpecDiff } from "@openpkg-ts/spec";
 type MemberChangeType = "added" | "removed" | "signature-changed";
 interface MemberChange {
@@ -1690,6 +1838,22 @@ interface SpecDiffWithDocs extends SpecDiff2 {
 	memberChanges?: MemberChange[];
 	/** Breaking changes categorized by severity (high/medium/low) */
 	categorizedBreaking?: CategorizedBreaking[];
+	/** Coverage score from old spec */
+	oldCoverage: number;
+	/** Coverage score from new spec */
+	newCoverage: number;
+	/** Change in coverage (newCoverage - oldCoverage) */
+	coverageDelta: number;
+	/** Number of new drift issues introduced */
+	driftIntroduced: number;
+	/** Number of drift issues resolved */
+	driftResolved: number;
+	/** New exports that are undocumented */
+	newUndocumented: string[];
+	/** Exports with improved coverage */
+	improvedExports: string[];
+	/** Exports with regressed coverage */
+	regressedExports: string[];
 }
 /**
 * Options for diffSpecWithDocs
@@ -2515,7 +2679,7 @@ interface SpecSummary {
 * ```
 */
 declare function extractSpecSummary(openpkg: OpenPkg8, doccov: DocCovSpec4): SpecSummary;
-import { OpenPkg as OpenPkg_kdpxrtnzlr } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg_tgtzybcxvb } from "@openpkg-ts/spec";
 /**
 * Build Plan types for AI-powered repository scanning.
 */
@@ -2612,7 +2776,7 @@ interface BuildPlanExecutionResult {
 	/** Whether all required steps succeeded */
 	success: boolean;
 	/** Generated OpenPkg spec (if successful) */
-	spec?: OpenPkg_kdpxrtnzlr;
+	spec?: OpenPkg_tgtzybcxvb;
 	/** Results for each step */
 	stepResults: BuildPlanStepResult[];
 	/** Total execution time in milliseconds */
@@ -2620,4 +2784,4 @@ interface BuildPlanExecutionResult {
 	/** Overall error message if failed */
 	error?: string;
 }
-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, loadSnapshots, loadCachedReport, listWorkspacePackages, isStandardJSONSchema, isSchemaType, isFixableDrift, isExportFullyDocumented, isExecutableLang, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getTrend, getSupportedLibraries, getSpecCachePath, getRunCommand, getReportPath, getRegisteredAdapters, getPrimaryBuildScript, getInstallCommand, getExtendedTrend, getExportScore, getExportMissing, getExportDrift, getExportAnalysis, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, generateReportFromDocCov, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, formatDelta, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, findAdapter, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractStandardSchemasFromProject, extractStandardSchemas, extractSpecSummary, extractSchemaType, extractSchemaOutputType, extractPackageSpec, extractImports, extractFunctionCalls, ensureSpecCoverage, diffSpecWithDocs, diffHashes, detectRuntimeSchemas, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeSnapshot, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, calculateAggregateCoverage, buildRawUrl, buildExportRegistry, buildDocCovSpec, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, WorkspaceConfig, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SummaryDriftIssue, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SpecSummary, SpecDocDrift, 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, DriftType, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DriftCategory, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, DetectedSchemaEntry, DetectedPackageManager, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, 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, BuildDocCovOptions, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, ALL_VALIDATIONS };
+export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveSnapshot, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, resolveCompiledPath, renderSparkline, renderApiSurface, readPackageJson, pruneHistory, pruneByTier, previewForgottenExportFixes, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, loadSpecCache, loadSnapshots, loadCachedReport, listWorkspacePackages, isStandardJSONSchema, isSchemaType, isFixableDrift, isExportFullyDocumented, isExecutableLang, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupFixesByFile, groupDriftsByCategory, getUndocumentedExports, getTrend, getSupportedLibraries, getSpecCachePath, getRunCommand, getReportPath, getRegisteredAdapters, getPrimaryBuildScript, getInstallCommand, getExtendedTrend, getExportScore, getExportMissing, getExportDrift, getExportAnalysis, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, generateReportFromDocCov, generateReport, generateForgottenExportFixes, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, formatDelta, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, findAdapter, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractStandardSchemasFromProject, extractStandardSchemas, extractSpecSummary, extractSchemaType, extractSchemaOutputType, extractPackageSpec, extractImports, extractFunctionCalls, ensureSpecCoverage, diffSpecWithDocs, diffHashes, detectRuntimeSchemas, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeSnapshot, computeHealth, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, calculateAggregateCoverage, buildRawUrl, buildExportRegistry, buildDocCovSpec, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyForgottenExportFixes, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, WorkspaceConfig, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SummaryDriftIssue, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SpecSummary, SpecDocDrift, 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, HealthInput, HISTORY_DIR, GitHubRepoMetadata, GitHubProjectContext, GenerateForgottenExportFixesOptions, ForgottenExportResult, ForgottenExportFix, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, FetchGitHubContextOptions, ExtractStandardSchemasOptions, ExtendedTrendAnalysis, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, DriftType, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DriftCategory2 as DriftCategory, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, DetectedSchemaEntry, DetectedPackageManager, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, 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, BuildDocCovOptions, ApplyForgottenExportResult, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, ALL_VALIDATIONS };

package/dist/index.js

@@ -5,6 +5,7 @@ import {
   HISTORY_DIR,
   RETENTION_DAYS,
   applyEdits,
+  applyForgottenExportFixes,
   applyPatchToJSDoc,
   buildDocCovSpec,
   buildExportRegistry,
@@ -13,6 +14,7 @@ import {
   categorizeDrifts,
   computeDrift,
   computeExportDrift,
+  computeHealth,
   computeSnapshot,
   createSourceFile,
   detectExampleAssertionFailures,
@@ -26,6 +28,7 @@ import {
   formatDriftSummaryLine,
   generateFix,
   generateFixesForExport,
+  generateForgottenExportFixes,
   generateReport,
   generateReportFromDocCov,
   getDriftSummary,
@@ -36,6 +39,7 @@ import {
   getExtendedTrend,
   getTrend,
   groupDriftsByCategory,
+  groupFixesByFile,
   hasNonAssertionComments,
   isBuiltInIdentifier,
   isExportFullyDocumented,
@@ -46,6 +50,7 @@ import {
   mergeFixes,
   parseAssertions,
   parseJSDocToPatch,
+  previewForgottenExportFixes,
   pruneByTier,
   pruneHistory,
   renderApiSurface,
@@ -55,7 +60,7 @@ import {
   saveSnapshot,
   serializeJSDoc,
   ts
-} from "./shared/chunk-cbe8089a.js";
+} from "./shared/chunk-v62zsv8j.js";
 import {
   mergeFilters,
   parseListFlag
@@ -290,7 +295,8 @@ async function runAnalysis(input) {
       sourceFiles
     },
     diagnostics,
-    specDiagnostics
+    specDiagnostics,
+    forgottenExports: extractResult.forgottenExports
   };
 }
 
@@ -617,7 +623,7 @@ ${extraction.errors.map((e) => `  - ${e}`).join(`
 `)}`);
     }
   }
-  const result = runAnalysis({
+  const result = await runAnalysis({
     entryFile,
     packageDir,
     content,
@@ -868,7 +874,8 @@ class DocCov {
         ...analysis.specDiagnostics,
         ...filterOutcome.diagnostics
       ],
-      metadata: this.normalizeMetadata(analysis.metadata)
+      metadata: this.normalizeMetadata(analysis.metadata),
+      forgottenExports: analysis.forgottenExports
     };
   }
   async analyzeFileWithDiagnostics(filePath, analyzeOptions = {}) {
@@ -907,7 +914,8 @@ class DocCov {
         ...filterOutcome.diagnostics
       ],
       metadata,
-      fromCache: false
+      fromCache: false,
+      forgottenExports: analysis.forgottenExports
     };
     if (useCache) {
       this.saveToCache(result, resolvedPath, analysis.metadata);
@@ -2487,7 +2495,7 @@ function extractMethodCallsAST(code) {
             if (ts.isIdentifier(objectExpr.expression)) {
               objectName = objectExpr.expression.text;
             }
-          } else if (ts.isThisKeyword(objectExpr)) {
+          } else if (objectExpr.kind === ts.SyntaxKind.ThisKeyword) {
             objectName = "this";
           }
           if (objectName && !isBuiltInIdentifier(objectName)) {
@@ -3105,22 +3113,84 @@ function diffSpecWithDocs(oldSpec, newSpec, options = {}) {
   const baseDiff = diffSpec(oldSpec, newSpec);
   const memberChanges = diffMemberChanges(oldSpec, newSpec, baseDiff.breaking);
   const categorizedBreaking = categorizeBreakingChanges(baseDiff.breaking, oldSpec, newSpec, memberChanges);
+  const { oldCoverage, newCoverage, coverageDelta, improvedExports, regressedExports } = computeCoverageMetrics(oldSpec, newSpec);
+  const { driftIntroduced, driftResolved } = computeDriftMetrics(oldSpec, newSpec);
+  const oldExportIds = new Set(oldSpec.exports?.map((e) => e.id) ?? []);
+  const newUndocumented = (newSpec.exports ?? []).filter((e) => !oldExportIds.has(e.id) && !hasDocumentation(e)).map((e) => e.name);
+  const baseResult = {
+    ...baseDiff,
+    memberChanges: memberChanges.length > 0 ? memberChanges : undefined,
+    categorizedBreaking: categorizedBreaking.length > 0 ? categorizedBreaking : undefined,
+    oldCoverage,
+    newCoverage,
+    coverageDelta,
+    driftIntroduced,
+    driftResolved,
+    newUndocumented,
+    improvedExports,
+    regressedExports
+  };
   if (!options.markdownFiles?.length) {
-    return {
-      ...baseDiff,
-      memberChanges: memberChanges.length > 0 ? memberChanges : undefined,
-      categorizedBreaking: categorizedBreaking.length > 0 ? categorizedBreaking : undefined
-    };
+    return baseResult;
   }
   const newExportNames = newSpec.exports?.map((e) => e.name) ?? [];
   const docsImpact = analyzeDocsImpact(baseDiff, options.markdownFiles, newExportNames, memberChanges);
   return {
-    ...baseDiff,
-    docsImpact,
-    memberChanges: memberChanges.length > 0 ? memberChanges : undefined,
-    categorizedBreaking: categorizedBreaking.length > 0 ? categorizedBreaking : undefined
+    ...baseResult,
+    docsImpact
   };
 }
+function computeCoverageMetrics(oldSpec, newSpec) {
+  const oldCoverage = getSpecCoverage(oldSpec);
+  const newCoverage = getSpecCoverage(newSpec);
+  const coverageDelta = newCoverage - oldCoverage;
+  const oldExportScores = new Map;
+  for (const exp of oldSpec.exports ?? []) {
+    const enriched = exp;
+    oldExportScores.set(exp.id, enriched.docs?.coverageScore ?? 0);
+  }
+  const improvedExports = [];
+  const regressedExports = [];
+  for (const exp of newSpec.exports ?? []) {
+    const enriched = exp;
+    const oldScore = oldExportScores.get(exp.id);
+    if (oldScore === undefined)
+      continue;
+    const newScore = enriched.docs?.coverageScore ?? 0;
+    if (newScore > oldScore) {
+      improvedExports.push(exp.name);
+    } else if (newScore < oldScore) {
+      regressedExports.push(exp.name);
+    }
+  }
+  return { oldCoverage, newCoverage, coverageDelta, improvedExports, regressedExports };
+}
+function getSpecCoverage(spec) {
+  const exports = spec.exports ?? [];
+  if (exports.length === 0)
+    return 0;
+  const totalScore = exports.reduce((sum, exp) => {
+    const enriched = exp;
+    return sum + (enriched.docs?.coverageScore ?? 0);
+  }, 0);
+  return Math.round(totalScore / exports.length);
+}
+function computeDriftMetrics(oldSpec, newSpec) {
+  const oldDriftCount = countDriftIssues(oldSpec);
+  const newDriftCount = countDriftIssues(newSpec);
+  const driftIntroduced = Math.max(0, newDriftCount - oldDriftCount);
+  const driftResolved = Math.max(0, oldDriftCount - newDriftCount);
+  return { driftIntroduced, driftResolved };
+}
+function countDriftIssues(spec) {
+  return (spec.exports ?? []).reduce((sum, exp) => {
+    const enriched = exp;
+    return sum + (enriched.docs?.drift?.length ?? 0);
+  }, 0);
+}
+function hasDocumentation(exp) {
+  return Boolean(exp.docs?.description || exp.description);
+}
 function hasDocsImpact(diff) {
   if (!diff.docsImpact)
     return false;
@@ -3575,6 +3645,7 @@ export {
   readPackageJson,
   pruneHistory,
   pruneByTier,
+  previewForgottenExportFixes,
   parseGitHubUrl2 as parseScanGitHubUrl,
   parseMarkdownFiles,
   parseMarkdownFile,
@@ -3601,6 +3672,7 @@ export {
   hasNonAssertionComments,
   hasDocsImpact,
   hasDocsForExport,
+  groupFixesByFile,
   groupDriftsByCategory,
   getUndocumentedExports,
   getTrend,
@@ -3622,6 +3694,7 @@ export {
   getDiffReportPath,
   generateReportFromDocCov,
   generateReport,
+  generateForgottenExportFixes,
   generateFixesForExport,
   generateFix,
   formatPackageList,
@@ -3658,6 +3731,7 @@ export {
   createSourceFile,
   createNodeCommandRunner,
   computeSnapshot,
+  computeHealth,
   computeExportDrift,
   computeDrift,
   clearSpecCache,
@@ -3671,6 +3745,7 @@ export {
   buildCloneUrl,
   blockReferencesExport,
   applyPatchToJSDoc,
+  applyForgottenExportFixes,
   applyEdits,
   analyzeProject,
   analyzeFile,

package/dist/shared/{chunk-cbe8089a.js → chunk-v62zsv8j.js}

@@ -3,6 +3,57 @@ import {
   REPORT_VERSION
 } from "./chunk-esptwrfq.js";
 
+// src/analysis/health.ts
+function computeHealth(input) {
+  const {
+    coverageScore,
+    documentedExports,
+    totalExports,
+    missingByRule,
+    driftIssues,
+    fixableDrift,
+    driftByCategory,
+    examples
+  } = input;
+  const completenessScore = coverageScore;
+  const driftRatio = documentedExports > 0 ? driftIssues / documentedExports : 0;
+  const driftPenalty = Math.min(driftRatio * 0.5, 0.5);
+  const accuracyScore = Math.round((1 - driftPenalty) * 100);
+  let exampleScore;
+  if (examples && examples.total > 0) {
+    exampleScore = Math.round(examples.passed / examples.total * 100);
+  }
+  let health = completenessScore * (1 - driftPenalty);
+  if (exampleScore !== undefined) {
+    const examplePenalty = (100 - exampleScore) / 100 * 0.3;
+    health = health * (1 - examplePenalty);
+  }
+  const result = {
+    score: Math.round(health),
+    completeness: {
+      score: Math.round(completenessScore),
+      documented: documentedExports,
+      total: totalExports,
+      missing: missingByRule
+    },
+    accuracy: {
+      score: accuracyScore,
+      issues: driftIssues,
+      fixable: fixableDrift,
+      byCategory: driftByCategory
+    }
+  };
+  if (examples) {
+    result.examples = {
+      score: exampleScore,
+      passed: examples.passed,
+      failed: examples.failed,
+      total: examples.total
+    };
+  }
+  return result;
+}
+
 // src/fix/deterministic-fixes.ts
 var FIXABLE_DRIFT_TYPES = new Set([
   "param-mismatch",
@@ -797,6 +848,123 @@ function createSourceFile(filePath) {
   const content = fs.readFileSync(filePath, "utf-8");
   return ts.createSourceFile(path.basename(filePath), content, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
 }
+
+// src/fix/forgotten-exports.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+function generateForgottenExportFixes(apiSurface, options) {
+  const { baseDir, entryFile } = options;
+  const fixes = [];
+  for (const forgotten of apiSurface.forgotten) {
+    if (forgotten.isExternal)
+      continue;
+    if (!forgotten.fix)
+      continue;
+    const targetFile = forgotten.fix.targetFile ? path2.resolve(baseDir, forgotten.fix.targetFile) : path2.resolve(baseDir, entryFile);
+    fixes.push({
+      type: "forgotten-export",
+      typeName: forgotten.name,
+      targetFile,
+      exportStatement: forgotten.fix.exportStatement,
+      insertPosition: "append"
+    });
+  }
+  return fixes;
+}
+function groupFixesByFile(fixes) {
+  const grouped = new Map;
+  for (const fix of fixes) {
+    const existing = grouped.get(fix.targetFile) ?? [];
+    existing.push(fix);
+    grouped.set(fix.targetFile, existing);
+  }
+  return grouped;
+}
+async function applyForgottenExportFixes(fixes) {
+  const result = {
+    filesModified: 0,
+    fixesApplied: 0,
+    errors: []
+  };
+  const grouped = groupFixesByFile(fixes);
+  for (const [filePath, fileFixes] of grouped) {
+    try {
+      if (!fs2.existsSync(filePath)) {
+        result.errors.push({
+          file: filePath,
+          error: "File not found"
+        });
+        continue;
+      }
+      const content = await fs2.promises.readFile(filePath, "utf8");
+      const lines = content.split(`
+`);
+      const insertLine = findBestInsertionPoint(lines, fileFixes);
+      const statements = fileFixes.map((f) => f.exportStatement);
+      const uniqueStatements = [...new Set(statements)];
+      const newContent = insertExportStatements(lines, insertLine, uniqueStatements);
+      await fs2.promises.writeFile(filePath, newContent, "utf8");
+      result.filesModified++;
+      result.fixesApplied += uniqueStatements.length;
+    } catch (err) {
+      result.errors.push({
+        file: filePath,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return result;
+}
+function findBestInsertionPoint(lines, _fixes) {
+  let lastExportLine = -1;
+  let lastReExportLine = -1;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.match(/^export\s+(\*|\{[^}]*\})\s+from\s+['"]/)) {
+      lastReExportLine = i;
+    }
+    if (line.startsWith("export ")) {
+      lastExportLine = i;
+    }
+  }
+  if (lastReExportLine >= 0) {
+    return lastReExportLine + 1;
+  }
+  if (lastExportLine >= 0) {
+    return lastExportLine + 1;
+  }
+  return lines.length;
+}
+function insertExportStatements(lines, insertLine, statements) {
+  const newLines = [...lines];
+  const needsBlankBefore = insertLine > 0 && newLines[insertLine - 1]?.trim() !== "" && !newLines[insertLine - 1]?.trim().startsWith("export");
+  const insertBlock = statements.join(`
+`);
+  if (needsBlankBefore) {
+    newLines.splice(insertLine, 0, "", insertBlock);
+  } else {
+    newLines.splice(insertLine, 0, insertBlock);
+  }
+  return newLines.join(`
+`);
+}
+function previewForgottenExportFixes(fixes) {
+  const previews = new Map;
+  const grouped = groupFixesByFile(fixes);
+  for (const [filePath, fileFixes] of grouped) {
+    try {
+      if (!fs2.existsSync(filePath))
+        continue;
+      const content = fs2.readFileSync(filePath, "utf8");
+      const lines = content.split(`
+`);
+      const insertLine = findBestInsertionPoint(lines, fileFixes);
+      const statements = [...new Set(fileFixes.map((f) => f.exportStatement))];
+      previews.set(filePath, { insertLine, statements });
+    } catch {}
+  }
+  return previews;
+}
 // src/analysis/drift/example-drift.ts
 import ts2 from "typescript";
 
@@ -2019,7 +2187,7 @@ function computeExportDrift(entry, registry) {
 // src/analysis/doccov-builder.ts
 import { DRIFT_CATEGORIES } from "@doccov/spec";
 function buildDocCovSpec(options) {
-  const { openpkg, openpkgPath } = options;
+  const { openpkg, openpkgPath, forgottenExports, apiSurfaceIgnore } = options;
   const registry = buildExportRegistry(openpkg);
   const exports = {};
   let totalScore = 0;
@@ -2062,8 +2230,18 @@ function buildDocCovSpec(options) {
     }
   }
   const exportCount = openpkg.exports?.length ?? 0;
+  const coverageScore = exportCount > 0 ? Math.round(totalScore / exportCount) : 100;
+  const health = computeHealth({
+    coverageScore,
+    documentedExports: documentedCount,
+    totalExports: exportCount,
+    missingByRule,
+    driftIssues: totalDrift,
+    fixableDrift,
+    driftByCategory
+  });
   const summary = {
-    score: exportCount > 0 ? Math.round(totalScore / exportCount) : 100,
+    score: coverageScore,
     totalExports: exportCount,
     documentedExports: documentedCount,
     missingByRule,
@@ -2071,8 +2249,10 @@ function buildDocCovSpec(options) {
       total: totalDrift,
       fixable: fixableDrift,
       byCategory: driftByCategory
-    }
+    },
+    health
   };
+  const apiSurface = computeApiSurface(forgottenExports, openpkg.types?.length ?? 0, apiSurfaceIgnore);
   return {
     doccov: "1.0.0",
     source: {
@@ -2083,7 +2263,33 @@ function buildDocCovSpec(options) {
     },
     generatedAt: new Date().toISOString(),
     summary,
-    exports
+    exports,
+    ...apiSurface ? { apiSurface } : {}
+  };
+}
+function computeApiSurface(forgottenExports, exportedTypesCount, ignoreList) {
+  if (!forgottenExports)
+    return;
+  const ignoreSet = new Set(ignoreList ?? []);
+  const filteredExports = forgottenExports.filter((f) => !ignoreSet.has(f.name));
+  const forgotten = filteredExports.map((f) => ({
+    name: f.name,
+    definedIn: f.definedIn ? { file: f.definedIn } : undefined,
+    referencedBy: f.referencedBy.map((r) => ({
+      exportName: r.exportName,
+      location: r.location
+    })),
+    isExternal: f.isExternal,
+    fix: f.fix ? { targetFile: f.definedIn ?? "index.ts", exportStatement: f.fix } : undefined
+  }));
+  const forgottenCount = forgotten.length;
+  const totalReferenced = exportedTypesCount + forgottenCount;
+  const completeness = totalReferenced > 0 ? Math.round(exportedTypesCount / totalReferenced * 100) : 100;
+  return {
+    totalReferenced,
+    exported: exportedTypesCount,
+    forgotten,
+    completeness
   };
 }
 function computeExportCoverage(exp) {
@@ -2141,13 +2347,14 @@ function computeExportCoverage(exp) {
 }
 function toCategorizedDrift(drift) {
   const driftType = drift.type;
+  const specDrift = { ...drift, type: driftType };
   return {
     type: driftType,
     target: drift.target,
     issue: drift.issue,
     suggestion: drift.suggestion,
     category: DRIFT_CATEGORIES[driftType],
-    fixable: isFixableDrift(drift)
+    fixable: isFixableDrift(specDrift)
   };
 }
 
@@ -2285,8 +2492,8 @@ function isExportFullyDocumented(exp, doccov) {
 }
 
 // src/analysis/report.ts
-import * as fs2 from "node:fs";
-import * as path2 from "node:path";
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
 function generateReport(spec, openpkgPath = "openpkg.json") {
   const doccov = buildDocCovSpec({ openpkg: spec, openpkgPath });
   return generateReportFromDocCov(spec, doccov);
@@ -2339,28 +2546,29 @@ function generateReportFromDocCov(openpkg, doccov) {
       version: openpkg.meta.version
     },
     coverage,
-    exports: exportsData
+    exports: exportsData,
+    apiSurface: doccov.apiSurface
   };
 }
 function loadCachedReport(reportPath = DEFAULT_REPORT_PATH) {
   try {
-    const fullPath = path2.resolve(reportPath);
-    if (!fs2.existsSync(fullPath)) {
+    const fullPath = path3.resolve(reportPath);
+    if (!fs3.existsSync(fullPath)) {
       return null;
     }
-    const content = fs2.readFileSync(fullPath, "utf-8");
+    const content = fs3.readFileSync(fullPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
 function saveReport(report, reportPath = DEFAULT_REPORT_PATH) {
-  const fullPath = path2.resolve(reportPath);
-  const dir = path2.dirname(fullPath);
-  if (!fs2.existsSync(dir)) {
-    fs2.mkdirSync(dir, { recursive: true });
+  const fullPath = path3.resolve(reportPath);
+  const dir = path3.dirname(fullPath);
+  if (!fs3.existsSync(dir)) {
+    fs3.mkdirSync(dir, { recursive: true });
   }
-  fs2.writeFileSync(fullPath, JSON.stringify(report, null, 2));
+  fs3.writeFileSync(fullPath, JSON.stringify(report, null, 2));
 }
 function isCachedReportValid(reportPath = DEFAULT_REPORT_PATH, sourceFiles = []) {
   const report = loadCachedReport(reportPath);
@@ -2370,7 +2578,7 @@ function isCachedReportValid(reportPath = DEFAULT_REPORT_PATH, sourceFiles = [])
   const reportTime = new Date(report.generatedAt).getTime();
   for (const file of sourceFiles) {
     try {
-      const stat = fs2.statSync(file);
+      const stat = fs3.statSync(file);
       if (stat.mtimeMs > reportTime) {
         return false;
       }
@@ -2559,8 +2767,8 @@ function renderApiSurface(spec) {
 
 // src/extract/schema/standard-schema.ts
 import { spawn } from "node:child_process";
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
+import * as fs4 from "node:fs";
+import * as path4 from "node:path";
 function isStandardJSONSchema(obj) {
   if (typeof obj !== "object" || obj === null)
     return false;
@@ -2667,16 +2875,16 @@ async function extract() {
 extract();
 `;
 function resolveCompiledPath(tsPath, baseDir) {
-  const relativePath = path3.relative(baseDir, tsPath);
+  const relativePath = path4.relative(baseDir, tsPath);
   const withoutExt = relativePath.replace(/\.tsx?$/, "");
   const candidates = [
-    path3.join(baseDir, `${withoutExt}.js`),
-    path3.join(baseDir, "dist", `${withoutExt.replace(/^src\//, "")}.js`),
-    path3.join(baseDir, "build", `${withoutExt.replace(/^src\//, "")}.js`),
-    path3.join(baseDir, "lib", `${withoutExt.replace(/^src\//, "")}.js`)
+    path4.join(baseDir, `${withoutExt}.js`),
+    path4.join(baseDir, "dist", `${withoutExt.replace(/^src\//, "")}.js`),
+    path4.join(baseDir, "build", `${withoutExt.replace(/^src\//, "")}.js`),
+    path4.join(baseDir, "lib", `${withoutExt.replace(/^src\//, "")}.js`)
   ];
   for (const candidate of candidates) {
-    if (fs3.existsSync(candidate)) {
+    if (fs4.existsSync(candidate)) {
       return candidate;
     }
   }
@@ -2688,11 +2896,11 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
     schemas: new Map,
     errors: []
   };
-  if (!fs3.existsSync(compiledJsPath)) {
+  if (!fs4.existsSync(compiledJsPath)) {
     result.errors.push(`Compiled JS not found: ${compiledJsPath}`);
     return result;
   }
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const child = spawn("node", ["-e", WORKER_SCRIPT, compiledJsPath, target], {
       timeout,
       stdio: ["ignore", "pipe", "pipe"]
@@ -2708,14 +2916,14 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
     child.on("close", (code) => {
       if (code !== 0) {
         result.errors.push(`Extraction process failed: ${stderr || `exit code ${code}`}`);
-        resolve2(result);
+        resolve3(result);
         return;
       }
       try {
         const parsed = JSON.parse(stdout);
         if (!parsed.success) {
           result.errors.push(`Extraction failed: ${parsed.error}`);
-          resolve2(result);
+          resolve3(result);
           return;
         }
         for (const item of parsed.results) {
@@ -2729,11 +2937,11 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
       } catch (e) {
         result.errors.push(`Failed to parse extraction output: ${e}`);
       }
-      resolve2(result);
+      resolve3(result);
     });
     child.on("error", (err) => {
       result.errors.push(`Subprocess error: ${err.message}`);
-      resolve2(result);
+      resolve3(result);
     });
   });
 }
@@ -2774,8 +2982,8 @@ async function detectRuntimeSchemas(context) {
 }
 
 // src/analysis/history.ts
-import * as fs4 from "node:fs";
-import * as path4 from "node:path";
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
 var HISTORY_DIR = ".doccov/history";
 var RETENTION_DAYS = {
   free: 7,
@@ -2813,24 +3021,24 @@ function computeSnapshot(spec, options) {
   };
 }
 function saveSnapshot(snapshot, cwd) {
-  const historyDir = path4.resolve(cwd, HISTORY_DIR);
-  if (!fs4.existsSync(historyDir)) {
-    fs4.mkdirSync(historyDir, { recursive: true });
+  const historyDir = path5.resolve(cwd, HISTORY_DIR);
+  if (!fs5.existsSync(historyDir)) {
+    fs5.mkdirSync(historyDir, { recursive: true });
   }
   const filename = getSnapshotFilename(new Date(snapshot.timestamp));
-  const filepath = path4.join(historyDir, filename);
-  fs4.writeFileSync(filepath, JSON.stringify(snapshot, null, 2));
+  const filepath = path5.join(historyDir, filename);
+  fs5.writeFileSync(filepath, JSON.stringify(snapshot, null, 2));
 }
 function loadSnapshots(cwd) {
-  const historyDir = path4.resolve(cwd, HISTORY_DIR);
-  if (!fs4.existsSync(historyDir)) {
+  const historyDir = path5.resolve(cwd, HISTORY_DIR);
+  if (!fs5.existsSync(historyDir)) {
     return [];
   }
-  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const files = fs5.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
   const snapshots = [];
   for (const file of files) {
     try {
-      const content = fs4.readFileSync(path4.join(historyDir, file), "utf-8");
+      const content = fs5.readFileSync(path5.join(historyDir, file), "utf-8");
       snapshots.push(JSON.parse(content));
     } catch {}
   }
@@ -2870,15 +3078,15 @@ function formatDelta(delta) {
   return "→0%";
 }
 function pruneHistory(cwd, keepCount = 100) {
-  const historyDir = path4.resolve(cwd, HISTORY_DIR);
-  if (!fs4.existsSync(historyDir)) {
+  const historyDir = path5.resolve(cwd, HISTORY_DIR);
+  if (!fs5.existsSync(historyDir)) {
     return 0;
   }
-  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const files = fs5.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
   const toDelete = files.slice(keepCount);
   for (const file of toDelete) {
     try {
-      fs4.unlinkSync(path4.join(historyDir, file));
+      fs5.unlinkSync(path5.join(historyDir, file));
     } catch {}
   }
   return toDelete.length;
@@ -2887,20 +3095,20 @@ function pruneByTier(cwd, tier) {
   const retentionDays = RETENTION_DAYS[tier];
   const cutoffDate = new Date;
   cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
-  const historyDir = path4.resolve(cwd, HISTORY_DIR);
-  if (!fs4.existsSync(historyDir)) {
+  const historyDir = path5.resolve(cwd, HISTORY_DIR);
+  if (!fs5.existsSync(historyDir)) {
     return 0;
   }
-  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json"));
+  const files = fs5.readdirSync(historyDir).filter((f) => f.endsWith(".json"));
   let deleted = 0;
   for (const file of files) {
     try {
-      const filepath = path4.join(historyDir, file);
-      const content = fs4.readFileSync(filepath, "utf-8");
+      const filepath = path5.join(historyDir, file);
+      const content = fs5.readFileSync(filepath, "utf-8");
       const snapshot = JSON.parse(content);
       const snapshotDate = new Date(snapshot.timestamp);
       if (snapshotDate < cutoffDate) {
-        fs4.unlinkSync(filepath);
+        fs5.unlinkSync(filepath);
         deleted++;
       }
     } catch {}
@@ -3000,4 +3208,4 @@ function getExtendedTrend(spec, cwd, options) {
   };
 }
 
-export { isFixableDrift, generateFix, generateFixesForExport, mergeFixes, categorizeDrifts, ts, parseJSDocToPatch, applyPatchToJSDoc, serializeJSDoc, findJSDocLocation, applyEdits, createSourceFile, isBuiltInIdentifier, detectExampleRuntimeErrors, parseAssertions, hasNonAssertionComments, detectExampleAssertionFailures, buildExportRegistry, computeDrift, computeExportDrift, buildDocCovSpec, DRIFT_CATEGORIES2 as DRIFT_CATEGORIES, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, categorizeDrift, groupDriftsByCategory, getDriftSummary, formatDriftSummaryLine, calculateAggregateCoverage, ensureSpecCoverage, getExportAnalysis, getExportScore, getExportDrift, getExportMissing, isExportFullyDocumented, generateReport, generateReportFromDocCov, loadCachedReport, saveReport, isCachedReportValid, renderApiSurface, isStandardJSONSchema, resolveCompiledPath, extractStandardSchemas, extractStandardSchemasFromProject, detectRuntimeSchemas, HISTORY_DIR, RETENTION_DAYS, computeSnapshot, saveSnapshot, loadSnapshots, getTrend, renderSparkline, formatDelta, pruneHistory, pruneByTier, loadSnapshotsForDays, generateWeeklySummaries, getExtendedTrend };
+export { computeHealth, isFixableDrift, generateFix, generateFixesForExport, mergeFixes, categorizeDrifts, ts, parseJSDocToPatch, applyPatchToJSDoc, serializeJSDoc, findJSDocLocation, applyEdits, createSourceFile, generateForgottenExportFixes, groupFixesByFile, applyForgottenExportFixes, previewForgottenExportFixes, isBuiltInIdentifier, detectExampleRuntimeErrors, parseAssertions, hasNonAssertionComments, detectExampleAssertionFailures, buildExportRegistry, computeDrift, computeExportDrift, buildDocCovSpec, DRIFT_CATEGORIES2 as DRIFT_CATEGORIES, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, categorizeDrift, groupDriftsByCategory, getDriftSummary, formatDriftSummaryLine, calculateAggregateCoverage, ensureSpecCoverage, getExportAnalysis, getExportScore, getExportDrift, getExportMissing, isExportFullyDocumented, generateReport, generateReportFromDocCov, loadCachedReport, saveReport, isCachedReportValid, renderApiSurface, isStandardJSONSchema, resolveCompiledPath, extractStandardSchemas, extractStandardSchemasFromProject, detectRuntimeSchemas, HISTORY_DIR, RETENTION_DAYS, computeSnapshot, saveSnapshot, loadSnapshots, getTrend, renderSparkline, formatDelta, pruneHistory, pruneByTier, loadSnapshotsForDays, generateWeeklySummaries, getExtendedTrend };

package/dist/types/index.d.ts

@@ -24,6 +24,17 @@ type ExampleValidationMode = "presence" | "typecheck" | "run";
 */
 type SchemaExtractionMode = "static" | "runtime" | "hybrid";
 /**
+* API surface configuration options.
+*/
+interface ApiSurfaceConfig {
+	/** Minimum completeness percentage to pass (0-100) */
+	minCompleteness?: number;
+	/** Warning threshold - warn when below this (0-100) */
+	warnBelow?: number;
+	/** Type names to ignore (won't be flagged as forgotten exports) */
+	ignore?: string[];
+}
+/**
 * Check command configuration options.
 */
 interface CheckConfig {
@@ -35,10 +46,22 @@ interface CheckConfig {
 	* - 'run': Execute examples and validate assertions
 	*/
 	examples?: ExampleValidationMode | ExampleValidationMode[] | string;
-	/** Minimum coverage percentage required (0-100) */
+	/** Minimum health score required (0-100). Unified metric combining coverage + accuracy. */
+	minHealth?: number;
+	/**
+	* Minimum coverage percentage required (0-100)
+	* @deprecated Use `minHealth` instead. Will be removed in next major.
+	*/
 	minCoverage?: number;
-	/** Maximum drift percentage allowed (0-100) */
+	/**
+	* Maximum drift percentage allowed (0-100)
+	* @deprecated Use `minHealth` instead. Drift is now factored into health score.
+	*/
 	maxDrift?: number;
+	/** Minimum API surface completeness percentage (0-100) - deprecated, use apiSurface.minCompleteness */
+	minApiSurface?: number;
+	/** API surface configuration */
+	apiSurface?: ApiSurfaceConfig;
 }
 /**
 * Normalized DocCov configuration.
@@ -155,6 +178,7 @@ interface CategorizedDrift extends SpecDocDrift {
 	category: DriftCategory;
 	fixable: boolean;
 }
+import { ApiSurfaceResult, DocumentationHealth } from "@doccov/spec";
 /**
 * DocCov report schema version.
 */
@@ -330,5 +354,13 @@ interface DocCovReport {
 	* Per-coverage data, keyed by ID.
 	*/
 	exports: Record<string, ExportCoverageData>;
+	/**
+	* API surface analysis (forgotten exports).
+	*/
+	apiSurface?: ApiSurfaceResult;
+	/**
+	* Unified documentation health score.
+	*/
+	health?: DocumentationHealth;
 }
 export { parseListFlag, mergeFilters, getReportPath, getDiffReportPath, ResolvedFilters, ReleaseTag, REPORT_VERSION, REPORT_EXTENSIONS, FilterSource, FilterOptions, ExportCoverageData, DriftReportSummary, DriftReport, DocCovReport, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.25.12",
+  "version": "0.27.0",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -47,8 +47,8 @@
     "dist"
   ],
   "dependencies": {
-    "@doccov/spec": "^0.24.1",
-    "@openpkg-ts/extract": "^0.15.0",
+    "@doccov/spec": "^0.27.0",
+    "@openpkg-ts/extract": "^0.16.0",
     "@openpkg-ts/spec": "^0.12.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",