@xemahq/repo-build-tooling 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.2.3",
+  "version": "0.3.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)",
@@ -17,18 +17,21 @@
   },
   "type": "module",
   "files": [
-    "README.md"
+    "README.md",
+    "src"
   ],
   "bin": {
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
-    "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs"
+    "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
+    "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs"
   },
   "exports": {
-    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
+    "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
+    "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./package.json": "./package.json",
-    "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs"
+    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs"
   }
 }

package/src/check-no-vendored-deps.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// A `workspace:` range for a package this repo does NOT own is a VENDORED
+// UPSTREAM DEP: the name resolves to a local directory instead of the registry
+// version the rest of the fleet installs. Two copies of one class, one of them
+// invisible to every version gate, because a lockfile that never resolved the
+// name has nothing to compare.
+//
+// ── Why this is one shared bin and not four copies ──
+//
+// It was four: xema-kernel-sdk, xema-kernel-contracts, xema-biome-sdk and
+// xema-runtime-core each carried `tooling/boundaries/check-no-vendored-deps.mjs`.
+// All four asserted the IDENTICAL predicate — byte-equivalent modulo quote
+// style — and differed only in how they walked `packages/`. That is not
+// per-repo configuration: all four `pnpm-workspace.yaml` files declare the same
+// two globs, so there was nothing to configure and three of the four traversals
+// were elaborations nobody needed.
+//
+// They had also drifted in a way that MATTERS. xema-kernel-contracts' copy
+// recursed without bound and without stopping at a package leaf, so applied to
+// xema-biome-sdk's tree it ingested two TEST FIXTURES as locally-owned packages
+// — widening the allowed set, latent rather than live only because both
+// fixtures happen to declare registry ranges today. Nothing bound the four
+// copies to each other; `check-carved-lib-parity` covers `lib/` helpers, not
+// gates.
+//
+// ── The vacuous-green hole, fixed here ──
+//
+// All four copies guarded that `packages/` EXISTS and never that any manifest
+// was FOUND. A directory rename below it, or a layout change, and every one of
+// them printed `OK: … (0 local packages scanned)` and exited 0 — green while
+// executing nothing, this fleet's most-repeated defect. The two shallow
+// traversals were precisely the ones a layout change would silently empty.
+// `assertNonEmptyCorpus` below refuses a zero-manifest scan.
+//
+// Usage (from the repository root):
+//   xema-check-no-vendored-deps
+// ═══════════════════════════════════════════════════════════════════════════
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies'];
+
+/**
+ * The DEPTHS at which a workspace manifest may sit, derived from
+ * `pnpm-workspace.yaml` rather than assumed.
+ *
+ * Deriving is what stops the kernel-contracts defect recurring: an unbounded
+ * walk ingests a `test/fixtures/**\/package.json` as a locally-owned package,
+ * which WIDENS the allowed set — the one direction a gate must never drift in.
+ * A glob of `packages/*` admits `packages/<a>/package.json` (2 segments below
+ * the root); `packages/*\/*` admits 3.
+ *
+ * Returns null when the file declares no `packages/`-rooted glob at all, which
+ * the caller treats as "this repo is not shaped for this check" rather than as
+ * an empty result.
+ *
+ * The depth is `find`'s, i.e. levels BELOW the `packages` start path, and it
+ * equals the glob's segment count: `packages/*` admits `packages/a/package.json`
+ * at depth 2, `packages/*\/*` admits `packages/a/b/package.json` at depth 3.
+ *
+ * Written as `length + 1` first, which passed every repo — because BOTH entries
+ * were off by one and the two ranges overlapped on a tree whose packages all
+ * sit at one level. The counts matched the four incumbent gates exactly, which
+ * is precisely what made it look right. A repo with a manifest directly at
+ * `packages/<name>/package.json` would have been silently skipped, and a
+ * narrowed scan is the one failure this check exists to prevent.
+ */
+export function manifestDepthsFor(workspaceYaml) {
+  const depths = new Set();
+  for (const line of workspaceYaml.split('\n')) {
+    const m = line.match(/^\s*-\s*['"]?(packages\/[^'"#\s]*)['"]?\s*$/);
+    if (!m) continue;
+    depths.add(m[1].split('/').length);
+  }
+  return depths.size > 0 ? [...depths].sort((a, b) => a - b) : null;
+}
+
+/**
+ * Every manifest at exactly the declared depths. `find` rather than a hand
+ * walk, for the same reason the sibling check uses it: no dependency, and the
+ * depth bounds are expressed once instead of reimplemented per level.
+ */
+function listManifests(repoRoot, depths) {
+  const out = [];
+  for (const depth of depths) {
+    let stdout;
+    try {
+      stdout = execFileSync(
+        'find',
+        [
+          'packages',
+          '-mindepth', String(depth),
+          '-maxdepth', String(depth),
+          '-name', 'package.json',
+          '-not', '-path', '*/node_modules/*',
+          '-not', '-path', '*/dist/*',
+        ],
+        { cwd: repoRoot, encoding: 'utf8' },
+      );
+    } catch {
+      continue;
+    }
+    for (const line of stdout.split('\n')) if (line.trim()) out.push(line.trim());
+  }
+  return [...new Set(out)].sort();
+}
+
+/**
+ * The finding set. Pure over its inputs so it is testable without a tree.
+ *
+ * @param {Array<{path:string, manifest:object}>} manifests
+ * @returns {Array<{path:string, field:string, depName:string, depRange:string}>}
+ */
+export function findVendoredDeps(manifests) {
+  const localPackageNames = new Set(
+    manifests.map(({ manifest }) => manifest.name).filter(Boolean),
+  );
+  const offenders = [];
+  for (const { path, manifest } of manifests) {
+    for (const field of DEP_FIELDS) {
+      const deps = manifest[field];
+      if (!deps) continue;
+      for (const [depName, depRange] of Object.entries(deps)) {
+        if (typeof depRange !== 'string') continue;
+        if (!depRange.startsWith('workspace:')) continue;
+        if (localPackageNames.has(depName)) continue;
+        offenders.push({ path, field, depName, depRange });
+      }
+    }
+  }
+  return offenders;
+}
+
+/**
+ * A corpus of zero manifests is a FAILURE, never a pass.
+ *
+ * This is the assertion all four predecessors lacked. `packages/` existing says
+ * nothing about whether anything was read, and a check that reports OK over an
+ * empty scan is worse than no check because it reads as protection in review.
+ */
+function assertNonEmptyCorpus(count, repoRoot, depths) {
+  if (count > 0) return null;
+  return (
+    `found ZERO package manifests under ${join(repoRoot, 'packages')} at the depth(s) ` +
+    `${depths.join(', ')} declared by pnpm-workspace.yaml.\n` +
+    'An empty scan must never read as a passing one. Either the workspace globs and the ' +
+    'tree have diverged, or this check is pointed at the wrong root.'
+  );
+}
+
+export function main() {
+  const repoRoot = process.cwd();
+  if (!existsSync(join(repoRoot, 'package.json'))) {
+    console.error(
+      `::error::${repoRoot} has no package.json — run this from the repository root ` +
+        'so it scans the repository, not whatever directory it was invoked from.',
+    );
+    return 1;
+  }
+
+  const wsPath = join(repoRoot, 'pnpm-workspace.yaml');
+  if (!existsSync(wsPath)) {
+    console.error(`::error::no pnpm-workspace.yaml at ${repoRoot}; cannot derive the scan depth.`);
+    return 1;
+  }
+  const depths = manifestDepthsFor(readFileSync(wsPath, 'utf8'));
+  if (depths === null) {
+    console.error(
+      `::error::pnpm-workspace.yaml at ${repoRoot} declares no \`packages/\` glob. ` +
+        'This check asserts a property of that tree; it must not silently pass over its absence.',
+    );
+    return 1;
+  }
+
+  const manifests = [];
+  for (const rel of listManifests(repoRoot, depths)) {
+    try {
+      manifests.push({ path: rel, manifest: JSON.parse(readFileSync(join(repoRoot, rel), 'utf8')) });
+    } catch (error) {
+      console.error(`::error::${rel} is not readable JSON: ${error.message}`);
+      return 1;
+    }
+  }
+
+  const empty = assertNonEmptyCorpus(manifests.length, repoRoot, depths);
+  if (empty) {
+    console.error(`::error::${empty}`);
+    return 1;
+  }
+
+  const offenders = findVendoredDeps(manifests);
+  if (offenders.length > 0) {
+    console.error('Vendored upstream deps detected (must use the registry version):');
+    for (const o of offenders) {
+      console.error(`  ${o.path}  ${o.field}.${o.depName} = ${o.depRange}`);
+    }
+    console.error(
+      '\nA `workspace:` range for a package this repo does not own resolves to a local ' +
+        'directory instead of the registry version the rest of the fleet installs.',
+    );
+    return 1;
+  }
+
+  console.log(
+    `OK: no vendored upstream workspace deps (${manifests.length} local packages scanned ` +
+      `at depth ${depths.join(', ')})`,
+  );
+  return 0;
+}
+
+// The sibling `xema-check-workspace-ranges` documents why this guard is written
+// with `realpathSync`: invoked through a pnpm bin shim, `process.argv[1]` is the
+// SYMLINK, so a naive `import.meta.url === pathToFileURL(argv[1]).href` is false
+// and the bin prints nothing and exits 0. That hole shipped, and it was
+// invisible in carved CI — which installs the published tarball, where argv[1]
+// is already a real path. Same shape, same treatment.
+const invokedPath = process.argv[1];
+let invokedRealPath = null;
+if (typeof invokedPath === 'string' && invokedPath.length > 0) {
+  try {
+    invokedRealPath = realpathSync(invokedPath);
+  } catch {
+    invokedRealPath = null;
+  }
+}
+if (invokedRealPath !== null && import.meta.url === pathToFileURL(invokedRealPath).href) {
+  process.exit(main());
+}

