@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/src/manifest/discovery.js

@@ -0,0 +1,386 @@
+'use strict';
+
+/**
+ * Discovery — who wears the uniform.
+ *
+ * Confirmation `biz-service-manifest` 005 point 1: completeness is discovery.
+ * The manifest names a pattern; the check walks the disk and binds every bearer
+ * it finds to the SSOT that owns the names (004 point 2 — a reference, never a
+ * copy). A directory that matches no pattern, or one whose SSOT does not know
+ * it, is `U-ORPHAN`. No header is read and none is needed: a bearer's uniform
+ * is its location.
+ *
+ * Disagreement between the SSOT and the disk in the OTHER direction (a name
+ * declared with no directory) is a finding of the SSOT or of the repository,
+ * not of the manifest (004 point 4); `api/tests/scripts/repository-inventory.bats`
+ * already owns it and nothing here reimplements it.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { resolveWorkspacePath } = require('./workspaceRoot');
+
+/** Never walked: neither is part of any repository's declared shape. */
+const NEVER_WALKED = Object.freeze(['node_modules', '.git']);
+
+/**
+ * This package's own root — the directory carrying `manifests/` and
+ * `templates/`. Derived from this file's location, so it is the SAME copy the
+ * pin decides: a checkout's `api/shared/connector/conn-orch-validator`, or the
+ * `node_modules/@onlineapps/conn-orch-validator` a service installed.
+ */
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+
+/**
+ * Whether a `from:` reference names a file this package carries itself.
+ *
+ * The distinction decides where the file is read from AND whether the row can
+ * run at all without a workspace, so it is asked in one place and never by
+ * looking at a path prefix (`change-discipline.md` § One rail per concern).
+ *
+ * @param {*} from the reference as written
+ * @returns {boolean}
+ */
+function isPackageReference(from) {
+  return from !== null && typeof from === 'object' && typeof from.package === 'string' && from.package.length > 0;
+}
+
+/**
+ * The file a reference names, as a reader is told where to find it: the
+ * workspace-relative path, or the package-relative one. Every message about a
+ * reference goes through this, so a row that moved its fact from the workspace
+ * into the package does not leave a message pointing at the old owner.
+ *
+ * @param {*} from the reference as written
+ * @returns {string}
+ */
+function referenceOwner(from) {
+  if (isPackageReference(from)) return from.package;
+  if (from !== null && typeof from === 'object' && typeof from.path === 'string') return from.path;
+  throw new Error('[ManifestDiscovery] Reference names no file - referenceOwner() got '
+    + `${JSON.stringify(from)}. Fix: a from: reference names either a workspace "path" or a "package" file.`);
+}
+
+/** `**` matches any number of directories, `*` matches within one segment. */
+function globToRegExp(pattern) {
+  const segments = pattern.split('/');
+  let source = '^';
+  segments.forEach((segment, index) => {
+    const last = index === segments.length - 1;
+    if (segment === '**') {
+      source += last ? '.*' : '(?:[^/]+/)*';
+      return;
+    }
+    source += segment.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+    if (!last) source += '/';
+  });
+  return new RegExp(`${source}$`);
+}
+
+/**
+ * @param {string} relativePath path relative to the workspace root, `/`-separated
+ * @param {string[]} [patterns] the manifest's exclude patterns
+ * @returns {boolean}
+ */
+function isExcluded(relativePath, patterns) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return false;
+  return patterns.some((pattern) => globToRegExp(pattern).test(relativePath));
+}
+
+const listEntries = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Every file under `root` matching `pattern`, as workspace-relative paths.
+ *
+ * @param {string} root workspace root
+ * @param {string} pattern the manifest's discovery pattern
+ * @returns {string[]}
+ */
+function expandPattern(root, pattern) {
+  const segments = pattern.split('/');
+  const found = [];
+
+  const walk = (relativeDir, index) => {
+    const segment = segments[index];
+    const last = index === segments.length - 1;
+    const absoluteDir = relativeDir ? resolveWorkspacePath(root, relativeDir) : root;
+    const join = (name) => (relativeDir ? `${relativeDir}/${name}` : name);
+
+    if (segment === '**') {
+      walk(relativeDir, index + 1);
+      for (const entry of listEntries(absoluteDir)) {
+        if (!entry.isDirectory() || NEVER_WALKED.includes(entry.name)) continue;
+        walk(join(entry.name), index);
+      }
+      return;
+    }
+
+    if (segment.includes('*')) {
+      const matcher = globToRegExp(segment);
+      for (const entry of listEntries(absoluteDir)) {
+        if (!matcher.test(entry.name)) continue;
+        if (last && entry.isFile()) found.push(join(entry.name));
+        else if (!last && entry.isDirectory()) walk(join(entry.name), index + 1);
+      }
+      return;
+    }
+
+    const candidate = resolveWorkspacePath(root, join(segment));
+    if (last) {
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) found.push(join(segment));
+      return;
+    }
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) walk(join(segment), index + 1);
+  };
+
+  walk('', 0);
+  return found;
+}
+
+/**
+ * The directory a pattern starts from: its longest prefix carrying no wildcard.
+ *
+ * That directory is what has to EXIST before the pattern can answer anything.
+ * `api_biz/*/package.json` starts at `api_biz`, `api/infra/*/package.json`
+ * at `api/infra`, `api/shared/**/package.json` at `api/shared`. In a checkout
+ * that carries `api/` alone — CI's `git archive` export — the first is absent and
+ * the other two are not, and a check reading it must say NOT RUN rather than
+ * report the empty set as an answer (`automation-gates.md` §5).
+ *
+ * @param {string} pattern a workspace-relative discovery pattern
+ * @returns {string} the workspace-relative directory it starts from
+ */
+function rootOfPattern(pattern) {
+  const segments = pattern.split('/');
+  const wildcard = segments.findIndex((segment) => segment.includes('*'));
+  const directory = wildcard === -1 ? segments.slice(0, -1) : segments.slice(0, wildcard);
+  return directory.join('/');
+}
+
+/**
+ * The container a `<dir>/*&#47;<file>` pattern enumerates, so that a directory
+ * carrying no matching file can still be seen. A pattern of another shape has
+ * no container, and orphan detection over directories does not apply to it.
+ *
+ * @param {string} pattern
+ * @returns {string|null}
+ */
+function containerOf(pattern) {
+  const segments = pattern.split('/');
+  if (segments.length < 3) return null;
+  if (segments[1] !== '*') return null;
+  if (segments.includes('**')) return null;
+  return segments[0];
+}
+
+/**
+ * Read the file a `from:` reference points at. Nothing is interpreted here — the
+ * three resolvers below decide what the reference means.
+ *
+ * @param {{ from: {path: string}, workspaceRoot: string }} params
+ * @returns {string} the file's contents
+ */
+function readReferencedFile({ from, workspaceRoot }) {
+  if (!from || (typeof from.path !== 'string' && !isPackageReference(from))) {
+    throw new Error('[ManifestDiscovery] Row or discovery block has no "from" reference - the fact has an '
+      + 'owner and the manifest never copies it. Fix: add from { path, ... } naming the file that owns it, '
+      + 'or from { package, text: true } for a file this package carries.');
+  }
+
+  if (isPackageReference(from)) {
+    const packaged = path.join(PACKAGE_ROOT, ...from.package.split('/'));
+    try {
+      return fs.readFileSync(packaged, 'utf8');
+    } catch (cause) {
+      throw new Error(`[ManifestDiscovery] Packaged file not found - ${from.package} is missing from `
+        + `${PACKAGE_ROOT}, and this package is what owns it. `
+        + 'Fix: reinstall @onlineapps/conn-orch-validator; the file ships inside it.', { cause });
+    }
+  }
+
+  const file = resolveWorkspacePath(workspaceRoot, from.path);
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (cause) {
+    throw new Error(`[ManifestDiscovery] Referenced file not found - ${from.path} under ${workspaceRoot}. `
+      + 'Fix: run with --workspace pointing at the directory that holds api/ and api_biz/.', { cause });
+  }
+}
+
+/**
+ * The whole referenced file as one value: `{ path, text: true }`.
+ *
+ * The shape exists because not every SSOT is a JSON document. `api/.nvmrc`
+ * carries the platform Node major as its only line (confirmation
+ * `node-runtime-version` 003), and a row that needs that major references the
+ * file rather than restating the number.
+ *
+ * @param {{ from: {path: string, text: boolean}, workspaceRoot: string }} params
+ * @returns {string} the file's contents, trimmed
+ */
+function resolveFromValue({ from, workspaceRoot }) {
+  if (!from || from.text !== true) {
+    throw new Error('[ManifestDiscovery] Reference is not a text reference - resolveFromValue needs '
+      + `from { path, text: true } and got ${JSON.stringify(from)}. `
+      + 'Fix: use resolveFromReference for a list of names.');
+  }
+  return readReferencedFile({ from, workspaceRoot }).trim();
+}
+
+/**
+ * The node a `from.list` path points at, as the owner file writes it.
+ *
+ * @param {{ from: {path: string, list: string}, workspaceRoot: string }} params
+ * @returns {Array|object} the array or the object map the reference names
+ */
+function resolveFromMap({ from, workspaceRoot }) {
+  const raw = readReferencedFile({ from, workspaceRoot });
+
+  let document;
+  try {
+    document = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`[ManifestDiscovery] Referenced file is not valid JSON - ${from.path}. `
+      + 'Fix: repair the file; it is the SSOT this row reads.', { cause });
+  }
+
+  const node = from.list.split('.').reduce((current, key) => (current == null ? undefined : current[key]), document);
+  if (node === null || node === undefined || typeof node !== 'object') {
+    throw new Error(`[ManifestDiscovery] Referenced list not found - "${from.list}" in ${from.path}. `
+      + 'Fix: point the reference at the array or object that owns the names.');
+  }
+  return node;
+}
+
+/**
+ * Read the list a `from:` reference points at, and return the names it owns.
+ *
+ * Two shapes, because the two SSOTs are written differently and neither is going
+ * to be rewritten for the manifest's convenience:
+ *   - `{ path, list, key }`         — an array of objects; the name is `entry[key]`
+ *     (`api/config/services.json`, `businessServices.services[].directory`);
+ *   - `{ path, list, names: "keys" }` — an object map; the names ARE the keys
+ *     (`api/config/libraries.json`, `libraries`).
+ *
+ * @param {{ from: {path: string, list: string, key?: string, names?: string}, workspaceRoot: string }} params
+ * @returns {string[]}
+ */
+function resolveFromReference({ from, workspaceRoot }) {
+  const list = resolveFromMap({ from, workspaceRoot });
+
+  if (from.names === 'keys') {
+    if (Array.isArray(list)) {
+      throw new Error(`[ManifestDiscovery] Referenced list is an array, not a map - "${from.list}" in ${from.path} `
+        + 'was referenced with names: "keys". Fix: use { list, key } for an array of objects.');
+    }
+    return Object.keys(list);
+  }
+
+  if (!Array.isArray(list)) {
+    throw new Error(`[ManifestDiscovery] Referenced list is not an array - "${from.list}" in ${from.path}. `
+      + 'Fix: reference an object map with names: "keys", or point at the array that owns the names.');
+  }
+
+  // An entry that does not carry the key declares no bearer of this uniform, and
+  // that is a real shape of the SSOT rather than damage: `services.json` holds
+  // `evidence-service` with `enabled: false` and no `directory` (measured
+  // 2026-09-09), a service that exists as a plan and not as a repository. The
+  // reference reads the set of names the owner file DECLARES; a name it does not
+  // declare cannot bind a directory, and a directory nobody declares is exactly
+  // what U-ORPHAN reports. A key that IS there but is not a string is damage,
+  // and it stops the run rather than being coerced.
+  const names = [];
+  list.forEach((entry, index) => {
+    const value = entry == null ? undefined : entry[from.key];
+    if (value === undefined) return;
+    if (typeof value !== 'string') {
+      throw new Error(`[ManifestDiscovery] Referenced list entry has a non-string "${from.key}" - `
+        + `${from.list}[${index}] in ${from.path} carries ${JSON.stringify(value)}. `
+        + 'Fix: repair the SSOT; the reference reads names, not values of another kind.');
+    }
+    names.push(value);
+  });
+  return names;
+}
+
+/**
+ * @param {{ block: object, workspaceRoot: string }} params the discovery block and where to look
+ * @returns {{ bearers: Array<{name: string, relativeDir: string, dir: string, file: string}>,
+ *            excluded: string[],
+ *            orphans: Array<{name: string, relativeDir: string, dir: string, reason: string}> }}
+ */
+function discoverBearers({ block, workspaceRoot }) {
+  if (!block || typeof block.pattern !== 'string') {
+    throw new Error('[ManifestDiscovery] Discovery block needs a "pattern" - discoverBearers({ block }) got none. '
+      + 'Fix: state the pattern that finds the bearers of this uniform.');
+  }
+  if (typeof workspaceRoot !== 'string' || workspaceRoot.length === 0) {
+    throw new Error('[ManifestDiscovery] Workspace root is required - discoverBearers({ workspaceRoot }) got none. '
+      + 'Fix: resolve it first (resolveWorkspaceRoot) and report NOT RUN when it is unreachable.');
+  }
+
+  const matched = expandPattern(workspaceRoot, block.pattern);
+  const excluded = matched.filter((relative) => isExcluded(relative, block.exclude));
+  const bearers = matched
+    .filter((relative) => !excluded.includes(relative))
+    .map((relative) => {
+      const relativeDir = path.posix.dirname(relative);
+      return {
+        name: path.posix.basename(relativeDir),
+        relativeDir,
+        dir: resolveWorkspacePath(workspaceRoot, relativeDir),
+        file: relative
+      };
+    });
+
+  const orphans = [];
+  const container = containerOf(block.pattern);
+  if (container && block.from) {
+    const known = resolveFromReference({ from: block.from, workspaceRoot });
+    for (const entry of listEntries(resolveWorkspacePath(workspaceRoot, container))) {
+      if (!entry.isDirectory()) continue;
+      const relativeDir = `${container}/${entry.name}`;
+      if (isExcluded(relativeDir, block.exclude)) continue;
+
+      const isBearer = bearers.some((bearer) => bearer.relativeDir === relativeDir);
+      const reason = !isBearer
+        ? `matches no discovery pattern of this uniform (${block.pattern})`
+        : (known.includes(entry.name)
+          ? null
+          : `not declared in ${block.from.path} (${block.from.list}[].${block.from.key})`);
+
+      if (reason) {
+        orphans.push({
+          name: entry.name, relativeDir, dir: resolveWorkspacePath(workspaceRoot, relativeDir), reason
+        });
+      }
+    }
+  }
+
+  return { bearers, excluded, orphans };
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  isPackageReference,
+  referenceOwner,
+  discoverBearers,
+  resolveFromReference,
+  resolveFromValue,
+  resolveFromMap,
+  readReferencedFile,
+  expandPattern,
+  rootOfPattern,
+  containerOf,
+  isExcluded,
+  globToRegExp
+};

