@xemahq/repo-build-tooling 0.7.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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,7 +62,8 @@
  * honestly.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { existsSync, readdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
@@ -228,6 +229,38 @@ function exportsNamedByRefusal(output) {
   return [...named];
 }
 
+/** Tracked-or-untracked paths under `dir` git reports as dirty, as a Set of `XY path` lines. */
+function trackedDirtyPaths(dir) {
+  try {
+    return new Set(
+      sh(['git', 'status', '--porcelain', '--untracked-files=all', '--', dir], { capture: true })
+        .split('\n')
+        .filter(Boolean),
+    );
+  } catch {
+    return new Set(); // not a git checkout: nothing can be restored, and nothing is claimed
+  }
+}
+
+/**
+ * Put back what a refused regeneration wrote: every path under `packages/clients`
+ * that is dirty NOW and was not dirty BEFORE the attempt. Tracked files return
+ * to HEAD; files the refusal created are removed. Nothing that was already
+ * dirty before the attempt is touched — that is somebody's in-flight work.
+ */
+export function newlyDirtyPaths(before, after) {
+  return [...after].filter((line) => !before.has(line));
+}
+
+function restoreWhatTheRefusalWrote(dirtyBefore) {
+  const lines = newlyDirtyPaths(dirtyBefore, trackedDirtyPaths('packages/clients'));
+  const created = lines.filter((l) => l.startsWith('??')).map((l) => l.slice(3));
+  const modified = lines.filter((l) => !l.startsWith('??')).map((l) => l.slice(3));
+  if (modified.length > 0) sh(['git', 'checkout', '--', ...modified], { capture: true });
+  for (const rel of created) rmSync(path.join(ROOT, rel), { force: true });
+  return [...modified, ...created];
+}
+
 function sh(argv, { capture = false, env } = {}) {
   return execFileSync(argv[0], argv.slice(1), {
     cwd: ROOT,
@@ -252,6 +285,13 @@ function servicesWith(script) {
   }
   const names = [];
   for (const entry of Array.isArray(parsed) ? parsed : [parsed]) {
+    // The ROOT is not a service. A root `client:generate: turbo run
+    // client:generate` is an AGGREGATE over every service, so running it here
+    // regenerates all of them at once, turbo-prefixes the one refusal that
+    // matters, and then applies a recorded decision to services it was never
+    // recorded for. Measured 2026-09-20 in xema-community. The per-service
+    // loop below is the whole point: a failure NAMES the service.
+    if (path.resolve(entry.path ?? '') === ROOT) continue;
     const manifest = path.join(entry.path ?? '', 'package.json');
     if (!existsSync(manifest)) continue;
     try {
@@ -376,51 +416,156 @@ export function packagesOwningPaths(root, relPaths, script = 'test') {
  * largest repository here, and CI owns it. What this owns is "the thing I just
  * edited still passes its own proofs".
  */
+/**
+ * The DECISION for one affected stage, pure over its inputs so it is testable.
+ *
+ * Four outcomes, and the first is the one this used to get wrong:
+ *
+ *   - `workspace`   — there is NO branch point (`origin/develop` and
+ *                     `origin/main` are both unfetched, as in a scratch export
+ *                     or an archive). This used to SKIP, print "fetch, or run
+ *                     this by hand", and let the run end on "converged — safe to
+ *                     push". Measured 2026-09-20 in a scratch export: typecheck,
+ *                     lint AND tests all skipped, exit 0, banner green — the
+ *                     "reports green while executing nothing" shape this fleet
+ *                     names as its most-repeated defect, in the one tool written
+ *                     to end it. Without a diff there is no affected set, so the
+ *                     honest scope is the WHOLE repository: the root script when
+ *                     the root declares one (a root `lint` or `typecheck` covers
+ *                     every member), else every member declaring it — which is
+ *                     exactly what CI runs.
+ *   - `affected`    — the changed paths are owned by members declaring it.
+ *   - `root`        — no changed member declares it but the root does: run it
+ *                     REPO-WIDE, labelled, because skipping would drop a proof.
+ *   - `inapplicable`— nothing declares it. Genuinely nothing to run.
+ */
+export function affectedStagePlan({ base, paths, packages, rootDeclares }) {
+  if (!base) return { mode: 'workspace', viaRoot: rootDeclares };
+  if (packages.length > 0) return { mode: 'affected', packages };
+  if (paths.length > 0 && rootDeclares) return { mode: 'root' };
+  return { mode: 'inapplicable' };
+}
+
 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 this by hand.',
-    );
-    return;
-  }
-  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) declaring \`${script}\``,
-  );
-  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;
+  const packages = base ? packagesOwningPaths(ROOT, paths, script) : [];
+  const plan = affectedStagePlan({
+    base,
+    paths,
+    packages,
+    rootDeclares: Boolean(scripts[script]),
+  });
+  switch (plan.mode) {
+    case 'workspace':
+      console.log(
+        '  no branch point — neither origin/develop nor origin/main is fetched here,\n' +
+          '  so there is no affected set to derive. Running REPO-WIDE instead, which\n' +
+          '  is what CI runs; this is reported as repo-wide, never as affected.',
+      );
+      if (plan.viaRoot) sh(['pnpm', 'run', script]);
+      else sh(['pnpm', '-r', '--if-present', 'run', script]);
+      return;
+    case 'affected':
+      // 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)} -> ` +
+          `${plan.packages.length} package(s) declaring \`${script}\``,
+      );
+      for (const name of plan.packages) console.log(`    - ${name}`);
+      for (const name of plan.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;
+    case 'root':
+      // 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.
+      console.log(
+        `  ${paths.length} changed path(s) since ${base.slice(0, 9)}; 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;
+    default:
+      console.log(
+        `  nothing to run — no changed package declares \`${script}\` and the root\n` +
+          '  declares none either, so this stage is genuinely inapplicable here.',
+      );
   }
-  // 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]) {
+}
+
+
+/**
+ * Publishability — DELEGATED to the checker that already owns the verdict.
+ *
+ * Every publishing repository declares `verify:release-readiness` as
+ * `xema-publish-packages --check`: it packs every public package and validates
+ * the tarball offline — identity, source binding, access, resolved ranges, entry
+ * points — and CI runs that exact command after build. It never contacts the
+ * registry and never uploads, so it is the same proof in the same built state,
+ * with one more caller.
+ *
+ * This is deliberately NOT a readiness-local predicate. A first version of this
+ * tool omitted publishability on the reasoning that deciding whether a change
+ * OWES a changeset needs packed bytes compared to the registry, which only the
+ * publisher can do — true, and a false dichotomy: the choice was never "duplicate
+ * the publisher" or "omit the proof". The owning checker was already exposed as
+ * a root script in all six repositories, so the correct stage is one call to it.
+ * One authority, two callers.
+ *
+ * It runs LAST, after the generators and the affected stages, because it packs
+ * what is on disk: a tarball packed before `build` grades stale `dist/`. And it
+ * SKIPS — printed, never silently — in a repository that declares no such script,
+ * because there the fact is genuinely inapplicable rather than unchecked.
+ *
+ * If this checker ever behaves badly for a local call, the fix is to that shared
+ * checker, where CI benefits too. Never a weaker copy here.
+ */
+function runReleaseReadiness() {
+  console.log('\n=== release-readiness — the tarballs this tree would publish ===');
+  if (!scripts['verify:release-readiness']) {
     console.log(
-      `  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.',
+      '  SKIPPED — this repository declares no `verify:release-readiness`, so it\n' +
+        '  publishes nothing from here and there is no tarball to grade.',
     );
-    sh(['pnpm', 'run', script]);
     return;
   }
+  // This runs BEFORE the commit, over the clients and ledgers the stages above
+  // just regenerated — so the checker's committed-tree refusal would report
+  // every package this run touched as NOT JUDGED, i.e. red exactly when
+  // readiness did its job. `--check --working-tree` (release-policy >= 12.2.0)
+  // grades the bytes the next commit would pack; an older checker is called
+  // without it and says so, rather than being passed a flag it refuses.
+  const flag = releasePolicySupportsWorkingTree() ? ['--working-tree'] : [];
   console.log(
-    `  nothing to run — no changed package declares \`${script}\` and the root\n` +
-      '  declares none either, so this stage is genuinely inapplicable here.',
+    `  delegating to \`pnpm verify:release-readiness${flag.length ? ' --working-tree' : ''}\` — the checker CI runs` +
+      (flag.length
+        ? ''
+        : '\n  (the installed @xemahq/release-policy predates --working-tree; packages this run\n' +
+          '  regenerated will read NOT JUDGED until they are committed — raise it to >=12.2.0)'),
   );
+  sh(['pnpm', 'run', 'verify:release-readiness', ...flag]);
 }
 
+/** Does the checker this repository resolves accept `--check --working-tree`? Added in 12.2.0. */
+function releasePolicySupportsWorkingTree() {
+  try {
+    const manifest = createRequire(path.join(ROOT, 'package.json')).resolve(
+      '@xemahq/release-policy/package.json',
+    );
+    const [major, minor] = JSON.parse(readFileSync(manifest, 'utf8')).version.split('.').map(Number);
+    return major > 12 || (major === 12 && minor >= 2);
+  } catch {
+    return false;
+  }
+}
 
 function run() {
   // ── WHAT `--allow-dirty` INCLUDES, STATED RATHER THAN ASSUMED ─────────────
@@ -470,7 +615,10 @@ function run() {
   }
 
   const only = process.argv.find((a) => a.startsWith('--only='))?.slice('--only='.length);
-  console.log(`readiness: ${path.basename(ROOT)} — prisma -> build -> specs -> clients -> ledgers -> checks\n`);
+  console.log(
+    `readiness: ${path.basename(ROOT)} — ` +
+      'prisma -> build -> specs -> clients -> ledgers -> checks -> typecheck -> lint -> tests -> release-readiness\n',
+  );
 
   for (const step of STEPS) {
     if (only && only !== step.id) continue;
@@ -493,6 +641,7 @@ function run() {
     for (const name of services) {
       // One at a time on purpose: a failure must name the service, and a single
       // `--filter a --filter b` invocation reports only the first.
+      const dirtyBefore = trackedDirtyPaths('packages/clients');
       try {
         sh(['pnpm', '--filter', name, step.perService]);
       } catch (error) {
@@ -530,6 +679,20 @@ function run() {
           throw error;
         }
 
+        // The refused run may have REGENERATED before it refused — every
+        // `@xemahq/api-client-generator` below 1.0.2 does — and a re-run over
+        // the regenerated bytes compares them with themselves, holds the
+        // version line, and leaves changed client bytes under a served
+        // version. Measured 2026-09-20 in xema-operator and xema-store-api. So
+        // what the refusal wrote is put back to the committed bytes first; a
+        // refused run has produced nothing worth keeping.
+        const written = restoreWhatTheRefusalWrote(dirtyBefore);
+        if (written.length > 0) {
+          console.log(
+            `  ${name}: the refused run had already written ${written.length} client file(s); ` +
+              'restored to the committed bytes so the re-run sees the real change',
+          );
+        }
         // Not a retry loop: ONE re-run, driven by recorded data rather than by hope,
         // for a refusal whose every subject is already decided.
         console.log(
@@ -564,6 +727,8 @@ function run() {
     runAffectedStage(stage);
   }
 
+  runReleaseReadiness();
+
   console.log(
     '\nreadiness: converged. Every derived artifact describes the source beside it,\n' +
       'and the repository\'s own checks agree. Safe to push.',
@@ -612,12 +777,21 @@ try {
     // imported for its exports; nothing to do
   } else process.exit(run());
 } catch (error) {
+  // `sh` PIPES stderr so a generator refusal can be matched against a recorded
+  // decision — which means a failing stage's own explanation never reached the
+  // terminal. Measured 2026-09-20: `verify:release-readiness` refused a
+  // first-party override with a full paragraph naming the package and the
+  // remedy, and this report showed only "Command failed: pnpm run
+  // verify:release-readiness". The captured text is re-emitted here, whole.
+  const captured = typeof error?.stderr === 'string' ? error.stderr.trim() : '';
+  if (captured.length > 0) console.error(`\n${captured}\n`);
   console.error(
     `\nreadiness: FAILED at the step above. That is the ROOT cause — the steps after it\n` +
       'were not reached, so do not read their absence as a second failure.\n' +
       `\n  ${error?.message?.split('\n')[0] ?? error}\n` +
       '\nIf a CHECK failed rather than a generator, a dependency in\n' +
-      'prisma -> build -> specs -> clients -> ledgers was violated. Find it; do not re-run.\n',
+      'prisma -> build -> specs -> clients -> ledgers was violated. Find it; do not\n' +
+      're-run. A stage AFTER `checks` failing is a real finding about your change.\n',
   );
   process.exit(1);
 }

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 { invokedDirectly, packagesOwningPaths } from './readiness.mjs';
+import { affectedStagePlan, invokedDirectly, newlyDirtyPaths, packagesOwningPaths } from './readiness.mjs';
 
 /** A throwaway workspace: root + four members with different shapes. */
 async function fixture() {
@@ -178,7 +178,20 @@ test('the run guard sees through a SYMLINK — pnpm links every package this way
     const link = path.join(root, 'linked.mjs');
     await fs.symlink(real, link);
 
-    const url = `file://${real}`;
+    const realUrl = `file://${real}`;
+    const linkUrl = `file://${link}`;
+    // ALL FOUR SPELLINGS, because the bug was SPELLING-DEPENDENCE itself and a
+    // single-spelling test passes for whoever happens to write it. Measured: the
+    // two of us hit opposite answers from the same package at the same version,
+    // decided only by whether pnpm's `.bin` shim pointed at the symlink or at the
+    // `.pnpm/` realpath. Every combination names ONE file, so every one is true.
+    for (const argv of [real, link]) {
+      for (const url of [realUrl, linkUrl]) {
+        assert.equal(invokedDirectly(argv, url), true, `${argv} vs ${url}`);
+      }
+    }
+
+    const url = realUrl;
     // 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);
@@ -200,3 +213,48 @@ test('the run guard sees through a SYMLINK — pnpm links every package this way
     await fs.rm(root, { recursive: true, force: true });
   }
 });
+
+test('an affected stage with NO branch point runs REPO-WIDE — it never skips', () => {
+  // The defect this pins: a scratch export or an archive has no origin/develop,
+  // and the stage used to SKIP and let the run end "converged — safe to push"
+  // with typecheck, lint and tests all unexecuted. Green over nothing.
+  assert.deepEqual(
+    affectedStagePlan({ base: undefined, paths: [], packages: [], rootDeclares: true }),
+    { mode: 'workspace', viaRoot: true },
+  );
+  assert.deepEqual(
+    affectedStagePlan({ base: undefined, paths: [], packages: [], rootDeclares: false }),
+    { mode: 'workspace', viaRoot: false },
+  );
+  // A base with owning packages is the ordinary affected run.
+  assert.deepEqual(
+    affectedStagePlan({ base: 'abc', paths: ['a/x.ts'], packages: ['a'], rootDeclares: true }),
+    { mode: 'affected', packages: ['a'] },
+  );
+  // A base where only the ROOT declares the script runs the root, labelled.
+  assert.deepEqual(
+    affectedStagePlan({ base: 'abc', paths: ['README.md'], packages: [], rootDeclares: true }),
+    { mode: 'root' },
+  );
+  // Nothing declares it: the only outcome that runs nothing, and it needs a
+  // base to be trusted — without one it is the workspace run above.
+  assert.deepEqual(
+    affectedStagePlan({ base: 'abc', paths: ['README.md'], packages: [], rootDeclares: false }),
+    { mode: 'inapplicable' },
+  );
+});
+
+test('only what the REFUSED run wrote is restored — in-flight work that was dirty before is untouched', () => {
+  const before = new Set([' M packages/clients/a/src/models/x.ts', '?? packages/clients/a/src/models/draft.ts']);
+  const after = new Set([
+    ' M packages/clients/a/src/models/x.ts',          // was dirty before: somebody's work
+    '?? packages/clients/a/src/models/draft.ts',       // was there before: somebody's work
+    ' M packages/clients/a/src/models/problem.ts',     // the refusal wrote this
+    '?? packages/clients/b/src/endpoints/new.ts',      // and created this
+  ]);
+  assert.deepEqual(newlyDirtyPaths(before, after), [
+    ' M packages/clients/a/src/models/problem.ts',
+    '?? packages/clients/b/src/endpoints/new.ts',
+  ]);
+  assert.deepEqual(newlyDirtyPaths(new Set(), new Set()), []);
+});