@hublo/sentinel 1.4.0-alpha.9 → 1.4.0

package/docs/test-adoption.md

@@ -10,6 +10,7 @@ that decided a design choice say which choice.
 - [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 two DOM matchers, which a react module gets without asking](#the-two-dom-matchers-which-a-react-module-gets-without-asking)
 - [The check that decides whether you are done](#the-check-that-decides-whether-you-are-done)
 
 ## What the ground actually looks like
@@ -131,19 +132,294 @@ import SIDE EFFECT, a decorator writing into a catalog when its module loads, so
 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 two DOM matchers, which a react module gets without asking
+
+Adopting the test role on a **react** module also registers two matchers. Nothing changes until a
+test calls one: registering a matcher does not make anything fail.
+
+```ts
+const { container } = render(<SaveButton />)
+
+await expect(container).toBeAccessible()   // axe-core
+await expect(container).toBeValidHtml()    // html-validate
+```
+
+A **nest** module gets neither, because there is no DOM to assert on.
+
+⚠️ The generated config imports these by their package subpath, so they only resolve once
+`pnpm install` has run. Skip that step and Vitest reports `Cannot find module
+'<module>/@hublo/sentinel/test/setup/a11y'`, which names a path inside your module and reads like
+a missing file rather than a missing install.
+
+### What they found on the first module that ran them
+
+`libs/front/components`, the design system, on the first run after migrating. The `Checkbox` given
+a `label` had no accessible name at all, and both engines said so independently:
+
+| engine          | message                                                     |
+| --------------- | ----------------------------------------------------------- |
+| `axe-core`      | `aria-prohibited-attr`: aria-label cannot be used on a span |
+| `axe-core`      | `label`: form elements must have labels                     |
+| `html-validate` | `aria-label-misuse`                                         |
+| `html-validate` | `input-missing-label`                                       |
+
+One line caused it: `aria-label` was passed to the component, so MUI put it on the root `<span>`
+rather than on the `<input>`. What makes it worth repeating here is why nothing had caught it. The
+component is used across an app of several hundred screens, its tests were green, and
+`getByLabelText` FOUND it: the query returned the wrapper span, so a test could locate the
+checkbox, click it, and never notice it was announced with no name. The name was invisible to
+everything except a screen reader and these two engines.
+
+### What `toBeAccessible()` does and does not say
+
+It runs axe on what you hand it and fails on any violation, naming the rule, the elements and the
+page that explains the fix.
+
+⚠️ It never fails on a check axe calls INCOMPLETE. Under jsdom those are undecidable by
+construction, colour contrast against a computed background being the usual one, and failing on
+them teaches everyone to switch the matcher off. So a pass means _no violation axe could decide
+here_, never _this is accessible_, and the message says so with the count.
+
+Two refusals worth recognising:
+
+| What it says                           | What to do                                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `needs the "jsdom" environment`        | axe does not support happy-dom; set `environment: 'jsdom'`, or `// @vitest-environment jsdom` for one file |
+| `needs a node that is IN the document` | axe analyses the page, so a detached node has nothing to analyse; pass `container`, not `asFragment()`     |
+
+### What `toBeValidHtml()` does
+
+It puts your markup inside a minimal valid page and validates the page. A component renders a
+fragment, and a fragment has no doctype, no `lang`, no `<title>`; switching those rules off would
+lose exactly the rules that catch what a component breaks inside a real page. Measured, the
+wrapper buys `heading-level`, a skipped heading rank no fragment-level check can see, and costs no
+false positive. A subject that already IS a document is left alone.
+
+The engine is an implementation detail on purpose. The matcher is the contract, so `html-validate`
+can be replaced by the W3C's own `vnu` the day this repo's CI carries a Java runtime, without
+touching a single test.
+
+### The cost, since it is on by default
+
+Both engines load on FIRST USE. Imported eagerly they cost 103ms per test FILE under Vitest's
+isolation, which on `host-admin` and its 1460 files would add 150 seconds to every run for a
+matcher almost no file calls. Lazily, a suite that never asserts on either pays 0.5ms.
+
+## After the migration: the four things you will actually hit
+
+None of these is a defect, and the tool names each one in its own output. They are listed here
+because they arrive after the rewrite, when the diff already looks finished, and each one costs an
+hour the first time.
+
+### 1. `import/order`, which no formatter fixes
+
+The migration formats what it writes with your module's own formatter, and a formatter does not
+ORDER imports. So a module whose lint enforces `import/order` comes out lint-red on lines the
+migration touched, and only those.
+
+Measured: 95 errors on `institution`, 298 across the three `cloud` modules, every one that rule and
+every one cleared by the module's own fixer.
+
+```bash
+pnpm exec eslint <module> -c <module>/eslint.config.js --fix   # or: nx run <module>:lint --fix
+```
+
+Run it, then re-run the suite. Nothing else is expected to change.
+
+### 2. Your config files are named `vitest.*` now
+
+An ignore written by NAME no longer covers them. This repo's root eslint config ignores
+`**/jest.*.{ts,js,cjs,mjs}`, so `jest.config.ts` and `jest.setup.js` were never linted; their
+replacements are and, across the front family, that is 136 files seen by the linter for the first
+time. Nothing there is wrong, but it is a batch of findings that arrives with a migration that did
+not cause them.
+
+The same is true of the secret scanner. A `vitest.config.*` is a NEW file carrying the env values
+`jest.config.*` already had, so `gitleaks` sees them for the first time and refuses the commit:
+
+```
+Finding:  HERMES_API_KEY: 'HERMESKEY'
+File:     libs/cloud/events-notifications/vitest.config.mts:24
+```
+
+The values are not new, only the file is. This repo's `.gitleaks.toml` now exempts a test runner's
+config, which its `.test.`/`.spec.` siblings already were.
+
+### 3. `legacyFakeTimers` is REMOVED, not translated
+
+`useFakeTimers({ legacyFakeTimers: true })` selects jest's pre-27 clock. Vitest installs sinon's and
+has nothing else, so no spelling keeps it. The option is dropped and the run SAYS so, because a
+choice that loses something is no longer a transposition. The call then uses the modern clock, which
+is what jest itself defaults to. Re-read any test that depended on the old one.
+
+### 4. The typecheck, and the modules where nothing declares one
+
+`--run --test` passing says nothing about types, and the migration rewrites types as well as calls.
+Run your module's `typecheck`.
+
+⚠️ And if your module declares none, run `tsc -b <module>/tsconfig.json` by hand at least once. Two
+of the three `cloud` modules declare `test` and `lint` and no typecheck target, and the repo's
+commit hook was the only thing that caught 21 type errors between them. Both were defects in this
+package, both are fixed, and neither would have been visible to a declared target or to CI.
+
+## What the package ships so your untouched helpers keep compiling
+
+A migration rewrites the module's test files and deliberately leaves shared helpers alone, including
+helpers in OTHER projects that your specs import. Two declarations, named in `tsconfig.spec.json`,
+keep those compiling:
+
+|                          | what it answers                                                                                      |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `declare const jest`     | `jest.fn()` at module scope in a helper, because the setup puts `vi` on `globalThis` under that name |
+| `declare namespace jest` | `jest.Mock` and its seven siblings in TYPE position, which a const cannot answer                     |
+
+The namespace keeps JEST's generic order on `Mock` and `SpyInstance`, where jest's first generic is
+the return type and Vitest's is the whole signature. It serves files still written for jest, so it
+has to read jest's spelling.
+
+## One rewrite worth recognising in the diff
+
+    const provider = require('../providers/x')
+    const provider = (await import('../providers/x')) as unknown as Record<string, Mock>
+
+`require()` returns `any`, so `provider.getThing.mockResolvedValue({ id: 1 })` compiled. A dynamic
+import returns the module's real namespace, where that method does not exist, and typing the binding
+as `Mocked<typeof import(...)>` is worse: it demands the real return type and turns 20 errors into
+21, because those fixtures were always partial and `any` was hiding it.
+
+`Record<string, Mock>` describes what the factory on the line above actually built. It gives up the
+member NAMES, which `any` gave up too. Applied only when the SAME file mocks that specifier.
+
+## Going faster than jest ever was, if your module can
+
+Vitest gives every test file its own module registry and its own environment, so nothing one file
+does can reach the next. That is what makes a run expensive: the whole import graph is re-evaluated
+once per file. Measured on `libs/front/components`, 230 files and 1418 tests, same machine and
+session:
+
+|                                    | wall       |
+| ---------------------------------- | ---------- |
+| jest, files in parallel            | 15.9 s     |
+| vitest, isolated (the default)     | 44.6 s     |
+| **vitest, files sharing a worker** | **13.0 s** |
+
+On a real CI agent, same module: jest 158.7 s, isolated vitest 352.5 s, shared worker **92.7 s**.
+
+You ask for it with one line:
+
+```ts
+reactTestConfig({
+  root: import.meta.dirname,
+  workspaceRoot: path.resolve(import.meta.dirname, '../../..'),
+  isolate: false,
+  overrides: { ... },
+})
+```
+
+### What sentinel does so that this is safe
+
+Two things travel with the option, and neither is optional.
+
+**A file boundary.** A setup file is re-executed for every test file even when the registry is
+shared, so `afterAll` in a setup file IS the end of a file. Sentinel puts one there and gives back,
+per file, what isolation used to reset for free: Testing Library's cleanup (it registers itself at
+IMPORT time, so without this it arms for one file and 342 of 1418 tests fail with
+`Found multiple elements`), an empty `document`, every spy, real timers, and the file's own mock
+register.
+
+That last one is worth knowing about. Measured on plain vitest, `vi.resetAllMocks()` DESTROYS a
+mock's implementation while `clearAllMocks` and `restoreAllMocks` keep it. Under jest that could not
+outlive the file. Sharing a worker it reaches every later file, so one `vi.resetAllMocks()` in one
+hook leaves a shared fixture returning `undefined` for the rest of the run. Sentinel scopes those
+three calls back to the file, and never touches what a setup file built.
+
+**A split.** `vi.mock` has to be in place before the module it replaces is imported, and a module
+already evaluated cannot be un-evaluated. So the files that declare a module mock keep their
+isolation, in a second vitest project, and the rest share. The list is read from your sources on
+every run, so adding a test never puts it in the wrong project. On `libs/front/components` that is
+13 files of 230.
+
+### What you may have to change
+
+**One line, if your suite closes msw itself.** `server.close()` disposes the interceptors msw
+installed and leaves a dead registry behind, so the next `listen()` finds it and interception
+silently stops. Its boundary is the worker, not the file. If your setup has
+`afterAll(() => server.close())`, remove it; if you use `@hublo/sentinel/test/setup/msw-lifecycle`,
+this is already handled.
+
+**Anything else `--validate` names.** A mutable singleton at module scope in product code, a test
+writing to `globalThis` without cleaning up: these were forgiven by isolation and are not any more.
+
+### Nest does not get this, and the refusal says why
+
+Measured on `apps/nest/microservices/agency`: 43 s to 40 s, seven percent, where a jsdom module
+goes from 44.6 s to 13 s. A Nest suite's cost is its test bodies; a React suite's is re-evaluating
+its import graph. Against that seven percent, Nest registers its metadata as an import SIDE EFFECT,
+so a shared registry lets one suite see what another registered. The flavour refuses the option
+rather than ignoring it.
+
+### The order is the proof, and `--validate` takes it
+
+Isolation's whole product is that the order of your files cannot change the result. So when your
+config says `isolate: false`, `--validate` runs the suite a SECOND time in a random file order and
+compares that run against the same reference. One call, both claims: nothing was lost, and nothing
+depends on the order.
+
+This is not ceremony. Three runs of an identical configuration once gave three different failure
+lists, because vitest's default sequencer puts previously-failed files first, and each new order
+exposed a different leak. A single green run says very little.
+
+```console
+✗ front-components (main) — this suite shares a worker, and it depends on the ORDER of its files:
+  in a random order (seed 418293) it no longer matches. ... Reproduce with
+  `--sequence.shuffle.files --sequence.seed=418293`. Something a file does outlives it; until that
+  is found, the suite is not safe without isolation.
+```
+
+### Whether it is worth it for your module
+
+Ask how many of your test files declare a module mock, since those keep their isolation:
+
+```console
+$ rg -l 'vi\.mock\(|vi\.doMock\(' src --glob '*.{test,spec}.{ts,tsx}' | wc -l
+```
+
+`libs/front/components` has 13 of 230 and gains 3.4x. `apps/front/host-admin` has 603 of 1463, so
+most of its files would keep isolating and most of the cost would stay.
+
 ## The check that decides whether you are done
 
 Not "the suite is green". **The suite runs the same tests as before**. You do not have to arrange
-that comparison; the two commands do it between them:
+that comparison; `--validate` does it, on either side of the migration:
 
 ```console
-$ sentinel --init --test    # runs jest ONCE first, records every test name, then migrates
-$ pnpm install              # the module's dependencies changed
-$ sentinel --run --test     # runs vitest, compares against that recording, then spends it
+$ sentinel --validate --test   # on the JEST state: records every passing test name
+$ sentinel --init --test       # migrates
+$ pnpm install                 # the module's dependencies changed
+$ sentinel --validate --test   # runs vitest, compares against that recording, then spends it
 ```
 
 A codemod touching thousands of files cannot be reviewed by hand. This comparison is the review.
 
+⚠️ **The first command comes first, and the tool enforces it.** Start with `--init` and the jest
+config is already gone, so there is nothing left to record and nothing to compare against:
+
+```console
+✗ recruitment — already migrated, and no reference was recorded before it was, so there is
+  nothing to compare against. A proof has to be started BEFORE the migration:
+  `sentinel --validate --test` on the jest state, then `--init --test`, then this again.
+```
+
+### Why the proof is its own verb
+
+Because of what SURVIVES a run. `--init` and `--migrate` write state that stays, which is their
+whole purpose and why they are strict about what they touch. `--validate` may instrument the module
+it is proving, provided nothing it writes remains. Those are different contracts, so they are
+different verbs, and the proof can grow without touching a migration that is already proven.
+
+It answers every type, too: `sentinel --validate --lint` is a well-formed command, so it says "not
+available yet" rather than calling your sentence wrong.
+
 ### Why it cannot be one command
 
 The reference only exists BEFORE the migration, and the thing that produces it, the jest config, is
@@ -163,7 +439,7 @@ shorter.
 So the gate refuses a run that lost a name or invented one, and says which:
 
 ```console
-$ sentinel --run --test
+$ sentinel --validate --test
   1 test(s) no longer exist: useHublerNetworkProfilesQuery builds the URL with employment
   statuses only. (reference: jest.config.ts, 2026-09-23T21:10:00.000Z) The reference is KEPT
   until a run passes it, so this does not go green by running again. Fix the suite and re-run,
@@ -198,6 +474,7 @@ have read that improvement as a regression.
 ```console
 $ nx run <module>:typecheck            # BEFORE, and write that down too
 $ sentinel --init --test
+$ pnpm install
 $ nx run <module>:typecheck            # after
 ```
 

package/docs/using-sentinel.md

@@ -29,11 +29,27 @@ everywhere (`--run --json` and `--inspect` answer them), and `--migrate` is refu
 | `--typescript` | writes/extends the tsconfig + `typecheck` script                                                          | typechecks                                                     | resolved options, what is deferred, drift                        |
 | `--build`      | points the module's Vite config at sentinel's toolchain + scripts + nx metadata                           | builds                                                         | runner, config file, whose Vite, how many overrides, adoption    |
 | `--dev`        | adopts the BUILD too: one plan writes both `build` and `serve`                                            | serves; long-running, so never swept by an unqualified `--run` | refuses, and sends you to `--inspect --build`: it is that config |
-| `--test`       | records the jest reference, THEN the Vitest config + scripts + nx metadata, and migrates every spec file  | runs Vitest and compares against that reference                | runner, which configs were found, adoption state, drift          |
+| `--test`       | the Vitest config + scripts + nx metadata, and migrates every spec file                                   | runs Vitest                                                    | runner, which configs were found, adoption state, drift          |
 
 `--json` works for every verb, and stdout carries **only** the envelope, so `| jq` always
 parses. `--dry-run` applies to `--init` and writes nothing.
 
+**`--validate` is a verb of its own**, and the proof of a migration lives there rather than on
+`--init` or `--run`. Run before a migration it records what the module does today; run after, it
+compares by test NAME and refuses a run that lost one or invented one. What separates it from
+`--init` is what SURVIVES the run: `--init` and `--migrate` write state that remains, `--validate`
+may instrument the module it is proving provided nothing it writes stays.
+
+```console
+$ sentinel --validate --test   # on the jest state: records the reference
+$ sentinel --init --test       # migrates
+$ pnpm install
+$ sentinel --validate --test   # compares, then spends the reference
+```
+
+It composes with every type, and answers "not available yet" for the ones with no proof rather
+than calling a valid command wrong.
+
 `--init` is the one verb that targets exactly **one** module. Adopting everything at once
 would be a big-bang; migration is meant to be gradual and per-team.
 

package/docs/validating-a-change.md

@@ -7,6 +7,7 @@ Everything here was learned the expensive way. None of it is theory.
 - [The rule everything follows](#the-rule-everything-follows)
 - [Phase 0: prove the premise](#phase-0-prove-the-premise)
 - [Phase 1: measure the output](#phase-1-measure-the-output)
+- [Measuring a migration, where both sides must be the same program](#measuring-a-migration-where-both-sides-must-be-the-same-program)
 - [Traps that report success](#traps-that-report-success)
 - [What CI does not cover](#what-ci-does-not-cover)
 
@@ -69,6 +70,34 @@ rm -rf apps/front/<x>/.output && nx run <x>:build     # cache hit: same count re
 `console` once restored **0 of 464** files from a green cache hit. Its image runs `pnpm` rather
 than nx, so the one caller that would have failed never used the cache.
 
+## Measuring a migration, where both sides must be the same program
+
+A migration is proved by comparing a suite BEFORE against the same suite AFTER. That comparison is
+only worth something if the two runs differ in the one variable being changed. Three ways they
+silently differed here, each one costing hours of attributing a real-looking red to the wrong
+cause.
+
+**Run the module's OWN installed binary.** Invoking a local build by path (`node
+/path/to/sentinel/dist/bin/sentinel.js`) resolves the runner through SENTINEL's manifest, so the
+suite runs against the sentinel repo's physical install of vitest rather than the monorepo's. Two
+red modules in one campaign were that and nothing else. A campaign runs `npx
+@hublo/sentinel@<version>` or the module's own script, never a path.
+
+**Run from the workspace ROOT.** The adapter relocates vitest to the root with `--root <module>`,
+because a module's config resolves workspace aliases from there. Running the same command from
+inside the module changes what resolves, and the failure looks like the migration's fault.
+
+**Let the module's environment in, deliberately.** nx loads the repo's dotenv files into a task:
+314 environment names under nx against 49 direct. One of them, set in a module's own `.env.local`,
+made a single test fail, and the reference recorded without it reported a name that "disappeared".
+This is the one place where the usual instinct, isolate, is WRONG: the two sides of a comparison
+have to be the same program, so the proof loads the same files the module's own target loads.
+
+**A name can leave both lists without failing.** Vitest reports the tests of a suite whose hook
+threw as `skipped`, where jest counted them FAILED. The count moves, no test is red, and the
+comparison must say "missing because skipped" rather than "lost", or it accuses the migration of
+something the runner did.
+
 ## Traps that report success
 
 | Trap                        | What it looks like              | What closes it                                                             |
@@ -79,9 +108,13 @@ than nx, so the one caller that would have failed never used the cache.
 | A clock reading vs an mtime | passes locally, fails in CI     | stamp from the same filesystem                                             |
 | A stale cache entry         | a hit that restores nothing     | `nx reset`; entries predating a module's `outputs` restore nothing forever |
 | `"$var:generate-x"` in zsh  | a task name that does not exist | brace it: `"${var}:generate-x"` — `:g` is a zsh modifier                   |
+| `rc=$?` after a pipeline    | the status of `tail`, not yours | capture before piping, or `set -o pipefail`                                |
+| `timeout` on macOS          | an empty run read as green      | it does not exist there; the command never ran                             |
+| A local build by path       | a red that is not the module's  | resolves the runner through SENTINEL's install                             |
 
-The last one is the only one that lies toward FAILURE, which makes it visible but sends you
-hunting for causes elsewhere. It produced several "failures" that were only quoting.
+`rc=$?` after a pipeline caught us three times in one day, and once produced a claim we had
+already announced. The zsh one is the only entry that lies toward FAILURE, which makes it visible
+but sends you hunting for causes elsewhere.
 
 ## What CI does not cover
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.4.0-alpha.9",
+  "version": "1.4.0",
   "description": "One CLI that guards code health across Hublo repos: shared lint/typescript/build/test presets, static & dynamic analysis, and architecture checks.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,14 @@
       "types": "./dist/roles/test/setup/jest-parity.d.ts",
       "import": "./dist/roles/test/setup/jest-parity.js"
     },
+    "./test/setup/file-boundary": {
+      "types": "./dist/roles/test/setup/file-boundary.d.ts",
+      "import": "./dist/roles/test/setup/file-boundary.js"
+    },
+    "./test/setup/file-boundary-close": {
+      "types": "./dist/roles/test/setup/file-boundary-close.d.ts",
+      "import": "./dist/roles/test/setup/file-boundary-close.js"
+    },
     "./test/msw": {
       "types": "./dist/roles/test/setup/msw-server.d.ts",
       "import": "./dist/roles/test/setup/msw-server.js"
@@ -66,6 +74,10 @@
       "types": "./dist/roles/test/tools/msw.d.ts",
       "import": "./dist/roles/test/tools/msw.js"
     },
+    "./test/tools/mock-extended": {
+      "types": "./dist/roles/test/setup/mock-extended.d.ts",
+      "import": "./dist/roles/test/setup/mock-extended.js"
+    },
     "./test/setup/msw-lifecycle": {
       "types": "./dist/roles/test/setup/msw-lifecycle.d.ts",
       "import": "./dist/roles/test/setup/msw-lifecycle.js"
@@ -73,10 +85,19 @@
     "./test/setup/workspace": {
       "types": "./dist/roles/test/setup/workspace-entry.d.ts",
       "import": "./dist/roles/test/setup/workspace-entry.js"
+    },
+    "./test/setup/a11y": {
+      "types": "./dist/roles/test/setup/a11y.d.ts",
+      "import": "./dist/roles/test/setup/a11y.js"
+    },
+    "./test/setup/w3c": {
+      "types": "./dist/roles/test/setup/w3c.d.ts",
+      "import": "./dist/roles/test/setup/w3c.js"
     }
   },
   "files": [
     "dist",
+    "types",
     "docs",
     "lint",
     "oxlint",
@@ -87,6 +108,7 @@
     "@tailwindcss/vite": "4.1.18",
     "@vitejs/plugin-react": "6.0.1",
     "@vitest/coverage-v8": "4.1.4",
+    "axe-core": "^4.13.0",
     "commander": "^13.0.0",
     "dotenv-flow": "4.1.0",
     "eslint-plugin-jest-dom": "5.5.0",
@@ -94,6 +116,7 @@
     "eslint-plugin-react-refresh": "0.4.19",
     "eslint-plugin-storybook": "10.3.5",
     "eslint-plugin-styled-components-a11y": "2.2.0",
+    "html-validate": "^11.16.0",
     "jsdom": "^24.1.3",
     "jsonc-parser": "^3.3.1",
     "msw": "1.3.3",
@@ -102,6 +125,7 @@
     "oxfmt": "0.63.0",
     "oxlint": "1.77.0",
     "oxlint-tsgolint": "7.0.2001",
+    "tinyglobby": "0.2.17",
     "typescript": "5.9.3",
     "vite": "8.2.2",
     "vite-plugin-svgr": "5.2.0",

package/types/jest-global.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The type-level half of the `jest` global the setup installs.
+ *
+ * ## What it pairs with
+ *
+ * The migration rewrites SPEC files and deliberately leaves helpers alone, because the setup puts
+ * Vitest's `vi` on `globalThis` under the name `jest`:
+ *
+ *     // setup/jest-global.ts
+ *     ;(globalThis as Record<string, unknown>).jest = vi
+ *
+ * That is what lets a module migrate on its own while a shared helper still calls `jest.fn()`, and
+ * it is why the suite of a migrated module is green with untouched helpers.
+ *
+ * The shim answers the RUNTIME. It says nothing to TypeScript, and the migration also replaces
+ * `"jest"` with `"vitest/globals"` in the module's `tsconfig.spec.json`, so the name stops being a
+ * value at compile time while it still is one at run time.
+ *
+ * Measured on `apps/nest/microservices/institution` with alpha.14, a module whose typecheck was
+ * green before it migrated and whose 2958 tests all pass after:
+ *
+ *     src/app/institution.test-wrapper.ts(83,22)
+ *       error TS2708: Cannot use namespace 'jest' as a value.
+ *     tests/support/institution-prisma.test-wrapper.ts(58,22)
+ *       error TS2708: Cannot use namespace 'jest' as a value.
+ *
+ * Both are helpers, neither is a spec, and both run correctly. This file states, for the type
+ * checker, exactly what the setup states for the runtime.
+ *
+ * ## Why `typeof vi` and not a hand-written subset
+ *
+ * The shim assigns the whole `vi`, so anything narrower would describe something the module does
+ * not run. Writing the truth costs one line and cannot drift.
+ *
+ * ## In a program that still carries `@types/jest`
+ *
+ * No conflict, and this one wins: measured on a fixture holding both, `jest.hoisted(() => 1)`
+ * compiles, and `hoisted` exists only on `vi`. So a module part-way through its migration gets the
+ * type of what actually executes rather than the type of the runner it is leaving.
+ */
+declare const jest: (typeof import('vitest'))['vi']
+
+/**
+ * The same answer for TYPE positions, which the const above does not reach.
+ *
+ * `declare const jest` makes `jest.fn()` compile and says nothing about `jest.Mock`, because a
+ * const has no type members. A helper that annotates with one gets:
+ *
+ *     libs/front/tests/src/mocks/libs/analytics.mock.ts(2,22)
+ *       error TS2694: Namespace 'jest' has no exported member 'Mock'.
+ *
+ * Measured on `libs/front/components`, whose typecheck was green before it migrated: 8 of these,
+ * every one of them in `libs/front/tests`, a project this module reads and does not own. Repo-wide
+ * the whole vocabulary is eight names, and here is each one's Vitest counterpart.
+ *
+ * ⚠️ `Mock` and `SpyInstance` take JEST's generics here, not Vitest's, and the difference is not
+ * cosmetic: jest's first generic is the RETURN type, Vitest's is the whole SIGNATURE. These
+ * declarations serve files that are still written for jest, so they must read jest's spelling;
+ * `codemod/spy-instance-type.ts` is the other half, and it converts the spelling in the files the
+ * migration does rewrite.
+ *
+ * A type-only namespace declares no value, which is why it merges with the const above instead of
+ * colliding with it.
+ *
+ * ## Alongside a program that still carries `@types/jest`
+ *
+ * No collision either, and it was measured rather than assumed: a fixture with
+ * `types: ["jest", "vitest/globals"]` plus this file compiles clean, and the same fixture WITHOUT
+ * this file also compiles, which is what proves `@types/jest` was really loaded. Declaration
+ * merging applies to the namespace the way it already applies to the const, so a module part-way
+ * through its migration is not broken by carrying both.
+ */
+declare namespace jest {
+  type Mock<T = any, Y extends any[] = any[]> = import('vitest').Mock<(...args: Y) => T>
+  type Mocked<T> = import('vitest').Mocked<T>
+  type MockedObject<T> = import('vitest').MockedObject<T>
+  type MockedClass<T extends abstract new (...args: any[]) => any> = import('vitest').MockedClass<T>
+  type MockedFunction<T extends (...args: any[]) => any> = import('vitest').MockedFunction<T>
+  /** jest's own alias for `MockedFunction`. */
+  type MockedFn<T extends (...args: any[]) => any> = import('vitest').MockedFunction<T>
+  type SpyInstance<T = any, Y extends any[] = any[]> = import('vitest').MockInstance<
+    (...args: Y) => T
+  >
+  type SpiedFunction<T extends (...args: any[]) => any> = import('vitest').MockInstance<T>
+}

package/types/mock-extended.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The type-level half of the `jest-mock-extended` alias.
+ *
+ * The generated Vitest config aliases `jest-mock-extended` to the fork sentinel ships, so at RUN
+ * time a migrated module has ONE copy. TypeScript does not read Vite's aliases, so it keeps
+ * resolving the jest package and a migrated spec ends up compiling two worlds at once:
+ *
+ *     the value    typeof mockDeep<Db>()    -> CalledWithMock<…> extends jest.Mock
+ *     the spec     let spy: MockInstance    -> vitest's own type
+ *     TS2322       not assignable
+ *
+ * Measured on `apps/nest/microservices/agency`: one error, on a module whose typecheck was clean
+ * before it migrated. 34 files under `libs/` export a type built this way.
+ *
+ * ## Why it re-exports a SUBPATH of sentinel rather than `vitest-mock-extended`
+ *
+ * Because a bare `vitest-mock-extended` does not resolve from here, which was measured with
+ * `--traceResolution` after the first attempt emptied the module out:
+ *
+ *     Resolving module 'vitest-mock-extended' from '…/agency/node_modules/@hublo/sentinel/types/…'
+ *     Module name 'vitest-mock-extended' was not resolved.
+ *
+ * The module's `tsconfig.spec.json` names this file by PATH, so TypeScript keeps the symlink path
+ * pnpm installed and walks up from there: `…/sentinel/node_modules`, then the module's, then the
+ * workspace's. Sentinel's own dependency sits in the store beside its real directory, and none of
+ * those three is it. A file reached by RESOLUTION is realpathed into the store instead, and its
+ * dependencies are found: same trace, `@hublo/sentinel/test/tools/msw` → `msw` resolved.
+ *
+ * `skipLibCheck` is on in every module here, so the failed `export *` was silent and what surfaced
+ * was an empty module: 18 × `Module '"jest-mock-extended"' has no exported member 'mockDeep'`.
+ *
+ * ## Why THIS subpath
+ *
+ * `@hublo/sentinel/test/tools/mock-extended` is the very module the runtime alias points at, so the
+ * types a spec compiles against are the ones it runs against, down to the lifecycle helpers the
+ * fork adds. Re-exporting `vitest-mock-extended` directly would describe something adjacent to what
+ * executes.
+ *
+ * ## Why it does not couple modules to each other
+ *
+ * An ambient declaration applies to the PROGRAM that includes it, and nothing else. A module that
+ * includes it compiles against the Vitest types; a module still on jest, consuming the very same
+ * shared helper, keeps compiling against the jest ones. Proved on an isolated fixture: both
+ * programs green, over one unmodified shared lib.
+ *
+ * That is the whole point. Héla, 2026-09-24, on tying a module's migration to a library's:
+ * "ça crée des couplages et bloquent les migrations". lint, format and typescript each migrate one
+ * module at a time; this keeps the test role the same.
+ */
+declare module 'jest-mock-extended' {
+  export * from '@hublo/sentinel/test/tools/mock-extended'
+}