@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/workspaceRoot.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * Where the `from:` references of the manifest are resolved.
+ *
+ * Two facts, and they are not the same one:
+ *
+ *   - the **api checkout** — the repository this package is part of, which owns
+ *     the platform SSOT (`config/services.json`, `.nvmrc`, `config/libraries.json`);
+ *   - the **workspace** — the directory holding that checkout and its siblings
+ *     (`api_biz/*`, `fe_adminui`), which exist in local development and in
+ *     nothing else.
+ *
+ * `api/` at the head of a manifest path is a CONVENTION of the declaring text,
+ * never the name of a directory on disk. GitLab CI checks the repository out
+ * under the project name (`infra-mono`), so joining the literal string onto the
+ * workspace resolves to a directory that is not there: measured 2026-09-09,
+ * `--library --all --workspace "$CI_PROJECT_DIR/.."` died with
+ * `[ManifestWorkspace] Workspace root does not carry api/config/services.json`,
+ * and every workspace row was reported NOT RUN — a green job that had checked
+ * nothing. `scripts/ci/lint-biz-docs.mjs` (§ resolveWorkspaceRelative) already
+ * answers this for the doc tree by deriving its `API_ROOT` from the script's own
+ * location; the rule here is the same one, for the same reason.
+ *
+ * So the api checkout is derived from THIS FILE'S location — the directory that
+ * carries this package as `shared/connector/<package>` and carries the marker —
+ * and the workspace is its parent. An explicit `--workspace` still wins, and
+ * fails fast when the root it names holds no api checkout. `oa-validate` asks
+ * for nothing else: which SSOT it reads no longer depends on where the shell
+ * happened to stand, nor on what the checkout is named (`automation-gates.md`
+ * §1.1, predictable).
+ *
+ * The upward search survives as `workspaceAbove`, for the callers whose subject
+ * IS a tree rather than the platform — `oa-sync-template --target <service>`,
+ * which writes into that tree, and the in-service `ValidationOrchestrator`,
+ * whose subject is the service it was constructed with. Those callers pass
+ * `startDir` and get the workspace THAT TREE belongs to. It is a different
+ * question, asked explicitly, never a fallback of the other one.
+ *
+ * An INSTALLED copy (`<service>/node_modules/@onlineapps/conn-orch-validator`)
+ * lies in no checkout, so it resolves nothing and the rows that need the SSOT
+ * are reported NOT RUN — loudly, never as a pass (`automation-gates.md` §5).
+ * That is what a service container has, and it is unchanged by this rule.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** The prefix every manifest path uses for the api checkout. */
+const API_PREFIX = 'api';
+
+/** What identifies an api checkout, whatever the checkout is named. */
+const API_MARKER = 'config/services.json';
+
+/**
+ * The same marker as a workspace-relative path — the shape the manifest and the
+ * CLIs write it in. Kept as the exported name it has always had.
+ */
+const WORKSPACE_MARKER = `${API_PREFIX}/${API_MARKER}`;
+
+/** Where this package sits inside an api checkout, from the checkout down. */
+const PACKAGE_LOCATION = ['shared', 'connector'];
+
+/** This package's root: `<checkout>/shared/connector/<package>`. */
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+
+const carriesMarker = (dir) => fs.existsSync(path.join(dir, ...API_MARKER.split('/')));
+
+/**
+ * One directory, one name: the path with every symlink resolved.
+ *
+ * Two roots reach a run by two different routes. The workspace root is derived
+ * from THIS FILE'S location, and node resolves a module's own path through its
+ * symlinks; the service or package root is an argument, and `path.resolve()`
+ * keeps the spelling the caller typed. On macOS `/var` is a symlink to
+ * `/private/var`, so a run over a directory below the system temp gets one root
+ * in each spelling — and "is the service inside the workspace", which is a
+ * string prefix, then answers no about a service that is plainly inside it.
+ *
+ * Measured 2026-09-09 over the pre-push export of this repository
+ * (`api/tests/scripts/library-uniform-hook.bats`, "over an export of this
+ * repository the sibling rows are NOT RUN"): the package root came back
+ * `/var/folders/…/export/api/shared/mq-client-core`, the workspace root
+ * `/private/var/folders/…/export`, and all six rows were reported `service root
+ * is outside the workspace root` — a sentence that was false, over a run whose
+ * real findings were never raised. A NOT RUN nobody can act on is the false
+ * guarantee of `automation-gates.md` §5.
+ *
+ * So every root passes through here BEFORE it is compared or printed, and it is
+ * one function rather than a `realpathSync` at each call site, because the
+ * fourth call site is the one that would forget (`change-discipline.md` § One
+ * rail per concern).
+ *
+ * A path that does not exist is NOT canonicalised into something else: the
+ * caller that owns the message about a missing root says it in its own words,
+ * so this refuses rather than guesses (`architecture-principles.md` §3).
+ *
+ * @param {string} dir an absolute or relative path to an existing directory
+ * @returns {string} the same directory, with no symlink left in the path
+ */
+function canonicalRoot(dir) {
+  if (typeof dir !== 'string' || dir.length === 0) {
+    throw new Error(`[ManifestWorkspace] Root path is required - canonicalRoot() got ${JSON.stringify(dir)}. `
+      + 'Fix: pass the directory to canonicalise.');
+  }
+
+  try {
+    return fs.realpathSync(path.resolve(dir));
+  } catch (cause) {
+    throw new Error(`[ManifestWorkspace] Root does not exist - ${path.resolve(dir)} cannot be resolved, `
+      + 'so it cannot be compared with the other roots of this run. '
+      + 'Fix: pass an existing directory.', { cause });
+  }
+}
+
+/**
+ * The api checkout this package is part of, or `null` when it is part of none.
+ *
+ * Both conditions must hold, and neither is guessed at: the package lies where a
+ * checkout puts it, and the directory above carries the marker. An installed
+ * copy fails the first, a stray copy fails the second.
+ *
+ * @param {string} packageRoot
+ * @returns {string|null}
+ */
+function checkoutCarrying(packageRoot) {
+  const segments = path.resolve(packageRoot).split(path.sep);
+  const parents = segments.slice(-1 - PACKAGE_LOCATION.length, -1);
+  if (parents.join('/') !== PACKAGE_LOCATION.join('/')) return null;
+
+  const candidate = path.resolve(packageRoot, ...PACKAGE_LOCATION.map(() => '..'), '..');
+  return carriesMarker(candidate) ? candidate : null;
+}
+
+/** The api checkout this run speaks for, decided once, from this file's location. */
+const API_CHECKOUT_ROOT = checkoutCarrying(PACKAGE_ROOT);
+
+/**
+ * The api checkout of a given workspace: this package's own when the workspace
+ * is the one it lives in, and otherwise the checkout the prefix names literally
+ * — a fixture workspace, or any tree a `--workspace` points at.
+ *
+ * @param {string} workspaceRoot
+ * @returns {string|null}
+ */
+function apiCheckoutOf(workspaceRoot) {
+  const root = path.resolve(workspaceRoot);
+  if (API_CHECKOUT_ROOT !== null && path.dirname(API_CHECKOUT_ROOT) === root) return API_CHECKOUT_ROOT;
+
+  const named = path.join(root, API_PREFIX);
+  return carriesMarker(named) ? named : null;
+}
+
+/**
+ * Resolve a manifest path — `api/config/services.json`, `api_biz/*&#47;package.json`
+ * — to an absolute path under `workspaceRoot`.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} relative a `/`-separated workspace-relative path
+ * @returns {string}
+ */
+function resolveWorkspacePath(workspaceRoot, relative) {
+  if (typeof workspaceRoot !== 'string' || workspaceRoot.length === 0) {
+    throw new Error('[ManifestWorkspace] Workspace root is required - resolveWorkspacePath() got '
+      + `${JSON.stringify(workspaceRoot)}. Fix: resolve it first (resolveWorkspaceRoot).`);
+  }
+
+  const segments = String(relative).split('/').filter((segment) => segment.length > 0);
+  if (segments[0] !== API_PREFIX) return path.join(workspaceRoot, ...segments);
+
+  const apiRoot = apiCheckoutOf(workspaceRoot);
+  if (apiRoot === null) {
+    throw new Error(`[ManifestWorkspace] Workspace root holds no api checkout - ${path.resolve(workspaceRoot)} `
+      + `carries no directory with ${API_MARKER}, so "${relative}" resolves to nothing. `
+      + 'Fix: pass --workspace <root> holding the api checkout (under any name).');
+  }
+  return path.join(apiRoot, ...segments.slice(1));
+}
+
+/**
+ * The workspace a given tree belongs to: the nearest ancestor carrying the
+ * marker under the name the prefix writes. This answers a DIFFERENT question
+ * from the one above — not "which SSOT does this package speak for" but "which
+ * workspace is this tree part of" — and it is the question a run that writes
+ * INTO a tree has to ask (`oa-sync-template --target <service>`, and the
+ * in-service `ValidationOrchestrator` step, whose subject is the service it was
+ * constructed with). A caller states which question it is asking by passing
+ * `startDir` or leaving it out; neither is a default of the other.
+ *
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+function workspaceAbove(startDir) {
+  let current = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(current, ...WORKSPACE_MARKER.split('/')))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * @param {{ explicit?: string|null, startDir?: string|null }} params
+ * @returns {string|null} absolute workspace root, or null when neither the named
+ *   tree nor this package lies in one
+ */
+function resolveWorkspaceRoot({ explicit = null, startDir = null } = {}) {
+  if (explicit !== null && explicit !== undefined) {
+    const resolved = path.resolve(explicit);
+    if (apiCheckoutOf(resolved) === null) {
+      throw new Error(`[ManifestWorkspace] Workspace root does not carry ${WORKSPACE_MARKER} - ${resolved}, `
+        + 'and this package\'s own checkout is not a directory under it. '
+        + `Fix: pass --workspace <root> holding the api checkout — under any name, carrying ${API_MARKER}.`);
+    }
+    return canonicalRoot(resolved);
+  }
+
+  if (startDir !== null && startDir !== undefined) {
+    if (typeof startDir !== 'string' || startDir.length === 0) {
+      throw new Error('[ManifestWorkspace] Start directory is required - resolveWorkspaceRoot({ startDir }) got '
+        + `${JSON.stringify(startDir)}. Fix: pass the tree the run is about, or omit it to use this `
+        + 'package\'s own checkout.');
+    }
+    const above = workspaceAbove(startDir);
+    return above === null ? null : canonicalRoot(above);
+  }
+
+  return API_CHECKOUT_ROOT === null ? null : canonicalRoot(path.dirname(API_CHECKOUT_ROOT));
+}
+
+module.exports = {
+  resolveWorkspaceRoot,
+  canonicalRoot,
+  workspaceAbove,
+  resolveWorkspacePath,
+  apiCheckoutOf,
+  API_CHECKOUT_ROOT,
+  API_MARKER,
+  PACKAGE_ROOT,
+  WORKSPACE_MARKER
+};

