@dsivd/prestations-ng 19.0.7 → 19.0.8

package/src/eslint/rules/no-direct-signal-mutation.mjs

@@ -1,14 +1,52 @@
+import { resolveComponentPath } from "../component-path.mjs";
+import {
+  AMBIGUOUS,
+  COMPUTED,
+  factoryKind,
+  FROM_OBSERVABLE,
+  INPUT,
+  VIEW_QUERY,
+  WRITABLE,
+} from "../signal-kinds.mjs";
+import { collectSignalKinds } from "../signal-names.mjs";
 import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
 
 /**
- * ESLint rule to detect direct mutations of signal/getter results.
- * Warns against patterns like: model().property = value
+ * ESLint rule to detect mutations of the value held by a signal.
+ * Warns against patterns like: model().property = value, model().items.splice(i, 1)
  * Suggests using .update() or .set() instead.
  *
  * Applies to TypeScript files and to Angular templates, where the mutation is also
  * hidden in every two-way binding on a call result: [(ngModel)]="model().property".
+ *
+ * No signal's value is to be mutated, whatever its kind — a mutation notifies none of its
+ * dependents. A view query is the single exception: it hands out a DOM element or a
+ * component instance, and mutating that is the reason for asking for it.
+ *
+ * Only the signals the class really declares are inspected, resolved through the whole
+ * inheritance chain, so a plain method (`this.getConfig().items.push(x)`) is left alone.
  */
 
