@complior/engine 0.9.0

package/src/domain/scanner/checks/permission-scanner.test.ts

@@ -0,0 +1,279 @@
+import { describe, it, expect } from 'vitest';
+import { createScanFile, createScanCtx } from '../../../test-helpers/factories.js';
+import { checkPermissions } from './permission-scanner.js';
+import { scanPermissionsDetailed } from '../../passport/discovery/permission-scanner.js';
+
+const createPassportManifest = (tools: readonly string[] = []): string =>
+  JSON.stringify({
+    name: 'test-agent',
+    version: '1.0.0',
+    permissions: { tools },
+  });
+
+// --- Tests ---
+
+describe('checkPermissions', () => {
+  it('skips when no passport found', () => {
+    const ctx = createScanCtx([
+      createScanFile('src/agent.ts', 'const x = 1;'),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe('skip');
+  });
+
+  it('passes when no tools and passport tools empty', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile('src/index.ts', 'console.log("hello");'),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe('pass');
+  });
+
+  it('detects undeclared LangChain StructuredTool', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.ts',
+        `class SearchTool extends StructuredTool {
+  name = 'search';
+}`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].type === 'fail' && undeclared[0].severity).toBe('high');
+  });
+
+  it('detects undeclared OpenAI function definition', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/agent.ts',
+        `const tools = [{
+  function: { name: 'get_weather', parameters: {} }
+}];`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('get_weather');
+  });
+
+  it('detects undeclared Anthropic tool definition', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.ts',
+        `const tools = [{ name: 'calculator', input_schema: { type: 'object' } }];`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('calculator');
+  });
+
+  it('detects undeclared MCP server.tool() registration', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/server.ts',
+        `server.tool('read_file', { path: z.string() }, async (params) => {});`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('read_file');
+  });
+
+  it('detects undeclared CrewAI tool', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.py',
+        `search = Tool(name='web_search', description='Search the web')`,
+        '.py',
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('web_search');
+  });
+
+  it('reports unused declared permission', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest(['delete_user', 'send_email'])),
+      createScanFile('src/index.ts', 'console.log("no tools here");'),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const unused = results.filter((r) => r.type === 'fail' && r.checkId === 'unused-declared-permission');
+    expect(unused).toHaveLength(2);
+    expect(unused[0].type === 'fail' && unused[0].severity).toBe('low');
+  });
+
+  it('passes when discovered matches declared', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest(['read_file'])),
+      createScanFile(
+        'src/server.ts',
+        `server.tool('read_file', {}, async () => {});`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe('pass');
+  });
+
+  it('handles multiple undeclared tools', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.ts',
+        `server.tool('tool_a', {}, async () => {});
+server.tool('tool_b', {}, async () => {});
+server.tool('tool_c', {}, async () => {});`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared).toHaveLength(3);
+  });
+
+  it('reports both undeclared and unused in same scan', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest(['old_tool'])),
+      createScanFile(
+        'src/server.ts',
+        `server.tool('new_tool', {}, async () => {});`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    const unused = results.filter((r) => r.type === 'fail' && r.checkId === 'unused-declared-permission');
+    expect(undeclared).toHaveLength(1);
+    expect(unused).toHaveLength(1);
+  });
+
+  it('handles multiple passports independently', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/agent1-manifest.json', createPassportManifest([])),
+      createScanFile('.complior/agents/agent2-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/server.ts',
+        `server.tool('read_file', {}, async () => {});`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    // Each passport should report undeclared independently
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared).toHaveLength(2);
+  });
+
+  it('normalizes tool names (case-insensitive, strips Tool suffix)', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest(['search'])),
+      createScanFile(
+        'src/tools.ts',
+        `class SearchTool extends StructuredTool {
+  name = 'search';
+}`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    // 'SearchTool' normalizes to 'search', matching declared 'search'
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe('pass');
+  });
+
+  it('detects undeclared Vercel AI tool', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.ts',
+        `import { tool } from 'ai';
+const myTool = tool('my_tool', { execute: async () => {} });`,
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('my_tool');
+  });
+
+  it('detects undeclared generic Python @tool decorator', () => {
+    const ctx = createScanCtx([
+      createScanFile('.complior/agents/test-manifest.json', createPassportManifest([])),
+      createScanFile(
+        'src/tools.py',
+        `@tool()
+def search_web(query: str):
+    return results`,
+        '.py',
+      ),
+    ]);
+
+    const results = checkPermissions(ctx);
+
+    const undeclared = results.filter((r) => r.type === 'fail' && r.checkId === 'undeclared-permission');
+    expect(undeclared.length).toBeGreaterThanOrEqual(1);
+    expect(undeclared[0].message).toContain('search_web');
+  });
+
+  it('detects file operations in data access', () => {
+    const ctx = createScanCtx([
+      createScanFile('src/loader.ts', `const data = readFileSync('./config.json');
+writeFile('output.txt', result);`),
+    ]);
+
+    const detailed = scanPermissionsDetailed(ctx);
+
+    expect(detailed.dataAccess.read).toContain('filesystem');
+    expect(detailed.dataAccess.write).toContain('filesystem');
+  });
+
+  it('detects API calls in data access', () => {
+    const ctx = createScanCtx([
+      createScanFile('src/client.ts', `const res = await fetch('https://api.example.com/data');
+const users = await axios.get('/users');`),
+    ]);
+
+    const detailed = scanPermissionsDetailed(ctx);
+
+    expect(detailed.dataAccess.read).toContain('network');
+  });
+});

