@optave/codegraph 3.3.1 → 3.4.1

package/src/mcp/{tool-registry.js → tool-registry.ts}

@@ -7,19 +7,29 @@
 import { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND, VALID_ROLES } from '../domain/queries.js';
 import { AST_NODE_KINDS } from '../features/ast.js';
 
-const REPO_PROP = {
+interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+const REPO_PROP: Record<string, unknown> = {
   repo: {
     type: 'string',
     description: 'Repository name from the registry (omit for local project)',
   },
 };
 
-const PAGINATION_PROPS = {
+const PAGINATION_PROPS: Record<string, unknown> = {
   limit: { type: 'number', description: 'Max results to return (pagination)' },
   offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
 };
 
-const BASE_TOOLS = [
+const BASE_TOOLS: ToolSchema[] = [
   {
     name: 'query',
     description:
@@ -67,20 +77,27 @@ const BASE_TOOLS = [
   },
   {
     name: 'path',
-    description: 'Find shortest path between two symbols in the dependency graph',
+    description:
+      'Find shortest path between two symbols (or files with file_mode) in the dependency graph',
     inputSchema: {
       type: 'object',
       properties: {
-        from: { type: 'string', description: 'Source symbol name' },
-        to: { type: 'string', description: 'Target symbol name' },
+        from: { type: 'string', description: 'Source symbol name (or file path with file_mode)' },
+        to: { type: 'string', description: 'Target symbol name (or file path with file_mode)' },
         depth: { type: 'number', description: 'Max traversal depth (default: 10)' },
         edge_kinds: {
           type: 'array',
           items: { type: 'string', enum: EVERY_EDGE_KIND },
-          description: 'Edge kinds to follow (default: ["calls"])',
+          description:
+            'Edge kinds to follow (default: ["calls"] for symbols, ["imports","imports-type"] for files)',
         },
         from_file: { type: 'string', description: 'Disambiguate source by file' },
         to_file: { type: 'string', description: 'Disambiguate target by file' },
+        file_mode: {
+          type: 'boolean',
+          description: 'Treat from/to as file paths and find file-to-file shortest path',
+          default: false,
+        },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['from', 'to'],
@@ -139,7 +156,6 @@ const BASE_TOOLS = [
       properties: {
         file: { type: 'string', description: 'File path to analyze' },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
-        ...PAGINATION_PROPS,
       },
       required: ['file'],
     },
@@ -821,7 +837,7 @@ const BASE_TOOLS = [
   },
 ];
 
-const LIST_REPOS_TOOL = {
+const LIST_REPOS_TOOL: ToolSchema = {
   name: 'list_repos',
   description: 'List all repositories registered in the codegraph registry',
   inputSchema: {
@@ -832,10 +848,8 @@ const LIST_REPOS_TOOL = {
 
 /**
  * Build the tool list based on multi-repo mode.
- * @param {boolean} multiRepo - If true, inject `repo` prop into each tool and append `list_repos`
- * @returns {object[]}
  */
-export function buildToolList(multiRepo) {
+export function buildToolList(multiRepo: boolean): ToolSchema[] {
   if (!multiRepo) return BASE_TOOLS;
   return [
     ...BASE_TOOLS.map((tool) => ({
@@ -850,4 +864,4 @@ export function buildToolList(multiRepo) {
 }
 
 // Backward-compatible export: full multi-repo tool list
-export const TOOLS = buildToolList(true);
+export const TOOLS: ToolSchema[] = buildToolList(true);

package/src/mcp/tools/{ast-query.js → ast-query.ts}

@@ -1,8 +1,19 @@
+import type { ASTNodeKind } from '../../types.js';
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'ast_query';
 
-export async function handler(args, ctx) {
+interface AstQueryArgs {
+  pattern?: string;
+  kind?: ASTNodeKind;
+  file?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: AstQueryArgs, ctx: McpToolContext): Promise<unknown> {
   const { astQueryData } = await import('../../features/ast.js');
   return astQueryData(args.pattern, ctx.dbPath, {
     kind: args.kind,

package/src/mcp/tools/{audit.js → audit.ts}

@@ -1,13 +1,25 @@
 import { effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'audit';
 
-export async function handler(args, ctx) {
+interface AuditArgs {
+  target: string;
+  quick?: boolean;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: AuditArgs, ctx: McpToolContext): Promise<unknown> {
   if (args.quick) {
     const { explainData } = await ctx.getQueries();
     return explainData(args.target, ctx.dbPath, {
       noTests: args.no_tests,
-      limit: Math.min(args.limit ?? MCP_DEFAULTS.explain, MCP_MAX_LIMIT),
+      limit: Math.min(args.limit ?? MCP_DEFAULTS.explain ?? 100, MCP_MAX_LIMIT),
       offset: effectiveOffset(args),
     });
   }

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

@@ -0,0 +1,22 @@
+import type { McpToolContext } from '../server.js';
+
+export const name = 'batch_query';
+
+interface BatchQueryArgs {
+  command: string;
+  targets: string[];
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+}
+
+export async function handler(args: BatchQueryArgs, ctx: McpToolContext): Promise<unknown> {
+  const { batchData } = await import('../../features/batch.js');
+  return batchData(args.command, args.targets, ctx.dbPath, {
+    depth: args.depth,
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/{branch-compare.js → branch-compare.ts}

@@ -1,6 +1,16 @@
+import type { McpToolContext } from '../server.js';
+
 export const name = 'branch_compare';
 
-export async function handler(args, _ctx) {
+interface BranchCompareArgs {
+  base: string;
+  target: string;
+  depth?: number;
+  no_tests?: boolean;
+  format?: 'json' | 'mermaid';
+}
+
+export async function handler(args: BranchCompareArgs, _ctx: McpToolContext): Promise<unknown> {
   const { branchCompareData, branchCompareMermaid } = await import(
     '../../features/branch-compare.js'
   );

package/src/mcp/tools/brief.ts

@@ -0,0 +1,15 @@
+import type { McpToolContext } from '../server.js';
+
+export const name = 'brief';
+
+interface BriefArgs {
+  file: string;
+  no_tests?: boolean;
+}
+
+export async function handler(args: BriefArgs, ctx: McpToolContext): Promise<unknown> {
+  const { briefData } = await ctx.getQueries();
+  return briefData(args.file, ctx.dbPath, {
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/{cfg.js → cfg.ts}

@@ -1,14 +1,25 @@
 import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'cfg';
 
-export async function handler(args, ctx) {
+interface CfgArgs {
+  name: string;
+  format?: 'json' | 'dot' | 'mermaid';
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: CfgArgs, ctx: McpToolContext): Promise<unknown> {
   const { cfgData, cfgToDOT, cfgToMermaid } = await import('../../features/cfg.js');
   const cfgResult = cfgData(args.name, ctx.dbPath, {
     file: args.file,
     kind: args.kind,
     noTests: args.no_tests,
-    limit: Math.min(args.limit ?? MCP_DEFAULTS.query, ctx.MCP_MAX_LIMIT),
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.query ?? 100, ctx.MCP_MAX_LIMIT),
     offset: effectiveOffset(args),
   });
   if (args.format === 'dot') {

package/src/mcp/tools/{check.js → check.ts}

@@ -1,8 +1,25 @@
 import { effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'check';
 
-export async function handler(args, ctx) {
+interface CheckArgs {
+  ref?: string;
+  staged?: boolean;
+  rules?: boolean;
+  cycles?: boolean;
+  blast_radius?: number;
+  signatures?: boolean;
+  boundaries?: boolean;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: CheckArgs, ctx: McpToolContext): Promise<unknown> {
   const isDiffMode = args.ref || args.staged;
 
   if (!isDiffMode && !args.rules) {
@@ -11,7 +28,7 @@ export async function handler(args, ctx) {
       file: args.file,
       noTests: args.no_tests,
       kind: args.kind,
-      limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto, MCP_MAX_LIMIT),
+      limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto ?? 100, MCP_MAX_LIMIT),
       offset: effectiveOffset(args),
     });
   }
@@ -34,7 +51,7 @@ export async function handler(args, ctx) {
       file: args.file,
       noTests: args.no_tests,
       kind: args.kind,
-      limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto, MCP_MAX_LIMIT),
+      limit: Math.min(args.limit ?? MCP_DEFAULTS.manifesto ?? 100, MCP_MAX_LIMIT),
       offset: effectiveOffset(args),
     });
     return { check: checkResult, manifesto: manifestoResult };

package/src/mcp/tools/{co-changes.js → co-changes.ts}

@@ -1,8 +1,17 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'co_changes';
 
-export async function handler(args, ctx) {
+interface CoChangesArgs {
+  file?: string;
+  limit?: number;
+  offset?: number;
+  min_jaccard?: number;
+  no_tests?: boolean;
+}
+
+export async function handler(args: CoChangesArgs, ctx: McpToolContext): Promise<unknown> {
   const { coChangeData, coChangeTopData } = await import('../../features/cochange.js');
   return args.file
     ? coChangeData(args.file, ctx.dbPath, {

package/src/mcp/tools/code-owners.ts

@@ -0,0 +1,22 @@
+import type { McpToolContext } from '../server.js';
+
+export const name = 'code_owners';
+
+interface CodeOwnersArgs {
+  file?: string;
+  owner?: string;
+  boundary?: boolean;
+  kind?: string;
+  no_tests?: boolean;
+}
+
+export async function handler(args: CodeOwnersArgs, ctx: McpToolContext): Promise<unknown> {
+  const { ownersData } = await import('../../features/owners.js');
+  return ownersData(ctx.dbPath, {
+    file: args.file,
+    owner: args.owner,
+    boundary: args.boundary,
+    kind: args.kind,
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/{communities.js → communities.ts}

@@ -1,8 +1,18 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'communities';
 
-export async function handler(args, ctx) {
+interface CommunitiesArgs {
+  functions?: boolean;
+  resolution?: number;
+  drift?: boolean;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: CommunitiesArgs, ctx: McpToolContext): Promise<unknown> {
   const { communitiesData } = await import('../../features/communities.js');
   return communitiesData(ctx.dbPath, {
     functions: args.functions,

package/src/mcp/tools/{complexity.js → complexity.ts}

@@ -1,8 +1,21 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'complexity';
 
-export async function handler(args, ctx) {
+interface ComplexityArgs {
+  name?: string;
+  file?: string;
+  limit?: number;
+  offset?: number;
+  sort?: string;
+  above_threshold?: boolean;
+  health?: boolean;
+  no_tests?: boolean;
+  kind?: string;
+}
+
+export async function handler(args: ComplexityArgs, ctx: McpToolContext): Promise<unknown> {
   const { complexityData } = await import('../../features/complexity.js');
   return complexityData(ctx.dbPath, {
     target: args.name,
@@ -11,7 +24,6 @@ export async function handler(args, ctx) {
     offset: effectiveOffset(args),
     sort: args.sort,
     aboveThreshold: args.above_threshold,
-    health: args.health,
     noTests: args.no_tests,
     kind: args.kind,
   });

package/src/mcp/tools/{context.js → context.ts}

@@ -1,8 +1,21 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'context';
 
-export async function handler(args, ctx) {
+interface ContextArgs {
+  name: string;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_source?: boolean;
+  no_tests?: boolean;
+  include_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: ContextArgs, ctx: McpToolContext): Promise<unknown> {
   const { contextData } = await ctx.getQueries();
   return contextData(args.name, ctx.dbPath, {
     depth: args.depth,

package/src/mcp/tools/{dataflow.js → dataflow.ts}

@@ -1,8 +1,20 @@
 import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'dataflow';
 
-export async function handler(args, ctx) {
+interface DataflowArgs {
+  mode?: string;
+  name: string;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: DataflowArgs, ctx: McpToolContext): Promise<unknown> {
   const dfMode = args.mode || 'edges';
   if (dfMode === 'impact') {
     const { dataflowImpactData } = await import('../../features/dataflow.js');
@@ -11,7 +23,7 @@ export async function handler(args, ctx) {
       file: args.file,
       kind: args.kind,
       noTests: args.no_tests,
-      limit: Math.min(args.limit ?? MCP_DEFAULTS.fn_impact, ctx.MCP_MAX_LIMIT),
+      limit: Math.min(args.limit ?? MCP_DEFAULTS.fn_impact ?? 100, ctx.MCP_MAX_LIMIT),
       offset: effectiveOffset(args),
     });
   }
@@ -20,7 +32,7 @@ export async function handler(args, ctx) {
     file: args.file,
     kind: args.kind,
     noTests: args.no_tests,
-    limit: Math.min(args.limit ?? MCP_DEFAULTS.query, ctx.MCP_MAX_LIMIT),
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.query ?? 100, ctx.MCP_MAX_LIMIT),
     offset: effectiveOffset(args),
   });
 }

package/src/mcp/tools/{diff-impact.js → diff-impact.ts}

@@ -1,8 +1,19 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'diff_impact';
 
-export async function handler(args, ctx) {
+interface DiffImpactArgs {
+  format?: string;
+  staged?: boolean;
+  ref?: string;
+  depth?: number;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: DiffImpactArgs, ctx: McpToolContext): Promise<unknown> {
   if (args.format === 'mermaid') {
     const { diffImpactMermaid } = await ctx.getQueries();
     return diffImpactMermaid(ctx.dbPath, {

package/src/mcp/tools/{execution-flow.js → execution-flow.ts}

@@ -1,8 +1,20 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'execution_flow';
 
-export async function handler(args, ctx) {
+interface ExecutionFlowArgs {
+  list?: boolean;
+  name?: string;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: ExecutionFlowArgs, ctx: McpToolContext): Promise<unknown> {
   if (args.list) {
     const { listEntryPointsData } = await import('../../features/flow.js');
     return listEntryPointsData(ctx.dbPath, {

package/src/mcp/tools/{export-graph.js → export-graph.ts}

@@ -1,17 +1,27 @@
 import { findDbPath } from '../../db/index.js';
 import { effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'export_graph';
 
-export async function handler(args, ctx) {
+interface ExportGraphArgs {
+  format: string;
+  file_level?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: ExportGraphArgs, ctx: McpToolContext): Promise<unknown> {
   const { exportDOT, exportGraphML, exportGraphSON, exportJSON, exportMermaid, exportNeo4jCSV } =
     await import('../../features/export.js');
   const Database = ctx.getDatabase();
   const db = new Database(findDbPath(ctx.dbPath), { readonly: true });
   const fileLevel = args.file_level !== false;
-  const exportLimit = args.limit ? Math.min(args.limit, MCP_MAX_LIMIT) : MCP_DEFAULTS.export_graph;
+  const exportLimit = args.limit
+    ? Math.min(args.limit, MCP_MAX_LIMIT)
+    : (MCP_DEFAULTS.export_graph ?? 500);
 
-  let result;
+  let result: unknown;
   try {
     switch (args.format) {
       case 'dot':

package/src/mcp/tools/{file-deps.js → file-deps.ts}

@@ -1,8 +1,16 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'file_deps';
 
-export async function handler(args, ctx) {
+interface FileDepsArgs {
+  file: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: FileDepsArgs, ctx: McpToolContext): Promise<unknown> {
   const { fileDepsData } = await ctx.getQueries();
   return fileDepsData(args.file, ctx.dbPath, {
     noTests: args.no_tests,

package/src/mcp/tools/{file-exports.js → file-exports.ts}

@@ -1,8 +1,17 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'file_exports';
 
-export async function handler(args, ctx) {
+interface FileExportsArgs {
+  file: string;
+  no_tests?: boolean;
+  unused?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: FileExportsArgs, ctx: McpToolContext): Promise<unknown> {
   const { exportsData } = await ctx.getQueries();
   return exportsData(args.file, ctx.dbPath, {
     noTests: args.no_tests,

package/src/mcp/tools/{find-cycles.js → find-cycles.ts}

@@ -1,9 +1,13 @@
 import { findDbPath } from '../../db/index.js';
 import { findCycles } from '../../domain/graph/cycles.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'find_cycles';
 
-export async function handler(_args, ctx) {
+export async function handler(
+  _args: Record<string, unknown>,
+  ctx: McpToolContext,
+): Promise<{ cycles: string[][]; count: number }> {
   const Database = ctx.getDatabase();
   const db = new Database(findDbPath(ctx.dbPath), { readonly: true });
   try {

package/src/mcp/tools/{fn-impact.js → fn-impact.ts}

@@ -1,8 +1,19 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'fn_impact';
 
-export async function handler(args, ctx) {
+interface FnImpactArgs {
+  name: string;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: FnImpactArgs, ctx: McpToolContext): Promise<unknown> {
   const { fnImpactData } = await ctx.getQueries();
   return fnImpactData(args.name, ctx.dbPath, {
     depth: args.depth,

package/src/mcp/tools/impact-analysis.ts

@@ -0,0 +1,15 @@
+import type { McpToolContext } from '../server.js';
+
+export const name = 'impact_analysis';
+
+interface ImpactAnalysisArgs {
+  file: string;
+  no_tests?: boolean;
+}
+
+export async function handler(args: ImpactAnalysisArgs, ctx: McpToolContext): Promise<unknown> {
+  const { impactAnalysisData } = await ctx.getQueries();
+  return impactAnalysisData(args.file, ctx.dbPath, {
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/{implementations.js → implementations.ts}

@@ -1,8 +1,18 @@
 import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../server.js';
 
 export const name = 'implementations';
 
-export async function handler(args, ctx) {
+interface ImplementationsArgs {
+  name: string;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: ImplementationsArgs, ctx: McpToolContext): Promise<unknown> {
   const { implementationsData } = await ctx.getQueries();
   return implementationsData(args.name, ctx.dbPath, {
     file: args.file,

package/src/mcp/tools/{index.js → index.ts}

@@ -2,6 +2,13 @@
  * Barrel module — registers all MCP tool handlers.
  */
 
+import type { McpToolContext } from '../server.js';
+
+export interface McpToolHandler {
+  name: string;
+  handler(args: any, ctx: McpToolContext): Promise<unknown>;
+}
+
 import * as astQuery from './ast-query.js';
 import * as audit from './audit.js';
 import * as batchQuery from './batch-query.js';
@@ -29,7 +36,7 @@ import * as listFunctions from './list-functions.js';
 import * as listRepos from './list-repos.js';
 import * as moduleMap from './module-map.js';
 import * as nodeRoles from './node-roles.js';
-import * as path from './path.js';
+import * as pathTool from './path.js';
 import * as query from './query.js';
 import * as semanticSearch from './semantic-search.js';
 import * as sequence from './sequence.js';
@@ -38,9 +45,9 @@ import * as symbolChildren from './symbol-children.js';
 import * as triage from './triage.js';
 import * as where from './where.js';
 
-export const TOOL_HANDLERS = new Map([
+export const TOOL_HANDLERS = new Map<string, McpToolHandler>([
   [query.name, query],
-  [path.name, path],
+  [pathTool.name, pathTool],
   [fileDeps.name, fileDeps],
   [fileExports.name, fileExports],
   [impactAnalysis.name, impactAnalysis],