@onlineapps/conn-orch-validator 12.1.1 → 13.0.0

package/src/utils/yamlTopLevel.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * Which top-level key of a YAML document owns a line — the ONE definition of
+ * that question in this package.
+ *
+ * Two modules ask it, for two different purposes, and both used to answer it
+ * themselves: `src/sync/serviceTemplate.js` (which keys the platform block
+ * declares, and whose spans the sync replaces) and `src/utils/deployContract.js`
+ * (which JOB a `git reset --hard` sits in, so R2 can refuse a guard standing in
+ * another one). Two regexes for one fact, with two tolerances and no note that
+ * they differed: `.claude/rules/change-discipline.md` § One rail per concern.
+ *
+ * Column 0 is the whole rule, and it is enough for the files this reads: a
+ * `.gitlab-ci.yml` job is a top-level key and everything it owns is indented
+ * under it. Text in, positions out — nothing is re-serialized, so a comment and
+ * a quoting style survive (`.claude/rules/automation-gates.md` §1 requirement 3).
+ *
+ * The two readings differ in ONE thing, and it is a named predicate over this
+ * one regex rather than a second regex:
+ *
+ *   `topLevelKeys`            every key, hidden ones included. A hidden key
+ *                             (`.oa-uniform:`) is a declaration GitLab never runs
+ *                             as a job, but it is still a key, and a reader
+ *                             asking "which key is this line under" has to place
+ *                             it somewhere truthful.
+ *   `rewritableTopLevelKeys`  hidden keys dropped. This is the reading a
+ *                             GENERATOR may act on: `replaceTopLevelKeys`
+ *                             DELETES the spans it is given, and a hidden key a
+ *                             service wrote itself is not the platform's to
+ *                             delete (tests/unit/manifestCiBlock.test.js, G-CI
+ *                             over a pipeline that predates the markers).
+ */
+
+/**
+ * A top-level mapping key: a line that starts in column 0 and ends its key with
+ * a colon. The leading dot is optional, because a hidden key is a key.
+ *
+ * The key's characters are what excludes the lines that are not keys: a list
+ * item (`- if: …`), a comment (`# build:`), an indented key, and anything with a
+ * space in it cannot match, so no `.gitlab-ci.yml` construct is mistaken for one.
+ */
+const TOP_LEVEL_KEY = /^(\.?[A-Za-z_][A-Za-z0-9_.-]*):/gm;
+
+/** What `topLevelKeyAt` answers for text that precedes the first key. */
+const NO_TOP_LEVEL_KEY = '(before the first key)';
+
+/** True for a hidden key — GitLab runs nothing whose name starts with a dot. */
+function isHiddenKey(name) {
+  return name.startsWith('.');
+}
+
+/**
+ * Every top-level key of the document, in file order.
+ *
+ * @param {string} text the document
+ * @returns {Array<{name: string, at: number, line: number}>} `at` is the offset
+ *   of the key in `text`, `line` its 0-based index in `text.split('\n')`.
+ */
+function topLevelKeys(text) {
+  if (typeof text !== 'string') {
+    throw new Error('[YamlTopLevel] Missing document text - Expected the YAML as a string. '
+      + 'Fix: pass the file contents, not a path and not an array of lines.');
+  }
+  const keys = [];
+  TOP_LEVEL_KEY.lastIndex = 0;
+  let scanned = 0;
+  let line = 0;
+  let hit;
+  while ((hit = TOP_LEVEL_KEY.exec(text)) !== null) {
+    for (let i = scanned; i < hit.index; i += 1) if (text[i] === '\n') line += 1;
+    scanned = hit.index;
+    keys.push({ name: hit[1], at: hit.index, line });
+  }
+  return keys;
+}
+
+/**
+ * The top-level keys a generator may rewrite: every key except the hidden ones.
+ *
+ * @param {string} text the document
+ * @returns {Array<{name: string, at: number, line: number}>}
+ */
+function rewritableTopLevelKeys(text) {
+  return topLevelKeys(text).filter((key) => !isHiddenKey(key.name));
+}
+
+/**
+ * The key an offset sits under — for a command in a `.gitlab-ci.yml`, the job
+ * whose shell runs it.
+ *
+ * @param {Array<{name: string, at: number}>} keys from `topLevelKeys`
+ * @param {number} offset an offset into the same document
+ * @returns {string} the key's name, or `NO_TOP_LEVEL_KEY`
+ */
+function topLevelKeyAt(keys, offset) {
+  let name = NO_TOP_LEVEL_KEY;
+  for (const key of keys) {
+    if (key.at > offset) break;
+    name = key.name;
+  }
+  return name;
+}
+
+module.exports = { topLevelKeys, rewritableTopLevelKeys, topLevelKeyAt, NO_TOP_LEVEL_KEY, isHiddenKey };

