@doccov/sdk 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -45,8 +45,8 @@ declare function runExamples(examples: string[], options?: RunExampleOptions): P
 * runs all examples, then cleans up.
 */
 declare function runExamplesWithPackage(examples: string[], options: RunExamplesWithPackageOptions): Promise<RunExamplesWithPackageResult>;
-import { OpenPkg } from "@openpkg-ts/spec";
-type OpenPkgSpec = OpenPkg;
+import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+type OpenPkgSpec = OpenPkg2;
 /**
 * Result of computing drift for a single export.
 */
@@ -177,7 +177,55 @@ declare function getDriftSummary(drifts: SpecDocDrift[]): DriftSummary;
 * ```
 */
 declare function formatDriftSummaryLine(summary: DriftSummary): string;
-import { OpenPkg as OpenPkg2, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+/**
+* Calculate aggregate coverage score from a spec's exports.
+*
+* This is a lightweight function that calculates coverage without
+* requiring full quality evaluation. It handles three cases:
+* 1. Exports with `docs.coverageScore` - uses that value
+* 2. Exports without score but with description - counts as 100%
+* 3. Exports without score and no description - counts as 0%
+*
+* @param spec - The OpenPkg spec to calculate coverage for
+* @returns The aggregate coverage score (0-100)
+*
+* @example
+* ```ts
+* import { calculateAggregateCoverage } from '@doccov/sdk';
+*
+* const coverage = calculateAggregateCoverage(spec);
+* console.log(`Coverage: ${coverage}%`);
+* ```
+*/
+declare function calculateAggregateCoverage(spec: OpenPkgSpec): number;
+/**
+* Ensure a spec has a top-level docs.coverageScore.
+*
+* If the spec already has `docs.coverageScore`, returns the spec unchanged.
+* Otherwise, calculates aggregate coverage from exports and returns a
+* new spec with the coverage score added.
+*
+* This is useful for commands like `diff` that need coverage scores
+* but may receive raw specs that haven't been enriched.
+*
+* @param spec - The OpenPkg spec to ensure coverage for
+* @returns The spec with guaranteed top-level coverage score
+*
+* @example
+* ```ts
+* import { ensureSpecCoverage } from '@doccov/sdk';
+*
+* // Works with raw or enriched specs
+* const specWithCoverage = ensureSpecCoverage(rawSpec);
+* console.log(specWithCoverage.docs?.coverageScore); // e.g., 85
+* ```
+*/
+declare function ensureSpecCoverage(spec: OpenPkgSpec): OpenPkgSpec & {
+	docs: {
+		coverageScore: number;
+	};
+};
+import { OpenPkg as OpenPkg3, SpecDocDrift as SpecDocDrift2, SpecDocsMetadata, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
 import { SpecExport as SpecExport2, SpecExportKind } from "@openpkg-ts/spec";
 import * as TS from "typescript";
 /**
@@ -397,7 +445,7 @@ type EnrichedDocsMetadata = SpecDocsMetadata & {
 * An enriched OpenPkg spec with computed documentation metadata.
 * Extends OpenPkg with per-and aggregate coverage data.
 */
-type EnrichedOpenPkg = Omit<OpenPkg2, "exports"> & {
+type EnrichedOpenPkg = Omit<OpenPkg3, "exports"> & {
 	exports: EnrichedExport[];
 	docs?: EnrichedDocsMetadata;
 	/** Drift summary with category breakdown (if drift exists) */
@@ -442,8 +490,8 @@ interface EnrichOptions {
 * console.log(enriched.docs?.missing); // e.g., ['has-examples']
 * ```
 */
