@doccov/sdk 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -69,6 +69,214 @@ 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[];
+/**
+* Markdown/MDX documentation analysis types
+*/
+/**
+* A code block extracted from a markdown file
+*/
+interface MarkdownCodeBlock {
+	/** Language tag (ts, typescript, js, javascript, tsx, jsx) */
+	lang: string;
+	/** The code content */
+	code: string;
+	/** Raw meta string from code fence (e.g., "title=example.ts") */
+	meta?: string;
+	/** Starting line number in the markdown file */
+	lineStart: number;
+	/** Ending line number in the markdown file */
+	lineEnd: number;
+}
+/**
+* A parsed markdown documentation file
+*/
+interface MarkdownDocFile {
+	/** File path relative to project root */
+	path: string;
+	/** All executable code blocks found */
+	codeBlocks: MarkdownCodeBlock[];
+}
+/**
+* A reference to an found in markdown
+*/
+interface ExportReference {
+	/** The name of the being referenced */
+	exportName: string;
+	/** File path where the reference was found */
+	file: string;
+	/** Line number in the file */
+	line: number;
+	/** Surrounding code/text for context */
+	context: string;
+	/** Whether this reference is inside a code block */
+	inCodeBlock: boolean;
+	/** The code block index if inside a code block */
+	blockIndex?: number;
+}
+/**
+* Change type for an impacted reference
+*/
+type DocsChangeType = "signature-changed" | "removed" | "deprecated";
+/**
+* An impacted reference in a documentation file
+*/
+interface DocsImpactReference {
+	/** The name that was changed */
+	exportName: string;
+	/** Line number in the file */
+	line: number;
+	/** Type of change affecting this reference */
+	changeType: DocsChangeType;
+	/** Suggested fix (AI-generated or deterministic) */
+	suggestion?: string;
+	/** Context around the reference */
+	context?: string;
+}
+/**
+* Documentation file impact summary
+*/
+interface DocsImpact {
+	/** File path */
+	file: string;
+	/** All impacted references in this file */
+	references: DocsImpactReference[];
+}
+/**
+* Complete docs impact analysis result
+*/
+interface DocsImpactResult {
+	/** Files with impacted references */
+	impactedFiles: DocsImpact[];
+	/** New exports that have no documentation */
+	missingDocs: string[];
+	/** Statistics */
+	stats: {
+		/** Total markdown files scanned */
+		filesScanned: number;
+		/** Total code blocks found */
+		codeBlocksFound: number;
+		/** Total references found */
+		referencesFound: number;
+		/** References impacted by changes */
+		impactedReferences: number;
+	};
+}
+/**
+* Check if a language tag represents executable code
+*/
+declare function isExecutableLang(lang: string | null | undefined): boolean;
+/**
+* Parse a markdown file and extract code blocks
+*/
+declare function parseMarkdownFile(content: string, filePath: string): MarkdownDocFile;
+/**
+* Parse multiple markdown files
+*/
+declare function parseMarkdownFiles(files: Array<{
+	path: string;
+	content: string;
+}>): MarkdownDocFile[];
+/**
+* Extract import statements from code
+* Finds named imports: import { X, Y } from 'pkg'
+*/
+declare function extractImports(code: string): Array<{
+	name: string;
+	from: string;
+}>;
+/**
+* Extract function calls from code
+* Finds: functionName( or functionName<
+*/
+declare function extractFunctionCalls(code: string): string[];
+/**
+* Find all references to given names in markdown files
+*/
+declare function findExportReferences(files: MarkdownDocFile[], exportNames: string[]): ExportReference[];
+/**
+* Check if a code block references any of the given names
+*/
+declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
+import { SpecDiff } from "@openpkg-ts/spec";
+/**
+* Analyze docs impact from a spec diff
+*
+* @param diff - The spec diff result
+* @param markdownFiles - Parsed markdown files
+* @param newExportNames - All names in the new spec (for missing docs detection)
+*/
+declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFile[], newExportNames?: string[]): DocsImpactResult;
+/**
+* Find references to deprecated exports
+*/
+declare function findDeprecatedReferences(markdownFiles: MarkdownDocFile[], deprecatedExports: string[]): ExportReference[];
+/**
+* Find references to removed exports
+*/
+declare function findRemovedReferences(markdownFiles: MarkdownDocFile[], removedExports: string[]): ExportReference[];
+/**
+* Check if any docs reference a specific */
+declare function hasDocsForExport(markdownFiles: MarkdownDocFile[], exportName: string): boolean;
+/**
+* Get all exports that have documentation
+*/
+declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+/**
+* Get all exports that lack documentation
+*/
+declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+import { OpenPkg as OpenPkg2, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
+/**
+* Extended spec diff result with docs impact
+*/
+interface SpecDiffWithDocs extends SpecDiff2 {
+	/** Docs impact analysis (only present if markdown files provided) */
+	docsImpact?: DocsImpactResult;
+}
+/**
+* Options for diffSpecWithDocs
+*/
+interface DiffWithDocsOptions {
+	/** Parsed markdown documentation files */
+	markdownFiles?: MarkdownDocFile[];
+}
+/**
+* Compute spec diff with optional docs impact analysis
+*
+* @param oldSpec - Previous version of the spec
+* @param newSpec - Current version of the spec
+* @param options - Options including markdown files to analyze
+* @returns Extended diff result with docs impact
+*
+* @example
+* ```ts
+* import { diffSpecWithDocs, parseMarkdownFiles } from '@doccov/sdk';
+*
+* const markdownFiles = parseMarkdownFiles([
+*   { path: 'docs/guide.md', content: '...' },
+* ]);
+*
+* const diff = diffSpecWithDocs(oldSpec, newSpec, { markdownFiles });
+*
+* if (diff.docsImpact?.impactedFiles.length) {
+*   console.log('Docs need updating!');
+* }
+* ```
+*/
+declare function diffSpecWithDocs(oldSpec: OpenPkg2, newSpec: OpenPkg2, options?: DiffWithDocsOptions): SpecDiffWithDocs;
+/**
+* Check if a diff has any docs impact
+*/
+declare function hasDocsImpact(diff: SpecDiffWithDocs): boolean;
+/**
+* Get summary of docs impact for display
+*/
+declare function getDocsImpactSummary(diff: SpecDiffWithDocs): {
+	impactedFileCount: number;
+	impactedReferenceCount: number;
+	missingDocsCount: number;
+	totalIssues: number;
+};
 interface DocCovOptions {
 	includePrivate?: boolean;
 	followImports?: boolean;
@@ -258,5 +466,261 @@ declare class DocCov {
 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 { 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 };
+declare const OpenPkg3: typeof DocCov;
+/**
+* Project detection types for I/O-agnostic project analysis.
+* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
+*/
+/**
+* Minimal filesystem interface for I/O-agnostic detection.
+* Implementations: NodeFileSystem (CLI), SandboxFileSystem (API)
+*/
+interface FileSystem {
+	/** Check if a file or directory exists */
+	exists(path: string): Promise<boolean>;
+	/** Read file contents as string */
+	readFile(path: string): Promise<string>;
+	/** List directory contents (file/folder names only) */
+	readDir(path: string): Promise<string[]>;
+	/** Check if path is a directory */
+	isDirectory(path: string): Promise<boolean>;
+}
+/** Supported package managers */
+type PackageManager = "npm" | "yarn" | "pnpm" | "bun";
+/** Package manager detection result with install/run commands */
+interface PackageManagerInfo {
+	/** Package manager name */
+	name: PackageManager;
+	/** Lockfile that was detected (null if none found) */
+	lockfile: string | null;
+	/** Arguments for install command, e.g. ['install', '--frozen-lockfile'] */
+	installArgs: string[];
+	/** Prefix for running scripts, e.g. ['npm', 'run'] or ['pnpm'] */
+	runPrefix: string[];
+}
+/** Monorepo type based on configuration */
+type MonorepoType = "npm-workspaces" | "pnpm-workspaces" | "lerna" | "none";
+/** Monorepo detection result */
+interface MonorepoInfo {
+	/** Whether this is a monorepo */
+	isMonorepo: boolean;
+	/** Type of monorepo configuration */
+	type: MonorepoType;
+	/** Workspace patterns from config (e.g. ['packages/*']) */
+	patterns: string[];
+	/** Resolved workspace packages */
+	packages: WorkspacePackage[];
+}
+/** A package within a monorepo workspace */
+interface WorkspacePackage {
+	/** Package name from package.json */
+	name: string;
+	/** Relative path to package directory */
+	path: string;
+	/** Whether the package is marked as private */
+	private: boolean;
+}
+/** Entry point source - where the entry was detected from */
+type EntryPointSource = "types" | "exports" | "main" | "module" | "fallback";
+/** Entry point detection result */
+interface EntryPointInfo {
+	/** Path to entry file (relative to package root) */
+	path: string;
+	/** Where the entry point was detected from */
+	source: EntryPointSource;
+	/** Whether this is a .d.ts file (no source available) */
+	isDeclarationOnly: boolean;
+}
+/** Build configuration detection result */
+interface BuildInfo {
+	/** Build-related script names found (e.g. ['build', 'build:types']) */
+	scripts: string[];
+	/** Whether any build script was found */
+	hasBuildScript: boolean;
+	/** Whether TypeScript is configured/installed */
+	hasTypeScript: boolean;
+	/** Indicators for exotic project types */
+	exoticIndicators: {
+		/** WASM project (Cargo.toml or wasm-pack scripts) */
+		wasm: boolean;
+		/** napi-rs native addon project */
+		napi: boolean;
+	};
+}
+/** Complete project analysis result */
+interface ProjectInfo {
+	/** Package manager info */
+	packageManager: PackageManagerInfo;
+	/** Monorepo info */
+	monorepo: MonorepoInfo;
+	/** Entry point info */
+	entryPoint: EntryPointInfo;
+	/** Build info */
+	build: BuildInfo;
+}
+/** Options for analyzeProject() */
+interface AnalyzeProjectOptions {
+	/** Target package name for monorepos */
+	targetPackage?: string;
+}
+import { Sandbox } from "@vercel/sandbox";
+/**
+* Node.js filesystem implementation for CLI usage.
+* Wraps Node.js fs module with a base path.
+*/
+declare class NodeFileSystem implements FileSystem {
+	private basePath;
+	constructor(basePath: string);
+	private resolve;
+	exists(relativePath: string): Promise<boolean>;
+	readFile(relativePath: string): Promise<string>;
+	readDir(relativePath: string): Promise<string[]>;
+	isDirectory(relativePath: string): Promise<boolean>;
+}
+/**
+* Vercel Sandbox filesystem implementation for API usage.
+* Uses sandbox.runCommand() with shell commands.
+*/
+declare class SandboxFileSystem implements FileSystem {
+	private sandbox;
+	constructor(sandbox: Sandbox);
+	exists(path: string): Promise<boolean>;
+	readFile(path: string): Promise<string>;
+	readDir(path: string): Promise<string[]>;
+	isDirectory(path: string): Promise<boolean>;
+}
+/**
+* Detect package manager based on lockfile presence.
+*
+* Priority order:
+* 1. pnpm-lock.yaml
+* 2. bun.lock / bun.lockb
+* 3. yarn.lock
+* 4. package-lock.json
+* 5. Default to npm
+*/
+declare function detectPackageManager(fs: FileSystem): Promise<PackageManagerInfo>;
+/**
+* Get install command for a package manager.
+* Returns [command, ...args] array.
+*/
+declare function getInstallCommand(pm: PackageManagerInfo): string[];
+/**
+* Get run command for a package manager script.
+* Returns [command, ...args, scriptName] array.
+*/
+declare function getRunCommand(pm: PackageManagerInfo, script: string): string[];
+/**
+* Detect if a project is a monorepo and list its packages.
+*
+* Detection triggers (in order):
+* 1. package.json has workspaces field (npm/yarn)
+* 2. pnpm-workspace.yaml exists
+* 3. lerna.json exists
+*/
+declare function detectMonorepo(fs: FileSystem): Promise<MonorepoInfo>;
+/**
+* Find a package by name or path in a list of workspace packages.
+*/
+declare function findPackageByName(packages: WorkspacePackage[], nameOrPath: string): WorkspacePackage | undefined;
+/**
+* Format package list for display in error messages.
+*/
+declare function formatPackageList(packages: WorkspacePackage[], limit?: number): string;
+/**
+* Detect the TypeScript entry point for a package.
+*
+* Priority order:
+* 1. package.json -> types or typings field
+* 2. package.json -> exports["."].types
+* 3. package.json -> main field (resolve to .ts)
+* 4. package.json -> module field (resolve to .ts)
+* 5. Common fallback paths
+*
+* @param fs - FileSystem implementation
+* @param packagePath - Path to package directory (default: ".")
+* @returns Entry point info
+* @throws Error if no entry point can be found
+*/
+declare function detectEntryPoint(fs: FileSystem, packagePath?: string): Promise<EntryPointInfo>;
+/**
+* Detect build configuration and exotic project indicators.
+*
+* @param fs - FileSystem implementation
+* @param packagePath - Path to package directory (default: ".")
+* @returns Build info including scripts and exotic indicators
+*/
+declare function detectBuildInfo(fs: FileSystem, packagePath?: string): Promise<BuildInfo>;
+/**
+* Get the primary build script name to run.
+* Prefers 'build' over 'compile' over 'tsc'.
+*/
+declare function getPrimaryBuildScript(buildInfo: BuildInfo): string | null;
+/**
+* Safely parse a JSON file, returning null on any error.
+*/
+declare function safeParseJson<T = Record<string, unknown>>(fs: FileSystem, path: string): Promise<T | null>;
+/**
+* Standard package.json structure for detection purposes.
+*/
+interface PackageJson {
+	name?: string;
+	version?: string;
+	private?: boolean;
+	main?: string;
+	module?: string;
+	types?: string;
+	typings?: string;
+	exports?: PackageExports;
+	workspaces?: string[] | {
+		packages: string[];
+	};
+	scripts?: Record<string, string>;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+}
+/**
+* Package.json exports field structure.
+*/
+type PackageExports = string | {
+	"."?: string | {
+		types?: string;
+		import?: string;
+		require?: string;
+		default?: string;
+	};
+	[key: string]: unknown;
+};
+/**
+* Read and parse package.json from a directory.
+*/
+declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJson | null>;
+/**
+* Analyze a project's structure for scanning.
+*
+* This is the main entry point for project detection. It combines all
+* detection functions into a single call that returns complete project info.
+*
+* For monorepos, you must specify the target package via options.targetPackage.
+* If not specified and a monorepo is detected, an error is thrown with the
+* list of available packages.
+*
+* @param fs - FileSystem implementation (NodeFileSystem or SandboxFileSystem)
+* @param options - Options including targetPackage for monorepos
+* @returns Complete project info
+* @throws Error if monorepo detected without targetPackage specified
+* @throws Error if targetPackage not found in monorepo
+*
+* @example
+* ```typescript
+* // Single package
+* const fs = new NodeFileSystem('/path/to/package');
+* const project = await analyzeProject(fs);
+*
+* // Monorepo with target package
+* const fs = new NodeFileSystem('/path/to/monorepo');
+* const project = await analyzeProject(fs, { targetPackage: '@scope/core' });
+* ```
+*/
+declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
+export { serializeJSDoc, safeParseJson, runExamplesWithPackage, runExamples, runExample, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseJSDocToPatch, parseAssertions, mergeFixes, isFixableDrift, isExecutableLang, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, getUndocumentedExports, getRunCommand, getPrimaryBuildScript, getInstallCommand, getDocumentedExports, getDocsImpactSummary, generateFixesForExport, generateFix, formatPackageList, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, extractPackageSpec, extractImports, extractFunctionCalls, diffSpecWithDocs, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, createSourceFile, categorizeDrifts, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, SpecDiffWithDocs, SandboxFileSystem, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ProjectInfo, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg3 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoInfo, MarkdownDocFile, MarkdownCodeBlock, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, FixType, FixSuggestion, FilterOptions, FileSystem, ExportReference, ExampleRunResult, EntryPointSource, EntryPointInfo, DocsImpactResult, DocsImpactReference, DocsImpact, DocsChangeType, DocCovOptions, DocCov, DiffWithDocsOptions, Diagnostic, BuildInfo, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult };