@doccov/sdk 0.25.7 → 0.25.9

package/README.md

@@ -1,6 +1,6 @@
 # @doccov/sdk
 
-Programmatic API for documentation coverage analysis.
+Programmatic API for documentation coverage analysis, drift detection, and spec generation.
 
 ## Install
 
@@ -8,36 +8,132 @@ Programmatic API for documentation coverage analysis.
 npm install @doccov/sdk
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { DocCov } from '@doccov/sdk';
+import { DocCov, buildDocCovSpec } from '@doccov/sdk';
 
+// Analyze a package
 const doccov = new DocCov();
-const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+const result = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+
+// Build coverage spec
+const spec = buildDocCovSpec({
+  openpkg: result.spec,
+  openpkgPath: 'src/index.ts',
+  packagePath: process.cwd(),
+});
+
+console.log(`Coverage: ${spec.summary.score}%`);
+console.log(`Drift issues: ${spec.summary.drift.total}`);
+```
+
+## Core API
+
+### DocCov Class
+
+Main analysis engine.
+
+```typescript
+import { DocCov } from '@doccov/sdk';
 
-console.log(`Coverage: ${spec.docs?.coverageScore}%`);
+const doccov = new DocCov({
+  resolveExternalTypes: true,
+  maxDepth: 20,
+  useCache: true,
+});
 
-// Check for drift
-for (const exp of spec.exports) {
-  if (exp.docs?.drift?.length) {
-    console.log(`${exp.name}: ${exp.docs.drift.length} drift issues`);
-  }
-}
+const { spec, diagnostics } = await doccov.analyzeFileWithDiagnostics(
+  'src/index.ts',
+  { filters: { visibility: ['public', 'beta'] } }
+);
+```
+
+### Coverage Analysis
+
+```typescript
+import { buildDocCovSpec, getExportDrift } from '@doccov/sdk';
+
+// Build DocCov spec with coverage data
+const doccovSpec = buildDocCovSpec({ openpkg, openpkgPath, packagePath });
+
+// Get drift for specific export
+const drifts = getExportDrift(someExport, doccovSpec);
+```
+
+### Example Validation
+
+```typescript
+import { runExamples, typecheckExamples, validateExamples } from '@doccov/sdk';
+
+// Run @example blocks
+const results = await runExamples(spec.exports, { cwd: process.cwd() });
+
+// Typecheck examples
+const typeErrors = await typecheckExamples(spec.exports, { cwd: process.cwd() });
+
+// Full validation
+const validation = await validateExamples(spec, {
+  validations: ['presence', 'typecheck', 'run'],
+  targetDir: process.cwd(),
+});
+```
+
+### Target Resolution
+
+```typescript
+import { resolveTarget, NodeFileSystem } from '@doccov/sdk';
+
+const fs = new NodeFileSystem(process.cwd());
+const { entryFile, targetDir, packageInfo } = await resolveTarget(fs, {
+  cwd: process.cwd(),
+  package: '@my/package', // For monorepos
+});
+```
+
+### History & Trends
+
+```typescript
+import { saveSnapshot, loadSnapshots, getTrend } from '@doccov/sdk';
+
+// Save coverage snapshot
+saveSnapshot(computeSnapshot(spec), process.cwd());
+
+// Load history
+const snapshots = loadSnapshots(process.cwd());
+
+// Get trend analysis
+const trend = getTrend(spec, process.cwd());
+console.log(`Delta: ${trend.delta}%`);
 ```
 
 ## Exports
 
+### Analysis
 - `DocCov` - Main analysis class
-- `runExample` / `runExamples` - Execute @example blocks
-- `detectExampleRuntimeErrors` - Check for runtime failures
+- `buildDocCovSpec` - Build coverage spec
+- `getExportDrift` - Get drift for an export
+- `generateReport` - Generate coverage reports
+
+### Examples
+- `runExamples` / `runExample` - Execute @example blocks
+- `typecheckExamples` - Type-check examples
+- `validateExamples` - Full example validation
+
+### Resolution
+- `resolveTarget` - Resolve entry points
+- `NodeFileSystem` - File system adapter
+- `detectPackageManager` - Detect npm/yarn/pnpm/bun
 
-## Documentation
+### History
+- `saveSnapshot` / `loadSnapshots` - Manage coverage history
+- `getTrend` / `getExtendedTrend` - Trend analysis
+- `pruneHistory` - Clean old snapshots
 
-- [SDK Overview](../../docs/sdk/overview.md)
-- [DocCov Class](../../docs/sdk/doccov-class.md)
-- [Example Runner](../../docs/sdk/example-runner.md)
-- [Filtering](../../docs/sdk/filtering.md)
+### Utilities
+- `diffSpecWithDocs` - Diff specs with doc impact
+- `parseMarkdownFiles` - Parse markdown for refs
+- `generateFix` / `applyPatchToJSDoc` - Auto-fix drift
 
 ## License
 

package/dist/index.d.ts

@@ -2515,7 +2515,7 @@ interface SpecSummary {
 * ```
 */
 declare function extractSpecSummary(openpkg: OpenPkg8, doccov: DocCovSpec4): SpecSummary;
-import { OpenPkg as OpenPkg_pdwketyesh } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg_gniycepely } from "@openpkg-ts/spec";
 /**
 * Build Plan types for AI-powered repository scanning.
 */
@@ -2612,7 +2612,7 @@ interface BuildPlanExecutionResult {
 	/** Whether all required steps succeeded */
 	success: boolean;
 	/** Generated OpenPkg spec (if successful) */
-	spec?: OpenPkg_pdwketyesh;
+	spec?: OpenPkg_gniycepely;
 	/** Results for each step */
 	stepResults: BuildPlanStepResult[];
 	/** Total execution time in milliseconds */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.25.7",
+  "version": "0.25.9",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -48,7 +48,7 @@
   ],
   "dependencies": {
     "@doccov/spec": "^0.24.1",
-    "@openpkg-ts/extract": "^0.14.1",
+    "@openpkg-ts/extract": "^0.14.3",
     "@openpkg-ts/spec": "^0.12.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",