@complior/engine 0.9.0

package/src/services/passport-documents.ts

@@ -0,0 +1,258 @@
+/**
+ * Passport document generation sub-module.
+ * Handles: FRIA, worker notification, policy, doc-by-type, all-docs, export.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { AgentPassport } from '../types/passport.types.js';
+import { createEvidence } from '../domain/scanner/evidence.js';
+import { generateFria } from '../domain/fria/fria-generator.js';
+import type { FriaResult } from '../domain/fria/fria-generator.js';
+import { exportPassport as exportPassportFn } from '../domain/passport/export/index.js';
+import type { ExportFormat, ExportResult } from '../domain/passport/export/index.js';
+import { generateWorkerNotification as generateWorkerNotificationDoc } from '../domain/documents/worker-notification-generator.js';
+import type { WorkerNotificationResult } from '../domain/documents/worker-notification-generator.js';
+import { generatePolicy as generatePolicyDoc } from '../domain/documents/policy-generator.js';
+import type { PolicyResult } from '../domain/documents/policy-generator.js';
+import { generateDocument, ALL_DOC_TYPES, TEMPLATE_FILE_MAP } from '../domain/documents/document-generator.js';
+import type { DocType, DocResult } from '../domain/documents/document-generator.js';
+import type { IndustryId } from '../data/industry-patterns.js';
+import { INDUSTRY_TEMPLATE_MAP } from '../data/industry-patterns.js';
+import type { PassportServiceDeps } from './passport-service.js';
+import { ensureTemplate, saveDocumentReport, updatePassportCompliance } from './passport-service-utils.js';
+
+export interface PassportDocumentOps {
+  readonly showPassport: (name: string, projectPath?: string) => Promise<AgentPassport | null>;
+}
+
+export const createPassportDocuments = (deps: PassportServiceDeps, ops: PassportDocumentOps) => {
+  const { showPassport } = ops;
+
+  const generateFriaReport = async (
+    name: string,
+    projectPath?: string,
+    options?: { organization?: string; assessor?: string; impact?: string; mitigation?: string; approval?: string },
+  ): Promise<(FriaResult & { savedPath: string }) | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    const template = await ensureTemplate(deps, 'fria.md');
+    const result = generateFria({
+      manifest,
+      template,
+      organization: options?.organization,
+      assessor: options?.assessor,
+      impact: options?.impact,
+      mitigation: options?.mitigation,
+      approval: options?.approval,
+    });
+
+    const savedPath = await saveDocumentReport(deps, name, 'fria', result.markdown, 'fria', projectPath);
+
+    const path = projectPath ?? deps.getProjectPath();
+    const jsonPath = join(path, '.complior', 'reports', `fria-${name}.json`);
+    await writeFile(jsonPath, JSON.stringify(result.structured, null, 2));
+
+    const today = new Date().toISOString().slice(0, 10);
+    await updatePassportCompliance(deps, name, { fria_completed: true, fria_date: today }, projectPath);
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('fria.generated', { name, savedPath }, name);
+    }
+
+    return { ...result, savedPath };
+  };
+
+  const generateWorkerNotification = async (
+    name: string,
+    projectPath?: string,
+    options?: {
+      companyName?: string;
+      contactName?: string;
+      contactEmail?: string;
+      contactPhone?: string;
+      deploymentDate?: string;
+      affectedRoles?: string;
+      impactDescription?: string;
+    },
+  ): Promise<(WorkerNotificationResult & { savedPath: string }) | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    const template = await ensureTemplate(deps, 'worker-notification.md');
+    const result = generateWorkerNotificationDoc({
+      manifest,
+      template,
+      companyName: options?.companyName,
+      contactName: options?.contactName,
+      contactEmail: options?.contactEmail,
+      contactPhone: options?.contactPhone,
+      deploymentDate: options?.deploymentDate,
+      affectedRoles: options?.affectedRoles,
+      impactDescription: options?.impactDescription,
+    });
+
+    const savedPath = await saveDocumentReport(
+      deps, name, 'worker-notification', result.markdown, 'worker-notification', projectPath,
+    );
+
+    const today = new Date().toISOString().slice(0, 10);
+    await updatePassportCompliance(
+      deps, name,
+      { worker_notification_sent: true, worker_notification_date: today },
+      projectPath,
+    );
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('worker_notification.generated', { name, savedPath }, name);
+    }
+
+    return { ...result, savedPath };
+  };
+
+  const exportPassportToFormat = async (
+    name: string,
+    format: ExportFormat,
+    projectPath?: string,
+  ): Promise<(ExportResult & { savedPath: string }) | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    const result = exportPassportFn(manifest, format);
+
+    const path = projectPath ?? deps.getProjectPath();
+    const exportsDir = join(path, '.complior', 'exports');
+    await mkdir(exportsDir, { recursive: true });
+    const savedPath = join(exportsDir, `${name}-${format}.json`);
+    await writeFile(savedPath, JSON.stringify(result.data, null, 2));
+
+    if (deps.evidenceStore) {
+      const evidence = createEvidence(name, 'export', 'export', { file: savedPath, snippet: `format: ${format}` });
+      await deps.evidenceStore.append([evidence], randomUUID());
+    }
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('passport.exported', { name, format, savedPath }, name);
+    }
+
+    return { ...result, savedPath };
+  };
+
+  const generatePolicy = async (
+    name: string,
+    industry: IndustryId,
+    projectPath?: string,
+    options?: { organization?: string; approver?: string },
+  ): Promise<(PolicyResult & { savedPath: string }) | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    if (!deps.loadPolicyTemplate) {
+      throw new Error('loadPolicyTemplate dependency not provided');
+    }
+    const templateFile = INDUSTRY_TEMPLATE_MAP[industry];
+    const template = await deps.loadPolicyTemplate(templateFile);
+
+    const result = generatePolicyDoc({
+      manifest,
+      template,
+      industry,
+      organization: options?.organization,
+      approver: options?.approver,
+    });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const savedPath = await saveDocumentReport(
+      deps, timestamp, `${industry}-ai-policy`, result.markdown, 'policy',
+      projectPath, 'policies', { industry },
+    );
+
+    const today = new Date().toISOString().slice(0, 10);
+    await updatePassportCompliance(deps, name, { policy_generated: true, policy_date: today }, projectPath);
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('policy.generated', { name, industry, savedPath }, name);
+    }
+
+    return { ...result, savedPath };
+  };
+
+  const generateDocByType = async (
+    name: string,
+    docType: DocType,
+    projectPath?: string,
+    options?: { organization?: string },
+  ): Promise<(DocResult & { savedPath: string }) | null> => {
+    const manifest = await showPassport(name, projectPath);
+    if (manifest === null) return null;
+
+    const templateFile = TEMPLATE_FILE_MAP[docType];
+    const template = await ensureTemplate(deps, templateFile);
+
+    const result = generateDocument({
+      manifest,
+      template,
+      docType,
+      organization: options?.organization,
+    });
+
+    const savedPath = await saveDocumentReport(
+      deps, name, docType, result.markdown, 'document', projectPath,
+      'documents', { docType },
+    );
+
+    if (deps.auditStore) {
+      await deps.auditStore.append('document.generated', { name, docType, savedPath }, name);
+    }
+
+    return { ...result, savedPath };
+  };
+
+  const generateAllDocs = async (
+    name: string,
+    projectPath?: string,
+    options?: { organization?: string },
+  ): Promise<{ generated: { docType: string; savedPath: string }[]; errors: string[] }> => {
+    const generated: { docType: string; savedPath: string }[] = [];
+    const errors: string[] = [];
+
+    for (const docType of ALL_DOC_TYPES) {
+      try {
+        const result = await generateDocByType(name, docType, projectPath, options);
+        if (result) {
+          generated.push({ docType, savedPath: result.savedPath });
+        } else {
+          errors.push(`${docType}: passport not found`);
+        }
+      } catch (e) {
+        errors.push(`${docType}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+
+    try {
+      const fria = await generateFriaReport(name, projectPath, { organization: options?.organization });
+      if (fria) generated.push({ docType: 'fria', savedPath: fria.savedPath });
+    } catch (e) {
+      errors.push(`fria: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    try {
+      const wn = await generateWorkerNotification(name, projectPath, { companyName: options?.organization });
+      if (wn) generated.push({ docType: 'worker-notification', savedPath: wn.savedPath });
+    } catch (e) {
+      errors.push(`worker-notification: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    return { generated, errors };
+  };
+
+  return Object.freeze({
+    generateFriaReport,
+    generateWorkerNotification,
+    exportPassportToFormat,
+    generatePolicy,
+    generateDocByType,
+    generateAllDocs,
+  });
+};

package/src/services/passport-service-utils.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared utilities for passport service sub-modules.
+ * Extracted from passport-service.ts for SRP compliance.
+ */
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { AgentPassport } from '../types/passport.types.js';
+import { parsePassport } from '../types/passport-schemas.js';
+import { createEvidence, type EvidenceSource } from '../domain/scanner/evidence.js';
+import { loadOrCreateKeyPair, signPassport } from '../domain/passport/crypto-signer.js';
+import type { PassportServiceDeps } from './passport-service.js';
+
+export const ensureTemplate = async (deps: PassportServiceDeps, file: string): Promise<string> => {
+  if (!deps.loadTemplate) {
+    throw new Error('loadTemplate dependency not provided');
+  }
+  return deps.loadTemplate(file);
+};
+
+export const saveDocumentReport = async (
+  deps: PassportServiceDeps,
+  name: string,
+  filePrefix: string,
+  markdown: string,
+  evidenceType: EvidenceSource,
+  projectPath?: string,
+  subDir: string = 'reports',
+  _evidenceMeta?: Record<string, unknown>,
+): Promise<string> => {
+  const path = projectPath ?? deps.getProjectPath();
+  const outDir = join(path, '.complior', subDir);
+  await mkdir(outDir, { recursive: true });
+  const savedPath = join(outDir, `${filePrefix}-${name}.md`);
+  await writeFile(savedPath, markdown);
+
+  if (deps.evidenceStore) {
+    const evidence = createEvidence(name, evidenceType, evidenceType, { file: savedPath });
+    await deps.evidenceStore.append([evidence], randomUUID());
+  }
+
+  return savedPath;
+};
+
+export const updatePassportCompliance = async (
+  deps: PassportServiceDeps,
+  name: string,
+  complianceUpdate: Partial<AgentPassport['compliance']>,
+  projectPath?: string,
+): Promise<void> => {
+  const path = projectPath ?? deps.getProjectPath();
+  const manifestPath = join(path, '.complior', 'agents', `${name}-manifest.json`);
+  try {
+    const rawManifest = await readFile(manifestPath, 'utf-8');
+    const currentManifest = parsePassport(rawManifest);
+    if (!currentManifest) return;
+
+    const updatedManifest: AgentPassport = {
+      ...currentManifest,
+      compliance: { ...currentManifest.compliance, ...complianceUpdate },
+      updated: new Date().toISOString(),
+    };
+
+    const keyPair = await loadOrCreateKeyPair();
+    const newSignature = signPassport(updatedManifest, keyPair.privateKey);
+    const resignedManifest: AgentPassport = { ...updatedManifest, signature: newSignature };
+
+    await writeFile(manifestPath, JSON.stringify(resignedManifest, null, 2));
+  } catch {
+    // Passport file doesn't exist or can't be updated — non-fatal
+  }
+};

