@doccov/sdk 0.5.9 → 0.7.0

package/dist/index.d.ts

@@ -70,6 +70,608 @@ declare function hasNonAssertionComments(code: string): boolean;
 */
 declare function detectExampleAssertionFailures(entry: SpecExport, runtimeResults: Map<number, ExampleRunResult>): SpecDocDrift[];
 /**
+* 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;
+}
+/**
+* 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;
+/**
+* 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>;
+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 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 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 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[];
+/**
+* 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
+* import { NodeFileSystem, analyzeProject } from '@doccov/sdk';
+*
+* // Single package
+* const singleFs = new NodeFileSystem('/path/to/package');
+* const singleProject = await analyzeProject(singleFs);
+*
+* // Monorepo with target package
+* const monoFs = new NodeFileSystem('/path/to/monorepo');
+* const monoProject = await analyzeProject(monoFs, { targetPackage: '@scope/core' });
+* ```
+*/
+declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
+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[];
+}
+/**
+* Configuration types for DocCov.
+* These types are shared between CLI and API.
+*/
+/**
+* Documentation configuration options.
+*/
+interface DocsConfig {
+	/** Glob patterns for markdown docs to include */
+	include?: string[];
+	/** Glob patterns for markdown docs to exclude */
+	exclude?: string[];
+}
+/**
+* Check command configuration options.
+*/
+interface CheckConfig {
+	/** Enable lint checks (default: true) */
+	lint?: boolean;
+	/** Enable typecheck for examples (default: true) */
+	typecheck?: boolean;
+	/** Enable runtime execution of examples (default: false) */
+	exec?: boolean;
+}
+/**
+* Lint severity level.
+*/
+type LintSeverity = "error" | "warn" | "off";
+/**
+* Lint rules configuration.
+*/
+interface LintRulesConfig {
+	/** Rule severity overrides */
+	rules?: Record<string, LintSeverity>;
+}
+/**
+* Normalized DocCov configuration.
+* This is the parsed/normalized form used by commands.
+*/
+interface DocCovConfig {
+	/** Export include patterns */
+	include?: string[];
+	/** Export exclude patterns */
+	exclude?: string[];
+	/** Plugins (future) */
+	plugins?: unknown[];
+	/** Documentation configuration */
+	docs?: DocsConfig;
+	/** Check command configuration */
+	check?: CheckConfig;
+	/** Lint configuration */
+	lint?: LintRulesConfig;
+}
+/**
+* Define a DocCov configuration.
+* Helper function for type-safe configuration in doccov.config.ts.
+*
+* @param config - Configuration object
+* @returns The configuration object (for type inference)
+*
+* @example
+* ```typescript
+* // doccov.config.ts
+* import { defineConfig } from '@doccov/sdk';
+*
+* defineConfig({
+*   include: ['MyClass', 'myFunction'],
+*   exclude: ['internal*'],
+*   docs: {
+*     include: ['docs/**\/*.md'],
+*   },
+*   lint: {
+*     rules: {
+*       'require-description': 'error',
+*       'require-example': 'warn',
+*     },
+*   },
+* });
+* ```
+*/
+declare function defineConfig(config: DocCovConfig): DocCovConfig;
+/**
+* Source of filter options.
+*/
+type FilterSource = "config" | "override" | "combined";
+/**
+* Resolved filter options after merging config and overrides.
+*/
+interface ResolvedFilters {
+	/** Include patterns */
+	include?: string[];
+	/** Exclude patterns */
+	exclude?: string[];
+	/** Source of the filters */
+	source?: FilterSource;
+	/** Whether filters were applied from config */
+	fromConfig: boolean;
+	/** Whether filters were applied from overrides */
+	fromOverride: boolean;
+}
+/**
+* Parse a comma-separated list flag into an array.
+*
+* @param value - String or string array from CLI flag
+* @returns Parsed array, or undefined if empty
+*
+* @example
+* ```typescript
+* parseListFlag('a,b,c'); // ['a', 'b', 'c']
+* parseListFlag(['a,b', 'c']); // ['a', 'b', 'c']
+* parseListFlag(undefined); // undefined
+* ```
+*/
+declare function parseListFlag(value?: string | string[]): string[] | undefined;
+/**
+* Merge filter options from config and CLI/API overrides.
+*
+* Merge behavior:
+* - Include: CLI values intersect with config values (narrowing)
+* - Exclude: CLI values are added to config values (expanding)
+*
+* @param config - Configuration (from doccov.config.ts)
+* @param overrides - Override filters (from CLI flags or API params)
+* @returns Merged filter options
+*
+* @example
+* ```typescript
+* const config = { include: ['A', 'B', 'C'] };
+* const overrides = { include: ['B', 'C', 'D'] };
+*
+* const resolved = mergeFilters(config, overrides);
+* // resolved.include = ['B', 'C'] (intersection)
+* ```
+*/
+declare function mergeFilters(config: DocCovConfig | null, overrides: FilterOptions): ResolvedFilters;
+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[];
+};
+import { SpecExport as SpecExport4 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+type LintSeverity2 = "error" | "warn" | "off";
+interface LintViolation {
+	rule: string;
+	severity: "error" | "warn";
+	message: string;
+	line?: number;
+	fixable: boolean;
+}
+interface LintRule {
+	name: string;
+	defaultSeverity: LintSeverity2;
+	check(exp: SpecExport3, rawJSDoc?: string): LintViolation[];
+	fix?(exp: SpecExport3, rawJSDoc?: string): JSDocPatch | null;
+}
+interface LintConfig {
+	rules: Record<string, LintSeverity2>;
+}
+interface LintResult {
+	violations: LintViolation[];
+	errorCount: number;
+	warningCount: number;
+	fixableCount: number;
+}
+/** 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;
+}
+/**
 * Markdown/MDX documentation analysis types
 */
 /**
@@ -120,7 +722,7 @@ type DocsChangeType = "signature-changed" | "removed" | "deprecated" | "method-r
 /**
 * Member-level change type
 */
-type MemberChangeType = "added" | "removed" | "signature-changed";
+type MemberChangeType2 = "added" | "removed" | "signature-changed";
 /**
 * An impacted reference in a documentation file
 */
@@ -138,7 +740,7 @@ interface DocsImpactReference {
 	/** Member/method name if this is a member-level change */
 	memberName?: string;
 	/** Type of member change (added, removed, signature-changed) */
-	memberChangeType?: MemberChangeType;
+	memberChangeType?: MemberChangeType2;
 	/** Suggested replacement for removed/changed members */
 	replacementSuggestion?: string;
 	/** True if this is just a class instantiation (new ClassName()) */
@@ -180,60 +782,6 @@ interface DocsImpactResult {
 	};
 }
 /**
-* 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";
-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;
-}
-/**
 * Analyze docs impact from a spec diff
 *
 * @param diff - The spec diff result
@@ -248,224 +796,121 @@ declare function analyzeDocsImpact(diff: SpecDiff, markdownFiles: MarkdownDocFil
 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
-*/
-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[];
-}
-/**
-* 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: 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;
-};
-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[];
-}
-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;
-}
+*/
+declare function findRemovedReferences(markdownFiles: MarkdownDocFile[], removedExports: string[]): ExportReference[];
 /**
-* Result of applying edits to source files
+* Check if any docs reference a specific */
+declare function hasDocsForExport(markdownFiles: MarkdownDocFile[], exportName: string): boolean;
+/**
+* Get all exports that have documentation
 */
