@optave/codegraph 3.1.3 → 3.1.4

package/src/index.js

@@ -1,243 +1,66 @@
 /**
  * codegraph — Programmatic API
  *
+ * Curated public surface: *Data() query functions, graph building,
+ * export formats, and essential constants. CLI formatters and internal
+ * utilities are not exported — import them directly if needed.
+ *
  * Usage:
- *   import { buildGraph, queryNameData, findCycles, exportDOT } from 'codegraph';
+ *   import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph';
  */
 
-// AST node queries
-export { AST_NODE_KINDS, astQuery, astQueryData } from './ast.js';
-// Audit (composite report)
+export { astQueryData } from './ast.js';
 export { auditData } from './audit.js';
-// Batch querying
-export {
-  BATCH_COMMANDS,
-  batchData,
-  multiBatchData,
-  splitTargets,
-} from './batch.js';
-// Architecture boundary rules
-export { evaluateBoundaries, PRESETS, validateBoundaryConfig } from './boundaries.js';
-// Branch comparison
-export { branchCompareData, branchCompareMermaid } from './branch-compare.js';
-// Graph building
-export { buildGraph, collectFiles, loadPathAliases, resolveImportPath } from './builder.js';
-// Control flow graph (intraprocedural)
-export {
-  buildCFGData,
-  buildFunctionCFG,
-  CFG_RULES,
-  cfgData,
-  cfgToDOT,
-  cfgToMermaid,
-} from './cfg.js';
-// Check (CI validation predicates)
+export { batchData } from './batch.js';
+export { branchCompareData } from './branch-compare.js';
+export { buildGraph } from './builder.js';
+export { cfgData } from './cfg.js';
 export { checkData } from './check.js';
-// Co-change analysis
-export {
-  analyzeCoChanges,
-  coChangeData,
-  coChangeForFiles,
-  coChangeTopData,
-  computeCoChanges,
-  scanGitHistory,
-} from './cochange.js';
-export { audit } from './commands/audit.js';
-export { batch, batchQuery } from './commands/batch.js';
-export { cfg } from './commands/cfg.js';
-export { check } from './commands/check.js';
-export { communities } from './commands/communities.js';
-export { complexity } from './commands/complexity.js';
-export { dataflow } from './commands/dataflow.js';
-export { manifesto } from './commands/manifesto.js';
-export { owners } from './commands/owners.js';
-export { sequence } from './commands/sequence.js';
-export { formatHotspots, formatModuleBoundaries, formatStructure } from './commands/structure.js';
-export { triage } from './commands/triage.js';
-// Community detection
-export { communitiesData, communitySummaryForStats } from './communities.js';
-// Complexity metrics
-export {
-  COMPLEXITY_RULES,
-  complexityData,
-  computeFunctionComplexity,
-  computeHalsteadMetrics,
-  computeLOCMetrics,
-  computeMaintainabilityIndex,
-  findFunctionNode,
-  HALSTEAD_RULES,
-  iterComplexity,
-} from './complexity.js';
-// Configuration
+export { coChangeData } from './cochange.js';
+export { communitiesData } from './communities.js';
+export { complexityData } from './complexity.js';
 export { loadConfig } from './config.js';
