@complior/engine 0.9.0

package/src/onboarding/onboarding.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { QUESTION_BLOCKS, getAllBlockIds } from './questions.js';
+import { buildProfile, computeRiskLevel, computeApplicableObligations, validateProfile } from './profile.js';
+import type { AutoDetectResult } from './auto-detect.js';
+
+const mockAutoDetect: AutoDetectResult = {
+  language: 'TypeScript',
+  framework: 'Next.js',
+  cicd: 'github-actions',
+  deployment: 'Docker',
+  aiLibraries: ['OpenAI SDK', 'Vercel AI SDK'],
+  hasDockerCompose: true,
+  hasEnvExample: true,
+  detectedModels: ['gpt-4o'],
+  confidence: 0.83,
+};
+
+describe('Onboarding Questions', () => {
+  it('has 3 question blocks', () => {
+    expect(QUESTION_BLOCKS).toHaveLength(3);
+    expect(getAllBlockIds()).toEqual(['role', 'business', 'data']);
+  });
+
+  it('every block has at least one question', () => {
+    for (const block of QUESTION_BLOCKS) {
+      expect(block.questions.length).toBeGreaterThan(0);
+      for (const q of block.questions) {
+        expect(q.id).toBeTruthy();
+        expect(q.text).toBeTruthy();
+      }
+    }
+  });
+});
+
+describe('Profile Builder', () => {
+  it('builds complete profile with computed fields', () => {
+    const profile = buildProfile(mockAutoDetect, {
+      org_role: 'deployer',
+      domain: 'healthcare',
+      data_types: ['personal', 'health'],
+      data_storage: 'eu',
+    });
+
+    expect(profile.version).toBe('1.0');
+    expect(profile.autoDetected.language).toBe('TypeScript');
+    expect(profile.aiSystem.type).toBe('feature'); // default
+    expect(profile.jurisdiction.primary).toBe('EU'); // default
+    expect(profile.business.domain).toBe('healthcare');
+    expect(profile.computed.riskLevel).toBe('high');
+    expect(profile.computed.applicableObligations.length).toBeGreaterThan(15);
+    expect(profile.computed.estimatedScore).toBe(25);
+  });
+
+  it('validates correct profile', () => {
+    const profile = buildProfile(mockAutoDetect, { domain: 'general' });
+    const result = validateProfile(profile);
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects invalid profile', () => {
+    const result = validateProfile({ version: '2.0', invalid: true });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toBeDefined();
+  });
+});
+
+describe('Risk Level Computation', () => {
+  it('healthcare domain → high', () => {
+    expect(computeRiskLevel('healthcare', ['personal'], 'feature')).toBe('high');
+  });
+
+  it('biometric data → high', () => {
+    expect(computeRiskLevel('general', ['biometric'], 'feature')).toBe('high');
+  });
+
+  it('general + public data → limited', () => {
+    expect(computeRiskLevel('general', ['public'], 'feature')).toBe('limited');
+  });
+
+  it('internal + public data → minimal', () => {
+    expect(computeRiskLevel('general', ['public'], 'internal')).toBe('minimal');
+  });
+
+  it('high-risk adds extra obligations', () => {
+    const high = computeApplicableObligations('healthcare', 'high');
+    const limited = computeApplicableObligations('general', 'limited');
+    expect(high.length).toBeGreaterThan(limited.length);
+  });
+});

