@complior/engine 0.9.0

package/src/domain/scanner/finding-explainer.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getExplanation,
+  explainFinding,
+  explainFindings,
+  getAvailableCheckIds,
+} from './finding-explainer.js';
+import type { Finding } from '../../types/common.types.js';
+
+const makeFinding = (checkId: string, type: 'pass' | 'fail' = 'fail'): Finding => ({
+  checkId,
+  type,
+  message: `Test finding for ${checkId}`,
+  severity: 'medium',
+});
+
+describe('US-S05-07: Finding Explainer', () => {
+  // ── getExplanation ──────────────────────────────────────────────
+
+  describe('getExplanation', () => {
+    it('returns explanation for L1 check_id', () => {
+      const expl = getExplanation('ai-disclosure');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 50(1)');
+      expect(expl!.penalty).toContain('7.5M');
+      expect(expl!.deadline).toBe('2025-08-02');
+      expect(expl!.business_impact).toContain('informed');
+    });
+
+    it('returns explanation for L2 check_id', () => {
+      const expl = getExplanation('l2-fria');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 27');
+      expect(expl!.business_impact).toContain('Fundamental Rights');
+    });
+
+    it('returns explanation for L3 check_id', () => {
+      const expl = getExplanation('l3-log-retention');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 12');
+    });
+
+    it('returns explanation for L4 check_id', () => {
+      const expl = getExplanation('l4-bare-llm');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 50(1)');
+      expect(expl!.business_impact).toContain('informational');
+    });
+
+    it('normalizes l3-banned-{package} to generic key', () => {
+      const expl = getExplanation('l3-banned-tensorflow');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 15(4)');
+    });
+
+    it('returns undefined for unknown check_id', () => {
+      expect(getExplanation('nonexistent-check')).toBeUndefined();
+    });
+
+    it('returns explanation for passport-presence', () => {
+      const expl = getExplanation('passport-presence');
+      expect(expl).toBeDefined();
+      expect(expl!.article).toBe('Art. 26(4)');
+      expect(expl!.penalty).toContain('15M');
+    });
+  });
+
+  // ── explainFinding ──────────────────────────────────────────────
+
+  describe('explainFinding', () => {
+    it('enriches a finding with explanation', () => {
+      const finding = makeFinding('ai-disclosure');
+      const result = explainFinding(finding);
+      expect(result.explanation).toBeDefined();
+      expect(result.explanation!.article).toBe('Art. 50(1)');
+      expect(result.checkId).toBe('ai-disclosure');
+    });
+
+    it('returns finding unchanged for unknown check_id', () => {
+      const finding = makeFinding('unknown-xyz');
+      const result = explainFinding(finding);
+      expect(result.explanation).toBeUndefined();
+      expect(result.checkId).toBe('unknown-xyz');
+    });
+
+    it('does not mutate original finding', () => {
+      const finding = makeFinding('ai-disclosure');
+      explainFinding(finding);
+      expect((finding as Record<string, unknown>)['explanation']).toBeUndefined();
+    });
+  });
+
+  // ── explainFindings ─────────────────────────────────────────────
+
+  describe('explainFindings', () => {
+    it('enriches all findings in array', () => {
+      const findings = [
+        makeFinding('ai-disclosure'),
+        makeFinding('passport-presence'),
+        makeFinding('unknown-check'),
+      ];
+      const results = explainFindings(findings);
+      expect(results).toHaveLength(3);
+      expect(results[0].explanation).toBeDefined();
+      expect(results[1].explanation).toBeDefined();
+      expect(results[2].explanation).toBeUndefined();
+    });
+
+    it('handles empty array', () => {
+      expect(explainFindings([])).toEqual([]);
+    });
+  });
+
+  // ── getAvailableCheckIds ────────────────────────────────────────
+
+  describe('getAvailableCheckIds', () => {
+    it('returns all mapped check_ids', () => {
+      const ids = getAvailableCheckIds();
+      expect(ids.length).toBeGreaterThanOrEqual(19);
+      expect(ids).toContain('ai-disclosure');
+      expect(ids).toContain('l2-fria');
+      expect(ids).toContain('l4-bare-llm');
+    });
+  });
+
+  // ── Coverage: all explanations have required fields ─────────────
+
+  describe('data integrity', () => {
+    it('all explanations have article, penalty, deadline, business_impact', () => {
+      const ids = getAvailableCheckIds();
+      for (const id of ids) {
+        const expl = getExplanation(id);
+        expect(expl, `Missing explanation for ${id}`).toBeDefined();
+        expect(expl!.article, `Missing article for ${id}`).toBeTruthy();
+        expect(expl!.penalty, `Missing penalty for ${id}`).toBeTruthy();
+        expect(expl!.deadline, `Missing deadline for ${id}`).toBeTruthy();
+        expect(expl!.business_impact, `Missing business_impact for ${id}`).toBeTruthy();
+      }
+    });
+
+    it('deadlines are valid ISO date format', () => {
+      const ids = getAvailableCheckIds();
+      for (const id of ids) {
+        const expl = getExplanation(id);
+        expect(expl!.deadline, `Invalid deadline for ${id}`).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      }
+    });
+
+    it('penalties reference EUR amounts', () => {
+      const ids = getAvailableCheckIds();
+      for (const id of ids) {
+        const expl = getExplanation(id);
+        expect(expl!.penalty, `Penalty for ${id} should mention EUR`).toMatch(/€/);
+      }
+    });
+  });
+});

