@mishasinitcyn/betterrank 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mishasinitcyn/betterrank",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Structural code index with PageRank-ranked repo maps, symbol search, call-graph queries, and dependency analysis. Built on tree-sitter and graphology.",
   "type": "module",
   "main": "src/index.js",

package/src/cache.js

@@ -24,38 +24,90 @@ function getPlatformCacheDir() {
 const CACHE_DIR = getPlatformCacheDir();
 
 const IGNORE_PATTERNS = [
-  // Dependencies & generated
+  // ── JS / Node ──────────────────────────────────────────
   '**/node_modules/**',
-  '**/dist/**',
-  '**/build/**',
-  '**/coverage/**',
-  '**/vendor/**',
+  '**/.npm/**',
+  '**/.yarn/**',
+  '**/.pnp.*',
+  '**/bower_components/**',
   '**/*.min.js',
   '**/*.bundle.js',
   '**/*.map',
 
-  // VCS & tool caches
-  '**/.git/**',
-  '**/.code-index/**',
-  '**/.claude/**',
-  '**/.cursor/**',
-
-  // Language-specific caches
+  // ── Python ─────────────────────────────────────────────
   '**/__pycache__/**',
   '**/.venv/**',
+  '**/venv/**',
+  '**/env/**',
+  '**/.env/**',
+  '**/.virtualenvs/**',
+  '**/site-packages/**',
+  '**/*.egg-info/**',
+  '**/.eggs/**',
+  '**/.tox/**',
+  '**/.mypy_cache/**',
+  '**/.pytest_cache/**',
+  '**/.ruff_cache/**',
+
+  // ── Rust ───────────────────────────────────────────────
+  '**/target/debug/**',
+  '**/target/release/**',
+
+  // ── Java / JVM ─────────────────────────────────────────
+  '**/.gradle/**',
+  '**/.m2/**',
+
+  // ── Ruby ───────────────────────────────────────────────
+  '**/.bundle/**',
+
+  // ── C / C++ ────────────────────────────────────────────
+  '**/cmake-build-*/**',
+  '**/CMakeFiles/**',
+
+  // ── Go ─────────────────────────────────────────────────
+  '**/vendor/**',
+
+  // ── Build output & generated ───────────────────────────
+  '**/dist/**',
+  '**/build/**',
+  '**/out/**',
+  '**/coverage/**',
+
+  // ── Frameworks ─────────────────────────────────────────
   '**/.next/**',
   '**/.nuxt/**',
-
-  // iOS / mobile vendor
+  '**/.output/**',
+  '**/.svelte-kit/**',
+  '**/.angular/**',
+  '**/.turbo/**',
+  '**/.parcel-cache/**',
+  '**/.cache/**',
+
+  // ── iOS / mobile ───────────────────────────────────────
   '**/Pods/**',
   '**/*.xcframework/**',
 
-  // UI component libraries (shadcn, etc.) — high fan-in but rarely investigation targets.
+  // ── Infrastructure / deploy ────────────────────────────
+  '**/.terraform/**',
+  '**/.serverless/**',
+  '**/cdk.out/**',
+  '**/.vercel/**',
+  '**/.netlify/**',
+
+  // ── VCS & tool caches ──────────────────────────────────
+  '**/.git/**',
+  '**/.code-index/**',
+  '**/.claude/**',
+  '**/.cursor/**',
+  '**/.nx/**',
+
+  // ── UI component libraries ─────────────────────────────
+  // shadcn, etc. — high fan-in but rarely investigation targets.
   // To re-include, add "!**/components/ui/**" in .code-index/config.json ignore list,
   // or pass --ignore '!**/components/ui/**' on the CLI.
   '**/components/ui/**',
 
-  // Scratch / temp
+  // ── Scratch / temp ─────────────────────────────────────
   'tmp/**',
 ];
 
@@ -98,7 +150,7 @@ class CodeIndexCache {
       this.initialized = true;
     }
 
-    const { changed, deleted } = await this._getChangedFiles();
+    const { changed, deleted, totalScanned } = await this._getChangedFiles();
 
     if (changed.length === 0 && deleted.length === 0) {
       if (!this.graph) {
@@ -107,9 +159,15 @@ class CodeIndexCache {
         const MDG = graphology.default?.MultiDirectedGraph || graphology.MultiDirectedGraph;
         this.graph = new MDG({ allowSelfLoops: false });
       }
-      return { changed: 0, deleted: 0 };
+      return { changed: 0, deleted: 0, totalScanned };
+    }
+
+    const isColdStart = !this.graph;
+    if (isColdStart) {
+      process.stderr.write(`Indexing ${this.projectRoot}... ${changed.length} files found, parsing...\n`);
     }
 
+    const t0 = Date.now();
     const newSymbols = await this._parseFiles(changed);
 
     if (!this.graph) {
@@ -123,7 +181,14 @@ class CodeIndexCache {
 
     await saveGraph(this.graph, this.mtimes, this.cachePath);
 
-    return { changed: changed.length, deleted: deleted.length };
+    if (isColdStart) {
+      const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+      let symbols = 0;
+      this.graph.forEachNode((_n, attrs) => { if (attrs.type === 'symbol') symbols++; });
+      process.stderr.write(`Indexed ${changed.length} files (${symbols} symbols, ${this.graph.size} edges) in ${elapsed}s\n`);
+    }
+
+    return { changed: changed.length, deleted: deleted.length, totalScanned };
   }
 
   /**
@@ -204,7 +269,7 @@ class CodeIndexCache {
       }
     }
 
-    return { changed, deleted };
+    return { changed, deleted, totalScanned: files.length };
   }
 
   /**

package/src/cli.js

@@ -27,8 +27,152 @@ Global flags:
   --count           Return counts only (no content)
   --offset N        Skip first N results
   --limit N         Max results to return (default: ${DEFAULT_LIMIT} for list commands)
+  --help            Show help for a command (e.g. betterrank search --help)
 `.trim();
 
+const COMMAND_HELP = {
+  map: `betterrank map [--focus file1,file2] [--root <path>]
+
+Aider-style repo map: the most structurally important definitions ranked by PageRank.
+
+Options:
+  --focus <files>   Comma-separated files to bias ranking toward
+  --count           Return total symbol count only
+  --offset N        Skip first N symbols
+  --limit N         Max symbols to return (default: ${DEFAULT_LIMIT})
+
+Examples:
+  betterrank map --root ./backend
+  betterrank map --root ./frontend --limit 100
+  betterrank map --root ./backend --focus src/auth/handlers.ts,src/api/login.ts`,
+
+  search: `betterrank search <query> [--kind type] [--root <path>]
+
+Substring search on symbol names + full signatures (param names, types, defaults).
+Results ranked by PageRank (most structurally important first).
+
+Options:
+  --kind <type>    Filter: function, class, type, variable, namespace, import
+  --count          Return match count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+Tips:
+  Use short substrings (3-5 chars) — PageRank ranking handles noise.
+  "imp" finds encrypt_imp_payload, increment_impression, etc.
+  Searches match against both symbol names AND full signatures (param names, types).
+
+Examples:
+  betterrank search resolve --root ./backend
+  betterrank search auth --kind function --limit 10
+  betterrank search max_age --root . --count`,
+
+  structure: `betterrank structure [--depth N] [--root <path>]
+
+File tree with symbol counts per file.
+
+Options:
+  --depth N     Max directory depth (default: ${DEFAULT_DEPTH})
+
+Examples:
+  betterrank structure --root ./backend --depth 2`,
+
+  symbols: `betterrank symbols [--file path] [--kind type] [--root <path>]
+
+List symbol definitions, optionally filtered by file or kind.
+Results ranked by PageRank (most structurally important first).
+
+Options:
+  --file <path>    Filter to a specific file (relative to --root)
+  --kind <type>    Filter: function, class, type, variable, namespace, import
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+Examples:
+  betterrank symbols --file src/auth/handlers.ts --root ./backend
+  betterrank symbols --kind class --root . --limit 20`,
+
+  callers: `betterrank callers <symbol> [--file path] [--root <path>]
+
+Find all files that reference a symbol. Ranked by file-level PageRank.
+
+Options:
+  --file <path>    Disambiguate when multiple symbols share a name
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+Examples:
+  betterrank callers authenticateUser --root ./backend
+  betterrank callers resolve --file src/utils.ts --root .`,
+
+  deps: `betterrank deps <file> [--root <path>]
+
+What this file imports / depends on. Ranked by PageRank.
+
+Options:
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+Examples:
+  betterrank deps src/auth/handlers.ts --root ./backend`,
+
+  dependents: `betterrank dependents <file> [--root <path>]
+
+What files import this file. Ranked by PageRank.
+
+Options:
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+Examples:
+  betterrank dependents src/auth/handlers.ts --root ./backend`,
+
+  neighborhood: `betterrank neighborhood <file> [--hops N] [--max-files N] [--root <path>]
+
+Local subgraph around a file: its imports, importers, and their symbols.
+
+Options:
+  --hops N          BFS depth for outgoing imports (default: 2)
+  --max-files N     Max files to include (default: 15, direct neighbors always included)
+  --count           Return counts only
+  --offset N        Skip first N files
+  --limit N         Max files to return
+
+Examples:
+  betterrank neighborhood src/auth/handlers.ts --root ./backend
+  betterrank neighborhood src/api/bid.js --hops 3 --max-files 20 --root .`,
+
+  reindex: `betterrank reindex [--root <path>]
+
+Force a full rebuild of the index. Use after branch switches, large merges,
+or if results seem stale.
+
+Examples:
+  betterrank reindex --root ./backend`,
+
+  stats: `betterrank stats [--root <path>]
+
+Show index statistics: file count, symbol count, edge count.
+
+Examples:
+  betterrank stats --root .`,
+
+  ui: `betterrank ui [--port N]
+
+Launch the interactive web UI for exploring the index.
+
+Options:
+  --port N    Port to listen on (default: 3333)
+
+Examples:
+  betterrank ui
+  betterrank ui --port 8080`,
+};
+
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
@@ -39,6 +183,16 @@ async function main() {
   const command = args[0];
   const flags = parseFlags(args.slice(1));
 
+  // Per-command --help
+  if (flags.help === true || flags.h === true) {
+    if (COMMAND_HELP[command]) {
+      console.log(COMMAND_HELP[command]);
+    } else {
+      console.log(USAGE);
+    }
+    process.exit(0);
+  }
+
   // UI command doesn't need --root or a CodeIndex instance
   if (command === 'ui') {
     const { startServer } = await import('./server.js');
@@ -73,6 +227,35 @@ async function main() {
     return rel;
   }
 
+  /** Print file-not-found diagnostics and exit. Returns true if handled. */
+  function handleFileNotFound(result, filePath) {
+    if (!result || !result.fileNotFound) return false;
+    console.error(`File "${filePath}" not found in index.`);
+    if (result.suggestions && result.suggestions.length > 0) {
+      console.error(`Did you mean:`);
+      for (const s of result.suggestions) console.error(`  ${s}`);
+    }
+    console.error(`Tip: File paths are relative to --root. Use \`betterrank structure\` to see indexed files.`);
+    return true;
+  }
+
+  /** Suggest shorter query alternatives by splitting on _ and camelCase boundaries. */
+  function suggestShorterQueries(query) {
+    const parts = new Set();
+    // Split on underscores
+    for (const p of query.split('_')) {
+      if (p.length >= 3) parts.add(p.toLowerCase());
+    }
+    // Split on camelCase boundaries
+    const camelParts = query.replace(/([a-z])([A-Z])/g, '$1_$2').split('_');
+    for (const p of camelParts) {
+      if (p.length >= 3) parts.add(p.toLowerCase());
+    }
+    // Remove the original query itself
+    parts.delete(query.toLowerCase());
+    return [...parts].slice(0, 4);
+  }
+
   switch (command) {
     case 'map': {
       const focusFiles = flags.focus ? flags.focus.split(',') : [];
@@ -87,6 +270,17 @@ async function main() {
           console.log(`Use --limit N to show more, or --count for totals`);
         }
       }
+      // Diagnostics on empty index
+      if (result.diagnostics) {
+        const d = result.diagnostics;
+        console.log(`\nDiagnostics:`);
+        console.log(`  Root:        ${d.root}`);
+        console.log(`  Files found: ${d.filesScanned}`);
+        console.log(`  Extensions:  ${d.extensions}`);
+        if (d.filesScanned === 0) {
+          console.log(`  Tip:         No supported files found. Try a broader --root.`);
+        }
+      }
       break;
     }
 
@@ -102,7 +296,17 @@ async function main() {
           console.log(`${s.file}:${s.lineStart}  [${s.kind}] ${s.signature}`);
         }
         if (result.length === 0) {
-          console.log('(no matches)');
+          const st = await idx.stats();
+          console.log(`(no matches for "${query}")`);
+          if (st.symbols > 0) {
+            console.log(`Index has ${st.symbols.toLocaleString()} symbols across ${st.files.toLocaleString()} files.`);
+            const suggestions = suggestShorterQueries(query);
+            if (suggestions.length > 0) {
+              console.log(`Tip: Use shorter substrings. Try: ${suggestions.map(s => `"${s}"`).join(', ')}`);
+            }
+          } else {
+            console.log(`Index is empty. Check --root or run: betterrank map --root <path>`);
+          }
         } else if (result.length === effectiveLimit && userLimit === undefined) {
           console.log(`\n(showing top ${effectiveLimit} by relevance — use --limit N or --count for total)`);
         }
@@ -163,13 +367,15 @@ async function main() {
       if (!file) { console.error('Usage: betterrank deps <file>'); process.exit(1); }
       const effectiveLimit = countMode ? undefined : (userLimit !== undefined ? userLimit : DEFAULT_LIMIT);
       const result = await idx.dependencies({ file, count: countMode, offset, limit: effectiveLimit });
+      if (handleFileNotFound(result, file)) break;
       if (countMode) {
         console.log(`total: ${result.total}`);
       } else {
-        for (const d of result) console.log(d);
-        if (result.length === 0) {
+        const items = result.items || result;
+        for (const d of items) console.log(d);
+        if (items.length === 0) {
           console.log('(no dependencies)');
-        } else if (result.length === effectiveLimit && userLimit === undefined) {
+        } else if (items.length === effectiveLimit && userLimit === undefined) {
           console.log(`\n(showing top ${effectiveLimit} by relevance — use --limit N or --count for total)`);
         }
       }
@@ -181,13 +387,15 @@ async function main() {
       if (!file) { console.error('Usage: betterrank dependents <file>'); process.exit(1); }
       const effectiveLimit = countMode ? undefined : (userLimit !== undefined ? userLimit : DEFAULT_LIMIT);
       const result = await idx.dependents({ file, count: countMode, offset, limit: effectiveLimit });
+      if (handleFileNotFound(result, file)) break;
       if (countMode) {
         console.log(`total: ${result.total}`);
       } else {
-        for (const d of result) console.log(d);
-        if (result.length === 0) {
+        const items = result.items || result;
+        for (const d of items) console.log(d);
+        if (items.length === 0) {
           console.log('(no dependents)');
-        } else if (result.length === effectiveLimit && userLimit === undefined) {
+        } else if (items.length === effectiveLimit && userLimit === undefined) {
           console.log(`\n(showing top ${effectiveLimit} by relevance — use --limit N or --count for total)`);
         }
       }
@@ -208,6 +416,7 @@ async function main() {
         const preview = await idx.neighborhood({
           file, hops, maxFiles: maxFilesFlag, count: true,
         });
+        if (handleFileNotFound(preview, file)) break;
         console.log(`files: ${preview.totalFiles} (${preview.totalVisited} visited, ${preview.totalFiles} after ranking)`);
         console.log(`symbols: ${preview.totalSymbols}`);
         console.log(`edges: ${preview.totalEdges}`);
@@ -219,6 +428,7 @@ async function main() {
         file, hops, maxFiles: maxFilesFlag,
         count: countMode, offset, limit: userLimit,
       });
+      if (handleFileNotFound(result, file)) break;
 
       if (countMode) {
         console.log(`files: ${result.totalFiles} (${result.totalVisited} visited, ${result.totalFiles} after ranking)`);
@@ -284,7 +494,10 @@ function parseFlags(args) {
   const flags = { _positional: [] };
   let i = 0;
   while (i < args.length) {
-    if (args[i].startsWith('--')) {
+    if (args[i] === '-h') {
+      flags.help = true;
+      i++;
+    } else if (args[i].startsWith('--')) {
       const key = args[i].substring(2);
       if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
         flags[key] = args[i + 1];

package/src/index.js

@@ -1,8 +1,32 @@
 import { readFile } from 'fs/promises';
-import { join, dirname, relative, sep } from 'path';
+import { join, dirname, relative, sep, basename } from 'path';
 import { CodeIndexCache } from './cache.js';
 import { rankedSymbols } from './graph.js';
 
+/**
+ * Find file nodes in the graph that look similar to the given path.
+ * Uses basename matching and substring matching on the full path.
+ */
+function findSimilarFiles(graph, filePath, maxSuggestions = 5) {
+  if (!graph) return [];
+  const base = basename(filePath);
+  const baseLower = base.toLowerCase();
+  const pathLower = filePath.toLowerCase();
+  const suggestions = [];
+
+  graph.forEachNode((node, attrs) => {
+    if (attrs.type !== 'file') return;
+    const nodeLower = node.toLowerCase();
+    const nodeBase = basename(node).toLowerCase();
+    // Exact basename match or basename contains query
+    if (nodeBase === baseLower || nodeBase.includes(baseLower) || nodeLower.includes(pathLower)) {
+      suggestions.push(node);
+    }
+  });
+
+  return suggestions.slice(0, maxSuggestions);
+}
+
 /**
  * Apply offset/limit pagination to an array.
  * Returns { items, total } where total is the unpaginated count.
@@ -78,13 +102,18 @@ class CodeIndex {
    * @param {boolean} [opts.count] - If true, return only { total }
    * @returns {{content, shownFiles, shownSymbols, totalFiles, totalSymbols}|{total: number}}
    */
-  async map({ focusFiles = [], offset, limit, count = false } = {}) {
-    await this._ensureReady();
+  async map({ focusFiles = [], offset, limit, count = false, structured = false } = {}) {
+    const ensureResult = await this._ensureReady();
     const graph = this.cache.getGraph();
     if (!graph || graph.order === 0) {
-      return count
-        ? { total: 0 }
-        : { content: '(empty index)', shownFiles: 0, shownSymbols: 0, totalFiles: 0, totalSymbols: 0 };
+      const diagnostics = {
+        root: this.projectRoot,
+        filesScanned: ensureResult.totalScanned || 0,
+        extensions: this.cache.extensions.join(', '),
+      };
+      if (count) return { total: 0, diagnostics };
+      if (structured) return { files: [], shownFiles: 0, shownSymbols: 0, totalFiles: 0, totalSymbols: 0, diagnostics };
+      return { content: '(empty index)', shownFiles: 0, shownSymbols: 0, totalFiles: 0, totalSymbols: 0, diagnostics };
     }
 
     // Count totals from the graph
@@ -97,7 +126,7 @@ class CodeIndex {
 
     const ranked = this._getRanked(focusFiles);
 
-    // Collect all symbol entries ranked by PageRank
+    // Collect all symbol entries ranked by PageRank (rich data for both formats)
     const allEntries = [];
     for (const [symbolKey, _score] of ranked) {
       let attrs;
@@ -108,18 +137,48 @@ class CodeIndex {
       }
       if (attrs.type !== 'symbol') continue;
 
-      const line = `  ${String(attrs.lineStart).padStart(4)}│ ${attrs.signature}`;
-      allEntries.push({ file: attrs.file, line });
+      allEntries.push({
+        file: attrs.file,
+        name: attrs.name,
+        kind: attrs.kind,
+        lineStart: attrs.lineStart,
+        lineEnd: attrs.lineEnd,
+        signature: attrs.signature,
+      });
     }
 
     if (count) return { total: allEntries.length };
 
     const { items } = paginate(allEntries, { offset, limit });
 
+    // Structured format: return file objects with nested symbol arrays
+    if (structured) {
+      const fileGroups = new Map();
+      for (const entry of items) {
+        if (!fileGroups.has(entry.file)) fileGroups.set(entry.file, []);
+        fileGroups.get(entry.file).push({
+          name: entry.name,
+          kind: entry.kind,
+          lineStart: entry.lineStart,
+          lineEnd: entry.lineEnd,
+          signature: entry.signature,
+        });
+      }
+      return {
+        files: [...fileGroups.entries()].map(([path, symbols]) => ({ path, symbols })),
+        shownFiles: fileGroups.size,
+        shownSymbols: items.length,
+        totalFiles,
+        totalSymbols,
+      };
+    }
+
+    // Text format (CLI output)
     const fileGroups = new Map();
     for (const entry of items) {
       if (!fileGroups.has(entry.file)) fileGroups.set(entry.file, []);
-      fileGroups.get(entry.file).push(entry.line);
+      const line = `  ${String(entry.lineStart).padStart(4)}│ ${entry.signature}`;
+      fileGroups.get(entry.file).push(line);
     }
 
     const lines = [];
@@ -332,7 +391,11 @@ class CodeIndex {
   async dependencies({ file, offset, limit, count = false }) {
     await this._ensureReady();
     const graph = this.cache.getGraph();
-    if (!graph || !graph.hasNode(file)) return count ? { total: 0 } : [];
+    if (!graph || !graph.hasNode(file)) {
+      const suggestions = findSimilarFiles(graph, file);
+      if (count) return { total: 0, fileNotFound: true, suggestions };
+      return { items: [], fileNotFound: true, suggestions };
+    }
 
     const fileScores = this._getFileScores();
 
@@ -366,7 +429,11 @@ class CodeIndex {
   async dependents({ file, offset, limit, count = false }) {
     await this._ensureReady();
     const graph = this.cache.getGraph();
-    if (!graph || !graph.hasNode(file)) return count ? { total: 0 } : [];
+    if (!graph || !graph.hasNode(file)) {
+      const suggestions = findSimilarFiles(graph, file);
+      if (count) return { total: 0, fileNotFound: true, suggestions };
+      return { items: [], fileNotFound: true, suggestions };
+    }
 
     const fileScores = this._getFileScores();
 
@@ -420,9 +487,10 @@ class CodeIndex {
     await this._ensureReady();
     const graph = this.cache.getGraph();
     if (!graph || !graph.hasNode(file)) {
+      const suggestions = findSimilarFiles(graph, file);
       return count
-        ? { totalFiles: 0, totalSymbols: 0, totalEdges: 0 }
-        : { files: [], symbols: [], edges: [] };
+        ? { totalFiles: 0, totalSymbols: 0, totalEdges: 0, fileNotFound: true, suggestions }
+        : { files: [], symbols: [], edges: [], fileNotFound: true, suggestions };
     }
 
     // BFS over file nodes, following outgoing IMPORTS edges (dependencies)
@@ -567,6 +635,61 @@ class CodeIndex {
     };
   }
 
+  /**
+   * File-level dependency graph for visualization.
+   * Returns nodes (files) ranked by PageRank and IMPORTS edges between them.
+   *
+   * @param {object} opts
+   * @param {number} [opts.limit] - Max nodes to return (default: 500)
+   * @returns {{ nodes: Array<{id, label, category, score}>, edges: Array<{source, target}> }}
+   */
+  async graph({ limit = 500 } = {}) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph || graph.order === 0) {
+      return { nodes: [], edges: [] };
+    }
+
+    const fileScores = this._getFileScores();
+
+    // Collect file nodes with scores, sorted by PageRank
+    const fileEntries = [];
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'file') return;
+      fileEntries.push({ id: node, score: fileScores.get(node) || 0 });
+    });
+    fileEntries.sort((a, b) => b.score - a.score);
+
+    // Cap to limit
+    const capped = fileEntries.slice(0, limit);
+    const cappedSet = new Set(capped.map(f => f.id));
+
+    // Build nodes with category (first path segment) and label (filename)
+    const nodes = capped.map(f => {
+      const parts = f.id.split('/');
+      const category = parts.length > 1 ? parts[0] : 'root';
+      const label = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+      return { id: f.id, label, category, score: f.score };
+    });
+
+    // Collect IMPORTS edges between capped files
+    const edges = [];
+    const edgeSet = new Set();
+    for (const f of capped) {
+      graph.forEachOutEdge(f.id, (_edge, attrs, source, target) => {
+        if (attrs.type !== 'IMPORTS') return;
+        if (!cappedSet.has(target)) return;
+        const key = `${source}->${target}`;
+        if (!edgeSet.has(key)) {
+          edgeSet.add(key);
+          edges.push({ source, target });
+        }
+      });
+    }
+
+    return { nodes, edges };
+  }
+
   /**
    * Force a full rebuild.
    */