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

package/package.json

@@ -40,7 +40,7 @@
   "ng-update": {
     "migrations": "./schematics/migration-collection.json"
   },
-  "version": "19.0.6-beta.2",
+  "version": "19.0.6",
   "module": "fesm2022/dsivd-prestations-ng.mjs",
   "typings": "types/dsivd-prestations-ng.d.ts",
   "exports": {

package/src/eslint/configs/__tests__/configs.test.mjs

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import prestationsNg, { configs, plugin, rules } from '../../index.mjs';
+
+const PLUGIN_KEY = '@dsivd/prestations-ng';
+
+const configNames = Object.keys(configs);
+
+// Rule ids enabled by a config, whatever its severity.
+const enabledIdsOf = (config) =>
+  config.flatMap((entry) => Object.keys(entry.rules ?? {}));
+
+describe('eslint configs', () => {
+  it('should expose one config per lint target', () => {
+    expect(configNames).toEqual(['tsRecommended', 'templateRecommended']);
+  });
+
+  it.each(configNames)('%s should register the plugin first', (name) => {
+    const [base, ...rest] = configs[name];
+
+    expect(base.plugins).toEqual({ [PLUGIN_KEY]: plugin });
+    expect(base.rules).toBeUndefined();
+    expect(rest.every((entry) => entry.plugins === undefined)).toBe(true);
+  });
+
+  it.each(configNames)('%s should name every entry', (name) => {
+    for (const entry of configs[name]) {
+      expect(entry.name).toMatch(/^prestations-ng\//);
+    }
+  });
+
+  // A config referencing a rule that does not exist breaks the lint of every
+  // consuming project at once, so it must never reach a release.
+  it.each(configNames)('%s should only enable existing rules', (name) => {
+    for (const id of enabledIdsOf(configs[name])) {
+      expect(id.startsWith(`${PLUGIN_KEY}/`)).toBe(true);
+      expect(rules).toHaveProperty(id.slice(PLUGIN_KEY.length + 1));
+    }
+  });
+
+  it('should enable every rule in at least one config', () => {
+    const enabled = new Set(configNames.flatMap((n) => enabledIdsOf(configs[n])));
+
+    for (const ruleName of Object.keys(rules)) {
+      expect(enabled).toContain(`${PLUGIN_KEY}/${ruleName}`);
+    }
+  });
+
+  it('should keep the template-only rule out of the TypeScript config', () => {
+    expect(enabledIdsOf(configs.tsRecommended)).not.toContain(
+      `${PLUGIN_KEY}/no-uninvoked-signal-in-template`,
+    );
+  });
+});
+
+describe('eslint plugin', () => {
+  it('should be named after the npm package', () => {
+    expect(plugin.meta.name).toBe(PLUGIN_KEY);
+  });
+
+  it('should mirror the named exports on the default export', () => {
+    expect(prestationsNg).toEqual({ configs, plugin, rules });
+  });
+
+  it.each(Object.entries(rules))('%s should be a usable rule', (_, rule) => {
+    expect(typeof rule.create).toBe('function');
+    expect(Object.keys(rule.meta.messages).length).toBeGreaterThan(0);
+    expect(rule.meta.type).toBe('problem');
+  });
+});

package/src/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/src/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/src/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/src/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/src/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/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs

@@ -1,3 +1,4 @@
+import * as templateParser from '@angular-eslint/template-parser';
 import { describe, it } from 'vitest';
 import { RuleTester } from 'eslint';
 import rule from '../no-direct-signal-mutation.mjs';
@@ -46,13 +47,13 @@ describe('no-direct-signal-mutation', () => {
         'this.pendingFilesByFormKey.get(formKey).url = baseUrl',
         'const autocompleteComponent = viewChild("auto"); autocompleteComponent().inputElement().nativeElement.hidden = true',
         'component.inputElement().nativeElement.value = ""',
+        // A view query signal is read-only: there is no `.set()`/`.update()` to suggest,
+        // so `viewChild.required(…)` has to be excluded like `viewChild(…)`.
+        'const requiredChild = viewChild.required("req"); requiredChild().nativeElement.hidden = true',
+        'const requiredRows = contentChildren.required("row"); requiredRows()[0].hidden = true',
 
         // Method chaining without assignment
         'model().update((v) => v).subscribe()',
-
-        // One-way bindings are OK
-        '[model]="model().property"',
-        '[ngModel]="model().comment"',
       ],
 
       invalid: [
@@ -95,4 +96,85 @@ describe('no-direct-signal-mutation', () => {
       ],
     });
   });
+
+  const templateRuleTester = new RuleTester({
+    languageOptions: { parser: templateParser },
+  });
+
+  it('should validate signal mutation rule in templates', () => {
+    templateRuleTester.run('no-direct-signal-mutation', rule, {
+      valid: [
+        // Reads only
+        '{{ model().property }}',
+        '<div [value]="model().property"></div>',
+        '<div [value]="model().deeply.nested.property"></div>',
+        '<div [value]="model().array[0]"></div>',
+
+        // Going through the signal API
+        '<button (click)="model.set({ property: value })"></button>',
+        '<button (click)="model.update((v) => ({ ...v, property: value }))"></button>',
+
+        // Assignments that do not target a call result
+        '<button (click)="property = value"></button>',
+        '<button (click)="obj.property = value"></button>',
+        '<button (click)="this.obj.property = value"></button>',
+
+        // Two-way binding on the signal itself: Angular calls `.set()`
+        '<input [(ngModel)]="model" />',
+        '<app-child [(value)]="comment"></app-child>',
+
+        // Same exclusions as the TypeScript side: a call taking arguments, or reached
+        // through a foreign receiver, is not assumed to be a signal read.
+        '<button (click)="pendingFilesByFormKey.get(formKey).files = []"></button>',
+        '<button (click)="this.pendingFilesByFormKey.get(formKey).url = baseUrl"></button>',
+        '<button (click)="component.inputElement().nativeElement.value = &quot;&quot;"></button>',
+        '<button (click)="obj.getter().property = value"></button>',
+        // An output named `…Change` that carries no assignment
+        '<app-child (valueChange)="model.set($event)"></app-child>',
+      ],
+
+      invalid: [
+        {
+          code: '<button (click)="model().property = value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: '<button (click)="this.model().property = value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: '<button (click)="model().deeply.nested.property = value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: '<button (click)="model().array[0] = value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        // Every compound assignment accepted by the Angular parser
+        {
+          code: '<button (click)="model().property += value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: '<button (click)="model().property ??= value"></button>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        // The mutation hidden in a two-way binding, reported once and not twice
+        {
+          code: '<input [(ngModel)]="model().comment" />',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: '<app-child [(value)]="model().nested.property"></app-child>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+        // An explicit `…Change` handler carrying the assignment: the Binary reports it,
+        // the BoundEvent must not report it a second time.
+        {
+          code: '<app-child (valueChange)="model().property = $event"></app-child>',
+          errors: [{ messageId: 'directMutation' }],
+        },
+      ],
+    });
+  });
 });

package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs

@@ -0,0 +1,291 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as templateParser from '@angular-eslint/template-parser';
+import { RuleTester } from 'eslint';
+import { beforeAll, describe, it } from 'vitest';
+import rule from '../no-uninvoked-signal-in-template.mjs';
+
+describe('no-uninvoked-signal-in-template', () => {
+  const ruleTester = new RuleTester({
+    languageOptions: { parser: templateParser },
+  });
+
+  // The rule reads the twin `.ts` of the template and walks its inheritance chain, so
+  // the fixtures have to exist on disk. They are laid out like a real project — the
+  // base class package under `node_modules` — so that module resolution is exercised.
+  let templatePath;
+  let inlineTemplatePath;
+  let heirTemplatePath;
+
+  const write = (path, content) => {
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+  };
+
+  beforeAll(() => {
+    const root = mkdtempSync(join(tmpdir(), 'no-uninvoked-signal-'));
+
+    // A flattened declaration bundle, as published by ng-packagr: several classes in a
+    // single file, signal types qualified by the namespace they were imported under.
+    write(
+      join(root, 'node_modules', '@fake', 'kit', 'package.json'),
+      JSON.stringify({ name: '@fake/kit', types: 'index.d.ts' }),
+    );
+    write(
+      join(root, 'node_modules', '@fake', 'kit', 'index.d.ts'),
+      `import * as _angular_core from '@angular/core';
+       declare class KitInputComponent {
+         readonly label: _angular_core.InputSignal<string>;
+         readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+         readonly value: _angular_core.ModelSignal<string>;
+         plainInherited: string;
+         reset(): void;
+       }
+       declare class KitFieldComponent extends KitInputComponent {
+         readonly fieldId: _angular_core.Signal<string>;
+       }
+       declare class UnrelatedComponent {
+         readonly unrelated: _angular_core.InputSignal<string>;
+       }
+       export { KitFieldComponent, KitInputComponent, UnrelatedComponent };`,
+    );
+
+    // A base class of the project itself, reached through a relative import.
+    write(
+      join(root, 'src', 'abstract-page.component.ts'),
+      `import { KitFieldComponent } from '@fake/kit';
+       export abstract class AbstractPageComponent extends KitFieldComponent {
+         readonly foehnFormComponent = viewChild(FoehnFormComponent);
+         protected readonly step = signal(0);
+       }`,
+    );
+
+    write(
+      join(root, 'src', 'sample.component.ts'),
+      `import { Component, computed, input, model, signal } from '@angular/core';
+       import { AbstractPageComponent } from './abstract-page.component';
+
+       class LocalBaseComponent extends AbstractPageComponent {
+         readonly fromLocalBase = input<string>('');
+       }
+
+       @Component({ selector: 'app-sample', templateUrl: './sample.component.html' })
+       export class SampleComponent extends LocalBaseComponent {
+         readonly count = signal(0);
+         readonly title = input.required<string>();
+         readonly comment = model<string>('');
+         readonly double = computed(() => this.count() * 2);
+         readonly items = computed<string[]>(() => []);
+         readonly fromType: Signal<number> = this.double;
+         plainField = 'plain';
+         helper(): string { return ''; }
+       }`,
+    );
+
+    templatePath = join(root, 'src', 'sample.component.html');
+    // Virtual block name produced by `angular.processInlineTemplates`.
+    inlineTemplatePath = join(
+      root,
+      'src',
+      'sample.component.ts',
+      '1_inline-template-sample.component.ts-1.component.html',
+    );
+
+    // A component whose only signals come from its base classes.
+    write(
+      join(root, 'src', 'heir.component.ts'),
+      `import { AbstractPageComponent } from './abstract-page.component';
+       export class HeirComponent extends AbstractPageComponent {}`,
+    );
+    heirTemplatePath = join(root, 'src', 'heir.component.html');
+  });
+
+  const template = (code) => ({ code, filename: templatePath });
+  const invalidTemplate = (code, output, ...names) => ({
+    ...template(code),
+    output,
+    errors: names.map((name) => ({ messageId: 'uninvoked', data: { name } })),
+  });
+
+  it('should validate uninvoked signal rule', () => {
+    ruleTester.run('no-uninvoked-signal-in-template', rule, {
+      valid: [
+        // Invoked signals
+        template('{{ count() }}'),
+        template('{{ this.count() }}'),
+        template('{{ double() + count() }}'),
+        template('<div [hidden]="!count()"></div>'),
+        template('@if (double()) { {{ title() }} }'),
+
+        // Safe call
+        template('{{ count?.() }}'),
+
+        // Members of the signal API target the signal itself
+        template('<button (click)="count.set(1)"></button>'),
+        template('<button (click)="comment.update((v) => v + \'!\')"></button>'),
+        template('<app-child [value]="comment.asReadonly()"></app-child>'),
+
+        // Non-signal members
+        template('{{ plainField }}'),
+        template('{{ helper() }}'),
+
+        // Written position: Angular calls `.set()` itself
+        template('<button (click)="comment = \'x\'"></button>'),
+
+        // Template-local names shadow the class members
+        template('<input #count />{{ count.value }}'),
+        template('@for (title of items(); track title) { {{ title }} }'),
+        template('@if (comment(); as count) { {{ count }} }'),
+        template('@let count = 1; {{ count }}'),
+        template('<ng-template let-count>{{ count }}</ng-template>'),
+        template('@for (item of items(); track item) { {{ $index }} }'),
+
+        // No twin `.ts`: nothing to resolve
+        { code: '{{ count }}', filename: 'unknown.component.html' },
+      ],
+
+      invalid: [
+        invalidTemplate('{{ count }}', '{{ count() }}', 'count'),
+        invalidTemplate('{{ this.count }}', '{{ this.count() }}', 'count'),
+        invalidTemplate(
+          '<div [hidden]="!count"></div>',
+          '<div [hidden]="!count()"></div>',
+          'count',
+        ),
+        invalidTemplate(
+          '{{ title + \'x\' }}',
+          '{{ title() + \'x\' }}',
+          'title',
+        ),
+        invalidTemplate(
+          '@if (double) { {{ count }} }',
+          '@if (double()) { {{ count() }} }',
+          'double',
+          'count',
+        ),
+        invalidTemplate(
+          '<div>{{ items.length }}</div>',
+          '<div>{{ items().length }}</div>',
+          'items',
+        ),
+        // Declared by its type only, without a signal factory
+        invalidTemplate('{{ fromType }}', '{{ fromType() }}', 'fromType'),
+        invalidTemplate(
+          '@for (item of items; track item) { {{ item }} }',
+          '@for (item of items(); track item) { {{ item }} }',
+          'items',
+        ),
+        invalidTemplate(
+          '<button (click)="doSomething(count)"></button>',
+          '<button (click)="doSomething(count())"></button>',
+          'count',
+        ),
+      ],
+    });
+  });
+
+  // A writable signal is two-way bound WITHOUT parentheses: Angular reads it and calls
+  // `.set()` itself. Adding `()` there is a compilation error, so the autofix must not
+  // touch the target of a `[(…)]` binding.
+  it('should not require parentheses on a two-way bound writable signal', () => {
+    ruleTester.run('no-uninvoked-signal-in-template', rule, {
+      valid: [
+        template('<app-child [(value)]="comment"></app-child>'),
+        template('<app-child [(value)]="this.comment"></app-child>'),
+        template('<input [(ngModel)]="comment" />'),
+        // Inherited writable signal as the target
+        template('<app-child [(value)]="value"></app-child>'),
+        // Two-way binding next to a correctly invoked signal
+        template('<app-child [(value)]="comment" [label]="title()"></app-child>'),
+      ],
+
+      invalid: [
+        // The exemption is scoped to the bound position, not to the signal name
+        invalidTemplate(
+          '<app-child [(value)]="comment"></app-child>{{ comment }}',
+          '<app-child [(value)]="comment"></app-child>{{ comment() }}',
+          'comment',
+        ),
+        // A one-way binding on the same element is still reported, exactly once
+        invalidTemplate(
+          '<app-child [(value)]="comment" [label]="title"></app-child>',
+          '<app-child [(value)]="comment" [label]="title()"></app-child>',
+          'title',
+        ),
+        // `[value]` alone is not a two-way binding
+        invalidTemplate(
+          '<app-child [value]="comment"></app-child>',
+          '<app-child [value]="comment()"></app-child>',
+          'comment',
+        ),
+      ],
+    });
+  });
+
+  // No list of base-class members is configured anywhere: everything below is resolved
+  // by following the `extends` clauses across files and packages.
+  it('should resolve inherited signals automatically', () => {
+    const heir = (code) => ({ code, filename: heirTemplatePath });
+    const invalidHeir = (code, output, name) => ({
+      ...heir(code),
+      output,
+      errors: [{ messageId: 'uninvoked', data: { name } }],
+    });
+
+    ruleTester.run('no-uninvoked-signal-in-template', rule, {
+      valid: [
+        // Relative import, then a package, up the whole chain
+        heir('{{ foehnFormComponent()?.id }}'),
+        heir('{{ fieldId() }}'),
+        heir('<div [class.off]="disabled()">{{ label() }}</div>'),
+        template('{{ fromLocalBase() }}'),
+
+        // Not a signal, even though it sits on the same base class
+        heir('{{ plainInherited }}'),
+        heir('<button (click)="reset()"></button>'),
+
+        // A class of the same declaration bundle that is NOT in the chain
+        heir('{{ unrelated }}'),
+      ],
+
+      invalid: [
+        // Declared in the base class of the twin `.ts`
+        invalidHeir(
+          '{{ foehnFormComponent }}',
+          '{{ foehnFormComponent() }}',
+          'foehnFormComponent',
+        ),
+        // Declared in a package, reached through two levels of `extends`
+        invalidHeir('{{ label }}', '{{ label() }}', 'label'),
+        invalidHeir('{{ fieldId }}', '{{ fieldId() }}', 'fieldId'),
+        // `InputSignalWithTransform`
+        invalidHeir(
+          '<div [class.off]="disabled"></div>',
+          '<div [class.off]="disabled()"></div>',
+          'disabled',
+        ),
+        // Base class declared in the component file itself
+        invalidTemplate(
+          '{{ fromLocalBase }}',
+          '{{ fromLocalBase() }}',
+          'fromLocalBase',
+        ),
+      ],
+    });
+  });
+
+  it('should resolve the signals of an inline template', () => {
+    ruleTester.run('no-uninvoked-signal-in-template', rule, {
+      valid: [{ code: '{{ count() }}', filename: inlineTemplatePath }],
+      invalid: [
+        {
+          code: '{{ count }}',
+          filename: inlineTemplatePath,
+          output: '{{ count() }}',
+          errors: [{ messageId: 'uninvoked', data: { name: 'count' } }],
+        },
+      ],
+    });
+  });
+});

package/src/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,
+};