-declare function enrichSpec(spec: OpenPkg2, options?: EnrichOptions): EnrichedOpenPkg;
-import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
+declare function enrichSpec(spec: OpenPkg3, options?: EnrichOptions): EnrichedOpenPkg;
+import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
 import { DriftCategory as DriftCategory2, SpecDocDrift as SpecDocDrift3 } from "@openpkg-ts/spec";
 /**
 * DocCov report schema version.
@@ -476,6 +524,24 @@ declare const REPORT_EXTENSIONS: Record<string, string>;
 */
 declare function getReportPath(format: string, dir?: string): string;
 /**
+* Get the report path for a diff comparison.
+*
+* Uses truncated hashes from both specs to create a unique, deterministic filename.
+*
+* @param baseHash - Hash of the base (before) spec
+* @param headHash - Hash of the head (after) spec
+* @param format - The report format (json, markdown, html, github)
+* @param dir - The output directory (defaults to .doccov)
+* @returns The full path to the diff report file
+*
+* @example
+* ```ts
+* getDiffReportPath('abc123def456', 'xyz789uvw012', 'markdown');
+* // '.doccov/diff-abc123de-xyz789uv.md'
+* ```
+*/
+declare function getDiffReportPath(baseHash: string, headHash: string, format: string, dir?: string): string;
+/**
 * Drift summary with category breakdown.
 */
 interface DriftReportSummary {
@@ -620,7 +686,7 @@ interface DocCovReport {
 * console.log(`Coverage: ${report.coverage.score}%`);
 * ```
 */
-declare function generateReport(spec: OpenPkg3): DocCovReport;
+declare function generateReport(spec: OpenPkg4): DocCovReport;
 /**
 * Generate a DocCov report from an already-enriched spec.
 *
@@ -689,7 +755,7 @@ declare function hashFiles(filePaths: string[], cwd: string): Record<string, str
 * @returns Array of file paths that changed, were added, or were removed
 */
 declare function diffHashes(cached: Record<string, string>, current: Record<string, string>): string[];
-import { OpenPkg as OpenPkg4 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
 /** Current cache format version */
 declare const CACHE_VERSION = "1.0.0";
 /** Default cache file path */
@@ -724,7 +790,7 @@ interface SpecCache {
 	/** Analysis configuration that affects output */
 	config: SpecCacheConfig;
 	/** The cached OpenPkg spec */
-	spec: OpenPkg4;
+	spec: OpenPkg5;
 }
 /**
 * Result of cache validation.
@@ -767,7 +833,7 @@ declare function loadSpecCache(cwd: string): SpecCache | null;
 * @param spec - OpenPkg spec to cache
 * @param context - Cache context with file paths and config
 */
-declare function saveSpecCache(spec: OpenPkg4, context: CacheContext): void;
+declare function saveSpecCache(spec: OpenPkg5, context: CacheContext): void;
 /**
 * Validate if cached spec is still valid.
 *
@@ -1411,7 +1477,7 @@ declare function categorizeDrifts(drifts: SpecDocDrift4[]): {
 	fixable: SpecDocDrift4[];
 	nonFixable: SpecDocDrift4[];
 };
-import { OpenPkg as OpenPkg5 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg6 } from "@openpkg-ts/spec";
 /**
 * Parsed components of a GitHub URL.
 */
@@ -1504,7 +1570,7 @@ declare function buildRawUrl(parsed: ParsedGitHubUrl, filePath: string): string;
 * }
 * ```
 */
-declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg5 | null>;
+declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg6 | null>;
 /**
 * Fetch an OpenPkg spec from a GitHub repository by owner/repo/branch.
 *
@@ -1515,84 +1581,22 @@ declare function fetchSpecFromGitHub(parsed: ParsedGitHubUrl): Promise<OpenPkg5
 * @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<OpenPkg5 | null>;
+declare function fetchSpec(owner: string, repo: string, branch?: string): Promise<OpenPkg6 | null>;
 /**
-* Scan types for CLI, API, and SDK consumers.
-* Single source of truth for scan-related interfaces.
+* Progress event for installation status updates.
 */
-/**
-* 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[];
-}
-/**
-* A documentation drift issue.
-*/
-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;
-}
-/**
-* Options for running a scan.
-*/
-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;
-}
-/**
-* Stages of the scan pipeline.
-*/
-type ProgressStage = "cloning" | "detecting" | "installing" | "building" | "analyzing" | "complete";
-/**
-* Progress event emitted during scan operations.
-*/
-interface ProgressEvent {
-	/** Current stage of the scan */
-	stage: ProgressStage;
+interface InstallProgressEvent {
+	/** Current stage */
+	stage: "installing";
 	/** Human-readable message */
 	message: string;
 	/** Progress percentage (0-100), if known */
 	progress?: number;
 }
 /**
-* Callback for receiving progress events.
+* Callback for receiving installation progress events.
 */
-type ProgressCallback = (event: ProgressEvent) => void;
+type InstallProgressCallback = (event: InstallProgressEvent) => void;
 /**
 * Result of running a command.
 */
@@ -1636,7 +1640,7 @@ interface InstallOptions {
 	/** Order of fallback package managers to try */
 	fallbackOrder?: PackageManager[];
 	/** Progress callback for status updates */
-	onProgress?: ProgressCallback;
+	onProgress?: InstallProgressCallback;
 }
 /**
 * Install dependencies for a project.
@@ -1836,7 +1840,7 @@ declare function getDocumentedExports(markdownFiles: MarkdownDocFile[], exportNa
 * Get all exports that lack documentation
 */
 declare function getUndocumentedExports(markdownFiles: MarkdownDocFile[], exportNames: string[]): string[];
-import { CategorizedBreaking, OpenPkg as OpenPkg7, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
+import { CategorizedBreaking, OpenPkg as OpenPkg8, SpecDiff as SpecDiff2 } from "@openpkg-ts/spec";
 /**
 * Extended spec diff result with docs impact
 */
@@ -1882,7 +1886,7 @@ interface DiffWithDocsOptions {
 * }
 * ```
 */
-declare function diffSpecWithDocs(oldSpec: OpenPkg7, newSpec: OpenPkg7, options?: DiffWithDocsOptions): SpecDiffWithDocs;
+declare function diffSpecWithDocs(oldSpec: OpenPkg8, newSpec: OpenPkg8, options?: DiffWithDocsOptions): SpecDiffWithDocs;
 /**
 * Check if a diff has any docs impact
 */
@@ -1938,7 +1942,29 @@ declare function findExportReferences(files: MarkdownDocFile[], exportNames: str
 * Check if a code block references any of the given names
 */
 declare function blockReferencesExport(block: MarkdownCodeBlock, exportName: string): boolean;
-interface Diagnostic {
+import { EntryPointDetectionMethod } from "@openpkg-ts/spec";
+/**
+* Input for generation metadata that comes from the caller (CLI, API, etc.)
+*/
+interface GenerationInput {
+	/** Entry point file path (relative to package root) */
+	entryPoint: string;
+	/** How the entry point was detected */
+	entryPointSource: EntryPointDetectionMethod;
+	/** Whether this is a declaration-only analysis (.d.ts file) */
+	isDeclarationOnly?: boolean;
+	/** Generator tool name */
+	generatorName: string;
+	/** Generator tool version */
+	generatorVersion: string;
+	/** Detected package manager */
+	packageManager?: string;
+	/** Whether this is a monorepo */
+	isMonorepo?: boolean;
+	/** Target package name (for monorepos) */
+	targetPackage?: string;
+}
+interface Diagnostic2 {
 	message: string;
 	severity: "error" | "warning" | "info";
 	suggestion?: string;
@@ -1950,7 +1976,7 @@ interface Diagnostic {
 }
 interface AnalysisResult {
 	spec: OpenPkgSpec;
-	diagnostics: Diagnostic[];
+	diagnostics: Diagnostic2[];
 	metadata: AnalysisMetadata;
 	/** True if result came from cache (no fresh analysis) */
 	fromCache?: boolean;
@@ -1968,6 +1994,8 @@ interface AnalysisMetadata {
 }
 interface AnalyzeOptions {
 	filters?: FilterOptions;
+	/** Generation metadata input (entry point info, tool version, etc.) */
+	generationInput?: GenerationInput;
 }
 declare class DocCov {
 	private readonly options;
@@ -2002,7 +2030,7 @@ declare class DocCov {
 declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
 /** @deprecated Use DocCov instead */
-declare const OpenPkg8: typeof DocCov;
+declare const OpenPkg9: typeof DocCov;
 import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
 import { SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
 /**
@@ -2113,127 +2141,18 @@ interface ResolvedTarget {
 * ```
 */
 declare function resolveTarget(fs: FileSystem, options: ResolveTargetOptions): Promise<ResolvedTarget>;
-import { OpenPkg as OpenPkg9 } from "@openpkg-ts/spec";
-/**
-* 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;
-}
 /**
-* Context for the current scan operation.
+* A documentation drift issue in a spec summary.
 */
-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;
-}
-/**
-* 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<OpenPkg9>;
-	/**
-	* Run a complete scan workflow.
-	*
-	* @param options - Scan options
-	* @returns Scan result with coverage statistics
-	*/
-	scan(options: ScanOptions): Promise<ScanResult>;
-}
-/**
-* 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[]);
+interface SummaryDriftIssue {
+	/** 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;
 }
 /**
 * Summary of a spec's documentation coverage.
@@ -2251,7 +2170,7 @@ interface SpecSummary {
 	/** Names of undocumented or partially documented exports */
 	undocumented: string[];
 	/** Drift issues */
