@doccov/sdk 0.30.7 → 0.31.0

package/dist/analysis/index.d.ts

@@ -1,11 +1,41 @@
 /**
+* Documentation style presets.
+*
+* - 'minimal': Only description required (default)
+* - 'verbose': Description, params, returns all required
+* - 'types-only': No documentation required (rely on TypeScript types)
+*/
+type StylePreset = "minimal" | "verbose" | "types-only";
+/**
 * Pre-detected Standard Schema for a variable export.
 */
 interface DetectedSchemaEntry {
 	schema: Record<string, unknown>;
 	vendor: string;
 }
-import { DocCovSpec, TypeReferenceLocation } from "@doccov/spec";
+import { DocCovSpec, ExportAnalysis, TypeReferenceLocation } from "@doccov/spec";
+/**
+* Documentation style presets for DocCov.
+*
+* Presets define expected documentation patterns that vary by project.
+* Some projects require verbose docs with @param/@returns for every function,
+* while others rely on TypeScript types and only need descriptions.
+*/
+/**
+* Documentation requirements - what must be present for an to be considered documented.
+*/
+interface DocRequirements2 {
+	/** Require description/summary */
+	description: boolean;
+	/** Require @param tags for function parameters */
+	params: boolean;
+	/** Require @returns tag for functions */
+	returns: boolean;
+	/** Require @example blocks */
+	examples: boolean;
+	/** Require @since tag */
+	since: boolean;
+}
 import { OpenPkg } from "@openpkg-ts/spec";
 type OpenPkgSpec = OpenPkg;
 /** Forgotten from extract package (different shape than spec type) */
@@ -29,6 +59,23 @@ interface BuildDocCovOptions {
 	forgottenExports?: ExtractForgottenExport[];
 	/** Type names to ignore in API surface calculation */
 	apiSurfaceIgnore?: string[];
+	/**
+	* Export names from the package entry point.
+	* When analyzing a sub-file, provide this to filter out false positive
+	* "forgotten" exports that are actually exported from the main entry.
+	*/
+	entryExportNames?: string[];
+	/** Progress callback for long-running analysis */
+	onProgress?: (current: number, total: number, item: string) => void;
+	/**
+	* Callback invoked after each is analyzed.
+	* Can be used for incremental persistence (crash recovery).
+	*/
+	onExportAnalyzed?: (id: string, name: string, analysis: ExportAnalysis, index: number, total: number) => void | Promise<void>;
+	/** Documentation style preset */
+	style?: StylePreset;
+	/** Custom documentation requirements (overrides preset) */
+	require?: Partial<DocRequirements2>;
 }
 /**
 * Build a DocCov spec from an OpenPkg spec.
@@ -36,7 +83,7 @@ interface BuildDocCovOptions {
 * @param options - Build options
 * @returns DocCov specification with coverage analysis
 */
-declare function buildDocCovSpec(options: BuildDocCovOptions): DocCovSpec;
+declare function buildDocCovSpec(options: BuildDocCovOptions): Promise<DocCovSpec>;
 /**
 * All possible drift type identifiers.
 */
