@optave/codegraph 2.4.0 → 2.5.0

package/src/mcp.js

@@ -8,6 +8,7 @@
 import { createRequire } from 'node:module';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
+import { MCP_DEFAULTS, MCP_MAX_LIMIT } from './paginate.js';
 import { ALL_SYMBOL_KINDS, diffImpactMermaid, VALID_ROLES } from './queries.js';
 
 const REPO_PROP = {
@@ -17,6 +18,11 @@ const REPO_PROP = {
   },
 };
 
+const PAGINATION_PROPS = {
+  limit: { type: 'number', description: 'Max results to return (pagination)' },
+  offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
+};
+
 const BASE_TOOLS = [
   {
     name: 'query_function',
@@ -31,6 +37,7 @@ const BASE_TOOLS = [
           default: 2,
         },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
       required: ['name'],
     },
@@ -123,6 +130,33 @@ const BASE_TOOLS = [
       required: ['name'],
     },
   },
+  {
+    name: 'symbol_path',
+    description: 'Find the shortest path between two symbols in the call graph (A calls...calls B)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Source symbol name (partial match)' },
+        to: { type: 'string', description: 'Target symbol name (partial match)' },
+        max_depth: { type: 'number', description: 'Maximum BFS depth', default: 10 },
+        edge_kinds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Edge kinds to follow (default: ["calls"])',
+        },
+        reverse: { type: 'boolean', description: 'Follow edges backward', default: false },
+        from_file: { type: 'string', description: 'Disambiguate source by file (partial match)' },
+        to_file: { type: 'string', description: 'Disambiguate target by file (partial match)' },
+        kind: {
+          type: 'string',
+          enum: ALL_SYMBOL_KINDS,
+          description: 'Filter both symbols by kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['from', 'to'],
+    },
+  },
   {
     name: 'context',
     description:
@@ -187,6 +221,7 @@ const BASE_TOOLS = [
           default: false,
         },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
       required: ['target'],
     },
@@ -239,6 +274,7 @@ const BASE_TOOLS = [
           description: 'File-level graph (true) or function-level (false)',
           default: true,
         },
+        ...PAGINATION_PROPS,
       },
       required: ['format'],
     },
@@ -253,13 +289,14 @@ const BASE_TOOLS = [
         file: { type: 'string', description: 'Filter by file path (partial match)' },
         pattern: { type: 'string', description: 'Filter by function name (partial match)' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
     },
   },
   {
     name: 'structure',
     description:
-      'Show project structure with directory hierarchy, cohesion scores, and per-file metrics',
+      'Show project structure with directory hierarchy, cohesion scores, and per-file metrics. Per-file details are capped at 25 files by default; use full=true to show all.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -270,6 +307,11 @@ const BASE_TOOLS = [
           enum: ['cohesion', 'fan-in', 'fan-out', 'density', 'files'],
           description: 'Sort directories by metric',
         },
+        full: {
+          type: 'boolean',
+          description: 'Return all files without limit',
+          default: false,
+        },
       },
     },
   },
@@ -287,6 +329,7 @@ const BASE_TOOLS = [
         },
         file: { type: 'string', description: 'Scope to a specific file (partial match)' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
       },
     },
   },
@@ -333,6 +376,121 @@ const BASE_TOOLS = [
       },
     },
   },
