@optave/codegraph 3.1.3 → 3.1.4

package/src/extractors/csharp.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { extractModifierVisibility, findChild, nodeEndLine } from './helpers.js';
 
 /**
  * Extract symbols from C# files.
@@ -133,6 +133,7 @@ export function extractCSharpSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: extractModifierVisibility(node),
           });
         }
         break;
@@ -150,6 +151,7 @@ export function extractCSharpSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: extractModifierVisibility(node),
           });
         }
         break;
@@ -165,6 +167,7 @@ export function extractCSharpSymbols(tree, _filePath) {
             kind: 'property',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
+            visibility: extractModifierVisibility(node),
           });
         }
         break;
@@ -260,7 +263,12 @@ function extractCSharpClassFields(classNode) {
       if (!child || child.type !== 'variable_declarator') continue;
       const nameNode = child.childForFieldName('name');
       if (nameNode) {
-        fields.push({ name: nameNode.text, kind: 'property', line: member.startPosition.row + 1 });
+        fields.push({
+          name: nameNode.text,
+          kind: 'property',
+          line: member.startPosition.row + 1,
+          visibility: extractModifierVisibility(member),
+        });
       }
     }
   }

package/src/extractors/go.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { findChild, goVisibility, nodeEndLine } from './helpers.js';
 
 /**
  * Extract symbols from Go files.
@@ -22,6 +22,7 @@ export function extractGoSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: goVisibility(nameNode.text),
           });
         }
         break;
@@ -55,6 +56,7 @@ export function extractGoSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: goVisibility(nameNode.text),
           });
         }
         break;

package/src/extractors/helpers.js

@@ -9,3 +9,74 @@ export function findChild(node, type) {
   }
   return null;
 }
+
+/**
+ * Extract visibility from a node by scanning its children for modifier keywords.
+ * Works for Java, C#, PHP, and similar languages where modifiers are child nodes.
+ * @param {object} node - tree-sitter node
+ * @param {Set<string>} [modifierTypes] - node types that indicate modifiers
+ * @returns {'public'|'private'|'protected'|undefined}
+ */
+const DEFAULT_MODIFIER_TYPES = new Set([
+  'modifiers',
+  'modifier',
+  'visibility_modifier',
+  'accessibility_modifier',
+]);
+const VISIBILITY_KEYWORDS = new Set(['public', 'private', 'protected']);
+
+/**
+ * Python convention: __name → private, _name → protected, else undefined.
+ */
+export function pythonVisibility(name) {
+  if (name.startsWith('__') && name.endsWith('__')) return undefined; // dunder — public
+  if (name.startsWith('__')) return 'private';
+  if (name.startsWith('_')) return 'protected';
+  return undefined;
+}
+
+/**
+ * Go convention: uppercase first letter → public, lowercase → private.
+ */
+export function goVisibility(name) {
+  if (!name) return undefined;
+  // Strip receiver prefix (e.g., "Receiver.Method" → check "Method")
+  const bare = name.includes('.') ? name.split('.').pop() : name;
+  if (!bare) return undefined;
+  return bare[0] === bare[0].toUpperCase() && bare[0] !== bare[0].toLowerCase()
+    ? 'public'
+    : 'private';
+}
+
+/**
+ * Rust: check for `visibility_modifier` child (pub, pub(crate), etc.).
+ */
+export function rustVisibility(node) {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === 'visibility_modifier') {
+      return 'public'; // pub, pub(crate), pub(super) all mean "visible"
+    }
+  }
+  return 'private';
+}
+
+export function extractModifierVisibility(node, modifierTypes = DEFAULT_MODIFIER_TYPES) {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    // Direct keyword match (e.g., PHP visibility_modifier = "public")
+    if (modifierTypes.has(child.type)) {
+      const text = child.text;
+      if (VISIBILITY_KEYWORDS.has(text)) return text;
+      // C# 'private protected' — accessible to derived types in same assembly → protected
+      if (text === 'private protected') return 'protected';
+      // Compound modifiers node (Java: "public static") — scan its text for a keyword
+      for (const kw of VISIBILITY_KEYWORDS) {
+        if (text.includes(kw)) return kw;
+      }
+    }
+  }
+  return undefined;
+}

