@complior/engine 0.9.0

package/src/domain/frameworks/eu-ai-act-framework.ts

@@ -0,0 +1,100 @@
+/**
+ * EU AI Act Framework Adapter — wraps existing calculateScore results.
+ * Does NOT re-run calculateScore; reads metrics.scanResult.score directly.
+ */
+
+import type { ScoringData, WeightedCategory } from '../../data/schemas/schemas.js';
+import type {
+  ComplianceFramework,
+  FoundationMetrics,
+  FrameworkCategory,
+  FrameworkCategoryScore,
+  FrameworkCheck,
+  FrameworkScoreResult,
+} from '../../types/framework.types.js';
+import { EU_AI_ACT_DEADLINE_ISO, LETTER_GRADE_THRESHOLDS, resolveGrade } from '../shared/compliance-constants.js';
+
+export const createEuAiActFramework = (
+  scoringData: ScoringData | undefined,
+): ComplianceFramework => {
+  const categories: FrameworkCategory[] = (scoringData?.weighted_categories ?? []).map(
+    (wc: WeightedCategory) => ({
+      id: wc.category,
+      name: wc.category,
+      weight: wc.weight,
+    }),
+  );
+
+  const checks: FrameworkCheck[] = (scoringData?.weighted_categories ?? []).flatMap(
+    (wc: WeightedCategory) =>
+      wc.obligations_in_category.map((oblId) => ({
+        id: oblId,
+        name: oblId,
+        source: 'scan_check' as const,
+        target: oblId,
+        categoryId: wc.category,
+        weight: 1,
+        description: `EU AI Act obligation ${oblId}`,
+      })),
+  );
+
+  return Object.freeze({
+    id: 'eu-ai-act',
+    name: 'EU AI Act',
+    version: '2024/1689',
+    deadline: EU_AI_ACT_DEADLINE_ISO,
+    checks,
+    categories,
+    gradeMapping: {
+      type: 'letter',
+      thresholds: LETTER_GRADE_THRESHOLDS,
+    },
+  });
+};
+
+export const scoreEuAiAct = (
+  fw: ComplianceFramework,
+  metrics: FoundationMetrics,
+): FrameworkScoreResult => {
+  const scanScore = metrics.scanResult?.score;
+
+  if (!scanScore) {
+    return Object.freeze({
+      frameworkId: fw.id,
+      frameworkName: fw.name,
+      score: 0,
+      grade: 'F',
+      gradeType: 'letter' as const,
+      gaps: 0,
+      totalChecks: 0,
+      passedChecks: 0,
+      deadline: fw.deadline,
+      categories: [],
+    });
+  }
+
+  const grade =
+    resolveGrade(scanScore.totalScore);
+
+  const categories: FrameworkCategoryScore[] = scanScore.categoryScores.map((cs) => ({
+    categoryId: cs.category,
+    categoryName: cs.category,
+    score: cs.score,
+    weight: cs.weight,
+    passedChecks: cs.passedCount,
+    totalChecks: cs.obligationCount,
+  }));
+
+  return Object.freeze({
+    frameworkId: fw.id,
+    frameworkName: fw.name,
+    score: scanScore.totalScore,
+    grade,
+    gradeType: 'letter' as const,
+    gaps: scanScore.failedChecks,
+    totalChecks: scanScore.totalChecks,
+    passedChecks: scanScore.passedChecks,
+    deadline: fw.deadline,
+    categories,
+  });
+};

