@optave/codegraph 2.1.0 → 2.1.1-dev.0e15f12

package/src/db.js

@@ -67,6 +67,10 @@ export const MIGRATIONS = [
       );
     `,
   },
+  {
+    version: 4,
+    up: `ALTER TABLE file_hashes ADD COLUMN size INTEGER DEFAULT 0;`,
+  },
 ];
 
 export function openDb(dbPath) {

package/src/extractors/csharp.js

@@ -186,7 +186,12 @@ export function extractCSharpSymbols(tree, _filePath) {
             calls.push({ name: fn.text, line: node.startPosition.row + 1 });
           } else if (fn.type === 'member_access_expression') {
             const name = fn.childForFieldName('name');
-            if (name) calls.push({ name: name.text, line: node.startPosition.row + 1 });
+            if (name) {
+              const expr = fn.childForFieldName('expression');
+              const call = { name: name.text, line: node.startPosition.row + 1 };
+              if (expr) call.receiver = expr.text;
+              calls.push(call);
+            }
           } else if (fn.type === 'generic_name' || fn.type === 'member_binding_expression') {
             const name = fn.childForFieldName('name') || fn.child(0);
             if (name) calls.push({ name: name.text, line: node.startPosition.row + 1 });

package/src/extractors/go.js

@@ -152,7 +152,12 @@ export function extractGoSymbols(tree, _filePath) {
             calls.push({ name: fn.text, line: node.startPosition.row + 1 });
           } else if (fn.type === 'selector_expression') {
             const field = fn.childForFieldName('field');
-            if (field) calls.push({ name: field.text, line: node.startPosition.row + 1 });
+            if (field) {
+              const operand = fn.childForFieldName('operand');
+              const call = { name: field.text, line: node.startPosition.row + 1 };
+              if (operand) call.receiver = operand.text;
+              calls.push(call);
+            }
           }
         }
         break;

package/src/extractors/java.js

@@ -203,7 +203,10 @@ export function extractJavaSymbols(tree, _filePath) {
       case 'method_invocation': {
         const nameNode = node.childForFieldName('name');
         if (nameNode) {
-          calls.push({ name: nameNode.text, line: node.startPosition.row + 1 });
+          const obj = node.childForFieldName('object');
+          const call = { name: nameNode.text, line: node.startPosition.row + 1 };
+          if (obj) call.receiver = obj.text;
+          calls.push(call);
         }
         break;
       }

package/src/extractors/javascript.js

@@ -140,6 +140,8 @@ export function extractSymbols(tree, _filePath) {
             calls.push(callInfo);
           }
         }
+        const cbDef = extractCallbackDefinition(node);
+        if (cbDef) definitions.push(cbDef);
         break;
       }
 
@@ -313,6 +315,18 @@ function extractImplementsFromNode(node) {
   return result;
 }
 
+function extractReceiverName(objNode) {
+  if (!objNode) return undefined;
+  if (objNode.type === 'identifier') return objNode.text;
+  if (objNode.type === 'this') return 'this';
+  if (objNode.type === 'super') return 'super';
+  if (objNode.type === 'member_expression') {
+    const prop = objNode.childForFieldName('property');
+    if (prop) return objNode.text;
+  }
+  return objNode.text;
+}
+
 function extractCallInfo(fn, callNode) {
   if (fn.type === 'identifier') {
     return { name: fn.text, line: callNode.startPosition.row + 1 };
@@ -335,21 +349,147 @@ function extractCallInfo(fn, callNode) {
 
     if (prop.type === 'string' || prop.type === 'string_fragment') {
       const methodName = prop.text.replace(/['"]/g, '');
-      if (methodName)
-        return { name: methodName, line: callNode.startPosition.row + 1, dynamic: true };
+      if (methodName) {
+        const receiver = extractReceiverName(obj);
+        return { name: methodName, line: callNode.startPosition.row + 1, dynamic: true, receiver };
+      }
     }
 
-    return { name: prop.text, line: callNode.startPosition.row + 1 };
+    const receiver = extractReceiverName(obj);
+    return { name: prop.text, line: callNode.startPosition.row + 1, receiver };
   }
 
   if (fn.type === 'subscript_expression') {
+    const obj = fn.childForFieldName('object');
     const index = fn.childForFieldName('index');
     if (index && (index.type === 'string' || index.type === 'template_string')) {
       const methodName = index.text.replace(/['"`]/g, '');
