@onlineapps/conn-orch-validator 3.3.1 → 4.0.0

package/src/utils/setupDatabase.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * The one schema build for every biz service.
+ *
+ * The service declares WHAT its database is in integration-contract.json; this
+ * decides HOW it gets built, identically for all of them
+ * (docs/biz/00-model/uniformity-principle.md).
+ *
+ * It replaces six per-repo ci-setup-db.js scripts that had each solved the same
+ * problem differently — 113, 69, 56, 54, 22 and 20 lines, in three strategies,
+ * two of which bypassed migrations entirely with sequelize.sync(). That bypass
+ * let a service's CI prove a schema built from models while production ran one
+ * built from hand-applied migrations. There is deliberately no option here to
+ * build from anything but the migrations: the absence is what makes the bypass
+ * impossible rather than merely discouraged.
+ *
+ * Two invariants, both from ADR 0006:
+ *
+ *   §2 every .sql file in the declared directory is applied, in sorted order.
+ *      No list lives in this file — the set grows with each schema change, and a
+ *      list would drift until a missing table surfaced in an unrelated test.
+ *
+ *   §3 foreign key checks stay ON. Deferring them would let a migration
+ *      reference a table a later file creates and still report success, which is
+ *      the exact defect class building from empty exists to catch.
+ *
+ * SQL runs through the mysql/mariadb CLI rather than a driver, because trigger
+ * definitions use DELIMITER — a client directive drivers report as a syntax
+ * error. The executor is injected so the decisions are testable without a
+ * database.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function requireValue(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`[SetupDatabase] Missing ${name} - Expected a value. `
+      + `Fix: set ${name} in the CI job (or env-active/*.env locally).`);
+  }
+  return value;
+}
+
+/**
+ * Decide which files to apply and in what order.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {{migrations: string, seeds: string[]}} database the contract declaration
+ */
+function resolveMigrationPlan(serviceRoot, database) {
+  // The declaration is a glob-ish path; only the directory part is read, and
+  // only its own .sql files — subdirectories such as migrations/superseded/ hold
+  // the record of how a baseline was reached and must not be replayed.
+  const dir = path.resolve(serviceRoot, path.dirname(database.migrations));
+
+  if (!fs.existsSync(dir)) {
+    throw new Error(`[SetupDatabase] Migrations directory not found: ${dir}\n`
+      + `       Fix: create it, or correct database.migrations in the integration contract.`);
+  }
+
+  const migrations = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => path.join(dir, name));
+
+  if (migrations.length === 0) {
+    throw new Error(`[SetupDatabase] No .sql files in ${dir} - refusing to report a schema as built.\n`
+      + '       Fix: the migration set is the source of truth for the schema; it cannot be empty.');
+  }
+
+  const seeds = (database.seeds ?? []).map((seed) => {
+    const file = path.resolve(serviceRoot, seed);
+    if (!fs.existsSync(file)) {
+      throw new Error(`[SetupDatabase] Declared seed not found: ${seed}\n`
+        + '       Fix: correct database.seeds in the integration contract, or add the file.');
+    }
+    return file;
+  });
+
+  return { dir, migrations, seeds };
+}
+
+/** Run one statement or file through the CLI client. Injectable for tests. */
+function defaultExec({ connection, schema, sql, file }) {
+  const client = ['mariadb', 'mysql'].find((bin) => !spawnSync(bin, ['--version'], { encoding: 'utf8' }).error);
+  if (!client) {
+    return {
+      status: 1,
+      stderr: '[SetupDatabase] No mysql/mariadb client on PATH - required because migrations use DELIMITER. '
+        + 'Fix: install mariadb-client in the CI job image.'
+    };
+  }
+
+  const args = ['-h', connection.host, '-P', String(connection.port), '-u', connection.user,
+    '--default-character-set=utf8mb4'];
+  // MariaDB Connector/C 3.x requires TLS by default and the CI database is a
+  // sidecar with none; the connection never leaves the job's private network.
+  if (connection.requireTls !== true) args.push('--skip-ssl');
+  if (connection.password) args.push(`-p${connection.password}`);
+  if (schema) args.push(schema);
+
+  const result = spawnSync(client, args, {
+    input: sql !== undefined ? sql : fs.readFileSync(file, 'utf8'),
+    encoding: 'utf8'
+  });
+
+  return {
+    status: result.error ? 1 : result.status,
+    stderr: result.error ? result.error.message
+      : (result.stderr || '').split('\n').filter((l) => !l.includes('Using a password')).join('\n').trim()
+  };
+}
+
+/**
+ * Build the schema from the declared migrations.
+ *
+ * @returns {{schema: string, migrationsApplied: number, seedsApplied: number}}
+ */
+function buildSchema({ serviceRoot, database, connection, exec = defaultExec }) {
+  requireValue(connection?.host, 'DB_HOST');
+  requireValue(connection?.user, 'DB_USER');
+  const port = connection.port ?? 3306;
+
+  const conn = { ...connection, port };
+  const plan = resolveMigrationPlan(serviceRoot, database);
+
+  const created = exec({ connection: conn, sql: `CREATE DATABASE IF NOT EXISTS \`${database.schema}\`;` });
+  if (created.status !== 0) {
+    throw new Error(`[SetupDatabase] Could not create schema ${database.schema}:\n${created.stderr}`);
+  }
+
+  const apply = (file, kind) => {
+    const result = exec({ connection: conn, schema: database.schema, file });
+    if (result.status !== 0) {
+      throw new Error(`[SetupDatabase] ${kind} ${path.basename(file)} failed:\n${result.stderr}\n`
+        + '       Fix: the set must apply to an empty database in file order. Either the SQL is wrong, '
+        + 'or the file is numbered before something it depends on.');
+    }
+  };
+
+  for (const file of plan.migrations) apply(file, 'Migration');
+  for (const file of plan.seeds) apply(file, 'Seed');
+
+  return {
+    schema: database.schema,
+    migrationsApplied: plan.migrations.length,
+    seedsApplied: plan.seeds.length
+  };
+}
+
+module.exports = { resolveMigrationPlan, buildSchema };

