@doccov/sdk 0.22.1 → 0.24.0

package/dist/analysis/index.d.ts

@@ -0,0 +1,691 @@
+/**
+* Pre-detected Standard Schema for a variable export.
+*/
+interface DetectedSchemaEntry {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
+/**
+* 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.
+*/
+type ExportDriftResult = {
+	id: string;
+	drift: SpecDocDrift[];
+};
+/**
+* Result of computing drift for all exports.
+*/
+type DriftResult = {
+	exports: Map<string, SpecDocDrift[]>;
+};
+/**
+* Information about an for context-aware suggestions.
+*/
+interface ExportInfo {
+	name: string;
+	kind: string;
+	isCallable: boolean;
+}
+/**
+* Registry of exports and types for cross-reference validation.
+*/
+interface ExportRegistry {
+	/** Map of names to their info (for context-aware suggestions) */
+	exports: Map<string, ExportInfo>;
+	/** Set of type names (interfaces, type aliases, etc.) */
+	types: Set<string>;
+	/** Combined set of all names (for backward compatibility) */
+	all: Set<string>;
+}
+/**
+* Extended drift with category and fixability metadata.
+*/
+interface CategorizedDrift extends SpecDocDrift {
+	category: DriftCategory;
+	fixable: boolean;
+}
+/**
+* Summary of drift issues by category.
+*/
+interface DriftSummary {
+	total: number;
+	byCategory: Record<DriftCategory, number>;
+	fixable: number;
+}
+/**
+* Categorize a single drift issue.
+*
+* @param drift - The drift to categorize
+* @returns The drift with category and fixable metadata
+*
+* @example
+* ```ts
+* const drift: SpecDocDrift = {
+*   type: 'param-type-mismatch',
+*   target: 'userId',
+*   issue: 'Type mismatch'
+* };
+* const categorized = categorizeDrift(drift);
+* console.log(categorized.category); // => 'structural'
+* console.log(categorized.fixable);  // => true
+* ```
+*/
+declare function categorizeDrift(drift: SpecDocDrift): CategorizedDrift;
+/**
+* Group drifts by category.
+*
+* @param drifts - Array of drift issues to group
+* @returns Drifts organized by category
+*
+* @example
+* ```ts
+* const grouped = groupDriftsByCategory(spec.docs.drift ?? []);
+* console.log(grouped.structural.length); // Number of structural issues
+* console.log(grouped.semantic.length);   // Number of semantic issues
+* console.log(grouped.example.length);    // Number of example issues
+* ```
+*/
+declare function groupDriftsByCategory(drifts: SpecDocDrift[]): Record<DriftCategory, CategorizedDrift[]>;
+/**
+* Get drift summary counts by category.
+*
+* @param drifts - Array of drift issues
+* @returns Summary with totals, category breakdown, and fixable count
+*
+* @example
+* ```ts
+* const summary = getDriftSummary(exportEntry.docs?.drift ?? []);
+* console.log(`${summary.total} issues: ${summary.fixable} fixable`);
+* // => "5 issues: 3 fixable"
+* ```
+*/
+declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
+/**
+* Format drift summary for CLI output (single line).
+*
+* @param summary - Drift summary to format
+* @returns Human-readable summary string
+*
+* @example
+* ```ts
+* const summary = getDriftSummary(drifts);
+* console.log(formatDriftSummaryLine(summary));
+* // => "5 issues (3 structural, 1 semantic, 1 example)"
+* ```
+*/
+declare function formatDriftSummaryLine(summary: DriftSummary): string;
+import { SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg } from "@openpkg-ts/spec";
+type OpenPkgSpec = OpenPkg;
+/**
+* Build a registry of all export/type names for cross-reference validation.
+*/
+declare function buildExportRegistry(spec: OpenPkgSpec): ExportRegistry;
+/**
+* Compute drift for all exports in a spec.
+*
+* @param spec - The OpenPkg spec to analyze
+* @returns Drift results per */
+declare function computeDrift(spec: OpenPkgSpec): DriftResult;
+/**
+* Compute drift for a single export.
+*
+* @param entry - The to analyze
+* @param registry - Registry of known exports and types for validation
+* @returns Array of drift issues detected
+*/
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
+/**
+* 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 { SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+interface ExampleRunResult {
+	success: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+	duration: number;
+}
+/**
+* Detect runtime errors in @example blocks.
+* Results are provided externally after running examples via runExamples().
+*/
+declare function detectExampleRuntimeErrors(entry: SpecExport2, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
+/**
+* Parse assertion comments from example code.
+* Matches: // => expected_value
+*/
+declare function parseAssertions(code: string): Array<{
+	lineNumber: number;
+	expected: string;
+}>;
+/**
+* Check if code contains comments that are not assertion syntax.
+* Used to determine if LLM fallback should be attempted.
+*/
+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, SpecExport as SpecExport7 } from "@openpkg-ts/spec";
+/**
+* An enriched with computed documentation metadata.
+* Extends SpecExport with the `docs` field for coverage analysis.
+*/
+type EnrichedExport = SpecExport7 & {
+	docs?: EnrichedDocsMetadata;
+};
+/**
+* Extended docs metadata.
+*/
+type EnrichedDocsMetadata = SpecDocsMetadata;
+/**
+* An enriched OpenPkg spec with computed documentation metadata.
+* Extends OpenPkg with per-and aggregate coverage data.
+*/
+type EnrichedOpenPkg = Omit<OpenPkg2, "exports"> & {
+	exports: EnrichedExport[];
+	docs?: EnrichedDocsMetadata;
+	/** Drift summary with category breakdown (if drift exists) */
+	driftSummary?: DriftSummary;
+};
+interface EnrichOptions {
+	/**
+	* Per-drift issues to include in enrichment.
+	* Map from ID to drift issues.
+	*/
+	driftByExport?: Map<string, SpecDocDrift[]>;
+}
+/**
+* Enrich an OpenPkg spec with documentation coverage metadata.
+*
+* Computes coverage scores and detects drift issues.
+*
+* @param spec - The pure OpenPkg spec to enrich
+* @param options - Optional enrichment configuration
+* @returns An enriched spec with documentation metadata
+*
+* @example
+* ```ts
+* import { DocCov, enrichSpec } from '@doccov/sdk';
+*
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+*
+* const enriched = enrichSpec(spec);
+* console.log(enriched.docs?.coverageScore); // e.g., 85
+* ```
+*/
+declare function enrichSpec(spec: OpenPkg2, options?: EnrichOptions): EnrichedOpenPkg;
+import { SpecDiff } from "@openpkg-ts/spec";
+/**
+* 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";
+/**
+* A historical coverage snapshot.
+*/
+interface CoverageSnapshot {
+	/** ISO 8601 timestamp */
+	timestamp: string;
+	/** Package name */
+	package: string;
+	/** Package version (if available) */
+	version?: string;
+	/** Coverage score (0-100) */
+	coverageScore: number;
+	/** Total number of exports */
+	totalExports: number;
+	/** Number of documented exports */
+	documentedExports: number;
+	/** Number of drift issues */
+	driftCount: number;
+	/** Git commit hash (if available) */
+	commit?: string;
+	/** Git branch (if available) */
+	branch?: string;
+}
+/**
+* Coverage trend data.
+*/
+interface CoverageTrend {
+	/** Current snapshot */
+	current: CoverageSnapshot;
+	/** Previous snapshots (most recent first) */
+	history: CoverageSnapshot[];
+	/** Score delta from previous */
+	delta?: number;
+	/** Sparkline data (last N scores) */
+	sparkline: number[];
+}
+/**
+* Tier-based retention settings.
+*/
+type RetentionTier = "free" | "team" | "pro";
+/**
+* Retention days per tier.
+*/
+declare const RETENTION_DAYS: Record<RetentionTier, number>;
+/**
+* Weekly summary of coverage data.
+*/
+interface WeeklySummary {
+	/** Week start date (ISO string) */
+	weekStart: string;
+	/** Week end date (ISO string) */
+	weekEnd: string;
+	/** Average coverage for the week */
+	avgCoverage: number;
+	/** Coverage at start of week */
+	startCoverage: number;
+	/** Coverage at end of week */
+	endCoverage: number;
+	/** Change during the week */
+	delta: number;
+	/** Number of snapshots in the week */
+	snapshotCount: number;
+}
+/**
+* Extended trend analysis result.
+*/
+interface ExtendedTrendAnalysis {
+	/** Current trend data */
+	trend: CoverageTrend;
+	/** Weekly summaries (most recent first) */
+	weeklySummaries: WeeklySummary[];
+	/** 7-day velocity (average daily change) */
+	velocity7d: number;
+	/** 30-day velocity */
+	velocity30d: number;
+	/** 90-day velocity (Pro only) */
+	velocity90d?: number;
+	/** Projected coverage in 30 days (based on velocity) */
+	projected30d: number;
+	/** Best coverage ever recorded */
+	allTimeHigh: number;
+	/** Worst coverage ever recorded */
+	allTimeLow: number;
+	/** Date range of available data */
+	dataRange: {
+		start: string;
+		end: string;
+	} | null;
+}
+/**
+* Compute a coverage snapshot from an OpenPkg spec.
+*/
+declare function computeSnapshot(spec: OpenPkg3, options?: {
+	commit?: string;
+	branch?: string;
+}): CoverageSnapshot;
+/**
+* Save a coverage snapshot to history.
+*
+* @param snapshot - The snapshot to save
+* @param cwd - Working directory
+*/
+declare function saveSnapshot(snapshot: CoverageSnapshot, cwd: string): void;
+/**
+* Load all historical snapshots.
+*
+* @param cwd - Working directory
+* @returns Array of snapshots sorted by timestamp (most recent first)
+*/
+declare function loadSnapshots(cwd: string): CoverageSnapshot[];
+/**
+* Get coverage trend data.
+*
+* @param spec - Current OpenPkg spec
+* @param cwd - Working directory
+* @param options - Optional git metadata
+* @returns Trend data with history and delta
+*/
+declare function getTrend(spec: OpenPkg3, cwd: string, options?: {
+	commit?: string;
+	branch?: string;
+}): CoverageTrend;
+/**
+* Generate a sparkline character representation.
+*
+* @param values - Array of values (0-100 for coverage)
+* @returns Sparkline string using unicode characters
+*/
+declare function renderSparkline(values: number[]): string;
+/**
+* Format a delta value with arrow and color indicator.
+*
+* @param delta - Coverage delta (positive = improvement)
+* @returns Formatted delta string
+*/
+declare function formatDelta(delta: number): string;
+/**
+* Prune old snapshots to keep history manageable.
+*
+* @param cwd - Working directory
+* @param keepCount - Number of snapshots to keep (default: 100)
+* @returns Number of snapshots deleted
+*/
+declare function pruneHistory(cwd: string, keepCount?: number): number;
+/**
+* Prune snapshots based on tier retention policy.
+*
+* @param cwd - Working directory
+* @param tier - Retention tier (free: 7d, team: 30d, pro: 90d)
+* @returns Number of snapshots deleted
+*/
+declare function pruneByTier(cwd: string, tier: RetentionTier): number;
+/**
+* Load snapshots within a date range.
+*
+* @param cwd - Working directory
+* @param days - Number of days to include
+* @returns Filtered snapshots
+*/
+declare function loadSnapshotsForDays(cwd: string, days: number): CoverageSnapshot[];
+/**
+* Generate weekly summaries from snapshots.
+*
+* @param snapshots - Snapshots to summarize (most recent first)
+* @returns Weekly summaries (most recent first)
+*/
+declare function generateWeeklySummaries(snapshots: CoverageSnapshot[]): WeeklySummary[];
+/**
+* Get extended trend analysis with velocity and projections.
+*
+* @param spec - Current OpenPkg spec
+* @param cwd - Working directory
+* @param options - Analysis options
+* @returns Extended trend analysis
+*/
+declare function getExtendedTrend(spec: OpenPkg3, cwd: string, options?: {
+	commit?: string;
+	branch?: string;
+	tier?: RetentionTier;
+}): ExtendedTrendAnalysis;
+import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
+/**
+* Drift summary with category breakdown.
+*/
+interface DriftReportSummary {
+	/**
+	* Total number of drift issues.
+	*/
+	total: number;
+	/**
+	* Count of issues per category.
+	*/
+	byCategory: Record<DriftCategory, number>;
+	/**
+	* Number of auto-fixable issues.
+	*/
+	fixable: number;
+}
+/**
+* Coverage summary for an entire package or project.
+*/
+interface CoverageSummary {
+	/**
+	* Overall coverage score (0-100).
+	*/
+	score: number;
+	/**
+	* Total number of exports analyzed.
+	*/
+	totalExports: number;
+	/**
+	* Number of fully documented exports.
+	*/
+	documentedExports: number;
+	/**
+	* Breakdown of missing documentation by rule ID.
+	*/
+	missingByRule: Record<string, number>;
+	/**
+	* Total number of drift issues detected.
+	*/
+	driftCount: number;
+	/**
+	* Drift summary with category breakdown.
+	*/
+	driftSummary?: DriftReportSummary;
+}
+/**
+* Coverage data for a single export.
+*/
+interface ExportCoverageData {
+	/**
+	* Export name.
+	*/
+	name: string;
+	/**
+	* Export kind (function, class, etc.).
+	*/
+	kind: string;
+	/**
+	* Coverage score for this (0-100).
+	*/
+	coverageScore: number;
+	/**
+	* Missing documentation rule IDs.
+	*/
+	missing?: string[];
+	/**
+	* Drift issues for this export.
+	*/
+	drift?: SpecDocDrift[];
+}
+/**
+* DocCov report - a persistable coverage analysis result.
+*
+* This is the format saved to `.doccov/report.json` and returned
+* by the `check` command with `--format json`.
+*/
+interface DocCovReport {
+	/**
+	* JSON Schema reference for validation.
+	*/
+	$schema: string;
+	/**
+	* Report format version.
+	*/
+	version: string;
+	/**
+	* ISO 8601 timestamp when report was generated.
+	*/
+	generatedAt: string;
+	/**
+	* Package/project metadata.
+	*/
+	spec: {
+		name: string;
+		version?: string;
+	};
+	/**
+	* Aggregate coverage summary.
+	*/
+	coverage: CoverageSummary;
+	/**
+	* Per-coverage data, keyed by ID.
+	*/
+	exports: Record<string, ExportCoverageData>;
+}
+/**
+* Generate a DocCov report from an OpenPkg spec.
+*
+* @param spec - The pure OpenPkg spec to analyze
+* @returns A DocCov report with coverage analysis
+*
+* @example
+* ```ts
+* import { DocCov, generateReport } from '@doccov/sdk';
+*
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* const report = generateReport(spec);
+*
+* console.log(`Coverage: ${report.coverage.score}%`);
+* ```
+*/
+declare function generateReport(spec: OpenPkg4): DocCovReport;
+/**
+* Generate a DocCov report from an already-enriched spec.
+*
+* Use this when you've already called enrichSpec() and want to avoid
+* recomputing coverage data.
+*
+* @param enriched - The enriched OpenPkg spec
+* @returns A DocCov report with coverage analysis
+*/
+declare function generateReportFromEnriched(enriched: EnrichedOpenPkg): DocCovReport;
+/**
+* Load a cached DocCov report from disk.
+*
+* @param reportPath - Path to the report file (defaults to .doccov/report.json)
+* @returns The cached report, or null if not found
+*/
+declare function loadCachedReport(reportPath?: string): DocCovReport | null;
+/**
+* Save a DocCov report to disk.
+*
+* @param report - The report to save
+* @param reportPath - Path to save the report (defaults to .doccov/report.json)
+*/
+declare function saveReport(report: DocCovReport, reportPath?: string): void;
+/**
+* Check if a cached report is still valid.
+*
+* A report is considered stale if:
+* - It doesn't exist
+* - The spec version has changed
+* - Source files have been modified since generation
+*
+* @param reportPath - Path to the report file
+* @param sourceFiles - Source files to check modification times against
+* @returns True if the cached report is still valid
+*/
+declare function isCachedReportValid(reportPath?: string, sourceFiles?: string[]): boolean;
+/**
+* Generate a git-trackable API surface markdown file from an OpenPkg spec.
+*
+* This produces a deterministic, sorted output suitable for version control.
+* Changes to the API will show up as diffs in this file.
+*
+* @param spec - The OpenPkg spec to render
+* @returns Markdown string representing the API surface
+*
+* @example
+* ```ts
+* import { DocCov, renderApiSurface } from '@doccov/sdk';
+*
+* const doccov = new DocCov();
+* const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+* const apiSurface = renderApiSurface(spec);
+*
+* fs.writeFileSync('api-surface.md', apiSurface);
+* ```
+*/
+declare function renderApiSurface(spec: OpenPkg4): string;
+interface SchemaDetectionContext {
+	baseDir: string;
+	entryFile: string;
+}
+interface DetectedSchema {
+	schema: Record<string, unknown>;
+	vendor: string;
+}
+interface SchemaDetectionResult {
+	schemas: Map<string, DetectedSchema>;
+	errors: string[];
+	/** Warning when runtime was requested but compiled JS not found */
+	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, 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 };