@onlineapps/conn-orch-validator 3.3.2 → 4.0.1

package/src/cli/biz-ci-gate.js

@@ -3,6 +3,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const { spawnSync } = require('child_process');
 const {
   DEFAULT_CONTRACT_RELATIVE_PATH,
   loadAndValidateIntegrationContract,
@@ -14,6 +15,20 @@ const {
   runConnectorSetup,
   writeJsonFile,
 } = require('../utils/bizCiGateContract');
+const {
+  DEFAULT_REPORT_DIR_RELATIVE_PATH,
+  runIntegrationSuite,
+} = require('../utils/integrationRun');
+const { verifyDeployContract } = require('../utils/deployContract');
+const { verifyInstallContract } = require('../utils/installContract');
+const {
+  verifyEnvCompleteness,
+  ENV_SCAN_SCOPE,
+  ENV_SCAN_BLIND_SPOTS,
+} = require('../utils/envContract');
+const { runPreValidation } = require('../utils/preValidation');
+const { checkLibCompat, loadLibrarySet } = require('../utils/libCompat');
+const { buildSchema } = require('../utils/setupDatabase');
 
 function parseArgs(argv) {
   const parsed = {
@@ -47,10 +62,31 @@ Usage:
   oa-biz-ci-gate <command> [--service-root <path>] [--contract <path>] [options]
 
 Commands:
-  verify-contract             Validate integration-contract.json schema and connector flags.
+  verify-contract             Validate integration-contract.json schema, connector flags,
+                             the deploy contract (R1-R7), the installation contract AND
+                             the env contract.
+  verify-env-contract        Env contract only: every environment variable the service
+                             repository visibly reads is declared in the contract's env
+                             block or covered by a config placeholder / required connector.
+                             Prints its measurement boundary on every run.
+  verify-deploy-contract     Deploy contract only (R1-R7): image pin, deploy sequence,
+                             Node major agreement, no published ports, full commit SHA,
+                             CI database engine.
+  verify-install-contract    Installation contract only: the docs/setup package every repo
+                             carries, plus the BASELINE/SEED SQL tree required of every repo
+                             whose contract declares a database.
+  run-prevalidation          Run the service's cookbooks offline against mocked infrastructure
+                             and write conn-runtime/validation-proof.json. Replaces the
+                             per-service scripts/run-pre-validation.js.
+  verify-lib-compat          Compare @onlineapps/* pins against the platform library SSOT (R6).
   verify-integration-minimum Validate package scripts + fail on empty integration suite.
+  run-integration            Run the integration suite (one runner process per test file)
+                             and fail unless the tests actually EXECUTED and passed.
+                             Counting files on disk cannot see a suite that was
+                             skipped; this reads the runner's own JSON report.
   emit-ci-env                Emit connector-aware CI environment exports.
   wait-connectors            Wait for required connector TCP endpoints.
+  setup-db                   Build the schema from the declared migrations (contract database block).
   run-setup                  Run optional connector setup commands from contract.
   write-summary              Write normalized integration signal artifact JSON.
 
@@ -59,6 +95,10 @@ Common options:
   --contract <path>          Contract path (absolute or relative to service root).
                              Default: ${DEFAULT_CONTRACT_RELATIVE_PATH}
 
+verify-lib-compat options:
+  --libraries <path|url>          Library SSOT source. Default: $LIBRARIES_SSOT_URL
+                                  Auth for an https source: $LIBRARIES_SSOT_TOKEN
+
 emit-ci-env options:
   --format <shell|dotenv|json>    Output format. Default: shell
   --output <path>                 Optional output file path
@@ -71,8 +111,10 @@ write-summary options:
   --output <path>                 Summary artifact path. Default: <service-root>/ci/integration-signal.json
   --gate-verdict <pass|fail>      Override gate verdict
   --gate-reason <text>            Override gate reason
-  --unit-executed <number>        Executed unit suite count
-  --integration-executed <number> Executed integration suite count
+
+  Executed test counts are read from ci/integration-run.json, written by
+  run-integration. Without that artifact the summary reports them as unknown —
+  it never substitutes a count of files on disk.
 `);
 }
 
@@ -84,11 +126,167 @@ function resolveContractOptions(options) {
   return {
     serviceRoot: options['service-root'] || process.cwd(),
     contractPath: options.contract || undefined,
+    // Undefined here means loadLibrarySet falls back to LIBRARIES_SSOT_URL and
+    // fails fast if that is unset too — never a silent skip.
+    libraries: options.libraries || undefined,
   };
 }
 
-function runVerifyContract(options) {
+/**
+ * Render a deploy-contract result and signal whether it passed.
+ * The rules live in utils/deployContract; this only presents them.
+ */
+function reportDeployContract(result) {
+  if (result.ok) {
+    process.stdout.write(`[BizCiGate] OK deploy-contract (${result.service}) — R1-R7 satisfied\n`);
+    return true;
+  }
+  for (const violation of result.violations) {
+    process.stderr.write(`[BizCiGate] FAIL ${result.service} — ${violation.requirement} — ${violation.message}\n`);
+  }
+  process.stderr.write(`[BizCiGate] FAIL ${result.service} — ${result.violations.length} deploy-contract violation(s)\n`);
+  return false;
+}
+
+/**
+ * Render the env-contract completeness result and signal whether it passed.
+ *
+ * The scope line is printed on every run, pass or fail. A gate that reports
+ * "OK" without saying what it looked at invites the reader to assume it looked
+ * at everything; this one measures literal reads in the service repository and
+ * says so out loud, including how many dynamic accesses it could not resolve.
+ */
+function reportEnvContract(serviceName, contract, result) {
+  process.stdout.write(`[BizCiGate] env-contract scope: ${ENV_SCAN_SCOPE}\n`);
+  process.stdout.write(`[BizCiGate] env-contract NOT measured: ${ENV_SCAN_BLIND_SPOTS}`
+    + ` — ${result.dynamicSites.length} dynamic access site(s) in this repo\n`);
+
+  if (result.ok) {
+    const adoption = contract.env ? '' : ' — no "env" block declared yet (F16 adoption pending)';
+    process.stdout.write(`[BizCiGate] OK env-contract (${serviceName}) — ${result.readCount} name(s) read, `
+      + `${result.declaredCount} declared, ${result.coveredCount} covered${adoption}\n`);
+    return true;
+  }
+
+  for (const violation of result.violations) {
+    process.stderr.write(`[BizCiGate] FAIL ${serviceName} — ENV_COMPLETENESS — `
+      + `"${violation.name}" is read in ${violation.sources.join(', ')} but is neither declared in `
+      + 'config/service/integration-contract.json (env.required / env.optional) nor covered by a '
+      + '${...} config placeholder or a required connector.\n'
+      + `       Fix: add { "name": "${violation.name}", "why": "<what the service does with it>" } `
+      + 'to env.optional (or env.required if the service cannot start without it), or delete the read.\n');
+  }
+  process.stderr.write(`[BizCiGate] FAIL ${serviceName} — ${result.violations.length} env-contract violation(s)\n`);
+  return false;
+}
+
+function reportInstallContract(result) {
+  if (result.ok) {
+    const half = result.databaseChecked ? 'docs + SQL package' : 'docs (no database declared)';
+    process.stdout.write(`[BizCiGate] OK install-contract (${result.service}) — ${half}\n`);
+    return true;
+  }
+  for (const violation of result.violations) {
+    process.stderr.write(`[BizCiGate] FAIL ${result.service} — ${violation.requirement} — ${violation.message}\n`);
+  }
+  process.stderr.write(`[BizCiGate] FAIL ${result.service} — ${result.violations.length} install-contract violation(s)\n`);
+  return false;
+}
+
+/**
+ * Build the schema the contract declares. One implementation for every service:
+ * the repo declares WHAT, this decides HOW (docs/biz/00-model/uniformity-principle.md).
+ */
+function runSetupDb(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  const database = contractInfo.contract.database;
+
+  if (!database) {
+    // Skipping is explicit and visible — a service with no database says so by
+    // omitting the block, and that is not the same as a failure to find one.
+    process.stdout.write('[BizCiGate] OK setup-db — no database declared, nothing to build\n');
+    return;
+  }
+
+  const result = buildSchema({
+    serviceRoot: contractInfo.serviceRoot,
+    database,
+    connection: {
+      host: process.env.DB_HOST,
+      port: Number.parseInt(process.env.DB_PORT || '3306', 10),
+      user: process.env.DB_USER,
+      password: process.env.DB_PASSWORD ?? '',
+      requireTls: process.env.DB_REQUIRE_TLS === '1'
+    }
+  });
+
+  process.stdout.write(`[BizCiGate] OK setup-db — ${result.schema}: `
+    + `${result.migrationsApplied} migration(s), ${result.seedsApplied} seed(s)\n`);
+}
+
+async function runVerifyLibCompat(options) {
+  const pkgPath = path.join(options.serviceRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    process.stderr.write(`[BizCiGate] FAIL verify-lib-compat — package.json not found at ${pkgPath}\n`);
+    process.exit(1);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const librarySet = await loadLibrarySet(options.libraries);
+  const result = checkLibCompat(pkg, librarySet);
+
+  if (result.notGated.length > 0) {
+    process.stdout.write(`[BizCiGate] not gated (no infra service installs these): ${result.notGated.join(', ')}\n`);
+  }
+  if (!result.ok) {
+    for (const violation of result.violations) {
+      process.stderr.write(`[BizCiGate] FAIL verify-lib-compat — ${violation.message}\n`);
+    }
+    process.exit(1);
+  }
+  process.stdout.write(`[BizCiGate] OK verify-lib-compat — ${result.gated.length} pin(s) match the platform library set\n`);
+}
+
+async function runVerifyContract(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+
+  // The deploy contract (R1-R7) is part of the same mandatory gate: a service
+  // whose compose, deploy sequence, Node major or database engine breaks the
+  // platform contract must not reach the build stage. Folding it in here means
+  // a version bump activates it — no per-repo CI edit, nothing to forget.
+  if (!reportDeployContract(verifyDeployContract(contractInfo.serviceRoot))) {
+    process.exit(1);
+  }
+
+  // The installation contract joins the same gate on the same argument: a repo
+  // whose setup docs or SQL package are missing cannot be installed from its own
+  // instructions, and that must not reach the build stage. Folding it in also
+  // retires the eight drifting shell copies — and with them the hand-maintained
+  // REPO_HAS_DB literal, since the database block already says whether the SQL
+  // half applies.
+  if (!reportInstallContract(
+    verifyInstallContract(contractInfo.serviceRoot, contractInfo.contract.database)
+  )) {
+    process.exit(1);
+  }
+
+  // The env contract joins on the same argument once more: a repo that reads a
+  // variable nobody declared has no way to tell a missing value from a dead one,
+  // and finds out at runtime — biz-emailer read EMAIL_PROVIDER_LIVE_MODE that no
+  // template ever set, so live mail was silently off (defect D1).
+  if (!reportEnvContract(
+    contractInfo.contract.serviceName || path.basename(contractInfo.serviceRoot),
+    contractInfo.contract,
+    verifyEnvCompleteness({ serviceRoot: contractInfo.serviceRoot, contract: contractInfo.contract })
+  )) {
+    process.exit(1);
+  }
+
+  // R6 belongs to the same gate for the same reason. It needs LIBRARIES_SSOT_URL;
+  // an unconfigured gate fails loudly rather than passing, so the CI variable
+  // must exist before any repo pins a version carrying this check.
+  await runVerifyLibCompat({ ...options, serviceRoot: contractInfo.serviceRoot });
+
   process.stdout.write(`[BizCiGate] OK verify-contract\n`);
   process.stdout.write(`${JSON.stringify({
     serviceRoot: contractInfo.serviceRoot,
@@ -99,6 +297,87 @@ function runVerifyContract(options) {
   }, null, 2)}\n`);
 }
 
+
+/**
+ * Resolve the service URL from the service's OWN config.
+ *
+ * ConfigLoader lives in @onlineapps/service-wrapper (L4) and this package is L3,
+ * so it is never a dependency here — it is resolved from the service being
+ * validated, which is where it legitimately exists.
+ */
+function resolveServiceUrl(serviceRoot) {
+  let wrapperPath;
+  try {
+    wrapperPath = require.resolve('@onlineapps/service-wrapper', { paths: [serviceRoot] });
+  } catch {
+    throw new Error('[PreValidation] Missing dependency - @onlineapps/service-wrapper is not '
+      + `installed in ${serviceRoot}. Fix: run npm install in the service repository.`);
+  }
+
+  const { ConfigLoader } = require(wrapperPath);
+  const config = ConfigLoader.loadAll({ basePath: serviceRoot, env: process.env });
+  return config.service.url;
+}
+
+async function runRunPreValidation(options) {
+  const outcome = await runPreValidation({
+    serviceRoot: path.resolve(options.serviceRoot),
+    serviceUrl: resolveServiceUrl(path.resolve(options.serviceRoot)),
+    RunnerClass: require('../CookbookTestRunner'),
+    ProofGeneratorClass: require('../validators/ValidationProofGenerator'),
+    logger: console
+  });
+
+  const { results } = outcome;
+  process.stdout.write(`[BizCiGate] cookbooks — total ${results.total}, `
+    + `passed ${results.passed}, failed ${results.failed} (${results.duration}ms)\n`);
+
+  if (!outcome.ok) {
+    for (const step of outcome.failedSteps) {
+      process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${step.id}: ${step.error}\n`);
+      for (const validationError of step.validationErrors) {
+        process.stderr.write(`[BizCiGate]   * ${validationError}\n`);
+      }
+    }
+    process.stderr.write(`[BizCiGate] FAIL run-prevalidation — ${results.failed} failed step(s); `
+      + 'no validation proof written\n');
+    process.exit(1);
+  }
+
+  process.stdout.write(`[BizCiGate] OK run-prevalidation — proof ${outcome.proof.validationProof.slice(0, 16)}... `
+    + `-> ${outcome.proofPath}\n`);
+}
+
+/** Same checks, runnable on their own — for the cross-repo audit and local use. */
+function runVerifyDeployContract(options) {
+  if (!reportDeployContract(verifyDeployContract(options.serviceRoot))) {
+    process.exit(1);
+  }
+}
+
+/** Same checks, runnable on their own. Loads the contract because the database
+ *  block is what decides whether the SQL half of the contract applies. */
+function runVerifyInstallContract(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  if (!reportInstallContract(
+    verifyInstallContract(contractInfo.serviceRoot, contractInfo.contract.database)
+  )) {
+    process.exit(1);
+  }
+}
+
+/** Same check, runnable on its own — for the cross-repo audit and local use. */
+function runVerifyEnvContract(options) {
+  const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
+  if (!reportEnvContract(
+    contractInfo.contract.serviceName || path.basename(contractInfo.serviceRoot),
+    contractInfo.contract,
+    verifyEnvCompleteness({ serviceRoot: contractInfo.serviceRoot, contract: contractInfo.contract })
+  )) {
+    process.exit(1);
+  }
+}
+
 function runVerifyIntegrationMinimum(options) {
   const result = verifyIntegrationMinimum(options.serviceRoot, options.contractPath);
   process.stdout.write(`[BizCiGate] OK verify-integration-minimum\n`);
@@ -111,6 +390,44 @@ function runVerifyIntegrationMinimum(options) {
   }, null, 2)}\n`);
 }
 
+/**
+ * The gate's only honest observation point for "did the suite run?".
+ *
+ * The file-count check runs first as a cheap precondition, then every discovered
+ * file gets its own runner process and its own JSON report. Per-file processes
+ * are the library's HOW, not a per-repo declaration: biz-invoicing already needed
+ * them (its suite was OOM-killed in a single process), and they bound one leaking
+ * suite's blast radius for everyone else.
+ */
+function runRunIntegration(options) {
+  const verified = verifyIntegrationMinimum(options.serviceRoot, options.contractPath);
+
+  const result = runIntegrationSuite({
+    serviceRoot: verified.serviceRoot,
+    testFiles: verified.integrationTestFiles,
+    jestBin: path.join(verified.serviceRoot, 'node_modules', '.bin', 'jest'),
+    jestConfig: path.join(verified.serviceRoot, 'jest.config.js'),
+    reportDir: path.join(verified.serviceRoot, DEFAULT_REPORT_DIR_RELATIVE_PATH),
+    spawn: spawnSync,
+  });
+
+  const { aggregate, evaluation } = result;
+
+  if (!evaluation.ok) {
+    for (const violation of evaluation.violations) {
+      process.stderr.write(`${violation.message}\n`);
+    }
+    process.stderr.write(`[BizCiGate] FAIL run-integration — ${aggregate.executedTests} test(s) executed, `
+      + `${aggregate.notExecutedTests} skipped, ${aggregate.failedTests} failed, `
+      + `across ${aggregate.reportCount} runner process(es). Report: ${result.artefactPath}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`[BizCiGate] OK run-integration — ${aggregate.executedTests} test(s) executed and passed `
+    + `in ${aggregate.totalSuites} suite(s), across ${aggregate.reportCount} runner process(es)\n`);
+  process.stdout.write(`[BizCiGate] Wrote integration run artefact to ${result.artefactPath}\n`);
+}
+
 function runEmitCiEnv(options) {
   const contractInfo = loadAndValidateIntegrationContract(options.serviceRoot, options.contractPath);
   const env = buildCiEnvironment(contractInfo);
@@ -161,8 +478,6 @@ function runWriteSummary(options) {
     contractPath: options.contractPath,
     gateVerdict: options['gate-verdict'],
     gateReason: options['gate-reason'],
-    unitExecuted: options['unit-executed'],
-    integrationExecuted: options['integration-executed'],
   });
 
   const outputPath = options.output
@@ -187,13 +502,42 @@ async function main() {
 
   try {
     if (command === 'verify-contract') {
-      runVerifyContract(options);
+      await runVerifyContract(options);
+      return;
+    }
+
+    if (command === 'verify-deploy-contract') {
+      runVerifyDeployContract(options);
+      return;
+    }
+
+    if (command === 'run-prevalidation') {
+      await runRunPreValidation(options);
+      return;
+    }
+
+    if (command === 'verify-install-contract') {
+      runVerifyInstallContract(options);
+      return;
+    }
+
+    if (command === 'verify-env-contract') {
+      runVerifyEnvContract(options);
+      return;
+    }
+
+    if (command === 'verify-lib-compat') {
+      await runVerifyLibCompat(options);
       return;
     }
     if (command === 'verify-integration-minimum') {
       runVerifyIntegrationMinimum(options);
       return;
     }
+    if (command === 'run-integration') {
+      runRunIntegration(options);
+      return;
+    }
     if (command === 'emit-ci-env') {
       runEmitCiEnv(options);
       return;
@@ -202,6 +546,11 @@ async function main() {
       await runWaitConnectors(options);
       return;
     }
+    if (command === 'setup-db') {
+      runSetupDb(options);
+      return;
+    }
+
     if (command === 'run-setup') {
       runSetup(options);
       return;

package/src/helpers/README.md

@@ -13,7 +13,7 @@ Instead of **copying test code** between services, we provide **reusable test he
 
 ## Available Helpers
 
-### 1. createServiceReadinessTests
+### createServiceReadinessTests
 
 **Purpose:** Integration test for service HTTP API readiness
 
@@ -55,63 +55,11 @@ createServiceReadinessTests(__dirname, {
 
 ---
 
-### 2. createPreValidationTests
-
-**Purpose:** Tier 1 pre-validation process tests
-
-**File:** `createPreValidationTests.js`
-
-**What it does:**
-- Validates pre-requisites (cookbooks/, operations.json, scripts)
-- Runs cookbook tests with mocked infrastructure
-- Validates ValidationProof generation
-- Tests proof structure and integrity
-- Verifies SHA256 hash correctness
-- Tests tamper detection
-- Validates dependencies tracking
-
-**Usage:**
-```javascript
-// services/my-service/tests/integration/pre-validation-process.test.js
-const { createPreValidationTests } = require('@onlineapps/conn-orch-validator');
-
-createPreValidationTests(__dirname);
-```
-
-**Options:**
-```javascript
-createPreValidationTests(__dirname, {
-  timeout: 60000  // Test timeout in ms (default: 60000)
-});
-```
-
-**Test Structure:**
-1. Pre-requisites Check
-   - cookbooks/ directory exists
-   - operations.json exists
-   - Pre-validation script configured
-2. Cookbook Test Execution
-   - Runs npm run test:cookbooks
-   - Verifies infrastructure mocking
-3. ValidationProof Generation
-   - Creates .validation-proof.json
-   - Validates proof structure
-   - Checks SHA256 hash
-4. Proof Integrity Verification
-   - ValidationProofCodec decode
-   - Hash matching
-   - Age verification
-   - Tamper detection
-5. Dependencies Tracking
-   - Proof includes @onlineapps/* versions
-
----
-
 ## How It Works
 
 ### Automatic Structure Validation
 
-Both helpers use `ServiceStructureValidator` to validate service structure BEFORE running tests:
+The helper uses `ServiceStructureValidator` to validate service structure BEFORE running tests:
 
 ```
 🔍 Validating service structure...
@@ -156,7 +104,7 @@ If validation fails, clear error messages are shown:
 
 ### Zero Configuration
 
-Helpers automatically detect and load:
+The helper automatically detects and loads:
 
 ```javascript
 // Service root (2 levels up from tests/integration/)

package/src/helpers/createServiceReadinessTests.js

@@ -31,6 +31,7 @@ const fs = require('fs');
 const ServiceReadinessValidator = require('../ServiceReadinessValidator');
 const MockRegistry = require('../mocks/MockRegistry');
 const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
+const { MIN_COOKBOOK_FORMAT_VERSION } = require('../utils/cookbookFormat');
 
 /**
  * Create service readiness integration test suite
@@ -97,7 +98,10 @@ function createServiceReadinessTests(testsDir, options = {}) {
       if (includeOptionalChecks) {
         mockRegistry = new MockRegistry();
         testCookbook = {
-          version: '1.0.0',
+          // Cookbook FORMAT version — the synthesised cookbook must satisfy the
+          // same rule the Tier-1 gate enforces (api/docs/biz/40-cookbooks/format.md
+          // § Required fields), otherwise this helper rejects its own output.
+          version: MIN_COOKBOOK_FORMAT_VERSION,
           steps: Object.entries(operationsFlat).map(([name, op]) => ({
             id: `test-${name}`,
             type: 'task',

package/src/index.js

@@ -33,7 +33,6 @@ const ServiceReadinessValidator = require('./ServiceReadinessValidator');
 const ValidationOrchestrator = require('./ValidationOrchestrator');
 
 const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
-const { createPreValidationTests } = require('./helpers/createPreValidationTests');
 
 module.exports = {
   get MockMQClient() { return MockMQClient; },
@@ -48,9 +47,13 @@ module.exports = {
   get ServiceStructureValidator() { return ServiceStructureValidator; },
   get ValidationOrchestrator() { return ValidationOrchestrator; },
 
+  // The namespace an integration test may write into — read from the platform
+  // env, never chosen per test. Enforced by deploy-contract R8.
+  get getTestNamespace() { return require('./utils/testNamespace').getTestNamespace; },
+
   get createServiceReadinessTests() { return createServiceReadinessTests; },
-  get createPreValidationTests() { return createPreValidationTests; },
   get BizCiGateContract() { return BizCiGateContract; },
+  get IntegrationRun() { return require('./utils/integrationRun'); },
 
   createMockMQ: () => new MockMQClient(),
   createMockRegistry: () => new MockRegistry(),