@dsivd/prestations-ng 19.0.7 → 19.0.8

package/CHANGELOG.md

@@ -6,6 +6,33 @@
 
 ---
 
+## [19.0.8]
+
+### Changed
+
+- ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) now
+  covers much more than the plain assignment it started with. 🚨 Expect new errors on
+  `npm update`; each can be turned off from your own `rules` block.
+    - **in-place mutators** are reported as well, since they notify nothing either: those of
+      `Array` (`splice`, `push`, `pop`, `shift`, `unshift`, `sort`, `reverse`, `fill`,
+      `copyWithin`) and of `Map` / `Set` (`set`, `add`, `delete`, `clear`)
+    - so are `delete model().users[0]` and `Object.assign(model(), …)`, and
+      `items()["push"](x)` counts as `items().push(x)`
+    - the value is **followed through the bindings that can be resolved exactly**: a
+      variable written once, the element parameter of an iteration callback, a `@for` item
+      and a `@let`. `@for (user of model().users)` then `user.done = true` is reported
+    - 🚨 **no signal is mutable**, whatever its kind: `signal()`, `model()`,
+      `linkedSignal()`, `computed()`, `input()` and `toSignal()` are all reported, each with
+      the fix that applies to it. A **view query** is the single exception —
+      `viewChild()`, `contentChildren()` and their `.required` variants hand out a DOM
+      element or a component instance, which is there to be mutated
+    - 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 never
+      reported
+    - a signal inherited from a published package and known by its type only (`Signal<T>`)
+      is left alone: a declaration file no longer says whether it was a `computed()` or a
+      view query
+
 ## [19.0.7]
 
 ### Added
@@ -44,7 +71,6 @@
 - [recaptcha.service.ts](projects/prestations-ng/src/sdk-recaptcha/recaptcha.service.ts)
     - fixed recaptcha called infinitely when backend says that it must be revalidated
 
-
 ## [19.0.0] - should be aligned with prestations-be 19.0.x
 
 ### Added

package/ESLINT_PLUGIN.md

@@ -50,8 +50,8 @@ from the config. Inline templates written in a `@Component` are covered too, thr
 
 | Config                        | Target      | Contents                                                       |
 | ----------------------------- | ----------- | -------------------------------------------------------------- |
-| `configs.tsRecommended`       | `**/*.ts`   | the baselines, the house style, and `tsRules`                   |
-| `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules`             |
+| `configs.tsRecommended`       | `**/*.ts`   | the baselines, the house style, and `tsRules`                  |
+| `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules`            |
 | `configs.tsRules`             | `**/*.ts`   | `no-direct-signal-mutation`                                    |
 | `configs.templateRules`       | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template` |
 
@@ -96,8 +96,9 @@ your own `rules` block. It is applied after the shared config, so it wins:
 
 ### `no-direct-signal-mutation`
 
-Reports an assignment into a member of a signal's value. Mutating the object held by a
-signal does not notify its dependents, so the view is not refreshed.
+Reports a mutation of the value held by a signal, in either of its two forms: an
+assignment into one of its members, or a call to an in-place mutator. Mutating that value
+does not notify the signal's dependents, so the view is not refreshed.
 
 Applies to **TypeScript files and templates**, including the case where the mutation hides
 in a two-way binding.
@@ -105,14 +106,20 @@ in a two-way binding.
 ```ts
 // ✗ mutates the object inside the signal, no notification
 this.model().property = value;
+this.model().items.splice(index, 1);
 
 // ✓
 this.model.update((current) => ({ ...current, property: value }));
+this.model.update((current) => ({
+    ...current,
+    items: current.items.filter((_, i) => i !== index),
+}));
 ```
 
 ```html
 <!-- ✗ -->
 <button (click)="model().property = value">…</button>
+<button (click)="model().items.splice(index, 1)">…</button>
 <input [(ngModel)]="model().property" />
 
 <!-- ✓ -->
