@optave/codegraph 3.0.4 → 3.1.0

package/src/queries.js

@@ -163,7 +163,7 @@ function resolveMethodViaHierarchy(db, methodName) {
  * Find nodes matching a name query, ranked by relevance.
  * Scoring: exact=100, prefix=60, word-boundary=40, substring=10, plus fan-in tiebreaker.
  */
-function findMatchingNodes(db, name, opts = {}) {
+export function findMatchingNodes(db, name, opts = {}) {
   const kinds = opts.kind ? [opts.kind] : FUNCTION_KINDS;
   const placeholders = kinds.map(() => '?').join(', ');
   const params = [`%${name}%`, ...kinds];
@@ -3134,31 +3134,49 @@ export function roles(customDbPath, opts = {}) {
 
 // ─── exportsData ─────────────────────────────────────────────────────
 
-function exportsFileImpl(db, target, noTests, getFileLines) {
+function exportsFileImpl(db, target, noTests, getFileLines, unused) {
   const fileNodes = db
     .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
     .all(`%${target}%`);
   if (fileNodes.length === 0) return [];
 
+  // Detect whether exported column exists
+  let hasExportedCol = false;
+  try {
+    db.prepare('SELECT exported FROM nodes LIMIT 0').raw();
+    hasExportedCol = true;
+  } catch {
+    /* old DB without exported column */
+  }
+
   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
+    let exported;
+    if (hasExportedCol) {
+      // Use the exported column populated during build
+      exported = 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'`,
+          "SELECT * FROM nodes WHERE file = ? AND kind != 'file' AND exported = 1 ORDER BY line",
         )
-        .all(fn.file, fn.file)
-        .map((r) => r.target_id),
-    );
-
-    const exported = symbols.filter((s) => exportedIds.has(s.id));
+        .all(fn.file);
+    } else {
+      // Fallback: symbols that have incoming calls from other files
+      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),
+      );
+      exported = symbols.filter((s) => exportedIds.has(s.id));
+    }
     const internalCount = symbols.length - exported.length;
 
     const results = exported.map((s) => {
@@ -3185,6 +3203,8 @@ function exportsFileImpl(db, target, noTests, getFileLines) {
       };
     });
 
+    const totalUnused = results.filter((r) => r.consumerCount === 0).length;
+
     // Files that re-export this file (barrel → this file)
     const reexports = db
       .prepare(
@@ -3194,12 +3214,18 @@ function exportsFileImpl(db, target, noTests, getFileLines) {
       .all(fn.id)
       .map((r) => ({ file: r.file }));
 
+    let filteredResults = results;
+    if (unused) {
+      filteredResults = results.filter((r) => r.consumerCount === 0);
+    }
+
     return {
       file: fn.file,
-      results,
+      results: filteredResults,
       reexports,
       totalExported: exported.length,
       totalInternal: internalCount,
+      totalUnused,
     };
   });
 }
@@ -3229,12 +3255,13 @@ export function exportsData(file, customDbPath, opts = {}) {
     }
   }
 
