heicat 0.1.2

package/packages/core/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@heicat/core",
+  "version": "0.1.0",
+  "description": "Runtime-enforced API contract validation middleware for Node.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "api",
+    "contract",
+    "validation",
+    "middleware",
+    "express",
+    "fastify",
+    "nodejs"
+  ],
+  "author": "Backend Contract Studio",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.0",
+    "glob": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  }
+}

package/packages/core/src/__tests__/contract-loader.test.ts

@@ -0,0 +1,112 @@
+import { loadContracts, findContract } from '../contract-loader';
+import { Contract } from '../types/contract';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { resolve } from 'path';
+
+describe('Contract Loader', () => {
+  const testDir = resolve(__dirname, 'test-contracts');
+
+  beforeEach(() => {
+    // Create test directory
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    // Clean up
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe('loadContracts', () => {
+    it('should load valid contract files', async () => {
+      const contract1: Contract = {
+        method: 'GET',
+        path: '/users',
+        response: {
+          200: { data: { type: 'array' } }
+        }
+      };
+
+      const contract2: Contract = {
+        method: 'POST',
+        path: '/users',
+        request: {
+          body: { name: { type: 'string' } }
+        }
+      };
+
+      writeFileSync(resolve(testDir, 'users.contract.json'), JSON.stringify(contract1));
+      writeFileSync(resolve(testDir, 'create-user.contract.json'), JSON.stringify(contract2));
+
+      const contracts = await loadContracts(testDir);
+
+      expect(contracts).toHaveLength(2);
+      expect(contracts[0].method).toBe('GET');
+      expect(contracts[1].method).toBe('POST');
+    });
+
+    it('should ignore non-contract files', async () => {
+      const contract: Contract = {
+        method: 'GET',
+        path: '/users'
+      };
+
+      writeFileSync(resolve(testDir, 'users.contract.json'), JSON.stringify(contract));
+      writeFileSync(resolve(testDir, 'config.json'), JSON.stringify({ key: 'value' }));
+      writeFileSync(resolve(testDir, 'readme.txt'), 'readme content');
+
+      const contracts = await loadContracts(testDir);
+
+      expect(contracts).toHaveLength(1);
+      expect(contracts[0].path).toBe('/users');
+    });
+
+    it('should throw error for invalid JSON', async () => {
+      writeFileSync(resolve(testDir, 'invalid.contract.json'), '{ invalid json }');
+
+      await expect(loadContracts(testDir)).rejects.toThrow();
+    });
+
+    it('should return empty array for empty directory', async () => {
+      const contracts = await loadContracts(testDir);
+
+      expect(contracts).toEqual([]);
+    });
+  });
+
+  describe('findContract', () => {
+    it('should find contract by method and path', () => {
+      const contracts: Contract[] = [
+        { method: 'GET', path: '/users' },
+        { method: 'POST', path: '/users' },
+        { method: 'GET', path: '/posts' }
+      ];
+
+      const contract = findContract(contracts, 'POST', '/users');
+
+      expect(contract).toBeDefined();
+      expect(contract?.method).toBe('POST');
+      expect(contract?.path).toBe('/users');
+    });
+
+    it('should return undefined for non-existent contract', () => {
+      const contracts: Contract[] = [
+        { method: 'GET', path: '/users' }
+      ];
+
+      const contract = findContract(contracts, 'POST', '/users');
+
+      expect(contract).toBeUndefined();
+    });
+
+    it('should handle path matching with query parameters', () => {
+      const contracts: Contract[] = [
+        { method: 'GET', path: '/users' }
+      ];
+
+      const contract = findContract(contracts, 'GET', '/users?page=1');
+
+      expect(contract).toBeDefined();
+      expect(contract?.path).toBe('/users');
+    });
+  });
+});

package/packages/core/src/__tests__/validation-engine.test.ts

@@ -0,0 +1,213 @@
+import { ValidationEngine } from '../validation-engine';
+import { Contract } from '../types/contract';
+
+describe('ValidationEngine', () => {
+  let engine: ValidationEngine;
+
+  beforeEach(() => {
+    engine = new ValidationEngine();
+  });
+
+  describe('validateRequest', () => {
+    it('should validate valid request body', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        request: {
+          body: {
+            email: { type: 'string', required: true },
+            password: { type: 'string', minLength: 8, required: true }
+          }
+        }
+      };
+
+      const req = {
+        body: {
+          email: 'test@example.com',
+          password: 'password123'
+        }
+      };
+
+      const result = engine.validateRequest(contract, req);
+
+      expect(result.isValid).toBe(true);
+      expect(result.violations).toHaveLength(0);
+    });
+
+    it('should reject request with missing required field', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        request: {
+          body: {
+            email: { type: 'string', required: true },
+            password: { type: 'string', required: true }
+          }
+        }
+      };
+
+      const req = {
+        body: {
+          password: 'password123'
+          // missing email
+        }
+      };
+
+      const result = engine.validateRequest(contract, req);
+
+      expect(result.isValid).toBe(false);
+      expect(result.violations).toHaveLength(1);
+      expect(result.violations[0].severity).toBe('error');
+      expect(result.violations[0].message).toContain('email');
+    });
+
+    it('should reject request with password too short', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        request: {
+          body: {
+            email: { type: 'string', required: true },
+            password: { type: 'string', minLength: 8, required: true }
+          }
+        }
+      };
+
+      const req = {
+        body: {
+          email: 'test@example.com',
+          password: 'short'
+        }
+      };
+
+      const result = engine.validateRequest(contract, req);
+
+      expect(result.isValid).toBe(false);
+      expect(result.violations).toHaveLength(1);
+    });
+
+    it('should validate without request schema', () => {
+      const contract: Contract = {
+        method: 'GET',
+        path: '/users'
+        // no request schema
+      };
+
+      const req = { body: {} };
+
+      const result = engine.validateRequest(contract, req);
+
+      expect(result.isValid).toBe(true);
+      expect(result.violations).toHaveLength(0);
+    });
+  });
+
+  describe('validateResponse', () => {
+    it('should validate valid response', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        response: {
+          201: {
+            id: { type: 'string' },
+            email: { type: 'string' }
+          }
+        }
+      };
+
+      const response = {
+        id: '123',
+        email: 'test@example.com'
+      };
+
+      const result = engine.validateResponse(contract, 201, response);
+
+      expect(result.isValid).toBe(true);
+      expect(result.violations).toHaveLength(0);
+    });
+
+    it('should reject response with missing field', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        response: {
+          201: {
+            id: { type: 'string' },
+            email: { type: 'string' }
+          }
+        }
+      };
+
+      const response = {
+        id: '123'
+        // missing email
+      };
+
+      const result = engine.validateResponse(contract, 201, response);
+
+      expect(result.isValid).toBe(false);
+      expect(result.violations).toHaveLength(1);
+      expect(result.violations[0].severity).toBe('warning');
+    });
+
+    it('should validate without response schema', () => {
+      const contract: Contract = {
+        method: 'GET',
+        path: '/users'
+        // no response schema
+      };
+
+      const response = { data: [] };
+
+      const result = engine.validateResponse(contract, 200, response);
+
+      expect(result.isValid).toBe(true);
+      expect(result.violations).toHaveLength(0);
+    });
+  });
+
+  describe('validateError', () => {
+    it('should validate valid error response', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        errors: {
+          400: {
+            message: { type: 'string' }
+          }
+        }
+      };
+
+      const error = {
+        message: 'Invalid input'
+      };
+
+      const result = engine.validateError(contract, 400, error);
+
+      expect(result.isValid).toBe(true);
+      expect(result.violations).toHaveLength(0);
+    });
+
+    it('should reject error with wrong schema', () => {
+      const contract: Contract = {
+        method: 'POST',
+        path: '/users',
+        errors: {
+          400: {
+            message: { type: 'string' }
+          }
+        }
+      };
+
+      const error = {
+        error: 'Invalid input'
+        // should be 'message', not 'error'
+      };
+
+      const result = engine.validateError(contract, 400, error);
+
+      expect(result.isValid).toBe(false);
+      expect(result.violations).toHaveLength(1);
+    });
+  });
+});