package/src/check-no-vendored-deps.test.mjs

@@ -0,0 +1,103 @@
+import { deepStrictEqual, strictEqual } from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { findVendoredDeps, manifestDepthsFor } from './check-no-vendored-deps.mjs';
+
+// ── manifestDepthsFor ─────────────────────────────────────────────────────
+// The depth is `find`'s: levels BELOW the `packages` start path. It equals the
+// glob's segment count. Both cases below are pinned because the first draft
+// used `length + 1` and PASSED on all four real repositories — the two entries
+// were each off by one and their ranges overlapped on a tree whose packages all
+// sit at one level. Matching counts is exactly what made the bug invisible.
+
+test('a one-level glob admits packages/<name>/package.json at depth 2', () => {
+  deepStrictEqual(manifestDepthsFor("packages:\n  - 'packages/*'\n"), [2]);
+});
+
+test('a two-level glob admits packages/<a>/<b>/package.json at depth 3', () => {
+  deepStrictEqual(manifestDepthsFor("packages:\n  - 'packages/*/*'\n"), [3]);
+});
+
+test('both globs together admit both depths, sorted', () => {
+  deepStrictEqual(
+    manifestDepthsFor("packages:\n  - 'packages/*'\n  - 'packages/*/*'\n"),
+    [2, 3],
+  );
+});
+
+test('a repo declaring no packages/ glob returns null, never an empty scan', () => {
+  // null is "not shaped for this check", which the caller REFUSES. Returning []
+  // would let it scan nothing and report OK — the defect this file replaces.
+  strictEqual(manifestDepthsFor("packages:\n  - 'apps/*'\n"), null);
+});
+
+test('unquoted and double-quoted globs parse identically', () => {
+  deepStrictEqual(manifestDepthsFor('packages:\n  - packages/*\n'), [2]);
+  deepStrictEqual(manifestDepthsFor('packages:\n  - "packages/*/*"\n'), [3]);
+});
+
+// ── findVendoredDeps ──────────────────────────────────────────────────────
+
+const local = (name, deps) => ({ path: `packages/${name}/package.json`, manifest: { name, ...deps } });
+
+test('a workspace: range for a package this repo OWNS is fine', () => {
+  const found = findVendoredDeps([
+    local('@x/a', { dependencies: { '@x/b': 'workspace:*' } }),
+    local('@x/b', {}),
+  ]);
+  deepStrictEqual(found, []);
+});
+
+test('a workspace: range for a package this repo does NOT own is a finding', () => {
+  const found = findVendoredDeps([
+    local('@x/a', { dependencies: { '@upstream/c': 'workspace:*' } }),
+  ]);
+  strictEqual(found.length, 1);
+  strictEqual(found[0].depName, '@upstream/c');
+  strictEqual(found[0].field, 'dependencies');
+});
+
+test('all three dependency fields are examined', () => {
+  const found = findVendoredDeps([
+    local('@x/a', {
+      dependencies: { '@u/one': 'workspace:*' },
+      devDependencies: { '@u/two': 'workspace:^1.0.0' },
+      peerDependencies: { '@u/three': 'workspace:~2.0.0' },
+    }),
+  ]);
+  deepStrictEqual(found.map((f) => f.field).sort(), [
+    'dependencies', 'devDependencies', 'peerDependencies',
+  ]);
+});
+
+test('a registry range is never a finding, whatever it names', () => {
+  deepStrictEqual(
+    findVendoredDeps([local('@x/a', { dependencies: { '@upstream/c': '^1.2.3' } })]),
+    [],
+  );
+});
+
+test('a non-string range is skipped rather than crashing the run', () => {
+  deepStrictEqual(
+    findVendoredDeps([local('@x/a', { dependencies: { '@u/c': null } })]),
+    [],
+  );
+});
+
+test('a fixture ingested as a local package WIDENS the allowed set', () => {
+  // The measured xema-kernel-contracts defect, pinned as behaviour rather than
+  // as prose: its unbounded walk ingested two test fixtures under
+  // packages/*/*/test/fixtures/, and a fixture whose name matches a declared
+  // dependency makes a real finding disappear. The depth bound is what stops
+  // it; this asserts the CONSEQUENCE so the bound cannot be relaxed silently.
+  const withoutFixture = findVendoredDeps([
+    local('@x/a', { dependencies: { '@u/fixture': 'workspace:*' } }),
+  ]);
+  strictEqual(withoutFixture.length, 1, 'the finding exists when the fixture is out of scope');
+
+  const withFixture = findVendoredDeps([
+    local('@x/a', { dependencies: { '@u/fixture': 'workspace:*' } }),
+    { path: 'packages/a/test/fixtures/f/package.json', manifest: { name: '@u/fixture' } },
+  ]);
+  strictEqual(withFixture.length, 0, 'ingesting the fixture SILENCES it — the widening');
+});

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);
+});