@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/manifest/checks/serviceScripts.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * The npm scripts of a biz service: the ones the uniform requires, with their
+ * canonical body, and the ones it forbids (confirmation `biz-service-manifest`
+ * 001 §2, § scripts).
+ *
+ * Why a body and not just a name: measured on 2026-09-09, seven of the eight
+ * services declare `test:all:container` in seven different spellings — and the
+ * only thing that differs is the container name. A row that compared the text
+ * would report seven findings and mean none of them, so the canonical body is
+ * PARAMETERISED by `${runner}`, and the runner is read where it is declared: the
+ * compose service carrying `profiles: [test]` (lead decision `api/shared/TODO.md`
+ * §0.2b-9 point 2 — one owner for that name, the compose file).
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2
+ * @see api/docs/governance/confirmations/biz-test-container.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readComposeServices } = require('./composeShape');
+
+/** Where the runner's name is declared, and the profile that identifies it. */
+const DEV_COMPOSE = 'docker-compose.yml';
+const TEST_PROFILE = 'test';
+
+/** The placeholder a canonical body spends on the one name that is per-repository. */
+const RUNNER_PLACEHOLDER = '${runner}';
+
+/**
+ * The npm scripts that run without anybody naming them. `pre<x>`/`post<x>` fire
+ * around `<x>`; the rest fire on an npm command (install, publish, pack).
+ * npm owns this list — the check cites it, and the row states the consequence.
+ */
+const NPM_LIFECYCLE = Object.freeze([
+  'preinstall', 'install', 'postinstall',
+  'prepublish', 'prepublishOnly', 'prepack', 'postpack', 'prepare'
+]);
+
+/**
+ * @param {string} serviceRoot repository root
+ * @returns {{ scripts: object, present: boolean }}
+ */
+function readScripts(serviceRoot) {
+  const file = path.join(serviceRoot, 'package.json');
+  if (!fs.existsSync(file)) return { scripts: {}, present: false };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { scripts: parsed.scripts || {}, present: true };
+  } catch (cause) {
+    throw new Error(`[ManifestScripts] package.json is not valid JSON - ${file}. `
+      + 'Fix: repair it; every row about a script reads it.', { cause });
+  }
+}
+
+/**
+ * The name of the one-shot test runner this repository declares, or null.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string|null}
+ */
+function runnerName(serviceRoot) {
+  const file = path.join(serviceRoot, DEV_COMPOSE);
+  if (!fs.existsSync(file)) return null;
+  const services = readComposeServices(fs.readFileSync(file, 'utf8'));
+  for (const [name, node] of services) {
+    if ((node.sequences.get('profiles') || []).includes(TEST_PROFILE)) return name;
+  }
+  return null;
+}
+
+/**
+ * The same command written the other way: `node <script> args…` is what a
+ * repository writes before the library's `bin` is on its PATH, `<bin> args…`
+ * after. Both spell one body, so a service switching between them at a version
+ * bump is not a finding (lead brief, d.210a).
+ *
+ * @param {string} body the canonical body
+ * @param {string} bin the bin name the row names
+ * @returns {string}
+ */
+function binSpelling(body, bin) {
+  const tokens = body.trim().split(/\s+/);
+  return [bin, ...tokens.slice(2)].join(' ');
+}
+
+/**
+ * Does this repository have an integration suite to run?
+ *
+ * The question decides whether `test:integration:container` is owed at all: a
+ * script pointing at an absent suite is the dead declaration
+ * `change-discipline.md` § "Removing something removes its declaration"
+ * forbids, and jest exits 1 on a path that matches no test — so requiring it
+ * unconditionally would ship a red script to every new service.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} relative the suite directory the row names
+ * @returns {boolean}
+ */
+function hasSuite(serviceRoot, relative) {
+  const dir = path.join(serviceRoot, ...relative.split('/'));
+  return fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length > 0;
+}
+
+const scriptBody = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['name', 'body']),
+
+  run({ row, serviceRoot }) {
+    if (row.only_with !== undefined && !hasSuite(serviceRoot, row.only_with)) return [];
+
+    const { scripts, present } = readScripts(serviceRoot);
+    if (!present) return [{ where: 'package.json', what: 'absent — nothing declares this directory a service' }];
+
+    const runner = row.body.includes(RUNNER_PLACEHOLDER) ? runnerName(serviceRoot) : null;
+    const expected = runner === null ? row.body : row.body.split(RUNNER_PLACEHOLDER).join(runner);
+    const unnamed = row.body.includes(RUNNER_PLACEHOLDER) && runner === null
+      ? ', and this repository declares no runner to name'
+      : '';
+    const alsoSpelled = row.bin === undefined
+      ? ''
+      : ` (the ${row.bin} bin spelling of it counts as the same body)`;
+
+    const declared = scripts[row.name];
+    if (declared === undefined) {
+      return [{
+        where: 'package.json',
+        what: `declares no script ${JSON.stringify(row.name)} — the uniform's body is `
+          + `${JSON.stringify(expected)}${unnamed}${alsoSpelled}`
+      }];
+    }
+
+    const accepted = [expected];
+    if (row.bin !== undefined) accepted.push(binSpelling(expected, row.bin));
+    if (accepted.includes(declared.trim())) return [];
+
+    return [{
+      where: 'package.json',
+      what: `script ${JSON.stringify(row.name)} is ${JSON.stringify(declared)}, the uniform's body is `
+        + `${JSON.stringify(expected)}${unnamed}${alsoSpelled}`
+    }];
+  }
+});
+
+const scriptForbidden = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['name']),
+
+  run({ row, serviceRoot }) {
+    const { scripts } = readScripts(serviceRoot);
+    if (scripts[row.name] === undefined) return [];
+
+    const because = row.why ? `: ${row.why}` : '';
+    return [{
+      where: 'package.json',
+      what: `script ${JSON.stringify(row.name)} is declared — this uniform forbids it${because}`
+    }];
+  }
+});
+
+const scriptImplicit = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  /**
+   * A script that fires because something else ran. Two shapes, one rule: npm's
+   * own lifecycle names, and a `pre`/`post` hook — including one whose target
+   * this package does not declare, which fires on nothing at all and is a
+   * declaration with nothing behind it.
+   */
+  run({ serviceRoot }) {
+    const { scripts } = readScripts(serviceRoot);
+    const findings = [];
+
+    for (const name of Object.keys(scripts)) {
+      if (NPM_LIFECYCLE.includes(name)) {
+        findings.push({
+          where: 'package.json',
+          what: `script ${JSON.stringify(name)} is an npm lifecycle hook — it fires on an npm command, `
+            + 'not on a name; a script runs when it is named, never as a side effect'
+        });
+        continue;
+      }
+
+      const hook = /^(pre|post)(.+)$/.exec(name);
+      if (hook === null) continue;
+      const target = hook[2];
+
+      findings.push({
+        where: 'package.json',
+        what: scripts[target] === undefined
+          ? `script ${JSON.stringify(name)} fires on "npm run ${target}", which this package does not declare — `
+            + 'a script runs when it is named, never as a side effect'
+          : `script ${JSON.stringify(name)} fires as a side effect of "npm run ${target}" — `
+            + 'a script runs when it is named, never as a side effect'
+      });
+    }
+
+    return findings;
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'script-body', check: scriptBody },
+    { name: 'script-forbidden', check: scriptForbidden },
+    { name: 'script-implicit', check: scriptImplicit }
+  ],
+  binSpelling,
+  runnerName
+};

