@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,89 @@
1
+ import { astOf, readsForm } from "../form-reads.mjs";
2
+
3
+ /**
4
+ * ESLint rule: a `foehn-*` component given a field of the form of the page with a
5
+ * one-way `[model]` must also listen to `(modelChange)`. Without it, what the user enters never
6
+ * reaches the form: the component changes its own model only. With the form held by a signal,
7
+ * bind `[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`.
8
+ *
9
+ * Only the models read from the form are checked (`form()`, `form.x`, and the names bound to
10
+ * it by `@if (form(); as form)`, `@let form = this.form()` or `@for (child of form.children)`):
11
+ * a one-way `[model]` is legitimate elsewhere (a table displaying a list, a menu...).
12
+ * `[(model)]` declares both bindings and is never reported.
13
+ *
14
+ * Not reported either, as the input of the user can't be lost: a component always disabled
15
+ * (`disabled="true"`, `[disabled]="true"`), the components which never write their model, and a
16
+ * component listening to `(userInput)`, whose handler writes the form.
17
+ */
18
+
19
+ /** Components which never write their model: they only display it. */
20
+ const READ_ONLY_COMPONENTS = new Set(["foehn-input-hidden", "foehn-table"]);
21
+
22
+ /**
23
+ * Whether the component is always disabled: a disabled component doesn't write its model, unless
24
+ * it is given `updateModelWhenDisabled`. A bare `disabled` gives `''`, which doesn't disable it.
25
+ */
26
+ function isAlwaysDisabled(node) {
27
+ const named = (name) => (binding) => binding.name === name;
28
+ const bindings = [...(node.attributes ?? []), ...(node.inputs ?? [])];
29
+ if (bindings.some(named("updateModelWhenDisabled"))) {
30
+ return false;
31
+ }
32
+ const disabled = astOf(node.inputs?.find(named("disabled"))?.value);
33
+ return (
34
+ node.attributes?.find(named("disabled"))?.value === "true" ||
35
+ (disabled?.type === "LiteralPrimitive" && disabled.value === true)
36
+ );
37
+ }
38
+
39
+ export default {
40
+ meta: {
41
+ type: "problem",
42
+ docs: {
43
+ description:
44
+ "Require (modelChange) next to a one-way [model] reading the form of the page",
45
+ category: "Possible Errors",
46
+ recommended: true,
47
+ },
48
+ schema: [],
49
+ messages: {
50
+ missing:
51
+ "'{{element}}' gets a field of the form with a one-way [model] without (modelChange): what the user enters never reaches the form. Add (modelChange), e.g. (modelChange)=\"patchForm([...], $event)\".",
52
+ },
53
+ },
54
+
55
+ create(context) {
56
+ const offset = (location) =>
57
+ typeof location === "number" ? location : location.offset;
58
+
59
+ return {
60
+ Element(node) {
61
+ if (!node.name?.startsWith("foehn-")) {
62
+ return;
63
+ }
64
+ const model = node.inputs?.find((input) => input.name === "model");
65
+ if (
66
+ !model ||
67
+ READ_ONLY_COMPONENTS.has(node.name) ||
68
+ node.outputs?.some(
69
+ (output) =>
70
+ output.name === "modelChange" || output.name === "userInput",
71
+ ) ||
72
+ isAlwaysDisabled(node) ||
73
+ !readsForm(astOf(model.value), node)
74
+ ) {
75
+ return;
76
+ }
77
+ const span = model.sourceSpan;
78
+ context.report({
79
+ messageId: "missing",
80
+ data: { element: node.name },
81
+ loc: {
82
+ start: context.sourceCode.getLocFromIndex(offset(span.start)),
83
+ end: context.sourceCode.getLocFromIndex(offset(span.end)),
84
+ },
85
+ });
86
+ },
87
+ };
88
+ },
89
+ };
@@ -0,0 +1,162 @@
1
+ import { isComponentReceiver } from "../template-ast.mjs";
2
+ import { astOf } from "../form-reads.mjs";
3
+
4
+ /**
5
+ * ESLint rule: a `@for` whose rows name their fields with the index of the row
6
+ * (`[name]="'children[' + $index + '].firstName'"`, `name="child{{ i }}"`), or the errors of the
7
+ * row (`[errorPrefix]` of `foehn-error-pill`), must track its rows by `$index`.
8
+ *
9
+ * The names of the fields follow the paths of the errors of GESDEM (`children[1].firstName`).
10
+ * Tracked by anything else (an identifier, the item), a row whose item moves (an earlier item
11
+ * removed or inserted, the list sorted) is kept with its fields renamed: `foehn-form` keeps them
12
+ * registered under their former names, so the row taking one of these names shares their
13
+ * `FormControl`, and the errors, read by name when they are emitted, stay those of the former
14
+ * name. Tracked by `$index`, a row never changes its names: only its item changes.
15
+ *
16
+ * The index is `$index` or an alias of it (`let i = $index`), of the innermost `@for` declaring
17
+ * the name: a name built with the index of an enclosing `@for` reports that one.
18
+ */
19
+
20
+ // The inputs naming a field, or the errors of a row
21
+ const NAME_INPUTS = new Set(["name", "errorPrefix"]);
22
+
23
+ // The members of an expression node that aren't expressions
24
+ const NOT_EXPRESSIONS = new Set([
25
+ "span",
26
+ "sourceSpan",
27
+ "nameSpan",
28
+ "keySpan",
29
+ "loc",
30
+ "parent",
31
+ ]);
32
+
33
+ /**
34
+ * The names read on the component by an expression (`i`, `$index`), nested reads included.
35
+ */
36
+ function namesReadBy(expression, names = []) {
37
+ if (Array.isArray(expression)) {
38
+ expression.forEach((item) => namesReadBy(item, names));
39
+ return names;
40
+ }
41
+ if (!expression || typeof expression !== "object") {
42
+ return names;
43
+ }
44
+ if (
45
+ expression.type === "PropertyRead" &&
46
+ isComponentReceiver(expression.receiver)
47
+ ) {
48
+ names.push(expression.name);
49
+ }
50
+ for (const [key, value] of Object.entries(expression)) {
51
+ if (!NOT_EXPRESSIONS.has(key) && value && typeof value === "object") {
52
+ namesReadBy(value, names);
53
+ }
54
+ }
55
+ return names;
56
+ }
57
+
58
+ /**
59
+ * The `@for` whose `$index` a name is: the innermost enclosing `@for` declaring the name, when
60
+ * it declares it as its `$index` (itself or an alias).
61
+ */
62
+ function forBlockIndexed(name, node) {
63
+ for (let current = node; current; current = current.parent) {
64
+ if (current.type !== "ForLoopBlock") {
65
+ continue;
66
+ }
67
+ const variable = current.contextVariables?.find(
68
+ (contextVariable) => contextVariable.name === name,
69
+ );
70
+ if (variable) {
71
+ return variable.value === "$index" ? current : undefined;
72
+ }
73
+ }
74
+ return undefined;
75
+ }
76
+
77
+ /**
78
+ * Whether a `@for` tracks its rows by its `$index`, or an alias of it.
79
+ */
80
+ function tracksIndex(forBlock) {
81
+ const track = astOf(forBlock.trackBy);
82
+ return (
83
+ track?.type === "PropertyRead" &&
84
+ isComponentReceiver(track.receiver) &&
85
+ !!forBlock.contextVariables?.some(
86
+ (contextVariable) =>
87
+ contextVariable.name === track.name &&
88
+ contextVariable.value === "$index",
89
+ )
90
+ );
91
+ }
92
+
93
+ export default {
94
+ meta: {
95
+ type: "problem",
96
+ docs: {
97
+ description:
98
+ "Require tracking by $index the rows of a @for that name their fields, or their errors, with the index of the row",
99
+ category: "Possible Errors",
100
+ recommended: true,
101
+ },
102
+ hasSuggestions: true,
103
+ schema: [],
104
+ messages: {
105
+ indexTrack:
106
+ "The rows of this list name their fields with the index ({{binding}}) but are tracked by '{{track}}': a row whose item moves keeps its fields registered under their former names, and mixes up their values and errors with the row taking these names. Track the rows by $index.",
107
+ trackByIndex: "Track the rows by $index",
108
+ },
109
+ },
110
+
111
+ create(context) {
112
+ // The @for naming the fields of their rows with their index, and the first such binding
113
+ const indexedBlocks = new Map();
114
+ const textOf = (expression) =>
115
+ context.sourceCode.text
116
+ .slice(expression.sourceSpan.start, expression.sourceSpan.end)
117
+ .replace(/\s+/g, " ")
118
+ .trim();
119
+
120
+ return {
121
+ Element(node) {
122
+ for (const input of node.inputs ?? []) {
123
+ if (!NAME_INPUTS.has(input.name)) {
124
+ continue;
125
+ }
126
+ for (const name of namesReadBy(astOf(input.value))) {
127
+ const forBlock = forBlockIndexed(name, node);
128
+ if (forBlock && !indexedBlocks.has(forBlock)) {
129
+ indexedBlocks.set(
130
+ forBlock,
131
+ `${input.name}="${input.value.source ?? textOf(astOf(input.value))}"`,
132
+ );
133
+ }
134
+ }
135
+ }
136
+ },
137
+ "Program:exit"() {
138
+ for (const [forBlock, binding] of indexedBlocks) {
139
+ if (tracksIndex(forBlock)) {
140
+ continue;
141
+ }
142
+ const track = astOf(forBlock.trackBy);
143
+ const { start, end } = track.sourceSpan;
144
+ context.report({
145
+ messageId: "indexTrack",
146
+ data: { binding, track: textOf(track) },
147
+ loc: {
148
+ start: context.sourceCode.getLocFromIndex(start),
149
+ end: context.sourceCode.getLocFromIndex(end),
150
+ },
151
+ suggest: [
152
+ {
153
+ messageId: "trackByIndex",
154
+ fix: (fixer) => fixer.replaceTextRange([start, end], "$index"),
155
+ },
156
+ ],
157
+ });
158
+ }
159
+ },
160
+ };
161
+ },
162
+ };
@@ -161,29 +161,95 @@ const classDeclarationsOf = (sourceFile, className) =>
161
161
  const isBarrelMiss = (className, classDeclarations) =>
