@hublo/sentinel 1.3.0 → 1.4.0-alpha.10

package/docs/using-sentinel.md

@@ -0,0 +1,195 @@
+# Using sentinel
+
+The commands, what an adopted module ends up looking like, and how versions move. For
+migrating a module see [`lint-adoption.md`](lint-adoption.md),
+[`format-adoption.md`](format-adoption.md),
+[`typescript-adoption.md`](typescript-adoption.md),
+[`build-adoption.md`](build-adoption.md) and
+[`test-adoption.md`](test-adoption.md), which also carries the reference gate `--test` runs a
+migration against.
+
+## The grid
+
+A command is **verb + target + location**.
+
+```bash
+sentinel --run --lint                      # in a module dir  -> that module
+sentinel --run --lint --module bff-admin   # from the root    -> one module
+sentinel --run --ci                        # from the root    -> affected only
+sentinel --run                             # no target        -> every wired target
+```
+
+Read it by target, since that is what you pick first. `--report` and `--status` are deprecated
+everywhere (`--run --json` and `--inspect` answer them), and `--migrate` is refused everywhere.
+
+| Target         | `--init` writes                                                                                           | `--run` does                                                   | `--inspect` shows                                                |
+| -------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `--lint`       | stub + scripts + nx metadata, removes the ESLint config and the module's ESLint deps, then autofixes once | lints; `--fix` autofixes in the same pass                      | rule count, what is disabled or downgraded and **why**, drift    |
+| `--format`     | materializes the preset + scripts + nx metadata, removes the Prettier config and deps, then formats once  | **checks**; `--fix` writes                                     | effective options, every departure from the standard and why     |
+| `--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          |
+
+`--json` works for every verb, and stdout carries **only** the envelope, so `| jq` always
+parses. `--dry-run` applies to `--init` and writes nothing.
+
+`--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.
+
+## When a role has nothing to do here
+
+Adoption is per role, not per module, and a role declines when **its own tool** has nothing to
+read. Run in `apps/front/maintenance`, which is a static `index.html`, a stylesheet and an SVG:
+
+```console
+$ sentinel --init
+  lint: no file oxlint can read (looked for .js, .mjs, .cjs, .jsx, .ts, ...), so there is
+        nothing to lint here. Other roles may still apply: the formatter reads markdown,
+        YAML, HTML and CSS too.
+  typescript: no TypeScript here (looked for .ts, .mts, .cts, .tsx), so there is nothing
+        for tsc to check.
+  wrote .oxfmtrc.json
+  ...
+```
+
+Two roles decline, the formatter adopts, and the command **exits 0**. Nothing failed: the
+module simply is what it is. "Not a TypeScript project" would have been the wrong question,
+since oxfmt has real work in exactly that module.
+
+Declining matters for the numbers as much as the tidiness. A lint config written for a module
+with nothing to lint reports as covered on the migration page, forever, while checking an
+empty set.
+
+The check names what it looked for, so you can disagree with it. It searches the whole module
+rather than assuming `src/` (code lives in `lib/`, `scripts/` and at the root here too), stops
+at the first match, and never descends into `node_modules` or build output: 0.1ms on a
+4210-file module, 47ms in the pathological case where nothing matches anywhere.
+
+## Asking the tool your own question
+
+Everything after `--` goes to the underlying tool, on `--run` only, with one target named:
+
+```bash
+sentinel --run --typescript -- --noImplicitAny   # what would this deferred rule cost?
+sentinel --run --lint -- --deny-warnings         # what would zero warnings take?
+sentinel --run --lint --fix -- src/a.ts src/b.ts # only these files (what a commit hook wants)
+```
+
+A trailing argument is a **file** when it exists on disk, and a tool **option** otherwise.
+That is why `-- -D no-console` still works: `no-console` is not a file.
+
+A run carrying your own options says so on stderr and marks itself in the `--json` envelope.
+These options can weaken a check as easily as strengthen it, and `--run` is what CI calls.
+
+## What a fully adopted module looks like
+
+Four files, and none of them holds a rule.
+
+```jsonc
+// .oxlintrc.json — the rules come from the preset; the ignores must be here, because oxlint
+// does not inherit them through `extends`
+{
+  "extends": ["./node_modules/@hublo/sentinel/oxlint/react.json"],
+  "ignorePatterns": ["**/dist/**", "**/node_modules/**", "..."],
+}
+```
+
+```jsonc
+// .oxfmtrc.json — MATERIALIZED, because oxfmt has no `extends` and ignores the key silently.
+// `$sentinel.local` names the options this module deliberately owns; a re-init keeps exactly
+// those and refreshes the rest.
+{
+  "$sentinel": { "preset": "base", "version": "1.1.0", "local": ["printWidth"] },
+  "printWidth": 100,
+  "semi": false,
+}
+```
+
+```jsonc
+// tsconfig.json — composes the repo base with the sentinel preset
+{
+  "extends": ["../../tsconfig.base.json", "@hublo/sentinel/tsconfig/react"],
+  "include": ["src"],
+}
+```
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    // `lint` checks BOTH, the way `prettier --check . && eslint .` used to. In the :fix pair
+    // the formatter runs LAST, because the linter's autofix rewrites code.
+    "lint": "sentinel --run --lint && sentinel --run --format",
+    "lint:fix": "sentinel --run --lint --fix && sentinel --run --format --fix",
+    "format": "sentinel --run --format",
+    "format:fix": "sentinel --run --format --fix",
+    "typecheck": "sentinel --run --typescript",
+    // `--` so the runner can still be asked your own question: `pnpm test -- --coverage`
+    "test": "sentinel --run --test --",
+  },
+  "devDependencies": { "@hublo/sentinel": "1.1.0" },
+}
+```
+
+The `nx` block carries what only nx needs: which inputs invalidate the cache. **Not the
+command.** `pnpm run lint` has to work whatever orchestrates the module, so nx must not be the
+only thing that knows how to check it; nx infers the target from the script, which it does
+even when the module also has a `project.json`.
+
+```jsonc
+// package.json, continued
+"nx": {
+  "targets": {
+    "lint": { "cache": true, "inputs": ["default", "{projectRoot}/.oxlintrc.json"] },
+    "format": { "cache": true, "inputs": ["default", "{projectRoot}/.oxfmtrc.json"] },
+    // the writer is never cached: a cache hit would change nothing and leave the files
+    // unformatted while nx reports success
+    "format:fix": { "cache": false },
+    // `outputs` is CARRIED from the target being replaced, never invented: without one, a
+    // cache hit restores nothing and the coverage directory is silently empty, so a target
+    // that declares none is left uncached on purpose
+    "test": {
+      "cache": true,
+      "inputs": ["default", "^default", "{projectRoot}/vitest.config.mts"],
+      "outputs": ["{workspaceRoot}/coverage/libs/front/api"],
+    },
+  },
+}
+```
+
+And **`--init` removes that role's target from `project.json`**, leaving every other target
+alone. Each adoption decouples one more thing from nx: the command moves to the script, the
+caching moves to the manifest, and `project.json` shrinks. Declaring the inputs is not
+tidiness, it is the point: without them the inferred target inherits `targetDefaults`, and in
+this repo the lint default pins the cache to the ROOT eslint config, a file an adopted module
+no longer uses.
+
+And one line, added by adoption, in the workspace root's `.prettierignore`, so the root
+formatter stops competing for a module that now formats itself.
+
+## Versions, and moving between them
+
+An adopting module pins an exact version:
+
+```json
+"devDependencies": { "@hublo/sentinel": "1.1.0-alpha.5" }
+```
+
+That pin is what makes a preset change **reviewable**: it lands in one module's PR, run by
+that module's team, rather than arriving everywhere at once on an unrelated install.
+
+How a change reaches modules depends on the role, and the difference is not cosmetic:
+
+- **lint and typescript** commit a stub that `extends` a file inside the package, so a preset
+  change arrives with the new version: bump, install, done.
+- **format** materializes the values, because oxfmt has no `extends`. A preset change reaches
+  nobody until someone re-runs `sentinel --init --format` in that module.
+
+`sentinel --inspect --format` from the root reports which modules are behind, so the gap is
+visible. Closing it in one action is [issue #17](https://github.com/hublo/sentinel/issues/17);
+today it is one command per module.
+
+**Upgrading:** bump the pin, `pnpm install`, then `sentinel --init` in the module and commit
+what changes. `--init` is idempotent, so on a version that changed nothing relevant it reports
+nothing to change.

package/docs/validating-a-change.md

@@ -0,0 +1,101 @@
+# Validating a change
+
+How a change to sentinel is proven before it ships, and the traps that made each step necessary.
+
+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)
+- [Traps that report success](#traps-that-report-success)
+- [What CI does not cover](#what-ci-does-not-cover)
+
+## The rule everything follows
+
+> A check must not be satisfiable by **doing nothing**.
+
+Ask what your check would report if the step it verifies never ran. If the answer is "success",
+the check is decoration.
+
+This is not abstract. A test asserting `plan().operations` is empty passed for a week on a code
+path that returned early and wrote nothing, while the thing it was supposed to guarantee (that
+re-running changes nothing on disk) was broken in the other direction.
+
+## Phase 0: prove the premise
+
+**Before** any expensive measurement, prove you are measuring the right thing. A perfect method
+pointed at the wrong object gives a perfectly wrong answer, and nothing in the result says so.
+
+For the build role that is one command:
+
+```bash
+sentinel --inspect --build      # conformant, or the drift named
+```
+
+It reports the seven things a half-adoption is missing. Every one of them shipped at least once.
+
+The cost of skipping this: a sweep once reported "36 of 36 contracts identical" on a branch where
+34 of the services still built with **webpack**. The method was sound. The premise was not, and the
+only reason it surfaced was an unrelated error message mentioning webpack.
+
+## Phase 1: measure the output
+
+For a Nest service, the acceptance test is its committed OpenAPI contract:
+
+```bash
+echo '{"corrompu":true}' > libs/api-types/service-<x>/src/service-<x>.swagger.json
+NX_CACHE_DIRECTORY=$(mktemp -d) nx run <x>:generate-swagger-file --skip-nx-cache
+git diff --exit-code -- libs/api-types/service-<x>/
+```
+
+Three things in there are load-bearing:
+
+- **overwrite the contract first.** An untouched file is byte-identical to the committed one, so
+  without this "identical" can mean "nothing ran".
+- **an empty `NX_CACHE_DIRECTORY`** kills the local cache.
+- **`--skip-nx-cache`** disconnects the remote one.
+
+Neither cache flag alone is enough, and neither name says what it does: `--skip-nx-cache` only
+disconnects Nx Cloud, and `--no-cache` only stops **writing**. Measured: with either alone, nx
+restored a cached contract over the corrupted file and reported success without building.
+
+For a front app the equivalent is the output count:
+
+```bash
+rm -rf apps/front/<x>/.output && nx run <x>:build     # note the file count
+rm -rf apps/front/<x>/.output && nx run <x>:build     # cache hit: same count restored?
+```
+
+`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.
+
+## Traps that report success
+
+| Trap                        | What it looks like              | What closes it                                                             |
+| --------------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| An untouched file           | "identical", forever            | overwrite it with garbage first                                            |
+| `--skip-nx-cache`           | a cold run                      | it only disconnects Nx Cloud                                               |
+| `--no-cache`                | a cold run                      | it only stops **writing** to 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                   |
+
+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.
+
+## What CI does not cover
+
+**The build only runs at deploy time.** Neither PR CI nor a local `nx build` exercises the image,
+so a regression there is invisible until a deploy. Two of five defects on one release were only
+visible on env4, which is why env4 is in the definition of done.
+
+**Prisma clients** need `pnpm prisma:gen:*` before a local Nest build, or resolution fails on a
+package that looks missing.
+
+**Front configs are executed**, so their environment variables must exist wherever you build:
+`host-admin` and `career` stop on a missing `VITE_BRAND_ID` before a single file is bundled.
+
+**Fixtures are not modules.** Every fixture in this repo writes a `package.json`, because that is
+what a module looks like once you have thought about it. Measured on the real monorepo: 22 of 37
+Nest services have none at all. A change that looked complete against 64 test files refused the
+majority of the migration, and only a sweep over every real module found it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.3.0",
+  "version": "1.4.0-alpha.10",
   "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",
