@syke1/mcp-server 1.4.16 → 1.4.18

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;