@optave/codegraph 2.6.0 → 3.0.0

package/src/paginate.js

@@ -9,17 +9,16 @@
 export const MCP_DEFAULTS = {
   // Existing
   list_functions: 100,
-  query_function: 50,
+  query: 10,
   where: 50,
   node_roles: 100,
-  list_entry_points: 100,
   export_graph: 500,
   // Smaller defaults for rich/nested results
-  fn_deps: 10,
   fn_impact: 5,
   context: 5,
   explain: 10,
   file_deps: 20,
+  file_exports: 20,
   diff_impact: 30,
   impact_analysis: 20,
   semantic_search: 20,
@@ -31,6 +30,7 @@ export const MCP_DEFAULTS = {
   communities: 20,
   structure: 30,
   triage: 20,
+  ast_query: 50,
 };
 
 /** Hard cap to prevent abuse via MCP. */

package/src/parser.js

@@ -142,6 +142,14 @@ function normalizeNativeSymbols(result) {
             maintainabilityIndex: d.complexity.maintainabilityIndex ?? null,
           }
         : null,
+      children: d.children?.length
+        ? d.children.map((c) => ({
+            name: c.name,
+            kind: c.kind,
+            line: c.line,
+            endLine: c.endLine ?? c.end_line ?? null,
+          }))
+        : undefined,
     })),
     calls: (result.calls || []).map((c) => ({
       name: c.name,

package/src/queries.js

@@ -59,7 +59,9 @@ export const FALSE_POSITIVE_NAMES = new Set([
 export const FALSE_POSITIVE_CALLER_THRESHOLD = 20;
 
 const FUNCTION_KINDS = ['function', 'method', 'class'];
-export const ALL_SYMBOL_KINDS = [
+
+// Original 10 kinds — used as default query scope
+export const CORE_SYMBOL_KINDS = [
   'function',
   'method',
   'class',
@@ -72,6 +74,39 @@ export const ALL_SYMBOL_KINDS = [
   'module',
 ];
 
+// Sub-declaration kinds (Phase 1)
+export const EXTENDED_SYMBOL_KINDS = [
+  'parameter',
+  'property',
+  'constant',
+  // Phase 2 (reserved, not yet extracted):
+  // 'constructor', 'namespace', 'decorator', 'getter', 'setter',
+];
+
+// Full set for --kind validation and MCP enum
+export const EVERY_SYMBOL_KIND = [...CORE_SYMBOL_KINDS, ...EXTENDED_SYMBOL_KINDS];
+
+// Backward compat: ALL_SYMBOL_KINDS stays as the core 10
+export const ALL_SYMBOL_KINDS = CORE_SYMBOL_KINDS;
+
+// ── Edge kind constants ─────────────────────────────────────────────
+// Core edge kinds — coupling and dependency relationships
+export const CORE_EDGE_KINDS = [
+  'imports',
+  'imports-type',
+  'reexports',
+  'calls',
+  'extends',
+  'implements',
+  'contains',
+];
+
+// Structural edge kinds — parent/child and type relationships
+export const STRUCTURAL_EDGE_KINDS = ['parameter_of', 'receiver'];
+
+// Full set for MCP enum and validation
+export const EVERY_EDGE_KIND = [...CORE_EDGE_KINDS, ...STRUCTURAL_EDGE_KINDS];
+
 export const VALID_ROLES = ['entry', 'core', 'utility', 'adapter', 'dead', 'leaf'];
 
 /**
@@ -190,6 +225,12 @@ export function kindIcon(kind) {
       return 'I';
     case 'type':
       return 'T';
+    case 'parameter':
+      return 'p';
+    case 'property':
+      return '.';
+    case 'constant':
+      return 'C';
     default:
       return '-';
   }
@@ -207,6 +248,7 @@ export function queryNameData(name, customDbPath, opts = {}) {
     return { query: name, results: [] };
   }
 
+  const hc = new Map();
   const results = nodes.map((node) => {
     let callees = db
       .prepare(`
@@ -230,10 +272,7 @@ export function queryNameData(name, customDbPath, opts = {}) {
     }
 
     return {
-      name: node.name,
-      kind: node.kind,
-      file: node.file,
-      line: node.line,
+      ...normalizeSymbol(node, db, hc),
       callees: callees.map((c) => ({
         name: c.name,
         kind: c.kind,
@@ -327,12 +366,12 @@ export function moduleMapData(customDbPath, limit = 20, opts = {}) {
   const nodes = db
     .prepare(`
     SELECT n.*,
-      (SELECT COUNT(*) FROM edges WHERE source_id = n.id AND kind != 'contains') as out_edges,
-      (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind != 'contains') as in_edges
+      (SELECT COUNT(*) FROM edges WHERE source_id = n.id AND kind NOT IN ('contains', 'parameter_of', 'receiver')) as out_edges,
+      (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind NOT IN ('contains', 'parameter_of', 'receiver')) as in_edges
     FROM nodes n
     WHERE n.kind = 'file'
       ${testFilter}
-    ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind != 'contains') DESC
+    ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind NOT IN ('contains', 'parameter_of', 'receiver')) DESC
     LIMIT ?
   `)
     .all(limit);
@@ -402,6 +441,7 @@ export function fnDepsData(name, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   const depth = opts.depth || 3;
   const noTests = opts.noTests || false;
+  const hc = new Map();
 
   const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
@@ -493,10 +533,7 @@ export function fnDepsData(name, customDbPath, opts = {}) {
     }
 
     return {
-      name: node.name,
-      kind: node.kind,
-      file: node.file,
-      line: node.line,
+      ...normalizeSymbol(node, db, hc),
       callees: filteredCallees.map((c) => ({
         name: c.name,
         kind: c.kind,
@@ -523,6 +560,7 @@ export function fnImpactData(name, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   const maxDepth = opts.depth || 5;
   const noTests = opts.noTests || false;
+  const hc = new Map();
 
   const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
@@ -559,10 +597,7 @@ export function fnImpactData(name, customDbPath, opts = {}) {
     }
 
     return {
-      name: node.name,
-      kind: node.kind,
-      file: node.file,
-      line: node.line,
+      ...normalizeSymbol(node, db, hc),
       levels,
       totalDependents: visited.size - 1,
     };
@@ -1194,14 +1229,16 @@ export function listFunctionsData(customDbPath, opts = {}) {
 
   let rows = db
     .prepare(
-      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
+      `SELECT name, kind, file, line, end_line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
     )
     .all(...params);
 
   if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
 
+  const hc = new Map();
+  const functions = rows.map((r) => normalizeSymbol(r, db, hc));
   db.close();
-  const base = { count: rows.length, functions: rows };
+  const base = { count: functions.length, functions };
   return paginateResult(base, 'functions', { limit: opts.limit, offset: opts.offset });
 }
 
@@ -1234,11 +1271,18 @@ export function* iterListFunctions(customDbPath, opts = {}) {
     }
 
     const stmt = db.prepare(
-      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
+      `SELECT name, kind, file, line, end_line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
     );
     for (const row of stmt.iterate(...params)) {
       if (noTests && isTestFile(row.file)) continue;
-      yield { name: row.name, kind: row.kind, file: row.file, line: row.line, role: row.role };
+      yield {
+        name: row.name,
+        kind: row.kind,
+        file: row.file,
+        line: row.line,
+        endLine: row.end_line ?? null,
+        role: row.role ?? null,
+      };
     }
   } finally {
     db.close();
@@ -1252,7 +1296,7 @@ export function* iterListFunctions(customDbPath, opts = {}) {
  * @param {boolean} [opts.noTests]
  * @param {string} [opts.role]
  * @param {string} [opts.file]
- * @yields {{ name: string, kind: string, file: string, line: number, role: string }}
+ * @yields {{ name: string, kind: string, file: string, line: number, endLine: number|null, role: string }}
  */
 export function* iterRoles(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
@@ -1271,11 +1315,18 @@ export function* iterRoles(customDbPath, opts = {}) {
     }
 
     const stmt = db.prepare(
-      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
+      `SELECT name, kind, file, line, end_line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
     );
     for (const row of stmt.iterate(...params)) {
       if (noTests && isTestFile(row.file)) continue;
-      yield { name: row.name, kind: row.kind, file: row.file, line: row.line, role: row.role };
+      yield {
+        name: row.name,
+        kind: row.kind,
+        file: row.file,
+        line: row.line,
+        endLine: row.end_line ?? null,
+        role: row.role ?? null,
+      };
     }
   } finally {
     db.close();
@@ -2214,6 +2265,17 @@ export function contextData(name, customDbPath, opts = {}) {
       /* table may not exist */
     }
 
+    // Children (parameters, properties, constants)
+    let nodeChildren = [];
+    try {
+      nodeChildren = db
+        .prepare('SELECT name, kind, line, end_line FROM nodes WHERE parent_id = ? ORDER BY line')
+        .all(node.id)
+        .map((c) => ({ name: c.name, kind: c.kind, line: c.line, endLine: c.end_line || null }));
+    } catch {
+      /* parent_id column may not exist */
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -2224,6 +2286,7 @@ export function contextData(name, customDbPath, opts = {}) {
       source,
       signature,
       complexity: complexityMetrics,
+      children: nodeChildren.length > 0 ? nodeChildren : undefined,
       callees,
       callers,
       relatedTests,
@@ -2263,6 +2326,15 @@ export function context(name, customDbPath, opts = {}) {
       console.log();
     }
 
+    // Children
+    if (r.children && r.children.length > 0) {
+      console.log(`## Children (${r.children.length})`);
+      for (const c of r.children) {
+        console.log(`  ${kindIcon(c.kind)} ${c.name}  :${c.line}`);
+      }
+      console.log();
+    }
+
     // Complexity
     if (r.complexity) {
       const cx = r.complexity;
@@ -2335,6 +2407,69 @@ export function context(name, customDbPath, opts = {}) {
   }
 }
 
+// ─── childrenData ───────────────────────────────────────────────────────
+
+export function childrenData(name, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+
+  const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
+  if (nodes.length === 0) {
+    db.close();
+    return { name, results: [] };
+  }
+
+  const results = nodes.map((node) => {
+    let children;
+    try {
+      children = db
+        .prepare('SELECT name, kind, line, end_line FROM nodes WHERE parent_id = ? ORDER BY line')
+        .all(node.id);
+    } catch {
+      children = [];
+    }
+    if (noTests) children = children.filter((c) => !isTestFile(c.file || node.file));
+    return {
+      name: node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.line,
+      children: children.map((c) => ({
+        name: c.name,
+        kind: c.kind,
+        line: c.line,
+        endLine: c.end_line || null,
+      })),
+    };
+  });
+
+  db.close();
+  const base = { name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
+}
+
+export function children(name, customDbPath, opts = {}) {
+  const data = childrenData(name, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (data.results.length === 0) {
+    console.log(`No symbol matching "${name}"`);
+    return;
+  }
+  for (const r of data.results) {
+    console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}`);
+    if (r.children.length === 0) {
+      console.log('  (no children)');
+    } else {
+      for (const c of r.children) {
+        console.log(`  ${kindIcon(c.kind)} ${c.name}  :${c.line}`);
+      }
+    }
+  }
+}
+
 // ─── explainData ────────────────────────────────────────────────────────
 
 function isFileLikeTarget(target) {
@@ -2457,6 +2592,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
   if (nodes.length === 0) return [];
 
+  const hc = new Map();
   return nodes.slice(0, 10).map((node) => {
     const fileLines = getFileLines(node.file);
     const lineCount = node.end_line ? node.end_line - node.line + 1 : null;
@@ -2514,12 +2650,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
     }
 
     return {
-      name: node.name,
-      kind: node.kind,
-      file: node.file,
-      line: node.line,
-      role: node.role || null,
-      endLine: node.end_line || null,
+      ...normalizeSymbol(node, db, hc),
       lineCount,
       summary,
       signature,
@@ -2732,6 +2863,41 @@ export function explain(target, customDbPath, opts = {}) {
 
 // ─── whereData ──────────────────────────────────────────────────────────
 
+function getFileHash(db, file) {
+  const row = db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file);
+  return row ? row.hash : null;
+}
+
+/**
+ * Normalize a raw DB/query row into the stable 7-field symbol shape.
+ * @param {object} row    - Raw row (from SELECT * or explicit columns)
+ * @param {object} [db]   - Open DB handle; when null, fileHash will be null
+ * @param {Map}    [hashCache] - Optional per-file cache to avoid repeated getFileHash calls
+ * @returns {{ name: string, kind: string, file: string, line: number, endLine: number|null, role: string|null, fileHash: string|null }}
+ */
+export function normalizeSymbol(row, db, hashCache) {
+  let fileHash = null;
+  if (db) {
+    if (hashCache) {
+      if (!hashCache.has(row.file)) {
+        hashCache.set(row.file, getFileHash(db, row.file));
+      }
+      fileHash = hashCache.get(row.file);
+    } else {
+      fileHash = getFileHash(db, row.file);
+    }
+  }
+  return {
+    name: row.name,
+    kind: row.kind,
+    file: row.file,
+    line: row.line,
+    endLine: row.end_line ?? row.endLine ?? null,
+    role: row.role ?? null,
+    fileHash,
+  };
+}
+
 function whereSymbolImpl(db, target, noTests) {
   const placeholders = ALL_SYMBOL_KINDS.map(() => '?').join(', ');
   let nodes = db
@@ -2741,6 +2907,7 @@ function whereSymbolImpl(db, target, noTests) {
     .all(`%${target}%`, ...ALL_SYMBOL_KINDS);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
+  const hc = new Map();
   return nodes.map((node) => {
     const crossFileCallers = db
       .prepare(
@@ -2759,11 +2926,7 @@ function whereSymbolImpl(db, target, noTests) {
     if (noTests) uses = uses.filter((u) => !isTestFile(u.file));
 
     return {
-      name: node.name,
-      kind: node.kind,
-      file: node.file,
-      line: node.line,
-      role: node.role || null,
+      ...normalizeSymbol(node, db, hc),
       exported,
       uses: uses.map((u) => ({ name: u.name, file: u.file, line: u.line })),
     };
@@ -2813,6 +2976,7 @@ function whereFileImpl(db, target) {
 
     return {
       file: fn.file,
+      fileHash: getFileHash(db, fn.file),
       symbols: symbols.map((s) => ({ name: s.name, kind: s.kind, line: s.line })),
       imports,
       importedBy,
@@ -2908,7 +3072,7 @@ export function rolesData(customDbPath, opts = {}) {
 
   let rows = db
     .prepare(
-      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
+      `SELECT name, kind, file, line, end_line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
     )
     .all(...params);
 
@@ -2919,8 +3083,10 @@ export function rolesData(customDbPath, opts = {}) {
     summary[r.role] = (summary[r.role] || 0) + 1;
   }
 
+  const hc = new Map();
+  const symbols = rows.map((r) => normalizeSymbol(r, db, hc));
   db.close();
-  const base = { count: rows.length, summary, symbols: rows };
+  const base = { count: symbols.length, summary, symbols };
   return paginateResult(base, 'symbols', { limit: opts.limit, offset: opts.offset });
 }
 
@@ -2966,6 +3132,166 @@ export function roles(customDbPath, opts = {}) {
   }
 }
 
+// ─── exportsData ─────────────────────────────────────────────────────
+
+function exportsFileImpl(db, target, noTests, getFileLines) {
+  const fileNodes = db
+    .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
+    .all(`%${target}%`);
+  if (fileNodes.length === 0) return [];
+
+  return fileNodes.map((fn) => {
+    const symbols = db
+      .prepare(`SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line`)
+      .all(fn.file);
+
+    // IDs of symbols that have incoming calls from other files (exported)
+    const exportedIds = new Set(
+      db
+        .prepare(
+          `SELECT DISTINCT e.target_id FROM edges e
+           JOIN nodes caller ON e.source_id = caller.id
+           JOIN nodes target ON e.target_id = target.id
+           WHERE target.file = ? AND caller.file != ? AND e.kind = 'calls'`,
+        )
+        .all(fn.file, fn.file)
+        .map((r) => r.target_id),
+    );
+
+    const exported = symbols.filter((s) => exportedIds.has(s.id));
+    const internalCount = symbols.length - exported.length;
+
+    const results = exported.map((s) => {
+      const fileLines = getFileLines(fn.file);
+
+      let consumers = db
+        .prepare(
+          `SELECT n.name, n.file, n.line FROM edges e JOIN nodes n ON e.source_id = n.id
+           WHERE e.target_id = ? AND e.kind = 'calls'`,
+        )
+        .all(s.id);
+      if (noTests) consumers = consumers.filter((c) => !isTestFile(c.file));
+
+      return {
+        name: s.name,
+        kind: s.kind,
+        line: s.line,
+        endLine: s.end_line ?? null,
+        role: s.role || null,
+        signature: fileLines ? extractSignature(fileLines, s.line) : null,
+        summary: fileLines ? extractSummary(fileLines, s.line) : null,
+        consumers: consumers.map((c) => ({ name: c.name, file: c.file, line: c.line })),
+        consumerCount: consumers.length,
+      };
+    });
+
+    // Files that re-export this file (barrel → this file)
+    const reexports = db
+      .prepare(
+        `SELECT DISTINCT n.file FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind = 'reexports'`,
+      )
+      .all(fn.id)
+      .map((r) => ({ file: r.file }));
+
+    return {
+      file: fn.file,
+      results,
+      reexports,
+      totalExported: exported.length,
+      totalInternal: internalCount,
+    };
+  });
+}
+
+export function exportsData(file, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+
+  const dbFilePath = findDbPath(customDbPath);
+  const repoRoot = path.resolve(path.dirname(dbFilePath), '..');
+
+  const fileCache = new Map();
+  function getFileLines(file) {
+    if (fileCache.has(file)) return fileCache.get(file);
+    try {
+      const absPath = safePath(repoRoot, file);
+      if (!absPath) {
+        fileCache.set(file, null);
+        return null;
+      }
+      const lines = fs.readFileSync(absPath, 'utf-8').split('\n');
+      fileCache.set(file, lines);
+      return lines;
+    } catch {
+      fileCache.set(file, null);
+      return null;
+    }
+  }
+
+  const fileResults = exportsFileImpl(db, file, noTests, getFileLines);
+  db.close();
+
+  if (fileResults.length === 0) {
+    return paginateResult(
+      { file, results: [], reexports: [], totalExported: 0, totalInternal: 0 },
+      'results',
+      { limit: opts.limit, offset: opts.offset },
+    );
+  }
+
+  // For single-file match return flat; for multi-match return first (like explainData)
+  const first = fileResults[0];
+  const base = {
+    file: first.file,
+    results: first.results,
+    reexports: first.reexports,
+    totalExported: first.totalExported,
+    totalInternal: first.totalInternal,
+  };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
+}
+
+export function fileExports(file, customDbPath, opts = {}) {
+  const data = exportsData(file, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (data.results.length === 0) {
+    console.log(`No exported symbols found for "${file}". Run "codegraph build" first.`);
+    return;
+  }
+
+  console.log(
+    `\n# ${data.file} — ${data.totalExported} exported, ${data.totalInternal} internal\n`,
+  );
+
+  for (const sym of data.results) {
+    const icon = kindIcon(sym.kind);
+    const sig = sym.signature?.params ? `(${sym.signature.params})` : '';
+    const role = sym.role ? ` [${sym.role}]` : '';
+    console.log(`  ${icon} ${sym.name}${sig}${role} :${sym.line}`);
+    if (sym.consumers.length === 0) {
+      console.log('    (no consumers)');
+    } else {
+      for (const c of sym.consumers) {
+        console.log(`    <- ${c.name} (${c.file}:${c.line})`);
+      }
+    }
+  }
+
+  if (data.reexports.length > 0) {
+    console.log(`\n  Re-exports: ${data.reexports.map((r) => r.file).join(', ')}`);
+  }
+  console.log();
+}
+
 export function fnImpact(name, customDbPath, opts = {}) {
   const data = fnImpactData(name, customDbPath, opts);
   if (opts.ndjson) {

package/src/structure.js

@@ -34,8 +34,11 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
   `);
 
   // Clean previous directory nodes/edges (idempotent rebuild)
+  // Scope contains-edge delete to directory-sourced edges only,
+  // preserving symbol-level contains edges (file→def, class→method, etc.)
   db.exec(`
-    DELETE FROM edges WHERE kind = 'contains';
+    DELETE FROM edges WHERE kind = 'contains'
+      AND source_id IN (SELECT id FROM nodes WHERE kind = 'directory');
     DELETE FROM node_metrics;
     DELETE FROM nodes WHERE kind = 'directory';
   `);