optave-codegraph 3.13.0

package/src/mcp/tools/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Barrel module — registers all MCP tool handlers.
+ */
+
+import type { McpToolHandler } from '../types.js';
+
+export type { McpToolContext, McpToolHandler } from '../types.js';
+
+import * as astQuery from './ast-query.js';
+import * as audit from './audit.js';
+import * as batchQuery from './batch-query.js';
+import * as branchCompare from './branch-compare.js';
+import * as brief from './brief.js';
+import * as cfg from './cfg.js';
+import * as check from './check.js';
+import * as coChanges from './co-changes.js';
+import * as codeOwners from './code-owners.js';
+import * as communities from './communities.js';
+import * as complexity from './complexity.js';
+import * as context from './context.js';
+import * as dataflow from './dataflow.js';
+import * as diffImpact from './diff-impact.js';
+import * as executionFlow from './execution-flow.js';
+import * as exportGraph from './export-graph.js';
+import * as fileDeps from './file-deps.js';
+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';
+import * as nodeRoles from './node-roles.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';
+import * as structure from './structure.js';
+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<string, McpToolHandler>([
+  [query.name, query],
+  [pathTool.name, pathTool],
+  [fileDeps.name, fileDeps],
+  [fileExports.name, fileExports],
+  [impactAnalysis.name, impactAnalysis],
+  [findCycles.name, findCycles],
+  [moduleMap.name, moduleMap],
+  [fnImpact.name, fnImpact],
+  [context.name, context],
+  [symbolChildren.name, symbolChildren],
+  [where.name, where],
+  [diffImpact.name, diffImpact],
+  [semanticSearch.name, semanticSearch],
+  [exportGraph.name, exportGraph],
+  [listFunctions.name, listFunctions],
+  [structure.name, structure],
+  [nodeRoles.name, nodeRoles],
+  [coChanges.name, coChanges],
+  [executionFlow.name, executionFlow],
+  [sequence.name, sequence],
+  [complexity.name, complexity],
+  [communities.name, communities],
+  [codeOwners.name, codeOwners],
+  [audit.name, audit],
+  [batchQuery.name, batchQuery],
+  [triage.name, triage],
+  [branchCompare.name, branchCompare],
+  [cfg.name, cfg],
+  [dataflow.name, dataflow],
+  [check.name, check],
+  [astQuery.name, astQuery],
+  [brief.name, brief],
+  [implementations.name, implementations],
+  [interfaces.name, interfaces],
+  [listRepos.name, listRepos],
+]);

package/src/mcp/tools/interfaces.ts

