@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/checks/serviceConfig.js

@@ -0,0 +1,390 @@
+'use strict';
+
+/**
+ * The files a service is configured by.
+ *
+ * Two of these rows overlap deliberately with the boot validation: step 2 of
+ * `ValidationOrchestrator` already refuses a `config.json` without
+ * `service.name` and an `operations.json` with no operations, and it does that
+ * INSIDE a boot. The rows exist because `npx oa-validate` is asked the same
+ * question outside one — in CI, in the image build, in a repository nobody has
+ * started — and because the manifest is where a rule of service shape is
+ * declared (003 §20: an `Enforced by` cell names a row id). The honest end state
+ * is one implementation: step 2 extracting its rule into a pure module that both
+ * call. That refactor touches `ValidationOrchestrator.js`, which d.210a does not
+ * own, so it is recorded for the lead rather than done here.
+ *
+ * `G-SHARED-ENV` is a different kind: `shared.env` is GENERATED from the
+ * platform manifest `api/config/shared-env.json` (003 §18), so the row does not
+ * describe the file at all — it calls the renderer that owns it
+ * (`src/sync/sharedEnv.js`, d.217a) and reports the difference.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
+const { whereOf } = require('./libraryContext');
+const { diffAgainst } = require('../../sync/sharedEnv');
+const { loadAndValidateIntegrationContract } = require('../../utils/bizCiGateContract');
+
+/** The generated platform file every service carries a copy of. */
+const SHARED_ENV = 'shared.env';
+
+/**
+ * @param {string} serviceRoot repository root
+ * @param {string} relative repository-relative path
+ * @returns {string|null}
+ */
+function readFileOrNull(serviceRoot, relative) {
+  const target = path.join(serviceRoot, ...relative.split('/'));
+  if (!fs.existsSync(target)) return null;
+  return fs.readFileSync(target, 'utf8');
+}
+
+/**
+ * Read a JSON file of the repository. A malformed one is a finding, not a
+ * throw: the run reports every row before it stops.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} relative repository-relative path
+ * @returns {{ json: object }|{ absent: true }|{ broken: string }}
+ */
+function readJson(serviceRoot, relative) {
+  const text = readFileOrNull(serviceRoot, relative);
+  if (text === null) return { absent: true };
+  try {
+    return { json: JSON.parse(text) };
+  } catch (error) {
+    return { broken: error.message };
+  }
+}
+
+/**
+ * The keys of `config/service/config.json` a reader demands, and the reader that
+ * demands each.
+ *
+ * The list is MEASURED, not designed: a key is here because grep finds the code
+ * that reads it and fails without it, and the keys the same measurement found
+ * unread are refused by `configDeadKeys` below rather than tolerated. What each
+ * reader does with the value is its own business — this row only settles that
+ * the value is there and has the type the reader assumes.
+ *
+ *   service.name                  ConfigLoader.js (throws), ServiceWrapper.js
+ *                                 (the registration identity)
+ *   service.workspaceScoped       ServiceWrapper._validateNamingAndWorkspaceScoped —
+ *                                 an explicit boolean, no default, and it decides
+ *                                 whether `list-workspaces` must exist
+ *   service.specificationEndpoint ServiceWrapper.js, published in the service
+ *                                 specification
+ */
+const REQUIRED_SERVICE_KEYS = Object.freeze([
+  Object.freeze({
+    key: 'name',
+    reader: 'the wrapper registers under that name',
+    ok: (value) => typeof value === 'string' && value.length > 0
+  }),
+  Object.freeze({
+    key: 'workspaceScoped',
+    reader: 'the wrapper refuses to boot without an explicit boolean',
+    ok: (value) => typeof value === 'boolean'
+  }),
+  Object.freeze({
+    key: 'specificationEndpoint',
+    reader: 'the wrapper publishes it in the service specification',
+    ok: (value) => typeof value === 'string' && value.length > 0
+  })
+]);
+
+const configService = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, serviceRoot }) {
+    const read = readJson(serviceRoot, row.path);
+    if (read.absent) return [{ where: row.path, what: 'absent — this uniform requires it' }];
+    if (read.broken) return [{ where: row.path, what: `is not valid JSON — ${read.broken}` }];
+
+    const service = read.json.service && typeof read.json.service === 'object' ? read.json.service : {};
+
+    // Absent and wrong-typed are separate sentences on purpose: "declares no X"
+    // sends the reader to the template, "declares X as <value>" sends them to
+    // the line they already wrote (`architecture-principles.md` §5).
+    return REQUIRED_SERVICE_KEYS
+      .filter((expected) => !expected.ok(service[expected.key]))
+      .map((expected) => ({
+        where: row.path,
+        what: service[expected.key] === undefined
+          ? `declares no service.${expected.key} — ${expected.reader}`
+          : `declares service.${expected.key} as ${JSON.stringify(service[expected.key])} — ${expected.reader}`
+      }));
+  }
+});
+
+/** Where every service declares what it integrates with. */
+const CONTRACT_PATH = 'config/service/integration-contract.json';
+
+/**
+ * The keys MEASURED to have no reader at all (d.217b, 2026-09-09).
+ *
+ * A declaration nothing reads is not harmless: it tells the next reader that
+ * something depends on it, and every new service copies it forward
+ * (`change-discipline.md` § Removing something removes its declaration). Each
+ * entry carries the evidence of its own deadness, because a ban whose reason is
+ * not written down is one nobody can re-check.
+ */
+const DEAD_KEYS = Object.freeze([
+  Object.freeze({
+    file: 'config/service/config.json',
+    path: Object.freeze(['service', 'version']),
+    label: 'service.version',
+    why: 'ConfigLoader assigns it from package.json on every load, so this value is never read'
+  }),
+  Object.freeze({
+    file: 'config/service/config.json',
+    path: Object.freeze(['service', 'port']),
+    label: 'service.port',
+    why: 'nothing reads it; a biz service binds no port'
+  }),
+  Object.freeze({
+    // Dated on purpose. The guard left the SOURCE in c7ee2256, but the artefact
+    // every service is pinned to today is the PUBLISHED 7.0.0, which still
+    // throws `Missing configuration - service.url is required` (measured
+    // 2026-09-14 in api_biz/invoicing/node_modules/@onlineapps/service-wrapper).
+    // A sentence saying "nothing reads it" would tell an author to delete a key
+    // their own boot demands (BIZ-invoicing 2026-09-11 point 1); the key travels
+    // WITH the pin, which is what confirmation biz-service-port-url 001 already
+    // said ("v rámci pin kaskády"). The row stays `deploy`: it names the work
+    // the cascade carries, it does not stop a boot.
+    file: 'config/service/config.json',
+    path: Object.freeze(['service', 'url']),
+    label: 'service.url',
+    why: 'dead from wrapper 8.0.0; the published 7.0.0 still refuses to boot without it '
+      + '("Missing configuration - service.url is required"), so the key goes WITH the pin, '
+      + 'never before it (confirmation biz-service-port-url 001)'
+  }),
+  Object.freeze({
+    file: 'config/service/config.json',
+    path: Object.freeze(['wrapper', 'registry', 'url']),
+    label: 'wrapper.registry.url',
+    why: 'nothing reads it; registration travels over MQ to registry.register '
+      + 'and discovery reads the Redis projection (confirmation biz-discovery-redis 002)'
+  }),
+  Object.freeze({
+    file: 'config/service/config.json',
+    path: Object.freeze(['wrapper', 'tenantContext']),
+    label: 'wrapper.tenantContext',
+    // `service-shape-v11-retirement` 001 retired the validator LEVEL that demanded
+    // the key EXIST; it never sanctioned deleting it. What killed the key is
+    // `wrapper-tenant-middleware` 001 — its only consumer and the runtime default
+    // both went in b5e36431 (controller finding 21, BIZ-converter 2026-09-14).
+    why: 'nothing reads it; its only consumer, createTenantContextMiddleware, was deleted '
+      + 'together with the runtime default in b5e36431 '
+      + '(confirmation wrapper-tenant-middleware 001)'
+  }),
+  Object.freeze({
+    file: CONTRACT_PATH,
+    path: Object.freeze(['contractVersion']),
+    label: 'contractVersion',
+    why: 'nothing reads it'
+  })
+]);
+
+/**
+ * @param {object} json parsed document
+ * @param {ReadonlyArray<string>} keyPath the key to look up
+ * @returns {boolean} whether the document declares it at all
+ */
+function declares(json, keyPath) {
+  let node = json;
+  for (const segment of keyPath) {
+    if (node === null || typeof node !== 'object' || !(segment in node)) return false;
+    node = node[segment];
+  }
+  return true;
+}
+
+const configDeadKeys = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  /**
+   * A document this row cannot parse raises nothing: `C-SERVICE` and
+   * `C-CONTRACT` already name a broken file with their own fix, and a second
+   * sentence about it would send the reader to two places for one defect.
+   */
+  run({ serviceRoot }) {
+    const parsed = new Map();
+    const findings = [];
+
+    for (const dead of DEAD_KEYS) {
+      if (!parsed.has(dead.file)) parsed.set(dead.file, readJson(serviceRoot, dead.file));
+      const read = parsed.get(dead.file);
+      if (read.absent || read.broken) continue;
+      if (!declares(read.json, dead.path)) continue;
+
+      findings.push({ where: dead.file, what: `declares ${dead.label} — ${dead.why}` });
+    }
+
+    return findings;
+  }
+});
+
+/**
+ * The integration contract, decided by the module that already owns its rules.
+ *
+ * `utils/bizCiGateContract.js` validates this document for the CI gate —
+ * connector booleans, the integration minimum, the database block and its
+ * agreement with `requiredConnectors.db`, the env block with a `why` per name.
+ * That validator IS the schema, so this row calls it instead of restating it in
+ * a second notation (lead decision, d.217b; `change-discipline.md` § One rail
+ * per concern). Confirmation `biz-service-manifest` 003 §18 asks for a shipped
+ * schema; the divergence between its wording and one rail is on the lead's
+ * table, not settled here.
+ */
+const configContract = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, serviceRoot }) {
+    const target = path.join(serviceRoot, ...row.path.split('/'));
+    if (!fs.existsSync(target)) {
+      return [{
+        where: row.path,
+        what: 'absent — every platform gate reads it: the connectors, the database, '
+          + 'the env declaration and the integration minimum'
+      }];
+    }
+
+    try {
+      loadAndValidateIntegrationContract(serviceRoot);
+      return [];
+    } catch (error) {
+      // The validator's own first line, without its `Fix:` sentence: the row
+      // carries a fix of its own, and two of them in one cell read as two
+      // defects (contractBridge.js summarise()).
+      const firstLine = String(error.message).split('\n')[0];
+      return [{ where: row.path, what: firstLine.split(' Fix:')[0].trim() }];
+    }
+  }
+});
+
+const configOperations = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, serviceRoot }) {
+    const read = readJson(serviceRoot, row.path);
+    if (read.absent) return [{ where: row.path, what: 'absent — this uniform requires it' }];
+    if (read.broken) return [{ where: row.path, what: `is not valid JSON — ${read.broken}` }];
+
+    const operations = read.json.operations;
+    const declared = operations && typeof operations === 'object' ? Object.keys(operations) : [];
+    if (declared.length > 0) return [];
+    return [{
+      where: row.path,
+      what: 'declares no operations — a service that dispatches nothing has no reason to boot'
+    }];
+  }
+});
+
+const envTemplates = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  /**
+   * One shared template and exactly one of the service's own.
+   *
+   * What the file is CALLED is not this row's business: the scaffold renames it
+   * to `<directory>.env` and `api/tests/scripts/add-service.bats` is the test of
+   * that rename (lead decision `api/shared/TODO.md` §0.2b-9 point 3). What the
+   * uniform fixes is that the service's own keys have exactly one home.
+   */
+  run({ row, serviceRoot }) {
+    const dir = path.join(serviceRoot, ...row.path.split('/'));
+    if (!fs.existsSync(dir)) {
+      return [{ where: `${row.path}/`, what: 'absent — the service is started from the templates in it' }];
+    }
+
+    const files = fs.readdirSync(dir).filter((name) => name.endsWith('.env')).sort();
+    const findings = [];
+
+    if (!files.includes(SHARED_ENV)) {
+      findings.push({ where: `${row.path}/`, what: `declares no ${SHARED_ENV} — the platform keys have nowhere to live` });
+    }
+
+    const own = files.filter((name) => name !== SHARED_ENV);
+    if (own.length === 0) {
+      findings.push({
+        where: `${row.path}/`,
+        what: `declares no service env template beside ${SHARED_ENV} — the service's own keys have nowhere to live`
+      });
+    } else if (own.length > 1) {
+      findings.push({
+        where: `${row.path}/`,
+        what: `declares ${own.length} service env templates (${own.join(', ')}) — the service's own keys have one home`
+      });
+    }
+
+    return findings;
+  }
+});
+
+/**
+ * `shared.env` is rendered from `api/config/shared-env.json`, and this row reads
+ * the RENDER the package carries (d.229): the platform manifest stays the owner
+ * of the key set, `templates/business-service/config/env-templates/shared.env`
+ * is its output, and `sharedEnvTemplate.test.js` is what keeps the two equal.
+ * Reading the render rather than the manifest is what lets the row run inside a
+ * service container, where `api/config/` is not there at all — and that is the
+ * only place a service's own `shared.env` is ever wrong for a reader who cannot
+ * fix it from the workspace.
+ */
+const sharedEnvGenerated = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'from']),
+
+  needsWorkspace: ({ row }) => !isPackageReference(row.from),
+
+  describeNotRun({ row }) {
+    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+  },
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const text = readFileOrNull(serviceRoot, row.path);
+    const owner = referenceOwner(row.from);
+    if (text === null) {
+      return [{ where, what: `absent — it is rendered from ${owner}` }];
+    }
+
+    const rendered = readReferencedFile({ from: row.from, workspaceRoot });
+    if (rendered === text) return [];
+
+    const differing = diffAgainst(rendered, text).split('\n').filter((line) => /^[-+]/.test(line)).length - 2;
+    return [{
+      where,
+      what: `differs from ${owner} — this file is generated, not written; `
+        + `${differing} line(s) differ`
+    }];
+  }
+});
+
+module.exports = {
+  // Exported for one reader: the test holding the row's `why` to the keys this
+  // list actually carries. The row enumerates them for a human, so the two drift
+  // the moment a key is added — measured 2026-09-11, `wrapper.registry.url`
+  // joined the list in d.244 and the row said nothing about it
+  // (`doc-code-binding.md` §1: a hand-written enumeration needs a mechanism).
+  DEAD_KEYS,
+  checks: [
+    { name: 'config-service', check: configService },
+    { name: 'config-dead-keys', check: configDeadKeys },
+    { name: 'config-contract', check: configContract },
+    { name: 'config-operations', check: configOperations },
+    { name: 'env-templates', check: envTemplates },
+    { name: 'shared-env-generated', check: sharedEnvGenerated }
+  ]
+};

