@dsivd/prestations-ng 19.2.0-beta.27 → 19.2.0-beta.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/AI_GUIDELINES.md +30 -9
  2. package/ANGULAR_SIGNALS.md +2 -2
  3. package/CHANGELOG.md +51 -3
  4. package/CONTRIBUTING.md +54 -12
  5. package/ESLINT_PLUGIN.md +110 -13
  6. package/GOOD_PRACTICES.md +34 -10
  7. package/README.md +18 -12
  8. package/UPGRADING_V19.md +154 -7
  9. package/eslint/configs/template-rules.mjs +3 -0
  10. package/eslint/rules/index.mjs +2 -0
  11. package/eslint/rules/no-direct-signal-mutation.mjs +104 -21
  12. package/eslint/rules/no-item-track-in-form-list.mjs +4 -3
  13. package/eslint/rules/require-track-index.mjs +162 -0
  14. package/eslint/signal-names.mjs +127 -21
  15. package/fesm2022/dsivd-prestations-ng.mjs +68 -22
  16. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  17. package/package.json +1 -1
  18. package/schematics/migration-collection.json +1 -1
  19. package/schematics/ng-update/migrations/update-19_2_0/index.js +15 -3
  20. package/schematics/utility/form-signal/class-migration.js +130 -6
  21. package/schematics/utility/form-signal/form-members.js +318 -0
  22. package/schematics/utility/form-signal/form-signal-migration.js +13 -75
  23. package/schematics/utility/form-signal/page-classes.js +11 -1
  24. package/schematics/utility/form-signal/template-migration.js +119 -10
  25. package/schematics/utility/never-connected-migration.js +87 -0
  26. package/schematics/utility/typescript-files.js +95 -0
  27. package/src/eslint/configs/template-rules.mjs +3 -0
  28. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +142 -0
  29. package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
  30. package/src/eslint/rules/index.mjs +2 -0
  31. package/src/eslint/rules/no-direct-signal-mutation.mjs +104 -21
  32. package/src/eslint/rules/no-item-track-in-form-list.mjs +4 -3
  33. package/src/eslint/rules/require-track-index.mjs +162 -0
  34. package/src/eslint/signal-names.mjs +127 -21
  35. package/types/dsivd-prestations-ng.d.ts +19 -3
