@doccov/sdk 0.26.0 → 0.27.0

package/dist/analysis/index.d.ts

@@ -484,7 +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 } from "@doccov/spec";
+import { ApiSurfaceResult, DocumentationHealth } from "@doccov/spec";
 /**
 * Drift summary with category breakdown.
 */
@@ -594,6 +594,10 @@ interface DocCovReport {
 	* API surface analysis (forgotten exports).
 	*/
 	apiSurface?: ApiSurfaceResult;
+	/**
+	* Unified documentation health score.
+	*/
+	health?: DocumentationHealth;
 }
 /**
 * Generate a DocCov report from an OpenPkg spec.

package/dist/analysis/index.js

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

package/dist/index.d.ts

@@ -1,3 +1,39 @@
+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;
@@ -43,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.
 */
@@ -92,7 +128,7 @@ interface ExportRegistry {
 * Extended drift with category and fixability metadata.
 */
 interface CategorizedDrift extends SpecDocDrift {
-	category: DriftCategory;
+	category: DriftCategory2;
 	fixable: boolean;
 }
 /**
@@ -100,7 +136,7 @@ interface CategorizedDrift extends SpecDocDrift {
 */
 interface DriftSummary {
 	total: number;
-	byCategory: Record<DriftCategory, number>;
+	byCategory: Record<DriftCategory2, number>;
 	fixable: number;
 }
 /**
@@ -136,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.
 *
@@ -301,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.
@@ -334,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.
 *
@@ -345,7 +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 } from "@doccov/spec";
+import { ApiSurfaceResult, DocumentationHealth as DocumentationHealth2 } from "@doccov/spec";
 /**
 * DocCov report schema version.
 */
@@ -405,7 +441,7 @@ interface DriftReportSummary {
 	/**
 	* Count of issues per category.
 	*/
-	byCategory: Record<DriftCategory, number>;
+	byCategory: Record<DriftCategory2, number>;
 	/**
 	* Number of auto-fixable issues.
 	*/
@@ -427,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).
 	*/
@@ -525,6 +561,10 @@ interface DocCovReport {
 	* API surface analysis (forgotten exports).
 	*/
 	apiSurface?: ApiSurfaceResult;
+	/**
+	* Unified documentation health score.
+	*/
+	health?: DocumentationHealth2;
 }
 /**
 * Generate a DocCov report from an OpenPkg spec.
@@ -792,9 +832,17 @@ 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;
@@ -1010,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) */
@@ -1790,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
@@ -2615,7 +2679,7 @@ interface SpecSummary {
 * ```
 */
 declare function extractSpecSummary(openpkg: OpenPkg8, doccov: DocCovSpec4): SpecSummary;
-import { OpenPkg as OpenPkg_ikpscozpjh } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg_tgtzybcxvb } from "@openpkg-ts/spec";
 /**
 * Build Plan types for AI-powered repository scanning.
 */
@@ -2712,7 +2776,7 @@ interface BuildPlanExecutionResult {
 	/** Whether all required steps succeeded */
 	success: boolean;
 	/** Generated OpenPkg spec (if successful) */
-	spec?: OpenPkg_ikpscozpjh;
+	spec?: OpenPkg_tgtzybcxvb;
 	/** Results for each step */
 	stepResults: BuildPlanStepResult[];
 	/** Total execution time in milliseconds */
@@ -2720,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, 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, 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, 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, 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 };
+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

@@ -14,6 +14,7 @@ import {
   categorizeDrifts,
   computeDrift,
   computeExportDrift,
+  computeHealth,
   computeSnapshot,
   createSourceFile,
   detectExampleAssertionFailures,
@@ -59,7 +60,7 @@ import {
   saveSnapshot,
   serializeJSDoc,
   ts
-} from "./shared/chunk-yqqqk8by.js";
+} from "./shared/chunk-v62zsv8j.js";
 import {
   mergeFilters,
   parseListFlag
@@ -622,7 +623,7 @@ ${extraction.errors.map((e) => `  - ${e}`).join(`
 `)}`);
     }
   }
-  const result = runAnalysis({
+  const result = await runAnalysis({
     entryFile,
     packageDir,
     content,
@@ -2494,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)) {
@@ -3112,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;
@@ -3668,6 +3731,7 @@ export {
   createSourceFile,
   createNodeCommandRunner,
   computeSnapshot,
+  computeHealth,
   computeExportDrift,
   computeDrift,
   clearSpecCache,

package/dist/shared/{chunk-yqqqk8by.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",
@@ -2179,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,
@@ -2188,7 +2249,8 @@ function buildDocCovSpec(options) {
       total: totalDrift,
       fixable: fixableDrift,
       byCategory: driftByCategory
-    }
+    },
+    health
   };
   const apiSurface = computeApiSurface(forgottenExports, openpkg.types?.length ?? 0, apiSurfaceIgnore);
   return {
@@ -2285,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)
   };
 }
 
@@ -3145,4 +3208,4 @@ function getExtendedTrend(spec, cwd, options) {
   };
 }
 
-export { 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 };
+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

@@ -46,9 +46,17 @@ 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;
@@ -170,7 +178,7 @@ interface CategorizedDrift extends SpecDocDrift {
 	category: DriftCategory;
 	fixable: boolean;
 }
-import { ApiSurfaceResult } from "@doccov/spec";
+import { ApiSurfaceResult, DocumentationHealth } from "@doccov/spec";
 /**
 * DocCov report schema version.
 */
@@ -350,5 +358,9 @@ interface DocCovReport {
 	* 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.26.0",
+  "version": "0.27.0",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -47,7 +47,7 @@
     "dist"
   ],
   "dependencies": {
-    "@doccov/spec": "^0.26.0",
+    "@doccov/spec": "^0.27.0",
     "@openpkg-ts/extract": "^0.16.0",
     "@openpkg-ts/spec": "^0.12.0",
     "@vercel/sandbox": "^1.0.3",