package/src/domain/frameworks/framework-registry.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { createFrameworkRegistry } from './framework-registry.js';
+import type { ComplianceFramework, FoundationMetrics, FrameworkScoreResult } from '../../types/framework.types.js';
+
+const mockFramework = (id: string): ComplianceFramework => ({
+  id,
+  name: `Test ${id}`,
+  version: '1.0',
+  checks: [],
+  categories: [],
+  gradeMapping: { type: 'letter', thresholds: [{ minScore: 0, grade: 'F' }] },
+});
+
+const mockScorer = (fw: ComplianceFramework, _metrics: FoundationMetrics): FrameworkScoreResult => ({
+  frameworkId: fw.id,
+  frameworkName: fw.name,
+  score: 75,
+  grade: 'B',
+  gradeType: 'letter',
+  gaps: 2,
+  totalChecks: 10,
+  passedChecks: 8,
+  categories: [],
+});
+
+describe('FrameworkRegistry', () => {
+  it('starts empty', () => {
+    const reg = createFrameworkRegistry();
+    expect(reg.ids()).toEqual([]);
+    expect(reg.getAll()).toEqual([]);
+  });
+
+  it('registers a framework', () => {
+    const reg = createFrameworkRegistry();
+    const fw = mockFramework('test-fw');
+    reg.register(fw, mockScorer);
+    expect(reg.has('test-fw')).toBe(true);
+    expect(reg.ids()).toEqual(['test-fw']);
+  });
+
+  it('retrieves a registered framework', () => {
+    const reg = createFrameworkRegistry();
+    const fw = mockFramework('alpha');
+    reg.register(fw, mockScorer);
+    const entry = reg.get('alpha');
+    expect(entry).toBeDefined();
+    expect(entry!.definition.id).toBe('alpha');
+  });
+
+  it('returns undefined for unknown id', () => {
+    const reg = createFrameworkRegistry();
+    expect(reg.get('nope')).toBeUndefined();
+    expect(reg.has('nope')).toBe(false);
+  });
+
+  it('registers multiple frameworks', () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFramework('a'), mockScorer);
+    reg.register(mockFramework('b'), mockScorer);
+    expect(reg.ids()).toEqual(['a', 'b']);
+    expect(reg.getAll()).toHaveLength(2);
+  });
+
+  it('overwrites on duplicate id', () => {
+    const reg = createFrameworkRegistry();
+    const fw1 = mockFramework('dup');
+    const fw2 = { ...mockFramework('dup'), name: 'Updated' };
+    reg.register(fw1, mockScorer);
+    reg.register(fw2, mockScorer);
+    expect(reg.get('dup')!.definition.name).toBe('Updated');
+    expect(reg.ids()).toEqual(['dup']);
+  });
+
+  it('scorer produces FrameworkScoreResult', () => {
+    const reg = createFrameworkRegistry();
+    const fw = mockFramework('score-test');
+    reg.register(fw, mockScorer);
+    const entry = reg.get('score-test')!;
+    const result = entry.score(entry.definition, {} as FoundationMetrics);
+    expect(result.score).toBe(75);
+    expect(result.grade).toBe('B');
+  });
+
+  it('getAll returns frozen array', () => {
+    const reg = createFrameworkRegistry();
+    reg.register(mockFramework('x'), mockScorer);
+    const all = reg.getAll();
+    expect(Array.isArray(all)).toBe(true);
+    expect(all).toHaveLength(1);
+  });
+});

package/src/domain/frameworks/framework-registry.ts

@@ -0,0 +1,38 @@
+import type { ComplianceFramework, FoundationMetrics, FrameworkScoreResult } from '../../types/framework.types.js';
+
+export type FrameworkScorer = (fw: ComplianceFramework, metrics: FoundationMetrics) => FrameworkScoreResult;
+
+export interface RegisteredFramework {
+  readonly definition: ComplianceFramework;
+  readonly score: FrameworkScorer;
+}
+
+export interface FrameworkRegistry {
+  readonly register: (fw: ComplianceFramework, scorer: FrameworkScorer) => void;
+  readonly get: (id: string) => RegisteredFramework | undefined;
+  readonly getAll: () => readonly RegisteredFramework[];
+  readonly has: (id: string) => boolean;
+  readonly ids: () => readonly string[];
+}
+
+export const createFrameworkRegistry = (): FrameworkRegistry => {
+  const map = new Map<string, RegisteredFramework>();
+
+  return Object.freeze({
+    register(fw: ComplianceFramework, scorer: FrameworkScorer): void {
+      map.set(fw.id, { definition: fw, score: scorer });
+    },
+    get(id: string): RegisteredFramework | undefined {
+      return map.get(id);
+    },
+    getAll(): readonly RegisteredFramework[] {
+      return [...map.values()];
+    },
+    has(id: string): boolean {
+      return map.has(id);
+    },
+    ids(): readonly string[] {
+      return [...map.keys()];
+    },
+  });
+};

