@doccov/sdk 0.2.1

package/README.md

@@ -0,0 +1,68 @@
+# @doccov/sdk
+
+Programmatic API for documentation coverage analysis and drift detection in TypeScript.
+
+## Install
+```bash
+npm install @doccov/sdk
+```
+
+## Minimal Usage
+```ts
+import { DocCov } from '@doccov/sdk';
+
+const doccov = new DocCov();
+const { spec, diagnostics } = await doccov.analyzeFileWithDiagnostics('src/index.ts');
+
+console.log(`Coverage: ${spec.docs?.coverageScore}%`);
+console.log(`${spec.exports.length} exports analyzed`);
+```
+
+## Checking for Drift
+```ts
+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}`);
+      }
+    }
+  }
+}
+```
+
+## 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
+
+## Filters
+```ts
+const { spec } = await doccov.analyzeFileWithDiagnostics('src/index.ts', {
+  filters: {
+    include: ['publicApi'],
+    exclude: ['internalHelper'],
+  },
+});
+```
+
+## 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
+}
+```
+
+## See Also
+- [Spec helpers](../spec/README.md)
+- [CLI usage](../cli/README.md)
+- [Fixtures](../../tests/fixtures/README.md)
+
+MIT License

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { OpenPkg } from "@openpkg-ts/spec";
+type OpenPkgSpec = OpenPkg;
+interface DocCovOptions {
+	includePrivate?: boolean;
+	followImports?: boolean;
+	maxDepth?: number;
+	resolveExternalTypes?: boolean;
+}
+/** @deprecated Use DocCovOptions instead */
+type OpenPkgOptions = DocCovOptions;
+declare function extractPackageSpec(entryFile: string, packageDir?: string, content?: string, options?: OpenPkgOptions): Promise<OpenPkgSpec>;
+interface FilterOptions {
+	include?: string[];
+	exclude?: string[];
+}
+interface Diagnostic {
+	message: string;
+	severity: "error" | "warning" | "info";
+	location?: {
+		file: string;
+		line?: number;
+		column?: number;
+	};
+}
+interface AnalysisResult {
+	spec: OpenPkgSpec;
+	diagnostics: Diagnostic[];
+	metadata: AnalysisMetadata;
+}
+interface AnalysisMetadata {
+	baseDir: string;
+	configPath?: string;
+	packageJsonPath?: string;
+	hasNodeModules: boolean;
+	resolveExternalTypes: boolean;
+}
+interface AnalyzeOptions {
+	filters?: FilterOptions;
+}
+declare class DocCov {
+	private readonly options;
+	constructor(options?: DocCovOptions);
+	analyze(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeFile(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeProject(entryPath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeWithDiagnostics(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	analyzeFileWithDiagnostics(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	private normalizeDiagnostic;
+	private mapSeverity;
+	private normalizeMetadata;
+	private applySpecFilters;
+}
+declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
+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 };