@xemahq/repo-build-tooling 0.10.0 → 0.10.2

package/README.md

@@ -1,138 +1,46 @@
-# `@xemahq/repo-build-tooling`
-
-This package belongs to Layer 1 — dev-time build tooling shared by every Xema
-repository. Nothing here ever ships inside a service image; every consumer
-declares it as a `devDependency`.
-
-## Why it is a package and not a file
-
-It used to be a file — five byte-identical copies of one 700-line script, one
-per repository that needed it, kept honest by a boundary check that ran each
-copy's `--self-test`.
-
-That arrangement could not hold the invariant it existed for. A defect found in
-one copy is fixed in one copy; the other four keep shipping it until someone
-remembers. Exactly that happened: three of the five copies deliberately carried
-*less* behaviour than the other two (they detected a leak shape without
-rewriting it), which was a reasonable decision at the time and then became a
-permanent, undocumented divergence nobody re-examined. A parity check on N
-copies is a workaround for not having one artifact.
-
-## How the two resolution modes work
-
-This is the standard shape in this fleet, and getting it wrong is the single
-most common source of "green locally, red in CI":
-
-- **Inside the `xema-monorepo` aggregator**, the root `package.json`'s
-  `pnpm.overrides` maps `@xemahq/repo-build-tooling` to `workspace:*`, so it
-  resolves to this directory. Editing the tool and rebuilding a service in the
-  same checkout needs no publish, no version bump and no registry round-trip.
-- **Inside each independent repository's own CI**, there is no aggregator and no
-  sibling checkout. The declared semver range is what resolves, from npm.
-
-So the range in a consumer's `package.json` is the real contract, and the local
-link is a development convenience layered on top. A symbol added here is not
-available to a consumer until this package is published AND that consumer's
-range admits the new version — the aggregator will happily compile against the
-local source and tell you nothing.
-
-## Contents
-
-### `xema-scrub-swagger-paths <dist-dir> [<dist-dir>…]`
-
-Post-build sanitizer for `@nestjs/swagger` plugin output, and the verification
-step for the same property. The plugin writes `require()` literals into
-`_OPENAPI_METADATA_FACTORY()` at `nest build` time — they exist in no source
-file — so this is the only thing in the fleet that can see them, and it runs
-immediately after `nest build` in all 54 services that use the plugin.
-
-It rewrites specifiers that name the builder's private install layout into the
-target package's public specifier, then re-reads the output from disk and fails
-the build if any leak survives.
-
-The rewrite is **derived and proved**, never tabled: the replacement comes from
-the target package's own `exports` map, and is accepted only if the emitted
-re-export chain (read statically — package code is never executed) reaches the
-same module. It refuses rather than guesses. That matters because the two
-packages that leak most are opposites — `@xemahq/kernel-contracts` exports only
-`./*` and has no root export, so rewriting to the bare name would swap one crash
-for another, while `@xemahq/platform-common` exports both `.` and `./dist/*`.
-
-`--self-test` proves, on a scratch tree with no build and no fixtures, that a
-missing/empty/no-`.js` directory each FAIL, that the detector matches every leak
-shape and no clean literal, and that a residual leak fails the run. This step's
-failure mode is silence, so "0 leaks" and "0 files read" must never be
-indistinguishable.
-
-### `xema-composed-image <command>`
-
-The build-time half of a repository's composed-process image (the runtime half,
-the `xema-composed-process` host, is `@xemahq/xema-service-nest`'s). One image per
-build carries every composable platform service of the repository at one commit.
-
-- `members --write|--check` derives that set from the tracked biome manifests and
-  writes or verifies `infra/composed-process/image-build-inputs.json`. A member is a
-  `kind: service` with `scheduler: platform`; workers, jobs and runtime-scheduled
-  services never are. A service is left out, with its reason printed, when its
-  `src/main.ts` is not one top-level `void bootstrapXemaService(…)`, it has its own
-  `Dockerfile`, it bakes cross-repository inputs, or the canonical Dockerfile
-  installs a toolchain for it. Options say where the repository keeps those facts:
-  `--manifests <glob>` (repeatable, default `**/xema-biome.json`),
-  `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>` (both optional).
-- Inside the image build: `filters` and `dirs` name the members' closures,
-  `pins <committed-lockfile>` refuses a re-resolution that moves a registry pin,
-  `index <commit> --build-source <repo>` writes the member index the host reads
-  (graded by `@xemahq/contracts/process-topology`, resolved from the members) and
-  links the host bin, and `load` evaluates every member's entry through the host's
-  `readServiceEntry`. `--build-source` is the `repo` the repository's subjects carry
-  in an edition's image lock.
-
-- `coordinate --image-name <name>` is the image's release coordinate: the content tag
-  and whether GHCR already serves it (only 200 and 404 are answers). The tag is computed
-  ONLY by the repository's own `@xemahq/distribution-source-hash` (`xema-compute-image-tag`,
-  resolved from the repository root); the command refuses when it is not installed, and never
-  hashes anything itself. Environment: `SHA`, `REGISTRY`, `REGISTRY_ORG`, `REGISTRY_USER`,
-  `REGISTRY_TOKEN`, optional `TAG_ARGS_FILE`, `GITHUB_OUTPUT`. Outputs `image`, `content_tag`,
-  `exists`, `entry`. The registry check is also exported as `./ghcr-manifest`
-  (`ghcrManifestExists`, `acquireGhcrPullToken`).
-- `load-image <image>` runs the member-load check inside the shipped image (`docker run`), as its own user and `NODE_ENV`; `load` runs in the builder and cannot prove that.
-- `smoke-refusal <image> [--member <biomeId>/<componentKey>]x2` boots the pushed image
-  with two members on one port and fails unless the host refuses at the declaration, names
-  the collision, and constructs no member. Needs only `docker`.
-- `dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>`
-  renders `infra/composed-process/Dockerfile` from one template. The builder stage installs
-  this tool at the EXACT version (so the hashed image directory moves when the tool does),
-  runs every step above, and runs `load` last as `node` with `NODE_ENV=production`. Nothing here
-  ships in an image: the final stage copies `/monorepo` only.
-
-Every step refuses rather than skips. The tool has no dependencies: the host and
-the kernel schema are resolved from the members being built.
-
-### `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]`
-
-Generates the descriptors `@xemahq/xema-service-nest` boots from, out of the
-repository's own `xema-biome.json` manifests. For every `kind: service` component
-it writes `src/generated/<name>.bootstrap.generated.ts` (a `BiomeServiceDescriptor`),
-and for every `kind: worker` component `src/generated/<key>.worker-descriptor.generated.ts`
-(a `XemaWorkerDescriptor`; a `shared-oci-image` worker lands in the package of the
-component whose image it shares). Only packages that declare
-`@xemahq/xema-service-nest` are written to.
-
-`requirements.scaling.concurrency.maximumPerInstance` becomes
-`maximumConcurrentRequests` on a service and `maximumConcurrentActivities` on a
-worker. A component without a positive integer there is refused, naming the
-manifest and the component.
-
-`--check` writes nothing and fails on any drift. A run that finds no manifest, or no
-service or worker to generate, fails rather than reporting success. Run it from the
-repository root, or pass `--root`.
-
-## Scope boundary
-
-Dev-time tooling that **more than one repository** runs. Two rules keep it from
-becoming a junk drawer:
-
-- Nothing with a runtime consumer. If a service imports it at run time it is not
-  build tooling and belongs in an SDK package.
-- Nothing with a single consumer. A tool used by one repository stays in that
-  repository until a second one needs it.
+# @xemahq/repo-build-tooling
+
+> Dev-time build tooling shared by every Xema repository
+
+## Overview
+
+Command-line tools that more than one Xema repository runs at build or check time. Nothing here ships in a service image; consumers declare it as a `devDependency`.
+
+## When to use it
+
+- To run the shared build and readiness checks in a repository, locally or in CI.
+
+## Installation
+
+```bash
+pnpm add -D @xemahq/repo-build-tooling
+```
+
+## Usage
+
+```bash
+pnpm exec xema-readiness
+pnpm exec xema-service-bootstrap --check
+pnpm exec xema-scrub-swagger-paths dist
+```
+
+| Bin | What it does |
+| --- | --- |
+| `xema-readiness` | Runs the ordered checks between a source change and a push |
+| `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
+| `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
+| `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
+| `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
+
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--tooling-version`, `--copy`, `--cache-id` and `--build-source`. Run `xema-composed-image` with no arguments for the full usage.
+
+Every step refuses rather than skips. The package has no dependencies.
+
+## Resolution
+
+Inside the `xema-monorepo` aggregator, `@xemahq/repo-build-tooling` resolves to this directory through a workspace override. In an independent repository's CI it resolves from npm by the declared range, so a change here reaches a consumer only after it is published and the consumer's range admits it.
+
+## License
+
+Apache-2.0 &copy; Xema — [xema.dev](https://xema.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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)",
@@ -42,6 +42,6 @@
     "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 && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/ghcr-manifest.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:525d85f0cc251fa763bc18261159ae689b59c3465d9da0d3c9f6037445d68713"
+    "sourceDigest": "sha256:6e85c2039576c5febe254e42d36eef92248dd33a88a8f86416ff654ff36a2765"
   }
 }

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

@@ -167,12 +167,15 @@ const FLAT_LEAK_REGEX = new RegExp(
 // a relative path from the service source file back up to the workspace root
 // and down into the contracts package.  There is no `node_modules/` segment
 // so shapes 1 and 2 above never fire.
-// Capture group 1: package directory name (= npm name without @xemahq/ scope).
+// Capture group 1: relative path from the scrubbed file to the package directory.
 // Capture group 2: first path segment after dist/ = the subpath export name.
+// The public package name is NOT derived from the directory name or a fixed
+// scope: it is read from the target package's own package.json `name`, so
+// unscoped and differently-named workspace packages resolve correctly.
 // Scoped to paths that pass through `packages/`, `biomes/`, or `kernel/` to
 // avoid false-positive matches on intra-service relative requires.
 const RELATIVE_WORKSPACE_REGEX = new RegExp(
-  `require\\("(?:\\.\\./)+(?:packages|biomes|kernel)/(?:[a-z0-9][a-z0-9.-]*/)*([a-z0-9][a-z0-9.-]*)/dist/([a-z0-9][a-z0-9-]*)(?:/[^"]*)?"\\)`,
+  `require\\("((?:\\.\\./)+(?:packages|biomes|kernel)/(?:[a-z0-9][a-z0-9.-]*/)*[a-z0-9][a-z0-9.-]*)/dist/([a-z0-9][a-z0-9-]*)(?:/[^"]*)?"\\)`,
   'g',
 );
 
