@doccov/sdk 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,103 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Ryan Waits
+Licensed Work:        DocCov SDK
+                      The Licensed Work is (c) 2024 Ryan Waits.
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you do not use the Licensed Work for a Documentation
+                      Coverage Service.
+
+                      A "Documentation Coverage Service" is a commercial
+                      offering that allows third parties to access the
+                      functionality of the Licensed Work by analyzing
+                      TypeScript/JavaScript code documentation coverage
+                      as a service.
+
+Change Date:          2028-11-26
+
+Change License:       Apache License 2.0
+
+For information about alternative licensing arrangements for the Software,
+please contact: licensing@doccov.dev
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

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 };