@hublo/sentinel 1.4.0-alpha.9 → 1.4.1

package/README.md

@@ -24,6 +24,7 @@ A large monorepo accumulates:
 - **One source of truth for config** — every project just `extends @hublo/sentinel/...`; the actual rules live in one versioned place. Change a rule once, everyone gets it on the next version bump.
 - **One source of truth for tooling dependencies** — a project depends on `@hublo/sentinel`, not on a scattered pile of eslint / vitest / plugin devDeps. Bump one version and the whole toolchain moves, atomically, tested in isolation first.
 - **`--init` sets a module up** — the one command generates the stubs the first time (**adopt**), regenerates them after a change like a runner swap (**refresh**), and applies the workspace prep the module needs. Run it module by module to roll out gradually. (`--migrate`, for changing an already-initialized setup, is a reserved future verb.)
+- **`--validate` proves the move did not change anything** — a verb of its own, because 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. Run before a migration it records what the module does today; run after, it compares and refuses a run that lost a test or invented one. It composes with every type, and answers "not available yet" for the ones without a proof rather than calling a valid command wrong.
 - **Move one module at a time** — installed per module, so you adopt at your pace; a module can adopt sentinel while its neighbour keeps the old setup. No big-bang.
 - **Swap tools without touching projects** — change eslint → biome (or benchmark them) in one place; `--init` regenerates the stubs.
 - **No silent drift** — the guard keeps every project's config converged on the source of truth.

package/dist/bin/sentinel.js

@@ -14,118 +14,33 @@ import {
   dispatch,
   palette,
   registerAdapters,
-  resolve,
-  resolveBin
-} from "../chunk-L7WS36XV.js";
+  resolve
+} from "../chunk-GRK2KRFI.js";
+import {
+  resolveContext
+} from "../chunk-DYJ6J43A.js";
+import "../chunk-O7REVMOC.js";
+import "../chunk-QXFCZON7.js";
 import {
-  WORKSPACE_ROOT_MARKER,
   ensureWorkspacePrep,
   findWorkspaceRoot,
   inspectWorkspacePrep,
-  moduleName,
   readOwnVersion,
   readProjectPackageJson
-} from "../chunk-WLFE5RUU.js";
+} from "../chunk-KMKQDGI6.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
 