@@ -0,0 +1,24 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'interfaces';
+
+interface InterfacesArgs {
+  name: string;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: InterfacesArgs, ctx: McpToolContext): Promise<unknown> {
+  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/list-functions.ts

@@ -0,0 +1,23 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'list_functions';
+
+interface ListFunctionsArgs {
+  file?: string;
+  pattern?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: ListFunctionsArgs, ctx: McpToolContext): Promise<unknown> {
+  const { listFunctionsData } = await ctx.getQueries();
+  return listFunctionsData(ctx.dbPath, {
+    file: args.file,
+    pattern: args.pattern,
+    noTests: args.no_tests,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/list-repos.ts

@@ -0,0 +1,17 @@
+import type { McpToolContext } from '../types.js';
+
+export const name = 'list_repos';
+
+interface ListReposArgs {
+  [key: string]: unknown;
+}
+
+export async function handler(_args: ListReposArgs, ctx: McpToolContext): Promise<unknown> {
+  const { listRepos, pruneRegistry } = await import('../../infrastructure/registry.js');
+  pruneRegistry();
+  let repos = listRepos();
+  if (ctx.allowedRepos) {
+    repos = repos.filter((r: { name: string }) => (ctx.allowedRepos as string[]).includes(r.name));
+  }
+  return { repos };
+}

package/src/mcp/tools/module-map.ts

@@ -0,0 +1,13 @@
+import type { McpToolContext } from '../types.js';
+
+export const name = 'module_map';
+
+interface ModuleMapArgs {
+  limit?: number;
+  no_tests?: boolean;
+}
+
+export async function handler(args: ModuleMapArgs, ctx: McpToolContext): Promise<unknown> {
+  const { moduleMapData } = await ctx.getQueries();
+  return moduleMapData(ctx.dbPath, args.limit || 20, { noTests: args.no_tests });
+}

package/src/mcp/tools/node-roles.ts

@@ -0,0 +1,23 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'node_roles';
+
+interface NodeRolesArgs {
+  role?: string;
+  file?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: NodeRolesArgs, ctx: McpToolContext): Promise<unknown> {
+  const { rolesData } = await ctx.getQueries();
+  return rolesData(ctx.dbPath, {
+    role: args.role,
+    file: args.file,
+    noTests: args.no_tests,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/path.ts

@@ -0,0 +1,34 @@
+import type { McpToolContext } from '../types.js';
+
+export const name = 'path';
+
+interface PathArgs {
+  from: string;
+  to: string;
+  depth?: number;
+  edge_kinds?: string[];
+  from_file?: string;
+  to_file?: string;
+  no_tests?: boolean;
+  file_mode?: boolean;
+}
+
+export async function handler(args: PathArgs, ctx: McpToolContext): Promise<unknown> {
+  if (args.file_mode) {
+    const { filePathData } = await ctx.getQueries();
+    return filePathData(args.from, args.to, ctx.dbPath, {
+      maxDepth: args.depth ?? 10,
+      edgeKinds: args.edge_kinds,
+      reverse: false,
+      noTests: args.no_tests,
+    });
+  }
+  const { pathData } = await ctx.getQueries();
+  return pathData(args.from, args.to, ctx.dbPath, {
+    maxDepth: args.depth ?? 10,
+    edgeKinds: args.edge_kinds,
+    fromFile: args.from_file,
+    toFile: args.to_file,
+    noTests: args.no_tests,
+  });
+}

package/src/mcp/tools/query.ts

@@ -0,0 +1,47 @@
+import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'query';
+
+interface QueryArgs {
+  name: string;
+  mode?: string;
+  to?: string;
+  depth?: number;
+  edge_kinds?: string[];
+  reverse?: boolean;
+  from_file?: string;
+  to_file?: string;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: QueryArgs, ctx: McpToolContext): Promise<unknown> {
+  const { fnDepsData, pathData } = await ctx.getQueries();
+  const qMode = args.mode || 'deps';
+  if (qMode === 'path') {
+    if (!args.to) {
+      return { error: 'path mode requires a "to" argument' };
+    }
+    return pathData(args.name, args.to, ctx.dbPath, {
+      maxDepth: args.depth ?? 10,
+      edgeKinds: args.edge_kinds,
+      reverse: args.reverse,
+      fromFile: args.from_file,
+      toFile: args.to_file,
+      kind: args.kind,
+      noTests: args.no_tests,
+    });
+  }
+  return fnDepsData(args.name, ctx.dbPath, {
+    depth: args.depth,
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.query ?? 100, ctx.MCP_MAX_LIMIT),
+    offset: effectiveOffset(args),
+  });
+}

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

@@ -0,0 +1,76 @@
+import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'semantic_search';
+
+interface SemanticSearchArgs {
+  query: string;
+  mode?: string;
+  limit?: number;
+  offset?: number;
+  min_score?: number;
+  file_pattern?: string | string[];
+}
+
+export async function handler(args: SemanticSearchArgs, ctx: McpToolContext): Promise<unknown> {
+  const mode = args.mode || 'hybrid';
+  const searchOpts = {
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.semantic_search ?? 100, ctx.MCP_MAX_LIMIT),
+    offset: effectiveOffset(args),
+    minScore: args.min_score,
+    filePattern: args.file_pattern,
+  };
+
+  if (mode === 'keyword') {
+    const { ftsSearchData } = await import('../../domain/search/index.js');
+    const result = ftsSearchData(args.query, ctx.dbPath, searchOpts);
+    if (result === null) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No FTS5 index found. Run `codegraph embed` to build the keyword index.',
+          },
+        ],
+        isError: true,
+      };
+    }
+    return result;
+  }
+
+  if (mode === 'semantic') {
+    const { searchData } = await import('../../domain/search/index.js');
+    const result = await searchData(args.query, ctx.dbPath, searchOpts);
+    if (result === null) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Semantic search unavailable. Run `codegraph embed` first.',
+          },
+        ],
+        isError: true,
+      };
+    }
+    return result;
+  }
+
+  // hybrid (default) — falls back to semantic if no FTS5
+  const { hybridSearchData, searchData } = await import('../../domain/search/index.js');
+  let result: unknown = await hybridSearchData(args.query, ctx.dbPath, searchOpts);
+  if (result === null) {
+    result = await searchData(args.query, ctx.dbPath, searchOpts);
+    if (result === null) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Semantic search unavailable. Run `codegraph embed` first.',
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+  return result;
+}