package/src/onboarding/profile.ts

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import type { AutoDetectResult } from './auto-detect.js';
+import riskProfileData from '../../data/onboarding/risk-profile.json' with { type: 'json' };
+
+// ── Zod validation for obligation IDs from JSON ─────────────
+const OblIdSchema = z.string().regex(/^OBL-\d{3}$/);
+const validatedRiskProfile = z.object({
+  high_risk_domains: z.array(z.string()),
+  domain_obligations: z.record(z.array(OblIdSchema)),
+  base_obligations: z.array(OblIdSchema),
+  high_risk_extra_obligations: z.array(OblIdSchema),
+}).parse(riskProfileData);
+
+export const ProjectProfileSchema = z.object({
+  version: z.literal('1.0'),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  autoDetected: z.object({
+    language: z.string(),
+    framework: z.string(),
+    cicd: z.string(),
+    deployment: z.string(),
+    aiLibraries: z.array(z.string()),
+    hasDockerCompose: z.boolean(),
+    hasEnvExample: z.boolean(),
+    detectedModels: z.array(z.string()),
+    confidence: z.number(),
+  }),
+  aiSystem: z.object({
+    type: z.enum(['feature', 'standalone', 'platform', 'internal']).default('feature'),
+    outputTypes: z.array(z.string()).default(['text']),
+  }).default({ type: 'feature', outputTypes: ['text'] }),
+  jurisdiction: z.object({
+    primary: z.string().default('EU'),
+    regulations: z.array(z.string()).default(['eu-ai-act']),
+  }).default({ primary: 'EU', regulations: ['eu-ai-act'] }),
+  organization: z.object({
+    role: z.enum(['provider', 'deployer', 'both']),
+  }),
+  business: z.object({
+    domain: z.string(),
+    companySize: z.enum(['startup', 'sme', 'enterprise']).default('startup'),
+  }),
+  data: z.object({
+    types: z.array(z.string()),
+    storage: z.enum(['eu', 'us', 'mixed']),
+  }),
+  goals: z.object({
+    priority: z.string().default('full'),
+    budget: z.enum(['minimal', 'moderate', 'full']).default('moderate'),
+  }).default({ priority: 'full', budget: 'moderate' }),
+  computed: z.object({
+    riskLevel: z.enum(['minimal', 'limited', 'high', 'unacceptable']),
+    applicableObligations: z.array(z.string()),
+    estimatedScore: z.number(),
+  }),
+});
+
+export type OnboardingProfile = z.infer<typeof ProjectProfileSchema>;
+
+export type OnboardingAnswers = Record<string, string | string[]>;
+
+const HIGH_RISK_DOMAINS = new Set(validatedRiskProfile.high_risk_domains);
+
+const DOMAIN_OBLIGATIONS: Record<string, readonly string[]> = validatedRiskProfile.domain_obligations;
+
+const BASE_OBLIGATIONS = validatedRiskProfile.base_obligations;
+
+export const computeRiskLevel = (
+  domain: string,
+  dataTypes: readonly string[],
+  systemType: string,
+): 'minimal' | 'limited' | 'high' | 'unacceptable' => {
+  if (dataTypes.includes('biometric')) return 'high';
+  if (HIGH_RISK_DOMAINS.has(domain)) return 'high';
+  if (dataTypes.includes('health') || dataTypes.includes('financial')) return 'high';
+  if (systemType === 'platform') return 'limited';
+  if (systemType === 'internal' && dataTypes.includes('public')) return 'minimal';
+  return 'limited';
+};
+
+export const computeApplicableObligations = (
+  domain: string,
+  riskLevel: string,
+): readonly string[] => {
+  const obligations = [...BASE_OBLIGATIONS];
+  const domainObs = DOMAIN_OBLIGATIONS[domain];
+  if (domainObs) obligations.push(...domainObs);
+  if (riskLevel === 'high') {
+    obligations.push(...validatedRiskProfile.high_risk_extra_obligations);
+  }
+  return obligations;
+};
+
+const answerStr = (answers: OnboardingAnswers, key: string, fallback: string): string => {
+  const v = answers[key];
+  return typeof v === 'string' ? v : fallback;
+};
+
+const answerArr = (answers: OnboardingAnswers, key: string, fallback: string[]): string[] => {
+  const v = answers[key];
+  return Array.isArray(v) ? v : fallback;
+};
+
+const SystemTypeSchema = z.enum(['feature', 'standalone', 'platform', 'internal']);
+const RoleSchema = z.enum(['provider', 'deployer', 'both']);
+const CompanySizeSchema = z.enum(['startup', 'sme', 'enterprise']);
+const StorageSchema = z.enum(['eu', 'us', 'mixed']);
+const BudgetSchema = z.enum(['minimal', 'moderate', 'full']);
+
+export const buildProfile = (
+  autoDetected: AutoDetectResult,
+  answers: OnboardingAnswers,
+): OnboardingProfile => {
+  const domain = answerStr(answers, 'domain', 'general');
+  const dataTypes = answerArr(answers, 'data_types', ['public']);
+  const systemType = answerStr(answers, 'system_type', 'feature');
+
+  const riskLevel = computeRiskLevel(domain, dataTypes, systemType);
+  const applicableObligations = computeApplicableObligations(domain, riskLevel);
+  const estimatedScore = riskLevel === 'high' ? 25 : riskLevel === 'limited' ? 40 : 60;
+
+  const now = new Date().toISOString();
+
+  return {
+    version: '1.0',
+    createdAt: now,
+    updatedAt: now,
+    autoDetected: {
+      ...autoDetected,
+      aiLibraries: [...autoDetected.aiLibraries],
+      detectedModels: [...autoDetected.detectedModels],
+    },
+    aiSystem: {
+      type: SystemTypeSchema.catch('feature').parse(systemType),
+      outputTypes: answerArr(answers, 'output_types', ['text']),
+    },
+    jurisdiction: {
+      primary: answerStr(answers, 'primary_jurisdiction', 'EU'),
+      regulations: ['eu-ai-act'],
+    },
+    organization: {
+      role: RoleSchema.catch('deployer').parse(answerStr(answers, 'org_role', 'deployer')),
+    },
+    business: {
+      domain,
+      companySize: CompanySizeSchema.catch('startup').parse(answerStr(answers, 'company_size', 'startup')),
+    },
+    data: {
+      types: dataTypes,
+      storage: StorageSchema.catch('eu').parse(answerStr(answers, 'data_storage', 'eu')),
+    },
+    goals: {
+      priority: answerStr(answers, 'priority', 'full'),
+      budget: BudgetSchema.catch('moderate').parse(answerStr(answers, 'budget', 'moderate')),
+    },
+    computed: {
+      riskLevel,
+      applicableObligations: [...applicableObligations],
+      estimatedScore,
+    },
+  };
+};
+
+export const validateProfile = (data: unknown): { valid: boolean; errors?: string[] } => {
+  const result = ProjectProfileSchema.safeParse(data);
+  if (result.success) return { valid: true };
+  return { valid: false, errors: result.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`) };
+};

package/src/onboarding/questions.ts

@@ -0,0 +1,112 @@
+export interface QuestionOption {
+  readonly value: string;
+  readonly label: string;
+}
+
+export interface QuestionBlock {
+  readonly id: string;
+  readonly title: string;
+  readonly questions: readonly Question[];
+}
+
+export interface Question {
+  readonly id: string;
+  readonly text: string;
+  readonly type: 'single' | 'multi' | 'text';
+  readonly options?: readonly QuestionOption[];
+  readonly default?: string;
+  /** Per-option explanations (value → description). Shown below the option in interactive CLI. */
+  readonly descriptions?: Readonly<Record<string, string>>;
+}
+
+export const QUESTION_BLOCKS: readonly QuestionBlock[] = [
+  {
+    id: 'role',
+    title: 'Organization Role',
+    questions: [
+      {
+        id: 'org_role',
+        text: 'Your role under EU AI Act?',
+        type: 'single',
+        options: [
+          { value: 'deployer', label: 'Deployer — we USE AI systems' },
+          { value: 'provider', label: 'Provider — we BUILD AI systems' },
+          { value: 'both', label: 'Both provider and deployer' },
+        ],
+        descriptions: {
+          deployer: 'You integrate AI APIs (OpenAI, Anthropic, Google) or use AI tools. ~10 obligations. Examples: SaaS with AI chatbot, internal AI tool, API-powered feature.',
+          provider: 'You develop, train, or rebrand AI systems under your name. ~30 obligations. Examples: AI SaaS product, model hosting, AI API provider. Art.25: if you put your brand on it, you are a provider.',
+          both: 'You build your own AI AND use third-party AI. Full obligation set.',
+        },
+        default: 'deployer',
+      },
+    ],
+  },
+  {
+    id: 'business',
+    title: 'Business Domain',
+    questions: [
+      {
+        id: 'domain',
+        text: 'Primary business domain?',
+        type: 'single',
+        options: [
+          { value: 'general', label: 'General / SaaS' },
+          { value: 'healthcare', label: 'Healthcare / Medical' },
+          { value: 'finance', label: 'Finance / Insurance' },
+          { value: 'hr', label: 'HR / Employment' },
+          { value: 'education', label: 'Education' },
+          { value: 'content', label: 'Content Generation' },
+          { value: 'customer_service', label: 'Customer Service' },
+        ],
+        descriptions: {
+          healthcare: 'Triggers HIGH RISK classification under EU AI Act.',
+          finance: 'Triggers HIGH RISK classification under EU AI Act.',
+          hr: 'Triggers HIGH RISK classification under EU AI Act.',
+          education: 'Triggers HIGH RISK classification under EU AI Act.',
+        },
+        default: 'general',
+      },
+    ],
+  },
+  {
+    id: 'data',
+    title: 'Data Handling',
+    questions: [
+      {
+        id: 'data_types',
+        text: 'What types of data does your AI process?',
+        type: 'multi',
+        options: [
+          { value: 'personal', label: 'Personal data (names, emails)' },
+          { value: 'biometric', label: 'Biometric data' },
+          { value: 'health', label: 'Health/Medical data' },
+          { value: 'financial', label: 'Financial data' },
+          { value: 'public', label: 'Public/Open data only' },
+        ],
+        descriptions: {
+          biometric: 'Triggers HIGH RISK classification.',
+          health: 'Triggers HIGH RISK classification.',
+          financial: 'Triggers HIGH RISK classification.',
+        },
+      },
+      {
+        id: 'data_storage',
+        text: 'Where is data stored?',
+        type: 'single',
+        options: [
+          { value: 'eu', label: 'EU only' },
+          { value: 'us', label: 'US only' },
+          { value: 'mixed', label: 'Mixed / Multi-region' },
+        ],
+        default: 'eu',
+      },
+    ],
+  },
+];
+
+export const getQuestionBlock = (blockId: string): QuestionBlock | undefined =>
+  QUESTION_BLOCKS.find((b) => b.id === blockId);
+
+export const getAllBlockIds = (): readonly string[] =>
+  QUESTION_BLOCKS.map((b) => b.id);

package/src/onboarding/wizard.ts

@@ -0,0 +1,66 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { autoDetect, type AutoDetectResult } from './auto-detect.js';
+import { QUESTION_BLOCKS } from './questions.js';
+import { buildProfile, validateProfile, ProjectProfileSchema, type OnboardingProfile, type OnboardingAnswers } from './profile.js';
+
+export interface WizardDeps {
+  readonly getProjectPath: () => string;
+}
+
+export interface WizardResult {
+  readonly profile: OnboardingProfile;
+  readonly autoDetected: AutoDetectResult;
+  readonly profilePath: string;
+}
+
+export const createOnboardingWizard = (deps: WizardDeps) => {
+  const { getProjectPath } = deps;
+
+  const detect = async (): Promise<AutoDetectResult> => {
+    return autoDetect(getProjectPath());
+  };
+
+  const getQuestions = () => QUESTION_BLOCKS;
+
+  const complete = async (answers: OnboardingAnswers): Promise<WizardResult> => {
+    const projectPath = getProjectPath();
+    const autoDetected = await autoDetect(projectPath);
+    const profile = buildProfile(autoDetected, answers);
+
+    // Validate
+    const validation = validateProfile(profile);
+    if (!validation.valid) {
+      throw new Error(`Invalid profile: ${validation.errors?.join(', ')}`);
+    }
+
+    // Save profile
+    const compliorDir = join(projectPath, '.complior');
+    await mkdir(compliorDir, { recursive: true });
+    const profilePath = join(compliorDir, 'profile.json');
+    await writeFile(profilePath, JSON.stringify(profile, null, 2), 'utf-8');
+
+    return Object.freeze({ profile, autoDetected, profilePath });
+  };
+
+  const loadProfile = async (): Promise<OnboardingProfile | null> => {
+    const profilePath = join(getProjectPath(), '.complior', 'profile.json');
+    const content = await readFile(profilePath, 'utf-8').catch(() => null);
+    if (!content) return null;
+
+    const parsed: unknown = JSON.parse(content);
+    const result = ProjectProfileSchema.safeParse(parsed);
+    if (!result.success) return null;
+
+    return result.data;
+  };
+
+  const hasProfile = async (): Promise<boolean> => {
+    const profile = await loadProfile();
+    return profile !== null;
+  };
+
+  return Object.freeze({ detect, getQuestions, complete, loadProfile, hasProfile });
+};
+
+export type OnboardingWizard = ReturnType<typeof createOnboardingWizard>;

package/src/output/github-issue.ts

@@ -0,0 +1,32 @@
+import type { ScanResult } from '../types/common.types.js';
+
+export const toGithubIssue = (result: ScanResult): string => {
+  const failFindings = result.findings.filter((f) => f.type === 'fail');
+  const lines: string[] = [
+    '## EU AI Act Compliance Checklist',
+    '',
+    `**Score:** ${result.score.totalScore}/100 (${result.score.zone.toUpperCase()})`,
+    `**Scanned:** ${result.scannedAt}`,
+    `**Files:** ${result.filesScanned}`,
+    '',
+    '### Findings',
+    '',
+  ];
+
+  if (failFindings.length === 0) {
+    lines.push('No violations found.');
+  } else {
+    for (const f of failFindings) {
+      const ref = f.articleReference ? ` (${f.articleReference})` : '';
+      const file = f.file ? ` — \`${f.file}\`` : '';
+      lines.push(`- [ ] **[${f.severity.toUpperCase()}]** ${f.checkId}${ref}: ${f.message}${file}`);
+      if (f.fix) {
+        lines.push(`  - Fix: ${f.fix}`);
+      }
+    }
+  }
+
+  lines.push('', '---', '*Generated by [Complior](https://complior.ai)*');
+
+  return lines.join('\n');
+};