-	drift: DriftIssue[];
+	drift: SummaryDriftIssue[];
 }
 /**
 * Extract a summary from an enriched OpenPkg spec.
@@ -2276,6 +2195,188 @@ interface SpecSummary {
 */
 declare function extractSpecSummary(spec: EnrichedOpenPkg): SpecSummary;
 /**
+* Build Plan types for AI-powered repository scanning.
+*/
+/**
+* Target repository information for a build plan.
+*/
+interface BuildPlanTarget {
+	/** Target type (currently only GitHub is supported) */
+	type: "github";
+	/** Full GitHub repository URL */
+	repoUrl: string;
+	/** Git ref (branch, tag, or commit) */
+	ref: string;
+	/** Root path within the repository (for monorepos) */
+	rootPath?: string;
+	/** Entry point files to analyze */
+	entryPoints: string[];
+}
+/**
+* Runtime environment configuration for executing a build plan.
+*/
+interface BuildPlanEnvironment {
+	/** Node.js or Bun runtime */
+	runtime: "node20" | "node22" | "bun";
+	/** Package manager to use */
+	packageManager: "npm" | "yarn" | "pnpm" | "bun";
+	/** Additional tools required (e.g., 'wasm-pack', 'cargo') */
+	requiredTools?: string[];
+}
+/**
+* A single step in the build plan.
+*/
+interface BuildPlanStep {
+	/** Unique identifier for this step */
+	id: string;
+	/** Human-readable step name */
+	name: string;
+	/** Command to execute */
+	command: string;
+	/** Command arguments */
+	args: string[];
+	/** Working directory (relative to repo root) */
+	cwd?: string;
+	/** Timeout in milliseconds */
+	timeout?: number;
+	/** If true, failure won't stop the plan execution */
+	optional?: boolean;
+}
+/**
+* AI-generated build plan for analyzing a repository.
+*/
+interface BuildPlan {
+	/** Build plan schema version */
+	version: "1.0.0";
+	/** When the plan was generated */
+	generatedAt: string;
+	/** Target repository information */
+	target: BuildPlanTarget;
+	/** Environment configuration */
+	environment: BuildPlanEnvironment;
+	/** Ordered list of steps to execute */
+	steps: BuildPlanStep[];
+	/** AI reasoning about the plan */
+	reasoning: {
+		/** Brief summary of the approach */
+		summary: string;
+		/** Why this approach was chosen */
+		rationale: string;
+		/** Potential issues or concerns */
+		concerns: string[];
+	};
+	/** AI confidence in the plan */
+	confidence: "high" | "medium" | "low";
+}
+/**
+* Result of executing a single build plan step.
+*/
+interface BuildPlanStepResult {
+	/** Step ID that was executed */
+	stepId: string;
+	/** Whether the step succeeded */
+	success: boolean;
+	/** Duration in milliseconds */
+	duration: number;
+	/** Command output (stdout) */
+	output?: string;
+	/** Error message if failed */
+	error?: string;
+}
+/**
+* Result of executing a complete build plan.
+*/
+interface BuildPlanExecutionResult {
+	/** Whether all required steps succeeded */
+	success: boolean;
+	/** Generated OpenPkg spec (if successful) */
+	spec?: import("@openpkg-ts/spec").OpenPkg;
+	/** Results for each step */
+	stepResults: BuildPlanStepResult[];
+	/** Total execution time in milliseconds */
+	totalDuration: number;
+	/** Overall error message if failed */
+	error?: string;
+}
+/**
+* GitHub context fetcher for AI-powered build plan generation.
+* Fetches project context via GitHub API without cloning the repository.
+*/
+/**
+* Repository metadata from GitHub API.
+*/
+interface GitHubRepoMetadata {
+	owner: string;
+	repo: string;
+	defaultBranch: string;
+	description: string | null;
+	language: string | null;
+	topics: string[];
+	isPrivate: boolean;
+}
+/**
+* Detected package manager from lockfile.
+*/
+type DetectedPackageManager = "npm" | "yarn" | "pnpm" | "bun" | "unknown";
+/**
+* Workspace/monorepo configuration.
+*/
+interface WorkspaceConfig {
+	isMonorepo: boolean;
+	tool?: "npm" | "yarn" | "pnpm" | "lerna" | "turborepo" | "nx";
+	packages?: string[];
+}
+/**
+* Build hints detected from project files.
+*/
+interface BuildHints {
+	hasTypeScript: boolean;
+	hasWasm: boolean;
+	hasNativeModules: boolean;
+	hasBuildScript: boolean;
+	buildScript?: string;
+	frameworks: string[];
+}
+/**
+* Complete project context for build plan generation.
+*/
+interface GitHubProjectContext {
+	/** Repository metadata */
+	metadata: GitHubRepoMetadata;
+	/** Git ref being analyzed */
+	ref: string;
+	/** Detected package manager */
+	packageManager: DetectedPackageManager;
+	/** Workspace/monorepo configuration */
+	workspace: WorkspaceConfig;
+	/** Build hints from project files */
+	buildHints: BuildHints;
+	/** Raw file contents for AI analysis */
+	files: {
+		packageJson?: string;
+		tsconfigJson?: string;
+		lockfile?: {
+			name: string;
+			content: string;
+		};
+	};
+}
+/**
+* Parse GitHub URL into owner and repo.
+*/
+declare function parseGitHubUrl2(url: string): {
+	owner: string;
+	repo: string;
+} | null;
+/**
+* Fetch complete project context from GitHub.
+*/
+declare function fetchGitHubContext(repoUrl: string, ref?: string): Promise<GitHubProjectContext>;
+/**
+* List packages in a monorepo workspace.
+*/
+declare function listWorkspacePackages(owner: string, repo: string, ref: string, patterns: string[]): Promise<string[]>;
+/**
 * Type-check a single example
 */
 declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
