sdl-mcp 0.6.0

package/dist/graph/cache.js

@@ -0,0 +1,237 @@
+/**
+ * LRU Cache with version-based invalidation for SDL-MCP
+ *
+ * Provides in-memory caching for SymbolCard and GraphSlice objects with:
+ * - LRU (Least Recently Used) eviction policy
+ * - Version-based cache key invalidation
+ * - Cache statistics tracking (hits, misses, evictions)
+ * - Configurable size limits per cache type
+ */
+const DEFAULT_CACHE_CONFIG = {
+    maxEntries: 1000,
+    maxSizeBytes: 50 * 1024 * 1024,
+};
+const DEFAULT_SYMBOL_CACHE_CONFIG = {
+    maxEntries: 2000,
+    maxSizeBytes: 100 * 1024 * 1024,
+};
+/**
+ * LRU Cache implementation with version-based invalidation
+ */
+class LRUCache {
+    cache = new Map();
+    accessOrder = [];
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        currentSize: 0,
+        entryCount: 0,
+    };
+    config;
+    lock = Promise.resolve();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
+    }
+    /**
+     * Generates a cache key including version for invalidation
+     */
+    makeKey(repoId, id, versionId) {
+        return `${repoId}:${id}:${versionId}`;
+    }
+    /**
+     * Estimates size of a cache entry in bytes
+     * Accounts for object overhead and string encoding
+     */
+    estimateSize(value) {
+        try {
+            const jsonString = JSON.stringify(value);
+            const stringBytes = Buffer.byteLength(jsonString, "utf8");
+            const objectOverhead = 64;
+            return stringBytes + objectOverhead;
+        }
+        catch {
+            return 1024;
+        }
+    }
+    /**
+     * Updates access order for LRU tracking
+     */
+    updateAccessOrder(key) {
+        const index = this.accessOrder.indexOf(key);
+        if (index !== -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        this.accessOrder.push(key);
+    }
+    /**
+     * Evicts entries to fit within cache limits
+     */
+    evictIfNeeded() {
+        while (this.accessOrder.length > this.config.maxEntries ||
+            (this.stats.currentSize > this.config.maxSizeBytes &&
+                this.accessOrder.length > 1)) {
+            if (this.accessOrder.length === 0)
+                break;
+            const oldestKey = this.accessOrder.shift();
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                this.stats.currentSize -= entry.size;
+                this.stats.entryCount--;
+                this.stats.evictions++;
+                this.cache.delete(oldestKey);
+            }
+        }
+    }
+    /**
+     * Invalidates all cache entries for a specific version
+     */
+    invalidateVersion(versionId) {
+        const keysToDelete = [];
+        for (const key of this.cache.keys()) {
+            if (key.endsWith(`:${versionId}`)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            const entry = this.cache.get(key);
+            if (entry) {
+                this.stats.currentSize -= entry.size;
+                this.stats.entryCount--;
+            }
+            this.cache.delete(key);
+            const index = this.accessOrder.indexOf(key);
+            if (index !== -1) {
+                this.accessOrder.splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Clears all cache entries
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+        this.stats.currentSize = 0;
+        this.stats.entryCount = 0;
+    }
+    /**
+     * Gets a cached value
+     */
+    get(repoId, id, versionId) {
+        const key = this.makeKey(repoId, id, versionId);
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.updateAccessOrder(key);
+            entry.lastAccessed = Date.now();
+            this.stats.hits++;
+            return entry.value;
+        }
+        this.stats.misses++;
+        return undefined;
+    }
+    /**
+     * Sets a cached value
+     */
+    async set(repoId, id, versionId, value) {
+        let releaseLock;
+        const nextLock = new Promise((resolve) => {
+            releaseLock = resolve;
+        });
+        const previousLock = this.lock;
+        this.lock = previousLock.then(() => nextLock);
+        await previousLock;
+        try {
+            const key = this.makeKey(repoId, id, versionId);
+            const size = this.estimateSize(value);
+            const now = Date.now();
+            const existingEntry = this.cache.get(key);
+            if (existingEntry) {
+                this.stats.currentSize -= existingEntry.size;
+                this.stats.entryCount--;
+            }
+            const newTotalSize = this.stats.currentSize + size;
+            if (newTotalSize > this.config.maxSizeBytes &&
+                this.accessOrder.length > 0) {
+                const oldestKey = this.accessOrder.shift();
+                const entry = this.cache.get(oldestKey);
+                if (entry) {
+                    this.stats.currentSize -= entry.size;
+                    this.stats.entryCount--;
+                    this.stats.evictions++;
+                    this.cache.delete(oldestKey);
+                }
+            }
+            this.cache.set(key, {
+                value,
+                versionId,
+                lastAccessed: now,
+                size,
+            });
+            this.stats.currentSize += size;
+            this.stats.entryCount++;
+            this.updateAccessOrder(key);
+            this.evictIfNeeded();
+        }
+        finally {
+            releaseLock?.();
+        }
+    }
+    /**
+     * Checks if a key exists in the cache
+     */
+    has(repoId, id, versionId) {
+        const key = this.makeKey(repoId, id, versionId);
+        return this.cache.has(key);
+    }
+    /**
+     * Gets cache statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Resets cache statistics
+     */
+    resetStats() {
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.evictions = 0;
+    }
+}
+/**
+ * Global cache instances
+ */
+export const symbolCardCache = new LRUCache(DEFAULT_SYMBOL_CACHE_CONFIG);
+/**
+ * Cache key generators
+ */
+export function makeSymbolCardCacheKey(repoId, symbolId, versionId) {
+    return `${repoId}:${symbolId}:${versionId}`;
+}
+/**
+ * Cache statistics retrieval
+ */
+export function getSymbolCardCacheStats() {
+    return symbolCardCache.getStats();
+}
+/**
+ * Cache invalidation helpers
+ */
+export function invalidateSymbolCardVersion(versionId) {
+    symbolCardCache.invalidateVersion(versionId);
+}
+/**
+ * Clears all caches
+ */
+export function clearAllCaches() {
+    symbolCardCache.clear();
+}
+/**
+ * Resets all cache statistics
+ */
+export function resetAllCacheStats() {
+    symbolCardCache.resetStats();
+}
+export { LRUCache };
+//# sourceMappingURL=cache.js.map

package/dist/graph/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/graph/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyBH,MAAM,oBAAoB,GAAgB;IACxC,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;CAC/B,CAAC;AAEF,MAAM,2BAA2B,GAAgB;IAC/C,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,QAAQ;IACJ,KAAK,GAA+B,IAAI,GAAG,EAAE,CAAC;IAC9C,WAAW,GAAa,EAAE,CAAC;IAC3B,KAAK,GAAe;QAC1B,IAAI,EAAE,CAAC;QACP,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,CAAC;KACd,CAAC;IACM,MAAM,CAAc;IACpB,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhD,YAAY,SAA+B,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAAC;IACvD,CAAC;IAED;;OAEG;IACK,OAAO,CAAC,MAAc,EAAE,EAAU,EAAE,SAAoB;QAC9D,OAAO,GAAG,MAAM,IAAI,EAAE,IAAI,SAAS,EAAE,CAAC;IACxC,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,KAAc;QACjC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACzC,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC1D,MAAM,cAAc,GAAG,EAAE,CAAC;YAC1B,OAAO,WAAW,GAAG,cAAc,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,GAAW;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACK,aAAa;QACnB,OACE,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU;YAChD,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY;gBAChD,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,EAC9B,CAAC;YACD,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM;YAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAG,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACxC,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC;gBACrC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,SAAoB;QACpC,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC,EAAE,CAAC;gBAClC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC;gBACrC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;gBACjB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,MAAc,EAAE,EAAU,EAAE,SAAoB;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;YAC5B,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAChC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CACP,MAAc,EACd,EAAU,EACV,SAAoB,EACpB,KAAQ;QAER,IAAI,WAAqC,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC7C,WAAW,GAAG,OAAO,CAAC;QACxB,CAAC,CAAC,CAAC;QACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;QAE9C,MAAM,YAAY,CAAC;QAEnB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAEvB,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,aAAa,EAAE,CAAC;gBAClB,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,aAAa,CAAC,IAAI,CAAC;gBAC7C,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1B,CAAC;YAED,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;YAEnD,IACE,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY;gBACvC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAC3B,CAAC;gBACD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAG,CAAC;gBAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACxC,IAAI,KAAK,EAAE,CAAC;oBACV,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC;oBACrC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;oBACxB,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;oBACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;gBAClB,KAAK;gBACL,SAAS;gBACT,YAAY,EAAE,GAAG;gBACjB,IAAI;aACL,CAAC,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YACxB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;YAE5B,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,WAAW,EAAE,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,MAAc,EAAE,EAAU,EAAE,SAAoB;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,QAAQ,CACzC,2BAA2B,CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,QAAkB,EAClB,SAAoB;IAEpB,OAAO,GAAG,MAAM,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;AAC9C,CAAC;AAGD;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,eAAe,CAAC,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAoB;IAC9D,eAAe,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,eAAe,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,eAAe,CAAC,UAAU,EAAE,CAAC;AAC/B,CAAC;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/graph/metrics.d.ts

@@ -0,0 +1,12 @@
+import type { RepoConfig } from "../config/types.js";
+import type { StalenessTiers } from "../mcp/types.js";
+declare function collectTestRefs(repoRoot: string, symbols: Array<{
+    symbol_id: string;
+    name: string;
+}>, config: RepoConfig, _changedTestFiles?: Set<string>): Map<string, Set<string>>;
+export declare function clearTestRefCache(repoRoot?: string): void;
+export { collectTestRefs };
+export declare function calculateRiskScore(tiers: StalenessTiers, fanIn: number, fanOut: number, hasDiagnostics: boolean): number;
+export declare function calculateRiskScoresForSymbols(symbolTiers: Map<string, StalenessTiers>, diagnostics: Map<string, boolean>): Map<string, number>;
+export declare function updateMetricsForRepo(repoId: string, changedFileIds?: Set<number>): Promise<void>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/graph/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/graph/metrics.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAkItD,iBAAS,eAAe,CACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,MAAM,EAAE,UAAU,EAClB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC9B,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAqF1B;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAMzD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,OAAO,GACtB,MAAM,CAcR;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACxC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBrB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAgEf"}

package/dist/graph/metrics.js

@@ -0,0 +1,253 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+import fg from "fast-glob";
+import { getEdgesByRepo, getFilesByRepo, getMetrics, getRepo, getSymbolsByRepo, upsertMetrics, } from "../db/queries.js";
+import { normalizePath } from "../util/paths.js";
+import { logger } from "../util/logger.js";
+const execAsync = promisify(exec);
+// Avoid flakiness when multiple updates happen within the same millisecond.
+// Some environments (and our unit tests) assume `updatedAt` changes on each update.
+let lastMetricsUpdateMs = 0;
+function monotonicIsoNow() {
+    const nowMs = Date.now();
+    const ms = nowMs <= lastMetricsUpdateMs ? lastMetricsUpdateMs + 1 : nowMs;
+    lastMetricsUpdateMs = ms;
+    return new Date(ms).toISOString();
+}
+const CHURN_CACHE_TTL_MS = 5 * 60 * 1000;
+const churnCacheByRepo = new Map();
+const testRefCacheByRepo = new Map();
+function calculateFanMetrics(edges, symbols) {
+    const metrics = new Map();
+    for (const edge of edges) {
+        if (!symbols.has(edge.from_symbol_id) || !symbols.has(edge.to_symbol_id)) {
+            continue;
+        }
+        const from = metrics.get(edge.from_symbol_id) ?? { fanIn: 0, fanOut: 0 };
+        from.fanOut += 1;
+        metrics.set(edge.from_symbol_id, from);
+        const to = metrics.get(edge.to_symbol_id) ?? { fanIn: 0, fanOut: 0 };
+        to.fanIn += 1;
+        metrics.set(edge.to_symbol_id, to);
+    }
+    return metrics;
+}
+async function getCurrentCommitHash(repoRoot) {
+    try {
+        const { stdout } = await execAsync("git rev-parse HEAD", {
+            cwd: repoRoot,
+        });
+        return stdout.trim();
+    }
+    catch {
+        return "";
+    }
+}
+async function getChurnByFile(repoRoot) {
+    try {
+        const { stdout } = await execAsync("git log --since=30.days --name-only --pretty=format:", {
+            cwd: repoRoot,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        const churn = new Map();
+        const lines = stdout.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            const relPath = normalizePath(trimmed);
+            churn.set(relPath, (churn.get(relPath) ?? 0) + 1);
+        }
+        return churn;
+    }
+    catch {
+        return new Map();
+    }
+}
+async function getChurnByFileCached(repoRoot) {
+    const cached = churnCacheByRepo.get(repoRoot);
+    const currentHead = await getCurrentCommitHash(repoRoot);
+    if (cached &&
+        cached.lastCommitHash === currentHead &&
+        Date.now() - cached.cachedAt < CHURN_CACHE_TTL_MS) {
+        logger.debug(`Churn cache HIT for repo ${repoRoot} (commit: ${currentHead})`);
+        return cached.churnMap;
+    }
+    logger.debug(`Churn cache MISS for repo ${repoRoot} (commit: ${currentHead})`);
+    const churnMap = await getChurnByFile(repoRoot);
+    churnCacheByRepo.set(repoRoot, {
+        repoRoot,
+        lastCommitHash: currentHead,
+        churnMap,
+        cachedAt: Date.now(),
+    });
+    return churnMap;
+}
+function computeFileHash(content) {
+    return createHash("md5").update(content).digest("hex");
+}
+function collectTestRefs(repoRoot, symbols, config, _changedTestFiles) {
+    const extGroup = config.languages.join(",");
+    const patterns = [
+        `**/*.test.{${extGroup}}`,
+        `**/*.spec.{${extGroup}}`,
+        `**/__tests__/**/*.${extGroup}`,
+        `**/tests/**/*.${extGroup}`,
+    ];
+    const testFiles = fg.sync(patterns, {
+        cwd: repoRoot,
+        ignore: config.ignore,
+        dot: false,
+    });
+    const nameToSymbolIds = new Map();
+    for (const symbol of symbols) {
+        const existing = nameToSymbolIds.get(symbol.name) ?? [];
+        existing.push(symbol.symbol_id);
+        nameToSymbolIds.set(symbol.name, existing);
+    }
+    const symbolNames = new Set(symbols.map((s) => s.name));
+    const cached = testRefCacheByRepo.get(repoRoot);
+    const fileHashes = cached?.fileHashes || new Map();
+    const newTestRefs = new Map();
+    const testRefs = new Map();
+    for (const file of testFiles) {
+        let content = "";
+        try {
+            content = readFileSync(join(repoRoot, file), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const hash = computeFileHash(content);
+        if (cached && cached.fileHashes.get(file) === hash) {
+            const cachedFileRefs = cached.testRefs.get(file);
+            if (cachedFileRefs) {
+                for (const ref of cachedFileRefs) {
+                    const symbolIds = nameToSymbolIds.get(ref);
+                    if (symbolIds) {
+                        for (const symbolId of symbolIds) {
+                            const existing = testRefs.get(symbolId) ?? new Set();
+                            existing.add(normalizePath(file));
+                            testRefs.set(symbolId, existing);
+                        }
+                    }
+                }
+                continue;
+            }
+        }
+        fileHashes.set(file, hash);
+        const tokens = content.match(/[A-Za-z_][A-Za-z0-9_]*/g) || [];
+        const matchedSymbols = new Set();
+        for (const token of new Set(tokens)) {
+            if (symbolNames.has(token)) {
+                matchedSymbols.add(token);
+                const symbolIds = nameToSymbolIds.get(token);
+                if (symbolIds) {
+                    for (const symbolId of symbolIds) {
+                        const existing = testRefs.get(symbolId) ?? new Set();
+                        existing.add(normalizePath(file));
+                        testRefs.set(symbolId, existing);
+                    }
+                }
+            }
+        }
+        newTestRefs.set(file, matchedSymbols);
+    }
+    testRefCacheByRepo.set(repoRoot, {
+        repoRoot,
+        fileHashes,
+        testRefs: newTestRefs,
+        cachedAt: Date.now(),
+    });
+    return testRefs;
+}
+export function clearTestRefCache(repoRoot) {
+    if (repoRoot) {
+        testRefCacheByRepo.delete(repoRoot);
+    }
+    else {
+        testRefCacheByRepo.clear();
+    }
+}
+export { collectTestRefs };
+export function calculateRiskScore(tiers, fanIn, fanOut, hasDiagnostics) {
+    let riskScore = tiers.riskScore;
+    const fanInPenalty = Math.min(fanIn * 2, 20);
+    const fanOutPenalty = Math.min(fanOut, 10);
+    riskScore += fanInPenalty;
+    riskScore += fanOutPenalty;
+    if (hasDiagnostics) {
+        riskScore += 15;
+    }
+    return Math.min(riskScore, 100);
+}
+export function calculateRiskScoresForSymbols(symbolTiers, diagnostics) {
+    const riskScores = new Map();
+    for (const [symbolId, tiers] of symbolTiers) {
+        const metrics = getMetrics(symbolId);
+        if (!metrics)
+            continue;
+        const hasDiagnostics = diagnostics.get(symbolId) ?? false;
+        const riskScore = calculateRiskScore(tiers, metrics.fan_in, metrics.fan_out, hasDiagnostics);
+        riskScores.set(symbolId, riskScore);
+    }
+    return riskScores;
+}
+export async function updateMetricsForRepo(repoId, changedFileIds) {
+    const edges = getEdgesByRepo(repoId);
+    const repo = getRepo(repoId);
+    if (!repo) {
+        return;
+    }
+    const config = JSON.parse(repo.config_json);
+    const files = getFilesByRepo(repoId);
+    const fileById = new Map(files.map((file) => [file.file_id, file.rel_path]));
+    const allSymbols = getSymbolsByRepo(repoId);
+    const symbolIds = new Set(allSymbols.map((symbol) => symbol.symbol_id));
+    let symbols = allSymbols;
+    // If an empty set is explicitly passed, it means no files changed - nothing to update
+    if (changedFileIds && changedFileIds.size === 0) {
+        logger.debug("Empty changedFileIds provided - no updates needed");
+        return;
+    }
+    if (changedFileIds && changedFileIds.size > 0) {
+        const affectedSymbolIds = new Set();
+        for (const symbol of allSymbols) {
+            if (changedFileIds.has(symbol.file_id)) {
+                affectedSymbolIds.add(symbol.symbol_id);
+            }
+        }
+        for (const edge of edges) {
+            if (affectedSymbolIds.has(edge.from_symbol_id)) {
+                affectedSymbolIds.add(edge.to_symbol_id);
+            }
+            if (affectedSymbolIds.has(edge.to_symbol_id)) {
+                affectedSymbolIds.add(edge.from_symbol_id);
+            }
+        }
+        symbols = allSymbols.filter((s) => affectedSymbolIds.has(s.symbol_id));
+        logger.debug(`Incremental metrics: updating ${symbols.length} of ${allSymbols.length} symbols for ${changedFileIds.size} changed files`);
+    }
+    const fanMetrics = calculateFanMetrics(edges, symbolIds);
+    const churnByFile = await getChurnByFileCached(repo.root_path);
+    const testRefs = collectTestRefs(repo.root_path, allSymbols, config);
+    const now = monotonicIsoNow();
+    for (const symbol of symbols) {
+        const metric = fanMetrics.get(symbol.symbol_id) ?? { fanIn: 0, fanOut: 0 };
+        const relPath = fileById.get(symbol.file_id);
+        const churn = relPath ? (churnByFile.get(relPath) ?? 0) : 0;
+        const refs = Array.from(testRefs.get(symbol.symbol_id) ?? []);
+        upsertMetrics({
+            symbolId: symbol.symbol_id,
+            fanIn: metric.fanIn,
+            fanOut: metric.fanOut,
+            churn30d: churn,
+            testRefsJson: JSON.stringify(refs),
+            updatedAt: now,
+        });
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/graph/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/graph/metrics.ts"],"names":[],"mappings":"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"}

package/dist/graph/minHeap.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Min-heap data structure for efficient priority queue operations.
+ * Used in beam search to maintain sorted frontier with O(log n) operations.
+ *
+ * @template T - Type of items in the heap (must have a numeric score property)
+ */
+export declare class MinHeap<T extends {
+    score: number;
+    priority?: number;
+    sequence?: number;
+}> {
+    private heap;
+    /**
+     * Insert an item into the heap.
+     * Time complexity: O(log n)
+     *
+     * @param item - Item to insert (must have a score property)
+     */
+    insert(item: T): void;
+    /**
+     * Remove and return the item with the lowest score.
+     * Time complexity: O(log n)
+     *
+     * @returns Item with minimum score, or undefined if heap is empty
+     */
+    extractMin(): T | undefined;
+    /**
+     * Peek at the item with the lowest score without removing it.
+     * Time complexity: O(1)
+     *
+     * @returns Item with minimum score, or undefined if heap is empty
+     */
+    peek(): T | undefined;
+    /**
+     * Check if the heap is empty.
+     * Time complexity: O(1)
+     *
+     * @returns true if heap has no items
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the number of items in the heap.
+     * Time complexity: O(1)
+     *
+     * @returns Number of items in the heap
+     */
+    size(): number;
+    /**
+     * Convert heap to array sorted by score (lowest to highest).
+     * This is a destructive operation - empties the heap.
+     *
+     * @returns Array of items sorted by score (lowest to highest)
+     */
+    toArray(): T[];
+    /**
+     * Get items as array in heap order (not sorted).
+     * This is non-destructive.
+     *
+     * @returns Copy of internal heap array
+     */
+    toHeapArray(): T[];
+    /**
+     * Clear all items from the heap.
+     */
+    clear(): void;
+    /**
+     * Move item at index up to restore heap property.
+     *
+     * @param index - Index of item to bubble up
+     */
+    private bubbleUp;
+    /**
+     * Move item at index down to restore heap property.
+     *
+     * @param index - Index of item to bubble down
+     */
+    private bubbleDown;
+    /**
+     * Swap two items in the heap array.
+     *
+     * @param i - First index
+     * @param j - Second index
+     */
+    private swap;
+    /**
+     * Compare two heap items with deterministic tie-breakers.
+     * Lower score is better; ties are broken by priority and then insertion sequence.
+     */
+    private compare;
+}
+//# sourceMappingURL=minHeap.d.ts.map

package/dist/graph/minHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minHeap.d.ts","sourceRoot":"","sources":["../../src/graph/minHeap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,OAAO,CAClB,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;IAEjE,OAAO,CAAC,IAAI,CAAW;IAEvB;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAKrB;;;;;OAKG;IACH,UAAU,IAAI,CAAC,GAAG,SAAS;IAgB3B;;;;;OAKG;IACH,IAAI,IAAI,CAAC,GAAG,SAAS;IAIrB;;;;;OAKG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;OAKG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,OAAO,IAAI,CAAC,EAAE;IAQd;;;;;OAKG;IACH,WAAW,IAAI,CAAC,EAAE;IAIlB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAWhB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA8BlB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAIZ;;;OAGG;IACH,OAAO,CAAC,OAAO;CAShB"}