package/src/extractors/java.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { extractModifierVisibility, findChild, nodeEndLine } from './helpers.js';
 
 /**
  * Extract symbols from Java files.
@@ -165,6 +165,7 @@ export function extractJavaSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: extractModifierVisibility(node),
           });
         }
         break;
@@ -182,6 +183,7 @@ export function extractJavaSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: extractModifierVisibility(node),
           });
         }
         break;
@@ -267,7 +269,12 @@ function extractClassFields(classNode) {
       if (!child || child.type !== 'variable_declarator') continue;
       const nameNode = child.childForFieldName('name');
       if (nameNode) {
-        fields.push({ name: nameNode.text, kind: 'property', line: member.startPosition.row + 1 });
+        fields.push({
+          name: nameNode.text,
+          kind: 'property',
+          line: member.startPosition.row + 1,
+          visibility: extractModifierVisibility(member),
+        });
       }
     }
   }

package/src/extractors/javascript.js

@@ -77,12 +77,14 @@ function extractSymbolsQuery(tree, query) {
       const parentClass = findParentClass(c.meth_node);
       const fullName = parentClass ? `${parentClass}.${methName}` : methName;
       const methChildren = extractParameters(c.meth_node);
+      const methVis = extractVisibility(c.meth_node);
       definitions.push({
         name: fullName,
         kind: 'method',
         line: c.meth_node.startPosition.row + 1,
         endLine: nodeEndLine(c.meth_node),
         children: methChildren.length > 0 ? methChildren : undefined,
+        visibility: methVis,
       });
     } else if (c.iface_node) {
       // interface_declaration (TS/TSX only)
@@ -375,12 +377,14 @@ function extractSymbolsWalk(tree) {
           const parentClass = findParentClass(node);
           const fullName = parentClass ? `${parentClass}.${nameNode.text}` : nameNode.text;
           const methChildren = extractParameters(node);
+          const methVis = extractVisibility(node);
           definitions.push({
             name: fullName,
             kind: 'method',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: methChildren.length > 0 ? methChildren : undefined,
+            visibility: methVis,
           });
         }
         break;
@@ -701,13 +705,46 @@ function extractClassProperties(classNode) {
           nameNode.type === 'identifier' ||
           nameNode.type === 'private_property_identifier')
       ) {
-        props.push({ name: nameNode.text, kind: 'property', line: child.startPosition.row + 1 });
+        // Private # fields: nameNode.type is 'private_property_identifier'
+        // TS modifiers: accessibility_modifier child on the field_definition
+        const vis =
+          nameNode.type === 'private_property_identifier' ? 'private' : extractVisibility(child);
+        props.push({
+          name: nameNode.text,
+          kind: 'property',
+          line: child.startPosition.row + 1,
+          visibility: vis,
+        });
       }
     }
   }
   return props;
 }
 
+/**
+ * Extract visibility modifier from a class member node.
+ * Checks for TS access modifiers (public/private/protected) and JS private (#) fields.
+ * Returns 'public' | 'private' | 'protected' | undefined.
+ */
+function extractVisibility(node) {
+  // Check for TS accessibility modifiers (accessibility_modifier child)
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === 'accessibility_modifier') {
+      const text = child.text;
+      if (text === 'private' || text === 'protected' || text === 'public') return text;
+    }
+  }
+  // Check for JS private name (# prefix) — try multiple field names
+  const nameNode =
+    node.childForFieldName('name') || node.childForFieldName('property') || node.child(0);
+  if (nameNode && nameNode.type === 'private_property_identifier') {
+    return 'private';
+  }
+  return undefined;
+}
+
 function isConstantValue(valueNode) {
   if (!valueNode) return false;
   const t = valueNode.type;

package/src/extractors/php.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { extractModifierVisibility, findChild, nodeEndLine } from './helpers.js';
 
 function extractPhpParameters(fnNode) {
   const params = [];
@@ -35,6 +35,7 @@ function extractPhpClassChildren(classNode) {
             name: varNode.text,
             kind: 'property',
             line: member.startPosition.row + 1,
+            visibility: extractModifierVisibility(member),
           });
         }
       }
@@ -231,6 +232,7 @@ export function extractPHPSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: extractModifierVisibility(node),
           });
         }
         break;