@@ -2283,4 +2384,4 @@ declare function typecheckExample(example: string, packagePath: string, options?
 * Type-check multiple examples
 */
 declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
-export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadCachedReport, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getSpecCachePath, getRunCommand, getRulesForKind, getRule, getReportPath, getPrimaryBuildScript, getInstallCommand, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDefaultConfig, getCoverageRules, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, evaluateQuality, evaluateExportQuality, enrichSpec, diffSpecWithDocs, diffHashes, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, buildRawUrl, buildExportRegistry, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, ScanResult, ScanOrchestratorOptions, ScanOrchestrator, ScanOptions, ScanContext, SandboxFileSystem, STYLE_RULES, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, RuleContext, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, REPORT_VERSION, REPORT_EXTENSIONS, QualityViolation, QualitySeverity2 as QualitySeverity, QualityRulesConfig, QualityRule, QualityResult, QualityConfig, ProjectInfo, ProgressStage, ProgressEvent, ProgressCallback, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg8 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoRequiresPackageError, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DriftIssue, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildInfo, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };
+export { validateSpecCache, validateExamples, typecheckExamples, typecheckExample, shouldValidate, serializeJSDoc, saveSpecCache, saveReport, safeParseJson, runExamplesWithPackage, runExamples, runExample, resolveTarget, readPackageJson, parseGitHubUrl2 as parseScanGitHubUrl, parseMarkdownFiles, parseMarkdownFile, parseListFlag, parseJSDocToPatch, parseGitHubUrl, parseExamplesFlag, parseAssertions, mergeFixes, mergeFilters, mergeConfig, loadSpecCache, loadCachedReport, listWorkspacePackages, isFixableDrift, isExecutableLang, isCachedReportValid, installDependencies, hashString, hashFiles, hashFile, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, groupDriftsByCategory, getUndocumentedExports, getSpecCachePath, getRunCommand, getRulesForKind, getRule, getReportPath, getPrimaryBuildScript, getInstallCommand, getDriftSummary, getDocumentedExports, getDocsImpactSummary, getDiffReportPath, getDefaultConfig, getCoverageRules, generateReportFromEnriched, generateReport, generateFixesForExport, generateFix, formatPackageList, formatDriftSummaryLine, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, fetchSpecFromGitHub, fetchSpec, fetchGitHubContext, extractSpecSummary, extractPackageSpec, extractImports, extractFunctionCalls, evaluateQuality, evaluateExportQuality, ensureSpecCoverage, enrichSpec, diffSpecWithDocs, diffHashes, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, defineConfig, createSourceFile, createNodeCommandRunner, computeExportDrift, computeDrift, clearSpecCache, categorizeDrifts, categorizeDrift, calculateAggregateCoverage, buildRawUrl, buildExportRegistry, buildDisplayUrl, buildCloneUrl, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, WorkspaceConfig, VALIDATION_INFO, TypecheckValidationResult, TypecheckResult, TypecheckOptions, SummaryDriftIssue, SpecSummary, SpecDiffWithDocs, SpecCacheConfig, SpecCache, SandboxFileSystem, STYLE_RULES, SPEC_CACHE_FILE, RuntimeDrift, RunValidationResult, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, RuleContext, ResolvedTarget, ResolvedFilters, ResolveTargetOptions, REPORT_VERSION, REPORT_EXTENSIONS, QualityViolation, QualitySeverity2 as QualitySeverity, QualityRulesConfig, QualityRule, QualityResult, QualityConfig, ProjectInfo, PresenceResult, ParsedGitHubUrl, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg9 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LLMAssertion, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, InstallResult, InstallOptions, GitHubRepoMetadata, GitHubProjectContext, FixType, FixSuggestion, FilterSource, FilterOptions, FileSystem, ExportReference, ExportDriftResult, ExportCoverageData, ExampleValidationTypeError, ExampleValidationResult, ExampleValidationOptions, ExampleValidationMode, ExampleValidation, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, EnrichedOpenPkg, EnrichedExport, EnrichedDocsMetadata, EnrichOptions, DriftSummary, DriftResult, DriftReportSummary, DriftReport, DocsImpactResult, DocsImpactReference, DocsImpact, DocsConfig, DocsChangeType, DocCovReport, DocCovOptions, DocCovConfig, DocCov, DiffWithDocsOptions, Diagnostic2 as Diagnostic, DetectedPackageManager, DEFAULT_REPORT_PATH, DEFAULT_REPORT_DIR, CoverageSummary, CommandRunner, CommandResult, CheckConfig, CategorizedDrift, CacheValidationResult, CacheContext, CORE_RULES, CACHE_VERSION, BuildPlanTarget, BuildPlanStepResult, BuildPlanStep, BuildPlanExecutionResult, BuildPlanEnvironment, BuildPlan, BuildInfo, BuildHints, BUILTIN_RULES, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult, AggregateQualityResult, ALL_VALIDATIONS };