-// Shared constants
-export { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-// Circular dependency detection
-export { findCycles, formatCycles } from './cycles.js';
-// Dataflow analysis
-export {
-  buildDataflowEdges,
-  dataflowData,
-  dataflowImpactData,
-  dataflowPathData,
-  extractDataflow,
-} from './dataflow.js';
-// Database utilities
-export {
-  countEdges,
-  countFiles,
-  countNodes,
-  fanInJoinSQL,
-  fanOutJoinSQL,
-  findDbPath,
-  findNodesForTriage,
-  findNodesWithFanIn,
-  getBuildMeta,
-  initSchema,
-  iterateFunctionNodes,
-  kindInClause,
-  listFunctionNodes,
-  NodeQuery,
-  openDb,
-  openReadonlyOrFail,
-  setBuildMeta,
-  testFilterSQL,
-} from './db.js';
-// Embeddings
+export { EXTENSIONS, IGNORE_DIRS } from './constants.js';
+export { findCycles } from './cycles.js';
+export { dataflowData } from './dataflow.js';
 export {
   buildEmbeddings,
-  cosineSim,
-  DEFAULT_MODEL,
-  disposeModel,
-  EMBEDDING_STRATEGIES,
-  embed,
-  estimateTokens,
-  ftsSearchData,
   hybridSearchData,
-  MODELS,
   multiSearchData,
-  search,
   searchData,
-} from './embedder.js';
-// Export (DOT/Mermaid/JSON/GraphML/GraphSON/Neo4j CSV)
-export {
-  exportDOT,
-  exportGraphML,
-  exportGraphSON,
-  exportJSON,
-  exportMermaid,
-  exportNeo4jCSV,
-} from './export.js';
-// Execution flow tracing
-export { entryPointType, flowData, listEntryPointsData } from './flow.js';
-// Result formatting
-export { outputResult } from './infrastructure/result-formatter.js';
-// Test file detection
-export { isTestFile, TEST_PATTERN } from './infrastructure/test-filter.js';
-// Logger
-export { setVerbose } from './logger.js';
-// Manifesto rule engine
-export { manifestoData, RULE_DEFS } from './manifesto.js';
-// Native engine
-export { isNativeAvailable } from './native.js';
-// Ownership (CODEOWNERS)
-export { matchOwners, ownersData, ownersForFiles, parseCodeowners } from './owners.js';
-// Pagination utilities
-export { MCP_DEFAULTS, MCP_MAX_LIMIT, paginate, paginateResult, printNdjson } from './paginate.js';
-// Unified parser API
+} from './embeddings/index.js';
 export {
-  disposeParsers,
-  getActiveEngine,
-  isWasmAvailable,
-  parseFileAuto,
-  parseFilesAuto,
-} from './parser.js';
-// Query functions (data-returning)
+  AnalysisError,
+  BoundaryError,
+  CodegraphError,
+  ConfigError,
+  DbError,
+  EngineError,
+  ParseError,
+  ResolutionError,
+} from './errors.js';
+export { exportDOT, exportJSON, exportMermaid } from './export.js';
+export { flowData, listEntryPointsData } from './flow.js';
+export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './kinds.js';
+export { manifestoData } from './manifesto.js';
+export { ownersData } from './owners.js';
 export {
-  ALL_SYMBOL_KINDS,
-  CORE_EDGE_KINDS,
-  CORE_SYMBOL_KINDS,
   childrenData,
   contextData,
   diffImpactData,
-  diffImpactMermaid,
-  EVERY_EDGE_KIND,
-  EVERY_SYMBOL_KIND,
-  EXTENDED_SYMBOL_KINDS,
   explainData,
   exportsData,
-  FALSE_POSITIVE_CALLER_THRESHOLD,
-  FALSE_POSITIVE_NAMES,
   fileDepsData,
   fnDepsData,
   fnImpactData,
   impactAnalysisData,
-  iterListFunctions,
-  iterRoles,
-  iterWhere,
-  kindIcon,
   moduleMapData,
-  normalizeSymbol,
   pathData,
   queryNameData,
   rolesData,
-  STRUCTURAL_EDGE_KINDS,
   statsData,
-  VALID_ROLES,
   whereData,
 } from './queries.js';
-// Query CLI display wrappers
-export {
-  children,
-  context,
-  diffImpact,
-  explain,
-  fileDeps,
-  fileExports,
-  fnDeps,
-  fnImpact,
-  impactAnalysis,
-  moduleMap,
-  queryName,
-  roles,
-  stats,
-  symbolPath,
-  where,
-} from './queries-cli.js';
-// Registry (multi-repo)
-export {
-  listRepos,
-  loadRegistry,
-  pruneRegistry,
-  REGISTRY_PATH,
-  registerRepo,
-  resolveRepoDbPath,
-  saveRegistry,
-  unregisterRepo,
-} from './registry.js';
-// Sequence diagram generation
-export { sequenceData, sequenceToMermaid } from './sequence.js';
-// Snapshot management
-export {
-  snapshotDelete,
-  snapshotList,
-  snapshotRestore,
-  snapshotSave,
-  snapshotsDir,
-  validateSnapshotName,
-} from './snapshot.js';
-// Structure analysis
-export {
-  buildStructure,
-  classifyNodeRoles,
-  FRAMEWORK_ENTRY_PREFIXES,
-  hotspotsData,
-  moduleBoundariesData,
-  structureData,
-} from './structure.js';
-// Triage — composite risk audit
+export { sequenceData } from './sequence.js';
+export { hotspotsData, moduleBoundariesData, structureData } from './structure.js';
 export { triageData } from './triage.js';
-// Interactive HTML viewer
-export { generatePlotHTML, loadPlotConfig } from './viewer.js';
-// Watch mode
-export { watchProject } from './watcher.js';

package/src/infrastructure/result-formatter.js

@@ -1,21 +1,2 @@
-import { printNdjson } from '../paginate.js';
-
-/**
- * Shared JSON / NDJSON output dispatch for CLI wrappers.
- *
- * @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? })
- * @returns {boolean} true if output was handled (caller should return early)
- */
-export function outputResult(data, field, opts) {
-  if (opts.ndjson) {
-    printNdjson(data, field);
-    return true;
-  }
-  if (opts.json) {
-    console.log(JSON.stringify(data, null, 2));
-    return true;
-  }
-  return false;
-}
+// Re-export from presentation layer — this file exists for backward compatibility.
+export { outputResult } from '../presentation/result-formatter.js';

