@doccov/sdk 0.23.0 → 0.24.1

package/dist/analysis/index.d.ts

@@ -5,8 +5,26 @@ interface DetectedSchemaEntry {
 	schema: Record<string, unknown>;
 	vendor: string;
 }
-import { DriftCategory as DriftCategory2, SpecDocDrift as SpecDocDrift2 } from "@openpkg-ts/spec";
-import { DriftCategory, SpecDocDrift } from "@openpkg-ts/spec";
+import { SpecDiff } from "@openpkg-ts/spec";
+/**
+* All possible drift type identifiers.
+*/
+type DriftType = "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "async-mismatch" | "property-type-drift" | "example-drift" | "example-syntax-error" | "example-runtime-error" | "example-assertion-failed" | "broken-link";
+type SpecDocDrift = {
+	type: DriftType;
+	target?: string;
+	issue: string;
+	suggestion?: string;
+};
+/**
+* Drift categories group related drift types for progressive disclosure.
+*/
+type DriftCategory = "structural" | "semantic" | "example";
+type SpecDocsMetadata = {
+	coverageScore?: number;
+	missing?: string[];
+	drift?: SpecDocDrift[];
+};
 /**
 * Result of computing drift for a single export.
 */
@@ -54,6 +72,7 @@ interface DriftSummary {
 	byCategory: Record<DriftCategory, number>;
 	fixable: number;
 }
