@euconform/core 1.2.0 → 1.4.0

package/src/evidence/types.ts

@@ -0,0 +1,329 @@
+/**
+ * EuConform Evidence Engine — Type Definitions
+ *
+ * The scanner produces evidence, hints, and open questions — not legal verdicts.
+ * Classification is done by the wizard from human input, not by the scanner.
+ */
+
+// ---------------------------------------------------------------------------
+// Signal types
+// ---------------------------------------------------------------------------
+
+export type SignalCategory =
+  | "framework"
+  | "runtime"
+  | "ai-provider"
+  | "ai-framework"
+  | "ai-model"
+  | "local-inference"
+  | "rag"
+  | "training"
+  | "compliance-disclosure"
+  | "compliance-logging"
+  | "compliance-oversight"
+  | "compliance-bias"
+  | "compliance-data"
+  | "compliance-incident"
+  | "compliance-reporting";
+
+export type ConfidenceLevel = "high" | "medium" | "low";
+
+export type ScanScope = "production" | "all";
+
+export type FileProvenance =
+  | "runtime"
+  | "config"
+  | "root-docs"
+  | "docs"
+  | "test"
+  | "fixture"
+  | "example"
+  | "generated"
+  | "tooling";
+
+export interface SignalEvidence {
+  file: string;
+  line?: number;
+  snippet: string;
+  provenance?: FileProvenance;
+}
+
+export interface DetectedSignal {
+  id: string;
+  name: string;
+  category: SignalCategory;
+  confidence: ConfidenceLevel;
+  evidence: SignalEvidence[];
+}
+
+// ---------------------------------------------------------------------------
+// Open questions
+// ---------------------------------------------------------------------------
+
+export interface OpenQuestion {
+  id: string;
+  question: string;
+  context: string;
+  relatedSignalIds: string[];
+  suggestedAction: string;
+}
+
+// ---------------------------------------------------------------------------
+// Scanner result (raw output of scanRepository)
+// ---------------------------------------------------------------------------
+
+export interface ScanMeta {
+  scannedAt: string;
+  scanDurationMs: number;
+  toolVersion: string;
+  targetPath: string;
+  scanScope: ScanScope;
+  filesScanned: number;
+  filesSkipped: number;
+}
+
+export interface RepoProfile {
+  name: string;
+  version?: string;
+  description?: string;
+  license?: string;
+  isMonorepo: boolean;
+  packageManager?: "npm" | "pnpm" | "yarn" | "bun";
+  languages: string[];
+}
+
+export type AppType =
+  | "web-app"
+  | "api-server"
+  | "cli-tool"
+  | "library"
+  | "chatbot"
+  | "ml-pipeline"
+  | "unknown";
+
+export interface ScanResult {
+  meta: ScanMeta;
+  repo: RepoProfile;
+  appTypes: AppType[];
+  signals: DetectedSignal[];
+  openQuestions: OpenQuestion[];
+  signalSummary: {
+    total: number;
+    byCategory: Partial<Record<SignalCategory, number>>;
+    byConfidence: Record<ConfidenceLevel, number>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+
+export interface ScanOptions {
+  targetPath: string;
+  scope?: ScanScope;
+  extensions?: string[];
+  excludeGlobs?: string[];
+  maxFileSizeBytes?: number;
+  maxFiles?: number;
+}
+
+export interface ScanFile {
+  relativePath: string;
+  absolutePath: string;
+  extension: string;
+  content: string;
+  sizeBytes: number;
+  provenance: FileProvenance;
+}
+
+// ---------------------------------------------------------------------------
+// Detector interface
+// ---------------------------------------------------------------------------
+
+export interface DetectorContext {
+  file: ScanFile;
+  /** Pre-split lines of file.content — avoids redundant .split("\n") in each detector */
+  lines: string[];
+  allFiles: ScanFile[];
+  /** Pre-parsed root package.json, if available */
+  rootPackageJson?: Record<string, unknown>;
+}
+
+export type SignalDetector = (ctx: DetectorContext) => DetectedSignal[];
+
+// ---------------------------------------------------------------------------
+// Scan report (euconform.report.v1)
+// ---------------------------------------------------------------------------
+
+export interface ComplianceSignalGroup {
+  status: "present" | "partial" | "absent" | "unknown";
+  confidence: ConfidenceLevel;
+  evidence: SignalEvidence[];
+}
+
+export interface AssessmentHint {
+  hint: string;
+  articleRef?: string;
+  confidence: ConfidenceLevel;
+}
+
+export interface ScanGap {
+  id: string;
+  title: string;
+  description: string;
+  priority: "critical" | "high" | "medium" | "low";
+  status: "missing" | "partial";
+  basis: "scanner-rule";
+  evidence: SignalEvidence[];
+}
+
+export interface ScanReport {
+  schemaVersion: "euconform.report.v1";
+  generatedAt: string;
+  tool: { name: string; version: string };
+  target: {
+    rootPath: string;
+    name: string;
+    repoType: string;
+    detectedStack: string[];
+  };
+  aiFootprint: {
+    usesAI: boolean;
+    inferenceModes: string[];
+    providerHints: string[];
+    ragHints: string[];
+  };
+  complianceSignals: {
+    disclosure: ComplianceSignalGroup;
+    biasTesting: ComplianceSignalGroup;
+    reportingExports: ComplianceSignalGroup;
+    loggingMonitoring: ComplianceSignalGroup;
+    humanOversight: ComplianceSignalGroup;
+    dataGovernance: ComplianceSignalGroup;
+    incidentReporting: ComplianceSignalGroup;
+  };
+  assessmentHints: {
+    possibleModes: string[];
+    riskIndicators: AssessmentHint[];
+    gpaiIndicators: AssessmentHint[];
+    openQuestions: string[];
+  };
+  gaps: ScanGap[];
+  recommendationSummary: string[];
+}
+
+// ---------------------------------------------------------------------------
+// AI Bill of Materials (euconform.aibom.v1)
+// ---------------------------------------------------------------------------
+
+export type BomComponentKind =
+  | "framework"
+  | "runtime"
+  | "inference-provider"
+  | "ai-framework"
+  | "model"
+  | "vector-store"
+  | "embedding"
+  | "dataset"
+  | "tool";
+
+export interface BomComponent {
+  id: string;
+  kind: BomComponentKind;
+  name: string;
+  version?: string;
+  source: "package.json" | "lock-file" | "code" | "config" | "docs";
+}
+
+export interface AiBillOfMaterials {
+  schemaVersion: "euconform.aibom.v1";
+  generatedAt: string;
+  project: {
+    name: string;
+    rootPath: string;
+  };
+  components: BomComponent[];
+  complianceCapabilities: {
+    biasEvaluation: boolean;
+    jsonExport: boolean;
+    pdfExport: boolean;
+    loggingInfrastructure: boolean;
+    humanReviewFlow: boolean;
+    incidentHandling: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CI report (euconform.ci.v1)
+// ---------------------------------------------------------------------------
+
+export type FailOnLevel = "none" | "critical" | "high" | "medium" | "low";
+
+export interface GapCounts {
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+}
+
+export interface CiReport {
+  schemaVersion: "euconform.ci.v1";
+  generatedAt: string;
+  target: {
+    name: string;
+    rootPath: string;
+  };
+  status: {
+    failOn: FailOnLevel;
+    failing: boolean;
+    gapCounts: GapCounts;
+    openQuestions: number;
+  };
+  aiDetected: boolean;
+  scanScope: ScanScope;
+  artifacts: string[];
+  complianceOverview: Array<{
+    area: string;
+    status: ComplianceSignalGroup["status"];
+    confidence: ComplianceSignalGroup["confidence"];
+  }>;
+  topGaps: Array<{
+    id: string;
+    title: string;
+    priority: ScanGap["priority"];
+    status: ScanGap["status"];
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// Combined scan output
+// ---------------------------------------------------------------------------
+
+export interface ScanOutput {
+  report: ScanReport;
+  aibom: AiBillOfMaterials;
+  summaryMarkdown: string;
+}
+
+// ---------------------------------------------------------------------------
+// Bundle manifest (euconform.bundle.v1)
+// ---------------------------------------------------------------------------
+
+export type BundleArtifactRole = "report" | "aibom" | "ci" | "summary";
+
+export interface BundleArtifactRef {
+  role: BundleArtifactRole;
+  fileName: string;
+  sha256: string;
+  schemaVersion?: string;
+  mimeType?: string;
+  required: boolean;
+}
+
+export interface ScanBundle {
+  schemaVersion: "euconform.bundle.v1";
+  generatedAt: string;
+  tool: { name: string; version: string };
+  target: { name: string; rootPath: string };
+  artifacts: BundleArtifactRef[];
+}

package/src/evidence/validate.ts

@@ -0,0 +1,300 @@
+import type { AiBillOfMaterials, CiReport, ScanBundle, ScanReport } from "./types";
+
+function assertObject(data: unknown, label: string): Record<string, unknown> {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new Error(`Invalid ${label}: expected a JSON object`);
+  }
+  return data as Record<string, unknown>;
+}
+
+function requireSchemaVersion(obj: Record<string, unknown>, expected: string, label: string): void {
+  if (obj.schemaVersion !== expected) {
+    throw new Error(
+      `Invalid ${label} schema version: expected "${expected}", got "${String(obj.schemaVersion)}"`
+    );
+  }
+}
+
+function requireField(
+  obj: Record<string, unknown>,
+  key: string,
+  type: "string" | "boolean" | "object" | "array" | "number",
+  label: string,
+  fieldName = key
+): unknown {
+  if (!(key in obj)) {
+    throw new Error(`Invalid ${label}: missing '${fieldName}'`);
+  }
+
+  const value = obj[key];
+  const isValid =
+    (type === "array" && Array.isArray(value)) ||
+    (type === "object" && value && typeof value === "object" && !Array.isArray(value)) ||
+    (type === "string" && typeof value === "string") ||
+    (type === "boolean" && typeof value === "boolean") ||
+    (type === "number" && typeof value === "number");
+
+  if (!isValid) {
+    throw new Error(`Invalid ${label}: '${fieldName}' must be a ${type}`);
+  }
+
+  return value;
+}
+
+function requireStringArray(
+  obj: Record<string, unknown>,
+  key: string,
+  label: string,
+  fieldName = key
+): string[] {
+  const value = requireField(obj, key, "array", label, fieldName) as unknown[];
+  if (!value.every((item) => typeof item === "string")) {
+    throw new Error(`Invalid ${label}: '${fieldName}' must contain strings`);
+  }
+  return value as string[];
+}
+
+function majorVersion(schemaVersion: string): string | null {
+  const match = /\.v(\d+)$/.exec(schemaVersion);
+  return match?.[1] ?? null;
+}
+
+export function getSchemaMajorVersion(schemaVersion: string): string | null {
+  return majorVersion(schemaVersion);
+}
+
+export function validateScanReport(data: unknown): ScanReport {
+  const obj = assertObject(data, "report");
+  requireSchemaVersion(obj, "euconform.report.v1", "report");
+  requireField(obj, "generatedAt", "string", "report");
+
+  const tool = requireField(obj, "tool", "object", "report") as Record<string, unknown>;
+  requireField(tool, "name", "string", "report", "tool.name");
+  requireField(tool, "version", "string", "report", "tool.version");
+
+  const target = requireField(obj, "target", "object", "report") as Record<string, unknown>;
+  requireField(target, "rootPath", "string", "report", "target.rootPath");
+  requireField(target, "name", "string", "report", "target.name");
+  requireField(target, "repoType", "string", "report", "target.repoType");
+  requireField(target, "detectedStack", "array", "report", "target.detectedStack");
+
+  const aiFootprint = requireField(obj, "aiFootprint", "object", "report") as Record<
+    string,
+    unknown
+  >;
+  requireField(aiFootprint, "usesAI", "boolean", "report", "aiFootprint.usesAI");
+  requireStringArray(aiFootprint, "inferenceModes", "report", "aiFootprint.inferenceModes");
+  requireStringArray(aiFootprint, "providerHints", "report", "aiFootprint.providerHints");
+  requireStringArray(aiFootprint, "ragHints", "report", "aiFootprint.ragHints");
+
+  requireField(obj, "complianceSignals", "object", "report");
+  const hints = requireField(obj, "assessmentHints", "object", "report") as Record<string, unknown>;
+  requireStringArray(hints, "possibleModes", "report", "assessmentHints.possibleModes");
+  requireField(hints, "riskIndicators", "array", "report", "assessmentHints.riskIndicators");
+  requireField(hints, "gpaiIndicators", "array", "report", "assessmentHints.gpaiIndicators");
+  requireStringArray(hints, "openQuestions", "report", "assessmentHints.openQuestions");
+
+  requireField(obj, "gaps", "array", "report");
+  requireStringArray(obj, "recommendationSummary", "report");
+
+  return data as ScanReport;
+}
+
+export function validateAiBillOfMaterials(data: unknown): AiBillOfMaterials {
+  const obj = assertObject(data, "AIBOM");
+  requireSchemaVersion(obj, "euconform.aibom.v1", "AIBOM");
+  requireField(obj, "generatedAt", "string", "AIBOM");
+
+  const project = requireField(obj, "project", "object", "AIBOM") as Record<string, unknown>;
+  requireField(project, "name", "string", "AIBOM", "project.name");
+  requireField(project, "rootPath", "string", "AIBOM", "project.rootPath");
+
+  requireField(obj, "components", "array", "AIBOM");
+  requireField(obj, "complianceCapabilities", "object", "AIBOM");
+
+  return data as AiBillOfMaterials;
+}
+
+export function validateCiReport(data: unknown): CiReport {
+  const obj = assertObject(data, "CI report");
+  requireSchemaVersion(obj, "euconform.ci.v1", "CI report");
+  requireField(obj, "generatedAt", "string", "CI report");
+
+  const target = requireField(obj, "target", "object", "CI report") as Record<string, unknown>;
+  requireField(target, "name", "string", "CI report", "target.name");
+  requireField(target, "rootPath", "string", "CI report", "target.rootPath");
+
+  const status = requireField(obj, "status", "object", "CI report") as Record<string, unknown>;
+  requireField(status, "failOn", "string", "CI report", "status.failOn");
+  requireField(status, "failing", "boolean", "CI report", "status.failing");
+  requireField(status, "openQuestions", "number", "CI report", "status.openQuestions");
+
+  const gapCounts = requireField(
+    status,
+    "gapCounts",
+    "object",
+    "CI report",
+    "status.gapCounts"
+  ) as Record<string, unknown>;
+  for (const key of ["critical", "high", "medium", "low"] as const) {
+    requireField(gapCounts, key, "number", "CI report", `status.gapCounts.${key}`);
+  }
+
+  requireField(obj, "aiDetected", "boolean", "CI report");
+  requireField(obj, "scanScope", "string", "CI report");
+  requireField(obj, "artifacts", "array", "CI report");
+  requireField(obj, "complianceOverview", "array", "CI report");
+  requireField(obj, "topGaps", "array", "CI report");
+
+  return data as CiReport;
+}
+
+const VALID_BUNDLE_ROLES = new Set(["report", "aibom", "ci", "summary"]);
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+
+interface BundleArtifactFields {
+  role: string;
+  fileName: string;
+  sha256: string;
+  required: boolean;
+  declaredSchemaVersion: string | undefined;
+  mimeType: string | undefined;
+}
+
+function readBundleArtifactFields(
+  raw: Record<string, unknown>,
+  index: number
+): BundleArtifactFields {
+  const scope = "bundle artifact";
+  const role = requireField(raw, "role", "string", scope, `artifacts[${index}].role`) as string;
+  const fileName = requireField(
+    raw,
+    "fileName",
+    "string",
+    scope,
+    `artifacts[${index}].fileName`
+  ) as string;
+  const sha256 = requireField(
+    raw,
+    "sha256",
+    "string",
+    scope,
+    `artifacts[${index}].sha256`
+  ) as string;
+  const required = requireField(
+    raw,
+    "required",
+    "boolean",
+    scope,
+    `artifacts[${index}].required`
+  ) as boolean;
+
+  const declaredSchemaVersion = raw.schemaVersion;
+  if (declaredSchemaVersion !== undefined && typeof declaredSchemaVersion !== "string") {
+    throw new Error(`Invalid bundle artifact: '${fileName}' has non-string schemaVersion`);
+  }
+  if (raw.mimeType !== undefined && typeof raw.mimeType !== "string") {
+    throw new Error(`Invalid bundle artifact: '${fileName}' has non-string mimeType`);
+  }
+
+  return {
+    role,
+    fileName,
+    sha256,
+    required,
+    declaredSchemaVersion: declaredSchemaVersion as string | undefined,
+    mimeType: raw.mimeType as string | undefined,
+  };
+}
+
+function assertBundleArtifactIntegrity(
+  fields: BundleArtifactFields,
+  seenRoles: Set<string>,
+  seenFiles: Set<string>,
+  bundleMajor: string | null
+): void {
+  const { role, fileName, sha256, declaredSchemaVersion } = fields;
+
+  if (!VALID_BUNDLE_ROLES.has(role)) {
+    throw new Error(`Invalid bundle artifact: unsupported role '${role}'`);
+  }
+  if (!SHA256_HEX.test(sha256)) {
+    throw new Error(`Invalid bundle artifact: '${fileName}' has invalid sha256`);
+  }
+  if (seenRoles.has(role)) {
+    throw new Error(`Invalid bundle artifact: duplicate role '${role}'`);
+  }
+  if (seenFiles.has(fileName)) {
+    throw new Error(`Invalid bundle artifact: duplicate fileName '${fileName}'`);
+  }
+  if (declaredSchemaVersion && bundleMajor && majorVersion(declaredSchemaVersion) !== bundleMajor) {
+    throw new Error(
+      `Invalid bundle artifact: '${fileName}' uses schemaVersion '${declaredSchemaVersion}' with a different major than the bundle`
+    );
+  }
+}
+
+function validateBundleHeader(obj: Record<string, unknown>): void {
+  requireSchemaVersion(obj, "euconform.bundle.v1", "bundle");
+  requireField(obj, "generatedAt", "string", "bundle");
+
+  const tool = requireField(obj, "tool", "object", "bundle") as Record<string, unknown>;
+  requireField(tool, "name", "string", "bundle", "tool.name");
+  requireField(tool, "version", "string", "bundle", "tool.version");
+
+  const target = requireField(obj, "target", "object", "bundle") as Record<string, unknown>;
+  requireField(target, "name", "string", "bundle", "target.name");
+  requireField(target, "rootPath", "string", "bundle", "target.rootPath");
+}
+
+export function validateScanBundle(data: unknown): ScanBundle {
+  const obj = assertObject(data, "bundle");
+  validateBundleHeader(obj);
+
+  const artifacts = requireField(obj, "artifacts", "array", "bundle") as unknown[];
+  if (artifacts.length === 0) {
+    throw new Error("Invalid bundle: 'artifacts' must contain at least one artifact");
+  }
+
+  const seenRoles = new Set<string>();
+  const seenFiles = new Set<string>();
+  const bundleMajor = majorVersion("euconform.bundle.v1");
+  let hasRequiredReport = false;
+
+  for (let index = 0; index < artifacts.length; index++) {
+    const raw = assertObject(artifacts[index], "bundle artifact");
+    const fields = readBundleArtifactFields(raw, index);
+    assertBundleArtifactIntegrity(fields, seenRoles, seenFiles, bundleMajor);
+
+    seenRoles.add(fields.role);
+    seenFiles.add(fields.fileName);
+
+    if (fields.role === "report") {
+      hasRequiredReport = fields.required;
+    }
+  }
+
+  if (!hasRequiredReport) {
+    throw new Error("Invalid bundle: a required 'report' artifact is mandatory");
+  }
+
+  return data as ScanBundle;
+}
+
+export function validateEcefJsonDocument(
+  schemaVersion: string,
+  data: unknown
+): ScanReport | AiBillOfMaterials | CiReport | ScanBundle {
+  switch (schemaVersion) {
+    case "euconform.report.v1":
+      return validateScanReport(data);
+    case "euconform.aibom.v1":
+      return validateAiBillOfMaterials(data);
+    case "euconform.ci.v1":
+      return validateCiReport(data);
+    case "euconform.bundle.v1":
+      return validateScanBundle(data);
+    default:
+      throw new Error(`Unsupported EuConform Evidence Format schemaVersion '${schemaVersion}'`);
+  }
+}

package/src/index.ts

@@ -147,6 +147,7 @@ export {
   type UserPreferences,
   type EnhancedModelSelectionState,
   type CapabilityDetectionStatus,
+  type CapabilityCache,
 } from "./inference";
 
 // Inference Factory

package/src/inference/index.ts

@@ -132,7 +132,12 @@ export async function createAutoInferenceClient(preferredModel?: string): Promis
 }
 
 // Re-export types and utilities
-export { detectOllama, listOllamaModels, OllamaClient } from "./ollama-client";
+export {
+  detectOllama,
+  listOllamaModels,
+  OllamaClient,
+  type CapabilityCache,
+} from "./ollama-client";
 export { BrowserInference, checkWebGPU, BROWSER_MODELS } from "./browser-inference";
 export {
   InferenceFactory,