package/src/output/json-output.ts

@@ -0,0 +1,67 @@
+import type { ScanResult } from '../types/common.types.js';
+
+export interface JsonOutput {
+  readonly scanner: string;
+  readonly version: string;
+  readonly score: number;
+  readonly zone: string;
+  readonly totalChecks: number;
+  readonly passedChecks: number;
+  readonly failedChecks: number;
+  readonly criticalCapApplied: boolean;
+  readonly findings: readonly {
+    readonly checkId: string;
+    readonly type: string;
+    readonly severity: string;
+    readonly message: string;
+    readonly obligationId?: string;
+    readonly articleReference?: string;
+    readonly file?: string;
+    readonly line?: number;
+    readonly fix?: string;
+  }[];
+  readonly categories: readonly {
+    readonly category: string;
+    readonly weight: number;
+    readonly score: number;
+    readonly passed: number;
+    readonly total: number;
+  }[];
+  readonly scannedAt: string;
+  readonly projectPath: string;
+  readonly filesScanned: number;
+  readonly duration: number;
+}
+
+export const toJsonOutput = (result: ScanResult, version: string): JsonOutput => ({
+  scanner: 'complior',
+  version,
+  score: result.score.totalScore,
+  zone: result.score.zone,
+  totalChecks: result.score.totalChecks,
+  passedChecks: result.score.passedChecks,
+  failedChecks: result.score.failedChecks,
+  criticalCapApplied: result.score.criticalCapApplied,
+  findings: result.findings.map((f) => ({
+    checkId: f.checkId,
+    type: f.type,
+    severity: f.severity,
+    message: f.message,
+    obligationId: f.obligationId,
+    articleReference: f.articleReference,
+    file: f.file,
+    line: f.line,
+    fix: f.fix,
+  })),
+  categories: result.score.categoryScores.map((c) => ({
+    category: c.category,
+    weight: c.weight,
+    score: c.score,
+    passed: c.passedCount,
+    total: c.obligationCount,
+  })),
+  scannedAt: result.scannedAt,
+  projectPath: result.projectPath,
+  filesScanned: result.filesScanned,
+  duration: result.duration,
+});