package/src/extractors/python.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { findChild, nodeEndLine, pythonVisibility } from './helpers.js';
 
 /**
  * Extract symbols from Python files.
@@ -30,6 +30,7 @@ export function extractPythonSymbols(tree, _filePath) {
             endLine: nodeEndLine(node),
             decorators,
             children: fnChildren.length > 0 ? fnChildren : undefined,
+            visibility: pythonVisibility(nameNode.text),
           });
         }
         break;
@@ -209,7 +210,12 @@ export function extractPythonSymbols(tree, _filePath) {
           const left = assignment.childForFieldName('left');
           if (left && left.type === 'identifier' && !seen.has(left.text)) {
             seen.add(left.text);
-            props.push({ name: left.text, kind: 'property', line: child.startPosition.row + 1 });
+            props.push({
+              name: left.text,
+              kind: 'property',
+              line: child.startPosition.row + 1,
+              visibility: pythonVisibility(left.text),
+            });
           }
         }
       }
@@ -262,7 +268,12 @@ export function extractPythonSymbols(tree, _filePath) {
         !seen.has(attr.text)
       ) {
         seen.add(attr.text);
-        props.push({ name: attr.text, kind: 'property', line: stmt.startPosition.row + 1 });
+        props.push({
+          name: attr.text,
+          kind: 'property',
+          line: stmt.startPosition.row + 1,
+          visibility: pythonVisibility(attr.text),
+        });
       }
     }
   }

package/src/extractors/rust.js

@@ -1,4 +1,4 @@
-import { findChild, nodeEndLine } from './helpers.js';
+import { findChild, nodeEndLine, rustVisibility } from './helpers.js';
 
 /**
  * Extract symbols from Rust files.
@@ -37,6 +37,7 @@ export function extractRustSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: params.length > 0 ? params : undefined,
+            visibility: rustVisibility(node),
           });
         }
         break;
@@ -52,6 +53,7 @@ export function extractRustSymbols(tree, _filePath) {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
             children: fields.length > 0 ? fields : undefined,
+            visibility: rustVisibility(node),
           });
         }
         break;

package/src/graph/algorithms/bfs.js

@@ -0,0 +1,49 @@
+/**
+ * Breadth-first traversal on a CodeGraph.
+ *
+ * @param {import('../model.js').CodeGraph} graph
+ * @param {string|string[]} startIds - One or more starting node IDs
+ * @param {{ maxDepth?: number, direction?: 'forward'|'backward'|'both' }} [opts]
+ * @returns {Map<string, number>} nodeId → depth from nearest start node
+ */
+export function bfs(graph, startIds, opts = {}) {
+  const maxDepth = opts.maxDepth ?? Infinity;
+  const direction = opts.direction ?? 'forward';
+  const starts = Array.isArray(startIds) ? startIds : [startIds];
+
+  const depths = new Map();
+  const queue = [];
+
+  for (const id of starts) {
+    const key = String(id);
+    if (graph.hasNode(key)) {
+      depths.set(key, 0);
+      queue.push(key);
+    }
+  }
+
+  let head = 0;
+  while (head < queue.length) {
+    const current = queue[head++];
+    const depth = depths.get(current);
+    if (depth >= maxDepth) continue;
+
+    let neighbors;
+    if (direction === 'forward') {
+      neighbors = graph.successors(current);
+    } else if (direction === 'backward') {
+      neighbors = graph.predecessors(current);
+    } else {
+      neighbors = graph.neighbors(current);
+    }
+
+    for (const n of neighbors) {
+      if (!depths.has(n)) {
+        depths.set(n, depth + 1);
+        queue.push(n);
+      }
+    }
+  }
+
+  return depths;
+}

package/src/graph/algorithms/centrality.js

@@ -0,0 +1,16 @@
+/**
+ * Fan-in / fan-out centrality for all nodes in a CodeGraph.
+ *
+ * @param {import('../model.js').CodeGraph} graph
+ * @returns {Map<string, { fanIn: number, fanOut: number }>}
+ */
+export function fanInOut(graph) {
+  const result = new Map();
+  for (const id of graph.nodeIds()) {
+    result.set(id, {
+      fanIn: graph.inDegree(id),
+      fanOut: graph.outDegree(id),
+    });
+  }
+  return result;
+}