package/src/domain/scanner/checks/permission-scanner.ts

@@ -0,0 +1,90 @@
+import type { CheckResult } from '../../../types/common.types.js';
+import type { ScanContext } from '../../../ports/scanner.port.js';
+import { scanPermissionsDetailed } from '../../passport/discovery/permission-scanner.js';
+import { filterPassportManifests } from '../../passport/builder/manifest-files.js';
+
+const CHECK_ID_UNDECLARED = 'undeclared-permission';
+const CHECK_ID_UNUSED = 'unused-declared-permission';
+const ARTICLE_REF = 'Art. 26(4)';
+const OBLIGATION_ID = 'eu-ai-act-OBL-011';
+
+const normalizeName = (name: string): string =>
+  name.toLowerCase().replace(/(?:_tool|tool)$/, '');
+
+const parseDeclaredTools = (content: string): readonly string[] => {
+  try {
+    const manifest = JSON.parse(content) as Record<string, unknown>;
+    const permissions = manifest.permissions as Record<string, unknown> | undefined;
+    return Array.isArray(permissions?.tools)
+      ? (permissions.tools as string[]).filter((t): t is string => typeof t === 'string')
+      : [];
+  } catch {
+    return [];
+  }
+};
+
+export const checkPermissions = (ctx: ScanContext): readonly CheckResult[] => {
+  const passportFiles = filterPassportManifests(ctx.files);
+
+  if (passportFiles.length === 0) {
+    return [{
+      type: 'skip',
+      checkId: CHECK_ID_UNDECLARED,
+      reason: 'No passport found',
+    }];
+  }
+
+  const { toolsDetailed } = scanPermissionsDetailed(ctx);
+  const results: CheckResult[] = [];
+
+  for (const file of passportFiles) {
+    const declaredTools = parseDeclaredTools(file.content);
+    const declaredNormalized = new Set(declaredTools.map(normalizeName));
+    const discoveredNormalized = new Map(
+      toolsDetailed.map((tool) => [normalizeName(tool.name), tool] as const),
+    );
+
+    // Undeclared: discovered in code but not in passport
+    for (const [normalized, tool] of discoveredNormalized) {
+      if (!declaredNormalized.has(normalized)) {
+        results.push({
+          type: 'fail',
+          checkId: CHECK_ID_UNDECLARED,
+          message: `Tool '${tool.name}' (${tool.framework}) used in code but not declared in Agent Passport — ${ARTICLE_REF}`,
+          severity: 'high',
+          obligationId: OBLIGATION_ID,
+          articleReference: ARTICLE_REF,
+          file: tool.file,
+          line: tool.line,
+          fix: `Add '${tool.name}' to permissions.tools[] in your Agent Passport`,
+        });
+      }
+    }
+
+    // Unused: declared in passport but not found in code
+    for (const declared of declaredTools) {
+      if (!discoveredNormalized.has(normalizeName(declared))) {
+        results.push({
+          type: 'fail',
+          checkId: CHECK_ID_UNUSED,
+          message: `Tool '${declared}' declared in Agent Passport but not found in code — ${ARTICLE_REF}`,
+          severity: 'low',
+          obligationId: OBLIGATION_ID,
+          articleReference: ARTICLE_REF,
+          fix: `Remove '${declared}' from permissions.tools[] or implement it in code`,
+        });
+      }
+    }
+  }
+
+  // All match → pass
+  if (results.length === 0) {
+    return [{
+      type: 'pass',
+      checkId: CHECK_ID_UNDECLARED,
+      message: `All tool permissions match between code and Agent Passport — ${ARTICLE_REF}`,
+    }];
+  }
+
+  return results;
+};