+  {
+    name: 'execution_flow',
+    description:
+      'Trace execution flow forward from an entry point (route, command, event) through callees to leaf functions. Answers "what happens when X is called?"',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description:
+            'Entry point or function name (e.g. "POST /login", "build"). Supports prefix-stripped matching.',
+        },
+        depth: { type: 'number', description: 'Max forward traversal depth', default: 10 },
+        file: {
+          type: 'string',
+          description: 'Scope search to functions in this file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: ALL_SYMBOL_KINDS,
+          description: 'Filter to a specific symbol kind',
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'list_entry_points',
+    description:
+      'List all framework entry points (routes, commands, events) in the codebase, grouped by type',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        ...PAGINATION_PROPS,
+      },
+    },
+  },
+  {
+    name: 'complexity',
+    description:
+      'Show per-function complexity metrics (cognitive, cyclomatic, nesting, Halstead, Maintainability Index). Sorted by most complex first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Function name filter (partial match)' },
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        limit: { type: 'number', description: 'Max results', default: 20 },
+        sort: {
+          type: 'string',
+          enum: ['cognitive', 'cyclomatic', 'nesting', 'mi', 'volume', 'effort', 'bugs', 'loc'],
+          description: 'Sort metric',
+          default: 'cognitive',
+        },
+        above_threshold: {
+          type: 'boolean',
+          description: 'Only functions exceeding warn thresholds',
+          default: false,
+        },
+        health: {
+          type: 'boolean',
+          description: 'Include Halstead and Maintainability Index metrics',
+          default: false,
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        kind: {
+          type: 'string',
+          description: 'Filter by symbol kind (function, method, class, etc.)',
+        },
+      },
+    },
+  },
+  {
+    name: 'manifesto',
+    description:
+      'Evaluate manifesto rules and return pass/fail verdicts for code health. Checks function complexity, file metrics, and cycle rules against configured thresholds.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Scope to file (partial match)' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        kind: {
+          type: 'string',
+          description: 'Filter by symbol kind (function, method, class, etc.)',
+        },
+      },
+    },
+  },
+  {
+    name: 'communities',
+    description:
+      'Detect natural module boundaries using Louvain community detection. Compares discovered communities against directory structure and surfaces architectural drift.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        functions: {
+          type: 'boolean',
+          description: 'Function-level instead of file-level',
+          default: false,
+        },
+        resolution: {
+          type: 'number',
+          description: 'Louvain resolution parameter (higher = more communities)',
+          default: 1.0,
+        },
+        drift: {
+          type: 'boolean',
+          description: 'Show only drift analysis (omit community member lists)',
+          default: false,
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+    },
+  },
 ];
 
 const LIST_REPOS_TOOL = {
@@ -405,6 +563,7 @@ export async function startMCPServer(customDbPath, options = {}) {
     fileDepsData,
     fnDepsData,
     fnImpactData,
+    pathData,
     contextData,
     explainData,
     whereData,
@@ -457,7 +616,11 @@ export async function startMCPServer(customDbPath, options = {}) {
       let result;
       switch (name) {
         case 'query_function':
-          result = queryNameData(args.name, dbPath, { noTests: args.no_tests });
+          result = queryNameData(args.name, dbPath, {
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.query_function, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
           break;
         case 'file_deps':
           result = fileDepsData(args.file, dbPath, { noTests: args.no_tests });
@@ -491,6 +654,17 @@ export async function startMCPServer(customDbPath, options = {}) {
             noTests: args.no_tests,
           });
           break;
+        case 'symbol_path':
+          result = pathData(args.from, args.to, dbPath, {
+            maxDepth: args.max_depth,
+            edgeKinds: args.edge_kinds,
+            reverse: args.reverse,
+            fromFile: args.from_file,
+            toFile: args.to_file,
+            kind: args.kind,
+            noTests: args.no_tests,
+          });
+          break;
         case 'context':
           result = contextData(args.name, dbPath, {
             depth: args.depth,
@@ -508,6 +682,8 @@ export async function startMCPServer(customDbPath, options = {}) {
           result = whereData(args.target, dbPath, {
             file: args.file_mode,
             noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.where, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         case 'diff_impact':
@@ -547,15 +723,21 @@ export async function startMCPServer(customDbPath, options = {}) {
           const { exportDOT, exportMermaid, exportJSON } = await import('./export.js');
           const db = new Database(findDbPath(dbPath), { readonly: true });
           const fileLevel = args.file_level !== false;
+          const exportLimit = args.limit
+            ? Math.min(args.limit, MCP_MAX_LIMIT)
+            : MCP_DEFAULTS.export_graph;
           switch (args.format) {
             case 'dot':
-              result = exportDOT(db, { fileLevel });
+              result = exportDOT(db, { fileLevel, limit: exportLimit });
               break;
             case 'mermaid':
-              result = exportMermaid(db, { fileLevel });
+              result = exportMermaid(db, { fileLevel, limit: exportLimit });
               break;
             case 'json':
-              result = exportJSON(db);
+              result = exportJSON(db, {
+                limit: exportLimit,
+                offset: args.offset ?? 0,
+              });
               break;
             default:
               db.close();
@@ -577,6 +759,8 @@ export async function startMCPServer(customDbPath, options = {}) {
             file: args.file,
             pattern: args.pattern,
             noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.list_functions, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         case 'node_roles':
@@ -584,6 +768,8 @@ export async function startMCPServer(customDbPath, options = {}) {
             role: args.role,
             file: args.file,
             noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.node_roles, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
           });
           break;
         case 'structure': {
@@ -592,6 +778,7 @@ export async function startMCPServer(customDbPath, options = {}) {
             directory: args.directory,
             depth: args.depth,
             sort: args.sort,
+            full: args.full,
           });
           break;
         }
@@ -620,6 +807,58 @@ export async function startMCPServer(customDbPath, options = {}) {
               });
           break;
         }
+        case 'execution_flow': {
+          const { flowData } = await import('./flow.js');
+          result = flowData(args.name, dbPath, {
+            depth: args.depth,
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+          });
+          break;
+        }
+        case 'list_entry_points': {
+          const { listEntryPointsData } = await import('./flow.js');
+          result = listEntryPointsData(dbPath, {
+            noTests: args.no_tests,
+            limit: Math.min(args.limit ?? MCP_DEFAULTS.list_entry_points, MCP_MAX_LIMIT),
+            offset: args.offset ?? 0,
+          });
+          break;
+        }
+        case 'complexity': {
+          const { complexityData } = await import('./complexity.js');
+          result = complexityData(dbPath, {
+            target: args.name,
+            file: args.file,
+            limit: args.limit,
+            sort: args.sort,
+            aboveThreshold: args.above_threshold,
+            health: args.health,
+            noTests: args.no_tests,
+            kind: args.kind,
+          });
+          break;
+        }
+        case 'manifesto': {
+          const { manifestoData } = await import('./manifesto.js');
+          result = manifestoData(dbPath, {
+            file: args.file,
+            noTests: args.no_tests,
+            kind: args.kind,
+          });
+          break;
+        }
+        case 'communities': {
+          const { communitiesData } = await import('./communities.js');
+          result = communitiesData(dbPath, {
+            functions: args.functions,
+            resolution: args.resolution,
+            drift: args.drift,
+            noTests: args.no_tests,
+          });
+          break;
+        }
         case 'list_repos': {
           const { listRepos, pruneRegistry } = await import('./registry.js');
           pruneRegistry();

package/src/paginate.js

@@ -0,0 +1,70 @@
+/**
+ * Pagination utilities for bounded, context-friendly query results.
+ *
+ * Offset/limit pagination — the DB is a read-only snapshot so data doesn't
+ * change between pages; offset/limit is simpler and maps directly to SQL.
+ */
+
+/** Default limits applied by MCP tool handlers (not by the programmatic API). */
+export const MCP_DEFAULTS = {
+  list_functions: 100,
+  query_function: 50,
+  where: 50,
+  node_roles: 100,
+  list_entry_points: 100,
+  export_graph: 500,
+};
+
+/** Hard cap to prevent abuse via MCP. */
+export const MCP_MAX_LIMIT = 1000;
+
+/**
+ * Paginate an array.
+ *
+ * When `limit` is undefined the input is returned unchanged (no-op).
+ *
+ * @param {any[]} items
+ * @param {{ limit?: number, offset?: number }} opts
+ * @returns {{ items: any[], pagination?: { total: number, offset: number, limit: number, hasMore: boolean, returned: number } }}
+ */
+export function paginate(items, { limit, offset } = {}) {
+  if (limit === undefined) {
+    return { items };
+  }
+  const total = items.length;
+  const off = Math.max(0, Math.min(offset || 0, total));
+  const lim = Math.max(0, limit);
+  const page = items.slice(off, off + lim);
+  return {
+    items: page,
+    pagination: {
+      total,
+      offset: off,
+      limit: lim,
+      hasMore: off + lim < total,
+      returned: page.length,
+    },
+  };
+}
+
+/**
+ * Apply pagination to a named array field on a result object.
+ *
+ * When `limit` is undefined the result is returned unchanged (backward compat).
+ * When active, `_pagination` metadata is added to the result.
+ *
+ * @param {object} result - The result object (e.g. `{ count: 42, functions: [...] }`)
+ * @param {string} field  - The array field name to paginate (e.g. `'functions'`)
+ * @param {{ limit?: number, offset?: number }} opts
+ * @returns {object} - Result with paginated field + `_pagination` (if active)
+ */
+export function paginateResult(result, field, { limit, offset } = {}) {
+  if (limit === undefined) {
+    return result;
+  }
+  const arr = result[field];
+  if (!Array.isArray(arr)) return result;
+
+  const { items, pagination } = paginate(arr, { limit, offset });
+  return { ...result, [field]: items, _pagination: pagination };
+}

package/src/parser.js

@@ -125,12 +125,23 @@ function resolveEngine(opts = {}) {
  */
 function normalizeNativeSymbols(result) {
   return {
+    _lineCount: result.lineCount ?? result.line_count ?? null,
     definitions: (result.definitions || []).map((d) => ({
       name: d.name,
       kind: d.kind,
       line: d.line,
       endLine: d.endLine ?? d.end_line ?? null,
       decorators: d.decorators,
+      complexity: d.complexity
+        ? {
+            cognitive: d.complexity.cognitive,
+            cyclomatic: d.complexity.cyclomatic,
+            maxNesting: d.complexity.maxNesting,
+            halstead: d.complexity.halstead ?? null,
+            loc: d.complexity.loc ?? null,
+            maintainabilityIndex: d.complexity.maintainabilityIndex ?? null,
+          }
+        : null,
     })),
     calls: (result.calls || []).map((c) => ({
       name: c.name,
@@ -279,7 +290,8 @@ function wasmExtractSymbols(parsers, filePath, code) {
   const entry = _extToLang.get(ext);
   if (!entry) return null;
   const query = _queryCache.get(entry.id) || null;
-  return entry.extractor(tree, filePath, query);
+  const symbols = entry.extractor(tree, filePath, query);
+  return symbols ? { symbols, tree, langId: entry.id } : null;
 }
 
 /**
@@ -300,7 +312,8 @@ export async function parseFileAuto(filePath, source, opts = {}) {
 
   // WASM path
   const parsers = await createParsers();
-  return wasmExtractSymbols(parsers, filePath, source);
+  const extracted = wasmExtractSymbols(parsers, filePath, source);
+  return extracted ? extracted.symbols : null;
 }
 
 /**
@@ -335,10 +348,13 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
       warn(`Skipping ${path.relative(rootDir, filePath)}: ${err.message}`);
       continue;
     }
-    const symbols = wasmExtractSymbols(parsers, filePath, code);
-    if (symbols) {
+    const extracted = wasmExtractSymbols(parsers, filePath, code);
+    if (extracted) {
       const relPath = path.relative(rootDir, filePath).split(path.sep).join('/');
-      result.set(relPath, symbols);
+      extracted.symbols._tree = extracted.tree;
+      extracted.symbols._langId = extracted.langId;
+      extracted.symbols._lineCount = code.split('\n').length;
+      result.set(relPath, extracted.symbols);
     }
   }
   return result;