package/src/ports/browser.port.ts

@@ -0,0 +1,23 @@
+/** PageData — the shape of data produced by a headless browser crawl */
+export interface PageData {
+  readonly url: string;
+  readonly html: string;
+  readonly title: string;
+  readonly headers: Record<string, string>;
+  readonly metaTags: readonly { readonly name: string; readonly content: string }[];
+  readonly images: readonly { readonly src: string; readonly alt: string }[];
+  readonly links: readonly { readonly href: string; readonly text: string }[];
+  readonly scripts: readonly string[];
+  readonly hasWebSocket: boolean;
+  readonly chatInputs: readonly { readonly placeholder: string; readonly type: string }[];
+  readonly wellKnownAiCompliance: string | null;
+  readonly privacyPolicyUrl: string | null;
+  readonly privacyPolicyText: string | null;
+}
+
+/** BrowserPort — contract for headless browser capabilities */
+export interface BrowserPort {
+  readonly crawl: (url: string, timeout?: number) => Promise<PageData>;
+  readonly screenshot: (url: string, outputPath: string) => Promise<string>;
+  readonly close: () => Promise<void>;
+}

package/src/ports/events.port.ts

@@ -0,0 +1,28 @@
+import type { ScanResult, GateResult, ScoreZone } from '../types/common.types.js';
+import type { DriftResult } from '../domain/scanner/drift.js';
+
+export interface EventMap {
+  readonly 'scan.completed': { readonly result: ScanResult };
+  readonly 'scan.started': { readonly projectPath: string };
+  readonly 'scan.drift': { readonly drift: DriftResult };
+  readonly 'file.changed': { readonly path: string; readonly action: 'create' | 'edit' | 'delete' };
+  readonly 'score.updated': { readonly before: number; readonly after: number };
+  readonly 'gate.checked': { readonly result: GateResult };
+  readonly 'fix.validated': { readonly checkId: string; readonly passed: boolean; readonly scoreDelta: number };
+  readonly 'fix.undone': { readonly checkId: string; readonly restoredFiles: readonly string[] };
+  readonly 'badge.generated': { readonly path: string; readonly score: number; readonly zone: ScoreZone };
+  readonly 'share.created': { readonly id: string; readonly score: number };
+  readonly 'external-scan.completed': { readonly url: string; readonly score: number };
+  readonly 'report.generated': { readonly path: string; readonly format: 'pdf' | 'markdown' };
+  readonly 'agent.scan.completed': { readonly agentName: string; readonly result: ScanResult };
+  readonly 'agent.score.updated': { readonly agentName: string; readonly before: number; readonly after: number };
+  readonly 'passport.imported': { readonly name: string; readonly format: string; readonly fieldsImported: number };
+}
+
+export type EventHandler<T> = (payload: T) => void;
+
+export interface EventBusPort {
+  readonly on: <K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>) => void;
+  readonly off: <K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>) => void;
+  readonly emit: <K extends keyof EventMap>(event: K, payload: EventMap[K]) => void;
+}