package/src/domain/frameworks/index.ts

@@ -0,0 +1,8 @@
+export { createFrameworkRegistry } from './framework-registry.js';
+export type { FrameworkRegistry, FrameworkScorer, RegisteredFramework } from './framework-registry.js';
+export { createEuAiActFramework, scoreEuAiAct } from './eu-ai-act-framework.js';
+export { createAiuc1Framework, scoreAiuc1 } from './aiuc1-framework.js';
+export { createOwaspLlmFramework, scoreOwaspLlm } from './owasp-llm-framework.js';
+export { createMitreAtlasFramework, scoreMitreAtlas } from './mitre-atlas-framework.js';
+export { collectFoundationMetrics } from './collect-foundation-metrics.js';
+export type { FoundationMetricsDeps } from './collect-foundation-metrics.js';

package/src/domain/frameworks/mitre-atlas-framework.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { createMitreAtlasFramework, scoreMitreAtlas } from './mitre-atlas-framework.js';
+import type { FoundationMetrics } from '../../types/framework.types.js';
+
+const emptyMetrics: FoundationMetrics = {
+  scanResult: null,
+  passport: null,
+  passportCompleteness: 0,
+  evidenceChainValid: false,
+  evidenceEntryCount: 0,
+  evidenceScanCount: 0,
+  documents: new Set(),
+};
+
+describe('MITRE ATLAS Framework', () => {
+  it('creates framework with correct id and 6 categories', () => {
+    const fw = createMitreAtlasFramework();
+    expect(fw.id).toBe('mitre-atlas');
+    expect(fw.name).toBe('MITRE ATLAS');
+    expect(fw.categories).toHaveLength(6);
+    expect(fw.gradeMapping.type).toBe('letter');
+  });
+
+  it('returns grade F with score 0 when no scan result', () => {
+    const fw = createMitreAtlasFramework();
+    const result = scoreMitreAtlas(fw, emptyMetrics);
+    expect(result.score).toBe(0);
+    expect(result.grade).toBe('F');
+    expect(result.frameworkId).toBe('mitre-atlas');
+  });
+
+  it('returns score 0 when scan has no relevant findings (untested)', () => {
+    const fw = createMitreAtlasFramework();
+    const scan = {
+      score: { totalScore: 80 },
+      findings: [],
+      projectPath: '/test',
+      scannedAt: new Date().toISOString(),
+      duration: 100,
+      filesScanned: 5,
+    } as any;
+
+    const result = scoreMitreAtlas(fw, { ...emptyMetrics, scanResult: scan });
+    // No relevant findings → 0 (untested = not secure)
+    expect(result.score).toBe(0);
+    expect(result.grade).toBe('F');
+  });
+
+  it('has correct grade thresholds', () => {
+    const fw = createMitreAtlasFramework();
+    expect(fw.gradeMapping.thresholds).toHaveLength(5);
+  });
+});

package/src/domain/frameworks/mitre-atlas-framework.ts

