@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/scripts/verrous/verrou.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// The write lock of a role agent: a PreToolUse hook declared in the settings of its session
+// (scripts/droits.mjs: `npx grillhouse verrou <role>`). It reads the hook's JSON on stdin and refuses a
+// file write the role does not own, with exit code 2 and its reason on stderr.
+//
+// - A path under the system temp directory (the session scratchpad) is always writable.
+// - testwriter writes the files it owns (`isTesterFile`): test files, and every file of a package
+//   of the shared test material.
+// - The repository root is that of the git repository holding the written file, whatever the
+//   agent's working directory; a file outside any repository is read against the working directory.
+// - developpeur writes none of the testwriter's files, and no other file until its ticket's
+//   description holds a "## Architecture" section. The ticket is the "TON TICKET : <id>" line of the agent's
+//   launch prompt, read from its transcript.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { matieres, NOM_DE_TEST } from '../consommateurs.mjs';
+
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+
+export function isTestFile(file) {
+  const parts = file.split(/[\\/]/);
+  const base = parts[parts.length - 1];
+  return (
+    parts.slice(0, -1).some(d => d === 'test' || d === 'tests' || d === '__tests__') ||
+    NOM_DE_TEST.test(base)
+  );
+}
+
+// True when <file>, absolute or relative to the repository root <racine>, is written by the
+// testwriter: a test file, or a file of a package of the shared test material (a component of
+// <racine> whose package exports `./test-fixtures`, `matieres` of `scripts/consommateurs.mjs`).
+// The one rule of ownership, read by the locks of both roles and by the integration's lots.
+export function isTesterFile(file, racine) {
+  const abs = path.resolve(racine, file);
+  if (isTestFile(path.relative(path.resolve(racine), abs))) {
+    return true;
+  }
+  return matieres(racine).some(m => isInside(abs, m.dir));
+}
+
+// True when <file> lies strictly under the directory <dir>.
+function isInside(file, dir) {
+  const rel = path.relative(path.resolve(dir), file);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+const isScratch = (file, tmp = tmpdir()) => isInside(file, tmp);
+
+// The root of the git repository (or worktree) that holds the absolute path <file>, read from its
+// nearest existing directory; null when no repository holds it.
+function racineDe(file) {
+  let dir = path.dirname(file);
+  while (!existsSync(dir)) {
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  try {
+    return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// The ticket id of the launch prompt. A sub-agent's prompt opens its own transcript, next to the
+// session's; an agent launched as its own session (`claude --agent`) has it in the session's.
+function ticketOf(input) {
+  if (!input.transcript_path) {
+    return null;
+  }
+  const transcript = input.agent_id
+    ? path.join(
+        input.transcript_path.replace(/\.jsonl$/, ''),
+        'subagents',
+        `agent-${input.agent_id}.jsonl`
+      )
+    : input.transcript_path;
+  let first;
+  try {
+    first = readFileSync(transcript, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(l => JSON.parse(l))
+      .find(e => e.type === 'user');
+  } catch {
+    return null;
+  }
+  const content = first?.message?.content;
+  const text = Array.isArray(content) ? content.map(c => c.text ?? '').join('\n') : content;
+  const m = /TON TICKET\s*:\s*([A-Za-z0-9_.-]+)/.exec(text ?? '');
+  return m ? m[1] : null;
+}
+
+function ticketDescription(id, cwd) {
+  try {
+    const out = execFileSync('bd', ['show', id, '--json'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: 256 * 1024 * 1024,
+    });
+    return JSON.parse(out)[0]?.description ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The refusal reason for this hook input, or null when the write is allowed.
+export function refusal(role, input, { tmp = tmpdir(), describe = ticketDescription } = {}) {
+  if (!WRITE_TOOLS.has(input.tool_name)) {
+    return null;
+  }
+  const raw = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
+  if (!raw) {
+    return null;
+  }
+  const cwd = input.cwd ?? process.cwd();
+  const file = path.resolve(cwd, raw);
+  if (isScratch(file, tmp)) {
+    return null;
+  }
+  const racine = racineDe(file) ?? cwd;
+  const testwriter = isTesterFile(file, racine);
+
+  if (role === 'testwriter') {
+    return testwriter
+      ? null
+      : `Le testwriter écrit seulement des fichiers de test et la matière de test partagée ; ${raw} n'est ni l'un ni l'autre. Le code revient au développeur.`;
+  }
+  if (role === 'developpeur') {
+    if (testwriter) {
+      return isTestFile(path.relative(path.resolve(racine), file))
+        ? `Les tests appartiennent au testwriter : ${raw} est un fichier de test. Un test faux se signale au superviseur.`
+        : `La matière de test partagée appartient au testwriter : ${raw} en fait partie. Un besoin de matière se signale au superviseur.`;
+    }
+    const id = ticketOf(input);
+    if (!id) {
+      return 'Ton ticket est introuvable : ton message de lancement porte « TON TICKET : <id> ».';
+    }
+    const description = describe(id, input.cwd);
+    if (description === null) {
+      return `Le ticket ${id} est illisible par bd.`;
+    }
+    if (!/^##\s+Architecture\b/m.test(description)) {
+      return `Le ticket ${id} n'a pas sa section « ## Architecture » : le code attend l'architecture. Rends la question au superviseur.`;
+    }
+    return null;
+  }
+  return `Rôle inconnu du verrou : ${role}.`;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const reason = refusal(process.argv[2], input);
+  if (reason) {
+    process.stderr.write(reason + '\n');
+    process.exitCode = 2;
+  }
+}

package/scripts/vitest-config/avancement.mjs

@@ -0,0 +1,39 @@
+// The progress of a pass, as Bazel counts its actions « [1 234 / 2 000] »: the variable that names
+// the progress directory of a pass, `GRILLHOUSE_AVANCEMENT`, the reporter the base configuration
+// adds while it is set (./base.mjs, ./avancement.reporter.mjs), and the writing of a record. The
+// reading, the plan and the totals kept are scripts/avancement.mjs.
+//
+// - Each task of a pass writes its own record to `<dossier>/taches/<nom>.json`: `{ hash, faits,
+//   prevus, a }`, the hash of its Turborepo task (`TURBO_HASH`, null out of Turborepo), its files
+//   done and planned, and the instant of the writing (ms). Two packages, or the same one twice,
+//   never write the same file.
+// - A record is written whole or not at all: to a file of its own, renamed over the record.
+// - The variable passes through Turborepo without entering any hash (`globalPassThroughEnv` of the
+//   root's turbo.json, which scripts/turbo-des-paquets.mjs writes and checks).
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const AVANCEMENT = 'GRILLHOUSE_AVANCEMENT';
+// The subdirectory of the records in a progress directory.
+export const TACHES = 'taches';
+
+// Writes <objet> as JSON to <fichier>, whole or not at all.
+export function ecrireAtomique(fichier, objet) {
+  mkdirSync(path.dirname(fichier), { recursive: true });
+  const provisoire = `${fichier}.${process.pid}.tmp`;
+  writeFileSync(provisoire, JSON.stringify(objet));
+  renameSync(provisoire, fichier);
+}
+
+// Writes the record <nom> of the progress directory <dossier>: <faits> done of <prevus>, now.
+export function ecrireTache(dossier, nom, { hash = null, faits, prevus }) {
+  ecrireAtomique(path.join(dossier, TACHES, `${nom}.json`), { hash, faits, prevus, a: Date.now() });
+}
+
+// The reporter of progress under <env>'s progress directory, as Vitest's `reporters` take it; an
+// empty list without the variable.
+export function rapportAvancement(env = process.env) {
+  if (!env[AVANCEMENT]) return [];
+  return [fileURLToPath(new URL('./avancement.reporter.mjs', import.meta.url))];
+}

package/scripts/vitest-config/avancement.reporter.mjs

@@ -0,0 +1,56 @@
+// The reporter of progress of the base configuration, while the variable GRILLHOUSE_AVANCEMENT
+// names the progress directory of a pass (./avancement.mjs): it writes the record of its task
+// once Vitest knows the files it plays (their number, the files planned), then at each test file
+// done, then at the end of the run, every file done. The name of the record is made of the package
+// directory it runs in and its process; it carries the hash of its Turborepo task (TURBO_HASH), by
+// which the pass knows it again in Turborepo's cache (scripts/avancement.mjs).
+import { AVANCEMENT, ecrireTache } from './avancement.mjs';
+
+const FINIS = new Set(['pass', 'fail', 'skip', 'todo']);
+
+export default class AvancementReporter {
+  constructor() {
+    this.dossier = process.env[AVANCEMENT];
+    this.nom = `${process.cwd().split('/').filter(Boolean).join('-') || 'racine'}-${process.pid}`;
+    this.prevus = 0;
+    this.faits = new Set();
+  }
+
+  onInit(ctx) {
+    this.ctx = ctx;
+  }
+
+  ecrire() {
+    try {
+      ecrireTache(this.dossier, this.nom, {
+        hash: process.env.TURBO_HASH ?? null,
+        faits: this.faits.size,
+        prevus: Math.max(this.prevus, this.faits.size),
+      });
+    } catch {
+      // A directory that does not write leaves the run going, without its progress.
+    }
+  }
+
+  onPathsCollected(fichiers = []) {
+    this.prevus = fichiers.length;
+    this.ecrire();
+  }
+
+  onTaskUpdate(paquets = []) {
+    let change = false;
+    for (const [id, resultat] of paquets) {
+      const t = this.ctx?.state?.idMap?.get(id);
+      if (!t?.filepath || t.file !== t || !FINIS.has(resultat?.state)) continue;
+      if (this.faits.has(id)) continue;
+      this.faits.add(id);
+      change = true;
+    }
+    if (change) this.ecrire();
+  }
+
+  onFinished(fichiers = []) {
+    for (const f of fichiers) this.faits.add(f.id);
+    this.ecrire();
+  }
+}

package/scripts/vitest-config/base-de-passe.mjs

@@ -0,0 +1,128 @@
+// The base of a pass: the temporary directory of a run, its own and removed at its end, as Bazel
+// gives each test its temporary directory (TEST_TMPDIR) under the base of its run. A pass killed
+// leaves its base, which the next pass sweeps, as Bazel cleans its sandboxes.
+//
+// - A base is a directory `<dans>/grillhouse-<genre>-XXXXXX/`, `<dans>` the temporary directory of
+//   whoever opens it (`os.tmpdir()`). It holds its owner (`.grillhouse-base`: the process that
+//   opened it and that process's PID namespace) and `t/`, the directory where the pass and its
+//   processes write: the pass names it in `TMPDIR` to its children, so `os.tmpdir()`, `mktemp` and
+//   Claude Code (`CLAUDE_CODE_TMPDIR`, else `os.tmpdir()`) write there.
+// - The genres: `vitest`, each run of Vitest (`baseDeVitest`, a plugin of the base configuration,
+//   ./base.mjs), which holds Vitest's own temporary directory too; `tests`, `npm test` (scripts/tests.mjs); `verification`,
+//   `npm run verifier` (scripts/verifier.mjs), whose base Turborepo passes to its tasks
+//   (`globalPassThroughEnv`, scripts/turbo-des-paquets.mjs); `circuit`, the results and progress
+//   of the passes of a circuit's run (scripts/circuit.mjs; its working directory is the ticket's,
+//   beside its copy, which no sweep touches); `integration`, the working directory of an
+//   integration (scripts/integration/integrer.mjs); `enveloppe`, the throwaway state of a session's envelope
+//   (scripts/enveloppe/enveloppe.mjs).
+// - The base is removed at the end of the pass, green or red (`fermer`).
+// - Opening a base first sweeps `<dans>`: every base there whose owner is gone is removed, whatever
+//   its genre. A base is judged by its owner's process only when that owner lives in the PID
+//   namespace of the sweeper (an envelope has its own, bwrap --unshare-pid, where a number means
+//   nothing outside): a base of another namespace, a base without a readable owner (one being
+//   created) and a base whose owner lives are never touched.
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+// The prefix of a base's name, and the file of its owner.
+const PREFIXE = 'grillhouse-';
+const PROPRIETAIRE = '.grillhouse-base';
+
+/** Whether the process `pid` exists. */
+export function vivant(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+// The PID namespace of this process, or null when /proc does not tell it.
+function espace() {
+  try {
+    return readlinkSync('/proc/self/ns/pid');
+  } catch {
+    return null;
+  }
+}
+
+// Whether the base <base> is an orphan: its owner reads, lives in this namespace, and is gone.
+function orpheline(base) {
+  let p;
+  try {
+    p = JSON.parse(readFileSync(path.join(base, PROPRIETAIRE), 'utf8'));
+  } catch {
+    return false;
+  }
+  const ici = espace();
+  return ici !== null && p.espace === ici && Number.isInteger(p.pid) && !vivant(p.pid);
+}
+
+// Removes every orphan base in <dans>.
+function balayer(dans) {
+  let noms;
+  try {
+    noms = readdirSync(dans);
+  } catch {
+    return;
+  }
+  for (const nom of noms) {
+    const base = path.join(dans, nom);
+    if (nom.startsWith(PREFIXE) && orpheline(base)) rmSync(base, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Opens the base of a pass of <genre> in <dans>, after sweeping the orphan bases there.
+ * @param {string} genre what the pass is (`vitest`, `circuit`…), in the base's name
+ * @param {{ dans?: string }} options `dans`, the directory of the base (`os.tmpdir()`)
+ * @returns {{ base: string, dossier: string, fermer: () => void }} the base, the directory its
+ *   pass writes in (`TMPDIR` of its children), and the removal of the base
+ */
+export function ouvrirBase(genre, { dans = tmpdir() } = {}) {
+  balayer(dans);
+  mkdirSync(dans, { recursive: true });
+  const base = mkdtempSync(path.join(dans, `${PREFIXE}${genre}-`));
+  writeFileSync(
+    path.join(base, PROPRIETAIRE),
+    `${JSON.stringify({ pid: process.pid, espace: espace() })}\n`
+  );
+  const dossier = path.join(base, 't');
+  mkdirSync(dossier);
+  return { base, dossier, fermer: () => rmSync(base, { recursive: true, force: true }) };
+}
+
+// The variable that marks the base of a run of Vitest: `<process>:<base>`, the process that opened
+// it. A configuration loaded again in that process (Vite bundles each load) keeps that base.
+const MARQUE = 'GRILLHOUSE_BASE_DE_VITEST';
+
+/**
+ * The plugin of the base configuration that gives a run of Vitest its base: while Vite resolves
+ * the configuration, before Vitest makes its own temporary directory (`join(tmpdir(), nanoid())`,
+ * its transformed modules), the main process opens a base of genre `vitest` and names it in its
+ * `TMPDIR`, which every test process inherits; the base is removed when the process exits, green
+ * or red. A process that already opened its base keeps it.
+ * @returns {{ name: string, config: () => void }} a plugin of Vite
+ */
+export function baseDeVitest() {
+  return {
+    name: 'grillhouse:base-de-passe',
+    config() {
+      if (process.env[MARQUE]?.startsWith(`${process.pid}:`)) return;
+      const b = ouvrirBase('vitest');
+      process.env[MARQUE] = `${process.pid}:${b.base}`;
+      process.env.TMPDIR = b.dossier;
+      process.on('exit', b.fermer);
+    },
+  };
+}

package/scripts/vitest-config/base.d.ts

@@ -0,0 +1,6 @@
+// The types of ./base.mjs, for a Vitest configuration written in TypeScript that imports
+// `@roomi-fields/grillhouse/vitest-config` and extends it (`mergeConfig`).
+import type { UserConfig } from 'vitest/config';
+
+declare const base: UserConfig;
+export default base;

package/scripts/vitest-config/base.mjs

@@ -0,0 +1,87 @@
+// The frame's base configuration of the day's tests, exported by the frame's package as
+// `@roomi-fields/grillhouse/vitest-config`: every Vitest configuration of a project extends it
+// (`mergeConfig(base, defineConfig({ … }))`) and adds its own `include`, coverage and options
+// without repeating what this file sets.
+//
+// - Every configuration imports it by its name (`import base from
+//   '@roomi-fields/grillhouse/vitest-config'`), the root's of a project as each package's, as the
+//   examples of Turborepo reach their configuration packages (@repo/eslint-config): a package is
+//   reached by its name, never by a path into it. In a repository of packages, each tested
+//   package declares the frame's package in its devDependencies, which the update of the frame
+//   writes (scripts/grillhouse-maj.mjs). Grillhouse's package imports it by its own name.
+//
+// - The exclusions of the day: a night test (`*.nuit.test.*`, `*.nuit.spec.*`) is too long for the
+//   day, and the measures of a time budget bench (`*.budget.test.*`, `*.budget.spec.*`) move with
+//   the load of the day: `npm test`, `npm run verifier` and the integration leave both out, and
+//   the night plays them (scripts/nuit.sh, scripts/vitest.nuit.config.mjs); a targeted run that
+//   names the file of one itself plays it, under the measure of time below (./cibles.mjs, where
+//   the patterns live). `mergeConfig` adds the exclusions of a configuration that extends this one
+//   to these.
+// - A run that plays no test fails, as Vitest's default has it (`passWithNoTests` unset): a
+//   targeted run (`npm test -- <paths>`, scripts/tests.mjs) plays each path in its package only,
+//   and a path that names no test is a mistake, never a green.
+// - The tests a targeted run names arrive in the variable `GRILLHOUSE_TESTS`, which a plugin
+//   reads once the configuration is merged and turns into the files played (./cibles.mjs); without
+//   it, nothing changes. The same plugin restricts a pass measured against the last green to the
+//   tests Vitest relates to the files changed since it (`GRILLHOUSE_CHANGEMENTS`,
+//   ./changements.mjs). `mergeConfig` adds the plugins of a configuration that extends this one to
+//   it.
+// - The common environment: Node, no watch, and git's settings for the tests by the environment
+//   (GIT_CONFIG_COUNT/KEY/VALUE, git-config(1)), the automatic maintenance and garbage collection
+//   off (maintenance.auto=false, gc.auto=0). This file is the one address of these settings; the
+//   night configuration takes them from here.
+// - A time witness is measured with the CPU at rest: a setup file notes the CPU pressure at the
+//   start and at the end of each test (./mesure.setup.mjs), and the duration reporter, beside
+//   Vitest's default one, gives the exit code 75, « à repasser », when every failure depends on a
+//   duration and one took place under load (./duree.reporter.mjs; the signal and its threshold,
+//   ./pression.mjs). A test that measures time marks itself (`mesurerAuRepos`,
+//   `@roomi-fields/grillhouse/vitest-config/mesure`). `mergeConfig` adds the reporters and the setup files of
+//   a configuration that extends this one to these; a reporter named on the command line
+//   (`--reporter`) replaces them, and Vitest's code then stands.
+// - The machine of a test file is its own: a setup file gives it a lock of the heavy measure of
+//   its own, so that a `npm run verifier` a test plays in a repository of trial neither waits for
+//   the lock of the machine nor holds it (./machine.setup.mjs, scripts/verrou-de-machine.mjs).
+// - The time witnesses play alone in `npm run verifier`: the plugin below leaves them out of its
+//   pass, then plays them in a pass of their own (./cibles.mjs, scripts/verifier.mjs).
+// - While a run names its results directory (`GRILLHOUSE_RESULTATS`, ./resultats.mjs), the JSON
+//   reporter writes Vitest's report there too, which the circuit reads (scripts/resultats.mjs); a
+//   setup file gives each test file's processes a results directory of their own, so that a run a
+//   test plays in a repository of trial never writes in it (./resultats.setup.mjs).
+// - A run of Vitest has a base of its own, as Bazel gives each test its TEST_TMPDIR: a plugin opens
+//   it while the configuration resolves, sweeping the orphan bases a killed run left, and names
+//   it in TMPDIR, so that Vitest's own temporary directory, each test process and everything they
+//   start write there; the base is removed when the run exits, green or red
+//   (./base-de-passe.mjs).
+// - While a run names the progress directory of its pass (`GRILLHOUSE_AVANCEMENT`,
+//   ./avancement.mjs), the reporter of progress writes there the files done and planned of its
+//   task at each test file done, which the board reads (scripts/avancement.mjs,
+//   scripts/tableau.mjs).
+import { fileURLToPath } from 'node:url';
+import { baseDeVitest } from './base-de-passe.mjs';
+import { ciblage, HORS_DU_JOUR } from './cibles.mjs';
+import { rapportAvancement } from './avancement.mjs';
+import { rapportJson } from './resultats.mjs';
+
+const ici = f => fileURLToPath(new URL(f, import.meta.url));
+
+export default {
+  plugins: [baseDeVitest(), ciblage()],
+  test: {
+    environment: 'node',
+    env: {
+      GIT_CONFIG_COUNT: '2',
+      GIT_CONFIG_KEY_0: 'maintenance.auto',
+      GIT_CONFIG_VALUE_0: 'false',
+      GIT_CONFIG_KEY_1: 'gc.auto',
+      GIT_CONFIG_VALUE_1: '0',
+    },
+    exclude: ['**/node_modules/**', '**/dist/**', ...HORS_DU_JOUR],
+    reporters: ['default', ici('./duree.reporter.mjs'), ...rapportJson(), ...rapportAvancement()],
+    setupFiles: [
+      ici('./mesure.setup.mjs'),
+      ici('./machine.setup.mjs'),
+      ici('./resultats.setup.mjs'),
+    ],
+    watch: false,
+  },
+};

package/scripts/vitest-config/changements.mjs

@@ -0,0 +1,173 @@
+// The changes since the last green that a pass measures itself against (scripts/dernier-vert.mjs
+// writes them), as the plugin of ./cibles.mjs reads them in the package whose configuration it
+// runs: the tests Vitest relates to them, or every test of the package when one of them lies
+// where Vitest's graph of a test does not reach. `vitest --changed <ref>` is the model: Vitest
+// relates a test to the files it reads from git (`<ref>...HEAD`, the files staged, modified and
+// untracked), and plays the tests whose graph holds one of them (`related`); the frame gives it
+// the files that differ from the tree of the last green instead, which Vitest's git cannot read
+// (a green kept on a copy whose lot is not committed).
+//
+// - The variable `GRILLHOUSE_CHANGEMENTS` names a JSON file, `{ racine, fichiers, supprimes }`: the
+//   top of the repository, the files changed or added since the last green and the files removed,
+//   each path from the top. It passes through Turborepo without entering any hash (the root's
+//   `globalPassThroughEnv`, which scripts/turbo-des-paquets.mjs writes and checks): a package whose
+//   inputs did not move replays its last green from Turborepo's cache, whatever the last green.
+//   The plugin takes it out of the environment once read: no process the tests start receives it.
+// - The graph of a test is the test file and the modules it imports, statically or dynamically,
+//   node_modules left out (`getTestDependencies` of Vitest). Vitest does not see what lies out of
+//   it, and the package plays whole (`entier`) when a change lies there, the reason written:
+//   1. a file removed, in the package or in a package it depends on: no graph of today holds it;
+//   2. the frame's base configuration (this directory), which every configuration extends;
+//   3. the configuration of the repository at its top: `package.json`, `package-lock.json`,
+//      `turbo.json`, `turbo.jsonc`, `tsconfig*.json`;
+//   4. the configuration of the package at its top: `package.json`, `vitest.config.*`,
+//      `vite.config.*`, `vitest.workspace.*`, `tsconfig*.json`; its `setupFiles` and its
+//      `globalSetup`, which Vitest runs beside the graph;
+//   5. a path its tests declare they read (`grillhouse.lit` of its package.json, from the top):
+//      a script they run, a file they read, as Bazel's `data`;
+//   6. a file of a package it depends on (its `dependencies`, `devDependencies`,
+//      `optionalDependencies` and `peerDependencies` that resolve to a directory of the repository,
+//      out of node_modules, transitively), a test file of that package aside: its tests read that
+//      package built, not the source git follows;
+//   7. a file of the package that no graph can hold, its extension not that of a module (`.js`,
+//      `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.jsx`, `.tsx`, `.json`): data, a template, a
+//      script of the shell, a document, which a test reads without importing it.
+//   Vitest's own `forceRerunTriggers` (a configuration's, or its default) still apply, as with
+//   `--changed`.
+// - Otherwise the tests played are those Vitest relates to the files changed or added (`related`,
+//   absolute), and the files a targeted run names themselves (./cibles.mjs) join them: a file named
+//   plays, changed or not. A package where none relates plays none and passes
+//   (`passWithNoTests`), as Vitest's `--changed` has it.
+//
+// This module uses Node alone.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CHANGEMENTS = 'GRILLHOUSE_CHANGEMENTS';
+// This directory, the frame's base configuration.
+const BASE = path.dirname(fileURLToPath(import.meta.url));
+// The extension of a module, which a graph of Vitest can hold.
+const MODULE = /\.(?:[cm]?[jt]sx?|json)$/;
+// A test file, as Vitest's default `include` names one.
+const TEST = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const DU_DEPOT = /^(?:package\.json|package-lock\.json|turbo\.jsonc?|tsconfig[^/]*\.json)$/;
+const DU_PAQUET =
+  /^(?:package\.json|(?:vitest|vite)\.config\.[^/]+|vitest\.workspace\.[^/]+|tsconfig[^/]*\.json)$/;
+const CHAMPS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+
+const lireJson = f => {
+  try {
+    return JSON.parse(readFileSync(f, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+// Whether the absolute path <f> lies under the directory <dir> (or is it).
+const sous = (f, dir) => {
+  const r = path.relative(dir, f);
+  return r === '' || (!r.startsWith('..') && !path.isAbsolute(r));
+};
+
+// The changes the file at <chemin> holds, `{ racine, fichiers, supprimes }`; null when it does not
+// read.
+export function lireChangements(chemin) {
+  const c = lireJson(chemin);
+  const liste = l => Array.isArray(l) && l.every(x => typeof x === 'string');
+  if (!c || typeof c.racine !== 'string' || !liste(c.fichiers) || !liste(c.supprimes)) return null;
+  return c;
+}
+
+// The directories of the packages of the repository at <racine> that the package at <dossier>
+// depends on, transitively, itself left out.
+function dependances(racine, dossier) {
+  const vus = new Set([dossier]);
+  const out = [];
+  const suivre = d => {
+    const pkg = lireJson(path.join(d, 'package.json')) ?? {};
+    const noms = new Set(CHAMPS.flatMap(c => Object.keys(pkg[c] ?? {})));
+    for (const nom of noms) {
+      for (let ici = d; sous(ici, racine); ici = path.dirname(ici)) {
+        const lien = path.join(ici, 'node_modules', nom);
+        if (!existsSync(lien)) {
+          if (ici === racine) break;
+          continue;
+        }
+        let reel;
+        try {
+          reel = realpathSync(lien);
+        } catch {
+          break;
+        }
+        const r = path.relative(racine, reel);
+        if (sous(reel, racine) && !r.split(path.sep).includes('node_modules') && !vus.has(reel)) {
+          vus.add(reel);
+          out.push(reel);
+          suivre(reel);
+        }
+        break;
+      }
+    }
+  };
+  suivre(dossier);
+  return out;
+}
+
+// Why the package whose configuration's root is <dossier> plays whole under the changes <ch>, its
+// test configuration <test>: `{ raison, fichier }`, the first change out of Vitest's graph (the
+// path from the top of the repository); null when Vitest sees them all.
+function paquetEntier(ch, dossier, test = {}) {
+  const racine = ch.racine;
+  const abs = f => path.join(racine, f);
+  const deps = dependances(racine, dossier);
+  const lit = (lireJson(path.join(dossier, 'package.json'))?.grillhouse?.lit ?? [])
+    .filter(l => typeof l === 'string')
+    .map(l => l.replace(/^\.\//, '').replace(/\/+$/, ''));
+  const preparation = [test.setupFiles, test.globalSetup]
+    .flat()
+    .filter(f => typeof f === 'string')
+    .map(f => path.resolve(dossier, f));
+  for (const f of ch.supprimes) {
+    if ([dossier, ...deps].some(d => sous(abs(f), d))) {
+      return { raison: 'un fichier supprimé, que le graphe des tests ne tient plus', fichier: f };
+    }
+  }
+  for (const f of ch.fichiers) {
+    const a = abs(f);
+    const raison = sous(a, BASE)
+      ? 'la configuration de base du cadre'
+      : !f.includes('/') && DU_DEPOT.test(f)
+        ? 'la configuration du dépôt'
+        : path.dirname(a) === dossier && DU_PAQUET.test(path.basename(a))
+          ? 'la configuration du paquet'
+          : preparation.includes(a)
+            ? 'un fichier de préparation des tests'
+            : lit.some(l => f === l || f.startsWith(`${l}/`))
+              ? 'un chemin que ses tests déclarent lire (grillhouse.lit)'
+              : deps.some(d => sous(a, d)) && !TEST.test(f)
+                ? 'le code d’un paquet dont il dépend, que ses tests lisent construit'
+                : sous(a, dossier) && !MODULE.test(f)
+                  ? 'un fichier qu’aucun module n’importe, qu’un test lit sans l’importer'
+                  : null;
+    if (raison) return { raison, fichier: f };
+  }
+  return null;
+}
+
+// Restricts the test configuration <test> of the package at <dossier> to the changes <ch>: the
+// tests Vitest relates to them and the files <nommes> (absolute), or every test, when a change
+// lies out of Vitest's graph; <dire> writes the line that says which.
+export function restreindre(test, dossier, ch, nommes, dire) {
+  const nom = path.relative(ch.racine, dossier) || '.';
+  const entier = paquetEntier(ch, dossier, test);
+  if (entier) {
+    dire(`↳ ${nom} : tous ses tests, ${entier.raison} (${entier.fichier}).`);
+    return;
+  }
+  test.related = [...new Set([...ch.fichiers.map(f => path.join(ch.racine, f)), ...nommes])];
+  test.passWithNoTests = true;
+  dire(
+    `↳ ${nom} : les tests que Vitest relie aux ${ch.fichiers.length} fichier(s) changé(s) depuis le dernier vert.`
+  );
+}