package/src/mocks/MockMQClient.js

@@ -61,8 +61,10 @@ class MockMQClient {
    */
   async publish(queue, message, options = {}) {
     if (!this._connected) {
-      // Wording per BaseClient.publish (ConnectionError).
-      throw new Error('Cannot publish: client is not connected');
+      // The mock states the same refusal as BaseClient.publish (ConnectionError) under
+      // its own context — it does not copy that text, so the two can never be mistaken
+      // for one another in a log.
+      throw new Error('[MockMQClient] Cannot publish - client is not connected. Fix: call connect() first');
     }
 
     if (!this.queues[queue]) {
@@ -79,32 +81,13 @@ class MockMQClient {
     this.queues[queue].push(messageWrapper);
     this.publishedMessages.push({ queue, message, options, timestamp: Date.now() });
 
-    // Auto-reply simulation for workflow task requests:
-    // When a task is published to service.*.request, publish a deterministic response
-    // to workflow.<workflow_id>.response so WorkflowTestRunner unit tests can run
-    // end-to-end with mocked MQ.
-    if (
-      typeof queue === 'string' &&
-      queue.startsWith('service.') &&
-      queue.endsWith('.request') &&
-      message &&
-      typeof message === 'object' &&
-      message.workflow_id &&
-      message.step_id
-    ) {
-      const responseQueue = `workflow.${message.workflow_id}.response`;
-      const response = {
-        step_id: message.step_id,
-        result: {
-          processed: true,
-          operation: message.operation,
-          input: message.input,
-          output: { mocked: true }
-        }
-      };
-      // Enqueue response (does not recurse into auto-reply because queue prefix differs)
-      await this.publish(responseQueue, response);
-    }
+    // The auto-reply that used to sit here — publish to service.*.request, get a
+    // synthetic `workflow.<workflow_id>.response` back — existed for exactly one
+    // reader, and said so in its own comment: WorkflowTestRunner's unit tests.
+    // That rail was deleted on 2026-09-05, and nothing else in the workspace
+    // publishes or consumes those queues through this mock (measured: api,
+    // api_biz/*, fe_adminui). A mock that invents traffic nobody reads is not
+    // harmless — it makes a test look end-to-end when nothing answered.
 
     // Trigger consumers if any
     if (this.consumers[queue]) {
@@ -122,8 +105,8 @@ class MockMQClient {
    */
   async consume(queue, callback, options = {}) {
     if (!this._connected) {
-      // Wording per BaseClient.consume (ConnectionError).
-      throw new Error('Cannot consume: client is not connected');
+      // Same shape as publish() above, and deliberately not a copy of BaseClient.consume.
+      throw new Error('[MockMQClient] Cannot consume - client is not connected. Fix: call connect() first');
     }
 
     this.consumers[queue] = {

package/src/mocks/MockRegistry.js

@@ -18,7 +18,8 @@ class MockRegistry {
     const { name, version, url, healthCheck, openapi } = serviceData;
 
     if (!name) {
-      throw new Error('Service name is required');
+      throw new Error('[MockRegistry] Service name is required - Expected serviceData.name to be a '
+        + 'non-empty string. Fix: pass { name } to register().');
     }
 
     this.services[name] = {
@@ -60,7 +61,8 @@ class MockRegistry {
    */
   async heartbeat(serviceName) {
     if (!this.services[serviceName]) {
-      throw new Error(`Service ${serviceName} not registered`);
+      throw new Error(`[MockRegistry] Service ${serviceName} not registered - Expected a prior `
+        + 'register() call for that name. Fix: register the service before sending a heartbeat.');
     }
 
     this.heartbeats[serviceName] = {

package/src/mocks/MockStorage.js

@@ -59,7 +59,8 @@ class MockStorage {
    */
   async get(bucket, key) {
     if (!this.buckets[bucket] || !this.buckets[bucket][key]) {
-      throw new Error(`Object not found: ${bucket}/${key}`);
+      throw new Error(`[MockStorage] Object not found: ${bucket}/${key} - Expected the object to have `
+        + 'been stored first. Fix: put(bucket, key, content) in the test setup before reading it.');
     }
 
     const obj = this.buckets[bucket][key];
@@ -128,7 +129,8 @@ class MockStorage {
    */
   async getMetadata(bucket, key) {
     if (!this.metadata[bucket] || !this.metadata[bucket][key]) {
-      throw new Error(`Metadata not found: ${bucket}/${key}`);
+      throw new Error(`[MockStorage] Metadata not found: ${bucket}/${key} - Expected metadata written `
+        + 'by put(). Fix: store the object with put(bucket, key, content) before reading its metadata.');
     }
     return this.metadata[bucket][key];
   }