@ngcompass/planner 0.1.1-beta

package/dist/index.d.ts

@@ -0,0 +1,826 @@
+import { CacheContext, CacheKeyContext, ResultCache } from '@ngcompass/cache';
+import { RuleSeverity, ResolvedRule, ConfigOverride, AnalysisResult, Result } from '@ngcompass/common';
+export { Err, Ok, Result } from '@ngcompass/common';
+
+/**
+ * Execution Plan Types
+ *
+ * Maps discovered files + resolved rules → executable tasks with indexes.
+ */
+
+/**
+ * Complete execution plan output (plan + tasks + indexes)
+ *
+ * - tasks: Flat array of all tasks (task-centric, content-addressed)
+ * - plan: File-grouped view (file-centric, backward compatible)
+ * - indexes: Pre-computed indexes for both file and task queries
+ */
+interface ExecutionPlanOutput {
+    /** All tasks to execute (primary execution structure) */
+    readonly tasks: ReadonlyArray<Task>;
+    /** File-grouped view (backward compatible, derived from tasks) */
+    readonly plan: ExecutionPlan;
+    /** Pre-computed indexes for efficient queries */
+    readonly indexes: ExecutionIndexes;
+    /** Tasks that were skipped */
+    readonly skippedTasks: ReadonlyArray<Task>;
+    /** Pre-loaded cached results (taskId → result) */
+    readonly cachedResults?: ReadonlyMap<string, unknown>;
+    /** Global content hash for the entire plan */
+    readonly globalHash?: string;
+    /** Pre-computed analysis result (if fully cached) */
+    readonly precomputedAnalysis?: AnalysisResult;
+    /**
+     * Files whose tasks were not found in the result cache and will be
+     * re-analysed. Populated when `options.cache` is provided and incremental
+     * filtering has run. `undefined` when caching is disabled.
+     */
+    readonly changedFiles?: ReadonlyArray<string>;
+    /**
+     * Files whose tasks were found in the result cache and skipped.
+     * Populated when `options.cache` is provided and incremental
+     * filtering has run. `undefined` when caching is disabled.
+     */
+    readonly cachedFiles?: ReadonlyArray<string>;
+}
+/**
+ * Execution plan - one entry per discovered file
+ */
+type ExecutionPlan = Readonly<Record<string, FileAnalysisUnit>>;
+/**
+ * A single file that needs to be analyzed
+ */
+interface FileAnalysisUnit {
+    /** The primary file being analyzed */
+    readonly file: FileInfo;
+    /** All the tasks/rules that will run on this file */
+    readonly tasks: ReadonlyArray<RuleTask>;
+}
+/**
+ * Information about the file being analyzed
+ */
+interface FileInfo {
+    /** File path (absolute) */
+    readonly path: string;
+    /** File type (component, service, etc) */
+    readonly type: FileType;
+    /** Content hash for cache invalidation */
+    readonly hash: string;
+}
+/**
+ * File type classification.
+ *
+ * `'unknown'` is used for files that do not match any recognised Angular or
+ * TypeScript pattern (e.g. stray JSON, Markdown, or binary files that
+ * somehow enter the file list). Rules are never applied to `'unknown'` files.
+ */
+type FileType = 'component' | 'directive' | 'pipe' | 'service' | 'module' | 'guard' | 'logic' | 'angular-class' | 'spec' | 'template' | 'style' | 'config' | 'unknown';
+/**
+ * A single rule execution task
+ */
+interface RuleTask {
+    /** Which rule to run */
+    readonly ruleName: string;
+    /** Rule severity level */
+    readonly severity: RuleSeverity;
+    /** Rule options (configuration from resolved rules) */
+    readonly options: Readonly<Record<string, unknown>>;
+    /** Cache key for this specific task */
+    readonly cacheKey: string;
+    /** What files this task needs to read and analyze */
+    readonly inputs: TaskInputs;
+    /**
+     * Whether this task requires the TypeScript type-checker (expensive!).
+     * When true the file is included in `indexes.filesNeedingTypeChecker` so
+     * the engine can set up a full TypeScript Program for that file.
+     */
+    readonly needsTypeChecker?: boolean;
+    /**
+     * Whether this task requires a pre-computed `ProjectContext` (CTX-001).
+     * Routed to the type-aware execution path alongside `needsTypeChecker`.
+     */
+    readonly needsProjectContext?: boolean;
+}
+/**
+ * All the files this task needs to read
+ */
+interface TaskInputs {
+    /** TypeScript file input (always present) */
+    typescript: FileInput;
+    /** Template file input (if needed) */
+    template?: FileInput;
+    /** Style files input (if needed) */
+    styles?: ReadonlyArray<FileInput>;
+    /** Spec file input (if needed) */
+    spec?: FileInput;
+}
+/**
+ * A single file input for a task
+ */
+interface FileInput {
+    /** Path to the file (absolute) */
+    readonly path: string;
+    /** Content hash of this file (SHA-256) */
+    readonly hash: string;
+    /** Does this task need to parse this file into AST? */
+    readonly needsAst: boolean;
+}
+/**
+ * Resource type enum
+ */
+type ResourceType = 'typescript' | 'template' | 'styles' | 'spec';
+/**
+ * A single executable task (task-centric architecture)
+ *
+ * Task is the fundamental unit of execution with content-based identity.
+ * Unlike RuleTask (file-centric), Task uses content-addressable cache keys
+ * that survive file renames and enable precise cache invalidation.
+ *
+ * Key differences from RuleTask:
+ * - taskId: Content-based (SHA-256 of all inputs + options)
+ * - filePath: Explicit (not embedded in cache key)
+ * - inputs: Include content hashes for each file
+ */
+interface Task {
+    /**
+     * Content-based task identifier (primary cache key)
+     *
+     * Format: SHA256(ruleName + typescript.hash + template?.hash + styles?.hashes + spec?.hash + options)
+     *
+     * This enables:
+     * - Cache hits even after file renames (content unchanged)
+     * - Precise invalidation (only affected tasks)
+     * - Cross-project cache sharing (same content = same ID)
+     */
+    readonly taskId: string;
+    /** Which rule to execute */
+    readonly ruleName: string;
+    /** Which file is being analyzed */
+    readonly filePath: string;
+    /** Rule severity level */
+    readonly severity: RuleSeverity;
+    /** Rule options (configuration) */
+    readonly options: Readonly<Record<string, unknown>>;
+    /** Input files with content hashes */
+    readonly inputs: TaskInputs;
+    /**
+     * Whether this task requires the TypeScript type-checker (expensive!).
+     * Mirrors `RuleTask.needsTypeChecker` on the task-centric view.
+     */
+    readonly needsTypeChecker?: boolean;
+    /**
+     * Whether this task requires a pre-computed `ProjectContext` (CTX-001).
+     *
+     * When `true` the task is routed to the type-aware execution path on the
+     * main thread (same as `needsTypeChecker`) because `ProjectContext` is
+     * built from the TypeScript `Program` created there.
+     * Rules receive the context via `RuleContext.project`.
+     */
+    readonly needsProjectContext?: boolean;
+}
+/**
+ * Pre-computed indexes for efficient engine queries
+ *
+ * - File-level indexes: For parsing optimization (parse once, reuse)
+ * - Task-level indexes: For execution strategies (by rule, by severity, etc)
+ */
+interface ExecutionIndexes {
+    /** Files that need TypeScript AST parsing */
+    readonly filesNeedingTsAst: ReadonlyArray<string>;
+    /** Files that need HTML AST parsing */
+    readonly filesNeedingHtmlAst: ReadonlyArray<string>;
+    /** Files that need CSS AST parsing */
+    readonly filesNeedingCssAst: ReadonlyArray<string>;
+    /**
+     * Files that need the TypeScript type-checker (expensive!).
+     * The engine should allocate a full TypeScript Program only for these files.
+     */
+    readonly filesNeedingTypeChecker: ReadonlyArray<string>;
+    /** Tasks grouped by file path: filePath → tasks */
+    readonly tasksByFile: Readonly<Record<string, ReadonlyArray<Task>>>;
+    /** Tasks grouped by rule name: ruleName → tasks */
+    readonly tasksByRule: Readonly<Record<string, ReadonlyArray<string>>>;
+    /** Tasks grouped by severity: severity → tasks */
+    readonly tasksBySeverityLevel: Readonly<Record<RuleSeverity, ReadonlyArray<Task>>>;
+    /** Files grouped by type: fileType → file paths */
+    readonly filesByType: Readonly<Record<FileType, ReadonlyArray<string>>>;
+    /** Task count by severity level (backward compatible) */
+    readonly tasksBySeverity: Readonly<Record<RuleSeverity, number>>;
+    /** Global statistics */
+    readonly stats: ExecutionStats;
+}
+/**
+ * Global execution statistics
+ */
+interface ExecutionStats {
+    /** Total files in the plan */
+    readonly totalFiles: number;
+    /** Total tasks to execute */
+    readonly totalTasks: number;
+    /** Average tasks per file */
+    readonly avgTasksPerFile: number;
+    /** Files with templates */
+    readonly filesWithTemplates: number;
+    /** Files with styles */
+    readonly filesWithStyles: number;
+    /** Files with specs */
+    readonly filesWithSpecs: number;
+}
+/**
+ * Options for building the execution plan
+ */
+interface ExecutionPlanOptions {
+    /** Discovered files from Phase 1 */
+    readonly files: ReadonlyArray<string>;
+    /** Resolved rules from Phase 1.5 */
+    readonly rules: ReadonlyMap<string, ResolvedRule>;
+    /** Root directory for resolving relative paths */
+    readonly rootDir: string;
+    /** Optional cache context for persistent optimizations */
+    readonly cache?: CacheContext;
+    /** Debug mode for detailed timing logging */
+    readonly debug?: boolean;
+    /** Options for incremental filtering */
+    readonly incremental?: IncrementalFilterOptions;
+    /**
+     * Version context for cache key generation.
+     * When provided, toolVersion and ruleRegistryHash are embedded in taskIds
+     * and globalHash, ensuring caches are invalidated on tool / rule-set upgrades.
+     *
+     * Strongly recommended for production use. Omitting risks stale result-cache
+     * hits after an upgrade.
+     */
+    readonly cacheKeyCtx?: CacheKeyContext;
+    /**
+     * Number of files at which task-building switches from sequential to
+     * parallel (worker threads). Defaults to 10 000.
+     *
+     * Lower this value to enable parallelism on smaller projects.
+     * Set to `Infinity` to always use the sequential path (useful for debugging).
+     */
+    readonly parallelThreshold?: number;
+    /**
+     * Number of worker threads to use when parallel mode is active.
+     * Defaults to 4.
+     */
+    readonly workerCount?: number;
+    /**
+     * Per-file rule overrides from config.overrides[].
+     *
+     * Each override entry's `files` glob patterns are matched against each
+     * analysed file path. Matching override rules are merged on top of the
+     * global resolved rules before tasks are created for that file.
+     * Last matching override wins.
+     *
+     * - `'off'`        → rule is disabled for matching files
+     * - `'warn'|'error'` → severity changed, options inherited from global
+     * - object form   → severity + options merged (override wins on conflicts)
+     */
+    readonly overrides?: ReadonlyArray<ConfigOverride>;
+}
+/**
+ * Incremental execution plan with cache-based filtering
+ */
+interface IncrementalPlan {
+    /** Tasks with results in cache (can be skipped) */
+    readonly skippedTasks: ReadonlyArray<Task>;
+    /** Tasks without cache entries (must be executed) */
+    readonly tasks: ReadonlyArray<Task>;
+    /** Pre-loaded cached results (taskId → result) */
+    readonly cachedResults: ReadonlyMap<string, unknown>;
+    /** Cache statistics */
+    readonly stats: CacheFilterStats;
+}
+/**
+ * Cache filtering statistics
+ */
+interface CacheFilterStats {
+    /** Total tasks in execution plan */
+    readonly totalTasks: number;
+    /** Tasks found in cache */
+    readonly cachedTasks: number;
+    /** Tasks not in cache (need execution) */
+    readonly pendingTasks: number;
+    /** Cache hit rate (0.0 to 1.0) */
+    readonly cacheHitRate: number;
+    /**
+     * Estimated percentage of execution time saved due to caching (0–100).
+     *
+     * Computed as `cacheHitRate × 100`, which is accurate when tasks have
+     * roughly equal cost. Use as a fast approximation for progress UIs and
+     * log messages.
+     */
+    readonly timeSavedEstimate: number;
+}
+/**
+ * Options for incremental filtering
+ */
+interface IncrementalFilterOptions {
+    /** Force re-execution even if cached */
+    readonly forceRerun?: boolean;
+    /** Load cached results into memory */
+    readonly loadCachedResults?: boolean;
+    /** Maximum age of cached results (ms) */
+    readonly maxCacheAge?: number;
+}
+/**
+ * Options for cache pruning
+ */
+interface CachePruneOptions {
+    /** Maximum age of cache entries (ms) */
+    readonly maxAge?: number;
+    /** Maximum number of entries to keep */
+    readonly maxEntries?: number;
+    /** Minimum hit count to keep */
+    readonly minHits?: number;
+}
+
+/**
+ * Execution Plan Builder
+ *
+ * Builds an execution plan from discovered files and resolved rules.
+ * Produces both task-centric and file-centric representations plus indexes.
+ */
+
+/**
+ * Builds complete execution plan with indexes and optional caching.
+ *
+ * @param options - Build options (files + rules)
+ * @returns ExecutionPlanOutput with tasks[] + plan + indexes
+ */
+declare const buildExecutionPlan: (options: ExecutionPlanOptions) => Promise<Result<ExecutionPlanOutput>>;
+/**
+ * Gets execution plan summary (for logging).
+ *
+ * @param output - Execution plan output
+ * @returns Summary string
+ */
+declare const getExecutionPlanSummary: (output: ExecutionPlanOutput) => string;
+
+/**
+ * File Type Detection
+ *
+ * Pure functions for detecting Angular file types based on naming conventions.
+ * Follows FP principles: pure, deterministic, no side effects.
+ */
+
+/**
+ * Detects file type based on file path and naming conventions.
+ *
+ * Convention rules:
+ * - *.component.ts → component
+ * - *.directive.ts → directive
+ * - *.pipe.ts → pipe
+ * - *.service.ts → service
+ * - *.module.ts → module
+ * - *.guard.ts → guard
+ * - *.html → template
+ * - *.css, *.scss, *.sass, *.less → style
+ * - *.config.ts, *.json → config
+ * - *.ts (other TypeScript) → logic
+ * - Everything else → unknown (rules are never applied to unknown files)
+ *
+ * @param filePath - Absolute or relative file path
+ * @returns FileType classification
+ */
+declare const detectFileType: (filePath: string) => FileType;
+/**
+ * Checks if a file is a TypeScript file.
+ *
+ * @param filePath - File path
+ * @returns true if TypeScript file
+ */
+declare const isTypeScriptFile: (filePath: string) => boolean;
+/**
+ * Checks if a file is a template file (HTML).
+ *
+ * @param filePath - File path
+ * @returns true if template file
+ */
+declare const isTemplateFile: (filePath: string) => boolean;
+/**
+ * Checks if a file is a style file (CSS/SCSS/etc).
+ *
+ * @param filePath - File path
+ * @returns true if style file
+ */
+declare const isStyleFile: (filePath: string) => boolean;
+/**
+ * Checks if a file is a spec file (test).
+ *
+ * @param filePath - File path
+ * @returns true if spec file
+ */
+declare const isSpecFile: (filePath: string) => boolean;
+/**
+ * Checks if a file is a component file.
+ *
+ * @param filePath - File path
+ * @returns true if component file
+ */
+declare const isComponentFile: (filePath: string) => boolean;
+/**
+ * Gets the base name without Angular suffix.
+ * Example: "user.component.ts" → "user"
+ *
+ * @param filePath - File path
+ * @returns Base name without suffix
+ */
+declare const getBaseName: (filePath: string) => string;
+
+/**
+ * Resource Discovery
+ *
+ * Pure functions for discovering related files (templates, styles, specs)
+ * using convention-based detection (no parsing).
+ */
+
+/**
+ * Discovers all related resources for a TypeScript file.
+ *
+ * @param tsFilePath - TypeScript file path (absolute)
+ * @param needsTsAst - Whether TypeScript input requires AST
+ * @param needsHtmlAst - Whether template input requires AST
+ * @param needsCssAst - Whether styles inputs require AST
+ * @param needsSpecAst - Whether spec input requires AST
+ * @param directoryCache - Optional directory listing cache
+ * @returns TaskInputs with all discovered resources
+ */
+declare const discoverResources: (tsFilePath: string, needsTsAst: boolean, needsHtmlAst: boolean, needsCssAst: boolean, needsSpecAst: boolean, directoryCache?: Map<string, string[]>) => Promise<TaskInputs>;
+/**
+ * Checks if any resource file exists for the given TypeScript file.
+ *
+ * @param tsFilePath - TypeScript file path
+ * @param resourceType - Type of resource to check
+ * @param directoryCache - Optional directory listing cache
+ * @returns true if resource exists
+ */
+declare const resourceExists: (tsFilePath: string, resourceType: "template" | "style" | "spec", directoryCache?: Map<string, string[]>) => Promise<boolean>;
+/**
+ * Gets all style file paths for a component.
+ *
+ * @param tsFilePath - Component TypeScript file path
+ * @param directoryCache - Optional directory listing cache
+ * @returns Array of style file paths
+ */
+declare const getStyleFiles: (tsFilePath: string, directoryCache?: Map<string, string[]>) => Promise<ReadonlyArray<string>>;
+/**
+ * Gets the template file path for a component.
+ *
+ * @param tsFilePath - Component TypeScript file path
+ * @param directoryCache - Optional directory listing cache
+ * @returns Template file path or null if not found
+ */
+declare const getTemplateFile: (tsFilePath: string, directoryCache?: Map<string, string[]>) => Promise<string | null>;
+/**
+ * Gets the spec file path.
+ *
+ * @param tsFilePath - TypeScript file path
+ * @param directoryCache - Optional directory listing cache
+ * @returns Spec file path or null if not found
+ */
+declare const getSpecFile: (tsFilePath: string, directoryCache?: Map<string, string[]>) => Promise<string | null>;
+
+interface ComponentNode {
+    tsPath: string;
+    templatePath?: string;
+    stylePaths: string[];
+    specPath?: string;
+    type: FileType;
+}
+/**
+ * A graph of component dependencies (template, styles, specs).
+ * Built in a single pass to avoid repeated directory scans.
+ */
+declare class ComponentDependencyGraph {
+    private graph;
+    /**
+     * Builds the graph from a list of files.
+     * O(N) complexity where N is the number of files.
+     * Falls back to decorator-based templateUrl/styleUrls extraction when
+     * convention-based discovery finds no template or styles.
+     */
+    build(files: ReadonlyArray<string>): Promise<void>;
+    /**
+     * Gets resources for a given component file.
+     * O(1) lookup.
+     */
+    getResources(tsPath: string): ComponentNode | undefined;
+}
+
+/**
+ * Task Builder
+ *
+ * Pure functions for building executable tasks by matching rules to files.
+ */
+
+interface GraphStats {
+    hits: number;
+    misses: number;
+    fallbacks: number;
+}
+/**
+ * Context for task building to enable memoization and shared caches.
+ */
+interface TaskBuilderContext {
+    hashCache?: Map<string, string>;
+    resourceCache?: Map<string, TaskInputs>;
+    directoryCache?: Map<string, string[]>;
+    globalHash?: string;
+    componentGraph?: ComponentDependencyGraph;
+    graphStats?: GraphStats;
+    /**
+     * Version context forwarded to calculateTaskId.
+     * When provided, toolVersion and ruleRegistryHash are mixed into every
+     * taskId so that upgrading the tool or a plugin invalidates per-task
+     * result-cache entries automatically.
+     */
+    cacheKeyCtx?: CacheKeyContext;
+}
+/**
+ * Checks if a rule should be applied to a file type.
+ *
+ * @param rule - Resolved rule
+ * @param fileType - File type
+ * @returns true if rule applies to this file type
+ */
+declare const shouldApplyRule: (rule: ResolvedRule, fileType: FileType) => boolean;
+/**
+ * Filters rules that require a specific analysis capability.
+ *
+ * @param rules - All resolved rules
+ * @param astType - Capability to filter by
+ * @returns Filtered rules
+ */
+declare const filterRulesByAstRequirement: (rules: ReadonlyMap<string, ResolvedRule>, astType: "tsAst" | "htmlAst" | "cssAst" | "typeChecker" | "projectContext") => ReadonlyArray<ResolvedRule>;
+/**
+ * Groups rules by dependency type.
+ *
+ * @param rules - All resolved rules
+ * @returns Rules grouped by dependency type
+ */
+declare const groupRulesByDependencyType: (rules: ReadonlyMap<string, ResolvedRule>) => Readonly<Record<string, ReadonlyArray<ResolvedRule>>>;
+/**
+ * Builds a single task with content-based taskId.
+ *
+ * @param filePath - File path
+ * @param fileType - File type
+ * @param rule - Resolved rule
+ * @param context - Optional builder context
+ * @returns Task or null if rule does not apply
+ */
+declare const buildTask: (filePath: string, fileType: FileType, rule: ResolvedRule, context?: TaskBuilderContext) => Promise<Task | null>;
+/**
+ * Builds all applicable tasks for a file.
+ *
+ * @param filePath - File path
+ * @param fileType - File type
+ * @param rules - All resolved rules
+ * @param context - Optional context
+ * @returns Array of tasks
+ */
+declare const buildTasksForFileTaskCentric: (filePath: string, fileType: FileType, rules: ReadonlyMap<string, ResolvedRule>, context?: TaskBuilderContext) => Promise<ReadonlyArray<Task>>;
+
+/**
+ * Content Hashing
+ *
+ * Deterministic hashing utilities for cache invalidation.
+ * Hash inputs may include: file content, related resources, and active rules.
+ */
+
+/**
+ * Reads file content and returns a content hash.
+ *
+ * @param filePath - File path
+ * @param cache - Optional in-memory cache
+ * @returns Content hash
+ */
+declare const hashFile: (filePath: string, cache?: Map<string, string>) => Promise<string>;
+/**
+ * Calculates a combined hash for multiple files.
+ *
+ * @param filePaths - Array of file paths
+ * @param cache - Optional hash cache
+ * @returns Combined hash
+ */
+declare const hashFiles: (filePaths: ReadonlyArray<string>, cache?: Map<string, string>) => Promise<string>;
+/**
+ * Calculates hash for rules configuration.
+ *
+ * @param rules - Rules that apply to this file
+ * @returns Rules hash
+ */
+declare const hashRules: (rules: ReadonlyArray<ResolvedRule>) => string;
+/**
+ * Calculates combined hash for a file and its resources.
+ *
+ * @param inputs - Task inputs with hashes
+ * @param applicableRules - Rules that apply to this file
+ * @returns Combined content hash
+ */
+declare const calculateFileHash: (inputs: TaskInputs, applicableRules: ReadonlyArray<ResolvedRule>) => string;
+/**
+ * Calculates hash for task inputs only (no rules).
+ *
+ * @param inputs - Task inputs
+ * @returns Inputs hash
+ */
+declare const hashTaskInputs: (inputs: TaskInputs) => Promise<string>;
+/**
+ * Fast hash using only file stats.
+ *
+ * @param filePath - File path
+ * @returns Stats-based hash
+ */
+declare const hashFileStats: (filePath: string) => Promise<string>;
+
+/**
+ * Index Builder
+ *
+ * Pure functions for building pre-computed indexes for O(1) queries.
+ * Indexes enable efficient incremental execution strategies.
+ */
+
+/**
+ * Builds all indexes from execution plan and optional task list.
+ *
+ * @param plan - Execution plan (file-centric view)
+ * @param tasks - Task-centric list (optional for backward compatibility)
+ * @returns Comprehensive pre-computed indexes
+ */
+declare function buildIndexes(plan: ExecutionPlan): ExecutionIndexes;
+declare function buildIndexes(plan: ExecutionPlan, tasks: ReadonlyArray<Task>): ExecutionIndexes;
+/**
+ * Filters index to get files for specific rules.
+ *
+ * @param index - TasksByRule index
+ * @param ruleNames - Rule names to filter by
+ * @returns Combined array of file paths
+ */
+declare const getFilesForRules: (index: Readonly<Record<string, ReadonlyArray<string>>>, ruleNames: ReadonlyArray<string>) => ReadonlyArray<string>;
+/**
+ * Gets total task count from indexes.
+ *
+ * @param indexes - Execution indexes
+ * @returns Total task count
+ */
+declare const getTotalTasks: (indexes: ExecutionIndexes) => number;
+/**
+ * Gets tasks count for a specific severity level.
+ *
+ * @param indexes - Execution indexes
+ * @param severity - Severity level
+ * @returns Task count
+ */
+declare const getTasksCountBySeverity: (indexes: ExecutionIndexes, severity: RuleSeverity) => number;
+
+/**
+ * Incremental Planner (Phase 2.0)
+ *
+ * Filters execution tasks by cache status.
+ * Splits tasks into cached (skip) and pending (execute).
+ */
+
+/**
+ * Filters tasks by cache status.
+ *
+ * @param tasks - All tasks from execution plan
+ * @param cache - Result cache
+ * @param options - Filter options
+ * @returns Incremental plan with cache split
+ */
+declare const filterCachedTasks: (tasks: ReadonlyArray<Task>, cache: ResultCache, options?: IncrementalFilterOptions) => Promise<IncrementalPlan>;
+/**
+ * Checks if all tasks are cached.
+ *
+ * @param tasks - Tasks to check
+ * @param cache - Result cache
+ * @returns true if all tasks are cached
+ */
+declare const areAllTasksCached: (tasks: ReadonlyArray<Task>, cache: ResultCache) => Promise<boolean>;
+/**
+ * Gets cache hit rate for a set of tasks.
+ *
+ * @param tasks - Tasks to check
+ * @param cache - Result cache
+ * @returns Cache hit rate (0.0 to 1.0)
+ */
+declare const getCacheHitRate: (tasks: ReadonlyArray<Task>, cache: ResultCache) => Promise<number>;
+/**
+ * Prunes stale cache entries.
+ *
+ * @param taskIds - All current task IDs
+ * @param cache - Result cache
+ * @param options - Prune options
+ * @returns Number of entries removed
+ */
+declare const pruneStaleCache: (taskIds: ReadonlyArray<string>, cache: ResultCache, options?: CachePruneOptions) => Promise<number>;
+
+/**
+ * Groups tasks by file path.
+ *
+ * @param tasks - Flat list of tasks
+ * @returns Map keyed by file path
+ */
+declare const groupTasksByFile: (tasks: ReadonlyArray<Task>) => Map<string, Task[]>;
+
+/**
+ * Scanner → Planner Bridge Utilities
+ *
+ * Convenience helpers that convert `@ngcompass/scanner`'s `ScanResult` into
+ * the inputs expected by `@ngcompass/planner`'s `buildExecutionPlan`.
+ *
+ * Using this module eliminates the boilerplate of manually forwarding
+ * `ScanResult.files` and keeps the two packages loosely coupled — if either
+ * package changes its contract, only this file needs updating.
+ */
+
+/**
+ * Minimal `ScanResult` shape consumed by the bridge.
+ *
+ * This matches `@ngcompass/scanner`'s `ScanResult` interface and is kept
+ * inline to avoid a circular package dependency (scanner → planner would
+ * create a cycle). Only the fields actually used by `scanResultToPlanInput`
+ * are listed here.
+ */
+interface ScanResultBridge {
+    /** Discovered file paths (absolute). */
+    readonly files: ReadonlyArray<string>;
+    /** Optional scan timestamp (ms since epoch). */
+    readonly timestamp?: number;
+}
+/**
+ * Options for converting a scan result into planner inputs.
+ */
+interface ScanToPlanOptions {
+    /** Resolved rules produced by the rule resolver (Phase 1.5). */
+    readonly rules: ReadonlyMap<string, ResolvedRule>;
+    /** Absolute path to the project root. */
+    readonly rootDir: string;
+    /** Optional cache context for persistent plan and result caching. */
+    readonly cache?: CacheContext;
+    /** Debug mode: emit detailed timing output to the planner logger. */
+    readonly debug?: boolean;
+    /** Options for incremental (cache-based) task filtering. */
+    readonly incremental?: IncrementalFilterOptions;
+    /**
+     * Version context for cache key generation. Strongly recommended for
+     * production use — omitting risks stale cache hits after a tool upgrade.
+     */
+    readonly cacheKeyCtx?: CacheKeyContext;
+    /**
+     * File count threshold above which task-building switches to parallel
+     * worker threads. Forwarded verbatim to `ExecutionPlanOptions`.
+     * @default 10000
+     */
+    readonly parallelThreshold?: number;
+    /**
+     * Number of worker threads used in parallel mode.
+     * @default 4
+     */
+    readonly workerCount?: number;
+}
+/**
+ * Converts a `ScanResult` (from `@ngcompass/scanner`) into an
+ * `ExecutionPlanOptions` object ready to pass to `buildExecutionPlan`.
+ *
+ * @example
+ * ```typescript
+ * import { scan } from '@ngcompass/scanner';
+ * import { buildExecutionPlan } from '@ngcompass/planner';
+ * import { scanResultToPlanInput } from '@ngcompass/planner/integration';
+ *
+ * const scanResult = await scan({ rootDir: '.', include: [], exclude: [] });
+ * if (!scanResult.ok) throw scanResult.error;
+ *
+ * const planOptions = scanResultToPlanInput(scanResult.data, {
+ *   rules,
+ *   rootDir: '.',
+ *   cache,
+ * });
+ *
+ * const plan = await buildExecutionPlan(planOptions);
+ * ```
+ *
+ * @param scanResult - Result of a successful `scan()` call.
+ * @param opts       - Planner configuration (rules, rootDir, cache, …).
+ * @returns           `ExecutionPlanOptions` ready for `buildExecutionPlan`.
+ */
+declare const scanResultToPlanInput: (scanResult: ScanResultBridge, opts: ScanToPlanOptions) => ExecutionPlanOptions;
+/**
+ * Returns `true` if the scan produced at least one file that the planner
+ * can operate on (i.e. the file list is non-empty).
+ *
+ * Useful as a fast guard before calling `buildExecutionPlan`.
+ *
+ * @param scanResult - Bridge-compatible scan result.
+ */
+declare const hasScanFiles: (scanResult: ScanResultBridge) => boolean;
+/**
+ * Returns the discovered file count from a scan result.
+ *
+ * @param scanResult - Bridge-compatible scan result.
+ */
+declare const getScanFileCount: (scanResult: ScanResultBridge) => number;
+
+export { type CacheFilterStats, type CachePruneOptions, type ExecutionIndexes, type ExecutionPlan, type ExecutionPlanOptions, type ExecutionPlanOutput, type ExecutionStats, type FileAnalysisUnit, type FileInfo, type FileInput, type FileType, type IncrementalFilterOptions, type IncrementalPlan, type ResourceType, type RuleTask, type ScanResultBridge, type ScanToPlanOptions, type Task, type TaskInputs, areAllTasksCached, buildExecutionPlan, buildIndexes, buildTask, buildTasksForFileTaskCentric as buildTasksForFile, calculateFileHash, detectFileType, discoverResources, filterCachedTasks, filterRulesByAstRequirement, getBaseName, getCacheHitRate, getExecutionPlanSummary, getFilesForRules, getScanFileCount, getSpecFile, getStyleFiles, getTasksCountBySeverity, getTemplateFile, getTotalTasks, groupRulesByDependencyType, groupTasksByFile, hasScanFiles, hashFile, hashFileStats, hashFiles, hashRules, hashTaskInputs, isComponentFile, isSpecFile, isStyleFile, isTemplateFile, isTypeScriptFile, pruneStaleCache, resourceExists, scanResultToPlanInput, shouldApplyRule };