@onlineapps/conn-orch-validator 2.0.33 → 3.0.0

package/src/index.js

@@ -1,17 +1,25 @@
 'use strict';
 
-// Mock infrastructure components (load first - no dependencies)
+/**
+ * @module @onlineapps/conn-orch-validator
+ * @description Service validation framework using the operations.json contract.
+ *
+ * Production entry point: {@link ValidationOrchestrator} (6-step pre-validation
+ * driven by operations.json — OpenAPI path iteration is NOT supported).
+ *
+ * @see /api/docs/standards/operations-registry-contract.md §3 (operations.json)
+ * @see /api/docs/standards/validation-probe-contract.md (validation probes)
+ * @see /api/docs/architecture/validator.md (validator architecture)
+ */
+
 const MockMQClient = require('./mocks/MockMQClient');
 const MockRegistry = require('./mocks/MockRegistry');
 const MockStorage = require('./mocks/MockStorage');
 
-// Base test utilities (no circular dependencies)
-const ServiceValidator = require('./ServiceValidator');
 const CookbookTestUtils = require('./CookbookTestUtils');
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
 
-// Test runners (depend on mocks)
 let CookbookTestRunner;
 try {
   CookbookTestRunner = require('./CookbookTestRunner');
@@ -20,43 +28,29 @@ try {
 }
 const WorkflowTestRunner = require('./WorkflowTestRunner');
 
-// Orchestrators (depend on validators and runners)
 const ServiceReadinessValidator = require('./ServiceReadinessValidator');
-const TestOrchestrator = require('./TestOrchestrator');
-const ServiceTestHarness = require('./ServiceTestHarness');
 const ValidationOrchestrator = require('./ValidationOrchestrator');
 
-// Test helpers (generic test suite creators)
 const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
 const { createPreValidationTests } = require('./helpers/createPreValidationTests');
 
-// Export all components with getters to avoid circular dependency issues
 module.exports = {
-  // Mocks
   get MockMQClient() { return MockMQClient; },
   get MockRegistry() { return MockRegistry; },
   get MockStorage() { return MockStorage; },
 
-  // Test utilities
-  get ServiceTestHarness() { return ServiceTestHarness; },
-  get ServiceValidator() { return ServiceValidator; },
   get WorkflowTestRunner() { return WorkflowTestRunner; },
   get CookbookTestUtils() { return CookbookTestUtils; },
   get ServiceReadinessValidator() { return ServiceReadinessValidator; },
-  get TestOrchestrator() { return TestOrchestrator; },
   get CookbookTestRunner() { return CookbookTestRunner; },
   get ValidationProofGenerator() { return ValidationProofGenerator; },
   get ServiceStructureValidator() { return ServiceStructureValidator; },
   get ValidationOrchestrator() { return ValidationOrchestrator; },
 
-  // Test helpers (NEW - generic test suite creators)
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get createPreValidationTests() { return createPreValidationTests; },
 
-  // Convenience factory functions
-  createTestHarness: (options) => new ServiceTestHarness(options),
-  createValidator: (options) => new ServiceValidator(options),
   createMockMQ: () => new MockMQClient(),
   createMockRegistry: () => new MockRegistry(),
   createMockStorage: () => new MockStorage()
-};
+};

package/src/validators/ServiceStructureValidator.js

@@ -410,7 +410,8 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate operations.json structure
+   * Validate operations.json structure (v3 — handler registry dispatch).
+   * v3 schema per biz-service-invocation-model.md §5.3.
    */
   validateOperationsStructure(operations) {
     if (!operations.operations) {
@@ -418,7 +419,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: /docs/standards/OPERATIONS.md'
+        fix: 'Wrap operations in {"operations": {...}}. See: biz-service-invocation-model.md §5.3'
       });
       return;
     }
