@xemahq/repo-build-tooling 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.1.0",
+  "version": "0.2.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)",
@@ -21,13 +21,15 @@
     "README.md"
   ],
   "bin": {
-    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
+    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
+    "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs"
   },
   "exports": {
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs"
   }
 }

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

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// A `workspace:` range that the local package does NOT satisfy is not an
+// error — it is a SILENTLY DROPPED BUILD EDGE.
+//
+// `pnpm install` honours the lockfile, so the symlink is created either way and
+// the dependency resolves at runtime. But `pnpm -r run build` derives its
+// topological order from the CURRENT manifests: a dependency whose local
+// version falls outside the declared range is not counted as a workspace
+// dependency at all, so the consumer is scheduled in the FIRST batch —
+// before the dependency has emitted `dist/`.
+//
+// Nothing about that is visible locally. A developer tree almost always has a
+// stale `dist/` on disk from an earlier build, so `tsc` resolves the types and
+// the build passes. CI installs clean, and the consumer fails with
+// `TS2307: Cannot find module '@xemahq/…'` naming a package that is right
+// there in `node_modules` as a symlink — which reads as a broken install
+// rather than a misdeclared range, and sends you looking in the wrong place.
+//
+// That is exactly how it presented: `biome-activity-sdk` declared
+// `workspace:^0.2.0` against a client that had moved to `0.3.0`, and it was
+// the FIRST package pnpm tried to build.
+//
+// Fixing one occurrence is worthless — 58 manifests carried the same skew,
+// each a latent version of the same failure waiting for its package to be
+// scheduled first. Hence a check rather than a patch.
+//
+// `workspace:*` / `^` / `~` are always satisfied by definition and are not
+// examined.
+// ═══════════════════════════════════════════════════════════════════════════
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The repository being CHECKED, not the package doing the checking. As a
+// shipped bin this file lives in the consumer's node_modules, so resolving the
+// root from its own location would scan the package itself — 1 manifest, 0
+// findings, and a confident green over nothing.
+//
+// `process.cwd()` is where the consumer's script runs, and it must look like a
+// repo root: a bin that silently scans whatever directory it was invoked from
+// is the same defect one level up.
+const REPO_ROOT = process.cwd();
+if (!existsSync(join(REPO_ROOT, 'package.json'))) {
+  console.error(
+    `::error::${REPO_ROOT} has no package.json — run this from the repository root ` +
+      'so it scans the repository, not whatever directory it was invoked from.',
+  );
+  process.exit(1);
+}
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies'];
+
+// ── Minimal range satisfaction ────────────────────────────────────────────
+// Deliberately dependency-free: this runs in CI before any install in some
+// lanes, and a boundary check that needs `node_modules` to answer is a check
+// that cannot run when it matters most.
+const parse = (v) => v.split('-')[0].split('.').map(Number);
+const cmp = (a, b) => {
+  for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  return 0;
+};
+
+/** Does `version` satisfy `range`? Covers `^`, `~`, `>=` and exact. */
+export function satisfies(version, range) {
+  const v = parse(version);
+  if (range.startsWith('>=')) return cmp(v, parse(range.slice(2).trim())) >= 0;
+  const op = range[0] === '^' || range[0] === '~' ? range[0] : '=';
+  const base = parse(op === '=' ? range : range.slice(1));
+  if (op === '=') return cmp(v, base) === 0;
+  if (cmp(v, base) < 0) return false;
+  // `^0.y.z` pins the minor (npm's 0.x rule) — which is precisely why a client
+  // moving 0.2.0 → 0.3.0 falls out of `^0.2.0`. `~` always pins the minor.
+  if (op === '~' || base[0] === 0) return v[0] === base[0] && v[1] === base[1];
+  return v[0] === base[0];
+}
+
+function listManifests() {
+  return execFileSync(
+    'find',
+    [
+      REPO_ROOT,
+      '-name',
+      'package.json',
+      '-not',
+      '-path',
+      '*/node_modules/*',
+      '-not',
+      '-path',
+      '*/dist/*',
+    ],
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+  )
+    .split('\n')
+    .filter(Boolean);
+}
+
+/** Every `workspace:<range>` declaration the local package does not satisfy. */
+export function findViolations({ rewrite = false } = {}) {
+  const manifests = [];
+  const localVersions = new Map();
+  for (const file of listManifests()) {
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(file, 'utf8'));
+    } catch {
+      continue; // a malformed manifest is another check's problem, not this one's
+    }
+    if (pkg.name && pkg.version) localVersions.set(pkg.name, pkg.version);
+    manifests.push({ file, pkg });
+  }
+
+  const violations = [];
+  for (const { file, pkg } of manifests) {
+    let mutated = false;
+    for (const field of DEP_FIELDS) {
+      for (const [dep, spec] of Object.entries(pkg[field] ?? {})) {
+        if (typeof spec !== 'string' || !spec.startsWith('workspace:')) continue;
+        const range = spec.slice('workspace:'.length);
+        if (range === '*' || range === '^' || range === '~') continue;
+        const local = localVersions.get(dep);
+        if (!local) continue; // not a workspace package here; nothing to compare
+        if (satisfies(local, range)) continue;
+
+        violations.push({ file: relative(REPO_ROOT, file), dep, range, local });
+        if (rewrite) {
+          pkg[field][dep] = `workspace:${range[0] === '~' ? '~' : '^'}${local}`;
+          mutated = true;
+        }
+      }
+    }
+    if (mutated) writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+  return violations;
+}
+
+function main() {
+  const rewrite = process.argv.includes('--fix');
+  const violations = findViolations({ rewrite });
+
+  if (violations.length === 0) {
+    console.log(
+      'workspace ranges match their local packages — every build edge is visible to pnpm.',
+    );
+    return 0;
+  }
+
+  if (rewrite) {
+    console.log(`Rewrote ${violations.length} workspace range(s):`);
+    for (const v of violations) {
+      console.log(`  ${v.file}: ${v.dep} ${v.range} -> ${v.local}`);
+    }
+    console.log('\nRun `pnpm install` so the lockfile records the new specifiers.');
+    return 0;
+  }
+
+  console.error(
+    `${violations.length} workspace range(s) exclude their own local package.\n` +
+      'pnpm drops these edges from the build graph, so the consumer is built\n' +
+      'BEFORE its dependency emits dist/ — green locally on a stale dist/, and\n' +
+      'a TS2307 in CI that names a package which is present as a symlink.\n',
+  );
+  for (const v of violations) {
+    console.error(
+      `  ${v.file}\n      ${v.dep}  wants ${v.range}  local ${v.local}`,
+    );
+  }
+  console.error(
+    '\nFix: xema-check-workspace-ranges --fix && pnpm install',
+  );
+  return 1;
+}
+
+// Importing this module must not run the scan — the test suite imports it for
+// `satisfies` alone.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '.').href) {
+  process.exit(main());
+}

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

