@dsivd/prestations-ng 19.0.6-beta.2 → 19.0.6

package/CHANGELOG.md

@@ -6,6 +6,30 @@
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- ESLint plugin: **shareable configs**, documented in [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)
+    - add `configs.tsRecommended` and `configs.templateRecommended` to the `extends` of your
+      `**/*.ts` and `**/*.html` blocks — see [UPGRADING_V19.md](UPGRADING_V19.md). Nothing
+      else is needed: no `plugins` declaration, no rule list.
+    - 🚨 **Prerequisite**: `lintFilePatterns` in your `angular.json` must include
+      `src/**/*.html`, otherwise the template rules never run
+    - 🚨 **A rule added to these configs makes your lint fail on `npm update`.** This is
+      intentional. Every addition will be listed here, and a rule can be turned off from your
+      own `rules` block.
+- ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation)
+    - reports an assignment into a member of a signal's value
+      (`model().property = value`), which mutates the object without notifying the signal.
+      Covers TypeScript files and templates, including the mutation hidden in a two-way
+      binding (`[(ngModel)]="model().property"`)
+- ESLint rule [`no-uninvoked-signal-in-template`](ESLINT_PLUGIN.md#no-uninvoked-signal-in-template)
+    - reports a signal referenced in a template without being called (`{{ mySignal }}`,
+      `!mySignal`, `mySignal + 'x'`), which the Angular compiler only partially catches.
+      Autofixable. No configuration: inherited signals are resolved by walking the `extends`
+      chain of the component
+
 ## [19.0.2]
 
 ### Fixed

package/CONTRIBUTING.md

@@ -122,6 +122,30 @@ You can auto-format the code on save with IntelliJ. More informations
 
 Please make sure you have followed the **Before committing** section so you will see formating/linting errors before you commit.
 
+### Adding a rule to the ESLint plugin
+
+The library ships its own ESLint plugin (see [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)). Its rules
+reach every consuming project through shareable configs, so **adding a rule breaks the lint of
+those projects on their next `npm update`**. That is the intent, but it makes the checklist
+below mandatory:
+
+1. Write the rule in `projects/prestations-ng/src/eslint/rules/<rule-name>.mjs`
+2. Register it in `rules/index.mjs`, keyed by its public kebab-case name
+3. Enable it in `configs/ts-recommended.mjs`, `configs/template-recommended.mjs`, or both
+   depending on what it inspects
+4. Test it in `rules/__tests__/<rule-name>.test.mjs` — use the `@angular-eslint/template-parser`
+   for a template rule
+5. Run `npm run test:eslint`, then `npm run lint:js` on the whole repository: a rule that
+   reports on the library's own code is a rule that will report on every project
+6. Document it in `ESLINT_PLUGIN.md`: what it catches, ✗/✓ examples, whether it autofixes, and
+   its known limitations
+7. Announce it in `CHANGELOG.md` **as a breaking change for consumers**, with the line needed
+   to turn it off
+
+Step 5 matters more than it looks: the config tests in `configs/__tests__/configs.test.mjs`
+guard against a config that references a rule which does not exist — a mistake that would
+break every consuming project at once.
+
 ## Publishing a new version of the package
 
 Please use the dedicated Jenkins build:

package/ESLINT_PLUGIN.md

@@ -0,0 +1,177 @@
+# ESLint plugin
+
+`@dsivd/prestations-ng` ships an ESLint plugin with rules that catch signal misuses the
+Angular compiler lets through. It is published as a subpath of the library, so the rules
+follow the version of the library.
+
+## Setup
+
+The plugin exposes **shareable configs**, in the same spirit as `angular-eslint`. Add them to
+the `extends` of the `**/*.ts` and `**/*.html` blocks of your `eslint.config.mjs`:
+
+```ts
+import angular from 'angular-eslint';
+import tseslint from 'typescript-eslint';
+import prestationsNg from '@dsivd/prestations-ng/eslint';
+
+export default tseslint.config(
+    {
+        files: ['**/*.ts'],
+        extends: [
+            ...angular.configs.tsRecommended,
+            ...prestationsNg.configs.tsRecommended,
+        ],
+        processor: angular.processInlineTemplates,
+    },
+    {
+        files: ['**/*.html'],
+        extends: [
+            ...angular.configs.templateRecommended,
+            ...prestationsNg.configs.templateRecommended,
+        ],
+    },
+);
+```
+
+That is all. You do **not** declare `plugins`, and you do **not** list the rules — both come
+from the config. Inline templates written in a `@Component` are covered too, through
+`angular.processInlineTemplates`.
+
+> 🚨 **Prerequisite**: `lintFilePatterns` in your `angular.json` must include
+> `src/**/*.html`. Without it `ng lint` never opens your templates, and the template rules
+> silently never run.
+
+| Config                        | Target      | Rules                                                          |
+| ----------------------------- | ----------- | -------------------------------------------------------------- |
+| `configs.tsRecommended`       | `**/*.ts`   | `no-direct-signal-mutation`                                    |
+| `configs.templateRecommended` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template` |
+
+`no-direct-signal-mutation` appears in both: the rule carries one visitor for TypeScript
+and one for the Angular template AST, and each fires on its own kind of file.
+
+## What happens when you update the library
+
+A new rule added to the library lands in the config, so `npm update @dsivd/prestations-ng`
+**will make your lint fail** on the code that violates it. This is intentional: it is how a
+new practice gets rolled out across every project using the library. Every added rule is
+listed in the [CHANGELOG](CHANGELOG.md).
+
+If you cannot fix the violations right away, turn the rule off — or lower its severity — in
+your own `rules` block. It is applied after the shared config, so it wins:
+
+```ts
+{
+    files: ['**/*.html'],
+    extends: [
+        ...angular.configs.templateRecommended,
+        ...prestationsNg.configs.templateRecommended,
+    ],
+    rules: {
+        // decided by this project, survives library updates
+        '@dsivd/prestations-ng/no-direct-signal-mutation': ['off'],
+    },
+},
+```
+
+## Rules
+
+### `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.
+
+Applies to **TypeScript files and templates**, including the case where the mutation hides
+in a two-way binding.
+
+```ts
+// ✗ mutates the object inside the signal, no notification
+this.model().property = value;
+
+// ✓
+this.model.update((current) => ({ ...current, property: value }));
+```
+
+```html
+<!-- ✗ -->
+<button (click)="model().property = value">…</button>
+<input [(ngModel)]="model().property" />
+
+<!-- ✓ -->
+<button (click)="model.update((v) => ({ ...v, property: value }))">…</button>
+```
+
+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:
+
+| 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 |
+
+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.
+
+### `no-uninvoked-signal-in-template`
+
+Reports a signal referenced in a template without being called. A bare reference evaluates
+to the function itself: always truthy, and serialized as source code when interpolated.
+
+Applies to **templates only** (external and inline).
+
+```html
+<!-- ✗ -->
+<p>{{ userName }}</p>
+<p>{{ userName + '!' }}</p>
+<div [hidden]="!isLoading">…</div>
+
+<!-- ✓ -->
+<p>{{ userName() }}</p>
+<p>{{ userName() + '!' }}</p>
+<div [hidden]="!isLoading()">…</div>
+```
+
+A control flow condition counts too: `@if (isLoading)` must be `@if (isLoading())`.
+
+The Angular compiler only covers part of these cases (`NG8109` / `NG8117`): it lets the
+negation and the concatenation through.
+
+The rule is **autofixable** — `npm run lint` with `--fix` adds the missing parentheses.
+
+Signal names are resolved automatically, with no configuration: the rule reads the twin
+`.ts` of the template and walks its whole inheritance chain, resolving each `extends` the
+way TypeScript would — relative paths, `node_modules`, `paths` mappings. Signals inherited
+from `FoehnInputComponent`, `AbstractPageComponent` or from one of your own base classes are
+found without declaring anything.
+
+**Not reported:**
+
+| Expression                                                   | Why                                                                                       |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `mySignal()`, `mySignal?.()`                                 | already called                                                                            |
+| `mySignal.set(…)`, `.update(…)`, `.asReadonly()`             | targets the signal, not its value                                                         |
+| `[(value)]="mySignal"`                                       | a writable signal is two-way bound **without** parentheses, Angular calls `.set()` itself |
+| `#ref`, `@for` items, `@if … as`, `@let`, `let-x`, `$index`… | template-local names shadow the class members                                             |
+
+## Also worth enabling
+
+`@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
+the real type checker — far more reliable than what a template rule can do. It cannot run on
+templates: it requires type information, which a `.html` file has no program for. The two
+are complementary, not redundant.
+
+```ts
+'@angular-eslint/no-uncalled-signals': 'error',
+```
+
+It only reports signals used in logic positions (`if`, `!x`, `&&`, `===`, `.length`…), not a
+bare `const x = mySignal`.

package/README.md

@@ -20,6 +20,9 @@ The documentation is available online at [https://dsi-vd.github.io/prestations-n
 - If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `^8`.
 - If you're using **Angular 5**, use `prestations-ng` at version `^7`.
 
+The library also ships an ESLint plugin whose rules apply to your project: see
+[the plugin guide](ESLINT_PLUGIN.md).
+
 Migration guides are available to provide an upgrade path from one major version to another.
 
 - If you need to upgrade to version `19+`, please refer to [the V19 upgrade guide](UPGRADING_V19.md).

package/UPGRADING_V19.md

@@ -381,7 +381,7 @@ ng update ngx-matomo-client@9
 
 - In your `.eslintrc.json`, remove `"/src/main.ts",` from `ignorePatterns`.
 - In `main.ts`, replace `platformBrowserDynamic` by `platformBrowser`.
-- When using `<foehn-list-summary` component, replace `list` by `model`.
+- When using `<foehn-list-summary` component, replace `[list]` by `[(model)]` (with double binding to handle item being removed).
 
 ### Now fix your project before continuing
 
@@ -1092,7 +1092,7 @@ import rxjs from '@smarttools/eslint-plugin-rxjs';
 import simpleImportSort from 'eslint-plugin-simple-import-sort';
 import prettier from 'eslint-config-prettier';
 import importX from 'eslint-plugin-import-x';
-import prestationsNgEslint from '@dsivd/prestations-ng/eslint';
+import prestationsNg from '@dsivd/prestations-ng/eslint';
 
 export default tseslint.config(
     {
@@ -1112,6 +1112,7 @@ export default tseslint.config(
             //   prefer-function-type…
             ...angular.configs.tsRecommended, // covers: prefer-inject, no-empty-lifecycle-method,
             //   use-lifecycle-interface…
+            ...prestationsNg.configs.tsRecommended, // covers: no-direct-signal-mutation
         ],
         languageOptions: {
             parserOptions: {
@@ -1123,7 +1124,6 @@ export default tseslint.config(
             rxjs,
             'simple-import-sort': simpleImportSort,
             'import-x': importX,
-            '@dsivd/prestations-ng': prestationsNgEslint,
         },
         processor: angular.processInlineTemplates,
         rules: {
@@ -1233,9 +1233,6 @@ export default tseslint.config(
             // ── simple-import-sort ───────────────────────────────────────────
             'simple-import-sort/imports': 'error',
             'simple-import-sort/exports': 'error',
-
-            // ── prestations-ng ──────────────────────────────────────────────
-            '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
         },
     },
 
@@ -1245,6 +1242,7 @@ export default tseslint.config(
         extends: [
             ...angular.configs.templateRecommended,
             ...angular.configs.templateAccessibility,
+            ...prestationsNg.configs.templateRecommended, // covers no-direct-signal-mutation, no-uninvoked-signal-in-template
         ],
         rules: {
             '@angular-eslint/template/no-negated-async': 'off',
@@ -1257,6 +1255,26 @@ export default tseslint.config(
 );
 ```
 
+#### prestations-ng ESLint rules
+
+The library ships **shareable custom configs** that are auto-updatable with the library version. Two
+rules are enabled today — `no-direct-signal-mutation` and `no-uninvoked-signal-in-template` — and both
+are documented in [the plugin guide](ESLINT_PLUGIN.md).
+
+One consequence to keep in mind:
+
+- A rule added in a later version of the library lands in the config, so `npm update` **will
+  make your lint fail** on the offending code. That is the point — it is how a practice is
+  rolled out to every project. Each addition is listed in the [CHANGELOG](CHANGELOG.md), and
+  a rule you cannot fix right away can be turned off in your own `rules` block, which is
+  applied after the shared config:
+
+    ```ts
+    rules: {
+        '@dsivd/prestations-ng/no-direct-signal-mutation': ['off'],
+    },
+    ```
+
 #### Delete `typings.d.ts`
 
 In `front/src/`, remove the file `typings.d.ts` if it is still there.

package/eslint/configs/template-base.mjs

@@ -0,0 +1,10 @@
+// Registers the plugin without enabling any rule. Meant to be used through
+// `templateRecommended`, inside the `extends` of a block that already targets
+// `**/*.html` and sets the Angular template parser.
+const templateBase = (plugin) => ({
+    name: 'prestations-ng/template-base',
+    plugins: {
+        '@dsivd/prestations-ng': plugin,
+    },
+});
+export default templateBase;

package/eslint/configs/template-recommended.mjs

@@ -0,0 +1,15 @@
+import templateBase from './template-base.mjs';
+
+const templateRecommended = (plugin) => [
+    templateBase(plugin),
+    {
+        name: 'prestations-ng/template-recommended',
+        rules: {
+            // Also in `tsRecommended`: the rule carries both an ESTree and an Angular
+            // template visitor, and each fires on its own kind of file.
+            '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
+            '@dsivd/prestations-ng/no-uninvoked-signal-in-template': 'error',
+        },
+    },
+];
+export default templateRecommended;

package/eslint/configs/ts-base.mjs

@@ -0,0 +1,10 @@
+// Registers the plugin without enabling any rule. Meant to be used through
+// `tsRecommended`, inside the `extends` of a block that already targets `**/*.ts`
+// and sets the TypeScript parser.
+const tsBase = (plugin) => ({
+    name: 'prestations-ng/ts-base',
+    plugins: {
+        '@dsivd/prestations-ng': plugin,
+    },
+});
+export default tsBase;

package/eslint/configs/ts-recommended.mjs

@@ -0,0 +1,12 @@
+import tsBase from './ts-base.mjs';
+
+const tsRecommended = (plugin) => [
+    tsBase(plugin),
+    {
+        name: 'prestations-ng/ts-recommended',
+        rules: {
+            '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
+        },
+    },
+];
+export default tsRecommended;

package/eslint/index.mjs

@@ -1,7 +1,16 @@
-import { noDirectSignalMutation } from './rules/index.mjs';
+import templateRecommended from './configs/template-recommended.mjs';
+import tsRecommended from './configs/ts-recommended.mjs';
+import rules from './rules/index.mjs';
 
-export default {
-  rules: {
-    'no-direct-signal-mutation': noDirectSignalMutation,
-  },
+const plugin = {
+  meta: { name: '@dsivd/prestations-ng' },
+  rules,
 };
+
+const configs = {
+  tsRecommended: tsRecommended(plugin),
+  templateRecommended: templateRecommended(plugin),
+};
+
+export { configs, plugin, rules };
+export default { configs, plugin, rules };

package/eslint/rules/index.mjs

@@ -1 +1,7 @@
-export { default as noDirectSignalMutation } from './no-direct-signal-mutation.mjs';
+import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
+import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
+
+export default {
+  'no-direct-signal-mutation': noDirectSignalMutation,
+  'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
+};