@@ -0,0 +1,53 @@
+/**
+ * MITRE ATLAS Framework Adapter.
+ * Follows the same create*Framework() + score*() pattern as eu-ai-act-framework.ts.
+ */
+
+import type { ComplianceFramework, FrameworkCategory, FrameworkCheck, FrameworkScoreResult, FoundationMetrics } from '../../types/framework.types.js';
+import { MITRE_ATLAS_TACTICS } from '../../data/security/mitre-atlas.js';
+import { LETTER_GRADE_THRESHOLDS } from '../shared/compliance-constants.js';
+import { scorePluginFramework } from './score-plugin-framework.js';
+
+export const createMitreAtlasFramework = (): ComplianceFramework => {
+  const categories: FrameworkCategory[] = MITRE_ATLAS_TACTICS.map((tactic) => ({
+    id: tactic.id,
+    name: tactic.name,
+    weight: 1,
+  }));
+
+  const checks: FrameworkCheck[] = MITRE_ATLAS_TACTICS.flatMap((tactic) =>
+    tactic.plugins.map((plugin, idx) => ({
+      id: `${tactic.id}-${idx}`,
+      name: `${tactic.name}: ${plugin}`,
+      source: 'scan_check' as const,
+      target: plugin,
+      categoryId: tactic.id,
+      weight: 1,
+      description: `MITRE ATLAS ${tactic.id} — test plugin: ${plugin}`,
+    })),
+  );
+
+  return Object.freeze({
+    id: 'mitre-atlas',
+    name: 'MITRE ATLAS',
+    version: '4.0',
+    checks,
+    categories,
+    gradeMapping: {
+      type: 'letter',
+      thresholds: [...LETTER_GRADE_THRESHOLDS],
+    },
+  });
+};
+
+/**
+ * Score the MITRE ATLAS framework (no critical cap).
+ */
+export const scoreMitreAtlas = (
+  fw: ComplianceFramework,
+  metrics: FoundationMetrics,
+): FrameworkScoreResult =>
+  scorePluginFramework(fw, metrics, MITRE_ATLAS_TACTICS, {
+    matchPrefix: (cat) => (cat as typeof MITRE_ATLAS_TACTICS[number]).tactic,
+    applyCriticalCap: false,
+  });

package/src/domain/frameworks/owasp-llm-framework.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { createOwaspLlmFramework, scoreOwaspLlm } from './owasp-llm-framework.js';
+import type { FoundationMetrics } from '../../types/framework.types.js';
+import type { ScanResult } from '../../types/common.types.js';
+
+const emptyMetrics: FoundationMetrics = {
+  scanResult: null,
+  passport: null,
+  passportCompleteness: 0,
+  evidenceChainValid: false,
+  evidenceEntryCount: 0,
+  evidenceScanCount: 0,
+  documents: new Set(),
+};
+
+describe('OWASP LLM Framework', () => {
+  it('creates framework with correct id and 10 categories', () => {
+    const fw = createOwaspLlmFramework();
+    expect(fw.id).toBe('owasp-llm-top10');
+    expect(fw.name).toBe('OWASP LLM Top 10');
+    expect(fw.categories).toHaveLength(10);
+    expect(fw.gradeMapping.type).toBe('letter');
+  });
+
+  it('returns grade F with score 0 when no scan result', () => {
+    const fw = createOwaspLlmFramework();
+    const result = scoreOwaspLlm(fw, emptyMetrics);
+    expect(result.score).toBe(0);
+    expect(result.grade).toBe('F');
+    expect(result.frameworkId).toBe('owasp-llm-top10');
+  });
+
+  it('returns score 0 when scan has no security findings (untested)', () => {
+    const fw = createOwaspLlmFramework();
+    const scan = {
+      score: { totalScore: 80, zone: 'yellow', categoryScores: [], criticalCapApplied: false, totalChecks: 10, passedChecks: 8, failedChecks: 2 },
+      findings: [],
+      projectPath: '/test',
+      scannedAt: new Date().toISOString(),
+      duration: 100,
+      filesScanned: 5,
+    } as unknown as ScanResult;
+
+    const result = scoreOwaspLlm(fw, { ...emptyMetrics, scanResult: scan });
+    // No security findings → 0 (untested = not secure)
+    expect(result.score).toBe(0);
+    expect(result.grade).toBe('F');
+  });
+
+  it('applies critical cap when a category has 0% pass rate', () => {
+    const fw = createOwaspLlmFramework();
+    const scan = {
+      score: { totalScore: 80, zone: 'yellow', categoryScores: [], criticalCapApplied: false, totalChecks: 10, passedChecks: 8, failedChecks: 2 },
+      findings: [
+        { checkId: 'security-indirect-prompt-injection', type: 'fail', message: 'test', severity: 'critical', obligation_id: null, article_reference: null },
+        { checkId: 'security-prompt-extraction', type: 'pass', message: 'test', severity: 'high', obligation_id: null, article_reference: null },
+      ],
+      projectPath: '/test',
+      scannedAt: new Date().toISOString(),
+      duration: 100,
+      filesScanned: 5,
+    } as unknown as ScanResult;
+
+    const result = scoreOwaspLlm(fw, { ...emptyMetrics, scanResult: scan });
+    // LLM01 has both indirect-prompt-injection and prompt-extraction in plugins
+    // One pass, one fail → 50% for that category, not 0%, so no critical cap here
+    expect(result.score).toBeLessThanOrEqual(100);
+  });
+
+  it('grade thresholds map correctly', () => {
+    const fw = createOwaspLlmFramework();
+    // Just test the framework creation is valid
+    expect(fw.gradeMapping.thresholds).toHaveLength(5);
+    expect(fw.gradeMapping.thresholds[0]!.minScore).toBe(90);
+    expect(fw.gradeMapping.thresholds[0]!.grade).toBe('A');
+  });
+});

