@machina.ai/openapi-contract-tester 2.1.0

package/.env.example

@@ -0,0 +1,91 @@
+# OpenAPI Contract Tester - Environment Variables Configuration
+# Copy this file to .env and customize as needed
+
+# ============================================
+# Directorios y Logging
+# ============================================
+
+# Directorio raíz para todos los archivos MCP
+# Default: ~/.openapi-contract-tester
+MCP_ROOT=~/.openapi-contract-tester
+
+# Nivel de logging: debug, info, warn, error
+# Default: info
+LOG_LEVEL=info
+
+# Override del directorio de logs (opcional)
+# Si no se especifica, usa MCP_ROOT/logs
+# LOG_DIR=/custom/path/logs
+
+# Tamaño máximo del archivo de log antes de rotación (bytes)
+# Default: 10485760 (10MB)
+MAX_LOG_FILE_SIZE=10485760
+
+# Número de archivos de log rotados a mantener
+# Default: 5
+MAX_LOG_FILES=5
+
+# ============================================
+# HTTP Client y Performance
+# ============================================
+
+# Timeout para requests HTTP en milisegundos
+# Default: 5000 (5 segundos)
+HTTP_TIMEOUT=5000
+
+# Máximo número de requests HTTP en paralelo
+# Default: 5
+MAX_PARALLEL_REQUESTS=5
+
+# Máximo número de tests a ejecutar en paralelo
+# Default: 5
+MAX_PARALLEL_TESTS=5
+
+# Timeout para ejecución de tests en milisegundos
+# Default: 30000 (30 segundos)
+TEST_TIMEOUT=30000
+
+# ============================================
+# Retry Logic (Exponential Backoff)
+# ============================================
+
+# Número máximo de reintentos para operaciones fallidas
+# Default: 3
+RETRY_MAX_ATTEMPTS=3
+
+# Delay inicial antes del primer reintento en milisegundos
+# Default: 1000 (1 segundo)
+RETRY_INITIAL_DELAY=1000
+
+# Delay máximo entre reintentos en milisegundos
+# Default: 10000 (10 segundos)
+RETRY_MAX_DELAY=10000
+
+# Multiplicador para exponential backoff
+# Delays: initial, initial*multiplier, initial*multiplier^2, ...
+# Default: 2
+RETRY_BACKOFF_MULTIPLIER=2
+
+# ============================================
+# Circuit Breaker Pattern
+# ============================================
+
+# Número de failures consecutivos antes de abrir el circuito
+# Default: 5
+CIRCUIT_BREAKER_THRESHOLD=5
+
+# Tiempo en milisegundos antes de intentar recovery (HALF_OPEN)
+# Default: 60000 (1 minuto)
+CIRCUIT_BREAKER_TIMEOUT=60000
+
+# Número de éxitos necesarios en HALF_OPEN para cerrar el circuito
+# Default: 2
+CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2
+
+# ============================================
+# MCP Mode (auto-detectado, raramente necesario)
+# ============================================
+
+# Forzar modo MCP (file logging vs console)
+# Auto-detectado desde STDIO, solo para debugging
+# MCP_MODE=true

package/README.md