package/src/graph/algorithms/index.js

@@ -0,0 +1,5 @@
+export { bfs } from './bfs.js';
+export { fanInOut } from './centrality.js';
+export { louvainCommunities } from './louvain.js';
+export { shortestPath } from './shortest-path.js';
+export { tarjan } from './tarjan.js';

package/src/graph/algorithms/louvain.js

@@ -0,0 +1,26 @@
+/**
+ * Louvain community detection via graphology.
+ *
+ * @param {import('../model.js').CodeGraph} graph
+ * @param {{ resolution?: number }} [opts]
+ * @returns {{ assignments: Map<string, number>, modularity: number }}
+ */
+import graphologyLouvain from 'graphology-communities-louvain';
+
+export function louvainCommunities(graph, opts = {}) {
+  const gy = graph.toGraphology({ type: 'undirected' });
+
+  if (gy.order === 0 || gy.size === 0) {
+    return { assignments: new Map(), modularity: 0 };
+  }
+
+  const resolution = opts.resolution ?? 1.0;
+  const details = graphologyLouvain.detailed(gy, { resolution });
+
+  const assignments = new Map();
+  for (const [nodeId, communityId] of Object.entries(details.communities)) {
+    assignments.set(nodeId, communityId);
+  }
+
+  return { assignments, modularity: details.modularity };
+}

package/src/graph/algorithms/shortest-path.js

@@ -0,0 +1,41 @@
+/**
+ * BFS-based shortest path on a CodeGraph.
+ *
+ * @param {import('../model.js').CodeGraph} graph
+ * @param {string} fromId
+ * @param {string} toId
+ * @returns {string[]|null} Path from fromId to toId (inclusive), or null if unreachable
+ */
+export function shortestPath(graph, fromId, toId) {
+  const from = String(fromId);
+  const to = String(toId);
+
+  if (!graph.hasNode(from) || !graph.hasNode(to)) return null;
+  if (from === to) return [from];
+
+  const parent = new Map();
+  parent.set(from, null);
+  const queue = [from];
+  let head = 0;
+
+  while (head < queue.length) {
+    const current = queue[head++];
+    for (const neighbor of graph.successors(current)) {
+      if (parent.has(neighbor)) continue;
+      parent.set(neighbor, current);
+      if (neighbor === to) {
+        // Reconstruct path
+        const path = [];
+        let node = to;
+        while (node !== null) {
+          path.push(node);
+          node = parent.get(node);
+        }
+        return path.reverse();
+      }
+      queue.push(neighbor);
+    }
+  }
+
+  return null;
+}

package/src/graph/algorithms/tarjan.js

@@ -0,0 +1,49 @@
+/**
+ * Tarjan's strongly connected components algorithm.
+ * Operates on a CodeGraph instance.
+ *
+ * @param {import('../model.js').CodeGraph} graph
+ * @returns {string[][]} SCCs with length > 1 (cycles)
+ */
+export function tarjan(graph) {
+  let index = 0;
+  const stack = [];
+  const onStack = new Set();
+  const indices = new Map();
+  const lowlinks = new Map();
+  const sccs = [];
+
+  function strongconnect(v) {
+    indices.set(v, index);
+    lowlinks.set(v, index);
+    index++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of graph.successors(v)) {
+      if (!indices.has(w)) {
+        strongconnect(w);
+        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+      } else if (onStack.has(w)) {
+        lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+      }
+    }
+
+    if (lowlinks.get(v) === indices.get(v)) {
+      const scc = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        scc.push(w);
+      } while (w !== v);
+      if (scc.length > 1) sccs.push(scc);
+    }
+  }
+
+  for (const id of graph.nodeIds()) {
+    if (!indices.has(id)) strongconnect(id);
+  }
+
+  return sccs;
+}

package/src/graph/builders/dependency.js