-interface ApplyEditsResult {
-	filesModified: number;
-	editsApplied: number;
-	errors: Array<{
-		file: string;
-		error: string;
-	}>;
-}
+declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
 /**
-* Parse a JSDoc comment string into a patchable structure
+* Get all exports that lack documentation
 */
-declare function parseJSDocToPatch(jsDocText: string): JSDocPatch;
+declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
+import { CategorizedBreaking, OpenPkg as OpenPkg3, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
 /**
-* Apply a partial patch to an existing JSDoc patch, preserving unmodified content
+* Extended spec diff result with docs impact
 */
-declare function applyPatchToJSDoc(existing: JSDocPatch, updates: Partial<JSDocPatch>): JSDocPatch;
+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[];
+}
 /**
-* Serialize a JSDocPatch back to a formatted comment string
+* Options for diffSpecWithDocs
 */
-declare function serializeJSDoc(patch: JSDocPatch, indent?: string): string;
+interface DiffWithDocsOptions {
+	/** Parsed markdown documentation files */
+	markdownFiles?: MarkdownDocFile[];
+}
 /**
-* Find the JSDoc location for a declaration in a source file
+* 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';
+* import type { OpenPkg } from '@openpkg-ts/spec';
+*
+* const oldSpec: OpenPkg = { openpkg: '0.2.0', meta: { name: 'my-pkg' }, exports: [] };
+* const newSpec: OpenPkg = { openpkg: '0.2.1', meta: { name: 'my-pkg' }, exports: [] };
+*
+* 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 findJSDocLocation(sourceFile: TS.SourceFile, symbolName: string, approximateLine?: number): {
-	startLine: number;
-	endLine: number;
-	declarationLine: number;
-	hasExisting: boolean;
-	existingJSDoc?: string;
-	indent: string;
-} | null;
+declare function diffSpecWithDocs(oldSpec: OpenPkg3, newSpec: OpenPkg3, options?: DiffWithDocsOptions): SpecDiffWithDocs;
 /**
-* Apply a batch of edits to source files
+* Check if a diff has any docs impact
 */
