@optave/codegraph 3.2.0 → 3.3.1

package/src/graph/classifiers/risk.js

@@ -26,6 +26,10 @@ export const ROLE_WEIGHTS = {
   leaf: 0.2,
   'test-only': 0.1,
   dead: 0.1,
+  'dead-leaf': 0.0,
+  'dead-entry': 0.3,
+  'dead-ffi': 0.05,
+  'dead-unresolved': 0.15,
 };
 
 const DEFAULT_ROLE_WEIGHT = 0.5;
@@ -48,11 +52,14 @@ function round4(n) {
  *
  * @param {{ fan_in: number, cognitive: number, churn: number, mi: number, role: string|null }[]} items
  * @param {object} [weights] - Override DEFAULT_WEIGHTS
+ * @param {{ roleWeights?: object, defaultRoleWeight?: number }} [opts] - Optional role weight overrides
  * @returns {{ normFanIn: number, normComplexity: number, normChurn: number, normMI: number, roleWeight: number, riskScore: number }[]}
  *   Parallel array with risk metrics for each input item.
  */
-export function scoreRisk(items, weights = {}) {
+export function scoreRisk(items, weights = {}, opts = {}) {
   const w = { ...DEFAULT_WEIGHTS, ...weights };
+  const rw = opts.roleWeights || ROLE_WEIGHTS;
+  const drw = opts.defaultRoleWeight ?? DEFAULT_ROLE_WEIGHT;
 
   const fanIns = items.map((r) => r.fan_in);
   const cognitives = items.map((r) => r.cognitive);
@@ -66,7 +73,7 @@ export function scoreRisk(items, weights = {}) {
   const normMIs = normMIsRaw.map((v) => round4(1 - v));
 
   return items.map((r, i) => {
-    const roleWeight = ROLE_WEIGHTS[r.role] ?? DEFAULT_ROLE_WEIGHT;
+    const roleWeight = rw[r.role] ?? drw;
     const riskScore =
       w.fanIn * normFanIns[i] +
       w.complexity * normCognitives[i] +

package/src/graph/classifiers/roles.js

@@ -1,11 +1,59 @@
 /**
  * Node role classification — pure logic, no DB.
  *
- * Roles: entry, core, utility, adapter, leaf, dead, test-only
+ * Roles: entry, core, utility, adapter, leaf, dead-*, test-only
+ *
+ * Dead sub-categories refine the coarse "dead" bucket:
+ *   dead-leaf       — parameters, properties, constants (leaf nodes by definition)
+ *   dead-entry      — framework dispatch: CLI commands, MCP tools, event handlers
+ *   dead-ffi        — cross-language FFI boundaries (e.g. Rust napi-rs bindings)
+ *   dead-unresolved — genuinely unreferenced callables (the real dead code)
  */
 
 export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
 
+// ── Dead sub-classification helpers ────────────────────────────────
+
+const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
+
+const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
+
+/** Path patterns indicating framework-dispatched entry points. */
+const ENTRY_PATH_PATTERNS = [
+  /cli[/\\]commands[/\\]/,
+  /mcp[/\\]/,
+  /routes?[/\\]/,
+  /handlers?[/\\]/,
+  /middleware[/\\]/,
+];
+
+/**
+ * Refine a "dead" classification into a sub-category.
+ *
+ * @param {{ kind?: string, file?: string }} node
+ * @returns {'dead-leaf'|'dead-entry'|'dead-ffi'|'dead-unresolved'}
+ */
+function classifyDeadSubRole(node) {
+  // Leaf kinds are dead by definition — they can't have callers
+  if (node.kind && LEAF_KINDS.has(node.kind)) return 'dead-leaf';
+
+  if (node.file) {
+    // Cross-language FFI: compiled-language files in a JS/TS project
+    // Priority: dead-ffi is checked before dead-entry deliberately — an FFI
+    // boundary is a more fundamental classification than a path-based hint.
+    // A .so/.dll in a routes/ directory is still FFI, not an entry point.
+    const dotIdx = node.file.lastIndexOf('.');
+    if (dotIdx !== -1 && FFI_EXTENSIONS.has(node.file.slice(dotIdx))) return 'dead-ffi';
+
+    // Framework-dispatched entry points (CLI commands, MCP tools, routes)
+    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file))) return 'dead-entry';
+  }
+
+  return 'dead-unresolved';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
 function median(sorted) {
   if (sorted.length === 0) return 0;
   const mid = Math.floor(sorted.length / 2);
@@ -15,7 +63,7 @@ function median(sorted) {
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
  *
- * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
+ * @param {{ id: string, name: string, kind?: string, file?: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
  * @returns {Map<string, string>} nodeId → role
  */
 export function classifyRoles(nodes) {
@@ -45,7 +93,7 @@ export function classifyRoles(nodes) {
     if (isFrameworkEntry) {
       role = 'entry';
     } else if (node.fanIn === 0 && !node.isExported) {
-      role = node.testOnlyFanIn > 0 ? 'test-only' : 'dead';
+      role = node.testOnlyFanIn > 0 ? 'test-only' : classifyDeadSubRole(node);
     } else if (node.fanIn === 0 && node.isExported) {
       role = 'entry';
     } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0) {

package/src/infrastructure/config.js

@@ -23,7 +23,7 @@ export const DEFAULTS = {
   },
   embeddings: { model: 'nomic-v1.5', llmProvider: null },
   llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
-  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15 },
+  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15, similarityWarnThreshold: 0.85 },
   ci: { failOnCycles: false, impactThreshold: null },
   manifesto: {
     rules: {
@@ -54,14 +54,95 @@ export const DEFAULTS = {
     minJaccard: 0.3,
     maxFilesPerCommit: 50,
   },
+  analysis: {
+    impactDepth: 3,
+    fnImpactDepth: 5,
+    auditDepth: 3,
+    sequenceDepth: 10,
+    falsePositiveCallers: 20,
+    briefCallerDepth: 5,
+    briefImporterDepth: 5,
+    briefHighRiskCallers: 10,
+    briefMediumRiskCallers: 3,
+  },
+  community: {
+    resolution: 1.0,
+  },
+  structure: {
+    cohesionThreshold: 0.3,
+  },
+  risk: {
+    weights: {
+      fanIn: 0.25,
+      complexity: 0.3,
+      churn: 0.2,
+      role: 0.15,
+      mi: 0.1,
+    },
+    roleWeights: {
+      core: 1.0,
+      utility: 0.9,
+      entry: 0.8,
+      adapter: 0.5,
+      leaf: 0.2,
+      'test-only': 0.1,
+      dead: 0.1,
+      'dead-leaf': 0.0,
+      'dead-entry': 0.3,
+      'dead-ffi': 0.05,
+      'dead-unresolved': 0.15,
+    },
+    defaultRoleWeight: 0.5,
+  },
+  display: {
+    maxColWidth: 40,
+    excerptLines: 50,
+    summaryMaxChars: 100,
+    jsdocEndScanLines: 10,
+    jsdocOpenScanLines: 20,
+    signatureGatherLines: 5,
+  },
+  mcp: {
+    defaults: {
+      list_functions: 100,
+      query: 10,
+      where: 50,
+      node_roles: 100,
+      export_graph: 500,
+      fn_impact: 5,
+      context: 5,
+      explain: 10,
+      file_deps: 20,
+      file_exports: 20,
+      diff_impact: 30,
+      impact_analysis: 20,
+      semantic_search: 20,
+      execution_flow: 50,
+      hotspots: 20,
+      co_changes: 20,
+      complexity: 30,
+      manifesto: 50,
+      communities: 20,
+      structure: 30,
+      triage: 20,
+      ast_query: 50,
+    },
+  },
 };
 
+// Per-cwd config cache — avoids re-reading the config file on every query call.
+// The config file rarely changes within a single process lifetime.
+const _configCache = new Map();
+
 /**
  * Load project configuration from a .codegraphrc.json or similar file.
- * Returns merged config with defaults.
+ * Returns merged config with defaults. Results are cached per cwd.
  */
 export function loadConfig(cwd) {
   cwd = cwd || process.cwd();
+  const cached = _configCache.get(cwd);
+  if (cached) return structuredClone(cached);
+
   for (const name of CONFIG_FILES) {
     const filePath = path.join(cwd, name);
     if (fs.existsSync(filePath)) {
@@ -74,13 +155,26 @@ export function loadConfig(cwd) {
           merged.query.excludeTests = Boolean(config.excludeTests);
         }
         delete merged.excludeTests;
-        return resolveSecrets(applyEnvOverrides(merged));
+        const result = resolveSecrets(applyEnvOverrides(merged));
+        _configCache.set(cwd, structuredClone(result));
+        return result;
       } catch (err) {
         debug(`Failed to parse config ${filePath}: ${err.message}`);
       }
     }
   }
-  return resolveSecrets(applyEnvOverrides({ ...DEFAULTS }));
+  const defaults = resolveSecrets(applyEnvOverrides({ ...DEFAULTS }));
+  _configCache.set(cwd, structuredClone(defaults));
+  return defaults;
+}
+
+/**
+ * Clear the config cache. Intended for long-running processes that need to
+ * pick up on-disk config changes, and for test isolation when tests share
+ * the same cwd.
+ */
+export function clearConfigCache() {
+  _configCache.clear();
 }
 
 const ENV_LLM_MAP = {
@@ -120,7 +214,183 @@ export function resolveSecrets(config) {
   return config;
 }
 
-function mergeConfig(defaults, overrides) {
+// ── Monorepo workspace detection ─────────────────────────────────────
+
+/**
+ * Expand a workspace glob pattern into matching directories.
+ * Supports trailing `/*` or `/**` patterns (e.g. "packages/*").
+ * Does not depend on an external glob library — uses fs.readdirSync.
+ */
+function expandWorkspaceGlob(pattern, rootDir) {
+  // Strip trailing /*, /**, or just *
+  const clean = pattern.replace(/\/?\*\*?$/, '');
+  const baseDir = path.resolve(rootDir, clean);
+  if (!fs.existsSync(baseDir)) return [];
+  try {
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(baseDir, e.name))
+      .filter((d) => fs.existsSync(path.join(d, 'package.json')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a package.json and return its name field, or null.
+ */
+function readPackageName(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the entry-point source file for a workspace package.
+ * Checks exports → main → index file fallback.
+ */
+function resolveWorkspaceEntry(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+
+    // Try "source" field first (common in monorepos for pre-built packages)
+    if (pkg.source) {
+      const s = path.resolve(pkgDir, pkg.source);
+      if (fs.existsSync(s)) return s;
+    }
+
+    // Try "main" field
+    if (pkg.main) {
+      const m = path.resolve(pkgDir, pkg.main);
+      if (fs.existsSync(m)) return m;
+    }
+
+    // Index file fallback
+    for (const idx of [
+      'index.ts',
+      'index.tsx',
+      'index.js',
+      'index.mjs',
+      'src/index.ts',
+      'src/index.tsx',
+      'src/index.js',
+    ]) {
+      const candidate = path.resolve(pkgDir, idx);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * Detect monorepo workspace packages from workspace configuration files.
+ *
+ * Checks (in order):
+ *   1. pnpm-workspace.yaml — `packages:` array
+ *   2. package.json — `workspaces` field (npm/yarn)
+ *   3. lerna.json — `packages` array
+ *
+ * @param {string} rootDir - Project root directory
+ * @returns {Map<string, { dir: string, entry: string|null }>}
+ *   Map of package name → { absolute dir, resolved entry file }
+ */
+export function detectWorkspaces(rootDir) {
+  const workspaces = new Map();
+  const patterns = [];
+
+  // 1. pnpm-workspace.yaml
+  const pnpmPath = path.join(rootDir, 'pnpm-workspace.yaml');
+  if (fs.existsSync(pnpmPath)) {
+    try {
+      const raw = fs.readFileSync(pnpmPath, 'utf-8');
+      // Simple YAML parse for `packages:` array — no dependency needed
+      const packagesMatch = raw.match(/^packages:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      if (packagesMatch) {
+        const lines = packagesMatch[1].match(/^\s+-\s+['"]?([^'"#\n]+)['"]?\s*$/gm);
+        if (lines) {
+          for (const line of lines) {
+            const m = line.match(/^\s+-\s+['"]?([^'"#\n]+?)['"]?\s*$/);
+            if (m) patterns.push(m[1].trim());
+          }
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // 2. package.json workspaces (npm/yarn)
+  if (patterns.length === 0) {
+    const rootPkgPath = path.join(rootDir, 'package.json');
+    if (fs.existsSync(rootPkgPath)) {
+      try {
+        const raw = fs.readFileSync(rootPkgPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        const ws = pkg.workspaces;
+        if (Array.isArray(ws)) {
+          patterns.push(...ws);
+        } else if (ws && Array.isArray(ws.packages)) {
+          // Yarn classic format: { packages: [...], nohoist: [...] }
+          patterns.push(...ws.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // 3. lerna.json
+  if (patterns.length === 0) {
+    const lernaPath = path.join(rootDir, 'lerna.json');
+    if (fs.existsSync(lernaPath)) {
+      try {
+        const raw = fs.readFileSync(lernaPath, 'utf-8');
+        const lerna = JSON.parse(raw);
+        if (Array.isArray(lerna.packages)) {
+          patterns.push(...lerna.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  if (patterns.length === 0) return workspaces;
+
+  // Expand glob patterns and collect packages
+  for (const pattern of patterns) {
+    // Check if pattern is a direct path (no glob) or a glob
+    if (pattern.includes('*')) {
+      for (const dir of expandWorkspaceGlob(pattern, rootDir)) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    } else {
+      // Direct path like "packages/core"
+      const dir = path.resolve(rootDir, pattern);
+      if (fs.existsSync(path.join(dir, 'package.json'))) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    }
+  }
+
+  if (workspaces.size > 0) {
+    debug(`Detected ${workspaces.size} workspace packages: ${[...workspaces.keys()].join(', ')}`);
+  }
+
+  return workspaces;
+}
+
+export function mergeConfig(defaults, overrides) {
   const result = { ...defaults };
   for (const [key, value] of Object.entries(overrides)) {
     if (
@@ -128,9 +398,10 @@ function mergeConfig(defaults, overrides) {
       typeof value === 'object' &&
       !Array.isArray(value) &&
       defaults[key] &&
-      typeof defaults[key] === 'object'
+      typeof defaults[key] === 'object' &&
+      !Array.isArray(defaults[key])
     ) {
-      result[key] = { ...defaults[key], ...value };
+      result[key] = mergeConfig(defaults[key], value);
     } else {
       result[key] = value;
     }

package/src/mcp/middleware.js

@@ -2,10 +2,28 @@
  * MCP middleware helpers — pagination defaults and limits.
  */
 
-import { MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
+import { getMcpDefaults, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
 
 export { MCP_DEFAULTS, MCP_MAX_LIMIT };
 
+/** Resolved MCP defaults (may include config overrides). Set via initMcpDefaults(). */
+let resolvedDefaults = MCP_DEFAULTS;
+
+/**
+ * Initialize MCP defaults from config. Call once at server startup.
+ * @param {object} [configMcpDefaults] - config.mcp.defaults overrides
+ */
+export function initMcpDefaults(configMcpDefaults) {
+  resolvedDefaults = getMcpDefaults(configMcpDefaults);
+}
+
+/**
+ * Reset MCP defaults back to the base defaults. Useful for test isolation.
+ */
+export function resetMcpDefaults() {
+  resolvedDefaults = MCP_DEFAULTS;
+}
+
 /**
  * Resolve effective limit for a tool call.
  * @param {object} args - Tool arguments
@@ -13,7 +31,7 @@ export { MCP_DEFAULTS, MCP_MAX_LIMIT };
  * @returns {number}
  */
 export function effectiveLimit(args, toolName) {
-  return Math.min(args.limit ?? MCP_DEFAULTS[toolName] ?? 100, MCP_MAX_LIMIT);
+  return Math.min(args.limit ?? resolvedDefaults[toolName] ?? 100, MCP_MAX_LIMIT);
 }
 
 /**

package/src/mcp/server.js

@@ -7,8 +7,10 @@
 
 import { createRequire } from 'node:module';
 import { findDbPath } from '../db/index.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { CodegraphError, ConfigError } from '../shared/errors.js';
 import { MCP_MAX_LIMIT } from '../shared/paginate.js';
+import { initMcpDefaults } from './middleware.js';
 import { buildToolList } from './tool-registry.js';
 import { TOOL_HANDLERS } from './tools/index.js';
 
@@ -91,6 +93,10 @@ export async function startMCPServer(customDbPath, options = {}) {
   const { allowedRepos } = options;
   const multiRepo = options.multiRepo || !!allowedRepos;
 
+  // Apply config-based MCP page-size overrides
+  const config = options.config || loadConfig();
+  initMcpDefaults(config.mcp?.defaults);
+
   const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } =
     await loadMCPSdk();
 

package/src/mcp/tool-registry.js

@@ -362,7 +362,7 @@ const BASE_TOOLS = [
   {
     name: 'node_roles',
     description:
-      'Show node role classification (entry, core, utility, adapter, dead, leaf) based on connectivity patterns',
+      'Show node role classification (entry, core, utility, adapter, dead [dead-leaf, dead-entry, dead-ffi, dead-unresolved], leaf) based on connectivity patterns',
     inputSchema: {
       type: 'object',
       properties: {
@@ -758,6 +758,45 @@ const BASE_TOOLS = [
       },
     },
   },
+  {
+    name: 'implementations',
+    description:
+      'List all concrete types (classes, structs, records) that implement a given interface or trait',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Interface/trait name (partial match)' },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: {
+          type: 'string',
+          enum: EVERY_SYMBOL_KIND,
+          description: 'Filter by symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'interfaces',
+    description: 'List all interfaces and traits that a given class, struct, or record implements',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Class/struct name (partial match)' },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        kind: {
+          type: 'string',
+          enum: EVERY_SYMBOL_KIND,
+          description: 'Filter by symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+      required: ['name'],
+    },
+  },
   {
     name: 'ast_query',
     description:

package/src/mcp/tools/implementations.js

@@ -0,0 +1,14 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+
+export const name = 'implementations';
+
+export async function handler(args, ctx) {
+  const { implementationsData } = await ctx.getQueries();
+  return implementationsData(args.name, ctx.dbPath, {
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/index.js

@@ -23,6 +23,8 @@ import * as fileExports from './file-exports.js';
 import * as findCycles from './find-cycles.js';
 import * as fnImpact from './fn-impact.js';
 import * as impactAnalysis from './impact-analysis.js';
+import * as implementations from './implementations.js';
+import * as interfaces from './interfaces.js';
 import * as listFunctions from './list-functions.js';
 import * as listRepos from './list-repos.js';
 import * as moduleMap from './module-map.js';
@@ -69,5 +71,7 @@ export const TOOL_HANDLERS = new Map([
   [check.name, check],
   [astQuery.name, astQuery],
   [brief.name, brief],
+  [implementations.name, implementations],
+  [interfaces.name, interfaces],
   [listRepos.name, listRepos],
 ]);

package/src/mcp/tools/interfaces.js

@@ -0,0 +1,14 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+
+export const name = 'interfaces';
+
+export async function handler(args, ctx) {
+  const { interfacesData } = await ctx.getQueries();
+  return interfacesData(args.name, ctx.dbPath, {
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/semantic-search.js

@@ -11,7 +11,7 @@ export async function handler(args, ctx) {
   };
 
   if (mode === 'keyword') {
-    const { ftsSearchData } = await import('../../embeddings/index.js');
+    const { ftsSearchData } = await import('../../domain/search/index.js');
     const result = ftsSearchData(args.query, ctx.dbPath, searchOpts);
     if (result === null) {
       return {
@@ -28,7 +28,7 @@ export async function handler(args, ctx) {
   }
 
   if (mode === 'semantic') {
-    const { searchData } = await import('../../embeddings/index.js');
+    const { searchData } = await import('../../domain/search/index.js');
     const result = await searchData(args.query, ctx.dbPath, searchOpts);
     if (result === null) {
       return {
@@ -45,7 +45,7 @@ export async function handler(args, ctx) {
   }
 
   // hybrid (default) — falls back to semantic if no FTS5
-  const { hybridSearchData, searchData } = await import('../../embeddings/index.js');
+  const { hybridSearchData, searchData } = await import('../../domain/search/index.js');
   let result = await hybridSearchData(args.query, ctx.dbPath, searchOpts);
   if (result === null) {
     result = await searchData(args.query, ctx.dbPath, searchOpts);