@hublo/sentinel 1.4.1 → 1.4.3

package/dist/bin/sentinel.js

@@ -15,10 +15,10 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-GRK2KRFI.js";
+} from "../chunk-DYK6UEMO.js";
 import {
   resolveContext
-} from "../chunk-DYJ6J43A.js";
+} from "../chunk-TDNPPNGK.js";
 import "../chunk-O7REVMOC.js";
 import "../chunk-QXFCZON7.js";
 import {
@@ -145,7 +145,7 @@ async function runValidate(ctx) {
     );
   }
   if (!ctx.targets.includes("test")) return 1;
-  const { validateModuleTests } = await import("../validate-57H7GK5B.js");
+  const { validateModuleTests } = await import("../validate-3QMCX2HW.js");
   const outcomes = modules.flatMap(
     (module) => validateModuleTests(module.name, module.root)
   );

package/dist/{chunk-GRK2KRFI.js → chunk-DYK6UEMO.js}

@@ -53,7 +53,7 @@ import {
   selfCommand,
   splitToolArgs,
   walk
-} from "./chunk-DYJ6J43A.js";
+} from "./chunk-TDNPPNGK.js";
 import {
   parseJsonc
 } from "./chunk-QXFCZON7.js";
@@ -5691,26 +5691,28 @@ function dependencyNames(cwd) {
     return [];
   }
 }
