From 6120471b664684be7157b07e32a5285a467a859c Mon Sep 17 00:00:00 2001
From: Julien Gautier <jgautier.webdev@gmail.com>
Date: Fri, 15 May 2026 12:25:20 +0200
Subject: [PATCH] chore(workspace): tsconfig composite refs + axe-linter
 false-positive config (#147)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Three editor-noise sources flagged by the VS Code TypeScript service + the Deque axe Linter extension, each tamed at the right layer. No runtime behaviour change.

| Source | Fix |
| --- | --- |
| **TS6306** — Referenced project `libs/{shared/ui,shared/state,feature/auth}` must have `composite: true`. Nx 22's lib generator doesn't emit `composite`; modern VS Code TS service flags it. | Add `composite: true` to each lib's `tsconfig.lib.json`, let `nx sync` redirect consumer references in `apps/portal-{shell,admin}/tsconfig.app.json` to point at the `.lib.json` directly. |
| **TS6504** — `moduleResolution: "node"` / `"node10"` deprecated, removed in TS 7.0. Two hits on the BFF tsconfigs. | Add `ignoreDeprecations: "5.0"` on `apps/portal-bff/tsconfig.{app,spec}.json` — the opt-out knob the diagnostic itself suggests. A proper migration to `nodenext`/`node16` is a separate chantier. |
| **axe-core/list (WCAG 1.3.1)** — `<ul>` "must only directly contain `<li>`, `<script>`, or `<template>`" — fires on Angular 17+ `@for` blocks inside lists. Pure static-linter limitation; rendered DOM is fine. | New `.axe-linter.yml` at repo root: `global-disable: [list]`. |

## What lands

### `composite: true` on lib `.lib.json`

[`libs/shared/ui/tsconfig.lib.json`](libs/shared/ui/tsconfig.lib.json), [`libs/shared/state/tsconfig.lib.json`](libs/shared/state/tsconfig.lib.json), [`libs/feature/auth/tsconfig.lib.json`](libs/feature/auth/tsconfig.lib.json) get `composite: true` added. `nx sync` then automatically rewrites consumer references:

```diff
- "path": "../../libs/shared/ui"
+ "path": "../../libs/shared/ui/tsconfig.lib.json"
```

in [`apps/portal-shell/tsconfig.app.json`](apps/portal-shell/tsconfig.app.json) and [`apps/portal-admin/tsconfig.app.json`](apps/portal-admin/tsconfig.app.json). Semantically cleaner — the app references the lib's actual compile config (which produces the `.d.ts` it consumes), not the lib's solution-style root tsconfig.

**Earlier attempt — composite on the solution `tsconfig.json` — silently broke `vitest`**: the Angular Vite plugin chokes on a composite project with `files: []` / `include: []` and falls through, leaving spec files loaded but tests not registered (`"No test suite found in file"`). Moving `composite` to `.lib.json` (the project that actually has inputs) fixes the contract without poking the plugin.

### `ignoreDeprecations: "5.0"`

[`apps/portal-bff/tsconfig.app.json`](apps/portal-bff/tsconfig.app.json) and [`apps/portal-bff/tsconfig.spec.json`](apps/portal-bff/tsconfig.spec.json) — silences `Option 'moduleResolution=node10' is deprecated and will stop functioning in TypeScript 7.0`. The diagnostic suggests `"6.0"` as the value, but TS 5.9 (our pinned version) only accepts `"5.0"`; using `"6.0"` results in `TS5103: Invalid value for '--ignoreDeprecations'` and breaks every spec. `"5.0"` is the current-gen accepted value.

The deprecation is real — TS 7.0 will drop both `"node"` and `"node10"` `moduleResolution` modes. The migration target is `moduleResolution: "nodenext"` paired with matching `module: "nodenext"`, but that interacts non-trivially with Nest's CommonJS pipeline and the BFF's import semantics. Out of scope for a drive-by fix; we'll handle it as a dedicated chantier when TS 7.0 lands on the roadmap.

### `.axe-linter.yml`

New file at repo root:

```yaml
global-disable:
  - list
```

The Deque axe Linter VS Code extension reads `.axe-linter.yml` at workspace root. The `list` rule (WCAG 1.3.1) fires false positives on Angular 17+ control-flow syntax — `@for (item of list; ...) { <li>… }` looks like a non-`<li>` child of `<ul>` to a static HTML scanner. The Angular compiler erases those tokens at build time; the rendered DOM is compliant. CI accessibility coverage is provided by `axe-playwright` per [ADR-0016 §"Tooling"](docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md) — it runs against the rendered DOM and is unaffected by this disable.

## Notes for the reviewer

- **Why not `composite: true` on every lib?** Per CLAUDE.md "no premature abstractions" — `libs/shared/{tokens,util}` are not currently referenced by any `tsconfig.app.json`, so they don't trigger TS6306. Adding `composite` to them would be future-proofing without a current consumer. When a consumer reference is added, the same one-line fix lands then.
- **Why not migrate `moduleResolution` properly?** The BFF runs on Nest's CommonJS pipeline; `nodenext` brings stricter ESM resolution (`.js` extensions in imports, package `exports` map enforcement) that ripples through. Not a 5-minute change. The `ignoreDeprecations` knob is the textbook defer mechanism for exactly this case.
- **Why disable `list` globally rather than per-file?** The rule's false-positive pattern (`<ul><@for>` / `<ol><@for>`) applies workspace-wide; we use `@for` consistently across `portal-shell` + `portal-admin`. Per-file disables would multiply as new templates land. axe-playwright remains the authoritative check on the rule.

## Test plan

- [x] `pnpm nx run-many -t lint test build --projects=portal-shell,portal-admin,portal-bff,shared-ui,shared-state,feature-auth` — 18/18 tasks pass. **517 specs green** across the affected projects.
- [x] `pnpm nx sync:check` — workspace in sync after the changes; running `sync` again is a no-op.
- [ ] Editor smoke — reopen the workspace in VS Code: the TS6306 errors on lib `tsconfig.json` files should be gone, the two `moduleResolution=node10` deprecation lines on BFF tsconfigs should be silenced, and the `list` rule under `sidebar.html` (`portal-admin`) should no longer surface.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: https://git.unespace.com/julien/apf_portal/pulls/147
---
 .axe-linter.yml                     | 14 ++++++++++++++
 apps/portal-admin/tsconfig.app.json |  4 ++--
 apps/portal-bff/tsconfig.app.json   |  3 ++-
 apps/portal-bff/tsconfig.spec.json  |  1 +
 apps/portal-shell/tsconfig.app.json |  6 +++---
 libs/feature/auth/tsconfig.lib.json |  1 +
 libs/shared/state/tsconfig.lib.json |  1 +
 libs/shared/ui/tsconfig.lib.json    |  1 +
 8 files changed, 25 insertions(+), 6 deletions(-)
 create mode 100644 .axe-linter.yml

diff --git a/.axe-linter.yml b/.axe-linter.yml
new file mode 100644
index 0000000..62130ae
--- /dev/null
+++ b/.axe-linter.yml
@@ -0,0 +1,14 @@
+# Deque axe Linter config — silences false positives the static
+# HTML scanner emits against Angular 17+ control-flow blocks
+# (`@for`, `@if`, `@switch`) used inline in templates.
+#
+# The `list` rule (WCAG 1.3.1) flags `@for (item of …) { <li>… }`
+# constructs as if the `@for` text were a non-<li> child of <ul>/<ol>.
+# At build time, the Angular compiler erases those tokens — the
+# rendered DOM only contains <li> children. The axe-playwright suite
+# wired into CI per ADR-0016 runs against the rendered DOM, so the
+# real accessibility contract is enforced there; this file only
+# tames the editor-side noise.
+
+global-disable:
+  - list
diff --git a/apps/portal-admin/tsconfig.app.json b/apps/portal-admin/tsconfig.app.json
index 66d8e42..4ff1d86 100644
--- a/apps/portal-admin/tsconfig.app.json
+++ b/apps/portal-admin/tsconfig.app.json
@@ -8,10 +8,10 @@
   "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
   "references": [
     {
-      "path": "../../libs/shared/ui"
+      "path": "../../libs/shared/ui/tsconfig.lib.json"
     },
     {
-      "path": "../../libs/feature/auth"
+      "path": "../../libs/feature/auth/tsconfig.lib.json"
     }
   ]
 }
