@doccov/sdk 0.5.8 → 0.6.0

package/dist/index.d.ts

@@ -70,254 +70,260 @@ declare function hasNonAssertionComments(code: string): boolean;
 */
 declare function detectExampleAssertionFailures(entry: SpecExport, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 /**
-* Markdown/MDX documentation analysis types
+* Project detection types for I/O-agnostic project analysis.
+* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
 */
 /**
-* A code block extracted from a markdown file
+* Minimal filesystem interface for I/O-agnostic detection.
+* Implementations: NodeFileSystem (CLI), SandboxFileSystem (API)
 */
-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;
+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>;
 }
-/**
-* A parsed markdown documentation file
-*/
-interface MarkdownDocFile {
-	/** File path relative to project root */
+/** 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;
-	/** All executable code blocks found */
-	codeBlocks: MarkdownCodeBlock[];
+	/** 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;
 }
 /**
-* A reference to an found in markdown
+* 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
 */
-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;
-}
+declare function detectBuildInfo(fs: FileSystem, packagePath?: string): Promise<BuildInfo>;
 /**
-* Change type for an impacted reference
+* Get the primary build script name to run.
+* Prefers 'build' over 'compile' over 'tsc'.
 */
-type DocsChangeType = "signature-changed" | "removed" | "deprecated" | "method-removed" | "method-changed" | "method-deprecated";
+declare function getPrimaryBuildScript(buildInfo: BuildInfo): string | null;
 /**
-* Member-level change type
+* 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
 */
-type MemberChangeType = "added" | "removed" | "signature-changed";
+declare function detectEntryPoint(fs: FileSystem, packagePath?: string): Promise<EntryPointInfo>;
+import { Sandbox } from "@vercel/sandbox";
 /**
-* An impacted reference in a documentation file
+* Node.js filesystem implementation for CLI usage.
+* Wraps Node.js fs module with a base path.
 */
-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;
-	/** Member/method name if this is a member-level change */
-	memberName?: string;
-	/** Type of member change (added, removed, signature-changed) */
-	memberChangeType?: MemberChangeType;
-	/** Suggested replacement for removed/changed members */
-	replacementSuggestion?: string;
-	/** True if this is just a class instantiation (new ClassName()) */
-	isInstantiation?: boolean;
+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>;
 }
 /**
-* Documentation file impact summary
+* Vercel Sandbox filesystem implementation for API usage.
+* Uses sandbox.runCommand() with shell commands.
 */
-interface DocsImpact {
-	/** File path */
-	file: string;
-	/** All impacted references in this file */
-	references: DocsImpactReference[];
+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>;
 }
 /**
-* Complete docs impact analysis result
+* 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
 */
-interface DocsImpactResult {
-	/** Files with impacted references */
-	impactedFiles: DocsImpact[];
-	/** New exports (from this diff) that have no documentation */
-	missingDocs: string[];
-	/** ALL exports from the spec that have no documentation in the scanned files */
-	allUndocumented: 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;
-		/** Total exports in the spec */
-		totalExports: number;
-		/** Exports found documented in markdown */
-		documentedExports: number;
-	};
-}
+declare function detectMonorepo(fs: FileSystem): Promise<MonorepoInfo>;
 /**
-* Check if a language tag represents executable code
+* Find a package by name or path in a list of workspace packages.
 */
-declare function isExecutableLang(lang: string | null | undefined): boolean;
+declare function findPackageByName(packages: WorkspacePackage[], nameOrPath: string): WorkspacePackage | undefined;
 /**
-* Parse a markdown file and extract code blocks
+* Format package list for display in error messages.
 */
-declare function parseMarkdownFile(content: string, filePath: string): MarkdownDocFile;
+declare function formatPackageList(packages: WorkspacePackage[], limit?: number): string;
 /**
-* Parse multiple markdown files
+* Detect package manager based on lockfile presence and package.json hints.
+*
+* Resolution order:
+* 1. packageManager field in package.json (e.g., "pnpm@9.0.0")
+* 2. Most recently modified lockfile (when multiple exist)
+* 3. Static priority order: pnpm > bun > yarn > npm
+* 4. Default to npm
 */
-declare function parseMarkdownFiles(files: Array<{
-	path: string;
-	content: string;
-}>): MarkdownDocFile[];
+declare function detectPackageManager(fs: FileSystem): Promise<PackageManagerInfo>;
 /**
-* Extract import statements from code
-* Finds named imports: import { X, Y } from 'pkg'
+* Get install command for a package manager.
+* Returns [command, ...args] array.
 */