@@ -416,6 +419,28 @@ function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
   );
 }
 
+/**
+ * The npm name of the workspace package at `packageDir`, read from the
+ * package.json AT that directory. No walk-up: an ancestor's manifest (usually
+ * the workspace root) names a different package. Never a fixed scope or the
+ * directory name.
+ */
+function packageNameAt(packageDir, original) {
+  const manifest = join(packageDir, 'package.json');
+  let raw;
+  try {
+    raw = readFileSync(manifest, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err;
+    throw new ScrubFailure(`${packageDir} has no package.json, so no specifier can be derived for\n  ${original}`);
+  }
+  const { name } = JSON.parse(raw);
+  if (typeof name !== 'string' || name === '') {
+    throw new ScrubFailure(`${manifest} has no "name", so no specifier can be derived for\n  ${original}`);
+  }
+  return name;
+}
+
 async function* walk(dir) {
   let entries;
   try {
@@ -561,9 +586,10 @@ async function scrubFile(path) {
         `  rather than reaching through dist/.`,
     );
   }
-  out = out.replace(RELATIVE_WORKSPACE_REGEX, (_match, pkgName, subpath) => {
+  out = out.replace(RELATIVE_WORKSPACE_REGEX, (match, relPackageDir, subpath) => {
     count += 1;
-    return `require("@xemahq/${pkgName}/${subpath}")`;
+    const name = packageNameAt(resolve(dirname(path), relPackageDir), match);
+    return `require("${name}/${subpath}")`;
   });
   if (count > 0) {
     await writeFile(path, out, 'utf8');
@@ -796,6 +822,59 @@ async function selfTest() {
       throw new Error(`self-test: rewritten file still leaks: ${greenAfter}`);
     }
 
+    // 4b. RELATIVE-WORKSPACE — the rewritten specifier is the target package's
+    // own manifest `name`: scoped, unscoped, and name != directory.
+    const ws = join(root, 'ws');
+    const pkgs = [
+      ['packages/contracts/scoped-dir', '@xemahq/scoped-dir'],
+      ['packages/contracts/plain-dir', 'plain-contract'],
+      ['packages/contracts/other-dir', '@xemahq/renamed'],
+    ];
+    for (const [dir, name] of pkgs) {
+      await mkdir(join(ws, dir, 'dist/lib'), { recursive: true });
+      await writeFile(join(ws, dir, 'package.json'), JSON.stringify({ name }), 'utf8');
+    }
+    await mkdir(join(ws, 'services/svc/dist'), { recursive: true });
+    const wsFile = join(ws, 'services/svc/dist/dto.js');
+    const relOf = (dir) => `../../../${dir}/dist/lib/x`;
+    await writeFile(
+      wsFile,
+      `class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { ${pkgs
+        .map(([dir], i) => `k${i}: () => require("${relOf(dir)}")`)
+        .join(', ')} };\n  }\n}\n`,
+      'utf8',
+    );
+    await run([join(ws, 'services/svc/dist')]);
+    const wsAfter = await readFile(wsFile, 'utf8');
+    for (const expected of ['require("@xemahq/scoped-dir/lib")', 'require("plain-contract/lib")', 'require("@xemahq/renamed/lib")']) {
+      if (!wsAfter.includes(expected)) {
+        throw new Error(`self-test: relative-workspace rewrite missing ${expected}: ${wsAfter}`);
+      }
+    }
+    // A target directory without its own package.json is a hard failure.
+    const orphan = join(root, 'orphan');
+    await mkdir(join(orphan, 'svc/dist'), { recursive: true });
+    await writeFile(
+      join(orphan, 'svc/dist/dto.js'),
+      'class D {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { a: () => require("../../packages/none/dist/lib/x") };\n  }\n}\n',
+      'utf8',
+    );
+    await expectFailure('relative workspace target without package.json', () => run([join(orphan, 'svc/dist')]));
+
+    // An ANCESTOR's package.json must not stand in for the target's own.
+    const walkup = join(root, 'walkup');
+    await mkdir(join(walkup, 'packages/none/dist/lib'), { recursive: true });
+    await mkdir(join(walkup, 'svc/dist'), { recursive: true });
+    await writeFile(join(walkup, 'package.json'), JSON.stringify({ name: 'workspace-root' }), 'utf8');
+    await writeFile(
+      join(walkup, 'svc/dist/dto.js'),
+      'class D {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { a: () => require("../../packages/none/dist/lib/x") };\n  }\n}\n',
+      'utf8',
+    );
+    await expectFailure('relative workspace target without package.json but with an ancestor that has one', () =>
+      run([join(walkup, 'svc/dist')]),
+    );
+
     // 5. End-to-end RED — a DOUBLY-nested literal. One `String.replace` pass
     //    does not re-scan its own replacement, so the rewrite leaves a literal
     //    that is still a leak. This is the case the old script shipped