@optave/codegraph 3.1.3 → 3.1.5

package/src/graph/model.js

@@ -0,0 +1,230 @@
+/**
+ * Unified in-memory graph model.
+ *
+ * Stores directed (default) or undirected graphs with node/edge attributes.
+ * Node IDs are always strings. DB integer IDs should be stringified before use.
+ */
+
+import Graph from 'graphology';
+
+export class CodeGraph {
+  /**
+   * @param {{ directed?: boolean }} [opts]
+   */
+  constructor(opts = {}) {
+    this._directed = opts.directed !== false;
+    /** @type {Map<string, object>} */
+    this._nodes = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (target → edgeAttrs) */
+    this._successors = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (source → edgeAttrs) */
+    this._predecessors = new Map();
+  }
+
+  get directed() {
+    return this._directed;
+  }
+
+  get nodeCount() {
+    return this._nodes.size;
+  }
+
+  get edgeCount() {
+    let count = 0;
+    for (const targets of this._successors.values()) count += targets.size;
+    // Undirected graphs store each edge twice (a→b and b→a)
+    return this._directed ? count : count / 2;
+  }
+
+  // ─── Node operations ────────────────────────────────────────────
+
+  addNode(id, attrs = {}) {
+    const key = String(id);
+    this._nodes.set(key, attrs);
+    if (!this._successors.has(key)) this._successors.set(key, new Map());
+    if (!this._predecessors.has(key)) this._predecessors.set(key, new Map());
+    return this;
+  }
+
+  hasNode(id) {
+    return this._nodes.has(String(id));
+  }
+
+  getNodeAttrs(id) {
+    return this._nodes.get(String(id));
+  }
+
+  /** @returns {IterableIterator<[string, object]>} */
+  nodes() {
+    return this._nodes.entries();
+  }
+
+  /** @returns {string[]} */
+  nodeIds() {
+    return [...this._nodes.keys()];
+  }
+
+  // ─── Edge operations ────────────────────────────────────────────
+
+  addEdge(source, target, attrs = {}) {
+    const src = String(source);
+    const tgt = String(target);
+    // Auto-add nodes if missing
+    if (!this._nodes.has(src)) this.addNode(src);
+    if (!this._nodes.has(tgt)) this.addNode(tgt);
+
+    this._successors.get(src).set(tgt, attrs);
+    this._predecessors.get(tgt).set(src, attrs);
+
+    if (!this._directed) {
+      this._successors.get(tgt).set(src, attrs);
+      this._predecessors.get(src).set(tgt, attrs);
+    }
+    return this;
+  }
+
+  hasEdge(source, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.has(src) && this._successors.get(src).has(tgt);
+  }
+
+  getEdgeAttrs(source, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.get(src)?.get(tgt);
+  }
+
+  /** @yields {[string, string, object]} source, target, attrs */
+  *edges() {
+    const seen = this._directed ? null : new Set();
+    for (const [src, targets] of this._successors) {
+      for (const [tgt, attrs] of targets) {
+        if (!this._directed) {
+          // \0 is safe as separator — node IDs are file paths/symbols, never contain null bytes
+          const key = src < tgt ? `${src}\0${tgt}` : `${tgt}\0${src}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        yield [src, tgt, attrs];
+      }
+    }
+  }
+
+  // ─── Adjacency ──────────────────────────────────────────────────
+
+  /** Direct successors of a node (outgoing edges). */
+  successors(id) {
+    const key = String(id);
+    const map = this._successors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** Direct predecessors of a node (incoming edges). */
+  predecessors(id) {
+    const key = String(id);
+    const map = this._predecessors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** All neighbors (union of successors + predecessors). */
+  neighbors(id) {
+    const key = String(id);
+    const set = new Set();
+    const succ = this._successors.get(key);
+    if (succ) for (const k of succ.keys()) set.add(k);
+    const pred = this._predecessors.get(key);
+    if (pred) for (const k of pred.keys()) set.add(k);
+    return [...set];
+  }
+
+  outDegree(id) {
+    const map = this._successors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  inDegree(id) {
+    const map = this._predecessors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  // ─── Filtering ──────────────────────────────────────────────────
+
+  /** Return a new graph containing only nodes matching the predicate. */
+  subgraph(predicate) {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      if (predicate(id, attrs)) g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (g.hasNode(src) && g.hasNode(tgt)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  /** Return a new graph containing only edges matching the predicate. */
+  filterEdges(predicate) {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (predicate(src, tgt, attrs)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  // ─── Conversion ─────────────────────────────────────────────────
+
+  /** Convert to flat edge array for native Rust interop. */
+  toEdgeArray() {
+    const result = [];
+    for (const [source, target] of this.edges()) {
+      result.push({ source, target });
+    }
+    return result;
+  }
+
+  /** Convert to graphology instance (for Louvain etc). */
+  toGraphology(opts = {}) {
+    const type = opts.type || (this._directed ? 'directed' : 'undirected');
+    const g = new Graph({ type });
+    for (const [id] of this._nodes) {
+      g.addNode(id);
+    }
+
+    for (const [src, tgt] of this.edges()) {
+      if (src === tgt) continue;
+      if (!g.hasEdge(src, tgt)) g.addEdge(src, tgt);
+    }
+    return g;
+  }
+
+  // ─── Utilities ──────────────────────────────────────────────────
+
+  clone() {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      g.addEdge(src, tgt, { ...attrs });
+    }
+    return g;
+  }
+
+  /** Merge another graph into this one. Nodes/edges from other override on conflict. */
+  merge(other) {
+    for (const [id, attrs] of other.nodes()) {
+      this.addNode(id, attrs);
+    }
+    for (const [src, tgt, attrs] of other.edges()) {
+      this.addEdge(src, tgt, attrs);
+    }
+    return this;
+  }
+}

package/src/index.cjs

@@ -0,0 +1,16 @@
+/**
+ * CJS compatibility wrapper — delegates to ESM via dynamic import().
+ *
+ * This wrapper always returns a Promise on every Node version, because
+ * import() is unconditionally async. You must always await the result:
+ *
+ *   const codegraph = await require('@optave/codegraph');
+ *
+ * // Named destructuring at require-time does NOT work — always await the full result first.
+ * // BAD:  const { buildGraph } = require('@optave/codegraph');  // buildGraph is undefined
+ * // GOOD: const { buildGraph } = await require('@optave/codegraph');
+ */
+// Note: if import() rejects (e.g. missing dependency), the rejected Promise is cached
+// by the CJS module system and every subsequent require() call will re-surface the same
+// rejection without re-attempting the load.
+module.exports = import('./index.js');

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 { 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 { 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 { 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 {
-  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
+export { buildGraph } from './domain/graph/builder.js';
+export { findCycles } from './domain/graph/cycles.js';
 export {
-  disposeParsers,
-  getActiveEngine,
-  isWasmAvailable,
-  parseFileAuto,
-  parseFilesAuto,
-} from './parser.js';
-// Query functions (data-returning)
-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)
+} from './domain/queries.js';
 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
+  buildEmbeddings,
+  hybridSearchData,
+  multiSearchData,
+  searchData,
+} from './domain/search/index.js';
+export { astQueryData } from './features/ast.js';
+export { auditData } from './features/audit.js';
+export { batchData } from './features/batch.js';
+export { branchCompareData } from './features/branch-compare.js';
+export { cfgData } from './features/cfg.js';
+export { checkData } from './features/check.js';
+export { coChangeData } from './features/cochange.js';
+export { communitiesData } from './features/communities.js';
+export { complexityData } from './features/complexity.js';
+export { dataflowData } from './features/dataflow.js';
+export { exportDOT, exportJSON, exportMermaid } from './features/export.js';
+export { flowData, listEntryPointsData } from './features/flow.js';
+export { manifestoData } from './features/manifesto.js';
+export { ownersData } from './features/owners.js';
+export { sequenceData } from './features/sequence.js';
+export { hotspotsData, moduleBoundariesData, structureData } from './features/structure.js';
+export { triageData } from './features/triage.js';
+export { loadConfig } from './infrastructure/config.js';
+export { EXTENSIONS, IGNORE_DIRS } from './shared/constants.js';
 export {
-  buildStructure,
-  classifyNodeRoles,
-  FRAMEWORK_ENTRY_PREFIXES,
-  hotspotsData,
-  moduleBoundariesData,
-  structureData,
-} from './structure.js';
-// Triage — composite risk audit
-export { triageData } from './triage.js';
-// Interactive HTML viewer
-export { generatePlotHTML, loadPlotConfig } from './viewer.js';
-// Watch mode
-export { watchProject } from './watcher.js';
+  AnalysisError,
+  BoundaryError,
+  CodegraphError,
+  ConfigError,
+  DbError,
+  EngineError,
+  ParseError,
+  ResolutionError,
+} from './shared/errors.js';
+export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './shared/kinds.js';

package/src/{native.js → infrastructure/native.js}

@@ -8,6 +8,7 @@
 
 import { createRequire } from 'node:module';
 import os from 'node:os';
+import { EngineError } from '../shared/errors.js';
 
 let _cached; // undefined = not yet tried, null = failed, object = module
 let _loadError = null;
@@ -101,9 +102,10 @@ export function getNativePackageVersion() {
 export function getNative() {
   const mod = loadNative();
   if (!mod) {
-    throw new Error(
+    throw new EngineError(
       `Native codegraph-core not available: ${_loadError?.message || 'unknown error'}. ` +
         'Install the platform package or use --engine wasm.',
+      { cause: _loadError },
     );
   }
   return mod;

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 '../shared/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;
+}