package/src/validators/ServiceStructureValidator.js

@@ -17,7 +17,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const { HANDLER_REF_PATTERN } = require('../utils/handlerRef');
+const { operationsRuleRecords } = require('../utils/operationsRules');
+const { operationsDocumentFindings, documentFindingRecord } = require('../utils/operationsDocumentRules');
 
 /**
  * Read a configuration file from the ONE place a service may keep it:
@@ -130,7 +131,7 @@ function readFile(root, rel) {
  * The body is `[^{}]*?`, NOT `[\s\S]*?`: a lazy any-character body starts at the
  * nearest preceding `const {` and swallows whole lines to reach the right
  * `require`, which dropped the first imported name. Measured on
- * `api_biz/meta/src/handlers/persons.js:10-11`, where an unrelated `models`
+ * the imports of `api_biz/meta/src/handlers/persons.js`, where an unrelated `models`
  * destructuring sits directly above the service-common one.
  *
  * @returns {string[]}
@@ -279,7 +280,7 @@ const STANDARD_LEVELS = [
   // infrastructureGate, health, validation, mq, registry, monitoring, state,
   // secrets and heartbeat — not tenantContext; `createTenantContextMiddleware`
   // was deleted on 2026-09-05 together with the runtime-defaults key
-  // (docs/governance/confirmations/wrapper-tenant-middleware.md). A
+  // (api/docs/governance/confirmations/wrapper-tenant-middleware.md). A
   // level enforcing a dead declaration is the false guarantee automation-gates.md
   // §5 names, so the level is GONE rather than emptied — an empty level would
   // pass for every service while asserting nothing.
@@ -423,7 +424,7 @@ class ServiceStructureValidator {
             ? `Standard ${nextLevel.level} (${nextLevel.name}): ${check.message}`
             : `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
           fix: check.fix
-            || `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/biz/60-templates/service-template.md`
+            || `Implement ${check.message} to reach standard ${nextLevel.level}. See api/docs/biz/60-templates/service-template.md`
         });
       }
     }
@@ -510,7 +511,7 @@ class ServiceStructureValidator {
         type: 'MISSING_CONFIG',
         path: 'config/service/config.json',
         message: 'Service configuration missing: config/service/config.json',
-        fix: 'Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md'
+        fix: 'Create config.json with service metadata. See: api/docs/biz/60-templates/service-template.md'
       });
     } else {
       try {
@@ -533,7 +534,7 @@ class ServiceStructureValidator {
         type: 'MISSING_OPERATIONS',
         path: 'config/service/operations.json',
         message: 'Operations specification missing: config/service/operations.json',
-        fix: 'Create operations.json. See: /docs/biz/30-operations/schema-v3.md'
+        fix: 'Create operations.json. See: api/docs/biz/30-operations/schema-v3.md'
       });
     } else {
       try {
@@ -552,40 +553,42 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate config.json structure
-   * Note: service.version is now read from package.json (Single Source of Truth)
+   * What step 1 still says about `config.json`: nothing about WHICH KEYS it
+   * carries. That question has one owner, the manifest row `C-SERVICE`, and
+   * this step is the structural half — the file is there, it reads, it parses.
+   *
+   * Until d.726 a `requiredFields = ['service.name']` lived here, with a
+   * message and a fix of its own, beside a row that demands the same key and
+   * two more. The four questions the removal has to answer
+   * (`.claude/rules/change-discipline.md` § Removing something removes its
+   * declaration):
+   *
+   *   how it came to be — step 1 predates the manifest. When it was written it
+   *   WAS the only reader of `config.json`, so the key list had to live
+   *   somewhere and this was the only somewhere there was.
+   *
+   *   which part of the concept carried it — service shape, and that part still
+   *   stands. What moved is where it is declared: confirmation
+   *   `biz-service-manifest` §2 makes the manifest the place a rule of service
+   *   shape is written, with an id, an owner, a severity, a fix and a doc
+   *   pointer. d.465 already moved boot step 2 onto it.
+   *
+   *   why there were two — nobody removed the first when the second arrived.
+   *
+   *   is the replacement MORE conceptual — yes, and measurably so. `C-SERVICE`
+   *   demands three keys, not one, and each because grep found the reader that
+   *   fails without it (`manifest/checks/serviceConfig.js`,
+   *   REQUIRED_SERVICE_KEYS). The list here had one key and no reader named.
+   *
+   * And the two rails did not merely overlap: measured d.726, step 1 failing on
+   * `name` FAIL-FASTED the orchestrator, so step 2 never ran and a missing
+   * `workspaceScoped` — which the wrapper refuses to boot without — was not
+   * reported at all until `name` was fixed. The narrower rail was hiding the
+   * conceptual one.
+   *
+   * Note: service.version is read from package.json (Single Source of Truth).
    */
   validateConfigStructure(config) {
-    // Required fields (version comes from package.json, not config.json).
-    //
-    // `service.port` was required here until 2026-08-30. ADR 0005 removed the
-    // HTTP surface from biz containers, so nothing listens and the number has
-    // no consumer — requiring it forced every repo to keep a declaration that
-    // means nothing, which is what `change-discipline.md` § "Removing something
-    // removes its declaration" exists to prevent. Absence is now correct;
-    // presence is reported below as a warning, never as a failure.
-    const requiredFields = [
-      'service.name'
-    ];
-
-    for (const field of requiredFields) {
-      const parts = field.split('.');
-      let value = config;
-      for (const part of parts) {
-        value = value?.[part];
-      }
-
-      if (!value) {
-        this.errors.push({
-          type: 'MISSING_CONFIG_FIELD',
-          path: 'config/service/config.json',
-          field: field,
-          message: `Required field missing in config.json: ${field}`,
-          fix: `Add "${field}" to config.json`
-        });
-      }
-    }
-
     // A port that is still declared is a stale declaration, not a failure. Say
     // so out loud: `automation-gates.md` §5 — a check that stays silent about a
     // thing it can see is a false guarantee, and the eight services measured in
@@ -638,118 +641,19 @@ class ServiceStructureValidator {
   /**
    * Validate operations.json structure (v3 — handler registry dispatch).
    *
+   * Nothing about `operations.json` is decided in this method. The rules about
+   * the DOCUMENT (`schema_version`, an operations map with nothing in it) are
+   * `src/utils/operationsDocumentRules.js`; the rules about each OPERATION are
+   * `src/utils/operationsRules.js`, which asks
+   * `@onlineapps/service-validator-core` — the mirror of what the Registry
+   * refuses a registration on. Both used to be restated here, and both said
+   * something different from what the other rails said (d.465, d.465b).
+   *
    * @see api/docs/biz/30-operations/schema-v3.md § File shape
    */
   validateOperationsStructure(operations) {
-    if (!operations.operations) {
-      this.errors.push({
-        type: 'INVALID_OPERATIONS_STRUCTURE',
-        path: 'config/service/operations.json',
-        message: 'operations.json must have "operations" key',
-        fix: 'Wrap operations in {"operations": {...}} in config/service/operations.json'
-      });
-      return;
-    }
-
-    const ops = operations.operations;
-    if (typeof ops !== 'object' || Array.isArray(ops)) {
-      this.errors.push({
-        type: 'INVALID_OPERATIONS_TYPE',
-        path: 'config/service/operations.json',
-        message: 'operations must be an object',
-        fix: 'operations should be key-value pairs: {"operation-name": {...}}'
-      });
-      return;
-    }
-
-    if (operations.schema_version && operations.schema_version !== '3.0') {
-      this.warnings.push({
-        type: 'SCHEMA_VERSION_MISMATCH',
-        path: 'config/service/operations.json',
-        field: 'schema_version',
-        value: operations.schema_version,
-        message: `operations.json schema_version is "${operations.schema_version}" — expected "3.0"`,
-        fix: 'Set schema_version to "3.0" in config/service/operations.json'
-      });
-    }
-
-    if (Object.keys(ops).length === 0) {
-      this.warnings.push({
-        type: 'NO_OPERATIONS',
-        path: 'config/service/operations.json',
-        message: 'No operations defined',
-        fix: 'Add at least one operation to operations.json'
-      });
-      return;
-    }
-
-    for (const [operationName, operationSpec] of Object.entries(ops)) {
-      this.validateOperation(operationName, operationSpec);
-    }
-  }
-
-  /**
-   * Validate single operation structure (v3).
-   * Required: handler, bundle_scope. Forbidden (v2): endpoint, method, path.
-   *
-   * @see api/docs/biz/30-operations/schema-v3.md § Per-operation keys
-   */
-  validateOperation(name, spec) {
-    const requiredFields = ['handler', 'bundle_scope'];
-
-    for (const field of requiredFields) {
-      if (!spec[field]) {
-        this.errors.push({
-          type: 'MISSING_OPERATION_FIELD',
-          path: 'config/service/operations.json',
-          operation: name,
-          field,
-          message: `Operation "${name}" missing required field: ${field}`,
-          fix: `Add "${field}" to operation "${name}" in config/service/operations.json`
-        });
-      }
-    }
-
-    if (spec.handler && !HANDLER_REF_PATTERN.test(spec.handler)) {
-      this.errors.push({
-        type: 'INVALID_HANDLER_REF',
-        path: 'config/service/operations.json',
-        operation: name,
-        field: 'handler',
-        value: spec.handler,
-        message: `Handler must be in form 'handlers/<path>#<exportName>': ${spec.handler}`,
-        fix: `Change handler to form 'handlers/v3/<file>#<exportName>'`
-      });
-    }
-
-    const validScopes = ['platform', 'tenant', 'workspace'];
-    if (spec.bundle_scope && !validScopes.includes(spec.bundle_scope)) {
-      this.errors.push({
-        type: 'INVALID_BUNDLE_SCOPE',
-        path: 'config/service/operations.json',
-        operation: name,
-        field: 'bundle_scope',
-        value: spec.bundle_scope,
-        message: `Invalid bundle_scope: ${spec.bundle_scope}`,
-        fix: `Use one of: ${validScopes.join(', ')}`
-      });
-    }
-
-    // Reject v2 HTTP-routing fields (clean break per ARCHITECTURE_PRINCIPLES.md §11).
-    const forbiddenV2Fields = ['endpoint', 'method', 'path'];
-    for (const forbidden of forbiddenV2Fields) {
-      if (forbidden in spec) {
-        this.errors.push({
-          type: 'V2_FIELD_PRESENT',
-          path: 'config/service/operations.json',
-          operation: name,
-          field: forbidden,
-          value: spec[forbidden],
-          message: `Operation "${name}" has retired v2 field "${forbidden}" — not allowed in v3 schema`,
-          fix: `Remove "${forbidden}" from operation "${name}" in config/service/operations.json — v3 dispatches via the handler registry, not by URL`
-        });
-      }
-    }
+    this.errors.push(...operationsDocumentFindings(operations).map(documentFindingRecord));
+    this.errors.push(...operationsRuleRecords(operations && operations.operations).records);
   }
 
   /**
@@ -791,11 +695,22 @@ class ServiceStructureValidator {
         }
       }
 
-      // Check for @onlineapps dependencies
+      // The @onlineapps packages a biz service cannot be without: the wrapper it
+      // boots through, and this validator, which its own gate runs.
+      //
+      // `@onlineapps/service-common` was a third entry and is not one any more.
+      // The v1.2 block at the top of this file records the decision it
+      // contradicted: `dep_service_common` and `business_error_usage` were
+      // RETIRED because the error hierarchy moved to the wrapper — so this file
+      // refused an import from that package up there and advised installing it
+      // down here. It stays a live package, which makes it a dependency a
+      // service adds when it needs what that package exports, never a
+      // recommendation for every service. See api/docs/biz/RETIRED-VOCABULARY.md,
+      // and tests/unit/serviceStructureRecommendedDeps.test.js for what was
+      // measured.
       const requiredDeps = [
         '@onlineapps/service-wrapper',
-        '@onlineapps/conn-orch-validator',
-        '@onlineapps/service-common'
+        '@onlineapps/conn-orch-validator'
       ];
 
       for (const dep of requiredDeps) {
@@ -844,7 +759,7 @@ class ServiceStructureValidator {
         type: 'MISSING_HANDLERS',
         path: 'src/handlers',
         message: 'Handlers directory missing: src/handlers/',
-        fix: 'Create src/handlers/ with at least one v3 handler module. See: /docs/biz/60-templates/service-template.md'
+        fix: 'Create src/handlers/ with at least one v3 handler module. See: api/docs/biz/60-templates/service-template.md'
       });
     } else {
       this.info.push('✓ Found src/handlers/');
@@ -860,7 +775,7 @@ class ServiceStructureValidator {
         type: 'LEGACY_APP_JS',
         path: 'src/app.js',
         message: 'src/app.js is dead code post-ADR 0005 (bootstrap no longer reads it)',
-        fix: 'Delete src/app.js; move any residual middleware into the wrapper adapter. See: /docs/biz/80-decisions/0005-no-http-in-biz-containers.md'
+        fix: 'Delete src/app.js; move any residual middleware into the wrapper adapter. See: api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md'
       });
     }