@syke1/mcp-server 1.4.17 → 1.4.18

package/dist/scoring/risk-scorer.js

@@ -0,0 +1,623 @@
+"use strict";
+/**
+ * Composite Risk Scoring for SYKE.
+ *
+ * Combines multiple signals (fan-in, instability, cyclomatic complexity,
+ * cascade depth) into a single 0-1 risk score using weighted normalization.
+ *
+ * Based on Robert C. Martin's stability metrics and standard software
+ * engineering coupling/cohesion analysis.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RISK_WEIGHTS = void 0;
+exports.invalidateProjectMetrics = invalidateProjectMetrics;
+exports.computeCouplingMetrics = computeCouplingMetrics;
+exports.computeInstability = computeInstability;
+exports.computeComplexity = computeComplexity;
+exports.computeCascadeDepth = computeCascadeDepth;
+exports.classifyCompositeRisk = classifyCompositeRisk;
+exports.computeRiskScore = computeRiskScore;
+exports.computeProjectMetrics = computeProjectMetrics;
+exports.getRiskScore = getRiskScore;
+exports.formatRiskScore = formatRiskScore;
+const fs = __importStar(require("fs"));
+const plugin_1 = require("../languages/plugin");
+const pagerank_1 = require("./pagerank");
+// ── Weights (tunable constants) ──
+exports.RISK_WEIGHTS = {
+    fanIn: 0.30, // Most important: how many things break
+    stability: 0.20, // Foundation files are riskier
+    complexity: 0.20, // Complex files are harder to change safely
+    cascadeDepth: 0.15, // Deep cascades mean wider blast radius
+    pageRank: 0.15, // Recursive importance from the dependency graph
+};
+// ── Risk Level Thresholds ──
+const RISK_THRESHOLDS = {
+    CRITICAL: 0.8,
+    HIGH: 0.6,
+    MEDIUM: 0.4,
+    LOW: 0.2,
+};
+// ── Cached Project Metrics ──
+let cachedProjectMetrics = null;
+let cachedProjectRoot = null;
+/**
+ * Invalidate cached project metrics. Call when the graph is rebuilt.
+ */
+function invalidateProjectMetrics() {
+    cachedProjectMetrics = null;
+    cachedProjectRoot = null;
+}
+// ── Core Metric Computations ──
+/**
+ * Compute coupling metrics for a single file from the dependency graph.
+ */
+function computeCouplingMetrics(filePath, graph) {
+    const fanIn = (graph.reverse.get(filePath) || []).length;
+    const fanOut = (graph.forward.get(filePath) || []).length;
+    const transitiveFanIn = computeTransitiveFanIn(filePath, graph);
+    return { fanIn, fanOut, transitiveFanIn };
+}
+/**
+ * BFS reverse traversal to count all transitive dependents.
+ */
+function computeTransitiveFanIn(filePath, graph) {
+    const visited = new Set();
+    const queue = [];
+    const directDeps = graph.reverse.get(filePath) || [];
+    for (const dep of directDeps) {
+        if (!visited.has(dep)) {
+            visited.add(dep);
+            queue.push(dep);
+        }
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const dependents = graph.reverse.get(current) || [];
+        for (const dep of dependents) {
+            if (!visited.has(dep) && dep !== filePath) {
+                visited.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return visited.size;
+}
+/**
+ * Robert C. Martin's Instability Index.
+ *
+ * I = Ce / (Ca + Ce) where Ca = fanIn, Ce = fanOut
+ * 0 = maximally stable (everything depends on it, dangerous to change)
+ * 1 = maximally unstable (leaf node, safe to change)
+ */
+function computeInstability(fanIn, fanOut) {
+    if (fanIn + fanOut === 0)
+        return 0.5; // isolated file
+    return fanOut / (fanIn + fanOut);
+}
+// ── Cyclomatic Complexity (regex-based) ──
+/**
+ * Language-specific regex patterns for counting decision points.
+ * Each pattern matches one decision point in source code.
+ */
+const COMPLEXITY_PATTERNS = {
+    typescript: [
+        /\bif\s*\(/g,
+        /\belse\s+if\s*\(/g,
+        /\bfor\s*\(/g,
+        /\bwhile\s*\(/g,
+        /\bdo\s*\{/g,
+        /\bswitch\s*\(/g,
+        /\bcase\s+/g,
+        /\bcatch\s*\(/g,
+        /\?\s*[^:?]/g, // ternary (simplified)
+        /&&/g,
+        /\|\|/g,
+        /\?\?/g,
+    ],
+    javascript: [], // same as typescript, populated below
+    dart: [
+        /\bif\s*\(/g,
+        /\belse\s+if\s*\(/g,
+        /\bfor\s*\(/g,
+        /\bwhile\s*\(/g,
+        /\bdo\s*\{/g,
+        /\bswitch\s*\(/g,
+        /\bcase\s+/g,
+        /\bcatch\s*\(/g,
+        /\?\s*[^:?]/g,
+        /&&/g,
+        /\|\|/g,
+        /\?\?/g,
+        /\blate\s+/g,
+    ],
+    python: [
+        /\bif\s+/g,
+        /\belif\s+/g,
+        /\bfor\s+/g,
+        /\bwhile\s+/g,
+        /\bexcept\s*/g,
+        /\band\b/g,
+        /\bor\b/g,
+        /\bwith\s+/g,
+    ],
+    go: [
+        /\bif\s+/g,
+        /\bfor\s+/g,
+        /\bselect\s*\{/g,
+        /\bcase\s+/g,
+        /&&/g,
+        /\|\|/g,
+    ],
+    rust: [
+        /\bif\s+/g,
+        /\belse\s+if\s+/g,
+        /\bfor\s+/g,
+        /\bwhile\s+/g,
+        /\bloop\s*\{/g,
+        /\bmatch\s+/g,
+        /=>/g,
+        /&&/g,
+        /\|\|/g,
+    ],
+    java: [
+        /\bif\s*\(/g,
+        /\belse\s+if\s*\(/g,
+        /\bfor\s*\(/g,
+        /\bwhile\s*\(/g,
+        /\bdo\s*\{/g,
+        /\bswitch\s*\(/g,
+        /\bcase\s+/g,
+        /\bcatch\s*\(/g,
+        /\?\s*[^:?]/g,
+        /&&/g,
+        /\|\|/g,
+    ],
+    cpp: [
+        /\bif\s*\(/g,
+        /\belse\s+if\s*\(/g,
+        /\bfor\s*\(/g,
+        /\bwhile\s*\(/g,
+        /\bdo\s*\{/g,
+        /\bswitch\s*\(/g,
+        /\bcase\s+/g,
+        /\bcatch\s*\(/g,
+        /\?\s*[^:?]/g,
+        /&&/g,
+        /\|\|/g,
+    ],
+    ruby: [
+        /\bif\s+/g,
+        /\belsif\s+/g,
+        /\bunless\s+/g,
+        /\bwhile\s+/g,
+        /\buntil\s+/g,
+        /\bfor\s+/g,
+        /\bwhen\s+/g,
+        /\brescue\b/g,
+        /&&/g,
+        /\|\|/g,
+    ],
+};
+// JavaScript uses same patterns as TypeScript
+COMPLEXITY_PATTERNS.javascript = COMPLEXITY_PATTERNS.typescript;
+/**
+ * Map language plugin IDs to complexity pattern keys.
+ */
+const LANGUAGE_ID_MAP = {
+    typescript: "typescript",
+    dart: "dart",
+    python: "python",
+    go: "go",
+    rust: "rust",
+    java: "java",
+    cpp: "cpp",
+    ruby: "ruby",
+};
+/**
+ * Detect the language for a file based on extension or plugin ID.
+ */
+function detectLanguageForFile(filePath) {
+    const plugin = (0, plugin_1.getPluginForFile)(filePath);
+    if (plugin) {
+        return LANGUAGE_ID_MAP[plugin.id] || "typescript";
+    }
+    // Fallback: detect by extension
+    const ext = filePath.split(".").pop()?.toLowerCase() || "";
+    const extMap = {
+        ts: "typescript", tsx: "typescript", js: "javascript", jsx: "javascript",
+        dart: "dart", py: "python", go: "go", rs: "rust",
+        java: "java", cpp: "cpp", cc: "cpp", cxx: "cpp", c: "cpp", h: "cpp", hpp: "cpp",
+        rb: "ruby",
+    };
+    return extMap[ext] || "typescript";
+}
+/**
+ * Strip comments and string literals from source code to avoid
+ * false positives in complexity counting.
+ */
+function stripCommentsAndStrings(content) {
+    // Remove block comments
+    let stripped = content.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Remove line comments
+    stripped = stripped.replace(/\/\/.*$/gm, "");
+    // Remove Python/Ruby line comments
+    stripped = stripped.replace(/#.*$/gm, "");
+    // Remove double-quoted strings (simple approach)
+    stripped = stripped.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    // Remove single-quoted strings
+    stripped = stripped.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+    // Remove template literals
+    stripped = stripped.replace(/`(?:[^`\\]|\\.)*`/g, "``");
+    return stripped;
+}
+/**
+ * Compute cyclomatic complexity of source code using regex-based
+ * decision point counting.
+ *
+ * Returns the raw count of decision points (base complexity of 1 is NOT added).
+ */
+function computeComplexity(content, language) {
+    const patterns = COMPLEXITY_PATTERNS[language] || COMPLEXITY_PATTERNS.typescript;
+    const stripped = stripCommentsAndStrings(content);
+    let count = 0;
+    for (const pattern of patterns) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        const matches = stripped.match(pattern);
+        if (matches) {
+            count += matches.length;
+        }
+    }
+    return count;
+}
+// ── Cascade Depth ──
+/**
+ * Compute the maximum cascade depth from the condensed DAG.
+ * This is the longest path from the file's SCC through the reverse edges
+ * of the condensed DAG (i.e., how many layers deep the impact propagates).
+ */
+function computeCascadeDepth(filePath, graph) {
+    const scc = graph.scc;
+    if (!scc) {
+        // Fallback: use simple BFS depth on raw graph
+        return computeRawCascadeDepth(filePath, graph);
+    }
+    const sccIndex = scc.nodeToComponent.get(filePath);
+    if (sccIndex === undefined)
+        return 0;
+    // BFS on condensed DAG reverse edges to find max depth
+    const visited = new Map(); // SCC index -> depth
+    visited.set(sccIndex, 0);
+    const queue = [
+        { idx: sccIndex, depth: 0 },
+    ];
+    let maxDepth = 0;
+    while (queue.length > 0) {
+        const { idx, depth } = queue.shift();
+        const dependentSCCs = scc.condensed.reverse.get(idx) || [];
+        for (const depSCC of dependentSCCs) {
+            if (!visited.has(depSCC)) {
+                const newDepth = depth + 1;
+                visited.set(depSCC, newDepth);
+                maxDepth = Math.max(maxDepth, newDepth);
+                queue.push({ idx: depSCC, depth: newDepth });
+            }
+        }
+    }
+    return maxDepth;
+}
+/**
+ * Fallback: simple BFS depth on the raw reverse graph.
+ */
+function computeRawCascadeDepth(filePath, graph) {
+    const visited = new Set();
+    visited.add(filePath);
+    let currentLevel = [filePath];
+    let depth = 0;
+    while (currentLevel.length > 0) {
+        const nextLevel = [];
+        for (const file of currentLevel) {
+            const dependents = graph.reverse.get(file) || [];
+            for (const dep of dependents) {
+                if (!visited.has(dep)) {
+                    visited.add(dep);
+                    nextLevel.push(dep);
+                }
+            }
+        }
+        if (nextLevel.length > 0) {
+            depth++;
+        }
+        currentLevel = nextLevel;
+    }
+    return depth;
+}
+// ── Normalization ──
+/**
+ * Min-max normalize a value to the 0-1 range.
+ * Returns 0 if max equals min (all values identical).
+ */
+function normalize(value, min, max) {
+    if (max <= min)
+        return 0;
+    return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+// ── Risk Level Classification ──
+/**
+ * Map a composite score (0-1) to a risk level.
+ */
+function classifyCompositeRisk(score) {
+    if (score >= RISK_THRESHOLDS.CRITICAL)
+        return "CRITICAL";
+    if (score >= RISK_THRESHOLDS.HIGH)
+        return "HIGH";
+    if (score >= RISK_THRESHOLDS.MEDIUM)
+        return "MEDIUM";
+    if (score >= RISK_THRESHOLDS.LOW)
+        return "LOW";
+    return "SAFE";
+}
+// ── Main Scoring Functions ──
+/**
+ * Read file content from disk (used when no content is passed).
+ */
+function readFileContent(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the composite risk score for a single file.
+ *
+ * If `projectMetrics` is provided, uses pre-computed normalization bounds.
+ * Otherwise, uses raw metrics without normalization (less accurate but functional).
+ */
+function computeRiskScore(filePath, graph, fileContent, projectMetrics) {
+    // Compute coupling metrics
+    const coupling = computeCouplingMetrics(filePath, graph);
+    // Compute instability
+    const instability = computeInstability(coupling.fanIn, coupling.fanOut);
+    // Compute complexity
+    const content = fileContent ?? readFileContent(filePath);
+    const language = detectLanguageForFile(filePath);
+    const complexity = content ? computeComplexity(content, language) : 0;
+    // Compute cascade depth
+    const cascadeDepth = computeCascadeDepth(filePath, graph);
+    // Normalize using project-wide bounds (or use raw values)
+    let normalizedFanIn;
+    let normalizedComplexity;
+    let normalizedCascadeDepth;
+    if (projectMetrics) {
+        normalizedFanIn = normalize(coupling.transitiveFanIn, 0, projectMetrics.maxTransitiveFanIn);
+        normalizedComplexity = normalize(complexity, 0, projectMetrics.maxComplexity);
+        normalizedCascadeDepth = normalize(cascadeDepth, 0, projectMetrics.maxCascadeDepth);
+    }
+    else {
+        // Without project metrics, use simple heuristic normalization
+        normalizedFanIn = normalize(coupling.transitiveFanIn, 0, Math.max(coupling.transitiveFanIn, 20));
+        normalizedComplexity = normalize(complexity, 0, Math.max(complexity, 50));
+        normalizedCascadeDepth = normalize(cascadeDepth, 0, Math.max(cascadeDepth, 5));
+    }
+    // Retrieve PageRank data if available on the graph
+    let pageRankScore;
+    let pageRankPercentile;
+    let normalizedPageRank = 0;
+    let hasPageRank = false;
+    if (graph.pageRank) {
+        const prData = (0, pagerank_1.getFileRank)(filePath, graph.pageRank);
+        if (prData) {
+            pageRankScore = prData.score;
+            pageRankPercentile = prData.percentile;
+            normalizedPageRank = prData.percentile / 100; // 0-1 range
+            hasPageRank = true;
+        }
+    }
+    // Composite score — include PageRank if available, otherwise normalize
+    // remaining weights to sum to 1 for backward compatibility
+    let composite;
+    if (hasPageRank) {
+        composite =
+            exports.RISK_WEIGHTS.fanIn * normalizedFanIn +
+                exports.RISK_WEIGHTS.stability * (1 - instability) +
+                exports.RISK_WEIGHTS.complexity * normalizedComplexity +
+                exports.RISK_WEIGHTS.cascadeDepth * normalizedCascadeDepth +
+                exports.RISK_WEIGHTS.pageRank * normalizedPageRank;
+    }
+    else {
+        // Fallback: redistribute pageRank weight proportionally among other signals
+        const baseSum = exports.RISK_WEIGHTS.fanIn + exports.RISK_WEIGHTS.stability +
+            exports.RISK_WEIGHTS.complexity + exports.RISK_WEIGHTS.cascadeDepth;
+        composite =
+            (exports.RISK_WEIGHTS.fanIn / baseSum) * normalizedFanIn +
+                (exports.RISK_WEIGHTS.stability / baseSum) * (1 - instability) +
+                (exports.RISK_WEIGHTS.complexity / baseSum) * normalizedComplexity +
+                (exports.RISK_WEIGHTS.cascadeDepth / baseSum) * normalizedCascadeDepth;
+    }
+    // Clamp to 0-1
+    const clampedComposite = Math.min(1, Math.max(0, composite));
+    return {
+        composite: Math.round(clampedComposite * 100) / 100,
+        fanIn: coupling.fanIn,
+        fanOut: coupling.fanOut,
+        transitiveFanIn: coupling.transitiveFanIn,
+        instability: Math.round(instability * 100) / 100,
+        complexity,
+        normalizedComplexity: Math.round(normalizedComplexity * 100) / 100,
+        cascadeDepth,
+        riskLevel: classifyCompositeRisk(clampedComposite),
+        pageRank: pageRankScore,
+        pageRankPercentile,
+    };
+}
+/**
+ * Pre-compute metrics for all files in the project.
+ * This establishes normalization bounds and caches per-file scores.
+ *
+ * Uses lazy initialization and caches results until invalidated.
+ */
+function computeProjectMetrics(graph, getFileContent) {
+    // Return cached if available and for the same project
+    if (cachedProjectMetrics && cachedProjectRoot === graph.projectRoot) {
+        return cachedProjectMetrics;
+    }
+    const contentGetter = getFileContent || readFileContent;
+    // Phase 1: Compute raw metrics for all files
+    const rawMetrics = new Map();
+    let maxFanIn = 0;
+    let maxTransitiveFanIn = 0;
+    let maxComplexity = 0;
+    let maxCascadeDepth = 0;
+    for (const filePath of graph.files) {
+        const coupling = computeCouplingMetrics(filePath, graph);
+        const instability = computeInstability(coupling.fanIn, coupling.fanOut);
+        const content = contentGetter(filePath);
+        const language = detectLanguageForFile(filePath);
+        const complexity = content ? computeComplexity(content, language) : 0;
+        const cascadeDepth = computeCascadeDepth(filePath, graph);
+        rawMetrics.set(filePath, { coupling, instability, complexity, cascadeDepth });
+        maxFanIn = Math.max(maxFanIn, coupling.fanIn);
+        maxTransitiveFanIn = Math.max(maxTransitiveFanIn, coupling.transitiveFanIn);
+        maxComplexity = Math.max(maxComplexity, complexity);
+        maxCascadeDepth = Math.max(maxCascadeDepth, cascadeDepth);
+    }
+    // Phase 2: Compute normalized composite scores for all files
+    const projectMetrics = {
+        maxFanIn,
+        maxTransitiveFanIn,
+        maxComplexity,
+        maxCascadeDepth,
+        fileMetrics: new Map(),
+    };
+    for (const [filePath, raw] of rawMetrics) {
+        const normalizedFanIn = normalize(raw.coupling.transitiveFanIn, 0, maxTransitiveFanIn);
+        const normalizedComplexity = normalize(raw.complexity, 0, maxComplexity);
+        const normalizedCascadeDepth = normalize(raw.cascadeDepth, 0, maxCascadeDepth);
+        // Retrieve PageRank data if available
+        let pageRankScore;
+        let pageRankPercentile;
+        let normalizedPageRank = 0;
+        let hasPageRank = false;
+        if (graph.pageRank) {
+            const prData = (0, pagerank_1.getFileRank)(filePath, graph.pageRank);
+            if (prData) {
+                pageRankScore = prData.score;
+                pageRankPercentile = prData.percentile;
+                normalizedPageRank = prData.percentile / 100;
+                hasPageRank = true;
+            }
+        }
+        let composite;
+        if (hasPageRank) {
+            composite =
+                exports.RISK_WEIGHTS.fanIn * normalizedFanIn +
+                    exports.RISK_WEIGHTS.stability * (1 - raw.instability) +
+                    exports.RISK_WEIGHTS.complexity * normalizedComplexity +
+                    exports.RISK_WEIGHTS.cascadeDepth * normalizedCascadeDepth +
+                    exports.RISK_WEIGHTS.pageRank * normalizedPageRank;
+        }
+        else {
+            const baseSum = exports.RISK_WEIGHTS.fanIn + exports.RISK_WEIGHTS.stability +
+                exports.RISK_WEIGHTS.complexity + exports.RISK_WEIGHTS.cascadeDepth;
+            composite =
+                (exports.RISK_WEIGHTS.fanIn / baseSum) * normalizedFanIn +
+                    (exports.RISK_WEIGHTS.stability / baseSum) * (1 - raw.instability) +
+                    (exports.RISK_WEIGHTS.complexity / baseSum) * normalizedComplexity +
+                    (exports.RISK_WEIGHTS.cascadeDepth / baseSum) * normalizedCascadeDepth;
+        }
+        const clampedComposite = Math.min(1, Math.max(0, composite));
+        projectMetrics.fileMetrics.set(filePath, {
+            composite: Math.round(clampedComposite * 100) / 100,
+            fanIn: raw.coupling.fanIn,
+            fanOut: raw.coupling.fanOut,
+            transitiveFanIn: raw.coupling.transitiveFanIn,
+            instability: Math.round(raw.instability * 100) / 100,
+            complexity: raw.complexity,
+            normalizedComplexity: Math.round(normalizedComplexity * 100) / 100,
+            cascadeDepth: raw.cascadeDepth,
+            riskLevel: classifyCompositeRisk(clampedComposite),
+            pageRank: pageRankScore,
+            pageRankPercentile,
+        });
+    }
+    // Cache the result
+    cachedProjectMetrics = projectMetrics;
+    cachedProjectRoot = graph.projectRoot;
+    console.error(`[syke:scoring] Project metrics computed for ${graph.files.size} files ` +
+        `(maxFanIn=${maxFanIn}, maxTransFanIn=${maxTransitiveFanIn}, ` +
+        `maxComplexity=${maxComplexity}, maxCascadeDepth=${maxCascadeDepth})`);
+    return projectMetrics;
+}
+/**
+ * Get the cached risk score for a file, or compute it on the fly.
+ * Uses project-wide normalization when available.
+ */
+function getRiskScore(filePath, graph, fileContent) {
+    // Try to use cached project metrics for accurate normalization
+    if (cachedProjectMetrics && cachedProjectRoot === graph.projectRoot) {
+        const cached = cachedProjectMetrics.fileMetrics.get(filePath);
+        if (cached)
+            return cached;
+        // File not in cache (possibly new), compute with project bounds
+        return computeRiskScore(filePath, graph, fileContent ?? null, cachedProjectMetrics);
+    }
+    // No project metrics available, compute without normalization
+    return computeRiskScore(filePath, graph, fileContent ?? null);
+}
+/**
+ * Format a risk score for display in MCP tool output.
+ */
+function formatRiskScore(score) {
+    const stabilityDesc = score.instability <= 0.2 ? "very stable -- dangerous to change" :
+        score.instability <= 0.4 ? "stable -- be cautious" :
+            score.instability <= 0.6 ? "balanced" :
+                score.instability <= 0.8 ? "unstable -- relatively safe" :
+                    "very unstable -- safe to change";
+    const lines = [
+        `Risk Score: ${score.composite.toFixed(2)} (${score.riskLevel})`,
+        `  Fan-in: ${score.transitiveFanIn} (direct: ${score.fanIn}, fan-out: ${score.fanOut})`,
+        `  Stability: ${score.instability.toFixed(2)} (${stabilityDesc})`,
+        `  Complexity: ${score.complexity} (normalized: ${score.normalizedComplexity.toFixed(2)})`,
+        `  Cascade depth: ${score.cascadeDepth} level(s)`,
+    ];
+    if (score.pageRank !== undefined && score.pageRankPercentile !== undefined) {
+        lines.push(`  PageRank: ${score.pageRank.toFixed(6)} (${score.pageRankPercentile}th percentile)`);
+    }
+    return lines.join("\n");
+}

package/dist/tools/analyze-impact.d.ts

@@ -1,5 +1,13 @@
 import { DependencyGraph } from "../graph";
+import { RiskScore } from "../scoring/risk-scorer";
+import { MemoCache } from "../graph/memo-cache";
 export type RiskLevel = "HIGH" | "MEDIUM" | "LOW" | "NONE";
+export interface CoupledFileInfo {
+    relativePath: string;
+    confidence: number;
+    coChangeCount: number;
+    inDependencyGraph: boolean;
+}
 export interface ImpactResult {
     filePath: string;
     relativePath: string;
@@ -7,11 +15,38 @@ export interface ImpactResult {
     directDependents: string[];
     transitiveDependents: string[];
     totalImpacted: number;
+    /** Cascade depth of each impacted file in the condensed DAG */
+    cascadeLevels?: Map<string, number>;
+    /** Files in the same cyclic SCC as the changed file (if any) */
+    circularCluster?: string[];
+    /** Total number of SCCs in the project */
+    sccCount?: number;
+    /** Number of SCCs with more than one file (circular dependencies) */
+    cyclicSCCs?: number;
+    /** Composite risk score (0-1) combining multiple signals */
+    riskScore?: RiskScore;
+    /** Files that historically co-change but may not be in the dependency graph */
+    coupledFiles?: CoupledFileInfo[];
+    /** True if the BFS result came from the memo cache (fast path) */
+    fromCache?: boolean;
 }
 /**
  * BFS reverse traversal to find all files impacted by modifying `filePath`.
+ * When SCC data is available, uses the condensed DAG for more accurate
+ * cascade-level analysis and circular dependency detection.
+ *
+ * Optionally computes a composite risk score when `includeRiskScore` is true.
+ * Optionally computes historical change coupling when `includeCoupling` is true.
+ */
+export declare function analyzeImpact(filePath: string, graph: DependencyGraph, options?: {
+    includeRiskScore?: boolean;
+    fileContent?: string | null;
+    includeCoupling?: boolean;
+}): Promise<ImpactResult>;
+/**
+ * Get the memo cache instance for diagnostics (cache stats, etc.).
  */
-export declare function analyzeImpact(filePath: string, graph: DependencyGraph): ImpactResult;
+export declare function getImpactMemoCache(): MemoCache;
 export declare function classifyRisk(count: number): RiskLevel;
 /**
  * Rank files by number of reverse dependents (hub score).