-  const fileResults = exportsFileImpl(db, file, noTests, getFileLines);
+  const unused = opts.unused || false;
+  const fileResults = exportsFileImpl(db, file, noTests, getFileLines, unused);
   db.close();
 
   if (fileResults.length === 0) {
     return paginateResult(
-      { file, results: [], reexports: [], totalExported: 0, totalInternal: 0 },
+      { file, results: [], reexports: [], totalExported: 0, totalInternal: 0, totalUnused: 0 },
       'results',
       { limit: opts.limit, offset: opts.offset },
     );
@@ -3248,6 +3275,7 @@ export function exportsData(file, customDbPath, opts = {}) {
     reexports: first.reexports,
     totalExported: first.totalExported,
     totalInternal: first.totalInternal,
+    totalUnused: first.totalUnused,
   };
   return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
@@ -3264,13 +3292,24 @@ export function fileExports(file, customDbPath, opts = {}) {
   }
 
   if (data.results.length === 0) {
-    console.log(`No exported symbols found for "${file}". Run "codegraph build" first.`);
+    if (opts.unused) {
+      console.log(`No unused exports found for "${file}".`);
+    } else {
+      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`,
-  );
+  if (opts.unused) {
+    console.log(
+      `\n# ${data.file} — ${data.totalUnused} unused export${data.totalUnused !== 1 ? 's' : ''} (of ${data.totalExported} exported)\n`,
+    );
+  } else {
+    const unusedNote = data.totalUnused > 0 ? ` (${data.totalUnused} unused)` : '';
+    console.log(
+      `\n# ${data.file} — ${data.totalExported} exported${unusedNote}, ${data.totalInternal} internal\n`,
+    );
+  }
 
   for (const sym of data.results) {
     const icon = kindIcon(sym.kind);

package/src/resolve.js

@@ -146,8 +146,12 @@ export function computeConfidence(callerFile, targetFile, importedFrom) {
 /**
  * Batch resolve multiple imports in a single native call.
  * Returns Map<"fromFile|importSource", resolvedPath> or null when native unavailable.
+ * @param {Array} inputs - Array of { fromFile, importSource }
+ * @param {string} rootDir - Project root
+ * @param {object} aliases - Path aliases
+ * @param {string[]} [knownFiles] - Optional file paths for FS cache (avoids syscalls)
  */
-export function resolveImportsBatch(inputs, rootDir, aliases) {
+export function resolveImportsBatch(inputs, rootDir, aliases, knownFiles) {
   const native = loadNative();
   if (!native) return null;
 
@@ -156,7 +160,12 @@ export function resolveImportsBatch(inputs, rootDir, aliases) {
       fromFile,
       importSource,
     }));
-    const results = native.resolveImports(nativeInputs, rootDir, convertAliasesForNative(aliases));
+    const results = native.resolveImports(
+      nativeInputs,
+      rootDir,
+      convertAliasesForNative(aliases),
+      knownFiles || null,
+    );
     const map = new Map();
     for (const r of results) {
       map.set(`${r.fromFile}|${r.importSource}`, normalizePath(path.normalize(r.resolvedPath)));

package/src/sequence.js

@@ -0,0 +1,369 @@
+/**
+ * Sequence diagram generation – Mermaid sequenceDiagram from call graph edges.
+ *
+ * Participants are files (not individual functions). Calls within the same file
+ * become self-messages. This keeps diagrams readable and matches typical
+ * sequence-diagram conventions.
+ */
+
+import { openReadonlyOrFail } from './db.js';
+import { paginateResult, printNdjson } from './paginate.js';
+import { findMatchingNodes, isTestFile, kindIcon } from './queries.js';
+import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
+
+// ─── Alias generation ────────────────────────────────────────────────
+
+/**
+ * Build short participant aliases from file paths with collision handling.
+ * e.g. "src/builder.js" → "builder", but if two files share basename,
+ * progressively add parent dirs: "src/builder" vs "lib/builder".
+ */
+function buildAliases(files) {
+  const aliases = new Map();
+  const basenames = new Map();
+
+  // Group by basename
+  for (const file of files) {
+    const base = file
+      .split('/')
+      .pop()
+      .replace(/\.[^.]+$/, '');
+    if (!basenames.has(base)) basenames.set(base, []);
+    basenames.get(base).push(file);
+  }
+
+  for (const [base, paths] of basenames) {
+    if (paths.length === 1) {
+      aliases.set(paths[0], base);
+    } else {
+      // Collision — progressively add parent dirs until aliases are unique
+      for (let depth = 2; depth <= 10; depth++) {
+        const trial = new Map();
+        let allUnique = true;
+        const seen = new Set();
+
+        for (const p of paths) {
+          const parts = p.replace(/\.[^.]+$/, '').split('/');
+          const alias = parts
+            .slice(-depth)
+            .join('_')
+            .replace(/[^a-zA-Z0-9_-]/g, '_');
+          trial.set(p, alias);
+          if (seen.has(alias)) allUnique = false;
+          seen.add(alias);
+        }
+
+        if (allUnique || depth === 10) {
+          for (const [p, alias] of trial) {
+            aliases.set(p, alias);
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return aliases;
+}
+
+// ─── Core data function ──────────────────────────────────────────────
+
+/**
+ * Build sequence diagram data by BFS-forward from an entry point.
+ *
+ * @param {string} name - Symbol name to trace from
+ * @param {string} [dbPath]
+ * @param {object} [opts]
+ * @param {number} [opts.depth=10]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.file]
+ * @param {string} [opts.kind]
+ * @param {boolean} [opts.dataflow]
+ * @param {number} [opts.limit]
+ * @param {number} [opts.offset]
+ * @returns {{ entry, participants, messages, depth, totalMessages, truncated }}
+ */
+export function sequenceData(name, dbPath, opts = {}) {
+  const db = openReadonlyOrFail(dbPath);
+  const maxDepth = opts.depth || 10;
+  const noTests = opts.noTests || false;
+  const withDataflow = opts.dataflow || false;
+
+  // Phase 1: Direct LIKE match
+  let matchNode = findMatchingNodes(db, name, opts)[0] ?? null;
+
+  // Phase 2: Prefix-stripped matching
+  if (!matchNode) {
+    for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
+      matchNode = findMatchingNodes(db, `${prefix}${name}`, opts)[0] ?? null;
+      if (matchNode) break;
+    }
+  }
+
+  if (!matchNode) {
+    db.close();
+    return {
+      entry: null,
+      participants: [],
+      messages: [],
+      depth: maxDepth,
+      totalMessages: 0,
+      truncated: false,
+    };
+  }
+
+  const entry = {
+    name: matchNode.name,
+    file: matchNode.file,
+    kind: matchNode.kind,
+    line: matchNode.line,
+  };
+
+  // BFS forward — track edges, not just nodes
+  const visited = new Set([matchNode.id]);
+  let frontier = [matchNode.id];
+  const messages = [];
+  const fileSet = new Set([matchNode.file]);
+  const idToNode = new Map();
+  idToNode.set(matchNode.id, matchNode);
+  let truncated = false;
+
+  const getCallees = db.prepare(
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'calls'`,
+  );
+
+  for (let d = 1; d <= maxDepth; d++) {
+    const nextFrontier = [];
+
+    for (const fid of frontier) {
+      const callees = getCallees.all(fid);
+
+      const caller = idToNode.get(fid);
+
+      for (const c of callees) {
+        if (noTests && isTestFile(c.file)) continue;
+
+        // Always record the message (even for visited nodes — different caller path)
+        fileSet.add(c.file);
+        messages.push({
+          from: caller.file,
+          to: c.file,
+          label: c.name,
+          type: 'call',
+          depth: d,
+        });
+
+        if (visited.has(c.id)) continue;
+
+        visited.add(c.id);
+        nextFrontier.push(c.id);
+        idToNode.set(c.id, c);
+      }
+    }
+
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+
+    if (d === maxDepth && frontier.length > 0) {
+      // Only mark truncated if at least one frontier node has further callees
+      const hasMoreCalls = frontier.some((fid) => getCallees.all(fid).length > 0);
+      if (hasMoreCalls) truncated = true;
+    }
+  }
+
+  // Dataflow annotations: add return arrows
+  if (withDataflow && messages.length > 0) {
+    const hasTable = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='dataflow'")
+      .get();
+
+    if (hasTable) {
+      // Build name|file lookup for O(1) target node access
+      const nodeByNameFile = new Map();
+      for (const n of idToNode.values()) {
+        nodeByNameFile.set(`${n.name}|${n.file}`, n);
+      }
+
+      const getReturns = db.prepare(
+        `SELECT d.expression FROM dataflow d
+         WHERE d.source_id = ? AND d.kind = 'returns'`,
+      );
+      const getFlowsTo = db.prepare(
+        `SELECT d.expression FROM dataflow d
+         WHERE d.target_id = ? AND d.kind = 'flows_to'
+         ORDER BY d.param_index`,
+      );
+
+      // For each called function, check if it has return edges
+      const seenReturns = new Set();
+      for (const msg of [...messages]) {
+        if (msg.type !== 'call') continue;
+        const targetNode = nodeByNameFile.get(`${msg.label}|${msg.to}`);
+        if (!targetNode) continue;
+
+        const returnKey = `${msg.to}->${msg.from}:${msg.label}`;
+        if (seenReturns.has(returnKey)) continue;
+
+        const returns = getReturns.all(targetNode.id);
+
+        if (returns.length > 0) {
+          seenReturns.add(returnKey);
+          const expr = returns[0].expression || 'result';
+          messages.push({
+            from: msg.to,
+            to: msg.from,
+            label: expr,
+            type: 'return',
+            depth: msg.depth,
+          });
+        }
+      }
+
+      // Annotate call messages with parameter names
+      for (const msg of messages) {
+        if (msg.type !== 'call') continue;
+        const targetNode = nodeByNameFile.get(`${msg.label}|${msg.to}`);
+        if (!targetNode) continue;
+
+        const params = getFlowsTo.all(targetNode.id);
+
+        if (params.length > 0) {
+          const paramNames = params
+            .map((p) => p.expression)
+            .filter(Boolean)
+            .slice(0, 3);
+          if (paramNames.length > 0) {
+            msg.label = `${msg.label}(${paramNames.join(', ')})`;
+          }
+        }
+      }
+    }
+  }
+
+  // Sort messages by depth, then call before return
+  messages.sort((a, b) => {
+    if (a.depth !== b.depth) return a.depth - b.depth;
+    if (a.type === 'call' && b.type === 'return') return -1;
+    if (a.type === 'return' && b.type === 'call') return 1;
+    return 0;
+  });
+
+  // Build participant list from files
+  const aliases = buildAliases([...fileSet]);
+  const participants = [...fileSet].map((file) => ({
+    id: aliases.get(file),
+    label: file.split('/').pop(),
+    file,
+  }));
+
+  // Sort participants: entry file first, then alphabetically
+  participants.sort((a, b) => {
+    if (a.file === entry.file) return -1;
+    if (b.file === entry.file) return 1;
+    return a.file.localeCompare(b.file);
+  });
+
+  // Replace file paths with alias IDs in messages
+  for (const msg of messages) {
+    msg.from = aliases.get(msg.from);
+    msg.to = aliases.get(msg.to);
+  }
+
+  db.close();
+
+  const base = {
+    entry,
+    participants,
+    messages,
+    depth: maxDepth,
+    totalMessages: messages.length,
+    truncated,
+  };
+  const result = paginateResult(base, 'messages', { limit: opts.limit, offset: opts.offset });
+  if (opts.limit !== undefined || opts.offset !== undefined) {
+    const activeFiles = new Set(result.messages.flatMap((m) => [m.from, m.to]));
+    result.participants = result.participants.filter((p) => activeFiles.has(p.id));
+  }
+  return result;
+}
+
+// ─── Mermaid formatter ───────────────────────────────────────────────
+
+/**
+ * Escape special Mermaid characters in labels.
+ */
+function escapeMermaid(str) {
+  return str
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/:/g, '#colon;')
+    .replace(/"/g, '#quot;');
+}
+
+/**
+ * Convert sequenceData result to Mermaid sequenceDiagram syntax.
+ * @param {{ participants, messages, truncated }} seqResult
+ * @returns {string}
+ */
+export function sequenceToMermaid(seqResult) {
+  const lines = ['sequenceDiagram'];
+
+  for (const p of seqResult.participants) {
+    lines.push(`    participant ${p.id} as ${escapeMermaid(p.label)}`);
+  }
+
+  for (const msg of seqResult.messages) {
+    const arrow = msg.type === 'return' ? '-->>' : '->>';
+    lines.push(`    ${msg.from}${arrow}${msg.to}: ${escapeMermaid(msg.label)}`);
+  }
+
+  if (seqResult.truncated && seqResult.participants.length > 0) {
+    lines.push(
+      `    note right of ${seqResult.participants[0].id}: Truncated at depth ${seqResult.depth}`,
+    );
+  }
+
+  return lines.join('\n');
+}
+
+// ─── CLI formatter ───────────────────────────────────────────────────
+
+/**
+ * CLI entry point — format sequence data as mermaid, JSON, or ndjson.
+ */
+export function sequence(name, dbPath, opts = {}) {
+  const data = sequenceData(name, dbPath, opts);
+
+  if (opts.ndjson) {
+    printNdjson(data, 'messages');
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  // Default: mermaid format
+  if (!data.entry) {
+    console.log(`No matching function found for "${name}".`);
+    return;
+  }
+
+  const e = data.entry;
+  console.log(`\nSequence from: [${kindIcon(e.kind)}] ${e.name}  ${e.file}:${e.line}`);
+  console.log(`Participants: ${data.participants.length}  Messages: ${data.totalMessages}`);
+  if (data.truncated) {
+    console.log(`  (truncated at depth ${data.depth})`);
+  }
+  console.log();
+
+  if (data.messages.length === 0) {
+    console.log('  (leaf node — no callees)');
+    return;
+  }
+
+  console.log(sequenceToMermaid(data));
+}