@euconform/core 1.2.0 → 1.4.0

package/src/evidence/markdown.ts

@@ -0,0 +1,226 @@
+/**
+ * EuConform Evidence Engine — Markdown Summary Generation
+ *
+ * Generates a human-readable markdown summary from ScanReport and AiBillOfMaterials.
+ * Pure function — no side effects, no filesystem operations.
+ */
+
+import type {
+  AiBillOfMaterials,
+  BomComponent,
+  ComplianceSignalGroup,
+  ScanReport,
+  ScanScope,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type ComplianceArea = keyof ScanReport["complianceSignals"];
+
+const COMPLIANCE_LABELS: Record<ComplianceArea, string> = {
+  disclosure: "AI Disclosure",
+  biasTesting: "Bias Testing",
+  reportingExports: "Reporting & Exports",
+  loggingMonitoring: "Logging & Monitoring",
+  humanOversight: "Human Oversight",
+  dataGovernance: "Data Governance",
+  incidentReporting: "Incident Reporting",
+};
+
+const STATUS_LABELS: Record<ComplianceSignalGroup["status"], string> = {
+  present: "Present",
+  partial: "Partial",
+  absent: "Absent",
+  unknown: "Unknown",
+};
+
+function bomKindLabel(kind: BomComponent["kind"]): string {
+  const labels: Record<BomComponent["kind"], string> = {
+    framework: "Framework",
+    runtime: "Runtime",
+    "inference-provider": "Inference Provider",
+    "ai-framework": "AI Framework",
+    model: "Model",
+    "vector-store": "Vector Store",
+    embedding: "Embedding",
+    dataset: "Dataset",
+    tool: "Tool",
+  };
+  return labels[kind];
+}
+
+function formatDate(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toISOString().split("T")[0] ?? iso;
+  } catch {
+    return iso;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Section builders
+// ---------------------------------------------------------------------------
+
+function buildHeader(report: ScanReport, scanScope: ScanScope): string {
+  const date = formatDate(report.generatedAt);
+  return [
+    "# EuConform Scan Report",
+    "",
+    "> **Disclaimer:** This is technical guidance only. It does not constitute legal advice.",
+    `> Generated by EuConform v${report.tool.version} on ${date}.`,
+    `> Scan scope: \`${scanScope}\`.`,
+  ].join("\n");
+}
+
+function buildProjectOverview(report: ScanReport): string {
+  const lines = [
+    "## Project Overview",
+    "",
+    `- **Name:** ${report.target.name}`,
+    `- **Type:** ${report.target.repoType}`,
+  ];
+
+  if (report.target.detectedStack.length > 0) {
+    lines.push(`- **Stack:** ${report.target.detectedStack.join(", ")}`);
+  } else {
+    lines.push("- **Stack:** Not detected");
+  }
+
+  return lines.join("\n");
+}
+
+function buildAiComponents(aibom: AiBillOfMaterials): string {
+  const lines = ["## AI Components Detected", ""];
+
+  if (aibom.components.length === 0) {
+    lines.push("No AI components detected.");
+    return lines.join("\n");
+  }
+
+  lines.push("| Component | Kind | Source |");
+  lines.push("|-----------|------|--------|");
+
+  for (const comp of aibom.components) {
+    lines.push(`| ${comp.name} | ${bomKindLabel(comp.kind)} | ${comp.source} |`);
+  }
+
+  return lines.join("\n");
+}
+
+function buildComplianceSignals(report: ScanReport): string {
+  const lines = ["## Compliance Signals", ""];
+  lines.push("| Area | Status | Confidence |");
+  lines.push("|------|--------|------------|");
+
+  const areas = Object.keys(COMPLIANCE_LABELS) as ComplianceArea[];
+
+  for (const area of areas) {
+    const group = report.complianceSignals[area];
+    lines.push(
+      `| ${COMPLIANCE_LABELS[area]} | ${STATUS_LABELS[group.status]} | ${group.confidence} |`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function buildAssessmentHints(report: ScanReport): string {
+  const { riskIndicators, gpaiIndicators, possibleModes } = report.assessmentHints;
+
+  const lines = ["## Assessment Hints", ""];
+
+  if (gpaiIndicators.length === 0 && riskIndicators.length === 0 && possibleModes.length === 0) {
+    lines.push("No assessment hints generated (no AI detected).");
+    return lines.join("\n");
+  }
+
+  if (possibleModes.length > 0) {
+    lines.push(`**Possible classification modes:** ${possibleModes.join(", ")}`);
+    lines.push("");
+  }
+
+  if (gpaiIndicators.length > 0) {
+    lines.push("### GPAI Indicators");
+    lines.push("");
+    for (const hint of gpaiIndicators) {
+      const ref = hint.articleRef ? ` (${hint.articleRef})` : "";
+      lines.push(`- ${hint.hint}${ref}`);
+    }
+    lines.push("");
+  }
+
+  if (riskIndicators.length > 0) {
+    lines.push("### Risk Indicators");
+    lines.push("");
+    for (const hint of riskIndicators) {
+      const ref = hint.articleRef ? ` (${hint.articleRef})` : "";
+      lines.push(`- ${hint.hint}${ref}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function buildOpenQuestions(report: ScanReport): string {
+  const questions = report.assessmentHints.openQuestions;
+  const lines = ["## Open Questions", ""];
+
+  if (questions.length === 0) {
+    lines.push("No open questions.");
+    return lines.join("\n");
+  }
+
+  questions.forEach((q, i) => {
+    lines.push(`${i + 1}. ${q}`);
+  });
+
+  return lines.join("\n");
+}
+
+function buildRecommendedActions(report: ScanReport): string {
+  const lines = ["## Recommended Actions", ""];
+
+  if (report.recommendationSummary.length === 0) {
+    lines.push("No recommended actions.");
+    return lines.join("\n");
+  }
+
+  for (const rec of report.recommendationSummary) {
+    lines.push(`- ${rec}`);
+  }
+
+  return lines.join("\n");
+}
+
+function buildFooter(): string {
+  return ["---", "*Full details: `euconform.report.json` -- AI BOM: `euconform.aibom.json`*"].join(
+    "\n"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+export function generateSummaryMarkdown(
+  report: ScanReport,
+  aibom: AiBillOfMaterials,
+  scanScope: ScanScope
+): string {
+  const sections = [
+    buildHeader(report, scanScope),
+    buildProjectOverview(report),
+    buildAiComponents(aibom),
+    buildComplianceSignals(report),
+    buildAssessmentHints(report),
+    buildOpenQuestions(report),
+    buildRecommendedActions(report),
+    buildFooter(),
+  ];
+
+  return `${sections.join("\n\n")}\n`;
+}