package/src/mcp/tools/sequence.ts

@@ -0,0 +1,30 @@
+import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'sequence';
+
+interface SequenceArgs {
+  name: string;
+  depth?: number;
+  file?: string;
+  kind?: string;
+  dataflow?: boolean;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+  format?: string;
+}
+
+export async function handler(args: SequenceArgs, ctx: McpToolContext): Promise<unknown> {
+  const { sequenceData, sequenceToMermaid } = await import('../../features/sequence.js');
+  const seqResult = sequenceData(args.name, ctx.dbPath, {
+    depth: args.depth,
+    file: args.file,
+    kind: args.kind,
+    dataflow: args.dataflow,
+    noTests: args.no_tests,
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.execution_flow ?? 100, ctx.MCP_MAX_LIMIT),
+    offset: effectiveOffset(args),
+  });
+  return args.format === 'json' ? seqResult : { text: sequenceToMermaid(seqResult), ...seqResult };
+}

package/src/mcp/tools/structure.ts

@@ -0,0 +1,25 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'structure';
+
+interface StructureArgs {
+  directory?: string;
+  depth?: number;
+  sort?: string;
+  full?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: StructureArgs, ctx: McpToolContext): Promise<unknown> {
+  const { structureData } = await import('../../features/structure.js');
+  return structureData(ctx.dbPath, {
+    directory: args.directory,
+    depth: args.depth,
+    sort: args.sort,
+    full: args.full,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/symbol-children.ts

@@ -0,0 +1,24 @@
+import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'symbol_children';
+
+interface SymbolChildrenArgs {
+  name: string;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: SymbolChildrenArgs, ctx: McpToolContext): Promise<unknown> {
+  const { childrenData } = await ctx.getQueries();
+  return childrenData(args.name, ctx.dbPath, {
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+    limit: Math.min(args.limit ?? MCP_DEFAULTS.context ?? 100, ctx.MCP_MAX_LIMIT),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/triage.ts

@@ -0,0 +1,50 @@
+import type { Role } from '../../types.js';
+import { effectiveLimit, effectiveOffset, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'triage';
+
+interface TriageArgs {
+  level?: string;
+  sort?: string;
+  min_score?: number;
+  role?: string;
+  file?: string;
+  kind?: string;
+  no_tests?: boolean;
+  weights?: Record<string, number>;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: TriageArgs, ctx: McpToolContext): Promise<unknown> {
+  if (args.level === 'file' || args.level === 'directory') {
+    const { hotspotsData } = await import('../../features/structure.js');
+    const TRIAGE_TO_HOTSPOT: Record<string, string> = {
+      risk: 'fan-in',
+      complexity: 'density',
+      churn: 'coupling',
+      mi: 'fan-in',
+    };
+    const metric = TRIAGE_TO_HOTSPOT[args.sort as string] ?? args.sort;
+    return hotspotsData(ctx.dbPath, {
+      metric,
+      level: args.level,
+      limit: Math.min(args.limit ?? MCP_DEFAULTS.hotspots ?? 100, MCP_MAX_LIMIT),
+      offset: effectiveOffset(args),
+      noTests: args.no_tests,
+    });
+  }
+  const { triageData } = await import('../../features/triage.js');
+  return triageData(ctx.dbPath, {
+    sort: args.sort,
+    minScore: args.min_score,
+    role: args.role as Role | undefined,
+    file: args.file,
+    kind: args.kind,
+    noTests: args.no_tests,
+    weights: args.weights,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/tools/where.ts

@@ -0,0 +1,22 @@
+import { effectiveLimit, effectiveOffset } from '../middleware.js';
+import type { McpToolContext } from '../types.js';
+
+export const name = 'where';
+
+interface WhereArgs {
+  target: string;
+  file_mode?: string;
+  no_tests?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function handler(args: WhereArgs, ctx: McpToolContext): Promise<unknown> {
+  const { whereData } = await ctx.getQueries();
+  return whereData(args.target, ctx.dbPath, {
+    file: args.file_mode,
+    noTests: args.no_tests,
+    limit: effectiveLimit(args, name),
+    offset: effectiveOffset(args),
+  });
+}

package/src/mcp/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared MCP types used by server.ts and all tool modules.
+ * Extracted here to break the circular dependency between server.ts and tools/index.ts.
+ */
+
+import type Database from 'better-sqlite3';
+import type { findDbPath } from '../db/index.js';
+
+export interface McpToolContext {
+  dbPath: string | undefined;
+  getQueries(): Promise<any>;
+  getDatabase(): typeof Database;
+  findDbPath: typeof findDbPath;
+  allowedRepos: string[] | undefined;
+  MCP_MAX_LIMIT: number;
+}
+
+export interface McpToolHandler {
+  name: string;
+  handler(args: any, ctx: McpToolContext): Promise<unknown>;
+}

package/src/presentation/audit.ts

@@ -0,0 +1,109 @@
+import { kindIcon } from '../domain/queries.js';
+import { auditData } from '../features/audit.js';
+import { outputResult } from '../infrastructure/result-formatter.js';
+
+interface AuditOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  noTests?: boolean;
+  file?: string;
+  kind?: string;
+  quick?: boolean;
+  limit?: number;
+  offset?: number;
+  depth?: number;
+  config?: unknown;
+}
+
+/** Render health metrics for a single audit function. */
+function renderHealthMetrics(fn: any): void {
+  if (fn.health.cognitive == null) return;
+  console.log(`\n  Health:`);
+  console.log(
+    `    Cognitive: ${fn.health.cognitive}  Cyclomatic: ${fn.health.cyclomatic}  Nesting: ${fn.health.maxNesting}`,
+  );
+  console.log(`    MI: ${fn.health.maintainabilityIndex}`);
+  if (fn.health.halstead.volume) {
+    console.log(
+      `    Halstead: vol=${fn.health.halstead.volume} diff=${fn.health.halstead.difficulty} effort=${fn.health.halstead.effort} bugs=${fn.health.halstead.bugs}`,
+    );
+  }
+  if (fn.health.loc) {
+    console.log(
+      `    LOC: ${fn.health.loc}  SLOC: ${fn.health.sloc}  Comments: ${fn.health.commentLines}`,
+    );
+  }
+}
+
+/** Render a single audited function with all its sections. */
+function renderAuditFunction(fn: any): void {
+  const lineRange = fn.endLine ? `${fn.line}-${fn.endLine}` : `${fn.line}`;
+  const roleTag = fn.role ? ` [${fn.role}]` : '';
+  console.log(`## ${kindIcon(fn.kind)} ${fn.name} (${fn.kind})${roleTag}`);
+  console.log(`  ${fn.file}:${lineRange}${fn.lineCount ? ` (${fn.lineCount} lines)` : ''}`);
+  if (fn.summary) console.log(`  ${fn.summary}`);
+  if (fn.signature) {
+    if (fn.signature.params != null) console.log(`  Parameters: (${fn.signature.params})`);
+    if (fn.signature.returnType) console.log(`  Returns: ${fn.signature.returnType}`);
+  }
+
+  renderHealthMetrics(fn);
+
+  if (fn.health.thresholdBreaches.length > 0) {
+    console.log(`\n  Threshold Breaches:`);
+    for (const b of fn.health.thresholdBreaches) {
+      const icon = b.level === 'fail' ? 'FAIL' : 'WARN';
+      console.log(`    [${icon}] ${b.metric}: ${b.value} >= ${b.threshold}`);
+    }
+  }
+
+  console.log(`\n  Impact: ${fn.impact.totalDependents} transitive dependent(s)`);
+  for (const [level, nodes] of Object.entries(fn.impact.levels)) {
+    console.log(
+      `    Level ${level}: ${(nodes as Array<{ name: string }>).map((n) => n.name).join(', ')}`,
+    );
+  }
+
+  if (fn.callees.length > 0) {
+    console.log(`\n  Calls (${fn.callees.length}):`);
+    for (const c of fn.callees) {
+      console.log(`    ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+    }
+  }
+  if (fn.callers.length > 0) {
+    console.log(`\n  Called by (${fn.callers.length}):`);
+    for (const c of fn.callers) {
+      console.log(`    ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+    }
+  }
+  if (fn.relatedTests.length > 0) {
+    console.log(`\n  Tests (${fn.relatedTests.length}):`);
+    for (const t of fn.relatedTests) {
+      console.log(`    ${t.file}`);
+    }
+  }
+
+  console.log();
+}
+
+export function audit(
+  target: string,
+  customDbPath: string | undefined,
+  opts: AuditOpts = {},
+): void {
+  const data: any = auditData(target, customDbPath, opts as any);
+
+  if (outputResult(data, null, opts)) return;
+
+  if (data.functions.length === 0) {
+    console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);
+    return;
+  }
+
+  console.log(`\n# Audit: ${target} (${data.kind})`);
+  console.log(`  ${data.functions.length} function(s) analyzed\n`);
+
+  for (const fn of data.functions) {
+    renderAuditFunction(fn);
+  }
+}

package/src/presentation/batch.ts

@@ -0,0 +1,50 @@
+import { batchData, multiBatchData } from '../features/batch.js';
+
+interface BatchOpts {
+  json?: boolean;
+  ndjson?: boolean;
+  noTests?: boolean;
+  file?: string;
+  kind?: string;
+  command?: string;
+  limit?: number;
+  offset?: number;
+  [key: string]: unknown;
+}
+
+interface MultiBatchTarget {
+  command: string;
+  target: string;
+  [key: string]: unknown;
+}
+
+export function batch(
+  command: string,
+  targets: string[],
+  customDbPath: string | undefined,
+  opts: BatchOpts = {},
+): void {
+  const data = batchData(command, targets, customDbPath, opts);
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function batchQuery(
+  targets: Array<string | MultiBatchTarget>,
+  customDbPath: string | undefined,
+  opts: BatchOpts = {},
+): void {
+  const { command: defaultCommand = 'where', ...rest } = opts;
+  const isMulti =
+    targets.length > 0 &&
+    targets[0] !== null &&
+    typeof targets[0] === 'object' &&
+    !!(targets[0] as MultiBatchTarget).command;
+
+  let data: unknown;
+  if (isMulti) {
+    data = multiBatchData(targets as MultiBatchTarget[], customDbPath, rest);
+  } else {
+    data = batchData(defaultCommand, targets as string[], customDbPath, rest);
+  }
+  console.log(JSON.stringify(data, null, 2));
+}