@syke1/mcp-server 1.4.16 → 1.4.18

package/dist/graph/scc.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Strongly Connected Components (SCC) via Tarjan's algorithm,
+ * graph condensation into a DAG, and topological sort via Kahn's algorithm.
+ *
+ * Used to detect circular dependencies and provide accurate cascade-level
+ * impact analysis on the condensed (acyclic) dependency graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSCC = computeSCC;
+exports.condenseGraph = condenseGraph;
+exports.topologicalSort = topologicalSort;
+// ── Tarjan's SCC Algorithm ──
+/**
+ * Compute all Strongly Connected Components of the dependency graph
+ * using Tarjan's algorithm. Returns SCCs, a file-to-SCC mapping,
+ * and the condensed DAG with topological ordering.
+ */
+function computeSCC(graph) {
+    // Handle empty graph
+    if (graph.files.size === 0) {
+        const emptyDAG = {
+            nodes: [],
+            forward: new Map(),
+            reverse: new Map(),
+            topologicalOrder: [],
+        };
+        return {
+            components: [],
+            nodeToComponent: new Map(),
+            condensed: emptyDAG,
+        };
+    }
+    const components = [];
+    // Tarjan state
+    let indexCounter = 0;
+    const nodeIndex = new Map();
+    const nodeLowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    function strongConnect(node) {
+        nodeIndex.set(node, indexCounter);
+        nodeLowlink.set(node, indexCounter);
+        indexCounter++;
+        stack.push(node);
+        onStack.add(node);
+        const successors = graph.forward.get(node) || [];
+        for (const successor of successors) {
+            // Only process nodes that exist in the graph
+            if (!graph.files.has(successor))
+                continue;
+            if (!nodeIndex.has(successor)) {
+                // Successor not yet visited — recurse
+                strongConnect(successor);
+                nodeLowlink.set(node, Math.min(nodeLowlink.get(node), nodeLowlink.get(successor)));
+            }
+            else if (onStack.has(successor)) {
+                // Successor is on the stack — part of current SCC
+                nodeLowlink.set(node, Math.min(nodeLowlink.get(node), nodeIndex.get(successor)));
+            }
+        }
+        // If node is a root of an SCC, pop the stack to form a component
+        if (nodeLowlink.get(node) === nodeIndex.get(node)) {
+            const component = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+            } while (w !== node);
+            components.push(component);
+        }
+    }
+    // Visit all nodes (handles disconnected components)
+    for (const file of graph.files) {
+        if (!nodeIndex.has(file)) {
+            strongConnect(file);
+        }
+    }
+    // Build file-to-component mapping
+    const nodeToComponent = new Map();
+    for (let i = 0; i < components.length; i++) {
+        for (const file of components[i]) {
+            nodeToComponent.set(file, i);
+        }
+    }
+    // Build the condensed DAG
+    const condensed = condenseGraph(graph, components, nodeToComponent);
+    return { components, nodeToComponent, condensed };
+}
+// ── Graph Condensation ──
+/**
+ * Build a DAG where each node represents one SCC.
+ * Edges between SCCs are derived from the original graph's edges
+ * between files belonging to different SCCs.
+ */
+function condenseGraph(graph, components, nodeToComponent) {
+    const numComponents = components.length;
+    // Build condensed nodes
+    const nodes = components.map((files, index) => ({
+        index,
+        files,
+        size: files.length,
+        isCyclic: files.length > 1,
+    }));
+    // Build forward and reverse edges between SCCs (deduplicated)
+    const forwardSets = new Map();
+    const reverseSets = new Map();
+    for (let i = 0; i < numComponents; i++) {
+        forwardSets.set(i, new Set());
+        reverseSets.set(i, new Set());
+    }
+    for (const [file, deps] of graph.forward) {
+        const srcSCC = nodeToComponent.get(file);
+        if (srcSCC === undefined)
+            continue;
+        for (const dep of deps) {
+            const dstSCC = nodeToComponent.get(dep);
+            if (dstSCC === undefined)
+                continue;
+            // Skip self-edges (within the same SCC)
+            if (srcSCC === dstSCC)
+                continue;
+            forwardSets.get(srcSCC).add(dstSCC);
+            reverseSets.get(dstSCC).add(srcSCC);
+        }
+    }
+    // Convert sets to arrays
+    const forward = new Map();
+    const reverse = new Map();
+    for (const [key, set] of forwardSets) {
+        forward.set(key, [...set]);
+    }
+    for (const [key, set] of reverseSets) {
+        reverse.set(key, [...set]);
+    }
+    const dag = {
+        nodes,
+        forward,
+        reverse,
+        topologicalOrder: [],
+    };
+    // Compute topological order
+    dag.topologicalOrder = topologicalSort(dag);
+    return dag;
+}
+// ── Topological Sort (Kahn's Algorithm) ──
+/**
+ * Compute a topological ordering of the condensed DAG using Kahn's algorithm.
+ * The condensed graph is guaranteed to be acyclic after SCC condensation.
+ *
+ * Returns SCC indices in dependency order: dependencies come before dependents.
+ * This uses the `forward` edges (file A imports B means A -> B in forward),
+ * so we process nodes with no incoming forward edges first (leaf dependencies).
+ */
+function topologicalSort(dag) {
+    const numNodes = dag.nodes.length;
+    if (numNodes === 0)
+        return [];
+    // In-degree = number of dependencies (forward edges out of each node).
+    // forward[A] = [B] means A imports B, so A depends on B.
+    // For "dependencies first" ordering, nodes with zero dependencies come first.
+    const inDegree = new Map();
+    for (let i = 0; i < numNodes; i++) {
+        inDegree.set(i, 0);
+    }
+    for (const [src, dsts] of dag.forward) {
+        inDegree.set(src, (inDegree.get(src) || 0) + dsts.length);
+    }
+    // Start with nodes that have no dependencies (in-degree 0 in forward)
+    const queue = [];
+    for (const [node, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(node);
+        }
+    }
+    const order = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        order.push(current);
+        // current has no remaining dependencies.
+        // For all nodes that depend on current (reverse edges: who imports current),
+        // decrement their in-degree.
+        const dependents = dag.reverse.get(current) || [];
+        for (const dependent of dependents) {
+            const newDegree = (inDegree.get(dependent) || 0) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    // If order doesn't contain all nodes, there's a bug (shouldn't happen after SCC condensation)
+    if (order.length !== numNodes) {
+        console.error(`[syke:scc] WARNING: Topological sort produced ${order.length}/${numNodes} nodes. ` +
+            `This indicates a bug in SCC condensation.`);
+        // Add remaining nodes at the end
+        const ordered = new Set(order);
+        for (let i = 0; i < numNodes; i++) {
+            if (!ordered.has(i)) {
+                order.push(i);
+            }
+        }
+    }
+    return order;
+}

package/dist/graph.d.ts

@@ -1,3 +1,5 @@
+import { SCCResult } from "./graph/scc";
+import { PageRankResult } from "./scoring/pagerank";
 export interface DependencyGraph {
     forward: Map<string, string[]>;
     reverse: Map<string, string[]>;
@@ -7,6 +9,10 @@ export interface DependencyGraph {
     sourceDirs: string[];
     /** backward compat: first source directory */
     sourceDir: string;
+    /** Strongly Connected Components — computed after graph build */
+    scc?: SCCResult;
+    /** PageRank importance scores — computed after graph build */
+    pageRank?: PageRankResult;
 }
 export declare function buildGraph(projectRoot: string, packageName?: string): DependencyGraph;
 export declare function getGraph(projectRoot: string, packageName?: string): DependencyGraph;

package/dist/graph.js

@@ -39,6 +39,10 @@ exports.refreshGraph = refreshGraph;
 const path = __importStar(require("path"));
 const plugin_1 = require("./languages/plugin");
 const typescript_1 = require("./languages/typescript");
+const scc_1 = require("./graph/scc");
+const risk_scorer_1 = require("./scoring/risk-scorer");
+const pagerank_1 = require("./scoring/pagerank");
+const memo_cache_1 = require("./graph/memo-cache");
 let cachedGraph = null;
 function buildGraph(projectRoot, packageName) {
     const detectedPlugins = (0, plugin_1.detectLanguages)(projectRoot);
@@ -85,8 +89,17 @@ function buildGraph(projectRoot, packageName) {
         sourceDirs: allSourceDirs,
         sourceDir,
     };
+    // Invalidate memo cache (full rebuild means all cached BFS results are stale)
+    (0, memo_cache_1.resetMemoCache)();
+    // Compute SCC and attach to graph
+    const scc = (0, scc_1.computeSCC)(graph);
+    graph.scc = scc;
+    // Compute PageRank importance scores
+    (0, pagerank_1.invalidatePageRank)();
+    graph.pageRank = (0, pagerank_1.computePageRank)(graph);
+    const cyclicCount = scc.condensed.nodes.filter(n => n.isCyclic).length;
     cachedGraph = graph;
-    console.error(`[syke] Graph built (${languages.join("+")}): ${files.size} files, ${countEdges(forward)} edges`);
+    console.error(`[syke] Graph built (${languages.join("+")}): ${files.size} files, ${countEdges(forward)} edges, ${scc.components.length} SCCs (${cyclicCount} cyclic)`);
     return graph;
 }
 function countEdges(forward) {
@@ -105,5 +118,8 @@ function getGraph(projectRoot, packageName) {
 function refreshGraph(projectRoot, packageName) {
     cachedGraph = null;
     (0, typescript_1.clearAliasCache)();
+    (0, risk_scorer_1.invalidateProjectMetrics)();
+    (0, pagerank_1.invalidatePageRank)();
+    (0, memo_cache_1.resetMemoCache)();
     return buildGraph(projectRoot, packageName);
 }

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;