@@ -0,0 +1,54 @@
+/**
+ * The whole check rests on ONE predicate — `satisfies` — so that is what these
+ * tests attack.
+ *
+ * The failure this guard exists to prevent is subtle in exactly one place: npm's
+ * `^0.y.z` rule pins the MINOR, not the major. A `satisfies` that treats `^` as
+ * "same major" uniformly would call `0.3.0` a match for `^0.2.0` and report a
+ * clean scan over all 58 real violations — a check that reports green while
+ * examining everything and concluding nothing. Every 0.x case below is aimed at
+ * that specific wrong implementation.
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { 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
+  // consumer's range, silently dropping the build edge.
+  assert.equal(satisfies('0.3.0', '^0.2.0'), false);
+  assert.equal(satisfies('0.2.9', '^0.2.0'), true);
+  assert.equal(satisfies('0.2.0', '^0.2.1'), false); // below the floor
+  assert.equal(satisfies('1.0.0', '^0.2.0'), false);
+});
+
+test('^x.y.z (x > 0) pins the MAJOR', () => {
+  assert.equal(satisfies('1.9.3', '^1.2.0'), true);
+  assert.equal(satisfies('2.0.0', '^1.2.0'), false);
+  assert.equal(satisfies('1.1.0', '^1.2.0'), false); // below the floor
+});
+
+test('~ pins the minor at every major', () => {
+  assert.equal(satisfies('1.2.9', '~1.2.0'), true);
+  assert.equal(satisfies('1.3.0', '~1.2.0'), false);
+  assert.equal(satisfies('0.2.9', '~0.2.0'), true);
+  assert.equal(satisfies('0.3.0', '~0.2.0'), false);
+});
+
+test('>= is a floor with no ceiling', () => {
+  assert.equal(satisfies('7.5.0', '>=0.14.0'), true);
+  assert.equal(satisfies('0.13.0', '>=0.14.0'), false);
+});
+
+test('an exact range means exactly that version', () => {
+  assert.equal(satisfies('1.2.3', '1.2.3'), true);
+  assert.equal(satisfies('1.2.4', '1.2.3'), false);
+});
+
+test('a prerelease is compared on its release part, never string-wise', () => {
+  // `0.3.0-rc.1` must not read as "less than 0.3.0 therefore outside ^0.2.0
+  // is fine" — the range check has to reach the same verdict as `0.3.0`.
+  assert.equal(satisfies('0.3.0-rc.1', '^0.2.0'), false);
+  assert.equal(satisfies('0.2.5-rc.1', '^0.2.0'), true);
+});

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

@@ -133,6 +133,7 @@ import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 
 // Matches the two known leak shapes. We intentionally scope to `@xemahq`
 // because:
@@ -216,7 +217,7 @@ const PNPM_STORE_LEAK_REGEX = new RegExp(
 //
 // Mirrors `tooling/boundaries/check-no-deep-require-leaks.mjs` — if you change
 // one, change both.
-const LEAK_DETECTORS = [
+export const LEAK_DETECTORS = [
   // STRUCTURAL, and deliberately not a mirror of any rewrite regex above.
   //
   // The property is objective and shape-free: a require specifier in built
@@ -243,7 +244,7 @@ const LEAK_DETECTORS = [
 ];
 
 /** Every leak literal in `content`, de-duplicated, tagged with its shape. */
