@doccov/sdk 0.2.2 → 0.3.0

package/README.md

@@ -1,68 +1,44 @@
 # @doccov/sdk
 
-Programmatic API for documentation coverage analysis and drift detection in TypeScript.
+Programmatic API for documentation coverage analysis.
 
 ## Install
+
 ```bash
 npm install @doccov/sdk
 ```
 
-## Minimal Usage
-```ts
+## Usage
+
+```typescript
 import { DocCov } from '@doccov/sdk';
 
 const doccov = new DocCov();
-const { spec, diagnostics } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
 
 console.log(`Coverage: ${spec.docs?.coverageScore}%`);
-console.log(`${spec.exports.length} exports analyzed`);
-```
 
-## Checking for Drift
-```ts
+// Check for drift
 for (const exp of spec.exports) {
-  const drift = exp.docs?.drift ?? [];
-  if (drift.length > 0) {
-    console.log(`${exp.name}: ${drift.length} drift issues`);
-    for (const d of drift) {
-      console.log(`  - ${d.issue}`);
-      if (d.suggestion) {
-        console.log(`    Suggestion: ${d.suggestion}`);
-      }
-    }
+  if (exp.docs?.drift?.length) {
+    console.log(`${exp.name}: ${exp.docs.drift.length} drift issues`);
   }
 }
 ```
 
-## Helper Functions
-- `analyze(code)` – analyze an in-memory string
-- `analyzeFile(path)` – analyze a single entry point
-- `analyzeWithDiagnostics` / `analyzeFileWithDiagnostics` – include TypeScript diagnostics
-- `extractPackageSpec` – lower-level hook used by the CLI
+## Exports
 
-## Filters
-```ts
-const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts', {
-  filters: {
-    include: ['publicApi'],
-    exclude: ['internalHelper'],
-  },
-});
-```
+- `DocCov` - Main analysis class
+- `runExample` / `runExamples` - Execute @example blocks
+- `detectExampleRuntimeErrors` - Check for runtime failures
 
-## Coverage Metadata
-Each export includes documentation health info:
-```ts
-interface SpecDocsMetadata {
-  coverageScore?: number;           // 0-100
-  missing?: ('description' | 'params' | 'returns' | 'examples')[];
-  drift?: SpecDocDrift[];           // List of drift issues
-}
-```
+## Documentation
+
+- [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)
 
-## See Also
-- [Spec helpers](../spec/README.md)
-- [CLI usage](../cli/README.md)
-- [Fixtures](../../tests/fixtures/README.md)
+## License
 
-MIT License
+MIT

package/dist/index.d.ts

@@ -1,5 +1,74 @@
+import { SpecDocDrift, SpecExport } from "@openpkg-ts/spec";
+interface ExampleRunResult {
+	success: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+	duration: number;
+}
+interface RunExampleOptions {
+	/** Timeout in milliseconds (default: 5000) */
+	timeout?: number;
+	/** Working directory for execution */
+	cwd?: string;
+}
+interface RunExamplesWithPackageOptions extends RunExampleOptions {
+	/** Path to the local package to install */
+	packagePath: string;
+	/** Package manager to use (auto-detected if not specified) */
+	packageManager?: "npm" | "pnpm" | "bun";
+	/** Timeout for package installation in ms (default: 60000) */
+	installTimeout?: number;
+}
+interface RunExamplesWithPackageResult {
+	/** Results for each example by index */
+	results: Map<number, ExampleRunResult>;
+	/** Whether package installation succeeded */
+	installSuccess: boolean;
+	/** Error message if installation failed */
+	installError?: string;
+	/** Total duration including install */
+	totalDuration: number;
+}
+/**
+* Run an example code snippet in an isolated Node process.
+* Uses Node 22+ --experimental-strip-types for direct TS execution.
+*/
+declare function runExample(code: string, options?: RunExampleOptions): Promise<ExampleRunResult>;
+/**
+* Run multiple examples and collect results
+*/
+declare function runExamples(examples: string[], options?: RunExampleOptions): Promise<Map<number, ExampleRunResult>>;
+/**
+* Run multiple examples with a pre-installed local package.
+* Creates a single temp directory, installs the package once,
+* runs all examples, then cleans up.
+*/
+declare function runExamplesWithPackage(examples: string[], options: RunExamplesWithPackageOptions): Promise<RunExamplesWithPackageResult>;
 import { OpenPkg } from "@openpkg-ts/spec";
 type OpenPkgSpec = OpenPkg;
+/**
+* Detect runtime errors in @example blocks.
+* Results are provided externally after running examples via runExamples().
+*/
+declare function detectExampleRuntimeErrors(entry: SpecExport, 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: SpecExport, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 interface DocCovOptions {
 	includePrivate?: boolean;
 	followImports?: boolean;
@@ -13,9 +82,145 @@ interface FilterOptions {
 	include?: string[];
 	exclude?: string[];
 }
+import { SpecDocDrift as SpecDocDrift2, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+import * as TS from "typescript";
+/**
+* Represents a single parameter in a JSDoc patch
+*/
+interface JSDocParam {
+	name: string;
+	type?: string;
+	description?: string;
+	optional?: boolean;
+}
+/**
+* Represents a return type in a JSDoc patch
+*/
+interface JSDocReturn {
+	type?: string;
+	description?: string;
+}
+/**
+* Represents a generic tag in a JSDoc patch
+*/
+interface JSDocTag {
+	name: string;
+	text: string;
+}
+/**
+* A patchable representation of a JSDoc comment
+*/
+interface JSDocPatch {
+	description?: string;
+	params?: JSDocParam[];
+	returns?: JSDocReturn;
+	examples?: string[];
+	deprecated?: string | false;
+	async?: boolean;
+	type?: string;
+	typeParams?: Array<{
+		name: string;
+		constraint?: string;
+		description?: string;
+	}>;
+	otherTags?: JSDocTag[];
+}
+/**
+* Represents an edit to be applied to a source file
+*/
+interface JSDocEdit {
+	filePath: string;
+	symbolName: string;
+	startLine: number;
+	endLine: number;
+	hasExisting: boolean;
+	existingJSDoc?: string;
+	newJSDoc: string;
+	indent: string;
+}
+/**
+* Result of applying edits to source files
+*/
+interface ApplyEditsResult {
+	filesModified: number;
+	editsApplied: number;
+	errors: Array<{
+		file: string;
+		error: string;
+	}>;
+}
+/**
+* Parse a JSDoc comment string into a patchable structure
+*/
+declare function parseJSDocToPatch(jsDocText: string): JSDocPatch;
+/**
+* Apply a partial patch to an existing JSDoc patch, preserving unmodified content
+*/
+declare function applyPatchToJSDoc(existing: JSDocPatch, updates: Partial<JSDocPatch>): JSDocPatch;
+/**
+* Serialize a JSDocPatch back to a formatted comment string
+*/
+declare function serializeJSDoc(patch: JSDocPatch, indent?: string): string;
+/**
+* Find the JSDoc location for a declaration in a source file
+*/
+declare function findJSDocLocation(sourceFile: TS.SourceFile, symbolName: string, approximateLine?: number): {
+	startLine: number;
+	endLine: number;
+	declarationLine: number;
+	hasExisting: boolean;
+	existingJSDoc?: string;
+	indent: string;
+} | null;
+/**
+* Apply a batch of edits to source files
+*/
+declare function applyEdits(edits: JSDocEdit[]): Promise<ApplyEditsResult>;
+/**
+* Create a TypeScript source file from a file path
+*/
+declare function createSourceFile(filePath: string): TS.SourceFile;
+/**
+* Types of fixes that can be generated
+*/
+type FixType = "add-param" | "remove-param" | "update-param-type" | "update-param-optionality" | "update-return-type" | "update-assertion" | "add-template" | "update-template-constraint" | "add-deprecated" | "remove-deprecated" | "add-async" | "remove-async" | "update-property-type";
+/**
+* A fix suggestion with the patch to apply
+*/
+interface FixSuggestion {
+	type: FixType;
+	driftType: SpecDocDrift2["type"];
+	target: string;
+	description: string;
+	patch: Partial<JSDocPatch>;
+}
+/**
+* Check if a drift type can be fixed deterministically
+*/
+declare function isFixableDrift(drift: SpecDocDrift2): boolean;
+/**
+* Generate a fix for a single drift issue
+*/
+declare function generateFix(drift: SpecDocDrift2, exportEntry: SpecExport2, existingPatch?: JSDocPatch): FixSuggestion | null;
+/**
+* Generate all fixes for an export's drift issues
+*/
+declare function generateFixesForExport(exportEntry: SpecExport2, existingPatch?: JSDocPatch): FixSuggestion[];
+/**
+* Merge multiple fix patches into a single patch
+*/
+declare function mergeFixes(fixes: FixSuggestion[], basePatch?: JSDocPatch): JSDocPatch;
+/**
+* Get a summary of fixable vs non-fixable drifts
+*/
+declare function categorizeDrifts(drifts: SpecDocDrift2[]): {
+	fixable: SpecDocDrift2[];
+	nonFixable: SpecDocDrift2[];
+};
 interface Diagnostic {
 	message: string;
 	severity: "error" | "warning" | "info";
+	suggestion?: string;
 	location?: {
 		file: string;
 		line?: number;
@@ -54,4 +259,4 @@ declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPk
 declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 /** @deprecated Use DocCov instead */
 declare const OpenPkg2: typeof DocCov;
-export { extractPackageSpec, analyzeFile, analyze, OpenPkgSpec, OpenPkgOptions, OpenPkg2 as OpenPkg, FilterOptions, DocCovOptions, DocCov, Diagnostic, AnalyzeOptions, AnalysisResult };
+export { serializeJSDoc, runExamplesWithPackage, runExamples, runExample, parseJSDocToPatch, parseAssertions, mergeFixes, isFixableDrift, hasNonAssertionComments, generateFixesForExport, generateFix, findJSDocLocation, extractPackageSpec, detectExampleRuntimeErrors, detectExampleAssertionFailures, createSourceFile, categorizeDrifts, applyPatchToJSDoc, applyEdits, analyzeFile, analyze, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, OpenPkgSpec, OpenPkgOptions, OpenPkg2 as OpenPkg, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, FixType, FixSuggestion, FilterOptions, ExampleRunResult, DocCovOptions, DocCov, Diagnostic, ApplyEditsResult, AnalyzeOptions, AnalysisResult };