package/src/ports/llm.port.ts

@@ -0,0 +1,23 @@
+import type { LanguageModel } from 'ai';
+
+export type ProviderName = 'openai' | 'anthropic' | 'openrouter';
+
+export interface ProviderInfo {
+  readonly name: ProviderName;
+  readonly available: boolean;
+  readonly envVar: string;
+}
+
+export interface ModelSelection {
+  readonly provider: ProviderName;
+  readonly modelId: string;
+  readonly reason: string;
+}
+
+export interface LlmPort {
+  readonly getModel: (provider: ProviderName, modelId: string, apiKey?: string) => Promise<LanguageModel>;
+  readonly detectProviders: () => readonly ProviderInfo[];
+  readonly getAvailableProviders: () => readonly ProviderInfo[];
+  readonly getDefaultProvider: () => ProviderName;
+  readonly routeModel: (taskType: string, preferredProvider?: ProviderName) => ModelSelection;
+}

package/src/ports/logger.port.ts

@@ -0,0 +1,6 @@
+export interface LoggerPort {
+  readonly info: (message: string, ...args: unknown[]) => void;
+  readonly warn: (message: string, ...args: unknown[]) => void;
+  readonly error: (message: string, ...args: unknown[]) => void;
+  readonly debug: (message: string, ...args: unknown[]) => void;
+}

package/src/ports/process.port.ts

@@ -0,0 +1,6 @@
+/** Contract for running external processes (subprocess execution). */
+export type ProcessRunner = (
+  cmd: string,
+  args: readonly string[],
+  options?: { readonly timeout?: number; readonly cwd?: string },
+) => Promise<{ readonly stdout: string; readonly stderr: string; readonly exitCode: number }>;

package/src/ports/scanner.port.ts

@@ -0,0 +1,15 @@
+import type { CheckResult } from '../types/common.types.js';
+
+export interface FileInfo {
+  readonly path: string;
+  readonly content: string;
+  readonly extension: string;
+  readonly relativePath: string;
+}
+
+export interface ScanContext {
+  readonly files: readonly FileInfo[];
+  readonly projectPath: string;
+}
+
+export type CheckFunction = (ctx: ScanContext) => readonly CheckResult[];