-declare function extractImports(code: string): Array<{
-	name: string;
-	from: string;
-}>;
+declare function getInstallCommand(pm: PackageManagerInfo): string[];
 /**
-* Extract function calls from code
-* Finds: functionName( or functionName<
+* Get run command for a package manager script.
+* Returns [command, ...args, scriptName] array.
 */
-declare function extractFunctionCalls(code: string): string[];
+declare function getRunCommand(pm: PackageManagerInfo, script: string): string[];
 /**
-* Find all references to given names in markdown files
+* Safely parse a JSON file, returning null on any error.
 */
-declare function findExportReferences(files: MarkdownDocFile[], exportNames: string[]): ExportReference[];
+declare function safeParseJson<T = Record<string, unknown>>(fs: FileSystem, path: string): Promise<T | null>;
 /**
-* Check if a code block references any of the given names
+* Standard package.json structure for detection purposes.
 */
-declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
-import { SpecDiff } from "@openpkg-ts/spec";
-type MemberChangeType2 = "added" | "removed" | "signature-changed";
-interface MemberChange {
-	/** The class this member belongs to */
-	className: string;
-	/** The member name (e.g., "evaluateChainhook") */
-	memberName: string;
-	/** Kind of member */
-	memberKind: "method" | "property" | "accessor" | "constructor";
-	/** Type of change */
-	changeType: MemberChangeType2;
-	/** Old signature string (for signature changes) */
-	oldSignature?: string;
-	/** New signature string (for signature changes) */
-	newSignature?: string;
-	/** Suggested replacement (e.g., "Use replayChainhook instead") */
-	suggestion?: string;
+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>;
 }
 /**
-* 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)
-* @param memberChanges - Optional member-level changes for granular detection
-*/
-declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFile[], newExportNames?: string[], memberChanges?: MemberChange[]): 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 { CategorizedBreaking, OpenPkg as OpenPkg3, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
-/**
-* Extended spec diff result with docs impact
+* Package.json exports field structure.
 */
-interface SpecDiffWithDocs extends SpecDiff2 {
-	/** Docs impact analysis (only present if markdown files provided) */
-	docsImpact?: DocsImpactResult;
-	/** Member-level changes for classes (methods added/removed/changed) */
-	memberChanges?: MemberChange[];
-	/** Breaking changes categorized by severity (high/medium/low) */
-	categorizedBreaking?: CategorizedBreaking[];
-}
+type PackageExports = string | {
+	"."?: string | {
+		types?: string;
+		import?: string;
+		require?: string;
+		default?: string;
+	};
+	[key: string]: unknown;
+};
 /**
-* Options for diffSpecWithDocs
+* Read and parse package.json from a directory.
 */
-interface DiffWithDocsOptions {
-	/** Parsed markdown documentation files */
-	markdownFiles?: MarkdownDocFile[];
-}
+declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJson | null>;
 /**
-* Compute spec diff with optional docs impact analysis
+* Analyze a project's structure for scanning.
 *
-* @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
+* This is the main entry point for project detection. It combines all
+* detection functions into a single call that returns complete project info.
 *
-* @example
-* ```ts
-* import { diffSpecWithDocs, parseMarkdownFiles } from '@doccov/sdk';
+* 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.
 *
-* const markdownFiles = parseMarkdownFiles([
-*   { path: 'docs/guide.md', content: '...' },
-* ]);
+* @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
 *
-* const diff = diffSpecWithDocs(oldSpec, newSpec, { markdownFiles });
+* @example
+* ```typescript
+* // Single package
+* const fs = new NodeFileSystem('/path/to/package');
+* const project = await analyzeProject(fs);
 *
-* if (diff.docsImpact?.impactedFiles.length) {
-*   console.log('Docs need updating!');
-* }
+* // Monorepo with target package
+* const fs = new NodeFileSystem('/path/to/monorepo');
+* const project = await analyzeProject(fs, { targetPackage: '@scope/core' });
 * ```
 */
-declare function diffSpecWithDocs(oldSpec: OpenPkg3, newSpec: OpenPkg3, 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;
-	memberChangesCount: number;
-};
+declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
 interface DocCovOptions {
 	includePrivate?: boolean;
 	followImports?: boolean;
@@ -466,348 +472,346 @@ declare function categorizeDrifts(drifts: SpecDocDrift2[]): {
 	fixable: SpecDocDrift2[];
 	nonFixable: SpecDocDrift2[];
 };
-interface Diagnostic {
+import { SpecExport as SpecExport4 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+type LintSeverity = "error" | "warn" | "off";
+interface LintViolation {
+	rule: string;
+	severity: "error" | "warn";
 	message: string;
-	severity: "error" | "warning" | "info";
-	suggestion?: string;
-	location?: {
-		file: string;
-		line?: number;
-		column?: number;
-	};
+	line?: number;
+	fixable: boolean;
 }
-interface AnalysisResult {
-	spec: OpenPkgSpec;
-	diagnostics: Diagnostic[];
-	metadata: AnalysisMetadata;
+interface LintRule {
+	name: string;
+	defaultSeverity: LintSeverity;
+	check(exp: SpecExport3, rawJSDoc?: string): LintViolation[];
+	fix?(exp: SpecExport3, rawJSDoc?: string): JSDocPatch | null;
 }
-interface AnalysisMetadata {
-	baseDir: string;
-	configPath?: string;
-	packageJsonPath?: string;
-	hasNodeModules: boolean;
-	resolveExternalTypes: boolean;
+interface LintConfig {
+	rules: Record<string, LintSeverity>;
 }
-interface AnalyzeOptions {
-	filters?: FilterOptions;
+interface LintResult {
+	violations: LintViolation[];
+	errorCount: number;
+	warningCount: number;
+	fixableCount: number;
 }
-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;
+/** All available lint rules */
+declare const allRules: LintRule[];
+/** Default configuration with rule defaults */
+declare function getDefaultConfig(): LintConfig;
+/** Get a rule by name */
+declare function getRule(name: string): LintRule | undefined;
+/** Lint a single */
+declare function lintExport(exp: SpecExport4, rawJSDoc?: string, config?: LintConfig): LintViolation[];
+/** Lint multiple exports and aggregate results */
+declare function lintExports(exports: Array<{
+	export: SpecExport4;
+	rawJSDoc?: string;
+}>, config?: LintConfig): LintResult;
+/** Merge user config with defaults */
+declare function mergeConfig(userConfig: Partial<LintConfig>): LintConfig;
+declare const consistentParamStyle: LintRule;
+declare const noEmptyReturns: LintRule;
+declare const requireDescription: LintRule;
+declare const requireExample: LintRule;
+import { SpecDiff } from "@openpkg-ts/spec";
+type MemberChangeType = "added" | "removed" | "signature-changed";
+interface MemberChange {
+	/** The class this member belongs to */
+	className: string;
+	/** The member name (e.g., "evaluateChainhook") */
+	memberName: string;
+	/** Kind of member */
+	memberKind: "method" | "property" | "accessor" | "constructor";
+	/** Type of change */
+	changeType: MemberChangeType;
+	/** Old signature string (for signature changes) */
+	oldSignature?: string;
+	/** New signature string (for signature changes) */
+	newSignature?: string;
+	/** Suggested replacement (e.g., "Use replayChainhook instead") */
+	suggestion?: string;
 }
-declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
-declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
-/** @deprecated Use DocCov instead */
-declare const OpenPkg4: typeof DocCov;
 /**
-* Project detection types for I/O-agnostic project analysis.
-* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
+* Markdown/MDX documentation analysis types
 */
 /**
-* Minimal filesystem interface for I/O-agnostic detection.
-* Implementations: NodeFileSystem (CLI), SandboxFileSystem (API)
+* A code block extracted from a markdown file
 */
-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;
+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;
 }
-/** 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) */
+/**
+* A parsed markdown documentation file
+*/
+interface MarkdownDocFile {
+	/** File path relative to project 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;
-	};
+	/** All executable code blocks found */
+	codeBlocks: MarkdownCodeBlock[];
 }
-/** Complete project analysis result */
-interface ProjectInfo {
-	/** Package manager info */
-	packageManager: PackageManagerInfo;
-	/** Monorepo info */
-	monorepo: MonorepoInfo;
-	/** Entry point info */
-	entryPoint: EntryPointInfo;
-	/** Build info */
-	build: BuildInfo;
+/**
+* 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;
 }
-/** Options for analyzeProject() */
-interface AnalyzeProjectOptions {
-	/** Target package name for monorepos */
-	targetPackage?: string;
+/**
+* Change type for an impacted reference
+*/
+type DocsChangeType = "signature-changed" | "removed" | "deprecated" | "method-removed" | "method-changed" | "method-deprecated";
+/**
+* Member-level change type
+*/
+type MemberChangeType2 = "added" | "removed" | "signature-changed";
+/**
+* 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;
+	/** Member/method name if this is a member-level change */
+	memberName?: string;
+	/** Type of member change (added, removed, signature-changed) */
+	memberChangeType?: MemberChangeType2;
+	/** Suggested replacement for removed/changed members */
+	replacementSuggestion?: string;
+	/** True if this is just a class instantiation (new ClassName()) */
+	isInstantiation?: boolean;
 }
-import { Sandbox } from "@vercel/sandbox";
 /**
-* Node.js filesystem implementation for CLI usage.
-* Wraps Node.js fs module with a base path.
+* Documentation file impact summary
 */
-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>;
+interface DocsImpact {
+	/** File path */
+	file: string;
+	/** All impacted references in this file */
+	references: DocsImpactReference[];
 }
 /**
-* Vercel Sandbox filesystem implementation for API usage.
-* Uses sandbox.runCommand() with shell commands.
+* Complete docs impact analysis result
 */
-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>;
+interface DocsImpactResult {
+	/** Files with impacted references */
+	impactedFiles: DocsImpact[];
+	/** New exports (from this diff) that have no documentation */
+	missingDocs: string[];
+	/** ALL exports from the spec that have no documentation in the scanned files */
+	allUndocumented: 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;
+		/** Total exports in the spec */
+		totalExports: number;
+		/** Exports found documented in markdown */
+		documentedExports: number;
+	};
 }
 /**
-* Detect package manager based on lockfile presence.
+* Analyze docs impact from a spec diff
 *
-* Priority order:
-* 1. pnpm-lock.yaml
-* 2. bun.lock / bun.lockb
-* 3. yarn.lock
-* 4. package-lock.json
-* 5. Default to npm
+* @param diff - The spec diff result
+* @param markdownFiles - Parsed markdown files
+* @param newExportNames - All names in the new spec (for missing docs detection)
+* @param memberChanges - Optional member-level changes for granular detection
 */
-declare function detectPackageManager(fs: FileSystem): Promise<PackageManagerInfo>;
+declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFile[], newExportNames?: string[], memberChanges?: MemberChange[]): DocsImpactResult;
 /**
-* Get install command for a package manager.
-* Returns [command, ...args] array.
+* Find references to deprecated exports
 */
-declare function getInstallCommand(pm: PackageManagerInfo): string[];
+declare function findDeprecatedReferences(markdownFiles: MarkdownDocFile[], deprecatedExports: string[]): ExportReference[];
 /**
-* Get run command for a package manager script.
-* Returns [command, ...args, scriptName] array.
+* Find references to removed exports
 */
-declare function getRunCommand(pm: PackageManagerInfo, script: string): string[];
+declare function findRemovedReferences(markdownFiles: MarkdownDocFile[], removedExports: string[]): ExportReference[];
 /**
-* 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
+* Check if any docs reference a specific */
+declare function hasDocsForExport(markdownFiles: MarkdownDocFile[], exportName: string): boolean;
+/**
+* Get all exports that have documentation
 */
-declare function detectMonorepo(fs: FileSystem): Promise<MonorepoInfo>;
+declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
 /**
-* Find a package by name or path in a list of workspace packages.
+* Get all exports that lack documentation
 */
-declare function findPackageByName(packages: WorkspacePackage[], nameOrPath: string): WorkspacePackage | undefined;
+declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+import { CategorizedBreaking, OpenPkg as OpenPkg3, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
 /**
-* Format package list for display in error messages.
+* Extended spec diff result with docs impact
 */
-declare function formatPackageList(packages: WorkspacePackage[], limit?: number): string;
+interface SpecDiffWithDocs extends SpecDiff2 {
+	/** Docs impact analysis (only present if markdown files provided) */
+	docsImpact?: DocsImpactResult;
+	/** Member-level changes for classes (methods added/removed/changed) */
+	memberChanges?: MemberChange[];
+	/** Breaking changes categorized by severity (high/medium/low) */
+	categorizedBreaking?: CategorizedBreaking[];
+}
 /**
-* Detect the TypeScript entry point for a package.
+* Options for diffSpecWithDocs
+*/
+interface DiffWithDocsOptions {
+	/** Parsed markdown documentation files */
+	markdownFiles?: MarkdownDocFile[];
+}
+/**
+* Compute spec diff with optional docs impact analysis
 *
-* 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 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
 *
-* @param fs - FileSystem implementation
-* @param packagePath - Path to package directory (default: ".")
-* @returns Entry point info
-* @throws Error if no entry point can be found
+* @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 detectEntryPoint(fs: FileSystem, packagePath?: string): Promise<EntryPointInfo>;
+declare function diffSpecWithDocs(oldSpec: OpenPkg3, newSpec: OpenPkg3, options?: DiffWithDocsOptions): SpecDiffWithDocs;
 /**
-* 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
+* Check if a diff has any docs impact
 */
-declare function detectBuildInfo(fs: FileSystem, packagePath?: string): Promise<BuildInfo>;
+declare function hasDocsImpact(diff: SpecDiffWithDocs): boolean;
 /**
-* Get the primary build script name to run.
-* Prefers 'build' over 'compile' over 'tsc'.
+* Get summary of docs impact for display
 */
-declare function getPrimaryBuildScript(buildInfo: BuildInfo): string | null;
+declare function getDocsImpactSummary(diff: SpecDiffWithDocs): {
+	impactedFileCount: number;
+	impactedReferenceCount: number;
+	missingDocsCount: number;
+	totalIssues: number;
+	memberChangesCount: number;
+};
 /**
-* Safely parse a JSON file, returning null on any error.
+* Extract import statements from code (legacy interface).
+* @deprecated Use extractImportsAST for more detailed info.
 */
-declare function safeParseJson<T = Record<string, unknown>>(fs: FileSystem, path: string): Promise<T | null>;
+declare function extractImports(code: string): Array<{
+	name: string;
+	from: string;
+}>;
 /**
-* Standard package.json structure for detection purposes.
+* Extract function calls from code (legacy interface).
+* @deprecated Use extractCallsAST for more detailed info.
 */
-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>;
+declare function extractFunctionCalls(code: string): string[];
+/** Options for parsing markdown files */
+interface ParseOptions {
+	/** Custom set of executable language tags */
+	executableLangs?: string[];
 }
 /**
-* Package.json exports field structure.
+* Check if a language tag represents executable code
 */
-type PackageExports = string | {
-	"."?: string | {
-		types?: string;
-		import?: string;
-		require?: string;
-		default?: string;
-	};
-	[key: string]: unknown;
-};
+declare function isExecutableLang(lang: string | null | undefined, customLangs?: Set<string>): boolean;
 /**
-* Read and parse package.json from a directory.
+* Parse a markdown file and extract code blocks
 */
-declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJson | null>;
+declare function parseMarkdownFile(content: string, filePath: string, options?: ParseOptions): MarkdownDocFile;
 /**
-* 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' });
-* ```
+* Parse multiple markdown files
 */
-declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
-import { SpecExport as SpecExport4 } from "@openpkg-ts/spec";
-import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
-type LintSeverity = "error" | "warn" | "off";
-interface LintViolation {
-	rule: string;
-	severity: "error" | "warn";
+declare function parseMarkdownFiles(files: Array<{
+	path: string;
+	content: string;
+}>, options?: ParseOptions): MarkdownDocFile[];
+/**
+* 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;
+interface Diagnostic {
 	message: string;
-	line?: number;
-	fixable: boolean;
+	severity: "error" | "warning" | "info";
+	suggestion?: string;
+	location?: {
+		file: string;
+		line?: number;
+		column?: number;
+	};
 }
-interface LintRule {
-	name: string;
-	defaultSeverity: LintSeverity;
-	check(exp: SpecExport3, rawJSDoc?: string): LintViolation[];
-	fix?(exp: SpecExport3, rawJSDoc?: string): JSDocPatch | null;
+interface AnalysisResult {
+	spec: OpenPkgSpec;
+	diagnostics: Diagnostic[];
+	metadata: AnalysisMetadata;
 }
-interface LintConfig {
-	rules: Record<string, LintSeverity>;
+interface AnalysisMetadata {
+	baseDir: string;
+	configPath?: string;
+	packageJsonPath?: string;
+	hasNodeModules: boolean;
+	resolveExternalTypes: boolean;
 }
-interface LintResult {
-	violations: LintViolation[];
-	errorCount: number;
-	warningCount: number;
-	fixableCount: number;
+interface AnalyzeOptions {
+	filters?: FilterOptions;
 }
-/** All available lint rules */
-declare const allRules: LintRule[];
-/** Default configuration with rule defaults */
-declare function getDefaultConfig(): LintConfig;
-/** Get a rule by name */
-declare function getRule(name: string): LintRule | undefined;
-/** Lint a single */
-declare function lintExport(exp: SpecExport4, rawJSDoc?: string, config?: LintConfig): LintViolation[];
-/** Lint multiple exports and aggregate results */
-declare function lintExports(exports: Array<{
-	export: SpecExport4;
-	rawJSDoc?: string;
-}>, config?: LintConfig): LintResult;
-/** Merge user config with defaults */
-declare function mergeConfig(userConfig: Partial<LintConfig>): LintConfig;
-declare const consistentParamStyle: LintRule;
-declare const noEmptyReturns: LintRule;
-declare const requireDescription: LintRule;
-declare const requireExample: LintRule;
+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 OpenPkg4: typeof DocCov;
 interface ExampleTypeError {
 	/** Index of the example in the examples array */
 	exampleIndex: number;