@optave/codegraph 3.13.0 → 3.15.0

package/src/features/triage.ts

@@ -116,6 +116,33 @@ interface TriageDataOpts {
   repo?: Repository;
 }
 
+interface ResolvedRiskConfig {
+  weights: RiskWeights;
+  riskOpts: { roleWeights?: Record<string, number>; defaultRoleWeight?: number };
+}
+
+/** Resolve risk weights and role-weight options from config + opts overrides. */
+function resolveRiskConfig(opts: TriageDataOpts): ResolvedRiskConfig {
+  const config = opts.config || loadConfig();
+  const riskConfig = ((config as unknown as Record<string, unknown>).risk || {}) as {
+    weights?: Partial<RiskWeights>;
+    roleWeights?: Record<string, number>;
+    defaultRoleWeight?: number;
+  };
+  const weights: RiskWeights = {
+    ...DEFAULT_WEIGHTS,
+    ...(riskConfig.weights || {}),
+    ...(opts.weights || {}),
+  };
+  return {
+    weights,
+    riskOpts: {
+      roleWeights: riskConfig.roleWeights,
+      defaultRoleWeight: riskConfig.defaultRoleWeight,
+    },
+  };
+}
+
 export function triageData(
   customDbPath?: string,
   opts: TriageDataOpts = {},
@@ -125,21 +152,7 @@ export function triageData(
     const noTests = opts.noTests || false;
     const minScore = opts.minScore != null ? Number(opts.minScore) : null;
     const sort = opts.sort || 'risk';
-    const config = opts.config || loadConfig();
-    const riskConfig = ((config as unknown as Record<string, unknown>).risk || {}) as {
-      weights?: Partial<RiskWeights>;
-      roleWeights?: Record<string, number>;
-      defaultRoleWeight?: number;
-    };
-    const weights: RiskWeights = {
-      ...DEFAULT_WEIGHTS,
-      ...(riskConfig.weights || {}),
-      ...(opts.weights || {}),
-    };
-    const riskOpts = {
-      roleWeights: riskConfig.roleWeights,
-      defaultRoleWeight: riskConfig.defaultRoleWeight,
-    };
+    const { weights, riskOpts } = resolveRiskConfig(opts);
 
     let rows: TriageNodeRow[];
     try {

package/src/graph/algorithms/bfs.ts

@@ -6,10 +6,17 @@ export interface BfsOpts {
   direction?: 'forward' | 'backward' | 'both';
 }
 
+/** Resolve the neighbor list for a node given traversal direction. */
+function getNeighbors(graph: CodeGraph, node: string, direction: string): string[] {
+  if (direction === 'forward') return graph.successors(node);
+  if (direction === 'backward') return graph.predecessors(node);
+  return graph.neighbors(node);
+}
+
 /**
  * Breadth-first traversal on a CodeGraph.
  *
- * Tries the native Rust implementation first, falls back to JS.
+ * Tries the native Rust implementation first, falls back to a pure-JS queue.
  *
  * @returns nodeId → depth from nearest start node
  */
@@ -46,7 +53,10 @@ export function bfs(
   return bfsJS(graph, starts, maxDepth, direction);
 }
 
-/** Pure JS fallback for BFS (used when native addon is unavailable). */
+/**
+ * Pure-JS BFS queue (used when native addon is unavailable).
+ * Separated from bfs() to keep each function's complexity within thresholds.
+ */
 function bfsJS(
   graph: CodeGraph,
   starts: string[],
@@ -70,16 +80,7 @@ function bfsJS(
     const depth = depths.get(current)!;
     if (depth >= maxDepth) continue;
 
-    let neighbors: string[];
-    if (direction === 'forward') {
-      neighbors = graph.successors(current);
-    } else if (direction === 'backward') {
-      neighbors = graph.predecessors(current);
-    } else {
-      neighbors = graph.neighbors(current);
-    }
-
-    for (const n of neighbors) {
+    for (const n of getNeighbors(graph, current, direction)) {
       if (!depths.has(n)) {
         depths.set(n, depth + 1);
         queue.push(n);

package/src/graph/algorithms/tarjan.ts

@@ -15,6 +15,7 @@ export function tarjan(graph: CodeGraph): string[][] {
   const sccs: string[][] = [];
 
   function strongconnect(v: string): void {
+    // Assign the next discovery index and initialise lowlink to self
     indices.set(v, index);
     lowlinks.set(v, index);
     index++;
@@ -23,13 +24,16 @@ export function tarjan(graph: CodeGraph): string[][] {
 
     for (const w of graph.successors(v)) {
       if (!indices.has(w)) {
+        // Tree edge: recurse then propagate lowlink upward
         strongconnect(w);
         lowlinks.set(v, Math.min(lowlinks.get(v)!, lowlinks.get(w)!));
       } else if (onStack.has(w)) {
+        // Back/cross edge to a node still on the stack: update lowlink via index
         lowlinks.set(v, Math.min(lowlinks.get(v)!, indices.get(w)!));
       }
     }
 
+    // v is the root of an SCC when its lowlink equals its own discovery index
     if (lowlinks.get(v) === indices.get(v)) {
       const scc: string[] = [];
       let w: string | undefined;
@@ -38,6 +42,7 @@ export function tarjan(graph: CodeGraph): string[][] {
         onStack.delete(w);
         scc.push(w);
       } while (w !== v);
+      // Only report non-trivial SCCs (length > 1 = a real cycle)
       if (scc.length > 1) sccs.push(scc);
     }
   }

package/src/graph/builders/dependency.ts

@@ -78,6 +78,37 @@ interface MinConfidenceEdgeRow {
   target_id: number;
 }
 
+/**
+ * Fetch call edges from `dbOrRepo`, optionally filtered by a minimum confidence
+ * threshold. When `minConfidence` is unset, all call edges are returned.
+ */
+function resolveCallEdges(
+  dbOrRepo: BetterSqlite3Database | Repository,
+  isRepo: boolean,
+  minConfidence?: number,
+): CallEdgeRow[] | MinConfidenceEdgeRow[] {
+  if (minConfidence == null) {
+    return isRepo
+      ? (dbOrRepo as Repository).getCallEdges()
+      : getCallEdges(dbOrRepo as BetterSqlite3Database);
+  }
+  if (isRepo) {
+    // Trade-off: Repository.getCallEdges() returns all call edges, so we
+    // filter in JS. This is O(all call edges) rather than the SQL path's
+    // indexed WHERE clause. Acceptable for current data sizes; a dedicated
+    // getCallEdgesByMinConfidence(threshold) method on the Repository
+    // interface would be the proper fix if this becomes a bottleneck.
+    return (dbOrRepo as Repository)
+      .getCallEdges()
+      .filter((e) => e.confidence != null && e.confidence >= minConfidence);
+  }
+  return (dbOrRepo as BetterSqlite3Database)
+    .prepare<MinConfidenceEdgeRow>(
+      "SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?",
+    )
+    .all(minConfidence);
+}
+
 function buildFunctionLevelGraph(
   dbOrRepo: BetterSqlite3Database | Repository,
   noTests: boolean,
@@ -86,7 +117,9 @@ function buildFunctionLevelGraph(
   const graph = new CodeGraph();
   const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes: CallableNodeRow[] = isRepo ? dbOrRepo.getCallableNodes() : getCallableNodes(dbOrRepo);
+  let nodes: CallableNodeRow[] = isRepo
+    ? (dbOrRepo as Repository).getCallableNodes()
+    : getCallableNodes(dbOrRepo as BetterSqlite3Database);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   const nodeIds = new Set<number>();
@@ -100,28 +133,7 @@ function buildFunctionLevelGraph(
     nodeIds.add(n.id);
   }
 
-  let edges: CallEdgeRow[] | MinConfidenceEdgeRow[];
-  if (minConfidence != null) {
-    if (isRepo) {
-      // Trade-off: Repository.getCallEdges() returns all call edges, so we
-      // filter in JS. This is O(all call edges) rather than the SQL path's
-      // indexed WHERE clause. Acceptable for current data sizes; a dedicated
-      // getCallEdgesByMinConfidence(threshold) method on the Repository
-      // interface would be the proper fix if this becomes a bottleneck.
-      edges = dbOrRepo
-        .getCallEdges()
-        .filter((e) => e.confidence != null && e.confidence >= minConfidence);
-    } else {
-      edges = (dbOrRepo as BetterSqlite3Database)
-        .prepare<MinConfidenceEdgeRow>(
-          "SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?",
-        )
-        .all(minConfidence);
-    }
-  } else {
-    edges = isRepo ? dbOrRepo.getCallEdges() : getCallEdges(dbOrRepo);
-  }
-
+  const edges = resolveCallEdges(dbOrRepo, isRepo, minConfidence);
   for (const e of edges) {
     if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
     const src = String(e.source_id);

package/src/graph/classifiers/roles.ts

@@ -18,6 +18,14 @@ export const FRAMEWORK_ENTRY_PREFIXES: readonly string[] = ['route:', 'event:',
 
 const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
 
+/**
+ * Type definition kinds that are consumed via type annotations rather than calls.
+ * These have no inbound call edges by design — they are "used" by type references,
+ * struct literals, and generic parameters, none of which produce call edges.
+ * If the same file has active callables, type definitions are almost certainly live.
+ */
+const TYPE_DEF_KINDS = new Set(['struct', 'enum', 'trait', 'type', 'interface', 'record']);
+
 const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
 
 /** Path patterns indicating framework-dispatched entry points. */
@@ -29,6 +37,17 @@ const ENTRY_PATH_PATTERNS: readonly RegExp[] = [
   /middleware[/\\]/,
 ];
 
+/**
+ * Well-known Commander.js dispatch method names.
+ * When a method with one of these names lives in a file that matches
+ * ENTRY_PATH_PATTERNS, it is the actual framework entry point — not merely a
+ * candidate — so it must be classified as `entry` rather than `dead-entry`.
+ *
+ * `execute` — the action callback invoked by Commander on `program.action()`.
+ * `validate` — a pre-execution argument/option validator called before `execute`.
+ */
+const COMMANDER_DISPATCH_NAMES = new Set(['execute', 'validate']);
+
 export interface ClassifiableNode {
   kind?: string;
   file?: string;
@@ -74,7 +93,16 @@ export interface RoleClassificationNode {
   isExported: boolean;
   testOnlyFanIn?: number;
   productionFanIn?: number;
-  /** True when the same file contains at least one non-constant callable connected to the graph (fanIn > 0 or fanOut > 0). */
+  /**
+   * True when the same file contains at least one callable connected to the graph
+   * (fanIn > 0 or fanOut > 0) that is not itself an annotation-only kind.
+   * Annotation-only kinds are `constant` and all members of `TYPE_DEF_KINDS`
+   * (struct, enum, trait, type, interface, record) — these are excluded because
+   * they are consumed via references/type-annotations rather than call edges and
+   * would otherwise produce a circular dependency in the active-file heuristic.
+   * Populated only for `constant` and `TYPE_DEF_KINDS` nodes; `undefined` for
+   * regular callables (functions, methods, classes, etc.) which don't need it.
+   */
   hasActiveFileSiblings?: boolean;
 }
 
@@ -99,11 +127,37 @@ function computeFanMedians(nodes: RoleClassificationNode[]): { fanIn: number; fa
  * Covers framework-active constants, test-only callables, and the dead-* family.
  */
 function classifyUnreferencedNode(node: RoleClassificationNode): Role {
-  if (node.kind === 'constant' && node.hasActiveFileSiblings) {
-    // Constants consumed via identifier reference (not calls) have no
-    // inbound call edges. If the same file has active callables, the
-    // constant is almost certainly used locally — classify as leaf.
-    return 'leaf';
+  if (node.hasActiveFileSiblings) {
+    if (node.kind === 'constant') {
+      // Constants consumed via identifier reference (not calls) have no
+      // inbound call edges. If the same file has active callables, the
+      // constant is almost certainly used locally — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind && TYPE_DEF_KINDS.has(node.kind)) {
+      // Type definitions (struct, enum, trait, type, interface, record) are
+      // consumed via type annotations and struct literals — not calls — so they
+      // never get inbound call edges. If the same file has active callables,
+      // these types are almost certainly live — classify as leaf.
+      return 'leaf';
+    }
+    if (node.kind === 'method' && node.fanOut > 0) {
+      // Methods implementing interfaces are dispatched via conditional property
+      // access e.g. `if (v.enterFunction) v.enterFunction(...)`. Codegraph
+      // resolves the call to the property accessor rather than to the concrete
+      // method implementation, so the method has no inbound call edge. We
+      // require `fanOut > 0` as evidence of non-triviality, mirroring the
+      // function case — trivially-inert dead helper methods remain visible.
+      return 'leaf';
+    }
+    if (node.kind === 'function' && node.fanOut > 0) {
+      // Functions referenced as logical-or fallback defaults — e.g.
+      // `const fn = options._fetchLatest || fetchLatestVersion` — appear as
+      // value references, not call sites, so no call edge is produced. We
+      // require `fanOut > 0` as evidence that the function is non-trivial
+      // (i.e. it calls something), ruling out truly inert dead helpers.
+      return 'leaf';
+    }
   }
   if (node.testOnlyFanIn != null && node.testOnlyFanIn > 0) return 'test-only';
   return classifyDeadSubRole(node);
@@ -129,7 +183,20 @@ function classifyNodeRole(node: RoleClassificationNode, medFanIn: number, medFan
   if (FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p))) return 'entry';
 
   if (node.fanIn === 0) {
-    return node.isExported ? 'entry' : classifyUnreferencedNode(node);
+    if (!node.isExported) {
+      // Well-known Commander.js dispatch methods (execute, validate) in framework
+      // directories are confirmed entry points, not candidates. Promote them to
+      // `entry` directly so they don't appear in `--role dead` output.
+      if (
+        node.file &&
+        COMMANDER_DISPATCH_NAMES.has(node.name) &&
+        ENTRY_PATH_PATTERNS.some((p) => p.test(node.file!))
+      ) {
+        return 'entry';
+      }
+      return classifyUnreferencedNode(node);
+    }
+    return 'entry';
   }
 
   const hasProdFanIn = typeof node.productionFanIn === 'number';

package/src/infrastructure/config.ts

@@ -21,6 +21,7 @@ export const DEFAULTS = {
   include: [] as string[],
   exclude: [] as string[],
   ignoreDirs: [] as string[],
+  ignoreAdditionalDirs: [] as string[],
   extensions: [] as string[],
   aliases: {} as Record<string, string>,
   build: {
@@ -29,6 +30,8 @@ export const DEFAULTS = {
     driftThreshold: 0.2,
     smallFilesThreshold: 5,
     typescriptResolver: true,
+    engine: 'auto' as 'auto' | 'native' | 'wasm',
+    fastSkipDiag: false,
   },
   query: {
     defaultDepth: 3,
@@ -87,9 +90,16 @@ export const DEFAULTS = {
     // TODO(Phase 8.3): wire these into the points-to solver and type-propagation path
     // once config is threaded through to extractSymbols / buildPointsToMap. Currently
     // controlled by hardcoded constants in src/extractors/javascript.ts
-    // (MAX_PROPAGATION_DEPTH, PROPAGATION_HOP_PENALTY) and in
+    // (MAX_PROPAGATION_DEPTH, PROPAGATION_HOP_PENALTY, INFERRED_RETURN_TYPE_CONFIDENCE) and in
     // src/domain/graph/resolver/points-to.ts (MAX_SOLVER_ITERATIONS).
     typePropagationDepth: 3,
+    /**
+     * Confidence score assigned to a return type inferred from `return new Constructor()`
+     * when no explicit TypeScript annotation is present.
+     * Mirrors `INFERRED_RETURN_TYPE_CONFIDENCE` in `src/extractors/javascript.ts`.
+     * @reserved — not yet wired; see TODO above.
+     */
+    typeInferenceConfidence: 0.85,
     /**
      * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
      * @reserved — currently not wired to either the WASM solver
@@ -443,6 +453,7 @@ const BUILD_HASH_KEYS: ReadonlyArray<keyof CodegraphConfig> = [
   'include',
   'exclude',
   'ignoreDirs',
+  'ignoreAdditionalDirs',
   'extensions',
   'aliases',
   'build',
@@ -658,8 +669,8 @@ export function loadConfigWithProvenance(
         const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as Record<string, unknown>;
         for (const k of Object.keys(raw)) provenance[k] = 'project';
         break;
-      } catch {
-        // ignore
+      } catch (err) {
+        debug(`loadConfigWithProvenance: failed to parse ${filePath}: ${toErrorMessage(err)}`);
       }
     }
   }
@@ -686,6 +697,24 @@ export function applyEnvOverrides(config: CodegraphConfig): CodegraphConfig {
         process.env[envKey as keyof NodeJS.ProcessEnv];
     }
   }
+  // Engine selection: CODEGRAPH_ENGINE env always wins over config-file value.
+  if (process.env.CODEGRAPH_ENGINE !== undefined) {
+    const raw = process.env.CODEGRAPH_ENGINE;
+    const valid = ['auto', 'native', 'wasm'] as const;
+    if ((valid as readonly string[]).includes(raw)) {
+      (config.build as Record<string, unknown>).engine = raw as 'auto' | 'native' | 'wasm';
+    } else {
+      warn(
+        `CODEGRAPH_ENGINE="${raw}" is not a valid engine value (expected auto|native|wasm). Falling back to "auto".`,
+      );
+      (config.build as Record<string, unknown>).engine = 'auto';
+    }
+  }
+  // Fast-skip diagnostic flag.
+  if (process.env.CODEGRAPH_FAST_SKIP_DIAG !== undefined) {
+    (config.build as Record<string, unknown>).fastSkipDiag =
+      process.env.CODEGRAPH_FAST_SKIP_DIAG === '1';
+  }
   return config;
 }
 

package/src/infrastructure/registry.ts

@@ -242,19 +242,18 @@ interface PrunedEntry {
  *
  * When `dryRun` is true, entries are identified but not removed from disk.
  */
-export function pruneRegistry(
-  registryPath: string = REGISTRY_PATH,
-  ttlDays: number = DEFAULT_TTL_DAYS,
-  excludeNames: string[] = [],
-  dryRun = false,
+/**
+ * Walk `registry.repos`, identify entries that are missing on disk or have
+ * exceeded the TTL, and optionally delete them (when `dryRun` is false).
+ * Returns the list of entries that were (or would be) pruned.
+ */
+function pruneRepoEntries(
+  registry: Registry,
+  cutoff: number,
+  excludeSet: Set<string>,
+  dryRun: boolean,
 ): PrunedEntry[] {
-  const registry = loadRegistry(registryPath);
   const pruned: PrunedEntry[] = [];
-  const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
-  const excludeSet = new Set(
-    excludeNames.filter((n) => typeof n === 'string' && n.trim().length > 0),
-  );
-
   for (const [name, entry] of Object.entries(registry.repos)) {
     if (excludeSet.has(name)) continue;
     if (!fs.existsSync(entry.path)) {
@@ -268,18 +267,43 @@ export function pruneRegistry(
       if (!dryRun) delete registry.repos[name];
     }
   }
+  return pruned;
+}
 
-  // Prune consent entries whose repo paths no longer exist on disk.
-  // Consent entries are TTL-exempt — only the missing-path rule applies.
-  let consentChanged = false;
-  if (!dryRun && registry.userConfig?.consent) {
-    for (const p of Object.keys(registry.userConfig.consent)) {
-      if (!fs.existsSync(p)) {
-        delete registry.userConfig.consent[p];
-        consentChanged = true;
-      }
+/**
+ * Prune consent entries whose repo paths no longer exist on disk.
+ * Consent entries are TTL-exempt — only the missing-path rule applies.
+ * Returns true when at least one entry was removed.
+ */
+function pruneConsentEntries(consent: Record<string, ConsentDecision>): boolean {
+  let changed = false;
+  for (const p of Object.keys(consent)) {
+    if (!fs.existsSync(p)) {
+      delete consent[p];
+      changed = true;
     }
   }
+  return changed;
+}
+
+export function pruneRegistry(
+  registryPath: string = REGISTRY_PATH,
+  ttlDays: number = DEFAULT_TTL_DAYS,
+  excludeNames: string[] = [],
+  dryRun = false,
+): PrunedEntry[] {
+  const registry = loadRegistry(registryPath);
+  const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
+  const excludeSet = new Set(
+    excludeNames.filter((n) => typeof n === 'string' && n.trim().length > 0),
+  );
+
+  const pruned = pruneRepoEntries(registry, cutoff, excludeSet, dryRun);
+
+  const consentChanged =
+    !dryRun && registry.userConfig?.consent
+      ? pruneConsentEntries(registry.userConfig.consent)
+      : false;
 
   if (!dryRun && (pruned.length > 0 || consentChanged)) {
     saveRegistry(registry, registryPath);

package/src/infrastructure/update-check.ts

@@ -61,6 +61,33 @@ function saveCache(cache: UpdateCache, cachePath: string = CACHE_PATH): void {
   fs.renameSync(tmp, cachePath);
 }
 
+/**
+ * Collect the full response body from an IncomingMessage stream.
+ * Resolves with the body string, or null on parse/status error.
+ */
+function collectResponseBody(res: import('node:http').IncomingMessage): Promise<string | null> {
+  return new Promise((resolve) => {
+    if (res.statusCode !== 200) {
+      res.resume();
+      resolve(null);
+      return;
+    }
+    let body = '';
+    res.setEncoding('utf-8');
+    res.on('data', (chunk: string) => {
+      body += chunk;
+    });
+    res.on('end', () => {
+      try {
+        const data = JSON.parse(body);
+        resolve(typeof data.version === 'string' ? data.version : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+
 /**
  * Fetch the latest version string from the npm registry.
  * Returns the version string or null on failure.
@@ -71,24 +98,7 @@ function fetchLatestVersion(): Promise<string | null> {
       REGISTRY_URL,
       { timeout: FETCH_TIMEOUT_MS, headers: { Accept: 'application/json' } },
       (res) => {
-        if (res.statusCode !== 200) {
-          res.resume();
-          resolve(null);
-          return;
-        }
-        let body = '';
-        res.setEncoding('utf-8');
-        res.on('data', (chunk: string) => {
-          body += chunk;
-        });
-        res.on('end', () => {
-          try {
-            const data = JSON.parse(body);
-            resolve(typeof data.version === 'string' ? data.version : null);
-          } catch {
-            resolve(null);
-          }
-        });
+        collectResponseBody(res).then(resolve);
       },
     );
     req.on('error', () => resolve(null));
@@ -109,6 +119,32 @@ interface CheckForUpdatesOptions {
   _fetchLatest?: () => Promise<string | null>;
 }
 
+/**
+ * Return the latest version from cache if fresh, or fetch it from the registry.
+ * Persists the fetched version to the cache only when a network fetch occurs
+ * (i.e. the cache is stale or missing). Returns the cached value directly
+ * without updating the cache when the cache is still within `CACHE_TTL_MS`.
+ * Returns null when the network fetch fails or the cache is corrupt.
+ */
+async function resolveLatestVersion(
+  cachePath: string,
+  fetchFn: () => Promise<string | null>,
+): Promise<string | null> {
+  const cache = loadCache(cachePath);
+
+  if (cache && Date.now() - cache.lastCheckedAt < CACHE_TTL_MS) {
+    // Cache is fresh — use stored value directly
+    return cache.latestVersion;
+  }
+
+  // Cache is stale or missing — fetch from registry
+  const latest = await fetchFn();
+  if (!latest) return null;
+
+  saveCache({ lastCheckedAt: Date.now(), latestVersion: latest }, cachePath);
+  return latest;
+}
+
 /**
  * Check whether a newer version of codegraph is available.
  *
@@ -129,23 +165,9 @@ export async function checkForUpdates(
   const fetchFn = options._fetchLatest || fetchLatestVersion;
 
   try {
-    const cache = loadCache(cachePath);
-
-    // Cache is fresh — use it
-    if (cache && Date.now() - cache.lastCheckedAt < CACHE_TTL_MS) {
-      if (semverCompare(currentVersion, cache.latestVersion) < 0) {
-        return { current: currentVersion, latest: cache.latestVersion };
-      }
-      return null;
-    }
-
-    // Cache is stale or missing — fetch
-    const latest = await fetchFn();
+    const latest = await resolveLatestVersion(cachePath, fetchFn);
     if (!latest) return null;
 
-    // Update cache regardless of result
-    saveCache({ lastCheckedAt: Date.now(), latestVersion: latest }, cachePath);
-
     if (semverCompare(currentVersion, latest) < 0) {
       return { current: currentVersion, latest };
     }

package/src/mcp/server.ts

@@ -20,6 +20,7 @@ import type { CodegraphConfig, MCPServerOptions } from '../types.js';
 import { initMcpDefaults } from './middleware.js';
 import { buildToolList } from './tool-registry.js';
 import { TOOL_HANDLERS } from './tools/index.js';
+import type { McpToolContext } from './types.js';
 
 /**
  * Module-level guard to register shutdown handlers only once per process.
@@ -28,14 +29,7 @@ import { TOOL_HANDLERS } from './tools/index.js';
  */
 let _activeServer: any = null;
 
-export interface McpToolContext {
-  dbPath: string | undefined;
-  getQueries(): Promise<any>;
-  getDatabase(): any;
-  findDbPath: typeof findDbPath;
-  allowedRepos: string[] | undefined;
-  MCP_MAX_LIMIT: number;
-}
+export type { McpToolContext };
 
 interface MCPServerOptionsInternal extends MCPServerOptions {
   config?: CodegraphConfig;

package/src/mcp/tools/ast-query.ts

@@ -1,6 +1,6 @@
 import type { ASTNodeKind } from '../../types.js';
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
-import type { McpToolContext } from '../server.js';
+import type { McpToolContext } from '../types.js';
 
 export const name = 'ast_query';
 

package/src/mcp/tools/audit.ts

@@ -1,5 +1,5 @@
 import { effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
-import type { McpToolContext } from '../server.js';
+import type { McpToolContext } from '../types.js';
 
 export const name = 'audit';
 

package/src/mcp/tools/batch-query.ts

@@ -1,4 +1,4 @@
-import type { McpToolContext } from '../server.js';
+import type { McpToolContext } from '../types.js';
 
 export const name = 'batch_query';
 

package/src/mcp/tools/branch-compare.ts

@@ -1,4 +1,4 @@
-import type { McpToolContext } from '../server.js';
+import type { McpToolContext } from '../types.js';
 
 export const name = 'branch_compare';
 

package/src/mcp/tools/brief.ts

@@ -1,4 +1,4 @@
-import type { McpToolContext } from '../server.js';
+import type { McpToolContext } from '../types.js';
 
 export const name = 'brief';