package/src/mcp/index.js

@@ -0,0 +1,2 @@
+export { startMCPServer } from './server.js';
+export { buildToolList, TOOLS } from './tool-registry.js';

package/src/mcp/middleware.js

@@ -0,0 +1,26 @@
+/**
+ * MCP middleware helpers — pagination defaults and limits.
+ */
+
+import { MCP_DEFAULTS, MCP_MAX_LIMIT } from '../paginate.js';
+
+export { MCP_DEFAULTS, MCP_MAX_LIMIT };
+
+/**
+ * Resolve effective limit for a tool call.
+ * @param {object} args - Tool arguments
+ * @param {string} toolName - Tool name (for default lookup)
+ * @returns {number}
+ */
+export function effectiveLimit(args, toolName) {
+  return Math.min(args.limit ?? MCP_DEFAULTS[toolName] ?? 100, MCP_MAX_LIMIT);
+}
+
+/**
+ * Resolve effective offset for a tool call.
+ * @param {object} args - Tool arguments
+ * @returns {number}
+ */
+export function effectiveOffset(args) {
+  return args.offset ?? 0;
+}

package/src/mcp/server.js

@@ -0,0 +1,128 @@
+/**
+ * MCP (Model Context Protocol) server for codegraph.
+ * Exposes codegraph queries as tools that AI coding assistants can call.
+ *
+ * Requires: npm install @modelcontextprotocol/sdk
+ */
+
+import { createRequire } from 'node:module';
+import { findDbPath } from '../db.js';
+import { CodegraphError, ConfigError } from '../errors.js';
+import { MCP_MAX_LIMIT } from '../paginate.js';
+import { buildToolList } from './tool-registry.js';
+import { TOOL_HANDLERS } from './tools/index.js';
+
+/**
+ * Start the MCP server.
+ * This function requires @modelcontextprotocol/sdk to be installed.
+ *
+ * @param {string} [customDbPath] - Path to a specific graph.db
+ * @param {object} [options]
+ * @param {boolean} [options.multiRepo] - Enable multi-repo access (default: false)
+ * @param {string[]} [options.allowedRepos] - Restrict access to these repo names only
+ */
+export async function startMCPServer(customDbPath, options = {}) {
+  const { allowedRepos } = options;
+  const multiRepo = options.multiRepo || !!allowedRepos;
+  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 {
+    throw new ConfigError(
+      'MCP server requires @modelcontextprotocol/sdk.\nInstall it with: npm install @modelcontextprotocol/sdk',
+    );
+  }
+
+  // Connect transport FIRST so the server can receive the client's
+  // `initialize` request while heavy modules (queries, better-sqlite3)
+  // are still loading.  These are lazy-loaded on the first tool call
+  // and cached for subsequent calls.
+  let _queries;
+  let _Database;
+
+  async function getQueries() {
+    if (!_queries) {
+      _queries = await import('../queries.js');
+    }
+    return _queries;
+  }
+
+  function getDatabase() {
+    if (!_Database) {
+      const require = createRequire(import.meta.url);
+      _Database = require('better-sqlite3');
+    }
+    return _Database;
+  }
+
+  const server = new Server(
+    { name: 'codegraph', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: buildToolList(multiRepo),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      if (!multiRepo && args.repo) {
+        throw new ConfigError(
+          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
+        );
+      }
+      if (!multiRepo && name === 'list_repos') {
+        throw new ConfigError(
+          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
+        );
+      }
+
+      let dbPath = customDbPath || undefined;
+      if (args.repo) {
+        if (allowedRepos && !allowedRepos.includes(args.repo)) {
+          throw new ConfigError(`Repository "${args.repo}" is not in the allowed repos list.`);
+        }
+        const { resolveRepoDbPath } = await import('../registry.js');
+        const resolved = resolveRepoDbPath(args.repo);
+        if (!resolved)
+          throw new ConfigError(
+            `Repository "${args.repo}" not found in registry or its database is missing.`,
+          );
+        dbPath = resolved;
+      }
+
+      const toolEntry = TOOL_HANDLERS.get(name);
+      if (!toolEntry) {
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+      }
+
+      const ctx = {
+        dbPath,
+        getQueries,
+        getDatabase,
+        findDbPath,
+        allowedRepos,
+        MCP_MAX_LIMIT,
+      };
+
+      const result = await toolEntry.handler(args, ctx);
+      if (result?.content) return result; // pass-through MCP responses
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      const code = err instanceof CodegraphError ? err.code : 'UNKNOWN_ERROR';
+      const text =
+        err instanceof CodegraphError ? `[${code}] ${err.message}` : `Error: ${err.message}`;
+      return { content: [{ type: 'text', text }], isError: true };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}