@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/utils/testCoverageContract.js

@@ -0,0 +1,539 @@
+'use strict';
+
+/**
+ * Test-coverage contract — every test file the service has is RUN somewhere,
+ * and the somewhere is either `test:all` or a declared stack tier.
+ *
+ * A test suite that runs nowhere fails nowhere. It sits in the repository
+ * looking like coverage, it is green whenever somebody runs it by hand, and
+ * nothing reports that CI never touches it. Measured over the eight biz
+ * repositories on 2026-09-07: hello-service matched 17 test files and ran 14 —
+ * the three `tests/bootstrap/*` suites were in no job at all.
+ *
+ * ## What the gate compares
+ *
+ *   T  every file the service's jest config matches       `jest --listTests`
+ *   A  every file the `test:all` chain runs               the chain decomposed
+ *                                                         (`npm run …`) down to
+ *                                                         jest invocations, each
+ *                                                         asked `--listTests`
+ *   B  every file the declared stack tiers run            same, per declared script
+ *   D  every platform test file present on disk           the repository walked,
+ *                                                         `**\/tests\/**\/*.test.js`
+ *
+ * ## Why the disk is a side of the comparison at all
+ *
+ * T, A and B all ask the SAME jest. Narrow `testMatch` to `tests/unit`, and
+ * `tests/integration/` disappears from every one of them at once: absent from T
+ * and absent from A, it cannot fall out of T \ (A ∪ B), and the gate prints OK
+ * over a suite that runs nowhere. Measured 2026-09-08 on a fixture repository —
+ * `EXIT=0`, "1 file(s) matched, 1 run by the test:all chain", with
+ * `tests/integration/beta.spec.js` on disk and in no job.
+ *
+ * So the gate asks one question jest cannot be the source for: what is actually
+ * THERE. What counts as a test file on disk is the PLATFORM's `testMatch`, not
+ * the service's — the service's is the thing under test, and a pattern invented
+ * here would be a third opinion nobody declared. The platform pattern is the one
+ * `templates/business-service/jest.config.js` declares, and all eight biz
+ * repositories use it verbatim (verified 2026-09-08).
+ *
+ * The decomposition asks JEST, never a parser. A parse of `jest --config
+ * jest.config.js tests/unit --runInBand` answers with the shape of the command;
+ * only jest answers with the files, and the files are the question. That is also
+ * why the jest binary is the SERVICE's own (resolved from its `node_modules`),
+ * not this package's: a different jest version resolves a different `testMatch`.
+ *
+ * ## Why a declared tier exists at all
+ *
+ * `tests/e2e/mq-invocation` needs a live consumer on the service workflow queue.
+ * CI runs mariadb/redis/rabbitmq sidecars and no service runtime, so in
+ * `test:all` that suite would be red in every pipeline forever. The honest
+ * answer is a declaration in the contract — the script, and the reason it cannot
+ * run in `test:all`:
+ *
+ *   "stackTiers": [
+ *     { "script": "test:e2e", "requires": "needs a live biz-hello consumer on biz-hello.workflow" }
+ *   ]
+ *
+ * Declaring is a valid answer. Silence is not: a file in T that is in neither
+ * A nor B is the defect this gate exists to name (automation-gates.md §5).
+ *
+ * There is deliberately no exemption by directory name. `tests/e2e/**` is not
+ * self-evidently un-runnable — hello-service's e2e HTTP suite was deleted rather
+ * than declared, because it tested something the platform no longer does. A name
+ * cannot carry a reason; only a declaration can (automation-gates.md §3).
+ *
+ * Pure module: reads the repository, spawns jest to ask it questions, returns a
+ * structured result. It renders nothing and exits nothing — the CLI owns
+ * presentation, this owns the rules.
+ *
+ * @see .claude/rules/automation-gates.md
+ * @see .claude/rules/change-discipline.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const TEST_COVERAGE_SCOPE = 'files the service jest config matches (jest --listTests) vs. the files '
+  + 'the test:all chain runs, decomposed npm run → jest, plus the scripts declared in contract stackTiers; '
+  + 'and that same matched set vs. every platform test file present on disk (**/tests/**/*.test.js)';
+
+const TEST_COVERAGE_NOT_MEASURED = 'whether a declared stack tier is ever RUN — the declaration says '
+  + 'why it cannot run in test:all, never that something else runs it';
+
+const STACK_TIER_KEYS = ['script', 'requires'];
+
+/** The entry script of the chain. Every biz repo already declares it; the integration minimum requires it. */
+const CHAIN_ENTRY_SCRIPT = 'test:all';
+
+/**
+ * Validate and normalize the `stackTiers` block of an integration contract.
+ *
+ * Absent means "this service has no suite outside test:all" — the ordinary case,
+ * and null rather than [] so a caller can say so instead of reporting an empty
+ * declaration as a satisfied one.
+ *
+ * @param {Array|undefined|null} rawStackTiers the contract's `stackTiers` value
+ * @returns {Array<{script: string, requires: string}>|null}
+ */
+function normalizeStackTiersDeclaration(rawStackTiers) {
+  if (rawStackTiers === undefined || rawStackTiers === null) return null;
+
+  if (!Array.isArray(rawStackTiers)) {
+    throw new Error('[BizCiGate] Invalid stackTiers - Expected an array of '
+      + '{ "script": "...", "requires": "..." } entries. Fix: use an array, or omit the key entirely.');
+  }
+
+  if (rawStackTiers.length === 0) {
+    throw new Error('[BizCiGate] Empty stackTiers - The array declares no script. '
+      + 'Fix: declare the script that needs a running stack, or omit the "stackTiers" key entirely.');
+  }
+
+  const declared = new Set();
+
+  return rawStackTiers.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`[BizCiGate] Invalid stackTiers[${index}] - Expected an object with "script" and `
+        + '"requires". Fix: { "script": "test:e2e", "requires": "<why it cannot run in test:all>" }.');
+    }
+
+    for (const key of Object.keys(entry)) {
+      if (!STACK_TIER_KEYS.includes(key)) {
+        throw new Error(`[BizCiGate] Unknown stackTiers[${index}] key - "${key}" is not part of a `
+          + 'stack-tier entry. Fix: an entry has exactly two keys, "script" and "requires".');
+      }
+    }
+
+    if (typeof entry.script !== 'string' || entry.script.trim() === '') {
+      throw new Error(`[BizCiGate] Invalid stackTiers[${index}].script - Expected the name of an npm `
+        + 'script. Fix: "script": "test:e2e".');
+    }
+
+    // The reason is the whole point of the declaration. A tier nobody can justify
+    // is exactly the one nobody dares delete (change-discipline.md § Removing
+    // something removes its declaration), and a reader of a red pipeline must be
+    // able to see why this suite is not in it.
+    if (typeof entry.requires !== 'string' || entry.requires.trim() === '') {
+      throw new Error(`[BizCiGate] Invalid stackTiers[${index}].requires - Expected a non-empty sentence `
+        + 'saying why the script cannot run in test:all. Fix: "requires": "needs a live biz-hello '
+        + 'consumer on biz-hello.workflow; CI has no service runtime".');
+    }
+
+    if (declared.has(entry.script)) {
+      throw new Error(`[BizCiGate] Duplicate stackTiers entry - "${entry.script}" is declared twice. `
+        + 'Fix: keep one entry per script.');
+    }
+    declared.add(entry.script);
+
+    return { script: entry.script, requires: entry.requires };
+  });
+}
+
+/**
+ * What a test file looks like on disk, platform-wide.
+ *
+ * Kept as the literal pattern the platform template declares, and split into the
+ * two halves the walk needs, so the constant and the check cannot drift apart.
+ * ❌ Do NOT derive this from the service's jest config: that config is the side
+ * under test, and a gate that takes its yardstick from the thing it measures
+ * agrees with everything.
+ *
+ * @see templates/business-service/jest.config.js — the declaration this mirrors
+ */
+const PLATFORM_TEST_FILE_PATTERN = '**/tests/**/*.test.js';
+const PLATFORM_TEST_DIRECTORY = 'tests';
+const PLATFORM_TEST_FILE_SUFFIX = '.test.js';
+
+/**
+ * Directories a repository walk never descends into.
+ *
+ * `node_modules` holds other people's suites — reporting them would blame the
+ * service for a dependency's files. `.git` holds no source at all.
+ */
+const UNWALKED_DIRECTORIES = new Set(['node_modules', '.git']);
+
+/**
+ * Every file under the repository that matches PLATFORM_TEST_FILE_PATTERN.
+ *
+ * Returned sorted, so a repository with several hidden suites reports them in
+ * the same order on every run — a gate whose output moves between runs is not
+ * predictable (automation-gates.md §1.1).
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string[]} absolute paths
+ */
+function listPlatformTestFilesOnDisk(serviceRoot) {
+  const found = [];
+
+  const walk = (directory, insideTestsDirectory) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+      throw new Error(`[BizCiGate] Could not read ${directory} - ${error.message}. `
+        + 'Fix: the test-coverage gate walks the repository for test files; make the directory readable.');
+    }
+
+    for (const entry of entries) {
+      const absolutePath = path.join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        if (UNWALKED_DIRECTORIES.has(entry.name)) continue;
+        walk(absolutePath, insideTestsDirectory || entry.name === PLATFORM_TEST_DIRECTORY);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+      if (!insideTestsDirectory) continue;
+      if (!entry.name.endsWith(PLATFORM_TEST_FILE_SUFFIX)) continue;
+
+      found.push(absolutePath);
+    }
+  };
+
+  walk(serviceRoot, false);
+
+  return found.sort();
+}
+
+/**
+ * The service's own jest binary, resolved without following a symlink.
+ *
+ * `node_modules/.bin/jest` is a symlink, and `require.resolve('jest/bin/jest.js')`
+ * fails on jest 29: the package's `exports` map publishes `./bin/jest`, not the
+ * `.js` path. So the package manifest is resolved (it is always exported) and its
+ * own declared `bin` is joined to it — whatever jest calls its entry point.
+ */
+function resolveJestBin(serviceRoot) {
+  let manifestPath;
+  try {
+    manifestPath = require.resolve('jest/package.json', { paths: [serviceRoot] });
+  } catch (error) {
+    throw new Error(`[BizCiGate] jest is not installed for ${serviceRoot} - the test-coverage gate asks `
+      + 'jest which files it would run, so it cannot run before the dependencies are there. '
+      + 'Fix: run "npm ci" in the service repository before the gate.');
+  }
+
+  const declaredBin = JSON.parse(fs.readFileSync(manifestPath, 'utf8')).bin;
+  const relativeBin = typeof declaredBin === 'string' ? declaredBin : declaredBin && declaredBin.jest;
+  if (!relativeBin) {
+    throw new Error(`[BizCiGate] Unusable jest installation - ${manifestPath} declares no "bin". `
+      + 'Fix: reinstall jest in the service repository.');
+  }
+
+  return path.join(path.dirname(manifestPath), relativeBin);
+}
+
+/** Split a script body into `&&`-separated steps; anything else is left in the step, and rejected there. */
+function splitChainSteps(command) {
+  return command
+    .split('&&')
+    .map((step) => step.trim())
+    .filter((step) => step !== '');
+}
+
+/** Minimal shell tokenizer: whitespace, single and double quotes. Enough for an npm script body. */
+function tokenize(step) {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let started = false;
+
+  for (const character of step) {
+    if (quote) {
+      if (character === quote) quote = null;
+      else current += character;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (started || current !== '') tokens.push(current);
+      current = '';
+      started = false;
+      continue;
+    }
+    current += character;
+  }
+  if (started || current !== '') tokens.push(current);
+
+  return tokens;
+}
+
+function isJestExecutable(token) {
+  return token === 'jest' || /(^|[/\\])jest(\.js)?$/.test(token);
+}
+
+/**
+ * Classify one step of a chain.
+ * @returns {{kind: 'script', script: string}|{kind: 'jest', args: string[]}|{kind: 'unreadable'}}
+ */
+function classifyStep(step) {
+  // A step the gate would have to GUESS about is never guessed. `;`, `|` and `||`
+  // change what actually runs, and a chain read as if they were not there would
+  // report a count nobody can rely on.
+  if (/[;|]/.test(step)) return { kind: 'unreadable' };
+
+  const tokens = tokenize(step);
+  if (tokens.length === 0) return { kind: 'unreadable' };
+
+  const [head, ...rest] = tokens;
+
+  if (head === 'npm') {
+    if ((rest[0] === 'run' || rest[0] === 'run-script') && rest[1]) {
+      return { kind: 'script', script: rest[1] };
+    }
+    if (rest[0] === 'test' || rest[0] === 't') {
+      return { kind: 'script', script: 'test' };
+    }
+    return { kind: 'unreadable' };
+  }
+
+  if (head === 'npx' && rest[0] && isJestExecutable(rest[0])) {
+    return { kind: 'jest', args: rest.slice(1) };
+  }
+
+  if (isJestExecutable(head)) {
+    return { kind: 'jest', args: rest };
+  }
+
+  return { kind: 'unreadable' };
+}
+
+/**
+ * Decompose an npm script into the jest invocations it eventually runs.
+ *
+ * @returns {{commands: Array<{args: string[], viaScript: string}>, problems: Array<{message: string}>}}
+ */
+function decomposeScriptChain(scripts, entryScript, visited = new Set(), problems = [], commands = []) {
+  if (visited.has(entryScript)) {
+    problems.push({
+      message: `Cyclic npm script chain - "${entryScript}" runs itself, directly or through another `
+        + 'script, so the gate cannot list what it runs. Fix: break the cycle.',
+    });
+    return { commands, problems };
+  }
+  visited.add(entryScript);
+
+  const body = scripts[entryScript];
+  if (typeof body !== 'string' || body.trim() === '') {
+    problems.push({
+      message: `Missing script in the ${CHAIN_ENTRY_SCRIPT} chain - "${entryScript}" is run by the chain `
+        + 'but package.json defines no such script. Fix: add the script, or stop calling it.',
+    });
+    return { commands, problems };
+  }
+
+  for (const step of splitChainSteps(body)) {
+    const classified = classifyStep(step);
+
+    if (classified.kind === 'script') {
+      decomposeScriptChain(scripts, classified.script, visited, problems, commands);
+      continue;
+    }
+
+    if (classified.kind === 'jest') {
+      commands.push({ args: classified.args, viaScript: entryScript });
+      continue;
+    }
+
+    problems.push({
+      message: `Unreadable step in the ${CHAIN_ENTRY_SCRIPT} chain - "${step}" (via ${entryScript}) is `
+        + 'neither "npm run <script>" nor a jest invocation, so the gate cannot ask which tests it runs. '
+        + 'Fix: express the step as "npm run <script>" or as a jest command.',
+    });
+  }
+
+  return { commands, problems };
+}
+
+/**
+ * Ask jest which files a command would run.
+ *
+ * An empty match is jest's own exit 0 with no output (measured, jest 29.7.0), so
+ * a non-zero exit is a real failure and is raised rather than counted as "no
+ * tests" — the difference between "this script runs nothing" and "this gate
+ * could not run" must never be silently the same number.
+ */
+function listTests({ serviceRoot, jestBin, args, spawn }) {
+  const result = spawn(process.execPath, [jestBin, ...args, '--listTests'], {
+    cwd: serviceRoot,
+    encoding: 'utf8',
+    env: process.env,
+  });
+
+  if (result.error) {
+    throw new Error(`[BizCiGate] Could not run jest --listTests - ${result.error.message}. `
+      + `Fix: verify the jest installation in ${serviceRoot}.`);
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`[BizCiGate] jest --listTests failed (exit ${result.status}) for `
+      + `"jest ${args.join(' ')}" in ${serviceRoot}. jest said: ${(result.stderr || '').trim()}`);
+  }
+
+  return (result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '');
+}
+
+/**
+ * Verify the test-coverage contract for one service repository.
+ *
+ * Every violation is reported, not just the first, so a repo can be fixed in one
+ * pass.
+ *
+ * @param {object} options
+ * @param {string} options.serviceRoot repository root
+ * @param {object} options.contract normalized integration contract (carries stackTiers)
+ * @param {Function} [options.spawn] injected spawnSync, for tests that must not run jest
+ */
+function verifyTestCoverage({ serviceRoot, contract, spawn = spawnSync }) {
+  const packageJsonPath = path.join(serviceRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`[BizCiGate] Missing file - ${packageJsonPath}`);
+  }
+  const scripts = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).scripts || {};
+
+  if (!scripts[CHAIN_ENTRY_SCRIPT]) {
+    throw new Error(`[BizCiGate] Missing package script - ${CHAIN_ENTRY_SCRIPT} is required by the `
+      + 'test-coverage gate: it is the chain every test file must be reachable from. '
+      + `Fix: define "${CHAIN_ENTRY_SCRIPT}" in package.json.`);
+  }
+
+  const jestBin = resolveJestBin(serviceRoot);
+  const memo = new Map();
+  const ask = (args) => {
+    const key = JSON.stringify(args);
+    if (!memo.has(key)) memo.set(key, listTests({ serviceRoot, jestBin, args, spawn }));
+    return memo.get(key);
+  };
+
+  const relative = (absolutePath) => path.relative(serviceRoot, absolutePath);
+  const violations = [];
+  const add = (requirement, message) => violations.push({ requirement, message });
+
+  // T — everything the service's jest config matches, asked without a path filter.
+  const matched = new Set(ask([]));
+
+  // D \ T — a suite that is on disk and in no jest answer. Checked FIRST because
+  // it is the only defect the other three cannot express: a file jest does not
+  // match is missing from both sides of every comparison below, so silence there
+  // says nothing about it (automation-gates.md §5).
+  for (const file of listPlatformTestFilesOnDisk(serviceRoot)) {
+    if (matched.has(file)) continue;
+    add('TEST_NOT_MATCHED', `Test file matched by nothing - ${relative(file)} is a platform test file `
+      + `on disk (${PLATFORM_TEST_FILE_PATTERN}, the testMatch templates/business-service/jest.config.js `
+      + 'declares), but the service jest config does not match it, so no script can run it and no other '
+      + `check can even name it. Fix: widen testMatch in jest.config.js to the platform pattern, or move `
+      + 'the file out of tests/ (or delete it) if it is not a test.');
+  }
+
+  // A — everything the test:all chain runs.
+  const chain = decomposeScriptChain(scripts, CHAIN_ENTRY_SCRIPT);
+  for (const problem of chain.problems) add('TEST_ALL_CHAIN', problem.message);
+  const inTestAll = new Set();
+  for (const command of chain.commands) {
+    for (const file of ask(command.args)) inTestAll.add(file);
+  }
+
+  // B — everything the declared stack tiers run.
+  const declaredTiers = contract.stackTiers || [];
+  const inStackTiers = new Set();
+  const stackTiers = [];
+
+  for (const tier of declaredTiers) {
+    if (!scripts[tier.script]) {
+      add('STACK_TIER_SCRIPT', `Declared stack tier has no script - stackTiers declares `
+        + `"${tier.script}", but package.json defines no such script. `
+        + 'Fix: add the script, or remove the declaration.');
+      continue;
+    }
+
+    const tierChain = decomposeScriptChain(scripts, tier.script);
+    for (const problem of tierChain.problems) add('TEST_ALL_CHAIN', problem.message);
+
+    const tierFiles = [];
+    for (const command of tierChain.commands) {
+      for (const file of ask(command.args)) {
+        if (!tierFiles.includes(file)) tierFiles.push(file);
+      }
+    }
+
+    if (tierFiles.length === 0) {
+      add('STACK_TIER_EMPTY', `Declared stack tier runs no test - "${tier.script}" lists 0 test files, `
+        + 'so the declaration has no consumer. '
+        + 'Fix: point the script at the tests it is meant to run, or remove the declaration.');
+      continue;
+    }
+
+    const alsoInTestAll = tierFiles.filter((file) => inTestAll.has(file));
+    if (alsoInTestAll.length > 0) {
+      add('STACK_TIER_IN_TEST_ALL', `Declared stack tier already runs in test:all - "${tier.script}" `
+        + `lists ${alsoInTestAll.map(relative).join(', ')}, which the test:all chain runs too. `
+        + 'Fix: remove the declaration — a stack tier is the part test:all CANNOT run, '
+        + 'and declaring one that it can run states something untrue.');
+      continue;
+    }
+
+    for (const file of tierFiles) inStackTiers.add(file);
+    stackTiers.push({ script: tier.script, requires: tier.requires, files: tierFiles.map(relative) });
+  }
+
+  // (1) — the defect the gate exists for.
+  for (const file of matched) {
+    if (inTestAll.has(file) || inStackTiers.has(file)) continue;
+    add('TEST_RUNS_NOWHERE', `Test file runs nowhere - ${relative(file)} is matched by the jest config, `
+      + 'the test:all chain does not run it, and no stackTiers entry declares it. '
+      + 'Fix: run it from a script the test:all chain reaches, or — if it needs a running stack — '
+      + 'declare its script in config/service/integration-contract.json: '
+      + '"stackTiers": [{ "script": "test:e2e", "requires": "<why it cannot run in test:all>" }].');
+  }
+
+  return {
+    ok: violations.length === 0,
+    violations,
+    totals: {
+      matched: matched.size,
+      inTestAll: inTestAll.size,
+      inStackTiers: inStackTiers.size,
+    },
+    stackTiers,
+  };
+}
+
+module.exports = {
+  TEST_COVERAGE_SCOPE,
+  TEST_COVERAGE_NOT_MEASURED,
+  PLATFORM_TEST_FILE_PATTERN,
+  listPlatformTestFilesOnDisk,
+  normalizeStackTiersDeclaration,
+  decomposeScriptChain,
+  resolveJestBin,
+  verifyTestCoverage,
+};