@xemahq/repo-build-tooling 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/readiness.mjs

@@ -62,8 +62,9 @@
  * honestly.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 
 // THE ROOT IS THE CONSUMER'S REPOSITORY, NEVER THIS PACKAGE'S LOCATION.
@@ -163,11 +164,26 @@ const STEPS = [
   {
     id: 'ledgers',
     why: "each biome's integrity claim over its own bytes, specs and clients included",
-    // `--allow-dirty` is SAFE HERE AND ONLY HERE, because `run()` refuses to start
-    // on a dirty tree — so every modified file at this point is output THIS RUN
-    // produced. Without it the step is a no-op in exactly the case it exists for:
-    // the biomes it must re-hash are the ones the specs and clients just dirtied,
-    // so the deriver skips precisely those and exits 0.
+    // `--allow-dirty` is REQUIRED here: without it the step is a no-op in exactly
+    // the case it exists for, because the biomes it must re-hash are the ones the
+    // specs and clients just dirtied, so the deriver skips precisely those and
+    // exits 0 — a green command over a skipped corpus.
+    //
+    // WHAT IT DOES NOT MEAN, corrected 2026-09-19. This said "SAFE HERE AND ONLY
+    // HERE, because `run()` refuses to start on a dirty tree". `run()` does no
+    // such thing: it REPORTS pre-existing modified paths and continues, and its
+    // only refusal is for an install behind its own lockfile. The claim made this
+    // authority internally contradictory with its own `run()` forty lines down,
+    // and it was the load-bearing half — it is the reason the flag reads as safe,
+    // so a reader who checked it would have stopped there.
+    //
+    // The honest statement is narrower. A ledger hashes the WORKING TREE, so
+    // anything already modified when this starts is hashed in too. For the
+    // workflow this serves — regenerating alongside edits you are about to commit
+    // — that is correct, and refusing would break the one loop the command exists
+    // for. In a SHARED checkout holding somebody else's modifications it IS a
+    // waived check, which is why `run()` prints those paths and asks the reader
+    // whether all of them are theirs.
     run: ['node', 'tooling/codegen/derive-biome-index.mjs', '--allow-dirty'],
     needs: 'derive:biome-index',
     gate: 'check:biome-index-ledger',
@@ -282,7 +298,7 @@ function changedPackages() {
     .map((l) => l.trim())
     .filter(Boolean);
 
-  return { base, paths, packages: packagesOwningPaths(ROOT, paths) };
+  return { base, paths };
 }
 
 /**
@@ -292,13 +308,13 @@ function changedPackages() {
  *
  * Two rules, both deliberate:
  *   - the ROOT manifest never owns anything. It is not a workspace member, and
- *     its `test` script is usually `turbo run test` — the whole fleet, which is
- *     the opposite of affected.
- *   - a package with no `test` script owns nothing, so it is absent from the set
- *     rather than present-and-skipped. A skipped member inflates the corpus line
- *     and makes "0 ran" look like "all passed".
+ *     its script is usually `turbo run <x>` — the whole fleet, which is the
+ *     opposite of affected. The root is handled separately, as a FALLBACK.
+ *   - a package not declaring THIS script owns nothing for this stage, so it is
+ *     absent from the set rather than present-and-skipped. A skipped member
+ *     inflates the corpus line and makes "0 ran" look like "all passed".
  */
-export function packagesOwningPaths(root, relPaths) {
+export function packagesOwningPaths(root, relPaths, script = 'test') {
   // CONTAINMENT IS A PATH QUESTION, NEVER A STRING PREFIX. `dir.startsWith(root)`
   // admits a SIBLING whose name merely begins with the same characters — for
   // root `/x/repo`, the path `/x/repo-legacy/pkg` passes — and this fleet keeps
@@ -314,10 +330,14 @@ export function packagesOwningPaths(root, relPaths) {
     let dir = path.dirname(path.resolve(root, rel));
     while (contains(dir)) {
       const manifest = path.join(dir, 'package.json');
-      if (dir !== root && existsSync(manifest)) {
+      // No `dir !== root` guard: `contains()` already excludes it, because
+      // `path.relative(root, root)` is the empty string. A mutation restoring
+      // that guard changed no behaviour, which is what identified it as inert
+      // rather than as an untested branch.
+      if (existsSync(manifest)) {
         try {
           const json = JSON.parse(readFileSync(manifest, 'utf8'));
-          if (json.name && json.scripts?.test) owners.add(json.name);
+          if (json.name && json.scripts?.[script]) owners.add(json.name);
         } catch {
           /* an unreadable manifest owns nothing */
         }
@@ -337,37 +357,71 @@ export function packagesOwningPaths(root, relPaths) {
  * CI owns that question. What this owns is "the thing I just edited still
  * passes its own tests", which is the one that was missing.
  */
-function runAffectedTests() {
-  console.log('\n=== tests — the affected packages\' own suites ===');
-  const { base, paths, packages } = changedPackages();
+/**
+ * Run ONE affected stage — the changed packages' own `<script>`.
+ *
+ * THREE STAGES, NOT ONE, because they are ORTHOGONAL PROOFS and this command is
+ * the only place that owns the ordering:
+ *
+ *   tests green      != typecheck green   (a suite can compile nothing)
+ *   typecheck green  != tests green       (compiling proves no behaviour)
+ *   either green     != lint green
+ *
+ * They run AFTER the generators, not before, and that order is not a preference:
+ * a service typechecks against its GENERATED client, so typechecking before
+ * `clients` grades a stale artifact and reports the CONSUMER — the same fake
+ * cascade the header above describes for spec extraction.
+ *
+ * Dependents are deliberately excluded: that closure reaches 144 packages in the
+ * largest repository here, and CI owns it. What this owns is "the thing I just
+ * edited still passes its own proofs".
+ */
+function runAffectedStage({ id, script, why }) {
+  console.log(`\n=== ${id} — ${why} ===`);
+  const { base, paths } = changedPackages();
   if (!base) {
     console.log(
       '  SKIPPED — neither origin/develop nor origin/main is fetched here, so\n' +
-        '  there is no branch point to diff against. Fetch, or run the suites by hand.',
+        '  there is no branch point to diff against. Fetch, or run this by hand.',
     );
     return;
   }
-  // The CORPUS, printed: a verdict with no denominator cannot be graded in
-  // either direction, and "0 tests ran" and "0 tests failed" look identical.
+  const packages = packagesOwningPaths(ROOT, paths, script);
+  // The CORPUS, printed with BOTH counts: "0 ran" and "0 failed" look identical
+  // otherwise, and a green command over an empty scan is not proof.
   console.log(
     `  ${paths.length} changed path(s) since ${base.slice(0, 9)} -> ` +
-      `${packages.length} package(s) with a test script`,
+      `${packages.length} package(s) declaring \`${script}\``,
   );
-  if (packages.length === 0) {
+  if (packages.length > 0) {
+    for (const name of packages) console.log(`    - ${name}`);
+    for (const name of packages) {
+      // One at a time, so a failure NAMES the package; a single multi-filter
+      // invocation reports only the first.
+      sh(['pnpm', '--filter', name, script]);
+    }
+    return;
+  }
+  // FALLBACK, and it is the difference between "inapplicable" and "not checked".
+  // Some repositories own a stage only at the root — `lint: eslint .` covers
+  // every package without any of them declaring `lint`. Skipping there would
+  // silently drop a real proof, so the root script runs, LABELLED as repo-wide
+  // rather than affected, so nobody reads it as an affected result.
+  if (paths.length > 0 && scripts[script]) {
     console.log(
-      '  nothing to run — the changed paths belong to no workspace package with\n' +
-        '  a test script (a workflow, a root document, generated output).',
+      `  no changed package declares \`${script}\`, but the ROOT does — running it\n` +
+        '  REPO-WIDE. This is applicable-but-not-affected, and is reported as such.',
     );
+    sh(['pnpm', 'run', script]);
     return;
   }
-  for (const name of packages) console.log(`    - ${name}`);
-  for (const name of packages) {
-    // One at a time, so a failure NAMES the package; a single multi-filter
-    // invocation reports only the first.
-    sh(['pnpm', '--filter', name, 'test']);
-  }
+  console.log(
+    `  nothing to run — no changed package declares \`${script}\` and the root\n` +
+      '  declares none either, so this stage is genuinely inapplicable here.',
+  );
 }
 
+
 function run() {
   // ── WHAT `--allow-dirty` INCLUDES, STATED RATHER THAN ASSUMED ─────────────
   // This regenerates derived artifacts and hashes them into biome ledgers, and a
@@ -502,7 +556,13 @@ function run() {
     if (scripts[gate]) sh(['pnpm', gate]);
   }
 
-  runAffectedTests();
+  for (const stage of [
+    { id: 'typecheck', script: 'typecheck', why: 'the compiler, which a passing suite does not imply' },
+    { id: 'lint', script: 'lint', why: 'the rules neither the compiler nor a suite enforces' },
+    { id: 'tests', script: 'test', why: "the affected packages' own suites" },
+  ]) {
+    runAffectedStage(stage);
+  }
 
   console.log(
     '\nreadiness: converged. Every derived artifact describes the source beside it,\n' +
@@ -511,11 +571,41 @@ function run() {
   return 0;
 }
 
-// Executed as a bin, imported by its test. `process.argv[1]` is this file only
-// when node was asked to RUN it — an import leaves it pointing at the test.
-const INVOKED_DIRECTLY =
-  process.argv[1] !== undefined &&
-  path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+/**
+ * Was this module RUN, or merely imported (by its own test)?
+ *
+ * BOTH SIDES ARE REALPATH'D, and that is the whole correctness of it. pnpm's
+ * isolated linker puts the package at `node_modules/.pnpm/<pkg>@<ver>/...` and
+ * symlinks `node_modules/@scope/<pkg>` to it, so `process.argv[1]` and
+ * `import.meta.url` can name the SAME FILE by two different paths. Comparing
+ * them unresolved gives an answer that depends on HOW THE PACKAGE WAS LINKED —
+ * true through pnpm's bin shim, which invokes the realpath, and false when the
+ * symlinked path is invoked. A predicate whose answer depends on the linker is
+ * not a predicate.
+ *
+ * The failure mode is the one this whole tool exists to prevent: a false answer
+ * takes the import branch, `run()` is never called, and the process exits 0 —
+ * a chain reporting success without running. Caught by a peer, not by me, and
+ * not by any test, which is why `invokedDirectly` is exported and asserted
+ * below against a REAL symlink.
+ *
+ * `fileURLToPath` rather than `new URL(...).pathname`: the latter is not the
+ * documented conversion and is wrong independently of the symlink — it breaks on
+ * a Windows drive letter and on any percent-encoded character, and a single
+ * SPACE in a checkout path is enough to produce one.
+ */
+export function invokedDirectly(argv1, metaUrl) {
+  if (argv1 === undefined) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    // An unresolvable path cannot be this module; never guess YES, because a
+    // wrong YES runs the chain from a context that did not ask for it.
+    return false;
+  }
+}
+
+const INVOKED_DIRECTLY = invokedDirectly(process.argv[1], import.meta.url);
 
 try {
   if (!INVOKED_DIRECTLY) {

package/src/readiness.test.mjs

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
-import { packagesOwningPaths } from './readiness.mjs';
+import { invokedDirectly, packagesOwningPaths } from './readiness.mjs';
 
 /** A throwaway workspace: root + four members with different shapes. */
 async function fixture() {
@@ -20,6 +20,8 @@ async function fixture() {
   await write('packages/outer/package.json', JSON.stringify({ name: '@t/outer', scripts: { test: 'jest' } }));
   await write('packages/outer/nested/package.json', JSON.stringify({ name: '@t/nested', scripts: { test: 'jest' } }));
   await write('packages/broken/package.json', '{ this is not json');
+  // Declares typecheck+lint but NOT test — the orthogonal-proof case.
+  await write('packages/compiled/package.json', JSON.stringify({ name: '@t/compiled', scripts: { typecheck: 'tsc --noEmit', lint: 'eslint .' } }));
   return root;
 }
 
@@ -127,3 +129,74 @@ test('a path escaping the root owns nothing, even reaching a REAL sibling manife
     await fs.rm(sibling, { recursive: true, force: true });
   }
 });
+
+test('the owning scan is keyed on the SCRIPT, so the three stages see different sets', async () => {
+  const root = await fixture();
+  try {
+    const changed = ['packages/compiled/src/a.ts', 'packages/tested/src/a.ts'];
+    // `tests green != typecheck green` is not a slogan here — the two stages
+    // genuinely grade different packages, and a single set would silently run
+    // one package's suite and call the other proven.
+    assert.deepEqual(packagesOwningPaths(root, changed, 'test'), ['@t/tested']);
+    assert.deepEqual(packagesOwningPaths(root, changed, 'typecheck'), ['@t/compiled']);
+    assert.deepEqual(packagesOwningPaths(root, changed, 'lint'), ['@t/compiled']);
+    // Default stays `test`, so the original call shape is unchanged.
+    assert.deepEqual(packagesOwningPaths(root, changed), ['@t/tested']);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a script no package declares yields an EMPTY set, never the root', async () => {
+  const root = await fixture();
+  try {
+    // The root fixture declares `test`; asking for a script nothing declares must
+    // not fall back to it inside this function. The root FALLBACK is a decision
+    // made by the caller, which labels it repo-wide — folding it in here would
+    // report a repo-wide run as an affected one.
+    assert.deepEqual(packagesOwningPaths(root, ['packages/tested/src/a.ts'], 'nonexistent'), []);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+/**
+ * The guard that decides whether this module RUNS. It had no test, and it was
+ * wrong: it compared `process.argv[1]` against `new URL(import.meta.url).pathname`
+ * UNRESOLVED, so under pnpm's isolated linker — which symlinks
+ * `node_modules/@scope/<pkg>` at `node_modules/.pnpm/<pkg>@<ver>/...` — the same
+ * file compared unequal whenever the symlinked path was the one invoked. The
+ * branch taken then does nothing and the process exits 0: a chain reporting
+ * success without running, which is the exact defect this tool exists to prevent.
+ */
+test('the run guard sees through a SYMLINK — pnpm links every package this way', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'xema-guard-'));
+  try {
+    const real = path.join(root, 'real', 'readiness.mjs');
+    await fs.mkdir(path.dirname(real), { recursive: true });
+    await fs.writeFile(real, '// module\n', 'utf8');
+    const link = path.join(root, 'linked.mjs');
+    await fs.symlink(real, link);
+
+    const url = `file://${real}`;
+    // THE CASE THAT FAILED: invoked by the symlink, module loaded from the
+    // realpath. Unresolved string comparison says false; the answer is true.
+    assert.equal(invokedDirectly(link, url), true);
+    // And the plain case still holds.
+    assert.equal(invokedDirectly(real, url), true);
+
+    // A DIFFERENT file must stay false, or the guard would run the chain from
+    // any import — the opposite failure, and the louder one.
+    const other = path.join(root, 'other.mjs');
+    await fs.writeFile(other, '// not it\n', 'utf8');
+    assert.equal(invokedDirectly(other, url), false);
+
+    // No argv[1] at all (`node --eval`) is an import, never a run.
+    assert.equal(invokedDirectly(undefined, url), false);
+    // An unresolvable path must answer NO rather than throw: a wrong YES runs
+    // the whole chain from a context that never asked for it.
+    assert.equal(invokedDirectly(path.join(root, 'gone.mjs'), url), false);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});