package/src/manifest/deployabilitySignal.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * `ci/deployability.json` — the machine half of the manifest verdict.
+ *
+ * Confirmation `biz-service-manifest` 001 §4: a `deploy` finding lets the
+ * service start and makes it undeployable. The banner says that to a human; this
+ * file says it to `deploy-production`, which refuses on a single row and names
+ * it. Its shape follows the signal this package already writes,
+ * `ci/integration-signal.json` (`utils/bizCiGateContract.js`
+ * buildIntegrationSignalSummary), with three deliberate differences:
+ *
+ *   - **no `generatedAt`.** The integration signal stamps every write, so two
+ *     runs over an unchanged repository produce two different files. This one is
+ *     a verdict about the tree, not about the moment, and an unchanged tree must
+ *     produce an unchanged file — otherwise nothing can tell a re-run from a
+ *     change.
+ *   - **`validatorVersion` instead of a version of its own.** The manifest ships
+ *     inside this package, so the manifest version IS the validator version and
+ *     the service's pin decides which shape it was measured against
+ *     (confirmation 004 § point 2, `loadManifest.js`).
+ *   - **`deployable` instead of a `gate: {verdict, reason}` block.** The verdict
+ *     is one boolean and its reasons are the findings; a second field restating
+ *     it would be a second owner of one fact.
+ *
+ * `notRun` is carried on purpose: inside a service container the workspace SSOTs
+ * are not present, so workspace-scoped rows cannot look. A signal that stayed
+ * silent about them would read as "everything checked, nothing found"
+ * (`.claude/rules/automation-gates.md` §5). It does not change the verdict —
+ * a row that did not run is not a finding.
+ *
+ * **`complete` is what the gate reads beside `deployable`** (d.230).
+ * `deployable` is true when nothing blocked among the rows that RAN; `complete`
+ * is true when no row that CAN block was skipped. In a container the second is
+ * routinely false, and until it was written down the deploy gate had no way to
+ * tell a proven tree from an unexamined one — it was honouring a `--skip` nobody
+ * had flagged (`automation-gates.md` §1.5). The deploy gate takes a signal only
+ * when both are true; the complete run is produced from the api checkout, with
+ * `npx oa-validate --workspace <root>`. Neither field changes an exit code: a
+ * partial run in the container is the intent, and completeness is the gate's
+ * question, not the boot's.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §4
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Where the signal lives, relative to the service root. One place, named once. */
+const SIGNAL_RELATIVE_PATH = 'ci/deployability.json';
+
+const PACKAGE_NAME = '@onlineapps/conn-orch-validator';
+
+/**
+ * @param {object} params
+ * @param {object} params.result the value `runManifest` returned
+ * @param {string} params.validatorVersion the running package version — the manifest version
+ * @returns {{validator: string, validatorVersion: string, uniform: string, serviceRoot: string,
+ *            deployable: boolean, complete: boolean, findings: Array<object>, notRun: Array<object>}}
+ */
+function buildDeployabilitySignal({ result, validatorVersion }) {
+  if (result === null || typeof result !== 'object') {
+    throw new Error('[DeployabilitySignal] Manifest result is required - buildDeployabilitySignal({ result }) got '
+      + `${JSON.stringify(result)}. Fix: pass the value runManifest() returned.`);
+  }
+  if (typeof validatorVersion !== 'string' || validatorVersion.length === 0) {
+    throw new Error('[DeployabilitySignal] Validator version is required - buildDeployabilitySignal('
+      + `{ validatorVersion }) got ${JSON.stringify(validatorVersion)}. `
+      + 'Fix: pass require("../package.json").version; the manifest version IS the validator version.');
+  }
+
+  if (typeof result.complete !== 'boolean') {
+    throw new Error('[DeployabilitySignal] Manifest result does not say whether it was complete - '
+      + `buildDeployabilitySignal({ result }) got complete=${JSON.stringify(result.complete)}. `
+      + 'Fix: pass the value runManifest() returned; a signal without it would let a gate read a '
+      + 'partial run as a proven one.');
+  }
+
+  return {
+    validator: PACKAGE_NAME,
+    validatorVersion,
+    uniform: result.uniform,
+    serviceRoot: result.serviceRoot,
+    deployable: result.ok,
+    complete: result.complete,
+    findings: result.findings,
+    notRun: result.notRun
+  };
+}
+
+/**
+ * Write the signal into `<serviceRoot>/ci/`, creating the directory.
+ *
+ * There is no switch that skips the write and no environment variable that
+ * moves it: the step that produces the verdict is the step that records it
+ * (`.claude/rules/automation-gates.md` §1 requirement 5).
+ *
+ * @param {{serviceRoot: string, signal: object}} params
+ * @returns {string} the absolute path written
+ */
+function writeDeployabilitySignal({ serviceRoot, signal }) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.length === 0) {
+    throw new Error('[DeployabilitySignal] Service root is required - writeDeployabilitySignal({ serviceRoot }) got '
+      + `${JSON.stringify(serviceRoot)}. Fix: pass the repository the signal describes.`);
+  }
+
+  const target = path.join(path.resolve(serviceRoot), ...SIGNAL_RELATIVE_PATH.split('/'));
+
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(signal, null, 2)}\n`);
+  } catch (cause) {
+    throw new Error(`[DeployabilitySignal] Cannot write the deployability signal to ${target} `
+      + '- Expected the service root to be writable. Fix: repair whatever the cause names '
+      + `(${cause.message})`, { cause });
+  }
+
+  return target;
+}
+
+module.exports = { buildDeployabilitySignal, writeDeployabilitySignal, SIGNAL_RELATIVE_PATH };