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

package/CHANGELOG.md

@@ -6,6 +6,37 @@
 
 ---
 
+## [19.0.7]
+
+### 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). They carry
+      the whole shared setup: the `eslint`, `typescript-eslint` and `angular-eslint`
+      baselines, the house conventions, and the rules below. Nothing else is needed: no
+      `plugins` declaration, no rule list.
+    - `configs.tsRules` and `configs.templateRules` enable only the rules written here, for a
+      project that supplies its own style
+    - 🚨 do **not** also spread `angular.configs.tsRecommended` or
+      `angular.configs.templateRecommended`: they are already included, and declaring the
+      same plugin twice makes ESLint fail outright
+    - 🚨 **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,31 @@ 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-rules.mjs`, `configs/template-rules.mjs`, or both depending on
+   what it inspects — the `*-recommended.mjs` presets pick those layers up. A change to a
+   shared convention rather than to a rule of ours goes into `configs/ts-recommended.mjs`.
+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,198 @@
+# ESLint plugin
+
+`@dsivd/prestations-ng` ships an ESLint plugin with rules that catch signal misuses the
+Angular compiler lets through, plus the lint setup shared by every project built on the
+library. It is published as a subpath of the library, so both 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: [...prestationsNg.configs.tsRecommended],
+        languageOptions: {
+            parserOptions: {
+                projectService: true,
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+        processor: angular.processInlineTemplates,
+    },
+    {
+        files: ['**/*.html'],
+        extends: [...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`.
+
+> 🚨 **Do not spread `angular.configs.tsRecommended` or `angular.configs.templateRecommended`
+> alongside these configs.** They already include them. Declaring the same plugin twice from
+> two different copies makes ESLint fail outright, before linting anything.
+
+> 🚨 **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.
+
+## The configs
+
+| Config                        | Target      | Contents                                                       |
+| ----------------------------- | ----------- | -------------------------------------------------------------- |
+| `configs.tsRecommended`       | `**/*.ts`   | the baselines, the house style, and `tsRules`                   |
+| `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules`             |
+| `configs.tsRules`             | `**/*.ts`   | `no-direct-signal-mutation`                                    |
+| `configs.templateRules`       | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template` |
+
+The `*Recommended` presets are what a project normally extends. On top of the rules written
+here they bring:
+
+- the baselines — `eslint.configs.recommended`, `typescript-eslint` recommended and
+  stylistic, `angular-eslint` recommended, and for templates its accessibility set;
+- the house style — naming and selector conventions, import ordering
+  (`simple-import-sort`, `import-x`), rxjs conventions, and the signal rules of
+  `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`).
+
+Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
+the rules of this library. They register the plugin and nothing else, so you keep control of
+the baselines — and stay responsible for keeping them aligned.
+
+`no-direct-signal-mutation` appears in both targets: 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: [...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                                             |
+
+## The TypeScript counterpart
+
+`@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.
+
+`configs.tsRecommended` already enables it. With `configs.tsRules` you enable it yourself:
+
+```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
 
@@ -1085,14 +1085,11 @@ rm .eslintrc.json
 
 ```ts
 // @ts-check
-import eslint from '@eslint/js';
+import prettier from 'eslint-config-prettier';
 import tseslint from 'typescript-eslint';
 import angular from 'angular-eslint';