package/README.md CHANGED
@@ -8,17 +8,23 @@ The generated documentation of our entire library is available online at [https:
8
8
 
9
9
  The documentation is available online at [https://dsi-vd.github.io/prestations-ng/](https://dsi-vd.github.io/prestations-ng/)
10
10
 
11
- - If you're using **Angular 21**, use `@dsivd/prestations-ng` at version `^19`.
12
- - If you're using **Angular 19**, use `@dsivd/prestations-ng` at version `^18`.
13
- - If you're using **Angular 17**, use `@dsivd/prestations-ng` at version `^17`.
14
- - If you're using **Angular 15**, use `@dsivd/prestations-ng` at version `^16`.
15
- - If you're using **Angular 13**, use `@dsivd/prestations-ng` at version `^15`.
16
- - If you're using **Angular 12**, use `@dsivd/prestations-ng` at version `^14.5.0`.
17
- - If you're using **Angular 11**, use `@dsivd/prestations-ng` at version `^13` until `14.4.1`.
18
- - If you're using **Angular 9**, use `@dsivd/prestations-ng` at version `^11`.
19
- - If you're using **Angular 8**, use `@dsivd/prestations-ng` at version `^9`.
20
- - If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `^8`.
21
- - If you're using **Angular 5**, use `prestations-ng` at version `^7`.
11
+ - If you're using **Angular 21**, use `@dsivd/prestations-ng` at version `19`.
12
+ - If you're using **Angular 19**, use `@dsivd/prestations-ng` at version `18`.
13
+ - If you're using **Angular 17**, use `@dsivd/prestations-ng` at version `17`.
14
+ - If you're using **Angular 15**, use `@dsivd/prestations-ng` at version `16`.
15
+ - If you're using **Angular 13**, use `@dsivd/prestations-ng` at version `15`.
16
+ - If you're using **Angular 12**, use `@dsivd/prestations-ng` at version `14`, from `14.5.0`.
17
+ - If you're using **Angular 11**, use `@dsivd/prestations-ng` at version `13`, or `14` until `14.4.1`.
18
+ - If you're using **Angular 9**, use `@dsivd/prestations-ng` at version `11`.
19
+ - If you're using **Angular 8**, use `@dsivd/prestations-ng` at version `9`.
20
+ - If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `8`.
21
+ - If you're using **Angular 5**, use `prestations-ng` at version `7`.
22
+
23
+ These are the major versions to use. In your `package.json`, declare the library with a tilde (e.g.
24
+ `"@dsivd/prestations-ng": "~19.2.0"`): a minor version may break and goes with the same minor version of
25
+ `prestations-be` (see "Dependency on `prestations-be`" below), and a caret would let `npm install` or the lock file
26
+ maintenance of Renovate install the next one. `npm install @dsivd/prestations-ng@<version>` writes a caret, even over a
27
+ tilde: install a version with `npm install @dsivd/prestations-ng@~<version>`.
22
28
 
23
29
  The library also ships an ESLint plugin whose rules apply to your project: see
24
30
  [the plugin guide](ESLINT_PLUGIN.md).
@@ -44,7 +50,7 @@ Migration guides are available to provide an upgrade path from one major version
44
50
 
45
51
  `@dsivd/prestations-ng` is part of [PrestaKit](https://www.vd.ch/prestakit/) and depends on `prestations-be`.
46
52
 
47
- In order to use all the features of `@dsivd/prestation-ng`, you must use the same minor version of `prestations-be`, see [Notes about versioning in Prestakit](CHANGELOG.md#notes-about-versioning-in-prestakit)
53
+ In order to use all the features of `@dsivd/prestations-ng`, you must use the same minor version of `prestations-be`, see [Notes about versioning in Prestakit](README_COMMON.md#notes-about-versioning-in-prestakit)
48
54
 
49
55
  `prestations-be` is available on the DSI-VD Maven repository. An exemple of integration is available with [Eldorado](https://prestations.vd.ch/pub/101016).
50
56
 
package/UPGRADING_V19.md CHANGED
@@ -259,6 +259,10 @@ ng update @angular/core@19 @angular/cli@19
259
259
  ng update @dsivd/prestations-ng@18
260
260
  ```
261
261
 
262
+ 🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
263
+ `@dsivd/prestations-ng` with a caret (e.g. `"^18.3.16"`), replace it with a tilde (`"~18.3.16"`), then run
264
+ `npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
265
+
262
266
  #### Switch to node 22+
263
267
 
264
268
  ##### If you are using our `slave-apps`
@@ -308,10 +312,11 @@ ng update @angular/core@20 @angular/cli@20
308
312
  - accept **"router-current-navigation"** by hitting "Space" key
309
313
  - hit "Enter" key
310
314
 
311
- 🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present and has a unique identifier.
312
- When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index`. Since
313
- 19.2.0, never track by object a list of the form whose rows edit their item: track it by `id` or by `$index` (see
314
- "The form of your pages is a signal").**
315
+ 🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present. Track by
316
+ `$index` the rows naming their fields with the index (`[name]="'children[' + $index + '].firstName'"`, every list of
317
+ the form): tracked by an identifier, a row whose item moves keeps the names of its former position and gets the
318
+ values and the errors of another row (`require-track-index`, since 19.2.0). Since 19.2.0, never track by object a list
319
+ of the form whose rows edit their item (see "The form of your pages is a signal").**
315
320
 
316
321
  💡 **NB: When using `@angular/cdk` in your project**
317
322
 
@@ -368,6 +373,10 @@ ng update @dsivd/prestations-ng@latest
368
373
  - accept **"router-current-navigation"** by hitting "Space" key
369
374
  - hit "Enter" key
370
375
 
376
+ 🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
377
+ `@dsivd/prestations-ng` with a caret (e.g. `"^19.1.4"`), replace it with a tilde (`"~19.1.4"`), then run
378
+ `npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
379
+
371
380
  ```bash
372
381
  ng update @angular/cli@21
373
382
  ```
@@ -394,6 +403,55 @@ ng update ngx-matomo-client@9
394
403
 
395
404
  💡 **NB: Upgrade all other libraries needed by your project (such as: primeng, lodash, ...) to their latest version compatible with angular 21**
396
405
 
406
+ ### Instructions for your AI assistant (since 19.2.0)
407
+
408
+ The library ships [AI_GUIDELINES.md](AI_GUIDELINES.md): the rules an AI assistant (Claude Code, GitHub Copilot...)
409
+ follows in a project using it, for the version installed. Give them to your assistant now, so that it follows them
410
+ for the rest of this migration. The versions before 19.2.0 (e.g. 19.1.x) don't have the file: skip this step, and come
411
+ back to it once you upgrade to 19.2.0.
412
+
413
+ At the root of the project holding the front (not in the `front` folder):
414
+
415
+ 1. For Claude Code, create the `.claude` folder and its `CLAUDE.md` file if they don't exist, and add the import of
416
+ the file, its path being relative to `CLAUDE.md`:
417
+
418
+ ```text
419
+ @../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
420
+ ```
421
+
422
+ 2. For the other assistants (GitHub Copilot, Codex, Cursor...), create the `AGENTS.md` file if it doesn't exist, and
423
+ add this sentence to it: they read `AGENTS.md`, but can't import a file.
424
+
425
+ ```text
426
+ Before changing the front, read and follow `front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`:
427
+ the rules of the installed version of `@dsivd/prestations-ng`.
428
+ ```
429
+
430
+ Then:
431
+
432
+ - The project is your repository or, in a repository holding several projects (e.g. `my-project-fo/front` and
433
+ `my-project-bo/front`), the folder of each one: each project gets its own `.claude/CLAUDE.md` and `AGENTS.md`, with
434
+ the rules of its version of `prestations-ng`. Claude Code loads `.claude/CLAUDE.md` when it's started in the
435
+ project or one of its folders (e.g. `front`) or, started at the root of the repository, as soon as it reads a file
436
+ of the project.
437
+ - If the project already has a `CLAUDE.md` at its root, add the import there rather than creating a second file:
438
+ `@front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
439
+ - A project with several fronts, or an Angular library shared by the fronts of the repository: both files in the
440
+ folder of each one, next to its `node_modules`, with `@../node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` and
441
+ `node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
442
+ - Keep the import in `.claude/CLAUDE.md` even with `AGENTS.md`: Claude Code reads `AGENTS.md` only in a folder
443
+ without `CLAUDE.md`, and not in every mode.
444
+ - An import loads nothing until the dependencies of its front are installed (`npm ci` after a clone): until then,
445
+ your assistant doesn't have the rules.
446
+ - Commit `.claude/CLAUDE.md` and `AGENTS.md`, so that the whole team gets the rules, but not the permissions each
447
+ developer grants to Claude Code for the project, which it keeps in `.claude/settings.local.json`: add
448
+ `**/.claude/settings.local.json` to the `.gitignore` of your repository.
449
+ - Refer to the file rather than copying it: the rules follow the version installed at each upgrade, those of
450
+ Renovate included, without changing your files.
451
+
452
+ 💡 **NB: The rules describe the code once migrated. Your assistant follows the steps of this guide in order, without
453
+ anticipating the next ones: `AI_GUIDELINES.md` tells it so.**
454
+
397
455
  ### Quick fix
398
456
 
399
457
  - In all custom components extending `FoehnInputComponent`, in `providers` providing `FoehnInputComponent` remove `multi: true,`.
@@ -1603,6 +1661,20 @@ removed item stays in the form and comes back when the form is saved. In a page,
1603
1661
  }
1604
1662
  ```
1605
1663
 
1664
+ ### `FoehnListItem` has no `trackingIndex` (since 19.2.0)
1665
+
1666
+ The library tracks the rows of a list by their index (see `require-track-index` in [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)):
1667
+ `FoehnListItem.trackingIndex` is removed, and `AbstractListDetailPageComponent` no longer sets it on a new item
1668
+ (`getNextTrackingIndex()` is removed too). The id of a row of `foehn-list-summary` is `list-summary-<its position
1669
+ from 1>`.
1670
+
1671
+ - Track your lists by `$index`, not by `item.trackingIndex`.
1672
+ - The code reading `trackingIndex` on an item typed with `FoehnListItem`, or calling or overriding
1673
+ `getNextTrackingIndex()`, no longer compiles: remove it.
1674
+ - 🚨 Nothing reports a backend needing the field (e.g. a `@NotNull trackingIndex`, a list sorted by it): a new item
1675
+ now reaches it without one. Remove the field from the backend and from its data, or, to keep it, declare it in your
1676
+ item class and set it in `getNewListItem()`.
1677
+
1606
1678
  ### `core-js` is no longer needed (since 19.2.0)
1607
1679
 
1608
1680
  prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
@@ -1645,6 +1717,34 @@ In the templates, it reads it through a `@let reference = this.reference();`, so
1645
1717
  (`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
1646
1718
  which would hide the signal, and lists such a field holding a value.
1647
1719
 
1720
+ The migration only adds the parentheses: the request still leaves when your code sends it, whatever the reference
1721
+ (`api/undefined/...` before the form is loaded), and isn't sent again when the reference changes. Turn a request built
1722
+ with the reference into a resource (see [AI_GUIDELINES.md](AI_GUIDELINES.md)), which waits for the reference and
1723
+ replaces the subscription, or the `async` pipe, and the fields that only served it. E.g. the sections of the
1724
+ verification page:
1725
+
1726
+ ```ts
1727
+ readonly recapSections = httpResource<FoehnRecapSection[]>(
1728
+ () => {
1729
+ const reference = this.reference();
1730
+ return reference ? `api/${reference}/pdf-sections` : undefined;
1731
+ },
1732
+ { defaultValue: [] },
1733
+ );
1734
+ ```
1735
+
1736
+ ```angular
1737
+ @if (recapSections.hasValue()) {
1738
+ @for (section of recapSections.value(); track $index) {
1739
+ <foehn-recap-section [data]="section" />
1740
+ }
1741
+ }
1742
+ ```
1743
+
1744
+ A request built by a method of a service: an `rxResource()` over it, whose `params` return `undefined` while the
1745
+ reference is missing. See "`rxResource()`" in [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md),
1746
+ for your specs too.
1747
+
1648
1748
  For a code it doesn't migrate (a class it doesn't recognize as a page):
1649
1749
 
1650
1750
  - in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
@@ -1732,6 +1832,37 @@ too (`this.form.x` doesn't exist on a signal):
1732
1832
  `*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
1733
1833
  - the `getList()` of the detail pages which compute their list, see below.
1734
1834
 
1835
+ It follows the getters of the page returning a path of the form, declared by the page or by a page it extends
1836
+ (since 19.2.0-beta.29, also in a page migrated by an earlier beta):
1837
+
1838
+ ```diff
1839
+ get step(): Step {
1840
+ - return this.form.etape;
1841
+ + return this.form()!.etape;
1842
+ }
1843
+
1844
+ - this.step.motif = value;
1845
+ + this.patchForm(['etape', 'motif'], value);
1846
+ ```
1847
+
1848
+ ```diff
1849
+ - <foehn-input-text name="motif" [(model)]="step.motif" />
1850
+ + <foehn-input-text name="motif" [model]="step.motif" (modelChange)="patchForm(['etape', 'motif'], $event)" />
1851
+ ```
1852
+
1853
+ Since 19.2.0-beta.29, it also lists what the compiler doesn't report:
1854
+
1855
+ - the writes through a getter it can't rewrite, or through a getter computing its value
1856
+ (`return this.form?.etape ?? new Step();`): what such a getter returns may not be in the form. Write the form with
1857
+ `patchForm()`, the path of the field in full;
1858
+ - the `effect()`s reading the form, directly or through a method they call: the migration turns `this.form` into
1859
+ `this.form()` there too, and the effect then runs again at every input of the user. When the form isn't a trigger
1860
+ of the effect, read it with `untracked(this.form)`, or call the method in `untracked(() => this.applyResult(x))`;
1861
+ - the methods of the page writing the form or the reference called by its template outside an event
1862
+ (`@if (initDefaults())`, `[hidden]="!check()"`, `{{ total() }}`): a signal written while the view is rendered
1863
+ throws NG0600. Make them pure, and write the form where it is loaded (see "`(modelChange)` is emitted only when
1864
+ the component writes its model").
1865
+
1735
1866
  Also check:
1736
1867
 
1737
1868
  - your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
@@ -1750,14 +1881,16 @@ Also check:
1750
1881
  not those of a callback given to a service.
1751
1882
 
1752
1883
  `no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
1753
- `[(model)]="form.x"` inside `@if (form(); as form)` included.
1884
+ `[(model)]="form.x"` inside `@if (form(); as form)` included, and since 19.2.0-beta.29 those through a getter of the
1885
+ page returning the form or a part of it (`this.step.motif = x`, `[(model)]="step.motif"`).
1754
1886
 
1755
1887
  #### Lists of the form
1756
1888
 
1757
1889
  `patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
1758
1890
  is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
1759
- list edited by its rows by an identifier of the item (`track child.id`), or by `$index`. The migration does it for the
1760
- lists it migrates, and `no-item-track-in-form-list` (`configs.templateRecommended`) reports the others.
1891
+ list edited by its rows by `$index`, the index naming their fields (an identifier of the item, `track child.id`, only
1892
+ when they name nothing with it). The migration does it for the lists it migrates, and `no-item-track-in-form-list`
1893
+ and `require-track-index` (`configs.templateRecommended`) report the others.
1761
1894
 
1762
1895
  #### Write your templates
1763
1896
 
@@ -1807,6 +1940,20 @@ getListPath(): ObjectPath<ApForm | AfForm> {
1807
1940
  }
1808
1941
  ```
1809
1942
 
1943
+ ### `neverConnected` is provided with `NEVER_CONNECTED` (since 19.2.0)
1944
+
1945
+ `SessionInfo` reads the `NEVER_CONNECTED` token: a provider `{ provide: 'neverConnected', useValue: true }` is ignored
1946
+ without any error, and your application fetches the session and displays the connected user or the login button.
1947
+ `ng update @dsivd/prestations-ng` replaces it (see "Run the migration" above to run it by hand):
1948
+
1949
+ ```diff
1950
+ - { provide: 'neverConnected', useValue: true },
1951
+ + { provide: NEVER_CONNECTED, useValue: true },
1952
+ ```
1953
+
1954
+ with `NEVER_CONNECTED` imported from `@dsivd/prestations-ng`. It lists the other uses of the string `'neverConnected'`
1955
+ it doesn't rewrite: search them in your providers, e.g. a value coming from a constant or a shared library.
1956
+
1810
1957
  ### Zoneless (optional but recommended)
1811
1958
 
1812
1959
  Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
@@ -20,6 +20,9 @@ const templateRules = (plugin) => [
20
20
  // loses the focus at every input
21
21
  '@dsivd/prestations-ng/require-model-change': 'error',
22
22
  '@dsivd/prestations-ng/no-item-track-in-form-list': 'error',
23
+ // The rows naming their fields with their index keep these names
24
+ // only when tracked by $index
25
+ '@dsivd/prestations-ng/require-track-index': 'error',
23
26
  },
24
27
  },
25
28
  ];
@@ -2,10 +2,12 @@ import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
2
2
  import noItemTrackInFormList from './no-item-track-in-form-list.mjs';
3
3
  import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
4
4
  import requireModelChange from './require-model-change.mjs';
5
+ import requireTrackIndex from './require-track-index.mjs';
5
6
 
6
7
  export default {
7
8
  'no-direct-signal-mutation': noDirectSignalMutation,
8
9
  'no-item-track-in-form-list': noItemTrackInFormList,
9
10
  'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
10
11
  'require-model-change': requireModelChange,
12
+ 'require-track-index': requireTrackIndex,
11
13
  };
@@ -8,7 +8,7 @@ import {
8
8
  VIEW_QUERY,
9
9
  WRITABLE,
10
10
  } from "../signal-kinds.mjs";
11
- import { collectSignalKinds } from "../signal-names.mjs";
11
+ import { collectSignalAliases, collectSignalKinds } from "../signal-names.mjs";
12
12
  import {
13
13
  handlerExpressionOf,
14
14
  isComponentReceiver,
@@ -30,6 +30,10 @@ import {
30
30
  *
31
31
  * Only the signals the class really declares are inspected, resolved through the whole
32
32
  * inheritance chain, so a plain method (`this.getConfig().items.push(x)`) is left alone.
33
+ *
34
+ * A getter of the class returning the value of a signal, or a part of it
35
+ * (`get step() { return this.form()!.step; }`), hands out that value too: a write through
36
+ * it (`this.step.motif = x`, `[(model)]="step.motif"`) is reported as well.
33
37
  */
34
38
 
35
39
  // Kinds a mutation is not reported on: a view query hands out a DOM element or a component
@@ -201,6 +205,33 @@ function signalFactoryKind(node) {
201
205
  return callee?.type === "Identifier" ? factoryKind(callee.name) : undefined;
202
206
  }
203
207
 
208
+ // The value of a signal of the class: its kind, and the getter it was read through, if any.
209
+ const valueOf = (kind) => (kind ? { kind } : undefined);
210
+
211
+ /**
212
+ * The getter of the class a member chain reads first, `this.step` in `this.step.motif`,
213
+ * when it aliases the value of a signal. `undefined` for anything else.
214
+ */
215
+ function aliasReadOf(node, scopeContext) {
216
+ let current = node;
217
+ while (
218
+ current?.type === "MemberExpression" ||
219
+ TYPE_WRAPPERS.has(current?.type)
220
+ ) {
221
+ if (
222
+ current.type === "MemberExpression" &&
223
+ current.object.type === "ThisExpression"
224
+ ) {
225
+ const name = current.computed ? undefined : getCalledName(current);
226
+ const alias = name ? scopeContext.alias(name) : undefined;
227
+ return alias ? { ...alias, getter: name } : undefined;
228
+ }
229
+ current =
230
+ current.type === "MemberExpression" ? current.object : current.expression;
231
+ }
232
+ return undefined;
233
+ }
234
+
204
235
  function signalRootCallKind(node, scopeContext) {
205
236
  if (node.arguments.length !== 0) {
206
237
  return undefined;
@@ -233,14 +264,18 @@ function signalRootCallKind(node, scopeContext) {
233
264
  }
234
265
 
235
266
  /**
236
- * Kind of signal whose value an expression evaluates to, `undefined` when it is not one.
237
- * The expression may be the signal read itself (`this.model()`), a member of its value
238
- * (`this.model().items`), or a name bound to either.
267
+ * The value of a signal an expression evaluates to (`{ kind, getter? }`), `undefined` when
268
+ * it is not one. The expression may be the signal read itself (`this.model()`), a member of
269
+ * its value (`this.model().items`), a getter aliasing either (`this.step.items`), or a name
270
+ * bound to any of them.
239
271
  */
240
272
  function signalValueKind(node, scopeContext, seen = new Set()) {
241
273
  const base = baseOf(node);
242
274
  if (base?.type === "CallExpression") {
243
- return signalRootCallKind(base, scopeContext);
275
+ return valueOf(signalRootCallKind(base, scopeContext));
276
+ }
277
+ if (base?.type === "ThisExpression") {
278
+ return aliasReadOf(node, scopeContext);
244
279
  }
245
280
  return base?.type === "Identifier"
246
281
  ? boundNameSignalKind(base, scopeContext, seen)
@@ -314,7 +349,7 @@ function signalRootTemplateCallKind(node, templateContext) {
314
349
  return undefined;
315
350
  }
316
351
  return isComponentReceiver(callee.receiver)
317
- ? templateContext.memberKind(callee.name ?? "")
352
+ ? valueOf(templateContext.memberKind(callee.name ?? ""))
318
353
  : undefined;
319
354
  }
320
355
 
@@ -352,10 +387,19 @@ function boundTemplateExpression(read, templateContext) {
352
387
  }
353
388
 
354
389
  /**
355
- * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, or
356
- * a template name bound to either.
390
+ * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, a
391
+ * getter of the component aliasing either, or a template name bound to any of them.
392
+ *
393
+ * `assigned`: the expression is the target of an assignment (`step.motif = x`, or the
394
+ * expression of a two-way binding), so the getter itself as the whole target
395
+ * (`step = x`) calls its setter and mutates nothing.
357
396
  */
358
- function signalTemplateValueKind(node, templateContext, seen = new Set()) {
397
+ function signalTemplateValueKind(
398
+ node,
399
+ templateContext,
400
+ seen = new Set(),
401
+ assigned = false,
402
+ ) {
359
403
  const value = unwrapTemplate(node);
360
404
  if (value?.type === "Call" || value?.type === "SafeCall") {
361
405
  return signalRootTemplateCallKind(value, templateContext);
@@ -379,11 +423,15 @@ function signalTemplateValueKind(node, templateContext, seen = new Set()) {
379
423
  return undefined;
380
424
  }
381
425
  seen.add(base.name);
382
- return signalTemplateValueKind(
383
- boundTemplateExpression(base, templateContext),
384
- templateContext,
385
- seen,
386
- );
426
+ const bound = boundTemplateExpression(base, templateContext);
427
+ if (bound === undefined) {
428
+ // A member of the component, not shadowed by a name of the template.
429
+ const alias = templateContext.alias(base.name);
430
+ return alias && (value !== base || !assigned)
431
+ ? { ...alias, getter: base.name }
432
+ : undefined;
433
+ }
434
+ return signalTemplateValueKind(bound, templateContext, seen);
387
435
  }
388
436
 
389
437
  // Method a template call invokes, `undefined` when the name is not statically known.
@@ -413,6 +461,8 @@ export default {
413
461
  "In-place mutation of a signal's value detected. `{{method}}` changes the value without notifying the signal: use .update() with a new value instead.",
414
462
  readOnlyMutation:
415
463
  "Mutation of the value of {{kind}} detected, which notifies none of its dependents. {{advice}}.",
464
+ getterMutation:
465
+ "Mutation of the value of {{signal}} through the getter `{{getter}}` detected, which notifies none of its dependents. {{advice}}.",
416
466
  },
417
467
  },
418
468
 
@@ -422,18 +472,41 @@ export default {
422
472
  const declaringPath =
423
473
  resolveComponentPath(context.filename) ?? context.filename;
424
474
  const memberKinds = collectSignalKinds(declaringPath);
475
+ const aliases = collectSignalAliases(declaringPath);
425
476
 
426
477
  // `memberKinds` is undefined when the declaring file could not be read: its signals
427
478
  // are unknown, so fall back to treating every argument-less accessor as a writable
428
- // one. A false positive costs a disable comment; a missed mutation is silent.
479
+ // one. A false positive costs a disable comment; a missed mutation is silent. Its
480
+ // getters are unknown too: none is taken for an alias.
429
481
  const memberKind = (name) =>
430
482
  memberKinds ? memberKinds.get(name) : WRITABLE;
483
+ const alias = (name) => aliases?.get(name);
431
484
 
432
- const reportMutation = (node, kind, method) => {
485
+ const reportMutation = (node, value, method) => {
486
+ const kind = value?.kind;
433
487
  if (!kind || TOLERATED_KINDS.has(kind)) {
434
488
  return;
435
489
  }
436
- if (kind !== WRITABLE) {
490
+ if (value.getter) {
491
+ const [name, advice] =
492
+ kind === WRITABLE
493
+ ? [
494
+ "the signal",
495
+ method
496
+ ? `\`${method}\` changes it in place: write a new value with .set() or .update() instead (patchForm() for the form of a page)`
497
+ : "Write a new value with .set() or .update() instead (patchForm() for the form of a page)",
498
+ ]
499
+ : READ_ONLY_ADVICE[kind];
500
+ context.report({
501
+ node,
502
+ messageId: "getterMutation",
503
+ data: {
504
+ signal: `${name} \`${value.signal}\``,
505
+ getter: value.getter,
506
+ advice,
507
+ },
508
+ });
509
+ } else if (kind !== WRITABLE) {
437
510
  const [name, advice] = READ_ONLY_ADVICE[kind];
438
511
  context.report({
439
512
  node,
@@ -447,9 +520,9 @@ export default {
447
520
  }
448
521
  };
449
522
 
450
- const scopeContext = { memberKind, sourceCode: context.sourceCode };
523
+ const scopeContext = { memberKind, alias, sourceCode: context.sourceCode };
451
524
  // `@let` bindings, always declared before they are used.
452
- const templateContext = { memberKind, letBindings: new Map() };
525
+ const templateContext = { memberKind, alias, letBindings: new Map() };
453
526
 
454
527
  const checkTemplateInPlaceCall = (node) => {
455
528
  const method = templateMethodName(node.receiver);
@@ -471,6 +544,16 @@ export default {
471
544
  }
472
545
  },
473
546
 
547
+ // `this.model().count++` writes into the value, like `+= 1`.
548
+ UpdateExpression(node) {
549
+ if (node.argument.type === "MemberExpression") {
550
+ reportMutation(
551
+ node,
552
+ signalValueKind(node.argument.object, scopeContext),
553
+ );
554
+ }
555
+ },
556
+
474
557
  UnaryExpression(node) {
475
558
  // `delete model().users[0]` drops an entry of the value, notifying nothing.
476
559
  if (
@@ -519,7 +602,7 @@ export default {
519
602
  if (TEMPLATE_ASSIGNMENTS.has(node.operation)) {
520
603
  reportMutation(
521
604
  node,
522
- signalTemplateValueKind(node.left, templateContext),
605
+ signalTemplateValueKind(node.left, templateContext, new Set(), true),
523
606
  );
524
607
  }
525
608
  },
@@ -537,7 +620,7 @@ export default {
537
620
  const handler = handlerExpressionOf(node);
538
621
  reportMutation(
539
622
  handler,
540
- signalTemplateValueKind(handler, templateContext),
623
+ signalTemplateValueKind(handler, templateContext, new Set(), true),
541
624
  );
542
625
  },
543
626
  };
@@ -11,8 +11,9 @@ import { astOf, resolveRoot } from "../form-reads.mjs";
11
11
  * `FoehnInputComponent` writes a new list in its model, its items replaced (`updateNgModel()`).
12
12
  * A row tracked by its item is then destroyed and created again at every input, and the field
13
13
  * being edited loses the focus; two items equal by value (e.g. two empty strings) even collide.
14
- * Track the rows by `$index`, or by an identifier of the item (`track child.id`), which the copy
15
- * keeps.
14
+ * Track the rows by `$index`: an identifier of the item (`track child.id`), which the copy keeps,
15
+ * only when the rows name nothing with their index (see `require-track-index`, which reports
16
+ * these lists too when they do).
16
17
  *
17
18
  * A row edits its item when one of its elements has a `model` read from it
18
19
  * (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
@@ -108,7 +109,7 @@ export default {
108
109
  schema: [],
109
110
  messages: {
110
111
  itemTrack:
111
- "The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index or by an identifier of the item.",
112
+ "The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index (by an identifier of the item only when the rows name nothing with their index).",
112
113
  trackByIndex: "Track the rows by $index",
113
114
  },
114
115
  },