@onlineapps/conn-orch-validator 3.3.1 → 4.0.0

package/src/validators/ServiceStructureValidator.js

@@ -37,6 +37,184 @@ function hasConfigDir(root) {
          fs.existsSync(path.join(root, 'conn-config'));
 }
 
+
+// ---------------------------------------------------------------------------
+// v1.2 — business-error CONTRACT (DÁVKA 50)
+//
+// Owner decision: api/docs/governance/confirmations/business-error-contract.md
+// (20260829-1500-business-error-contract-001, CONFIRMED).
+//
+// v1.2 used to ask "does the service depend on @onlineapps/service-common and
+// import an error class FROM IT?". Both retired checks (`dep_service_common`,
+// `business_error_usage`) demanded the defeated hierarchy, so a service that had
+// already migrated to the wrapper's classes failed the gate for being correct.
+//
+// The question is now the contract, which survives the package moving: does the
+// service raise errors that the wrapper's ErrorMapper will translate — i.e. a
+// BusinessError family from @onlineapps/service-wrapper, or its own class
+// declaring the brand `onlineapps.businessError`?
+//
+// Scope is ANY file under src/, not "a handler or a src/lib/ module a handler
+// requires" — one rule, one sentence (automation-gates.md §1 requirement 2,
+// Simple). A static check cannot prove a `throw` reaches a handler anyway; it
+// can only see the declaration. The narrower rule was measured on 2026-08-29
+// and failed biz-converter and biz-ingest, both of which declare the contract in
+// src/lib/ and reach it through src/services/. Lead decision, same day.
+// ---------------------------------------------------------------------------
+
+/** Names exported by the wrapper's error module that satisfy the contract. */
+const WRAPPER_ERROR_NAMES = [
+  'BusinessError',
+  'ValidationError',
+  'NotFoundError',
+  'ConflictError',
+  'BusinessRuleError',
+  'AuthorizationError',
+  'InvalidEnvelopeError',
+  'BUSINESS_ERROR_BRAND'
+];
+
+/**
+ * The RETIRED hierarchy: everything @onlineapps/service-common exports from
+ * src/errors/BusinessError.js. Deliberately NOT every error class in that
+ * package — `ScopedRegistryError` belongs to the live scoped-registry helper and
+ * is not part of what DÁVKA 50 retires.
+ */
+const RETIRED_ERROR_NAMES = [
+  'BusinessError',
+  'NotFoundError',
+  'ValidationError',
+  'ConflictError',
+  'BusinessRuleError',
+  'AuthorizationError',
+  'ServiceUnavailableError',
+  'isBusinessError',
+  'ERROR_TYPES',
+  'businessErrorHandler'
+];
+
+const BUSINESS_ERROR_BRAND_TOKEN = 'onlineapps.businessError';
+
+function requirePattern(pkg) {
+  return new RegExp(`require\\(\\s*['"]${pkg.replace('/', '\\/')}['"]\\s*\\)`);
+}
+
+/** Collect every .js file under `dir`, as paths relative to `root`. */
+function listJsFiles(root, dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.isFile() && entry.name.endsWith('.js')) out.push(path.relative(root, p));
+    }
+  };
+  try { walk(dir); } catch { /* unreadable tree — callers treat as empty */ }
+  return out;
+}
+
+function readFile(root, rel) {
+  try { return fs.readFileSync(path.join(root, rel), 'utf-8'); } catch { return null; }
+}
+
+/**
+ * Names destructured from `require('<pkg>')` in `content`, across every such
+ * statement (single-line or multi-line).
+ *
+ * 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`
+ * destructuring sits directly above the service-common one.
+ *
+ * @returns {string[]}
+ */
+function destructuredFrom(content, pkg) {
+  const re = new RegExp(
+    `(?:const|let|var)\\s*\\{([^{}]*?)\\}\\s*=\\s*require\\(\\s*['"]${pkg.replace('/', '\\/')}['"]\\s*\\)`,
+    'g'
+  );
+  const names = [];
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    for (const raw of m[1].split(',')) {
+      const name = raw.split(':')[0].trim();
+      if (name) names.push(name);
+    }
+  }
+  return names;
+}
+
+/** Does this file satisfy the business-error contract? */
+function declaresBusinessErrorContract(content) {
+  if (content.includes(BUSINESS_ERROR_BRAND_TOKEN)) return true;
+  if (!requirePattern('@onlineapps/service-wrapper').test(content)) return false;
+  return destructuredFrom(content, '@onlineapps/service-wrapper')
+    .some(name => WRAPPER_ERROR_NAMES.includes(name));
+}
+
+/**
+ * v1.2 checks: the business-error contract is declared somewhere under src/, and
+ * the retired hierarchy is gone from src/ entirely.
+ *
+ * @param {string} root - Service root
+ * @returns {Array<{ passed: boolean, id: string, message: string, fix?: string }>}
+ */
+function businessErrorChecks(root) {
+  const srcFiles = listJsFiles(root, path.join(root, 'src'));
+
+  let contractFile = null;
+  for (const rel of srcFiles) {
+    const content = readFile(root, rel);
+    if (content && declaresBusinessErrorContract(content)) { contractFile = rel; break; }
+  }
+
+  const contractCheck = contractFile
+    ? {
+      passed: true,
+      id: 'business_error_contract',
+      message: `Business-error contract declared in ${contractFile}`
+    }
+    : {
+      passed: false,
+      id: 'business_error_contract',
+      message: '[ServiceStructureValidator] no business-error contract declared - ' +
+        'nothing under src/ imports a BusinessError family from @onlineapps/service-wrapper ' +
+        'or declares the brand ' + BUSINESS_ERROR_BRAND_TOKEN,
+      fix: 'Throw a contract-carrying error: ' +
+        "const { ValidationError } = require('@onlineapps/service-wrapper'); " +
+        `— or declare Symbol.for('${BUSINESS_ERROR_BRAND_TOKEN}') on the service's own error class.`
+    };
+
+  const offenders = [];
+  for (const rel of listJsFiles(root, path.join(root, 'src'))) {
+    const content = readFile(root, rel);
+    if (!content) continue;
+    const names = destructuredFrom(content, '@onlineapps/service-common')
+      .filter(name => RETIRED_ERROR_NAMES.includes(name));
+    if (names.length > 0) offenders.push({ file: rel, names });
+  }
+
+  const retiredCheck = offenders.length === 0
+    ? {
+      passed: true,
+      id: 'no_retired_error_hierarchy',
+      message: 'No @onlineapps/service-common error-hierarchy import under src/'
+    }
+    : {
+      passed: false,
+      id: 'no_retired_error_hierarchy',
+      message: '[ServiceStructureValidator] retired error hierarchy imported from @onlineapps/service-common - ' +
+        offenders.map(o => `${o.file} imports ${o.names.join(', ')}`).join('; '),
+      fix: offenders
+        .map(o => `Replace in ${o.file} with: const { ${o.names.join(', ')} } = require('@onlineapps/service-wrapper');`)
+        .join(' ')
+    };
+
+  return [contractCheck, retiredCheck];
+}
+
 const STANDARD_LEVELS = [
   {
     level: 'v1.0',
@@ -50,7 +228,9 @@ const STANDARD_LEVELS = [
       results.push({ passed: hasConfigDir(root), id: 'dir_conn_config', message: 'config/service/ or conn-config/ directory' });
       results.push({ passed: has('src'), id: 'dir_src', message: 'src/ directory' });
       results.push({ passed: has('tests'), id: 'dir_tests', message: 'tests/ directory' });
-      results.push({ passed: has('src/app.js'), id: 'file_app', message: 'src/app.js' });
+      // ADR 0005: src/handlers/ replaces src/app.js. Flat handlers/ or
+      // handlers/v3/ subdir are both valid canonical shapes.
+      results.push({ passed: has('src/handlers'), id: 'dir_handlers', message: 'src/handlers/ (v3 handler modules)' });
       results.push({ passed: has('index.js'), id: 'file_index', message: 'index.js entry point' });
 
       const configRaw = readConfigFile(root, 'config.json');
@@ -58,10 +238,11 @@ const STANDARD_LEVELS = [
       if (configRaw) {
         try {
           const cfg = JSON.parse(configRaw);
-          configValid = !!(cfg.service?.name && cfg.service?.port);
+          // ADR 0005: service.port not required post zero-HTTP. Just name.
+          configValid = !!cfg.service?.name;
         } catch { /* invalid JSON */ }
       }
-      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name + service.port' });
+      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name' });
 
       const opsRaw = readConfigFile(root, 'operations.json');
       let opsValid = false;
@@ -108,24 +289,35 @@ const STANDARD_LEVELS = [
     level: 'v1.2',
     name: 'Business Error Handling Standard',
     since: '2026-03-24',
+    checks: (root) => businessErrorChecks(root)
+  },
+  {
+    level: 'v1.3',
+    name: 'Zero-HTTP Shape (ADR 0005)',
+    since: '2026-08-17',
     checks: (root) => {
+      const has = (p) => fs.existsSync(path.join(root, p));
       const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
 
+      // v1.3 asserts that F6/A2 cleanup landed: no dead Express surface.
+      const noAppJs = !has('src/app.js');
+      const noRoutesDir = !has('src/routes');
+      const noMiddlewaresDir = !has('src/middlewares');
+
       const pkgRaw = read('package.json');
-      let hasServiceCommon = false;
+      let noExpressDep = true;
       if (pkgRaw) {
         try {
           const pkg = JSON.parse(pkgRaw);
-          hasServiceCommon = !!pkg.dependencies?.['@onlineapps/service-common'];
-        } catch { /* invalid JSON */ }
+          noExpressDep = !pkg.dependencies?.express;
+        } catch { /* invalid JSON — separate check catches it */ }
       }
 
-      const appContent = read('src/app.js') || '';
-      const hasErrorMiddleware = appContent.includes('businessErrorHandler');
-
       return [
-        { passed: hasServiceCommon, id: 'dep_service_common', message: '@onlineapps/service-common dependency' },
-        { passed: hasErrorMiddleware, id: 'error_middleware', message: 'businessErrorHandler middleware in src/app.js' }
+        { passed: noAppJs, id: 'no_app_js', message: 'src/app.js absent (retired Express dispatch surface)' },
+        { passed: noRoutesDir, id: 'no_routes_dir', message: 'src/routes/ absent (dead HTTP route mounts)' },
+        { passed: noMiddlewaresDir, id: 'no_middlewares_dir', message: 'src/middlewares/ absent (dead Express middleware)' },
+        { passed: noExpressDep, id: 'no_express_dep', message: 'express not in package.json dependencies' }
       ];
     }
   }
@@ -218,12 +410,18 @@ class ServiceStructureValidator {
     if (nextLevel) {
       const failing = nextLevel.checks.filter(c => !c.passed);
       for (const check of failing) {
+        // A check that carries its own `fix` has already written a
+        // `[Context] Problem - Expected/Fix` message naming the offending file;
+        // wrapping it in "missing …" would only bury the finding.
         this.warnings.push({
           type: 'STANDARD_LEVEL_GAP',
           level: nextLevel.level,
           check: check.id,
-          message: `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
-          fix: `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/biz/60-templates/service-template.md`
+          message: check.fix
+            ? `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`
         });
       }
     }
@@ -411,7 +609,8 @@ class ServiceStructureValidator {
 
   /**
    * Validate operations.json structure (v3 — handler registry dispatch).
-   * v3 schema per biz-service-invocation-model.md §5.3.
+   *
+   * @see api/docs/biz/30-operations/schema-v3.md § File shape
    */
   validateOperationsStructure(operations) {
     if (!operations.operations) {
@@ -419,7 +618,7 @@ class ServiceStructureValidator {
         type: 'INVALID_OPERATIONS_STRUCTURE',
         path: 'config/service/operations.json',
         message: 'operations.json must have "operations" key',
-        fix: 'Wrap operations in {"operations": {...}}. See: biz-service-invocation-model.md §5.3'
+        fix: 'Wrap operations in {"operations": {...}} in config/service/operations.json'
       });
       return;
     }
@@ -442,7 +641,7 @@ class ServiceStructureValidator {
         field: 'schema_version',
         value: operations.schema_version,
         message: `operations.json schema_version is "${operations.schema_version}" — expected "3.0"`,
-        fix: 'Update schema_version to "3.0" (RFC §5.3)'
+        fix: 'Set schema_version to "3.0" in config/service/operations.json'
       });
     }
 
@@ -464,6 +663,8 @@ class ServiceStructureValidator {
   /**
    * 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'];
@@ -476,7 +677,7 @@ class ServiceStructureValidator {
           operation: name,
           field,
           message: `Operation "${name}" missing required field: ${field}`,
-          fix: `Add "${field}" to operation "${name}" (v3 schema — RFC §5.3)`
+          fix: `Add "${field}" to operation "${name}" in config/service/operations.json`
         });
       }
     }
@@ -517,7 +718,7 @@ class ServiceStructureValidator {
           field: forbidden,
           value: spec[forbidden],
           message: `Operation "${name}" has retired v2 field "${forbidden}" — not allowed in v3 schema`,
-          fix: `Remove "${forbidden}" — v3 dispatches via handler registry (RFC §5.3, §5.9)`
+          fix: `Remove "${forbidden}" from operation "${name}" in config/service/operations.json — v3 dispatches via the handler registry, not by URL`
         });
       }
     }
@@ -594,39 +795,45 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate source code structure
+   * Validate source code structure.
+   *
+   * ADR 0005 (2026-08-17): biz containers have zero HTTP surface —
+   * no Express, no `src/app.js`, no per-op HTTP routes. The v3
+   * handler-registry model instead requires `src/handlers/` (flat
+   * or `handlers/v3/` subdir — both variants of the canonical
+   * shape) with `handler` refs from `operations.json` resolvable
+   * to real exports.
    */
   validateSourceStructure() {
-    const appPath = path.join(this.serviceRoot, 'src/app.js');
-    if (!fs.existsSync(appPath)) {
+    // Post-ADR-0005 hard requirement: at least one handler module
+    // (flat or under v3/) must exist. HandlerRegistry.validate() at
+    // bootstrap time enforces per-op resolution; here we just ensure
+    // the directory itself is present so the service has something
+    // to dispatch to.
+    const handlersFlat = path.join(this.serviceRoot, 'src/handlers');
+    if (!fs.existsSync(handlersFlat)) {
       this.errors.push({
-        type: 'MISSING_APP',
-        path: 'src/app.js',
-        message: 'Express application missing: src/app.js',
-        fix: 'Create src/app.js with Express app. See: /docs/biz/60-templates/service-template.md'
+        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'
       });
     } else {
-      this.info.push('✓ Found src/app.js');
+      this.info.push('✓ Found src/handlers/');
+    }
 
-      try {
-        const appContent = fs.readFileSync(appPath, 'utf-8');
-        if (appContent.includes('businessErrorHandler')) {
-          this.info.push('✓ businessErrorHandler middleware registered');
-        } else {
-          this.warnings.push({
-            type: 'MISSING_ERROR_MIDDLEWARE',
-            path: 'src/app.js',
-            message: 'businessErrorHandler middleware not found in src/app.js',
-            fix: 'Register businessErrorHandler from @onlineapps/service-common as Express error middleware. See: /docs/standards/ERROR_HANDLING.md'
-          });
-        }
-      } catch (readError) {
-        this.warnings.push({
-          type: 'UNREADABLE_APP',
-          path: 'src/app.js',
-          message: `Could not read src/app.js: ${readError.message}`
-        });
-      }
+    // src/app.js is ANTI-PATTERN post-ADR 0005 (dead Express surface).
+    // Warn if present so authors of new services notice they should
+    // remove it; existing services scheduled to be cleaned up via the
+    // Fáze F6 pass.
+    const appPath = path.join(this.serviceRoot, 'src/app.js');
+    if (fs.existsSync(appPath)) {
+      this.warnings.push({
+        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'
+      });
     }
 
     const indexPath = path.join(this.serviceRoot, 'index.js');

package/src/config.js

@@ -1,32 +0,0 @@
-'use strict';
-
-/**
- * Runtime configuration schema for @onlineapps/conn-orch-validator.
- *
- * Uses @onlineapps/runtime-config for unified priority:
- * 1. Explicit config (passed to ValidationOrchestrator/readiness options)
- * 2. Environment variable
- * 3. Module-owned defaults (none for topology)
- *
- * IMPORTANT: Integration test topology is FAIL-FAST (no defaults).
- */
-
-const { createRuntimeConfig } = require('@onlineapps/runtime-config');
-const DEFAULTS = require('./defaults');
-
-const runtimeCfg = createRuntimeConfig({
-  defaults: DEFAULTS,
-  schema: {
-    serviceUrl: { env: 'TEST_SERVICE_URL', required: true },
-    mqUrl: { env: 'TEST_MQ_URL', required: true },
-    registryUrl: { env: 'TEST_REGISTRY_URL', required: true },
-    storageUrl: { env: 'TEST_STORAGE_URL', required: true },
-  }
-});
-
-module.exports = runtimeCfg;
-
-
-
-
-

package/src/defaults.js

@@ -1,11 +0,0 @@
-'use strict';
-
-/**
- * Module-owned defaults for @onlineapps/conn-orch-validator.
- *
- * NOTE: Integration test topology (URLs) is FAIL-FAST and has NO defaults.
- */
-
-module.exports = {};
-
-