@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

package/src/manifest/checks/composeRunnerBlock.js

@@ -24,19 +24,24 @@
  * (here) — one concern, one rail (`.claude/rules/change-discipline.md` § One rail
  * per concern). Everything else in the block is compared byte for byte.
  *
- * The service's own identity is the other normalization: the runner's key is
- * `<container>_tests`, and the container name is the one thing that is per
- * repository by construction. It is substituted back to the template's
- * placeholders before the comparison, so the block is read as the template
- * wrote it.
+ * The service's own identity is the other half, and it is settled in ONE
+ * direction: the reference is RENDERED with this repository's names and the
+ * result compared against the file, never the file read back into placeholders
+ * (d.531). The runner's key is `<container>_tests` and the container name is per
+ * repository by construction, so a render is exact; reading a name back is not,
+ * because a name is also an ordinary word — for `api_biz/meta` it rewrote the
+ * template's own citation of that path and reported a conformant block as
+ * drifted. `renderRunnerIdentity` below is that one direction, and both the
+ * check and the generator go through it.
  *
  * ## The same definition renders
  *
- * `renderRunnerBlock` performs exactly the inverse: the template's block with
- * this repository's identity in it and this repository's three shared
- * declarations grafted in. That is what makes `npx oa-sync-template
- * docker-compose.yml` produce a block the check then finds clean — a generator
- * whose output its own check rejects is the defect this module exists to avoid.
+ * `renderRunnerBlock` is the generator's half: the same identity render, plus
+ * this repository's three shared declarations grafted in. That is what makes
+ * `npx oa-sync-template docker-compose.yml` produce a block the check then finds
+ * clean — a generator whose output its own check rejects is the defect this
+ * module exists to avoid, and it is measured over a service called `meta`
+ * (`tests/unit/manifestServiceFiles.test.js`).
  *
  * @see api/docs/governance/confirmations/biz-service-manifest.md §2, §3.2
  * @see api/docs/governance/confirmations/biz-test-container.md
@@ -156,8 +161,22 @@ function stripDeclarations(lines, keys) {
 }
 
 /**
- * A repository's runner block as the template wrote it: its identity replaced by
- * the placeholders, and the three shared declarations removed.
+ * The template's block with one repository's identity in it — the ONE direction
+ * this module substitutes (d.531).
+ *
+ * The other direction, reading a repository's block back into placeholders, was
+ * a second rail under the same rule and it could not be made right: a
+ * substitution of the service's NAME rewrites every occurrence of that string,
+ * including one in the template's own prose. Measured over `api_biz/meta`: the
+ * block cites `api_biz/meta/docker-compose.yml` as the file the memory numbers
+ * were taken in, so that service's conformant block was normalized into
+ * `api_biz/__SERVICE_NAME__/docker-compose.yml` and reported as drifted, while
+ * `oa-sync-template docker-compose.yml --check` — which renders — called the
+ * same file unchanged.
+ *
+ * A placeholder is a name nothing else can be, so rendering is total; a name is
+ * a word, and reading it back is a guess. One rail, and it is this one
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
  *
  * The container name is substituted BEFORE the service name on purpose: the
  * container name normally contains the service name (`api_service_converter`
@@ -167,10 +186,10 @@ function stripDeclarations(lines, keys) {
  * @param {{lines: string[], containerName: string, serviceName: string}} args
  * @returns {string[]}
  */