package/dist/index.js

@@ -1201,6 +1201,35 @@ function formatDriftSummaryLine(summary) {
   const fixableNote = summary.fixable > 0 ? ` (${summary.fixable} auto-fixable)` : "";
   return `${summary.total} issues (${parts.join(", ")})${fixableNote}`;
 }
+function calculateAggregateCoverage(spec) {
+  const exports = spec.exports ?? [];
+  if (exports.length === 0)
+    return 100;
+  let totalScore = 0;
+  for (const exp of exports) {
+    const score = exp.docs?.coverageScore;
+    if (score !== undefined) {
+      totalScore += score;
+    } else {
+      totalScore += exp.description ? 100 : 0;
+    }
+  }
+  return Math.round(totalScore / exports.length);
+}
+function ensureSpecCoverage(spec) {
+  const specWithDocs = spec;
+  if (specWithDocs.docs?.coverageScore !== undefined) {
+    return spec;
+  }
+  const coverage = calculateAggregateCoverage(spec);
+  return {
+    ...spec,
+    docs: {
+      ...specWithDocs.docs ?? {},
+      coverageScore: coverage
+    }
+  };
+}
 // src/fix/jsdoc-writer.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -1938,6 +1967,11 @@ function getReportPath(format, dir = DEFAULT_REPORT_DIR) {
   const ext = REPORT_EXTENSIONS[format] ?? format;
   return `${dir}/report.${ext}`;
 }
+function getDiffReportPath(baseHash, headHash, format, dir = DEFAULT_REPORT_DIR) {
+  const ext = REPORT_EXTENSIONS[format] ?? format;
+  const hash = `${baseHash.slice(0, 8)}-${headHash.slice(0, 8)}`;
+  return `${dir}/diff-${hash}.${ext}`;
+}
 
 // src/analysis/report.ts
 function generateReport(spec) {
@@ -6113,10 +6147,30 @@ class TypeRegistry {
 }
 
 // src/analysis/spec-builder.ts
-function buildOpenPkgSpec(context, resolveExternalTypes) {
-  const { baseDir, checker: typeChecker, sourceFile, program } = context;
+function createDefaultGenerationInfo(entryFile) {
+  return {
+    timestamp: new Date().toISOString(),
+    generator: {
+      name: "@doccov/sdk",
+      version: "0.0.0"
+    },
+    analysis: {
+      entryPoint: entryFile,
+      entryPointSource: "explicit",
+      isDeclarationOnly: entryFile.endsWith(".d.ts"),
+      resolvedExternalTypes: false
+    },
+    environment: {
+      hasNodeModules: false
+    },
+    issues: []
+  };
+}
+function buildOpenPkgSpec(context, resolveExternalTypes, generation) {
+  const { baseDir, checker: typeChecker, sourceFile, program, entryFile } = context;
   const packageJsonPath = path9.join(baseDir, "package.json");
   const packageJson = fs8.existsSync(packageJsonPath) ? JSON.parse(fs8.readFileSync(packageJsonPath, "utf-8")) : {};
+  const generationInfo = generation ?? createDefaultGenerationInfo(path9.relative(baseDir, entryFile));
   const spec = {
     $schema: SCHEMA_URL,
     openpkg: SCHEMA_VERSION,
@@ -6129,7 +6183,8 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
       ecosystem: "js/ts"
     },
     exports: [],
-    types: []
+    types: [],
+    generation: generationInfo
   };
   const typeRegistry = new TypeRegistry;
   const serializerContext = {
@@ -6446,7 +6501,7 @@ function hasExternalImports(sourceFile) {
   });
   return found;
 }
-function runAnalysis(input) {
+function runAnalysis(input, generationInput) {
   const context = createAnalysisContext(input);
   const { baseDir, options, program } = context;
   const packageJsonPath = findNearestPackageJson(baseDir);
@@ -6459,30 +6514,65 @@ function runAnalysis(input) {
 `);
     return !/allowJs/i.test(msg);
   });
-  const spec = buildOpenPkgSpec(context, resolveExternalTypes);
   const specDiagnostics = [];
+  const generationIssues = [];
   if (!hasNodeModules && hasExternalImports(context.sourceFile)) {
-    specDiagnostics.push({
+    const issue = {
+      code: "NO_NODE_MODULES",
       message: "External imports detected but node_modules not found.",
       severity: "info",
       suggestion: "Run npm install or bun install for complete type resolution."
-    });
-  }
+    };
+    specDiagnostics.push(issue);
+    generationIssues.push(issue);
+  }
+  const generation = generationInput ? {
+    timestamp: new Date().toISOString(),
+    generator: {
+      name: generationInput.generatorName,
+      version: generationInput.generatorVersion
+    },
+    analysis: {
+      entryPoint: generationInput.entryPoint,
+      entryPointSource: generationInput.entryPointSource,
+      isDeclarationOnly: generationInput.isDeclarationOnly ?? false,
+      resolvedExternalTypes: resolveExternalTypes,
+      maxTypeDepth: options.maxDepth
+    },
+    environment: {
+      packageManager: generationInput.packageManager,
+      hasNodeModules,
+      isMonorepo: generationInput.isMonorepo,
+      targetPackage: generationInput.targetPackage
+    },
+    issues: generationIssues
+  } : undefined;
+  const spec = buildOpenPkgSpec(context, resolveExternalTypes, generation);
   const danglingRefs = collectDanglingRefs(spec);
   for (const ref of danglingRefs) {
-    specDiagnostics.push({
+    const issue = {
+      code: "DANGLING_REF",
       message: `Type '${ref}' is referenced but not defined in types[].`,
       severity: "warning",
       suggestion: hasNodeModules ? "The type may be from an external package. Check import paths." : "Run npm/bun install to resolve external types."
-    });
+    };
+    specDiagnostics.push(issue);
+    if (generation) {
+      generation.issues.push(issue);
+    }
   }
   const externalTypes = collectExternalTypes(spec);
   if (externalTypes.length > 0) {
-    specDiagnostics.push({
+    const issue = {
+      code: "EXTERNAL_TYPE_STUBS",
       message: `${externalTypes.length} external type(s) could not be fully resolved: ${externalTypes.slice(0, 5).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
       severity: "warning",
       suggestion: hasNodeModules ? "Types are from external packages. Full resolution requires type declarations." : "Run npm/bun install to resolve external type definitions."
-    });
+    };
+    specDiagnostics.push(issue);
+    if (generation) {
+      generation.issues.push(issue);
+    }
   }
   const sourceFiles = program.getSourceFiles().filter((sf) => !sf.isDeclarationFile && sf.fileName.startsWith(baseDir)).map((sf) => sf.fileName);
   return {
@@ -8142,7 +8232,7 @@ class DocCov {
       packageDir,
       content: code,
       options: this.options
-    });
+    }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     return {
       spec: filterOutcome.spec,
@@ -8177,7 +8267,7 @@ class DocCov {
       packageDir,
       content,
       options: this.options
-    });
+    }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     const metadata = this.normalizeMetadata(analysis.metadata);
     const result = {
@@ -8452,130 +8542,204 @@ function extractSpecSummary(spec) {
     drift
   };
 }