-      if (methodName && !methodName.includes('$'))
-        return { name: methodName, line: callNode.startPosition.row + 1, dynamic: true };
+      if (methodName && !methodName.includes('$')) {
+        const receiver = extractReceiverName(obj);
+        return { name: methodName, line: callNode.startPosition.row + 1, dynamic: true, receiver };
+      }
+    }
+  }
+
+  return null;
+}
+
+function findAnonymousCallback(argsNode) {
+  for (let i = 0; i < argsNode.childCount; i++) {
+    const child = argsNode.child(i);
+    if (child && (child.type === 'arrow_function' || child.type === 'function_expression')) {
+      return child;
+    }
+  }
+  return null;
+}
+
+function findFirstStringArg(argsNode) {
+  for (let i = 0; i < argsNode.childCount; i++) {
+    const child = argsNode.child(i);
+    if (child && child.type === 'string') {
+      return child.text.replace(/['"]/g, '');
     }
   }
+  return null;
+}
+
+function walkCallChain(startNode, methodName) {
+  let current = startNode;
+  while (current) {
+    if (current.type === 'call_expression') {
+      const fn = current.childForFieldName('function');
+      if (fn && fn.type === 'member_expression') {
+        const prop = fn.childForFieldName('property');
+        if (prop && prop.text === methodName) {
+          return current;
+        }
+      }
+    }
+    if (current.type === 'member_expression') {
+      const obj = current.childForFieldName('object');
+      current = obj;
+    } else if (current.type === 'call_expression') {
+      const fn = current.childForFieldName('function');
+      current = fn;
+    } else {
+      break;
+    }
+  }
+  return null;
+}
+
+const EXPRESS_METHODS = new Set([
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+  'all',
+  'use',
+]);
+const EVENT_METHODS = new Set(['on', 'once', 'addEventListener', 'addListener']);
+
+function extractCallbackDefinition(callNode) {
+  const fn = callNode.childForFieldName('function');
+  if (!fn || fn.type !== 'member_expression') return null;
+
+  const prop = fn.childForFieldName('property');
+  if (!prop) return null;
+  const method = prop.text;
+
+  const args = callNode.childForFieldName('arguments') || findChild(callNode, 'arguments');
+  if (!args) return null;
+
+  // Commander: .action(callback) with .command('name') in chain
+  if (method === 'action') {
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    const commandCall = walkCallChain(fn.childForFieldName('object'), 'command');
+    if (!commandCall) return null;
+    const cmdArgs =
+      commandCall.childForFieldName('arguments') || findChild(commandCall, 'arguments');
+    if (!cmdArgs) return null;
+    const cmdName = findFirstStringArg(cmdArgs);
+    if (!cmdName) return null;
+    const firstWord = cmdName.split(/\s/)[0];
+    return {
+      name: `command:${firstWord}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
+
+  // Express: app.get('/path', callback)
+  if (EXPRESS_METHODS.has(method)) {
+    const strArg = findFirstStringArg(args);
+    if (!strArg || !strArg.startsWith('/')) return null;
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    return {
+      name: `route:${method.toUpperCase()} ${strArg}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
+
+  // Events: emitter.on('event', callback)
+  if (EVENT_METHODS.has(method)) {
+    const eventName = findFirstStringArg(args);
+    if (!eventName) return null;
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    return {
+      name: `event:${eventName}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
 
   return null;
 }

package/src/extractors/php.js

@@ -206,7 +206,10 @@ export function extractPHPSymbols(tree, _filePath) {
       case 'member_call_expression': {
         const name = node.childForFieldName('name');
         if (name) {
-          calls.push({ name: name.text, line: node.startPosition.row + 1 });
+          const obj = node.childForFieldName('object');
+          const call = { name: name.text, line: node.startPosition.row + 1 };
+          if (obj) call.receiver = obj.text;
+          calls.push(call);
         }
         break;
       }
@@ -214,7 +217,10 @@ export function extractPHPSymbols(tree, _filePath) {
       case 'scoped_call_expression': {
         const name = node.childForFieldName('name');
         if (name) {
-          calls.push({ name: name.text, line: node.startPosition.row + 1 });
+          const scope = node.childForFieldName('scope');
+          const call = { name: name.text, line: node.startPosition.row + 1 };
+          if (scope) call.receiver = scope.text;
+          calls.push(call);
         }
         break;
       }

package/src/extractors/python.js

@@ -69,12 +69,19 @@ export function extractPythonSymbols(tree, _filePath) {
         const fn = node.childForFieldName('function');
         if (fn) {
           let callName = null;
+          let receiver;
           if (fn.type === 'identifier') callName = fn.text;
           else if (fn.type === 'attribute') {
             const attr = fn.childForFieldName('attribute');
             if (attr) callName = attr.text;
+            const obj = fn.childForFieldName('object');
+            if (obj) receiver = obj.text;
+          }
+          if (callName) {
+            const call = { name: callName, line: node.startPosition.row + 1 };
+            if (receiver) call.receiver = receiver;
+            calls.push(call);
           }
-          if (callName) calls.push({ name: callName, line: node.startPosition.row + 1 });
         }
         break;
       }

package/src/extractors/ruby.js

@@ -170,7 +170,10 @@ export function extractRubySymbols(tree, _filePath) {
               }
             }
           } else {
-            calls.push({ name: methodNode.text, line: node.startPosition.row + 1 });
+            const recv = node.childForFieldName('receiver');
+            const call = { name: methodNode.text, line: node.startPosition.row + 1 };
+            if (recv) call.receiver = recv.text;
+            calls.push(call);
           }
         }
         break;

package/src/extractors/rust.js

@@ -135,10 +135,20 @@ export function extractRustSymbols(tree, _filePath) {
             calls.push({ name: fn.text, line: node.startPosition.row + 1 });
           } else if (fn.type === 'field_expression') {
             const field = fn.childForFieldName('field');
-            if (field) calls.push({ name: field.text, line: node.startPosition.row + 1 });
+            if (field) {
+              const value = fn.childForFieldName('value');
+              const call = { name: field.text, line: node.startPosition.row + 1 };
+              if (value) call.receiver = value.text;
+              calls.push(call);
+            }
           } else if (fn.type === 'scoped_identifier') {
             const name = fn.childForFieldName('name');
-            if (name) calls.push({ name: name.text, line: node.startPosition.row + 1 });
+            if (name) {
+              const path = fn.childForFieldName('path');
+              const call = { name: name.text, line: node.startPosition.row + 1 };
+              if (path) call.receiver = path.text;
+              calls.push(call);
+            }
           }
         }
         break;

package/src/index.js

@@ -38,7 +38,12 @@ export { isNativeAvailable } from './native.js';
 export { getActiveEngine, parseFileAuto, parseFilesAuto } from './parser.js';
 // Query functions (data-returning)
 export {
+  ALL_SYMBOL_KINDS,
+  contextData,
   diffImpactData,
+  explainData,
+  FALSE_POSITIVE_CALLER_THRESHOLD,
+  FALSE_POSITIVE_NAMES,
   fileDepsData,
   fnDepsData,
   fnImpactData,
@@ -46,6 +51,7 @@ export {
   moduleMapData,
   queryNameData,
   statsData,
+  whereData,
 } from './queries.js';
 // Registry (multi-repo)
 export {

package/src/journal.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { debug, warn } from './logger.js';
+
+export const JOURNAL_FILENAME = 'changes.journal';
+const HEADER_PREFIX = '# codegraph-journal v1 ';
+
+/**
+ * Read and validate the change journal.
+ * Returns { valid, timestamp, changed[], removed[] } or { valid: false }.
+ */
+export function readJournal(rootDir) {
+  const journalPath = path.join(rootDir, '.codegraph', JOURNAL_FILENAME);
+  let content;
+  try {
+    content = fs.readFileSync(journalPath, 'utf-8');
+  } catch {
+    return { valid: false };
+  }
+
+  const lines = content.split('\n');
+  if (lines.length === 0 || !lines[0].startsWith(HEADER_PREFIX)) {
+    debug('Journal has malformed or missing header');
+    return { valid: false };
+  }
+
+  const timestamp = Number(lines[0].slice(HEADER_PREFIX.length).trim());
+  if (!Number.isFinite(timestamp) || timestamp <= 0) {
+    debug('Journal has invalid timestamp');
+    return { valid: false };
+  }
+
+  const changed = [];
+  const removed = [];
+  const seenChanged = new Set();
+  const seenRemoved = new Set();
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#')) continue;
+
+    if (line.startsWith('DELETED ')) {
+      const filePath = line.slice(8);
+      if (filePath && !seenRemoved.has(filePath)) {
+        seenRemoved.add(filePath);
+        removed.push(filePath);
+      }
+    } else {
+      if (!seenChanged.has(line)) {
+        seenChanged.add(line);
+        changed.push(line);
+      }
+    }
+  }
+
+  return { valid: true, timestamp, changed, removed };
+}
+
+/**
+ * Append changed/deleted paths to the journal.
+ * Creates the journal with a header if it doesn't exist.
+ */
+export function appendJournalEntries(rootDir, entries) {
+  const dir = path.join(rootDir, '.codegraph');
+  const journalPath = path.join(dir, JOURNAL_FILENAME);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // If journal doesn't exist, create with a placeholder header
+  if (!fs.existsSync(journalPath)) {
+    fs.writeFileSync(journalPath, `${HEADER_PREFIX}0\n`);
+  }
+
+  const lines = entries.map((e) => {
+    if (e.deleted) return `DELETED ${e.file}`;
+    return e.file;
+  });
+
+  fs.appendFileSync(journalPath, `${lines.join('\n')}\n`);
+}
+
+/**
+ * Write a fresh journal header after a successful build.
+ * Atomic: write to temp file then rename.
+ */
+export function writeJournalHeader(rootDir, timestamp) {
+  const dir = path.join(rootDir, '.codegraph');
+  const journalPath = path.join(dir, JOURNAL_FILENAME);
+  const tmpPath = `${journalPath}.tmp`;
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  try {
+    fs.writeFileSync(tmpPath, `${HEADER_PREFIX}${timestamp}\n`);
+    fs.renameSync(tmpPath, journalPath);
+  } catch (err) {
+    warn(`Failed to write journal header: ${err.message}`);
+    // Clean up temp file if rename failed
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/mcp.js

@@ -8,6 +8,7 @@
 import { createRequire } from 'node:module';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
+import { ALL_SYMBOL_KINDS } from './queries.js';
 
 const REPO_PROP = {
   repo: {
@@ -81,6 +82,15 @@ const BASE_TOOLS = [
       properties: {
         name: { type: 'string', description: 'Function/method/class name (partial match)' },
         depth: { type: 'number', description: 'Transitive caller depth', default: 3 },
+        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'],
@@ -95,11 +105,88 @@ const BASE_TOOLS = [
       properties: {
         name: { type: 'string', description: 'Function/method/class name (partial match)' },
         depth: { type: 'number', description: 'Max traversal depth', default: 5 },
+        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: 'context',
+    description:
+      'Full context for a function: source code, dependencies with summaries, callers, signature, and related tests — everything needed to understand or modify a function in one call',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Function/method/class name (partial match)' },
+        depth: {
+          type: 'number',
+          description: 'Include callee source up to N levels deep (0=no source, 1=direct)',
+          default: 0,
+        },
+        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_source: {
+          type: 'boolean',
+          description: 'Skip source extraction (metadata only)',
+          default: false,
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+        include_tests: {
+          type: 'boolean',
+          description: 'Include test file source code',
+          default: false,
+        },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'explain',
+    description:
+      'Structural summary of a file or function: public/internal API, data flow, dependencies. No LLM needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'File path or function name' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'where',
+    description:
+      'Find where a symbol is defined and used, or list symbols/imports/exports for a file. Minimal, fast lookup.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'Symbol name or file path' },
+        file_mode: {
+          type: 'boolean',
+          description: 'Treat target as file path (list symbols/imports/exports)',
+          default: false,
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['target'],
+    },
+  },
   {
     name: 'diff_impact',
     description: 'Analyze git diff to find which functions changed and their transitive callers',
@@ -245,12 +332,15 @@ export { TOOLS, buildToolList };
 export async function startMCPServer(customDbPath, options = {}) {
   const { allowedRepos } = options;
   const multiRepo = options.multiRepo || !!allowedRepos;
-  let Server, StdioServerTransport;
+  let Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema;
   try {
     const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
     Server = sdk.Server;
     const transport = await import('@modelcontextprotocol/sdk/server/stdio.js');
     StdioServerTransport = transport.StdioServerTransport;
+    const types = await import('@modelcontextprotocol/sdk/types.js');
+    ListToolsRequestSchema = types.ListToolsRequestSchema;
+    CallToolRequestSchema = types.CallToolRequestSchema;
   } catch {
     console.error(
       'MCP server requires @modelcontextprotocol/sdk.\n' +
@@ -267,6 +357,9 @@ export async function startMCPServer(customDbPath, options = {}) {
     fileDepsData,
     fnDepsData,
     fnImpactData,
+    contextData,
+    explainData,
+    whereData,
     diffImpactData,
     listFunctionsData,
   } = await import('./queries.js');
@@ -279,9 +372,11 @@ export async function startMCPServer(customDbPath, options = {}) {
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler('tools/list', async () => ({ tools: buildToolList(multiRepo) }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: buildToolList(multiRepo),
+  }));
 
-  server.setRequestHandler('tools/call', async (request) => {
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
 
     try {
@@ -334,12 +429,35 @@ export async function startMCPServer(customDbPath, options = {}) {
         case 'fn_deps':
           result = fnDepsData(args.name, dbPath, {
             depth: args.depth,
+            file: args.file,
+            kind: args.kind,
             noTests: args.no_tests,
           });
           break;
         case 'fn_impact':
           result = fnImpactData(args.name, dbPath, {
             depth: args.depth,
+            file: args.file,
+            kind: args.kind,
+            noTests: args.no_tests,
+          });
+          break;
+        case 'context':
+          result = contextData(args.name, dbPath, {
+            depth: args.depth,
+            file: args.file,
+            kind: args.kind,
+            noSource: args.no_source,
+            noTests: args.no_tests,
+            includeTests: args.include_tests,
+          });
+          break;
+        case 'explain':
+          result = explainData(args.target, dbPath, { noTests: args.no_tests });
+          break;
+        case 'where':
+          result = whereData(args.target, dbPath, {
+            file: args.file_mode,
             noTests: args.no_tests,
           });
           break;

package/src/parser.js

@@ -101,6 +101,7 @@ function normalizeNativeSymbols(result) {
       name: c.name,
       line: c.line,
       dynamic: c.dynamic,
+      receiver: c.receiver,
     })),
     imports: (result.imports || []).map((i) => ({
       source: i.source,