@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/checks/libraryWorkspace.js

@@ -0,0 +1,293 @@
+'use strict';
+
+/**
+ * The rows a library cannot answer alone: whether the SSOT knows it, whether its
+ * declared category survives contact with the dependency graph, whether its pins
+ * are the versions the SSOT declares, whether anybody uses it at all, and whether
+ * a tooling package has stayed out of the services.
+ *
+ * None of them can answer from the package root alone, and they split by WHAT
+ * they are about. `U-ORPHAN` and `U-MISMATCH` are about the whole set, so they
+ * are `scope: 'workspace'`. `L-PINS`, `L-CONSUMER` and `L-TOOLING` are facts of
+ * ONE package — its pins against the SSOT, who pins it, which service carries
+ * it — that reach the answer only through the workspace, so they are
+ * `scope: 'bearer'` and run once per package. Carried as `workspace` they had to
+ * read a null package root and return `[]`, and the whole-set run then said
+ * nothing about them at all.
+ * Inside a container none of these files is present, and a row that cannot look
+ * is reported NOT RUN and never as passing
+ * (`.claude/rules/automation-gates.md` §5). The same holds one level down: a
+ * row reading a directory this checkout does not carry declares it in
+ * `requiresSiblings`, and the runner reports NOT RUN before the check runs.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §11
+ */
+
+const path = require('path');
+
+const {
+  discoverBearers, resolveFromReference, resolveFromMap, expandPattern, rootOfPattern
+} = require('../discovery');
+const { resolveWorkspacePath } = require('../workspaceRoot');
+const {
+  readJson, readPackage, whereOf, declaredCategory, appliesTo, scopedDeps, SCOPE
+} = require('./libraryContext');
+
+/** The section that decides the layer: what the package pulls into a runtime. */
+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`;
+
+/**
+ * Every package the uniform's discovery pattern finds, indexed by the name its
+ * own `package.json` carries. That name — not the directory — is what the SSOT
+ * owns and what a dependency writes.
+ *
+ * @param {{ block: object, workspaceRoot: string }} params
+ * @returns {Map<string, {relativeDir: string, dir: string, category: string|null}>}
+ */
+function indexBearers({ block, workspaceRoot }) {
+  const { bearers } = discoverBearers({ block, workspaceRoot });
+  const index = new Map();
+
+  for (const bearer of bearers) {
+    const json = readJson(resolveWorkspacePath(workspaceRoot, bearer.file));
+    if (json === null || typeof json.name !== 'string') continue;
+    index.set(json.name, {
+      relativeDir: bearer.relativeDir,
+      dir: bearer.dir,
+      category: declaredCategory(json)
+    });
+  }
+  return index;
+}
+
+const libraryOrphan = Object.freeze({
+  scope: 'workspace',
+  requires: Object.freeze([]),
+
+  requiresSiblings({ block }) {
+    return [rootOfPattern(block.pattern)];
+  },
+
+  describeNotRun({ block }) {
+    return notRunBecause(block && block.from ? block.from.path : 'the referenced SSOT');
+  },
+
+  run({ block, workspaceRoot }) {
+    const onDisk = indexBearers({ block, workspaceRoot });
+    const declared = new Set(resolveFromReference({ from: block.from, workspaceRoot }));
+    const findings = [];
+
+    for (const [name, bearer] of onDisk) {
+      if (declared.has(name)) continue;
+      findings.push({
+        where: bearer.relativeDir,
+        what: `${name} is not declared in ${block.from.path} (${block.from.list}) — nothing pins it and nothing publishes it`
+      });
+    }
+
+    for (const name of declared) {
+      if (onDisk.has(name)) continue;
+      findings.push({
+        where: block.from.path,
+        what: `${name} is declared with a version but no package matches ${block.pattern}`
+      });
+    }
+
+    return findings;
+  }
+});
+
+const libraryCategory = Object.freeze({
+  scope: 'workspace',
+  requires: Object.freeze([]),
+
+  requiresSiblings({ block }) {
+    return [rootOfPattern(block.pattern)];
+  },
+
+  describeNotRun() {
+    return notRunBecause('the categories of the packages this one depends on');
+  },
+
+  run({ block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null) return [];
+    const where = whereOf({ scope: 'workspace', serviceRoot, workspaceRoot, relative: 'package.json' });
+
+    const declared = declaredCategory(json);
+    if (declared === null) {
+      return [{
+        where,
+        what: 'declares no "oa"."category" — the layer a package is meant to sit in cannot be derived from anything else'
+      }];
+    }
+
+    const definition = block.categories[declared];
+    if (definition === undefined) {
+      return [{
+        where,
+        what: `declares category "${declared}", which this uniform does not define `
+          + `(defined: ${Object.keys(block.categories).join(', ')})`
+      }];
+    }
+
+    const index = indexBearers({ block, workspaceRoot });
+    const allowed = new Set(definition.may_depend_on);
+
+    return scopedDeps(json, RUNTIME_SECTIONS).map(({ name }) => {
+      const dependency = index.get(name);
+      if (dependency === undefined) {
+        return {
+          where,
+          what: `depends on ${name}, which no package under ${block.pattern} provides — its category cannot be read`
+        };
+      }
+      if (dependency.category === null) {
+        return {
+          where,
+          what: `depends on ${name}, which declares no category — the layer of "${declared}" cannot be verified`
+        };
+      }
+      if (!allowed.has(dependency.category)) {
+        return {
+          where,
+          what: `declares category "${declared}" but depends on ${name}, which is "${dependency.category}" `
+            + `(may_depend_on: ${definition.may_depend_on.join(', ') || 'nothing'})`
+        };
+      }
+      return null;
+    }).filter((finding) => finding !== null);
+  }
+});
+
+const libraryPins = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['from']),
+
+  describeNotRun({ row }) {
+    return notRunBecause(row.from.path);
+  },
+
+  run({ row, block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const ssot = resolveFromMap({ from: row.from, workspaceRoot });
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'package.json' });
+
+    return scopedDeps(json, PINNED_SECTIONS)
+      .map(({ name, spec, section }) => {
+        const owned = ssot[name];
+        if (owned === undefined) {
+          return { where, what: `${section} pins ${name}, which ${row.from.path} does not declare` };
+        }
+        if (spec !== owned) {
+          return { where, what: `${section} pins ${name} at "${spec}" but ${row.from.path} declares ${owned}` };
+        }
+        return null;
+      })
+      .filter((finding) => finding !== null);
+  }
+});
+
+const libraryConsumer = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['consumer_patterns']),
+
+  // The row already says where the consumers live; the roots it needs are read
+  // off that, never restated. In a checkout carrying `api/` alone, `api_biz` is
+  // absent and "pinned by nothing" would be a lie about a file nobody opened.
+  requiresSiblings({ row }) {
+    return row.consumer_patterns.map(rootOfPattern);
+  },
+
+  describeNotRun({ row }) {
+    return notRunBecause(`the consumers under ${row.consumer_patterns.join(', ')}`);
+  },
+
+  run({ row, block, serviceRoot, workspaceRoot }) {
+    const { json, file } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const own = path.resolve(file);
+    const consumers = [];
+
+    for (const pattern of row.consumer_patterns) {
+      for (const relative of expandPattern(workspaceRoot, pattern)) {
+        const absolute = resolveWorkspacePath(workspaceRoot, relative);
+        if (path.resolve(absolute) === own) continue;
+        const consumer = readJson(absolute);
+        if (consumer === null) continue;
+        const declared = { ...(consumer.dependencies || {}), ...(consumer.devDependencies || {}) };
+        if (Object.prototype.hasOwnProperty.call(declared, json.name)) consumers.push(relative);
+      }
+    }
+
+    if (consumers.length > 0) return [];
+    return [{
+      where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'package.json' }),
+      what: `${json.name} is pinned by nothing under ${row.consumer_patterns.join(', ')} — it is unwired or dead`
+    }];
+  }
+});
+
+const libraryTooling = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['service_pattern']),
+
+  requiresSiblings({ row }) {
+    return [rootOfPattern(row.service_pattern)];
+  },
+
+  describeNotRun({ row }) {
+    return notRunBecause(`the services under ${row.service_pattern}`);
+  },
+
+  run({ row, block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const where = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'package.json' });
+    const findings = [];
+
+    const bin = json.bin;
+    const hasBin = typeof bin === 'string' ? bin.length > 0 : (bin !== null && typeof bin === 'object' && Object.keys(bin).length > 0);
+    if (!hasBin) {
+      findings.push({ where, what: 'declares no "bin" — tooling is reached by a command, not by an import' });
+    }
+
+    for (const relative of expandPattern(workspaceRoot, row.service_pattern)) {
+      const service = readJson(resolveWorkspacePath(workspaceRoot, relative));
+      if (service === null) continue;
+      if (!Object.prototype.hasOwnProperty.call(service.dependencies || {}, json.name)) continue;
+      // The finding is reported at the LIBRARY, not at the service: it is the
+      // library's duty and the library's table, and a finding placed under a
+      // neighbour's root is one a service-mode run would drop entirely
+      // (`runManifest.js` § The two modes).
+      findings.push({
+        where,
+        what: `${relative} carries ${json.name} in dependencies — tooling never runs inside a service`
+      });
+    }
+
+    return findings;
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'library-orphan', check: libraryOrphan },
+    { name: 'library-category', check: libraryCategory },
+    { name: 'library-pins', check: libraryPins },
+    { name: 'library-consumer', check: libraryConsumer },
+    { name: 'library-tooling', check: libraryTooling }
+  ],
+  indexBearers,
+  SCOPE
+};

package/src/manifest/checks/readmeRegion.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * The `Uniform:` region of a README, as a ROW rather than only as a `--check`.
+ *
+ * Owner decision 2026-09-09 (answering the kontrolor's d.215c note): that region
+ * is of the class `generated` — confirmation `biz-service-manifest` 001 §2 makes
+ * such a class a GENERATOR plus a row carrying the `--check` as its gate, the
+ * precedent being `G-SHARED-ENV`. Until this module the generator existed and
+ * the gate did not, so a README whose pointer had gone stale was reported by
+ * nothing anybody runs on a repository — the false guarantee of
+ * `.claude/rules/automation-gates.md` §5.
+ *
+ * ONE IMPLEMENTATION, TWO READERS. Nothing here decides what the region says:
+ * it renders through `readmePointer.js` and compares through the very
+ * `checkUniformRegion` the `--check` run calls, so the row and the command
+ * cannot disagree about the same file (`.claude/rules/change-discipline.md`
+ * § One rail per concern). Where the region's link points is
+ * `readmeLocation.js`, for the same reason.
+ *
+ * WHAT THE FINDING SAYS. The `--check` run prints the whole region twice, as a
+ * `-`/`+` block; a row's `what` is a table cell, so it names the first line that
+ * differs and what the file says there — the locator shape `F-INIT` and the sync
+ * already use. The full diff is one command away, and that command is the row's
+ * `fix`.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+const { KINDS, extractRegion, checkUniformRegion } = require('../../sync/readmePointer');
+const {
+  readReadme, serviceRegion, libraryRegion, PACKAGE_IN_WORKSPACE
+} = require('../../sync/readmeLocation');
+const { whereOf, declaredCategory, readPackage } = require('./libraryContext');
+
+/**
+ * The first line at which the region on disk stops being the rendered one, and
+ * what the file says there.
+ *
+ * @param {string} expected the rendered region
+ * @param {string} actual the region on disk
+ * @returns {string}
+ */
+function firstDifference(expected, actual) {
+  const want = expected.split('\n');
+  const have = actual.split('\n');
+  const length = Math.max(want.length, have.length);
+  for (let index = 0; index < length; index += 1) {
+    if (want[index] === have[index]) continue;
+    return `at region line ${index + 1}: ${JSON.stringify(have[index] === undefined ? '<end of region>' : have[index].trim())}`;
+  }
+  return 'nowhere — the region matches line for line';
+}
+
+/**
+ * One README measured against the region its manifest renders.
+ *
+ * @param {{ kind: string, dir: string, region: string, where: string, path: string }} params
+ * @returns {Array<{where: string, what: string}>}
+ */
+function compare({ kind, dir, region, where, path: relative }) {
+  const text = readReadme(dir);
+  if (text === null) {
+    return [{ where, what: `absent — the uniform pointer is a generated region of ${relative}` }];
+  }
+
+  const result = checkUniformRegion(text, region, { kind });
+  if (result.ok) return [];
+
+  const actual = extractRegion(text, { kind });
+  if (actual === null) {
+    return [{
+      where,
+      what: 'carries no generated uniform region — which uniform a repository wears is rendered from the '
+        + 'manifest, never typed and never absent'
+    }];
+  }
+  return [{ where, what: `the generated uniform region is not what the manifest renders, ${firstDifference(region, actual)}` }];
+}
+
+const readmeUniformCurrent = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'from']),
+
+  run({ row, serviceRoot }) {
+    return compare({
+      kind: KINDS.service,
+      dir: serviceRoot,
+      path: row.path,
+      where: row.path,
+      region: serviceRegion(serviceRoot)
+    });
+  }
+});
+
+const libraryReadmeRegion = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path']),
+
+  // The link this region carries points at the library manifest as it lies in
+  // the checkout being read, so the row can only answer where that checkout
+  // holds a copy of this package.
+  requiresSiblings: () => (PACKAGE_IN_WORKSPACE === null ? [] : [PACKAGE_IN_WORKSPACE]),
+
+  describeNotRun() {
+    return 'the workspace root is not reachable, so the manifest the region links at cannot be located';
+  },
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+
+    // A package declaring no category is `U-MISMATCH`, blocking, with its own
+    // fix — and the region cannot be rendered without one, because the duty
+    // sections it lists ARE the category's. Saying so twice would give one
+    // defect two owners; this is the same silence `oa-sync-template
+    // readme-uniform --all` keeps, and for the same reason.
+    if (json === null || declaredCategory(json) === null) return [];
+
+    return compare({
+      kind: KINDS.library,
+      dir: serviceRoot,
+      path: row.path,
+      where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path }),
+      region: libraryRegion({ packageDir: serviceRoot, pkg: json, workspaceRoot })
+    });
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'readme-uniform-current', check: readmeUniformCurrent },
+    { name: 'library-readme-region', check: libraryReadmeRegion }
+  ],
+  firstDifference
+};