@@ -122,23 +129,130 @@ this.model.update((current) => ({ ...current, property: value }));
 All the assignment operators accepted by the Angular expression parser are covered: `=`,
 `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
 
-**Not reported**, because the call is not assumed to be a signal read:
+The in-place mutators covered are those of `Array` — `push`, `pop`, `shift`, `unshift`,
+`splice`, `sort`, `reverse`, `fill`, `copyWithin` — and of `Map` / `Set` — `set`, `add`,
+`delete`, `clear`. Their non-mutating counterparts, `toSorted`, `toReversed`, `filter`,
+`concat`, `with`, are never reported: they return a new value. `items()["push"](x)` is the
+same call as `items().push(x)` and is reported alike.
 
-| Expression                                          | Why                                                               |
-| --------------------------------------------------- | ----------------------------------------------------------------- |
-| `map.get(key).files = []`                           | the call takes arguments                                          |
-| `component.inputElement().nativeElement.value = ''` | reached through a foreign receiver, not `this`                    |
-| `obj.getter().property = value`                     | idem                                                              |
-| `viewChild(…)` / `viewChild.required(…)` accessors  | a view query signal is read-only, there is no `.set()` to suggest |
+Two other ways of writing into the value are covered, in TypeScript — the Angular template
+parser accepts neither:
+
+```ts
+delete this.model().users[0];
+Object.assign(this.model(), { property: value });
+```
+
+#### Names bound to the value
+
+A mutation is rarely written on the signal read itself. The rule follows the value through
+the bindings it can resolve exactly, and only those:
+
+```ts
+// ✗ a variable written once
+const users = this.model().users;
+users.push(user);
+
+// ✗ the element parameter of an iteration callback
+this.model().users.forEach((user) => (user.done = true));
+```
+
+```angular-html
+<!-- ✗ a @for item, bound only inside its own block -->
+@for (user of model().users; track user.id) {
+    <input [(ngModel)]="user.done" />
+    <button (click)="user.tags.push(tag)">…</button>
+}
+
+<!-- ✗ a @let -->
+@let users = model().users;
+<button (click)="users.push(user)">…</button>
+```
+
+In TypeScript these come from ESLint's scope analysis, in templates from the block that
+introduces the name — nothing is inferred from a naming convention. A variable that is
+**reassigned** is dropped: the name may hold something else by the time it is mutated. Same
+for `reduce`, whose first parameter is the accumulator and not an element.
+
+**What it cannot follow** is a value crossing a function boundary — handed to a method,
+stored in a class field, returned and mutated elsewhere:
+
+```ts
+// not reported: the rule cannot know what `sortInto` does
+this.sortInto(this.model().users);
+```
+
+That needs interprocedural analysis, which ESLint does not provide; a full type checker
+would be required. It is the one remaining gap in detection.
+
+#### Only real signals are inspected
+
+The rule does not guess from the shape of a call. It reads the declaring class — the linted
+file itself, or the component a template belongs to — and resolves its signal members
+through the whole inheritance chain, the way TypeScript would: relative paths,
+`node_modules`, `paths` mappings, and the flattened `.d.ts` of a published library. Nothing
+has to be declared by hand.
+
+**No signal's value is to be mutated, whatever its kind** — a mutation notifies none of its
+dependents. The kinds differ only in the advice the message carries, since none but the
+first has a `.set()`:
+
+| Declared as                             | On a mutation of its value                                  |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `signal()`, `model()`, `linkedSignal()` | use `.set()` / `.update()`                                  |
+| `computed()`                            | the value is derived: mutate the signal it is computed from |
+| `input()`                               | the value belongs to the parent: ask through an `output()`  |
+| `toSignal()`                            | the value comes from the observable: change it upstream     |
+| `viewChild()`, `contentChildren()`, …   | **the one exception**, left alone: see below                |
+
+A view query is the exception because it hands out a DOM element or a component instance,
+and mutating that is the reason for asking for it: `rows().nativeElement.hidden = true` is
+the normal way to use one. `.required` variants included.
+
+Anything that is not a declared signal is left alone as well:
+
+| Expression                           | Why                                                          |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `this.getConfig().items.push(item)`  | `getConfig()` is a plain method, not a signal                |
+| `map.get(key).files.push(file)`      | the call takes arguments, so it is not a signal read         |
+| `component.model().items.push(item)` | reached through a foreign receiver, not the component itself |
+
+Because the rule knows a real signal from an ordinary method, `set` / `add` / `delete` are
+safe to report: `byId().set(k, v)` mutates the `Map` inside the signal, while `byId.set(m)`
+replaces the signal's value and is correct.
+
+**One accepted false positive.** A `computed()` may legitimately hand out a live mutable
+object, and no type information is available to tell that apart from a derived value:
+
+```ts
+readonly items = computed(() => this.form.get('items') as FormArray);
+this.items().push(control); // reported, though this is the FormArray API
+```
+
+**One accepted gap, and it is forced.** A published declaration file spells a `computed()`,
+a `toSignal()` and a view query alike, `Signal<T>` — the factory name is gone. A signal
+**inherited from a package** and known by its type only is therefore left alone:
+
+```ts
+// in the published .d.ts, indistinguishable from one another
+readonly fieldId: Signal<string>; // was a computed()
+readonly inputElement: Signal<ElementRef>; // was a viewChild()
+```
+
+Reporting that group would break the lint of every project extending a component of this
+library: `prestations-ng` publishes 54 view queries, `AbstractPageComponent` and
+`FoehnInputComponent` among them, and touching the element they queried is normal code. So
+a mutation of an inherited `computed()` goes unreported — the narrower harm of the two.
+Signals declared in your own project, base classes included, are unaffected: their factory
+call is right there to be read.
 
 The rule has no autofix: the correct rewrite depends on what you meant.
 
-**Known limitation.** The view query exclusion needs the component class, which a template
-AST does not carry. A mutation reached through a view query **from a template** is therefore
-still reported, with a message suggesting a `.update()` that does not exist on a read-only
-signal. It is rare — mutating the DOM from a template expression — but if you hit it, turn
-the rule off for that file. The same imprecision applies to `computed()` in TypeScript,
-which is read-only as well.
+**When the declaring class cannot be read** — an unsaved buffer, a template with no twin
+`.ts` — its signals are unknown, and the rule falls back to treating any argument-less
+accessor on the component as a signal. It may then report a plain method. That direction is
+deliberate: a false positive costs one `eslint-disable-next-line`, a missed mutation is a
+silent bug.
 
 ### `no-uninvoked-signal-in-template`