@vibecheckai/cli 3.5.0 → 3.5.2

package/bin/runners/lib/reality/api-contract-validator.js

@@ -1,1012 +0,0 @@
-/**
- * API Contract Validation Engine
- * 
- * ═══════════════════════════════════════════════════════════════════════════════
- * COMPETITIVE MOAT FEATURE - Runtime API Contract Verification
- * ═══════════════════════════════════════════════════════════════════════════════
- * 
- * This engine validates API requests and responses against OpenAPI/Swagger specs
- * during Reality Mode runtime. It catches:
- * - Response schema mismatches
- * - Missing required fields
- * - Type violations
- * - Undocumented endpoints
- * - Request validation failures
- * - Status code mismatches
- * 
- * Features:
- * - Auto-discovery of OpenAPI specs
- * - Runtime request/response interception
- * - Detailed violation reporting
- * - Schema drift detection
- * - API coverage tracking
- */
-
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// OPENAPI SPEC LOCATIONS (auto-discovery)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const SPEC_LOCATIONS = [
-  "openapi.json",
-  "openapi.yaml",
-  "openapi.yml",
-  "swagger.json",
-  "swagger.yaml",
-  "swagger.yml",
-  "api/openapi.json",
-  "api/swagger.json",
-  "docs/openapi.json",
-  "docs/swagger.json",
-  ".vibecheck/contracts/openapi.json",
-  "public/api-docs/openapi.json"
-];
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// JSON SCHEMA VALIDATOR (Pure JS Implementation)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-class SchemaValidator {
-  constructor() {
-    this.errors = [];
-  }
-
-  /**
-   * Validate data against JSON Schema
-   */
-  validate(data, schema, path = "") {
-    this.errors = [];
-    this._validate(data, schema, path);
-    return {
-      valid: this.errors.length === 0,
-      errors: this.errors
-    };
-  }
-
-  _validate(data, schema, path) {
-    if (!schema) return;
-
-    // Handle $ref (simplified - doesn't resolve external refs)
-    if (schema.$ref) {
-      // Would need to resolve reference here
-      return;
-    }
-
-    // Handle allOf, anyOf, oneOf
-    if (schema.allOf) {
-      for (const subSchema of schema.allOf) {
-        this._validate(data, subSchema, path);
-      }
-      return;
-    }
-
-    if (schema.anyOf) {
-      const originalErrors = [...this.errors];
-      let anyValid = false;
-      
-      for (const subSchema of schema.anyOf) {
-        this.errors = [];
-        this._validate(data, subSchema, path);
-        if (this.errors.length === 0) {
-          anyValid = true;
-          break;
-        }
-      }
-      
-      if (!anyValid) {
-        this.errors = originalErrors;
-        this.errors.push({
-          path,
-          message: "Value does not match any of the allowed schemas",
-          keyword: "anyOf"
-        });
-      } else {
-        this.errors = originalErrors;
-      }
-      return;
-    }
-
-    if (schema.oneOf) {
-      let matchCount = 0;
-      const originalErrors = [...this.errors];
-      
-      for (const subSchema of schema.oneOf) {
-        this.errors = [];
-        this._validate(data, subSchema, path);
-        if (this.errors.length === 0) {
-          matchCount++;
-        }
-      }
-      
-      this.errors = originalErrors;
-      if (matchCount !== 1) {
-        this.errors.push({
-          path,
-          message: `Value must match exactly one schema, matched ${matchCount}`,
-          keyword: "oneOf"
-        });
-      }
-      return;
-    }
-
-    // Type validation
-    if (schema.type) {
-      const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-      const actualType = this._getType(data);
-      
-      if (!types.includes(actualType) && !(actualType === "integer" && types.includes("number"))) {
-        // Handle nullable
-        if (data === null && schema.nullable) {
-          return;
-        }
-        
-        this.errors.push({
-          path,
-          message: `Expected ${types.join(" or ")}, got ${actualType}`,
-          keyword: "type",
-          expected: types,
-          actual: actualType
-        });
-        return;
-      }
-    }
-
-    // Null check
-    if (data === null) {
-      if (!schema.nullable && schema.type !== "null") {
-        this.errors.push({
-          path,
-          message: "Value cannot be null",
-          keyword: "nullable"
-        });
-      }
-      return;
-    }
-
-    // String validations
-    if (typeof data === "string") {
-      if (schema.minLength !== undefined && data.length < schema.minLength) {
-        this.errors.push({
-          path,
-          message: `String must be at least ${schema.minLength} characters`,
-          keyword: "minLength"
-        });
-      }
-      
-      if (schema.maxLength !== undefined && data.length > schema.maxLength) {
-        this.errors.push({
-          path,
-          message: `String must be at most ${schema.maxLength} characters`,
-          keyword: "maxLength"
-        });
-      }
-      
-      if (schema.pattern) {
-        const regex = new RegExp(schema.pattern);
-        if (!regex.test(data)) {
-          this.errors.push({
-            path,
-            message: `String does not match pattern: ${schema.pattern}`,
-            keyword: "pattern"
-          });
-        }
-      }
-      
-      if (schema.format) {
-        this._validateFormat(data, schema.format, path);
-      }
-      
-      if (schema.enum && !schema.enum.includes(data)) {
-        this.errors.push({
-          path,
-          message: `Value must be one of: ${schema.enum.join(", ")}`,
-          keyword: "enum"
-        });
-      }
-    }
-
-    // Number validations
-    if (typeof data === "number") {
-      if (schema.minimum !== undefined) {
-        const valid = schema.exclusiveMinimum ? data > schema.minimum : data >= schema.minimum;
-        if (!valid) {
-          this.errors.push({
-            path,
-            message: `Number must be ${schema.exclusiveMinimum ? ">" : ">="} ${schema.minimum}`,
-            keyword: "minimum"
-          });
-        }
-      }
-      
-      if (schema.maximum !== undefined) {
-        const valid = schema.exclusiveMaximum ? data < schema.maximum : data <= schema.maximum;
-        if (!valid) {
-          this.errors.push({
-            path,
-            message: `Number must be ${schema.exclusiveMaximum ? "<" : "<="} ${schema.maximum}`,
-            keyword: "maximum"
-          });
-        }
-      }
-      
-      if (schema.multipleOf !== undefined && data % schema.multipleOf !== 0) {
-        this.errors.push({
-          path,
-          message: `Number must be a multiple of ${schema.multipleOf}`,
-          keyword: "multipleOf"
-        });
-      }
-    }
-
-    // Array validations
-    if (Array.isArray(data)) {
-      if (schema.minItems !== undefined && data.length < schema.minItems) {
-        this.errors.push({
-          path,
-          message: `Array must have at least ${schema.minItems} items`,
-          keyword: "minItems"
-        });
-      }
-      
-      if (schema.maxItems !== undefined && data.length > schema.maxItems) {
-        this.errors.push({
-          path,
-          message: `Array must have at most ${schema.maxItems} items`,
-          keyword: "maxItems"
-        });
-      }
-      
-      if (schema.uniqueItems) {
-        const seen = new Set();
-        for (let i = 0; i < data.length; i++) {
-          const key = JSON.stringify(data[i]);
-          if (seen.has(key)) {
-            this.errors.push({
-              path,
-              message: "Array items must be unique",
-              keyword: "uniqueItems"
-            });
-            break;
-          }
-          seen.add(key);
-        }
-      }
-      
-      if (schema.items) {
-        for (let i = 0; i < data.length; i++) {
-          this._validate(data[i], schema.items, `${path}[${i}]`);
-        }
-      }
-    }
-
-    // Object validations
-    if (typeof data === "object" && data !== null && !Array.isArray(data)) {
-      const properties = schema.properties || {};
-      const required = schema.required || [];
-      const additionalProperties = schema.additionalProperties;
-      
-      // Check required properties
-      for (const prop of required) {
-        if (!(prop in data)) {
-          this.errors.push({
-            path: path ? `${path}.${prop}` : prop,
-            message: `Missing required property: ${prop}`,
-            keyword: "required"
-          });
-        }
-      }
-      
-      // Validate properties
-      for (const [key, value] of Object.entries(data)) {
-        const propPath = path ? `${path}.${key}` : key;
-        
-        if (properties[key]) {
-          this._validate(value, properties[key], propPath);
-        } else if (additionalProperties === false) {
-          this.errors.push({
-            path: propPath,
-            message: `Unexpected property: ${key}`,
-            keyword: "additionalProperties"
-          });
-        } else if (typeof additionalProperties === "object") {
-          this._validate(value, additionalProperties, propPath);
-        }
-      }
-      
-      // Check property count
-      const propCount = Object.keys(data).length;
-      if (schema.minProperties !== undefined && propCount < schema.minProperties) {
-        this.errors.push({
-          path,
-          message: `Object must have at least ${schema.minProperties} properties`,
-          keyword: "minProperties"
-        });
-      }
-      
-      if (schema.maxProperties !== undefined && propCount > schema.maxProperties) {
-        this.errors.push({
-          path,
-          message: `Object must have at most ${schema.maxProperties} properties`,
-          keyword: "maxProperties"
-        });
-      }
-    }
-  }
-
-  _getType(value) {
-    if (value === null) return "null";
-    if (Array.isArray(value)) return "array";
-    if (Number.isInteger(value)) return "integer";
-    return typeof value;
-  }
-
-  _validateFormat(data, format, path) {
-    const formats = {
-      "date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
-      "date": /^\d{4}-\d{2}-\d{2}$/,
-      "time": /^\d{2}:\d{2}:\d{2}(\.\d+)?$/,
-      "email": /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-      "uri": /^https?:\/\/.+/,
-      "uuid": /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
-      "ipv4": /^(\d{1,3}\.){3}\d{1,3}$/,
-      "ipv6": /^([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$/i
-    };
-
-    if (formats[format] && !formats[format].test(data)) {
-      this.errors.push({
-        path,
-        message: `String does not match format: ${format}`,
-        keyword: "format"
-      });
-    }
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// API CONTRACT VALIDATOR CLASS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-class APIContractValidator {
-  constructor(options = {}) {
-    this.projectRoot = options.projectRoot || process.cwd();
-    this.spec = null;
-    this.specPath = options.specPath || null;
-    this.strictMode = options.strictMode || false;
-    this.ignorePatterns = options.ignorePatterns || [];
-    this.schemaValidator = new SchemaValidator();
-    this.violations = [];
-    this.coverage = {
-      endpoints: new Map(),
-      statusCodes: new Map()
-    };
-  }
-
-  /**
-   * Load OpenAPI specification
-   */
-  async loadSpec(specPath = null) {
-    const pathToLoad = specPath || this.specPath || this.findSpec();
-    
-    if (!pathToLoad) {
-      return {
-        loaded: false,
-        error: "No OpenAPI/Swagger specification found"
-      };
-    }
-
-    try {
-      const content = fs.readFileSync(pathToLoad, "utf8");
-      
-      // Parse YAML or JSON
-      if (pathToLoad.endsWith(".yaml") || pathToLoad.endsWith(".yml")) {
-        // Simple YAML parsing (would use js-yaml in production)
-        this.spec = this.parseYaml(content);
-      } else {
-        this.spec = JSON.parse(content);
-      }
-
-      this.specPath = pathToLoad;
-      this.resolveRefs();
-
-      return {
-        loaded: true,
-        path: pathToLoad,
-        info: this.spec.info,
-        endpointCount: this.countEndpoints()
-      };
-    } catch (error) {
-      return {
-        loaded: false,
-        error: error.message,
-        path: pathToLoad
-      };
-    }
-  }
-
-  /**
-   * Find OpenAPI spec in project
-   */
-  findSpec() {
-    for (const location of SPEC_LOCATIONS) {
-      const fullPath = path.join(this.projectRoot, location);
-      if (fs.existsSync(fullPath)) {
-        return fullPath;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Simple YAML parser (subset)
-   */
-  parseYaml(content) {
-    // For production, use js-yaml library
-    // This is a simplified parser for common cases
-    try {
-      // Try JSON first (YAML is a superset of JSON)
-      return JSON.parse(content);
-    } catch {
-      // Basic YAML parsing
-      // This would need a proper YAML library
-      throw new Error("YAML parsing requires js-yaml library");
-    }
-  }
-
-  /**
-   * Resolve $ref references in spec
-   */
-  resolveRefs() {
-    if (!this.spec) return;
-    
-    const components = this.spec.components || this.spec.definitions || {};
-    
-    const resolveObject = (obj) => {
-      if (!obj || typeof obj !== "object") return obj;
-      
-      if (obj.$ref) {
-        const refPath = obj.$ref.replace("#/components/schemas/", "")
-                                .replace("#/definitions/", "");
-        const resolved = components.schemas?.[refPath] || components[refPath];
-        if (resolved) {
-          return resolveObject({ ...resolved });
-        }
-        return obj;
-      }
-      
-      if (Array.isArray(obj)) {
-        return obj.map(resolveObject);
-      }
-      
-      const result = {};
-      for (const [key, value] of Object.entries(obj)) {
-        result[key] = resolveObject(value);
-      }
-      return result;
-    };
-
-    this.spec = resolveObject(this.spec);
-  }
-
-  /**
-   * Count endpoints in spec
-   */
-  countEndpoints() {
-    if (!this.spec?.paths) return 0;
-    
-    let count = 0;
-    for (const path of Object.values(this.spec.paths)) {
-      count += Object.keys(path).filter(m => 
-        ["get", "post", "put", "delete", "patch", "options", "head"].includes(m)
-      ).length;
-    }
-    return count;
-  }
-
-  // ═══════════════════════════════════════════════════════════════════════════
-  // REQUEST/RESPONSE VALIDATION
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  /**
-   * Validate an API request
-   */
-  validateRequest(request) {
-    if (!this.spec) {
-      return { valid: true, errors: [], skipped: true, reason: "No spec loaded" };
-    }
-
-    const { method, url, body, headers, queryParams } = request;
-    const errors = [];
-
-    // Match endpoint
-    const match = this.matchEndpoint(method, url);
-    
-    if (!match) {
-      if (this.strictMode) {
-        errors.push({
-          type: "undocumented_endpoint",
-          severity: "WARN",
-          message: `Undocumented endpoint: ${method.toUpperCase()} ${url}`,
-          details: { method, url }
-        });
-      }
-      return { valid: errors.length === 0, errors };
-    }
-
-    const { operation, pathParams } = match;
-
-    // Track coverage
-    this.trackCoverage(method, match.pathPattern);
-
-    // Validate path parameters
-    if (operation.parameters) {
-      for (const param of operation.parameters.filter(p => p.in === "path")) {
-        if (param.required && !pathParams[param.name]) {
-          errors.push({
-            type: "missing_path_param",
-            severity: "BLOCK",
-            message: `Missing required path parameter: ${param.name}`,
-            details: { parameter: param.name }
-          });
-        }
-      }
-    }
-
-    // Validate query parameters
-    if (operation.parameters && queryParams) {
-      for (const param of operation.parameters.filter(p => p.in === "query")) {
-        if (param.required && !(param.name in queryParams)) {
-          errors.push({
-            type: "missing_query_param",
-            severity: "BLOCK",
-            message: `Missing required query parameter: ${param.name}`,
-            details: { parameter: param.name }
-          });
-        }
-        
-        if (param.name in queryParams && param.schema) {
-          const validation = this.schemaValidator.validate(
-            queryParams[param.name],
-            param.schema,
-            `query.${param.name}`
-          );
-          
-          if (!validation.valid) {
-            errors.push({
-              type: "invalid_query_param",
-              severity: "WARN",
-              message: `Invalid query parameter: ${param.name}`,
-              details: { parameter: param.name, errors: validation.errors }
-            });
-          }
-        }
-      }
-    }
-
-    // Validate request body
-    if (body && operation.requestBody) {
-      const contentType = headers?.["content-type"] || "application/json";
-      const mediaType = operation.requestBody.content?.[contentType] ||
-                       operation.requestBody.content?.["application/json"];
-      
-      if (mediaType?.schema) {
-        let bodyData = body;
-        if (typeof body === "string") {
-          try {
-            bodyData = JSON.parse(body);
-          } catch {
-            errors.push({
-              type: "invalid_json",
-              severity: "BLOCK",
-              message: "Request body is not valid JSON"
-            });
-            return { valid: false, errors };
-          }
-        }
-
-        const validation = this.schemaValidator.validate(bodyData, mediaType.schema, "body");
-        
-        if (!validation.valid) {
-          for (const error of validation.errors) {
-            errors.push({
-              type: "request_schema_violation",
-              severity: "BLOCK",
-              message: `Request body validation failed: ${error.message}`,
-              details: { path: error.path, keyword: error.keyword }
-            });
-          }
-        }
-      }
-    } else if (operation.requestBody?.required && !body) {
-      errors.push({
-        type: "missing_request_body",
-        severity: "BLOCK",
-        message: "Request body is required"
-      });
-    }
-
-    return { valid: errors.length === 0, errors, match };
-  }
-
-  /**
-   * Validate an API response
-   */
-  validateResponse(response, requestMatch = null) {
-    if (!this.spec) {
-      return { valid: true, errors: [], skipped: true, reason: "No spec loaded" };
-    }
-
-    const { status, body, headers, method, url } = response;
-    const errors = [];
-
-    // Get match from request or find it
-    let match = requestMatch;
-    if (!match && method && url) {
-      match = this.matchEndpoint(method, url);
-    }
-
-    if (!match) {
-      if (this.strictMode) {
-        errors.push({
-          type: "undocumented_endpoint",
-          severity: "WARN",
-          message: `Response from undocumented endpoint: ${method?.toUpperCase()} ${url}`,
-          details: { method, url, status }
-        });
-      }
-      return { valid: errors.length === 0, errors };
-    }
-
-    const { operation, pathPattern } = match;
-
-    // Track status code coverage
-    this.trackStatusCode(pathPattern, method, status);
-
-    // Check if status code is documented
-    const responses = operation.responses || {};
-    const statusStr = status.toString();
-    const responseSpec = responses[statusStr] || 
-                        responses[`${Math.floor(status / 100)}XX`] ||
-                        responses.default;
-
-    if (!responseSpec) {
-      errors.push({
-        type: "undocumented_status",
-        severity: "WARN",
-        message: `Undocumented status code: ${status} for ${method?.toUpperCase()} ${pathPattern}`,
-        details: { status, documentedStatuses: Object.keys(responses) }
-      });
-      return { valid: errors.length === 0, errors };
-    }
-
-    // Validate response body
-    if (body && responseSpec.content) {
-      const contentType = headers?.["content-type"]?.split(";")[0] || "application/json";
-      const mediaType = responseSpec.content[contentType] ||
-                       responseSpec.content["application/json"] ||
-                       responseSpec.content["*/*"];
-
-      if (mediaType?.schema) {
-        let bodyData = body;
-        if (typeof body === "string") {
-          try {
-            bodyData = JSON.parse(body);
-          } catch {
-            errors.push({
-              type: "invalid_json",
-              severity: "WARN",
-              message: "Response body is not valid JSON"
-            });
-            return { valid: false, errors };
-          }
-        }
-
-        const validation = this.schemaValidator.validate(bodyData, mediaType.schema, "response");
-
-        if (!validation.valid) {
-          for (const error of validation.errors) {
-            errors.push({
-              type: "response_schema_violation",
-              severity: "BLOCK",
-              message: `Response validation failed: ${error.message}`,
-              details: { 
-                path: error.path, 
-                keyword: error.keyword,
-                status,
-                endpoint: `${method?.toUpperCase()} ${pathPattern}`
-              }
-            });
-          }
-        }
-      }
-    }
-
-    // Check for expected error responses
-    if (status >= 400 && status < 500) {
-      // Client errors should have proper structure
-      const bodyData = typeof body === "string" ? JSON.parse(body) : body;
-      if (bodyData && !bodyData.error && !bodyData.message && !bodyData.errors) {
-        errors.push({
-          type: "poor_error_response",
-          severity: "WARN",
-          message: `Error response lacks standard error structure`,
-          details: { status, hasError: !!bodyData.error, hasMessage: !!bodyData.message }
-        });
-      }
-    }
-
-    return { valid: errors.length === 0, errors, match };
-  }
-
-  /**
-   * Match URL to endpoint in spec
-   */
-  matchEndpoint(method, url) {
-    if (!this.spec?.paths) return null;
-
-    const urlObj = new URL(url, "http://localhost");
-    const pathname = urlObj.pathname;
-    const methodLower = method.toLowerCase();
-
-    for (const [pattern, pathItem] of Object.entries(this.spec.paths)) {
-      if (!pathItem[methodLower]) continue;
-
-      const match = this.matchPath(pathname, pattern);
-      if (match) {
-        return {
-          pathPattern: pattern,
-          operation: pathItem[methodLower],
-          pathParams: match.params
-        };
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Match URL path against pattern
-   */
-  matchPath(pathname, pattern) {
-    // Convert OpenAPI pattern to regex
-    // /users/{id} -> /users/([^/]+)
-    const paramNames = [];
-    const regexPattern = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
-      paramNames.push(name);
-      return "([^/]+)";
-    });
-
-    const regex = new RegExp(`^${regexPattern}$`);
-    const match = pathname.match(regex);
-
-    if (!match) return null;
-
-    const params = {};
-    paramNames.forEach((name, i) => {
-      params[name] = match[i + 1];
-    });
-
-    return { params };
-  }
-
-  // ═══════════════════════════════════════════════════════════════════════════
-  // COVERAGE TRACKING
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  /**
-   * Track endpoint coverage
-   */
-  trackCoverage(method, pathPattern) {
-    const key = `${method.toUpperCase()} ${pathPattern}`;
-    const current = this.coverage.endpoints.get(key) || { count: 0, lastSeen: null };
-    
-    this.coverage.endpoints.set(key, {
-      count: current.count + 1,
-      lastSeen: new Date().toISOString()
-    });
-  }
-
-  /**
-   * Track status code coverage
-   */
-  trackStatusCode(pathPattern, method, status) {
-    const key = `${method.toUpperCase()} ${pathPattern}`;
-    const current = this.coverage.statusCodes.get(key) || new Set();
-    current.add(status);
-    this.coverage.statusCodes.set(key, current);
-  }
-
-  /**
-   * Get coverage report
-   */
-  getCoverageReport() {
-    if (!this.spec?.paths) {
-      return { available: false };
-    }
-
-    const documented = new Set();
-    const documentedStatusCodes = new Map();
-
-    // Collect all documented endpoints
-    for (const [pattern, pathItem] of Object.entries(this.spec.paths)) {
-      for (const method of ["get", "post", "put", "delete", "patch"]) {
-        if (pathItem[method]) {
-          const key = `${method.toUpperCase()} ${pattern}`;
-          documented.add(key);
-          
-          const responses = pathItem[method].responses || {};
-          documentedStatusCodes.set(key, Object.keys(responses).filter(s => s !== "default"));
-        }
-      }
-    }
-
-    // Calculate coverage
-    const testedEndpoints = new Set(this.coverage.endpoints.keys());
-    const coveredEndpoints = [...documented].filter(e => testedEndpoints.has(e));
-    
-    const coverage = {
-      endpoints: {
-        total: documented.size,
-        covered: coveredEndpoints.length,
-        percentage: documented.size > 0 
-          ? ((coveredEndpoints.length / documented.size) * 100).toFixed(1) 
-          : 0,
-        missing: [...documented].filter(e => !testedEndpoints.has(e)),
-        undocumented: [...testedEndpoints].filter(e => !documented.has(e))
-      },
-      statusCodes: {
-        byEndpoint: {}
-      }
-    };
-
-    // Status code coverage per endpoint
-    for (const [endpoint, statuses] of this.coverage.statusCodes) {
-      const documented = documentedStatusCodes.get(endpoint) || [];
-      const testedStatuses = [...statuses].map(String);
-      
-      coverage.statusCodes.byEndpoint[endpoint] = {
-        documented,
-        tested: testedStatuses,
-        missing: documented.filter(s => !testedStatuses.includes(s))
-      };
-    }
-
-    return coverage;
-  }
-
-  // ═══════════════════════════════════════════════════════════════════════════
-  // INTEGRATION WITH REALITY MODE
-  // ═══════════════════════════════════════════════════════════════
-
-  /**
-   * Create Playwright network interceptor
-   */
-  createInterceptor() {
-    const self = this;
-    
-    return async (route, request) => {
-      const url = request.url();
-      const method = request.method();
-      
-      // Skip non-API requests
-      if (!url.includes("/api/") && !self.isApiRequest(url)) {
-        await route.continue();
-        return;
-      }
-
-      // Validate request
-      const requestBody = request.postData();
-      const requestValidation = self.validateRequest({
-        method,
-        url,
-        body: requestBody,
-        headers: request.headers(),
-        queryParams: Object.fromEntries(new URL(url).searchParams)
-      });
-
-      // Continue and capture response
-      const response = await route.fetch();
-      const responseBody = await response.text();
-      
-      // Validate response
-      const responseValidation = self.validateResponse({
-        status: response.status(),
-        body: responseBody,
-        headers: Object.fromEntries(response.headers()),
-        method,
-        url
-      }, requestValidation.match);
-
-      // Collect violations
-      if (!requestValidation.valid) {
-        self.violations.push(...requestValidation.errors.map(e => ({
-          ...e,
-          request: { method, url }
-        })));
-      }
-      
-      if (!responseValidation.valid) {
-        self.violations.push(...responseValidation.errors.map(e => ({
-          ...e,
-          request: { method, url },
-          response: { status: response.status() }
-        })));
-      }
-
-      // Fulfill with original response
-      await route.fulfill({
-        status: response.status(),
-        headers: Object.fromEntries(response.headers()),
-        body: responseBody
-      });
-    };
-  }
-
-  /**
-   * Check if URL is an API request
-   */
-  isApiRequest(url) {
-    try {
-      const urlObj = new URL(url);
-      const patterns = [
-        /\/api\//,
-        /\/v\d+\//,
-        /\/graphql/,
-        /\.(json)$/
-      ];
-      return patterns.some(p => p.test(urlObj.pathname));
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Get violations report
-   */
-  getViolationsReport() {
-    const byType = {};
-    const bySeverity = { BLOCK: [], WARN: [], INFO: [] };
-
-    for (const violation of this.violations) {
-      const type = violation.type;
-      if (!byType[type]) {
-        byType[type] = [];
-      }
-      byType[type].push(violation);
-      
-      const severity = violation.severity || "WARN";
-      bySeverity[severity]?.push(violation);
-    }
-
-    return {
-      total: this.violations.length,
-      byType,
-      bySeverity,
-      blockers: bySeverity.BLOCK.length,
-      warnings: bySeverity.WARN.length,
-      violations: this.violations
-    };
-  }
-
-  /**
-   * Reset state
-   */
-  reset() {
-    this.violations = [];
-    this.coverage.endpoints.clear();
-    this.coverage.statusCodes.clear();
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXPORTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-module.exports = {
-  APIContractValidator,
-  SchemaValidator,
-  SPEC_LOCATIONS
-};