@bfra.me/workspace-analyzer 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,3701 @@
+import { Result } from '@bfra.me/es/result';
+export { Err, Ok, Result, err, flatMap, fromPromise, fromThrowable, isErr, isOk, map, mapErr, ok, unwrap, unwrapOr } from '@bfra.me/es/result';
+import { IssueCategory, Severity, Issue, IssueLocation, AnalysisProgress, AnalysisResult } from './types/index.js';
+export { AnalysisError, AnalysisResultType, AnalysisSummary, AnalyzeWorkspaceOptions, AnalyzerConfig } from './types/index.js';
+import { SourceFile, Project } from 'ts-morph';
+import { ChangeDetectorOptions, ChangeDetector, FileHasher } from '@bfra.me/es/watcher';
+export { ChangeDetector, ChangeDetectorOptions, FileHasher, createChangeDetector, createFileHasher } from '@bfra.me/es/watcher';
+import { z } from 'zod';
+import { ParseError } from '@bfra.me/doc-sync/types';
+export { ParseError, ParseErrorCode } from '@bfra.me/doc-sync/types';
+export { TypeScriptParserOptions, createProject, parseSourceContent, parseSourceFile } from '@bfra.me/doc-sync/parsers';
+
+/**
+ * Workspace scanner for discovering and analyzing packages in a monorepo.
+ *
+ * Adapts the createPackageScanner() pattern from @bfra.me/doc-sync for workspace analysis.
+ * Uses fs.readdir pattern (not fast-glob) for better control over directory traversal.
+ */
+
+/**
+ * Options for configuring the workspace scanner.
+ */
+interface WorkspaceScannerOptions {
+    /** Root directory of the workspace/monorepo */
+    readonly rootDir: string;
+    /** Glob patterns for package locations (e.g., ['packages/*', 'apps/*']) */
+    readonly includePatterns?: readonly string[];
+    /** Package names to exclude from scanning */
+    readonly excludePackages?: readonly string[];
+    /** File extensions to include in source file collection */
+    readonly sourceExtensions?: readonly string[];
+    /** Directories to skip during source file collection */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Minimal package.json structure for workspace analysis.
+ */
+interface WorkspacePackageJson {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly main?: string;
+    readonly module?: string;
+    readonly types?: string;
+    readonly exports?: Record<string, unknown>;
+    readonly dependencies?: Readonly<Record<string, string>>;
+    readonly devDependencies?: Readonly<Record<string, string>>;
+    readonly peerDependencies?: Readonly<Record<string, string>>;
+    readonly optionalDependencies?: Readonly<Record<string, string>>;
+}
+/**
+ * Information about a discovered workspace package.
+ */
+interface WorkspacePackage {
+    /** Package name from package.json */
+    readonly name: string;
+    /** Package version from package.json */
+    readonly version: string;
+    /** Absolute path to the package directory */
+    readonly packagePath: string;
+    /** Absolute path to package.json */
+    readonly packageJsonPath: string;
+    /** Absolute path to source directory (if exists) */
+    readonly srcPath: string;
+    /** Parsed package.json content */
+    readonly packageJson: WorkspacePackageJson;
+    /** List of source file paths in the package */
+    readonly sourceFiles: readonly string[];
+    /** Whether the package has a tsconfig.json */
+    readonly hasTsConfig: boolean;
+    /** Whether the package has an eslint config */
+    readonly hasEslintConfig: boolean;
+}
+/**
+ * Error that occurred during workspace scanning.
+ */
+interface ScanError {
+    /** Error code for programmatic handling */
+    readonly code: 'INVALID_PATH' | 'NO_PACKAGE_JSON' | 'INVALID_PACKAGE_JSON' | 'READ_ERROR';
+    /** Human-readable error message */
+    readonly message: string;
+    /** Path where the error occurred */
+    readonly path: string;
+    /** Underlying error cause */
+    readonly cause?: unknown;
+}
+/**
+ * Result of a workspace scan operation.
+ */
+interface WorkspaceScanResult {
+    /** All discovered packages */
+    readonly packages: readonly WorkspacePackage[];
+    /** Root workspace path */
+    readonly workspacePath: string;
+    /** Errors encountered during scanning */
+    readonly errors: readonly ScanError[];
+    /** Duration of scan in milliseconds */
+    readonly durationMs: number;
+}
+/**
+ * Creates a workspace scanner for discovering and analyzing packages.
+ *
+ * @example
+ * ```ts
+ * const scanner = createWorkspaceScanner({rootDir: '/path/to/monorepo'})
+ * const result = await scanner.scan()
+ *
+ * for (const pkg of result.packages) {
+ *   console.log(`Found package: ${pkg.name}`)
+ * }
+ * ```
+ */
+declare function createWorkspaceScanner(options: WorkspaceScannerOptions): {
+    /** Scan the entire workspace for packages */
+    readonly scan: () => Promise<WorkspaceScanResult>;
+    /** Scan a single package directory */
+    readonly scanPackage: (packagePath: string) => Promise<Result<WorkspacePackage, ScanError>>;
+    /** Collect source files from a directory */
+    readonly collectSourceFiles: (dir: string) => Promise<readonly string[]>;
+};
+/**
+ * Filter packages by name pattern.
+ */
+declare function filterPackagesByPattern(packages: readonly WorkspacePackage[], pattern: string): WorkspacePackage[];
+/**
+ * Group packages by their npm scope.
+ */
+declare function groupPackagesByScope(packages: readonly WorkspacePackage[]): Map<string, WorkspacePackage[]>;
+/**
+ * Extract the scope from a scoped package name.
+ */
+declare function getPackageScope(packageName: string): string | undefined;
+/**
+ * Get the unscoped name from a package name.
+ */
+declare function getUnscopedName(packageName: string): string;
+
+/**
+ * Core analyzer interface and types for workspace analysis.
+ *
+ * Defines the plugin architecture contract that all analyzers must implement,
+ * enabling extensible and composable analysis pipelines.
+ */
+
+/**
+ * Context provided to analyzers during analysis runs.
+ * Contains all information needed to perform analysis without side effects.
+ */
+interface AnalysisContext$1 {
+    /** Root path of the workspace being analyzed */
+    readonly workspacePath: string;
+    /** All packages discovered in the workspace */
+    readonly packages: readonly WorkspacePackage[];
+    /** Analyzer-specific configuration options */
+    readonly config: AnalyzerOptions;
+    /** Report progress during long-running analysis */
+    readonly reportProgress?: (message: string) => void;
+}
+/**
+ * Options for configuring analyzer behavior.
+ */
+interface AnalyzerOptions {
+    /** Glob patterns for files to include */
+    readonly include?: readonly string[];
+    /** Glob patterns for files to exclude */
+    readonly exclude?: readonly string[];
+    /** Minimum severity level to report */
+    readonly minSeverity?: Severity;
+    /** Categories to analyze (empty means all) */
+    readonly categories?: readonly IssueCategory[];
+    /** Analyzer-specific rule configurations */
+    readonly rules?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Error that can occur during analysis.
+ */
+interface AnalyzerError {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Additional context about the error */
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Metadata describing an analyzer implementation.
+ */
+interface AnalyzerMetadata {
+    /** Unique identifier for this analyzer */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of what this analyzer checks */
+    readonly description: string;
+    /** Categories of issues this analyzer can detect */
+    readonly categories: readonly IssueCategory[];
+    /** Default severity for issues from this analyzer */
+    readonly defaultSeverity: Severity;
+}
+/**
+ * Core interface that all analyzers must implement.
+ *
+ * @example
+ * ```ts
+ * const myAnalyzer: Analyzer = {
+ *   metadata: {
+ *     id: 'my-analyzer',
+ *     name: 'My Custom Analyzer',
+ *     description: 'Checks for custom patterns',
+ *     categories: ['architecture'],
+ *     defaultSeverity: 'warning',
+ *   },
+ *   async analyze(context) {
+ *     const issues: Issue[] = []
+ *     // Perform analysis...
+ *     return ok(issues)
+ *   },
+ * }
+ * ```
+ */
+interface Analyzer {
+    /** Metadata describing this analyzer */
+    readonly metadata: AnalyzerMetadata;
+    /**
+     * Perform analysis and return discovered issues.
+     *
+     * @param context - Analysis context with workspace information
+     * @returns Result containing issues found or an error
+     */
+    readonly analyze: (context: AnalysisContext$1) => Promise<Result<readonly Issue[], AnalyzerError>>;
+}
+/**
+ * Factory function signature for creating analyzers.
+ */
+type AnalyzerFactory = (options?: AnalyzerOptions) => Analyzer;
+/**
+ * Configuration for a single analyzer in the registry.
+ */
+interface AnalyzerRegistration {
+    /** The analyzer instance or factory */
+    readonly analyzer: Analyzer | AnalyzerFactory;
+    /** Whether this analyzer is enabled by default */
+    readonly enabled: boolean;
+    /** Priority for execution order (lower runs first) */
+    readonly priority: number;
+}
+/**
+ * Creates an issue with consistent defaults.
+ *
+ * @example
+ * ```ts
+ * const issue = createIssue({
+ *   id: 'missing-types',
+ *   title: 'Missing types field',
+ *   description: 'package.json should declare a types entry point',
+ *   severity: 'warning',
+ *   category: 'configuration',
+ *   location: {filePath: '/path/to/package.json'},
+ * })
+ * ```
+ */
+declare function createIssue(params: Omit<Issue, 'relatedLocations' | 'suggestion' | 'metadata'> & {
+    relatedLocations?: Issue['relatedLocations'];
+    suggestion?: Issue['suggestion'];
+    metadata?: Issue['metadata'];
+}): Issue;
+/**
+ * Helper to check if an analyzer should skip a category based on configuration.
+ */
+declare function shouldAnalyzeCategory(category: IssueCategory, options: AnalyzerOptions | undefined): boolean;
+/**
+ * Helper to check if an issue meets minimum severity threshold.
+ */
+declare function meetsMinSeverity(severity: Severity, minSeverity: Severity | undefined): boolean;
+/**
+ * Filters issues based on configuration options.
+ */
+declare function filterIssues(issues: readonly Issue[], options: AnalyzerOptions): readonly Issue[];
+
+/**
+ * Architectural rule engine for validating code patterns and enforcing best practices.
+ *
+ * Provides a plugin architecture for extensible analysis rules that detect
+ * architectural violations, anti-patterns, and best practice deviations.
+ */
+
+/**
+ * Context provided to rules during evaluation.
+ */
+interface RuleContext {
+    /** The source file being evaluated */
+    readonly sourceFile: SourceFile;
+    /** The package containing the source file */
+    readonly pkg: WorkspacePackage;
+    /** Root path of the workspace */
+    readonly workspacePath: string;
+    /** All packages in the workspace for cross-package analysis */
+    readonly allPackages: readonly WorkspacePackage[];
+    /** Resolved tsconfig paths for alias validation */
+    readonly tsconfigPaths?: Readonly<Record<string, readonly string[]>>;
+    /** Layer configuration for architectural validation */
+    readonly layerConfig?: LayerConfiguration;
+    /** Report progress during evaluation */
+    readonly reportProgress?: (message: string) => void;
+}
+/**
+ * Layer configuration for enforcing architectural boundaries.
+ */
+interface LayerConfiguration {
+    /** Layer definitions with allowed dependencies */
+    readonly layers: readonly LayerDefinition[];
+    /** File patterns to layer mapping */
+    readonly patterns: readonly LayerPattern[];
+}
+/**
+ * Defines an architectural layer with its allowed dependencies.
+ */
+interface LayerDefinition {
+    /** Layer name (e.g., 'domain', 'application', 'infrastructure') */
+    readonly name: string;
+    /** Other layers this layer can import from */
+    readonly allowedDependencies: readonly string[];
+}
+/**
+ * Maps file patterns to architectural layers.
+ */
+interface LayerPattern {
+    /** Glob pattern to match files */
+    readonly pattern: string;
+    /** Layer this pattern belongs to */
+    readonly layer: string;
+}
+/**
+ * Result of a single rule violation.
+ */
+interface RuleViolation {
+    /** Rule that was violated */
+    readonly ruleId: string;
+    /** Location of the violation */
+    readonly location: IssueLocation;
+    /** Human-readable message explaining the violation */
+    readonly message: string;
+    /** Suggested fix for the violation */
+    readonly suggestion?: string;
+    /** Related locations (e.g., the imported module) */
+    readonly relatedLocations?: readonly IssueLocation[];
+    /** Additional metadata for machine processing */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Result of evaluating a rule on a source file.
+ */
+interface RuleResult {
+    /** Violations found */
+    readonly violations: readonly RuleViolation[];
+    /** Whether the evaluation completed successfully */
+    readonly success: boolean;
+    /** Error message if evaluation failed */
+    readonly error?: string;
+}
+/**
+ * Metadata describing a rule.
+ */
+interface RuleMetadata {
+    /** Unique identifier for the rule */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of what the rule checks */
+    readonly description: string;
+    /** Default severity for violations */
+    readonly defaultSeverity: Severity;
+    /** Category for grouping */
+    readonly category: 'layer-violation' | 'barrel-export' | 'public-api' | 'side-effect' | 'boundary';
+    /** Documentation URL */
+    readonly docsUrl?: string;
+}
+/**
+ * Configuration options for a rule.
+ */
+interface RuleOptions {
+    /** Whether the rule is enabled */
+    readonly enabled?: boolean;
+    /** Severity override */
+    readonly severity?: Severity;
+    /** File patterns to include */
+    readonly include?: readonly string[];
+    /** File patterns to exclude */
+    readonly exclude?: readonly string[];
+    /** Rule-specific options */
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Core interface that all architectural rules must implement.
+ */
+interface Rule {
+    /** Metadata describing the rule */
+    readonly metadata: RuleMetadata;
+    /**
+     * Evaluate the rule against a source file.
+     *
+     * @param context - Rule evaluation context
+     * @returns Result containing violations found
+     */
+    readonly evaluate: (context: RuleContext) => Promise<RuleResult>;
+}
+/**
+ * Factory function signature for creating rules.
+ */
+type RuleFactory = (options?: RuleOptions) => Rule;
+/**
+ * Registration entry for a rule in the engine.
+ */
+interface RuleRegistration {
+    /** The rule instance or factory */
+    readonly rule: Rule | RuleFactory;
+    /** Whether the rule is enabled */
+    readonly enabled: boolean;
+    /** Priority for execution order (lower runs first) */
+    readonly priority: number;
+    /** Configuration options */
+    readonly options?: RuleOptions;
+}
+/**
+ * Rule engine for managing and executing architectural rules.
+ */
+interface RuleEngine {
+    /** Register a rule */
+    readonly register: (id: string, registration: RuleRegistration) => void;
+    /** Unregister a rule */
+    readonly unregister: (id: string) => boolean;
+    /** Get a registered rule */
+    readonly get: (id: string) => RuleRegistration | undefined;
+    /** Get all registered rules */
+    readonly getAll: () => Map<string, RuleRegistration>;
+    /** Get enabled rules sorted by priority */
+    readonly getEnabled: () => Rule[];
+    /** Check if a rule is registered */
+    readonly has: (id: string) => boolean;
+    /** Evaluate all enabled rules against a source file */
+    readonly evaluateFile: (context: RuleContext) => Promise<Result<readonly Issue[], RuleEngineError>>;
+    /** Evaluate all enabled rules against multiple source files */
+    readonly evaluateFiles: (contexts: readonly RuleContext[]) => Promise<Result<readonly Issue[], RuleEngineError>>;
+}
+/**
+ * Error from rule engine operations.
+ */
+interface RuleEngineError {
+    /** Error code for programmatic handling */
+    readonly code: 'RULE_EXECUTION_ERROR' | 'RULE_NOT_FOUND' | 'INVALID_CONFIGURATION';
+    /** Human-readable error message */
+    readonly message: string;
+    /** Rule ID that caused the error (if applicable) */
+    readonly ruleId?: string;
+    /** Additional context about the error */
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Creates a new rule engine instance.
+ *
+ * @example
+ * ```ts
+ * const engine = createRuleEngine()
+ *
+ * engine.register('no-barrel-exports', {
+ *   rule: createBarrelExportRule(),
+ *   enabled: true,
+ *   priority: 10,
+ * })
+ *
+ * const issues = await engine.evaluateFile(context)
+ * ```
+ */
+declare function createRuleEngine(): RuleEngine;
+/**
+ * Default layer configuration for typical TypeScript projects.
+ */
+declare const DEFAULT_LAYER_CONFIG: LayerConfiguration;
+/**
+ * Determines the architectural layer for a file path based on patterns.
+ *
+ * @param filePath - File path to check
+ * @param config - Layer configuration
+ * @returns Layer name or undefined if no match
+ */
+declare function getFileLayer(filePath: string, config: LayerConfiguration): string | undefined;
+/**
+ * Checks if an import from one layer to another is allowed.
+ *
+ * @param sourceLayer - Layer of the importing file
+ * @param targetLayer - Layer of the imported module
+ * @param config - Layer configuration
+ * @returns Whether the import is allowed
+ */
+declare function isLayerImportAllowed(sourceLayer: string, targetLayer: string, config: LayerConfiguration): boolean;
+/**
+ * Built-in rule IDs.
+ */
+declare const BUILTIN_RULE_IDS: {
+    readonly LAYER_VIOLATION: "layer-violation";
+    readonly BARREL_EXPORT: "barrel-export";
+    readonly PUBLIC_API: "public-api";
+    readonly SIDE_EFFECT: "side-effect";
+    readonly PATH_ALIAS: "path-alias";
+    readonly PACKAGE_BOUNDARY: "package-boundary";
+};
+
+/**
+ * ArchitecturalAnalyzer - Validates architectural patterns and enforces best practices.
+ *
+ * Integrates multiple architectural rules to detect:
+ * - Layer boundary violations
+ * - Barrel export (export *) misuse
+ * - Public API surface issues
+ * - Side effects in module initialization
+ * - Import path alias violations
+ * - Monorepo package boundary violations
+ */
+
+/**
+ * Configuration options for the ArchitecturalAnalyzer.
+ */
+interface ArchitecturalAnalyzerOptions extends AnalyzerOptions {
+    /** Layer configuration for architectural boundary enforcement */
+    readonly layerConfig?: LayerConfiguration;
+    /** tsconfig.json paths for alias validation */
+    readonly tsconfigPaths?: Readonly<Record<string, readonly string[]>>;
+    /** Enable layer violation detection */
+    readonly checkLayerViolations?: boolean;
+    /** Enable barrel export detection */
+    readonly checkBarrelExports?: boolean;
+    /** Enable public API validation */
+    readonly checkPublicApi?: boolean;
+    /** Enable side effect detection */
+    readonly checkSideEffects?: boolean;
+    /** Enable path alias validation */
+    readonly checkPathAliases?: boolean;
+    /** Enable package boundary enforcement */
+    readonly checkPackageBoundaries?: boolean;
+    /** File patterns for entry points */
+    readonly entryPointPatterns?: readonly string[];
+    /** Patterns allowed for barrel exports */
+    readonly allowedBarrelPatterns?: readonly string[];
+    /** Shared packages that can be imported from anywhere */
+    readonly sharedPackages?: readonly string[];
+    /** Severity for layer violations */
+    readonly layerViolationSeverity?: Severity;
+    /** Severity for barrel export issues */
+    readonly barrelExportSeverity?: Severity;
+    /** Severity for public API issues */
+    readonly publicApiSeverity?: Severity;
+    /** Severity for side effect issues */
+    readonly sideEffectSeverity?: Severity;
+}
+declare const architecturalAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates an ArchitecturalAnalyzer instance with all built-in rules.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createArchitecturalAnalyzer({
+ *   checkLayerViolations: true,
+ *   checkBarrelExports: true,
+ *   layerConfig: {
+ *     layers: [
+ *       {name: 'domain', allowedDependencies: []},
+ *       {name: 'application', allowedDependencies: ['domain']},
+ *     ],
+ *     patterns: [
+ *       {pattern: '**\/domain\/**', layer: 'domain'},
+ *       {pattern: '**\/application\/**', layer: 'application'},
+ *     ],
+ *   },
+ * })
+ *
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+declare function createArchitecturalAnalyzer(options?: ArchitecturalAnalyzerOptions): Analyzer;
+
+/**
+ * BuildConfigAnalyzer - Validates build configuration (tsup) for consistency and best practices.
+ *
+ * Detects issues such as:
+ * - Missing build configuration for publishable packages
+ * - Inconsistent build settings
+ * - Missing entry points
+ * - Format mismatches with package.json
+ */
+
+/**
+ * Configuration options specific to BuildConfigAnalyzer.
+ */
+interface BuildConfigAnalyzerOptions {
+    /** Whether to require build config for packages with build scripts */
+    readonly requireConfig?: boolean;
+    /** Expected config file pattern (e.g., 'tsup.config.ts') */
+    readonly expectedConfigFile?: string;
+    /** Whether to check for DTS generation */
+    readonly requireDts?: boolean;
+    /** Package names exempt from checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA$6: AnalyzerMetadata;
+/**
+ * Creates a BuildConfigAnalyzer instance.
+ */
+declare function createBuildConfigAnalyzer(options?: BuildConfigAnalyzerOptions): Analyzer;
+
+/**
+ * Import statement extractor for analyzing module dependencies.
+ *
+ * Extracts static imports, dynamic imports, and require() calls from TypeScript/JavaScript
+ * source files for dependency analysis.
+ *
+ * Uses ts-morph types (SourceFile, SyntaxKind) which are provided as a peer dependency
+ * via @bfra.me/doc-sync's transitive dependency on ts-morph.
+ */
+
+/**
+ * Type of import statement.
+ */
+type ImportType = 'static' | 'dynamic' | 'require' | 'type-only';
+/**
+ * Represents an extracted import statement.
+ */
+interface ExtractedImport {
+    /** The module specifier (path or package name) */
+    readonly moduleSpecifier: string;
+    /** Type of import */
+    readonly type: ImportType;
+    /** Imported names (for named imports) */
+    readonly importedNames?: readonly string[];
+    /** Default import name (if present) */
+    readonly defaultImport?: string;
+    /** Namespace import name (if present) */
+    readonly namespaceImport?: string;
+    /** Whether this is a side-effect only import */
+    readonly isSideEffectOnly: boolean;
+    /** Whether the import is from a relative path */
+    readonly isRelative: boolean;
+    /** Whether the import is from a workspace package */
+    readonly isWorkspacePackage: boolean;
+    /** Line number in the source file */
+    readonly line: number;
+    /** Column number in the source file */
+    readonly column: number;
+}
+/**
+ * Result of extracting imports from a source file.
+ */
+interface ImportExtractionResult {
+    /** All extracted imports */
+    readonly imports: readonly ExtractedImport[];
+    /** The source file path */
+    readonly filePath: string;
+    /** External package dependencies (non-relative, non-workspace) */
+    readonly externalDependencies: readonly string[];
+    /** Workspace package dependencies */
+    readonly workspaceDependencies: readonly string[];
+    /** Relative imports within the package */
+    readonly relativeImports: readonly string[];
+}
+/**
+ * Options for import extraction.
+ */
+interface ImportExtractorOptions {
+    /** Workspace package name prefixes (e.g., ['@bfra.me/']) */
+    readonly workspacePrefixes?: readonly string[];
+    /** Include type-only imports */
+    readonly includeTypeImports?: boolean;
+    /** Include dynamic imports */
+    readonly includeDynamicImports?: boolean;
+    /** Include require() calls */
+    readonly includeRequireCalls?: boolean;
+}
+/**
+ * Extracts all imports from a TypeScript/JavaScript source file.
+ *
+ * @example
+ * ```ts
+ * const project = createProject()
+ * const sourceFile = project.addSourceFileAtPath('./src/index.ts')
+ * const result = extractImports(sourceFile)
+ *
+ * for (const imp of result.imports) {
+ *   console.log(`Import: ${imp.moduleSpecifier} (${imp.type})`)
+ * }
+ * ```
+ */
+declare function extractImports(sourceFile: SourceFile, options?: ImportExtractorOptions): ImportExtractionResult;
+/**
+ * Checks if a module specifier is a relative import.
+ */
+declare function isRelativeImport(moduleSpecifier: string): boolean;
+/**
+ * Checks if a module specifier is a workspace package import.
+ */
+declare function isWorkspacePackageImport(moduleSpecifier: string, workspacePrefixes: readonly string[]): boolean;
+/**
+ * Extracts the package name from a module specifier.
+ *
+ * For scoped packages like '@scope/pkg/path', returns '@scope/pkg'.
+ * For unscoped packages like 'lodash/fp', returns 'lodash'.
+ */
+declare function getPackageNameFromSpecifier(moduleSpecifier: string): string;
+/**
+ * Resolves a relative import to an absolute file path.
+ */
+declare function resolveRelativeImport(fromFile: string, moduleSpecifier: string): string;
+/**
+ * Gets unique package dependencies from imports.
+ */
+declare function getUniqueDependencies(results: readonly ImportExtractionResult[]): {
+    readonly external: readonly string[];
+    readonly workspace: readonly string[];
+};
+
+/**
+ * Dependency graph builder for tracking import relationships.
+ *
+ * Builds an adjacency list representation of module dependencies
+ * for cycle detection and dependency analysis using Tarjan's algorithm.
+ *
+ * This module uses types from import-extractor.ts which depends on ts-morph
+ * (provided as a peer dependency via @bfra.me/doc-sync).
+ */
+
+/**
+ * A node in the dependency graph representing a module.
+ */
+interface DependencyNode {
+    /** Unique identifier (typically the file path) */
+    readonly id: string;
+    /** Display name for the node */
+    readonly name: string;
+    /** File path of the module */
+    readonly filePath: string;
+    /** Package name if this is the root of a package */
+    readonly packageName?: string;
+    /** Outgoing edges (modules this node imports from) */
+    readonly imports: readonly string[];
+    /** Incoming edges (modules that import this node) */
+    readonly importedBy: readonly string[];
+    /** All import details for this node */
+    readonly importDetails: readonly ExtractedImport[];
+}
+/**
+ * An edge in the dependency graph representing an import relationship.
+ */
+interface DependencyEdge {
+    /** Source node (the importing module) */
+    readonly from: string;
+    /** Target node (the imported module) */
+    readonly to: string;
+    /** Import type */
+    readonly type: ExtractedImport['type'];
+    /** Whether this is a type-only import */
+    readonly isTypeOnly: boolean;
+}
+/**
+ * A cycle detected in the dependency graph.
+ */
+interface DependencyCycle {
+    /** Nodes in the cycle, in order */
+    readonly nodes: readonly string[];
+    /** Edges forming the cycle */
+    readonly edges: readonly DependencyEdge[];
+    /** Human-readable representation of the cycle */
+    readonly description: string;
+}
+/**
+ * The complete dependency graph.
+ */
+interface DependencyGraph {
+    /** All nodes in the graph */
+    readonly nodes: ReadonlyMap<string, DependencyNode>;
+    /** All edges in the graph */
+    readonly edges: readonly DependencyEdge[];
+    /** Root workspace path */
+    readonly rootPath: string;
+    /** Total number of modules */
+    readonly moduleCount: number;
+    /** Total number of edges (import relationships) */
+    readonly edgeCount: number;
+}
+/**
+ * Statistics about the dependency graph.
+ */
+interface GraphStatistics {
+    /** Total number of nodes */
+    readonly nodeCount: number;
+    /** Total number of edges */
+    readonly edgeCount: number;
+    /** Number of external dependencies */
+    readonly externalDependencies: number;
+    /** Number of workspace dependencies */
+    readonly workspaceDependencies: number;
+    /** Most imported modules (by incoming edge count) */
+    readonly mostImported: readonly {
+        readonly id: string;
+        readonly count: number;
+    }[];
+    /** Modules with most imports (by outgoing edge count) */
+    readonly mostImporting: readonly {
+        readonly id: string;
+        readonly count: number;
+    }[];
+}
+/**
+ * Options for building a dependency graph.
+ */
+interface DependencyGraphOptions {
+    /** Root path of the workspace */
+    readonly rootPath: string;
+    /** Include type-only imports in the graph */
+    readonly includeTypeImports?: boolean;
+    /** Resolve relative imports to absolute paths */
+    readonly resolveRelativeImports?: boolean;
+}
+/**
+ * Builds a dependency graph from import extraction results.
+ *
+ * @example
+ * ```ts
+ * const results: ImportExtractionResult[] = [...]
+ * const graph = buildDependencyGraph(results, {rootPath: '/workspace'})
+ *
+ * for (const [id, node] of graph.nodes) {
+ *   console.log(`${node.name} imports ${node.imports.length} modules`)
+ * }
+ * ```
+ */
+declare function buildDependencyGraph(results: readonly ImportExtractionResult[], options: DependencyGraphOptions): DependencyGraph;
+/**
+ * Finds all cycles in a dependency graph using Tarjan's algorithm.
+ *
+ * @example
+ * ```ts
+ * const cycles = findCycles(graph)
+ * for (const cycle of cycles) {
+ *   console.log(`Cycle detected: ${cycle.description}`)
+ * }
+ * ```
+ */
+declare function findCycles(graph: DependencyGraph): readonly DependencyCycle[];
+/**
+ * Computes statistics about the dependency graph.
+ */
+declare function computeGraphStatistics(graph: DependencyGraph, topN?: number): GraphStatistics;
+/**
+ * Gets all transitive dependencies of a node.
+ */
+declare function getTransitiveDependencies(graph: DependencyGraph, nodeId: string): readonly string[];
+/**
+ * Gets all modules that transitively depend on a node.
+ */
+declare function getTransitiveDependents(graph: DependencyGraph, nodeId: string): readonly string[];
+
+/**
+ * CircularImportAnalyzer - Detects circular import chains in workspace packages.
+ *
+ * Uses the dependency graph builder and Tarjan's algorithm to identify
+ * circular dependencies, providing full path reporting and cycle visualization.
+ *
+ * Reports:
+ * - Direct cycles (A → B → A)
+ * - Transitive cycles (A → B → C → A)
+ * - Self-imports (A → A)
+ * - Cycle severity based on depth and involvement
+ */
+
+/**
+ * Configuration options specific to CircularImportAnalyzer.
+ */
+interface CircularImportAnalyzerOptions {
+    /** Maximum cycle length to report (helps avoid reporting very large cycles) */
+    readonly maxCycleLength?: number;
+    /** Whether to include type-only imports in cycle detection */
+    readonly includeTypeImports?: boolean;
+    /** Severity for direct (2-node) cycles */
+    readonly directCycleSeverity?: Severity;
+    /** Severity for transitive cycles */
+    readonly transitiveCycleSeverity?: Severity;
+    /** File patterns to exclude from analysis */
+    readonly excludePatterns?: readonly string[];
+    /** Workspace package prefixes */
+    readonly workspacePrefixes?: readonly string[];
+}
+declare const circularImportAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates a CircularImportAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createCircularImportAnalyzer({
+ *   maxCycleLength: 10,
+ *   directCycleSeverity: 'error',
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+declare function createCircularImportAnalyzer(options?: CircularImportAnalyzerOptions): Analyzer;
+/**
+ * Visualization data for a detected cycle.
+ */
+interface CycleVisualization {
+    /** Nodes in the cycle with display names */
+    readonly nodes: readonly CycleNode[];
+    /** Edges in the cycle */
+    readonly edges: readonly CycleEdge[];
+    /** ASCII art representation of the cycle */
+    readonly ascii: string;
+    /** Mermaid diagram code for rendering */
+    readonly mermaid: string;
+}
+/**
+ * A node in the cycle visualization.
+ */
+interface CycleNode {
+    /** Unique identifier */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** Full file path */
+    readonly filePath: string;
+    /** Whether this node starts the cycle */
+    readonly isStart: boolean;
+}
+/**
+ * An edge in the cycle visualization.
+ */
+interface CycleEdge {
+    /** Source node ID */
+    readonly from: string;
+    /** Target node ID */
+    readonly to: string;
+    /** Import type */
+    readonly importType: string;
+}
+/**
+ * Generates visualization data for a cycle.
+ */
+declare function generateCycleVisualization(cycle: DependencyCycle, _graph: DependencyGraph, workspacePath: string): CycleVisualization;
+/**
+ * Statistics about circular imports in a package.
+ */
+interface CircularImportStats {
+    /** Total number of cycles detected */
+    readonly totalCycles: number;
+    /** Number of direct (2-node) cycles */
+    readonly directCycles: number;
+    /** Number of transitive cycles */
+    readonly transitiveCycles: number;
+    /** Files involved in cycles */
+    readonly affectedFiles: readonly string[];
+    /** Average cycle length */
+    readonly averageCycleLength: number;
+    /** Maximum cycle length found */
+    readonly maxCycleLength: number;
+}
+/**
+ * Computes statistics about detected cycles.
+ */
+declare function computeCycleStats(cycles: readonly DependencyCycle[]): CircularImportStats;
+
+/**
+ * ConfigConsistencyAnalyzer - Cross-validates configuration across multiple config files.
+ *
+ * Detects issues such as:
+ * - Mismatches between package.json exports and tsconfig outDir
+ * - TypeScript target/module inconsistencies with package.json type
+ * - Build output directory mismatches
+ * - Inconsistent configurations across workspace packages
+ */
+
+/**
+ * Configuration options specific to ConfigConsistencyAnalyzer.
+ */
+interface ConfigConsistencyAnalyzerOptions {
+    /** Whether to check tsconfig/package.json consistency */
+    readonly checkTsconfigPackageJson?: boolean;
+    /** Whether to check cross-package consistency */
+    readonly checkCrossPackage?: boolean;
+    /** Package names exempt from checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA$5: AnalyzerMetadata;
+/**
+ * Creates a ConfigConsistencyAnalyzer instance.
+ */
+declare function createConfigConsistencyAnalyzer(options?: ConfigConsistencyAnalyzerOptions): Analyzer;
+
+/**
+ * DeadCodeAnalyzer - Detects unreachable exports and unused code.
+ *
+ * Identifies code that is exported but never imported or used:
+ * - Exported functions never imported anywhere
+ * - Exported classes never instantiated or extended
+ * - Exported constants never referenced
+ * - Public API surface that could be reduced
+ *
+ * This helps identify code that can be safely removed to reduce bundle size
+ * and maintenance burden.
+ */
+
+/**
+ * Configuration options for DeadCodeAnalyzer.
+ */
+interface DeadCodeAnalyzerOptions {
+    /** Check for unused exports */
+    readonly checkUnusedExports?: boolean;
+    /** Check for unreachable code paths */
+    readonly checkUnreachableCode?: boolean;
+    /** Analyze cross-package usage (exports used in other workspace packages) */
+    readonly crossPackageAnalysis?: boolean;
+    /** Consider re-exports as usage */
+    readonly countReexportsAsUsage?: boolean;
+    /** Export patterns to ignore (e.g., 'index.ts' entry points) */
+    readonly ignoreExportPatterns?: readonly string[];
+    /** Severity for unused export warnings */
+    readonly unusedExportSeverity?: Severity;
+    /** Severity for unreachable code warnings */
+    readonly unreachableCodeSeverity?: Severity;
+    /** File patterns to exclude from analysis */
+    readonly excludePatterns?: readonly string[];
+}
+declare const deadCodeAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Information about an exported symbol.
+ */
+interface ExportedSymbol {
+    /** Symbol name */
+    readonly name: string;
+    /** Export type */
+    readonly type: 'function' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'namespace';
+    /** File where exported */
+    readonly filePath: string;
+    /** Location of the export */
+    readonly location: IssueLocation;
+    /** Whether this is a re-export */
+    readonly isReexport: boolean;
+    /** Whether this is a default export */
+    readonly isDefault: boolean;
+    /** Package containing this export */
+    readonly packageName: string;
+}
+/**
+ * Creates a DeadCodeAnalyzer instance.
+ */
+declare function createDeadCodeAnalyzer(options?: DeadCodeAnalyzerOptions): Analyzer;
+/**
+ * Computes statistics about dead code in a package.
+ */
+interface DeadCodeStats {
+    /** Total exports analyzed */
+    readonly totalExports: number;
+    /** Number of unused exports */
+    readonly unusedExports: number;
+    /** Number of used exports */
+    readonly usedExports: number;
+    /** Usage percentage */
+    readonly usagePercentage: number;
+    /** Breakdown by export type */
+    readonly byType: Readonly<Record<string, {
+        total: number;
+        unused: number;
+    }>>;
+}
+/**
+ * Computes dead code statistics from analysis results.
+ */
+declare function computeDeadCodeStats(exports: readonly ExportedSymbol[], unusedExportNames: readonly string[]): DeadCodeStats;
+
+/**
+ * DuplicateCodeAnalyzer - Detects duplicate code patterns using AST fingerprinting.
+ *
+ * Identifies code duplication within and across packages in the workspace:
+ * - Exact function duplicates with different names
+ * - Similar code blocks that could be refactored
+ * - Duplicated utility functions across packages
+ *
+ * Uses structural AST fingerprinting rather than text comparison to detect
+ * semantically equivalent code regardless of variable naming or formatting.
+ */
+
+/**
+ * Configuration options for DuplicateCodeAnalyzer.
+ */
+interface DuplicateCodeAnalyzerOptions {
+    /** Minimum number of statements for a block to be considered for duplication */
+    readonly minStatements?: number;
+    /** Minimum fingerprint similarity threshold (0-1) for reporting */
+    readonly similarityThreshold?: number;
+    /** Check for duplicates across packages (not just within) */
+    readonly crossPackageAnalysis?: boolean;
+    /** Report duplicate functions */
+    readonly reportFunctions?: boolean;
+    /** Report duplicate class methods */
+    readonly reportMethods?: boolean;
+    /** Report similar code blocks */
+    readonly reportCodeBlocks?: boolean;
+    /** Severity for exact duplicates */
+    readonly exactDuplicateSeverity?: Severity;
+    /** Severity for similar code */
+    readonly similarCodeSeverity?: Severity;
+    /** File patterns to exclude from analysis */
+    readonly excludePatterns?: readonly string[];
+}
+declare const duplicateCodeAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates a DuplicateCodeAnalyzer instance.
+ */
+declare function createDuplicateCodeAnalyzer(options?: DuplicateCodeAnalyzerOptions): Analyzer;
+/**
+ * Fingerprint of a code fragment for comparison.
+ */
+interface CodeFingerprint {
+    /** Unique hash of the structural fingerprint */
+    readonly hash: string;
+    /** Type of code fragment */
+    readonly type: 'function' | 'method' | 'block';
+    /** Name of the function/method (if applicable) */
+    readonly name?: string;
+    /** Package containing this code */
+    readonly packageName: string;
+    /** File path */
+    readonly filePath: string;
+    /** Location in the file */
+    readonly location: IssueLocation;
+    /** Number of statements in the fragment */
+    readonly statementCount: number;
+    /** Original code (for display) */
+    readonly codePreview: string;
+    /** Structural elements for similarity comparison */
+    readonly structure: readonly string[];
+}
+/**
+ * Detected duplicate code pattern.
+ */
+interface DuplicatePattern {
+    /** Fingerprint hash */
+    readonly hash: string;
+    /** All occurrences of this duplicate */
+    readonly occurrences: readonly CodeFingerprint[];
+    /** Whether this is an exact match or similar */
+    readonly isExactMatch: boolean;
+    /** Similarity score (1.0 for exact matches) */
+    readonly similarity: number;
+}
+
+/**
+ * DuplicateDependencyAnalyzer - Detects duplicate and inconsistent dependencies across workspace packages.
+ *
+ * Identifies:
+ * - Same dependency with different versions across packages
+ * - Dependencies that could be hoisted to workspace root
+ * - Redundant devDependencies that match production dependencies
+ * - Version conflicts that may cause runtime issues
+ */
+
+/**
+ * Configuration options specific to DuplicateDependencyAnalyzer.
+ */
+interface DuplicateDependencyAnalyzerOptions {
+    /** Ignore version differences for these packages */
+    readonly ignorePackages?: readonly string[];
+    /** Severity for version conflicts */
+    readonly conflictSeverity?: Severity;
+    /** Whether to suggest hoisting common dependencies */
+    readonly suggestHoisting?: boolean;
+    /** Minimum number of packages using a dependency to suggest hoisting */
+    readonly hoistingThreshold?: number;
+    /** Check for redundant dev dependencies */
+    readonly checkRedundantDev?: boolean;
+}
+declare const duplicateDependencyAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Information about a dependency occurrence.
+ */
+interface DependencyOccurrence {
+    readonly packageName: string;
+    readonly version: string;
+    readonly type: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+    readonly packageJsonPath: string;
+}
+/**
+ * Aggregated dependency information across all packages.
+ */
+interface DependencyInfo {
+    readonly dependencyName: string;
+    readonly occurrences: readonly DependencyOccurrence[];
+    readonly versions: readonly string[];
+    readonly hasConflict: boolean;
+}
+/**
+ * Creates a DuplicateDependencyAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createDuplicateDependencyAnalyzer({
+ *   conflictSeverity: 'error',
+ *   suggestHoisting: true,
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+declare function createDuplicateDependencyAnalyzer(options?: DuplicateDependencyAnalyzerOptions): Analyzer;
+/**
+ * Aggregates duplicate dependency statistics.
+ */
+interface DuplicateDependencyStats {
+    /** Total unique dependencies across workspace */
+    readonly totalUniqueDependencies: number;
+    /** Number of dependencies with version conflicts */
+    readonly conflictingDependencies: number;
+    /** Number of packages with redundant dev dependencies */
+    readonly packagesWithRedundantDev: number;
+    /** Dependencies appearing in most packages */
+    readonly mostCommon: readonly {
+        readonly name: string;
+        readonly count: number;
+    }[];
+    /** Dependencies with the most version variants */
+    readonly mostVariants: readonly {
+        readonly name: string;
+        readonly versionCount: number;
+    }[];
+}
+/**
+ * Computes statistics about dependency duplicates.
+ */
+declare function computeDuplicateStats(dependencyMap: ReadonlyMap<string, DependencyInfo>, topN?: number): DuplicateDependencyStats;
+
+/**
+ * EslintConfigAnalyzer - Validates ESLint configuration for consistency and best practices.
+ *
+ * Detects issues such as:
+ * - Missing ESLint configuration files
+ * - Inconsistent config patterns across packages
+ * - Missing recommended plugins for TypeScript packages
+ */
+
+/**
+ * Configuration options specific to EslintConfigAnalyzer.
+ */
+interface EslintConfigAnalyzerOptions {
+    /** Whether to require ESLint config for all packages */
+    readonly requireConfig?: boolean;
+    /** Expected config file pattern (e.g., 'eslint.config.ts') */
+    readonly expectedConfigFile?: string;
+    /** Whether to check for flat config usage */
+    readonly requireFlatConfig?: boolean;
+    /** Package names exempt from checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA$4: AnalyzerMetadata;
+/**
+ * Creates an EslintConfigAnalyzer instance.
+ */
+declare function createEslintConfigAnalyzer(options?: EslintConfigAnalyzerOptions): Analyzer;
+
+/**
+ * ExportsFieldAnalyzer - Validates package.json exports against actual source structure.
+ *
+ * Detects issues such as:
+ * - Exports pointing to non-existent files
+ * - Missing exports for existing source files
+ * - Invalid export conditions
+ * - Inconsistent export patterns
+ */
+
+/**
+ * Configuration options specific to ExportsFieldAnalyzer.
+ */
+interface ExportsFieldAnalyzerOptions {
+    /** Whether to check if export paths resolve to existing files */
+    readonly validatePaths?: boolean;
+    /** Whether to check export condition order */
+    readonly checkConditionOrder?: boolean;
+    /** Whether to suggest missing exports for source files */
+    readonly suggestMissingExports?: boolean;
+    /** Common output directories to check for built files */
+    readonly outputDirs?: readonly string[];
+    /** Package names exempt from checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA$3: AnalyzerMetadata;
+/**
+ * Creates an ExportsFieldAnalyzer instance.
+ */
+declare function createExportsFieldAnalyzer(options?: ExportsFieldAnalyzerOptions): Analyzer;
+
+/**
+ * LargeDependencyAnalyzer - Identifies large dependencies that impact bundle size.
+ *
+ * Analyzes package dependencies to identify:
+ * - Known large packages that significantly impact bundle size
+ * - Dependencies with lighter alternatives
+ * - Packages that may be overkill for the actual usage
+ *
+ * Uses a database of known package sizes and suggests optimizations.
+ */
+
+/**
+ * Configuration options for LargeDependencyAnalyzer.
+ */
+interface LargeDependencyAnalyzerOptions {
+    /** Minimum size threshold in KB (gzipped) to report */
+    readonly sizeThresholdKb?: number;
+    /** Report lighter alternatives when available */
+    readonly suggestAlternatives?: boolean;
+    /** Check for packages with heavy transitive dependencies */
+    readonly checkTransitiveDeps?: boolean;
+    /** Severity for large dependency warnings */
+    readonly largeDependencySeverity?: Severity;
+    /** Severity for alternative suggestions */
+    readonly alternativeSuggestionSeverity?: Severity;
+    /** Packages to ignore */
+    readonly ignorePackages?: readonly string[];
+}
+declare const largeDependencyAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Known package sizes and metadata.
+ * Sizes are approximate gzipped KB.
+ */
+interface PackageInfo {
+    /** Approximate gzipped size in KB */
+    readonly sizeKb: number;
+    /** Category of the package */
+    readonly category: string;
+    /** Lighter alternatives (if any) */
+    readonly alternatives?: readonly AlternativePackage[];
+    /** Whether the package supports tree-shaking */
+    readonly treeShakable: boolean;
+    /** Notes about usage */
+    readonly notes?: string;
+}
+interface AlternativePackage {
+    /** Package name */
+    readonly name: string;
+    /** Approximate size in KB */
+    readonly sizeKb: number;
+    /** Notes about the alternative */
+    readonly notes?: string;
+}
+/**
+ * Creates a LargeDependencyAnalyzer instance.
+ */
+declare function createLargeDependencyAnalyzer(options?: LargeDependencyAnalyzerOptions): Analyzer;
+/**
+ * Gets known package information for a dependency.
+ */
+declare function getPackageInfo(packageName: string): PackageInfo | undefined;
+/**
+ * Gets all known large packages.
+ */
+declare function getKnownLargePackages(): readonly string[];
+
+/**
+ * PackageJsonAnalyzer - Validates package.json configuration for best practices.
+ *
+ * Detects issues such as:
+ * - Missing required fields (types, exports, etc.)
+ * - Inconsistent entry points
+ * - Invalid dependency versions
+ * - Missing peer dependency declarations
+ */
+
+/**
+ * Configuration options specific to PackageJsonAnalyzer.
+ */
+interface PackageJsonAnalyzerOptions {
+    /** Whether to require types field for TypeScript packages */
+    readonly requireTypes?: boolean;
+    /** Whether to require exports field for ESM packages */
+    readonly requireExports?: boolean;
+    /** Whether to check for common scripts like build, test, lint */
+    readonly checkScripts?: boolean;
+    /** Package names exempt from certain checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA$2: AnalyzerMetadata;
+/**
+ * Creates a PackageJsonAnalyzer instance.
+ */
+declare function createPackageJsonAnalyzer(options?: PackageJsonAnalyzerOptions): Analyzer;
+
+/**
+ * PeerDependencyAnalyzer - Validates peer dependency declarations in workspace packages.
+ *
+ * Ensures workspace packages correctly declare peer dependencies for:
+ * - Packages that should be provided by consumers
+ * - Plugin architectures where host version matters
+ * - Framework dependencies that consumers must provide
+ *
+ * Reports:
+ * - Missing peer dependency declarations
+ * - Peer dependency version mismatches
+ * - Invalid peer dependency ranges
+ * - Workspace packages not declared as peers when they should be
+ */
+
+/**
+ * Configuration options specific to PeerDependencyAnalyzer.
+ */
+interface PeerDependencyAnalyzerOptions {
+    /** Packages that should always be declared as peer dependencies */
+    readonly requiredPeers?: readonly string[];
+    /** Packages that should never be peer dependencies */
+    readonly disallowedPeers?: readonly string[];
+    /** Whether to check for workspace packages that should be peers */
+    readonly checkWorkspacePeers?: boolean;
+    /** Workspace package prefixes */
+    readonly workspacePrefixes?: readonly string[];
+    /** Check for peer dependencies that are also in dependencies (dual declaration) */
+    readonly checkDualDeclarations?: boolean;
+}
+declare const peerDependencyAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates a PeerDependencyAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createPeerDependencyAnalyzer({
+ *   requiredPeers: ['react', 'typescript'],
+ *   checkDualDeclarations: true,
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+declare function createPeerDependencyAnalyzer(options?: PeerDependencyAnalyzerOptions): Analyzer;
+
+/**
+ * TreeShakingBlockerAnalyzer - Detects patterns that prevent effective tree-shaking.
+ *
+ * Identifies code patterns that block bundler tree-shaking optimizations:
+ * - CommonJS require() calls mixed with ES modules
+ * - Namespace imports (import * as X)
+ * - Side-effect imports without proper module configuration
+ * - Module.exports patterns
+ * - Dynamic requires with non-literal arguments
+ *
+ * Also detects type-only import enforcement opportunities (TASK-051) and
+ * provides dynamic import optimization suggestions (TASK-052).
+ */
+
+/**
+ * Configuration options for TreeShakingBlockerAnalyzer.
+ */
+interface TreeShakingBlockerAnalyzerOptions {
+    /** Report namespace imports (import * as X) */
+    readonly reportNamespaceImports?: boolean;
+    /** Report CommonJS require() calls */
+    readonly reportRequireCalls?: boolean;
+    /** Report module.exports patterns */
+    readonly reportModuleExports?: boolean;
+    /** Report dynamic require with non-literal arguments */
+    readonly reportDynamicRequire?: boolean;
+    /** Report type-only import opportunities */
+    readonly reportTypeOnlyOpportunities?: boolean;
+    /** Report dynamic import optimization opportunities */
+    readonly reportDynamicImportOpportunities?: boolean;
+    /** Severity for CommonJS interop issues */
+    readonly commonJsInteropSeverity?: Severity;
+    /** Severity for namespace import issues */
+    readonly namespaceImportSeverity?: Severity;
+    /** Severity for type-only import opportunities */
+    readonly typeOnlyImportSeverity?: Severity;
+    /** File patterns to exclude from analysis */
+    readonly excludePatterns?: readonly string[];
+}
+declare const treeShakingBlockerAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates a TreeShakingBlockerAnalyzer instance.
+ */
+declare function createTreeShakingBlockerAnalyzer(options?: TreeShakingBlockerAnalyzerOptions): Analyzer;
+/**
+ * Detected tree-shaking blocker pattern.
+ */
+interface TreeShakingBlocker {
+    /** Type of blocker */
+    readonly type: TreeShakingBlockerType;
+    /** Location in source */
+    readonly location: IssueLocation;
+    /** Detailed description */
+    readonly description: string;
+    /** Suggested fix */
+    readonly suggestion: string;
+    /** Additional metadata */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+type TreeShakingBlockerType = 'namespace-import' | 'require-call' | 'module-exports' | 'dynamic-require' | 'side-effect-import' | 'type-only-opportunity' | 'dynamic-import-opportunity';
+
+/**
+ * TsconfigAnalyzer - Validates tsconfig.json configuration for consistency and best practices.
+ *
+ * Detects issues such as:
+ * - Missing recommended compiler options
+ * - Inconsistent settings across packages
+ * - Invalid path mappings
+ * - Missing project references
+ */
+
+/**
+ * Configuration options specific to TsconfigAnalyzer.
+ */
+interface TsconfigAnalyzerOptions {
+    /** Whether to check for strict mode */
+    readonly requireStrict?: boolean;
+    /** Whether to require explicit module settings */
+    readonly requireModuleSettings?: boolean;
+    /** Whether to check path mapping consistency */
+    readonly checkPaths?: boolean;
+    /** Whether to require project references in monorepo */
+    readonly requireReferences?: boolean;
+    /** Package names exempt from certain checks */
+    readonly exemptPackages?: readonly string[];
+    /** Expected base tsconfig to extend from */
+    readonly expectedExtends?: string;
+}
+declare const METADATA$1: AnalyzerMetadata;
+/**
+ * Creates a TsconfigAnalyzer instance.
+ */
+declare function createTsconfigAnalyzer(options?: TsconfigAnalyzerOptions): Analyzer;
+
+/**
+ * UnusedDependencyAnalyzer - Detects unused dependencies in workspace packages.
+ *
+ * Compares declared dependencies in package.json against actual imports
+ * found in source files to identify unused packages that can be removed.
+ *
+ * Handles:
+ * - Static imports (import { x } from 'pkg')
+ * - Dynamic imports (await import('pkg'))
+ * - require() calls (const x = require('pkg'))
+ * - Type-only imports (import type { T } from 'pkg')
+ * - Dev vs production dependency classification
+ */
+
+/**
+ * Configuration options specific to UnusedDependencyAnalyzer.
+ */
+interface UnusedDependencyAnalyzerOptions {
+    /** Include devDependencies in analysis */
+    readonly checkDevDependencies?: boolean;
+    /** Include peerDependencies in analysis */
+    readonly checkPeerDependencies?: boolean;
+    /** Include optionalDependencies in analysis */
+    readonly checkOptionalDependencies?: boolean;
+    /** Package names to ignore (regex patterns) */
+    readonly ignorePatterns?: readonly string[];
+    /** Packages known to be used implicitly (e.g., type packages, build tools) */
+    readonly implicitlyUsed?: readonly string[];
+    /** Workspace package prefixes for identifying workspace dependencies */
+    readonly workspacePrefixes?: readonly string[];
+}
+declare const unusedDependencyAnalyzerMetadata: AnalyzerMetadata;
+/**
+ * Creates an UnusedDependencyAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createUnusedDependencyAnalyzer({
+ *   checkDevDependencies: true,
+ *   ignorePatterns: ['@types/*'],
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+declare function createUnusedDependencyAnalyzer(options?: UnusedDependencyAnalyzerOptions): Analyzer;
+/**
+ * Aggregates import information from multiple packages for workspace-wide analysis.
+ */
+declare function aggregatePackageImports(packages: readonly WorkspacePackage[], importResults: ReadonlyMap<string, readonly ImportExtractionResult[]>): {
+    readonly externalByPackage: ReadonlyMap<string, Set<string>>;
+    readonly workspaceByPackage: ReadonlyMap<string, Set<string>>;
+};
+
+/**
+ * VersionAlignmentAnalyzer - Checks for consistent dependency versions across workspace.
+ *
+ * Detects issues such as:
+ * - Different versions of the same dependency across packages
+ * - Workspace packages with mismatched versions
+ * - Invalid workspace: protocol references
+ */
+
+/**
+ * Configuration options specific to VersionAlignmentAnalyzer.
+ */
+interface VersionAlignmentAnalyzerOptions {
+    /** Whether to check for misaligned external dependency versions */
+    readonly checkExternalVersions?: boolean;
+    /** Whether to check workspace protocol references */
+    readonly checkWorkspaceProtocol?: boolean;
+    /** Dependencies to ignore in version alignment checks */
+    readonly ignoreDependencies?: readonly string[];
+    /** Package names exempt from checks */
+    readonly exemptPackages?: readonly string[];
+}
+declare const METADATA: AnalyzerMetadata;
+/**
+ * Creates a VersionAlignmentAnalyzer instance.
+ */
+declare function createVersionAlignmentAnalyzer(options?: VersionAlignmentAnalyzerOptions): Analyzer;
+
+/**
+ * Analyzer registry and exports for workspace analysis.
+ *
+ * Provides a plugin architecture for registering and managing analyzers,
+ * with built-in analyzers for configuration validation and dependency analysis.
+ */
+
+/**
+ * Registry for managing analyzer registrations.
+ */
+interface AnalyzerRegistry {
+    /** Register an analyzer */
+    readonly register: (id: string, registration: AnalyzerRegistration) => void;
+    /** Unregister an analyzer */
+    readonly unregister: (id: string) => boolean;
+    /** Get a registered analyzer */
+    readonly get: (id: string) => AnalyzerRegistration | undefined;
+    /** Get all registered analyzers */
+    readonly getAll: () => Map<string, AnalyzerRegistration>;
+    /** Get enabled analyzers sorted by priority */
+    readonly getEnabled: () => Analyzer[];
+    /** Check if an analyzer is registered */
+    readonly has: (id: string) => boolean;
+}
+/**
+ * Creates a new analyzer registry.
+ *
+ * @example
+ * ```ts
+ * const registry = createAnalyzerRegistry()
+ *
+ * // Register a custom analyzer
+ * registry.register('my-analyzer', {
+ *   analyzer: createMyAnalyzer(),
+ *   enabled: true,
+ *   priority: 50,
+ * })
+ *
+ * // Get all enabled analyzers
+ * const analyzers = registry.getEnabled()
+ * ```
+ */
+declare function createAnalyzerRegistry(): AnalyzerRegistry;
+/**
+ * Built-in analyzer IDs.
+ */
+declare const BUILTIN_ANALYZER_IDS: {
+    readonly PACKAGE_JSON: "package-json";
+    readonly TSCONFIG: "tsconfig";
+    readonly ESLINT_CONFIG: "eslint-config";
+    readonly BUILD_CONFIG: "build-config";
+    readonly CONFIG_CONSISTENCY: "config-consistency";
+    readonly VERSION_ALIGNMENT: "version-alignment";
+    readonly EXPORTS_FIELD: "exports-field";
+    readonly UNUSED_DEPENDENCY: "unused-dependency";
+    readonly CIRCULAR_IMPORT: "circular-import";
+    readonly PEER_DEPENDENCY: "peer-dependency";
+    readonly DUPLICATE_DEPENDENCY: "duplicate-dependency";
+    readonly ARCHITECTURAL: "architectural";
+    readonly DEAD_CODE: "dead-code";
+    readonly DUPLICATE_CODE: "duplicate-code";
+    readonly LARGE_DEPENDENCY: "large-dependency";
+    readonly TREE_SHAKING_BLOCKER: "tree-shaking-blocker";
+};
+/**
+ * Creates a registry with all built-in analyzers registered.
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry()
+ *
+ * // Disable a specific analyzer
+ * const registration = registry.get('eslint-config')
+ * if (registration) {
+ *   registry.register('eslint-config', {...registration, enabled: false})
+ * }
+ *
+ * // Run enabled analyzers
+ * const analyzers = registry.getEnabled()
+ * ```
+ */
+declare function createDefaultRegistry(): AnalyzerRegistry;
+/**
+ * All built-in analyzer factories for direct use.
+ */
+declare const builtinAnalyzers: {
+    readonly packageJson: typeof createPackageJsonAnalyzer;
+    readonly tsconfig: typeof createTsconfigAnalyzer;
+    readonly eslintConfig: typeof createEslintConfigAnalyzer;
+    readonly buildConfig: typeof createBuildConfigAnalyzer;
+    readonly configConsistency: typeof createConfigConsistencyAnalyzer;
+    readonly versionAlignment: typeof createVersionAlignmentAnalyzer;
+    readonly exportsField: typeof createExportsFieldAnalyzer;
+    readonly unusedDependency: typeof createUnusedDependencyAnalyzer;
+    readonly circularImport: typeof createCircularImportAnalyzer;
+    readonly peerDependency: typeof createPeerDependencyAnalyzer;
+    readonly duplicateDependency: typeof createDuplicateDependencyAnalyzer;
+    readonly architectural: typeof createArchitecturalAnalyzer;
+    readonly deadCode: typeof createDeadCodeAnalyzer;
+    readonly duplicateCode: typeof createDuplicateCodeAnalyzer;
+    readonly largeDependency: typeof createLargeDependencyAnalyzer;
+    readonly treeShakingBlocker: typeof createTreeShakingBlockerAnalyzer;
+};
+
+/**
+ * Main public API for workspace analysis.
+ *
+ * Provides the `analyzeWorkspace()` function as the primary entry point
+ * for programmatic workspace analysis.
+ */
+
+/**
+ * Options for the analyzeWorkspace function.
+ */
+interface AnalyzeWorkspaceOptions {
+    /** Glob patterns for files to include */
+    readonly include?: readonly string[];
+    /** Glob patterns for files to exclude */
+    readonly exclude?: readonly string[];
+    /** Minimum severity level to report */
+    readonly minSeverity?: 'info' | 'warning' | 'error' | 'critical';
+    /** Categories of issues to check (empty means all) */
+    readonly categories?: readonly ('configuration' | 'dependency' | 'architecture' | 'performance' | 'circular-import' | 'unused-export' | 'type-safety')[];
+    /** Enable incremental analysis caching */
+    readonly cache?: boolean;
+    /** Custom rules configuration */
+    readonly rules?: Record<string, unknown>;
+    /** Glob patterns for package locations */
+    readonly packagePatterns?: readonly string[];
+    /** Maximum parallel analysis operations */
+    readonly concurrency?: number;
+    /** Directory for analysis cache files */
+    readonly cacheDir?: string;
+    /** Maximum cache age in milliseconds */
+    readonly maxCacheAge?: number;
+    /** Hash algorithm for file content */
+    readonly hashAlgorithm?: 'sha256' | 'md5';
+    /** Path to workspace-analyzer.config.ts file */
+    readonly configPath?: string;
+    /** Callback for progress reporting */
+    readonly onProgress?: (progress: AnalysisProgress) => void;
+    /** Per-analyzer configuration */
+    readonly analyzers?: Record<string, {
+        enabled?: boolean;
+        severity?: 'info' | 'warning' | 'error' | 'critical';
+        options?: Record<string, unknown>;
+    }>;
+    /** Architectural analysis rules */
+    readonly architecture?: {
+        layers?: {
+            name: string;
+            patterns: string[];
+            allowedImports: string[];
+        }[];
+        allowBarrelExports?: boolean | string[];
+        enforcePublicApi?: boolean;
+    };
+    /** Enable verbose logging */
+    readonly verbose?: boolean;
+}
+/**
+ * Error codes for workspace analysis.
+ */
+type AnalyzeWorkspaceErrorCode = 'CONFIG_ERROR' | 'SCAN_ERROR' | 'ANALYSIS_ERROR' | 'INVALID_PATH';
+/**
+ * Error that occurred during workspace analysis.
+ */
+interface AnalyzeWorkspaceError {
+    readonly code: AnalyzeWorkspaceErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+/**
+ * Analyzes a workspace for configuration, dependency, and architectural issues.
+ *
+ * This is the main entry point for programmatic workspace analysis.
+ *
+ * @param workspacePath - Path to the workspace root directory
+ * @param options - Analysis options
+ * @returns Result containing analysis results or an error
+ *
+ * @example
+ * ```ts
+ * import {analyzeWorkspace} from '@bfra.me/workspace-analyzer'
+ *
+ * const result = await analyzeWorkspace('./my-monorepo', {
+ *   minSeverity: 'warning',
+ *   categories: ['dependency', 'architecture'],
+ *   onProgress: (progress) => {
+ *     console.log(`${progress.phase}: ${progress.processed}/${progress.total}`)
+ *   },
+ * })
+ *
+ * if (result.success) {
+ *   console.log(`Found ${result.data.summary.totalIssues} issues`)
+ *   for (const issue of result.data.issues) {
+ *     console.log(`[${issue.severity}] ${issue.title}`)
+ *   }
+ * } else {
+ *   console.error(`Analysis failed: ${result.error.message}`)
+ * }
+ * ```
+ */
+declare function analyzeWorkspace(workspacePath: string, options?: AnalyzeWorkspaceOptions): Promise<Result<AnalysisResult, AnalyzeWorkspaceError>>;
+/**
+ * Analyzes specific packages within a workspace.
+ *
+ * @param workspacePath - Path to the workspace root directory
+ * @param packageNames - Names of packages to analyze
+ * @param options - Analysis options
+ * @returns Result containing analysis results or an error
+ *
+ * @example
+ * ```ts
+ * import {analyzePackages} from '@bfra.me/workspace-analyzer'
+ *
+ * const result = await analyzePackages('./my-monorepo', ['@myorg/core', '@myorg/utils'])
+ *
+ * if (result.success) {
+ *   console.log(`Analyzed ${result.data.summary.packagesAnalyzed} packages`)
+ * }
+ * ```
+ */
+declare function analyzePackages(workspacePath: string, packageNames: readonly string[], options?: AnalyzeWorkspaceOptions): Promise<Result<AnalysisResult, AnalyzeWorkspaceError>>;
+
+/**
+ * Cache schema types for workspace analyzer incremental analysis.
+ *
+ * These types define the structure for storing and retrieving analysis results
+ * to enable efficient incremental analysis on large codebases.
+ */
+
+/**
+ * Schema version for cache format migration.
+ * Increment when making breaking changes to cache structure.
+ */
+declare const CACHE_SCHEMA_VERSION = 1;
+/**
+ * Metadata about a cached file's state at analysis time.
+ */
+interface CachedFileState {
+    /** Absolute file path */
+    readonly path: string;
+    /** Content hash (SHA-256) at time of analysis */
+    readonly contentHash: string;
+    /** File modification timestamp (ISO 8601) */
+    readonly modifiedAt: string;
+    /** File size in bytes */
+    readonly size: number;
+}
+/**
+ * Metadata about a cached analysis run.
+ */
+interface CacheMetadata {
+    /** Cache schema version for migration support */
+    readonly version: number;
+    /** Workspace root path that was analyzed */
+    readonly workspacePath: string;
+    /** Timestamp when the cache was created (ISO 8601) */
+    readonly createdAt: string;
+    /** Timestamp when the cache was last updated (ISO 8601) */
+    readonly updatedAt: string;
+    /** Hash of the analyzer configuration */
+    readonly configHash: string;
+    /** Workspace analyzer package version */
+    readonly analyzerVersion: string;
+}
+/**
+ * A cached analysis result for a single file.
+ */
+interface CachedFileAnalysis {
+    /** File state at time of analysis */
+    readonly fileState: CachedFileState;
+    /** Issues found in this file */
+    readonly issues: readonly Issue[];
+    /** Analyzer IDs that processed this file */
+    readonly analyzersRun: readonly string[];
+    /** Analysis timestamp (ISO 8601) */
+    readonly analyzedAt: string;
+}
+/**
+ * A cached package-level analysis result.
+ */
+interface CachedPackageAnalysis {
+    /** Package name */
+    readonly packageName: string;
+    /** Package path relative to workspace root */
+    readonly packagePath: string;
+    /** Hash of package.json content */
+    readonly packageJsonHash: string;
+    /** Issues found at the package level */
+    readonly issues: readonly Issue[];
+    /** Analyzer IDs that processed this package */
+    readonly analyzersRun: readonly string[];
+    /** Analysis timestamp (ISO 8601) */
+    readonly analyzedAt: string;
+}
+/**
+ * Complete analysis cache for a workspace.
+ */
+interface AnalysisCache {
+    /** Cache metadata */
+    readonly metadata: CacheMetadata;
+    /** Per-file analysis results indexed by file path */
+    readonly files: Readonly<Record<string, CachedFileAnalysis>>;
+    /** Per-package analysis results indexed by package name */
+    readonly packages: Readonly<Record<string, CachedPackageAnalysis>>;
+    /** Workspace-level issues not tied to specific files */
+    readonly workspaceIssues: readonly Issue[];
+    /** Configuration files state for invalidation detection */
+    readonly configFiles: readonly CachedFileState[];
+}
+/**
+ * Result of cache validation check.
+ */
+interface CacheValidationResult {
+    /** Whether the cache is valid and can be used */
+    readonly isValid: boolean;
+    /** Files that have changed since last analysis */
+    readonly changedFiles: readonly string[];
+    /** Files that are new since last analysis */
+    readonly newFiles: readonly string[];
+    /** Files that were deleted since last analysis */
+    readonly deletedFiles: readonly string[];
+    /** Packages that need re-analysis */
+    readonly invalidatedPackages: readonly string[];
+    /** Configuration files that changed (triggers full invalidation) */
+    readonly changedConfigFiles: readonly string[];
+    /** Reason for invalidation if not valid */
+    readonly invalidationReason?: string;
+}
+/**
+ * Options for cache operations.
+ */
+interface CacheOptions {
+    /** Directory path for cache storage (default: .workspace-analyzer-cache) */
+    readonly cacheDir?: string;
+    /** Maximum cache age in milliseconds (default: 7 days) */
+    readonly maxAge?: number;
+    /** Whether to compress cache files (default: true) */
+    readonly compress?: boolean;
+    /** Hash algorithm for file content (default: sha256) */
+    readonly hashAlgorithm?: 'sha256' | 'md5';
+}
+/**
+ * Statistics about cache usage.
+ */
+interface CacheStatistics {
+    /** Number of cached files */
+    readonly cachedFiles: number;
+    /** Number of cached packages */
+    readonly cachedPackages: number;
+    /** Total cache size in bytes */
+    readonly totalSizeBytes: number;
+    /** Cache age in milliseconds */
+    readonly ageMs: number;
+    /** Number of cache hits during last analysis */
+    readonly hitCount: number;
+    /** Number of cache misses during last analysis */
+    readonly missCount: number;
+    /** Cache hit rate (0-1) */
+    readonly hitRate: number;
+}
+/**
+ * Configuration file patterns for cache invalidation.
+ * Changes to these files trigger re-analysis of affected areas.
+ */
+declare const CONFIG_FILE_PATTERNS: readonly string[];
+/**
+ * Default cache options.
+ */
+declare const DEFAULT_CACHE_OPTIONS: Required<CacheOptions>;
+/**
+ * Creates an empty analysis cache with default metadata.
+ */
+declare function createEmptyCache(workspacePath: string, configHash: string, analyzerVersion: string): AnalysisCache;
+/**
+ * Creates a cache entry for a file analysis result.
+ */
+declare function createFileAnalysisEntry(path: string, contentHash: string, modifiedAt: Date, size: number, issues: readonly Issue[], analyzersRun: readonly string[]): CachedFileAnalysis;
+/**
+ * Creates a cache entry for a package analysis result.
+ */
+declare function createPackageAnalysisEntry(packageName: string, packagePath: string, packageJsonHash: string, issues: readonly Issue[], analyzersRun: readonly string[]): CachedPackageAnalysis;
+
+/**
+ * Cache manager for workspace analysis results.
+ *
+ * Provides file-based storage for analysis caches with incremental updates,
+ * compression support, and automatic invalidation.
+ */
+
+/**
+ * Error codes for cache operations.
+ */
+type CacheErrorCode = 'CACHE_NOT_FOUND' | 'CACHE_CORRUPTED' | 'CACHE_EXPIRED' | 'CACHE_VERSION_MISMATCH' | 'CACHE_WRITE_FAILED' | 'CACHE_READ_FAILED' | 'CACHE_INVALID';
+/**
+ * Error for cache operations.
+ */
+interface CacheError {
+    readonly code: CacheErrorCode;
+    readonly message: string;
+    readonly cause?: Error;
+}
+/**
+ * Cache manager for workspace analysis.
+ */
+interface CacheManager {
+    /** Load cache from disk */
+    readonly load: () => Promise<Result<AnalysisCache, CacheError>>;
+    /** Save cache to disk */
+    readonly save: (cache: AnalysisCache) => Promise<Result<void, CacheError>>;
+    /** Validate cache against current workspace state */
+    readonly validate: (cache: AnalysisCache, currentFiles: readonly string[]) => Promise<CacheValidationResult>;
+    /** Update cache with new file analysis */
+    readonly updateFile: (cache: AnalysisCache, path: string, issues: readonly Issue[], analyzersRun: readonly string[]) => Promise<Result<AnalysisCache, CacheError>>;
+    /** Update cache with new package analysis */
+    readonly updatePackage: (cache: AnalysisCache, packageName: string, packagePath: string, issues: readonly Issue[], analyzersRun: readonly string[]) => Promise<Result<AnalysisCache, CacheError>>;
+    /** Clear all cache files */
+    readonly clear: () => Promise<Result<void, CacheError>>;
+    /** Get cache statistics */
+    readonly getStatistics: (cache: AnalysisCache) => CacheStatistics;
+    /** Check if cache is valid without full validation */
+    readonly quickValidate: (cache: AnalysisCache, configHash: string) => boolean;
+}
+/**
+ * Options for creating a cache manager.
+ */
+interface CacheManagerOptions extends CacheOptions {
+    /** Workspace root path */
+    readonly workspacePath: string;
+    /** Current analyzer version */
+    readonly analyzerVersion: string;
+}
+/**
+ * Creates a cache manager for workspace analysis.
+ *
+ * @param options - Cache manager configuration
+ * @returns A CacheManager instance
+ *
+ * @example
+ * ```ts
+ * const manager = createCacheManager({
+ *   workspacePath: '/path/to/workspace',
+ *   analyzerVersion: '1.0.0',
+ * })
+ *
+ * const result = await manager.load()
+ * if (isOk(result)) {
+ *   const validation = await manager.validate(result.data, currentFiles)
+ *   if (!validation.isValid) {
+ *     // Re-analyze changed files
+ *   }
+ * }
+ * ```
+ */
+declare function createCacheManager(options: CacheManagerOptions): CacheManager;
+/**
+ * Creates an empty cache for a workspace.
+ *
+ * @param workspacePath - Workspace root path
+ * @param configHash - Hash of the current configuration
+ * @param analyzerVersion - Current analyzer version
+ * @returns A new empty AnalysisCache
+ */
+declare function initializeCache(workspacePath: string, configHash: string, analyzerVersion: string): AnalysisCache;
+/**
+ * Collects configuration file states for cache invalidation tracking.
+ *
+ * @param workspacePath - Workspace root path
+ * @param packagePaths - Package directory paths (relative to workspace)
+ * @returns Array of configuration file states
+ */
+declare function collectConfigFileStates(workspacePath: string, packagePaths: readonly string[]): Promise<CachedFileState[]>;
+
+/**
+ * Change detector for incremental analysis.
+ *
+ * Re-exports from @bfra.me/es/watcher with workspace-analyzer-specific utilities.
+ */
+
+/**
+ * Options for creating an analysis change detector.
+ */
+interface AnalysisChangeDetectorOptions extends ChangeDetectorOptions {
+    /** Configuration file patterns to monitor for invalidation */
+    readonly configFilePatterns?: readonly string[];
+}
+/**
+ * Extended change detector for workspace analysis.
+ */
+interface AnalysisChangeDetector extends ChangeDetector {
+    /** Validate cache against current file states */
+    readonly validateCache: (cachedFiles: readonly CachedFileState[], currentFiles: readonly string[]) => Promise<CacheValidationResult>;
+    /** Get all recorded file paths */
+    readonly getRecordedPaths: () => readonly string[];
+    /** Check if configuration files have changed */
+    readonly hasConfigChanged: (configFiles: readonly CachedFileState[]) => Promise<boolean>;
+}
+/**
+ * Creates an extended change detector for workspace analysis.
+ *
+ * @param options - Change detector configuration options
+ * @returns An AnalysisChangeDetector instance
+ *
+ * @example
+ * ```ts
+ * const detector = createAnalysisChangeDetector()
+ *
+ * // Record initial file state
+ * await detector.record('src/index.ts')
+ *
+ * // Later, validate cache
+ * const validation = await detector.validateCache(
+ *   cachedFileStates,
+ *   currentFilePaths
+ * )
+ *
+ * if (!validation.isValid) {
+ *   console.log('Cache invalid:', validation.invalidationReason)
+ * }
+ * ```
+ */
+declare function createAnalysisChangeDetector(options?: AnalysisChangeDetectorOptions): AnalysisChangeDetector;
+
+/**
+ * File hasher for cache invalidation and change detection.
+ *
+ * Re-exports from @bfra.me/es/watcher with workspace-analyzer-specific utilities.
+ */
+
+/**
+ * Options for creating a workspace file hasher.
+ */
+interface WorkspaceHasherOptions {
+    /** Hash algorithm to use (default: sha256) */
+    readonly algorithm?: 'sha256' | 'md5';
+    /** Whether to normalize line endings before hashing (default: true) */
+    readonly normalizeLineEndings?: boolean;
+}
+/**
+ * Extended file hasher with workspace-specific utilities.
+ */
+interface WorkspaceFileHasher extends FileHasher {
+    /** Hash a JSON object consistently (keys sorted) */
+    readonly hashJson: (obj: unknown) => string;
+    /** Hash multiple files and return combined hash */
+    readonly hashFiles: (paths: readonly string[]) => Promise<string>;
+}
+/**
+ * Creates an extended file hasher with workspace-specific utilities.
+ *
+ * @param options - Hasher configuration options
+ * @returns A WorkspaceFileHasher instance
+ *
+ * @example
+ * ```ts
+ * const hasher = createWorkspaceHasher()
+ * const configHash = hasher.hashJson(analyzerConfig)
+ * const filesHash = await hasher.hashFiles(['package.json', 'tsconfig.json'])
+ * ```
+ */
+declare function createWorkspaceHasher(options?: WorkspaceHasherOptions): WorkspaceFileHasher;
+
+/**
+ * Default configuration values for workspace analyzer.
+ *
+ * Provides sensible defaults that work well for typical TypeScript monorepo projects,
+ * with all options explicitly documented and type-safe.
+ */
+
+/**
+ * Default glob patterns for including source files in analysis.
+ */
+declare const DEFAULT_INCLUDE_PATTERNS: readonly string[];
+/**
+ * Default glob patterns for excluding files from analysis.
+ */
+declare const DEFAULT_EXCLUDE_PATTERNS: readonly string[];
+/**
+ * Default package location patterns for monorepo scanning.
+ */
+declare const DEFAULT_PACKAGE_PATTERNS: readonly string[];
+/**
+ * Default concurrency limit for parallel analysis.
+ */
+declare const DEFAULT_CONCURRENCY = 4;
+/**
+ * Complete default analyzer configuration.
+ */
+interface DefaultAnalyzerConfig {
+    /** Glob patterns for files to include */
+    readonly include: readonly string[];
+    /** Glob patterns for files to exclude */
+    readonly exclude: readonly string[];
+    /** Minimum severity level to report */
+    readonly minSeverity: Severity;
+    /** Categories of issues to check (empty means all) */
+    readonly categories: readonly IssueCategory[];
+    /** Whether to enable caching */
+    readonly cache: boolean;
+    /** Custom rules configuration */
+    readonly rules: Readonly<Record<string, unknown>>;
+}
+/**
+ * Default analyzer configuration values.
+ */
+declare const DEFAULT_ANALYZER_CONFIG: DefaultAnalyzerConfig;
+/**
+ * Default workspace analyzer options.
+ */
+interface DefaultWorkspaceOptions {
+    /** Glob patterns for package locations */
+    readonly packagePatterns: readonly string[];
+    /** Maximum parallel analysis operations */
+    readonly concurrency: number;
+    /** Cache directory path */
+    readonly cacheDir: string;
+    /** Maximum cache age in milliseconds */
+    readonly maxCacheAge: number;
+    /** Hash algorithm for file content */
+    readonly hashAlgorithm: 'sha256' | 'md5';
+}
+/**
+ * Default workspace analyzer options values.
+ */
+declare const DEFAULT_WORKSPACE_OPTIONS: DefaultWorkspaceOptions;
+/**
+ * Complete default configuration combining analyzer and workspace options.
+ */
+interface DefaultConfig extends DefaultAnalyzerConfig, DefaultWorkspaceOptions {
+    /** Configuration file path (optional) */
+    readonly configPath?: string;
+}
+/**
+ * Get the complete default configuration.
+ */
+declare function getDefaultConfig(): DefaultConfig;
+
+/**
+ * Zod schemas for configuration validation.
+ *
+ * Provides runtime validation for workspace analyzer configuration,
+ * ensuring type safety and helpful error messages for invalid configs.
+ */
+
+/**
+ * Complete workspace analyzer configuration schema.
+ */
+declare const workspaceAnalyzerConfigSchema: z.ZodObject<{
+    analyzers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        severity: z.ZodOptional<z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+            critical: "critical";
+        }>>;
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>>;
+    architecture: z.ZodOptional<z.ZodObject<{
+        layers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            patterns: z.ZodArray<z.ZodString>;
+            allowedImports: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+        allowBarrelExports: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+        enforcePublicApi: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    packagePatterns: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    concurrency: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    cacheDir: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    maxCacheAge: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    hashAlgorithm: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        sha256: "sha256";
+        md5: "md5";
+    }>>>;
+    include: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    exclude: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    minSeverity: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        info: "info";
+        warning: "warning";
+        error: "error";
+        critical: "critical";
+    }>>>;
+    categories: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        configuration: "configuration";
+        dependency: "dependency";
+        architecture: "architecture";
+        performance: "performance";
+        "circular-import": "circular-import";
+        "unused-export": "unused-export";
+        "type-safety": "type-safety";
+    }>>>>;
+    cache: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    rules: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+/**
+ * Schema for the analyzeWorkspace() options parameter.
+ */
+declare const analyzeWorkspaceOptionsSchema: z.ZodObject<{
+    configPath: z.ZodOptional<z.ZodString>;
+    analyzers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        severity: z.ZodOptional<z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+            critical: "critical";
+        }>>;
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>>;
+    architecture: z.ZodOptional<z.ZodObject<{
+        layers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            patterns: z.ZodArray<z.ZodString>;
+            allowedImports: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+        allowBarrelExports: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+        enforcePublicApi: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    packagePatterns: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    concurrency: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    cacheDir: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    maxCacheAge: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    hashAlgorithm: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        sha256: "sha256";
+        md5: "md5";
+    }>>>;
+    include: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    exclude: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    minSeverity: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        info: "info";
+        warning: "warning";
+        error: "error";
+        critical: "critical";
+    }>>>;
+    categories: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        configuration: "configuration";
+        dependency: "dependency";
+        architecture: "architecture";
+        performance: "performance";
+        "circular-import": "circular-import";
+        "unused-export": "unused-export";
+        "type-safety": "type-safety";
+    }>>>>;
+    cache: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    rules: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+type WorkspaceAnalyzerConfigOutput = z.output<typeof workspaceAnalyzerConfigSchema>;
+type AnalyzeWorkspaceOptionsOutput = z.output<typeof analyzeWorkspaceOptionsSchema>;
+/**
+ * Validates and parses workspace analyzer configuration.
+ *
+ * @param config - Raw configuration input
+ * @returns Validated and defaulted configuration
+ * @throws {z.ZodError} If validation fails
+ */
+declare function parseWorkspaceAnalyzerConfig(config: unknown): WorkspaceAnalyzerConfigOutput;
+/**
+ * Safe parse result type for configuration validation.
+ */
+type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Validates analyzeWorkspace() options.
+ *
+ * @param options - Raw options input
+ * @returns Validation result with success status and data/error
+ */
+declare function safeParseAnalyzeOptions(options: unknown): SafeParseResult<AnalyzeWorkspaceOptionsOutput>;
+
+/**
+ * Configuration file loader for workspace-analyzer.config.ts files.
+ *
+ * Provides functionality to discover, load, and parse TypeScript configuration files
+ * using the defineConfig() pattern similar to other tools in the ecosystem.
+ */
+
+/**
+ * Error codes for configuration loading operations.
+ */
+type ConfigLoadErrorCode = 'FILE_NOT_FOUND' | 'IMPORT_ERROR' | 'VALIDATION_ERROR' | 'INVALID_EXPORT';
+/**
+ * Error that occurred during configuration loading.
+ */
+interface ConfigLoadError {
+    readonly code: ConfigLoadErrorCode;
+    readonly message: string;
+    readonly filePath?: string;
+    readonly cause?: unknown;
+}
+/**
+ * Result of loading a configuration file.
+ */
+interface ConfigLoadResult {
+    /** Loaded and validated configuration */
+    readonly config: WorkspaceAnalyzerConfigOutput;
+    /** Path to the loaded configuration file */
+    readonly filePath: string;
+}
+/**
+ * User-facing configuration interface for defineConfig().
+ * Allows partial configuration that will be merged with defaults.
+ */
+interface WorkspaceAnalyzerConfig {
+    /** Glob patterns for files to include */
+    include?: readonly string[];
+    /** Glob patterns for files to exclude */
+    exclude?: readonly string[];
+    /** Minimum severity level to report */
+    minSeverity?: 'info' | 'warning' | 'error' | 'critical';
+    /** Categories of issues to check (empty means all) */
+    categories?: readonly ('configuration' | 'dependency' | 'architecture' | 'performance' | 'circular-import' | 'unused-export' | 'type-safety')[];
+    /** Enable incremental analysis caching */
+    cache?: boolean;
+    /** Custom rules configuration */
+    rules?: Record<string, unknown>;
+    /** Glob patterns for package locations */
+    packagePatterns?: readonly string[];
+    /** Maximum parallel analysis operations */
+    concurrency?: number;
+    /** Directory for analysis cache files */
+    cacheDir?: string;
+    /** Maximum cache age in milliseconds */
+    maxCacheAge?: number;
+    /** Hash algorithm for file content */
+    hashAlgorithm?: 'sha256' | 'md5';
+    /** Per-analyzer configuration */
+    analyzers?: Record<string, {
+        enabled?: boolean;
+        severity?: 'info' | 'warning' | 'error' | 'critical';
+        options?: Record<string, unknown>;
+    }>;
+    /** Architectural analysis rules */
+    architecture?: {
+        layers?: {
+            name: string;
+            patterns: string[];
+            allowedImports: string[];
+        }[];
+        allowBarrelExports?: boolean | string[];
+        enforcePublicApi?: boolean;
+    };
+}
+/**
+ * Helper function for defining configuration with type safety.
+ *
+ * @example
+ * ```ts
+ * // workspace-analyzer.config.ts
+ * import {defineConfig} from '@bfra.me/workspace-analyzer'
+ *
+ * export default defineConfig({
+ *   minSeverity: 'warning',
+ *   categories: ['dependency', 'architecture'],
+ *   analyzers: {
+ *     'circular-import': {enabled: true},
+ *     'unused-dependency': {enabled: true},
+ *   },
+ * })
+ * ```
+ */
+declare function defineConfig(config: WorkspaceAnalyzerConfig): WorkspaceAnalyzerConfig;
+/**
+ * Finds a configuration file in the given directory or its parents.
+ *
+ * @param startDir - Directory to start searching from
+ * @param stopAt - Directory to stop searching at (defaults to filesystem root)
+ * @returns Path to the found configuration file, or undefined if not found
+ */
+declare function findConfigFile(startDir: string, stopAt?: string): Promise<string | undefined>;
+/**
+ * Loads and validates a configuration file.
+ *
+ * @param filePath - Path to the configuration file
+ * @returns Result containing the loaded config or an error
+ */
+declare function loadConfigFile(filePath: string): Promise<Result<ConfigLoadResult, ConfigLoadError>>;
+/**
+ * Discovers and loads configuration from the workspace.
+ *
+ * @param workspacePath - Root path of the workspace
+ * @param explicitPath - Optional explicit path to config file
+ * @returns Result containing the loaded config or an error
+ */
+declare function loadConfig(workspacePath: string, explicitPath?: string): Promise<Result<ConfigLoadResult | undefined, ConfigLoadError>>;
+
+/**
+ * Configuration merging utilities for workspace analyzer.
+ *
+ * Provides deep merging of configuration sources with proper precedence:
+ * programmatic options > config file > defaults
+ */
+
+/**
+ * Complete configuration after merging all sources.
+ */
+interface MergedConfig {
+    /** Glob patterns for files to include */
+    readonly include: readonly string[];
+    /** Glob patterns for files to exclude */
+    readonly exclude: readonly string[];
+    /** Minimum severity level to report */
+    readonly minSeverity: 'info' | 'warning' | 'error' | 'critical';
+    /** Categories of issues to check (empty means all) */
+    readonly categories: readonly ('configuration' | 'dependency' | 'architecture' | 'performance' | 'circular-import' | 'unused-export' | 'type-safety')[];
+    /** Enable incremental analysis caching */
+    readonly cache: boolean;
+    /** Custom rules configuration */
+    readonly rules: Readonly<Record<string, unknown>>;
+    /** Glob patterns for package locations */
+    readonly packagePatterns: readonly string[];
+    /** Maximum parallel analysis operations */
+    readonly concurrency: number;
+    /** Directory for analysis cache files */
+    readonly cacheDir: string;
+    /** Maximum cache age in milliseconds */
+    readonly maxCacheAge: number;
+    /** Hash algorithm for file content */
+    readonly hashAlgorithm: 'sha256' | 'md5';
+    /** Per-analyzer configuration */
+    readonly analyzers: Readonly<Record<string, {
+        readonly enabled?: boolean;
+        readonly severity?: 'info' | 'warning' | 'error' | 'critical';
+        readonly options?: Readonly<Record<string, unknown>>;
+    }>>;
+    /** Architectural analysis rules */
+    readonly architecture?: {
+        readonly layers?: readonly {
+            readonly name: string;
+            readonly patterns: readonly string[];
+            readonly allowedImports: readonly string[];
+        }[];
+        readonly allowBarrelExports?: boolean | readonly string[];
+        readonly enforcePublicApi?: boolean;
+    };
+}
+/**
+ * Merges analyzer-specific configurations.
+ *
+ * @param baseAnalyzers - Base analyzer config from file
+ * @param overrideAnalyzers - Override config from programmatic options
+ * @returns Merged analyzer configurations
+ */
+declare function mergeAnalyzerConfigs(baseAnalyzers: MergedConfig['analyzers'], overrideAnalyzers?: WorkspaceAnalyzerConfig['analyzers']): MergedConfig['analyzers'];
+/**
+ * Merges configuration from multiple sources.
+ *
+ * Precedence (highest to lowest):
+ * 1. Programmatic options passed to analyzeWorkspace()
+ * 2. Configuration file (workspace-analyzer.config.ts)
+ * 3. Default values
+ *
+ * @param fileConfig - Configuration loaded from file (optional)
+ * @param programmaticOptions - Options passed programmatically (optional)
+ * @returns Fully merged configuration with all defaults applied
+ */
+declare function mergeConfig(fileConfig?: WorkspaceAnalyzerConfigOutput, programmaticOptions?: WorkspaceAnalyzerConfig): MergedConfig;
+/**
+ * Creates analyzer options from merged configuration for a specific analyzer.
+ *
+ * @param mergedConfig - The fully merged configuration
+ * @param analyzerId - The ID of the analyzer to get options for
+ * @returns Options for the specified analyzer
+ */
+declare function getAnalyzerOptions(mergedConfig: MergedConfig, analyzerId: string): {
+    enabled: boolean;
+    minSeverity: MergedConfig['minSeverity'];
+    categories: MergedConfig['categories'];
+    options: Record<string, unknown>;
+};
+
+/**
+ * Incremental analyzer orchestrator for workspace analysis.
+ *
+ * Provides efficient incremental analysis by leveraging file change detection,
+ * cache management, and parallel execution for large codebase performance.
+ */
+
+/**
+ * Options for incremental analysis.
+ */
+interface IncrementalAnalysisOptions {
+    /** Workspace root path */
+    readonly workspacePath: string;
+    /** Current analyzer version (for cache invalidation) */
+    readonly analyzerVersion: string;
+    /** Whether to use caching (default: true) */
+    readonly useCache?: boolean;
+    /** Maximum number of concurrent file analyses (default: 4) */
+    readonly concurrency?: number;
+    /** Maximum cache age in milliseconds (default: 7 days) */
+    readonly maxCacheAge?: number;
+    /** Minimum severity to report (default: 'info') */
+    readonly minSeverity?: Severity;
+    /** Progress callback for reporting */
+    readonly onProgress?: (progress: AnalysisProgress) => void;
+    /** Cache directory (default: .workspace-analyzer-cache) */
+    readonly cacheDir?: string;
+    /** Hash algorithm for file content (default: sha256) */
+    readonly hashAlgorithm?: 'sha256' | 'md5';
+}
+/**
+ * Error codes for incremental analysis.
+ */
+type IncrementalAnalysisErrorCode = 'SCAN_FAILED' | 'ANALYSIS_FAILED' | 'CACHE_ERROR' | 'ANALYZER_ERROR' | 'TIMEOUT';
+/**
+ * Error for incremental analysis operations.
+ */
+interface IncrementalAnalysisError {
+    readonly code: IncrementalAnalysisErrorCode;
+    readonly message: string;
+    readonly cause?: Error;
+}
+/**
+ * Result of incremental analysis.
+ */
+interface IncrementalAnalysisResult {
+    /** All issues found */
+    readonly issues: readonly Issue[];
+    /** Number of files analyzed (not from cache) */
+    readonly filesAnalyzed: number;
+    /** Number of files loaded from cache */
+    readonly filesFromCache: number;
+    /** Number of packages analyzed */
+    readonly packagesAnalyzed: number;
+    /** Analysis duration in milliseconds */
+    readonly durationMs: number;
+    /** Whether cache was used */
+    readonly cacheUsed: boolean;
+    /** Cache statistics after analysis */
+    readonly cacheStats?: {
+        readonly hitRate: number;
+        readonly hitCount: number;
+        readonly missCount: number;
+    };
+}
+/**
+ * Extended analysis context with incremental analysis metadata.
+ */
+interface IncrementalAnalysisContext {
+    /** Workspace root path */
+    readonly workspacePath: string;
+    /** All source files in the workspace */
+    readonly files: readonly string[];
+    /** Package paths (relative to workspace root) */
+    readonly packagePaths: readonly string[];
+    /** Configuration hash for cache invalidation */
+    readonly configHash: string;
+    /** Current cache state (if available) */
+    readonly cache?: AnalysisCache;
+    /** Files that need fresh analysis */
+    readonly filesToAnalyze: readonly string[];
+    /** Files that can use cached results */
+    readonly cachedFiles: readonly string[];
+    /** Progress reporter */
+    readonly reportProgress: (current: string, processed: number, total?: number) => void;
+}
+/**
+ * Incremental analyzer orchestrator.
+ */
+interface IncrementalAnalyzer {
+    /** Run incremental analysis on the workspace */
+    readonly analyze: (files: readonly string[], packages: readonly WorkspacePackage[], analyzers: readonly Analyzer[]) => Promise<Result<IncrementalAnalysisResult, IncrementalAnalysisError>>;
+    /** Invalidate cache for specific files */
+    readonly invalidateFiles: (paths: readonly string[]) => Promise<void>;
+    /** Clear the entire cache */
+    readonly clearCache: () => Promise<Result<void, IncrementalAnalysisError>>;
+    /** Get current cache statistics */
+    readonly getCacheStats: () => Promise<Result<{
+        cachedFiles: number;
+        cachedPackages: number;
+        ageMs: number;
+    }, IncrementalAnalysisError>>;
+}
+/**
+ * Default options for incremental analysis.
+ */
+declare const DEFAULT_INCREMENTAL_OPTIONS: {
+    readonly useCache: true;
+    readonly concurrency: 4;
+    readonly maxCacheAge: number;
+    readonly minSeverity: Severity;
+    readonly cacheDir: ".workspace-analyzer-cache";
+    readonly hashAlgorithm: "sha256";
+};
+/**
+ * Creates an incremental analyzer orchestrator.
+ *
+ * @param options - Incremental analysis configuration
+ * @returns An IncrementalAnalyzer instance
+ *
+ * @example
+ * ```ts
+ * const analyzer = createIncrementalAnalyzer({
+ *   workspacePath: '/path/to/workspace',
+ *   analyzerVersion: '1.0.0',
+ *   onProgress: (progress) => {
+ *     console.error(`${progress.phase}: ${progress.processed}/${progress.total}`)
+ *   },
+ * })
+ *
+ * const result = await analyzer.analyze(files, packages, analyzers)
+ * if (result.success) {
+ *   console.error(`Found ${result.data.issues.length} issues`)
+ * }
+ * ```
+ */
+declare function createIncrementalAnalyzer(options: IncrementalAnalysisOptions): IncrementalAnalyzer;
+/**
+ * Creates a progress callback that logs to stderr.
+ */
+declare function createConsoleProgressCallback(): (progress: AnalysisProgress) => void;
+/**
+ * Creates a no-op progress callback.
+ */
+declare function createSilentProgressCallback(): (progress: AnalysisProgress) => void;
+
+/**
+ * Analysis orchestrator for workspace analysis.
+ *
+ * Adapts the doc-sync sync-orchestrator pattern for workspace analysis,
+ * coordinating scanner, analyzers, and reporters into a unified pipeline.
+ */
+
+/**
+ * Extended analysis context shared between analyzers.
+ * Contains all information needed to perform analysis operations.
+ */
+interface AnalysisContext {
+    /** Root path of the workspace being analyzed */
+    readonly workspacePath: string;
+    /** All packages discovered in the workspace */
+    readonly packages: readonly WorkspacePackage[];
+    /** All source files in the workspace */
+    readonly sourceFiles: readonly string[];
+    /** Merged configuration */
+    readonly config: MergedConfig;
+    /** Configuration hash for caching */
+    readonly configHash: string;
+    /** Report progress during analysis */
+    readonly reportProgress: (message: string) => void;
+}
+/**
+ * Error codes for orchestration operations.
+ */
+type OrchestratorErrorCode = 'SCAN_FAILED' | 'ANALYSIS_FAILED' | 'INVALID_CONFIG' | 'NO_PACKAGES';
+/**
+ * Error that occurred during orchestration.
+ */
+interface OrchestratorError {
+    readonly code: OrchestratorErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+/**
+ * Options for the analysis orchestrator.
+ */
+interface OrchestratorOptions {
+    /** Root path of the workspace to analyze */
+    readonly workspacePath: string;
+    /** Merged configuration */
+    readonly config: MergedConfig;
+    /** Progress callback */
+    readonly onProgress?: (progress: AnalysisProgress) => void;
+    /** Verbose logging */
+    readonly verbose?: boolean;
+}
+/**
+ * Analysis orchestrator interface.
+ */
+interface AnalysisOrchestrator {
+    /** Run full analysis on the workspace */
+    readonly analyzeAll: () => Promise<Result<AnalysisResult, OrchestratorError>>;
+    /** Run analysis on specific packages */
+    readonly analyzePackages: (packageNames: readonly string[]) => Promise<Result<AnalysisResult, OrchestratorError>>;
+    /** Get the current analysis context */
+    readonly getContext: () => Promise<Result<AnalysisContext, OrchestratorError>>;
+}
+/**
+ * Creates an analysis orchestrator for coordinating workspace analysis.
+ *
+ * @example
+ * ```ts
+ * const orchestrator = createOrchestrator({
+ *   config: mergedConfig,
+ *   onProgress: (progress) => console.log(progress.phase),
+ * })
+ *
+ * const result = await orchestrator.analyzeAll()
+ * if (result.success) {
+ *   console.log(`Found ${result.data.summary.totalIssues} issues`)
+ * }
+ * ```
+ */
+declare function createOrchestrator(options: OrchestratorOptions): AnalysisOrchestrator;
+
+/**
+ * Configuration file parser for package.json, tsconfig.json, and other config files.
+ *
+ * Provides utilities for parsing and extracting information from various
+ * configuration files used in TypeScript/JavaScript projects.
+ */
+
+/**
+ * Error codes for configuration parsing.
+ */
+type ConfigErrorCode = 'FILE_NOT_FOUND' | 'INVALID_JSON' | 'INVALID_CONFIG' | 'READ_ERROR';
+/**
+ * Error that occurred during configuration parsing.
+ */
+interface ConfigError {
+    /** Error code for programmatic handling */
+    readonly code: ConfigErrorCode;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Path to the config file */
+    readonly filePath: string;
+    /** Underlying cause */
+    readonly cause?: unknown;
+}
+/**
+ * Parsed package.json structure with relevant fields for analysis.
+ */
+interface ParsedPackageJson {
+    /** Package name */
+    readonly name: string;
+    /** Package version */
+    readonly version: string;
+    /** Package description */
+    readonly description?: string;
+    /** Main entry point */
+    readonly main?: string;
+    /** Module entry point (ESM) */
+    readonly module?: string;
+    /** Types entry point */
+    readonly types?: string;
+    /** Exports map */
+    readonly exports?: Record<string, unknown>;
+    /** Dependencies */
+    readonly dependencies?: Readonly<Record<string, string>>;
+    /** Development dependencies */
+    readonly devDependencies?: Readonly<Record<string, string>>;
+    /** Peer dependencies */
+    readonly peerDependencies?: Readonly<Record<string, string>>;
+    /** Optional dependencies */
+    readonly optionalDependencies?: Readonly<Record<string, string>>;
+    /** Package type (module or commonjs) */
+    readonly type?: 'module' | 'commonjs';
+    /** Scripts */
+    readonly scripts?: Readonly<Record<string, string>>;
+    /** Files to include in package */
+    readonly files?: readonly string[];
+    /** Raw package.json data */
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+/**
+ * Parsed tsconfig.json structure with relevant fields for analysis.
+ */
+interface ParsedTsConfig {
+    /** Extends from another config */
+    readonly extends?: string | readonly string[];
+    /** Compiler options */
+    readonly compilerOptions?: TsCompilerOptions;
+    /** Include patterns */
+    readonly include?: readonly string[];
+    /** Exclude patterns */
+    readonly exclude?: readonly string[];
+    /** Project references */
+    readonly references?: readonly TsProjectReference[];
+    /** File path of the config */
+    readonly filePath: string;
+    /** Raw tsconfig data */
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+/**
+ * TypeScript compiler options subset relevant for analysis.
+ */
+interface TsCompilerOptions {
+    /** Target ECMAScript version */
+    readonly target?: string;
+    /** Module system */
+    readonly module?: string;
+    /** Module resolution strategy */
+    readonly moduleResolution?: string;
+    /** Path mappings */
+    readonly paths?: Readonly<Record<string, readonly string[]>>;
+    /** Base URL for path resolution */
+    readonly baseUrl?: string;
+    /** Root directory */
+    readonly rootDir?: string;
+    /** Output directory */
+    readonly outDir?: string;
+    /** Strict mode */
+    readonly strict?: boolean;
+    /** Declaration files */
+    readonly declaration?: boolean;
+    /** Source maps */
+    readonly sourceMap?: boolean;
+    /** ESM interop */
+    readonly esModuleInterop?: boolean;
+    /** Allow synthetic default imports */
+    readonly allowSyntheticDefaultImports?: boolean;
+    /** Skip library check */
+    readonly skipLibCheck?: boolean;
+    /** Resolve JSON modules */
+    readonly resolveJsonModule?: boolean;
+    /** Isolated modules */
+    readonly isolatedModules?: boolean;
+}
+/**
+ * TypeScript project reference.
+ */
+interface TsProjectReference {
+    /** Path to referenced project */
+    readonly path: string;
+}
+/**
+ * Parses a package.json file.
+ *
+ * @example
+ * ```ts
+ * const result = await parsePackageJson('/path/to/package.json')
+ * if (result.success) {
+ *   console.log(`Package: ${result.data.name}@${result.data.version}`)
+ * }
+ * ```
+ */
+declare function parsePackageJson(packageJsonPath: string): Promise<Result<ParsedPackageJson, ConfigError>>;
+/**
+ * Parses package.json content from a string.
+ */
+declare function parsePackageJsonContent(content: string, filePath: string): Result<ParsedPackageJson, ConfigError>;
+/**
+ * Parses a tsconfig.json file.
+ *
+ * @example
+ * ```ts
+ * const result = await parseTsConfig('/path/to/tsconfig.json')
+ * if (result.success) {
+ *   console.log(`Target: ${result.data.compilerOptions?.target}`)
+ * }
+ * ```
+ */
+declare function parseTsConfig(tsconfigPath: string): Promise<Result<ParsedTsConfig, ConfigError>>;
+/**
+ * Parses tsconfig.json content from a string.
+ *
+ * Note: This does basic JSON parsing. tsconfig.json supports comments
+ * and trailing commas which this parser strips before parsing.
+ */
+declare function parseTsConfigContent(content: string, filePath: string): Result<ParsedTsConfig, ConfigError>;
+/**
+ * Gets all dependencies from a package.json (combined).
+ */
+declare function getAllDependencies(pkg: ParsedPackageJson): Readonly<Record<string, {
+    version: string;
+    type: 'prod' | 'dev' | 'peer' | 'optional';
+}>>;
+/**
+ * Resolves tsconfig extends chain.
+ */
+declare function resolveTsConfigExtends(tsconfigPath: string, maxDepth?: number): Promise<Result<ParsedTsConfig[], ConfigError>>;
+
+/**
+ * TypeScript AST parser utilities for workspace analysis.
+ *
+ * Re-exports core parsing utilities from @bfra.me/doc-sync/parsers and provides
+ * additional workspace-analyzer-specific helpers for multi-file analysis.
+ */
+
+/**
+ * Gets the source file at a path, creating the project if needed.
+ *
+ * Convenience function for one-off file parsing without manually managing a project.
+ */
+declare function getSourceFile(filePath: string, options?: {
+    tsConfigPath?: string;
+    compilerOptions?: Record<string, unknown>;
+}): Result<SourceFile, ParseError>;
+/**
+ * Parses multiple source files into a single project.
+ *
+ * More efficient than parsing files individually when analyzing many files,
+ * as the project can share type resolution and compiler settings.
+ */
+declare function parseSourceFiles(filePaths: readonly string[], options?: {
+    tsConfigPath?: string;
+    compilerOptions?: Record<string, unknown>;
+}): Result<Project, ParseError>;
+/**
+ * Gets all source files from a project.
+ */
+declare function getAllSourceFiles(project: Project): readonly SourceFile[];
+/**
+ * Checks if a file path represents a TypeScript file.
+ */
+declare function isTypeScriptFile(filePath: string): boolean;
+/**
+ * Checks if a file path represents a JavaScript file.
+ */
+declare function isJavaScriptFile(filePath: string): boolean;
+/**
+ * Checks if a file path is a parseable source file (TypeScript or JavaScript).
+ */
+declare function isSourceFile(filePath: string): boolean;
+
+/**
+ * Bundle size estimator for identifying large module contributors.
+ *
+ * Analyzes source files and dependencies to estimate bundle size impact,
+ * helping identify optimization opportunities for tree-shaking and code splitting.
+ *
+ * This is a heuristic estimator - actual bundle sizes depend on bundler configuration,
+ * tree-shaking effectiveness, and minification.
+ */
+
+/**
+ * Estimated size information for a module or package.
+ */
+interface BundleSizeEstimate {
+    /** Source file path or package name */
+    readonly identifier: string;
+    /** Raw source size in bytes (unminified) */
+    readonly sourceSize: number;
+    /** Estimated minified size in bytes (heuristic: ~60% of source) */
+    readonly estimatedMinifiedSize: number;
+    /** Estimated gzipped size in bytes (heuristic: ~30% of minified) */
+    readonly estimatedGzippedSize: number;
+    /** Number of imports this module brings in */
+    readonly importCount: number;
+    /** Number of exports this module provides */
+    readonly exportCount: number;
+    /** Whether this is a direct or transitive dependency */
+    readonly isTransitive: boolean;
+}
+/**
+ * Aggregated bundle size statistics for a package.
+ */
+interface PackageBundleStats {
+    /** Package name */
+    readonly packageName: string;
+    /** Total source size of all modules */
+    readonly totalSourceSize: number;
+    /** Estimated total minified size */
+    readonly totalMinifiedSize: number;
+    /** Estimated total gzipped size */
+    readonly totalGzippedSize: number;
+    /** Number of source files */
+    readonly fileCount: number;
+    /** Individual file estimates */
+    readonly files: readonly BundleSizeEstimate[];
+    /** External dependency size estimates */
+    readonly dependencies: readonly DependencySizeEstimate[];
+    /** Top contributors by size */
+    readonly topContributors: readonly BundleSizeEstimate[];
+}
+/**
+ * Size estimate for an external dependency.
+ */
+interface DependencySizeEstimate {
+    /** Package name */
+    readonly packageName: string;
+    /** Estimated size (if known from registry data) */
+    readonly estimatedSize?: number;
+    /** Whether size data is available */
+    readonly sizeKnown: boolean;
+    /** Number of times imported */
+    readonly importCount: number;
+    /** Import locations */
+    readonly locations: readonly string[];
+}
+/**
+ * Options for bundle size estimation.
+ */
+interface BundleEstimatorOptions {
+    /** Include node_modules size estimates */
+    readonly includeNodeModules?: boolean;
+    /** Maximum files to analyze (for performance) */
+    readonly maxFiles?: number;
+    /** Minification ratio estimate (0-1) */
+    readonly minificationRatio?: number;
+    /** Gzip ratio estimate (0-1) */
+    readonly gzipRatio?: number;
+    /** Size threshold for "large file" warnings (bytes) */
+    readonly largeFileThreshold?: number;
+    /** Size threshold for "large dependency" warnings (bytes) */
+    readonly largeDependencyThreshold?: number;
+}
+/**
+ * Estimates bundle size for source files in a package.
+ */
+declare function estimatePackageBundleSize(pkg: WorkspacePackage, importResults: readonly ImportExtractionResult[], options?: BundleEstimatorOptions): Promise<PackageBundleStats>;
+/**
+ * Estimates the size of a single source file.
+ */
+declare function estimateFileSize(filePath: string, options?: BundleEstimatorOptions): Promise<BundleSizeEstimate | null>;
+/**
+ * Estimates the size contribution of an external dependency.
+ */
+declare function estimateDependencySize(packageName: string): DependencySizeEstimate;
+/**
+ * Identifies files that exceed the large file threshold.
+ */
+declare function findLargeFiles(stats: PackageBundleStats, threshold?: number): readonly BundleSizeEstimate[];
+/**
+ * Identifies dependencies that exceed the large dependency threshold.
+ */
+declare function findLargeDependencies(stats: PackageBundleStats, threshold?: number): readonly DependencySizeEstimate[];
+/**
+ * Calculates the estimated tree-shaking savings for a file.
+ *
+ * Files that only use a subset of exports from large modules
+ * can benefit significantly from tree-shaking.
+ */
+declare function estimateTreeShakingSavings(imports: readonly ExtractedImport[]): TreeShakingSavingsEstimate;
+/**
+ * Estimate of potential tree-shaking savings.
+ */
+interface TreeShakingSavingsEstimate {
+    /** Total potential bytes saved */
+    readonly potentialSavings: number;
+    /** Imports that could be optimized */
+    readonly optimizableImports: readonly OptimizableImport[];
+    /** Whether any optimizations are available */
+    readonly hasPotentialOptimizations: boolean;
+}
+/**
+ * An import that could be optimized for better tree-shaking.
+ */
+interface OptimizableImport {
+    /** The module specifier */
+    readonly moduleSpecifier: string;
+    /** Current import style */
+    readonly currentImportStyle: 'namespace' | 'default' | 'side-effect';
+    /** Suggested import style */
+    readonly suggestedImportStyle: 'named' | 'dynamic';
+    /** Estimated bytes saved */
+    readonly estimatedSavings: number;
+    /** Line number */
+    readonly line: number;
+    /** Column number */
+    readonly column: number;
+}
+/**
+ * Formats a byte size as a human-readable string.
+ */
+declare function formatBytes(bytes: number): string;
+
+/**
+ * Report generator interface and base types for workspace analysis output.
+ *
+ * Defines the contract for reporters that format analysis results into
+ * various output formats (JSON, Markdown, console, etc.).
+ */
+
+/**
+ * Supported output formats for analysis reports.
+ */
+type ReportFormat = 'json' | 'markdown' | 'console';
+/**
+ * Options for configuring report generation.
+ */
+interface ReportOptions {
+    /** Minimum severity level to include in the report */
+    readonly minSeverity?: Severity;
+    /** Categories of issues to include (empty means all) */
+    readonly categories?: readonly IssueCategory[];
+    /** Whether to include file location details (line/column numbers) */
+    readonly includeLocation?: boolean;
+    /** Whether to include fix suggestions */
+    readonly includeSuggestions?: boolean;
+    /** Whether to group issues by file, category, or severity */
+    readonly groupBy?: 'file' | 'category' | 'severity' | 'none';
+    /** Whether to include summary statistics */
+    readonly includeSummary?: boolean;
+    /** Output file path (if writing to file) */
+    readonly outputPath?: string;
+    /** Whether to use colors in output (for console reporter) */
+    readonly colors?: boolean;
+    /** Maximum number of issues to display per group */
+    readonly maxIssuesPerGroup?: number;
+    /** Whether to include metadata in output */
+    readonly includeMetadata?: boolean;
+}
+/**
+ * Grouped issues organized by a specific key.
+ */
+interface GroupedIssues {
+    /** The grouping key (file path, category name, or severity level) */
+    readonly key: string;
+    /** Human-readable label for the group */
+    readonly label: string;
+    /** Issues in this group */
+    readonly issues: readonly Issue[];
+    /** Number of issues in this group */
+    readonly count: number;
+}
+/**
+ * Summary statistics for report output.
+ */
+interface ReportSummary {
+    /** Total number of issues */
+    readonly totalIssues: number;
+    /** Issues by severity */
+    readonly bySeverity: Readonly<Record<Severity, number>>;
+    /** Issues by category */
+    readonly byCategory: Readonly<Record<IssueCategory, number>>;
+    /** Number of packages analyzed */
+    readonly packagesAnalyzed: number;
+    /** Number of files analyzed */
+    readonly filesAnalyzed: number;
+    /** Duration in milliseconds */
+    readonly durationMs: number;
+    /** Number of files with issues */
+    readonly filesWithIssues: number;
+    /** Highest severity level found */
+    readonly highestSeverity: Severity | null;
+}
+/**
+ * Reporter interface that all report generators must implement.
+ *
+ * @example
+ * ```ts
+ * const jsonReporter = createJsonReporter()
+ * const report = jsonReporter.generate(analysisResult)
+ * await fs.writeFile('report.json', report)
+ * ```
+ */
+interface Reporter {
+    /** Unique identifier for this reporter */
+    readonly id: ReportFormat;
+    /** Human-readable name for this reporter */
+    readonly name: string;
+    /** Generate a report string from analysis results */
+    readonly generate: (result: AnalysisResult, options?: ReportOptions) => string;
+    /** Stream report output to a writable stream (for large reports) */
+    readonly stream?: (result: AnalysisResult, write: (chunk: string) => void, options?: ReportOptions) => void;
+}
+/**
+ * Factory function type for creating reporter instances.
+ */
+type ReporterFactory = (options?: ReportOptions) => Reporter;
+/**
+ * Default report options.
+ */
+declare const DEFAULT_REPORT_OPTIONS: Required<Omit<ReportOptions, 'outputPath' | 'categories' | 'minSeverity'>>;
+/**
+ * Severity display configuration for consistent formatting.
+ */
+declare const SEVERITY_CONFIG: Readonly<Record<Severity, {
+    label: string;
+    emoji: string;
+    color: string;
+    priority: number;
+}>>;
+/**
+ * Category display configuration for consistent formatting.
+ */
+declare const CATEGORY_CONFIG: Readonly<Record<IssueCategory, {
+    label: string;
+    emoji: string;
+    description: string;
+}>>;
+/**
+ * Filter issues based on report options.
+ */
+declare function filterIssuesForReport(issues: readonly Issue[], options: ReportOptions): readonly Issue[];
+/**
+ * Group issues by the specified key.
+ */
+declare function groupIssues(issues: readonly Issue[], groupBy: ReportOptions['groupBy']): readonly GroupedIssues[];
+/**
+ * Calculate summary statistics from analysis results.
+ */
+declare function calculateSummary(result: AnalysisResult): ReportSummary;
+/**
+ * Format a file location for display.
+ */
+declare function formatLocation(location: Issue['location'], options?: {
+    includeColumn?: boolean;
+}): string;
+/**
+ * Format duration for human-readable display.
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Truncate text to a maximum length with ellipsis.
+ */
+declare function truncateText(text: string, maxLength: number): string;
+/**
+ * Get relative path from workspace root.
+ */
+declare function getRelativePath(filePath: string, workspacePath: string): string;
+
+/**
+ * Console reporter for terminal output with colors and formatting.
+ *
+ * Generates colorful terminal output using consola and @clack/prompts
+ * for interactive analysis feedback and CI/CD integration.
+ */
+
+/**
+ * Options specific to console reporter.
+ */
+interface ConsoleReporterOptions extends ReportOptions {
+    /** Whether to use colors (auto-detected by default) */
+    readonly colors?: boolean;
+    /** Whether to show verbose output with full descriptions */
+    readonly verbose?: boolean;
+    /** Whether to show compact output (one line per issue) */
+    readonly compact?: boolean;
+    /** Maximum width for text wrapping */
+    readonly maxWidth?: number;
+    /** Whether to use @clack/prompts styling */
+    readonly useClack?: boolean;
+}
+/**
+ * Create a console reporter instance.
+ *
+ * @example
+ * ```ts
+ * const reporter = createConsoleReporter({verbose: true})
+ * reporter.generate(analysisResult) // Outputs to console
+ * ```
+ */
+declare function createConsoleReporter(defaultOptions?: ConsoleReporterOptions): Reporter;
+
+/**
+ * JSON reporter for machine-readable analysis output.
+ *
+ * Generates structured JSON reports suitable for CI/CD integration,
+ * programmatic processing, and data analysis tools.
+ */
+
+/**
+ * JSON report structure for serialization.
+ */
+interface JsonReport {
+    /** Schema version for compatibility checking */
+    readonly $schema?: string;
+    /** Report metadata */
+    readonly metadata: JsonReportMetadata;
+    /** Summary statistics */
+    readonly summary: ReportSummary;
+    /** All issues (filtered based on options) */
+    readonly issues: readonly JsonReportIssue[];
+    /** Issues grouped by the specified key */
+    readonly groupedIssues?: readonly JsonReportGroup[];
+}
+/**
+ * Report metadata for provenance tracking.
+ */
+interface JsonReportMetadata {
+    /** Report generation timestamp (ISO 8601) */
+    readonly generatedAt: string;
+    /** Analysis start timestamp (ISO 8601) */
+    readonly analysisStartedAt: string;
+    /** Analysis completion timestamp (ISO 8601) */
+    readonly analysisCompletedAt: string;
+    /** Workspace path that was analyzed */
+    readonly workspacePath: string;
+    /** Report options used for generation */
+    readonly reportOptions: Partial<ReportOptions>;
+    /** Analyzer version (if available) */
+    readonly version?: string;
+}
+/**
+ * Issue representation in JSON report.
+ */
+interface JsonReportIssue {
+    /** Issue identifier */
+    readonly id: string;
+    /** Issue title */
+    readonly title: string;
+    /** Issue description */
+    readonly description: string;
+    /** Severity level */
+    readonly severity: Issue['severity'];
+    /** Issue category */
+    readonly category: Issue['category'];
+    /** File location */
+    readonly location: JsonReportLocation;
+    /** Related locations (for multi-file issues like circular imports) */
+    readonly relatedLocations?: readonly JsonReportLocation[];
+    /** Suggested fix */
+    readonly suggestion?: string;
+    /** Additional metadata */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Location representation in JSON report.
+ */
+interface JsonReportLocation {
+    /** File path (relative to workspace root) */
+    readonly file: string;
+    /** Absolute file path */
+    readonly absolutePath: string;
+    /** Line number (1-indexed) */
+    readonly line?: number;
+    /** Column number (1-indexed) */
+    readonly column?: number;
+    /** End line number (1-indexed) */
+    readonly endLine?: number;
+    /** End column number (1-indexed) */
+    readonly endColumn?: number;
+}
+/**
+ * Grouped issues in JSON report.
+ */
+interface JsonReportGroup {
+    /** Group key */
+    readonly key: string;
+    /** Group label */
+    readonly label: string;
+    /** Number of issues in group */
+    readonly count: number;
+    /** Issues in this group */
+    readonly issues: readonly JsonReportIssue[];
+}
+/**
+ * Options specific to JSON reporter.
+ */
+interface JsonReporterOptions extends ReportOptions {
+    /** Whether to pretty-print JSON output */
+    readonly prettyPrint?: boolean;
+    /** Indentation size for pretty-printing (default: 2) */
+    readonly indentation?: number;
+    /** Whether to include grouped issues section */
+    readonly includeGroupedIssues?: boolean;
+    /** JSON schema URL for validation */
+    readonly schemaUrl?: string;
+}
+/**
+ * Create a JSON reporter instance.
+ *
+ * @example
+ * ```ts
+ * const reporter = createJsonReporter({prettyPrint: true})
+ * const json = reporter.generate(analysisResult)
+ * await fs.writeFile('report.json', json)
+ * ```
+ */
+declare function createJsonReporter(defaultOptions?: JsonReporterOptions): Reporter;
+
+/**
+ * Markdown reporter for human-readable analysis output.
+ *
+ * Generates well-formatted Markdown reports suitable for GitHub issues,
+ * pull request comments, documentation, and team review.
+ */
+
+/**
+ * Options specific to Markdown reporter.
+ */
+interface MarkdownReporterOptions extends ReportOptions {
+    /** Whether to use GitHub-flavored Markdown features (checkboxes, alerts) */
+    readonly githubFlavored?: boolean;
+    /** Title for the report document */
+    readonly title?: string;
+    /** Whether to include table of contents */
+    readonly includeTableOfContents?: boolean;
+    /** Whether to use emoji in headers and status */
+    readonly useEmoji?: boolean;
+    /** Whether to use collapsible sections for issue details */
+    readonly collapsibleDetails?: boolean;
+    /** Maximum issues to show per group before truncating */
+    readonly maxIssuesPerGroup?: number;
+}
+/**
+ * Create a Markdown reporter instance.
+ *
+ * @example
+ * ```ts
+ * const reporter = createMarkdownReporter({githubFlavored: true})
+ * const markdown = reporter.generate(analysisResult)
+ * await fs.writeFile('report.md', markdown)
+ * ```
+ */
+declare function createMarkdownReporter(defaultOptions?: MarkdownReporterOptions): Reporter;
+
+/**
+ * Built-in architectural rules for workspace analysis.
+ *
+ * Provides rules for detecting common architectural anti-patterns:
+ * - Layer violations (cross-layer imports)
+ * - Barrel export misuse (export * in application code)
+ * - Public API validation (explicit exports)
+ * - Side effects in module initialization
+ * - Import path alias violations
+ * - Package boundary enforcement
+ */
+
+/**
+ * Options for LayerViolationRule.
+ */
+interface LayerViolationRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Custom layer configuration */
+        readonly layerConfig?: LayerConfiguration;
+        /** Whether to report violations for unrecognized layers */
+        readonly reportUnknownLayers?: boolean;
+    };
+}
+declare const layerViolationRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that detects layer boundary violations.
+ *
+ * @example
+ * ```ts
+ * const rule = createLayerViolationRule({
+ *   options: {
+ *     layerConfig: {
+ *       layers: [
+ *         {name: 'domain', allowedDependencies: []},
+ *         {name: 'application', allowedDependencies: ['domain']},
+ *       ],
+ *       patterns: [
+ *         {pattern: '**\/domain\/**', layer: 'domain'},
+ *       ],
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function createLayerViolationRule(options?: LayerViolationRuleOptions): Rule;
+/**
+ * Options for BarrelExportRule.
+ */
+interface BarrelExportRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Allow export * in these file patterns (e.g., index.ts in libs) */
+        readonly allowedPatterns?: readonly string[];
+        /** Whether to allow export * from workspace packages */
+        readonly allowWorkspaceReexports?: boolean;
+    };
+}
+declare const barrelExportRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that detects export * (barrel export) misuse.
+ *
+ * @example
+ * ```ts
+ * const rule = createBarrelExportRule({
+ *   options: {
+ *     allowedPatterns: ['**\/index.ts'],
+ *     allowWorkspaceReexports: false,
+ *   },
+ * })
+ * ```
+ */
+declare function createBarrelExportRule(options?: BarrelExportRuleOptions): Rule;
+/**
+ * Options for PublicApiRule.
+ */
+interface PublicApiRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Entry point files that define the public API */
+        readonly entryPoints?: readonly string[];
+        /** Require all exports to be re-exported from entry points */
+        readonly requireReexport?: boolean;
+    };
+}
+declare const publicApiRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that validates public API surface definition.
+ *
+ * @example
+ * ```ts
+ * const rule = createPublicApiRule({
+ *   options: {
+ *     entryPoints: ['src/index.ts'],
+ *     requireReexport: true,
+ *   },
+ * })
+ * ```
+ */
+declare function createPublicApiRule(options?: PublicApiRuleOptions): Rule;
+/**
+ * Options for SideEffectRule.
+ */
+interface SideEffectRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Allow side effects in these file patterns */
+        readonly allowedPatterns?: readonly string[];
+        /** Check for console.log/warn/error at module level */
+        readonly checkConsoleCalls?: boolean;
+        /** Check for assignments to global objects */
+        readonly checkGlobalAssignments?: boolean;
+    };
+}
+declare const sideEffectRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that detects side effects at module initialization.
+ *
+ * @example
+ * ```ts
+ * const rule = createSideEffectRule({
+ *   options: {
+ *     allowedPatterns: ['**\/polyfills.ts'],
+ *     checkConsoleCalls: true,
+ *   },
+ * })
+ * ```
+ */
+declare function createSideEffectRule(options?: SideEffectRuleOptions): Rule;
+/**
+ * Options for PathAliasRule.
+ */
+interface PathAliasRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Require path aliases for deep imports */
+        readonly requireAliasForDeepImports?: boolean;
+        /** Depth threshold for requiring aliases */
+        readonly deepImportThreshold?: number;
+    };
+}
+declare const pathAliasRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that validates import path aliases against tsconfig.
+ *
+ * @example
+ * ```ts
+ * const rule = createPathAliasRule({
+ *   options: {
+ *     requireAliasForDeepImports: true,
+ *     deepImportThreshold: 3,
+ *   },
+ * })
+ * ```
+ */
+declare function createPathAliasRule(options?: PathAliasRuleOptions): Rule;
+/**
+ * Options for PackageBoundaryRule.
+ */
+interface PackageBoundaryRuleOptions extends RuleOptions {
+    readonly options?: {
+        /** Allowed cross-package import patterns */
+        readonly allowedCrossPackagePatterns?: readonly string[];
+        /** Packages that can be imported from anywhere */
+        readonly sharedPackages?: readonly string[];
+        /** Enforce importing only from package entry points */
+        readonly enforceEntryPointImports?: boolean;
+    };
+}
+declare const packageBoundaryRuleMetadata: RuleMetadata;
+/**
+ * Creates a rule that enforces monorepo package boundaries.
+ *
+ * @example
+ * ```ts
+ * const rule = createPackageBoundaryRule({
+ *   options: {
+ *     sharedPackages: ['@bfra.me/es', '@bfra.me/tsconfig'],
+ *     enforceEntryPointImports: true,
+ *   },
+ * })
+ * ```
+ */
+declare function createPackageBoundaryRule(options?: PackageBoundaryRuleOptions): Rule;
+
+/**
+ * Pattern matching utilities for glob-style file path matching.
+ *
+ * Provides simple glob pattern matching supporting ** (any path segments)
+ * and * (single segment) without external dependencies.
+ */
+/**
+ * Matches a file path against a glob pattern.
+ *
+ * Supported patterns:
+ * - `**` matches any number of path segments
+ * - `*` matches any characters except path separator
+ */
+declare function matchPattern(filePath: string, pattern: string): boolean;
+/**
+ * Checks if a file path matches any of the given patterns.
+ */
+declare function matchAnyPattern(filePath: string, patterns: readonly string[]): boolean;
+/**
+ * Normalizes a file path for consistent pattern matching.
+ *
+ * Converts backslashes to forward slashes for cross-platform compatibility.
+ */
+declare function normalizePath(filePath: string): string;
+
+export { type AnalysisCache, type AnalysisChangeDetector, type AnalysisChangeDetectorOptions, type AnalysisContext$1 as AnalysisContext, type AnalysisOrchestrator, AnalysisProgress, AnalysisResult, type Analyzer, type AnalyzerError, type AnalyzerFactory, type AnalyzerMetadata, type AnalyzerOptions, type AnalyzerRegistration, type AnalyzerRegistry, type ArchitecturalAnalyzerOptions, BUILTIN_ANALYZER_IDS, BUILTIN_RULE_IDS, type BarrelExportRuleOptions, type BuildConfigAnalyzerOptions, type BundleEstimatorOptions, type BundleSizeEstimate, CACHE_SCHEMA_VERSION, CATEGORY_CONFIG, CONFIG_FILE_PATTERNS, type CacheError, type CacheErrorCode, type CacheManager, type CacheManagerOptions, type CacheMetadata, type CacheOptions, type CacheStatistics, type CacheValidationResult, type CachedFileAnalysis, type CachedFileState, type CachedPackageAnalysis, type CircularImportAnalyzerOptions, type CircularImportStats, type CodeFingerprint, type ConfigConsistencyAnalyzerOptions, type ConfigError, type ConfigErrorCode, type ConfigLoadError, type ConfigLoadErrorCode, type ConfigLoadResult, type ConsoleReporterOptions, type CycleEdge, type CycleNode, type CycleVisualization, DEFAULT_ANALYZER_CONFIG, DEFAULT_CACHE_OPTIONS, DEFAULT_CONCURRENCY, DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS, DEFAULT_INCREMENTAL_OPTIONS, DEFAULT_LAYER_CONFIG, DEFAULT_PACKAGE_PATTERNS, DEFAULT_REPORT_OPTIONS, DEFAULT_WORKSPACE_OPTIONS, type DeadCodeAnalyzerOptions, type DeadCodeStats, type DependencyCycle, type DependencyEdge, type DependencyGraph, type DependencyGraphOptions, type DependencyNode, type DependencySizeEstimate, type DuplicateCodeAnalyzerOptions, type DuplicateDependencyAnalyzerOptions, type DuplicateDependencyStats, type DuplicatePattern, type EslintConfigAnalyzerOptions, type ExportedSymbol, type ExportsFieldAnalyzerOptions, type ExtractedImport, type GraphStatistics, type GroupedIssues, type ImportExtractionResult, type ImportExtractorOptions, type ImportType, type IncrementalAnalysisContext, type IncrementalAnalysisError, type IncrementalAnalysisErrorCode, type IncrementalAnalysisOptions, type IncrementalAnalysisResult, type IncrementalAnalyzer, Issue, IssueCategory, IssueLocation, type JsonReport, type JsonReportGroup, type JsonReportIssue, type JsonReportLocation, type JsonReportMetadata, type JsonReporterOptions, type LargeDependencyAnalyzerOptions, type LayerConfiguration, type LayerDefinition, type LayerPattern, type LayerViolationRuleOptions, type MarkdownReporterOptions, type MergedConfig, type OptimizableImport, type OrchestratorOptions, type PackageBoundaryRuleOptions, type PackageBundleStats, type PackageJsonAnalyzerOptions, type ParsedPackageJson, type ParsedTsConfig, type PathAliasRuleOptions, type PeerDependencyAnalyzerOptions, type PublicApiRuleOptions, type ReportFormat, type ReportOptions, type ReportSummary, type Reporter, type ReporterFactory, type Rule, type RuleContext, type RuleEngine, type RuleEngineError, type RuleFactory, type RuleMetadata, type RuleOptions, type RuleRegistration, type RuleResult, type RuleViolation, SEVERITY_CONFIG, type SafeParseResult, type ScanError, Severity, type SideEffectRuleOptions, type TreeShakingBlocker, type TreeShakingBlockerAnalyzerOptions, type TreeShakingBlockerType, type TreeShakingSavingsEstimate, type TsCompilerOptions, type TsProjectReference, type TsconfigAnalyzerOptions, type UnusedDependencyAnalyzerOptions, type VersionAlignmentAnalyzerOptions, type WorkspaceAnalyzerConfig, type WorkspaceFileHasher, type WorkspaceHasherOptions, type WorkspacePackage, type WorkspacePackageJson, type WorkspaceScanResult, type WorkspaceScannerOptions, aggregatePackageImports, analyzePackages, analyzeWorkspace, architecturalAnalyzerMetadata, barrelExportRuleMetadata, METADATA$6 as buildConfigAnalyzerMetadata, buildDependencyGraph, builtinAnalyzers, calculateSummary, circularImportAnalyzerMetadata, collectConfigFileStates, computeCycleStats, computeDeadCodeStats, computeDuplicateStats, computeGraphStatistics, METADATA$5 as configConsistencyAnalyzerMetadata, createAnalysisChangeDetector, createAnalyzerRegistry, createArchitecturalAnalyzer, createBarrelExportRule, createBuildConfigAnalyzer, createCacheManager, createCircularImportAnalyzer, createConfigConsistencyAnalyzer, createConsoleProgressCallback, createConsoleReporter, createDeadCodeAnalyzer, createDefaultRegistry, createDuplicateCodeAnalyzer, createDuplicateDependencyAnalyzer, createEmptyCache, createEslintConfigAnalyzer, createExportsFieldAnalyzer, createFileAnalysisEntry, createIncrementalAnalyzer, createIssue, createJsonReporter, createLargeDependencyAnalyzer, createLayerViolationRule, createMarkdownReporter, createOrchestrator, createPackageAnalysisEntry, createPackageBoundaryRule, createPackageJsonAnalyzer, createPathAliasRule, createPeerDependencyAnalyzer, createPublicApiRule, createRuleEngine, createSideEffectRule, createSilentProgressCallback, createTreeShakingBlockerAnalyzer, createTsconfigAnalyzer, createUnusedDependencyAnalyzer, createVersionAlignmentAnalyzer, createWorkspaceHasher, createWorkspaceScanner, deadCodeAnalyzerMetadata, defineConfig, duplicateCodeAnalyzerMetadata, duplicateDependencyAnalyzerMetadata, METADATA$4 as eslintConfigAnalyzerMetadata, estimateDependencySize, estimateFileSize, estimatePackageBundleSize, estimateTreeShakingSavings, METADATA$3 as exportsFieldAnalyzerMetadata, extractImports, filterIssues, filterIssuesForReport, filterPackagesByPattern, findConfigFile, findCycles, findLargeDependencies, findLargeFiles, formatBytes, formatDuration, formatLocation, generateCycleVisualization, getAllDependencies, getAllSourceFiles, getAnalyzerOptions, getDefaultConfig, getFileLayer, getKnownLargePackages, getPackageInfo, getPackageNameFromSpecifier, getPackageScope, getRelativePath, getSourceFile, getTransitiveDependencies, getTransitiveDependents, getUniqueDependencies, getUnscopedName, groupIssues, groupPackagesByScope, initializeCache, isJavaScriptFile, isLayerImportAllowed, isRelativeImport, isSourceFile, isTypeScriptFile, isWorkspacePackageImport, largeDependencyAnalyzerMetadata, layerViolationRuleMetadata, loadConfig, loadConfigFile, matchAnyPattern, matchPattern, meetsMinSeverity, mergeAnalyzerConfigs, mergeConfig, normalizePath, packageBoundaryRuleMetadata, METADATA$2 as packageJsonAnalyzerMetadata, parsePackageJson, parsePackageJsonContent, parseSourceFiles, parseTsConfig, parseTsConfigContent, parseWorkspaceAnalyzerConfig, pathAliasRuleMetadata, peerDependencyAnalyzerMetadata, publicApiRuleMetadata, resolveRelativeImport, resolveTsConfigExtends, safeParseAnalyzeOptions, shouldAnalyzeCategory, sideEffectRuleMetadata, treeShakingBlockerAnalyzerMetadata, truncateText, METADATA$1 as tsconfigAnalyzerMetadata, unusedDependencyAnalyzerMetadata, METADATA as versionAlignmentAnalyzerMetadata };