@dsivd/prestations-ng 19.2.0-beta.3 → 19.2.0-beta.30

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 (65) hide show
  1. package/AI_GUIDELINES.md +152 -0
  2. package/ANGULAR_SIGNALS.md +6 -2
  3. package/CHANGELOG.md +476 -0
  4. package/CONTRIBUTING.md +128 -8
  5. package/ESLINT_PLUGIN.md +262 -30
  6. package/GOOD_PRACTICES.md +983 -388
  7. package/INTRODUCTION_ANGULAR_SIGNALS.md +227 -155
  8. package/README.md +22 -12
  9. package/UPGRADING_V18.md +5 -5
  10. package/UPGRADING_V19.md +636 -19
  11. package/eslint/configs/spec-ts-recommended.mjs +34 -0
  12. package/eslint/configs/template-recommended.mjs +2 -0
  13. package/eslint/configs/template-rules.mjs +14 -2
  14. package/eslint/configs/ts-recommended.mjs +11 -0
  15. package/eslint/configs/ts-rules.mjs +6 -2
  16. package/eslint/form-reads.mjs +63 -0
  17. package/eslint/index.mjs +17 -0
  18. package/eslint/rules/index.mjs +6 -0
  19. package/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  20. package/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  21. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  22. package/eslint/rules/require-model-change.mjs +89 -0
  23. package/eslint/rules/require-track-index.mjs +162 -0
  24. package/eslint/signal-names.mjs +127 -21
  25. package/eslint/template-ast.mjs +12 -2
  26. package/fesm2022/dsivd-prestations-ng.mjs +2889 -2061
  27. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  28. package/package.json +1 -2
  29. package/schematics/migration-collection.json +5 -0
  30. package/schematics/ng-add/index.js +2 -4
  31. package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
  32. package/schematics/ng-update/migrations/update-19_2_0/index.js +52 -0
  33. package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
  34. package/schematics/utility/form-signal/class-migration.js +795 -0
  35. package/schematics/utility/form-signal/edits.js +34 -0
  36. package/schematics/utility/form-signal/form-members.js +318 -0
  37. package/schematics/utility/form-signal/form-signal-migration.js +134 -0
  38. package/schematics/utility/form-signal/page-classes.js +139 -0
  39. package/schematics/utility/form-signal/template-migration.js +775 -0
  40. package/schematics/utility/never-connected-migration.js +87 -0
  41. package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
  42. package/schematics/utility/typescript-files.js +95 -0
  43. package/src/eslint/configs/__tests__/configs.test.mjs +61 -2
  44. package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
  45. package/src/eslint/configs/template-recommended.mjs +2 -0
  46. package/src/eslint/configs/template-rules.mjs +14 -2
  47. package/src/eslint/configs/ts-recommended.mjs +11 -0
  48. package/src/eslint/configs/ts-rules.mjs +6 -2
  49. package/src/eslint/form-reads.mjs +63 -0
  50. package/src/eslint/index.mjs +17 -0
  51. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +200 -0
  52. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  53. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  54. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  55. package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
  56. package/src/eslint/rules/index.mjs +6 -0
  57. package/src/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  58. package/src/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  59. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  60. package/src/eslint/rules/require-model-change.mjs +89 -0
  61. package/src/eslint/rules/require-track-index.mjs +162 -0
  62. package/src/eslint/signal-names.mjs +127 -21
  63. package/src/eslint/template-ast.mjs +12 -2
  64. package/types/dsivd-prestations-ng.d.ts +719 -243
  65. package/dsivd-prestations-ng-19.2.0-beta.3.tgz +0 -0
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The house preset of the Vitest specs: the recommended rules of `@vitest/eslint-plugin`, with the
3
+ * assertions also made by the helpers of the specs and by the `HttpTestingController`.
4
+ *
5
+ * Meant for the `extends` of a `**\/*.spec.ts` block (the Cypress `*.spec.cy.ts` files are not
6
+ * Vitest specs).
7
+ *
8
+ * @param {import('@vitest/eslint-plugin').default} vitest the `@vitest/eslint-plugin` module
9
+ * @returns {import('typescript-eslint').ConfigArray}
10
+ */
11
+ const specTsRecommended = (vitest) => [
12
+ vitest.configs.recommended,
13
+ {
14
+ name: 'prestations-ng/spec-ts-recommended',
15
+ rules: {
16
+ 'vitest/expect-expect': [
17
+ 'error',
18
+ {
19
+ assertFunctionNames: [
20
+ 'expect',
21
+ 'expect*',
22
+ 'assert*',
23
+ 'test*',
24
+ '*.expectOne',
25
+ '*.expectNone',
26
+ '*.verify',
27
+ ],
28
+ },
29
+ ],
30
+ },
31
+ },
32
+ ];
33
+
34
+ export default specTsRecommended;
@@ -8,6 +8,8 @@ import templateRules from './template-rules.mjs';
8
8
  *