+import { OpenPkg as OpenPkg2, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 /**
 * Categorize a single drift issue.
 *
@@ -72,7 +91,7 @@ interface DriftSummary {
 * console.log(categorized.fixable);  // => true
 * ```
 */
-declare function categorizeDrift(drift: SpecDocDrift2): CategorizedDrift;
+declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
 /**
 * Group drifts by category.
 *
@@ -87,7 +106,7 @@ declare function categorizeDrift(drift: SpecDocDrift2): CategorizedDrift;
 * console.log(grouped.example.length);    // Number of example issues
 * ```
 */
-declare function groupDriftsByCategory(drifts: SpecDocDrift2[]): Record<DriftCategory2, CategorizedDrift[]>;
+declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
 /**
 * Get drift summary counts by category.
 *
@@ -101,7 +120,7 @@ declare function groupDriftsByCategory(drifts: SpecDocDrift2[]): Record<DriftCat
 * // => "5 issues: 3 fixable"
 * ```
 */
-declare function getDriftSummary(drifts: SpecDocDrift2[]): DriftSummary;
+declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 /**
 * Format drift summary for CLI output (single line).
 *
@@ -116,7 +135,7 @@ declare function getDriftSummary(drifts: SpecDocDrift2[]): DriftSummary;
 * ```
 */
 declare function formatDriftSummaryLine(summary: DriftSummary): string;
-import { SpecDocDrift as SpecDocDrift3, SpecExport } from "@openpkg-ts/spec";
+import { SpecExport } from "@openpkg-ts/spec";
 import { OpenPkg } from "@openpkg-ts/spec";
 type OpenPkgSpec = OpenPkg;
 /**
@@ -136,7 +155,7 @@ declare function computeDrift(spec: OpenPkgSpec): DriftResult;
 * @param registry - Registry of known exports and types for validation
 * @returns Array of drift issues detected
 */
-declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift3[];
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
 /**
 * Calculate aggregate coverage score from a spec's exports.
 *
@@ -185,7 +204,7 @@ declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
 		coverageScore: number;
 	};
 };
-import { SpecDocDrift as SpecDocDrift4, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 interface ExampleRunResult {
 	success: boolean;
 	stdout: string;
@@ -197,7 +216,7 @@ interface ExampleRunResult {
 * Detect runtime errors in @example blocks.
 * Results are provided externally after running examples via runExamples().
 */
-declare function detectExampleRuntimeErrors(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift4[];
+declare function detectExampleRuntimeErrors(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 /**
 * Parse assertion comments from example code.
 * Matches: // => expected_value
@@ -214,8 +233,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>): SpecDocDrift4[];
-import { OpenPkg as OpenPkg2, SpecDocDrift as SpecDocDrift8, SpecDocsMetadata, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
+declare function detectExampleAssertionFailures(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 /**
 * An enriched with computed documentation metadata.
 * Extends SpecExport with the `docs` field for coverage analysis.
@@ -242,7 +260,7 @@ interface EnrichOptions {
 	* Per-drift issues to include in enrichment.
 	* Map from ID to drift issues.
 	*/
-	driftByExport?: Map<string, SpecDocDrift8[]>;
+	driftByExport?: Map<string, SpecDocDrift[]>;
 }
 /**
 * Enrich an OpenPkg spec with documentation coverage metadata.
@@ -265,6 +283,30 @@ interface EnrichOptions {
 * ```
 */
 declare function enrichSpec(spec: OpenPkg2, options?: EnrichOptions): EnrichedOpenPkg;
+/**
+* Extended diff result with doccov-specific coverage tracking.
+*/
+interface EnrichedSpecDiff extends SpecDiff {
+	coverageDelta: number;
+	oldCoverage: number;
+	newCoverage: number;
+	newUndocumented: string[];
+	improvedExports: string[];
+	regressedExports: string[];
+	driftIntroduced: number;
+	driftResolved: number;
+}
+type ExportWithDocs = EnrichedExport & {
+	docs?: SpecDocsMetadata;
+};
+type SpecWithDocs = EnrichedOpenPkg & {
+	docs?: SpecDocsMetadata;
+	exports: ExportWithDocs[];
+};
+/**
+* Compare two enriched OpenPkg specs with coverage tracking.
+*/
+declare function diffEnrichedSpec(oldSpec: SpecWithDocs, newSpec: SpecWithDocs): EnrichedSpecDiff;
 import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
 /** Directory for storing history snapshots */
 declare const HISTORY_DIR = ".doccov/history";
@@ -449,7 +491,6 @@ declare function getExtendedTrend(spec: OpenPkg3, cwd: string, options?: {
 	tier?: RetentionTier;
 }): ExtendedTrendAnalysis;
 import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
-import { DriftCategory as DriftCategory3, SpecDocDrift as SpecDocDrift9 } from "@openpkg-ts/spec";
 /**
 * Drift summary with category breakdown.
 */
@@ -461,7 +502,7 @@ interface DriftReportSummary {
 	/**
 	* Count of issues per category.
 	*/
-	byCategory: Record<DriftCategory3, number>;
+	byCategory: Record<DriftCategory, number>;
 	/**
 	* Number of auto-fixable issues.
 	*/
@@ -519,7 +560,7 @@ interface ExportCoverageData {
 	/**
 	* Drift issues for this export.
 	*/
-	drift?: SpecDocDrift9[];
+	drift?: SpecDocDrift[];
 }
 /**
 * DocCov report - a persistable coverage analysis result.
@@ -647,4 +688,4 @@ interface SchemaDetectionResult {
 	noCompiledJsWarning?: boolean;
 }
 declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
-export { saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, pruneByTier, parseAssertions, loadSnapshotsForDays, loadSnapshots, loadCachedReport, isCachedReportValid, hasNonAssertionComments, groupDriftsByCategory, getTrend, getExtendedTrend, getDriftSummary, generateWeeklySummaries, generateReportFromEnriched, generateReport, formatDriftSummaryLine, formatDelta, ensureSpecCoverage, enrichSpec, detectRuntimeSchemas, detectExampleRuntimeErrors, detectExampleAssertionFailures, computeSnapshot, computeExportDrift, computeDrift, categorizeDrift, calculateAggregateCoverage, buildExportRegistry, WeeklySummary, SchemaDetectionResult, SchemaDetectionContext, RetentionTier, RETENTION_DAYS, OpenPkgSpec, HISTORY_DIR, ExtendedTrendAnalysis, ExportDriftResult, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift };
+export { saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, pruneByTier, parseAssertions, loadSnapshotsForDays, loadSnapshots, loadCachedReport, isCachedReportValid, hasNonAssertionComments, groupDriftsByCategory, getTrend, getExtendedTrend, getDriftSummary, generateWeeklySummaries, generateReportFromEnriched, generateReport, formatDriftSummaryLine, formatDelta, ensureSpecCoverage, enrichSpec, diffEnrichedSpec, detectRuntimeSchemas, detectExampleRuntimeErrors, detectExampleAssertionFailures, computeSnapshot, computeExportDrift, computeDrift, categorizeDrift, calculateAggregateCoverage, buildExportRegistry, WeeklySummary, SchemaDetectionResult, SchemaDetectionContext, RetentionTier, RETENTION_DAYS, OpenPkgSpec, HISTORY_DIR, ExtendedTrendAnalysis, ExportDriftResult, EnrichedSpecDiff, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift };

package/dist/analysis/index.js

@@ -33,8 +33,64 @@ import {
   renderSparkline,
   saveReport,
   saveSnapshot
-} from "../shared/chunk-nk2w5vws.js";
+} from "../shared/chunk-p1stkhse.js";
 import"../shared/chunk-esptwrfq.js";
+
+// src/analysis/diff-enriched.ts
+import { diffSpec } from "@openpkg-ts/spec";
+function diffEnrichedSpec(oldSpec, newSpec) {
+  const baseDiff = diffSpec(oldSpec, newSpec);
+  const result = {
+    ...baseDiff,
+    coverageDelta: 0,
+    oldCoverage: 0,
+    newCoverage: 0,
+    newUndocumented: [],
+    improvedExports: [],
+    regressedExports: [],
+    driftIntroduced: 0,
+    driftResolved: 0
+  };
+  result.oldCoverage = oldSpec.docs?.coverageScore ?? 0;
+  result.newCoverage = newSpec.docs?.coverageScore ?? 0;
+  result.coverageDelta = Math.round((result.newCoverage - result.oldCoverage) * 10) / 10;
+  const oldExportMap = toExportMap(oldSpec.exports);
+  const newExportMap = toExportMap(newSpec.exports);
+  for (const [id, newExport] of newExportMap.entries()) {
+    const oldExport = oldExportMap.get(id);
+    const newScore = newExport.docs?.coverageScore ?? 0;
+    const newDriftCount = newExport.docs?.drift?.length ?? 0;
+    if (!oldExport) {
+      if (newScore < 100 || (newExport.docs?.missing?.length ?? 0) > 0) {
+        result.newUndocumented.push(id);
+      }
+      result.driftIntroduced += newDriftCount;
+      continue;
+    }
+    const oldScore = oldExport.docs?.coverageScore ?? 0;
+    const oldDriftCount = oldExport.docs?.drift?.length ?? 0;
+    if (newScore > oldScore) {
+      result.improvedExports.push(id);
+    } else if (newScore < oldScore) {
+      result.regressedExports.push(id);
+    }
+    if (newDriftCount > oldDriftCount) {
+      result.driftIntroduced += newDriftCount - oldDriftCount;
+    } else if (oldDriftCount > newDriftCount) {
+      result.driftResolved += oldDriftCount - newDriftCount;
+    }
+  }
+  return result;
+}
+function toExportMap(exports) {
+  const map = new Map;
+  for (const exp of exports) {
+    if (exp && typeof exp.id === "string") {
+      map.set(exp.id, exp);
+    }
+  }
+  return map;
+}
 export {
   saveSnapshot,
   saveReport,
@@ -59,6 +115,7 @@ export {
   formatDelta,
   ensureSpecCoverage,
   enrichSpec,
+  diffEnrichedSpec,
   detectRuntimeSchemas,
   detectExampleRuntimeErrors,
   detectExampleAssertionFailures,