@@ -0,0 +1,472 @@
+# OpenAPI Contract Tester - MCP Server
+
+✅ **Status**: COMPLETE MVP - Fases 1-18 Implementadas
+
+Servidor MCP (Model Context Protocol) para testing comprehensivo de APIs basado en especificaciones OpenAPI 3.x con soporte para contract testing usando Pact.
+
+## 🎯 Características
+
+### Generación de Tests
+- ✅ **Happy Path Tests**: Tests con datos válidos para casos exitosos
+- ✅ **Edge Case Tests**: Boundary Value Analysis (valores límite, enums, campos opcionales)
+- ✅ **Error Case Tests**: Tests de errores 400/401/404 (campos faltantes, formatos inválidos, constraints)
+
+### Ejecución de Tests
+- ✅ **HTTP Client con Playwright**: Cliente robusto con soporte para todos los métodos HTTP
+- ✅ **Ejecución Paralela**: Ejecuta múltiples tests en paralelo
+- ✅ **Validación de Schemas**: Valida responses contra schemas OpenAPI usando ajv
+- ✅ **Soporte de Autenticación**: Bearer, API Key, Basic, OAuth2
+
+### Contract Testing
+- ✅ **Generación de Contratos Pact**: Convierte OpenAPI a contratos Pact
+- ✅ **Pact Matchers**: Matching flexible basado en tipos
+- ✅ **Verificación de Provider**: Verifica que el provider implementa el contrato
+- ✅ **Pact Broker**: Publicación y descarga de contratos
+
+### Error Handling & Resilience
+- ✅ **Custom Error Classes**: Errores semánticos con códigos (E001-E999) y mensajes user-friendly
+- ✅ **Retry Logic**: Exponential backoff para errores transitorios (timeout, network)
+- ✅ **Circuit Breaker**: Previene cascading failures con estados CLOSED/OPEN/HALF_OPEN
+- ✅ **Error Wrapping**: Conversión automática de errores nativos a errores custom
+- ✅ **Structured Logging**: Sistema de logs compatible con STDIO que escribe a archivo en modo MCP
+
+### MCP Tools (4 herramientas principales)
+
+1. **generate-tests**: Genera tests inteligentes desde especificaciones OpenAPI
+   - Happy path, edge cases, error cases
+   - Auto-detección de dependencias entre tests
+   - Generación de datos con IA contextual
+
+2. **run-tests**: Ejecuta tests contra APIs con análisis avanzado
+   - Ejecución paralela con control de dependencias
+   - Auto-detección de tokens (24 campos conocidos)
+   - Validación de schemas automática
+   - AI-powered failure analysis
+
+3. **export-results**: Exporta resultados con análisis profundo
+   - Formatos: JSON, HTML profesional, Markdown
+   - **Auto-comparación**: Si detecta specPath + codeEndpoints, ejecuta compare-sources automáticamente
+   - **Root Cause Analysis**: Correlaciona fallos con discrepancias conocidas
+   - Coverage analysis integrado
+   - AI-powered insights y recomendaciones
+
+4. **compare-sources**: Compara OpenAPI spec vs Código vs PRD
+   - **Priorización inteligente**: Critical/High/Medium/Low según keywords
+   - **Reporte HTML visual**: Matriz de endpoints, discrepancias color-coded
+   - **Detección semántica IA**: Encuentra matches no obvios (POST /users ≈ POST /register)
+   - Business rule mappings (PRD → código)
+   - Sugerencias de remediación accionables
+
+### 📊 Reportes Profesionales
+- **HTML**: Diseño moderno con gradientes, cards interactivos, tablas responsivas y progress bars
+- **Markdown**: Tablas con emojis, executive summary, métricas de performance y detalles de fallos
+- **Contenido**: Summary dashboard, breakdown por categoría/endpoint, failed tests con errores detallados
+
+## 📦 Instalación
+
+### Instalación para Desarrollo
+
+```bash
+npm install
+npm run build
+```
+
+### Instalación desde npm (Cuando esté publicado)
+
+```bash
+npm install -g openapi-contract-tester
+```
+
+### 🧪 Testing Local (Pre-Publicación)
+
+Para probar el paquete como si estuviera instalado desde npm:
+
+#### Opción 1: npm link (desarrollo activo)
+
+```bash
+npm run build
+npm link
+
+# Ahora puedes usar el comando globalmente
+which openapi-contract-tester
+```
+
+**Uso**: Ideal para desarrollo cuando haces cambios frecuentes. Los cambios se reflejan inmediatamente.
+
+#### Opción 2: npm pack (testing de publicación)
+
+```bash
+npm run build
+npm pack
+# Crea: openapi-contract-tester-1.0.0.tgz
+
+# Instalar globalmente desde el tarball
+npm install -g ./openapi-contract-tester-1.0.0.tgz
+
+# Verificar instalación
+which openapi-contract-tester
+# Output: /usr/local/lib/node_modules/openapi-contract-tester/dist/index.js
+```
+
+**Uso**: Prueba exacta de cómo funcionará cuando se publique en npm. Útil para validación final antes de `npm publish`.
+
+**Configuración en cell-cli** (después de instalar con cualquier opción):
+
+```json
+{
+  "mcpServers": {
+    "openapi-contract-tester": {
+      "command": "openapi-contract-tester",
+      "env": {
+        "MCP_ROOT": "~/.openapi-contract-tester",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+> **Nota:** Por defecto usa `gemini-3-flash-preview`. Puedes cambiar el modelo con `AI_MODEL` en `env`.
+
+**Limpiar instalación de prueba**:
+
+```bash
+# Si usaste npm link
+npm unlink -g openapi-contract-tester
+
+# Si usaste npm install -g
+npm uninstall -g openapi-contract-tester
+
+# Limpiar tarball
+rm openapi-contract-tester-*.tgz
+```
+
+## ⚙️ Configuración
+
+### Variables de Entorno
+
+Todas las configuraciones pueden ser controladas vía variables de entorno:
+
+#### Directorios y Logging
+```bash
+MCP_ROOT=~/.openapi-contract-tester     # Directorio raíz (default: ~/.openapi-contract-tester)
+LOG_LEVEL=info                           # Nivel de log: debug, info, warn, error (default: info)
+LOG_DIR=/custom/path/logs                # Override del directorio de logs
+MAX_LOG_FILE_SIZE=10485760               # Tamaño máximo antes de rotación en bytes (default: 10MB)
+MAX_LOG_FILES=5                          # Número de archivos rotados a mantener (default: 5)
+```
+
+#### AI/LLM Configuration
+```bash
+# Opción 1: Solo cambiar el modelo (recomendado)
+AI_MODEL=gemini-3-flash-preview          # Nombre del modelo (default: gemini-3-flash-preview)
+
+# Opción 2: Cambiar modelo a versión anterior
+AI_MODEL=gemini-2.5-flash                # Usa gemini-2.5-flash en lugar del default
+
+# Opción 3: URL completa personalizada (override total)
+AI_API_URL=https://custom-api.com/v1/generate
+
+# Opción 4: Configuración avanzada
+AI_BASE_URL=http://localhost:13800/cell_apps/v1.1/gemini/v1beta/models  # Base URL (default)
+AI_MODEL=gemini-3-flash-preview          # Modelo específico
+AI_ENDPOINT=generateContent              # Endpoint de generación (default: generateContent)
+```
+
+**Prioridad de configuración:**
+1. `AI_API_URL` - URL completa (ignora otras variables)
+2. `AI_MODEL` + `AI_BASE_URL` + `AI_ENDPOINT` - Construcción dinámica
+3. Valores por defecto (`gemini-3-flash-preview`)
+
+#### HTTP y Performance
+```bash
+HTTP_TIMEOUT=5000                        # Timeout para requests HTTP en ms (default: 5000)
+MAX_PARALLEL_REQUESTS=5                  # Requests HTTP paralelos (default: 5)
+MAX_PARALLEL_TESTS=5                     # Tests paralelos (default: 5)
+TEST_TIMEOUT=30000                       # Timeout de test execution en ms (default: 30000)
+```
+
+#### Retry Logic
+```bash
+RETRY_MAX_ATTEMPTS=3                     # Máximo de reintentos (default: 3)
+RETRY_INITIAL_DELAY=1000                 # Delay inicial en ms (default: 1000)
+RETRY_MAX_DELAY=10000                    # Delay máximo en ms (default: 10000)
+RETRY_BACKOFF_MULTIPLIER=2               # Multiplicador para backoff (default: 2)
+```
+
+#### Circuit Breaker
+```bash
+CIRCUIT_BREAKER_THRESHOLD=5              # Failures antes de abrir (default: 5)
+CIRCUIT_BREAKER_TIMEOUT=60000            # Tiempo antes de HALF_OPEN en ms (default: 60000)
+CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2      # Éxitos para cerrar en HALF_OPEN (default: 2)
+```
+
+### Estructura de Directorios
+
+Cuando se configura `MCP_ROOT`, se crea la siguiente estructura:
+
+```
+~/.openapi-contract-tester/
+└── logs/
+    ├── mcp-server-2025-01-19.log
+    └── mcp-server-2025-01-19-2025-01-19T10-30-00-123Z.log (rotados)
+```
+
+## 🚀 Uso
+
+### Como MCP Server para cell-cli
+
+1. Configura cell-cli para usar este servidor MCP:
+
+```json
+{
+  "mcpServers": {
+    "openapi-contract-tester": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
+      "env": {
+        "MCP_ROOT": "~/.openapi-contract-tester",
+        "LOG_LEVEL": "info",
+        "AI_MODEL": "gemini-3-flash-preview",
+        "HTTP_TIMEOUT": "10000",
+        "MAX_PARALLEL_TESTS": "10",
+        "RETRY_MAX_ATTEMPTS": "3",
+        "CIRCUIT_BREAKER_THRESHOLD": "5"
+      }
+    }
+  }
+}
+```
+
+**Configuración Mínima:**
+```json
+{
+  "mcpServers": {
+    "openapi-contract-tester": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
+      "env": {
+        "MCP_ROOT": "~/.openapi-contract-tester",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+> **Nota:** Si no especificas `AI_MODEL`, usa `gemini-3-flash-preview` por defecto.
+
+2. Usa los tools desde cell-cli:
+
+```
+> Genera tests para mi API usando el archivo ./api.yml
+> Ejecuta los tests contra http://localhost:8080
+> Crea un contrato Pact entre mi-app y user-api
+```
+
+### Uso Directo (sin cell-cli)
+
+#### 1. Generar Tests
+
+```typescript
+import { parseOpenAPISpec, extractEndpoints } from './dist/parsers/openapi-parser.js';
+import { generateHappyPathTests } from './dist/generators/happy-path-generator.js';
+import { generateEdgeCaseTests } from './dist/generators/edge-case-generator.js';
+import { generateErrorCaseTests } from './dist/generators/error-case-generator.js';
+
+// Parsear especificación
+const spec = await parseOpenAPISpec('./api.yml');
+const endpoints = extractEndpoints(spec);
+
+// Generar tests
+const happyTests = generateHappyPathTests(endpoints, { seed: 42 });
+const edgeTests = generateEdgeCaseTests(endpoints, { seed: 42 });
+const errorTests = generateErrorCaseTests(endpoints, spec, { seed: 42 });
+
+console.log(`Generated ${happyTests.length + edgeTests.length + errorTests.length} tests`);
+```
+
+#### 2. Ejecutar Tests
+
+```typescript
+import { TestRunner } from './dist/executor/test-runner.js';
+
+const environment = {
+  name: 'local',
+  baseUrl: 'http://localhost:8080',
+  timeout: 5000,
+  auth: {
+    type: 'bearer',
+    token: 'your-token-here'
+  }
+};
+
+const runner = new TestRunner(environment);
+const { results, summary } = await runner.runTests(allTests, endpoints, {
+  parallel: 5,
+  validateSchemas: true,
+  onProgress: (completed, total, current) => {
+    console.log(`Progress: ${completed}/${total} - ${current.name}`);
+  }
+});
+
+console.log(`Passed: ${summary.passed}/${summary.total}`);
+console.log(`Failed: ${summary.failed}/${summary.total}`);
+console.log(`Avg Response Time: ${summary.avgResponseTime}ms`);
+```
+
+#### 3. Contract Testing con Pact
+
+```typescript
+import { generatePactContract, pactContractToJSON } from './dist/pact/pact-generator.js';
+import { verifyPactProvider } from './dist/pact/pact-executor.js';
+import fs from 'fs/promises';
+
+// Generar contrato
+const contract = generatePactContract(endpoints, {
+  consumer: 'my-app',
+  provider: 'user-api',
+  useMatchers: true
+});
+
+// Guardar contrato
+await fs.writeFile(
+  './pacts/my-app-user-api.json',
+  pactContractToJSON(contract, true)
+);
+
+// Verificar provider
+const result = await verifyPactProvider({
+  provider: 'user-api',
+  providerBaseUrl: 'http://localhost:8080',
+  pactUrls: ['./pacts/my-app-user-api.json']
+});
+
+console.log(`Verification: ${result.success ? 'PASSED' : 'FAILED'}`);
+```
+
+## 📊 Ejemplo de Salida
+
+### Generación de Tests
+Desde una API de 5 endpoints + 3 archivos de documentación:
+```
+✅ Happy Path Tests: 4
+✅ Edge Case Tests: 24
+✅ Error Case Tests: 34
+✅ Business Rules Tests: 48 (desde docs/)
+📈 Total: 110 tests
+```
+
+### Ejecución de Tests
+```
+Summary:
+  Total: 62
+  Passed: 58 (93.55%)
+  Failed: 4 (6.45%)
+  Duration: 2,345ms
+  Avg Response Time: 156ms
+
+By Category:
+  happy-path: 4 passed, 0 failed
+  edge-case: 22 passed, 2 failed
+  error-case: 32 passed, 2 failed
+
+By Endpoint:
+  GET /users: 7 tests (7 passed)
+  POST /users: 28 tests (26 passed, 2 failed)
+  GET /users/{id}: 4 tests (4 passed)
+  PUT /users/{id}: 24 tests (22 passed, 2 failed)
+  DELETE /users/{id}: 3 tests (3 passed)
+```
+
+## 📁 Estructura del Proyecto
+
+```
+mcp_testing/
+├── src/
+│   ├── types/
+│   │   └── index.ts (800+ líneas de tipos con JSDoc)
+│   ├── parsers/
+│   │   └── openapi-parser.ts (400+ líneas)
+│   ├── generators/
+│   │   ├── data-generator.ts (500+ líneas)
+│   │   ├── happy-path-generator.ts (300+ líneas)
+│   │   ├── edge-case-generator.ts (450+ líneas)
+│   │   └── error-case-generator.ts (450+ líneas)
+│   ├── validators/
+│   │   ├── schema-validator.ts (400+ líneas)
+│   │   └── openapi-validator.ts (400+ líneas)
+│   ├── executor/
+│   │   ├── http-client.ts (400+ líneas)
+│   │   └── test-runner.ts (500+ líneas)
+│   ├── pact/
+│   │   ├── pact-generator.ts (450+ líneas)
+│   │   └── pact-executor.ts (500+ líneas)
+│   ├── utils/
+│   │   ├── logger.ts (400+ líneas)
+│   │   ├── errors.ts (450+ líneas)
+│   │   └── resilience.ts (350+ líneas)
+│   ├── mcp/
+│   │   └── server.ts (650+ líneas)
+│   └── index.ts (Entry point)
+├── examples/
+│   └── user-service.yml
+├── LOGGING.md (Logging documentation)
+├── ERROR-HANDLING.md (Error handling documentation)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+**Total: ~7,700+ líneas de código TypeScript con 100% JSDoc**
+
+## 🧪 Testing
+
+```bash
+# Ejecutar tests de validación
+node quick-test.js
+node test-all-generators.js
+node test-schema-validator.js
+node test-openapi-validator.js
+node test-business-rules.js
+node test-logger.js
+node test-error-handling.js
+node test-config.js
+
+# Test con variables de entorno personalizadas
+HTTP_TIMEOUT=10000 MAX_PARALLEL_TESTS=10 LOG_LEVEL=debug node test-config.js
+```
+
+## 🔧 Tecnologías
+
+- **TypeScript**: Strict mode con tipos completos
+- **Playwright**: HTTP client robusto
+- **Pact**: Contract testing consumer-driven
+- **ajv**: Validación de JSON Schemas
+- **Faker.js**: Generación de datos realistas
+- **MCP SDK**: Integración con CLI conversacional con MCP
+- **Node.js 18+**: ES Modules, async/await
+
+## 📖 Mejores Prácticas Aplicadas
+
+- ✅ TypeScript strict mode
+- ✅ 100% JSDoc coverage
+- ✅ ESLint + Prettier
+- ✅ Node.js 2025 best practices
+- ✅ Error handling comprehensivo con retry & circuit breaker
+- ✅ Async/await patterns
+- ✅ ES Modules (type: "module")
+- ✅ Reproducible test generation (seeds)
+- ✅ STDIO-safe logging para protocolo MCP
+- ✅ Structured error codes (E001-E999)
+
+## 📚 Documentación
+
+- [LOGGING.md](LOGGING.md) - Sistema de logging compatible con MCP
+- [ERROR-HANDLING.md](ERROR-HANDLING.md) - Error handling, retry logic y circuit breaker
+
+## 📝 Licencia
+
+MIT
+
+---
+
+Servidor MCP completo para testing de APIs con OpenAPI 3.x, Playwright, y Pact.

package/dist/ai-engine/assertion-generator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Assertion Generator - Smart business logic assertions
+ *
+ * Generates intelligent assertions beyond schema validation.
+ * Validates business rules like date consistency, logical constraints, state transitions.
+ *
+ * @module ai-engine/assertion-generator
+ */
+import type { OpenAPIV3 } from 'openapi-types';
+import type { AIConfig } from '../types/ai-config.js';
+import type { APIContext } from '../analyzers/context-analyzer.js';
+/**
+ * Assertion definition
+ */
+export interface Assertion {
+    /** Assertion description */
+    description: string;
+    /** JSONPath to value */
+    path: string;
+    /** Assertion type */
+    type: 'equals' | 'notEquals' | 'greaterThan' | 'lessThan' | 'contains' | 'matches' | 'custom';
+    /** Expected value or pattern */
+    expected?: any;
+    /** Custom JavaScript expression (for complex assertions) */
+    expression?: string;
+}
+/**
+ * Generates smart assertions for a test
+ *
+ * @param method - HTTP method
+ * @param path - Endpoint path
+ * @param responseSchema - Response schema
+ * @param apiContext - API context
+ * @param aiConfig - AI configuration
+ * @returns Array of assertions
+ *
+ * @example
+ * ```typescript
+ * const assertions = await generateAssertions('GET', '/users/{id}', schema, context, config);
+ * // Returns:
+ * // [
+ * //   { description: 'createdAt before updatedAt', path: 'createdAt', type: 'lessThan', expected: 'updatedAt' },
+ * //   { description: 'email format valid', path: 'email', type: 'matches', expected: /^.+@.+$/ }
+ * // ]
+ * ```
+ */
+export declare function generateAssertions(method: string, path: string, responseSchema: OpenAPIV3.SchemaObject | undefined, apiContext: APIContext, aiConfig: AIConfig): Promise<Assertion[]>;
+//# sourceMappingURL=assertion-generator.d.ts.map

package/dist/ai-engine/assertion-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-generator.d.ts","sourceRoot":"","sources":["../../src/ai-engine/assertion-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAMnE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9F,gCAAgC;IAChC,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,SAAS,CAAC,YAAY,GAAG,SAAS,EAClD,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB"}