@ngcompass/ast 0.1.1-beta

package/dist/index.d.cts

@@ -0,0 +1,523 @@
+import { Program } from 'oxc-parser';
+
+/**
+ * Minimal AST Type Definitions (Zero-Copy, ESTree-like)
+ *
+ * These types match Oxc's ESTree-compatible AST structure.
+ * Only include fields we actually use to minimize overhead.
+ */
+interface Node {
+    readonly type: string;
+    readonly span?: {
+        start: number;
+        end: number;
+    };
+    readonly start?: number;
+    readonly end?: number;
+}
+interface Identifier extends Node {
+    readonly type: 'Identifier';
+    readonly name: string;
+}
+interface Decorator extends Node {
+    readonly type: 'Decorator';
+    readonly expression?: CallExpression | Identifier;
+}
+interface CallExpression extends Node {
+    readonly type: 'CallExpression';
+    readonly callee: Expression;
+    readonly arguments: ReadonlyArray<Expression>;
+}
+interface NewExpression extends Node {
+    readonly type: 'NewExpression';
+    readonly callee: Expression;
+    readonly arguments: ReadonlyArray<Expression>;
+}
+interface MemberExpression extends Node {
+    readonly type: 'MemberExpression' | 'StaticMemberExpression';
+    readonly object: Expression;
+    readonly property: Identifier;
+}
+interface ObjectExpression extends Node {
+    readonly type: 'ObjectExpression';
+    readonly properties: ReadonlyArray<ObjectProperty | SpreadElement>;
+}
+interface ObjectProperty extends Node {
+    readonly type: 'ObjectProperty' | 'Property';
+    readonly key: Expression;
+    readonly value: Expression;
+}
+interface SpreadElement extends Node {
+    readonly type: 'SpreadElement';
+}
+interface ArrayExpression extends Node {
+    readonly type: 'ArrayExpression';
+    readonly elements: ReadonlyArray<Expression | SpreadElement | null>;
+}
+interface StringLiteral extends Node {
+    readonly type: 'StringLiteral' | 'Literal';
+    readonly value: string;
+}
+interface BooleanLiteral extends Node {
+    readonly type: 'BooleanLiteral' | 'Literal';
+    readonly value: boolean;
+}
+interface ArrowFunctionExpression extends Node {
+    readonly type: 'ArrowFunctionExpression';
+    readonly body: Expression | BlockStatement;
+    readonly expression: boolean;
+}
+interface FunctionExpression extends Node {
+    readonly type: 'FunctionExpression';
+    readonly body: BlockStatement;
+}
+interface BlockStatement extends Node {
+    readonly type: 'BlockStatement';
+    readonly body: ReadonlyArray<Node>;
+}
+interface ExpressionStatement extends Node {
+    readonly type: 'ExpressionStatement';
+    readonly expression: Expression;
+}
+interface AssignmentExpression extends Node {
+    readonly type: 'AssignmentExpression';
+    readonly left: Expression;
+    readonly right: Expression;
+    readonly operator: string;
+}
+interface UpdateExpression extends Node {
+    readonly type: 'UpdateExpression';
+    readonly operator: string;
+    readonly argument: Expression;
+    readonly prefix: boolean;
+}
+interface IfStatement extends Node {
+    readonly type: 'IfStatement';
+    readonly test: Expression;
+    readonly consequent: Node;
+    readonly alternate?: Node;
+}
+interface ReturnStatement extends Node {
+    readonly type: 'ReturnStatement';
+    readonly argument?: Expression;
+}
+interface ClassDeclaration extends Node {
+    readonly type: 'ClassDeclaration';
+    readonly id?: Identifier;
+    readonly decorators?: ReadonlyArray<Decorator>;
+    readonly body?: ClassBody;
+}
+interface ClassBody extends Node {
+    readonly type: 'ClassBody';
+    readonly body: ReadonlyArray<PropertyDefinition | MethodDefinition>;
+}
+interface PropertyDefinition extends Node {
+    readonly type: 'PropertyDefinition';
+    readonly key: Expression;
+    readonly value?: Expression;
+    readonly decorators?: ReadonlyArray<Decorator>;
+}
+interface MethodDefinition extends Node {
+    readonly type: 'MethodDefinition';
+    readonly key: Expression;
+}
+interface TemplateBlock extends Node {
+    readonly type: 'Block';
+    readonly name: string;
+    readonly parameters: ReadonlyArray<TemplateBlockParameter>;
+    readonly children: ReadonlyArray<Node>;
+}
+interface TemplateBlockParameter extends Node {
+    readonly type: 'BlockParameter';
+    readonly expression: string;
+}
+type Expression = Identifier | CallExpression | NewExpression | MemberExpression | ObjectExpression | ArrayExpression | StringLiteral | BooleanLiteral | ArrowFunctionExpression | FunctionExpression | AssignmentExpression | UpdateExpression | TemplateBlock | TemplateBlockParameter | Node;
+
+/**
+ * AST Matchers (Zero-Allocation, Pure Functions)
+ *
+ * PERFORMANCE RULES:
+ * - No object creation in hot paths
+ * - No array allocations
+ * - No string concatenation
+ * - Return primitives or pre-existing references only
+ *
+ * "Unsafe" suffix convention: May return undefined, caller must handle.
+ */
+
+/**
+ * Checks if a node has a specific decorator.
+ *
+ * @returns boolean (primitive, zero allocation)
+ */
+declare const hasDecorator: (classNode: ClassDeclaration, decoratorName: string) => boolean;
+/**
+ * Gets decorator name (unsafe: may return undefined).
+ *
+ * PERFORMANCE: Returns string reference from AST (zero copy).
+ * Rules must handle undefined.
+ */
+declare const getDecoratorNameUnsafe: (decorator: Decorator) => string | undefined;
+/**
+ * Gets first decorator argument if it's an object literal.
+ *
+ * PERFORMANCE: Returns AST reference (zero copy).
+ */
+declare const getDecoratorObjectArgUnsafe: (decorator: Decorator) => ObjectExpression | undefined;
+/**
+ * Checks if object has a property with given key.
+ *
+ * PERFORMANCE: No allocation, early return.
+ */
+declare const hasObjectProperty: (objectExpr: ObjectExpression, keyName: string) => boolean;
+/**
+ * Gets property value by key name (unsafe: may return undefined).
+ *
+ * PERFORMANCE: Returns AST reference (zero copy).
+ */
+declare const getObjectPropertyUnsafe: (objectExpr: ObjectExpression, keyName: string) => Expression | undefined;
+/**
+ * Gets key name from object key (unsafe).
+ *
+ * PERFORMANCE: Returns string reference from AST.
+ */
+declare const getKeyNameUnsafe: (key: Expression) => string | undefined;
+/**
+ * Checks if member expression matches pattern (e.g., ChangeDetectionStrategy.OnPush).
+ *
+ * PERFORMANCE: No allocation, early return.
+ */
+declare const matchesMemberExpression: (expr: Expression, objectName: string, propertyName: string) => boolean;
+/**
+ * Gets literal string value (unsafe: may return undefined).
+ *
+ * PERFORMANCE: Returns string reference from AST.
+ */
+declare const getLiteralStringValueUnsafe: (node: Expression) => string | undefined;
+/**
+ * Gets literal boolean value (unsafe: may return undefined).
+ *
+ * PERFORMANCE: Returns boolean primitive from AST.
+ */
+declare const getLiteralBooleanValueUnsafe: (node: Expression) => boolean | undefined;
+/**
+ * Checks if expression is an Angular input() signal call.
+ */
+declare const isInputSignal: (expr: Expression) => boolean;
+/**
+ * Extracts alias from input() signal call if present.
+ */
+declare const getInputSignalAliasUnsafe: (callExpr: CallExpression) => string | undefined;
+
+type LiteralValue<T> = {
+    readonly kind: 'literal';
+    readonly value: T;
+};
+type NonLiteralValue = {
+    readonly kind: 'non-literal';
+};
+type MissingValue = {
+    readonly kind: 'missing';
+};
+type MetadataValue<T> = LiteralValue<T> | NonLiteralValue | MissingValue;
+declare enum ChangeDetectionStrategy {
+    Default = 0,
+    OnPush = 1
+}
+interface HostDirectiveMetadata {
+    readonly directive: string | undefined;
+    readonly inputs: ReadonlyArray<{
+        readonly internal: string;
+        readonly external: string;
+    }>;
+    readonly outputs: ReadonlyArray<{
+        readonly internal: string;
+        readonly external: string;
+    }>;
+}
+interface ComponentMetadata {
+    readonly className: string | undefined;
+    readonly selector: MetadataValue<string>;
+    readonly changeDetection: MetadataValue<ChangeDetectionStrategy>;
+    readonly standalone: MetadataValue<boolean>;
+    readonly templateUrl: MetadataValue<string>;
+    readonly template: MetadataValue<string>;
+    readonly hostDirectives: MetadataValue<ReadonlyArray<HostDirectiveMetadata>>;
+    readonly decoratorStart: number;
+    readonly type: 'Component' | 'Directive';
+}
+interface CacheStatsAccumulator {
+    hits: number;
+    misses: number;
+}
+declare const getComponentCacheStats: () => Readonly<CacheStatsAccumulator>;
+declare const resetComponentCacheStats: () => void;
+/**
+ * Analyzes @Component / @Directive decorator metadata.
+ * Returns null if the class has neither decorator.
+ * Results are cached in a WeakMap — O(1) on subsequent calls.
+ */
+declare const analyzeComponent: (classNode: ClassDeclaration) => ComponentMetadata | null;
+declare const isComponent: (classNode: ClassDeclaration) => boolean;
+declare const usesOnPush: (classNode: ClassDeclaration) => boolean;
+declare const isStandalone: (classNode: ClassDeclaration) => boolean;
+
+/**
+ * Node Streams (Pre-Filtered Semantic Dispatch)
+ *
+ * PERFORMANCE RULE:
+ * Rules must subscribe to the most specific stream possible.
+ *
+ * FORBIDDEN:
+ * - Rules checking "is this a component?" (use AngularClassStream)
+ * - Rules checking "is this decorated?" (use DecoratedPropertyStream)
+ * - Rules checking node types (dispatcher handles this)
+ */
+
+interface TemplateExpressionNode {
+    readonly expression: Expression;
+    readonly sourceSpan: {
+        start: number;
+        end: number;
+    };
+}
+interface TemplateAttributeNode {
+    readonly name: string;
+    readonly value?: string;
+    readonly sourceSpan: {
+        start: number;
+        end: number;
+    };
+}
+interface TemplateBlockNode {
+    readonly name: string;
+    readonly parameters: ReadonlyArray<{
+        readonly expression: string;
+        readonly sourceSpan: {
+            start: number;
+            end: number;
+        };
+    }>;
+    readonly sourceSpan: {
+        start: number;
+        end: number;
+    };
+}
+interface TemplateAnalysis {
+    readonly expressions: ReadonlyArray<TemplateExpressionNode>;
+    readonly attributes: ReadonlyArray<TemplateAttributeNode>;
+    readonly blocks: ReadonlyArray<TemplateBlockNode>;
+}
+/**
+ * Angular Decorator Stream: ClassDeclaration nodes with @Component or @Directive.
+ *
+ * Rules subscribing to this stream are guaranteed:
+ * - Node is a ClassDeclaration
+ * - Node has @Component or @Directive decorator
+ * - Metadata is pre-analyzed and cached
+ */
+interface AngularClassNode {
+    readonly node: ClassDeclaration;
+    readonly metadata: ComponentMetadata;
+}
+/**
+ * Any Angular Decorated Class Stream: ClassDeclaration nodes with ANY Angular decorator.
+ *
+ * Rules subscribing to this stream are guaranteed:
+ * - Node is a ClassDeclaration
+ * - Node has at least one of: @Component, @Directive, @Pipe, @Injectable, @NgModule
+ *
+ * Use this when the rule applies beyond @Component/@Directive (e.g. naming rules
+ * for pipes, services, or guards).
+ */
+interface AnyAngularClassNode {
+    readonly node: ClassDeclaration;
+    readonly decoratorName: string;
+    readonly className: string | undefined;
+    readonly decoratorStart: number;
+}
+/**
+ * Decorated Property Stream: PropertyDefinition nodes with decorators.
+ *
+ * Rules subscribing to this stream are guaranteed:
+ * - Node is a PropertyDefinition
+ * - Node has at least one decorator (@Input, @Output, @ViewChild, etc.)
+ */
+interface DecoratedPropertyNode {
+    readonly node: PropertyDefinition;
+    readonly decorators: ReadonlyArray<Decorator>;
+}
+/**
+ * Filters ClassDeclaration nodes to Angular components or directives.
+ *
+ * PERFORMANCE: O(1) after first call (cached).
+ * Called by engine during traversal, not by rules.
+ */
+declare const toAngularClassStream: (classNode: ClassDeclaration) => AngularClassNode | null;
+/**
+ * Filters ClassDeclaration nodes to ANY Angular-decorated class.
+ *
+ * PERFORMANCE: O(D) where D = number of decorators on the class (usually 1).
+ * Called by engine during traversal, not by rules.
+ */
+declare const toAnyAngularClassStream: (classNode: ClassDeclaration) => AnyAngularClassNode | null;
+/**
+ * Filters PropertyDefinition nodes to decorated properties.
+ *
+ * PERFORMANCE: O(1) decorator array access.
+ * Called by engine, not by rules.
+ */
+declare const toDecoratedPropertyStream: (propertyNode: PropertyDefinition) => DecoratedPropertyNode | null;
+/**
+ * Pass-through filter for CallExpression stream.
+ */
+declare const toCallExpressionStream: (node: CallExpression) => CallExpression;
+/**
+ * Pass-through filter for NewExpression stream.
+ */
+declare const toNewExpressionStream: (node: NewExpression) => NewExpression;
+
+interface HtmlParserResult$1 {
+    rootNodes: readonly unknown[];
+}
+
+declare const analyzeTemplate: (htmlResult: HtmlParserResult$1) => {
+    expressions: TemplateExpressionNode[];
+    attributes: TemplateAttributeNode[];
+    blocks: TemplateBlockNode[];
+};
+
+interface TsParserResult {
+    program: Program;
+    errors: unknown[];
+}
+/**
+ * Parses TypeScript / TSX source code using Oxc.
+ *
+ * @param content - Source text
+ * @param filePath - Source filename (used for diagnostics)
+ * @returns Parsed program and parse errors
+ */
+declare const parseTs: (content: string, filePath: string) => TsParserResult;
+
+interface HtmlParserResult {
+    rootNodes: unknown[];
+    errors: unknown[];
+    /**
+     * Byte offset in the *source file* where the template content begins.
+     *
+     * - For external `.html` files this is always `0` — the HTML file is the
+     *   template, so its offsets are already file-absolute.
+     * - For inline templates inside a `.ts` file this is the position of the
+     *   first content character (right after the opening quote/backtick) in
+     *   the TypeScript source.
+     *
+     * Template rules MUST add this value to `node.sourceSpan.start` before
+     * calling `context.locator.location()` so that reported line/column
+     * numbers are correct for both inline and external templates.
+     */
+    templateStartOffset: number;
+}
+/**
+ * Parses Angular HTML template source.
+ *
+ * @param content             - Template source text (content only, no surrounding quotes)
+ * @param templateStartOffset - Byte offset in the original source file where
+ *                              `content[0]` lives. Use `0` for external `.html`
+ *                              files; supply the value from `extractTemplateFromProgram`
+ *                              for inline templates in `.ts` files.
+ * @returns Parsed root nodes, parse errors, and the start offset.
+ */
+declare const parseHtml: (content: string, templateStartOffset?: number) => HtmlParserResult;
+
+interface CssParserResult {
+    code: Buffer | Uint8Array;
+    map?: Buffer | Uint8Array | void;
+}
+/**
+ * Result type for CSS parsing and validation.
+ */
+type CssResult = {
+    ok: true;
+    code: Buffer | Uint8Array;
+    map?: Buffer | Uint8Array | void;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Parses and validates CSS using Lightning CSS.
+ *
+ * @param content - CSS source text
+ * @param filePath - Source filename for diagnostics
+ * @returns CssResult with transformed output or an error
+ */
+declare const parseCss: (content: string, filePath: string) => CssResult;
+
+/**
+ * Template Extractor
+ *
+ * Extracts the inline template string from an Oxc-parsed TypeScript program.
+ * Moved from orchestrator.ts to make it independently testable and reusable.
+ *
+ * Uses walkProgram() (the shared visitor) instead of a hand-rolled recursion,
+ * which is consistent with how the rules engine traverses the AST and
+ * benefits from the same early-exit optimisation (returning false stops descent).
+ *
+ * Handles both:
+ *  - StringLiteral:   template: '<h1>Hello</h1>'
+ *  - TemplateLiteral: template: `<h1>{{ name }}</h1>`
+ */
+
+/**
+ * Result of extracting an inline template from a TypeScript program.
+ */
+interface ExtractedTemplate {
+    /** The raw HTML content of the template (no surrounding quotes/backticks). */
+    readonly content: string;
+    /**
+     * Byte offset in the TypeScript source file where `content[0]` lives.
+     *
+     * This is used to convert template-relative offsets (produced by the HTML
+     * parser, which only sees the template content) back into file-absolute
+     * offsets (required by `Locator.location()`).
+     *
+     * For external .html files this value is always 0 — the HTML file IS the
+     * template, so its offsets are already file-absolute.
+     */
+    readonly startOffset: number;
+}
+/**
+ * Extracts the inline template string from the first @Component class found
+ * in the given Oxc program.
+ *
+ * @param program - Oxc-parsed Program node
+ * @returns ExtractedTemplate with content and its start offset in the file,
+ *          or `{ content: '', startOffset: 0 }` if no template was found.
+ */
+declare function extractTemplateFromProgram(program: Program): ExtractedTemplate;
+
+interface TraversableNode {
+    readonly type: string;
+}
+/**
+ * Iterative pre-order DFS walker for Oxc AST.
+ *
+ * Replaces the previous recursive implementation to eliminate two hotpath costs:
+ *   1. Call-stack overflow risk on deeply nested ASTs (large files with many nested
+ *      arrow functions, ternaries, optional chaining, etc.).
+ *   2. `Object.keys()` allocation on every node — on a 10 000-node AST that was
+ *      10 000 short-lived string arrays per file. `for...in` iterates without
+ *      allocating the intermediate array.
+ *
+ * Traversal order: identical to the recursive version (pre-order DFS, children
+ * visited in property-key insertion order). The engine relies only on the guarantee
+ * that every node is visited; it does NOT depend on parent-before-child ordering
+ * beyond what pre-order naturally provides.
+ *
+ * @param root    - The Program (or any sub-tree root) to walk
+ * @param visitor - Called for each node. Return `false` to skip that node's children.
+ */
+declare function walkProgram(root: TraversableNode | null | undefined, visitor: (node: TraversableNode) => void | boolean): void;
+
+export { type AngularClassNode, type AnyAngularClassNode, type ArrayExpression, type ArrowFunctionExpression, type AssignmentExpression, type BlockStatement, type BooleanLiteral, type CallExpression, ChangeDetectionStrategy, type ClassBody, type ClassDeclaration, type ComponentMetadata, type CssParserResult, type CssResult, type DecoratedPropertyNode, type Decorator, type Expression, type ExpressionStatement, type ExtractedTemplate, type FunctionExpression, type HtmlParserResult, type Identifier, type IfStatement, type LiteralValue, type MemberExpression, type MetadataValue, type MethodDefinition, type MissingValue, type NewExpression, type Node, type NonLiteralValue, type ObjectExpression, type ObjectProperty, type PropertyDefinition, type ReturnStatement, type SpreadElement, type StringLiteral, type TemplateAnalysis, type TemplateAttributeNode, type TemplateBlock, type TemplateBlockNode, type TemplateBlockParameter, type TemplateExpressionNode, type TsParserResult, type UpdateExpression, analyzeComponent, analyzeTemplate, extractTemplateFromProgram, getComponentCacheStats, getDecoratorNameUnsafe, getDecoratorObjectArgUnsafe, getInputSignalAliasUnsafe, getKeyNameUnsafe, getLiteralBooleanValueUnsafe, getLiteralStringValueUnsafe, getObjectPropertyUnsafe, hasDecorator, hasObjectProperty, isComponent, isInputSignal, isStandalone, matchesMemberExpression, parseCss, parseHtml, parseTs, resetComponentCacheStats, toAngularClassStream, toAnyAngularClassStream, toCallExpressionStream, toDecoratedPropertyStream, toNewExpressionStream, usesOnPush, walkProgram };