@taiga-ui/eslint-plugin-experience-next 0.466.0 → 0.467.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ui/eslint-plugin-experience-next",
-  "version": "0.466.0",
+  "version": "0.467.0",
   "description": "An ESLint plugin to enforce a consistent code styles across taiga-ui projects",
   "repository": {
     "type": "git",

package/rules/no-fully-untracked-effect.d.ts

@@ -0,0 +1,5 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"noTrackedReads", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/no-signal-reads-after-await-in-reactive-context.d.ts

@@ -0,0 +1,5 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"readAfterAwait", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/no-untracked-outside-reactive-context.d.ts

@@ -0,0 +1,5 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"outsideReactiveContext", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/no-useless-untracked.d.ts

@@ -0,0 +1,5 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"uselessUntracked", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/prefer-untracked-incidental-signal-reads.d.ts

@@ -0,0 +1,30 @@
+/**
+ * prefer-untracked-incidental-signal-reads
+ *
+ * Conservatively flags signal reads inside reactive callbacks that appear to be
+ * incidental — they provide only a snapshot value passed to a side-effecting
+ * consumer such as a signal write or DOM imperative call — and therefore
+ * probably should be wrapped in `untracked(...)`.
+ *
+ * Design principle: prefer false-negatives over false-positives.
+ * This rule only reports patterns it can confidently identify as suspicious.
+ *
+ * Limitations
+ * -----------
+ * Whether a signal read *should* be tracked is a question of developer intent,
+ * not syntax. The rule relies on heuristics (type-based signal detection,
+ * structural pattern matching) and will inevitably produce:
+ *
+ *  - False negatives: incidental reads that do not match the heuristics.
+ *  - False positives (rare): reads that look incidental but are intentional
+ *    dependencies (e.g. the developer intentionally re-runs the effect when
+ *    `mousePosition` changes to keep `position` in sync).
+ *
+ * Always review suggestions before accepting the fix. If the reported read
+ * IS meant to be a tracked dependency, disable the rule for that line.
+ */
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"incidentalRead", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/prefer-untracked-signal-getter.d.ts

@@ -0,0 +1,5 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const rule: ESLintUtils.RuleModule<"preferGetterForm", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default rule;

package/rules/utils/angular-imports.d.ts

@@ -0,0 +1,14 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+/**
+ * Returns the local name bound to a named import from a given source.
+ * Handles aliased imports: `import { untracked as ngUntracked } from '@angular/core'`
+ * returns `'ngUntracked'` for `exportedName = 'untracked'`.
+ */
+export declare function getLocalNameForImport(program: TSESTree.Program, source: string, exportedName: string): string | null;
+export declare function findAngularCoreImports(program: TSESTree.Program): TSESTree.ImportDeclaration[];
+export declare function findAngularCoreImport(program: TSESTree.Program): TSESTree.ImportDeclaration | null;
+export declare function findRuntimeAngularCoreImport(program: TSESTree.Program): TSESTree.ImportDeclaration | null;
+export declare function findAngularCoreImportSpecifier(program: TSESTree.Program, exportedName: string): {
+    readonly importDecl: TSESTree.ImportDeclaration;
+    readonly specifier: TSESTree.ImportSpecifier;
+} | null;

package/rules/utils/angular-signals.d.ts

@@ -0,0 +1,45 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+import ts from 'typescript';
+export { findAngularCoreImport, findAngularCoreImports, findAngularCoreImportSpecifier, findRuntimeAngularCoreImport, getLocalNameForImport, } from './angular-imports';
+export { walkAfterAsyncBoundaryAst, walkAst, walkSynchronousAst } from './ast-walk';
+export interface NodeMap {
+    get(node: TSESTree.Node): ts.Node | undefined;
+}
+type ReactiveCallback = TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression;
+export interface ReactiveScope {
+    readonly callback: ReactiveCallback;
+    readonly kind: string;
+    readonly owner: TSESTree.CallExpression;
+    readonly reportNode: TSESTree.Node;
+}
+export interface SignalUsage {
+    readonly reads: TSESTree.CallExpression[];
+    readonly writes: TSESTree.CallExpression[];
+}
+export declare function isAngularEffectCall(node: TSESTree.CallExpression, program: TSESTree.Program): boolean;
+export declare function isAngularUntrackedCall(node: TSESTree.CallExpression, program: TSESTree.Program): boolean;
+export declare function getReactiveScopes(node: TSESTree.CallExpression, program: TSESTree.Program): ReactiveScope[];
+export declare function isNodeInsideSynchronousReactiveScope(node: TSESTree.Node, callback: ReactiveCallback): boolean;
+export declare function findEnclosingReactiveScope(node: TSESTree.Node, program: TSESTree.Program): ReactiveScope | null;
+/**
+ * Returns true when the TypeScript type at `node` is an Angular signal type.
+ * Uses duck-typing: callable type whose name contains "Signal", or whose
+ * string-keyed properties include the Angular `ɵ` brand.
+ *
+ * Falls back to `false` on any error.
+ */
+export declare function isSignalType(node: TSESTree.Node, checker: ts.TypeChecker, esTreeNodeToTSNodeMap: NodeMap): boolean;
+export declare function isSignalReadCall(node: TSESTree.CallExpression, checker: ts.TypeChecker, esTreeNodeToTSNodeMap: NodeMap): boolean;
+export declare function isWritableSignalWrite(node: TSESTree.CallExpression, checker: ts.TypeChecker, esTreeNodeToTSNodeMap: NodeMap): boolean;
+/**
+ * Returns true when `node` is a member expression `foo.bar` where `bar` is a
+ * TypeScript getter. Getter accesses are opaque — the getter body can read
+ * signals, so wrapping them in `untracked()` is justified.
+ */
+export declare function isGetterMemberAccess(node: TSESTree.MemberExpression, checker: ts.TypeChecker, esTreeNodeToTSNodeMap: NodeMap): boolean;
+/**
+ * Walks `scopeNode` and collects all signal reads and writes within it,
+ * NOT recursing into nested `untracked(...)` calls (their contents are
+ * already hidden from tracking).
+ */
+export declare function collectSignalUsages(scopeNode: TSESTree.Node, checker: ts.TypeChecker, esTreeNodeToTSNodeMap: NodeMap, program: TSESTree.Program): SignalUsage;

package/rules/utils/ast-expressions.d.ts

@@ -0,0 +1,7 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+/**
+ * Strips TypeScript-only wrapper nodes that have no runtime meaning:
+ * `as` casts, non-null assertions (`!`), type assertions (`<T>expr`), and
+ * optional-chain wrappers. Iterates until no more wrappers are found.
+ */
+export declare function unwrapExpression(expression: TSESTree.Expression): TSESTree.Expression;

package/rules/utils/ast-walk.d.ts

@@ -0,0 +1,30 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+/**
+ * Walks the synchronous portion of a reactive scope.
+ *
+ * - Stops descending into nested function boundaries, since they run in their
+ *   own call context and should not be treated as reads/writes of the current
+ *   reactive scope.
+ * - Traverses the argument of `await`, because it is evaluated synchronously,
+ *   then stops visiting subsequent sibling nodes in the current execution path.
+ */
+export declare function walkSynchronousAst(root: TSESTree.Node, visitor: (node: TSESTree.Node) => false | void): void;
+/**
+ * Walks nodes that run after an async boundary inside a reactive callback.
+ *
+ * The traversal is intentionally conservative:
+ * - it never descends into nested function boundaries
+ * - it propagates async state through straight-line code
+ * - it does not propagate branch-local `await` from optional control-flow
+ *   bodies into later siblings, which avoids noisy false positives
+ */
+export declare function walkAfterAsyncBoundaryAst(root: TSESTree.Node, visitor: (node: TSESTree.Node) => void): void;
+/**
+ * Shallow AST walker. Visits `root` and every descendant, skipping the
+ * synthetic `parent` back-pointer to avoid cycles.
+ *
+ * If the visitor returns `false` for a node, that node's children are NOT
+ * visited (prune / stop-descend). Any other return value (including `void`)
+ * continues the walk.
+ */
+export declare function walkAst(root: TSESTree.Node, visitor: (node: TSESTree.Node) => false | void): void;

package/rules/utils/import-fix-helpers.d.ts

@@ -0,0 +1,14 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+import { type RuleFixer, type SourceCode } from '@typescript-eslint/utils/ts-eslint';
+/** Returns the local alias for `untracked` from `@angular/core`, or null if not imported. */
+export declare function findUntrackedAlias(program: TSESTree.Program): string | null;
+/**
+ * Builds fixer actions that add `untracked` to an existing `@angular/core` import,
+ * or insert a new import declaration when none exists.
+ */
+export declare function buildUntrackedImportFixes(program: TSESTree.Program, fixer: RuleFixer): Array<ReturnType<RuleFixer['insertTextBefore']>>;
+/**
+ * Removes the `untracked` import specifier from `@angular/core`.
+ * When it is the last specifier, removes the entire declaration.
+ */
+export declare function buildImportRemovalFixes(program: TSESTree.Program, fixer: RuleFixer, sourceCode: SourceCode): Array<ReturnType<RuleFixer['remove']>>;

package/rules/utils/untracked-docs.d.ts

@@ -0,0 +1,7 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const ANGULAR_SIGNALS_UNTRACKED_GUIDE_URL = "https://angular.dev/guide/signals#reading-without-tracking-dependencies";
+export declare const ANGULAR_SIGNALS_ASYNC_GUIDE_URL = "https://angular.dev/guide/signals#reactive-context-and-async-operations";
+export declare const UNTRACKED_RULES_README_URL = "https://github.com/taiga-family/taiga-ui/blob/main/projects/eslint-plugin-experience-next/README.md";
+export declare const createUntrackedRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};