@doccov/sdk 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -177,6 +177,54 @@ declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 * ```
 */
 declare function formatDriftSummaryLine(summary: DriftSummary): string;
+/**
+* Calculate aggregate coverage score from a spec's exports.
+*
+* This is a lightweight function that calculates coverage without
+* requiring full quality evaluation. It handles three cases:
+* 1. Exports with `docs.coverageScore` - uses that value
+* 2. Exports without score but with description - counts as 100%
+* 3. Exports without score and no description - counts as 0%
+*
+* @param spec - The OpenPkg spec to calculate coverage for
+* @returns The aggregate coverage score (0-100)
+*
+* @example
+* ```ts
+* import { calculateAggregateCoverage } from '@doccov/sdk';
+*
+* const coverage = calculateAggregateCoverage(spec);
+* console.log(`Coverage: ${coverage}%`);
+* ```
+*/
+declare function calculateAggregateCoverage(spec: OpenPkgSpec): number;
+/**
+* Ensure a spec has a top-level docs.coverageScore.
+*
+* If the spec already has `docs.coverageScore`, returns the spec unchanged.
+* Otherwise, calculates aggregate coverage from exports and returns a
+* new spec with the coverage score added.
+*
+* This is useful for commands like `diff` that need coverage scores
+* but may receive raw specs that haven't been enriched.
+*
+* @param spec - The OpenPkg spec to ensure coverage for
+* @returns The spec with guaranteed top-level coverage score
+*
+* @example
+* ```ts
+* import { ensureSpecCoverage } from '@doccov/sdk';
+*
+* // Works with raw or enriched specs
+* const specWithCoverage = ensureSpecCoverage(rawSpec);
+* console.log(specWithCoverage.docs?.coverageScore); // e.g., 85
+* ```
+*/
+declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
+	docs: {
+		coverageScore: number;
+	};
+};
 import { OpenPkg as OpenPkg2, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
 import { SpecExport as SpecExport2, SpecExportKind } from "@openpkg-ts/spec";
 import * as TS from "typescript";
@@ -476,6 +524,24 @@ declare const REPORT_EXTENSIONS: Record<string, string>;
 */
 declare function getReportPath(format: string, dir?: string): string;
 /**
+* Get the report path for a diff comparison.
+*
+* Uses truncated hashes from both specs to create a unique, deterministic filename.
+*
+* @param baseHash - Hash of the base (before) spec
+* @param headHash - Hash of the head (after) spec
+* @param format - The report format (json, markdown, html, github)
+* @param dir - The output directory (defaults to .doccov)
+* @returns The full path to the diff report file
+*
+* @example
+* ```ts
+* getDiffReportPath('abc123def456', 'xyz789uvw012', 'markdown');
+* // '.doccov/diff-abc123de-xyz789uv.md'
+* ```
+*/
+declare function getDiffReportPath(baseHash: string, headHash: string, format: string, dir?: string): string;
+/**
 * Drift summary with category breakdown.
 */
 interface DriftReportSummary {
@@ -2283,4 +2349,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, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadCachedReport, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getSpecCachePath, getRunCommand, getRulesForKind, getRule, getReportPath, getPrimaryBuildScript, getInstallCommand, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDefaultConfig, getCoverageRules, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, evaluateQuality, evaluateExportQuality, enrichSpec, diffSpecWithDocs, diffHashes, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, buildRawUrl, buildExportRegistry, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, ScanResult, ScanOrchestratorOptions, ScanOrchestrator, ScanOptions, ScanContext, 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, ProgressStage, ProgressEvent, ProgressCallback, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg8 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoRequiresPackageError, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, 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, DriftIssue, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildInfo, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };
+export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadCachedReport, 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, 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, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, ScanResult, ScanOrchestratorOptions, ScanOrchestrator, ScanOptions, ScanContext, 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, ProgressStage, ProgressEvent, ProgressCallback, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg8 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoRequiresPackageError, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, 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, DriftIssue, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildInfo, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };

package/dist/index.js

@@ -1201,6 +1201,35 @@ function formatDriftSummaryLine(summary) {
   const fixableNote = summary.fixable > 0 ? ` (${summary.fixable} auto-fixable)` : "";
   return `${summary.total} issues (${parts.join(", ")})${fixableNote}`;
 }
+function calculateAggregateCoverage(spec) {
+  const exports = spec.exports ?? [];
+  if (exports.length === 0)
+    return 100;
+  let totalScore = 0;
+  for (const exp of exports) {
+    const score = exp.docs?.coverageScore;
+    if (score !== undefined) {
+      totalScore += score;
+    } else {
+      totalScore += exp.description ? 100 : 0;
+    }
+  }
+  return Math.round(totalScore / exports.length);
+}
+function ensureSpecCoverage(spec) {
+  const specWithDocs = spec;
+  if (specWithDocs.docs?.coverageScore !== undefined) {
+    return spec;
+  }
+  const coverage = calculateAggregateCoverage(spec);
+  return {
+    ...spec,
+    docs: {
+      ...specWithDocs.docs ?? {},
+      coverageScore: coverage
+    }
+  };
+}
 // src/fix/jsdoc-writer.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -1938,6 +1967,11 @@ function getReportPath(format, dir = DEFAULT_REPORT_DIR) {
   const ext = REPORT_EXTENSIONS[format] ?? format;
   return `${dir}/report.${ext}`;
 }
+function getDiffReportPath(baseHash, headHash, format, dir = DEFAULT_REPORT_DIR) {
+  const ext = REPORT_EXTENSIONS[format] ?? format;
+  const hash = `${baseHash.slice(0, 8)}-${headHash.slice(0, 8)}`;
+  return `${dir}/diff-${hash}.${ext}`;
+}
 
 // src/analysis/report.ts
 function generateReport(spec) {
@@ -8626,6 +8660,7 @@ export {
   getDriftSummary,
   getDocumentedExports,
   getDocsImpactSummary,
+  getDiffReportPath,
   getDefaultConfig,
   getCoverageRules,
   generateReportFromEnriched,
@@ -8647,6 +8682,7 @@ export {
   extractFunctionCalls,
   evaluateQuality,
   evaluateExportQuality,
+  ensureSpecCoverage,
   enrichSpec,
   diffSpecWithDocs,
   diffHashes,
@@ -8664,6 +8700,7 @@ export {
   clearSpecCache,
   categorizeDrifts,
   categorizeDrift,
+  calculateAggregateCoverage,
   buildRawUrl,
   buildExportRegistry,
   buildDisplayUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",