package/src/manifest/checks/scriptHeaders.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * `S-SCRIPTS` — what a reader can learn about a script before running it.
+ *
+ * Confirmation `biz-service-manifest` 003 §19 makes the repository's own
+ * `scripts/` a duty of the uniform, checked by the lint "shipped in the
+ * validator package". That last clause is the whole design: the rules used to
+ * be a file of the `api` checkout, and a service has no such directory in its
+ * own CI and none at all inside its image, so the row could only ever have been
+ * NOT RUN where it is meant to answer. `src/lint/scripts/lintScripts.js` holds
+ * them now; this module is the bridge from the row to that module and decides
+ * nothing itself — the same shape `contractBridge.js` and `docsLintBridge.js`
+ * keep (004 point 4: a rule that exists is cited, never restated).
+ *
+ * ONE THING NEEDS THE WORKSPACE, AND ONLY WHEN IT IS USED. The header rules
+ * read the repository alone, so the row is `scope: service` and answers in a
+ * container. The exception is `S006`: a script may cite `api/docs/…`, and that
+ * path names the api checkout beside this repository, not a `docs/` of its own.
+ * With the workspace reachable the citation is resolved there; without it the
+ * lint returns the target as UNRESOLVED and this module reports the row NOT RUN
+ * with the targets named — a run that could not look must not report a pass
+ * (`.claude/rules/automation-gates.md` §5). A repository citing no such path is
+ * decided in full wherever it lies, which is the common case: measured
+ * 2026-09-10, 4 of the 47 `@see` lines under the eight services open with the
+ * prefix.
+ *
+ * @see api/docs/standards/SCRIPTS-STANDARD.md
+ * @see api/docs/governance/confirmations/biz-service-manifest.md
+ */
+
+const fs = require('fs');
+
+const { lintScripts, SCRIPT_SCOPE } = require('../../lint/scripts/lintScripts');
+const { resolveWorkspacePath, WORKSPACE_MARKER } = require('../workspaceRoot');
+
+/**
+ * The api checkout, by the name the workspace marker already spells. Written
+ * once, from the marker, so "which directory is the api one" has one owner
+ * (`api/.claude/rules/single-source-of-truth.md`).
+ */
+const API_CHECKOUT = WORKSPACE_MARKER.split('/')[0];
+
+/**
+ * Where the citations of one repository can be resolved, or null.
+ *
+ * @param {string|null} workspaceRoot
+ * @returns {string|null}
+ */
+function apiCheckout(workspaceRoot) {
+  if (workspaceRoot === null || workspaceRoot === undefined) return null;
+  const target = resolveWorkspacePath(workspaceRoot, API_CHECKOUT);
+  return fs.existsSync(target) && fs.statSync(target).isDirectory() ? target : null;
+}
+
+const scriptsLint = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ serviceRoot, workspaceRoot }) {
+    const result = lintScripts({ root: serviceRoot, apiRoot: apiCheckout(workspaceRoot) });
+
+    const findings = result.findings.map((finding) => ({
+      where: `${finding.file}:${finding.line}`,
+      what: `${finding.id} — ${finding.message}`
+    }));
+
+    if (result.unresolved.length === 0) return findings;
+
+    return {
+      findings,
+      notRun: `${result.unresolved.length} @see target(s) name the ${API_CHECKOUT} checkout, which this run `
+        + `cannot reach: ${result.unresolved.join(', ')}. Run the uniform from a workspace that carries `
+        + `${API_CHECKOUT}/.`
+    };
+  }
+});
+
+module.exports = { checks: [{ name: 'scripts-lint', check: scriptsLint }], SCRIPT_SCOPE, API_CHECKOUT };