+// Kinds a mutation is not reported on: a view query hands out a DOM element or a component
+// instance, and an ambiguous declaration may well be one.
+const TOLERATED_KINDS = new Set([VIEW_QUERY, AMBIGUOUS]);
+
+// How the message names each kind that has no `.set()` to offer, with the fix that applies.
+const READ_ONLY_ADVICE = {
+  [COMPUTED]: [
+    "a computed()",
+    "It is rebuilt from its sources, so the change is dropped on the next recomputation — mutate the signal it is computed from",
+  ],
+  [INPUT]: [
+    "an input()",
+    "The value belongs to the parent component — ask it for the change through an output()",
+  ],
+  [FROM_OBSERVABLE]: [
+    "a toSignal()",
+    "The value comes from the observable — change it upstream",
+  ],
+};
+
 // Assignment operators accepted by the Angular expression parser.
 const TEMPLATE_ASSIGNMENTS = new Set([
   "=",
@@ -23,6 +61,44 @@ const TEMPLATE_ASSIGNMENTS = new Set([
   "??=",
 ]);
 
+// Methods that mutate in place: called on a signal's value, they change it without
+// notifying the signal, exactly like an assignment. Their non-mutating counterparts
+// (`toSorted`, `filter`, `concat`…) return a new value and are none of the rule's
+// business.
+const MUTATING_METHODS = new Set([
+  // Array
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin",
+  // Map and Set
+  "set",
+  "add",
+  "delete",
+  "clear",
+]);
+
+// Iteration methods handing their callback an element of the receiver: mutating that
+// element mutates the array the signal holds. `reduce` needs no exclusion — its first
+// parameter is the accumulator, and only the first parameter is followed.
+const ITERATION_METHODS = new Set([
+  "forEach",
+  "map",
+  "filter",
+  "find",
+  "findLast",
+  "findIndex",
+  "findLastIndex",
+  "some",
+  "every",
+  "flatMap",
+]);
+
 const TEMPLATE_MEMBER_READS = new Set([
   "PropertyRead",
   "SafePropertyRead",
@@ -30,13 +106,6 @@ const TEMPLATE_MEMBER_READS = new Set([
   "SafeKeyedRead",
 ]);
 
-const VIEW_QUERY_FACTORIES = new Set([
-  "viewChild",
-  "viewChildren",
-  "contentChild",
-  "contentChildren",
-]);
-
 // ── TypeScript ───────────────────────────────────────────────────────────────
 
 function getCalledName(callee) {
@@ -46,175 +115,249 @@ function getCalledName(callee) {
   if (callee.type === "Identifier") {
     return callee.name;
   }
+  if (callee.type !== "MemberExpression") {
+    return null;
+  }
+  if (!callee.computed && callee.property.type === "Identifier") {
+    return callee.property.name;
+  }
+  // `users["push"](x)` is the same call as `users.push(x)`, written differently.
   if (
-    callee.type === "MemberExpression" &&
-    !callee.computed &&
-    callee.property.type === "Identifier"
+    callee.computed &&
+    callee.property.type === "Literal" &&
+    typeof callee.property.value === "string"
   ) {
-    return callee.property.name;
+    return callee.property.value;
   }
   return null;
 }
 
+function isObjectAssign(callee) {
+  return (
+    getCalledName(callee) === "assign" &&
+    callee.object?.type === "Identifier" &&
+    callee.object.name === "Object"
+  );
+}
+
 /**
- * Finds the first/root function call used as the base of a mutation chain.
- * Examples:
- * - model().property = x         => model()
- * - this.model().deep.prop = x   => this.model()
- * - this.query().el().x = y      => this.query()
+ * What a member chain is rooted at, the property and index reads stripped away:
+ * - `model().deep.property` => the `model()` call
+ * - `users[0].name`         => the `users` name
+ *
+ * Only reads are walked through. A chain rooted at anything else — `items().filter(f)`,
+ * `[...items()]` — designates a value of its own, and mutating that value is not mutating
+ * the signal.
  */
-function getFirstCallExpression(node) {
-  if (!node) {
-    return null;
-  }
-  if (node.type === "MemberExpression") {
-    return getFirstCallExpression(node.object);
+function baseOf(node) {
+  let current = node;
+  while (current?.type === "MemberExpression") {
+    current = current.object;
   }
-  if (node.type === "CallExpression") {
-    if (node.callee.type === "MemberExpression") {
-      const nestedCall = getFirstCallExpression(node.callee.object);
-      return nestedCall || node;
+  return current;
+}
+
+function findVariable(scope, name) {
+  for (let current = scope; current; current = current.upper) {
+    const found = current.variables.find((variable) => variable.name === name);
+    if (found) {
+      return found;
     }
-    return node;
   }
   return null;
 }
 
-function isViewQueryFactoryCall(node) {
+// Kind of signal a factory call produces, `undefined` for anything that is not one.
+function signalFactoryKind(node) {
   if (node?.type !== "CallExpression") {
-    return false;
+    return undefined;
   }
-  // `viewChild.required(…)` unwraps to its factory.
+  // `input.required(…)` and `viewChild.required(…)` unwrap to their factory.
   let callee = node.callee;
   while (callee?.type === "MemberExpression") {
     callee = callee.object;
   }
-  return callee?.type === "Identifier" && VIEW_QUERY_FACTORIES.has(callee.name);
+  return callee?.type === "Identifier" ? factoryKind(callee.name) : undefined;
 }
 
-function walkAst(node, visitor, visited = new WeakSet()) {
-  if (!node || typeof node !== "object") {
-    return;
-  }
-  if (visited.has(node)) {
-    return;
+function signalRootCallKind(node, scopeContext) {
+  if (node.arguments.length !== 0) {
+    return undefined;
   }
-  visited.add(node);
-
-  visitor(node);
 
-  for (const key of Object.keys(node)) {
-    // ESLint AST nodes include cyclic parent references.
-    if (key === "parent") {
-      continue;
-    }
-    const child = node[key];
-    if (Array.isArray(child)) {
-      for (const element of child) {
-        walkAst(element, visitor, visited);
-      }
-    } else {
-      walkAst(child, visitor, visited);
-    }
+  // model().prop = ... (a signal held by a variable of this file, resolved by scope)
+  if (node.callee.type === "Identifier") {
+    const variable = findVariable(
+      scopeContext.sourceCode.getScope(node.callee),
+      node.callee.name,
+    );
+    const definition =
+      variable?.defs.length === 1 ? variable.defs[0] : undefined;
+    return definition?.type === "Variable"
+      ? signalFactoryKind(definition.node.init)
+      : undefined;
   }
-}
-
-// A view query signal is read-only: `.set()` does not exist on it, so a mutation
-// reached through one must not be reported.
-function collectViewQueryAccessorNames(ast) {
-  const names = new Set();
 
-  walkAst(ast, (node) => {
-    if (
-      node.type === "VariableDeclarator" &&
-      node.id?.type === "Identifier" &&
-      isViewQueryFactoryCall(node.init)
-    ) {
-      names.add(node.id.name);
-      return;
-    }
-
-    if (
-      (node.type === "PropertyDefinition" || node.type === "ClassProperty") &&
-      node.key?.type === "Identifier" &&
-      isViewQueryFactoryCall(node.value)
-    ) {
-      names.add(node.key.name);
+  // this.model().prop = ... (a signal member of the class)
+  // component.model().prop = ... is not ours to judge: the receiver is foreign.
+  if (node.callee.type === "MemberExpression") {
+    if (node.callee.object?.type !== "ThisExpression") {
+      return undefined;
     }
-  });
+    const name = getCalledName(node.callee);
+    return name ? scopeContext.memberKind(name) : undefined;
+  }
 
-  return names;
+  return undefined;
 }
 
-function isViewQueryAccessorCall(callee, viewQueryAccessorNames) {
-  const calledName = getCalledName(callee);
-  return calledName ? viewQueryAccessorNames.has(calledName) : false;
+/**
+ * Kind of signal whose value an expression evaluates to, `undefined` when it is not one.
+ * The expression may be the signal read itself (`this.model()`), a member of its value
+ * (`this.model().items`), or a name bound to either.
+ */
+function signalValueKind(node, scopeContext, seen = new Set()) {
+  const base = baseOf(node);
+  if (base?.type === "CallExpression") {
+    return signalRootCallKind(base, scopeContext);
+  }
+  return base?.type === "Identifier"
+    ? boundNameSignalKind(base, scopeContext, seen)
+    : undefined;
 }
 
-function isSignalLikeRootCall(node, viewQueryAccessorNames) {
-  if (node.arguments.length !== 0) {
-    return false;
+/**
+ * Kind of signal a name is bound to the value of. Two bindings are followed, both
+ * resolved by ESLint's scope analysis rather than guessed:
+ * - a variable written exactly once, `const users = this.model().users`;
+ * - the element parameter of an iteration callback,
+ *   `this.model().users.forEach((user) => …)`.
+ *
+ * Anything crossing a function boundary — a value handed to a method, stored in a class
+ * field, or reassigned — is out of reach and left unreported.
+ */
+function boundNameSignalKind(identifier, scopeContext, seen) {
+  const variable = findVariable(
+    scopeContext.sourceCode.getScope(identifier),
+    identifier.name,
+  );
+  if (!variable || variable.defs.length !== 1 || seen.has(variable)) {
+    return undefined;
   }
+  seen.add(variable);
+  const definition = variable.defs[0];
 
-  // model().prop = ... (local signal-like accessor)
-  if (node.callee.type === "Identifier") {
-    return !viewQueryAccessorNames.has(node.callee.name);
+  if (definition.type === "Variable") {
+    // A reassignment makes the binding unreliable: the name may hold something else by
+    // the time it is mutated.
+    const writes = variable.references.filter((reference) =>
+      reference.isWrite(),
+    );
+    return writes.length === 1
+      ? signalValueKind(definition.node.init, scopeContext, seen)
+      : undefined;
   }
 
-  // this.model().prop = ... (component/service signal accessor)
-  // component.model().prop = ... should not be assumed to be a signal read.
-  if (node.callee.type === "MemberExpression") {
-    if (node.callee.object?.type !== "ThisExpression") {
-      return false;
+  if (definition.type === "Parameter") {
+    const callback = definition.node;
+    const call = callback.parent;
+    if (
+      callback.params[0] !== definition.name ||
+      call?.type !== "CallExpression" ||
+      call.arguments[0] !== callback ||
+      !ITERATION_METHODS.has(getCalledName(call.callee))
+    ) {
+      return undefined;
     }
-    return !isViewQueryAccessorCall(node.callee, viewQueryAccessorNames);
+    return signalValueKind(call.callee.object, scopeContext, seen);
   }
 
-  return false;
+  return undefined;
 }
 
 // ── Angular templates ────────────────────────────────────────────────────────
 
-// Template counterpart of `getFirstCallExpression`.
-function getFirstTemplateCall(node) {
-  if (!node) {
-    return null;
-  }
-  if (TEMPLATE_MEMBER_READS.has(node.type)) {
-    return getFirstTemplateCall(node.receiver);
-  }
-  if (node.type === "Call" || node.type === "SafeCall") {
-    return getFirstTemplateCall(node.receiver) || node;
-  }
-  return null;
-}
-
 /**
- * Template counterpart of `isSignalLikeRootCall`. A template has no bare identifier:
+ * Template counterpart of `signalRootCallKind`. A template has no bare identifier:
  * `model()` and `this.model()` both read the member directly on the component, so both
  * collapse to `isComponentReceiver`. `map.get(key)` (arguments) and
- * `component.inputElement()` (foreign receiver) are therefore not assumed to be signal
- * reads, as in TypeScript.
+ * `component.inputElement()` (foreign receiver) are therefore never signal reads, as in
+ * TypeScript.
  */
-function isSignalLikeRootTemplateCall(node) {
+function signalRootTemplateCallKind(node, templateContext) {
   if (node.args?.length !== 0) {
-    return false;
+    return undefined;
   }
   const callee = node.receiver;
   if (!callee || !TEMPLATE_MEMBER_READS.has(callee.type)) {
-    return false;
+    return undefined;
+  }
+  return isComponentReceiver(callee.receiver)
+    ? templateContext.memberKind(callee.name ?? "")
+    : undefined;
+}
+
+/**
+ * Expression a template name is bound to, `undefined` when the name is a component
+ * member. Mutating through such a name mutates whatever the expression yields:
+ * `@for (user of model().users)` hands out the elements of the signal's array.
+ *
+ * The item of a `@for` is only bound inside its own block, which the ancestor walk
+ * enforces exactly; a `@let` is looked up by name, its declaration always preceding its
+ * uses.
+ */
+function boundTemplateExpression(read, templateContext) {
+  for (let current = read; current; current = current.parent) {
+    if (current.type === "ForLoopBlock" && current.item?.name === read.name) {
+      return current.expression?.ast ?? current.expression;
+    }
+  }
+  const declared = templateContext.letBindings.get(read.name);
+  return declared?.ast ?? declared;
+}
+
+/**
+ * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, or
+ * a template name bound to either.
+ */
+function signalTemplateValueKind(node, templateContext, seen = new Set()) {
+  if (node?.type === "Call" || node?.type === "SafeCall") {
+    return signalRootTemplateCallKind(node, templateContext);
+  }
+  if (!TEMPLATE_MEMBER_READS.has(node?.type)) {
+    return undefined;
+  }
+
+  // Property and index reads are walked through; anything else roots a value of its own.
+  let base = node;
+  while (TEMPLATE_MEMBER_READS.has(base.receiver?.type)) {
+    base = base.receiver;
+  }
+  const receiver = base.receiver;
+
+  if (receiver?.type === "Call" || receiver?.type === "SafeCall") {
+    return signalRootTemplateCallKind(receiver, templateContext);
+  }
+  if (!isComponentReceiver(receiver) || seen.has(base.name)) {
+    return undefined;
   }
-  return isComponentReceiver(callee.receiver);
+  seen.add(base.name);
+  return signalTemplateValueKind(
+    boundTemplateExpression(base, templateContext),
+    templateContext,
+    seen,
+  );
 }
 
-// Template counterpart of the TypeScript checks: a member of a signal-like call
-// result, such as `model().property` or `this.model().array[0]`.
-function isTemplateCallResultMember(node) {
-  if (!node || !TEMPLATE_MEMBER_READS.has(node.type)) {
-    return false;
+// Method a template call invokes, `undefined` when the name is not statically known.
+function templateMethodName(receiver) {
+  if (receiver?.name) {
+    return receiver.name;
   }
-  const rootCall = getFirstTemplateCall(node.receiver);
-  return !!rootCall && isSignalLikeRootTemplateCall(rootCall);
+  // `users['push'](x)` is the same call as `users.push(x)`, written differently.
+  return typeof receiver?.key?.value === "string"
+    ? receiver.key.value
+    : undefined;
 }
 
 export default {
@@ -222,47 +365,131 @@ export default {
     type: "problem",
     docs: {
       description:
-        "Warn on direct property mutations of function call results (signals, getters, etc.)",
+        "Warn on mutations of the value held by a signal, which notify none of its dependents",
       category: "Best Practices",
       recommended: true,
     },
     messages: {
       directMutation:
-        "Direct mutation of function call result detected. Use .update() or .set() instead of direct assignment.",
+        "Direct mutation of a signal's value detected. Use .update() or .set() instead of direct assignment.",
+      inPlaceMutation:
+        "In-place mutation of a signal's value detected. `{{method}}` changes the value without notifying the signal: use .update() with a new value instead.",
+      readOnlyMutation:
+        "Mutation of the value of {{kind}} detected, which notifies none of its dependents. {{advice}}.",
     },
   },
 
   create(context) {
-    const viewQueryAccessorNames = collectViewQueryAccessorNames(
-      context.sourceCode.ast,
-    );
+    // The class holding the signals: the linted file itself, or the component a template
+    // belongs to.
+    const declaringPath =
+      resolveComponentPath(context.filename) ?? context.filename;
+    const memberKinds = collectSignalKinds(declaringPath);
 
-    const report = (node) =>
-      context.report({ node, messageId: "directMutation" });
+    // `memberKinds` is undefined when the declaring file could not be read: its signals
+    // are unknown, so fall back to treating every argument-less accessor as a writable
+    // one. A false positive costs a disable comment; a missed mutation is silent.
+    const memberKind = (name) =>
+      memberKinds ? memberKinds.get(name) : WRITABLE;
+
+    const reportMutation = (node, kind, method) => {
+      if (!kind || TOLERATED_KINDS.has(kind)) {
+        return;
+      }
+      if (kind !== WRITABLE) {
+        const [name, advice] = READ_ONLY_ADVICE[kind];
+        context.report({
+          node,
+          messageId: "readOnlyMutation",
+          data: { kind: name, advice },
+        });
+      } else if (method) {
+        context.report({ node, messageId: "inPlaceMutation", data: { method } });
+      } else {
+        context.report({ node, messageId: "directMutation" });
+      }
+    };
+
+    const scopeContext = { memberKind, sourceCode: context.sourceCode };
+    // `@let` bindings, always declared before they are used.
+    const templateContext = { memberKind, letBindings: new Map() };
+
+    const checkTemplateInPlaceCall = (node) => {
+      const method = templateMethodName(node.receiver);
+      if (!method || !MUTATING_METHODS.has(method)) {
+        return;
+      }
+      const kind = signalTemplateValueKind(
+        node.receiver.receiver,
+        templateContext,
+      );
+      reportMutation(node, kind, method);
+    };
 
     return {
       // ── TypeScript ───────────────────────────────────────────────────────────
       AssignmentExpression(node) {
-        if (node.left.type !== "MemberExpression") {
+        if (node.left.type === "MemberExpression") {
+          reportMutation(node, signalValueKind(node.left.object, scopeContext));
+        }
+      },
+
+      UnaryExpression(node) {
+        // `delete model().users[0]` drops an entry of the value, notifying nothing.
+        if (
+          node.operator === "delete" &&
+          node.argument.type === "MemberExpression"
+        ) {
+          reportMutation(
+            node,
+            signalValueKind(node.argument.object, scopeContext),
+            "delete",
+          );
+        }
+      },
+
+      CallExpression(node) {
+        if (node.callee.type !== "MemberExpression") {
+          return;
+        }
+
+        // `Object.assign(target, …)` writes into its first argument.
+        if (isObjectAssign(node.callee)) {
+          reportMutation(
+            node,
+            signalValueKind(node.arguments[0], scopeContext),
+            "Object.assign",
+          );
           return;
         }
 
-        const rootCall = getFirstCallExpression(node.left.object);
-        if (rootCall && isSignalLikeRootCall(rootCall, viewQueryAccessorNames)) {
-          report(node);
+        const method = getCalledName(node.callee);
+        if (method && MUTATING_METHODS.has(method)) {
+          reportMutation(
+            node,
+            signalValueKind(node.callee.object, scopeContext),
+            method,
+          );
         }
       },
 
       // ── Angular templates ────────────────────────────────────────────────────
+      LetDeclaration(node) {
+        templateContext.letBindings.set(node.name, node.value);
+      },
+
       Binary(node) {
-        if (
-          TEMPLATE_ASSIGNMENTS.has(node.operation) &&
-          isTemplateCallResultMember(node.left)
-        ) {
-          report(node);
+        if (TEMPLATE_ASSIGNMENTS.has(node.operation)) {
+          reportMutation(
+            node,
+            signalTemplateValueKind(node.left, templateContext),
+          );
         }
       },
 
+      Call: checkTemplateInPlaceCall,
+      SafeCall: checkTemplateInPlaceCall,
+
       BoundEvent(node) {
         // `[(x)]="model().property"` makes Angular assign into the value of the signal.
         // Reporting on the BoundEvent handler reports the binding exactly once.
@@ -270,9 +497,10 @@ export default {
           return;
         }
         const handler = handlerExpressionOf(node);
-        if (isTemplateCallResultMember(handler)) {
-          report(handler);
-        }
+        reportMutation(
+          handler,
+          signalTemplateValueKind(handler, templateContext),
+        );
       },
     };
   },

package/src/eslint/rules/no-uninvoked-signal-in-template.mjs

@@ -1,3 +1,4 @@
+import { resolveComponentPath } from "../component-path.mjs";
 import { collectSignalNames } from "../signal-names.mjs";
 import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
 
@@ -30,18 +31,6 @@ const TEMPLATE_BUILTINS = [
   "$implicit",
 ];
 
-// An inline template is a virtual block whose path is derived from the `.ts`, and whose
-// name ends with `.html` too: `foo.component.ts/1_inline-template-….component.html`.
-// It has to be matched BEFORE the external template, otherwise it resolves to garbage.
-function resolveComponentPath(filename) {
-  const inlineMatch = filename.match(/^(.*\.ts)(?:[/\\]|$)/);
-  if (inlineMatch) {
-    return inlineMatch[1];
-  }
-  return filename.endsWith(".html")
-    ? `${filename.slice(0, -".html".length)}.ts`
-    : undefined;
-}
 
 export default {
   meta: {