@complior/engine 0.9.0

package/src/types/contract.test.ts

@@ -0,0 +1,217 @@
+/**
+ * HTTP Contract Test — validates TS types match the shared JSON schema.
+ *
+ * This test ensures that:
+ * 1. TS types can construct objects matching the contract sample
+ * 2. The sample fixture round-trips through JSON serialization
+ * 3. All required fields are present and correctly typed
+ *
+ * If this test fails, TS types have drifted from the contract.
+ * Update both `common.types.ts` and `http-contract.json` together.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type {
+  ScanResult,
+  Finding,
+  ScoreBreakdown,
+  CategoryScore,
+  CodeContext,
+  CodeContextLine,
+  FixDiff,
+  Severity,
+  ScoreZone,
+} from './common.types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SAMPLE_PATH = resolve(__dirname, '../../data/schemas/http-contract-sample.json');
+const SCHEMA_PATH = resolve(__dirname, '../../data/schemas/http-contract.json');
+
+const loadSample = (): unknown => JSON.parse(readFileSync(SAMPLE_PATH, 'utf-8'));
+const loadSchema = (): unknown => JSON.parse(readFileSync(SCHEMA_PATH, 'utf-8'));
+
+describe('HTTP Contract — TS side', () => {
+  it('sample fixture exists and is valid JSON', () => {
+    const sample = loadSample();
+    expect(sample).toBeDefined();
+    expect(typeof sample).toBe('object');
+  });
+
+  it('schema file exists and is valid JSON Schema', () => {
+    const schema = loadSchema() as Record<string, unknown>;
+    expect(schema['$schema']).toContain('json-schema.org');
+    expect(schema['$defs']).toBeDefined();
+  });
+
+  it('sample deserializes as ScanResult with all required fields', () => {
+    const raw = loadSample() as ScanResult;
+
+    // ScanResult top-level
+    expect(typeof raw.projectPath).toBe('string');
+    expect(typeof raw.scannedAt).toBe('string');
+    expect(typeof raw.duration).toBe('number');
+    expect(typeof raw.filesScanned).toBe('number');
+    expect(Array.isArray(raw.findings)).toBe(true);
+    expect(raw.score).toBeDefined();
+  });
+
+  it('ScoreBreakdown has correct structure', () => {
+    const raw = loadSample() as ScanResult;
+    const score: ScoreBreakdown = raw.score;
+
+    expect(typeof score.totalScore).toBe('number');
+    expect(['red', 'yellow', 'green']).toContain(score.zone);
+    expect(Array.isArray(score.categoryScores)).toBe(true);
+    expect(typeof score.criticalCapApplied).toBe('boolean');
+    expect(typeof score.totalChecks).toBe('number');
+    expect(typeof score.passedChecks).toBe('number');
+    expect(typeof score.failedChecks).toBe('number');
+    expect(typeof score.skippedChecks).toBe('number');
+  });
+
+  it('CategoryScore has correct structure', () => {
+    const raw = loadSample() as ScanResult;
+    const cat: CategoryScore = raw.score.categoryScores[0]!;
+
+    expect(typeof cat.category).toBe('string');
+    expect(typeof cat.weight).toBe('number');
+    expect(typeof cat.score).toBe('number');
+    expect(typeof cat.obligationCount).toBe('number');
+    expect(typeof cat.passedCount).toBe('number');
+  });
+
+  it('Finding has correct required fields', () => {
+    const raw = loadSample() as ScanResult;
+    const finding: Finding = raw.findings[0]!;
+
+    expect(typeof finding.checkId).toBe('string');
+    expect(['pass', 'fail', 'skip', 'info']).toContain(finding.type);
+    expect(typeof finding.message).toBe('string');
+    expect(['critical', 'high', 'medium', 'low', 'info'] satisfies Severity[]).toContain(finding.severity);
+  });
+
+  it('Finding optional fields have correct types when present', () => {
+    const raw = loadSample() as ScanResult;
+    const finding: Finding = raw.findings[0]!;
+
+    // First finding has all optional fields
+    expect(typeof finding.file).toBe('string');
+    expect(typeof finding.line).toBe('number');
+    expect(typeof finding.obligationId).toBe('string');
+    expect(typeof finding.articleReference).toBe('string');
+    expect(typeof finding.fix).toBe('string');
+  });
+
+  it('CodeContext has correct structure when present', () => {
+    const raw = loadSample() as ScanResult;
+    const ctx: CodeContext = raw.findings[0]!.codeContext!;
+
+    expect(Array.isArray(ctx.lines)).toBe(true);
+    expect(typeof ctx.startLine).toBe('number');
+    expect(typeof ctx.highlightLine).toBe('number');
+
+    const line: CodeContextLine = ctx.lines[0]!;
+    expect(typeof line.num).toBe('number');
+    expect(typeof line.content).toBe('string');
+  });
+
+  it('FixDiff has correct structure when present', () => {
+    const raw = loadSample() as ScanResult;
+    // Find a finding with fixDiff (first finding is info, no fixDiff)
+    const findingWithDiff = raw.findings.find((f) => f.fixDiff !== undefined);
+    if (findingWithDiff === undefined) {
+      // No findings with fixDiff in sample — skip
+      return;
+    }
+    const diff: FixDiff = findingWithDiff.fixDiff!;
+
+    expect(Array.isArray(diff.before)).toBe(true);
+    expect(Array.isArray(diff.after)).toBe(true);
+    expect(typeof diff.startLine).toBe('number');
+    expect(typeof diff.filePath).toBe('string');
+  });
+
+  it('Severity enum values match contract', () => {
+    const validSeverities: Severity[] = ['critical', 'high', 'medium', 'low', 'info'];
+    const raw = loadSample() as ScanResult;
+    for (const f of raw.findings) {
+      expect(validSeverities).toContain(f.severity);
+    }
+  });
+
+  it('Zone enum values match contract', () => {
+    const validZones: ScoreZone[] = ['red', 'yellow', 'green'];
+    const raw = loadSample() as ScanResult;
+    expect(validZones).toContain(raw.score.zone);
+  });
+
+  it('Finding new optional fields have correct types when present', () => {
+    const raw = loadSample() as ScanResult;
+    const finding = raw.findings[0]! as Record<string, unknown>;
+
+    expect(typeof finding.priority).toBe('number');
+    expect(typeof finding.confidence).toBe('number');
+    expect(typeof finding.confidenceLevel).toBe('string');
+    expect(Array.isArray(finding.evidence)).toBe(true);
+  });
+
+  it('ScoreBreakdown has confidenceSummary', () => {
+    const raw = loadSample() as ScanResult;
+    const score = raw.score as Record<string, unknown>;
+    expect(score.confidenceSummary).toBeDefined();
+    expect(typeof score.confidenceSummary).toBe('object');
+  });
+
+  it('ScanResult has new optional fields', () => {
+    const raw = loadSample() as Record<string, unknown>;
+    expect(typeof raw.deepAnalysis).toBe('boolean');
+    expect(typeof raw.l5Cost).toBe('number');
+    expect(raw.regulationVersion).toBeDefined();
+  });
+
+  it('sample round-trips through JSON serialization', () => {
+    const original = loadSample();
+    const roundTripped = JSON.parse(JSON.stringify(original));
+    expect(roundTripped).toEqual(original);
+  });
+
+  it('TS can construct a type-safe ScanResult matching the fixture shape', () => {
+    // This verifies the TS interfaces can represent the fixture data.
+    // If interfaces change in a way that breaks the contract, this won't compile.
+    const result: ScanResult = {
+      score: {
+        totalScore: 72.5,
+        zone: 'yellow',
+        categoryScores: [{
+          category: 'documentation',
+          weight: 0.25,
+          score: 80.0,
+          obligationCount: 5,
+          passedCount: 4,
+        }],
+        criticalCapApplied: false,
+        totalChecks: 20,
+        passedChecks: 14,
+        failedChecks: 4,
+        skippedChecks: 2,
+      },
+      findings: [{
+        checkId: 'l4-bare-api-call',
+        type: 'fail',
+        message: 'test',
+        severity: 'high',
+        file: 'test.ts',
+        line: 1,
+      }],
+      projectPath: '/test',
+      scannedAt: '2026-01-01T00:00:00Z',
+      duration: 100,
+      filesScanned: 10,
+    };
+
+    expect(result.score.totalScore).toBe(72.5);
+    expect(result.findings).toHaveLength(1);
+  });
+});

package/src/types/errors.ts

@@ -0,0 +1,52 @@
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string) {
+    super(message, 'VALIDATION_ERROR', 400);
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string) {
+    super(message, 'NOT_FOUND', 404);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ConfigError extends AppError {
+  constructor(message: string) {
+    super(message, 'CONFIG_ERROR', 500);
+    this.name = 'ConfigError';
+  }
+}
+
+export class ScanError extends AppError {
+  constructor(message: string) {
+    super(message, 'SCAN_ERROR', 500);
+    this.name = 'ScanError';
+  }
+}
+
+export class LLMError extends AppError {
+  constructor(message: string) {
+    super(message, 'LLM_ERROR', 502);
+    this.name = 'LLMError';
+  }
+}
+
+export class ToolError extends AppError {
+  constructor(message: string) {
+    super(message, 'TOOL_ERROR', 500);
+    this.name = 'ToolError';
+  }
+}

package/src/types/framework.types.ts

@@ -0,0 +1,87 @@
+import type { ScanResult } from './common.types.js';
+import type { AgentPassport } from './passport.types.js';
+
+// --- Check sources: what Layer 1 metric does a framework check evaluate? ---
+export type CheckSource = 'scan_check' | 'passport_field' | 'document' | 'evidence';
+
+// --- Framework check definition ---
+export interface FrameworkCheck {
+  readonly id: string;
+  readonly name: string;
+  readonly source: CheckSource;
+  readonly target: string;
+  readonly categoryId: string;
+  readonly weight: number;
+  readonly description: string;
+}
+
+// --- Framework category ---
+export interface FrameworkCategory {
+  readonly id: string;
+  readonly name: string;
+  readonly weight: number;
+}
+
+// --- Grade mapping ---
+export interface GradeThreshold {
+  readonly minScore: number;
+  readonly grade: string;
+}
+
+export interface GradeMapping {
+  readonly type: 'letter' | 'level' | 'percentage';
+  readonly thresholds: readonly GradeThreshold[];
+}
+
+// --- Framework definition (data, not behavior) ---
+export interface ComplianceFramework {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly deadline?: string;
+  readonly checks: readonly FrameworkCheck[];
+  readonly categories: readonly FrameworkCategory[];
+  readonly gradeMapping: GradeMapping;
+}
+
+// --- Foundation metrics: Layer 1 input collected from existing services ---
+export interface FoundationMetrics {
+  readonly scanResult: ScanResult | null;
+  readonly passport: AgentPassport | null;
+  readonly passportCompleteness: number;
+  readonly evidenceChainValid: boolean;
+  readonly evidenceEntryCount: number;
+  readonly evidenceScanCount: number;
+  readonly documents: ReadonlySet<string>;
+}
+
+// --- Per-framework category score ---
+export interface FrameworkCategoryScore {
+  readonly categoryId: string;
+  readonly categoryName: string;
+  readonly score: number;
+  readonly weight: number;
+  readonly passedChecks: number;
+  readonly totalChecks: number;
+}
+
+// --- Per-framework output ---
+export interface FrameworkScoreResult {
+  readonly frameworkId: string;
+  readonly frameworkName: string;
+  readonly score: number;
+  readonly grade: string;
+  readonly gradeType: 'letter' | 'level' | 'percentage';
+  readonly gaps: number;
+  readonly totalChecks: number;
+  readonly passedChecks: number;
+  readonly deadline?: string;
+  readonly categories: readonly FrameworkCategoryScore[];
+}
+
+// --- All selected frameworks ---
+export interface MultiFrameworkScoreResult {
+  readonly frameworks: readonly FrameworkScoreResult[];
+  readonly selectedFrameworkIds: readonly string[];
+  readonly computedAt: string;
+}

package/src/types/passport-schemas.ts

@@ -0,0 +1,241 @@
+/**
+ * Zod validation schemas for Agent Passport types.
+ * Separated from interfaces (passport.types.ts) to keep both files under 300 lines.
+ */
+import { z } from 'zod';
+import type { AgentPassport } from './passport.types.js';
+
+// --- Sub-block schemas ---
+
+const OwnerBlockSchema = z.object({
+  team: z.string(),
+  contact: z.string(),
+  responsible_person: z.string(),
+});
+
+const AutonomyEvidenceSchema = z.object({
+  human_approval_gates: z.number().int().min(0),
+  unsupervised_actions: z.number().int().min(0),
+  no_logging_actions: z.number().int().min(0),
+  auto_rated: z.boolean(),
+});
+
+const ModelInfoSchema = z.object({
+  provider: z.string(),
+  model_id: z.string(),
+  deployment: z.string(),
+  data_residency: z.string(),
+});
+
+const DataBoundariesSchema = z.object({
+  pii_handling: z.enum(['block', 'redact', 'allow']),
+  geographic_restrictions: z.array(z.string()).optional(),
+  retention_days: z.number().int().min(0).optional(),
+  prohibited_data_types: z.array(z.string()).optional(),
+});
+
+const PermissionsBlockSchema = z.object({
+  tools: z.array(z.string()),
+  data_access: z.object({
+    read: z.array(z.string()),
+    write: z.array(z.string()),
+    delete: z.array(z.string()),
+  }),
+  denied: z.array(z.string()),
+  data_boundaries: DataBoundariesSchema.optional(),
+});
+
+const EscalationRuleSchema = z.object({
+  condition: z.string(),
+  action: z.enum(['require_approval', 'notify', 'block', 'log']),
+  description: z.string(),
+  timeout_minutes: z.number().int().min(0).optional(),
+});
+
+const ConstraintsBlockSchema = z.object({
+  rate_limits: z.object({ max_actions_per_minute: z.number().int().min(0) }),
+  budget: z.object({ max_cost_per_session_usd: z.number().min(0) }),
+  human_approval_required: z.array(z.string()),
+  prohibited_actions: z.array(z.string()),
+  escalation_rules: z.array(EscalationRuleSchema).optional(),
+});
+
+const ComplianceBlockSchema = z.object({
+  eu_ai_act: z.object({
+    risk_class: z.enum(['prohibited', 'high', 'limited', 'minimal']),
+    applicable_articles: z.array(z.string()),
+    deployer_obligations_met: z.array(z.string()),
+    deployer_obligations_pending: z.array(z.string()),
+  }),
+  /** Per-agent: passed / (passed + failed) × 100. No category weights. */
+  complior_score: z.number().min(0).max(100),
+  /** Project-wide: 8-category weighted average, capped at 40 if critical obligation fails. */
+  project_score: z.number().min(0).max(100).optional(),
+  last_scan: z.string(),
+  fria_completed: z.boolean().optional(),
+  fria_date: z.string().optional(),
+  worker_notification_sent: z.boolean().optional(),
+  worker_notification_date: z.string().optional(),
+  policy_generated: z.boolean().optional(),
+  policy_date: z.string().optional(),
+  ai_literacy: z.object({
+    training_completed: z.boolean().optional(),
+    last_training_date: z.string().optional(),
+    trained_count: z.number().int().min(0).optional(),
+    next_training_due: z.string().optional(),
+  }).optional(),
+  risk_management: z.object({
+    documented: z.boolean().optional(),
+    last_review: z.string().optional(),
+    risk_count: z.number().int().min(0).optional(),
+    residual_risks_accepted: z.number().int().min(0).optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  data_governance: z.object({
+    documented: z.boolean().optional(),
+    bias_tested: z.boolean().optional(),
+    last_audit: z.string().optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  technical_documentation: z.object({
+    documented: z.boolean().optional(),
+    last_update: z.string().optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  declaration_of_conformity: z.object({
+    documented: z.boolean().optional(),
+    date: z.string().optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  art5_screening: z.object({
+    completed: z.boolean().optional(),
+    date: z.string().optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  instructions_for_use: z.object({
+    documented: z.boolean().optional(),
+    last_update: z.string().optional(),
+    doc_quality: z.enum(['none', 'scaffold', 'draft', 'reviewed']).optional(),
+  }).optional(),
+  scan_summary: z.object({
+    total_checks: z.number().int().min(0),
+    passed: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    skipped: z.number().int().min(0),
+    by_category: z.record(z.object({
+      passed: z.number().int().min(0),
+      failed: z.number().int().min(0),
+    })),
+    failed_checks: z.array(z.string()),
+    scan_date: z.string(),
+  }).optional(),
+  multi_framework: z.array(z.object({
+    framework_id: z.string(),
+    framework_name: z.string(),
+    score: z.number().min(0).max(100),
+    grade: z.string().optional(),
+    assessed_at: z.string().optional(),
+  })).optional(),
+  doc_quality_summary: z.object({
+    none: z.number().int().min(0),
+    scaffold: z.number().int().min(0),
+    draft: z.number().int().min(0),
+    reviewed: z.number().int().min(0),
+  }).optional(),
+});
+
+const OversightBlockSchema = z.object({
+  responsible_person: z.string(),
+  role: z.string(),
+  contact: z.string(),
+  override_mechanism: z.string(),
+  escalation_procedure: z.string(),
+});
+
+const DisclosureBlockSchema = z.object({
+  user_facing: z.boolean(),
+  disclosure_text: z.string(),
+  ai_marking: z.object({
+    responses_marked: z.boolean(),
+    method: z.string(),
+  }),
+});
+
+const LoggingBlockSchema = z.object({
+  actions_logged: z.boolean(),
+  retention_days: z.number().int().min(0),
+  includes_decision_rationale: z.boolean(),
+});
+
+const LifecycleBlockSchema = z.object({
+  status: z.enum(['draft', 'review', 'active', 'suspended', 'retired']),
+  deployed_since: z.string(),
+  next_review: z.string(),
+  review_frequency_days: z.number().int().min(1),
+});
+
+const InteropBlockSchema = z.object({
+  mcp_servers: z.array(z.object({
+    name: z.string(),
+    tools_allowed: z.array(z.string()),
+  })),
+});
+
+const SignatureBlockSchema = z.object({
+  algorithm: z.string(),
+  public_key: z.string(),
+  signed_at: z.string(),
+  hash: z.string(),
+  value: z.string(),
+});
+
+const SourceBlockSchema = z.object({
+  mode: z.enum(['auto', 'semi-auto', 'manual']),
+  generated_by: z.string(),
+  code_analyzed: z.boolean(),
+  fields_auto_filled: z.array(z.string()),
+  fields_manual: z.array(z.string()),
+  confidence: z.number().min(0).max(1),
+});
+
+// --- Main passport schema ---
+
+export const AgentPassportSchema = z.object({
+  $schema: z.string(),
+  manifest_version: z.string(),
+  agent_id: z.string(),
+  name: z.string(),
+  display_name: z.string(),
+  description: z.string(),
+  version: z.string(),
+  created: z.string(),
+  updated: z.string(),
+  owner: OwnerBlockSchema,
+  type: z.enum(['autonomous', 'assistive', 'hybrid']),
+  autonomy_level: z.enum(['L1', 'L2', 'L3', 'L4', 'L5']),
+  autonomy_evidence: AutonomyEvidenceSchema,
+  framework: z.string(),
+  model: ModelInfoSchema,
+  permissions: PermissionsBlockSchema,
+  constraints: ConstraintsBlockSchema,
+  compliance: ComplianceBlockSchema,
+  oversight: OversightBlockSchema.optional(),
+  disclosure: DisclosureBlockSchema,
+  logging: LoggingBlockSchema,
+  lifecycle: LifecycleBlockSchema,
+  interop: InteropBlockSchema,
+  upstream_registry: z.array(z.record(z.unknown())).optional(),
+  source_files: z.array(z.string()).optional(),
+  endpoints: z.array(z.string().url()).optional(),
+  source: SourceBlockSchema,
+  signature: SignatureBlockSchema,
+});
+
+export const parsePassport = (json: string): AgentPassport | null => {
+  try {
+    const result = AgentPassportSchema.safeParse(JSON.parse(json));
+    return result.success ? (result.data as AgentPassport) : null;
+  } catch {
+    return null;
+  }
+};