-function normalizeRunnerBlock({ lines, containerName, serviceName }) {
-  return stripDeclarations(lines, SHARED_DECLARATIONS).map((line) => line
-    .split(containerName).join(CONTAINER_PLACEHOLDER)
-    .split(serviceName).join(SERVICE_PLACEHOLDER));
+function renderRunnerIdentity({ lines, containerName, serviceName }) {
+  return lines.map((line) => line
+    .split(CONTAINER_PLACEHOLDER).join(containerName)
+    .split(SERVICE_PLACEHOLDER).join(serviceName));
 }
 
 /**
@@ -188,9 +207,7 @@ function normalizeRunnerBlock({ lines, containerName, serviceName }) {
  * @returns {string[]} the block's lines, markers included
  */
 function renderRunnerBlock({ reference, composeText, containerName, serviceName }) {
-  let rendered = reference.map((line) => line
-    .split(CONTAINER_PLACEHOLDER).join(containerName)
-    .split(SERVICE_PLACEHOLDER).join(serviceName));
+  let rendered = renderRunnerIdentity({ lines: reference, containerName, serviceName });
 
   const service = serviceLines(composeText, containerName);
 
@@ -217,6 +234,6 @@ module.exports = {
   serviceLines,
   replaceServiceNode,
   stripDeclarations,
-  normalizeRunnerBlock,
+  renderRunnerIdentity,
   renderRunnerBlock
 };

package/src/manifest/checks/discoveryOrphan.js

@@ -18,6 +18,7 @@
  */
 
 const { discoverBearers, rootOfPattern } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 
 const check = Object.freeze({
   scope: 'workspace',
@@ -31,7 +32,7 @@ const check = Object.freeze({
   /** 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`;
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   /**

package/src/manifest/checks/docsLintBridge.js

@@ -54,7 +54,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const { whereOf } = require('./libraryContext');
-const { resolveWorkspacePath } = require('../workspaceRoot');
+const { resolveWorkspacePath, describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 
 /** The documentation lint, by the path the manifest writes every api path in. */
 const LINT_SCRIPT = 'api/scripts/ci/lint-biz-docs.mjs';
@@ -210,6 +210,55 @@ const ERROR_SEVERITY = 'error';
  */
 const errorGraded = (findings) => findings.filter((finding) => finding.severity === ERROR_SEVERITY);
 
+/**
+ * The NOT RUN sentence of a row the linter could not decide — the rules it could
+ * not evaluate, the linter's own reason for the first of them, and the command
+ * that turns this checkout into one where the question has an answer.
+ *
+ * Three things, and each has exactly one owner. The rule ids and the reason are
+ * the LINTER'S: this module cites the tool, it does not restate it, which is the
+ * whole point of the bridge (docblock at the top of this file). The remedy is
+ * `workspaceRoot.js` § describeWorkspaceFix, shared with
+ * `runManifest.js` § describeMissingRoots — the other place a row goes NOT RUN
+ * because a sibling was not there. Until d.516 this end of it stopped at the
+ * linter's reason: measured 2026-09-15 over a `git archive HEAD` export placed
+ * beside no `api_biz`, the run printed
+ *
+ *   NOT RUN  D-PORT — F002:http-ports could not be decided — api_biz/*/docker-compose.yml
+ *            lives in a sibling checkout this run does not have, so the probe could not
+ *            be evaluated
+ *
+ * while `U-ORPHAN`, in the SAME run and about the SAME absent directory, named
+ * the command. True, and nothing the reader could act on
+ * (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * What the fix asks the reader to carry is left as the phrase pointing back at
+ * the reason, rather than a root resolved here. The linter's skipped channel
+ * names the absent THING — a probe target, a scan root, a manifest — and it
+ * carries no structured root to read (`api/scripts/ci/lint-biz-docs.mjs`
+ * § markSkipped: `{ rule, reason }` and nothing else). Deriving one would mean
+ * parsing that sentence, which is the private dialect between row and tool this
+ * bridge exists to avoid; naming the siblings here instead would make this
+ * module a second owner of the lint's own probe configuration.
+ *
+ * Collapsed into one reason per row: a checkout without siblings makes a dozen
+ * bans undecidable at once, and twelve identical sentences say nothing the first
+ * one does not.
+ *
+ * @param {Array<{rule: string, reason: string}>} undecided at least one entry
+ * @returns {string}
+ */
+function describeUndecided(undecided) {
+  if (!Array.isArray(undecided) || undecided.length === 0) {
+    throw new Error('[DocsLintBridge] Undecided rules are required - describeUndecided() was given '
+      + `${JSON.stringify(undecided)}, and a row with nothing undecided is not NOT RUN. `
+      + 'Fix: call it only when the linter reported at least one rule it could not evaluate.');
+  }
+
+  return `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
+    + `${undecided[0].reason}. ${describeWorkspaceFix(AS_THE_REASON_NAMES)}`;
+}
+
 /**
  * Which row owns a lint finding: the one whose citation is the most specific.
  *
@@ -250,7 +299,11 @@ function claimantOf(ruleId, rows) {
  * @returns {{findings: Array<object>, skipped: Array<object>}|{problem: string}}
  */
 function lintOnce({ lintScript, docsDir, treeConfig }) {
-  const key = [lintScript, docsDir, treeConfig].join('');
+  // `\0` as the escape, never the raw byte: written literally it makes the
+  // whole file binary to grep, diff and every reader that asks what changed
+  // (measured 2026-09-16 — `grep -n` answered "Binary file … matches" and
+  // printed nothing). The value is identical; the source stays readable.
+  const key = [lintScript, docsDir, treeConfig].join('\0');
   if (answers.has(key)) return answers.get(key);
 
   const answer = runLint({ lintScript, docsDir, treeConfig });
@@ -394,15 +447,31 @@ function askLint({ block, serviceRoot, workspaceRoot }) {
   return { answer };
 }
 
+/**
+ * The absence BOTH documentation rows answer, in one sentence.
+ *
+ * `describeMissingRoots` answers "the workspace is there and the root is not";
+ * this one answers "there is no workspace at all". Until d.516b it stopped at
+ * the absence — the defect `.claude/rules/automation-gates.md` §1 requirement 4
+ * names, one channel over from the one d.516 closed. Until d.523 the sentence
+ * was then written TWICE, once per row, byte for byte: two rails for one
+ * concern (`.claude/rules/change-discipline.md` § One rail per concern), and
+ * the shape in which the first of the two would one day be improved alone.
+ *
+ * @returns {string}
+ */
+function describeLintNotRun() {
+  return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run. `
+    + describeWorkspaceFix(LINT_SCRIPT);
+}
+
 const docsLint = Object.freeze({
   scope: 'bearer',
   requires: Object.freeze(['rule']),
 
   requiresSiblings: () => [LINT_DIR],
 
-  describeNotRun() {
-    return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run`;
-  },
+  describeNotRun: describeLintNotRun,
 
   /**
    * @param {{ row: object, block: object, serviceRoot: string, workspaceRoot: string }} params
@@ -446,20 +515,15 @@ const docsLint = Object.freeze({
     // is `answer.problem` above, and the absent tree config before it, both of
     // which stay findings with a fix somebody can carry out.
     //
-    // Collapsed into one reason per row: a checkout without siblings makes a
-    // dozen bans undecidable at once, and twelve identical sentences say nothing
-    // the first one does not.
+    // The sentence itself is `describeUndecided` above — shared with `D-LINT`,
+    // which reports the same absence about the rules no row claims.
     const undecided = answer.skipped
       .filter((entry) => citations.some((citation) => covers(citation, entry.rule)))
       .filter((entry) => claimantOf(entry.rule, rows) === row.id);
 
     if (undecided.length === 0) return found;
 
-    return {
-      findings: found,
-      notRun: `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
-        + `${undecided[0].reason}`
-    };
+    return { findings: found, notRun: describeUndecided(undecided) };
   }
 });
 
@@ -497,9 +561,7 @@ const docsLintClean = Object.freeze({
 
   requiresSiblings: () => [LINT_DIR],
 
-  describeNotRun() {
-    return `the workspace root is not reachable, so ${LINT_SCRIPT} cannot be run`;
-  },
+  describeNotRun: describeLintNotRun,
 
   /**
    * @param {{ block: object, serviceRoot: string, workspaceRoot: string }} params
@@ -531,11 +593,7 @@ const docsLintClean = Object.freeze({
     const undecided = answer.skipped.filter((entry) => claimantOf(entry.rule, rows) === null);
     if (undecided.length === 0) return found;
 
-    return {
-      findings: found,
-      notRun: `${undecided.map((entry) => entry.rule).join(', ')} could not be decided — `
-        + `${undecided[0].reason}`
-    };
+    return { findings: found, notRun: describeUndecided(undecided) };
   }
 });
 

package/src/manifest/checks/gitTracked.js

@@ -45,7 +45,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
+const { gitCommand, listTrackedFiles, NOT_A_CHECKOUT } = require('../gitCheckout');
 
 /** Never walked: neither is part of a repository's declared shape. */
 const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
@@ -53,29 +53,6 @@ const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
 /** The file classes whose rows REQUIRE a path to be there. */
 const REQUIRING_CLASSES = Object.freeze(['identical', 'contains', 'generated']);
 
-/**
- * Run one git command in the repository, or return null when git itself could
- * not answer. Nothing here guesses: the caller turns a null into NOT RUN.
- *
- * @param {string} serviceRoot
- * @param {string[]} args
- * @param {string} [input]
- * @returns {string|null}
- */
-function git(serviceRoot, args, input = undefined) {
-  try {
-    return execFileSync('git', ['-C', serviceRoot, ...args], {
-      encoding: 'utf8',
-      input,
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-  } catch (error) {
-    // check-ignore exits 1 when nothing matched, which is an ANSWER.
-    if (error.status === 1 && typeof error.stdout === 'string') return error.stdout;
-    return null;
-  }
-}
-
 /**
  * Does the path exist under EXACTLY this spelling?
  *
@@ -161,12 +138,21 @@ const check = Object.freeze({
    * @returns {{findings: Array<{where: string, what: string}>, notRun: string|null}}
    */
   run({ block, serviceRoot }) {
-    const listed = git(serviceRoot, ['ls-files', '-z']);
+    const listed = listTrackedFiles(serviceRoot);
     if (listed === null) {
       return {
         findings: [],
-        notRun: 'this tree is not a git checkout (git ls-files could not answer), so what a clone '
-          + 'would receive cannot be read — a container and an exported tarball are in exactly this state'
+        // The remedy of this row is NOT the one every other NOT RUN of this
+        // package carries. `workspaceRoot.js` § describeWorkspaceFix names
+        // `--workspace`, which points at a tree of checkouts; no value of it
+        // turns an export into a checkout, and this row asks git, not the
+        // workspace. So the sentence is this row's own — one remedy, one owner,
+        // and neither borrowed from the other
+        // (`.claude/rules/change-discipline.md` § One rail per concern).
+        // Until d.518 it stopped at the absence, which is the dead end
+        // `.claude/rules/automation-gates.md` §1 requirement 4 forbids.
+        notRun: `${NOT_A_CHECKOUT} Fix: run this row over a git checkout — a clone of the repository, `
+          + 'never an export, a tarball or a built image.'
       };
     }
 
@@ -180,7 +166,7 @@ const check = Object.freeze({
 
     // Only now, and only for those: which of them a .gitignore rule covers is
     // what turns the finding into an edit the reader can make.
-    const answered = git(serviceRoot, ['check-ignore', '--stdin', '-z'], missing.map(({ file }) => file).join('\0'));
+    const answered = gitCommand(serviceRoot, ['check-ignore', '--stdin', '-z'], missing.map(({ file }) => file).join('\0'));
     const ignored = new Set((answered === null ? '' : answered).split('\0').filter((entry) => entry.length > 0));
 
     return {

package/src/manifest/checks/libraryPackage.js

@@ -17,6 +17,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { resolveFromValue } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const {
   readPackage, whereOf, appliesTo, allDeps, scopedDeps, nodeMajorOf
 } = require('./libraryContext');
@@ -91,7 +92,8 @@ const libraryEngines = Object.freeze({
   requires: Object.freeze(['from']),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${row.from.path} cannot be read`;
+    return `the workspace root is not reachable, so ${row.from.path} cannot be read. `
+      + describeWorkspaceFix(row.from.path);
   },
 
   run({ row, block, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/libraryWorkspace.js

@@ -28,7 +28,7 @@ const path = require('path');
 const {
   discoverBearers, resolveFromReference, resolveFromMap, expandPattern, rootOfPattern
 } = require('../discovery');
-const { resolveWorkspacePath } = require('../workspaceRoot');
+const { resolveWorkspacePath, describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 const {
   readJson, readPackage, whereOf, declaredCategory, appliesTo, scopedDeps, SCOPE
 } = require('./libraryContext');
@@ -39,8 +39,23 @@ const RUNTIME_SECTIONS = Object.freeze(['dependencies']);
 /** The sections `scripts/ci/verify-manifest-pins.mjs` compares against the SSOT. */
 const PINNED_SECTIONS = Object.freeze(['dependencies', 'devDependencies']);
 
-/** Why a workspace-scoped row prints nothing instead of a verdict. */
-const notRunBecause = (what) => `the workspace root is not reachable, so ${what} cannot be read`;
+/**
+ * Why a workspace-scoped row prints nothing instead of a verdict — and, since
+ * d.518, what to run so that it can.
+ *
+ * Five rows of the library uniform are reported through this one line
+ * (`U-ORPHAN`, `U-MISMATCH`, `L-PINS`, `L-CONSUMER`, `L-TOOLING`), so the
+ * command belongs here rather than at each of them: one remedy, one sentence,
+ * one owner (`workspaceRoot.js` § describeWorkspaceFix,
+ * `.claude/rules/change-discipline.md` § One rail per concern). Until d.518 all
+ * five stopped at the absence — true, and nothing a reader of a CI log can act
+ * on (`.claude/rules/automation-gates.md` §1 requirement 4).
+ *
+ * WHAT the checkout has to carry is already named by `what`, immediately before
+ * the fix, so the fix points back at it instead of repeating it in other words.
+ */
+const notRunBecause = (what) => `the workspace root is not reachable, so ${what} cannot be read. `
+  + describeWorkspaceFix(AS_THE_REASON_NAMES);
 
 /**
  * Every package the uniform's discovery pattern finds, indexed by the name its

package/src/manifest/checks/readmeRegion.js

@@ -32,6 +32,7 @@ const {
   readReadme, serviceRegion, libraryRegion, PACKAGE_IN_WORKSPACE
 } = require('../../sync/readmeLocation');
 const { whereOf, declaredCategory, readPackage } = require('./libraryContext');
+const { describeWorkspaceFix, AS_THE_REASON_NAMES } = require('../workspaceRoot');
 
 /**
  * The first line at which the region on disk stops being the rendered one, and
@@ -102,8 +103,15 @@ const libraryReadmeRegion = Object.freeze({
   // holds a copy of this package.
   requiresSiblings: () => (PACKAGE_IN_WORKSPACE === null ? [] : [PACKAGE_IN_WORKSPACE]),
 
+  // The absence, and then the command that removes it, from the one owner of
+  // that command (`workspaceRoot.js` § describeWorkspaceFix). What the checkout
+  // must carry is named by the sentence in front of it, so the fix points back
+  // at it rather than saying it a second time in other words — which is what
+  // `AS_THE_REASON_NAMES` is for. Until d.518 this ended at the absence
+  // (`.claude/rules/automation-gates.md` §1 requirement 4).
   describeNotRun() {
-    return 'the workspace root is not reachable, so the manifest the region links at cannot be located';
+    return 'the workspace root is not reachable, so the manifest the region links at cannot be located. '
+      + describeWorkspaceFix(AS_THE_REASON_NAMES);
   },
 
   run({ row, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/serviceConfig.js

@@ -25,9 +25,10 @@
 const fs = require('fs');
 const path = require('path');
 
-const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
+const { resolveFromDocument, isPackageReference, referenceOwner } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { whereOf } = require('./libraryContext');
-const { diffAgainst } = require('../../sync/sharedEnv');
+const { diffAgainst, renderSharedEnv } = require('../../sync/sharedEnv');
 const { loadAndValidateIntegrationContract } = require('../../utils/bizCiGateContract');
 
 /** The generated platform file every service carries a copy of. */
@@ -333,14 +334,29 @@ const envTemplates = Object.freeze({
 });
 
 /**
- * `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.
+ * `shared.env` is generated, never written, and this row reads the file that
+ * OWNS the key set — `api/config/shared-env.json` in the workspace — through the
+ * same renderer `npx oa-sync-template shared-env` writes with (`src/sync/sharedEnv.js`).
+ *
+ * Until d.536 it read the render this package carries (d.229), so the verdict
+ * depended on the day the validator was published rather than on the SSOT: the
+ * three services synced after the 9.0.0 publish were told "10 line(s) differ" by
+ * a row whose own fix command had just written the file, because the SSOT had
+ * gained `LOG_MAX_SIZE_BYTES`, `LOG_MAX_FILES` and a comment since. One fact
+ * cannot be read off two files (`.claude/rules/change-discipline.md` § One rail
+ * per concern), and a gate whose answer moves with a publication date is not
+ * predictable (`.claude/rules/automation-gates.md` §1.1).
+ *
+ * The reason d.229 gave for the packaged copy — "a service container has no
+ * `api/config/`" — no longer buys anything the row needs: the deploy job the
+ * uniform runs in clones the api checkout (confirmation `biz-service-manifest`
+ * 008), and where the workspace really is out of reach the row says NOT RUN and
+ * names the command, which is what every other workspace-reading row does. A
+ * silent pass measured against yesterday's key set is the false guarantee
+ * `automation-gates.md` §5 calls a defect.
+ *
+ * `templates/business-service/config/env-templates/shared.env` stays as the
+ * scaffold's own output, and `sharedEnvTemplate.test.js` stays the gate on it.
  */
 const sharedEnvGenerated = Object.freeze({
   scope: 'bearer',
@@ -349,7 +365,8 @@ const sharedEnvGenerated = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   run({ row, serviceRoot, workspaceRoot }) {
@@ -360,7 +377,7 @@ const sharedEnvGenerated = Object.freeze({
       return [{ where, what: `absent — it is rendered from ${owner}` }];
     }
 
-    const rendered = readReferencedFile({ from: row.from, workspaceRoot });
+    const rendered = renderSharedEnv(resolveFromDocument({ from: row.from, workspaceRoot }));
     if (rendered === text) return [];
 
     const differing = diffAgainst(rendered, text).split('\n').filter((line) => /^[-+]/.test(line)).length - 2;