@xemahq/repo-build-tooling 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.3.0",
+  "version": "0.5.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/check-no-vendored-deps.mjs

@@ -38,7 +38,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies'];

package/src/check-workspace-range-matches-local.mjs

@@ -75,19 +75,33 @@ export function satisfies(version, range) {
   return v[0] === base[0];
 }
 
-function listManifests() {
+/**
+ * Every `package.json` in the repository, EXCLUDING `node_modules`, `dist` and
+ * `.git`.
+ *
+ * `-prune` rather than `-not -path`, and the difference is not a style
+ * preference. A `-not -path` exclusion on a node_modules glob FILTERS the
+ * results while still
+ * DESCENDING into every one of them, so this walked hundreds of thousands of
+ * installed files to discard all of them — and, because it descended, it raced
+ * anything writing there. Measured 2026-09-18 on xema-base: the walk entered
+ * `node_modules/.cache/xema-declared-kernel/.staging-<version>-XXXX/`, a
+ * temporary directory another step deleted mid-walk, `find` exited non-zero,
+ * and `execFileSync` threw. The gate did not report a violation — it CRASHED,
+ * which reads in CI as a failing check rather than an absent one.
+ *
+ * Pruning cannot race what it never enters.
+ */
+export function listManifests(root = REPO_ROOT) {
   return execFileSync(
     'find',
     [
-      REPO_ROOT,
-      '-name',
-      'package.json',
-      '-not',
-      '-path',
-      '*/node_modules/*',
-      '-not',
-      '-path',
-      '*/dist/*',
+      root,
+      '(', '-name', 'node_modules', '-o', '-name', 'dist', '-o', '-name', '.git', ')',
+      '-prune',
+      '-o',
+      '-name', 'package.json',
+      '-print',
     ],
     { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
   )
@@ -131,16 +145,30 @@ export function findViolations({ rewrite = false } = {}) {
     }
     if (mutated) writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
   }
-  return violations;
+  return { violations, scanned: manifests.length };
 }
 
 function main() {
   const rewrite = process.argv.includes('--fix');
-  const violations = findViolations({ rewrite });
+  const { violations, scanned } = findViolations({ rewrite });
+
+  // A scan that read NOTHING and a scan that found nothing wrong print the
+  // same green and exit the same 0. Only the corpus separates them, so this
+  // refuses rather than reporting a pass it cannot justify. REPO_ROOT's own
+  // manifest is asserted to exist above, so zero here means the walk failed.
+  if (scanned === 0) {
+    console.error(
+      `::error::scanned 0 manifests under ${REPO_ROOT} — the walk found nothing, ` +
+        'not even this repository\'s own package.json. Refusing to report a pass ' +
+        'over an empty corpus.',
+    );
+    return 1;
+  }
 
   if (violations.length === 0) {
     console.log(
-      'workspace ranges match their local packages — every build edge is visible to pnpm.',
+      `workspace ranges match their local packages in all ${scanned} manifest(s) — ` +
+        'every build edge is visible to pnpm.',
     );
     return 0;
   }

package/src/check-workspace-range-matches-local.test.mjs

@@ -10,9 +10,12 @@
  * that specific wrong implementation.
  */
 import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
 import test from 'node:test';
 
-import { satisfies } from './check-workspace-range-matches-local.mjs';
+import { listManifests, satisfies } from './check-workspace-range-matches-local.mjs';
 
 test('^0.y.z pins the MINOR — the rule the whole check turns on', () => {
   // The real defect: a client moved 0.2.0 -> 0.3.0 and fell out of every
@@ -52,3 +55,51 @@ test('a prerelease is compared on its release part, never string-wise', () => {
   assert.equal(satisfies('0.3.0-rc.1', '^0.2.0'), false);
   assert.equal(satisfies('0.2.5-rc.1', '^0.2.0'), true);
 });
+
+// ── The WALK, not the predicate ───────────────────────────────────────────
+// A `-not -path` exclusion on a node_modules glob filters results while still
+// DESCENDING into
+// every one of them. That is not merely slow: it made the gate race a sibling
+// step that was deleting a temp directory under `node_modules`, so `find`
+// exited non-zero and the check CRASHED rather than reporting a violation.
+// A crash reads in CI as a failing check rather than an absent one.
+//
+// Two-sided on purpose. Asserting only that the pruned paths are absent would
+// also pass if the walk returned NOTHING — the empty-corpus failure this file
+// already warns about, one function over.
+test('listManifests does not DESCEND into node_modules — an untraversable dir there must not break the walk', () => {
+  const root = mkdtempSync(join(tmpdir(), 'xema-prune-'));
+  const blocked = join(root, 'node_modules', 'blocked');
+  try {
+    const write = (rel) => {
+      mkdirSync(join(root, dirname(rel)), { recursive: true });
+      writeFileSync(join(root, rel), '{"name":"x","version":"1.0.0"}\n');
+    };
+    write('package.json');
+    write('packages/real/package.json');
+    write('packages/real/dist/package.json');
+    write('node_modules/installed/package.json');
+
+    // Reproduces the real failure: a directory under node_modules the walk
+    // cannot traverse. A FILTERING walk descends, `find` exits non-zero on
+    // "Permission denied", and execFileSync THROWS -- the gate crashes instead
+    // of reporting a violation. A PRUNING walk never enters it.
+    //
+    // This is what the previous version of this test missed: `-not -path`
+    // filters the OUTPUT, so both walks return the identical set and an
+    // output assertion cannot tell them apart. Only descent is observable,
+    // and this is how you observe it.
+    mkdirSync(blocked, { recursive: true });
+    chmodSync(blocked, 0o000);
+
+    const found = listManifests(root).map((f) => relative(root, f)).sort();
+
+    // Control: the walk really ran and found the real manifests.
+    assert.deepEqual(found, ['package.json', 'packages/real/package.json']);
+    assert.equal(found.some((f) => f.includes('node_modules')), false);
+    assert.equal(found.some((f) => f.includes('dist')), false);
+  } finally {
+    try { chmodSync(blocked, 0o755); } catch { /* never created */ }
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/scrub-swagger-plugin-paths.mjs

@@ -26,7 +26,7 @@
 //       `node_modules/` but leaves the SECOND one inside the path,
 //       producing leaked emits like:
 //
-//         require("@xemahq/kernel-contracts/policy/node_modules/
+//         require("@xemahq/contracts/policy/node_modules/
 //                 @xemahq/kernel-contracts/execution-context/dist/lib/subject")
 //
 //       …which crashes the pod at boot with ERR_PACKAGE_PATH_NOT_EXPORTED
@@ -38,7 +38,7 @@
 //       via `@ApiProperty({ enum: ... })`, the plugin emits the
 //       declaration file path under the package's published layout:
 //
-//         require("@xemahq/kernel-contracts/capability/dist/lib/capability-grant")
+//         require("@xemahq/contracts/capability/dist/lib/capability-grant")
 //
 //       This crashes at boot with the same ERR_PACKAGE_PATH_NOT_EXPORTED
 //       whenever the contracts package's published `exports` map does NOT
@@ -438,6 +438,83 @@ async function* walk(dir) {
   }
 }
 
+// ── WHERE THE PLUGIN'S REQUIRES LIVE, AND WHY THAT IS THE WHOLE SCOPE ────────
+//
+// This file's own header states the scope: "Post-build sanitizer for
+// @nestjs/swagger plugin v11.x output", and "the swagger CLI plugin emits
+// `_OPENAPI_METADATA_FACTORY()` blocks that contain `require("<path>")` calls".
+// Every leak it exists to repair is therefore INSIDE such a block.
+//
+// Shape 2 did not honour that. It rewrote `require("@xemahq/<pkg>/dist/<rest>")`
+// ANYWHERE in the emitted file, on the assumption recorded above — "every
+// package they have ever matched exposes a root export". That assumption is
+// measurably false today, and a HAND-WRITTEN deep import compiles to exactly
+// the shape the regex matches, so it was rewritten too:
+//
+//     src:   import { RealmTokenVerifier }
+//              from '@xemahq/platform-common/dist/nestjs/auth/realm-token-verifier';
+//     dist:  const realm_token_verifier_1 = require("@xemahq/platform-common");
+//
+// The module loads, the binding is not on the root barrel, and the service dies
+// at DI time with "RealmTokenVerifier is not a constructor". That is what took
+// xema-shell-api's rollout down on 2026-09-17 — and every check was green,
+// because typecheck, jest and the pre-push gate all read the SOURCE, and
+// nothing executes the rewritten dist before the pod does.
+//
+// Measured across the four packages shape 2 matches in shipped source, asking
+// each published tarball whether its ROOT entry exports the symbol:
+//
+//     @xemahq/platform-common    RealmTokenVerifier              NOT on root
+//     @xemahq/biome-supply-chain CosignErrorCode                 NOT on root
+//     @xemahq/xema-service-nest  buildResourcePath               NOT on root
+//     @xemahq/biome-database-nest assertMigrationHistoryCompatible NOT on root
+//
+// so the blind rewrite was wrong for all four. (Only two reach a shipped dist:
+// xema-shell-api, which fired, and biome-host-api, which is armed on the
+// bundle-fetch ERROR path. The other nine occurrences are in tests, which run
+// from TypeScript and never see this rewriter.)
+//
+// The fix is a SCOPE correction, not more proof machinery: rewrite only what
+// the plugin emitted, and REFUSE anything else. `reExportsReach` cannot stand
+// in for this — it proves a module is REACHED, not that a BINDING is
+// re-exported, and `nestjs/index.js` requires `./auth` while re-exporting only
+// some of its names, so it would have called the bad rewrite provable.
+//
+// A refusal here is the whole point: it converts a production CrashLoopBackOff
+// into a build failure in the repository that wrote the import.
+function openApiFactoryRanges(src) {
+  const ranges = [];
+  const token = '_OPENAPI_METADATA_FACTORY';
+  let from = 0;
+  for (;;) {
+    const hit = src.indexOf(token, from);
+    if (hit === -1) break;
+    from = hit + token.length;
+    const open = src.indexOf('{', from);
+    if (open === -1) break;
+    // Brace-match. String and comment bodies inside a metadata factory are
+    // emitted by tsc and contain no unbalanced braces in practice; a miscount
+    // can only ever END the range early, which fails CLOSED (the require is
+    // then treated as hand-written and refused) rather than widening the
+    // rewrite to code the plugin did not emit.
+    let depth = 0;
+    let i = open;
+    for (; i < src.length; i += 1) {
+      if (src[i] === '{') depth += 1;
+      else if (src[i] === '}') {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    ranges.push([open, Math.min(i + 1, src.length)]);
+    from = i + 1;
+  }
+  return ranges;
+}
+
+const inAnyRange = (ranges, offset) =>
+  ranges.some(([start, end]) => offset >= start && offset < end);
+
 async function scrubFile(path) {
   const src = await readFile(path, 'utf8');
   let count = 0;
@@ -455,10 +532,35 @@ async function scrubFile(path) {
     count += 1;
     return `require("${kept}")`;
   });
-  out = out.replace(FLAT_LEAK_REGEX, (_match, pkg) => {
+  // Shape 2 is scoped to the plugin's own emits. Anything else matching this
+  // shape is a hand-written deep import, and rewriting it silently changes
+  // which module the service loads — see the note above `openApiFactoryRanges`.
+  const factoryRanges = openApiFactoryRanges(out);
+  const handWritten = [];
+  out = out.replace(FLAT_LEAK_REGEX, (match, pkg, offset) => {
+    if (!inAnyRange(factoryRanges, offset)) {
+      handWritten.push(match.slice('require("'.length, -2));
+      return match;
+    }
     count += 1;
     return `require("${pkg}")`;
   });
+  if (handWritten.length > 0) {
+    throw new ScrubFailure(
+      `${path}\n` +
+        `  ${handWritten.length} hand-written deep import(s) into a package's dist/:\n` +
+        handWritten.map((spec) => `    ${spec}`).join('\n') +
+        `\n\n  These are NOT swagger-plugin emits — they are outside every\n` +
+        `  _OPENAPI_METADATA_FACTORY block, so this rewriter is not entitled to\n` +
+        `  touch them. Rewriting one to the bare package specifier (which is what\n` +
+        `  this step used to do, silently) loads the package root instead, and any\n` +
+        `  binding the root barrel does not re-export becomes \`undefined\` at\n` +
+        `  runtime — a DI crash in the pod, with every build check green.\n\n` +
+        `  Fix the IMPORT, in source: use the package's public surface. If the\n` +
+        `  symbol is not on it, the package is missing an export — add it there\n` +
+        `  rather than reaching through dist/.`,
+    );
+  }
   out = out.replace(RELATIVE_WORKSPACE_REGEX, (_match, pkgName, subpath) => {
     count += 1;
     return `require("@xemahq/${pkgName}/${subpath}")`;
@@ -628,7 +730,7 @@ async function selfTest() {
         throw new Error(`self-test: detector missed the ${shape} shape: ${literal}`);
       }
     }
-    const clean = 'require("@xemahq/kernel-contracts");require("./local");require("../shared/util");';
+    const clean = 'require("@xemahq/contracts");require("./local");require("../shared/util");';
     if (findLeaks(clean).length !== 0) {
       throw new Error(`self-test: detector matched clean output: ${JSON.stringify(findLeaks(clean))}`);
     }
@@ -637,16 +739,57 @@ async function selfTest() {
     const green = join(root, 'green');
     await mkdir(green, { recursive: true });
     const greenFile = join(green, 'dto.js');
-    await writeFile(greenFile, `${samples[0][1]};\n`, 'utf8');
+    // The plugin emits its requires INSIDE `_OPENAPI_METADATA_FACTORY`, so the
+    // green fixture has to as well — a bare literal at top level is a
+    // HAND-WRITTEN import and is now refused, which is the point of the scope.
+    await writeFile(
+      greenFile,
+      `class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { x: { required: true, type: () => ${samples[0][1]} } };\n  }\n}\n`,
+      'utf8',
+    );
     const greenResult = await run([green]);
     if (greenResult.totalRewrites < 1) {
       throw new Error(`self-test: expected at least 1 rewrite, got ${greenResult.totalRewrites}`);
     }
+    // THE CASE THAT PINS THE SCOPE, both polarities in one fixture.
+    //
+    // Same package, same deep path, twice: once as the plugin emits it (inside
+    // `_OPENAPI_METADATA_FACTORY`) and once as tsc emits a hand-written
+    // `import ... from '@xemahq/<pkg>/dist/...'` (a top-level const). The
+    // rewriter must take the first and REFUSE the whole file for the second.
+    //
+    // Without this the fix is unpinned: the old blind pass rewrote both, and
+    // that is what put `require("@xemahq/platform-common")` into
+    // xema-shell-api's dist and crashlooped it in production with every build
+    // check green.
+    const mixed = join(root, 'mixed');
+    await mkdir(mixed, { recursive: true });
+    await writeFile(
+      join(mixed, 'dto.js'),
+      'const realm_token_verifier_1 = require("@xemahq/platform-common/dist/nestjs/auth/realm-token-verifier");\n' +
+        'class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n' +
+        '    return { x: { type: () => require("@xemahq/capability-contracts/dist/lib/capability-grant") } };\n  }\n}\n',
+      'utf8',
+    );
+    const refusal = await expectFailure('hand-written deep dist import', () => run([mixed]));
+    if (!refusal.message.includes('realm-token-verifier')) {
+      throw new Error(
+        `self-test: the refusal must NAME the offending specifier; got: ${refusal.message}`,
+      );
+    }
+    // And it must refuse the HAND-WRITTEN one, not the plugin's — if the scope
+    // check were inverted this assertion is what catches it.
+    if (refusal.message.includes('capability-grant')) {
+      throw new Error(
+        'self-test: the plugin-emitted require inside the factory was reported as hand-written — the scope test is inverted.',
+      );
+    }
+
     const greenAfter = await readFile(greenFile, 'utf8');
     // The NESTED pass unwraps to `@xemahq/subject-contracts/dist/lib/x`, which
     // the FLAT pass then reduces to the bare specifier — the two passes chain,
     // and the verification proves the chain terminated clean.
-    if (greenAfter.trim() !== 'require("@xemahq/subject-contracts");') {
+    if (!greenAfter.includes('require("@xemahq/subject-contracts")')) {
       throw new Error(`self-test: unexpected rewrite result: ${greenAfter.trim()}`);
     }
     if (findLeaks(greenAfter).length !== 0) {