@angular-eslint/eslint-plugin 22.2.1-alpha.13 → 22.2.1-alpha.14

package/README.md

@@ -29,6 +29,7 @@ The premade flat configs that combine these rules are provided by the umbrella [
 | [`no-developer-preview`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/no-developer-preview.md) | Disallow using code which is marked as developer preview |  |  |  |
 | [`no-experimental`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/no-experimental.md) | Disallow using code which is marked as experimental |  |  |  |
 | [`no-implicit-take-until-destroyed`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/no-implicit-take-until-destroyed.md) | Ensures that `takeUntilDestroyed()` is called with an explicit `DestroyRef` when used outside of an injection context |  |  |  |
+| [`reactive-context-must-read-signal`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/reactive-context-must-read-signal.md) | Ensures that reactive contexts such as computed(), linkedSignal() and effect() read at least one reactive value (a signal). A reactive context with no reactive dependencies never re-runs, which is almost always a mistake. |  |  |  |
 | [`require-lifecycle-on-prototype`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/require-lifecycle-on-prototype.md) | Ensures that lifecycle methods are defined on the object's prototype instead of on an instance. |  |  |  |
 | [`sort-lifecycle-methods`](https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/docs/rules/sort-lifecycle-methods.md) | Ensures that lifecycle methods are declared in order of execution |  |  |  |
 <!-- prettier-ignore-end -->

package/dist/index.d.ts

@@ -125,6 +125,9 @@ declare const _default: {
         "prefer-standalone": import("@typescript-eslint/utils/ts-eslint").RuleModule<import("./rules/prefer-standalone").MessageIds, [], import("./utils/create-eslint-rule").RuleDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
+        "reactive-context-must-read-signal": import("@typescript-eslint/utils/ts-eslint").RuleModule<"mustReadSignal", import("./rules/reactive-context-must-read-signal").Options, import("./utils/create-eslint-rule").RuleDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
         "relative-url-prefix": import("@typescript-eslint/utils/ts-eslint").RuleModule<"relativeUrlPrefix", [], import("./utils/create-eslint-rule").RuleDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuJA,kBAsDE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0JA,kBAuDE"}

package/dist/index.js

@@ -82,6 +82,7 @@ const no_developer_preview_1 = __importStar(require("./rules/no-developer-previe
 const no_implicit_take_until_destroyed_1 = __importStar(require("./rules/no-implicit-take-until-destroyed"));
 const computed_must_return_1 = __importStar(require("./rules/computed-must-return"));
 const inject_at_top_1 = __importStar(require("./rules/inject-at-top"));
+const reactive_context_must_read_signal_1 = __importStar(require("./rules/reactive-context-must-read-signal"));
 module.exports = {
     rules: {
         [component_class_suffix_1.RULE_NAME]: component_class_suffix_1.default,
@@ -123,6 +124,7 @@ module.exports = {
         [prefer_signal_model_1.RULE_NAME]: prefer_signal_model_1.default,
         [prefer_signals_1.RULE_NAME]: prefer_signals_1.default,
         [prefer_standalone_1.RULE_NAME]: prefer_standalone_1.default,
+        [reactive_context_must_read_signal_1.RULE_NAME]: reactive_context_must_read_signal_1.default,
         [relative_url_prefix_1.RULE_NAME]: relative_url_prefix_1.default,
         [require_lifecycle_on_prototype_1.RULE_NAME]: require_lifecycle_on_prototype_1.default,
         [require_localize_metadata_1.RULE_NAME]: require_localize_metadata_1.default,

package/dist/rules/reactive-context-must-read-signal.d.ts

@@ -0,0 +1,16 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export type Options = [
+    {
+        readonly checkResources?: boolean;
+    }
+];
+export type MessageIds = 'mustReadSignal';
+export declare const RULE_NAME = "reactive-context-must-read-signal";
+declare const _default: ESLintUtils.RuleModule<"mustReadSignal", Options, import("../utils/create-eslint-rule").RuleDocs, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default _default;
+export declare const RULE_DOCS_EXTENSION: {
+    rationale: string;
+};
+//# sourceMappingURL=reactive-context-must-read-signal.d.ts.map

package/dist/rules/reactive-context-must-read-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-context-must-read-signal.d.ts","sourceRoot":"","sources":["../../src/rules/reactive-context-must-read-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EAGZ,MAAM,0BAA0B,CAAC;AAMlC,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;KACnC;CACF,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAC1C,eAAO,MAAM,SAAS,sCAAsC,CAAC;;;;AA8D7D,wBA2SG;AAEH,eAAO,MAAM,mBAAmB;;CAG/B,CAAC"}

package/dist/rules/reactive-context-must-read-signal.js

@@ -0,0 +1,316 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_DOCS_EXTENSION = exports.RULE_NAME = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const tsutils = __importStar(require("ts-api-utils"));
+const typescript_1 = __importDefault(require("typescript"));
+const create_eslint_rule_1 = require("../utils/create-eslint-rule");
+const signals_1 = require("../utils/signals");
+exports.RULE_NAME = 'reactive-context-must-read-signal';
+/**
+ * Reactive contexts that should depend on at least one signal. The tracked
+ * function is the one whose signal reads define the context's dependencies:
+ * - `computed`/`effect`: the first argument.
+ * - `linkedSignal`: the first argument (shorthand) or the `source`/`computation`
+ *   functions of the options object.
+ * - `afterRenderEffect`: the first argument (shorthand) or the phase functions
+ *   of the options object.
+ */
+const DEFAULT_PRIMITIVES = {
+    afterRenderEffect: {
+        args: [0],
+        optionKeys: ['earlyRead', 'write', 'mixedReadWrite', 'read'],
+    },
+    computed: { args: [0], optionKeys: [] },
+    effect: { args: [0], optionKeys: [] },
+    linkedSignal: { args: [0], optionKeys: ['source', 'computation'] },
+};
+/**
+ * For resources, only the `params` (formerly `request`) function defines the
+ * reactive dependencies; reading a signal in the `loader`/`stream` does not make
+ * the resource reload. These are opt-in via the `checkResources` option.
+ */
+const RESOURCE_PRIMITIVES = {
+    resource: { args: [0], optionKeys: ['params', 'request'] },
+    rxResource: { args: [0], optionKeys: ['params', 'request'] },
+};
+function isFunction(node) {
+    return (node?.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node?.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression);
+}
+exports.default = (0, create_eslint_rule_1.createESLintRule)({
+    name: exports.RULE_NAME,
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Ensures that reactive contexts such as computed(), linkedSignal() and effect() read at least one reactive value (a signal). A reactive context with no reactive dependencies never re-runs, which is almost always a mistake.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    checkResources: {
+                        type: 'boolean',
+                        description: 'Also check that the `params` function of `resource()` and `rxResource()` reads a signal.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            mustReadSignal: '{{primitive}}() must read at least one signal, otherwise it will never re-run when state changes.',
+        },
+    },
+    defaultOptions: [{ checkResources: false }],
+    create(context, [{ checkResources = false }]) {
+        const services = utils_1.ESLintUtils.getParserServices(context);
+        const checker = services.program.getTypeChecker();
+        const primitives = checkResources
+            ? { ...DEFAULT_PRIMITIVES, ...RESOURCE_PRIMITIVES }
+            : DEFAULT_PRIMITIVES;
+        const analyses = new Map();
+        const trackedFnToCall = new Map();
+        const frameStack = [];
+        /**
+         * Returns true if calling `callee` reads a signal, i.e. `callee` has one of
+         * the known signal types. This mirrors the detection used by
+         * `no-uncalled-signals`.
+         */
+        function isSignalRead(callee) {
+            const type = services.getTypeAtLocation(callee);
+            const symbol = type.getSymbol();
+            if (symbol && signals_1.KNOWN_SIGNAL_TYPES.has(symbol.name)) {
+                return true;
+            }
+            // The `Signal` type is a type alias, so it is only reachable via the
+            // alias symbol. Other signal types (e.g. `InputSignal`) are interfaces
+            // and are found through `getSymbol()` above.
+            if (type.aliasSymbol && signals_1.KNOWN_SIGNAL_TYPES.has(type.aliasSymbol.name)) {
+                return true;
+            }
+            return false;
+        }
+        /**
+         * Returns true if the symbol is only declared in TypeScript's default
+         * library files. Those declarations (arrays, strings, `Math`, `JSON`,
+         * `Object`, `console`, DOM APIs, ...) cannot read an Angular signal.
+         */
+        function isDeclaredInDefaultLib(symbol) {
+            const declarations = symbol.getDeclarations();
+            return (!!declarations?.length &&
+                declarations.every((declaration) => services.program.isSourceFileDefaultLibrary(declaration.getSourceFile())));
+        }
+        /**
+         * Returns true if the node is a function-typed value that we cannot look
+         * inside, e.g. `this.transform` in `this.items.map(this.transform)`. The
+         * callee could invoke it, and it could read a signal.
+         */
+        function isOpaqueFunctionValue(node) {
+            if (isFunction(node)) {
+                // Inline functions are visited by this rule, so any signal they read is
+                // attributed to the enclosing reactive context.
+                return false;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                // We cannot tell what a spread expands to, so assume the worst.
+                return true;
+            }
+            return services.getTypeAtLocation(node).getCallSignatures().length > 0;
+        }
+        /**
+         * Records what a call, `new` expression or tagged template tells us about
+         * the reactive context we are currently inside. It is only known not to
+         * read a signal when the callee resolves to a declaration in a TypeScript
+         * default library and no argument is an opaque function value.
+         */
+        function analyseCallLike(callee, args, analysis) {
+            let symbol = services.getSymbolAtLocation(callee);
+            if (symbol && tsutils.isSymbolFlagSet(symbol, typescript_1.default.SymbolFlags.Alias)) {
+                symbol = checker.getAliasedSymbol(symbol);
+            }
+            if (!symbol ||
+                !isDeclaredInDefaultLib(symbol) ||
+                args.some(isOpaqueFunctionValue)) {
+                analysis.hasUnknown = true;
+            }
+        }
+        /** The analysis of the reactive context we are currently inside, if any. */
+        function currentAnalysis() {
+            const top = frameStack[frameStack.length - 1];
+            return top && analyses.get(top.call);
+        }
+        function registerTrackedFunction(node, call, analysis) {
+            if (isFunction(node)) {
+                trackedFnToCall.set(node, call);
+                analysis.hasTrackedFn = true;
+            }
+            else {
+                // The tracked slot holds something we cannot look inside, such as a
+                // signal passed directly as `source`, or a reference to a function
+                // declared elsewhere. It may well be reactive, so stay silent.
+                analysis.hasUnknown = true;
+            }
+        }
+        function registerTrackedOptions(options, call, config, analysis) {
+            for (const property of options.properties) {
+                if (property.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                    // The spread could provide any of the tracked options.
+                    analysis.hasUnknown = true;
+                }
+                else if (!property.computed &&
+                    property.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    config.optionKeys.includes(property.key.name)) {
+                    registerTrackedFunction(property.value, call, analysis);
+                }
+            }
+        }
+        function registerTrackedFunctions(call, config, analysis) {
+            for (const index of config.args) {
+                const arg = call.arguments[index];
+                if (arg === undefined) {
+                    continue;
+                }
+                if (config.optionKeys.length > 0 &&
+                    arg.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    registerTrackedOptions(arg, call, config, analysis);
+                }
+                else {
+                    registerTrackedFunction(arg, call, analysis);
+                }
+            }
+        }
+        function enterFunction(node) {
+            const call = trackedFnToCall.get(node);
+            if (call) {
+                frameStack.push({ fn: node, call });
+            }
+        }
+        function exitFunction(node) {
+            const top = frameStack[frameStack.length - 1];
+            if (top?.fn === node) {
+                frameStack.pop();
+            }
+        }
+        return {
+            ArrowFunctionExpression: enterFunction,
+            'ArrowFunctionExpression:exit': exitFunction,
+            FunctionExpression: enterFunction,
+            'FunctionExpression:exit': exitFunction,
+            MemberExpression(node) {
+                const analysis = currentAnalysis();
+                if (!analysis) {
+                    return;
+                }
+                // A getter runs arbitrary code, so `this.name` can read a signal even
+                // though it does not look like a call.
+                const symbol = services.getSymbolAtLocation(node);
+                if (symbol &&
+                    tsutils.isSymbolFlagSet(symbol, typescript_1.default.SymbolFlags.GetAccessor)) {
+                    analysis.hasUnknown = true;
+                }
+            },
+            NewExpression(node) {
+                const analysis = currentAnalysis();
+                if (analysis) {
+                    analyseCallLike(node.callee, node.arguments, analysis);
+                }
+            },
+            TaggedTemplateExpression(node) {
+                const analysis = currentAnalysis();
+                if (analysis) {
+                    analyseCallLike(node.tag, node.quasi.expressions, analysis);
+                }
+            },
+            CallExpression(node) {
+                // Attribute this call to the tracked function we are currently inside,
+                // if any. This runs before registration below, so a reactive context
+                // nested inside another tracked function is correctly treated as an
+                // (unknown) call of the outer function.
+                const analysis = currentAnalysis();
+                if (analysis) {
+                    if (isSignalRead(node.callee)) {
+                        analysis.hasReactiveRead = true;
+                    }
+                    else {
+                        analyseCallLike(node.callee, node.arguments, analysis);
+                    }
+                }
+                // Register this call if it is one of the reactive contexts.
+                if (node.callee.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                const config = primitives[node.callee.name];
+                if (!config) {
+                    return;
+                }
+                const newAnalysis = {
+                    call: node,
+                    primitiveName: node.callee.name,
+                    hasTrackedFn: false,
+                    hasReactiveRead: false,
+                    hasUnknown: false,
+                };
+                registerTrackedFunctions(node, config, newAnalysis);
+                analyses.set(node, newAnalysis);
+            },
+            'CallExpression:exit'(node) {
+                const analysis = analyses.get(node);
+                if (!analysis) {
+                    return;
+                }
+                analyses.delete(node);
+                // Only report when we are certain there is no reactivity: there is a
+                // tracked function, no signal was read, and there was nothing that
+                // might have read a signal on our behalf.
+                if (analysis.hasTrackedFn &&
+                    !analysis.hasReactiveRead &&
+                    !analysis.hasUnknown) {
+                    context.report({
+                        node: analysis.call,
+                        messageId: 'mustReadSignal',
+                        data: { primitive: analysis.primitiveName },
+                    });
+                }
+            },
+        };
+    },
+});
+exports.RULE_DOCS_EXTENSION = {
+    rationale: 'Reactive contexts like `computed()`, `linkedSignal()`, `effect()` and `afterRenderEffect()` re-run whenever a signal they read changes. If the relevant function never reads a signal, the context runs once and can never react to anything, so it adds overhead without providing reactivity. This is usually a mistake: either the developer forgot to call a signal (e.g. wrote `firstName` instead of `firstName()`), or the value is actually static and should be a plain constant, a `signal()`, or an `afterNextRender()` in the case of `afterRenderEffect()`. To avoid false positives, the rule only reports when everything the tracked function does is known not to read a signal. Calls into the TypeScript standard library (arrays, strings, `Math`, `JSON`, `console`, DOM APIs, etc.) are known to be safe; anything else keeps the rule silent, including a helper function, a service method, a getter, an unresolved symbol, and any Angular API such as `untracked()`. For `resource()`/`rxResource()` only the `params` function defines the dependencies, and these are opt-in via the `checkResources` option.',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-eslint/eslint-plugin",
-  "version": "22.2.1-alpha.13",
+  "version": "22.2.1-alpha.14",
   "description": "ESLint plugin for Angular applications, following https://angular.dev/style-guide",
   "license": "MIT",
   "main": "dist/index.js",
@@ -19,12 +19,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@angular-eslint/bundled-angular-compiler": "22.2.1-alpha.13",
-    "@angular-eslint/utils": "22.2.1-alpha.13",
+    "@angular-eslint/bundled-angular-compiler": "22.2.1-alpha.14",
+    "@angular-eslint/utils": "22.2.1-alpha.14",
     "ts-api-utils": "^2.1.0"
   },
   "devDependencies": {
-    "@angular-eslint/test-utils": "22.2.1-alpha.13"
+    "@angular-eslint/test-utils": "22.2.1-alpha.14"
   },
   "peerDependencies": {
     "@typescript-eslint/utils": "^8.0.0",