@@ -45,6 +92,11 @@ type SpecDocDrift = {
 	type: DriftType;
 	target?: string;
 	issue: string;
+	/** Expected value from JSDoc/documentation */
+	expected?: string;
+	/** Actual value from TypeScript signature/code */
+	actual?: string;
+	/** Actionable suggestion for fixing the drift */
 	suggestion?: string;
 };
 /**
@@ -166,6 +218,93 @@ declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 */
 declare function formatDriftSummaryLine(summary: DriftSummary): string;
 import { SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+/**
+* Information about a module in the graph.
+*/
+interface ModuleInfo {
+	/**
+	* Module name (package name).
+	*/
+	name: string;
+	/**
+	* Set of exported symbol names from this module.
+	*/
+	exports: Set<string>;
+	/**
+	* Set of type names exported from this module.
+	*/
+	types: Set<string>;
+}
+/**
+* Graph of modules and their exported symbols for cross-module validation.
+*/
+interface ModuleGraph {
+	/**
+	* Map of module names to their info.
+	*/
+	modules: Map<string, ModuleInfo>;
+	/**
+	* Map of symbol names to the module that exports them.
+	* For symbols exported from multiple modules, contains the first found.
+	*/
+	exports: Map<string, string>;
+	/**
+	* Map of type names to the module that exports them.
+	*/
+	types: Map<string, string>;
+	/**
+	* Combined set of all exported symbol and type names across all modules.
+	*/
+	all: Set<string>;
+}
+/**
+* Build a module graph from multiple OpenPkg specs.
+*
+* Used for cross-module @link validation in batch mode.
+*
+* @param specs - Array of OpenPkg specs to build graph from
+* @returns ModuleGraph for cross-module symbol lookup
+*
+* @example
+* ```ts
+* import { buildModuleGraph } from '@doccov/sdk';
+*
+* const graph = buildModuleGraph([pkg1Spec, pkg2Spec]);
+*
+* // Check if symbol exists in any module
+* if (graph.all.has('Schedule')) {
+*   console.log(`Schedule is exported from: ${graph.exports.get('Schedule')}`);
+* }
+* ```
+*/
+declare function buildModuleGraph(specs: OpenPkg2[]): ModuleGraph;
+/**
+* Check if a symbol exists in the module graph.
+*
+* @param graph - Module graph to search
+* @param symbol - Symbol name to find
+* @returns Module name if found, undefined otherwise
+*/
+declare function findSymbolModule(graph: ModuleGraph, symbol: string): string | undefined;
+/**
+* Check if a symbol exists anywhere in the module graph.
+*
+* @param graph - Module graph to search
+* @param symbol - Symbol name to check
+* @returns true if symbol exists in any module
+*/
+declare function symbolExistsInGraph(graph: ModuleGraph, symbol: string): boolean;
+/**
+* Options for computing drift.
+*/
+interface ComputeDriftOptions {
+	/**
+	* Module graph for cross-module @link validation.
+	* When provided, @link targets are validated across all modules.
+	*/
+	moduleGraph?: ModuleGraph;
+}
 /**
 * Build a registry of all export/type names for cross-reference validation.
 */
@@ -174,16 +313,18 @@ declare function buildExportRegistry(spec: OpenPkgSpec): ExportRegistry;
 * Compute drift for all exports in a spec.
 *
 * @param spec - The OpenPkg spec to analyze
+* @param options - Optional config including moduleGraph for cross-module validation
 * @returns Drift results per */
-declare function computeDrift(spec: OpenPkgSpec): DriftResult;
+declare function computeDrift(spec: OpenPkgSpec, options?: ComputeDriftOptions): DriftResult;
 /**
 * Compute drift for a single export.
 *
 * @param entry - The to analyze
 * @param registry - Registry of known exports and types for validation
+* @param options - Optional config including moduleGraph for cross-module validation
 * @returns Array of drift issues detected
 */
-declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry, options?: ComputeDriftOptions): SpecDocDrift[];
 /**
 * Calculate aggregate coverage score from a spec's exports.
 *
@@ -262,7 +403,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 { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
 /** Directory for storing history snapshots (relative to .doccov) */
 declare const HISTORY_DIR = ".doccov/history";
 /**
@@ -349,7 +490,7 @@ interface ExtendedTrendAnalysis {
 /**
 * Compute a coverage snapshot from an OpenPkg spec.
 */
