@onlineapps/conn-orch-validator 3.3.1 → 4.0.0

package/src/utils/deployContract.js

@@ -0,0 +1,488 @@
+'use strict';
+
+/**
+ * Deploy contract checks R1-R7 for a biz service repository.
+ *
+ * Requirements: api/docs/operations/biz-rework-deployment-requirements.md
+ * Database rules: ADR 0006 (api/docs/biz/80-decisions/)
+ *
+ *   R1  the production compose pins its image immutably
+ *   R2  the deploy resets to origin/production rather than merging
+ *   R3  CI Node major == Dockerfile Node major == engines.node major
+ *   R4  no published ports — the only public entrypoint is doorman
+ *   R5  images tagged with the full commit SHA, never the short one
+ *   R7  the CI database engine is the one the service actually talks to
+ *   R8  tenant / workspace identity has exactly one source
+ *
+ * Pure module: reads the repository, returns a structured result. It renders
+ * nothing and exits nothing — the CLI owns presentation, this owns the rules.
+ * That split is what lets the api-side cross-repo audit reuse the same logic
+ * instead of keeping a second copy that drifts.
+ *
+ * Every violated requirement is reported, not just the first, so a repo can be
+ * fixed in one pass.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const IDENTIFIER_ONLY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const REQUIRED_MARKER = /[@:]\$\{[A-Za-z_][A-Za-z0-9_]*:\?[^}]*\}$/;
+const BARE_VARIABLE = /\$\{[A-Za-z_][A-Za-z0-9_]*(:-[^}]*)?\}$/;
+
+function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** Strip surrounding whitespace, then surrounding quotes — internal spaces stay,
+ *  because they live inside the ${VAR:?message} marker. */
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+function nodeMajor(text) {
+  const match = /(\d+)/.exec(text);
+  return match ? match[1] : null;
+}
+
+function checkImagePins(compose, add) {
+  const ownImages = compose
+    .split('\n')
+    .filter((line) => /^\s*image:/.test(line) && /onlineapps/.test(line));
+
+  if (ownImages.length === 0) {
+    add('R1', 'No own-registry image found in docker-compose.production.yml. '
+      + 'Fix: the service must reference the image its CI builds.');
+    return;
+  }
+
+  for (const line of ownImages) {
+    const ref = unquote(line.slice(line.indexOf('image:') + 'image:'.length));
+
+    if (ref.includes('@sha256:') || REQUIRED_MARKER.test(ref)) continue;
+
+    if (ref.includes(':latest') || ref.includes(':-latest}')) {
+      add('R1', `Image resolves to the mutable tag 'latest': ${ref}\n`
+        + '       Two concurrent pipelines make it nondeterministic between push and pull, and rollback has no target.\n'
+        + '       Fix: pin by digest, e.g. image: <repo>@${BIZ_IMAGE_DIGEST:?BIZ_IMAGE_DIGEST is required}');
+    } else if (BARE_VARIABLE.test(ref)) {
+      add('R1', `Image variable has no required-marker: ${ref}\n`
+        + '       A bare ${VAR} resolves to empty when unset, producing a nameless image instead of an error.\n'
+        + '       Fix: use ${VAR:?VAR is required} so a missing value fails immediately with the key name.');
+    } else {
+      add('R1', `Image is pinned to a literal mutable tag: ${ref}\n`
+        + '       Fix: pin by digest, e.g. image: <repo>@${BIZ_IMAGE_DIGEST:?BIZ_IMAGE_DIGEST is required}');
+    }
+  }
+}
+
+function checkPublishedPorts(compose, add) {
+  const ports = compose.split('\n').filter((line) => /^\s*ports:/.test(line));
+  if (ports.length > 0) {
+    add('R4', 'Published ports found in docker-compose.production.yml.\n'
+      + '       Docker publishes past UFW, so a published port is reachable from the internet regardless of firewall rules.\n'
+      + '       Fix: remove the ports block; biz services talk over internal docker networks and the only public entrypoint is doorman.');
+  }
+}
+
+function checkDeploySequence(ci, add) {
+  if (/(^|[^\w-])git\s+pull([^\w-]|$)/m.test(ci)) {
+    add('R2', "'git pull' in the deploy path.\n"
+      + '       A local modification on the server turns the merge into a conflict and aborts the deploy halfway.\n'
+      + '       Fix: git fetch origin production && git reset --hard origin/production');
+  }
+  if (!/git\s+reset\s+--hard\s+origin\/production/.test(ci)) {
+    add('R2', "No 'git reset --hard origin/production' found in .gitlab-ci.yml.\n"
+      + '       Fix: the deploy must force the working tree to the pushed commit, matching the infra contract.');
+  }
+}
+
+function checkCommitShaScheme(ci, add) {
+  if (ci.includes('CI_COMMIT_SHORT_SHA')) {
+    add('R5', 'CI_COMMIT_SHORT_SHA used for image identity.\n'
+      + '       Infra tags with the full $CI_COMMIT_SHA; two lengths mean two schemes and the release manifest needs one.\n'
+      + '       Fix: use $CI_COMMIT_SHA.');
+  }
+}
+
+function checkNodeMajors(serviceRoot, ci, add) {
+  const pkgRaw = readIfExists(path.join(serviceRoot, 'package.json'));
+  if (pkgRaw === null) {
+    add('R3', 'package.json not found — the Node major cannot be checked.');
+    return;
+  }
+
+  let declared;
+  try {
+    declared = JSON.parse(pkgRaw).engines?.node;
+  } catch (err) {
+    add('R3', `package.json is not valid JSON - ${err.message}`);
+    return;
+  }
+  if (!declared) {
+    add('R3', 'package.json declares no engines.node.\n'
+      + '       Fix: declare the supported major explicitly, e.g. "engines": { "node": ">=22.0.0 <23" }; '
+      + 'it is the reference the CI image and Dockerfile are checked against.');
+    return;
+  }
+
+  const expected = nodeMajor(declared);
+
+  const dockerfile = readIfExists(path.join(serviceRoot, 'Dockerfile'));
+  if (dockerfile !== null) {
+    for (const line of dockerfile.split('\n')) {
+      if (!/^\s*FROM\s+node:/.test(line)) continue;
+      const major = nodeMajor(line.slice(line.indexOf('node:') + 'node:'.length));
+      if (major !== expected) {
+        add('R3', `Dockerfile ships Node ${major} but engines.node requires ${expected}: ${line.trim()}\n`
+          + '       Fix: align the base image with engines.node.');
+      }
+    }
+  }
+
+  for (const line of ci.split('\n')) {
+    if (!/^\s*image:\s*node:/.test(line)) continue;
+    const major = nodeMajor(line.slice(line.indexOf('node:') + 'node:'.length));
+    if (major !== expected) {
+      add('R3', `CI tests on Node ${major} but the service ships and declares ${expected}: ${line.trim()}\n`
+        + '       Testing on a different major than production runs means a passing pipeline proves nothing about the shipped runtime.\n'
+        + `       Fix: set the CI image to node:${expected}-alpine.`);
+    }
+  }
+}
+
+/** DB_HOST as declared in the service's env templates, or null. */
+function declaredDbHost(serviceRoot) {
+  const templatesDir = path.join(serviceRoot, 'config', 'env-templates');
+  if (!fs.existsSync(templatesDir)) return null;
+
+  for (const entry of fs.readdirSync(templatesDir).sort()) {
+    if (!entry.endsWith('.env')) continue;
+    const content = readIfExists(path.join(templatesDir, entry));
+    if (content === null) continue;
+    const match = /^DB_HOST=(.*)$/m.exec(content);
+    if (match) return unquote(match[1]);
+  }
+  return null;
+}
+
+function engineFamilyOfHost(host) {
+  const lower = (host ?? '').toLowerCase();
+  if (lower.includes('maria')) return 'mariadb';
+  if (lower.includes('mysql')) return 'mysql';
+  return null;
+}
+
+/** Database service images the CI file declares, e.g. {"mariadb:10.5"}. */
+function ciEngineImages(ci) {
+  const engines = new Set();
+  const pattern = /\b(mariadb|mysql):[0-9][0-9.]*/g;
+  let hit;
+  while ((hit = pattern.exec(ci)) !== null) engines.add(hit[0]);
+  return engines;
+}
+
+/**
+ * ADR 0006 §1 — the CI engine must be the one the service actually talks to.
+ *
+ * Two sources, in order of authority:
+ *
+ *   database.engine in integration-contract.json declares engine AND version,
+ *   so CI must run exactly that image. This is the target state (F1/F4).
+ *
+ *   DB_HOST in config/env-templates/ only implies a family, which is all that
+ *   can be inferred from a hostname. It governs repos that have not declared
+ *   yet, and it is not a fallback for a declared one — where both exist they
+ *   must agree, and disagreement is itself reported.
+ */
+function checkDatabaseEngine(serviceRoot, ci, add) {
+  const host = declaredDbHost(serviceRoot);
+  const hostFamily = engineFamilyOfHost(host);
+
+  const contractRaw = readIfExists(path.join(serviceRoot, 'config', 'service', 'integration-contract.json'));
+  let declaredEngine = null;
+  if (contractRaw !== null) {
+    try {
+      declaredEngine = JSON.parse(contractRaw).database?.engine ?? null;
+    } catch {
+      // A contract that cannot be parsed must not silently disable the check;
+      // the engine falls back to nothing and the host-based path still applies.
+      add('R7', 'config/service/integration-contract.json is not valid JSON — the declared database engine cannot be read.\n'
+        + '       Fix: repair the contract; an unreadable declaration must never leave a check silently disabled.');
+    }
+  }
+
+  const images = ciEngineImages(ci);
+
+  if (declaredEngine) {
+    const declaredFamily = declaredEngine.split(':')[0];
+
+    if (hostFamily && hostFamily !== declaredFamily) {
+      add('R7', `Contradictory declaration: the contract declares ${declaredEngine} but DB_HOST is "${host}" (a ${hostFamily} host).\n`
+        + '       Two statements about the same fact must agree; the contract does not overrule the environment the service connects to.\n'
+        + '       Fix: correct database.engine in the integration contract, or DB_HOST in config/env-templates/.');
+    }
+
+    if (images.size === 0) {
+      add('R7', `The contract declares ${declaredEngine} but .gitlab-ci.yml declares no database service.\n`
+        + '       The schema cannot be built, so the integration suite would run against nothing.\n'
+        + `       Fix: add a service block with image ${declaredEngine}.`);
+      return;
+    }
+
+    for (const image of images) {
+      if (image !== declaredEngine) {
+        add('R7', `CI runs ${image} but the contract declares ${declaredEngine}.\n`
+          + '       The declaration pins the version as well as the vendor: a schema built on one version is not proven by a run on another.\n'
+          + `       Fix: set the CI service image to ${declaredEngine}, or correct database.engine in the integration contract.`);
+      }
+    }
+    return;
+  }
+
+  // No declaration yet (pre-F4). A service with no database says nothing about
+  // engines, so stay silent; otherwise compare families only.
+  if (!hostFamily) return;
+
+  for (const image of images) {
+    if (!image.startsWith(`${hostFamily}:`)) {
+      add('R7', `CI runs ${image} but the service is configured against "${host}" (expects ${hostFamily}).\n`
+        + '       Testing on an engine the service never talks to proves nothing about its SQL: MariaDB-only syntax passes there and fails here, or the reverse.\n'
+        + `       Fix: set the CI service image to ${hostFamily}, matching DB_HOST in config/env-templates/.`);
+    }
+  }
+}
+
+// ── R8 — one source for tenant / workspace identity ────────────────────────
+//
+// Two incidents define this requirement.
+//
+// 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, verifiably.
+//
+// One layer down, 24 of biz-property's 26 integration tests carried their own
+// `const TENANT = 100` and inserted and deleted under it. Identity that should
+// arrive from ctx or from the platform env, frozen into code where nothing can
+// redirect it.
+//
+// Scope is deliberate rather than maximal:
+//
+//   src/, scripts/          no literal — production code and operational
+//                           scripts take identity from ctx / arguments / env.
+//   tests/integration/      must take the namespace from the repo's shared
+//                           test-namespace module. A positive rule, because the
+//                           literal hides behind any name a test invents
+//                           (`const T = 100`) and pattern-hunting loses.
+//   config/env-templates/   only shared.env may name the runner namespace.
+//   tests/unit/             exempt — pure in-memory mocks reach no database,
+//                           so a literal there is not a safety boundary, and
+//                           banning it would only teach people to obfuscate it.
+//   migrations/, docs/      exempt — seed data legitimately names its tenant.
+
+const NAMESPACE_ENV_KEYS = ['TESTING_TENANT_ID', 'TESTING_WORKSPACE_ID'];
+
+/** `tenant_id: 100`, `workspace_id = 1` — an identity frozen to a number. */
+const LITERAL_NAMESPACE = /\b(tenant_id|workspace_id)\s*(?::|={1,3})\s*\d+/;
+/** `const TENANT_ID = 100`, `let testWorkspaceId = 1` — the same thing, named. */
+const LITERAL_NAMESPACE_CONST =
+  /\b(?:const|let|var)\s+[A-Za-z_$][A-Za-z0-9_$]*(?:tenant|workspace)[A-Za-z0-9_$]*\s*=\s*\d+/i;
+
+const SCANNED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.json']);
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'coverage', 'dist', 'build']);
+
+/** True for the repo's shared test-namespace module, whatever it is named. */
+function isNamespaceModule(relativePath) {
+  return /(^|\/)(test-?namespace)[^/]*\.js$/i.test(relativePath);
+}
+
+/**
+ * True when the file actually CALLS the shared helper, on a line that executes.
+ *
+ * The permit used to be a whole-file text match, so a comment saying "TODO:
+ * switch to getTestNamespace()" excused the file from R8 entirely — a rule that
+ * a mention satisfies checks nothing (`automation-gates.md` §5). Nothing in any
+ * biz repo relied on the loose form: the two files that contain the word are the
+ * repo-local namespace modules, and those are handled above and never reach here.
+ */
+function callsNamespaceHelper(text) {
+  return text
+    .split('\n')
+    .some((line) => !isCommentLine(line) && /\bgetTestNamespace\s*\(/.test(line));
+}
+
+/** A literal inside a comment is prose — it cannot reach a database. */
+function isCommentLine(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+
+function walkFiles(dir, base, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(full, base, out);
+    } else if (SCANNED_EXTENSIONS.has(path.extname(entry.name))) {
+      out.push({ full, relative: path.relative(base, full).split(path.sep).join('/') });
+    }
+  }
+  return out;
+}
+
+/** Only shared.env may name the runner namespace; a per-service override is the incident. */
+function checkNamespaceEnvOverride(serviceRoot, add) {
+  const templates = path.join(serviceRoot, 'config', 'env-templates');
+  let entries;
+  try {
+    entries = fs.readdirSync(templates);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.env') || name === 'shared.env') continue;
+    const text = readIfExists(path.join(templates, name));
+    if (text === null) continue;
+    for (const key of NAMESPACE_ENV_KEYS) {
+      const match = new RegExp(`^\\s*${key}\\s*=(.*)$`, 'm').exec(text);
+      if (!match) continue;
+      add('R8', `config/env-templates/${name} overrides ${key}=${match[1].trim()}.\n`
+        + '       The Tier-1 cookbook runner fires at every service start, production\n'
+        + '       included, and writes into whatever namespace this names. Pointing it\n'
+        + '       at a workspace that holds real data means every restart writes there.\n'
+        + `       Fix: delete the override and let shared.env's platform default apply;\n`
+        + '       seed the runner namespace from migrations/ instead.');
+    }
+  }
+}
+
+/** No literal identity in code that can reach a real database. */
+function checkNamespaceLiterals(serviceRoot, add) {
+  for (const dir of ['src', 'scripts']) {
+    for (const file of walkFiles(path.join(serviceRoot, dir), serviceRoot, [])) {
+      const text = readIfExists(file.full);
+      if (text === null) continue;
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        add('R8', `${file.relative}:${i + 1} freezes a tenant / workspace id into code:\n`
+          + `       ${lines[i].trim()}\n`
+          + '       Fix: take it from ctx (handlers), from a CLI argument (scripts),\n'
+          + '       or from the platform env — never from a literal.');
+        break; // one report per file is enough to act on
+      }
+    }
+  }
+}
+
+/** Integration tests reach a real database, so their namespace has one owner. */
+function checkIntegrationNamespaceSource(serviceRoot, add) {
+  const root = path.join(serviceRoot, 'tests', 'integration');
+  for (const file of walkFiles(root, serviceRoot, [])) {
+    const text = readIfExists(file.full);
+    if (text === null) continue;
+
+    // The namespace module is the one place allowed to name the namespace — so
+    // it is also the one place that must not freeze it. It reads the platform
+    // env; otherwise the single source is merely a single hardcoding.
+    if (isNamespaceModule(file.relative)) {
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        if (!LITERAL_NAMESPACE.test(lines[i]) && !LITERAL_NAMESPACE_CONST.test(lines[i])) continue;
+        add('R8', `${file.relative}:${i + 1} freezes the test namespace into a literal:\n`
+          + `       ${lines[i].trim()}\n`
+          + '       This module exists so the namespace has one source; that source must\n'
+          + '       be the platform env, not a number typed here.\n'
+          + '       Fix: read TESTING_* from process.env and fail fast when it is absent.');
+        break;
+      }
+      continue;
+    }
+
+    if (!/tenant_id|workspace_id/i.test(text)) continue;
+    // Either the shared helper from conn-orch-validator, or a repo-local module
+    // that itself reads the platform env (checked above).
+    if (callsNamespaceHelper(text)) continue;
+    if (/require\([^)]*test-?namespace[^)]*\)/i.test(text)) continue;
+    add('R8', `${file.relative} names a tenant / workspace without taking it from the\n`
+      + '       shared test-namespace module.\n'
+      + '       An integration test writes into a real database, so the namespace it\n'
+      + '       targets is a safety boundary — and a boundary rewritten per file is a\n'
+      + '       boundary that drifts onto a live tenant.\n'
+      + '       Fix: require the repo\'s tests/integration/testNamespace.js and use it.');
+  }
+}
+
+/**
+ * Verify one biz repository against R1-R8.
+ *
+ * @param {string} serviceRoot absolute path to the biz repo
+ * @returns {{service: string, ok: boolean, violations: Array<{requirement: string, message: string}>}}
+ */
+function verifyDeployContract(serviceRoot) {
+  if (!serviceRoot || typeof serviceRoot !== 'string') {
+    throw new Error('[DeployContract] Missing serviceRoot - Expected the path to a biz repository. '
+      + 'Fix: pass --service-root <path> (defaults to the current working directory).');
+  }
+  if (!fs.existsSync(serviceRoot)) {
+    throw new Error(`[DeployContract] Service root not found: ${serviceRoot}`);
+  }
+
+  const violations = [];
+  const add = (requirement, message) => violations.push({ requirement, message });
+
+  const compose = readIfExists(path.join(serviceRoot, 'docker-compose.production.yml'));
+  if (compose === null) {
+    add('R1', 'docker-compose.production.yml not found — R1 and R4 cannot be checked.\n'
+      + '       Fix: this file is part of the deployable contract; restore it.');
+  } else {
+    checkImagePins(compose, add);
+    checkPublishedPorts(compose, add);
+  }
+
+  const ci = readIfExists(path.join(serviceRoot, '.gitlab-ci.yml'));
+  if (ci === null) {
+    add('R2', '.gitlab-ci.yml not found — R2, R3, R5 and R7 cannot be checked.\n'
+      + '       Fix: this file is part of the deployable contract; restore it.');
+  } else {
+    checkDeploySequence(ci, add);
+    checkCommitShaScheme(ci, add);
+    checkNodeMajors(serviceRoot, ci, add);
+    checkDatabaseEngine(serviceRoot, ci, add);
+  }
+
+  // R8 reads the repository tree directly — it depends on neither compose nor CI.
+  checkNamespaceEnvOverride(serviceRoot, add);
+  checkNamespaceLiterals(serviceRoot, add);
+  checkIntegrationNamespaceSource(serviceRoot, add);
+
+  return {
+    service: path.basename(path.resolve(serviceRoot)),
+    ok: violations.length === 0,
+    violations
+  };
+}
+
+module.exports = { verifyDeployContract };