package/src/utils/stepFailure.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * One owner for the sentence that says WHY a cookbook step failed.
+ *
+ * Two consumers read it and they must not drift apart:
+ *   - CookbookTestRunner.executeStep — the per-step log line at boot;
+ *   - ValidationOrchestrator.runCookbookTests — the step-4 error list that
+ *     reaches `results.errors`, the wrapper's `Validation failed: …` message
+ *     and validation.responses.
+ *
+ * Before 2026-08-29 neither of them said anything: the log line was
+ * `Step count_stub: FAILED (1101ms)` and the orchestrator's only error was
+ * `1 cookbook test(s) failed`. The reason existed the whole time in
+ * `result.validationErrors` / `result.error` and was discarded at both ends,
+ * so a failed biz-hello boot could not be diagnosed from its own logs
+ * (automation-gates.md §5 — silence is a defect).
+ */
+
+/**
+ * Why this step failed, in one line, from whichever field holds it.
+ *
+ * @param {Object} stepResult - a step result produced by CookbookTestRunner
+ * @returns {string} the concrete reason; never an empty string
+ */
+function describeStepFailure(stepResult) {
+  if (!stepResult || typeof stepResult !== 'object') {
+    throw new Error('[stepFailure] stepResult is required - Expected the step result object produced by CookbookTestRunner');
+  }
+
+  const parts = [];
+
+  if (Array.isArray(stepResult.validationErrors) && stepResult.validationErrors.length > 0) {
+    parts.push(stepResult.validationErrors.join('; '));
+  }
+
+  const error = stepResult.error;
+  if (typeof error === 'string' && error.length > 0) {
+    parts.push(error);
+  } else if (error && typeof error === 'object') {
+    parts.push(`${error.code || 'HANDLER_ERROR'}: ${error.message}`);
+  }
+
+  if (typeof stepResult.errorStack === 'string' && stepResult.errorStack.length > 0) {
+    parts.push(stepResult.errorStack);
+  }
+
+  if (parts.length === 0) {
+    // A step marked failed with nothing recorded is itself a defect; say so
+    // rather than printing an empty reason that reads like "no problem".
+    return 'no reason recorded — neither validationErrors nor error was set on the step result';
+  }
+
+  return parts.join(' | ');
+}
+
+/**
+ * The same reason, prefixed with enough context to find the case: which
+ * cookbook, which step, which operation. This is what step 4 puts into
+ * `results.errors`.
+ *
+ * @param {Object} stepResult - a step result carrying `cookbook`
+ * @returns {string}
+ */
+function describeStepFailureWithContext(stepResult) {
+  const reason = describeStepFailure(stepResult);
+  const cookbook = stepResult.cookbook || 'unknown cookbook';
+  const stepId = stepResult.id || stepResult.step_id || 'unnamed step';
+  const operation = stepResult.operation ? ` (${stepResult.operation})` : '';
+  return `cookbook "${cookbook}" step "${stepId}"${operation}: ${reason}`;
+}
+
+module.exports = { describeStepFailure, describeStepFailureWithContext };

