@syke1/mcp-server 1.4.17 → 1.4.18

package/dist/index.js

@@ -50,6 +50,9 @@ const graph_1 = require("./graph");
 const plugin_1 = require("./languages/plugin");
 const analyze_impact_1 = require("./tools/analyze-impact");
 const gate_build_1 = require("./tools/gate-build");
+const change_coupling_1 = require("./git/change-coupling");
+const risk_scorer_1 = require("./scoring/risk-scorer");
+const pagerank_1 = require("./scoring/pagerank");
 const analyzer_1 = require("./ai/analyzer");
 const provider_1 = require("./ai/provider");
 const server_1 = require("./web/server");
@@ -248,7 +251,7 @@ async function main() {
             case "gate_build": {
                 const graph = (0, graph_1.getGraph)(currentProjectRoot, currentPackageName);
                 const files = args.files?.map((f) => resolveFilePath(f, currentProjectRoot, graph.sourceDir));
-                const result = (0, gate_build_1.gateCheck)(graph, files);
+                const result = await (0, gate_build_1.gateCheck)(graph, files);
                 return {
                     content: [
                         { type: "text", text: appendDashboardFooter((0, gate_build_1.formatGateResult)(result)) },
@@ -273,24 +276,84 @@ async function main() {
                 if (!isFileInFreeSet(resolved, graph)) {
                     return { content: [{ type: "text", text: PRO_UPGRADE_MSG }] };
                 }
-                const result = (0, analyze_impact_1.analyzeImpact)(resolved, graph);
+                const result = await (0, analyze_impact_1.analyzeImpact)(resolved, graph, { includeRiskScore: true, includeCoupling: true });
+                const cachedTag = result.fromCache ? " (cached)" : "";
                 const lines = [
-                    `## Impact Analysis: ${result.relativePath}`,
+                    `## Impact Analysis: ${result.relativePath}${cachedTag}`,
                     `**Risk Level:** ${result.riskLevel}`,
                     `**Total impacted files:** ${result.totalImpacted}`,
                     "",
                 ];
+                // Show composite risk score
+                if (result.riskScore) {
+                    lines.push("### Composite Risk Score");
+                    lines.push((0, risk_scorer_1.formatRiskScore)(result.riskScore));
+                    lines.push("");
+                }
+                // Show circular dependency warning if file is in a cyclic SCC
+                if (result.circularCluster && result.circularCluster.length > 0) {
+                    lines.push("### Circular Dependency Cluster");
+                    lines.push(`This file is part of a circular dependency with ${result.circularCluster.length} other file(s):`);
+                    for (const f of result.circularCluster) {
+                        lines.push(`- ${f}`);
+                    }
+                    lines.push("**All files in this cluster are immediately affected by any change.**");
+                    lines.push("");
+                }
                 if (result.directDependents.length > 0) {
                     lines.push(`### Direct Dependents (${result.directDependents.length})`);
                     for (const d of result.directDependents) {
-                        lines.push(`- ${d}`);
+                        const level = result.cascadeLevels?.get(d);
+                        const levelStr = level !== undefined ? `, cascade level ${level}` : "";
+                        // Add PageRank percentile if available
+                        let prStr = "";
+                        if (graph.pageRank) {
+                            const absPath = path.normalize(path.join(graph.sourceDir, d));
+                            const prData = (0, pagerank_1.getFileRank)(absPath, graph.pageRank);
+                            if (prData) {
+                                prStr = `, PageRank ${prData.percentile}th percentile`;
+                            }
+                        }
+                        const annotationParts = [levelStr, prStr].filter(Boolean).join("");
+                        lines.push(`- ${d}${annotationParts ? ` (${annotationParts.replace(/^, /, "")})` : ""}`);
                     }
                 }
                 if (result.transitiveDependents.length > 0) {
                     lines.push("");
                     lines.push(`### Transitive Dependents (${result.transitiveDependents.length})`);
                     for (const d of result.transitiveDependents) {
-                        lines.push(`- ${d}`);
+                        const level = result.cascadeLevels?.get(d);
+                        const levelStr = level !== undefined ? `, cascade level ${level}` : "";
+                        // Add PageRank percentile if available
+                        let prStr = "";
+                        if (graph.pageRank) {
+                            const absPath = path.normalize(path.join(graph.sourceDir, d));
+                            const prData = (0, pagerank_1.getFileRank)(absPath, graph.pageRank);
+                            if (prData) {
+                                prStr = `, PageRank ${prData.percentile}th percentile`;
+                            }
+                        }
+                        const annotationParts = [levelStr, prStr].filter(Boolean).join("");
+                        lines.push(`- ${d}${annotationParts ? ` (${annotationParts.replace(/^, /, "")})` : ""}`);
+                    }
+                }
+                // Show historical change coupling (hidden dependencies)
+                if (result.coupledFiles && result.coupledFiles.length > 0) {
+                    lines.push("");
+                    lines.push("### Historical Change Coupling (hidden dependencies)");
+                    for (const cf of result.coupledFiles) {
+                        const pct = Math.round(cf.confidence * 100);
+                        lines.push(`  - ${cf.relativePath} (confidence: ${pct}%, co-changed ${cf.coChangeCount} times)`);
+                    }
+                    lines.push("These files frequently change together but have no import relationship.");
+                }
+                // SCC summary stats
+                if (result.sccCount !== undefined) {
+                    lines.push("");
+                    lines.push("### Graph Structure");
+                    lines.push(`- SCCs in project: ${result.sccCount}`);
+                    if (result.cyclicSCCs !== undefined && result.cyclicSCCs > 0) {
+                        lines.push(`- Circular dependency clusters: ${result.cyclicSCCs}`);
                     }
                 }
                 return { content: [{ type: "text", text: appendDashboardFooter(lines.join("\n")) }] };
@@ -312,13 +375,37 @@ async function main() {
                 if (!isFileInFreeSet(resolved, graph)) {
                     return { content: [{ type: "text", text: PRO_UPGRADE_MSG }] };
                 }
-                const result = (0, analyze_impact_1.analyzeImpact)(resolved, graph);
+                const result = await (0, analyze_impact_1.analyzeImpact)(resolved, graph, { includeRiskScore: true, includeCoupling: true });
                 const rel = path.relative(graph.sourceDir, resolved).replace(/\\/g, "/");
+                const safeCachedTag = result.fromCache ? " (cached)" : "";
+                // Enhanced output with composite risk score
+                let output = `${result.riskLevel} — ${rel} impacts ${result.totalImpacted} file(s)${safeCachedTag}`;
+                // Show file importance via PageRank
+                if (graph.pageRank) {
+                    const prData = (0, pagerank_1.getFileRank)(resolved, graph.pageRank);
+                    if (prData) {
+                        output += `\nFile importance: rank #${prData.rank} of ${graph.files.size} files (${prData.percentile}th percentile)`;
+                    }
+                }
+                if (result.riskScore) {
+                    output += `\n${(0, risk_scorer_1.formatRiskScore)(result.riskScore)}`;
+                }
+                // Mention high-confidence couplings as a warning
+                if (result.coupledFiles && result.coupledFiles.length > 0) {
+                    const highConf = result.coupledFiles.filter((cf) => cf.confidence >= 0.5);
+                    if (highConf.length > 0) {
+                        output += `\n\nHistorical coupling warning: ${highConf.length} file(s) frequently co-change with this file but have no import relationship:`;
+                        for (const cf of highConf) {
+                            const pct = Math.round(cf.confidence * 100);
+                            output += `\n  - ${cf.relativePath} (${pct}%, ${cf.coChangeCount} times)`;
+                        }
+                    }
+                }
                 return {
                     content: [
                         {
                             type: "text",
-                            text: appendDashboardFooter(`${result.riskLevel} — ${rel} impacts ${result.totalImpacted} file(s)`),
+                            text: appendDashboardFooter(output),
                         },
                     ],
                 };
@@ -368,6 +455,54 @@ async function main() {
                 const requestedN = args.top_n || 10;
                 const graph = (0, graph_1.getGraph)(currentProjectRoot, currentPackageName);
                 const hubs = (0, analyze_impact_1.getHubFiles)(graph, requestedN);
+                // If PageRank is available, build enriched entries sorted by PageRank
+                const pageRankAvailable = !!graph.pageRank;
+                if (pageRankAvailable) {
+                    // Enrich hub data with PageRank and re-sort by PageRank score
+                    const enriched = hubs.map(h => {
+                        const absPath = path.normalize(path.join(graph.sourceDir, h.relativePath));
+                        const prData = graph.pageRank ? (0, pagerank_1.getFileRank)(absPath, graph.pageRank) : null;
+                        return { ...h, prData };
+                    });
+                    // Sort by PageRank score descending (fallback to dependent count)
+                    enriched.sort((a, b) => {
+                        const scoreA = a.prData?.score ?? 0;
+                        const scoreB = b.prData?.score ?? 0;
+                        if (scoreB !== scoreA)
+                            return scoreB - scoreA;
+                        return b.dependentCount - a.dependentCount;
+                    });
+                    // Compute risk scores for hub files
+                    try {
+                        (0, risk_scorer_1.computeProjectMetrics)(graph);
+                    }
+                    catch { /* non-critical */ }
+                    const lines = [
+                        `## Hub Files (Top ${enriched.length}, ranked by PageRank)`,
+                        "",
+                    ];
+                    enriched.forEach((h, i) => {
+                        const prScore = h.prData?.score?.toFixed(6) ?? "N/A";
+                        const prRank = h.prData?.rank ?? "?";
+                        const prPercentile = h.prData?.percentile ?? "?";
+                        lines.push(`**#${i + 1}  ${h.relativePath}**`);
+                        lines.push(`    PageRank: ${prScore} (rank #${prRank}, ${prPercentile}th percentile)`);
+                        lines.push(`    Dependents: ${h.dependentCount} (direct)`);
+                        // Try to get risk score
+                        const absPath = path.normalize(path.join(graph.sourceDir, h.relativePath));
+                        try {
+                            const rs = (0, risk_scorer_1.getRiskScore)(absPath, graph);
+                            lines.push(`    Risk Score: ${rs.composite.toFixed(2)} (${rs.riskLevel})`);
+                        }
+                        catch {
+                            lines.push(`    Risk: ${h.riskLevel}`);
+                        }
+                        lines.push("");
+                    });
+                    lines.push(`Total files in graph: ${graph.files.size}`);
+                    return { content: [{ type: "text", text: lines.join("\n") }] };
+                }
+                // Fallback: original table format (no PageRank data)
                 const lines = [
                     `## Hub Files (Top ${hubs.length})`,
                     "",
@@ -383,11 +518,13 @@ async function main() {
             }
             case "refresh_graph": {
                 const graph = (0, graph_1.refreshGraph)(currentProjectRoot, currentPackageName);
+                (0, change_coupling_1.invalidateCouplingCache)();
+                const cacheStats = (0, analyze_impact_1.getImpactMemoCache)().stats();
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Graph refreshed (${graph.languages.join("+")}): ${graph.files.size} files scanned.`,
+                            text: `Graph refreshed (${graph.languages.join("+")}): ${graph.files.size} files scanned. Change coupling cache invalidated. Memo cache cleared (was ${cacheStats.size} entries, ${cacheStats.hits} hits / ${cacheStats.misses} misses).`,
                         },
                     ],
                 };
@@ -416,7 +553,7 @@ async function main() {
                 if (!isFileInFreeSet(resolved, graph)) {
                     return { content: [{ type: "text", text: PRO_UPGRADE_MSG }] };
                 }
-                const impactResult = (0, analyze_impact_1.analyzeImpact)(resolved, graph);
+                const impactResult = await (0, analyze_impact_1.analyzeImpact)(resolved, graph);
                 const aiResult = await (0, analyzer_1.analyzeWithAI)(resolved, impactResult, graph);
                 // Free tier: append partial analysis warning
                 let resultText = aiResult;
@@ -523,6 +660,7 @@ async function main() {
         // Initialize file cache (load ALL source files into memory)
         fileCache = new file_cache_1.FileCache(currentProjectRoot);
         fileCache.initialize();
+        fileCache.setGraph(graph); // Enable incremental graph updates on file changes
         fileCache.startWatching();
     }
     // Web server handle (set after server starts)
@@ -537,13 +675,15 @@ async function main() {
             fileCache.stop();
         fileCache = new file_cache_1.FileCache(newRoot);
         fileCache.initialize();
+        // Rebuild graph
+        const graph = (0, graph_1.refreshGraph)(newRoot, currentPackageName);
+        // Enable incremental updates on the new cache
+        fileCache.setGraph(graph);
         fileCache.startWatching();
         // Re-wire SSE events to the new FileCache
         if (webServerHandle) {
             webServerHandle.setFileCache(fileCache);
         }
-        // Rebuild graph
-        const graph = (0, graph_1.refreshGraph)(newRoot, currentPackageName);
         console.error(`[syke] Switched to project: ${newRoot}`);
         console.error(`[syke] Languages: ${plugins.map(p => p.name).join(", ")}`);
         console.error(`[syke] Package: ${currentPackageName}`);

package/dist/scoring/pagerank.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PageRank scoring for SYKE dependency graphs.
+ *
+ * Uses the Power Iteration algorithm to compute recursive importance scores.
+ * A file imported by many important files ranks higher than one imported by
+ * many leaf files. This provides a more nuanced importance signal than
+ * simple reverse dependent count (fan-in).
+ *
+ * In dependency graph terms:
+ *   - If A imports B, the forward edge is A -> B.
+ *   - B receives importance from A (B is important because A depends on it).
+ *   - So we iterate over graph.reverse to find incoming "importance links".
+ *
+ * Dangling nodes (files that import nothing) distribute their rank
+ * equally to all nodes, preventing rank from leaking out of the graph.
+ */
+import { DependencyGraph } from "../graph";
+export interface PageRankOptions {
+    dampingFactor?: number;
+    maxIterations?: number;
+    tolerance?: number;
+}
+export interface PageRankResult {
+    scores: Map<string, number>;
+    ranked: RankedFile[];
+    iterations: number;
+    computedAt: number;
+}
+export interface RankedFile {
+    filePath: string;
+    relativePath: string;
+    score: number;
+    rank: number;
+    percentile: number;
+}
+/**
+ * Invalidate the cached PageRank result.
+ * Call this when the dependency graph is rebuilt.
+ */
+export declare function invalidatePageRank(): void;
+/**
+ * Compute PageRank scores for all files in the dependency graph
+ * using the Power Iteration method.
+ *
+ * The algorithm:
+ *   1. Initialize rank[i] = 1/N for all N files.
+ *   2. Repeat until convergence or maxIterations:
+ *        For each file i:
+ *          newRank[i] = (1 - d) / N + d * SUM(rank[j] / outDegree[j])
+ *                       for all j that link to i (j imports i -> j is in reverse[i])
+ *        Handle dangling nodes: files with outDegree=0 distribute rank to all.
+ *        If max|newRank - rank| < tolerance: break
+ *        rank = newRank
+ *
+ * Direction clarification:
+ *   - forward[A] = [B] means "A imports B" (A -> B).
+ *   - reverse[B] = [A] means "A imports B" — A gives importance to B.
+ *   - outDegree of A = forward[A].length (how many files A imports).
+ *   - When computing rank for B, sum over reverse[B]: each file A that
+ *     imports B contributes rank[A] / outDegree[A] to B.
+ */
+export declare function computePageRank(graph: DependencyGraph, options?: PageRankOptions): PageRankResult;
+/**
+ * O(1) lookup of a file's PageRank data from a precomputed result.
+ * Returns null if the file is not in the result.
+ */
+export declare function getFileRank(filePath: string, result: PageRankResult): RankedFile | null;

package/dist/scoring/pagerank.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * PageRank scoring for SYKE dependency graphs.
+ *
+ * Uses the Power Iteration algorithm to compute recursive importance scores.
+ * A file imported by many important files ranks higher than one imported by
+ * many leaf files. This provides a more nuanced importance signal than
+ * simple reverse dependent count (fan-in).
+ *
+ * In dependency graph terms:
+ *   - If A imports B, the forward edge is A -> B.
+ *   - B receives importance from A (B is important because A depends on it).
+ *   - So we iterate over graph.reverse to find incoming "importance links".
+ *
+ * Dangling nodes (files that import nothing) distribute their rank
+ * equally to all nodes, preventing rank from leaking out of the graph.
+ */
+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.invalidatePageRank = invalidatePageRank;
+exports.computePageRank = computePageRank;
+exports.getFileRank = getFileRank;
+const path = __importStar(require("path"));
+// ── Module-level Cache ──
+let cachedResult = null;
+/**
+ * Invalidate the cached PageRank result.
+ * Call this when the dependency graph is rebuilt.
+ */
+function invalidatePageRank() {
+    cachedResult = null;
+}
+// ── Core Algorithm ──
+/**
+ * Compute PageRank scores for all files in the dependency graph
+ * using the Power Iteration method.
+ *
+ * The algorithm:
+ *   1. Initialize rank[i] = 1/N for all N files.
+ *   2. Repeat until convergence or maxIterations:
+ *        For each file i:
+ *          newRank[i] = (1 - d) / N + d * SUM(rank[j] / outDegree[j])
+ *                       for all j that link to i (j imports i -> j is in reverse[i])
+ *        Handle dangling nodes: files with outDegree=0 distribute rank to all.
+ *        If max|newRank - rank| < tolerance: break
+ *        rank = newRank
+ *
+ * Direction clarification:
+ *   - forward[A] = [B] means "A imports B" (A -> B).
+ *   - reverse[B] = [A] means "A imports B" — A gives importance to B.
+ *   - outDegree of A = forward[A].length (how many files A imports).
+ *   - When computing rank for B, sum over reverse[B]: each file A that
+ *     imports B contributes rank[A] / outDegree[A] to B.
+ */
+function computePageRank(graph, options) {
+    // Return cached result if available
+    if (cachedResult) {
+        return cachedResult;
+    }
+    const d = options?.dampingFactor ?? 0.85;
+    const maxIter = options?.maxIterations ?? 100;
+    const tol = options?.tolerance ?? 1e-6;
+    const files = [...graph.files];
+    const N = files.length;
+    // Handle empty graph
+    if (N === 0) {
+        const result = {
+            scores: new Map(),
+            ranked: [],
+            iterations: 0,
+            computedAt: Date.now(),
+        };
+        cachedResult = result;
+        return result;
+    }
+    // Build index maps for fast array-based iteration
+    const fileToIdx = new Map();
+    for (let i = 0; i < N; i++) {
+        fileToIdx.set(files[i], i);
+    }
+    // Compute out-degree for each file (number of files it imports)
+    const outDegree = new Float64Array(N);
+    for (let i = 0; i < N; i++) {
+        const deps = graph.forward.get(files[i]);
+        outDegree[i] = deps ? deps.length : 0;
+    }
+    // Identify dangling nodes (files with no outgoing edges / no imports)
+    const danglingNodes = [];
+    for (let i = 0; i < N; i++) {
+        if (outDegree[i] === 0) {
+            danglingNodes.push(i);
+        }
+    }
+    // Build reverse adjacency list as index arrays for performance
+    // reverseAdj[i] = list of indices j where file j imports file i
+    const reverseAdj = new Array(N);
+    for (let i = 0; i < N; i++) {
+        reverseAdj[i] = [];
+    }
+    for (const [target, sources] of graph.reverse) {
+        const targetIdx = fileToIdx.get(target);
+        if (targetIdx === undefined)
+            continue;
+        for (const source of sources) {
+            const sourceIdx = fileToIdx.get(source);
+            if (sourceIdx !== undefined) {
+                reverseAdj[targetIdx].push(sourceIdx);
+            }
+        }
+    }
+    // Initialize ranks
+    let rank = new Float64Array(N);
+    const initRank = 1.0 / N;
+    for (let i = 0; i < N; i++) {
+        rank[i] = initRank;
+    }
+    let iterations = 0;
+    const baseTeleport = (1.0 - d) / N;
+    for (let iter = 0; iter < maxIter; iter++) {
+        iterations = iter + 1;
+        // Compute dangling rank sum: total rank held by dangling nodes
+        let danglingSum = 0;
+        for (const idx of danglingNodes) {
+            danglingSum += rank[idx];
+        }
+        // Each node gets an equal share of the dangling rank (redistributed)
+        const danglingContribution = d * danglingSum / N;
+        const newRank = new Float64Array(N);
+        for (let i = 0; i < N; i++) {
+            // Sum contributions from all files that import file i
+            let incomingSum = 0;
+            for (const j of reverseAdj[i]) {
+                incomingSum += rank[j] / outDegree[j];
+            }
+            newRank[i] = baseTeleport + danglingContribution + d * incomingSum;
+        }
+        // Check convergence: max absolute difference
+        let maxDiff = 0;
+        for (let i = 0; i < N; i++) {
+            const diff = Math.abs(newRank[i] - rank[i]);
+            if (diff > maxDiff)
+                maxDiff = diff;
+        }
+        rank = newRank;
+        if (maxDiff < tol) {
+            break;
+        }
+    }
+    // Build scores map
+    const scores = new Map();
+    for (let i = 0; i < N; i++) {
+        scores.set(files[i], rank[i]);
+    }
+    // Build sorted ranked list
+    const indexedScores = [];
+    for (let i = 0; i < N; i++) {
+        indexedScores.push({ idx: i, score: rank[i] });
+    }
+    indexedScores.sort((a, b) => b.score - a.score);
+    const ranked = indexedScores.map((entry, position) => ({
+        filePath: files[entry.idx],
+        relativePath: path.relative(graph.sourceDir, files[entry.idx]).replace(/\\/g, "/"),
+        score: entry.score,
+        rank: position + 1,
+        percentile: Math.round(((N - 1 - position) / Math.max(1, N - 1)) * 100),
+    }));
+    const result = {
+        scores,
+        ranked,
+        iterations,
+        computedAt: Date.now(),
+    };
+    cachedResult = result;
+    console.error(`[syke:pagerank] Computed PageRank for ${N} files in ${iterations} iterations`);
+    return result;
+}
+// ── Lookup ──
+/**
+ * O(1) lookup of a file's PageRank data from a precomputed result.
+ * Returns null if the file is not in the result.
+ */
+function getFileRank(filePath, result) {
+    const score = result.scores.get(filePath);
+    if (score === undefined)
+        return null;
+    // Find the ranked entry (scores map guarantees it exists in ranked array)
+    const entry = result.ranked.find(r => r.filePath === filePath);
+    return entry || null;
+}

package/dist/scoring/risk-scorer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+import { DependencyGraph } from "../graph";
+export interface CouplingMetrics {
+    fanIn: number;
+    fanOut: number;
+    transitiveFanIn: number;
+}
+export type CompositeRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "SAFE";
+export interface RiskScore {
+    composite: number;
+    fanIn: number;
+    fanOut: number;
+    transitiveFanIn: number;
+    instability: number;
+    complexity: number;
+    normalizedComplexity: number;
+    cascadeDepth: number;
+    riskLevel: CompositeRiskLevel;
+    pageRank?: number;
+    pageRankPercentile?: number;
+}
+export interface ProjectMetrics {
+    maxFanIn: number;
+    maxTransitiveFanIn: number;
+    maxComplexity: number;
+    maxCascadeDepth: number;
+    fileMetrics: Map<string, RiskScore>;
+}
+export declare const RISK_WEIGHTS: {
+    fanIn: number;
+    stability: number;
+    complexity: number;
+    cascadeDepth: number;
+    pageRank: number;
+};
+/**
+ * Invalidate cached project metrics. Call when the graph is rebuilt.
+ */
+export declare function invalidateProjectMetrics(): void;
+/**
+ * Compute coupling metrics for a single file from the dependency graph.
+ */
+export declare function computeCouplingMetrics(filePath: string, graph: DependencyGraph): CouplingMetrics;
+/**
+ * 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)
+ */
+export declare function computeInstability(fanIn: number, fanOut: number): number;
+/**
+ * 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).
+ */
+export declare function computeComplexity(content: string, language: string): number;
+/**
+ * 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).
+ */
+export declare function computeCascadeDepth(filePath: string, graph: DependencyGraph): number;
+/**
+ * Map a composite score (0-1) to a risk level.
+ */
+export declare function classifyCompositeRisk(score: number): CompositeRiskLevel;
+/**
+ * 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).
+ */
+export declare function computeRiskScore(filePath: string, graph: DependencyGraph, fileContent: string | null, projectMetrics?: ProjectMetrics): RiskScore;
+/**
+ * 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.
+ */
+export declare function computeProjectMetrics(graph: DependencyGraph, getFileContent?: (path: string) => string | null): ProjectMetrics;
+/**
+ * Get the cached risk score for a file, or compute it on the fly.
+ * Uses project-wide normalization when available.
+ */
+export declare function getRiskScore(filePath: string, graph: DependencyGraph, fileContent?: string | null): RiskScore;
+/**
+ * Format a risk score for display in MCP tool output.
+ */
+export declare function formatRiskScore(score: RiskScore): string;