-declare function computeSnapshot(spec: OpenPkg2, options?: {
+declare function computeSnapshot(spec: OpenPkg3, options?: {
 	commit?: string;
 	branch?: string;
 }): CoverageSnapshot;
@@ -379,7 +520,7 @@ declare function loadSnapshots(cwd: string): CoverageSnapshot[];
 * @param options - Optional git metadata
 * @returns Trend data with history and delta
 */
-declare function getTrend(spec: OpenPkg2, cwd: string, options?: {
+declare function getTrend(spec: OpenPkg3, cwd: string, options?: {
 	commit?: string;
 	branch?: string;
 }): CoverageTrend;
@@ -430,11 +571,11 @@ declare function generateWeeklySummaries(snapshots: CoverageSnapshot[]): WeeklyS
 * @param options - Optional git metadata
 * @returns Extended trend analysis
 */
-declare function getExtendedTrend(spec: OpenPkg2, cwd: string, options?: {
+declare function getExtendedTrend(spec: OpenPkg3, cwd: string, options?: {
 	commit?: string;
 	branch?: string;
 }): ExtendedTrendAnalysis;
-import { DocCovDrift, DocCovSpec as DocCovSpec2, ExportAnalysis, MissingDocRule } from "@doccov/spec";
+import { DocCovDrift, DocCovSpec as DocCovSpec2, ExportAnalysis as ExportAnalysis2, MissingDocRule } from "@doccov/spec";
 import { SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 /**
 * Get the full analysis data for an export.
@@ -443,7 +584,7 @@ import { SpecExport as SpecExport7 } from "@openpkg-ts/spec";
 * @param doccov - The DocCov spec containing analysis data
 * @returns Export analysis or undefined if not found
 */
-declare function getExportAnalysis(exp: SpecExport7, doccov: DocCovSpec2): ExportAnalysis | undefined;
+declare function getExportAnalysis(exp: SpecExport7, doccov: DocCovSpec2): ExportAnalysis2 | undefined;
 /**
 * Get the coverage score for an export.
 *
@@ -477,7 +618,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 { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
 import { ApiSurfaceResult, DocumentationHealth } from "@doccov/spec";
 /**
 * Drift summary with category breakdown.
@@ -549,6 +690,10 @@ interface ExportCoverageData {
 	* Drift issues for this export.
 	*/
 	drift?: SpecDocDrift[];
+	/**
+	* Number of overloads if > 1 (for overloaded functions).
+	*/
+	overloadCount?: number;
 }
 /**
 * DocCov report - a persistable coverage analysis result.
@@ -611,7 +756,7 @@ interface DocCovReport {
 * console.log(`Coverage: ${report.coverage.score}%`);
 * ```
 */
-declare function generateReport(spec: OpenPkg3, openpkgPath?: string): DocCovReport;
+declare function generateReport(spec: OpenPkg4, openpkgPath?: string): Promise<DocCovReport>;
 /**
 * Generate a DocCov report from OpenPkg spec + DocCov spec composition.
 *
@@ -622,7 +767,7 @@ declare function generateReport(spec: OpenPkg3, openpkgPath?: string): DocCovRep
 * @param doccov - The DocCov spec with analysis data
 * @returns A DocCov report with coverage analysis
 */
-declare function generateReportFromDocCov(openpkg: OpenPkg3, doccov: DocCovSpec3): DocCovReport;
+declare function generateReportFromDocCov(openpkg: OpenPkg4, doccov: DocCovSpec3): DocCovReport;
 /**
 * Load a cached DocCov report from disk.
 *
@@ -670,7 +815,7 @@ declare function isCachedReportValid(reportPath?: string, sourceFiles?: string[]
 * fs.writeFileSync('api-surface.md', apiSurface);
 * ```
 */
-declare function renderApiSurface(spec: OpenPkg3): string;
+declare function renderApiSurface(spec: OpenPkg4): string;
 interface SchemaDetectionContext {
 	baseDir: string;
 	entryFile: string;
@@ -686,4 +831,131 @@ interface SchemaDetectionResult {
 	noCompiledJsWarning?: boolean;
 }
 declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
-export { saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, 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, OpenPkgSpec, HISTORY_DIR, ExtractForgottenExport, ExtendedTrendAnalysis, ExportDriftResult, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift, BuildDocCovOptions };
+import { DocCovDrift as DocCovDrift2, ExportAnalysis as ExportAnalysis3, MissingDocRule as MissingDocRule2 } from "@doccov/spec";
+/**
+* Result from analyzing a single incrementally.
+*/
+interface IncrementalExportResult {
+	/** Export ID (usually name) */
+	id: string;
+	/** Export name */
+	name: string;
+	/** Coverage score (0-100) */
+	coverageScore: number;
+	/** Missing documentation rules */
+	missing?: MissingDocRule2[];
+	/** Drift issues detected */
+	drift?: DocCovDrift2[];
+	/** Number of overloads (if > 1) */
+	overloadCount?: number;
+	/** Timestamp when this result was written */
+	timestamp: number;
+}
+/**
+* Partial analysis state recovered from temp file.
+*/
+interface PartialAnalysisState {
+	/** Results collected before interruption */
+	results: IncrementalExportResult[];
+	/** Total exports that were expected */
+	totalExpected?: number;
+	/** Whether analysis was interrupted */
+	interrupted: boolean;
+}
+/**
+* Options for IncrementalAnalyzer.
+*/
+interface IncrementalAnalyzerOptions {
+	/** Custom temp directory (defaults to os.tmpdir()) */
+	tempDir?: string;
+	/** Prefix for temp file name */
+	prefix?: string;
+}
+/**
+* Analyzer that persists results incrementally for crash recovery.
+*
+* Usage:
+* ```ts
+* const analyzer = new IncrementalAnalyzer();
+* analyzer.setTotal(exports.length);
+*
+* for (const exp of exports) {
+*   const result = analyzeExport(exp);
+*   await analyzer.writeResult(result);
+* }
+*
+* // On success, clean up
+* analyzer.cleanup();
+*
+* // On crash, recover partial results:
+* const partial = await analyzer.getPartialResults();
+* ```
+*/
+declare class IncrementalAnalyzer {
+	private tempPath;
+	private totalExpected?;
+	private resultCount;
+	private fileHandle?;
+	constructor(options?: IncrementalAnalyzerOptions);
+	/**
+	* Get the temp file path (for debugging/logging).
+	*/
+	get path(): string;
+	/**
+	* Get count of results written so far.
+	*/
+	get count(): number;
+	/**
+	* Set total expected exports (for progress reporting).
+	*/
+	setTotal(total: number): void;
+	/**
+	* Initialize the file handle for writing.
+	* Called automatically on first writeResult, but can be called
+	* explicitly for eager initialization.
+	*/
+	init(): Promise<void>;
+	/**
+	* Write a single result to the temp file.
+	*/
+	writeResult(result: IncrementalExportResult): Promise<void>;
+	/**
+	* Write an analysis result (converts from ExportAnalysis format).
+	*/
+	writeExportAnalysis(id: string, name: string, analysis: ExportAnalysis3): Promise<void>;
+	/**
+	* Read partial results from the temp file.
+	* Returns empty array if file doesn't exist.
+	*/
+	getPartialResults(): Promise<PartialAnalysisState>;
+	/**
+	* Clean up the temp file. Call this on successful completion.
+	*/
+	cleanup(): Promise<void>;
+	/**
+	* Synchronous cleanup for use in signal handlers.
+	* Note: May lose last few writes that haven't been flushed.
+	*/
+	cleanupSync(): void;
+	/**
+	* Check if temp file exists (for recovery detection).
+	*/
+	exists(): boolean;
+	/**
+	* Get partial results synchronously (for signal handlers).
+	* May miss most recent writes.
+	*/
+	getPartialResultsSync(): PartialAnalysisState;
+}
+/**
+* Find any orphaned temp files from previous crashed runs.
+* Returns paths to .ndjson files that match the doccov pattern.
+*/
+declare function findOrphanedTempFiles(tempDir?: string, prefix?: string): string[];
+/**
+* Clean up orphaned temp files older than maxAge.
+*
+* @param maxAge - Maximum age in milliseconds (default: 1 hour)
+*/
+declare function cleanupOrphanedTempFiles(tempDir?: string, prefix?: string, maxAge?: number): number;
+export { symbolExistsInGraph, saveSnapshot, saveReport, renderSparkline, renderApiSurface, pruneHistory, parseAssertions, loadSnapshotsForDays, loadSnapshots, loadCachedReport, isExportFullyDocumented, isCachedReportValid, hasNonAssertionComments, groupDriftsByCategory, getTrend, getExtendedTrend, getExportScore, getExportMissing, getExportDrift, getExportAnalysis, getDriftSummary, generateWeeklySummaries, generateReportFromDocCov, generateReport, formatDriftSummaryLine, formatDelta, findSymbolModule, findOrphanedTempFiles, ensureSpecCoverage, detectRuntimeSchemas, detectExampleRuntimeErrors, detectExampleAssertionFailures, computeSnapshot, computeExportDrift, computeDrift, cleanupOrphanedTempFiles, categorizeDrift, calculateAggregateCoverage, buildModuleGraph, buildExportRegistry, buildDocCovSpec, WeeklySummary, SchemaDetectionResult, SchemaDetectionContext, PartialAnalysisState, OpenPkgSpec, ModuleInfo, ModuleGraph, IncrementalExportResult, IncrementalAnalyzerOptions, IncrementalAnalyzer, HISTORY_DIR, ExtractForgottenExport, ExtendedTrendAnalysis, ExportDriftResult, DriftSummary, DriftResult, DetectedSchemaEntry, CoverageTrend, CoverageSnapshot, CategorizedDrift, BuildDocCovOptions };

package/dist/analysis/index.js

@@ -1,9 +1,12 @@
 import {
   HISTORY_DIR,
+  IncrementalAnalyzer,
   buildDocCovSpec,
   buildExportRegistry,
+  buildModuleGraph,
   calculateAggregateCoverage,
   categorizeDrift,
+  cleanupOrphanedTempFiles,
   computeDrift,
   computeExportDrift,
   computeSnapshot,
@@ -11,6 +14,8 @@ import {
   detectExampleRuntimeErrors,
   detectRuntimeSchemas,
   ensureSpecCoverage,
+  findOrphanedTempFiles,
+  findSymbolModule,
   formatDelta,
   formatDriftSummaryLine,
   generateReport,
@@ -35,10 +40,12 @@ import {
   renderApiSurface,
   renderSparkline,
   saveReport,
-  saveSnapshot
-} from "../shared/chunk-ehne5cde.js";
+  saveSnapshot,
+  symbolExistsInGraph
+} from "../shared/chunk-ee3ctqje.js";
 import"../shared/chunk-r4wa72ae.js";
 export {
+  symbolExistsInGraph,
   saveSnapshot,
   saveReport,
   renderSparkline,
@@ -64,6 +71,8 @@ export {
   generateReport,
   formatDriftSummaryLine,
   formatDelta,
+  findSymbolModule,
+  findOrphanedTempFiles,
   ensureSpecCoverage,
   detectRuntimeSchemas,
   detectExampleRuntimeErrors,
@@ -71,9 +80,12 @@ export {
   computeSnapshot,
   computeExportDrift,
   computeDrift,
+  cleanupOrphanedTempFiles,
   categorizeDrift,
   calculateAggregateCoverage,
+  buildModuleGraph,
   buildExportRegistry,
   buildDocCovSpec,
+  IncrementalAnalyzer,
   HISTORY_DIR
 };