@@ -434,6 +435,17 @@ class ServiceStructureValidator {
       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: 'Update schema_version to "3.0" (RFC §5.3)'
+      });
+    }
+
     if (Object.keys(ops).length === 0) {
       this.warnings.push({
         type: 'NO_OPERATIONS',
@@ -444,17 +456,17 @@ class ServiceStructureValidator {
       return;
     }
 
-    // Validate each operation
     for (const [operationName, operationSpec] of Object.entries(ops)) {
       this.validateOperation(operationName, operationSpec);
     }
   }
 
   /**
-   * Validate single operation structure
+   * Validate single operation structure (v3).
+   * Required: handler, bundle_scope. Forbidden (v2): endpoint, method, path.
    */
   validateOperation(name, spec) {
-    const requiredFields = ['endpoint', 'method'];
+    const requiredFields = ['handler', 'bundle_scope'];
 
     for (const field of requiredFields) {
       if (!spec[field]) {
@@ -462,39 +474,53 @@ class ServiceStructureValidator {
           type: 'MISSING_OPERATION_FIELD',
           path: 'config/service/operations.json',
           operation: name,
-          field: field,
+          field,
           message: `Operation "${name}" missing required field: ${field}`,
-          fix: `Add "${field}" to operation "${name}"`
+          fix: `Add "${field}" to operation "${name}" (v3 schema — RFC §5.3)`
         });
       }
     }
 
-    // Validate endpoint format
-    if (spec.endpoint && !spec.endpoint.startsWith('/')) {
+    if (spec.handler && !/^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/.test(spec.handler)) {
       this.errors.push({
-        type: 'INVALID_ENDPOINT',
+        type: 'INVALID_HANDLER_REF',
         path: 'config/service/operations.json',
         operation: name,
-        field: 'endpoint',
-        value: spec.endpoint,
-        message: `Endpoint must start with /: ${spec.endpoint}`,
-        fix: `Change endpoint to: /${spec.endpoint}`
+        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>'`
       });
     }
 
-    // Validate HTTP method
-    const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
-    if (spec.method && !validMethods.includes(spec.method)) {
+    const validScopes = ['platform', 'tenant', 'workspace'];
+    if (spec.bundle_scope && !validScopes.includes(spec.bundle_scope)) {
       this.errors.push({
-        type: 'INVALID_HTTP_METHOD',
+        type: 'INVALID_BUNDLE_SCOPE',
         path: 'config/service/operations.json',
         operation: name,
-        field: 'method',
-        value: spec.method,
-        message: `Invalid HTTP method: ${spec.method}`,
-        fix: `Use one of: ${validMethods.join(', ')}`
+        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}" — v3 dispatches via handler registry (RFC §5.3, §5.9)`
+        });
+      }
+    }
   }
 
   /**

package/examples/service-wrapper-usage.js

@@ -1,250 +0,0 @@
-'use strict';
-
-/**
- * Example: How service-wrapper uses connector-testing
- * Shows the integration between service-wrapper and testing framework
- */
-
-const { ServiceReadinessValidator, TestOrchestrator } = require('../src');
-
-/**
- * Enhanced ServiceWrapper with integrated testing
- */
-class ServiceWrapperWithTesting {
-  constructor(options) {
-    this.service = options.service;
-    this.serviceName = options.serviceName;
-    this.openApiSpec = options.openApiSpec;
-    this.config = options.config;
-
-    // Testing configuration
-    this.testingEnabled = options.testingEnabled !== false;
-    this.testLevel = options.testLevel || 'component'; // unit, component, or integration
-    this.validator = new ServiceReadinessValidator();
-  }
-
-  /**
-   * Start service with validation
-   */
-  async start() {
-    console.log(`Starting ${this.serviceName}...`);
-
-    // Step 1: Pre-start validation
-    if (this.testingEnabled) {
-      const validation = await this.validateBeforeStart();
-
-      if (!validation.ready) {
-        throw new Error(`Service validation failed: ${validation.recommendation}`);
-      }
-
-      console.log(`Validation passed with score: ${validation.score}/100`);
-    }
-
-    // Step 2: Start the actual service
-    await this.startService();
-
-    // Step 3: Post-start verification
-    if (this.testingEnabled) {
-      await this.verifyAfterStart();
-    }
-
-    console.log(`${this.serviceName} started successfully`);
-  }
-
-  /**
-   * Validate service before starting
-   */
-  async validateBeforeStart() {
-    console.log('Running pre-start validation...');
-
-    // Use TestOrchestrator for comprehensive testing
-    const orchestrator = new TestOrchestrator({
-      service: this.service,
-      serviceName: this.serviceName,
-      openApiSpec: this.openApiSpec
-    });
-
-    // Run tests based on configured level
-    let testResults;
-    switch (this.testLevel) {
-      case 'unit':
-        testResults = await orchestrator.runUnitTests();
-        break;
-      case 'component':
-        testResults = await orchestrator.runComponentTests();
-        break;
-      case 'integration':
-        testResults = await orchestrator.runIntegrationTests();
-        break;
-      default:
-        testResults = await orchestrator.runComponentTests();
-    }
-
-    // Convert test results to readiness format
-    return {
-      ready: testResults.passed,
-      score: testResults.coverage || 0,
-      recommendation: testResults.passed
-        ? 'Service passed validation'
-        : 'Service failed validation tests',
-      details: testResults
-    };
-  }
-
-  /**
-   * Start the actual service
-   */
-  async startService() {
-    // This would contain the actual service startup logic
-    // - Start Express server
-    // - Connect to MQ
-    // - Register with registry
-    // - etc.
-
-    return new Promise((resolve) => {
-      const PORT = this.config.port || 3000;
-      this.server = this.service.listen(PORT, () => {
-        console.log(`Service listening on port ${PORT}`);
-        resolve();
-      });
-    });
-  }
-
-  /**
-   * Verify service after start
-   */
-  async verifyAfterStart() {
-    console.log('Running post-start verification...');
-
-    const serviceUrl = `http://localhost:${this.config.port || 3000}`;
-
-    // Quick readiness check
-    const readiness = await this.validator.validateReadiness({
-      name: this.serviceName,
-      url: serviceUrl,
-      openApiSpec: this.openApiSpec,
-      healthEndpoint: '/health'
-    });
-
-    if (!readiness.ready) {
-      console.warn('Post-start verification found issues:', readiness.errors);
-    }
-
-    return readiness;
-  }
-
-  /**
-   * Stop service
-   */
-  async stop() {
-    if (this.server) {
-      await new Promise((resolve) => {
-        this.server.close(resolve);
-      });
-    }
-  }
-}
-
-// === Example Usage ===
-
-async function demonstrateUsage() {
-  const express = require('express');
-
-  // Create a simple service
-  const app = express();
-  app.use(express.json());
-
-  app.get('/health', (req, res) => {
-    res.json({ status: 'healthy' });
-  });
-
-  app.post('/api/process', (req, res) => {
-    res.json({ processed: true, data: req.body });
-  });
-
-  // OpenAPI spec
-  const openApiSpec = {
-    openapi: '3.0.0',
-    info: { title: 'Demo Service', version: '1.0.0' },
-    paths: {
-      '/health': {
-        get: {
-          operationId: 'healthCheck',
-          responses: {
-            '200': {
-              content: {
-                'application/json': {
-                  schema: {
-                    type: 'object',
-                    properties: {
-                      status: { type: 'string' }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      },
-      '/api/process': {
-        post: {
-          operationId: 'processData',
-          requestBody: {
-            content: {
-              'application/json': {
-                schema: { type: 'object' }
-              }
-            }
-          },
-          responses: {
-            '200': {
-              content: {
-                'application/json': {
-                  schema: { type: 'object' }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  };
-
-  // Create wrapper with testing
-  const wrapper = new ServiceWrapperWithTesting({
-    service: app,
-    serviceName: 'demo-service',
-    openApiSpec,
-    config: {
-      port: 3333
-    },
-    testingEnabled: true,
-    testLevel: 'unit' // Start with unit tests for speed
-  });
-
-  try {
-    // Start service (will run validation first)
-    await wrapper.start();
-
-    console.log('\nService is running with validation!');
-    console.log('Try: curl http://localhost:3333/health');
-
-    // Keep running for demo
-    await new Promise(resolve => setTimeout(resolve, 5000));
-
-    // Stop service
-    await wrapper.stop();
-    console.log('\nService stopped');
-
-  } catch (error) {
-    console.error('Failed to start service:', error.message);
-    process.exit(1);
-  }
-}
-
-// Run demonstration
-if (require.main === module) {
-  demonstrateUsage().catch(console.error);
-}
-
-module.exports = { ServiceWrapperWithTesting };

package/examples/three-tier-testing.js

@@ -1,144 +0,0 @@
-'use strict';
-
-/**
- * Example: Three-tier testing strategy
- * Shows how to use connector-testing for comprehensive service validation
- */
-
-const { TestOrchestrator } = require('../src');
-const express = require('express');
-
-// Example service
-const app = express();
-app.use(express.json());
-
-app.get('/health', (req, res) => {
-  res.json({ status: 'healthy', service: 'example-service' });
-});
-
-app.post('/process', (req, res) => {
-  res.json({
-    processed: true,
-    input: req.body,
-    timestamp: Date.now()
-  });
-});
-
-app.get('/status', (req, res) => {
-  res.json({
-    running: true,
-    uptime: process.uptime()
-  });
-});
-
-// OpenAPI specification
-const openApiSpec = {
-  openapi: '3.0.0',
-  info: {
-    title: 'Example Service',
-    version: '1.0.0'
-  },
-  paths: {
-    '/health': {
-      get: {
-        operationId: 'healthCheck',
-        responses: {
-          '200': {
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'object',
-                  properties: {
-                    status: { type: 'string' },
-                    service: { type: 'string' }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    '/process': {
-      post: {
-        operationId: 'processData',
-        requestBody: {
-          content: {
-            'application/json': {
-              schema: { type: 'object' }
-            }
-          }
-        },
-        responses: {
-          '200': {
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'object',
-                  properties: {
-                    processed: { type: 'boolean' },
-                    input: { type: 'object' },
-                    timestamp: { type: 'number' }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    '/status': {
-      get: {
-        operationId: 'getStatus',
-        responses: {
-          '200': {
-            content: {
-              'application/json': {
-                schema: {
-                  type: 'object',
-                  properties: {
-                    running: { type: 'boolean' },
-                    uptime: { type: 'number' }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-};
-
-async function runExample() {
-  console.log('=== Three-Tier Testing Example ===\n');
-
-  // Create test orchestrator
-  const orchestrator = new TestOrchestrator({
-    service: app,
-    serviceName: 'example-service',
-    openApiSpec,
-    logger: console
-  });
-
-  // Run all three levels of testing
-  console.log('Starting comprehensive test suite...\n');
-  const results = await orchestrator.runAllTests();
-
-  // Generate and display report
-  const report = orchestrator.generateReport(results);
-  console.log('\n' + report);
-
-  // Return exit code based on results
-  process.exit(results.passed ? 0 : 1);
-}
-
-// Run if executed directly
-if (require.main === module) {
-  runExample().catch(error => {
-    console.error('Test failed:', error);
-    process.exit(1);
-  });
-}
-
-module.exports = { app, openApiSpec, runExample };