package/src/utils/testNamespace.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * The tenant / workspace an integration test is allowed to write into.
+ *
+ * An integration test reaches a real database, so the namespace it targets is a
+ * safety boundary. Two incidents show what happens when that boundary is
+ * written per file instead of read from one source:
+ *
+ *   biz-property and biz-converter overrode TESTING_TENANT_ID in their own env
+ *   template to point at the LIVE tenant, because that is where their cookbook
+ *   fixtures happened to exist. The Tier-1 runner executes real handler
+ *   dispatch at every service start, production included — so every restart
+ *   wrote into real data, and did.
+ *
+ *   24 of biz-property's 26 integration tests carried their own
+ *   `const TENANT = 100` and inserted and deleted under it. Nothing could
+ *   redirect them, because there was nothing to redirect.
+ *
+ * So the value comes from the platform env (`TESTING_TENANT_ID` /
+ * `TESTING_WORKSPACE_ID`, set in `config/env-templates/shared.env`) and this
+ * module is the only place that reads it. It throws when the env is absent
+ * rather than guessing: a test that does not know which namespace it owns must
+ * not write anywhere at all.
+ *
+ * Enforced by deploy-contract requirement R8 (see utils/deployContract.js).
+ */
+
+/**
+ * The environment classes a validation or test run may write into.
+ *
+ * This is a WHITELIST, and that is the whole point. The previous rule refused
+ * the one tenant an env var declared live (`PLATFORM_LIVE_TENANT_ID=100`), which
+ * left every customer tenant — 101+, production, real data, 101 = Meditest —
+ * outside the guard, and the gap grew with every customer onboarded. Naming what
+ * is permitted cannot grow a gap: a class that is not on this list is refused
+ * whether or not anyone remembered to declare it.
+ *
+ * Why the values live in the library and not in the environment: they are a
+ * CONTRACT CONSTANT taken from a normative standard, not a deployment knob. The
+ * standard says WHAT each tenant id means (an environment class, allocated once,
+ * "Adding a class — do not"); this module is the HOW of enforcing it at run time.
+ * Architecture principle §2 (No Hardcoded Values) targets configuration of an
+ * environment — ports, hosts, timeouts, credentials — which differs per
+ * deployment by design. This boundary does not: it is identical in every
+ * environment because the norm defines it, and making it env-settable would hand
+ * the very misconfiguration this guard exists to stop a switch to turn it off.
+ *
+ * @see api/docs/standards/tenant-allocation.md § "The allocation"
+ */
+const ALLOWED_TENANT_CLASSES = Object.freeze([
+  96, // CI
+  97, // TESTING
+  98, // DEVEL
+  99 //  VALIDATION
+]);
+
+function readNamespaceId(key) {
+  const raw = process.env[key];
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    throw new Error(`[TestNamespace] Missing environment variable - ${key} is required. `
+      + 'Fix: set it in config/env-active/shared.env (the platform default is the '
+      + 'non-production namespace). An integration test may not pick a namespace itself.');
+  }
+  const value = Number(String(raw).trim());
+  if (!Number.isInteger(value)) {
+    throw new Error(`[TestNamespace] Invalid ${key}="${raw}" - Expected an integer id. `
+      + 'Fix: correct the value in config/env-active/shared.env.');
+  }
+  return value;
+}
+
+/**
+ * @returns {{tenant_id: number, workspace_id: number}} ctx-shaped, so it can be
+ *          spread straight into a handler call.
+ */
+function getTestNamespace() {
+  const tenantId = readNamespaceId('TESTING_TENANT_ID');
+
+  // The runtime half of the protection, and the reason the tenant is decided
+  // before anything else is read. R8 rejects a per-service override before it
+  // ships; this refuses the accident that ships anyway, so a startup probe can
+  // never reach real data even if the configuration is wrong.
+  //
+  // The workspace id is deliberately NOT class-checked: tenant-allocation.md
+  // allocates environment classes to TENANTS, and calls a workspace "the purpose
+  // within the class" without naming any range for it. A restriction here would
+  // be one this library invented.
+  if (!ALLOWED_TENANT_CLASSES.includes(tenantId)) {
+    throw new Error(`[TestNamespace] TESTING_TENANT_ID=${tenantId} is not an allowed `
+      + 'environment class - test and validation runs may never write into production data '
+      + '(100 = LIVE, 101+ = CUSTOMER tenants, both refused). Expected one of 96 (CI), '
+      + '97 (TESTING), 98 (DEVEL), 99 (VALIDATION). Fix: set TESTING_TENANT_ID to one of '
+      + 'those classes in config/env-active/shared.env and seed that namespace from '
+      + 'migrations/ - see api/docs/standards/tenant-allocation.md.');
+  }
+
+  return {
+    tenant_id: tenantId,
+    workspace_id: readNamespaceId('TESTING_WORKSPACE_ID')
+  };
+}
+
+module.exports = { getTestNamespace };