-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(
     {
@@ -1102,154 +1099,20 @@ export default tseslint.config(
     // ─── TypeScript ────────────────────────────────────────────────────────────
     {
         files: ['**/*.ts'],
-        extends: [
-            eslint.configs.recommended,
-            ...tseslint.configs.recommended, // covers: no-explicit-any, ban-ts-comment,
-            //   no-unused-expressions, no-var, no-unused-vars…
-            ...tseslint.configs.stylistic, // covers: array-type, consistent-type-assertions,
-            //   dot-notation, no-inferrable-types (default options),
-            //   no-empty-function (error), prefer-for-of,
-            //   prefer-function-type…
-            ...angular.configs.tsRecommended, // covers: prefer-inject, no-empty-lifecycle-method,
-            //   use-lifecycle-interface…
-        ],
+        extends: [...prestationsNg.configs.tsRecommended],
         languageOptions: {
             parserOptions: {
                 projectService: true,
                 tsconfigRootDir: import.meta.dirname,
             },
         },
-        plugins: {
-            rxjs,
-            'simple-import-sort': simpleImportSort,
-            'import-x': importX,
-            '@dsivd/prestations-ng': prestationsNgEslint,
-        },
         processor: angular.processInlineTemplates,
-        rules: {
-            // ── @angular-eslint ──────────────────────────────────────────────
-            '@angular-eslint/component-selector': [
-                'error',
-                {
-                    type: 'element',
-                    prefix: 'app',
-                    style: 'kebab-case',
-                },
-            ],
-            '@angular-eslint/directive-selector': [
-                'error',
-                {
-                    type: 'attribute',
-                    prefix: 'app',
-                    style: 'camelCase',
-                },
-            ],
-            '@angular-eslint/no-uncalled-signals': ['error'],
-            '@angular-eslint/prefer-signal-model': ['error'],
-            '@angular-eslint/prefer-signals': ['error'],
-
-            // ── @typescript-eslint ───────────────────────────────────────────
-            '@typescript-eslint/explicit-function-return-type': [
-                'error',
-                {
-                    allowExpressions: true,
-                    allowTypedFunctionExpressions: true,
-                    allowHigherOrderFunctions: true,
-                    allowDirectConstAssertionInArrowFunctions: true,
-                },
-            ],
-            '@typescript-eslint/explicit-member-accessibility': [
-                'error',
-                { accessibility: 'no-public' },
-            ],
-            '@typescript-eslint/member-delimiter-style': 'error',
-            '@typescript-eslint/member-ordering': 'error',
-            '@typescript-eslint/no-base-to-string': 'warn',
-            // stylistic enables no-inferrable-types with default options (ignoreParameters: false);
-            // override here to allow typed parameters explicitly
-            '@typescript-eslint/no-inferrable-types': [
-                'error',
-                { ignoreParameters: true },
-            ],
-            // stylistic sets no-empty-function to error; downgrade to warn
-            '@typescript-eslint/no-empty-function': 'warn',
-            '@typescript-eslint/prefer-includes': 'warn',
-            '@typescript-eslint/return-await': ['error', 'never'],
-            '@typescript-eslint/typedef': ['error', { parameter: true }],
-            '@typescript-eslint/unified-signatures': 'error',
-            // off here — @typescript-eslint/no-shadow handles it correctly for TS
-            'no-shadow': 'off',
-            '@typescript-eslint/no-shadow': ['error', { hoist: 'all' }],
-            '@typescript-eslint/no-unused-vars': [
-                'error',
-                {
-                    varsIgnorePattern: '^_',
-                    argsIgnorePattern: '^_',
-                    caughtErrorsIgnorePattern: '^_',
-                },
-            ],
-
-            // ── eslint core ──────────────────────────────────────────────────
-            'arrow-body-style': 'error',
-            'arrow-parens': ['error', 'as-needed'],
-            curly: 'error',
-            eqeqeq: ['error', 'always'],
-            'guard-for-in': 'error',
-            'no-bitwise': 'error',
-            'no-caller': 'error',
-            'no-console': ['error', { allow: ['log', 'warn', 'error'] }],
-            'no-eval': 'error',
-            'no-extra-boolean-cast': 'off',
-            'no-multiple-empty-lines': 'error',
-            'no-new-wrappers': 'error',
-            'no-restricted-imports': [
-                'error',
-                { paths: ['rxjs/Rx', 'primeng/primeng', 'primeng'] },
-            ],
-            'no-return-assign': 'error',
-            'no-throw-literal': 'error',
-            'no-undef-init': 'error',
-            'no-useless-concat': 'error',
-            'object-shorthand': ['error', 'always', { avoidQuotes: true }],
-            'one-var': ['error', 'never'],
-            'prefer-arrow-callback': 'error',
-            'prefer-template': 'error',
-            radix: 'error',
-
-            // ── rxjs ─────────────────────────────────────────────────────────
-            'rxjs/no-implicit-any-catch': ['error', { allowExplicitAny: true }],
-            'rxjs/no-sharereplay': 'off',
-
-            // ── import-x ─────────────────────────────────────────────────────
-            'import-x/no-cycle': [
-                'warn',
-                { maxDepth: 3, ignoreExternal: true },
-            ],
-            'import-x/no-deprecated': 'warn',
-            'import-x/first': 'error',
-            'import-x/newline-after-import': 'error',
-            'import-x/no-duplicates': 'error',
-
-            // ── simple-import-sort ───────────────────────────────────────────
-            'simple-import-sort/imports': 'error',
-            'simple-import-sort/exports': 'error',
-
-            // ── prestations-ng ──────────────────────────────────────────────
-            '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
-        },
     },
 
     // ─── HTML templates ────────────────────────────────────────────────────────
     {
         files: ['**/*.html'],
-        extends: [
-            ...angular.configs.templateRecommended,
-            ...angular.configs.templateAccessibility,
-        ],
-        rules: {
-            '@angular-eslint/template/no-negated-async': 'off',
-            '@angular-eslint/template/button-has-type': 'error',
-        },
+        extends: [...prestationsNg.configs.templateRecommended],
     },
 
     // ─── Prettier (must be last — disables formatting rules) ───────────────────
@@ -1257,6 +1120,38 @@ export default tseslint.config(
 );
 ```
 
+That is the whole file. The two `*Recommended` configs come from the library and carry
+everything: the `eslint`, `typescript-eslint` and `angular-eslint` baselines, the template
+accessibility set, the naming and import conventions, and the rules written by the library
+itself. You declare no `plugins` and list no rule.
+
+The packages installed above are still required — the library's config imports them from your
+`node_modules` rather than shipping its own copies. For the same reason, do **not** spread
+`angular.configs.tsRecommended` or `angular.configs.templateRecommended` yourself: they are
+already included, and declaring the same plugin twice from two different copies makes ESLint
+fail outright.
+
+#### 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), alongside the leaner `tsRules` / `templateRules`
+configs for a project that supplies its own style.
+
+One consequence to keep in mind:
+
+- A rule added — or tightened — 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
+// `templateRules` or `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,24 @@
+import angular from 'angular-eslint';
+
+import templateRules from './template-rules.mjs';
+
+/**
+ * The house Angular template preset: the recommended and accessibility baselines, this
+ * library's own rules, and the conventions every prestations-ng project follows.
+ *
+ * Meant for the `extends` of a `**\/*.html` block. It brings its own parser and plugins,
+ * so do not spread `angular.configs.templateRecommended` alongside it.
+ */
+const templateRecommended = (plugin) => [
+    ...angular.configs.templateRecommended,
+    ...angular.configs.templateAccessibility,
+    ...templateRules(plugin),
+    {
+        name: 'prestations-ng/template-recommended',
+        rules: {
+            '@angular-eslint/template/no-negated-async': 'off',
+            '@angular-eslint/template/button-has-type': 'error',
+        },
+    },
+];
+export default templateRecommended;

package/eslint/configs/template-rules.mjs

@@ -0,0 +1,17 @@
+import templateBase from './template-base.mjs';
+
+// Only the rules written by this library. `templateRecommended` includes it, alongside
+// the house style; use this layer directly to opt out of the latter.
+const templateRules = (plugin) => [
+    templateBase(plugin),
+    {
+        name: 'prestations-ng/template-rules',
+        rules: {
+            // Also in `tsRules`: 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 templateRules;

package/eslint/configs/ts-base.mjs

@@ -0,0 +1,10 @@
+// Registers the plugin without enabling any rule. Meant to be used through
+// `tsRules` or `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;