package/src/manifest/loadManifest.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * The packaged uniform manifest, read from disk.
+ *
+ * The manifest ships INSIDE this package, so the manifest version IS the
+ * validator version: a service pins the validator exactly (SSOT
+ * `api/config/libraries.json`, gate R6) and thereby pins the shape it is
+ * checked against. That is why no version field exists in the file — a field
+ * would be a second owner of the same fact.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-004
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Where the packaged manifest lives. The only default in this module family. */
+const DEFAULT_MANIFEST_PATH = path.join(__dirname, '..', '..', 'manifests', 'biz-service.manifest.json');
+
+/**
+ * Where the library uniform lives. It ships beside the service one, so the same
+ * pin decides both shapes (002 §12). Both paths belong to this module for the
+ * same reason: the manifest location is a fact about the package, not about the
+ * CLI — a boot step reads it without a CLI in sight.
+ */
+const LIBRARY_MANIFEST_PATH = path.join(__dirname, '..', '..', 'manifests', 'library.manifest.json');
+
+/**
+ * Read and parse a manifest. Nothing is validated here beyond "it is JSON" —
+ * the shape is `manifestShape.verifyManifestShape`, so a caller can inspect the
+ * violations instead of catching a throw.
+ *
+ * @param {string} manifestPath absolute path to the manifest file
+ * @returns {object} the parsed manifest
+ */
+function loadManifest(manifestPath) {
+  if (typeof manifestPath !== 'string' || manifestPath.length === 0) {
+    throw new Error('[Manifest] Manifest path is required - loadManifest(manifestPath) got '
+      + `${JSON.stringify(manifestPath)}. Fix: pass DEFAULT_MANIFEST_PATH or an explicit path.`);
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch (cause) {
+    throw new Error(`[Manifest] Manifest file not found - ${manifestPath}. `
+      + 'Fix: reinstall @onlineapps/conn-orch-validator; the manifest ships with the package.',
+    { cause });
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`[Manifest] Manifest is not valid JSON - ${manifestPath}. `
+      + 'Fix: repair the file; it is the machine-readable declaration of the uniform.',
+    { cause });
+  }
+}
+
+module.exports = { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH };