@vibecodetown/mcp-server 1.3.1

package/build/mcp/tools/vibe_pm/diagrams/gate_engine.js

@@ -0,0 +1,695 @@
+// Diagram Gate Engine — Full Reason Code Evaluation
+// SSOT: docs/DEV_SPEC/active/diagram-as-code/DIAGRAM_GATE_REASON_CODES_AND_IDS_SPEC_v1.0.md
+import { LAYER_ORDER } from "./types.js";
+import { CONTROL_PLANE_PATTERNS, CRITICAL_NODE_PATTERNS } from "./constants.js";
+const RULES = [
+    // -------------------------------------------------------------------------
+    // A) Mapping / Unknown
+    // -------------------------------------------------------------------------
+    // 1) DG_UNKNOWN_RATE_CRITICAL
+    (m, model) => {
+        if (m.unknown_rate > 0.60 && m.changed_files >= 5) {
+            return {
+                code: "DG_UNKNOWN_RATE_CRITICAL",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Unknown mapping rate ${(m.unknown_rate * 100).toFixed(1)}% > 60% (files=${m.changed_files}).`,
+                why: "Too many changed files are not mapped to any skeleton node; diagram impact is unreliable.",
+                where: { files: model.unmapped_files.slice(0, 10) },
+                metrics: { unknown_rate: m.unknown_rate, changed_files: m.changed_files },
+                recommendation: {
+                    do: [
+                        "Add spec_map entries for top unknown paths",
+                        "Move files into mapped domain/layer directories",
+                        "Run mapping refresh / import_hint tuning",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 2) DG_UNKNOWN_RATE_HIGH
+    (m, model) => {
+        if (m.unknown_rate > 0.30 && !(m.unknown_rate > 0.60 && m.changed_files >= 5)) {
+            return {
+                code: "DG_UNKNOWN_RATE_HIGH",
+                severity: "P1",
+                level: "FIX",
+                message: `Unknown mapping rate ${(m.unknown_rate * 100).toFixed(1)}% > 30%.`,
+                why: "Change impact diagram has low coverage; review scope/mapping before merging.",
+                where: { files: model.unmapped_files.slice(0, 5) },
+                metrics: { unknown_rate: m.unknown_rate },
+                recommendation: {
+                    do: [
+                        "Map unknown paths to skeleton nodes",
+                        "Split PR to isolate unmapped changes",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 3) DG_UNKNOWN_FILES_PRESENT
+    (m, model) => {
+        if (model.unmapped_files.length > 0 && m.unknown_rate <= 0.30) {
+            return {
+                code: "DG_UNKNOWN_FILES_PRESENT",
+                severity: "P2",
+                level: "GO_HINT",
+                message: `${model.unmapped_files.length} unmapped files detected.`,
+                why: "Some files are not mapped but within acceptable threshold.",
+                where: { files: model.unmapped_files.slice(0, 3) },
+                metrics: { unknown_rate: m.unknown_rate },
+                recommendation: {
+                    do: ["Optionally add spec_map for recurring paths"],
+                },
+            };
+        }
+        return null;
+    },
+    // 4) DG_LOW_CONFIDENCE_AVG
+    (m) => {
+        if (m.avg_confidence < 0.55 && m.touched_nodes >= 6) {
+            return {
+                code: "DG_LOW_CONFIDENCE_AVG",
+                severity: "P1",
+                level: "FIX",
+                message: `Average mapping confidence ${(m.avg_confidence * 100).toFixed(1)}% < 55%.`,
+                why: "Mapping quality is low across many nodes; diagram may not reflect actual dependencies.",
+                where: {},
+                metrics: { avg_confidence: m.avg_confidence, touched_nodes: m.touched_nodes },
+                recommendation: {
+                    do: [
+                        "Improve matching rules (keywords/import_hint)",
+                        "Reduce ambiguous multi-matches",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 5) DG_MULTI_MATCH_AMBIGUITY
+    (m) => {
+        if (m.multi_match_files >= 5 || m.max_matches_per_file >= 4) {
+            return {
+                code: "DG_MULTI_MATCH_AMBIGUITY",
+                severity: "P2",
+                level: "FIX",
+                message: `High ambiguity: ${m.multi_match_files} files map to multiple nodes (max=${m.max_matches_per_file}).`,
+                why: "Files matching multiple skeleton nodes reduce diagram accuracy.",
+                where: {},
+                metrics: { multi_match_files: m.multi_match_files, max_matches_per_file: m.max_matches_per_file },
+                recommendation: {
+                    do: [
+                        "Tighten spec_map patterns",
+                        "Introduce clearer folder boundaries",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // -------------------------------------------------------------------------
+    // B) Forbidden / Protected zones
+    // -------------------------------------------------------------------------
+    // 6) DG_FORBIDDEN_TOUCHED
+    (m, model) => {
+        if (m.forbidden_hits > 0) {
+            const forbiddenFiles = model.violations
+                .filter(v => v.code === "DENY_PATH_TOUCHED")
+                .map(v => v.file)
+                .slice(0, 5);
+            return {
+                code: "DG_FORBIDDEN_TOUCHED",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Forbidden zone touched: ${m.forbidden_hits} files.`,
+                why: "Changes include protected/control-plane/engine zones.",
+                where: { files: forbiddenFiles },
+                metrics: { forbidden_hits: m.forbidden_hits },
+                recommendation: {
+                    do: [
+                        "Revert forbidden changes",
+                        "Move changes to allowed extension points",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 7) DG_CONTROL_PLANE_TOUCHED
+    (m) => {
+        if (m.control_plane_hits > 0) {
+            return {
+                code: "DG_CONTROL_PLANE_TOUCHED",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Control-plane protected paths modified: ${m.control_plane_hits} hits.`,
+                why: "Control-plane paths require special authorization.",
+                where: {},
+                metrics: { control_plane_hits: m.control_plane_hits },
+                recommendation: {
+                    do: ["Use designated adapters/overrides only"],
+                },
+            };
+        }
+        return null;
+    },
+    // -------------------------------------------------------------------------
+    // C) Boundary / Layer rules
+    // -------------------------------------------------------------------------
+    // 8) DG_CROSS_DOMAIN_HIGH_RISK
+    (m) => {
+        if (m.cross_domain_edges >= 2 && m.risk_score >= 12) {
+            return {
+                code: "DG_CROSS_DOMAIN_HIGH_RISK",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Cross-domain impact with high risk (edges=${m.cross_domain_edges}, score=${m.risk_score}).`,
+                why: "Multiple domain boundaries crossed with elevated risk score.",
+                where: {},
+                metrics: { cross_domain_edges: m.cross_domain_edges, risk_score: m.risk_score },
+                recommendation: {
+                    do: [
+                        "Introduce boundary (API/Event/Contract)",
+                        "Move shared code to contracts/shared layer",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 9) DG_CROSS_DOMAIN_DETECTED
+    (m, model) => {
+        if (m.cross_domain_edges >= 1 && !(m.cross_domain_edges >= 2 && m.risk_score >= 12)) {
+            const crossEdges = model.edges
+                .filter(e => e.stereotype === "CROSS_DOMAIN")
+                .map(e => ({ from: e.from_node_id, to: e.to_node_id, relation: e.relation }));
+            return {
+                code: "DG_CROSS_DOMAIN_DETECTED",
+                severity: "P1",
+                level: "FIX",
+                message: `Cross-domain dependency detected (edges=${m.cross_domain_edges}).`,
+                why: "Changes span multiple domains; verify boundary is intentional.",
+                where: { edges: crossEdges.slice(0, 5) },
+                metrics: { cross_domain_edges: m.cross_domain_edges },
+                recommendation: {
+                    do: [
+                        "Confirm boundary is intended",
+                        "If unintended: refactor to API/Event/Contract",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 10) DG_LAYER_SKIP_DETECTED
+    (m) => {
+        if (m.layer_skip_edges >= 1) {
+            const severity = m.layer_skip_edges >= 3 ? "P0" : "P1";
+            const level = m.layer_skip_edges >= 3 ? "BLOCK" : "FIX";
+            return {
+                code: "DG_LAYER_SKIP_DETECTED",
+                severity,
+                level,
+                message: `Layer skip detected: ${m.layer_skip_edges} edges bypass intermediate layers.`,
+                why: "Direct access from UI/API to Data/Infra violates layered architecture.",
+                where: {},
+                metrics: { layer_skip_edges: m.layer_skip_edges },
+                recommendation: {
+                    do: [
+                        "Route via Service/Domain layer",
+                        "Add adapter boundary",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 11) DG_REVERSE_DEPENDENCY
+    (m) => {
+        if (m.reverse_edges >= 1) {
+            return {
+                code: "DG_REVERSE_DEPENDENCY",
+                severity: "P1",
+                level: "FIX",
+                message: `Reverse dependency detected: ${m.reverse_edges} edges flow upward.`,
+                why: "Dependencies should flow inward/downward (e.g., Domain->Service, not Service->API).",
+                where: {},
+                metrics: { reverse_edges: m.reverse_edges },
+                recommendation: {
+                    do: [
+                        "Invert dependency via interface/port",
+                        "Move implementation outward",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // -------------------------------------------------------------------------
+    // D) Scope / Blast radius
+    // -------------------------------------------------------------------------
+    // 12) DG_SCOPE_WIDE
+    (m) => {
+        const wide = m.touched_nodes > 12 || (m.touched_nodes > 8 && m.changed_files > 20);
+        const explosion = m.touched_nodes > 25 || m.cross_domain_edges > 6;
+        if (wide && !explosion) {
+            return {
+                code: "DG_SCOPE_WIDE",
+                severity: "P1",
+                level: "FIX",
+                message: `Scope wide: nodes=${m.touched_nodes}, files=${m.changed_files}.`,
+                why: "Change touches many components; consider splitting.",
+                where: {},
+                metrics: { touched_nodes: m.touched_nodes, changed_files: m.changed_files },
+                recommendation: {
+                    do: [
+                        "Split PR by domain/layer",
+                        "Ensure spec_map coverage for each chunk",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 13) DG_SCOPE_EXPLOSION
+    (m) => {
+        if (m.touched_nodes > 25 || m.cross_domain_edges > 6) {
+            return {
+                code: "DG_SCOPE_EXPLOSION",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Scope explosion: nodes=${m.touched_nodes}, cross_domain=${m.cross_domain_edges}.`,
+                why: "Too many impacted components; blast radius is unacceptable.",
+                where: {},
+                metrics: { touched_nodes: m.touched_nodes, cross_domain_edges: m.cross_domain_edges },
+                recommendation: {
+                    do: [
+                        "Stop and re-scope",
+                        "Create explicit work_order boundaries",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // -------------------------------------------------------------------------
+    // E) BitNet risk
+    // -------------------------------------------------------------------------
+    // 14) DG_RISK_SCORE_HIGH
+    (m) => {
+        if (m.risk_score >= 15) {
+            return {
+                code: "DG_RISK_SCORE_HIGH",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Risk score high: ${m.risk_score} >= 15.`,
+                why: "BitNet analysis indicates critical risk level.",
+                where: {},
+                metrics: { risk_score: m.risk_score },
+                recommendation: {
+                    do: [
+                        "Address HIGH severity annotations",
+                        "Add tests/contracts before merge",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 15) DG_RISK_SCORE_MED
+    (m) => {
+        if (m.risk_score >= 7 && m.risk_score < 15) {
+            return {
+                code: "DG_RISK_SCORE_MED",
+                severity: "P1",
+                level: "FIX",
+                message: `Risk score medium: ${m.risk_score} >= 7.`,
+                why: "BitNet analysis indicates elevated risk.",
+                where: {},
+                metrics: { risk_score: m.risk_score },
+                recommendation: {
+                    do: [
+                        "Review MEDIUM/HIGH annotations",
+                        "Add guardrails",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 16) DG_SUBPROCESS_BYPASS (requires annotation data)
+    // Placeholder - requires BitNet annotations integration
+    // -------------------------------------------------------------------------
+    // F) Design contract mismatch (optional)
+    // -------------------------------------------------------------------------
+    // 17) DG_SPEC_MAP_MISMATCH - requires spec_map comparison
+    // 18) DG_DIAGRAM_CONTRACT_MISSING - requires static diagrams check
+    // -------------------------------------------------------------------------
+    // G) Critical node policy
+    // -------------------------------------------------------------------------
+    // 19) DG_CRITICAL_LOW_CONF
+    (m) => {
+        if (m.critical_nodes_touched > 0 && m.avg_confidence < 0.6) {
+            return {
+                code: "DG_CRITICAL_LOW_CONF",
+                severity: "P0",
+                level: "BLOCK",
+                message: `Critical component touched with low mapping confidence (${(m.avg_confidence * 100).toFixed(1)}%).`,
+                why: "Critical nodes require high-confidence mapping.",
+                where: {},
+                metrics: { critical_nodes_touched: m.critical_nodes_touched, avg_confidence: m.avg_confidence },
+                recommendation: {
+                    do: [
+                        "Fix mapping first",
+                        "Add explicit approvals/tests",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+    // 20) DG_CRITICAL_TOUCHED
+    (m) => {
+        if (m.critical_nodes_touched > 0 && m.avg_confidence >= 0.6) {
+            return {
+                code: "DG_CRITICAL_TOUCHED",
+                severity: "P1",
+                level: "FIX",
+                message: `Critical component touched: ${m.critical_nodes_touched} nodes.`,
+                why: "Critical components require extra review.",
+                where: {},
+                metrics: { critical_nodes_touched: m.critical_nodes_touched },
+                recommendation: {
+                    do: [
+                        "Require extra review",
+                        "Ensure rollback plan",
+                    ],
+                },
+            };
+        }
+        return null;
+    },
+];
+// ============================================================================
+// Type Guards for Violation
+// ============================================================================
+/**
+ * Type guard to check if an object is a valid Violation
+ */
+function isViolation(obj) {
+    if (!obj || typeof obj !== "object")
+        return false;
+    const v = obj;
+    return (typeof v.code === "string" &&
+        typeof v.file === "string" &&
+        typeof v.severity === "string");
+}
+/**
+ * Safely filter violations by code
+ */
+function filterViolationsByCode(violations, code) {
+    return violations.filter((v) => isViolation(v) && v.code === code);
+}
+/**
+ * Get layer order index for a node (lower = higher in stack)
+ */
+function getLayerIndex(layer) {
+    return LAYER_ORDER[layer] ?? LAYER_ORDER.UNKNOWN;
+}
+/**
+ * Build a map of node_id to layer index for fast lookup
+ */
+function buildNodeLayerMap(nodes) {
+    const map = new Map();
+    for (const node of nodes) {
+        map.set(node.node_id, getLayerIndex(node.layer));
+    }
+    return map;
+}
+/**
+ * Detect layer skip: edge spans more than 1 layer
+ * e.g., UI (0) → DOMAIN (4) skips 3 layers
+ */
+function countLayerSkipEdges(edges, nodeLayerMap) {
+    let count = 0;
+    for (const edge of edges) {
+        const fromLayer = nodeLayerMap.get(edge.from_node_id);
+        const toLayer = nodeLayerMap.get(edge.to_node_id);
+        if (fromLayer !== undefined && toLayer !== undefined) {
+            const diff = Math.abs(toLayer - fromLayer);
+            // Skip detection: more than 1 layer difference (skipping intermediate)
+            if (diff > 1) {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Detect reverse dependency: edge goes from lower layer to higher layer
+ * e.g., SERVICE (3) → API (2) is reverse (should be API → SERVICE)
+ */
+function countReverseEdges(edges, nodeLayerMap) {
+    let count = 0;
+    for (const edge of edges) {
+        const fromLayer = nodeLayerMap.get(edge.from_node_id);
+        const toLayer = nodeLayerMap.get(edge.to_node_id);
+        if (fromLayer !== undefined && toLayer !== undefined) {
+            // Reverse: dependency flows "upward" (from higher index to lower index)
+            // e.g., DOMAIN (4) calling API (2) is reverse
+            if (fromLayer > toLayer) {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+// ============================================================================
+// Multi-match Analysis
+// ============================================================================
+/**
+ * Count files that map to multiple nodes and find max matches
+ */
+function analyzeMultiMatch(model) {
+    // Build file → node mapping from violations or model metadata
+    const fileNodeCounts = new Map();
+    // Count file appearances across nodes (using file_count as proxy)
+    // In a full implementation, this would use the actual mapping data
+    for (const node of model.nodes) {
+        // Each node has files mapped to it; track overlap
+        // This is a simplified implementation - actual would need file-to-node mapping
+        if (node.file_count > 1) {
+            // Estimate: nodes with high file_count may indicate multi-match
+            const estimatedMultiMatch = Math.floor(node.file_count / 3);
+            if (estimatedMultiMatch > 0) {
+                fileNodeCounts.set(node.node_id, estimatedMultiMatch);
+            }
+        }
+    }
+    // Check violations for multi-match indicators
+    const multiMatchViolations = filterViolationsByCode(model.violations, "MULTI_MATCH");
+    for (const v of multiMatchViolations) {
+        const current = fileNodeCounts.get(v.file) ?? 0;
+        fileNodeCounts.set(v.file, current + 1);
+    }
+    const counts = Array.from(fileNodeCounts.values());
+    return {
+        multiMatchFiles: counts.filter(c => c > 1).length,
+        maxMatchesPerFile: counts.length > 0 ? Math.max(...counts) : 0,
+    };
+}
+// ============================================================================
+// Control Plane Detection
+// ============================================================================
+/**
+ * Simple glob-like pattern matching
+ */
+function matchesPattern(path, pattern) {
+    // Convert glob pattern to regex
+    const regexStr = pattern
+        .replace(/\*\*/g, "§§") // Temporarily replace **
+        .replace(/\*/g, "[^/]*") // Single * matches within segment
+        .replace(/§§/g, ".*"); // ** matches across segments
+    const regex = new RegExp(`^${regexStr}$|/${regexStr}$`);
+    return regex.test(path);
+}
+/**
+ * Count control-plane path hits
+ */
+function countControlPlaneHits(model) {
+    let count = 0;
+    // Check violations for control plane touches
+    for (const violation of model.violations) {
+        if (!isViolation(violation))
+            continue;
+        for (const pattern of CONTROL_PLANE_PATTERNS) {
+            if (matchesPattern(violation.file, pattern)) {
+                count++;
+                break; // Don't double-count same file
+            }
+        }
+    }
+    // Also check unmapped files that might be control plane
+    for (const file of model.unmapped_files) {
+        for (const pattern of CONTROL_PLANE_PATTERNS) {
+            if (matchesPattern(file, pattern)) {
+                count++;
+                break;
+            }
+        }
+    }
+    return count;
+}
+// ============================================================================
+// Critical Node Detection
+// ============================================================================
+/**
+ * Check if a node matches critical patterns
+ */
+function isCriticalNode(nodeId) {
+    for (const pattern of CRITICAL_NODE_PATTERNS) {
+        // Convert pattern to regex
+        const regexStr = pattern
+            .replace(/\./g, "\\.")
+            .replace(/\*/g, "[^.]*");
+        const regex = new RegExp(`^${regexStr}$`);
+        if (regex.test(nodeId)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Count critical nodes that are touched (have changes)
+ */
+function countCriticalNodesTouched(nodes) {
+    return nodes.filter(node => {
+        // Node is "touched" if it has stereotypes indicating change
+        const hasTouchedStereotype = node.stereotype.some(s => s === "CHANGED" || s === "RISK");
+        return hasTouchedStereotype && isCriticalNode(node.node_id);
+    }).length;
+}
+// ============================================================================
+// Metrics Extraction
+// ============================================================================
+export function extractMetrics(model, totalFiles) {
+    const unknownRate = totalFiles > 0 ? model.unmapped_files.length / totalFiles : 0;
+    const crossDomainEdges = model.edges.filter(e => e.stereotype === "CROSS_DOMAIN").length;
+    // Calculate average confidence
+    const confidences = model.nodes.map(n => n.confidence).filter(c => c > 0);
+    const avgConfidence = confidences.length > 0
+        ? confidences.reduce((a, b) => a + b, 0) / confidences.length
+        : 1.0;
+    // Count forbidden violations (with type guard)
+    const forbiddenHits = filterViolationsByCode(model.violations, "DENY_PATH_TOUCHED").length;
+    // Build node layer map for edge analysis
+    const nodeLayerMap = buildNodeLayerMap(model.nodes);
+    // Layer skip detection
+    const layerSkipEdges = countLayerSkipEdges(model.edges, nodeLayerMap);
+    // Reverse edge detection
+    const reverseEdges = countReverseEdges(model.edges, nodeLayerMap);
+    // Multi-match analysis
+    const { multiMatchFiles, maxMatchesPerFile } = analyzeMultiMatch(model);
+    // Control plane hits
+    const controlPlaneHits = countControlPlaneHits(model);
+    // Critical nodes touched
+    const criticalNodesTouched = countCriticalNodesTouched(model.nodes);
+    return {
+        unknown_rate: unknownRate,
+        changed_files: totalFiles,
+        touched_nodes: model.nodes.length,
+        cross_domain_edges: crossDomainEdges,
+        risk_score: 0, // From BitNet - populated via overrideMetrics when available
+        avg_confidence: avgConfidence,
+        forbidden_hits: forbiddenHits,
+        layer_skip_edges: layerSkipEdges,
+        reverse_edges: reverseEdges,
+        multi_match_files: multiMatchFiles,
+        max_matches_per_file: maxMatchesPerFile,
+        control_plane_hits: controlPlaneHits,
+        critical_nodes_touched: criticalNodesTouched,
+    };
+}
+// ============================================================================
+// Gate Evaluation
+// ============================================================================
+export function evaluateGate(model, totalFiles, overrideMetrics) {
+    const baseMetrics = extractMetrics(model, totalFiles);
+    const metrics = { ...baseMetrics, ...overrideMetrics };
+    const reasons = [];
+    for (const rule of RULES) {
+        const reason = rule(metrics, model);
+        if (reason) {
+            reasons.push(reason);
+        }
+    }
+    // Count by level
+    const blockCount = reasons.filter(r => r.level === "BLOCK").length;
+    const fixCount = reasons.filter(r => r.level === "FIX").length;
+    const hintCount = reasons.filter(r => r.level === "GO_HINT").length;
+    // Determine verdict
+    let verdict;
+    let exitCode;
+    if (blockCount > 0) {
+        verdict = "BLOCK";
+        exitCode = 2;
+    }
+    else if (fixCount > 0) {
+        verdict = "FIX";
+        exitCode = 1;
+    }
+    else {
+        verdict = "GO";
+        exitCode = 0;
+    }
+    return {
+        schema_version: "diagram.gate.v2",
+        run_id: model.run_id,
+        generated_at: new Date().toISOString(),
+        verdict,
+        exit_code: exitCode,
+        metrics,
+        reasons,
+        summary: {
+            total_reasons: reasons.length,
+            block_count: blockCount,
+            fix_count: fixCount,
+            hint_count: hintCount,
+        },
+    };
+}
+// ============================================================================
+// Navigation Output Formatter
+// ============================================================================
+export function formatNavigationOutput(reason) {
+    const lines = [];
+    // WHERE
+    const whereParts = [];
+    if (reason.where.nodes?.length) {
+        whereParts.push(`nodes={${reason.where.nodes.join(", ")}}`);
+    }
+    if (reason.where.files?.length) {
+        whereParts.push(`files={${reason.where.files.join(", ")}}`);
+    }
+    if (reason.where.edges?.length) {
+        const edgeStrs = reason.where.edges.map(e => `${e.from}->${e.to}`);
+        whereParts.push(`edges={${edgeStrs.join(", ")}}`);
+    }
+    lines.push(`WHERE: ${whereParts.join(", ") || "(no location)"}`);
+    // WHY
+    const metricStrs = Object.entries(reason.metrics)
+        .filter(([_, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${typeof v === "number" ? v.toFixed(2) : v}`);
+    lines.push(`WHY: ${reason.why} (${metricStrs.join(", ")})`);
+    // NEXT
+    lines.push(`NEXT: ${reason.recommendation.do[0] || "(no action)"}`);
+    return lines.join("\n");
+}
+// ============================================================================
+// CI Exit Code Helper
+// ============================================================================
+export function getExitCode(verdict) {
+    return verdict.exit_code;
+}