@@ -0,0 +1,91 @@
+/**
+ * Build a CodeGraph from the SQLite database.
+ * Replaces inline graph construction in cycles.js, communities.js, viewer.js, export.js.
+ */
+
+import { getCallableNodes, getCallEdges, getFileNodesAll, getImportEdges } from '../../db.js';
+import { isTestFile } from '../../infrastructure/test-filter.js';
+import { CodeGraph } from '../model.js';
+
+/**
+ * @param {object} db - Open better-sqlite3 database (readonly)
+ * @param {object} [opts]
+ * @param {boolean} [opts.fileLevel=true] - File-level (imports) or function-level (calls)
+ * @param {boolean} [opts.noTests=false] - Exclude test files
+ * @param {number}  [opts.minConfidence] - Minimum edge confidence (function-level only)
+ * @returns {CodeGraph}
+ */
+export function buildDependencyGraph(db, opts = {}) {
+  const fileLevel = opts.fileLevel !== false;
+  const noTests = opts.noTests || false;
+
+  if (fileLevel) {
+    return buildFileLevelGraph(db, noTests);
+  }
+  return buildFunctionLevelGraph(db, noTests, opts.minConfidence);
+}
+
+function buildFileLevelGraph(db, noTests) {
+  const graph = new CodeGraph();
+
+  let nodes = getFileNodesAll(db);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+
+  const nodeIds = new Set();
+  for (const n of nodes) {
+    graph.addNode(String(n.id), { label: n.file, file: n.file, dbId: n.id });
+    nodeIds.add(n.id);
+  }
+
+  const edges = getImportEdges(db);
+  for (const e of edges) {
+    if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
+    const src = String(e.source_id);
+    const tgt = String(e.target_id);
+    if (src === tgt) continue;
+    if (!graph.hasEdge(src, tgt)) {
+      graph.addEdge(src, tgt, { kind: 'imports' });
+    }
+  }
+
+  return graph;
+}
+
+function buildFunctionLevelGraph(db, noTests, minConfidence) {
+  const graph = new CodeGraph();
+
+  let nodes = getCallableNodes(db);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+
+  const nodeIds = new Set();
+  for (const n of nodes) {
+    graph.addNode(String(n.id), {
+      label: n.name,
+      file: n.file,
+      kind: n.kind,
+      dbId: n.id,
+    });
+    nodeIds.add(n.id);
+  }
+
+  let edges;
+  if (minConfidence != null) {
+    edges = db
+      .prepare("SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?")
+      .all(minConfidence);
+  } else {
+    edges = getCallEdges(db);
+  }
+
+  for (const e of edges) {
+    if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
+    const src = String(e.source_id);
+    const tgt = String(e.target_id);
+    if (src === tgt) continue;
+    if (!graph.hasEdge(src, tgt)) {
+      graph.addEdge(src, tgt, { kind: 'calls' });
+    }
+  }
+
+  return graph;
+}

package/src/graph/builders/index.js

@@ -0,0 +1,3 @@
+export { buildDependencyGraph } from './dependency.js';
+export { buildStructureGraph } from './structure.js';
+export { buildTemporalGraph } from './temporal.js';

package/src/graph/builders/structure.js

@@ -0,0 +1,40 @@
+/**
+ * Build a containment graph (directory → file) from the SQLite database.
+ */
+
+import { CodeGraph } from '../model.js';
+
+/**
+ * @param {object} db - Open better-sqlite3 database (readonly)
+ * @returns {CodeGraph} Directed graph with directory→file containment edges
+ */
+export function buildStructureGraph(db) {
+  const graph = new CodeGraph();
+
+  const dirs = db.prepare("SELECT id, name FROM nodes WHERE kind = 'directory'").all();
+
+  for (const d of dirs) {
+    graph.addNode(String(d.id), { label: d.name, kind: 'directory' });
+  }
+
+  const files = db.prepare("SELECT id, name, file FROM nodes WHERE kind = 'file'").all();
+
+  for (const f of files) {
+    graph.addNode(String(f.id), { label: f.name, kind: 'file', file: f.file });
+  }
+
+  const containsEdges = db
+    .prepare(`
+      SELECT e.source_id, e.target_id
+      FROM edges e
+      JOIN nodes n ON e.source_id = n.id
+      WHERE e.kind = 'contains' AND n.kind = 'directory'
+    `)
+    .all();
+
+  for (const e of containsEdges) {
+    graph.addEdge(String(e.source_id), String(e.target_id), { kind: 'contains' });
+  }
+
+  return graph;
+}