@@ -49,26 +49,54 @@
     "./test/react": {
       "types": "./dist/roles/test/react/toolchain.d.ts",
       "import": "./dist/roles/test/react/toolchain.js"
+    },
+    "./test/nest": {
+      "types": "./dist/roles/test/nest/toolchain.d.ts",
+      "import": "./dist/roles/test/nest/toolchain.js"
+    },
+    "./test/setup/jest-parity": {
+      "types": "./dist/roles/test/setup/jest-parity.d.ts",
+      "import": "./dist/roles/test/setup/jest-parity.js"
+    },
+    "./test/msw": {
+      "types": "./dist/roles/test/setup/msw-server.d.ts",
+      "import": "./dist/roles/test/setup/msw-server.js"
+    },
+    "./test/tools/msw": {
+      "types": "./dist/roles/test/tools/msw.d.ts",
+      "import": "./dist/roles/test/tools/msw.js"
+    },
+    "./test/setup/msw-lifecycle": {
+      "types": "./dist/roles/test/setup/msw-lifecycle.d.ts",
+      "import": "./dist/roles/test/setup/msw-lifecycle.js"
+    },
+    "./test/setup/workspace": {
+      "types": "./dist/roles/test/setup/workspace-entry.d.ts",
+      "import": "./dist/roles/test/setup/workspace-entry.js"
     }
   },
   "files": [
     "dist",
+    "docs",
     "lint",
     "oxlint",
-    "plugins",
-    "!dist/**/*.map"
+    "plugins"
   ],
   "dependencies": {
     "@nx/eslint-plugin": "23.0.1",
     "@tailwindcss/vite": "4.1.18",
     "@vitejs/plugin-react": "6.0.1",
+    "@vitest/coverage-v8": "4.1.4",
     "commander": "^13.0.0",
+    "dotenv-flow": "4.1.0",
     "eslint-plugin-jest-dom": "5.5.0",
     "eslint-plugin-no-barrel-files": "1.2.1",
     "eslint-plugin-react-refresh": "0.4.19",
     "eslint-plugin-storybook": "10.3.5",
     "eslint-plugin-styled-components-a11y": "2.2.0",
+    "jsdom": "^24.1.3",
     "jsonc-parser": "^3.3.1",
+    "msw": "1.3.3",
     "nitro": "3.0.260415-beta",
     "oxc-parser": "0.147.0",
     "oxfmt": "0.63.0",
@@ -77,7 +105,8 @@
     "typescript": "5.9.3",
     "vite": "8.2.2",
     "vite-plugin-svgr": "5.2.0",
-    "vitest": "4.1.4"
+    "vitest": "4.1.4",
+    "vitest-mock-extended": "5.1.1"
   },
   "devDependencies": {
     "@hublo/sentinel": "link:.",
@@ -110,10 +139,10 @@
     "nx": ">= 21"
   },
   "peerDependenciesMeta": {
-    "nx": {
+    "@nx/js": {
       "optional": true
     },
-    "@nx/js": {
+    "nx": {
       "optional": true
     }
   },