@hublo/sentinel 1.3.0 → 1.4.0-alpha.2

package/docs/test-adoption.md

@@ -0,0 +1,175 @@
+# Test adoption cheat sheet
+
+Sentinel owns the test toolchain so a module can be tested on its own, and so the workspace can
+drop Jest before Nx v24 removes `@nx/jest:jest`.
+
+This page is written from measurement. Every number in it was taken on this monorepo, and the ones
+that decided a design choice say which choice.
+
+- [What the ground actually looks like](#what-the-ground-actually-looks-like)
+- [The one line that makes a per-module migration possible](#the-one-line-that-makes-a-per-module-migration-possible)
+- [What `--init --test` rewrites, and what it refuses](#what---init---test-rewrites-and-what-it-refuses)
+- [Nest services](#nest-services)
+- [The check that decides whether you are done](#the-check-that-decides-whether-you-are-done)
+
+## What the ground actually looks like
+
+|                                              |                                                |
+| -------------------------------------------- | ---------------------------------------------- |
+| test targets on `@nx/jest:jest`              | **107**, the executor Nx v24 removes           |
+| on `@nx/vitest:test`                         | 3, all front, target named `test`              |
+| target `vitest`, inferred from an npm script | 2, both Svelte                                 |
+| jest configs                                 | 108, of which **107 extend one shared preset** |
+| environment                                  | 102 `node`, 5 `jsdom`                          |
+| test files                                   | 6397, of which **3481 call `jest.*`**          |
+| files importing `jest-mock-extended`         | **2491**                                       |
+
+Two consequences worth stating before anything else.
+
+**The target is named `test` everywhere.** 107 modules already call it that, and so do the three
+fronts already on Vitest. The two Svelte modules call it `vitest` only because that is the name of
+an npm script, which nx turned into a target. Adopting under `test` means **CI never changes during
+the migration**: a module on Jest and a module on Vitest both answer `nx affected -t test`.
+
+**Tests are barely declared in `package.json` today.** Zero test targets in an `nx` block, four
+`test` scripts in the whole repo. Where the build role usually rewired a script that existed, this
+one creates it.
+
+## Which targets are in scope, decided by one question
+
+Not "which directory", because tests live wherever their authors put them. The question is whether
+a target **breaks when Jest is removed**, and that is measurable:
+
+| target                          | how many | what runs it                                     | in scope |
+| ------------------------------- | -------: | ------------------------------------------------ | -------- |
+| `test`                          |      107 | `@nx/jest:jest`                                  | **yes**  |
+| `test-integration`              |        3 | jest, 14 files call the jest API                 | **yes**  |
+| `test-acceptance` and `-legacy` |        3 | `nx:run-commands`, 15 files call the jest API    | **yes**  |
+| `test-prisma`                   |        1 | `@nx/jest:jest` with `jest.prisma.config.ts`     | **yes**  |
+| `test-functional`               |        1 | `@nx/jest:jest` with `jest.functional.config.ts` | **yes**  |
+| `stress-test`                   |        2 | `zx` scripts                                     | no       |
+| `loadtests`                     |        2 | `k6`                                             | no       |
+
+The last two never load Jest, so removing it changes nothing for them. Everything else does, which
+also means the migration has more than one config per module to answer for: `jest.prisma.config.ts`
+and `jest.functional.config.ts` are targets of their own.
+
+## A module with no tests is cleaned, not configured
+
+Six Nest services have **zero test files** and a green `test` target, because `passWithNoTests: true`
+makes an empty run a success. Writing them a Vitest config would be furniture for a room nobody
+enters.
+
+What they need is the opposite: their Jest leftovers removed, so nothing breaks the day Jest leaves
+the workspace. The Jest config file, the Jest dependencies, and nothing else. No new config, no new
+script, no change to what they build or ship.
+
+## The one line that makes a per-module migration possible
+
+**104 files under `libs/` import `jest-mock-extended`.** They are shared test helpers, used by
+modules on both runners. That package loads `@jest/globals`, which refuses to run outside Jest, so:
+
+- migrating them breaks every module still on Jest
+- leaving them breaks every module moved to Vitest
+
+Old and new do **not** cohabit on shared helpers, and that alone would force a big-bang migration.
+
+```ts
+{ find: /^jest-mock-extended$/, replacement: 'vitest-mock-extended' }
+```
+
+`vitest-mock-extended` is a fork of the Jest package and exports the same four names this repo uses
+(`mockDeep`, `mock`, `DeepMockProxy`, `MockProxy`), so an unmigrated helper resolves to the Vitest
+fork **inside an adopted module** and keeps resolving to the Jest one everywhere else. Measured on
+`mission`: failing suites went from **159 to 10**.
+
+A helper that uses the raw Jest API (`jest.fn()`) cannot be aliased, because that is a global rather
+than an import. There is one such helper on the Nest side, consumed by 6 modules. Sentinel ships the
+Vitest equivalent and an adopted module imports it from here, the same answer as the build role's
+toolchain: the tool owns the shared piece, so the monorepo keeps one copy per runner and no
+ordering constraint.
+
+## What `--init --test` rewrites, and what it refuses
+
+This role rewrites **test files**, not only configuration, and says so before it writes anything. A
+config-only adoption would leave the module red, so it would be worth nothing.
+
+| rule                                                                                                                | files in this repo |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `jest-mock-extended` → `vitest-mock-extended`                                                                       | 2491               |
+| `jest.*` → `vi.*`                                                                                                   | 3481               |
+| type references (`jest.Mock`, `jest.Mocked`, `jest.SpyInstance` → `MockInstance`, …) become an import from `vitest` | 744 occurrences    |
+| `jest.requireActual` → `await vi.importActual`, factory becomes `async`                                             | 26                 |
+| `jest.requireMock` → the mocked module imported directly, since `vi.mock` makes a static import the mock            | 16                 |
+| `jest.setTimeout(n)` → `vi.setConfig({ testTimeout: n })`                                                           | 4                  |
+| a mock factory returning a non-object → `{ default: … }`, which Vitest requires                                     | 2                  |
+| `jest.isolateModules` → `vi.resetModules()` + `await import(...)`                                                   | 1                  |
+
+**Selection is on API USE, never on file name.** Test helpers carry the same API as specs:
+`*.mock.ts`, `__mocks__/`, wrappers, fixtures. Ninety files in this repo are outside any spec glob.
+
+**What it refuses is fenced off before any global rewrite.** The first version of this codemod
+reported leaving two files alone and rewrote them anyway, producing `vi.requireMock`, which does not
+exist. Announcing a refusal and performing the change is worse than either.
+
+## Nest services
+
+The wall is decorator metadata: Nest resolves a constructor's parameters from
+`emitDecoratorMetadata`, and esbuild does not emit it. The build role's `decoratorMetadata` is a
+**Vite plugin**, so Vitest loads it unchanged, with the two compile modes already copied from nx.
+
+```ts
+plugins: [decoratorMetadata({ root: here })],
+resolve: { alias: [{ find: /^jest-mock-extended$/, replacement: 'vitest-mock-extended' },
+                   ...tsconfigAliases(workspaceRoot)] },
+test: { globals: true, environment: 'node', isolate: true },
+```
+
+**`isolate` stays `true`**, whatever the performance note in Vitest's docs suggests. Jest gives each
+test file a fresh module registry and `isolate: true` reproduces that. Nest registers metadata as an
+import SIDE EFFECT, a decorator writing into a catalog when its module loads, so a shared registry
+would make results depend on the order files ran in. That is the same fact the build role records
+next to `treeshake: { moduleSideEffects: true }`.
+
+## The check that decides whether you are done
+
+Not "the suite is green". **The suite gives the same result as before**, compared against a baseline
+taken BEFORE the migration:
+
+```console
+$ nx run <module>:test                 # jest, and write the numbers down
+$ sentinel --init --test
+$ nx run <module>:test                 # vitest
+```
+
+Take the baseline first, and compare the failing SETS rather than the counts. On `mission` the Jest
+baseline was not green (10 suites failed on `setTimeout is not defined`), and all ten pass under
+Vitest, so a count comparison would have read as a regression where there was an improvement.
+
+A codemod touching thousands of files cannot be reviewed by hand. The suite against its baseline is
+the review.
+
+### And the typecheck, which the suite cannot stand in for
+
+```console
+$ nx run <module>:typecheck            # BEFORE, and write that down too
+$ sentinel --init --test
+$ nx run <module>:typecheck            # after
+```
+
+⚠️ **A green suite does not mean a green module.** The migration rewrites TYPES as well as calls,
+and a wrong type is invisible to a run: the tests never evaluate it.
+
+Measured on `apps/nest/microservices/agency`, by someone adopting the published package with no
+knowledge of how it was built:
+
+|                      | before       | after         |
+| -------------------- | ------------ | ------------- |
+| `--run --test`       | 534 green    | 534 green     |
+| `--run --typescript` | **0 errors** | **10 errors** |
+
+All ten came from two wrong mappings, both since fixed. The point is not those ten. It is that a
+module can be migrated, pass its whole suite, and carry a broken typecheck into main, where the
+next CI run of a different target finds it.
+
+Take both baselines. A migration is done when both come back the same.

package/docs/typescript-adoption.md

@@ -0,0 +1,184 @@
+# TypeScript adoption cheat sheet
+
+A quick reference for adopting the sentinel TypeScript preset on a module, and for the everyday `--run` / `--inspect` commands. For the full, live command-and-output traces, see [`typescript-traces.md`](typescript-traces.md).
+
+## Adopt a module in two steps
+
+Run from the **module's own directory**. You do not need to install sentinel to run it: use `npx --yes` for a one-off.
+
+```bash
+# 1. write the module's config + the pinned devDependency, AND the workspace prep it needs
+cd apps/.../<module>
+npx --yes @hublo/sentinel@<version> --init --typescript --preset <react|nest|node>
+
+# 2. fetch what step 1 declared
+pnpm install
+```
+
+`--init` writes the module's `tsconfig` stub, its `typecheck` script, and pins `@hublo/sentinel@<version>` into the module's own `devDependencies` (so there is no manual `pnpm add`). It composes `extends: [<your base>, <preset>]` (keeping the monorepo's `paths` and structure), strips the options the preset owns (see below), and scaffolds a minimal `package.json` for a `project.json`-only module. Svelte is skipped (no preset yet). Always pass `--preset` in a monorepo: dependencies are hoisted, so detection can fall back to `node`.
+
+**`--init` also applies the workspace prep the module needs**, the one place it reaches the workspace root, because "set this module up" is not honest if the workspace then cannot install or resolve it. It is defensive: each fix is applied only when the root's own config shows it is needed, and is a no-op otherwise.
+
+- **release-age allow-list**: if the root uses pnpm's `minimumReleaseAgeExclude`, a freshly published sentinel is allow-listed so it installs.
+- **i18next singleton override**: if the root declares a second TypeScript (via `@typescript/native`), i18next is pinned to one instance so a re-resolve does not fork react-i18next and break translation-singleton tests. The pin tracks the declared version and disappears once the migration removes the second TypeScript.
+
+> **Renamed:** the option is `--preset`. `--flavour` was the original spelling and still
+> works, so nothing you have already written breaks, but it prints a deprecation notice and
+> will not be documented beyond this line.
+
+## Verbs at a glance
+
+| Verb        | Who / when         | Runs the tool?    | What you get                                                                |
+| ----------- | ------------------ | ----------------- | --------------------------------------------------------------------------- |
+| `--run`     | dev, everyday      | **yes** (tsc)     | executes the check, pass/fail. This is your `typecheck` script.             |
+| `--inspect` | dev, everyday      | no (reads config) | the resolved config: preset, target, and which rules are deferred           |
+| `--init`    | dev, once to adopt | writes files      | the tsconfig stub, the `typecheck` script, the pinned dep, + workspace prep |
+| `--migrate` | planned            | not available yet | reserved for changing an already-initialized setup (later ticket)           |
+| `--report`  | **deprecated**     | —                 | use `--run --json`: same work, same envelope                                |
+| `--status`  | **deprecated**     | —                 | use `--inspect`, which absorbed it                                          |
+
+**`--run` vs `--inspect`:** run _executes_ the check and gives you pass/fail plus the numbers (`--json` for error counts and structured diagnostics); inspect _reads_ the config and shows what applies, instantly and without running the tool, including adoption and conformity across modules.
+
+> **Deprecated, still working:** `--report` and `--status` were separate verbs and folded into
+> the two above, because they answered the same two questions in a different shape. Both still
+> run and print a notice telling you what to use instead.
+
+**Location** (any verb): from a module dir → that module; from the root → `--module <name>`, `--ci` (affected), or all modules. `--init` writes, so it targets one module only.
+
+**Your tsconfig extends exactly one preset.** The options every stack shares are flattened into
+each published preset at build time, so `@hublo/sentinel/tsconfig/react` is self-contained and
+there is nothing to stack under it. The shared layer lives in the repo as
+`src/roles/typescript/presets/shared.json`; it is ours and is never published on its own.
+
+## Everyday use (developers)
+
+```bash
+sentinel --run --typescript                     # in a module dir: type-check it (your `typecheck` script)
+sentinel --inspect --typescript                 # what config/preset applies here, and what's deferred
+sentinel --init --typescript --preset nest   # adopt this module (writes the stub)
+```
+
+## CI & reporting
+
+```bash
+sentinel --run --typescript --ci                # from the root: check affected modules, non-zero exit on failure
+sentinel --run --typescript --json              # machine-readable metrics + diagnostics for a dashboard
+sentinel --inspect --typescript                 # adoption + conformity coverage across the workspace
+```
+
+## Options
+
+| Option                  | What it does                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------- |
+| `--preset <name>`       | override detection (`react` / `nest` / `svelte` / `node`); recommended for `--init` |
+| `--module <name>`       | from the root, scope to one module                                                  |
+| `--ci`                  | from the root, only affected modules; non-zero exit on failure                      |
+| `--json`                | machine-readable envelope on stdout, for every verb; progress goes to stderr        |
+| `--max-diagnostics <n>` | cap the diagnostics embedded per module in `--run --json` (`0` = no cap)            |
+| `--dry-run`             | preview what `--init` would write, changing nothing                                 |
+| `--runner <tool>`       | override the default runner                                                         |
+| `-- <tool options>`     | `--run` only, one type named: everything after `--` goes to tsc itself (see below)  |
+
+## Measuring a deferred rule
+
+`--inspect` tells you a rule is deferred. That is honest, and it is not the question you
+actually have, which is how much debt is behind it. Everything after `--` is handed to tsc,
+so you can ask directly:
+
+```console
+$ sentinel --run --typescript -- --noImplicitAny
+sentinel: NOT the standard check — passing --noImplicitAny to the typescript tool.
+src/…/bulk-update-profile-exclusions-request.dto.ts(77,16): error TS7006: Parameter 'item' implicitly has an 'any' type.
+…
+```
+
+Three things worth knowing:
+
+- **The result is not your normal check**, and it says so on every run, plus `toolArgs` in
+  the `--json` envelope. These options can weaken a check as easily as strengthen it, and
+  `--run` is what CI calls, so never put one in a committed `typecheck` script.
+- **Emit is forced off.** This asks a question about the code, it does not build, so it will
+  not touch your build output or `.tsbuildinfo`.
+- **It checks the projects your `tsconfig.json` references**, not the solution file itself,
+  which holds no files. Build mode cannot serve this at all: it refuses compiler options
+  outright (`error TS5094: Compiler option '--noImplicitAny' may not be used with '--build'`).
+
+## Reading the numbers
+
+A plain `--run` streams tsc's own output, so you read the errors themselves, and the summary
+row is just the pass/fail mark. The counts are in the machine envelope:
+
+```console
+$ sentinel --run --typescript --json --max-diagnostics 1
+{
+  "schemaVersion": 2,
+  "results": [
+    {
+      "project": "network",
+      "target": "typescript",
+      "flavour": "node",
+      "ok": false,
+      "status": "failed",
+      "errors": 9,
+      "implicitAny": "deferred",
+      "diagnostics": [
+        { "file": "src/…/contractual-information.pg.repository.ts", "line": 133, "col": 21,
+          "code": "TS2339", "message": "Property 'closedAt' does not exist on type …" }
+      ],
+      "diagnosticsTruncated": true
+    }
+  ]
+}
+```
+
+- `errors` is the authoritative type-error count; `diagnostics` carries each one
+  (`{file, line, col, code, message}`), capped by `--max-diagnostics`, with
+  `diagnosticsTruncated` saying when the cap dropped some, so nothing is hidden silently.
+- `implicitAny: "deferred"` means the rule is off in phase 1 (non-breaking adoption),
+  reported honestly instead of a misleading `0`. To find out what it is hiding, see
+  [Measuring a deferred rule](#measuring-a-deferred-rule).
+- `flavour` is the stack (`node` here). The key kept its old name on purpose: `preset`
+  already means the preset PATH in this shape, and the migration status page reads
+  `flavour`.
+
+## Troubleshooting
+
+| Symptom                                                             | Cause and fix                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `target(s) not available yet: --test`                               | only wired types run; `--help` lists what is available now vs planned                                                                                                                                                                                        |
+| `preset is ambiguous, detected "react" ... also found sails`        | a mixed stack; pass `--preset` to be explicit                                                                                                                                                                                                                |
+| `sentinel requires Node >= 20.12`                                   | run sentinel with a modern Node via `fnm`/`nvm`; the project's own Node is untouched                                                                                                                                                                         |
+| fresh version will not install (`minimumReleaseAge`)                | `--init` allow-lists sentinel automatically when the root uses the gate; if you adopted by hand, add the package to `minimumReleaseAgeExclude` (or `--config.minimumReleaseAge=0`) until it ages                                                             |
+| a translation-singleton test goes red after adopting a front module | `--init` handles this automatically when the root runs more than one TypeScript: adopting re-resolves pnpm and can duplicate a package with an optional, type-only `typescript` peer (e.g. i18next); `--init` pins that peer so it collapses to one instance |
+
+## Phase 1 is non-breaking
+
+Adoption is a lateral move: `noImplicitAny` / `noUnusedLocals` / `noUnusedParameters` are deferred (a warning says so; `--inspect` lists them). Enabling them centrally in a later wave is the migration.
+
+## What `--init` strips, and what it leaves alone
+
+Your tsconfig ends up extending **two** things: your workspace base, then the sentinel preset. That is what decides which of your `compilerOptions` survive.
+
+| Your option                                                                   | What happens           | Why                                                           |
+| ----------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------- |
+| the preset sets it (`strict`, `jsx`, `module`, …)                             | **stripped**           | the preset's value governs, which is the point of adopting it |
+| on the allowlist (`paths`, `baseUrl`, `rootDir`, `outDir`, `tsBuildInfoFile`) | kept, silently         | genuinely project-specific, no preset can know them           |
+| the preset does **not** set it                                                | **kept, and reported** | see below                                                     |
+
+That last row exists because of a real breakage. `libs/nest/swagger-typescript-types` had:
+
+```jsonc
+{ "extends": "../../../tsconfig.base.json", "compilerOptions": { "verbatimModuleSyntax": false } } // deliberately opting OUT
+```
+
+The workspace base sets `verbatimModuleSyntax: true`; the sentinel preset does not set it at all. Removing that line therefore did not hand the decision to the preset, it handed it back to the base: the option switched on and nine files stopped compiling, while `--init` reported success. Across the Hublo monorepo, **205 tsconfigs** set an option this way, mostly `importHelpers: false`.
+
+So an option the preset has no opinion on is **yours**, not drift. `--init` keeps it and says so:
+
+```
+KEPT this module's own compilerOptions (verbatimModuleSyntax): the preset does not set them,
+so they are yours rather than drift. Removing them would not hand the decision to the preset,
+it would hand it to the workspace tsconfig this module extends
+```
+
+It is not reported as drift by `--inspect` either, so a module that legitimately overrides the base does not read as non-conformant forever.