package/src/domain/scanner/finding-explainer.ts

@@ -0,0 +1,73 @@
+/**
+ * US-S05-07: Finding Explanations — static mapping check_id → explanation.
+ *
+ * Enriches findings with article reference, penalty, deadline, and business impact.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Finding, FindingExplanation } from '../../types/common.types.js';
+
+export type { FindingExplanation } from '../../types/common.types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const EXPLANATIONS_PATH = resolve(__dirname, '../../data/finding-explanations.json');
+
+let cache: Record<string, FindingExplanation> | null = null;
+
+const loadExplanations = (): Record<string, FindingExplanation> => {
+  if (cache) return cache;
+  const raw = readFileSync(EXPLANATIONS_PATH, 'utf-8');
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  // Filter out $schema/$comment keys
+  const result: Record<string, FindingExplanation> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key.startsWith('$')) continue;
+    result[key] = value as FindingExplanation;
+  }
+  cache = result;
+  return result;
+};
+
+/**
+ * Normalize a check_id for lookup: strip layer prefix, handle l3-banned-* pattern.
+ */
+const normalizeCheckId = (checkId: string): string => {
+  // l3-banned-{package} → l3-banned-package (generic)
+  if (checkId.startsWith('l3-banned-')) return 'l3-banned-package';
+  // l4-nhi-{category} → l4-nhi-secret (generic)
+  if (checkId.startsWith('l4-nhi-') && checkId !== 'l4-nhi-clean') return 'l4-nhi-secret';
+  return checkId;
+};
+
+/**
+ * Look up the explanation for a given check_id.
+ */
+export const getExplanation = (checkId: string): FindingExplanation | undefined => {
+  const explanations = loadExplanations();
+  const normalized = normalizeCheckId(checkId);
+  return explanations[normalized];
+};
+
+/**
+ * Enrich a single finding with its explanation.
+ */
+export const explainFinding = (finding: Finding): Finding & { explanation?: FindingExplanation } => {
+  const explanation = getExplanation(finding.checkId);
+  if (!explanation) return finding;
+  return { ...finding, explanation };
+};
+
+/**
+ * Enrich an array of findings with explanations.
+ */
+export const explainFindings = (findings: readonly Finding[]): (Finding & { explanation?: FindingExplanation })[] => {
+  return findings.map(explainFinding);
+};
+
+/**
+ * Get all available check_ids in the explanations database.
+ */
+export const getAvailableCheckIds = (): string[] => {
+  return Object.keys(loadExplanations());
+};