package/src/domain/frameworks/owasp-llm-framework.ts

@@ -0,0 +1,54 @@
+/**
+ * OWASP LLM Top 10 Framework Adapter.
+ * Follows the same create*Framework() + score*() pattern as eu-ai-act-framework.ts.
+ */
+
+import type { ComplianceFramework, FrameworkCategory, FrameworkCheck, FrameworkScoreResult, FoundationMetrics } from '../../types/framework.types.js';
+import { OWASP_LLM_TOP_10 } from '../../data/security/owasp-llm-top10.js';
+import { LETTER_GRADE_THRESHOLDS } from '../shared/compliance-constants.js';
+import { scorePluginFramework } from './score-plugin-framework.js';
+
+export const createOwaspLlmFramework = (): ComplianceFramework => {
+  const categories: FrameworkCategory[] = OWASP_LLM_TOP_10.map((cat) => ({
+    id: cat.id,
+    name: cat.name,
+    weight: 1,
+  }));
+
+  const checks: FrameworkCheck[] = OWASP_LLM_TOP_10.flatMap((cat) =>
+    cat.plugins.map((plugin, idx) => ({
+      id: `${cat.id}-${idx}`,
+      name: `${cat.name}: ${plugin}`,
+      source: 'scan_check' as const,
+      target: plugin,
+      categoryId: cat.id,
+      weight: 1,
+      description: `OWASP ${cat.id} — test plugin: ${plugin}`,
+    })),
+  );
+
+  return Object.freeze({
+    id: 'owasp-llm-top10',
+    name: 'OWASP LLM Top 10',
+    version: '2025',
+    checks,
+    categories,
+    gradeMapping: {
+      type: 'letter',
+      thresholds: [...LETTER_GRADE_THRESHOLDS],
+    },
+  });
+};
+
+/**
+ * Score the OWASP LLM Top 10 framework.
+ * Key rule: **Critical cap** — if any category has 0 passed checks, overall score ≤ 49.
+ */
+export const scoreOwaspLlm = (
+  fw: ComplianceFramework,
+  metrics: FoundationMetrics,
+): FrameworkScoreResult =>
+  scorePluginFramework(fw, metrics, OWASP_LLM_TOP_10, {
+    matchPrefix: (cat) => cat.id.toLowerCase(),
+    applyCriticalCap: true,
+  });

package/src/domain/frameworks/score-plugin-framework.ts

