@optave/codegraph 3.2.0 → 3.3.0

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/presentation/queries-cli/exports.js

@@ -30,11 +30,39 @@ function printExportSymbols(results) {
   }
 }
 
+function printReexportedSymbols(reexportedSymbols) {
+  // Group by origin file
+  const byOrigin = new Map();
+  for (const sym of reexportedSymbols) {
+    if (!byOrigin.has(sym.originFile)) byOrigin.set(sym.originFile, []);
+    byOrigin.get(sym.originFile).push(sym);
+  }
+
+  for (const [originFile, syms] of byOrigin) {
+    console.log(`\n  from ${originFile}:`);
+    for (const sym of syms) {
+      const icon = kindIcon(sym.kind);
+      const sig = sym.signature?.params ? `(${sym.signature.params})` : '';
+      const role = sym.role ? ` [${sym.role}]` : '';
+      console.log(`    ${icon} ${sym.name}${sig}${role} :${sym.line}`);
+      if (sym.consumers.length === 0) {
+        console.log('      (no consumers)');
+      } else {
+        for (const c of sym.consumers) {
+          console.log(`      <- ${c.name} (${c.file}:${c.line})`);
+        }
+      }
+    }
+  }
+}
+
 export function fileExports(file, customDbPath, opts = {}) {
   const data = exportsData(file, customDbPath, opts);
   if (outputResult(data, 'results', opts)) return;
 
-  if (data.results.length === 0) {
+  const hasReexported = data.reexportedSymbols && data.reexportedSymbols.length > 0;
+
+  if (data.results.length === 0 && !hasReexported) {
     if (opts.unused) {
       console.log(`No unused exports found for "${file}".`);
     } else {
@@ -43,11 +71,33 @@ export function fileExports(file, customDbPath, opts = {}) {
     return;
   }
 
-  printExportHeader(data, opts);
-  printExportSymbols(data.results);
+  if (data.results.length > 0) {
+    printExportHeader(data, opts);
+    printExportSymbols(data.results);
+  }
+
+  if (hasReexported) {
+    const totalReexported = opts.unused
+      ? (data.totalReexportedUnused ?? data.reexportedSymbols.length)
+      : (data.totalReexported ?? data.reexportedSymbols.length);
+    if (data.results.length === 0) {
+      if (opts.unused) {
+        console.log(
+          `\n# ${data.file} — barrel file (${totalReexported} unused re-exported symbol${totalReexported !== 1 ? 's' : ''} from sub-modules)\n`,
+        );
+      } else {
+        console.log(
+          `\n# ${data.file} — barrel file (${totalReexported} re-exported symbol${totalReexported !== 1 ? 's' : ''} from sub-modules)\n`,
+        );
+      }
+    } else {
+      console.log(`\n  Re-exported symbols (${totalReexported} from sub-modules):`);
+    }
+    printReexportedSymbols(data.reexportedSymbols);
+  }
 
   if (data.reexports.length > 0) {
-    console.log(`\n  Re-exports: ${data.reexports.map((r) => r.file).join(', ')}`);
+    console.log(`\n  Re-exported by: ${data.reexports.map((r) => r.file).join(', ')}`);
   }
   console.log();
 }

package/src/presentation/queries-cli/index.js

@@ -1,5 +1,13 @@
 export { fileExports } from './exports.js';
 export { diffImpact, fileDeps, fnDeps, fnImpact, impactAnalysis } from './impact.js';
-export { children, context, explain, queryName, where } from './inspect.js';
+export {
+  children,
+  context,
+  explain,
+  implementations,
+  interfaces,
+  queryName,
+  where,
+} from './inspect.js';
 export { moduleMap, roles, stats } from './overview.js';
 export { symbolPath } from './path.js';

package/src/presentation/queries-cli/inspect.js

@@ -2,6 +2,8 @@ import {
   childrenData,
   contextData,
   explainData,
+  implementationsData,
+  interfacesData,
   kindIcon,
   queryNameData,
   whereData,
@@ -181,6 +183,22 @@ function renderContextResult(r) {
     console.log();
   }
 
+  if (r.implementors && r.implementors.length > 0) {
+    console.log(`## Implementors (${r.implementors.length})`);
+    for (const impl of r.implementors) {
+      console.log(`  ${kindIcon(impl.kind)} ${impl.name}  ${impl.file}:${impl.line}`);
+    }
+    console.log();
+  }
+
+  if (r.implements && r.implements.length > 0) {
+    console.log(`## Implements (${r.implements.length})`);
+    for (const iface of r.implements) {
+      console.log(`  ${kindIcon(iface.kind)} ${iface.name}  ${iface.file}:${iface.line}`);
+    }
+    console.log();
+  }
+
   if (r.relatedTests.length > 0) {
     console.log('## Related Tests');
     for (const t of r.relatedTests) {
@@ -327,3 +345,49 @@ export function explain(target, customDbPath, opts = {}) {
     }
   }
 }
+
+export function implementations(name, customDbPath, opts = {}) {
+  const data = implementationsData(name, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No symbol matching "${name}"`);
+    return;
+  }
+
+  for (const r of data.results) {
+    console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}`);
+    if (r.implementors.length === 0) {
+      console.log('  (no implementors found)');
+    } else {
+      console.log(`  Implementors (${r.implementors.length}):`);
+      for (const impl of r.implementors) {
+        console.log(`    ${kindIcon(impl.kind)} ${impl.name}  ${impl.file}:${impl.line}`);
+      }
+    }
+  }
+  console.log();
+}
+
+export function interfaces(name, customDbPath, opts = {}) {
+  const data = interfacesData(name, customDbPath, opts);
+  if (outputResult(data, 'results', opts)) return;
+
+  if (data.results.length === 0) {
+    console.log(`No symbol matching "${name}"`);
+    return;
+  }
+
+  for (const r of data.results) {
+    console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}`);
+    if (r.interfaces.length === 0) {
+      console.log('  (no interfaces/traits found)');
+    } else {
+      console.log(`  Implements (${r.interfaces.length}):`);
+      for (const iface of r.interfaces) {
+        console.log(`    ${kindIcon(iface.kind)} ${iface.name}  ${iface.file}:${iface.line}`);
+      }
+    }
+  }
+  console.log();
+}

package/src/presentation/queries-cli.js

@@ -4,7 +4,7 @@
  * The actual implementations live in queries-cli/ split by concern:
  *   path.js     — symbolPath
  *   overview.js — stats, moduleMap, roles
- *   inspect.js  — where, queryName, context, children, explain
+ *   inspect.js  — where, queryName, context, children, explain, implementations, interfaces
  *   impact.js   — fileDeps, fnDeps, impactAnalysis, fnImpact, diffImpact
  *   exports.js  — fileExports
  */
@@ -18,6 +18,8 @@ export {
   fnDeps,
   fnImpact,
   impactAnalysis,
+  implementations,
+  interfaces,
   moduleMap,
   queryName,
   roles,

package/src/presentation/result-formatter.js

@@ -1,3 +1,4 @@
+import { loadConfig } from '../infrastructure/config.js';
 import { printNdjson } from '../shared/paginate.js';
 import { formatTable, truncEnd } from './table.js';
 
@@ -85,11 +86,13 @@ const MAX_COL_WIDTH = 40;
  * Print data as an aligned table to stdout.
  * @param {object} data - Result object from a *Data() function
  * @param {string} field - Array field name (e.g. 'results')
+ * @param {{ maxColWidth?: number }} [displayOpts]
  */
-function printAutoTable(data, field) {
+function printAutoTable(data, field, displayOpts = {}) {
   const prepared = prepareFlatItems(data, field);
   if (!prepared) return false;
   const { flatItems, columns } = prepared;
+  const colWidth = displayOpts.maxColWidth ?? MAX_COL_WIDTH;
 
   const colDefs = columns.map((col) => {
     const maxLen = flatItems.reduce(
@@ -104,13 +107,13 @@ function printAutoTable(data, field) {
       });
     return {
       header: col,
-      width: Math.min(maxLen, MAX_COL_WIDTH),
+      width: Math.min(maxLen, colWidth),
       align: isNumeric ? 'right' : 'left',
     };
   });
 
   const rows = flatItems.map((item) =>
-    columns.map((col) => truncEnd(String(item[col] ?? ''), MAX_COL_WIDTH)),
+    columns.map((col) => truncEnd(String(item[col] ?? ''), colWidth)),
   );
 
   console.log(formatTable({ columns: colDefs, rows }));
@@ -122,7 +125,7 @@ function printAutoTable(data, field) {
  *
  * @param {object} data   - Result object from a *Data() function
  * @param {string} field  - Array field name for NDJSON streaming (e.g. 'results')
- * @param {object} opts   - CLI options ({ json?, ndjson?, table?, csv? })
+ * @param {object} opts   - CLI options ({ json?, ndjson?, table?, csv?, display?: { maxColWidth? } })
  * @returns {boolean} true if output was handled (caller should return early)
  */
 export function outputResult(data, field, opts) {
@@ -138,7 +141,8 @@ export function outputResult(data, field, opts) {
     return printCsv(data, field) !== false;
   }
   if (opts.table) {
-    return printAutoTable(data, field) !== false;
+    const displayOpts = opts.display ?? loadConfig().display;
+    return printAutoTable(data, field, displayOpts) !== false;
   }
   return false;
 }

package/src/shared/file-utils.js

@@ -13,14 +13,15 @@ export function safePath(repoRoot, file) {
   return resolved;
 }
 
-export function readSourceRange(repoRoot, file, startLine, endLine) {
+export function readSourceRange(repoRoot, file, startLine, endLine, opts = {}) {
   try {
     const absPath = safePath(repoRoot, file);
     if (!absPath) return null;
     const content = fs.readFileSync(absPath, 'utf-8');
     const lines = content.split('\n');
+    const excerptLines = opts.excerptLines ?? 50;
     const start = Math.max(0, (startLine || 1) - 1);
-    const end = Math.min(lines.length, endLine || startLine + 50);
+    const end = Math.min(lines.length, endLine || startLine + excerptLines);
     return lines.slice(start, end).join('\n');
   } catch (e) {
     debug(`readSourceRange failed for ${file}: ${e.message}`);
@@ -28,12 +29,15 @@ export function readSourceRange(repoRoot, file, startLine, endLine) {
   }
 }
 
-export function extractSummary(fileLines, line) {
+export function extractSummary(fileLines, line, opts = {}) {
   if (!fileLines || !line || line <= 1) return null;
   const idx = line - 2; // line above the definition (0-indexed)
-  // Scan up to 10 lines above for JSDoc or comment
+  const jsdocEndScanLines = opts.jsdocEndScanLines ?? 10;
+  const jsdocOpenScanLines = opts.jsdocOpenScanLines ?? 20;
+  const summaryMaxChars = opts.summaryMaxChars ?? 100;
+  // Scan up for JSDoc or comment
   let jsdocEnd = -1;
-  for (let i = idx; i >= Math.max(0, idx - 10); i--) {
+  for (let i = idx; i >= Math.max(0, idx - jsdocEndScanLines); i--) {
     const trimmed = fileLines[i].trim();
     if (trimmed.endsWith('*/')) {
       jsdocEnd = i;
@@ -45,13 +49,13 @@ export function extractSummary(fileLines, line) {
         .replace(/^\/\/\s*/, '')
         .replace(/^#\s*/, '')
         .trim();
-      return text.length > 100 ? `${text.slice(0, 100)}...` : text;
+      return text.length > summaryMaxChars ? `${text.slice(0, summaryMaxChars)}...` : text;
     }
     if (trimmed !== '' && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) break;
   }
   if (jsdocEnd >= 0) {
     // Find opening /**
-    for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - 20); i--) {
+    for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - jsdocOpenScanLines); i--) {
       if (fileLines[i].trim().startsWith('/**')) {
         // Extract first non-tag, non-empty line
         for (let j = i + 1; j <= jsdocEnd; j++) {
@@ -60,7 +64,9 @@ export function extractSummary(fileLines, line) {
             .replace(/^\*\s?/, '')
             .trim();
           if (docLine && !docLine.startsWith('@') && docLine !== '/' && docLine !== '*/') {
-            return docLine.length > 100 ? `${docLine.slice(0, 100)}...` : docLine;
+            return docLine.length > summaryMaxChars
+              ? `${docLine.slice(0, summaryMaxChars)}...`
+              : docLine;
           }
         }
         break;
@@ -70,11 +76,14 @@ export function extractSummary(fileLines, line) {
   return null;
 }
 
-export function extractSignature(fileLines, line) {
+export function extractSignature(fileLines, line, opts = {}) {
   if (!fileLines || !line) return null;
   const idx = line - 1;
-  // Gather up to 5 lines to handle multi-line params
-  const chunk = fileLines.slice(idx, Math.min(fileLines.length, idx + 5)).join('\n');
+  const signatureGatherLines = opts.signatureGatherLines ?? 5;
+  // Gather lines to handle multi-line params
+  const chunk = fileLines
+    .slice(idx, Math.min(fileLines.length, idx + signatureGatherLines))
+    .join('\n');
 
   // JS/TS: function name(params) or (params) => or async function
   let m = chunk.match(

package/src/shared/kinds.js

@@ -47,4 +47,17 @@ export const STRUCTURAL_EDGE_KINDS = ['parameter_of', 'receiver'];
 // Full set for MCP enum and validation
 export const EVERY_EDGE_KIND = [...CORE_EDGE_KINDS, ...STRUCTURAL_EDGE_KINDS];
 
-export const VALID_ROLES = ['entry', 'core', 'utility', 'adapter', 'dead', 'test-only', 'leaf'];
+// Dead sub-categories — refine the coarse "dead" bucket
+export const DEAD_ROLE_PREFIX = 'dead';
+export const DEAD_SUB_ROLES = ['dead-leaf', 'dead-entry', 'dead-ffi', 'dead-unresolved'];
+
+export const VALID_ROLES = [
+  'entry',
+  'core',
+  'utility',
+  'adapter',
+  'dead',
+  'test-only',
+  'leaf',
+  ...DEAD_SUB_ROLES,
+];

package/src/shared/paginate.js

@@ -7,13 +7,11 @@
 
 /** Default limits applied by MCP tool handlers (not by the programmatic API). */
 export const MCP_DEFAULTS = {
-  // Existing
   list_functions: 100,
   query: 10,
   where: 50,
   node_roles: 100,
   export_graph: 500,
-  // Smaller defaults for rich/nested results
   fn_impact: 5,
   context: 5,
   explain: 10,
@@ -33,6 +31,16 @@ export const MCP_DEFAULTS = {
   ast_query: 50,
 };
 
+/**
+ * Get MCP page-size defaults, optionally merged with config overrides.
+ * @param {object} [configDefaults] - Override map from config.mcp.defaults
+ * @returns {object}
+ */
+export function getMcpDefaults(configDefaults) {
+  if (!configDefaults) return MCP_DEFAULTS;
+  return { ...MCP_DEFAULTS, ...configDefaults };
+}
+
 /** Hard cap to prevent abuse via MCP. */
 export const MCP_MAX_LIMIT = 1000;