@ngcompass/common 0.1.1-beta

package/dist/index.d.ts

@@ -0,0 +1,975 @@
+import * as typescript from 'typescript';
+import typescript__default from 'typescript';
+import { Program } from 'oxc-parser';
+
+/**
+ * Constants used across packages
+ */
+declare const TOOL_NAME = "ngcompass";
+declare const PACKAGE_VERSION = "v.0.1.1-beta";
+declare const CACHE_VERSION = "1.0.0";
+declare const CONFIG_FILE_NAMES: readonly [".ngcompassrc.json", ".ngcompassrc.js", ".ngcompass.config.js", "ngcompass.config.json"];
+declare const DEFAULT_CACHE_DIR = "node_modules/.cache/ngcompass";
+declare const DEFAULT_INCLUDE_PATTERNS: readonly ["**/*.ts", "**/*.html"];
+declare const DEFAULT_EXCLUDE_PATTERNS: readonly ["**/node_modules/**", "**/dist/**", "**/build/**", "**/*.spec.ts", "**/*.test.ts"];
+declare const SUPPORTED_ANGULAR_VERSIONS: {
+    readonly min: 12;
+    readonly max: 21;
+};
+
+/**
+ * Helper to map string offsets to line/column numbers.
+ */
+declare class Locator {
+    private readonly lines;
+    constructor(content: string);
+    location(offset: number): {
+        line: number;
+        column: number;
+    };
+}
+
+/**
+ * Custom error types
+ */
+declare class AnalyzerError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+declare class ConfigurationError extends AnalyzerError {
+    constructor(message: string);
+}
+declare class ParseError extends AnalyzerError {
+    readonly filePath: string;
+    constructor(message: string, filePath: string);
+}
+declare class RuleError extends AnalyzerError {
+    readonly ruleId: string;
+    constructor(message: string, ruleId: string);
+}
+/**
+ * Thrown when a rule handler crashes during execution.
+ *
+ * Unlike ParseError (which is collected and surfaced as a warning),
+ * RuleExecutionError indicates a bug in the rule itself and is re-thrown
+ * so the caller can decide whether to fail loudly or skip the rule.
+ */
+declare class RuleExecutionError extends AnalyzerError {
+    readonly ruleName: string;
+    readonly filePath: string;
+    constructor(ruleName: string, filePath: string, cause: unknown);
+}
+/**
+ * Categories of infrastructure failures that can occur during analysis.
+ *
+ *  ParseError        — AST parsing failed for a source file
+ *  IOError           — File read / write failed
+ *  WorkerCrash       — A worker thread exited with a non-zero code
+ *  CacheCorruption   — A cached entry could not be deserialized
+ *  SerializationError — stableSerialize() threw (indicates a rule authoring bug)
+ */
+type InfrastructureErrorType = 'ParseError' | 'IOError' | 'WorkerCrash' | 'CacheCorruption' | 'SerializationError' | 'RuleExecutionError';
+/**
+ * Structured record of an infrastructure failure.
+ *
+ * recoverable: true  → the pipeline can continue (file is skipped / cold rebuild)
+ * recoverable: false → the pipeline cannot produce correct results and should abort
+ *                      and should abort the current run.
+ */
+interface InfrastructureError {
+    readonly type: InfrastructureErrorType;
+    readonly filePath?: string;
+    readonly cause: string;
+    readonly timestamp: number;
+    readonly recoverable: boolean;
+    readonly phase: 'config' | 'planner' | 'engine';
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Factory that stamps a timestamp and freezes the error object.
+ */
+declare function createInfrastructureError(type: InfrastructureErrorType, fields: Omit<InfrastructureError, 'type' | 'timestamp'>): InfrastructureError;
+/**
+ * Per-run accumulator of infrastructure errors.
+ *
+ * Passed through the pipeline so callers can inspect failures at the end
+ * after execution completes.
+ */
+declare class InfrastructureErrorCollector {
+    private readonly _errors;
+    record(error: InfrastructureError): void;
+    get errors(): ReadonlyArray<InfrastructureError>;
+    get hasFatalErrors(): boolean;
+    get hasAnyErrors(): boolean;
+    /** Returns only errors in a specific phase. */
+    forPhase(phase: InfrastructureError['phase']): ReadonlyArray<InfrastructureError>;
+}
+
+/**
+ * Violation severity levels:
+ *
+ *   error  — hard-constraint violations that should block CI / fail the run.
+ *   warn   — advisory violations surfaced as warnings.
+ */
+type Severity = 'warn' | 'error';
+/**
+ * Rule categories for organization
+ */
+declare enum RuleCategory {
+    Architecture = "architecture",
+    Performance = "performance",
+    SSR = "ssr",
+    Security = "security",
+    Accessibility = "accessibility",
+    Testing = "testing",
+    CodeSmell = "code-smell",
+    Reactivity = "reactivity",
+    BestPractice = "best-practice"
+}
+/**
+ * Result type for functional error handling
+ */
+type Result<T, E = Error> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Creates a successful result
+ */
+declare const Ok: <T>(data: T) => Result<T, never>;
+/**
+ * Creates a failed result
+ */
+declare const Err: <E>(error: E) => Result<never, E>;
+/**
+ * Rule severity levels
+ */
+type RuleSeverity = Severity | 'off';
+/**
+ * Short-hand rule configuration (just severity)
+ */
+type RuleConfigShorthand = RuleSeverity;
+/**
+ * Full rule configuration (severity + options)
+ */
+interface RuleConfigFull {
+    readonly severity: RuleSeverity;
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Rule configuration (either shorthand or full)
+ */
+type RuleConfig = RuleConfigShorthand | RuleConfigFull;
+/**
+ * Rules object (ruleName → config)
+ */
+type RulesConfig = Readonly<Record<string, RuleConfig>>;
+/**
+ * Dependency types for rules
+ */
+type RuleDependencyType = 'standalone' | 'component' | 'styles' | 'imports' | 'spec';
+/**
+ * AST requirements for a rule
+ */
+interface RuleAstRequirements {
+    readonly tsAst?: boolean;
+    readonly htmlAst?: boolean;
+    readonly cssAst?: boolean;
+    readonly specAst?: boolean;
+    readonly typeChecker?: boolean;
+    /**
+     * Set to `true` when the rule needs the project-wide import graph,
+     * component → template mapping, or other cross-file metadata provided
+     * by `ProjectContext`.
+     *
+     * Rules declaring this are routed to the type-aware execution path (main
+     * thread) so they always receive a populated `context.project`.
+     * Implies `typeChecker` for routing purposes (the TypeScript Program is
+     * required to build the import graph).
+     */
+    readonly projectContext?: boolean;
+}
+/**
+ * File type patterns a rule applies to
+ */
+interface RuleFilePatterns {
+    readonly include?: ReadonlyArray<string>;
+    readonly exclude?: ReadonlyArray<string>;
+}
+/**
+ * Rule metadata (describes rule behavior)
+ */
+interface RuleMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly category: string;
+    readonly dependencyType: RuleDependencyType;
+    readonly requires: RuleAstRequirements;
+    readonly filePatterns?: RuleFilePatterns;
+}
+/**
+ * Resolved rule (config + metadata)
+ */
+interface ResolvedRule {
+    readonly name: string;
+    readonly severity: RuleSeverity;
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly metadata: RuleMetadata;
+}
+/**
+ * Map of resolved rules
+ */
+type ResolvedRulesMap = ReadonlyMap<string, ResolvedRule>;
+/**
+ * Preset configuration file structure
+ */
+interface PresetConfig {
+    readonly name: string;
+    readonly description?: string;
+    readonly extends?: string | ReadonlyArray<string>;
+    readonly rules: RulesConfig;
+}
+/**
+ * Built-in preset names
+ */
+type BuiltinPreset = 'recommended' | 'strict' | 'performance' | 'reactivity' | 'security' | 'ssr' | 'all';
+/**
+ * Preset reference (builtin or file path)
+ */
+type PresetReference = string;
+/**
+ * Rule resolution result
+ */
+interface RuleResolutionResult {
+    readonly rules: ResolvedRulesMap;
+    readonly metadata: {
+        readonly totalRules: number;
+        readonly enabledRules: number;
+        readonly disabledRules: number;
+        readonly presetsLoaded: ReadonlyArray<string>;
+        readonly resolutionTime: number;
+    };
+}
+/**
+ * Rule registry entry (for looking up metadata)
+ */
+interface RuleRegistryEntry {
+    readonly name: string;
+    readonly metadata: RuleMetadata;
+    readonly defaultConfig: RuleConfigFull;
+}
+/**
+ * Rule registry (ruleName → entry)
+ */
+type RuleRegistryMap = ReadonlyMap<string, RuleRegistryEntry>;
+interface RegisterOptions {
+    allowOverride?: boolean;
+}
+interface RulePlugin {
+    readonly name: string;
+    /**
+     * The rule handler. Typed as `unknown` here because `@ngcompass/common`
+     * cannot import `RuleHandler` from `@ngcompass/engine` (would create a
+     * circular dependency). Call sites in `@ngcompass/rules` narrow this to
+     * `RuleHandler<unknown>` when registering.
+     */
+    readonly handler: unknown;
+    readonly meta?: Partial<RuleMetadata>;
+    readonly manifest?: PluginManifest;
+}
+interface RuleRegistry {
+    register(plugin: RulePlugin, opts?: RegisterOptions): void;
+    get(name: string): unknown;
+    has(name: string): boolean;
+    getRuleNames(): ReadonlyArray<string>;
+    getAll(): ReadonlyMap<string, unknown>;
+    getMeta(name: string): Partial<RuleMetadata> | undefined;
+    getMetadata(name: string): RuleMetadata | undefined;
+    getRegistryEntry(name: string): RuleRegistryEntry | undefined;
+    toReadonlyMap(): ReadonlyMap<string, RuleRegistryEntry>;
+    readonly size: number;
+}
+/**
+ * A single entry in the rules list output.
+ * Consumed by the RulesReporter to render a grouped, filterable rule catalog.
+ */
+interface RuleListEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly domain: string;
+    readonly severity: string;
+    readonly presets: readonly string[];
+}
+interface RuleFailure {
+    readonly filePath: string;
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+    readonly severity: RuleSeverity;
+    readonly ruleName: string;
+    /**
+     * Optional actionable fix recommendation shown in reporter output.
+     * Plain English description of how to resolve the violation.
+     * Example: "Add standalone: true to @Component({ ... })"
+     */
+    readonly fix?: string;
+    /**
+     * Optional multi-line code snippet illustrating the correct pattern.
+     * Displayed below the fix recommendation when no auto-fix is available.
+     * Use plain TypeScript — no ANSI codes.
+     */
+    readonly codeExample?: string;
+}
+interface RuleResult {
+    readonly ruleName: string;
+    readonly failures: ReadonlyArray<RuleFailure>;
+    readonly taskId?: string;
+}
+/**
+ * Minimal parsed template AST handed to rules via `RuleContext.template`.
+ * Mirrors `@ngcompass/ast`'s `HtmlParserResult` without importing it.
+ *
+ * Rule authors: access `rootNodes` to traverse the Angular HTML tree.
+ * Each node is typed `unknown` here; use `@ngcompass/ast`'s node interfaces
+ * (e.g. `Element`, `Text`, `BoundAttribute`) for narrowing.
+ */
+interface TemplateAst {
+    /** Root-level parsed nodes from the Angular HTML parser. */
+    readonly rootNodes: ReadonlyArray<unknown>;
+    /** Parse errors emitted by the HTML parser (does not throw). */
+    readonly errors: ReadonlyArray<unknown>;
+    /**
+     * Byte offset of the first template character inside the source file.
+     * - External `.html` files: always `0`.
+     * - Inline templates inside `.ts` files: position after the opening quote.
+     * Add this value to node `sourceSpan.start` before calling
+     * `context.locator.location()` to obtain correct line/column numbers.
+     */
+    readonly templateStartOffset: number;
+}
+/**
+ * Minimal parsed style AST handed to rules via `RuleContext.style`.
+ * Mirrors `@ngcompass/ast`'s `CssResult` without importing it.
+ */
+interface StyleAst {
+    /** Whether parsing succeeded. */
+    readonly ok: boolean;
+    /** Transformed CSS bytes — present when `ok` is `true`. */
+    readonly code?: Buffer | Uint8Array;
+    /** Parse/transform error — present when `ok` is `false`. */
+    readonly error?: unknown;
+}
+/**
+ * Component file cluster: the TypeScript class file and its associated
+ * template, styles, and spec (mirrors ComponentNode in @ngcompass/planner
+ * without creating a cross-package dependency).
+ */
+interface ComponentFiles {
+    /** Absolute path to the `.component.ts` file. */
+    readonly tsPath: string;
+    /** Absolute path to the external template file, if any. */
+    readonly templatePath?: string;
+    /** Absolute paths to associated style files. */
+    readonly stylePaths: ReadonlyArray<string>;
+    /** Absolute path to the spec file, if any. */
+    readonly specPath?: string;
+}
+/**
+ * Angular module metadata extracted from `@NgModule` or standalone
+ * `@Component` decorators.  Populated by CTX-004; initially empty.
+ */
+interface NgModuleInfo {
+    /** Absolute path to the module/component file. */
+    readonly filePath: string;
+    /** Class names declared in this module (or standalone imports array). */
+    readonly declarations: ReadonlySet<string>;
+    /** Class names imported by this module/standalone component. */
+    readonly imports: ReadonlySet<string>;
+    /** Class names exported from this module. */
+    readonly exports: ReadonlySet<string>;
+    /** Provider class names registered in this module/component. */
+    readonly providers: ReadonlySet<string>;
+    /** `true` for standalone components; `false` for NgModule-based. */
+    readonly isStandalone: boolean;
+}
+/**
+ * Project-wide, read-only context shared across all rules in a single run.
+ *
+ * Computed once by `buildProjectContext()` (@ngcompass/engine) before task
+ * dispatch and injected into every `RuleContext` for rules that opt-in via
+ * `requires.projectContext: true`.
+ *
+ * All file paths are absolute and normalised with `path.resolve()`.
+ */
+interface ProjectContext {
+    /**
+     * Forward import graph: absolute file path → set of absolute paths it
+     * directly imports (intra-project only; external packages excluded).
+     */
+    readonly importGraph: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Reverse import graph: absolute file path → set of absolute paths that
+     * directly import it.  Enables "who uses this file?" queries in O(1).
+     */
+    readonly reverseImportGraph: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Angular module / standalone component map.  (CTX-004)
+     *
+     * Key:   absolute path to the `@NgModule` or standalone `@Component` file.
+     * Value: `NgModuleInfo` with declarations, imports, exports, providers.
+     *
+     * Populated by scanning all `@NgModule` and `@Component({ standalone: true })`
+     * decorators in the project.  Empty for files that are neither.
+     */
+    readonly ngModuleMap: ReadonlyMap<string, NgModuleInfo>;
+    /**
+     * Set of absolute file paths for all standalone Angular entities.  (CTX-004)
+     *
+     * Includes files that contain `@Component({ standalone: true })`,
+     * `@Directive({ standalone: true })`, or `@Pipe({ standalone: true })`.
+     *
+     * Rules can use this to detect module-based components subject to a
+     * standalone-first migration policy, or to validate that standalone
+     * components only reference dependencies in their own `imports` array.
+     */
+    readonly standaloneComponents: ReadonlySet<string>;
+    /**
+     * Class name → absolute file path resolver.  (CTX-004)
+     *
+     * Maps the name of every exported class in the project to the absolute
+     * path of the file that declares it.  Enables NgModule rules to resolve
+     * the class names stored in `NgModuleInfo.declarations` / `imports` /
+     * `exports` / `providers` to concrete file paths without a linear scan.
+     *
+     * Only directly-exported class declarations are indexed (`export class Foo`);
+     * re-exports through barrel files are not followed.
+     *
+     * Example:
+     *   `project.classToFile.get('FooComponent')` → `'/src/app/foo/foo.component.ts'`
+     */
+    readonly classToFile: ReadonlyMap<string, string>;
+    /**
+     * Component file cluster map.
+     * Key: absolute path to the `.component.ts` file.
+     * Value: associated template, styles, and spec paths.
+     */
+    readonly componentGraph: ReadonlyMap<string, ComponentFiles>;
+    /**
+     * Full set of absolute file paths discovered by the scanner for this run.
+     */
+    readonly projectFiles: ReadonlySet<string>;
+    /** Root directory of the project (absolute, normalised). */
+    readonly rootDir: string;
+    /**
+     * Set of barrel file absolute paths.
+     *
+     * A barrel file is one whose every top-level statement is an
+     * `export … from '…'` re-export declaration (no regular imports,
+     * no class/function/variable declarations).  The canonical example is
+     * an `index.ts` or `public-api.ts` that re-exports sibling modules.
+     *
+     * Rules can use this to skip barrel files (no logic to lint) or to
+     * follow re-export chains when tracing where a symbol is consumed.
+     */
+    readonly barrelFiles: ReadonlySet<string>;
+    /**
+     * External dependency map (CTX-002).
+     *
+     * Key:   absolute path of the project source file.
+     * Value: set of npm package names (scope-aware bare specifiers, e.g.
+     *        `'@angular/core'`, `'rxjs'`) imported by that file.
+     *
+     * Sub-path specifiers are normalised to the package name:
+     *   `'rxjs/operators'`      → `'rxjs'`
+     *   `'@angular/core/rxjs-interop'` → `'@angular/core'`
+     *
+     * Relative imports and absolute paths are excluded.
+     * Entries are only present for files that have at least one external dep —
+     * files with no external deps simply have no entry in the map.
+     */
+    readonly externalDeps: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Reverse map: absolute template file path → absolute component `.ts` path.
+     *
+     * Enables template rules to answer "which component owns this template?"
+     * in O(1) without scanning the whole `componentGraph`.
+     *
+     * Built automatically from `componentGraph` by `buildProjectContext()`.
+     * Only files that have an explicit external template appear here; inline
+     * templates are associated via `componentGraph` keyed on the `.ts` path.
+     */
+    readonly templateToComponent: ReadonlyMap<string, string>;
+}
+/**
+ * Cross-reference between an Angular component and its associated files.
+ *
+ * Attached to `RuleContext.crossRef` for rules running on:
+ *   - `.component.ts` files — gives access to `templatePath`, `stylePaths`,
+ *     `specPath`, and `templateReferences` (members used in the template).
+ *   - `.component.html` template files — gives access to `componentPath`
+ *     and `publicMembers` (members declared on the component class).
+ *
+ * `undefined` for all other file types and when `project` is unavailable.
+ */
+interface ComponentCrossRef {
+    /** Absolute path to the `.component.ts` class file. */
+    readonly componentPath: string;
+    /**
+     * Absolute path to the external template `.html` file.
+     * `undefined` when the component uses an inline `template: '…'` string.
+     */
+    readonly templatePath?: string;
+    /** Absolute paths to associated style files (`.scss`, `.css`, …). */
+    readonly stylePaths: ReadonlyArray<string>;
+    /** Absolute path to the spec file, if any. */
+    readonly specPath?: string;
+    /**
+     * Names of public members (properties and methods) declared directly in
+     * the component class, extracted from the TypeScript `SourceFile`.
+     *
+     * Available in **template rules** to verify that every bound property /
+     * called method actually exists in the component class.
+     *
+     * Populated only when the type-aware execution path is active
+     * (`ts.Program` exists).  Private, protected, and `#private` members are
+     * excluded.
+     */
+    readonly publicMembers?: ReadonlySet<string>;
+    /**
+     * Public class fields that are known Angular signal-like values.
+     *
+     * These are safe to invoke from templates as `name()` because the call reads
+     * signal state rather than executing arbitrary component work.
+     */
+    readonly signalMembers?: ReadonlySet<string>;
+    /**
+     * Identifiers from the template that reference the component — property
+     * reads, method calls, and event-handler expressions whose implicit
+     * receiver is the component instance (`this`).
+     *
+     * Available in **component rules** to detect unused public members (a
+     * member not in this set is likely unreferenced in the template).
+     *
+     * Populated when the template AST is already loaded for the current
+     * analysis batch (i.e. the rule or a peer rule declared `htmlAst: true`).
+     */
+    readonly templateReferences?: ReadonlySet<string>;
+}
+interface RuleContext {
+    /**
+     * Lazily-created TypeScript `SourceFile` for this file.
+     *
+     * Populated on first access by `rule-utils.ts`:`getTsSymbolAtNode()` when a rule
+     * requests TypeChecker-based symbol resolution. Creating a `SourceFile` is O(n)
+     * in source length; caching it here ensures the cost is paid at most once per
+     * file, regardless of how many rules request type information.
+     *
+     * Rule authors: **do not read or write this field directly.** Use
+     * `getTsSymbolAtNode(node, context)` from `rule-utils` instead.
+     */
+    readonly sourceFile?: typescript.SourceFile;
+    readonly filePath: string;
+    readonly fileContent: string;
+    readonly locator: Locator;
+    readonly program?: Program;
+    readonly typeChecker?: typescript.TypeChecker;
+    /**
+     * Parsed template AST — use `rootNodes` to traverse the Angular HTML tree.
+     * Typed as `TemplateAst` (defined above) to avoid a circular dep on `@ngcompass/ast`.
+     */
+    readonly template?: TemplateAst;
+    /**
+     * External template file details used while dispatching template rules.
+     *
+     * Present only when a component rule batch loaded a separate `.html`
+     * template. Template rule execution may use these values so findings point
+     * at the HTML file instead of the owning `.component.ts` file.
+     */
+    readonly templateFilePath?: string;
+    readonly templateFileContent?: string;
+    readonly templateLocator?: Locator;
+    /**
+     * Parsed style AST — check `ok` before accessing `code`.
+     * Typed as `StyleAst` (defined above) to avoid a circular dep on `@ngcompass/ast`.
+     */
+    readonly style?: StyleAst;
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * Project-wide cross-file metadata (import graph, component clusters, …).
+     *
+     * Populated only for rules that declare `requires.projectContext: true`.
+     * `undefined` for all other rules — access is always guarded by an opt-in
+     * flag so there is zero overhead on rules that don't need it.
+     */
+    readonly project?: ProjectContext;
+    /**
+     * Component ↔ template cross-reference (CTX-003).
+     *
+     * Non-`undefined` when `project` is available **and** the file under
+     * analysis is either a `.component.ts` file or its associated template.
+     * Provides structural links (paths) and optional semantic sets
+     * (`publicMembers`, `templateReferences`) at zero extra parse cost for
+     * files that don't match either category.
+     */
+    readonly crossRef?: ComponentCrossRef;
+}
+/**
+ * Analysis aggregate output.
+ */
+interface AnalysisResult {
+    readonly results: ReadonlyArray<RuleResult>;
+    /**
+     * Parse errors encountered during analysis (collected, not thrown).
+     * Allows analysis to continue for other files while surfacing tool errors
+     * separately from rule violations in the reporter output.
+     */
+    readonly parseErrors: ReadonlyArray<ParseError>;
+    readonly stats: {
+        readonly totalFiles: number;
+        readonly totalErrors: number;
+        readonly totalWarnings: number;
+        readonly duration: number;
+        /**
+         * Fraction of tasks whose results were served from cache (0–1).
+         * `undefined` when no cache is in use (e.g. first cold run or worker path).
+         * Consumers can display this as a percentage: `(cacheHitRate * 100).toFixed(1)%`.
+         */
+        readonly cacheHitRate?: number;
+    };
+}
+/** Describes a task that failed inside a worker thread. */
+interface WorkerTaskError {
+    readonly task: {
+        readonly taskId: string;
+    };
+    readonly error: string;
+}
+/** File-level progress event emitted by a worker thread. */
+interface WorkerFileProgress {
+    readonly kind: 'file-progress';
+    readonly filePath: string;
+    readonly taskCount: number;
+    readonly issueCount: number;
+    readonly errorCount: number;
+    readonly warningCount: number;
+    readonly duration: number;
+}
+/** Message posted back from a worker thread to the orchestrator. */
+interface WorkerMessageResult {
+    readonly results: RuleResult[];
+    readonly errors: WorkerTaskError[];
+}
+
+/**
+ * Optional manifest that a plugin can export alongside its rules.
+ *
+ * When present the engine validates:
+ *  - That the current tool version satisfies engineVersionRange
+ *  - That required capabilities (typeInfo, templateAST) are available
+ *
+ * Plugins without a manifest are loaded with a deprecation warning.
+ * Enforcement (hard error on missing manifest) is reserved for the next major.
+ */
+interface PluginManifest {
+    /** Package name (must match the plugin's npm package name) */
+    readonly name: string;
+    /** Plugin semver version (e.g. "2.1.0") */
+    readonly version: string;
+    /** Engine API semver version this plugin was built against */
+    readonly apiVersion: string;
+    /**
+     * Semver range of ngcompass versions this plugin is compatible with.
+     * Examples: ">=1.0.0 <2.0.0",  "^1.2.0",  "*"
+     */
+    readonly engineVersionRange: string;
+    /** Optional capability declarations */
+    readonly capabilities?: {
+        /** Plugin uses the TypeScript type-checker (expensive) */
+        readonly requiresTypeInfo?: boolean;
+        /** Plugin needs the full HTML template AST */
+        readonly requiresTemplateAST?: boolean;
+        /** Plugin needs the CSS/SCSS AST */
+        readonly requiresCssAST?: boolean;
+    };
+}
+/** Minimal telemetry event shape used in config (avoids circular dep with core) */
+interface TelemetryEventBase {
+    readonly phase: 'config' | 'planner' | 'engine';
+    readonly operation: string;
+    readonly durationMs: number;
+    readonly cacheHit?: boolean;
+    readonly workerId?: number;
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+interface TelemetryConfig {
+    /** Whether telemetry collection is active (default: false) */
+    enabled?: boolean;
+    /**
+     * Called synchronously for every emitted event.
+     * Use this to pipe events to a file, stdout, or an external collector.
+     */
+    onEvent?: (event: TelemetryEventBase) => void;
+}
+/**
+ * Reporting output formats
+ */
+type OutputFormat = 'json' | 'text' | 'sarif' | 'html';
+/**
+ * Severity level that triggers failure in CI/build
+ */
+type FailSeverity = Severity;
+/**
+ * TypeScript parser options
+ */
+interface ParserOptions {
+    project?: string;
+    tsconfigRootDir?: string;
+    sourceType?: 'module' | 'commonjs';
+    ecmaVersion?: number;
+}
+/**
+ * Cache configuration options
+ */
+interface CacheOptions {
+    enabled?: boolean;
+    location?: string;
+    strategy?: 'memory' | 'local';
+    ttl?: number;
+}
+/**
+ * Configuration override for specific files
+ * Rules in overrides are merged with global rules
+ */
+interface ConfigOverride {
+    files: string | string[];
+    rules?: Record<string, RuleConfig | Severity | 'off'>;
+}
+/**
+ * Profile-specific configuration (dev/ci)
+ * Profiles can override most settings except nested profiles
+ */
+type ProfileConfig = Partial<Omit<AnalyzerConfig, 'profiles'>>;
+/**
+ * Main analyzer configuration interface
+ * Supports extends, rules, overrides, profiles, and more
+ */
+interface AnalyzerConfig {
+    /**
+     * Extend from other configuration presets
+     */
+    extends?: string | string[];
+    /**
+     * Files to include in analysis
+     */
+    include?: string[];
+    /**
+     * Files to exclude from analysis
+     */
+    exclude?: string[];
+    /**
+     * Maximum number of worker threads for parallel analysis
+     */
+    maxWorkers?: number;
+    /**
+     * Cache configuration
+     */
+    cache?: boolean | CacheOptions;
+    /**
+     * Output format for reports
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * Output file path for report
+     */
+    outputPath?: string;
+    /**
+     * Severity level that causes non-zero exit code
+     */
+    failOnSeverity?: FailSeverity;
+    /**
+     * Maximum number of violations allowed before failing
+     */
+    maxWarnings?: number;
+    /**
+     * Additional patterns to ignore
+     */
+    ignorePatterns?: string[];
+    /**
+     * External rule plugins to load.
+     * Each entry is a package name or file path that exports a RulePlugin or RulePlugin[].
+     * Example: ['@my-org/ngcompass-rules', './tools/local-rules']
+     */
+    plugins?: string[];
+    /**
+     * Rule configuration
+     */
+    rules?: Record<string, RuleConfig | Severity | 'off'>;
+    /**
+     * Per-file rule overrides
+     */
+    overrides?: ConfigOverride[];
+    /**
+     * TypeScript parser configuration
+     */
+    parserOptions?: ParserOptions;
+    /**
+     * Environment-specific profiles
+     */
+    profiles?: Record<string, ProfileConfig>;
+    /**
+     * Structured telemetry collection.
+     * Disabled by default — enabling it adds a small per-event overhead.
+     */
+    telemetry?: TelemetryConfig;
+    /**
+     * Engine execution thresholds.
+     * Override the built-in defaults for parallelism decisions.
+     */
+    engine?: {
+        /**
+         * Number of tasks above which the worker pool is used instead of
+         * local pLimit execution.  Default: 150.
+         */
+        parallelThreshold?: number;
+    };
+}
+/**
+ * Structured configuration issue
+ */
+interface ConfigIssue {
+    readonly code: string;
+    readonly message: string;
+    readonly path?: ReadonlyArray<string | number>;
+    readonly severity: 'error' | 'warning';
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly suggestion?: string;
+}
+/**
+ * Health report for configuration validation
+ */
+interface HealthReport {
+    valid: boolean;
+    issues: ConfigIssue[];
+    config?: unknown;
+}
+/**
+ * Configuration Report (alias for HealthReport)
+ */
+type ConfigReport = HealthReport;
+/**
+ * Result of the configuration initialization
+ */
+interface InitResult {
+    success: boolean;
+    filePath: string;
+    alreadyExists?: boolean;
+}
+interface NormalizedAnalyzerConfig extends Omit<AnalyzerConfig, 'cache' | 'maxWorkers' | 'outputFormat' | 'failOnSeverity' | 'maxWarnings' | 'rules'> {
+    /**
+     * Cache configuration.
+     * Guaranteed to be a full object, never boolean.
+     */
+    cache: Required<CacheOptions>;
+    /**
+     * Maximum number of worker threads.
+     * Defaults to (CPUs - 1) or 1.
+     */
+    maxWorkers: number;
+    /**
+     * Reporting format.
+     */
+    outputFormat: OutputFormat;
+    /**
+     * Severity level for non-zero exit code.
+     */
+    failOnSeverity: FailSeverity;
+    /**
+     * Max allowed warnings.
+     */
+    maxWarnings: number;
+    /**
+     * Resolved rule configuration.
+     */
+    rules: Record<string, RuleConfig | Severity | 'off'>;
+}
+interface ConfigValidationResult {
+    config?: NormalizedAnalyzerConfig;
+    report: HealthReport;
+}
+
+interface Location {
+    line: number;
+    column: number;
+}
+type LocationMap = Record<string, Location>;
+declare class ASTUtils {
+    /**
+     * Parses content into a TypeScript SourceFile.
+     */
+    static parse(content: string, fileName?: string): typescript__default.SourceFile;
+    /**
+     * Generates a map of all property locations in the object.
+     * Keys are dot-notation paths (e.g. "rules.my-rule").
+     */
+    static generateLocationMap(sourceFile: typescript__default.SourceFile): LocationMap;
+    private static getPropertyName;
+}
+
+/**
+ * Global Logger Module
+ *
+ * Provides debug and performance logging capabilities with namespace filtering.
+ * Follows industry standards (ESLint, TypeScript debug patterns).
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type Namespace = 'discovery' | 'loader' | 'validator' | 'cache' | 'scanner' | 'parser' | 'rules' | 'workers' | 'reporter' | 'init' | 'config' | 'planner' | 'incremental' | 'dry-run' | 'engine' | 'plugin-loader' | 'env-fingerprint';
+declare const debug: (namespace: Namespace, message: string, ...args: unknown[]) => void;
+declare const info: (namespace: Namespace, message: string, ...args: unknown[]) => void;
+declare const warn: (namespace: Namespace, message: string, ...args: unknown[]) => void;
+declare const error: (namespace: Namespace, message: string, ...args: unknown[]) => void;
+declare const time: (label: string) => void;
+declare const timeEnd: (label: string) => number;
+declare const timeLog: (label: string, namespace: Namespace, message?: string) => number;
+declare const enableDebug: (level?: LogLevel, namespaces?: Namespace[] | "all") => void;
+declare const disableDebug: () => void;
+declare const isDebugEnabled: () => boolean;
+
+/**
+ * Stable Serialization Utility
+ *
+ * Produces a deterministic JSON string suitable for use in cache keys and hashes.
+ *
+ * Guarantees:
+ *  - Objects: keys sorted alphabetically at every depth level
+ *  - Arrays: elements preserved in insertion order (NOT sorted)
+ *  - undefined values in objects: omitted (same as JSON.stringify)
+ *  - Date: serialized as ISO 8601 string
+ *  - RegExp: serialized as its string representation (e.g. "/abc/gi")
+ *  - Circular references: throws SerializationError (never silently sanitizes)
+ *  - Functions: throws SerializationError
+ *  - NaN / Infinity: throws SerializationError
+ *
+ * This replaces bare JSON.stringify() wherever the insertion order of object
+ * keys must not affect the resulting string (e.g. batch keys, cache keys).
+ */
+declare class SerializationError extends Error {
+    readonly path: string[];
+    constructor(message: string, path: string[]);
+}
+/**
+ * Produces a deterministic JSON string by sorting object keys recursively.
+ *
+ * @param value - The value to serialize
+ * @param _path - Internal: tracks key path for error messages
+ * @param _seen - Internal: tracks visited objects for circular detection
+ * @returns A stable, deterministic JSON string
+ * @throws {SerializationError} on circular references, functions, or non-finite numbers
+ */
+declare function stableSerialize(value: unknown, _path?: string[], _seen?: WeakSet<object>): string;
+
+export { ASTUtils, type AnalysisResult, type AnalyzerConfig, AnalyzerError, type BuiltinPreset, CACHE_VERSION, CONFIG_FILE_NAMES, type CacheOptions, type ComponentCrossRef, type ComponentFiles, type ConfigIssue, type ConfigOverride, type ConfigReport, type ConfigValidationResult, ConfigurationError, DEFAULT_CACHE_DIR, DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS, Err, type FailSeverity, type HealthReport, type InfrastructureError, InfrastructureErrorCollector, type InfrastructureErrorType, type InitResult, type Location, type LocationMap, Locator, type LogLevel, type Namespace, type NgModuleInfo, type NormalizedAnalyzerConfig, Ok, type OutputFormat, PACKAGE_VERSION, ParseError, type ParserOptions, type PluginManifest, type PresetConfig, type PresetReference, type ProjectContext, type RegisterOptions, type ResolvedRule, type ResolvedRulesMap, type Result, type RuleAstRequirements, RuleCategory, type RuleConfig, type RuleConfigFull, type RuleConfigShorthand, type RuleContext, type RuleDependencyType, RuleError, RuleExecutionError, type RuleFailure, type RuleFilePatterns, type RuleListEntry, type RuleMetadata, type RulePlugin, type RuleRegistry, type RuleRegistryEntry, type RuleRegistryMap, type RuleResolutionResult, type RuleResult, type RuleSeverity, type RulesConfig, SUPPORTED_ANGULAR_VERSIONS, SerializationError, type Severity, type StyleAst, TOOL_NAME, type TelemetryConfig, type TelemetryEventBase, type TemplateAst, type WorkerFileProgress, type WorkerMessageResult, type WorkerTaskError, createInfrastructureError, debug, disableDebug, enableDebug, error, info, isDebugEnabled, stableSerialize, time, timeEnd, timeLog, warn };