@@ -0,0 +1,117 @@
+/**
+ * Generic scoring helper for plugin-based security frameworks (OWASP, MITRE).
+ * Eliminates duplication between owasp-llm-framework.ts and mitre-atlas-framework.ts.
+ */
+
+import type { FrameworkCategoryScore, FrameworkScoreResult, FoundationMetrics, ComplianceFramework } from '../../types/framework.types.js';
+import { resolveGrade } from '../shared/compliance-constants.js';
+
+export interface PluginCategory {
+  readonly id: string;
+  readonly name: string;
+  readonly plugins: readonly string[];
+}
+
+export interface ScorePluginFrameworkOptions {
+  /** Match predicate suffix for checkId (e.g., 'security-{suffix}'). */
+  readonly matchPrefix: (cat: PluginCategory) => string;
+  /** Cap overall score at 49 if any category has 0% pass rate. */
+  readonly applyCriticalCap: boolean;
+}
+
+/**
+ * Score a plugin-based framework against scan findings.
+ * Groups findings by category using plugin-name matching, then computes per-category and overall scores.
+ */
+export const scorePluginFramework = (
+  fw: ComplianceFramework,
+  metrics: FoundationMetrics,
+  dataCategories: readonly PluginCategory[],
+  opts: ScorePluginFrameworkOptions,
+): FrameworkScoreResult => {
+  const scan = metrics.scanResult;
+
+  if (!scan) {
+    return Object.freeze({
+      frameworkId: fw.id,
+      frameworkName: fw.name,
+      score: 0,
+      grade: 'F',
+      gradeType: 'letter' as const,
+      gaps: 0,
+      totalChecks: 0,
+      passedChecks: 0,
+      categories: [],
+    });
+  }
+
+  const categoryResults = new Map<string, { passed: number; total: number }>();
+  for (const cat of dataCategories) {
+    categoryResults.set(cat.id, { passed: 0, total: 0 });
+  }
+
+  for (const finding of scan.findings) {
+    const checkId = finding.checkId;
+    for (const cat of dataCategories) {
+      const prefix = opts.matchPrefix(cat);
+      const isMatch = cat.plugins.some((plugin) =>
+        checkId.includes(plugin) || checkId.startsWith(`security-${prefix}`),
+      );
+      if (isMatch) {
+        const entry = categoryResults.get(cat.id)!;
+        entry.total++;
+        if (finding.type === 'pass') {
+          entry.passed++;
+        }
+      }
+    }
+  }
+
+  let totalPassed = 0;
+  let totalChecks = 0;
+  let hasCriticalGap = false;
+
+  const categories: FrameworkCategoryScore[] = dataCategories.map((cat) => {
+    const entry = categoryResults.get(cat.id)!;
+    const score = entry.total > 0 ? (entry.passed / entry.total) * 100 : 0;
+
+    if (opts.applyCriticalCap && entry.total > 0 && entry.passed === 0) {
+      hasCriticalGap = true;
+    }
+
+    totalPassed += entry.passed;
+    totalChecks += entry.total;
+
+    return {
+      categoryId: cat.id,
+      categoryName: cat.name,
+      score: Math.round(score),
+      weight: 1,
+      passedChecks: entry.passed,
+      totalChecks: entry.total,
+    };
+  });
+
+  const categoriesWithChecks = categories.filter((c) => c.totalChecks > 0);
+  let overallScore = categoriesWithChecks.length > 0
+    ? categoriesWithChecks.reduce((sum, c) => sum + c.score, 0) / categoriesWithChecks.length
+    : 0;
+
+  if (hasCriticalGap) {
+    overallScore = Math.min(overallScore, 49);
+  }
+
+  overallScore = Math.round(overallScore);
+
+  return Object.freeze({
+    frameworkId: fw.id,
+    frameworkName: fw.name,
+    score: overallScore,
+    grade: resolveGrade(overallScore),
+    gradeType: 'letter' as const,
+    gaps: totalChecks - totalPassed,
+    totalChecks,
+    passedChecks: totalPassed,
+    categories,
+  });
+};