@complior/engine 0.9.0

package/src/domain/passport/scan-to-compliance.ts

@@ -0,0 +1,166 @@
+/**
+ * Pure domain functions to derive passport compliance fields from scan results.
+ * Maps scanner checkIds → ComplianceBlock doc-status fields and builds scan_summary.
+ */
+import type { Finding } from '../../types/common.types.js';
+import type { ComplianceBlock, DocQualityLevel } from '../../types/passport.types.js';
+
+// --- Check ID → compliance field mapping ---
+
+type DocFieldMapper = (pass: boolean, date: string, docQuality?: DocQualityLevel) => Partial<ComplianceBlock>;
+
+const DOC_CHECK_TO_FIELD = new Map<string, DocFieldMapper>([
+  ['fria', (p, _d, q) => ({ fria_completed: p && q !== 'scaffold' && q !== 'none' })],
+  ['risk-management', (p, d, q) => ({ risk_management: { documented: p, last_review: d, doc_quality: q } })],
+  ['data-governance', (p, d, q) => ({ data_governance: { documented: p, last_audit: d, doc_quality: q } })],
+  ['technical-documentation', (p, d, q) => ({ technical_documentation: { documented: p, last_update: d, doc_quality: q } })],
+  ['tech-documentation', (p, d, q) => ({ technical_documentation: { documented: p, last_update: d, doc_quality: q } })],
+  ['declaration-of-conformity', (p, d, q) => ({ declaration_of_conformity: { documented: p, date: d, doc_quality: q } })],
+  ['declaration-conformity', (p, d, q) => ({ declaration_of_conformity: { documented: p, date: d, doc_quality: q } })],
+  ['art5-screening', (p, d, q) => ({ art5_screening: { completed: p, date: d, doc_quality: q } })],
+  ['instructions-for-use', (p, d, q) => ({ instructions_for_use: { documented: p, last_update: d, doc_quality: q } })],
+]);
+
+/**
+ * Derive document-status compliance fields from scan findings.
+ * Looks at L1/L2 findings whose checkId starts with a known doc prefix.
+ * A finding with type 'pass' → documented/completed = true.
+ */
+export const deriveDocStatusFromFindings = (
+  findings: readonly Finding[],
+  scanDate?: string,
+): Partial<ComplianceBlock> => {
+  const date = scanDate ?? new Date().toISOString();
+  let result: Partial<ComplianceBlock> = {};
+
+  for (const [prefix, mapper] of DOC_CHECK_TO_FIELD) {
+    const matches = findings.filter(
+      (f) => f.checkId === prefix || f.checkId.startsWith(`${prefix}-`) || f.checkId.startsWith(`l1-${prefix}`) || f.checkId.startsWith(`l2-${prefix}`),
+    );
+    // Prefer worst-case: L2 SHALLOW (fail) overrides L1 presence (pass)
+    const match = matches.find(f => f.type === 'fail')
+      ?? matches.find(f => f.docQuality !== undefined)
+      ?? matches[0];
+    if (match) {
+      // Extract docQuality from L2 finding (L1 findings won't have it)
+      const docQuality = match.docQuality ?? (match.type === 'pass' ? 'draft' : 'none');
+      result = { ...result, ...mapper(match.type === 'pass', date, docQuality) };
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Build a scan_summary block from a findings array — computes totals from findings directly.
+ * Accepts a filtered subset of findings (e.g. per-agent) rather than the full ScanResult.
+ */
+export const buildScanSummary = (
+  findings: readonly Finding[],
+  scanDate: string,
+): ComplianceBlock['scan_summary'] => {
+  const byCategory: Record<string, { passed: number; failed: number }> = {};
+  const failedChecks: string[] = [];
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+
+  for (const finding of findings) {
+    if (finding.type === 'pass') passed++;
+    else if (finding.type === 'fail') failed++;
+    else if (finding.type === 'skip') skipped++;
+
+    // Extract category from checkId (e.g. "risk-management" from "l1-risk-management")
+    const category = extractCategory(finding.checkId);
+
+    if (!byCategory[category]) {
+      byCategory[category] = { passed: 0, failed: 0 };
+    }
+
+    if (finding.type === 'pass') {
+      byCategory[category].passed++;
+    } else if (finding.type === 'fail') {
+      byCategory[category].failed++;
+      failedChecks.push(finding.checkId);
+    }
+  }
+
+  return {
+    total_checks: passed + failed + skipped,
+    passed,
+    failed,
+    skipped,
+    by_category: byCategory,
+    failed_checks: failedChecks,
+    scan_date: scanDate,
+  };
+};
+
+/**
+ * Build a summary of document quality levels across all doc fields in the compliance block.
+ * Counts how many docs are at each quality level (none, scaffold, draft, reviewed).
+ */
+export const buildDocQualitySummary = (
+  compliance: Partial<ComplianceBlock>,
+): ComplianceBlock['doc_quality_summary'] => {
+  const summary = { none: 0, scaffold: 0, draft: 0, reviewed: 0 };
+
+  const qualities: readonly (DocQualityLevel | undefined)[] = [
+    compliance.risk_management?.doc_quality,
+    compliance.data_governance?.doc_quality,
+    compliance.technical_documentation?.doc_quality,
+    compliance.declaration_of_conformity?.doc_quality,
+    compliance.art5_screening?.doc_quality,
+    compliance.instructions_for_use?.doc_quality,
+  ];
+
+  for (const quality of qualities) {
+    if (quality !== undefined && quality in summary) {
+      summary[quality]++;
+    } else {
+      summary.none++;
+    }
+  }
+
+  return summary;
+};
+
+/** Known multi-segment category names (3+ words) that must not be truncated. */
+const KNOWN_CATEGORIES: readonly string[] = [
+  'declaration-of-conformity',
+  'instructions-for-use',
+  'art5-screening',
+  'technical-documentation',
+  'risk-management',
+  'data-governance',
+  'worker-notification',
+  'monitoring-policy',
+  'incident-report',
+  'banned-with-wrapper',
+];
+
+/**
+ * Extract semantic category from a checkId.
+ * Strips layer prefix (l1-, l2-, l3-, l4-, l5-, cross-, ext-) if present,
+ * then matches against known multi-segment categories before falling back
+ * to first-two-segment truncation.
+ */
+const extractCategory = (checkId: string): string => {
+  const stripped = checkId.replace(/^(?:l[1-5]-|cross-)/, '');
+
+  // Check against known multi-segment categories first
+  for (const known of KNOWN_CATEGORIES) {
+    if (stripped === known || stripped.startsWith(known + '-')) return known;
+  }
+
+  // For external tool findings, keep the tool prefix (ext-semgrep, ext-detect)
+  if (stripped.startsWith('ext-')) {
+    const parts = stripped.split('-');
+    return parts.slice(0, 2).join('-');
+  }
+
+  // Default: first two segments
+  const parts = stripped.split('-');
+  if (parts.length <= 2) return stripped;
+  return parts.slice(0, 2).join('-');
+};

package/src/domain/passport/test-generator.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { generateComplianceTests } from './test-generator.js';
+
+describe('generateComplianceTests', () => {
+  it('generates basic test suite', () => {
+    const result = generateComplianceTests({ name: 'test-agent' });
+    expect(result.filename).toBe('test-agent-compliance-tests.ts');
+    expect(result.testCount).toBe(1); // minimum test
+    expect(result.content).toContain('test-agent');
+  });
+
+  it('generates permission tests', () => {
+    const result = generateComplianceTests({
+      name: 'bot',
+      permissions: { tools: ['read', 'write'], denied: ['delete'] },
+    });
+    expect(result.testCount).toBe(3);
+    expect(result.content).toContain("should allow tool: read");
+    expect(result.content).toContain("should allow tool: write");
+    expect(result.content).toContain("should block tool: delete");
+  });
+
+  it('generates rate limit tests', () => {
+    const result = generateComplianceTests({
+      name: 'bot',
+      constraints: { rate_limits: [{ action: 'api_call', limit: 100, window: '1h' }] },
+    });
+    expect(result.testCount).toBe(1);
+    expect(result.content).toContain('rate limit');
+  });
+
+  it('generates prohibited action tests', () => {
+    const result = generateComplianceTests({
+      name: 'bot',
+      constraints: { prohibited_actions: ['deploy', 'delete_data'] },
+    });
+    expect(result.testCount).toBe(2);
+  });
+
+  it('generates escalation rule tests', () => {
+    const result = generateComplianceTests({
+      name: 'bot',
+      constraints: {
+        escalation_rules: [
+          { condition: 'high_risk_decision', escalate_to: 'human_supervisor' },
+        ],
+      },
+    });
+    expect(result.testCount).toBe(1);
+    expect(result.content).toContain('escalate');
+    expect(result.content).toContain('high_risk_decision');
+  });
+
+  it('generates budget tests', () => {
+    const result = generateComplianceTests({
+      name: 'bot',
+      constraints: { budget: { max_cost: 50, currency: 'EUR' } },
+    });
+    expect(result.testCount).toBe(1);
+    expect(result.content).toContain('budget');
+    expect(result.content).toContain('50');
+  });
+
+  it('generates all constraint types together', () => {
+    const result = generateComplianceTests({
+      name: 'full-bot',
+      permissions: { tools: ['read'], denied: ['delete'] },
+      constraints: {
+        rate_limits: [{ action: 'api_call', limit: 100, window: '1h' }],
+        prohibited_actions: ['deploy'],
+        escalation_rules: [{ condition: 'risk', escalate_to: 'admin' }],
+        budget: { max_cost: 50, currency: 'USD' },
+      },
+    });
+    // 1 allowed + 1 denied + 1 rate limit + 1 prohibited + 1 escalation + 1 budget = 6
+    expect(result.testCount).toBe(6);
+  });
+
+  it('includes vitest import', () => {
+    const result = generateComplianceTests({ name: 'x' });
+    expect(result.content).toContain("import { describe, it, expect } from 'vitest'");
+  });
+
+  it('includes regeneration comment', () => {
+    const result = generateComplianceTests({ name: 'my-agent' });
+    expect(result.content).toContain('complior agent test-gen my-agent');
+  });
+
+  it('returns frozen result', () => {
+    const result = generateComplianceTests({ name: 'x' });
+    expect(Object.isFrozen(result)).toBe(true);
+  });
+});

package/src/domain/passport/test-generator.ts

@@ -0,0 +1,136 @@
+// US-S05-24: Generate compliance test suite from passport constraints
+
+export interface TestGeneratorInput {
+  readonly name: string;
+  readonly permissions?: {
+    readonly tools?: readonly string[];
+    readonly denied?: readonly string[];
+  };
+  readonly constraints?: {
+    readonly rate_limits?: readonly { action: string; limit: number; window: string }[];
+    readonly prohibited_actions?: readonly string[];
+    readonly escalation_rules?: readonly { condition: string; escalate_to: string }[];
+    readonly budget?: { max_cost: number; currency: string };
+  };
+}
+
+export interface GeneratedTestSuite {
+  readonly filename: string;
+  readonly content: string;
+  readonly testCount: number;
+}
+
+export const generateComplianceTests = (input: TestGeneratorInput): GeneratedTestSuite => {
+  const { name, permissions, constraints } = input;
+  const lines: string[] = [];
+  let testCount = 0;
+
+  lines.push(`// Auto-generated compliance tests for agent: ${name}`);
+  lines.push(`// Generated by Complior — DO NOT EDIT MANUALLY`);
+  lines.push(`// Regenerate with: complior agent test-gen ${name}`);
+  lines.push(`import { describe, it, expect } from 'vitest';`);
+  lines.push('');
+  lines.push(`describe('${name} compliance constraints', () => {`);
+
+  // 1. Permission tests — allowed tools
+  if (permissions?.tools?.length) {
+    lines.push('');
+    lines.push(`  describe('permissions.tools (allowed)', () => {`);
+    for (const tool of permissions.tools) {
+      lines.push(`    it('should allow tool: ${tool}', () => {`);
+      lines.push(`      const allowed = ${JSON.stringify(permissions.tools)};`);
+      lines.push(`      expect(allowed).toContain('${tool}');`);
+      lines.push(`    });`);
+      testCount++;
+    }
+    lines.push(`  });`);
+  }
+
+  // 2. Permission tests — denied tools
+  if (permissions?.denied?.length) {
+    lines.push('');
+    lines.push(`  describe('permissions.denied (blocked)', () => {`);
+    for (const tool of permissions.denied) {
+      lines.push(`    it('should block tool: ${tool}', () => {`);
+      lines.push(`      const denied = ${JSON.stringify(permissions.denied)};`);
+      lines.push(`      expect(denied).toContain('${tool}');`);
+      lines.push(`    });`);
+      testCount++;
+    }
+    lines.push(`  });`);
+  }
+
+  // 3. Rate limit tests
+  if (constraints?.rate_limits?.length) {
+    lines.push('');
+    lines.push(`  describe('rate limits', () => {`);
+    for (const rl of constraints.rate_limits) {
+      lines.push(`    it('should enforce rate limit: ${rl.action} <= ${rl.limit}/${rl.window}', () => {`);
+      lines.push(`      const limit = ${rl.limit};`);
+      lines.push(`      expect(limit).toBeGreaterThan(0);`);
+      lines.push(`      expect(limit).toBeLessThanOrEqual(${rl.limit});`);
+      lines.push(`    });`);
+      testCount++;
+    }
+    lines.push(`  });`);
+  }
+
+  // 4. Prohibited action tests
+  if (constraints?.prohibited_actions?.length) {
+    lines.push('');
+    lines.push(`  describe('prohibited actions', () => {`);
+    for (const action of constraints.prohibited_actions) {
+      lines.push(`    it('should prohibit: ${action}', () => {`);
+      lines.push(`      const prohibited = ${JSON.stringify(constraints.prohibited_actions)};`);
+      lines.push(`      expect(prohibited).toContain('${action}');`);
+      lines.push(`    });`);
+      testCount++;
+    }
+    lines.push(`  });`);
+  }
+
+  // 5. Escalation rule tests
+  if (constraints?.escalation_rules?.length) {
+    lines.push('');
+    lines.push(`  describe('escalation rules', () => {`);
+    for (const rule of constraints.escalation_rules) {
+      lines.push(`    it('should escalate "${rule.condition}" to ${rule.escalate_to}', () => {`);
+      lines.push(`      const escalation = ${JSON.stringify(rule)};`);
+      lines.push(`      expect(escalation.condition).toBeDefined();`);
+      lines.push(`      expect(escalation.escalate_to).toBeDefined();`);
+      lines.push(`    });`);
+      testCount++;
+    }
+    lines.push(`  });`);
+  }
+
+  // 6. Budget test
+  if (constraints?.budget) {
+    lines.push('');
+    lines.push(`  describe('budget constraints', () => {`);
+    lines.push(`    it('should enforce budget limit: ${constraints.budget.max_cost} ${constraints.budget.currency}', () => {`);
+    lines.push(`      const budget = ${JSON.stringify(constraints.budget)};`);
+    lines.push(`      expect(budget.max_cost).toBeGreaterThan(0);`);
+    lines.push(`    });`);
+    lines.push(`  });`);
+    testCount++;
+  }
+
+  // Minimum test if no constraints
+  if (testCount === 0) {
+    lines.push('');
+    lines.push(`  it('agent ${name} exists (no constraints defined)', () => {`);
+    lines.push(`    expect(true).toBe(true);`);
+    lines.push(`  });`);
+    testCount = 1;
+  }
+
+  lines.push(`});`);
+  lines.push('');
+
+  return Object.freeze({
+    filename: `${name}-compliance-tests.ts`,
+    content: lines.join('\n'),
+    testCount,
+  });
+};

package/src/domain/proxy/index.ts

@@ -0,0 +1,11 @@
+export { parseJsonRpcLine, serializeJsonRpc, isRequest, isResponse, createJsonRpcError } from './json-rpc.js';
+export { JsonRpcRequestSchema, JsonRpcResponseSchema } from './json-rpc.js';
+export type { JsonRpcRequest, JsonRpcResponse } from './json-rpc.js';
+export { createPolicyEngine, PolicyRuleSchema, ProxyPolicySchema } from './policy-engine.js';
+export type { PolicyRule, ProxyPolicy, PolicyDecision, PolicyEngine } from './policy-engine.js';
+export { createProxyBridge } from './proxy-bridge.js';
+export type { ProxyBridge } from './proxy-bridge.js';
+export { createInterceptor } from './proxy-interceptor.js';
+export type { InterceptorDeps, ProxyInterceptor } from './proxy-interceptor.js';
+export { ProxyConfigSchema } from './proxy-types.js';
+export type { ProxyConfig, McpCallLog, ProxyStats } from './proxy-types.js';

package/src/domain/proxy/json-rpc.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseJsonRpcLine, serializeJsonRpc, isRequest, isResponse, createJsonRpcError,
+  type JsonRpcRequest, type JsonRpcResponse,
+} from './json-rpc.js';
+
+describe('parseJsonRpcLine', () => {
+  it('parses a valid JSON-RPC request', () => {
+    const line = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_file"}}';
+    const result = parseJsonRpcLine(line);
+    expect(result).not.toBeNull();
+    expect(isRequest(result!)).toBe(true);
+    expect((result as JsonRpcRequest).method).toBe('tools/call');
+  });
+
+  it('parses a valid JSON-RPC response', () => {
+    const line = '{"jsonrpc":"2.0","id":1,"result":{"content":"hello"}}';
+    const result = parseJsonRpcLine(line);
+    expect(result).not.toBeNull();
+    expect(isResponse(result!)).toBe(true);
+  });
+
+  it('parses an error response', () => {
+    const line = '{"jsonrpc":"2.0","id":1,"error":{"code":-32600,"message":"Invalid"}}';
+    const result = parseJsonRpcLine(line);
+    expect(result).not.toBeNull();
+    expect((result as JsonRpcResponse).error?.code).toBe(-32600);
+  });
+
+  it('returns null for invalid JSON', () => {
+    expect(parseJsonRpcLine('not json')).toBeNull();
+  });
+
+  it('returns null for non-JSON-RPC JSON', () => {
+    expect(parseJsonRpcLine('{"foo":"bar"}')).toBeNull();
+  });
+
+  it('handles request without id (notification)', () => {
+    const line = '{"jsonrpc":"2.0","method":"notifications/initialized"}';
+    const result = parseJsonRpcLine(line);
+    expect(result).not.toBeNull();
+    expect(isRequest(result!)).toBe(true);
+  });
+});
+
+describe('serializeJsonRpc', () => {
+  it('serializes a request', () => {
+    const req: JsonRpcRequest = { jsonrpc: '2.0', id: 1, method: 'test' };
+    const result = serializeJsonRpc(req);
+    expect(JSON.parse(result)).toEqual(req);
+  });
+
+  it('serializes a response', () => {
+    const res: JsonRpcResponse = { jsonrpc: '2.0', id: 1, result: { ok: true } };
+    expect(JSON.parse(serializeJsonRpc(res))).toEqual(res);
+  });
+});
+
+describe('createJsonRpcError', () => {
+  it('creates an error response', () => {
+    const err = createJsonRpcError(1, -32600, 'Bad request');
+    expect(err.jsonrpc).toBe('2.0');
+    expect(err.id).toBe(1);
+    expect(err.error?.code).toBe(-32600);
+    expect(err.error?.message).toBe('Bad request');
+  });
+
+  it('handles undefined id', () => {
+    const err = createJsonRpcError(undefined, -32600, 'Bad');
+    expect(err.id).toBeNull();
+  });
+});

package/src/domain/proxy/json-rpc.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+export const JsonRpcRequestSchema = z.object({
+  jsonrpc: z.literal('2.0'),
+  id: z.union([z.string(), z.number()]).optional(),
+  method: z.string(),
+  params: z.unknown().optional(),
+});
+
+export type JsonRpcRequest = z.infer<typeof JsonRpcRequestSchema>;
+
+export const JsonRpcResponseSchema = z.object({
+  jsonrpc: z.literal('2.0'),
+  id: z.union([z.string(), z.number()]).optional().nullable(),
+  result: z.unknown().optional(),
+  error: z.object({
+    code: z.number(),
+    message: z.string(),
+    data: z.unknown().optional(),
+  }).optional(),
+});
+
+export type JsonRpcResponse = z.infer<typeof JsonRpcResponseSchema>;
+
+export const parseJsonRpcLine = (line: string): JsonRpcRequest | JsonRpcResponse | null => {
+  try {
+    const parsed = JSON.parse(line);
+    // Try request first
+    const reqResult = JsonRpcRequestSchema.safeParse(parsed);
+    if (reqResult.success) return reqResult.data;
+    // Try response
+    const resResult = JsonRpcResponseSchema.safeParse(parsed);
+    if (resResult.success) return resResult.data;
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+export const serializeJsonRpc = (msg: JsonRpcRequest | JsonRpcResponse): string =>
+  JSON.stringify(msg);
+
+export const isRequest = (msg: JsonRpcRequest | JsonRpcResponse): msg is JsonRpcRequest =>
+  'method' in msg;
+
+export const isResponse = (msg: JsonRpcRequest | JsonRpcResponse): msg is JsonRpcResponse =>
+  'result' in msg || 'error' in msg;
+
+export const createJsonRpcError = (id: string | number | undefined, code: number, message: string): JsonRpcResponse => ({
+  jsonrpc: '2.0',
+  id: id ?? null,
+  error: { code, message },
+});