9
9
  * Meant for the `extends` of a `**\/*.html` block. It brings its own parser and plugins,
10
10
  * so do not spread `angular.configs.templateRecommended` alongside it.
11
+ *
12
+ * @returns {import('typescript-eslint').ConfigArray}
11
13
  */
12
14
  const templateRecommended = (plugin) => [
13
15
  ...angular.configs.templateRecommended,
@@ -1,7 +1,11 @@
1
1
  import templateBase from './template-base.mjs';
2
2
 
3
- // Only the rules written by this library. `templateRecommended` includes it, alongside
4
- // the house style; use this layer directly to opt out of the latter.
3
+ /**
4
+ * Only the rules written by this library. `templateRecommended` includes it, alongside
5
+ * the house style; use this layer directly to opt out of the latter.
6
+ *
7
+ * @returns {import('typescript-eslint').ConfigArray}
8
+ */
5
9
  const templateRules = (plugin) => [
6
10
  templateBase(plugin),
7
11
  {
@@ -11,6 +15,14 @@ const templateRules = (plugin) => [
11
15
  // template visitor, and each fires on its own kind of file.
12
16
  '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
13
17
  '@dsivd/prestations-ng/no-uninvoked-signal-in-template': 'error',
18
+ // The form of the pages is a signal: a one-way [model] without
19
+ // (modelChange) loses the input, and a row tracked by its item
20
+ // loses the focus at every input
21
+ '@dsivd/prestations-ng/require-model-change': 'error',
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',
14
26
  },
15
27
  },
16
28
  ];
@@ -14,6 +14,8 @@ import tsRules from './ts-rules.mjs';
14
14
  * Meant for the `extends` of a `**\/*.ts` block. It brings its own parser and plugins,
15
15
  * so do not spread `angular.configs.tsRecommended` alongside it — declaring the same
16
16
  * plugin twice from two different copies makes ESLint fail outright.
17
+ *
18
+ * @returns {import('typescript-eslint').ConfigArray}
17
19
  */
18
20
  const tsRecommended = (plugin) => [
19
21
  eslint.configs.recommended,
@@ -71,6 +73,10 @@ const tsRecommended = (plugin) => [
71
73
  ],
72
74
  '@typescript-eslint/member-ordering': 'error',
73
75
  '@typescript-eslint/no-base-to-string': 'warn',
76
+ // a template literal only takes strings, numbers, booleans, null,
77
+ // undefined, any and RegExp: also reports a signal not called
78
+ // (`${this.reference}`), which no-uncalled-signals skips there
79
+ '@typescript-eslint/restrict-template-expressions': 'error',
74
80
  // stylistic enables no-inferrable-types with default options (ignoreParameters: false);
75
81
  // override here to allow typed parameters explicitly
76
82
  '@typescript-eslint/no-inferrable-types': [
@@ -86,6 +92,11 @@ const tsRecommended = (plugin) => [
86
92
  // off here — @typescript-eslint/no-shadow handles it correctly for TS
87
93
  'no-shadow': 'off',
88
94
  '@typescript-eslint/no-shadow': ['error', { hoist: 'all' }],
95
+ // a constructor only passing its parameters to super(), e.g. the
96
+ // `constructor() { super(); }` left once the services are injected with
97
+ // inject(); off here — the core rule ignores the parameter properties
98
+ 'no-useless-constructor': 'off',
99
+ '@typescript-eslint/no-useless-constructor': 'error',
89
100
  '@typescript-eslint/no-unused-vars': [
90
101
  'error',
91
102
  {
@@ -1,7 +1,11 @@
1
1
  import tsBase from './ts-base.mjs';
2
2
 
3
- // Only the rules written by this library. `tsRecommended` includes it, alongside the
4
- // house style; use this layer directly to opt out of the latter.
3
+ /**
4
+ * Only the rules written by this library. `tsRecommended` includes it, alongside the
5
+ * house style; use this layer directly to opt out of the latter.
6
+ *
7
+ * @returns {import('typescript-eslint').ConfigArray}
8
+ */
5
9
  const tsRules = (plugin) => [
6
10
  tsBase(plugin),
7
11
  {
@@ -0,0 +1,63 @@
1
+ import { isComponentReceiver } from "./template-ast.mjs";
2
+
3
+ /**
4
+ * Where a template expression reads its value from: the form of the page (a signal since
5
+ * 19.2.0), through the names bound by `@if (form(); as form)`, `@let form = this.form()` and
6
+ * `@for (child of form.children)`.
7
+ */
8
+
9
+ const MEMBER_READS = new Set([
10
+ "PropertyRead",
11
+ "SafePropertyRead",
12
+ "KeyedRead",
13
+ "SafeKeyedRead",
14
+ ]);
15
+
16
+ export const astOf = (expression) =>
17
+ expression?.type === "ASTWithSource" ? expression.ast : expression;
18
+
19
+ /**
20
+ * The root of an expression: a member of the component (`{ member }`), or the item of an
21
+ * enclosing `@for` (`{ forBlock }`). A name bound by `@if … as` is followed to its expression,
22
+ * evaluated outside its block (in `@if (form(); as form)`, `form()` is the member).
23
+ * `undefined` for anything else (a literal, a call with arguments...).
24
+ */
25
+ export function resolveRoot(expression, node) {
26
+ let base = expression;
27
+ while (MEMBER_READS.has(base?.type) && MEMBER_READS.has(base.receiver?.type)) {
28
+ base = base.receiver;
29
+ }
30
+ if (base?.type === "Call" || base?.type === "SafeCall") {
31
+ base = base.receiver;
32
+ }
33
+ const receiver = base?.receiver;
34
+ if (receiver?.type === "Call" || receiver?.type === "SafeCall") {
35
+ return resolveRoot(receiver, node);
36
+ }
37
+ if (!MEMBER_READS.has(base?.type) || !isComponentReceiver(receiver)) {
38
+ return undefined;
39
+ }
40
+ for (let current = node; current; current = current.parent) {
41
+ if (current.type === "ForLoopBlock" && current.item?.name === base.name) {
42
+ return { forBlock: current };
43
+ }
44
+ if (
45
+ current.type === "IfBlockBranch" &&
46
+ current.expressionAlias?.name === base.name
47
+ ) {
48
+ return resolveRoot(astOf(current.expression), current.parent);
49
+ }
50
+ }
51
+ return { member: base.name };
52
+ }
53
+
54
+ /**
55
+ * Whether an expression reads the form of the page, directly or through a template name.
56
+ */
57
+ export function readsForm(expression, node) {
58
+ const root = resolveRoot(expression, node);
59
+ if (root?.forBlock) {
60
+ return readsForm(astOf(root.forBlock.expression), root.forBlock.parent);
61
+ }
62
+ return root?.member === "form";
63
+ }
package/eslint/index.mjs CHANGED
@@ -1,9 +1,17 @@
1
+ import specTsRecommended from './configs/spec-ts-recommended.mjs';
1
2
  import templateRecommended from './configs/template-recommended.mjs';
2
3
  import templateRules from './configs/template-rules.mjs';
3
4
  import tsRecommended from './configs/ts-recommended.mjs';
4
5
  import tsRules from './configs/ts-rules.mjs';
5
6
  import rules from './rules/index.mjs';
6
7
 
8
+ // Only needed by the projects linting Vitest specs: the other configs can be used without it.
9
+ const vitest = await import('@vitest/eslint-plugin').then(
10
+ (module) => module.default,
11
+ () => null,
12
+ );
13
+ const specTsRecommendedConfig = vitest ? specTsRecommended(vitest) : null;
14
+
7
15
  const plugin = {
8
16
  meta: { name: '@dsivd/prestations-ng' },
9
17
  rules,
@@ -16,6 +24,15 @@ const configs = {
16
24
  // Only this library's own rules, for a project that supplies its own style.
17
25
  tsRules: tsRules(plugin),
18
26
  templateRules: templateRules(plugin),
27
+ // The preset of the Vitest specs (needs @vitest/eslint-plugin)
28
+ get specTsRecommended() {
29
+ if (!specTsRecommendedConfig) {
30
+ throw new Error(
31
+ 'prestationsNg.configs.specTsRecommended needs @vitest/eslint-plugin: npm install --save-dev @vitest/eslint-plugin@1',
32
+ );
33
+ }
34
+ return specTsRecommendedConfig;
35
+ },
19
36
  };
20
37
 
21
38
  export { configs, plugin, rules };
@@ -1,7 +1,13 @@
1
1
  import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
2
+ import noItemTrackInFormList from './no-item-track-in-form-list.mjs';
2
3
  import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
4
+ import requireModelChange from './require-model-change.mjs';
5
+ import requireTrackIndex from './require-track-index.mjs';
3
6
 
4
7
  export default {
5
8
  'no-direct-signal-mutation': noDirectSignalMutation,
9
+ 'no-item-track-in-form-list': noItemTrackInFormList,
6
10
  'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
11
+ 'require-model-change': requireModelChange,
12
+ 'require-track-index': requireTrackIndex,
7
13
  };
@@ -8,8 +8,12 @@ import {
8
8
  VIEW_QUERY,
9
9
  WRITABLE,
10
10
  } from "../signal-kinds.mjs";
11
- import { collectSignalKinds } from "../signal-names.mjs";
12
- import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
11
+ import { collectSignalAliases, collectSignalKinds } from "../signal-names.mjs";
12
+ import {
13
+ handlerExpressionOf,
14
+ isComponentReceiver,
15
+ isTwoWayBinding,
16
+ } from "../template-ast.mjs";
13
17
 
14
18
  /**
15
19
  * ESLint rule to detect mutations of the value held by a signal.
@@ -17,7 +21,8 @@ import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
17
21
  * Suggests using .update() or .set() instead.
18
22
  *
19
23
  * Applies to TypeScript files and to Angular templates, where the mutation is also
20
- * hidden in every two-way binding on a call result: [(ngModel)]="model().property".
24
+ * hidden in every two-way binding on a call result: [(ngModel)]="model().property", or on
25
+ * a name bound to it: [(model)]="form.property" inside @if (form(); as form).
21
26
  *
22
27
  * No signal's value is to be mutated, whatever its kind — a mutation notifies none of its
23
28
  * dependents. A view query is the single exception: it hands out a DOM element or a
@@ -25,6 +30,10 @@ import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
25
30
  *
26
31
  * Only the signals the class really declares are inspected, resolved through the whole
27
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.
28
37
  */
29
38
 
30
39
  // Kinds a mutation is not reported on: a view query hands out a DOM element or a component
@@ -106,6 +115,9 @@ const TEMPLATE_MEMBER_READS = new Set([
106
115
  "SafeKeyedRead",
107
116
  ]);
108
117
 
118
+ // Template wrappers that leave the value as is: `form()!`, `(form())`.
119
+ const TEMPLATE_WRAPPERS = new Set(["NonNullAssert", "ParenthesizedExpression"]);
120
+
109
121
  // ── TypeScript ───────────────────────────────────────────────────────────────
110
122
 
111
123
  function getCalledName(callee) {
@@ -140,9 +152,18 @@ function isObjectAssign(callee) {
140
152
  );
141
153
  }
142
154
 
155
+ // TypeScript wrappers that leave the value as is: `form()!`, `form() as Form`...
156
+ const TYPE_WRAPPERS = new Set([
157
+ "TSNonNullExpression",
158
+ "TSAsExpression",
159
+ "TSSatisfiesExpression",
160
+ "TSTypeAssertion",
161
+ ]);
162
+
143
163
  /**
144
164
  * What a member chain is rooted at, the property and index reads stripped away:
145
165
  * - `model().deep.property` => the `model()` call
166
+ * - `model()!.deep.property` => the `model()` call (a type wrapper keeps the value)
146
167
  * - `users[0].name` => the `users` name
147
168
  *
148
169
  * Only reads are walked through. A chain rooted at anything else — `items().filter(f)`,
@@ -151,8 +172,12 @@ function isObjectAssign(callee) {
151
172
  */
152
173
  function baseOf(node) {
153
174
  let current = node;
154
- while (current?.type === "MemberExpression") {
155
- current = current.object;
175
+ while (
176
+ current?.type === "MemberExpression" ||
177
+ TYPE_WRAPPERS.has(current?.type)
178
+ ) {
179
+ current =
180
+ current.type === "MemberExpression" ? current.object : current.expression;
156
181
  }
157
182
  return current;
158
183
  }
@@ -180,6 +205,33 @@ function signalFactoryKind(node) {
180
205
  return callee?.type === "Identifier" ? factoryKind(callee.name) : undefined;
181
206
  }
182
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
+
183
235
  function signalRootCallKind(node, scopeContext) {
184
236
  if (node.arguments.length !== 0) {
185
237
  return undefined;
@@ -212,14 +264,18 @@ function signalRootCallKind(node, scopeContext) {
212
264
  }
213
265
 
214
266
  /**
215
- * Kind of signal whose value an expression evaluates to, `undefined` when it is not one.
216
- * The expression may be the signal read itself (`this.model()`), a member of its value
217
- * (`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.
218
271
  */
219
272
  function signalValueKind(node, scopeContext, seen = new Set()) {
220
273
  const base = baseOf(node);
221
274
  if (base?.type === "CallExpression") {
222
- return signalRootCallKind(base, scopeContext);
275
+ return valueOf(signalRootCallKind(base, scopeContext));
276
+ }
277
+ if (base?.type === "ThisExpression") {
278
+ return aliasReadOf(node, scopeContext);
223
279
  }
224
280
  return base?.type === "Identifier"
225
281
  ? boundNameSignalKind(base, scopeContext, seen)
@@ -241,7 +297,7 @@ function boundNameSignalKind(identifier, scopeContext, seen) {
241
297
  scopeContext.sourceCode.getScope(identifier),
242
298
  identifier.name,
243
299
  );
244
- if (!variable || variable.defs.length !== 1 || seen.has(variable)) {
300
+ if (variable?.defs.length !== 1 || seen.has(variable)) {
245
301
  return undefined;
246
302
  }
247
303
  seen.add(variable);
@@ -293,22 +349,36 @@ function signalRootTemplateCallKind(node, templateContext) {
293
349
  return undefined;
294
350
  }
295
351
  return isComponentReceiver(callee.receiver)
296
- ? templateContext.memberKind(callee.name ?? "")
352
+ ? valueOf(templateContext.memberKind(callee.name ?? ""))
297
353
  : undefined;
298
354
  }
299
355
 
356
+ // The expression itself, a type wrapper stripped away: `form()!` is the `form()` call.
357
+ function unwrapTemplate(node) {
358
+ let current = node;
359
+ while (TEMPLATE_WRAPPERS.has(current?.type)) {
360
+ current = current.expression;
361
+ }
362
+ return current;
363
+ }
364
+
300
365
  /**
301
366
  * Expression a template name is bound to, `undefined` when the name is a component
302
367
  * member. Mutating through such a name mutates whatever the expression yields:
303
- * `@for (user of model().users)` hands out the elements of the signal's array.
368
+ * `@for (user of model().users)` hands out the elements of the signal's array, and
369
+ * `@if (model(); as value)` the value of the signal itself.
304
370
  *
305
- * The item of a `@for` is only bound inside its own block, which the ancestor walk
306
- * enforces exactly; a `@let` is looked up by name, its declaration always preceding its
307
- * uses.
371
+ * The item of a `@for` and the alias of an `@if` are only bound inside their own block,
372
+ * which the ancestor walk enforces exactly, the nearest one shadowing the others; a `@let`
373
+ * is looked up by name, its declaration always preceding its uses.
308
374
  */
309
375
  function boundTemplateExpression(read, templateContext) {
310
376
  for (let current = read; current; current = current.parent) {
311
- if (current.type === "ForLoopBlock" && current.item?.name === read.name) {
377
+ if (
378
+ (current.type === "ForLoopBlock" && current.item?.name === read.name) ||
379
+ (current.type === "IfBlockBranch" &&
380
+ current.expressionAlias?.name === read.name)
381
+ ) {
312
382
  return current.expression?.ast ?? current.expression;
313
383
  }
314
384
  }
@@ -317,23 +387,34 @@ function boundTemplateExpression(read, templateContext) {
317
387
  }
318
388
 
319
389
  /**
320
- * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, or
321
- * 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.
322
396
  */
323
- function signalTemplateValueKind(node, templateContext, seen = new Set()) {
324
- if (node?.type === "Call" || node?.type === "SafeCall") {
325
- return signalRootTemplateCallKind(node, templateContext);
397
+ function signalTemplateValueKind(
398
+ node,
399
+ templateContext,
400
+ seen = new Set(),
401
+ assigned = false,
402
+ ) {
403
+ const value = unwrapTemplate(node);
404
+ if (value?.type === "Call" || value?.type === "SafeCall") {
405
+ return signalRootTemplateCallKind(value, templateContext);
326
406
  }
327
- if (!TEMPLATE_MEMBER_READS.has(node?.type)) {
407
+ if (!TEMPLATE_MEMBER_READS.has(value?.type)) {
328
408
  return undefined;
329
409
  }
330
410
 
331
- // Property and index reads are walked through; anything else roots a value of its own.
332
- let base = node;
333
- while (TEMPLATE_MEMBER_READS.has(base.receiver?.type)) {
334
- base = base.receiver;
411
+ // Property and index reads are walked through, as are the type wrappers; anything else
412
+ // roots a value of its own.
413
+ let base = value;
414
+ while (TEMPLATE_MEMBER_READS.has(unwrapTemplate(base.receiver)?.type)) {
415
+ base = unwrapTemplate(base.receiver);
335
416
  }
336
- const receiver = base.receiver;
417
+ const receiver = unwrapTemplate(base.receiver);
337
418
 
338
419
  if (receiver?.type === "Call" || receiver?.type === "SafeCall") {
339
420
  return signalRootTemplateCallKind(receiver, templateContext);
@@ -342,11 +423,15 @@ function signalTemplateValueKind(node, templateContext, seen = new Set()) {
342
423
  return undefined;
343
424
  }
344
425
  seen.add(base.name);
345
- return signalTemplateValueKind(
346
- boundTemplateExpression(base, templateContext),
347
- templateContext,
348
- seen,
349
- );
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);
350
435
  }
351
436
 
352
437
  // Method a template call invokes, `undefined` when the name is not statically known.
@@ -376,6 +461,8 @@ export default {
376
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.",
377
462
  readOnlyMutation:
378
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}}.",
379
466
  },
380
467
  },
381
468
 
@@ -385,18 +472,41 @@ export default {
385
472
  const declaringPath =
386
473
  resolveComponentPath(context.filename) ?? context.filename;
387
474
  const memberKinds = collectSignalKinds(declaringPath);
475
+ const aliases = collectSignalAliases(declaringPath);
388
476
 
389
477
  // `memberKinds` is undefined when the declaring file could not be read: its signals
390
478
  // are unknown, so fall back to treating every argument-less accessor as a writable
391
- // 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.
392
481
  const memberKind = (name) =>
393
482
  memberKinds ? memberKinds.get(name) : WRITABLE;
483
+ const alias = (name) => aliases?.get(name);
394
484
 
395
- const reportMutation = (node, kind, method) => {
485
+ const reportMutation = (node, value, method) => {
486
+ const kind = value?.kind;
396
487
  if (!kind || TOLERATED_KINDS.has(kind)) {
397
488
  return;
398
489
  }
399
- 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) {
400
510
  const [name, advice] = READ_ONLY_ADVICE[kind];
401
511
  context.report({
402
512
  node,
@@ -410,9 +520,9 @@ export default {
410
520
  }
411
521
  };
412
522
 
413
- const scopeContext = { memberKind, sourceCode: context.sourceCode };
523
+ const scopeContext = { memberKind, alias, sourceCode: context.sourceCode };
414
524
  // `@let` bindings, always declared before they are used.
415
- const templateContext = { memberKind, letBindings: new Map() };
525
+ const templateContext = { memberKind, alias, letBindings: new Map() };
416
526
 
417
527
  const checkTemplateInPlaceCall = (node) => {
418
528
  const method = templateMethodName(node.receiver);
@@ -434,6 +544,16 @@ export default {
434
544
  }
435
545
  },
436
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
+
437
557
  UnaryExpression(node) {
438
558
  // `delete model().users[0]` drops an entry of the value, notifying nothing.
439
559
  if (
@@ -482,7 +602,7 @@ export default {
482
602
  if (TEMPLATE_ASSIGNMENTS.has(node.operation)) {
483
603
  reportMutation(
484
604
  node,
485
- signalTemplateValueKind(node.left, templateContext),
605
+ signalTemplateValueKind(node.left, templateContext, new Set(), true),
486
606
  );
487
607
  }
488
608
  },
@@ -492,14 +612,15 @@ export default {
492
612
 
493
613
  BoundEvent(node) {
494
614
  // `[(x)]="model().property"` makes Angular assign into the value of the signal.
495
- // Reporting on the BoundEvent handler reports the binding exactly once.
496
- if (!node.name?.endsWith("Change")) {
615
+ // Reporting on the BoundEvent handler reports the binding exactly once. An
616
+ // explicit `(xChange)="…"` handler is a statement, checked as any other.
617
+ if (!isTwoWayBinding(node)) {
497
618
  return;
498
619
  }
499
620
  const handler = handlerExpressionOf(node);
500
621
  reportMutation(
501
622
  handler,
502
- signalTemplateValueKind(handler, templateContext),
623
+ signalTemplateValueKind(handler, templateContext, new Set(), true),
503
624
  );
504
625
  },
505
626
  };