-// src/core/context.ts
-import { existsSync } from "fs";
-import { join as join2 } from "path";
-
-// src/core/discover-modules.ts
-import { execFileSync } from "child_process";
-import { mkdtempSync, readFileSync, rmSync } from "fs";
-import { tmpdir } from "os";
-import { join } from "path";
-function runNx(cwd2, args) {
-  const nx = resolveBin(cwd2, "nx") ?? "nx";
-  try {
-    return execFileSync(nx, args, {
-      cwd: cwd2,
-      encoding: "utf8",
-      env: { ...process.env, NX_DAEMON: "false" }
-    });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `sentinel: could not run nx (${message}). Is nx installed in this workspace, and are you at its root?`,
-      { cause: error }
-    );
-  }
-}
-function readGraph(cwd2) {
-  const dir = mkdtempSync(join(tmpdir(), "sentinel-nx-"));
-  const file = join(dir, "graph.json");
-  try {
-    runNx(cwd2, ["graph", "--file", file]);
-    const parsed = JSON.parse(readFileSync(file, "utf8"));
-    const nodes = parsed.graph?.nodes;
-    if (!nodes || typeof nodes !== "object") {
-      throw new Error(
-        "sentinel: unexpected nx graph output (no graph.nodes); the installed nx version may be incompatible."
-      );
-    }
-    return Object.entries(nodes).map(([name, node]) => ({
-      name,
-      root: join(cwd2, node.data.root)
-    }));
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-function discoverModules(cwd2, options = {}) {
-  const modules = readGraph(cwd2);
-  if (!options.affected) return modules;
-  const affected = new Set(
-    JSON.parse(runNx(cwd2, ["show", "projects", "--affected", "--json"]))
-  );
-  return modules.filter((module) => affected.has(module.name));
-}
-
-// src/core/context.ts
-var MODULE_MARKERS = ["package.json", "project.json"];
-function isModuleDir(cwd2) {
-  return MODULE_MARKERS.some((marker) => existsSync(join2(cwd2, marker)));
-}
-function resolveContext(cwd2, opts2) {
-  const atRoot = existsSync(join2(cwd2, WORKSPACE_ROOT_MARKER));
-  if (!atRoot && isModuleDir(cwd2)) {
-    if (opts2.module) {
-      throw new Error(
-        "You are in a module directory: drop --module (the context is the current module)."
-      );
-    }
-    if (opts2.ci) {
-      throw new Error("--ci selects the affected set from the workspace root; run it there.");
-    }
-    const name = moduleName(cwd2);
-    return { modules: [{ name, root: cwd2 }], scope: "cwd-module" };
-  }
-  if (atRoot) {
-    if (opts2.module) {
-      const found = discoverModules(cwd2).find((module) => module.name === opts2.module);
-      if (!found) throw new Error(`module "${opts2.module}" not found in the workspace.`);
-      return { modules: [found], scope: "named-module" };
-    }
-    if (opts2.ci) return { modules: discoverModules(cwd2, { affected: true }), scope: "affected" };
-    return { modules: discoverModules(cwd2), scope: "all" };
-  }
-  throw new Error(
-    `Run sentinel from a module directory or the workspace root (found neither ${MODULE_MARKERS.join("/")} nor ${WORKSPACE_ROOT_MARKER} here).`
-  );
-}
-
 // src/roles/build/declined.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 var DEPRECATED_NX_BUILDER = "@nx/webpack:webpack";
 function buildsWithDeprecatedExecutor(cwd2) {
-  const projectJson = join3(cwd2, "project.json");
-  if (!existsSync2(projectJson)) return false;
+  const projectJson = join(cwd2, "project.json");
+  if (!existsSync(projectJson)) return false;
   try {
-    const project = JSON.parse(readFileSync2(projectJson, "utf8"));
+    const project = JSON.parse(readFileSync(projectJson, "utf8"));
     return project.targets?.build?.executor === DEPRECATED_NX_BUILDER;
   } catch {
     return false;
@@ -218,6 +133,32 @@ sentinel (${type}): ${asMessage(error)}
   return worst;
 }
 
+// src/cli/run-validate.ts
+async function runValidate(ctx) {
+  const { modules } = resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci });
+  const unsupported = ctx.targets.filter((target) => target !== "test");
+  if (unsupported.length > 0) {
+    const named = unsupported.map((target) => `--${target}`).join(", ");
+    process.stdout.write(
+      `  \xB7 ${named}: not available yet. \`--validate\` answers \`--test\` today, by recording a suite before a migration and comparing it after. Nothing was checked for ${named}.
+`
+    );
+  }
+  if (!ctx.targets.includes("test")) return 1;
+  const { validateModuleTests } = await import("../validate-57H7GK5B.js");
+  const outcomes = modules.flatMap(
+    (module) => validateModuleTests(module.name, module.root)
+  );
+  for (const outcome of outcomes) {
+    const suite = outcome.suite === "main" ? "" : ` [${outcome.suite}]`;
+    process.stdout.write(
+      `  ${outcome.ok ? "\u2713" : "\u2717"} ${outcome.module}${suite} \u2014 ${outcome.message}
+`
+    );
+  }
+  return outcomes.every((outcome) => outcome.ok) ? 0 : 1;
+}
+
 // src/core/orchestrate.ts
 async function analyse(params) {
   const results = [];
@@ -645,13 +586,16 @@ program.name("sentinel").description("One CLI that guards code health: presets,
   "before",
   [
     "A check composes: verb + type + location.",
-    "  verb    what to do:   --run  --inspect  --report  --status  --init  (--migrate: planned)",
+    "  verb    what to do:   --run  --inspect  --report  --status  --init  --validate  (--migrate: planned)",
     "  type    which check:  --lint --typescript ...  (omit = all types; or --all)",
     "  where   run from a MODULE dir \u2192 that module; from the ROOT \u2192 --module <name>,",
     "          --ci (affected), or all modules. --init targets one module only.",
     ""
   ].join("\n")
-).option("--run", "execute the target tool").option("--inspect", "show the resolved configuration").option("--init", "set up a module: write its config stubs + the workspace prep it needs").option("--migrate", "planned: change an already-initialized setup (not available yet)").option("--report", "deprecated: use --run --json").option("--status", "deprecated: use --inspect").option(
+).option("--run", "execute the target tool").option("--inspect", "show the resolved configuration").option("--init", "set up a module: write its config stubs + the workspace prep it needs").option("--migrate", "planned: change an already-initialized setup (not available yet)").option(
+  "--validate",
+  "prove a migration kept the suite: record the reference, then compare against it"
+).option("--report", "deprecated: use --run --json").option("--status", "deprecated: use --inspect").option(
   "--module <name>",
   "from the workspace root: scope to one module (omit = all; inside a module dir, drop this)"
 ).option("--preset <name>", `the stack preset to apply (${PRESET_NAMES.join(", ")})`).option("--flavour <name>", "deprecated: use --preset").option("--runner <tool>", "override the default runner (e.g. eslint, biome)").option("--ci", "CI mode: from the root, only the affected modules; non-zero exit on failure").option("--fix", "auto-fix where applicable").option("--dry-run", "preview the changes without writing (--init)").option("--json", "machine-readable output, for every verb").option(
@@ -783,7 +727,7 @@ async function main() {
     dryRun: Boolean(opts.dryRun),
     fail: (message) => program.error(message)
   };
-  const exitCode = verb === "init" ? await runInit(context) : await runVerb(context);
+  const exitCode = verb === "init" ? await runInit(context) : verb === "validate" ? await runValidate(context) : await runVerb(context);
   await exitWithoutTruncating(exitCode);
 }
 main().catch((error) => {

package/dist/{chunk-7PUVK4YM.js → chunk-5VNYQIFD.js}

@@ -1,13 +1,90 @@
 import {
   decoratorMetadata,
   tsconfigAliases
-} from "./chunk-3TDUIKVQ.js";
+} from "./chunk-SWWQ7X7B.js";
 
 // src/roles/test/shared-test-config.ts
-import { existsSync } from "fs";
-import { createRequire } from "module";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/roles/test/isolation-split.ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globSync } from "tinyglobby";
+var DECLARES_A_MODULE_MOCK = /\b(?:vi|jest)\.(?:mock|doMock)\s*\(/;
+function testFilesUnder(root, include) {
+  return globSync([...include], { cwd: root, ignore: ["**/node_modules/**"] }).map(String).sort();
+}
+function splitByModuleMock(root, files) {
+  const mocked = [];
+  const shared = [];
+  for (const file of files) {
+    const source = readSource(join(root, file));
+    if (source !== void 0 && DECLARES_A_MODULE_MOCK.test(source)) mocked.push(file);
+    else shared.push(file);
+  }
+  return { mocked, shared };
+}
+function asIsolationSplit(config, root) {
+  const include = config.test?.include ?? [];
+  const files = testFilesUnder(root, include);
+  if (files.length === 0) return { ...config, test: { ...config.test, isolate: false } };
+  const { mocked, shared } = splitByModuleMock(root, files);
+  return {
+    ...config,
+    test: {
+      // Kept at the root, where a project cannot answer for the whole run.
+      coverage: config.test?.coverage,
+      projects: [project(config, "shared", shared, false), project(config, "mocked", mocked, true)]
+    }
+  };
+}
+function project(config, name, include, isolate) {
+  return {
+    ...config,
+    test: {
+      ...config.test,
+      name,
+      include,
+      isolate,
+      /*
+       * A project with nothing to run is still cheaper than a conditional here: Vitest starts it,
+       * finds no file and reports none. Leaving both projects in place keeps the shape of the
+       * config the same for every module, which is what makes a generated config reviewable.
+       */
+      coverage: void 0
+    }
+  };
+}
+function readSource(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/roles/test/msw-server-redirect.ts
+var WORKSPACE_MSW_SERVER = /(^|\/)msw\/server\.[cm]?[jt]sx?$/;
+function mswServerRedirect(serverFile, workspaceRoot) {
+  return {
+    name: "sentinel:msw-server-redirect",
+    // Before the resolver settles on the workspace file, since the point is to replace it.
+    enforce: "pre",
+    async resolveId(source, importer, options) {
+      if (source === serverFile) return void 0;
+      const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+      if (resolved === null || resolved.external) return void 0;
+      const id = resolved.id;
+      if (!id.startsWith(workspaceRoot)) return void 0;
+      if (id.includes("/node_modules/")) return void 0;
+      if (!WORKSPACE_MSW_SERVER.test(id)) return void 0;
+      return serverFile;
+    }
+  };
+}
 
 // src/roles/test/react/jest-export-conditions.ts
 var ABSENT_UNDER_JEST = /* @__PURE__ */ new Set(["development", "development|production"]);
@@ -72,8 +149,18 @@ function vitestMockExtendedPath() {
     }
   }
 }
+function mswServerFile() {
+  return siblingFile("./setup/msw-server.js");
+}
+function nextI18nextAlias(root, workspaceRoot) {
+  for (const base of [root, workspaceRoot]) {
+    const esm = join2(base, "node_modules", "next-i18next", "dist", "esm", "index.js");
+    if (existsSync(esm)) return [{ find: /^next-i18next$/, replacement: esm }];
+  }
+  return [];
+}
 function mswAliases() {
-  const server = siblingFile("./setup/msw-server.js");
+  const server = mswServerFile();
   const own = resolveFrom("msw");
   return [
     ...own === void 0 ? [] : [{ find: /^msw$/, replacement: own }],
@@ -82,25 +169,25 @@ function mswAliases() {
 }
 function luxonAlias(root, workspaceRoot) {
   for (const base of [root, workspaceRoot]) {
-    const manifest = join(base, "node_modules", "luxon", "package.json");
+    const manifest = join2(base, "node_modules", "luxon", "package.json");
     if (existsSync(manifest)) return [{ find: /^luxon$/, replacement: dirname(manifest) }];
   }
   return [];
 }
 function axiosAlias(root, workspaceRoot) {
   for (const base of [root, workspaceRoot]) {
-    const manifest = join(base, "node_modules", "axios", "package.json");
+    const manifest = join2(base, "node_modules", "axios", "package.json");
     if (existsSync(manifest)) return [{ find: /^axios$/, replacement: dirname(manifest) }];
   }
   return [];
 }
 function prismaRuntimeAlias(workspaceRoot) {
-  const prisma = join(workspaceRoot, "node_modules", "@prisma");
+  const prisma = join2(workspaceRoot, "node_modules", "@prisma");
   if (!existsSync(prisma)) return [];
   return [
     {
       find: /^@prisma\/([^/]+)\/runtime\/library$/,
-      replacement: join(prisma, "$1", "runtime", "library.js")
+      replacement: join2(prisma, "$1", "runtime", "library.js")
     }
   ];
 }
@@ -158,6 +245,13 @@ function baseConfig(options) {
      */
     plugins: [
       jestExportConditions(),
+      /*
+       * The alias beside it covers a file naming the workspace's msw server by its package
+       * specifier. This covers the one that reaches the same module RELATIVELY, which an alias
+       * cannot: `./server` is a spelling thousands of unrelated files use, so the redirect is
+       * decided on the resolved path instead. See `msw-server-redirect.ts` for the measurement.
+       */
+      ...mswServerFile() === void 0 ? [] : [mswServerRedirect(mswServerFile(), workspaceRoot)],
       ...options.lowerDecoratorsWithTypeScript ? [decoratorMetadata({ root })] : []
     ],
     /*
@@ -192,6 +286,7 @@ function baseConfig(options) {
       alias: [
         ...axiosAlias(root, workspaceRoot),
         ...luxonAlias(root, workspaceRoot),
+        ...nextI18nextAlias(root, workspaceRoot),
         /*
          * Nest only, and measured: 1186 files under `apps/nest` and `libs/nest` mention `@prisma/`,
          * and ZERO under `apps/front` and `libs/front`. A React module paying for an alias to a
@@ -223,6 +318,37 @@ function baseConfig(options) {
       globals: true,
       environment: "node",
       root,
+      /*
+       * The per-test budget, widened from Vitest's 5000 ms default.
+       *
+       * ⚠️ NOT because the migration made anything slower. Measured on the same machine, the same
+       * files, both runners:
+       *
+       *     regulation-balance, first test        jest 2283 ms    vitest 2411 ms
+       *     prisma-breaking-change-detector       jest 2558 ms    vitest 2363 ms
+       *     planning-requirement, first test                      vitest 1972 ms
+       *
+       * Vitest is within 6% on the slowest and FASTER on the others, and faster overall on every
+       * file (regulation-balance: 3.40 s under jest, 2.23 s under vitest). What these tests have
+       * in common is that they pay a one-off cost inside a test: loading a Nest module graph, or
+       * spawning a Prisma CLI process. Against 5000 ms that is a margin of about TWO, and a shared
+       * CI agent running three tasks at once eats it. All three timed out on CI under Vitest; on
+       * that evidence jest was simply on the lucky side of the same line.
+       *
+       * 15000 ms is six times the slowest measured test, so an agent three times slower than this
+       * machine still has a factor of two in hand.
+       *
+       * ⚠️ What it costs, said plainly: a test that HANGS now takes 15 s to fail instead of 5. It
+       * hides nothing else, since a hang still fails. A module that declared its own budget keeps
+       * it, because the module's own config is merged over this one.
+       */
+      testTimeout: 15e3,
+      /*
+       * The same budget for hooks. jest's one `testTimeout` covered both; Vitest splits them and
+       * defaults `hookTimeout` to 10 s, which is how `mission`'s `beforeAll` container start was
+       * cut off at 10012 ms. A hook doing the work a test does needs the budget a test has.
+       */
+      hookTimeout: 15e3,
       /*
        * What the repo's jest preset actually matched, copied rather than approximated:
        * `**\/?(*.)+(spec|test).[jt]s?(x)`.
@@ -281,7 +407,42 @@ function baseConfig(options) {
        * A module that declared its own concurrency overrides this, in both environments, exactly as
        * it does today.
        */
-      fileParallelism: !process.env.CI,
+      /*
+       * ⚠️ PARALLEL on CI too, since 26/09, and that reverses what the note above decided.
+       *
+       * The transposition was faithful and expensive. Measured on `libs/front/components`, 1418
+       * tests green on every line, on the repo's own 4-core agents:
+       *
+       *     jest, as CI runs it            158.7 s
+       *     vitest serial, the transposition   644.5 s     4.1x slower
+       *     vitest, 3 workers                  324.7 s     2.05x slower
+       *
+       * Serialising costs vitest far more than it costs jest, because vitest re-evaluates the
+       * module graph per file through Vite's SSR runner: 555 ms of `import` and 478 ms of
+       * `environment` per file against 139 ms of actual tests. Parallelism does not remove that
+       * cost, it pays it on several cores at once.
+       *
+       * Every other documented lever was measured and does nothing or breaks the suite:
+       * `deps.optimizer.ssr`, `NODE_COMPILE_CACHE` and `fsModuleCache` all cache TRANSFORMATION
+       * where the cost is EVALUATION; `pool: threads` is noise; `vmThreads` collapses into
+       * `no-isolate` when serial and fails 473 tests; `--no-isolate` fails 351.
+       *
+       * ⚠️ And NO worker cap, which is deliberate after reading vitest's own sizing:
+       *
+       *     getDefaultThreadsCount: config.watch ? max(numCpus / 2, 1) : max(numCpus - 1, 1)
+       *
+       * `cores - 1` is 3 on this repo's 4-core agents, which is exactly the pool the 324.7 s above
+       * was measured with, and 9 on a 10-core laptop. Pinning a number would slow every developer
+       * to serve the agent, and a percentage would only re-describe a default that already adapts.
+       * So one variable changes here and the tool keeps sizing its own pool.
+       *
+       * Memory was the reason to hesitate and it was measured rather than assumed: a full jsdom
+       * run holds 1.1 GB at three workers and 1.9 GB at six, on agents with 32 GB. The OOM this
+       * repo suffered was three nx tasks near 7.45 GB each, which is not what a test worker costs.
+       *
+       * A module that declares its own concurrency still overrides this, as before.
+       */
+      fileParallelism: true,
       /*
        * ⚠️ Sentinel's own setup files go through VITE, not round it, and that is load-bearing.
        *
@@ -309,8 +470,25 @@ function baseConfig(options) {
        * The narrow form `/@hublo\/sentinel\/dist\/roles\//` was tried and does NOT work: the pin
        * itself lives in a shared chunk at the dist root, which stays external. It has to be the
        * whole package.
+       *
+       * ## ⚠️ And `vitest` itself, for the same reason one level further out
+       *
+       * Inlining sentinel is not enough: its own `import { expect } from 'vitest'` still leaves
+       * through Node, which loads a SECOND instance of the runner. The snapshot client is
+       * per-instance state, so the instance the test file uses was never set up for that file:
+       *
+       *     Error: The snapshot state for '…/asyncapi.module.spec.ts' is not found.
+       *            Did you call 'SnapshotClient.setup()'?
+       *
+       * Isolated to the smallest possible case: an EMPTY setup file under `node_modules` passes,
+       * and the same file containing nothing but `import { expect } from 'vitest'` fails, while
+       * the identical import from a setup file INSIDE the module passes. So it is the location,
+       * not the import, and the remedy has to reach the import too.
+       *
+       * Measured on `libs/nest/asyncapi`: sentinel alone 1 failed of 13, sentinel and `vitest`
+       * 13 passed, 525 ms against 570 ms. Not a trade.
        */
-      server: { deps: { inline: [/@hublo\/sentinel/] } }
+      server: { deps: { inline: [/@hublo\/sentinel/, "vitest"] } }
     }
   };
 }
@@ -323,6 +501,39 @@ function asAliasArray(alias) {
   }));
 }
 function sharedTestConfig(options) {
+  return withIsolationChoice(mergedConfig(options), options);
+}
+function withIsolationChoice(config, options) {
+  if (options.isolate !== false) return config;
+  if (options.flavour === "nest") {
+    throw new Error(
+      "sentinel test: `isolate: false` is not available for a Nest suite. Nest registers its metadata as an import side effect, so sharing a module registry lets one suite see what another registered. Measured on `agency`, it would save 7% (43s to 40s) where a React module saves 71%, so the trade is not worth making. Remove the option."
+    );
+  }
+  const bracketed = {
+    ...config,
+    test: {
+      ...config.test,
+      /*
+       * The boundary brackets the module's own setup files rather than joining them. The closing
+       * entry has to run after the module's, because what it records as "infrastructure" is
+       * whatever the setup files built, and `setupFiles` order is the only way to say "last".
+       */
+      setupFiles: [
+        "@hublo/sentinel/test/setup/file-boundary",
+        ...asSetupList(config.test?.setupFiles),
+        "@hublo/sentinel/test/setup/file-boundary-close"
+      ]
+    }
+  };
+  return asIsolationSplit(bracketed, options.root);
+}
+function asSetupList(setupFiles) {
+  if (typeof setupFiles === "string") return [setupFiles];
+  if (Array.isArray(setupFiles)) return setupFiles;
+  return [];
+}
+function mergedConfig(options) {
   const base = baseConfig(options);
   if (options.overrides === void 0) return base;
   return {
@@ -394,4 +605,4 @@ export {
   jestExportConditions,
   sharedTestConfig
 };
-//# sourceMappingURL=chunk-7PUVK4YM.js.map
+//# sourceMappingURL=chunk-5VNYQIFD.js.map