-declare function applyEdits(edits: JSDocEdit[]): Promise<ApplyEditsResult>;
+declare function hasDocsImpact(diff: SpecDiffWithDocs): boolean;
 /**
-* Create a TypeScript source file from a file path
+* Get summary of docs impact for display
 */
-declare function createSourceFile(filePath: string): TS.SourceFile;
+declare function getDocsImpactSummary(diff: SpecDiffWithDocs): {
+	impactedFileCount: number;
+	impactedReferenceCount: number;
+	missingDocsCount: number;
+	totalIssues: number;
+	memberChangesCount: number;
+};
 /**
-* Types of fixes that can be generated
+* Extract import statements from code (legacy interface).
+* @deprecated Use extractImportsAST for more detailed info.
 */
-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";
+declare function extractImports(code: string): Array<{
+	name: string;
+	from: string;
+}>;
 /**
-* A fix suggestion with the patch to apply
+* Extract function calls from code (legacy interface).
+* @deprecated Use extractCallsAST for more detailed info.
 */
-interface FixSuggestion {
-	type: FixType;
-	driftType: SpecDocDrift2["type"];
-	target: string;
-	description: string;
-	patch: Partial<JSDocPatch>;
+declare function extractFunctionCalls(code: string): string[];
+/** Options for parsing markdown files */
+interface ParseOptions {
+	/** Custom set of executable language tags */
+	executableLangs?: string[];
 }
 /**
-* Check if a drift type can be fixed deterministically
+* Check if a language tag represents executable code
 */
-declare function isFixableDrift(drift: SpecDocDrift2): boolean;
+declare function isExecutableLang(lang: string | null | undefined, customLangs?: Set<string>): boolean;
 /**
-* Generate a fix for a single drift issue
+* Parse a markdown file and extract code blocks
 */
-declare function generateFix(drift: SpecDocDrift2, exportEntry: SpecExport2, existingPatch?: JSDocPatch): FixSuggestion | null;
+declare function parseMarkdownFile(content: string, filePath: string, options?: ParseOptions): MarkdownDocFile;
 /**
-* Generate all fixes for an export's drift issues
+* Parse multiple markdown files
 */
-declare function generateFixesForExport(exportEntry: SpecExport2, existingPatch?: JSDocPatch): FixSuggestion[];
+declare function parseMarkdownFiles(files: Array<{
+	path: string;
+	content: string;
+}>, options?: ParseOptions): MarkdownDocFile[];
 /**
-* Merge multiple fix patches into a single patch
+* Find all references to given names in markdown files
 */
-declare function mergeFixes(fixes: FixSuggestion[], basePatch?: JSDocPatch): JSDocPatch;
+declare function findExportReferences(files: MarkdownDocFile[], exportNames: string[]): ExportReference[];
 /**
-* Get a summary of fixable vs non-fixable drifts
+* Check if a code block references any of the given names
 */
-declare function categorizeDrifts(drifts: SpecDocDrift2[]): {
-	fixable: SpecDocDrift2[];
-	nonFixable: SpecDocDrift2[];
-};
+declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
 interface Diagnostic {
 	message: string;
 	severity: "error" | "warning" | "info";
@@ -508,338 +953,522 @@ declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPk
 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;
+	/** Line number within the example (1-based) */
+	line: number;
+	/** Column number (1-based) */
+	column: number;
+	/** Error message from TypeScript */
+	message: string;
+	/** TypeScript diagnostic code */
+	code: number;
+}
+interface TypecheckResult {
+	/** All type errors found across examples */
+	errors: ExampleTypeError[];
+	/** Number of examples that passed */
+	passed: number;
+	/** Number of examples that failed */
+	failed: number;
+}
+interface TypecheckOptions {
+	/** Path to tsconfig.json (auto-detected if not provided) */
+	tsconfig?: string;
+	/** Package name for imports (auto-detected from package.json if not provided) */
+	packageName?: string;
+}
 /**
-* Project detection types for I/O-agnostic project analysis.
-* Used by both CLI (NodeFileSystem) and API (SandboxFileSystem).
+* Type-check a single example
 */
+declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
 /**
-* Minimal filesystem interface for I/O-agnostic detection.
-* Implementations: NodeFileSystem (CLI), SandboxFileSystem (API)
+* Type-check multiple examples
 */
-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";
+declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
 /**
-* Node.js filesystem implementation for CLI usage.
-* Wraps Node.js fs module with a base path.
+* Scan types for CLI, API, and SDK consumers.
+* Single source of truth for scan-related interfaces.
 */
-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>;
+/**
+* Result of scanning a repository for documentation coverage.
+* Used by CLI scan command, API endpoints, and SDK consumers.
+*/
+interface ScanResult {
+	/** GitHub repository owner */
+	owner: string;
+	/** GitHub repository name */
+	repo: string;
+	/** Git ref (branch/tag) that was scanned */
+	ref: string;
+	/** Package name if scanning a monorepo package */
+	packageName?: string;
+	/** Overall documentation coverage percentage (0-100) */
+	coverage: number;
+	/** Number of public exports analyzed */
+	exportCount: number;
+	/** Number of types analyzed */
+	typeCount: number;
+	/** Number of documentation drift issues found */
+	driftCount: number;
+	/** Names of exports missing documentation */
+	undocumented: string[];
+	/** Drift issues found during analysis */
+	drift: DriftIssue[];
 }
 /**
-* Vercel Sandbox filesystem implementation for API usage.
-* Uses sandbox.runCommand() with shell commands.
+* A documentation drift issue.
 */
-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 DriftIssue {
+	/** Name of the with drift */
+	export: string;
+	/** Type of drift (e.g., 'param-mismatch', 'return-type') */
+	type: string;
+	/** Human-readable description of the issue */
+	issue: string;
+	/** Optional suggestion for fixing the issue */
+	suggestion?: string;
 }
 /**
-* 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
+* Options for running a scan.
 */
-declare function detectPackageManager(fs: FileSystem): Promise<PackageManagerInfo>;
+interface ScanOptions {
+	/** GitHub URL or owner/repo shorthand */
+	url: string;
+	/** Git ref (branch/tag) to scan */
+	ref?: string;
+	/** Target package name for monorepos */
+	package?: string;
+	/** Skip dependency installation */
+	skipInstall?: boolean;
+	/** Skip external type resolution */
+	skipResolve?: boolean;
+}
 /**
-* Get install command for a package manager.
-* Returns [command, ...args] array.
+* Stages of the scan pipeline.
 */
-declare function getInstallCommand(pm: PackageManagerInfo): string[];
+type ProgressStage = "cloning" | "detecting" | "installing" | "building" | "analyzing" | "complete";
 /**
-* Get run command for a package manager script.
-* Returns [command, ...args, scriptName] array.
+* Progress event emitted during scan operations.
 */
-declare function getRunCommand(pm: PackageManagerInfo, script: string): string[];
+interface ProgressEvent {
+	/** Current stage of the scan */
+	stage: ProgressStage;
+	/** Human-readable message */
+	message: string;
+	/** Progress percentage (0-100), if known */
+	progress?: number;
+}
 /**
-* 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
+* Callback for receiving progress events.
+*/
+type ProgressCallback = (event: ProgressEvent) => void;
+import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
+/**
+* Summary of a spec's documentation coverage.
+* Simpler than full ReportStats - focused on scan output.
+*/
+interface SpecSummary {
+	/** Overall coverage percentage */
+	coverage: number;
+	/** Number of exports */
+	exportCount: number;
+	/** Number of types */
+	typeCount: number;
+	/** Number of drift issues */
+	driftCount: number;
+	/** Names of undocumented or partially documented exports */
+	undocumented: string[];
+	/** Drift issues */
+	drift: DriftIssue[];
+}
+/**
+* Extract a summary from an OpenPkg spec.
+* 
+* This consolidates the logic previously duplicated in:
+* - CLI scan.ts (drift collection)
+* - CLI reports/stats.ts (computeStats)
+* - API scan-stream.ts (inline extraction script)
+* 
+* @param spec - The OpenPkg spec to summarize
+* @returns Summary of documentation coverage
+* 
+* @example
+* ```typescript
+* import { extractSpecSummary } from '@doccov/sdk';
+* 
+* const summary = extractSpecSummary(spec);
+* console.log(`Coverage: ${summary.coverage}%`);
+* console.log(`Undocumented: ${summary.undocumented.length}`);
+* ```
 */
-declare function detectMonorepo(fs: FileSystem): Promise<MonorepoInfo>;
+declare function extractSpecSummary(spec: OpenPkg5): SpecSummary;
+import { OpenPkg as OpenPkg7 } from "@openpkg-ts/spec";
 /**
-* Find a package by name or path in a list of workspace packages.
+* Result of running a command.
 */
-declare function findPackageByName(packages: WorkspacePackage[], nameOrPath: string): WorkspacePackage | undefined;
+interface CommandResult {
+	/** Exit code (0 = success) */
+	exitCode: number;
+	/** Standard output */
+	stdout: string;
+	/** Standard error */
+	stderr: string;
+}
 /**
-* Format package list for display in error messages.
+* Function that runs a shell command.
+* Abstracts the difference between Node.js execSync and Sandbox runCommand.
 */
-declare function formatPackageList(packages: WorkspacePackage[], limit?: number): string;
+type CommandRunner = (cmd: string, args: string[], options: {
+	cwd: string;
+	timeout?: number;
+}) => Promise<CommandResult>;
 /**
-* Detect the TypeScript entry point for a package.
+* Result of dependency installation.
+*/
+interface InstallResult {
+	/** Whether installation succeeded */
+	success: boolean;
+	/** Package manager that was used */
+	packageManager: PackageManager;
+	/** If a fallback was used, which one */
+	fallbackUsed?: PackageManager;
+	/** Error message if installation failed */
+	error?: string;
+	/** Detailed error messages from each attempt */
+	errors?: string[];
+}
+/**
+* Options for dependency installation.
+*/
+interface InstallOptions {
+	/** Timeout in milliseconds for install commands (default: 180000) */
+	timeout?: number;
+	/** Order of fallback package managers to try */
+	fallbackOrder?: PackageManager[];
+	/** Progress callback for status updates */
+	onProgress?: ProgressCallback;
+}
+/**
+* Install dependencies for a project.
 *
-* 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
+* This consolidates the install logic from CLI scan.ts and API scan-stream.ts:
+* 1. Detect package manager from lockfile
+* 2. Try primary install command
+* 3. Fall back to other package managers if primary fails
 *
-* @param fs - FileSystem implementation
-* @param packagePath - Path to package directory (default: ".")
-* @returns Entry point info
-* @throws Error if no entry point can be found
+* @param fs - FileSystem implementation for package manager detection
+* @param cwd - Working directory to install in
+* @param runCommand - Function to run shell commands
+* @param options - Installation options
+* @returns Result of the installation attempt
+*
+* @example
+* ```typescript
+* import { NodeFileSystem, installDependencies, createNodeCommandRunner } from '@doccov/sdk';
+*
+* const fs = new NodeFileSystem('/path/to/repo');
+* const result = await installDependencies(fs, '/path/to/repo', createNodeCommandRunner());
+*
+* if (result.success) {
+*   console.log(`Installed using ${result.packageManager}`);
+* } else {
+*   console.error(`Install failed: ${result.error}`);
+* }
+* ```
 */
-declare function detectEntryPoint(fs: FileSystem, packagePath?: string): Promise<EntryPointInfo>;
+declare function installDependencies(fs: FileSystem, cwd: string, runCommand: CommandRunner, options?: InstallOptions): Promise<InstallResult>;
 /**
-* Detect build configuration and exotic project indicators.
+* Create a command runner for Node.js environments using execSync.
+* This is used by the CLI for local dependency installation.
 *
-* @param fs - FileSystem implementation
-* @param packagePath - Path to package directory (default: ".")
-* @returns Build info including scripts and exotic indicators
+* @returns CommandRunner that uses child_process.execSync
+*
+* @example
+* ```typescript
+* const runner = createNodeCommandRunner();
+* const result = await runner('npm', ['install'], { cwd: '/path/to/repo' });
+* ```
 */
-declare function detectBuildInfo(fs: FileSystem, packagePath?: string): Promise<BuildInfo>;
+declare function createNodeCommandRunner(): CommandRunner;
+import { OpenPkg as OpenPkg6 } from "@openpkg-ts/spec";
 /**
-* Get the primary build script name to run.
-* Prefers 'build' over 'compile' over 'tsc'.
+* Parsed components of a GitHub URL.
 */
-declare function getPrimaryBuildScript(buildInfo: BuildInfo): string | null;
+interface ParsedGitHubUrl {
+	/** Repository owner (user or org) */
+	owner: string;
+	/** Repository name */
+	repo: string;
+	/** Git ref (branch or tag) */
+	ref: string;
+}
 /**
-* Safely parse a JSON file, returning null on any error.
+* Parse a GitHub URL or shorthand into components.
+*
+* Supported formats:
+* - https://github.com/owner/repo
+* - https://github.com/owner/repo/tree/branch
+* - https://github.com/owner/repo/tree/v1.0.0
+* - github.com/owner/repo
+* - owner/repo (shorthand)
+* - git@github.com:owner/repo.git
+*
+* @param input - GitHub URL or shorthand
+* @param defaultRef - Default ref if not specified in URL (default: 'main')
+* @returns Parsed components
+* @throws Error if the URL format is invalid
+*
+* @example
+* ```typescript
+* import { parseGitHubUrl } from '@doccov/sdk';
+*
+* const parsed = parseGitHubUrl('https://github.com/vercel/next.js/tree/canary');
+* // { owner: 'vercel', repo: 'next.js', ref: 'canary' }
+*
+* const shorthand = parseGitHubUrl('vercel/next.js');
+* // { owner: 'vercel', repo: 'next.js', ref: 'main' }
+* ```
 */
-declare function safeParseJson<T = Record<string, unknown>>(fs: FileSystem, path: string): Promise<T | null>;
+declare function parseGitHubUrl(input: string, defaultRef?: string): ParsedGitHubUrl;
 /**
-* Standard package.json structure for detection purposes.
+* Build a clone URL from parsed components.
+*
+* @param parsed - Parsed GitHub URL components
+* @returns HTTPS clone URL
+*
+* @example
+* ```typescript
+* const cloneUrl = buildCloneUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
+* // 'https://github.com/vercel/next.js.git'
+* ```
 */
-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 buildCloneUrl(parsed: ParsedGitHubUrl): string;
 /**
-* Package.json exports field structure.
+* Build a display-friendly URL (without protocol or .git suffix).
+*
+* @param parsed - Parsed GitHub URL components
+* @returns Display URL like 'github.com/owner/repo'
+*
+* @example
+* ```typescript
+* const displayUrl = buildDisplayUrl({ owner: 'vercel', repo: 'next.js', ref: 'main' });
+* // 'github.com/vercel/next.js'
+* ```
 */
-type PackageExports = string | {
-	"."?: string | {
-		types?: string;
-		import?: string;
-		require?: string;
-		default?: string;
-	};
-	[key: string]: unknown;
-};
+declare function buildDisplayUrl(parsed: ParsedGitHubUrl): string;
 /**
-* Read and parse package.json from a directory.
+* Build a raw.githubusercontent.com URL for a file.
+*
+* @param parsed - Parsed GitHub URL components
+* @param filePath - Path to the file in the repo
+* @returns Raw content URL
 */
-declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJson | null>;
+declare function buildRawUrl(parsed: ParsedGitHubUrl, filePath: string): string;
 /**
-* 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.
+* Fetch an OpenPkg spec from a GitHub repository.
 *
-* 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.
+* Tries the specified ref first, then falls back to 'master' if not found.
 *
-* @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
+* @param parsed - Parsed GitHub URL components
+* @returns The OpenPkg spec, or null if not found
 *
 * @example
 * ```typescript
-* // Single package
-* const fs = new NodeFileSystem('/path/to/package');
-* const project = await analyzeProject(fs);
+* import { parseGitHubUrl, fetchSpecFromGitHub } from '@doccov/sdk';
 *
-* // Monorepo with target package
-* const fs = new NodeFileSystem('/path/to/monorepo');
-* const project = await analyzeProject(fs, { targetPackage: '@scope/core' });
+* const parsed = parseGitHubUrl('vercel/next.js');
+* const spec = await fetchSpecFromGitHub(parsed);
+* if (spec) {
+*   console.log(`Coverage: ${spec.docs?.coverageScore}%`);
+* }
 * ```
 */
-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";
-	message: string;
-	line?: number;
-	fixable: boolean;
-}
-interface LintRule {
-	name: string;
-	defaultSeverity: LintSeverity;
-	check(exp: SpecExport3, rawJSDoc?: string): LintViolation[];
-	fix?(exp: SpecExport3, rawJSDoc?: string): JSDocPatch | null;
-}
-interface LintConfig {
-	rules: Record<string, LintSeverity>;
-}
-interface LintResult {
-	violations: LintViolation[];
-	errorCount: number;
-	warningCount: number;
-	fixableCount: number;
+declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg6 | null>;
+/**
+* Fetch an OpenPkg spec from a GitHub repository by owner/repo/branch.
+*
+* Convenience function that creates ParsedGitHubUrl internally.
+*
+* @param owner - Repository owner
+* @param repo - Repository name
+* @param branch - Branch name (default: 'main')
+* @returns The OpenPkg spec, or null if not found
+*/
+declare function fetchSpec(owner: string, repo: string, branch?: string): Promise<OpenPkg6 | null>;
+/**
+* Options for creating a ScanOrchestrator.
+*/
+interface ScanOrchestratorOptions {
+	/** Progress callback for status updates */
+	onProgress?: ProgressCallback;
+	/** Command runner for executing shell commands */
+	commandRunner?: CommandRunner;
+	/** Skip external type resolution */
+	skipResolve?: boolean;
 }
-/** 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;
-interface ExampleTypeError {
-	/** Index of the example in the examples array */
-	exampleIndex: number;
-	/** Line number within the example (1-based) */
-	line: number;
-	/** Column number (1-based) */
-	column: number;
-	/** Error message from TypeScript */
-	message: string;
-	/** TypeScript diagnostic code */
-	code: number;
+/**
+* Context for the current scan operation.
+*/
+interface ScanContext {
+	/** Parsed GitHub URL info */
+	parsed: ParsedGitHubUrl;
+	/** Target package name for monorepos */
+	packageName?: string;
+	/** Working directory for the scan */
+	workDir: string;
+	/** Entry point file path */
+	entryFile?: string;
 }
-interface TypecheckResult {
-	/** All type errors found across examples */
-	errors: ExampleTypeError[];
-	/** Number of examples that passed */
-	passed: number;
-	/** Number of examples that failed */
-	failed: number;
+/**
+* Orchestrates the scan workflow.
+*
+* The orchestrator coordinates:
+* 1. Repository cloning (for remote URLs)
+* 2. Monorepo detection and package resolution
+* 3. Entry point detection
+* 4. Dependency installation
+* 5. Build execution (if needed)
+* 6. Documentation analysis
+* 7. Summary extraction
+*
+* It's designed to be FileSystem-agnostic so it works with both:
+* - NodeFileSystem (CLI - local execution)
+* - SandboxFileSystem (API - isolated execution)
+*
+* @example
+* ```typescript
+* import { ScanOrchestrator, NodeFileSystem, createNodeCommandRunner } from '@doccov/sdk';
+*
+* const fs = new NodeFileSystem('/path/to/repo');
+* const orchestrator = new ScanOrchestrator(fs, {
+*   commandRunner: createNodeCommandRunner(),
+*   onProgress: (event) => console.log(event.message),
+* });
+*
+* const result = await orchestrator.scan({
+*   url: 'https://github.com/owner/repo',
+*   ref: 'main',
+* });
+*
+* console.log(`Coverage: ${result.coverage}%`);
+* ```
+*/
+declare class ScanOrchestrator {
+	private readonly fs;
+	private readonly options;
+	constructor(fs: FileSystem, options?: ScanOrchestratorOptions);
+	/**
+	* Emit a progress event.
+	*/
+	private emit;
+	/**
+	* Detect monorepo and resolve target package.
+	*
+	* @param packageName - Target package name (required for monorepos)
+	* @returns Target directory path (relative to workDir)
+	* @throws Error if monorepo requires --package flag
+	*/
+	detectPackage(packageName?: string): Promise<{
+		targetPath: string;
+		resolvedPackage?: string;
+	}>;
+	/**
+	* Detect entry point for the package.
+	*
+	* @param targetPath - Path to the package directory
+	* @returns Entry point file path (relative to workDir)
+	*/
+	detectEntry(targetPath: string): Promise<string>;
+	/**
+	* Install dependencies for the project.
+	*
+	* @param workDir - Working directory (absolute path)
+	* @returns Installation result
+	*/
+	install(workDir: string): Promise<InstallResult>;
+	/**
+	* Run build if needed.
+	*
+	* @param workDir - Working directory (absolute path)
+	* @param targetPath - Target package path (relative)
+	*/
+	build(workDir: string, targetPath: string): Promise<void>;
+	/**
+	* Run documentation analysis.
+	*
+	* @param entryFile - Path to entry file (absolute)
+	* @returns OpenPkg spec
+	*/
+	analyze(entryFile: string): Promise<OpenPkg7>;
+	/**
+	* Run a complete scan workflow.
+	*
+	* @param options - Scan options
+	* @returns Scan result with coverage statistics
+	*/
+	scan(options: ScanOptions): Promise<ScanResult>;
 }
-interface TypecheckOptions {
-	/** Path to tsconfig.json (auto-detected if not provided) */
-	tsconfig?: string;
-	/** Package name for imports (auto-detected from package.json if not provided) */
-	packageName?: string;
+/**
+* Error thrown when a monorepo is detected but no package is specified.
+*/
+declare class MonorepoRequiresPackageError extends Error {
+	/** Available package names */
+	readonly availablePackages: string[];
+	constructor(availablePackages: string[]);
 }
 /**
-* Type-check a single example
+* Options for resolving a target package/entry point.
 */
-declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
+interface ResolveTargetOptions {
+	/** Working directory (usually process.cwd()) */
+	cwd: string;
+	/** Target package name for monorepos */
+	package?: string;
+	/** Explicit entry point path (relative to cwd or package dir) */
+	entry?: string;
+}
 /**
-* Type-check multiple examples
+* Result of resolving a target package/entry point.
+*/
+interface ResolvedTarget {
+	/** Resolved directory containing the package */
+	targetDir: string;
+	/** Resolved entry point file path (absolute) */
+	entryFile: string;
+	/** Package info if this is a monorepo package */
+	packageInfo?: WorkspacePackage;
+	/** Entry point detection info */
+	entryPointInfo: EntryPointInfo;
+}
+/**
+* Resolve a target package and entry point.
+*
+* This consolidates the repeated pattern from CLI commands:
+* 1. If --package specified, detect monorepo and find the package
+* 2. If no entry specified, auto-detect entry point
+* 3. If entry is a directory, detect entry point within it
+*
+* @param fs - FileSystem implementation (NodeFileSystem or SandboxFileSystem)
+* @param options - Resolution options
+* @returns Resolved target info
+* @throws Error if monorepo package not found, or entry point detection fails
+*
+* @example
+* ```typescript
+* import { NodeFileSystem, resolveTarget } from '@doccov/sdk';
+*
+* // Simple usage
+* const fs = new NodeFileSystem(process.cwd());
+* const { targetDir, entryFile } = await resolveTarget(fs, { cwd: process.cwd() });
+*
+* // With monorepo package
+* const { targetDir, entryFile, packageInfo } = await resolveTarget(fs, {
+*   cwd: process.cwd(),
+*   package: '@myorg/core',
+* });
+* ```
 */
-declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
-export { typecheckExamples, typecheckExample, serializeJSDoc, safeParseJson, runExamplesWithPackage, runExamples, runExample, requireExample, requireDescription, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseJSDocToPatch, parseAssertions, noEmptyReturns, mergeFixes, mergeConfig, lintExports, lintExport, isFixableDrift, isExecutableLang, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, getUndocumentedExports, getRunCommand, getRule, getPrimaryBuildScript, getInstallCommand, getDocumentedExports, getDocsImpactSummary, getDefaultConfig, generateFixesForExport, generateFix, formatPackageList, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, extractPackageSpec, extractImports, extractFunctionCalls, diffSpecWithDocs, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, createSourceFile, consistentParamStyle, categorizeDrifts, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, allRules, WorkspacePackage, TypecheckResult, TypecheckOptions, SpecDiffWithDocs, SandboxFileSystem, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ProjectInfo, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg4 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LintViolation, LintSeverity, LintRule, LintResult, LintConfig, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, FixType, FixSuggestion, FilterOptions, FileSystem, ExportReference, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, DocsImpactResult, DocsImpactReference, DocsImpact, DocsChangeType, DocCovOptions, DocCov, DiffWithDocsOptions, Diagnostic, BuildInfo, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult };
+declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
+export { typecheckExamples, typecheckExample, serializeJSDoc, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, requireExample, requireDescription, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseAssertions, noEmptyReturns, mergeFixes, mergeFilters, mergeConfig, lintExports, lintExport, isFixableDrift, isExecutableLang, installDependencies, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, getUndocumentedExports, getRunCommand, getRule, getPrimaryBuildScript, getInstallCommand, getDocumentedExports, getDocsImpactSummary, getDefaultConfig, generateFixesForExport, generateFix, formatPackageList, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, diffSpecWithDocs, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, consistentParamStyle, categorizeDrifts, buildRawUrl, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, allRules, WorkspacePackage, TypecheckResult, TypecheckOptions, SpecSummary, SpecDiffWithDocs, ScanResult, ScanOrchestratorOptions, ScanOrchestrator, ScanOptions, ScanContext, SandboxFileSystem, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, ProjectInfo, ProgressStage, ProgressEvent, ProgressCallback, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg4 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoRequiresPackageError, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LintViolation, LintSeverity2 as LintSeverity, LintRulesConfig, LintRule, LintResult, LintConfig, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, ExportReference, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, DriftIssue, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, CommandRunner, CommandResult, CheckConfig, BuildInfo, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult };