@syke1/mcp-server 1.4.17 → 1.4.19

package/README.md

@@ -113,6 +113,88 @@ SYKE supports three AI providers for semantic analysis. Bring your own key:
 **Auto-selection:** SYKE uses the first available key (Gemini > OpenAI > Anthropic).
 **Force provider:** Set `aiProvider` in config (or `SYKE_AI_PROVIDER` env var) to override.
 
+### Advanced Graph Algorithms
+
+SYKE goes beyond simple dependency counting. Five production-grade algorithms work together to deliver precise, fast, and context-rich impact analysis — all running **locally with zero AI token cost**.
+
+#### 1. SCC Condensation + Topological Sort
+
+Circular dependencies are the #1 source of misleading impact analysis. SYKE uses **Tarjan's algorithm** to detect all Strongly Connected Components, condenses them into a clean DAG, then runs topological sort to compute correct cascade levels.
+
+```
+Before: "47 files affected" (inflated by cycles)
+After:  "3 files in circular cluster (Level 0) → 5 files (Level 1) → 4 files (Level 2)"
+```
+
+- O(V+E) computation — runs in single-digit milliseconds
+- Every SCC with size > 1 is flagged as a circular dependency cluster
+- Cascade levels are accurate even in heavily cyclic codebases
+
+#### 2. Composite Risk Scoring
+
+Five signals combined into a single 0–1 risk score:
+
+| Signal | Weight | What it measures |
+|--------|--------|-----------------|
+| **Fan-in** | 30% | How many files depend on this one |
+| **Stability Index** | 20% | I = Ce/(Ca+Ce) — lower = foundation file = riskier to change |
+| **Cyclomatic Complexity** | 20% | Internal branching complexity (regex-based, 8 languages) |
+| **Cascade Depth** | 15% | How many layers deep the impact propagates |
+| **PageRank** | 15% | Recursive importance in the dependency graph |
+
+```
+auth_service.ts → Risk: 0.82 (CRITICAL)
+  Fan-in: 24, Stability: 0.12, Complexity: 47, Cascade: 4 levels, PageRank: 99th
+
+string_utils.ts → Risk: 0.31 (LOW)
+  Fan-in: 18, Stability: 0.85, Complexity: 3, Cascade: 1 level, PageRank: 42nd
+```
+
+AI agents can now make threshold decisions: proceed if < 0.3, warn if 0.3–0.7, block if > 0.7.
+
+#### 3. Historical Change Coupling
+
+Static imports miss **hidden dependencies** — files that always change together but have no import relationship. SYKE mines your git history (last 500 commits) to find these logical couplings.
+
+```
+auth_service.ts changed →
+  [Dependency Graph] auth_provider.ts, login_screen.ts
+  [Git Coupling — Hidden Dependencies]
+    config/auth_config.json (85% confidence, 12 co-changes)
+    styles/auth.css (72% confidence, 8 co-changes)
+```
+
+- Catches 15–30% of impacted files that static analysis misses entirely
+- Filters mega-commits (>20 files) to avoid noise
+- 5-minute cache with auto-refresh
+
+#### 4. PageRank for File Importance
+
+Simple fan-in counts treat all dependents equally. **PageRank** computes recursive importance — a file imported by many *important* files ranks higher than one imported by many leaf files.
+
+```
+Before: utils.ts ranked #1 (25 dependents — but all are leaf components)
+After:  auth.ts ranked #1 (20 dependents — 15 of which are core modules)
+```
+
+- Standard Power Iteration with damping factor 0.85
+- Precomputed at startup, incrementally updated on file changes
+- Every file gets a rank position and percentile (e.g., "rank #3 of 245, 99th percentile")
+
+#### 5. Incremental Graph Updates + Memoized Queries
+
+For large codebases (10K+ files), full graph rebuilds are too slow. SYKE now updates **only the changed file's edges** and invalidates **only the affected cache entries**.
+
+```
+Before: 1 file changed → re-parse all 500 files → 2+ seconds
+After:  1 file changed → re-parse 1 file → edge diff → 50ms
+        Same file queried again → cache hit → O(1) instant
+```
+
+- Reverse index enables O(affected) cache invalidation instead of O(cache_size)
+- SCC and PageRank recompute after edge changes (still < 100ms for 10K files)
+- 500-entry LRU cache with hit/miss diagnostics
+
 ### Language Support
 
 Auto-detected, zero-config: **Dart/Flutter**, **TypeScript/JavaScript**, **Python**, **Go**, **Rust**, **Java**, **C++**, **Ruby**.

package/dist/ai/realtime-analyzer.js

@@ -112,7 +112,7 @@ async function analyzeChangeRealtime(change, graph, getFileContent) {
     const absPath = path.normalize(path.join(graph.sourceDir, relPath));
     let affectedNodes = [];
     if (graph.files.has(absPath)) {
-        const impact = (0, analyze_impact_1.analyzeImpact)(absPath, graph);
+        const impact = await (0, analyze_impact_1.analyzeImpact)(absPath, graph);
         affectedNodes = [...impact.directDependents, ...impact.transitiveDependents];
     }
     // Build context: changed file + top 5 connected files' smart context

package/dist/git/change-coupling.d.ts

@@ -0,0 +1,41 @@
+export interface ChangeCoupling {
+    file1: string;
+    file2: string;
+    coChangeCount: number;
+    file1Changes: number;
+    file2Changes: number;
+    confidence: number;
+    support: number;
+}
+export interface CouplingResult {
+    couplings: ChangeCoupling[];
+    fileCouplings: Map<string, ChangeCoupling[]>;
+    totalCommitsAnalyzed: number;
+    analyzedAt: number;
+}
+export interface CouplingOptions {
+    maxCommits?: number;
+    minSupport?: number;
+    minConfidence?: number;
+    maxFilesPerCommit?: number;
+}
+/**
+ * Invalidate the coupling cache. Call this when the graph is refreshed
+ * or when git history may have changed.
+ */
+export declare function invalidateCouplingCache(): void;
+/**
+ * Mine git history to find files that frequently co-change.
+ *
+ * Runs `git log --name-only` and analyzes pairwise file combinations
+ * within each commit to identify hidden logical dependencies.
+ */
+export declare function mineGitHistory(projectRoot: string, options?: CouplingOptions): Promise<CouplingResult>;
+/**
+ * Get all significant couplings for a given file path.
+ * Returns an empty array if no couplings are found.
+ *
+ * The filePath should be a relative path matching git log output format
+ * (forward slashes, relative to project root).
+ */
+export declare function getCoupledFiles(filePath: string, result: CouplingResult): ChangeCoupling[];

package/dist/git/change-coupling.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalidateCouplingCache = invalidateCouplingCache;
+exports.mineGitHistory = mineGitHistory;
+exports.getCoupledFiles = getCoupledFiles;
+const child_process_1 = require("child_process");
+// ── Defaults ──
+const DEFAULT_MAX_COMMITS = 500;
+const DEFAULT_MIN_SUPPORT = 3;
+const DEFAULT_MIN_CONFIDENCE = 0.3;
+const DEFAULT_MAX_FILES_PER_COMMIT = 20;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+// ── Cache ──
+let cachedResult = null;
+let cachedProjectRoot = null;
+/**
+ * Invalidate the coupling cache. Call this when the graph is refreshed
+ * or when git history may have changed.
+ */
+function invalidateCouplingCache() {
+    cachedResult = null;
+    cachedProjectRoot = null;
+}
+// ── Git History Mining ──
+/**
+ * Check whether the given directory is inside a git repository.
+ */
+function isGitRepo(projectRoot) {
+    try {
+        (0, child_process_1.execSync)("git rev-parse --is-inside-work-tree", {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse git log output into a list of commits, each containing
+ * the list of files changed in that commit.
+ */
+function parseGitLog(raw) {
+    const commits = [];
+    const segments = raw.split("COMMIT:");
+    for (const segment of segments) {
+        const trimmed = segment.trim();
+        if (!trimmed)
+            continue;
+        // First line is the commit hash, remaining lines are file paths
+        const lines = trimmed.split("\n");
+        const files = [];
+        for (let i = 1; i < lines.length; i++) {
+            const fileLine = lines[i].trim();
+            if (fileLine) {
+                files.push(fileLine);
+            }
+        }
+        if (files.length > 0) {
+            commits.push(files);
+        }
+    }
+    return commits;
+}
+/**
+ * Normalize a git-output path (forward slashes) to be consistent
+ * with how the dependency graph stores paths.
+ */
+function normalizePath(filePath) {
+    // Git always outputs forward slashes; normalize for consistency
+    return filePath.replace(/\\/g, "/");
+}
+/**
+ * Check if a file path looks like a source file (not binary, not config noise).
+ * We keep this broad — the dependency graph comparison will handle the real filtering.
+ */
+function isSourceFile(filePath) {
+    // Skip obviously non-source files
+    const skipPatterns = [
+        /\.lock$/,
+        /package-lock\.json$/,
+        /yarn\.lock$/,
+        /\.min\.(js|css)$/,
+        /\.map$/,
+        /\.d\.ts$/,
+        /\.png$/,
+        /\.jpg$/,
+        /\.jpeg$/,
+        /\.gif$/,
+        /\.svg$/,
+        /\.ico$/,
+        /\.woff2?$/,
+        /\.ttf$/,
+        /\.eot$/,
+        /\.pdf$/,
+        /\.zip$/,
+        /\.tar$/,
+        /\.gz$/,
+    ];
+    const normalized = filePath.toLowerCase();
+    return !skipPatterns.some((p) => p.test(normalized));
+}
+/**
+ * Create a canonical pair key for two files (order-independent).
+ */
+function pairKey(a, b) {
+    return a < b ? `${a}\0${b}` : `${b}\0${a}`;
+}
+/**
+ * Mine git history to find files that frequently co-change.
+ *
+ * Runs `git log --name-only` and analyzes pairwise file combinations
+ * within each commit to identify hidden logical dependencies.
+ */
+async function mineGitHistory(projectRoot, options) {
+    // Return cached result if still valid
+    if (cachedResult &&
+        cachedProjectRoot === projectRoot &&
+        Date.now() - cachedResult.analyzedAt < CACHE_TTL_MS) {
+        return cachedResult;
+    }
+    const maxCommits = options?.maxCommits ?? DEFAULT_MAX_COMMITS;
+    const minSupport = options?.minSupport ?? DEFAULT_MIN_SUPPORT;
+    const minConfidence = options?.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    const maxFilesPerCommit = options?.maxFilesPerCommit ?? DEFAULT_MAX_FILES_PER_COMMIT;
+    // Empty result for non-git projects
+    const emptyResult = {
+        couplings: [],
+        fileCouplings: new Map(),
+        totalCommitsAnalyzed: 0,
+        analyzedAt: Date.now(),
+    };
+    if (!isGitRepo(projectRoot)) {
+        cachedResult = emptyResult;
+        cachedProjectRoot = projectRoot;
+        return emptyResult;
+    }
+    // Run git log
+    let raw;
+    try {
+        raw = (0, child_process_1.execSync)(`git log --name-only --format="COMMIT:%H" --max-count=${maxCommits}`, {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            maxBuffer: 10 * 1024 * 1024,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    catch {
+        cachedResult = emptyResult;
+        cachedProjectRoot = projectRoot;
+        return emptyResult;
+    }
+    const commits = parseGitLog(raw);
+    // Track per-file change counts and per-pair co-change counts
+    const fileChangeCount = new Map();
+    const pairCoChangeCount = new Map();
+    let totalCommitsAnalyzed = 0;
+    for (const commitFiles of commits) {
+        // Filter to source files and normalize paths
+        const filtered = commitFiles
+            .map(normalizePath)
+            .filter(isSourceFile);
+        // Skip mega-commits (merge commits, large refactors)
+        if (filtered.length > maxFilesPerCommit || filtered.length < 2) {
+            if (filtered.length === 1) {
+                // Still count single-file commits for per-file totals
+                const file = filtered[0];
+                fileChangeCount.set(file, (fileChangeCount.get(file) || 0) + 1);
+            }
+            totalCommitsAnalyzed++;
+            continue;
+        }
+        totalCommitsAnalyzed++;
+        // Count per-file changes
+        for (const file of filtered) {
+            fileChangeCount.set(file, (fileChangeCount.get(file) || 0) + 1);
+        }
+        // Count pairwise co-changes
+        for (let i = 0; i < filtered.length; i++) {
+            for (let j = i + 1; j < filtered.length; j++) {
+                const key = pairKey(filtered[i], filtered[j]);
+                pairCoChangeCount.set(key, (pairCoChangeCount.get(key) || 0) + 1);
+            }
+        }
+    }
+    // Build coupling results, filtering by thresholds
+    const couplings = [];
+    for (const [key, coCount] of pairCoChangeCount) {
+        if (coCount < minSupport)
+            continue;
+        const [file1, file2] = key.split("\0");
+        const file1Changes = fileChangeCount.get(file1) || 0;
+        const file2Changes = fileChangeCount.get(file2) || 0;
+        const maxChanges = Math.max(file1Changes, file2Changes);
+        const confidence = maxChanges > 0 ? coCount / maxChanges : 0;
+        if (confidence < minConfidence)
+            continue;
+        couplings.push({
+            file1,
+            file2,
+            coChangeCount: coCount,
+            file1Changes,
+            file2Changes,
+            confidence,
+            support: coCount,
+        });
+    }
+    // Sort by confidence descending
+    couplings.sort((a, b) => b.confidence - a.confidence);
+    // Build the per-file lookup map
+    const fileCouplings = new Map();
+    for (const coupling of couplings) {
+        // Add to file1's list
+        if (!fileCouplings.has(coupling.file1)) {
+            fileCouplings.set(coupling.file1, []);
+        }
+        fileCouplings.get(coupling.file1).push(coupling);
+        // Add to file2's list
+        if (!fileCouplings.has(coupling.file2)) {
+            fileCouplings.set(coupling.file2, []);
+        }
+        fileCouplings.get(coupling.file2).push(coupling);
+    }
+    // Sort each file's couplings by confidence descending
+    for (const [, list] of fileCouplings) {
+        list.sort((a, b) => b.confidence - a.confidence);
+    }
+    const result = {
+        couplings,
+        fileCouplings,
+        totalCommitsAnalyzed,
+        analyzedAt: Date.now(),
+    };
+    cachedResult = result;
+    cachedProjectRoot = projectRoot;
+    return result;
+}
+/**
+ * Get all significant couplings for a given file path.
+ * Returns an empty array if no couplings are found.
+ *
+ * The filePath should be a relative path matching git log output format
+ * (forward slashes, relative to project root).
+ */
+function getCoupledFiles(filePath, result) {
+    const normalized = normalizePath(filePath);
+    return result.fileCouplings.get(normalized) || [];
+}

package/dist/graph/incremental.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Incremental Graph Updates for SYKE.
+ *
+ * Instead of rebuilding the entire dependency graph when a single file changes,
+ * this module re-parses only the changed file's imports and updates the
+ * forward/reverse maps in place. SCC and PageRank are recomputed fully
+ * (both are O(V+E) and fast enough) only when edges actually change.
+ *
+ * This brings update latency from O(N * parse) down to O(1 * parse + V+E)
+ * for large codebases (10K+ files).
+ */
+import { DependencyGraph } from "../graph";
+export interface IncrementalUpdateResult {
+    updatedFile: string;
+    addedEdges: [string, string][];
+    removedEdges: [string, string][];
+    edgesChanged: boolean;
+    affectedFiles: string[];
+}
+/**
+ * Update the graph for a single changed file.
+ * Re-parses only that file's imports and updates forward/reverse maps.
+ * Returns info about what changed for cache invalidation.
+ */
+export declare function updateGraphForFile(graph: DependencyGraph, filePath: string, projectRoot: string): IncrementalUpdateResult;
+/**
+ * Add a new file to the graph.
+ * Initializes forward/reverse entries, parses imports, and adds edges.
+ */
+export declare function addFileToGraph(graph: DependencyGraph, filePath: string, projectRoot: string): IncrementalUpdateResult;
+/**
+ * Remove a file from the graph.
+ * Cleans up all forward edges, reverse edges, and the files set.
+ */
+export declare function removeFileFromGraph(graph: DependencyGraph, filePath: string): IncrementalUpdateResult;