@optave/codegraph 2.3.0 → 2.3.1-dev.1aeea34

package/src/parser.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Language, Parser } from 'web-tree-sitter';
+import { Language, Parser, Query } from 'web-tree-sitter';
 import { warn } from './logger.js';
 import { getNative, loadNative } from './native.js';
 
@@ -38,6 +38,33 @@ function grammarPath(name) {
 
 let _initialized = false;
 
+// Query cache for JS/TS/TSX extractors (populated during createParsers)
+const _queryCache = new Map();
+
+// Shared patterns for all JS/TS/TSX (class_declaration excluded — name type differs)
+const COMMON_QUERY_PATTERNS = [
+  '(function_declaration name: (identifier) @fn_name) @fn_node',
+  '(variable_declarator name: (identifier) @varfn_name value: (arrow_function) @varfn_value)',
+  '(variable_declarator name: (identifier) @varfn_name value: (function_expression) @varfn_value)',
+  '(method_definition name: (property_identifier) @meth_name) @meth_node',
+  '(import_statement source: (string) @imp_source) @imp_node',
+  '(export_statement) @exp_node',
+  '(call_expression function: (identifier) @callfn_name) @callfn_node',
+  '(call_expression function: (member_expression) @callmem_fn) @callmem_node',
+  '(call_expression function: (subscript_expression) @callsub_fn) @callsub_node',
+  '(expression_statement (assignment_expression left: (member_expression) @assign_left right: (_) @assign_right)) @assign_node',
+];
+
+// JS: class name is (identifier)
+const JS_CLASS_PATTERN = '(class_declaration name: (identifier) @cls_name) @cls_node';
+
+// TS/TSX: class name is (type_identifier), plus interface and type alias
+const TS_EXTRA_PATTERNS = [
+  '(class_declaration name: (type_identifier) @cls_name) @cls_node',
+  '(interface_declaration name: (type_identifier) @iface_name) @iface_node',
+  '(type_alias_declaration name: (type_identifier) @type_name) @type_node',
+];
+
 export async function createParsers() {
   if (!_initialized) {
     await Parser.init();
@@ -51,6 +78,14 @@ export async function createParsers() {
       const parser = new Parser();
       parser.setLanguage(lang);
       parsers.set(entry.id, parser);
+      // Compile and cache tree-sitter Query for JS/TS/TSX extractors
+      if (entry.extractor === extractSymbols && !_queryCache.has(entry.id)) {
+        const isTS = entry.id === 'typescript' || entry.id === 'tsx';
+        const patterns = isTS
+          ? [...COMMON_QUERY_PATTERNS, ...TS_EXTRA_PATTERNS]
+          : [...COMMON_QUERY_PATTERNS, JS_CLASS_PATTERN];
+        _queryCache.set(entry.id, new Query(lang, patterns.join('\n')));
+      }
     } catch (e) {
       if (entry.required) throw e;
       warn(
@@ -242,7 +277,9 @@ function wasmExtractSymbols(parsers, filePath, code) {
 
   const ext = path.extname(filePath);
   const entry = _extToLang.get(ext);
-  return entry ? entry.extractor(tree, filePath) : null;
+  if (!entry) return null;
+  const query = _queryCache.get(entry.id) || null;
+  return entry.extractor(tree, filePath, query);
 }
 
 /**

package/src/queries.js

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { coChangeForFiles } from './cochange.js';
 import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
@@ -67,6 +68,8 @@ export const ALL_SYMBOL_KINDS = [
   'module',
 ];
 
+export const VALID_ROLES = ['entry', 'core', 'utility', 'adapter', 'dead', 'leaf'];
+
 /**
  * Get all ancestor class names for a given class using extends edges.
  */
@@ -728,16 +731,34 @@ export function diffImpactData(customDbPath, opts = {}) {
   const affectedFiles = new Set();
   for (const key of allAffected) affectedFiles.add(key.split(':')[0]);
 
+  // Look up historically coupled files from co-change data
+  let historicallyCoupled = [];
+  try {
+    db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
+    const changedFilesList = [...changedRanges.keys()];
+    const coResults = coChangeForFiles(changedFilesList, db, {
+      minJaccard: 0.3,
+      limit: 20,
+      noTests,
+    });
+    // Exclude files already found via static analysis
+    historicallyCoupled = coResults.filter((r) => !affectedFiles.has(r.file));
+  } catch {
+    /* co_changes table doesn't exist — skip silently */
+  }
+
   db.close();
   return {
     changedFiles: changedRanges.size,
     newFiles: [...newFiles],
     affectedFunctions: functionResults,
     affectedFiles: [...affectedFiles],
+    historicallyCoupled,
     summary: {
       functionsChanged: affectedFunctions.length,
       callersAffected: allAffected.size,
       filesAffected: affectedFiles.size,
+      historicallyCoupledCount: historicallyCoupled.length,
     },
   };
 }
@@ -876,7 +897,7 @@ export function listFunctionsData(customDbPath, opts = {}) {
 
   let rows = db
     .prepare(
-      `SELECT name, kind, file, line FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
+      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
     )
     .all(...params);
 
@@ -1077,6 +1098,22 @@ export function statsData(customDbPath, opts = {}) {
     falsePositiveWarnings,
   };
 
+  // Role distribution
+  let roleRows;
+  if (noTests) {
+    const allRoleNodes = db.prepare('SELECT role, file FROM nodes WHERE role IS NOT NULL').all();
+    const filtered = allRoleNodes.filter((n) => !isTestFile(n.file));
+    const counts = {};
+    for (const n of filtered) counts[n.role] = (counts[n.role] || 0) + 1;
+    roleRows = Object.entries(counts).map(([role, c]) => ({ role, c }));
+  } else {
+    roleRows = db
+      .prepare('SELECT role, COUNT(*) as c FROM nodes WHERE role IS NOT NULL GROUP BY role')
+      .all();
+  }
+  const roles = {};
+  for (const r of roleRows) roles[r.role] = r.c;
+
   db.close();
   return {
     nodes: { total: totalNodes, byKind: nodesByKind },
@@ -1086,6 +1123,7 @@ export function statsData(customDbPath, opts = {}) {
     hotspots,
     embeddings,
     quality,
+    roles,
   };
 }
 
@@ -1182,6 +1220,22 @@ export function stats(customDbPath, opts = {}) {
     }
   }
 
+  // Roles
+  if (data.roles && Object.keys(data.roles).length > 0) {
+    const total = Object.values(data.roles).reduce((a, b) => a + b, 0);
+    console.log(`\nRoles:     ${total} classified symbols`);
+    const roleParts = Object.entries(data.roles)
+      .sort((a, b) => b[1] - a[1])
+      .map(([k, v]) => `${k} ${v}`);
+    for (let i = 0; i < roleParts.length; i += 3) {
+      const row = roleParts
+        .slice(i, i + 3)
+        .map((p) => p.padEnd(18))
+        .join('');
+      console.log(`  ${row}`);
+    }
+  }
+
   console.log();
 }
 
@@ -1649,6 +1703,7 @@ export function contextData(name, customDbPath, opts = {}) {
       kind: node.kind,
       file: node.file,
       line: node.line,
+      role: node.role || null,
       endLine: node.end_line || null,
       source,
       signature,
@@ -1675,7 +1730,8 @@ export function context(name, customDbPath, opts = {}) {
 
   for (const r of data.results) {
     const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
-    console.log(`\n# ${r.name} (${r.kind}) — ${r.file}:${lineRange}\n`);
+    const roleTag = r.role ? ` [${r.role}]` : '';
+    console.log(`\n# ${r.name} (${r.kind})${roleTag} — ${r.file}:${lineRange}\n`);
 
     // Signature
     if (r.signature) {
@@ -1787,6 +1843,7 @@ function explainFileImpl(db, target, getFileLines) {
       name: s.name,
       kind: s.kind,
       line: s.line,
+      role: s.role || null,
       summary: fileLines ? extractSummary(fileLines, s.line) : null,
       signature: fileLines ? extractSignature(fileLines, s.line) : null,
     });
@@ -1907,6 +1964,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
       kind: node.kind,
       file: node.file,
       line: node.line,
+      role: node.role || null,
       endLine: node.end_line || null,
       lineCount,
       summary,
@@ -2018,8 +2076,9 @@ export function explain(target, customDbPath, opts = {}) {
         console.log(`\n## Exported`);
         for (const s of r.publicApi) {
           const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
+          const roleTag = s.role ? ` [${s.role}]` : '';
           const summary = s.summary ? `  -- ${s.summary}` : '';
-          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig} :${s.line}${summary}`);
+          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig}${roleTag} :${s.line}${summary}`);
         }
       }
 
@@ -2027,8 +2086,9 @@ export function explain(target, customDbPath, opts = {}) {
         console.log(`\n## Internal`);
         for (const s of r.internal) {
           const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
+          const roleTag = s.role ? ` [${s.role}]` : '';
           const summary = s.summary ? `  -- ${s.summary}` : '';
-          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig} :${s.line}${summary}`);
+          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig}${roleTag} :${s.line}${summary}`);
         }
       }
 
@@ -2045,9 +2105,10 @@ export function explain(target, customDbPath, opts = {}) {
       const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
       const lineInfo = r.lineCount ? `${r.lineCount} lines` : '';
       const summaryPart = r.summary ? ` | ${r.summary}` : '';
+      const roleTag = r.role ? ` [${r.role}]` : '';
       const depthLevel = r._depth || 0;
       const heading = depthLevel === 0 ? '#' : '##'.padEnd(depthLevel + 2, '#');
-      console.log(`\n${indent}${heading} ${r.name} (${r.kind})  ${r.file}:${lineRange}`);
+      console.log(`\n${indent}${heading} ${r.name} (${r.kind})${roleTag}  ${r.file}:${lineRange}`);
       if (lineInfo || r.summary) {
         console.log(`${indent}  ${lineInfo}${summaryPart}`);
       }
@@ -2134,6 +2195,7 @@ function whereSymbolImpl(db, target, noTests) {
       kind: node.kind,
       file: node.file,
       line: node.line,
+      role: node.role || null,
       exported,
       uses: uses.map((u) => ({ name: u.name, file: u.file, line: u.line })),
     };
@@ -2220,8 +2282,9 @@ export function where(target, customDbPath, opts = {}) {
 
   if (data.mode === 'symbol') {
     for (const r of data.results) {
+      const roleTag = r.role ? ` [${r.role}]` : '';
       const tag = r.exported ? '  (exported)' : '';
-      console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}${tag}`);
+      console.log(`\n${kindIcon(r.kind)} ${r.name}${roleTag}  ${r.file}:${r.line}${tag}`);
       if (r.uses.length > 0) {
         const useStrs = r.uses.map((u) => `${u.file}:${u.line}`);
         console.log(`  Used in: ${useStrs.join(', ')}`);
@@ -2250,6 +2313,81 @@ export function where(target, customDbPath, opts = {}) {
   console.log();
 }
 
+// ─── rolesData ──────────────────────────────────────────────────────────
+
+export function rolesData(customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+  const filterRole = opts.role || null;
+  const filterFile = opts.file || null;
+
+  const conditions = ['role IS NOT NULL'];
+  const params = [];
+
+  if (filterRole) {
+    conditions.push('role = ?');
+    params.push(filterRole);
+  }
+  if (filterFile) {
+    conditions.push('file LIKE ?');
+    params.push(`%${filterFile}%`);
+  }
+
+  let rows = db
+    .prepare(
+      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
+    )
+    .all(...params);
+
+  if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
+
+  const summary = {};
+  for (const r of rows) {
+    summary[r.role] = (summary[r.role] || 0) + 1;
+  }
+
+  db.close();
+  return { count: rows.length, summary, symbols: rows };
+}
+
+export function roles(customDbPath, opts = {}) {
+  const data = rolesData(customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (data.count === 0) {
+    console.log('No classified symbols found. Run "codegraph build" first.');
+    return;
+  }
+
+  const total = data.count;
+  console.log(`\nNode roles (${total} symbols):\n`);
+
+  const summaryParts = Object.entries(data.summary)
+    .sort((a, b) => b[1] - a[1])
+    .map(([role, count]) => `${role}: ${count}`);
+  console.log(`  ${summaryParts.join('  ')}\n`);
+
+  const byRole = {};
+  for (const s of data.symbols) {
+    if (!byRole[s.role]) byRole[s.role] = [];
+    byRole[s.role].push(s);
+  }
+
+  for (const [role, symbols] of Object.entries(byRole)) {
+    console.log(`## ${role} (${symbols.length})`);
+    for (const s of symbols.slice(0, 30)) {
+      console.log(`  ${kindIcon(s.kind)} ${s.name}  ${s.file}:${s.line}`);
+    }
+    if (symbols.length > 30) {
+      console.log(`  ... and ${symbols.length - 30} more`);
+    }
+    console.log();
+  }
+}
+
 export function fnImpact(name, customDbPath, opts = {}) {
   const data = fnImpactData(name, customDbPath, opts);
   if (opts.json) {
@@ -2309,9 +2447,20 @@ export function diffImpact(customDbPath, opts = {}) {
     console.log(`  ${kindIcon(fn.kind)} ${fn.name} -- ${fn.file}:${fn.line}`);
     if (fn.transitiveCallers > 0) console.log(`    ^ ${fn.transitiveCallers} transitive callers`);
   }
+  if (data.historicallyCoupled && data.historicallyCoupled.length > 0) {
+    console.log('\n  Historically coupled (not in static graph):\n');
+    for (const c of data.historicallyCoupled) {
+      const pct = `${(c.jaccard * 100).toFixed(0)}%`;
+      console.log(
+        `    ${c.file}  <- coupled with ${c.coupledWith} (${pct}, ${c.commitCount} commits)`,
+      );
+    }
+  }
   if (data.summary) {
-    console.log(
-      `\n  Summary: ${data.summary.functionsChanged} functions changed -> ${data.summary.callersAffected} callers affected across ${data.summary.filesAffected} files\n`,
-    );
+    let summaryLine = `\n  Summary: ${data.summary.functionsChanged} functions changed -> ${data.summary.callersAffected} callers affected across ${data.summary.filesAffected} files`;
+    if (data.summary.historicallyCoupledCount > 0) {
+      summaryLine += `, ${data.summary.historicallyCoupledCount} historically coupled`;
+    }
+    console.log(`${summaryLine}\n`);
   }
 }

package/src/registry.js

@@ -136,12 +136,20 @@ export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
  * or that haven't been accessed within `ttlDays` days.
  * Returns an array of `{ name, path, reason }` for each pruned entry.
  */
-export function pruneRegistry(registryPath = REGISTRY_PATH, ttlDays = DEFAULT_TTL_DAYS) {
+export function pruneRegistry(
+  registryPath = REGISTRY_PATH,
+  ttlDays = DEFAULT_TTL_DAYS,
+  excludeNames = [],
+) {
   const registry = loadRegistry(registryPath);
   const pruned = [];
   const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
+  const excludeSet = new Set(
+    excludeNames.filter((n) => typeof n === 'string' && n.trim().length > 0),
+  );
 
   for (const [name, entry] of Object.entries(registry.repos)) {
+    if (excludeSet.has(name)) continue;
     if (!fs.existsSync(entry.path)) {
       pruned.push({ name, path: entry.path, reason: 'missing' });
       delete registry.repos[name];

package/src/structure.js

@@ -224,6 +224,100 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
   debug(`Structure: ${dirCount} directories, ${fileSymbols.size} files with metrics`);
 }
 
+// ─── Node role classification ─────────────────────────────────────────
+
+function median(sorted) {
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+export function classifyNodeRoles(db) {
+  const rows = db
+    .prepare(
+      `SELECT n.id, n.kind, n.file,
+        COALESCE(fi.cnt, 0) AS fan_in,
+        COALESCE(fo.cnt, 0) AS fan_out
+      FROM nodes n
+      LEFT JOIN (
+        SELECT target_id, COUNT(*) AS cnt FROM edges WHERE kind = 'calls' GROUP BY target_id
+      ) fi ON n.id = fi.target_id
+      LEFT JOIN (
+        SELECT source_id, COUNT(*) AS cnt FROM edges WHERE kind = 'calls' GROUP BY source_id
+      ) fo ON n.id = fo.source_id
+      WHERE n.kind NOT IN ('file', 'directory')`,
+    )
+    .all();
+
+  if (rows.length === 0) {
+    return { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, leaf: 0 };
+  }
+
+  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 e.kind = 'calls' AND caller.file != target.file`,
+      )
+      .all()
+      .map((r) => r.target_id),
+  );
+
+  const nonZeroFanIn = rows
+    .filter((r) => r.fan_in > 0)
+    .map((r) => r.fan_in)
+    .sort((a, b) => a - b);
+  const nonZeroFanOut = rows
+    .filter((r) => r.fan_out > 0)
+    .map((r) => r.fan_out)
+    .sort((a, b) => a - b);
+
+  const medFanIn = median(nonZeroFanIn);
+  const medFanOut = median(nonZeroFanOut);
+
+  const updates = [];
+  const summary = { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, leaf: 0 };
+
+  for (const row of rows) {
+    const highIn = row.fan_in >= medFanIn && row.fan_in > 0;
+    const highOut = row.fan_out >= medFanOut && row.fan_out > 0;
+    const isExported = exportedIds.has(row.id);
+
+    let role;
+    if (row.fan_in === 0 && !isExported) {
+      role = 'dead';
+    } else if (row.fan_in === 0 && isExported) {
+      role = 'entry';
+    } else if (highIn && !highOut) {
+      role = 'core';
+    } else if (highIn && highOut) {
+      role = 'utility';
+    } else if (!highIn && highOut) {
+      role = 'adapter';
+    } else {
+      role = 'leaf';
+    }
+
+    updates.push({ id: row.id, role });
+    summary[role]++;
+  }
+
+  const clearRoles = db.prepare('UPDATE nodes SET role = NULL');
+  const setRole = db.prepare('UPDATE nodes SET role = ? WHERE id = ?');
+
+  db.transaction(() => {
+    clearRoles.run();
+    for (const u of updates) {
+      setRole.run(u.role, u.id);
+    }
+  })();
+
+  return summary;
+}
+
 // ─── Query functions (read-only) ──────────────────────────────────────
 
 /**