-function findLeaks(content) {
+export function findLeaks(content) {
   const found = [];
   for (const [shape, regex] of LEAK_DETECTORS) {
     const matches = content.match(regex);
@@ -321,8 +322,16 @@ function reExportsReach(entry, target, depth = 6, seen = new Set()) {
  * @param {string} subpath  physical path inside the package, e.g. `dist/agent-composition/lib/x`
  * @param {string} original the full leaked specifier, for the proof and the error
  */
+// NUL is the separator in the cache key because it cannot occur in a package
+// name or a subpath, so no two distinct specifiers can collide on a
+// concatenation. It MUST stay spelled as the unicode ESCAPE, never as a raw NUL
+// byte in the source: one raw byte makes every binary-skipping search tool
+// (ugrep, ripgrep, `grep -I`) classify the WHOLE file as binary and skip it
+// silently, and a file no search can read is a file no audit, no review and no
+// boundary check covers. Enforced by the aggregator boundary gate
+// `grep-readable-sources`.
 function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
-  const cacheKey = `${pkg}${subpath}`;
+  const cacheKey = `${pkg}\u0000${subpath}`;
   if (specifierCache.has(cacheKey)) return specifierCache.get(cacheKey);
 
   let target;
@@ -711,6 +720,16 @@ async function main() {
   }
 }
 
+// Importing this module gives you `findLeaks` / `LEAK_DETECTORS` and runs
+// nothing. The aggregator's post-build leak sweep imports the detector from
+// here rather than keeping its own copy of the regexes — it HAD its own copy,
+// missing two shapes, and reported "clean, 12052 files scanned" over 474 real
+// leaks. One definition of what a leak is, or the second one is decoration.
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
 main().catch((err) => {
   process.stderr.write(
     `scrub-swagger-plugin-paths: FAILED — ${
@@ -719,3 +738,4 @@ main().catch((err) => {
   );
   process.exit(1);
 });
+}