-function declaresJsx(cwd) {
+var REACT_TYPESCRIPT_PRESET = "@hublo/sentinel/typescript/react";
+function reactTsconfigEvidence(cwd) {
   let entries;
   try {
     entries = readdirSync3(cwd).filter(
       (name) => name.startsWith("tsconfig") && name.endsWith(".json")
     );
   } catch {
-    return false;
+    return void 0;
   }
   for (const name of entries) {
     try {
-      const config = parseJsonc(
-        readFileSync17(join19(cwd, name), "utf8"),
-        name
-      );
-      if (config.compilerOptions?.jsx !== void 0) return true;
+      const config = parseJsonc(readFileSync17(join19(cwd, name), "utf8"), name);
+      if (config.compilerOptions?.jsx !== void 0) return 'its tsconfig sets "jsx"';
+      const extended = Array.isArray(config.extends) ? config.extends : config.extends === void 0 ? [] : [config.extends];
+      if (extended.some((entry) => entry === REACT_TYPESCRIPT_PRESET)) {
+        return `its tsconfig extends "${REACT_TYPESCRIPT_PRESET}"`;
+      }
     } catch {
     }
   }
-  return false;
+  return void 0;
 }
 function presetSignals(cwd) {
   const signals = [];
@@ -5719,8 +5721,9 @@ function presetSignals(cwd) {
     const hit = dependencies.find((name) => pattern.test(name));
     if (hit) signals.push({ preset, evidence: `it depends on "${hit}"` });
   }
-  if (declaresJsx(cwd) && !signals.some((signal) => signal.preset === "react")) {
-    signals.push({ preset: "react", evidence: 'its tsconfig sets "jsx"' });
+  const reactTsconfig = reactTsconfigEvidence(cwd);
+  if (reactTsconfig !== void 0 && !signals.some((signal) => signal.preset === "react")) {
+    signals.push({ preset: "react", evidence: reactTsconfig });
   }
   const location = cwd.replaceAll("\\", "/");
   for (const { preset, pattern, evidence } of PATH_SIGNALS) {

package/dist/{chunk-DYJ6J43A.js → chunk-TDNPPNGK.js}

@@ -5572,6 +5572,100 @@ function planJestMigration(context, adoption) {
   return { operations, notes };
 }
 
+// src/roles/test/react/add-matcher-setups.ts
+import { parseSync as parseSync11 } from "oxc-parser";
+var MATCHER_SETUPS = [
+  "@hublo/sentinel/test/setup/a11y",
+  "@hublo/sentinel/test/setup/w3c"
+];
+function findSetupFilesValues(root) {
+  const found = [];
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk2 = (node) => {
+    if (node === null || typeof node !== "object") return;
+    if (seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const child of node) walk2(child);
+      return;
+    }
+    const record = node;
+    if (record.type === "Property") {
+      const key = record.key;
+      const name = key?.type === "Identifier" ? key.name : key?.value;
+      if (name === "setupFiles") found.push(record.value);
+    }
+    for (const value of Object.values(record)) walk2(value);
+  };
+  walk2(root);
+  return found;
+}
+function indentAt(source, offset) {
+  const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
+  return /^\s*/.exec(source.slice(lineStart, offset))?.[0] ?? "";
+}
+function quoteOf(source, value) {
+  const first = value.elements[0];
+  if (first === void 0) return "'";
+  return source.slice(first.start, first.end).startsWith('"') ? '"' : "'";
+}
+function addMatcherSetups(source, fileName) {
+  const { program, errors } = parseSync11(fileName, source, { sourceType: "module" });
+  if (errors.length > 0) {
+    return { kind: "skipped", why: `${fileName} does not parse` };
+  }
+  const values = findSetupFilesValues(program);
+  if (values.length === 0) {
+    return {
+      kind: "skipped",
+      why: `${fileName} declares no \`setupFiles\`, so there is no list to add them to`
+    };
+  }
+  if (values.length > 1) {
+    return {
+      kind: "skipped",
+      why: `${fileName} declares \`setupFiles\` ${values.length} times, so which list owns the matchers is ambiguous`
+    };
+  }
+  const value = values[0];
+  if (value === void 0 || value.type !== "ArrayExpression") {
+    return {
+      kind: "skipped",
+      why: `\`setupFiles\` in ${fileName} is not an array literal, so its entries cannot be read where they are written`
+    };
+  }
+  const declared = new Set(
+    value.elements.filter((element) => element.type === "Literal" && typeof element.value === "string").map((element) => element.value)
+  );
+  const missing = MATCHER_SETUPS.filter((entry) => !declared.has(entry));
+  if (missing.length === 0) {
+    return { kind: "unchanged", why: "this config already registers both matchers" };
+  }
+  const quote = quoteOf(source, value);
+  const first = value.elements[0];
+  const base = indentAt(source, value.start);
+  if (first !== void 0 && source.slice(value.start, first.start).includes("\n")) {
+    const indent = indentAt(source, first.start);
+    const inserted = missing.map((entry) => `${quote}${entry}${quote},
+${indent}`).join("");
+    return {
+      kind: "added",
+      source: source.slice(0, first.start) + inserted + source.slice(first.start),
+      added: missing
+    };
+  }
+  const existing = source.slice(value.start + 1, value.end - 1).split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+  const entries = [...missing.map((entry) => `${quote}${entry}${quote}`), ...existing];
+  const rendered = `[
+${entries.map((entry) => `${base}  ${entry},
+`).join("")}${base}]`;
+  return {
+    kind: "added",
+    source: source.slice(0, value.start) + rendered + source.slice(value.end),
+    added: missing
+  };
+}
+
 // src/roles/test/plan.ts
 function ownedTestDependencies(cwd, declared) {
   return declared.filter((entry) => SENTINEL_OWNED_TEST_PACKAGES.includes(entry.name)).flatMap((entry) => [
@@ -5634,21 +5728,34 @@ function plan(context) {
   }
   const operations = [];
   const notes = [];
-  const rewrite = rewriteToolchainImports(
-    testToolchain(context.preset),
-    readTestConfigSource(context.cwd, configFile),
-    configFile
-  );
+  const configSource = readTestConfigSource(context.cwd, configFile);
+  const rewrite = rewriteToolchainImports(testToolchain(context.preset), configSource, configFile);
   if (rewrite.kind === "blocked") {
     return {
       operations: [],
       skipped: `${configFile} could not be pointed at sentinel, so nothing was written: ${rewrite.why}. Nothing here is broken; this needs a look before the role applies.`
     };
   }
-  if (rewrite.kind === "rewritten") {
+  const base = rewrite.kind === "rewritten" ? rewrite.source : configSource;
+  const matchers = context.preset === "react" ? addMatcherSetups(base, configFile) : { kind: "unchanged", why: "this preset has no DOM matchers" };
+  if (matchers.kind === "added") {
+    operations.push({ kind: "write", path: configFile, contents: matchers.source });
+  } else if (rewrite.kind === "rewritten") {
     operations.push({ kind: "write", path: configFile, contents: rewrite.source });
+  }
+  if (rewrite.kind === "rewritten") {
+    notes.push(
+      `${configFile} now imports ${rewrite.moved.join(", ")} from sentinel. Beyond its import lines, every alias, timeout and coverage path is untouched, so this suite runs what it ran before.`
+    );
+  }
+  if (matchers.kind === "added") {
+    notes.push(
+      `${configFile} now registers ${matchers.added.join(" and ")} in its own \`setupFiles\`, which is what makes \`toBeAccessible()\` and \`toBeValidHtml()\` exist here. They are written where you can read them rather than merged in behind the config, and both engines load on FIRST USE, so a file calling neither pays only the import.`
+    );
+  }
+  if (matchers.kind === "skipped") {
     notes.push(
-      `${configFile} now imports ${rewrite.moved.join(", ")} from sentinel. Only the import lines changed: every alias, setup file, timeout and coverage path is untouched, so this suite runs what it ran before.`
+      `the two DOM matchers were NOT registered: ${matchers.why}. Add ${MATCHER_SETUPS.map((entry) => `\`${entry}\``).join(" and ")} to this module's \`setupFiles\` to get \`toBeAccessible()\` and \`toBeValidHtml()\`.`
     );
   }
   const existing = projectTargets(context.cwd)?.[TEST_SCRIPT_NAME] ?? manifestTargets(context.cwd)[TEST_SCRIPT_NAME];

package/dist/index.js

@@ -6,10 +6,10 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-GRK2KRFI.js";
+} from "./chunk-DYK6UEMO.js";
 import {
   BaseAdapter
-} from "./chunk-DYJ6J43A.js";
+} from "./chunk-TDNPPNGK.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";
 import "./chunk-KMKQDGI6.js";

package/dist/{validate-57H7GK5B.js → validate-3QMCX2HW.js}

@@ -7,7 +7,7 @@ import {
   readTestAdoption,
   resolveVitest,
   suiteOf
-} from "./chunk-DYJ6J43A.js";
+} from "./chunk-TDNPPNGK.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";
 import "./chunk-KMKQDGI6.js";

package/docs/test-adoption.md

@@ -6,6 +6,7 @@ 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.
 
+- [How to run it](#how-to-run-it)
 - [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)
@@ -13,6 +14,21 @@ that decided a design choice say which choice.
 - [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)
 
+## How to run it
+
+Every command on this page is written plainly as `sentinel --init --test`, because once a module
+has adopted, sentinel is one of its devDependencies and the module's own scripts call it. Before
+that, nothing is installed, so reach the tool with `npx`:
+
+```bash
+npx --yes @hublo/sentinel@<exact-version> --inspect --test
+```
+
+The two invocations that do not work there: `pnpm exec sentinel` answers `Command "sentinel" not
+found`, since the binary is not in the module's `node_modules` yet, and `pnpm dlx` aborts before
+sentinel runs at all under pnpm 12. The [README](../README.md) carries the measurements behind
+both.
+
 ## What the ground actually looks like
 
 |                                              |                                                |
@@ -146,11 +162,143 @@ await expect(container).toBeValidHtml()    // html-validate
 
 A **nest** module gets neither, because there is no DOM to assert on.
 
+How they get there depends on where your config comes from, and both paths end in the same list. A
+module migrated from jest receives a config that names them. A module that already had its own
+Vitest config keeps it, and `--init` adds the two entries to the `setupFiles` it already declares,
+sentinel's first:
+
+```ts
+setupFiles: [
+  '@hublo/sentinel/test/setup/a11y',
+  '@hublo/sentinel/test/setup/w3c',
+  './src/test/setup.ts',
+],
+```
+
+⚠️ If that list cannot be located, because the config declares none, declares several, or computes
+it, nothing is guessed: the adoption proceeds and the run says which two entries to add by hand.
+Losing a matcher costs a capability; refusing the adoption over it would cost a migration.
+
 ⚠️ 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.
 
+### Four cases, in React, with what they print
+
+Run on `libs/front/components` with `1.4.1`, after `--init --test` and `pnpm install`. Nothing was
+configured for them: `--init` wrote the wiring, what follows is only the assertions. Every subject
+is `container`, the element `render()` puts in the document.
+
+**An image with no alternative text.**
+
+```tsx
+const Avatar = () => <img src="/avatar.png" width={40} height={40} />
+
+const { container } = render(<Avatar />)
+await expect(container).toBeAccessible()
+```
+
+```
+Error: 1 accessibility violation(s):
+
+  image-alt (critical): Images must have alternative text
+    https://dequeuniversity.com/rules/axe/4.13/image-alt?application=axeAPI
+      img
+        Fix any of the following:
+  Element does not have an alt attribute
+  aria-label attribute does not exist or is empty
+  aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
+  Element has no title attribute
+  Element's default semantics were not overridden with role="none" or role="presentation"
+```
+
+**A button that is only an icon**, which is the same defect one layer deeper: the element has a
+role and no name.
+
+```tsx
+const CloseButton = () => (
+  <button type="button">
+    <svg width="16" height="16" aria-hidden="true" />
+  </button>
+)
+
+const { container } = render(<CloseButton />)
+await expect(container).toBeAccessible()
+```
+
+```
+Error: 1 accessibility violation(s):
+
+  button-name (critical): Buttons must have discernible text
+    https://dequeuniversity.com/rules/axe/4.13/button-name?application=axeAPI
+      button
+        Fix any of the following:
+  Element does not have inner text that is visible to screen readers
+  aria-label attribute does not exist or is empty
+  ...
+```
+
+In both, the message names the rule, its severity, the element, and every way of fixing it. The
+last point matters more than it looks: `aria-hidden` on the `<svg>` is correct and is not what is
+missing, so a list of the accepted fixes is what tells you to add the name on the button rather
+than to undo the `aria-hidden`.
+
+**A `<p>` inside a `<span>`**, which React renders happily and which no browser will keep.
+
+```tsx
+const Hint = () => (
+  <span>
+    <p>Ce champ est obligatoire</p>
+  </span>
+)
+
+const { container } = render(<Hint />)
+await expect(container).toBeValidHtml()
+```
+
+```
+Error: 1 HTML problem(s):
+
+  1:8  <p> element is not permitted as content under <span>  (element-permitted-content)
+```
+
+**A heading level that skips one.**
+
+```tsx
+const Panel = () => (
+  <section>
+    <h1>Mon compte</h1>
+    <h3>Coordonnées</h3>
+  </section>
+)
+
+const { container } = render(<Panel />)
+await expect(container).toBeValidHtml()
+```
+
+```
+Error: 1 HTML problem(s):
+
+  1:30  Heading level can only increase by one, expected <h2> but got <h3>  (heading-level)
+```
+
+This one is why the matcher wraps your markup in a document rather than validating the fragment
+alone: a heading rank is only wrong relative to the ranks around it, and a fragment has nothing to
+compare against.
+
+**And one case that neither of them catches**, worth knowing so you do not assume a green means
+more than it does. A `<button>` with no `type` defaults to `submit` and will post a form by
+surprise, yet:
+
+```tsx
+const Save = () => <button>Enregistrer</button>
+```
+
+passes `toBeAccessible()`, because axe has no rule for it, and passes `toBeValidHtml()`, because
+`no-implicit-button-type` is not in the preset we ship. Both were run; both are green. That one
+belongs to lint, not here.
+
 ### 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