package/src/services/passport-service.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createPassportService } from './passport-service.js';
+import type { PassportServiceDeps } from './passport-service.js';
+import type { ScanContext, FileInfo } from '../ports/scanner.port.js';
+import type { EventBusPort } from '../ports/events.port.js';
+
+
+// --- Helpers ---
+
+const createFile = (
+  relativePath: string,
+  content: string,
+  extension?: string,
+): FileInfo => ({
+  path: `/tmp/test/${relativePath}`,
+  content,
+  extension: extension ?? `.${relativePath.split('.').pop()}`,
+  relativePath,
+});
+
+const createMockDeps = (files: readonly FileInfo[] = []): PassportServiceDeps => ({
+  collectFiles: vi.fn().mockResolvedValue({
+    files,
+    projectPath: '/tmp/test',
+  } satisfies ScanContext),
+  scanner: { scan: vi.fn() },
+  events: {
+    on: vi.fn(),
+    off: vi.fn(),
+    emit: vi.fn(),
+  } as unknown as EventBusPort,
+  getProjectPath: () => '/tmp/test',
+  getLastScanResult: () => null,
+});
+
+// --- Tests ---
+
+describe('createPassportService', () => {
+  it('initPassport returns empty when no AI SDK', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'vanilla-app',
+          dependencies: { express: '4.18.0', lodash: '4.17.21' },
+        }),
+        '.json',
+      ),
+      createFile('src/index.ts', 'console.log("hello world")'),
+    ]);
+
+    const service = createPassportService(deps);
+    const result = await service.initPassport('/tmp/test');
+
+    expect(result.manifests).toEqual([]);
+    expect(result.savedPaths).toEqual([]);
+  });
+
+  it('initPassport discovers and generates passport', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'ai-bot',
+          dependencies: { openai: '4.20.0' },
+        }),
+        '.json',
+      ),
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();
+const res = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello' }],
+});`,
+      ),
+    ]);
+
+    const service = createPassportService(deps);
+    const result = await service.initPassport('/tmp/test', undefined, true);
+
+    expect(result.manifests).toHaveLength(1);
+    expect(result.manifests[0].name).toBe('ai-bot');
+    expect(result.manifests[0].agent_id).toMatch(/^ag_/);
+    expect(result.manifests[0].signature).toBeDefined();
+    expect(result.manifests[0].signature.algorithm).toBe('ed25519');
+  });
+
+  it('initPassport skips existing passport without --force', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'ai-bot',
+          dependencies: { openai: '4.20.0' },
+        }),
+        '.json',
+      ),
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();`,
+      ),
+    ]);
+
+    const service = createPassportService(deps);
+
+    // First call with force to ensure manifest exists on disk
+    await service.initPassport('/tmp/test', undefined, true);
+
+    // Second call without force — should skip
+    const result = await service.initPassport('/tmp/test');
+
+    expect(result.manifests).toHaveLength(0);
+    expect(result.skipped).toContain('ai-bot');
+  });
+
+  it('listPassports returns empty for new project', async () => {
+    const deps = createMockDeps();
+
+    const service = createPassportService(deps);
+    // The .complior/agents/ directory does not exist, so readdir will throw
+    const result = await service.listPassports('/tmp/nonexistent-project');
+
+    expect(result).toEqual([]);
+  });
+
+  it('showPassport returns null for nonexistent', async () => {
+    const deps = createMockDeps();
+
+    const service = createPassportService(deps);
+    const result = await service.showPassport('foo', '/tmp/nonexistent-project');
+
+    expect(result).toBeNull();
+  });
+
+  it('analyzeProjectAutonomy returns autonomy analysis', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'ai-app',
+          dependencies: { openai: '4.20.0' },
+        }),
+        '.json',
+      ),
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();
+const res = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello' }],
+});`,
+      ),
+    ]);
+
+    const service = createPassportService(deps);
+    const result = await service.analyzeProjectAutonomy('/tmp/test');
+
+    expect(result).toBeDefined();
+    expect(result.level).toMatch(/^L[1-5]$/);
+    expect(result.agentType).toMatch(/^(autonomous|assistive|hybrid)$/);
+    expect(result.evidence).toBeDefined();
+    expect(typeof result.evidence.human_approval_gates).toBe('number');
+    expect(typeof result.evidence.unsupervised_actions).toBe('number');
+  });
+
+  it('validatePassportByName returns null for nonexistent', async () => {
+    const deps = createMockDeps();
+
+    const service = createPassportService(deps);
+    const result = await service.validatePassportByName('nonexistent', '/tmp/test');
+
+    expect(result).toBeNull();
+  });
+
+  it('getPassportCompleteness returns null for nonexistent', async () => {
+    const deps = createMockDeps();
+
+    const service = createPassportService(deps);
+    const result = await service.getPassportCompleteness('nonexistent', '/tmp/test');
+
+    expect(result).toBeNull();
+  });
+
+  it('findAgentsForFile matches agent by source_files', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'ai-bot',
+          dependencies: { openai: '4.20.0' },
+        }),
+        '.json',
+      ),
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();
+const res = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello' }],
+});`,
+      ),
+    ]);
+
+    const service = createPassportService(deps);
+    // Create passport with source_files
+    await service.initPassport('/tmp/test', undefined, true);
+
+    // Match: file inside agent's source_files
+    const matched = await service.findAgentsForFile('/tmp/test/src/agent.ts');
+    expect(matched.length).toBeGreaterThan(0);
+    expect(matched[0].name).toBe('ai-bot');
+  });
+
+  it('findAgentsForFile returns empty for unrelated file', async () => {
+    const deps = createMockDeps([
+      createFile(
+        'package.json',
+        JSON.stringify({
+          name: 'ai-bot',
+          dependencies: { openai: '4.20.0' },
+        }),
+        '.json',
+      ),
+      createFile(
+        'src/agent.ts',
+        `import OpenAI from 'openai';
+const client = new OpenAI();`,
+      ),
+    ]);
+
+    const service = createPassportService(deps);
+    await service.initPassport('/tmp/test', undefined, true);
+
+    // No match: completely unrelated file
+    const matched = await service.findAgentsForFile('/tmp/test/docs/readme.md');
+    expect(matched).toHaveLength(0);
+  });
+
+  it('findAgentsForFile returns empty when no agents dir', async () => {
+    const deps = createMockDeps();
+
+    const service = createPassportService(deps);
+    const matched = await service.findAgentsForFile('/tmp/nonexistent/src/index.ts');
+    expect(matched).toEqual([]);
+  });
+});