-
-// src/scan/orchestrator.ts
-class ScanOrchestrator {
-  fs;
-  options;
-  constructor(fs11, options = {}) {
-    this.fs = fs11;
-    this.options = options;
-  }
-  emit(event) {
-    this.options.onProgress?.(event);
-  }
-  async detectPackage(packageName) {
-    this.emit({ stage: "detecting", message: "Detecting project structure...", progress: 10 });
-    const mono = await detectMonorepo(this.fs);
-    if (mono.isMonorepo) {
-      if (!packageName) {
-        const publicPackages = mono.packages.filter((p) => !p.private);
-        throw new MonorepoRequiresPackageError(publicPackages.map((p) => p.name));
-      }
-      const pkg = findPackageByName(mono.packages, packageName);
-      if (!pkg) {
-        throw new Error(`Package "${packageName}" not found. Available: ${mono.packages.map((p) => p.name).join(", ")}`);
-      }
-      this.emit({ stage: "detecting", message: `Found package: ${pkg.name}`, progress: 15 });
-      return { targetPath: pkg.path, resolvedPackage: pkg.name };
-    }
-    return { targetPath: "." };
-  }
-  async detectEntry(targetPath) {
-    this.emit({ stage: "detecting", message: "Detecting entry point...", progress: 18 });
-    const entry = await detectEntryPoint(this.fs, targetPath);
-    const entryFile = targetPath === "." ? entry.path : `${targetPath}/${entry.path}`;
-    this.emit({
-      stage: "detecting",
-      message: `Entry point: ${entry.path} (from ${entry.source})`,
-      progress: 20
-    });
-    return entryFile;
+// src/scan/github-context.ts
+function parseGitHubUrl2(url) {
+  const patterns = [
+    /github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/|$)/,
+    /^([^/]+)\/([^/]+)$/
+  ];
+  for (const pattern of patterns) {
+    const match = url.match(pattern);
+    if (match) {
+      return { owner: match[1], repo: match[2].replace(/\.git$/, "") };
+    }
   }
-  async install(workDir) {
-    if (!this.options.commandRunner) {
-      return {
-        success: false,
-        packageManager: "npm",
-        error: "No command runner provided"
-      };
+  return null;
+}
+async function fetchRawFile(owner, repo, ref, path13) {
+  const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path13}`;
+  try {
+    const response = await fetch(url);
+    if (response.ok) {
+      return await response.text();
     }
-    this.emit({ stage: "installing", message: "Installing dependencies...", progress: 25 });
-    const result = await installDependencies(this.fs, workDir, this.options.commandRunner, {
-      onProgress: this.options.onProgress
-    });
-    if (result.success) {
-      this.emit({ stage: "installing", message: "Dependencies installed", progress: 45 });
-    } else {
-      this.emit({
-        stage: "installing",
-        message: "Install failed (continuing with limited analysis)",
-        progress: 45
-      });
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function fetchRepoMetadata(owner, repo) {
+  const url = `https://api.github.com/repos/${owner}/${repo}`;
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "DocCov-Scanner"
     }
-    return result;
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch repository: ${response.status} ${response.statusText}`);
   }
-  async build(workDir, targetPath) {
-    if (!this.options.commandRunner)
-      return;
-    const buildInfo = await detectBuildInfo(this.fs, targetPath);
-    const buildScript = getPrimaryBuildScript(buildInfo);
-    if (!buildScript)
-      return;
-    this.emit({ stage: "building", message: "Running build...", progress: 50 });
-    const result = await this.options.commandRunner("npm", ["run", buildScript], {
-      cwd: workDir,
-      timeout: 300000
-    });
-    const buildMessage = result.exitCode === 0 ? "Build complete" : "Build failed (continuing)";
-    this.emit({ stage: "building", message: buildMessage, progress: 60 });
-  }
-  async analyze(entryFile) {
-    this.emit({ stage: "analyzing", message: "Analyzing documentation...", progress: 65 });
-    const doccov = new DocCov({ resolveExternalTypes: !this.options.skipResolve });
-    const result = await doccov.analyzeFileWithDiagnostics(entryFile);
-    this.emit({ stage: "analyzing", message: "Analysis complete", progress: 90 });
-    return result.spec;
-  }
-  async scan(options) {
-    const parsed = parseGitHubUrl(options.url, options.ref ?? "main");
-    this.emit({
-      stage: "detecting",
-      message: `Scanning ${parsed.owner}/${parsed.repo}...`,
-      progress: 5
-    });
-    const { targetPath, resolvedPackage } = await this.detectPackage(options.package);
-    const entryFile = await this.detectEntry(targetPath);
-    if (!options.skipInstall && this.options.commandRunner) {
-      await this.install(".");
-      await this.build(".", targetPath);
-    }
-    const spec = await this.analyze(entryFile);
-    this.emit({ stage: "complete", message: "Extracting results...", progress: 95 });
-    const summary = extractSpecSummary(spec);
-    this.emit({ stage: "complete", message: "Scan complete", progress: 100 });
+  const data = await response.json();
+  return {
+    owner,
+    repo,
+    defaultBranch: data.default_branch,
+    description: data.description,
+    language: data.language,
+    topics: data.topics ?? [],
+    isPrivate: data.private
+  };
+}
+async function detectPackageManager3(owner, repo, ref) {
+  const lockfiles = [
+    { name: "bun.lockb", manager: "bun" },
+    { name: "pnpm-lock.yaml", manager: "pnpm" },
+    { name: "yarn.lock", manager: "yarn" },
+    { name: "package-lock.json", manager: "npm" }
+  ];
+  for (const { name, manager } of lockfiles) {
+    const content = await fetchRawFile(owner, repo, ref, name);
+    if (content !== null) {
+      return { manager, lockfile: { name, content: content.slice(0, 1e4) } };
+    }
+  }
+  return { manager: "unknown" };
+}
+async function detectWorkspace(packageJson, owner, repo, ref) {
+  const pnpmWorkspace = await fetchRawFile(owner, repo, ref, "pnpm-workspace.yaml");
+  if (pnpmWorkspace) {
+    const packagesMatch = pnpmWorkspace.match(/packages:\s*\n((?:\s+-\s+['"]?[^\n]+['"]?\n?)+)/);
+    const packages = packagesMatch ? packagesMatch[1].split(`
+`).map((line) => line.replace(/^\s+-\s+['"]?/, "").replace(/['"]?\s*$/, "")).filter(Boolean) : undefined;
     return {
-      owner: parsed.owner,
-      repo: parsed.repo,
-      ref: parsed.ref,
-      packageName: resolvedPackage ?? options.package,
-      coverage: summary.coverage,
-      exportCount: summary.exportCount,
-      typeCount: summary.typeCount,
-      driftCount: summary.driftCount,
-      undocumented: summary.undocumented,
-      drift: summary.drift
+      isMonorepo: true,
+      tool: "pnpm",
+      packages
     };
   }
+  const lernaJson = await fetchRawFile(owner, repo, ref, "lerna.json");
+  if (lernaJson) {
+    return { isMonorepo: true, tool: "lerna" };
+  }
+  if (packageJson && typeof packageJson === "object") {
+    const pkg = packageJson;
+    if (pkg.workspaces) {
+      const workspaces = pkg.workspaces;
+      const packages = Array.isArray(workspaces) ? workspaces : workspaces.packages;
+      return {
+        isMonorepo: true,
+        tool: "npm",
+        packages: packages?.filter((p) => typeof p === "string")
+      };
+    }
+  }
+  return { isMonorepo: false };
 }
-
-class MonorepoRequiresPackageError extends Error {
-  availablePackages;
-  constructor(availablePackages) {
-    super(`Monorepo detected with ${availablePackages.length} packages. ` + `Specify target with --package. Available: ${availablePackages.join(", ")}`);
-    this.name = "MonorepoRequiresPackageError";
-    this.availablePackages = availablePackages;
+function detectBuildHints(packageJson, tsconfigJson) {
+  const hints = {
+    hasTypeScript: false,
+    hasWasm: false,
+    hasNativeModules: false,
+    hasBuildScript: false,
+    frameworks: []
+  };
+  if (!packageJson || typeof packageJson !== "object") {
+    return hints;
+  }
+  const pkg = packageJson;
+  const deps = {
+    ...typeof pkg.dependencies === "object" ? pkg.dependencies : {},
+    ...typeof pkg.devDependencies === "object" ? pkg.devDependencies : {}
+  };
+  hints.hasTypeScript = "typescript" in deps || tsconfigJson !== null;
+  hints.hasWasm = "wasm-pack" in deps || "@aspect-build/rules_esbuild" in deps;
+  hints.hasNativeModules = "node-gyp" in deps || "prebuild" in deps || "napi-rs" in deps;
+  const scripts = typeof pkg.scripts === "object" ? pkg.scripts : {};
+  if (scripts.build) {
+    hints.hasBuildScript = true;
+    hints.buildScript = scripts.build;
+  }
+  const frameworkDeps = [
+    { dep: "react", name: "React" },
+    { dep: "vue", name: "Vue" },
+    { dep: "svelte", name: "Svelte" },
+    { dep: "next", name: "Next.js" },
+    { dep: "nuxt", name: "Nuxt" },
+    { dep: "astro", name: "Astro" },
+    { dep: "express", name: "Express" },
+    { dep: "fastify", name: "Fastify" },
+    { dep: "hono", name: "Hono" }
+  ];
+  for (const { dep, name } of frameworkDeps) {
+    if (dep in deps) {
+      hints.frameworks.push(name);
+    }
+  }
+  return hints;
+}
+async function fetchGitHubContext(repoUrl, ref) {
+  const parsed = parseGitHubUrl2(repoUrl);
+  if (!parsed) {
+    throw new Error(`Invalid GitHub URL: ${repoUrl}`);
+  }
+  const { owner, repo } = parsed;
+  const metadata = await fetchRepoMetadata(owner, repo);
+  const targetRef = ref ?? metadata.defaultBranch;
+  const [packageJsonRaw, tsconfigJsonRaw, pmResult] = await Promise.all([
+    fetchRawFile(owner, repo, targetRef, "package.json"),
+    fetchRawFile(owner, repo, targetRef, "tsconfig.json"),
+    detectPackageManager3(owner, repo, targetRef)
+  ]);
+  let packageJson = null;
+  let tsconfigJson = null;
+  if (packageJsonRaw) {
+    try {
+      packageJson = JSON.parse(packageJsonRaw);
+    } catch {}
+  }
+  if (tsconfigJsonRaw) {
+    try {
+      tsconfigJson = JSON.parse(tsconfigJsonRaw);
+    } catch {}
+  }
+  const workspace = await detectWorkspace(packageJson, owner, repo, targetRef);
+  const buildHints = detectBuildHints(packageJson, tsconfigJson);
+  return {
+    metadata,
+    ref: targetRef,
+    packageManager: pmResult.manager,
+    workspace,
+    buildHints,
+    files: {
+      packageJson: packageJsonRaw ?? undefined,
+      tsconfigJson: tsconfigJsonRaw ?? undefined,
+      lockfile: pmResult.lockfile
+    }
+  };
+}
+async function listWorkspacePackages(owner, repo, ref, patterns) {
+  const packages = [];
+  for (const pattern of patterns) {
+    const baseDir = pattern.replace(/\/\*.*$/, "");
+    try {
+      const url = `https://api.github.com/repos/${owner}/${repo}/contents/${baseDir}?ref=${ref}`;
+      const response = await fetch(url, {
+        headers: {
+          Accept: "application/vnd.github.v3+json",
+          "User-Agent": "DocCov-Scanner"
+        }
+      });
+      if (response.ok) {
+        const contents = await response.json();
+        for (const item of contents) {
+          if (item.type === "dir") {
+            packages.push(`${baseDir}/${item.name}`);
+          }
+        }
+      }
+    } catch {}
   }