package/src/manifest/checks/serviceConnectors.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * `C-CONNECTORS` — a service's two declarations about its connections must
+ * agree.
+ *
+ * The rule is not new and it does not live here: `utils/connectorContract.js`
+ * has compared `config/service/config.json` → `wrapper.<connector>` against
+ * `config/service/integration-contract.json` → `requiredConnectors` since F12.
+ * What was missing was a consequence. At boot the contradiction goes into
+ * `results.warnings` and the service starts anyway, and the check ran in no CI
+ * job at all — a mechanism nothing acts on produces the feeling of a guarantee
+ * without the guarantee (`automation-gates.md` §5).
+ *
+ * Owner confirmation `connector-contract-check` 001 (2026-09-14) chose the
+ * uniform row over failing the boot: severity `deploy`, so the contradiction is
+ * caught before push and in CI, on one rail with the rest of the uniform, while
+ * the boot keeps reporting and keeps starting. "Fail the boot" may be proposed
+ * again only once all eight services measure clean on this row.
+ *
+ * The row asks only the DECLARATION half. The environment half of the boot check
+ * — is `REDIS_URL` set for a service that requires Redis — stays at boot, where
+ * an environment exists: asked from the api checkout it would fail all eight
+ * services for a configuration none of them is running in, and a gate whose
+ * violations have no fix is the grandfathering `automation-gates.md` §3 forbids.
+ *
+ * @see api/docs/governance/confirmations/connector-contract-check.md § Confirmation 20260914-0635-connector-contract-check-001
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { verifyConnectorDeclarations, CONFIG_PATH, CONTRACT_PATH } = require('../../utils/connectorContract');
+
+/**
+ * The two declarations, or the reason they could not be read.
+ *
+ * An absent or malformed file is `C-CONTRACT`'s and `C-SERVICE`'s finding — both
+ * call the validators that own those documents. This row says nothing about a
+ * fact it could not read rather than guessing which way it went, exactly as
+ * `D-DB-CONSISTENT` does.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {{config: object, requiredConnectors: object}|null}
+ */
+function readDeclarations(serviceRoot) {
+  const read = (relative) => {
+    const file = path.join(serviceRoot, ...relative.split('/'));
+    if (!fs.existsSync(file)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+
+  const config = read(CONFIG_PATH);
+  const contract = read(CONTRACT_PATH);
+  if (config === null || contract === null) return null;
+
+  const requiredConnectors = contract.requiredConnectors;
+  if (requiredConnectors === null || typeof requiredConnectors !== 'object') return null;
+
+  return { config, requiredConnectors };
+}
+
+const connectorContract = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run({ serviceRoot }) {
+    const declarations = readDeclarations(serviceRoot);
+    if (declarations === null) return [];
+
+    return verifyConnectorDeclarations(declarations)
+      .findings
+      .map(({ where, what }) => ({ where, what }));
+  }
+});
+
+module.exports = { name: 'connector-contract', check: connectorContract };