package/src/domain/scanner/fix-diff-builder.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { buildFixDiff, buildCodeContext } from './fix-diff-builder.js';
+
+describe('buildCodeContext', () => {
+  it('extracts surrounding lines with highlight', () => {
+    const content = Array.from({ length: 20 }, (_, i) => `line ${i + 1}`).join('\n');
+    const ctx = buildCodeContext(content, 10);
+    expect(ctx.highlightLine).toBe(10);
+    expect(ctx.startLine).toBe(5);
+    expect(ctx.lines.length).toBe(11);
+  });
+});
+
+// --- Bare LLM (now returns undefined — info findings have no fix diff) ---
+
+describe('buildFixDiff — bare LLM', () => {
+  it('returns undefined for bare-llm (info findings have no fix)', () => {
+    const content = "import OpenAI from 'openai';\nconst client = new OpenAI();";
+    const diff = buildFixDiff(content, 2, 'src/ai.ts', 'l4-bare-llm');
+    expect(diff).toBeUndefined();
+  });
+
+  it('returns undefined for ext-semgrep bare-call', () => {
+    const content = "const client = new OpenAI();";
+    const diff = buildFixDiff(content, 1, 'src/ai.ts', 'ext-semgrep-complior-bare-call');
+    expect(diff).toBeUndefined();
+  });
+});
+
+// --- NHI (secrets) ---
+
+describe('buildFixDiff — NHI', () => {
+  it('replaces TS secret with process.env', () => {
+    const content = "const API_KEY = 'sk-1234567890abcdef';";
+    const diff = buildFixDiff(content, 1, 'src/config.ts', 'l4-nhi-openai-key');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('process.env.API_KEY');
+    expect(diff!.after[0]).not.toContain('sk-');
+  });
+
+  it('replaces Python secret with os.environ.get', () => {
+    const content = 'API_KEY = "sk-1234567890abcdef"';
+    const diff = buildFixDiff(content, 1, 'config.py', 'l4-nhi-generic-secret');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain("os.environ.get('API_KEY'");
+    expect(diff!.importLine).toBe('import os');
+  });
+
+  it('replaces connection string with env var', () => {
+    const content = "const db = 'postgresql://user:pass@localhost/mydb';";
+    const diff = buildFixDiff(content, 1, 'src/db.ts', 'l4-nhi-connection-string');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('process.env.DATABASE_URL');
+  });
+
+  it('replaces single-line private key with env var (TS)', () => {
+    const content = "const key = '-----BEGIN RSA PRIVATE KEY----- ...';";
+    const diff = buildFixDiff(content, 1, 'src/auth.ts', 'l4-nhi-private-key');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('process.env.KEY');
+  });
+
+  it('replaces multi-line private key with env var (Python)', () => {
+    const lines = [
+      'PRIVATE_KEY = """-----BEGIN RSA PRIVATE KEY-----',
+      'MIIEpAIBAAKCAQEA0Z3VS5JJcds3xfn',
+      '-----END RSA PRIVATE KEY-----"""',
+    ];
+    const content = lines.join('\n');
+    const diff = buildFixDiff(content, 1, 'src/auth.py', 'l4-nhi-private-key');
+    expect(diff).toBeDefined();
+    expect(diff!.before).toHaveLength(3);
+    expect(diff!.after).toHaveLength(1);
+    expect(diff!.after[0]).toContain("os.environ.get('PRIVATE_KEY'");
+    expect(diff!.importLine).toBe('import os');
+  });
+
+  it('skips l4-nhi-clean', () => {
+    const content = "const x = process.env.KEY ?? '';";
+    const diff = buildFixDiff(content, 1, 'src/config.ts', 'l4-nhi-clean');
+    expect(diff).toBeUndefined();
+  });
+
+  it('replaces object property secret with process.env', () => {
+    const content = "  openai: 'sk-proj-aB3cD4eF5gH6iJ7kL8mN9oP0',";
+    const diff = buildFixDiff(content, 1, 'src/config.ts', 'l4-nhi-api_key');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('process.env.OPENAI');
+    expect(diff!.after[0]).not.toContain('sk-');
+  });
+
+  it('skips lines already using process.env', () => {
+    const content = "  apiKey: process.env.ANTHROPIC_API_KEY,";
+    const diff = buildFixDiff(content, 1, 'src/config.ts', 'l4-nhi-api_key');
+    expect(diff).toBeUndefined();
+  });
+});
+
+// --- Security risk ---
+
+describe('buildFixDiff — security risk', () => {
+  it('replaces pickle.load with json.load', () => {
+    const content = 'model = pickle.load(f)';
+    const diff = buildFixDiff(content, 1, 'ml/model.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('json.load(f)');
+    expect(diff!.importLine).toBe('import json');
+  });
+
+  it('replaces hashlib.md5 with hashlib.sha256', () => {
+    const content = 'h = hashlib.md5(data)';
+    const diff = buildFixDiff(content, 1, 'utils.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('hashlib.sha256');
+  });
+
+  it('replaces verify=False with verify=True', () => {
+    const content = 'r = requests.get(url, verify=False)';
+    const diff = buildFixDiff(content, 1, 'api.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('verify=True');
+  });
+
+  it('replaces shell=True with shell=False', () => {
+    const content = 'subprocess.run(cmd, shell=True)';
+    const diff = buildFixDiff(content, 1, 'run.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('shell=False');
+  });
+
+  it('disables eval()', () => {
+    const content = 'const result = eval(userInput);';
+    const diff = buildFixDiff(content, 1, 'src/app.ts', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('COMPLIOR: eval() disabled');
+    expect(diff!.after[0]).toContain('undefined');
+  });
+
+  it('replaces rejectUnauthorized: false', () => {
+    const content = '  rejectUnauthorized: false,';
+    const diff = buildFixDiff(content, 1, 'src/tls.ts', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('rejectUnauthorized: true');
+  });
+
+  it('adds weights_only to torch.load', () => {
+    const content = 'model = torch.load(path)';
+    const diff = buildFixDiff(content, 1, 'ml/train.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('weights_only=True');
+  });
+
+  it('disables new Function()', () => {
+    const content = 'const fn = new Function("return 1")';
+    const diff = buildFixDiff(content, 1, 'src/dyn.ts', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('COMPLIOR: new Function() disabled');
+  });
+
+  it('replaces os.system with subprocess.run', () => {
+    const content = 'os.system(cmd)';
+    const diff = buildFixDiff(content, 1, 'deploy.py', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('subprocess.run');
+    expect(diff!.importLine).toBe('import subprocess');
+  });
+
+  it('falls back to NHI for hardcoded secret patterns', () => {
+    const content = "  openai: 'sk-proj-aB3cD4eF5gH6iJ7kL8mN9oP0',";
+    const diff = buildFixDiff(content, 1, 'src/config.ts', 'l4-security-risk');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('process.env.');
+    expect(diff!.after[0]).not.toContain('sk-');
+  });
+
+  it('skips process.env references even for security-risk', () => {
+    const content = "  apiKey: process.env.ANTHROPIC_API_KEY,";
+    const diff = buildFixDiff(content, 1, 'src/chat.ts', 'l4-security-risk');
+    expect(diff).toBeUndefined();
+  });
+});
+
+// --- Error handling ---
+
+describe('buildFixDiff — error handling', () => {
+  it('wraps single-line TS LLM call in try/catch', () => {
+    const content = '  const r = await client.messages.create({ model: "claude-3" });';
+    const diff = buildFixDiff(content, 1, 'src/chat.ts', 'l4-ast-missing-error-handling');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('try {');
+    expect(diff!.after.some(l => l.includes('catch (err)'))).toBe(true);
+    expect(diff!.after.some(l => l.includes('throw err'))).toBe(true);
+  });
+
+  it('wraps multi-line TS LLM call', () => {
+    const lines = [
+      '  const r = await client.messages.create({',
+      '    model: "claude-3",',
+      '    messages: [{ role: "user", content: "hi" }],',
+      '  });',
+    ];
+    const content = lines.join('\n');
+    const diff = buildFixDiff(content, 1, 'src/chat.ts', 'l4-ast-missing-error-handling');
+    expect(diff).toBeDefined();
+    expect(diff!.before).toHaveLength(4);
+    expect(diff!.after[0]).toContain('try {');
+    expect(diff!.after[diff!.after.length - 1]).toContain('}');
+  });
+
+  it('wraps Python LLM call in try/except', () => {
+    const content = '    response = client.chat.completions.create(model="gpt-4")';
+    const diff = buildFixDiff(content, 1, 'src/agent.py', 'l4-ast-missing-error-handling');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('try:');
+    expect(diff!.after.some(l => l.includes('except Exception'))).toBe(true);
+    expect(diff!.after.some(l => l.includes('raise'))).toBe(true);
+  });
+
+  it('wraps images.generate in try/catch', () => {
+    const content = '  const r = await openai.images.generate({ prompt: "cat" });';
+    const diff = buildFixDiff(content, 1, 'src/gen.ts', 'l4-ast-missing-error-handling');
+    expect(diff).toBeDefined();
+    expect(diff!.after[0]).toContain('try {');
+  });
+});
+
+// --- Banned dep ---
+
+describe('buildFixDiff — banned dep', () => {
+  it('removes banned dep from package.json (with trailing comma)', () => {
+    const content = [
+      '{',
+      '  "dependencies": {',
+      '    "emotion-recognition": "^1.0.0",',
+      '    "express": "^4.18.0"',
+      '  }',
+      '}',
+    ].join('\n');
+    const diff = buildFixDiff(content, 0, 'package.json', 'l3-banned-emotion-recognition');
+    expect(diff).toBeDefined();
+    expect(diff!.before).toEqual(['    "emotion-recognition": "^1.0.0",']);
+    expect(diff!.after).toEqual([]);
+  });
+
+  it('removes last entry and cleans trailing comma from previous line', () => {
+    const content = [
+      '{',
+      '  "dependencies": {',
+      '    "express": "^4.18.0",',
+      '    "emotion-recognition": "^1.0.0"',
+      '  }',
+      '}',
+    ].join('\n');
+    const diff = buildFixDiff(content, 0, 'package.json', 'l3-banned-emotion-recognition');
+    expect(diff).toBeDefined();
+    expect(diff!.after.length).toBeLessThan(diff!.before.length);
+  });
+
+  it('removes banned dep from requirements.txt', () => {
+    const content = 'flask==2.3.0\nemotion-recognition==1.0.0\nrequests==2.31.0';
+    const diff = buildFixDiff(content, 0, 'requirements.txt', 'l3-banned-emotion-recognition');
+    expect(diff).toBeDefined();
+    expect(diff!.before).toEqual(['emotion-recognition==1.0.0']);
+    expect(diff!.after).toEqual([]);
+  });
+
+  it('returns undefined when package not found in file', () => {
+    const content = '{ "dependencies": { "express": "^4.0.0" } }';
+    const diff = buildFixDiff(content, 0, 'package.json', 'l3-banned-nonexistent');
+    expect(diff).toBeUndefined();
+  });
+});