package/packages/core/src/contract-loader.ts

@@ -0,0 +1,55 @@
+import { glob } from 'glob';
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, extname, join } from 'path';
+import { Contract } from './types/contract';
+
+export async function loadContracts(contractsPath: string): Promise<Contract[]> {
+  // Use manual directory traversal (more reliable than glob)
+  return loadContractsManually(contractsPath);
+}
+
+function loadContractsManually(contractsPath: string): Contract[] {
+  const contracts: Contract[] = [];
+  const fullPath = resolve(contractsPath);
+
+  try {
+    const items = readdirSync(fullPath);
+
+    for (const item of items) {
+      const itemPath = join(fullPath, item);
+      const stat = statSync(itemPath);
+
+      if (stat.isFile() && item.endsWith('.contract.json')) {
+        try {
+          const content = readFileSync(itemPath, 'utf-8');
+          const contract = JSON.parse(content) as Contract;
+
+          // Basic validation
+          if (!contract.method || !contract.path) {
+            console.warn(`Invalid contract in ${itemPath}: missing method or path`);
+            continue;
+          }
+
+          contracts.push(contract);
+        } catch (error) {
+          console.warn(`Failed to load contract from ${itemPath}:`, error);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn(`Failed to read contracts directory ${fullPath}:`, error);
+  }
+
+  return contracts;
+}
+
+export function findContract(
+  contracts: Contract[],
+  method: string,
+  path: string
+): Contract | undefined {
+  return contracts.find(contract =>
+    contract.method.toUpperCase() === method.toUpperCase() &&
+    contract.path === path
+  );
+}

package/packages/core/src/engine.ts

@@ -0,0 +1,95 @@
+import { Contract } from './types/contract';
+import { Violation } from './types/violation';
+import { ValidationEngine } from './validation-engine';
+import { ViolationStore } from './violation-store';
+import { loadContracts, findContract } from './contract-loader';
+import { ValidationMode } from './types/options';
+
+export class ContractEngine {
+  private contracts: Contract[] = [];
+  private validationEngine: ValidationEngine;
+  private violationStore: ViolationStore;
+  private mode: ValidationMode;
+
+  constructor(mode: ValidationMode) {
+    this.validationEngine = new ValidationEngine();
+    this.violationStore = new ViolationStore();
+    this.mode = mode;
+  }
+
+  async loadContracts(contractsPath: string): Promise<void> {
+    this.contracts = await loadContracts(contractsPath);
+    console.log(`Loaded ${this.contracts.length} contracts`);
+  }
+
+  validateRequest(method: string, path: string, req: any): Violation[] {
+    const contract = findContract(this.contracts, method, path);
+    if (!contract) {
+      return []; // No contract means no validation
+    }
+
+    const result = this.validationEngine.validateRequest(contract, req);
+
+    if (!result.isValid) {
+      result.violations.forEach(violation => {
+        this.violationStore.add(violation);
+        this.logViolation(violation);
+      });
+    }
+
+    return result.violations;
+  }
+
+  validateResponse(method: string, path: string, statusCode: number, body: any): Violation[] {
+    const contract = findContract(this.contracts, method, path);
+    if (!contract) {
+      return [];
+    }
+
+    const result = this.validationEngine.validateResponse(contract, statusCode, body);
+
+    if (!result.isValid) {
+      result.violations.forEach(violation => {
+        this.violationStore.add(violation);
+        this.logViolation(violation);
+      });
+    }
+
+    return result.violations;
+  }
+
+  validateError(method: string, path: string, statusCode: number, body: any): Violation[] {
+    const contract = findContract(this.contracts, method, path);
+    if (!contract) {
+      return [];
+    }
+
+    const result = this.validationEngine.validateError(contract, statusCode, body);
+
+    if (!result.isValid) {
+      result.violations.forEach(violation => {
+        this.violationStore.add(violation);
+        this.logViolation(violation);
+      });
+    }
+
+    return result.violations;
+  }
+
+  private logViolation(violation: Violation): void {
+    const prefix = violation.severity === 'error' ? '❌' : '⚠️';
+    console.log(`${prefix} ${violation.endpoint.method} ${violation.endpoint.path}: ${violation.message}`);
+  }
+
+  getViolations() {
+    return this.violationStore.getAll();
+  }
+
+  getStats() {
+    return this.violationStore.getStats();
+  }
+
+  clearViolations(): void {
+    this.violationStore.clear();
+  }
+}

package/packages/core/src/index.ts

@@ -0,0 +1,9 @@
+export { contractMiddleware } from './middleware';
+export { ContractEngine } from './engine';
+export { ViolationStore } from './violation-store';
+export { loadContracts } from './contract-loader';
+
+// Types
+export type { Contract } from './types/contract';
+export type { Violation } from './types/violation';
+export type { MiddlewareOptions } from './types/options';

package/packages/core/src/middleware.ts

@@ -0,0 +1,97 @@
+import { Request, Response, NextFunction } from 'express';
+import { MiddlewareOptions } from './types/options';
+import { ContractEngine } from './engine';
+
+declare global {
+  namespace Express {
+    interface Request {
+      _contractEngine?: ContractEngine;
+    }
+  }
+}
+
+// Shared engine instance across all requests
+let sharedEngine: ContractEngine | null = null;
+
+export function contractMiddleware(options: MiddlewareOptions) {
+  // Create shared engine instance only once
+  if (!sharedEngine) {
+    sharedEngine = new ContractEngine(options.mode);
+
+    // Load contracts asynchronously
+    sharedEngine.loadContracts(options.contractsPath).catch(error => {
+      console.error('Failed to load contracts:', error);
+    });
+  }
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    req._contractEngine = sharedEngine!;
+
+    // Validate request
+    const requestViolations = sharedEngine!.validateRequest(req.method, req.path, req);
+    if (requestViolations.some((v: any) => v.severity === 'error')) {
+      // Block invalid requests in all modes
+      const violation = requestViolations.find((v: any) => v.severity === 'error')!;
+      return res.status(400).json({
+        error: 'Request validation failed',
+        message: violation.message,
+        contract: violation.contractPath
+      });
+    }
+
+    // Store original send method
+    const originalSend = res.send;
+    const originalJson = res.json;
+    const originalStatus = res.status;
+
+    let responseSent = false;
+    let responseStatus = 200;
+    let responseBody: any = null;
+
+    // Override status to capture status code
+    res.status = function(code: number) {
+      responseStatus = code;
+      return originalStatus.call(this, code);
+    };
+
+    // Override json to capture response body
+    res.json = function(body: any) {
+      if (!responseSent) {
+        responseBody = body;
+        responseSent = true;
+
+        // Validate response
+        sharedEngine!.validateResponse(req.method, req.path, responseStatus, body);
+      }
+      return originalJson.call(this, body);
+    };
+
+    // Override send to capture response body
+    res.send = function(body: any) {
+      if (!responseSent) {
+        responseBody = body;
+        responseSent = true;
+
+        // Try to parse JSON, otherwise treat as raw response
+        let parsedBody = body;
+        if (typeof body === 'string') {
+          try {
+            parsedBody = JSON.parse(body);
+          } catch {
+            // Keep as string
+          }
+        }
+
+        // Validate response
+        sharedEngine!.validateResponse(req.method, req.path, responseStatus, parsedBody);
+      }
+      return originalSend.call(this, body);
+    };
+
+    next();
+  };
+}
+
+export function getContractEngine(req: Request): ContractEngine | undefined {
+  return req._contractEngine;
+}

package/packages/core/src/types/contract.ts

@@ -0,0 +1,28 @@
+export interface Contract {
+  method: string;
+  path: string;
+  auth?: string;
+  request?: {
+    body?: Record<string, any>;
+    query?: Record<string, any>;
+    params?: Record<string, any>;
+    headers?: Record<string, any>;
+  };
+  response?: Record<string, any>;
+  errors?: Record<string, any>;
+}
+
+export interface RequestContract {
+  body?: Record<string, any>;
+  query?: Record<string, any>;
+  params?: Record<string, any>;
+  headers?: Record<string, any>;
+}
+
+export interface ResponseContract {
+  [statusCode: string]: Record<string, any>;
+}
+
+export interface ErrorContract {
+  [statusCode: string]: Record<string, any>;
+}

package/packages/core/src/types/options.ts

@@ -0,0 +1,7 @@
+export interface MiddlewareOptions {
+  contractsPath: string;
+  mode: 'dev' | 'strict' | 'ci';
+  port?: number; // for future GUI
+}
+
+export type ValidationMode = 'dev' | 'strict' | 'ci';

package/packages/core/src/types/violation.ts

@@ -0,0 +1,19 @@
+export interface Violation {
+  id: string;
+  timestamp: Date;
+  type: 'request' | 'response' | 'error';
+  contractPath: string;
+  endpoint: {
+    method: string;
+    path: string;
+  };
+  expected: any;
+  actual: any;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  violations: Violation[];
+}