@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/checks/contractBridge.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * The bridge from a manifest row to a checker this package ALREADY runs.
+ *
+ * Confirmation `biz-service-manifest` 004 point 4: a rule that exists is cited,
+ * never restated. So none of the checks below decides anything — each one calls
+ * the module that owns the rule, keeps the violations of the requirement its row
+ * names, and maps them into the two columns a finding adds (`where`, `what`).
+ * The row's `severity`, `owner`, `fix` and `doc` are the row's own, and
+ * `runManifest` puts them on the table.
+ *
+ * Three checkers, one shape (lead decision `api/shared/TODO.md` §0.2b-8 point 3):
+ *
+ *   `deploy-contract`   → utils/deployContract.js  (R1, R4, … per row)
+ *   `install-contract`  → utils/installContract.js (the ids it exports)
+ *   `env-contract`      → utils/envContract.js     (completeness; it has no requirement ids)
+ *
+ * Why a row must name its requirement rather than take the whole result: a
+ * checker raises several unrelated rules at once, and a table row is one rule
+ * with one owner and one fix. R2 (the deploy sequence) and R8 (tenant identity)
+ * are not rows of this uniform, and a row that swallowed them would report a
+ * finding no `fix` sentence of its own answers.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-004
+ */
+
+const path = require('path');
+
+const { verifyDeployContract, DEPLOY_CONTRACT_REQUIREMENTS } = require('../../utils/deployContract');
+const { verifyInstallContract, INSTALL_CONTRACT_REQUIREMENTS } = require('../../utils/installContract');
+const { verifyEnvCompleteness } = require('../../utils/envContract');
+const { loadAndValidateIntegrationContract } = require('../../utils/bizCiGateContract');
+
+/** Where every service declares what it integrates with; three of these rows read it. */
+const CONTRACT_PATH = 'config/service/integration-contract.json';
+
+/**
+ * One violation as one table cell: the first line, without the `Fix:` sentence
+ * the row carries in its own column.
+ *
+ * @param {string} requirement the requirement id, kept so the table names it
+ * @param {string} message the checker's message, as it writes it
+ * @returns {string}
+ */
+function summarise(requirement, message) {
+  const firstLine = String(message).split('\n')[0];
+  const withoutFix = firstLine.split(' Fix:')[0];
+  return `${requirement}: ${withoutFix.trim()}`;
+}
+
+/**
+ * Refuse a row whose requirement the checker does not raise. Silence would be
+ * indistinguishable from a clean repository, which is the failure mode this
+ * whole subject exists to end.
+ *
+ * @param {object} row the manifest row
+ * @param {ReadonlyArray<string>} known the ids the checker raises
+ * @param {string} module the module that owns them, for the message
+ */
+function assertKnownRequirement(row, known, module) {
+  if (known.includes(row.requirement)) return;
+  throw new Error(`[ManifestBridge] Row ${row.id} names requirement "${row.requirement}", which `
+    + `${module} does not raise - Expected one of ${known.join(', ')}. `
+    + 'Fix: correct the row, or add the requirement to that module first; a row that cites a '
+    + 'requirement nobody raises reports nothing and reads as a pass.');
+}
+
+/**
+ * The service's normalized integration contract, or the reason it is unusable.
+ *
+ * A row that needs the contract and cannot read it says THAT — it never returns
+ * an empty list, which a reader would take for a clean repository. Row
+ * `C-CONTRACT` names the missing file with its own fix; this second sentence is
+ * about the requirement that could not be decided because of it.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {{ contract: object }|{ problem: string }}
+ */
+function contractOf(serviceRoot) {
+  try {
+    return { contract: loadAndValidateIntegrationContract(serviceRoot).contract };
+  } catch (error) {
+    return { problem: String(error.message).split('\n')[0].trim() };
+  }
+}
+
+/**
+ * @param {object} row the manifest row
+ * @param {string} problem why the contract could not be read
+ * @returns {Array<{where: string, what: string}>}
+ */
+const contractUnreadable = (row, problem) => [{
+  where: CONTRACT_PATH,
+  what: `${row.requirement} could not be decided — the integration contract is unreadable: ${problem}`
+}];
+
+const deployContract = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['requirement', 'path']),
+
+  /**
+   * @param {{ row: object, serviceRoot: string }} params
+   * @returns {Array<{where: string, what: string}>}
+   */
+  run({ row, serviceRoot }) {
+    assertKnownRequirement(row, DEPLOY_CONTRACT_REQUIREMENTS, 'utils/deployContract.js');
+
+    return verifyDeployContract(serviceRoot).violations
+      .filter((violation) => violation.requirement === row.requirement)
+      .map((violation) => ({
+        where: row.path,
+        what: summarise(violation.requirement, violation.message)
+      }));
+  }
+});
+
+const installContract = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['requirement', 'path']),
+
+  /**
+   * @param {{ row: object, serviceRoot: string }} params
+   * @returns {Array<{where: string, what: string}>}
+   */
+  run({ row, serviceRoot }) {
+    assertKnownRequirement(row, INSTALL_CONTRACT_REQUIREMENTS, 'utils/installContract.js');
+
+    const loaded = contractOf(serviceRoot);
+    if (loaded.problem !== undefined) return contractUnreadable(row, loaded.problem);
+
+    // Whether the SQL half applies at all is the contract's own decision, which
+    // is why the database block is handed over rather than derived here
+    // (installContract.js header: one fact, one owner).
+    return verifyInstallContract(serviceRoot, loaded.contract.database).violations
+      .filter((violation) => violation.requirement === row.requirement)
+      .map((violation) => ({
+        where: row.path,
+        what: summarise(violation.requirement, violation.message)
+      }));
+  }
+});
+
+const envContract = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  /**
+   * Completeness (F16): every environment name the repository visibly reads is
+   * declared in the contract's `env` block or covered by the platform env. The
+   * rule, the scan and its blind spots are `utils/envContract.js`; this row
+   * places its violations on the table.
+   *
+   * @param {{ row: object, serviceRoot: string }} params
+   * @returns {Array<{where: string, what: string}>}
+   */
+  run({ row, serviceRoot }) {
+    const loaded = contractOf(serviceRoot);
+    if (loaded.problem !== undefined) {
+      return [{
+        where: CONTRACT_PATH,
+        what: `the environment contract could not be decided — the integration contract is unreadable: ${loaded.problem}`
+      }];
+    }
+
+    return verifyEnvCompleteness({ serviceRoot: path.resolve(serviceRoot), contract: loaded.contract }).violations
+      .map((violation) => ({
+        where: violation.sources[0],
+        what: `${violation.name} is read here, and the contract neither declares it `
+          + 'nor is it covered by the platform env'
+      }));
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'deploy-contract', check: deployContract },
+    { name: 'install-contract', check: installContract },
+    { name: 'env-contract', check: envContract }
+  ]
+};