162
162
  Boolean(className) && classDeclarations.length === 0;
163
163
 
164
- const collectFromReExports = (sourceFile, path, className, kinds, visited) => {
164
+ const collectFromReExports = (sourceFile, path, className, members, visited) => {
165
165
  for (const specifier of reExportedModulesOf(sourceFile)) {
166
166
  const target = resolveModule(specifier, path);
167
167
  if (target) {
168
- collect(target, className, kinds, visited);
168
+ collect(target, className, members, visited);
169
169
  }
170
170
  }
171
171
  };
172
172
 
173
- const addMemberKindIfEligible = (member, kinds) => {
173
+ // TypeScript wrappers that leave the value as is: `this.form()!`, `this.form() as Form`...
174
+ const isValueWrapper = (node) =>
175
+ ts.isParenthesizedExpression(node) ||
176
+ ts.isNonNullExpression(node) ||
177
+ ts.isAsExpression(node) ||
178
+ ts.isSatisfiesExpression(node) ||
179
+ ts.isTypeAssertionExpression(node);
180
+
181
+ /**
182
+ * What the expression returned by a getter is rooted at, the property and index reads and
183
+ * the type wrappers stripped away: the read of a member of the class without arguments
184
+ * (`{ call: "form" }` for `this.form()!.step`), or a member read as is (`{ member: "step" }`
185
+ * for `this.step.motif`, another getter maybe). `undefined` for anything else: a
186
+ * computation, a copy or a call with arguments returns a value of its own.
187
+ */
188
+ const returnedRootOf = (expression) => {
189
+ let current = expression;
190
+ for (;;) {
191
+ if (isValueWrapper(current)) {
192
+ current = current.expression;
193
+ } else if (
194
+ ts.isPropertyAccessExpression(current) ||
195
+ ts.isElementAccessExpression(current)
196
+ ) {
197
+ if (current.expression.kind === ts.SyntaxKind.ThisKeyword) {
198
+ return ts.isPropertyAccessExpression(current) &&
199
+ ts.isIdentifier(current.name)
200
+ ? { member: current.name.text }
201
+ : undefined;
202
+ }
203
+ current = current.expression;
204
+ } else {
205
+ break;
206
+ }
207
+ }
208
+ const callee = ts.isCallExpression(current) ? current.expression : undefined;
209
+ return callee &&
210
+ current.arguments.length === 0 &&
211
+ ts.isPropertyAccessExpression(callee) &&
212
+ callee.expression.kind === ts.SyntaxKind.ThisKeyword &&
213
+ ts.isIdentifier(callee.name)
214
+ ? { call: callee.name.text }
215
+ : undefined;
216
+ };
217
+
218
+ // The expression a getter returns, when its body is a single `return` statement.
219
+ const returnedExpressionOf = (getter) => {
220
+ const statements = getter.body?.statements;
221
+ const statement = statements?.length === 1 ? statements[0] : undefined;
222
+ return statement && ts.isReturnStatement(statement)
223
+ ? statement.expression
224
+ : undefined;
225
+ };
226
+
227
+ const addMemberIfEligible = (member, { kinds, getters }) => {
174
228
  if (!member.name || !ts.isIdentifier(member.name)) {
175
229
  return;
176
230
  }
177
- const kind = kindOfMember(member);
231
+ const name = member.name.text;
178
232
  // A subclass overriding a member wins: it is collected first.
179
- if (kind && !kinds.has(member.name.text)) {
180
- kinds.set(member.name.text, kind);
233
+ if (kinds.has(name) || getters.has(name)) {
234
+ return;
235
+ }
236
+ const kind = kindOfMember(member);
237
+ if (kind) {
238
+ kinds.set(name, kind);
239
+ return;
240
+ }
241
+ const returned = ts.isGetAccessor(member)
242
+ ? returnedExpressionOf(member)
243
+ : undefined;
244
+ // Recorded even when it returns something else: it overrides the getter of a base class.
245
+ if (ts.isGetAccessor(member)) {
246
+ getters.set(name, returned ? returnedRootOf(returned) : undefined);
181
247
  }
182
248
  };
183
249
 
184
- const collectMemberKinds = (classDeclaration, kinds) => {
250
+ const collectMembers = (classDeclaration, members) => {
185
251
  for (const member of classDeclaration.members) {
186
- addMemberKindIfEligible(member, kinds);
252
+ addMemberIfEligible(member, members);
187
253
  }
188
254
  };
189
255
 
@@ -207,14 +273,14 @@ const baseTargetOf = (sourceFile, path, classDeclaration) => {
207
273
  return target ? { path: target, className: imported.exportedName } : undefined;
208
274
  };
209
275
 
210
- const collectBase = (sourceFile, path, classDeclaration, kinds, visited) => {
276
+ const collectBase = (sourceFile, path, classDeclaration, members, visited) => {
211
277
  const target = baseTargetOf(sourceFile, path, classDeclaration);
212
278
  if (target) {
213
- collect(target.path, target.className, kinds, visited);
279
+ collect(target.path, target.className, members, visited);
214
280
  }
215
281
  };
216
282
 
217
- const collect = (path, className, kinds, visited) => {
283
+ const collect = (path, className, members, visited) => {
218
284
  const key = `${path}::${className ?? "*"}`;
219
285
  if (visited.has(key)) {
220
286
  return;
@@ -230,27 +296,67 @@ const collect = (path, className, kinds, visited) => {
230
296
 
231
297
  // A barrel: the class is only re-exported from here.
232
298
  if (isBarrelMiss(className, classDeclarations)) {
233
- collectFromReExports(sourceFile, path, className, kinds, visited);
299
+ collectFromReExports(sourceFile, path, className, members, visited);
234
300
  return;
235
301
  }
236
302
 
237
303
  for (const classDeclaration of classDeclarations) {
238
- collectMemberKinds(classDeclaration, kinds);
239
- collectBase(sourceFile, path, classDeclaration, kinds, visited);
304
+ collectMembers(classDeclaration, members);
305
+ collectBase(sourceFile, path, classDeclaration, members, visited);
306
+ }
307
+ };
308
+
309
+ const collectAll = (componentPath) => {
310
+ if (!parseFile(componentPath)) {
311
+ return undefined;
312
+ }
313
+ const members = { kinds: new Map(), getters: new Map() };
314
+ collect(componentPath, undefined, members, new Set());
315
+ return members;
316
+ };
317
+
318
+ /**
319
+ * The getters returning the value of a signal of the class, or a part of it: `get step()
320
+ * { return this.form()!.step; }`, or another such getter read further (`this.step.motif`).
321
+ * Mapped to the signal and its kind. Mutating what they return mutates the value of the
322
+ * signal.
323
+ */
324
+ const resolveAliases = ({ kinds, getters }) => {
325
+ const aliases = new Map();
326
+ let added = true;
327
+ while (added) {
328
+ added = false;
329
+ for (const [name, root] of getters) {
330
+ if (aliases.has(name) || !root) {
331
+ continue;
332
+ }
333
+ const alias = root.call
334
+ ? kinds.has(root.call) && { signal: root.call, kind: kinds.get(root.call) }
335
+ : aliases.get(root.member);
336
+ if (alias) {
337
+ aliases.set(name, alias);
338
+ added = true;
339
+ }
340
+ }
240
341
  }
342
+ return aliases;
241
343
  };
242
344
 
243
345
  /**
244
346
  * Signal members of a component, mapped to their kind. `undefined` when the file
245
347
  * cannot be read: unknown signals must be distinguished from a component that has none.
246
348
  */
247
- export const collectSignalKinds = (componentPath) => {
248
- if (!parseFile(componentPath)) {
249
- return undefined;
250
- }
251
- const kinds = new Map();
252
- collect(componentPath, undefined, kinds, new Set());
253
- return kinds;
349
+ export const collectSignalKinds = (componentPath) =>
350
+ collectAll(componentPath)?.kinds;
351
+
352
+ /**
353
+ * Getters of a component aliasing the value of one of its signals, mapped to
354
+ * `{ signal, kind }`, walking up its inheritance chain. `undefined` when the file cannot be
355
+ * read.
356
+ */
357
+ export const collectSignalAliases = (componentPath) => {
358
+ const members = collectAll(componentPath);
359
+ return members && resolveAliases(members);
254
360
  };
255
361
 
256
362
  export const collectSignalNames = (componentPath) =>
@@ -1,8 +1,18 @@
1
1
  /**
2
- * Two subtleties of the Angular template AST that every template rule runs into.
3
- * Both are easy to get wrong, hence the shared names.
2
+ * Three subtleties of the Angular template AST that every template rule runs into.
3
+ * All are easy to get wrong, hence the shared names.
4
4
  */
5
5
 
6
+ /**
7
+ * Whether a `BoundEvent` is the one generated by a two-way binding `[(x)]="expr"`, whose
8
+ * handler is the target Angular writes into, not a statement.
9
+ *
10
+ * Its name alone can't tell: an explicit `(xChange)="refresh()"` has the same name. The
11
+ * key can: `x` for the two-way binding, `xChange` for the explicit handler.
12
+ */
13
+ export const isTwoWayBinding = (boundEvent) =>
14
+ boundEvent.name === `${boundEvent.keySpan?.details}Change`;
15
+
6
16
  /**
7
17
  * The expression carried by a `BoundEvent` handler.
8
18
  *