package/src/domain/scanner/checks/presence-check-factory.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest';
+import { createScanFile, createScanCtx } from '../../../test-helpers/factories.js';
+import { DOCUMENT_VALIDATORS } from '../validators.js';
+import {
+  ALL_PRESENCE_CONFIGS,
+  createPresenceCheck,
+} from './presence-check-factory.js';
+
+/**
+ * Content keyword samples for each checkId — used in content-match tests.
+ * Avoids fragile regex-to-text conversion by using known-good keywords.
+ */
+const CONTENT_SAMPLES: Record<string, string> = {
+  'fria': 'fundamental rights impact assessment',
+  'art5-screening': 'prohibited practices screening',
+  'technical-documentation': 'technical documentation for the AI system',
+  'incident-report': 'serious incident report',
+  'declaration-of-conformity': 'declaration of conformity',
+  'monitoring-policy': 'post-market monitoring policy',
+  'worker-notification': 'worker notification about AI systems',
+  'risk-management': 'risk management system for the AI application',
+  'data-governance': 'data governance policy and quality metrics',
+  'qms': 'quality management system for AI compliance',
+  'instructions-for-use': 'instructions for use including capabilities and limitations',
+};
+
+/**
+ * Map checkId → validator document name where they differ.
+ */
+const VALIDATOR_NAME: Record<string, string> = {
+  'technical-documentation': 'tech-documentation',
+  'declaration-of-conformity': 'declaration-conformity',
+};
+
+/**
+ * Data-driven tests for all 7 EU AI Act document presence checks.
+ * Each config is tested for: filename match, generated doc match,
+ * content keyword match, and failure when nothing found.
+ */
+describe.each(ALL_PRESENCE_CONFIGS)(
+  'presence check: $checkId',
+  (config) => {
+    const check = createPresenceCheck(config);
+
+    it('passes when matching file exists by name', () => {
+      // Get the first filename from validators.ts (single source of truth)
+      const validatorName = VALIDATOR_NAME[config.checkId] ?? config.checkId;
+      const validator = DOCUMENT_VALIDATORS.find((v) => v.document === validatorName);
+      const filename = validator?.file_patterns[0] ?? `${config.checkId}.md`;
+
+      const ctx = createScanCtx([
+        createScanFile(filename, `# ${config.docLabel}`),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('pass');
+      expect(results[0].checkId).toBe(config.checkId);
+    });
+
+    it('passes when generated doc found in .complior/documents/', () => {
+      const ctx = createScanCtx([
+        createScanFile(`.complior/documents/${config.checkId}-2026.md`, `# ${config.docLabel}`),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('pass');
+    });
+
+    it('passes when generated doc found in docs/compliance/', () => {
+      const ctx = createScanCtx([
+        createScanFile(`docs/compliance/${config.checkId}.md`, `# ${config.docLabel}`),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('pass');
+    });
+
+    it('passes when docs/ contains relevant content keyword', () => {
+      const keyword = CONTENT_SAMPLES[config.checkId] ?? config.docLabel;
+      const ctx = createScanCtx([
+        createScanFile('docs/compliance-overview.md', `This document covers ${keyword}`),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('pass');
+    });
+
+    it('fails when no matching document found', () => {
+      const ctx = createScanCtx([
+        createScanFile('README.md', '# My Project\nA simple web app'),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('fail');
+      if (results[0].type === 'fail') {
+        expect(results[0].severity).toBe(config.severity);
+        expect(results[0].obligationId).toBe(config.obligationId);
+        expect(results[0].articleReference).toBe(config.articleRef);
+        expect(results[0].fix).toBeDefined();
+      }
+    });
+
+    it('fails when docs/ has unrelated content', () => {
+      const ctx = createScanCtx([
+        createScanFile('docs/setup.md', '# Setup Guide\nRun npm install'),
+      ]);
+
+      const results = check(ctx);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].type).toBe('fail');
+    });
+  },
+);