package/src/manifest/checks/discoveryOrphan.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * `discovery-orphan` — everything the discovery pattern's container holds is a
+ * bearer of some uniform, and its SSOT knows it.
+ *
+ * Completeness is discovery (confirmation biz-service-manifest 005 point 1): no
+ * declaration is read, because a bearer's uniform is its location. What the
+ * check compares is the disk against the file that owns the names — resolved at
+ * run time, never copied into the manifest (004 point 2).
+ *
+ * The check is workspace-scoped: inside a service container the SSOT is not
+ * present, and the row is then reported NOT RUN rather than passed. The same is
+ * true one level down, in a checkout that carries `api/` and not `api_biz/`: an
+ * absent container holds no directory, and "every directory is declared" would
+ * be true of nothing (`automation-gates.md` §5), so the row declares the
+ * container it walks and the runner stops it before it looks.
+ */
+
+const { discoverBearers, rootOfPattern } = require('../discovery');
+
+const check = Object.freeze({
+  scope: 'workspace',
+  requires: Object.freeze([]),
+
+  /** The directory the pattern walks; absent, the answer would be an empty disk. */
+  requiresSiblings({ block }) {
+    return [rootOfPattern(block.pattern)];
+  },
+
+  /** What the run prints instead of a verdict when the workspace is unreachable. */
+  describeNotRun({ block }) {
+    const owner = block && block.from ? block.from.path : 'the referenced SSOT';
+    return `the workspace root is not reachable, so ${owner} cannot be read`;
+  },
+
+  /**
+   * @param {{ block: object, workspaceRoot: string }} params
+   * @returns {Array<{where: string, what: string}>}
+   */
+  run({ block, workspaceRoot }) {
+    const { orphans } = discoverBearers({ block, workspaceRoot });
+    return orphans.map((orphan) => ({
+      where: orphan.relativeDir,
+      what: `wears no uniform — ${orphan.reason}`
+    }));
+  }
+});
+
+module.exports = { name: 'discovery-orphan', check };