diff --git a/apps/portal-bff/tsconfig.app.json b/apps/portal-bff/tsconfig.app.json
index 2106ce4..800bc44 100644
--- a/apps/portal-bff/tsconfig.app.json
+++ b/apps/portal-bff/tsconfig.app.json
@@ -7,7 +7,8 @@
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
     "target": "es2021",
-    "moduleResolution": "node"
+    "moduleResolution": "node",
+    "ignoreDeprecations": "5.0"
   },
   "include": ["src/**/*.ts"],
   "exclude": ["jest.config.ts", "jest.config.cts", "src/**/*.spec.ts", "src/**/*.test.ts"]
diff --git a/apps/portal-bff/tsconfig.spec.json b/apps/portal-bff/tsconfig.spec.json
index 01c59b6..062d0ab 100644
--- a/apps/portal-bff/tsconfig.spec.json
+++ b/apps/portal-bff/tsconfig.spec.json
@@ -4,6 +4,7 @@
     "outDir": "../../dist/out-tsc",
     "module": "commonjs",
     "moduleResolution": "node10",
+    "ignoreDeprecations": "5.0",
     "types": ["jest", "node"]
   },
   "include": [
diff --git a/apps/portal-shell/tsconfig.app.json b/apps/portal-shell/tsconfig.app.json
index 804362f..989c317 100644
--- a/apps/portal-shell/tsconfig.app.json
+++ b/apps/portal-shell/tsconfig.app.json
@@ -8,13 +8,13 @@
   "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
   "references": [
     {
-      "path": "../../libs/shared/state"
+      "path": "../../libs/shared/state/tsconfig.lib.json"
     },
     {
-      "path": "../../libs/shared/ui"
+      "path": "../../libs/shared/ui/tsconfig.lib.json"
     },
     {
-      "path": "../../libs/feature/auth"
+      "path": "../../libs/feature/auth/tsconfig.lib.json"
     }
   ]
 }
diff --git a/libs/feature/auth/tsconfig.lib.json b/libs/feature/auth/tsconfig.lib.json
index a9b98ba..a89f7da 100644
--- a/libs/feature/auth/tsconfig.lib.json
+++ b/libs/feature/auth/tsconfig.lib.json
@@ -1,6 +1,7 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     "outDir": "../../../dist/out-tsc",
     "declaration": true,
     "declarationMap": true,
diff --git a/libs/shared/state/tsconfig.lib.json b/libs/shared/state/tsconfig.lib.json
index a9b98ba..a89f7da 100644
--- a/libs/shared/state/tsconfig.lib.json
+++ b/libs/shared/state/tsconfig.lib.json
@@ -1,6 +1,7 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     "outDir": "../../../dist/out-tsc",
     "declaration": true,
     "declarationMap": true,
diff --git a/libs/shared/ui/tsconfig.lib.json b/libs/shared/ui/tsconfig.lib.json
index a9b98ba..a89f7da 100644
--- a/libs/shared/ui/tsconfig.lib.json
+++ b/libs/shared/ui/tsconfig.lib.json
@@ -1,6 +1,7 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
+    "composite": true,
     "outDir": "../../../dist/out-tsc",
     "declaration": true,
     "declarationMap": true,