@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/CookbookTestUtils.js

@@ -3,7 +3,7 @@
 const {
   MIN_COOKBOOK_FORMAT_VERSION,
   checkCookbookFormatVersion,
-  normalizeCookbookSteps,
+  readCookbookSteps,
   stepIdentityOf
 } = require('./utils/cookbookFormat');
 
@@ -85,13 +85,12 @@ class CookbookTestUtils {
       errors.push(versionProblem);
     }
 
-    // Both documented shapes, through the one owner of that rule. Requiring an
-    // array here rejected every V2 object-shaped cookbook, and requiring `id`
-    // rejected every cookbook that follows format.md — measured 2026-08-30,
-    // that was 100 % of the tree.
+    // The one shape the format allows, through the one owner of that rule
+    // (`utils/cookbookFormat`), so this entry point and the Tier-1 runner cannot
+    // disagree about what a cookbook's steps are.
     let steps;
     try {
-      steps = normalizeCookbookSteps(cookbook.steps);
+      steps = readCookbookSteps(cookbook.steps);
     } catch (error) {
       // The refusal is the finding. This entry point answers with a list, not
       // an exception, so the message becomes one more error in that list.
@@ -137,8 +136,8 @@ class CookbookTestUtils {
     }
 
     // Compare steps
-    const steps1 = normalizeCookbookSteps(cookbook1.steps);
-    const steps2 = normalizeCookbookSteps(cookbook2.steps);
+    const steps1 = readCookbookSteps(cookbook1.steps);
+    const steps2 = readCookbookSteps(cookbook2.steps);
 
     if (steps1.length !== steps2.length) {
       differences.push({

package/src/ServiceReadinessValidator.js

@@ -1,10 +1,21 @@
 'use strict';
 
+const { assertLogger } = require('@onlineapps/logger-contract');
 const CookbookTestUtils = require('./CookbookTestUtils');
+const { HANDLER_REF_PATTERN } = require('./utils/handlerRef');
 
-// The logger methods this validator requires — the order is the order the
-// error message lists them in.
-const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+/**
+ * The semver 2.0.0 grammar, verbatim from semver.org's own published regular
+ * expression (anchored, no leading `v`, no surrounding whitespace, no leading
+ * zeroes in a numeric identifier).
+ *
+ * Written out rather than pulled from the `semver` package: this is the only
+ * version rule in the package, one anchored pattern expresses it completely,
+ * and a dependency added for a single `test()` call is a supply chain the gate
+ * does not need. If a second version rule ever appears here, that trade changes
+ * — and the change is then visible, because it is this comment that has to go.
+ */
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
 
 /**
  * ServiceReadinessValidator - Orchestrates complete service validation.
@@ -25,16 +36,9 @@ const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
  * previously spent on `health` fold into `operations` so total stays
  * at 100.
  *
- * 2026-08-22: the `url` the probe consumed is gone too. It outlived the
- * probe by five months as an accepted-and-ignored argument echoed into
- * `results.serviceUrl` and printed as a `URL:` line — a report field
- * naming an endpoint that does not exist. The only caller that still
- * passed one was Tier-1's readiness step, and that step is gone
- * (see ValidationOrchestrator: its verdict was a strict function of
- * steps 2 and 3). What is left has exactly one consumer:
- * `helpers/createServiceReadinessTests`, and through it the
- * `tests/bootstrap/` suites of the biz repos — which pass name, version,
- * operations, testCookbook and registry, and never passed a url.
+ * `validateReadiness(service)` reads `name`, `version`, `operations`,
+ * `testCookbook` and `registry`. Those five are what it reads, and it
+ * reads no others.
  *
  * @see api/docs/biz/30-operations/schema-v3.md
  * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (input probe contract)
@@ -48,26 +52,11 @@ class ServiceReadinessValidator {
     // caller that did not print the returned object learned nothing about why a
     // service was refused. Owner confirmation:
     // docs/governance/confirmations/connector-logger-contract.md 001.
-    if (!options.logger) {
-      throw new Error(
-        '[ServiceReadinessValidator] Logger is required - Expected: a logger with info/warn/error/debug, '
-        + 'so the readiness verdict leaves the process. '
-        + 'Fix: pass options.logger (e.g. the logger your service already built).'
-      );
-    }
-
-    const missingLoggerMethods = LOGGER_METHODS.filter(
-      (method) => typeof options.logger[method] !== 'function'
+    this.logger = assertLogger(
+      'ServiceReadinessValidator',
+      options.logger,
+      'the readiness verdict leaves the process'
     );
-    if (missingLoggerMethods.length > 0) {
-      throw new Error(
-        '[ServiceReadinessValidator] Logger is incomplete - Expected: info, warn, error, debug as functions; '
-        + `missing: ${missingLoggerMethods.join(', ')}. `
-        + 'Fix: pass a logger implementing all four.'
-      );
-    }
-
-    this.logger = options.logger;
 
     // Readiness checks: core (80 points) + optional (20 points) = 100 points max
     // Core checks ALWAYS run, optional checks run if testCookbook/registry provided
@@ -240,7 +229,6 @@ class ServiceReadinessValidator {
       }
 
       const validScopes = ['platform', 'tenant', 'workspace'];
-      const handlerPattern = /^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/;
       const forbiddenV2Fields = ['endpoint', 'method', 'path'];
 
       for (const [name, operation] of Object.entries(operations)) {
@@ -249,7 +237,7 @@ class ServiceReadinessValidator {
         }
         if (!operation.handler) {
           errors.push(`Operation '${name}' missing handler (v3 — 'handlers/<path>#<export>')`);
-        } else if (!handlerPattern.test(operation.handler)) {
+        } else if (!HANDLER_REF_PATTERN.test(operation.handler)) {
           errors.push(`Operation '${name}' has invalid handler ref: '${operation.handler}'`);
         }
         if (!operation.bundle_scope) {
@@ -311,16 +299,63 @@ class ServiceReadinessValidator {
   }
 
   /**
-   * Check registry compatibility
+   * Check registry compatibility.
+   *
+   * `canRegister` used to be `!!(name && version && operations)`. Truthiness is
+   * the wrong question about a version: the line below it compares this value
+   * against what the registry already holds, and a comparison between two
+   * strings that are not versions decides nothing. Measured (BIZ-ingest): every
+   * biz `config/service/config.json` declares
+   * `"service": { "version": "${npm_package_version}" }`, the placeholder was
+   * handed here unexpanded, and — being a non-empty string — it passed. The
+   * gate reported `canRegister: true` about a value that is not a version.
+   *
+   * The grammar is semver 2.0.0, checked here and nowhere else: this is the one
+   * place that decides `canRegister`. Callers supply the value (the `version`
+   * field of the service package.json, which is what ConfigLoader reads at
+   * runtime); they do not re-check it.
    */
   async checkRegistryCompatibility(service, registry) {
     try {
-      // Check if service can be registered
-      const canRegister = !!(
-        service.name &&
-        service.version &&
-        service.operations
-      );
+      const errors = [];
+
+      if (!service.name) {
+        errors.push(
+          '[ServiceReadinessValidator] Service name is missing - '
+          + 'validateReadiness() received no `name`. '
+          + 'Expected: the service name, e.g. biz-ingest. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      }
+
+      if (service.version === undefined || service.version === null) {
+        errors.push(
+          '[ServiceReadinessValidator] Service version is missing - '
+          + 'validateReadiness() received no `version`. '
+          + 'Expected: the `version` field of the service package.json, e.g. 1.4.2. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      } else if (!SEMVER_PATTERN.test(service.version)) {
+        errors.push(
+          '[ServiceReadinessValidator] Service version is not a semantic version - '
+          + `received "${service.version}". `
+          + 'Expected: MAJOR.MINOR.PATCH per semver 2.0.0, e.g. 1.4.2 or 1.4.2-rc.1. '
+          + 'Fix: pass the `version` field of the service package.json — the single source of '
+          + 'truth ConfigLoader reads at runtime. An unresolved "${...}" means the value came '
+          + 'from config.json instead, where the key is never expanded.'
+        );
+      }
+
+      if (!service.operations) {
+        errors.push(
+          '[ServiceReadinessValidator] Operations are missing - '
+          + 'validateReadiness() received no `operations`. '
+          + 'Expected: the flat operations object from config/service/operations.json. '
+          + 'Fix: pass it in the object handed to validateReadiness().'
+        );
+      }
+
+      const canRegister = errors.length === 0;
 
       // Check if service operations match registry expectations
       const registeredService = registry.getService(service.name);
@@ -331,7 +366,8 @@ class ServiceReadinessValidator {
         passed: canRegister && compatible,
         canRegister,
         compatible,
-        existingVersion: registeredService?.version
+        existingVersion: registeredService?.version,
+        errors
       };
     } catch (error) {
       return {