+  return packages;
 }
 export {
   validateSpecCache,
@@ -8592,6 +8756,7 @@ export {
   runExample,
   resolveTarget,
   readPackageJson,
+  parseGitHubUrl2 as parseScanGitHubUrl,
   parseMarkdownFiles,
   parseMarkdownFile,
   parseListFlag,
@@ -8604,6 +8769,7 @@ export {
   mergeConfig,
   loadSpecCache,
   loadCachedReport,
+  listWorkspacePackages,
   isFixableDrift,
   isExecutableLang,
   isCachedReportValid,
@@ -8626,6 +8792,7 @@ export {
   getDriftSummary,
   getDocumentedExports,
   getDocsImpactSummary,
+  getDiffReportPath,
   getDefaultConfig,
   getCoverageRules,
   generateReportFromEnriched,
@@ -8641,12 +8808,14 @@ export {
   findDeprecatedReferences,
   fetchSpecFromGitHub,
   fetchSpec,
+  fetchGitHubContext,
   extractSpecSummary,
   extractPackageSpec,
   extractImports,
   extractFunctionCalls,
   evaluateQuality,
   evaluateExportQuality,
+  ensureSpecCoverage,
   enrichSpec,
   diffSpecWithDocs,
   diffHashes,
@@ -8664,6 +8833,7 @@ export {
   clearSpecCache,
   categorizeDrifts,
   categorizeDrift,
+  calculateAggregateCoverage,
   buildRawUrl,
   buildExportRegistry,
   buildDisplayUrl,
@@ -8676,7 +8846,6 @@ export {
   analyzeDocsImpact,
   analyze,
   VALIDATION_INFO,
-  ScanOrchestrator,
   SandboxFileSystem,
   STYLE_RULES,
   SPEC_CACHE_FILE,
@@ -8684,7 +8853,6 @@ export {
   REPORT_EXTENSIONS,
   OpenPkg,
   NodeFileSystem,
-  MonorepoRequiresPackageError,
   DocCov,
   DEFAULT_REPORT_PATH,
   DEFAULT_REPORT_DIR,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -39,7 +39,7 @@
     "dist"
   ],
   "dependencies": {
-    "@openpkg-ts/spec": "^0.8.0",
+    "@openpkg-ts/spec": "^0.9.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",
     "remark-mdx": "^3.1.0",