@mishasinitcyn/betterrank 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mishasinitcyn/betterrank",
-  "version": "0.1.7",
+  "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

@@ -150,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) {
@@ -159,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) {
@@ -175,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 };
   }
 
   /**
@@ -256,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.
@@ -79,12 +103,17 @@ class CodeIndex {
    * @returns {{content, shownFiles, shownSymbols, totalFiles, totalSymbols}|{total: number}}
    */
   async map({ focusFiles = [], offset, limit, count = false, structured = false } = {}) {
-    await this._ensureReady();
+    const ensureResult = await this._ensureReady();
     const graph = this.cache.getGraph();
     if (!graph || graph.order === 0) {
-      if (count) return { total: 0 };
-      if (structured) return { files: [], shownFiles: 0, shownSymbols: 0, totalFiles: 0, totalSymbols: 0 };
-      return { 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
@@ -362,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();
 
@@ -396,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();
 
@@ -450,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)
@@ -597,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.
    */

package/src/server.js

@@ -248,6 +248,15 @@ const routes = {
     json(res, result);
   },
 
+  'GET /api/graph': async (req, res) => {
+    if (!requireIndex(res)) return;
+    const p = params(req.url);
+    const result = await currentIndex.graph({
+      limit: p.getInt('limit', 500),
+    });
+    json(res, result);
+  },
+
   'GET /api/structure': async (req, res) => {
     if (!requireIndex(res)) return;
     const p = params(req.url);

package/src/ui.html

@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>betterrank</title>
+<script src="https://d3js.org/d3.v7.min.js"></script>
 <style>
   :root {
     --bg: #0c0c0c;
@@ -569,6 +570,86 @@
     text-align: right;
     flex-shrink: 0;
   }
+
+  /* Graph view — inline within results area */
+  .graph-wrap {
+    position: relative;
+    height: calc(100vh - 280px);
+    min-height: 400px;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    overflow: hidden;
+  }
+  .graph-wrap svg { width: 100%; height: 100%; display: block; }
+  .graph-filters {
+    position: absolute; top: 12px; right: 12px; z-index: 10;
+    background: rgba(22,22,22,0.9); backdrop-filter: blur(8px);
+    border: 1px solid var(--border); border-radius: 10px;
+    padding: 10px 12px; max-width: 240px;
+  }
+  .graph-filters-title { font-size: 10px; color: var(--text-faint); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 8px; }
+  .graph-filter-badges { display: flex; flex-wrap: wrap; gap: 5px; }
+  .graph-badge {
+    display: inline-flex; align-items: center; gap: 5px;
+    padding: 3px 10px; border-radius: 999px;
+    font-size: 11px; font-weight: 500; cursor: pointer;
+    border: 1px solid var(--border); background: transparent;
+    color: var(--text-dim); transition: all 0.15s; user-select: none;
+  }
+  .graph-badge.active { background: var(--bg-raised); color: var(--text); }
+  .graph-badge .dot { width: 7px; height: 7px; border-radius: 50%; }
+  .graph-badge:hover { border-color: #3f3f46; }
+  .graph-detail {
+    position: absolute; bottom: 12px; left: 12px; z-index: 10;
+    background: rgba(22,22,22,0.95); backdrop-filter: blur(8px);
+    border: 1px solid var(--border); border-radius: 10px;
+    padding: 14px 18px; min-width: 260px; max-width: 340px;
+    display: none;
+  }
+  .graph-detail.visible { display: block; }
+  .graph-detail-cat { font-size: 10px; text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px; }
+  .graph-detail-name { font-size: 15px; font-weight: 600; margin-bottom: 2px; color: var(--text); }
+  .graph-detail-path { font-size: 11px; color: var(--text-faint); font-family: var(--mono); margin-bottom: 10px; cursor: pointer; }
+  .graph-detail-path:hover { color: var(--accent); text-decoration: underline; }
+  .graph-detail-section { margin-top: 8px; }
+  .graph-detail-section-title { font-size: 10px; color: var(--text-faint); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px; }
+  .graph-detail-item { font-size: 11px; color: var(--text-dim); padding: 2px 0; display: flex; align-items: center; gap: 6px; }
+  .graph-detail-item .dot { width: 5px; height: 5px; border-radius: 50%; flex-shrink: 0; }
+  .graph-tooltip {
+    position: fixed; z-index: 70; pointer-events: none;
+    background: var(--bg-raised); border: 1px solid var(--border); border-radius: 6px;
+    padding: 6px 10px; font-size: 11px; font-family: var(--mono); display: none;
+    color: var(--text); box-shadow: 0 4px 12px rgba(0,0,0,0.4);
+  }
+  .graph-search {
+    position: absolute; bottom: 12px; right: 12px; z-index: 10;
+    background: rgba(22,22,22,0.95); backdrop-filter: blur(8px);
+    border: 1px solid var(--border); border-radius: 10px;
+    padding: 10px 12px; width: 280px;
+  }
+  .graph-search input {
+    width: 100%; background: var(--bg-raised); border: 1px solid var(--border); border-radius: 6px;
+    padding: 7px 10px; font-size: 13px; color: var(--text); outline: none;
+    font-family: var(--mono);
+  }
+  .graph-search input::placeholder { color: var(--text-faint); }
+  .graph-search input:focus { border-color: var(--accent-dim); }
+  .graph-search-results { max-height: 200px; overflow-y: auto; margin-top: 8px; scrollbar-width: thin; scrollbar-color: var(--border) transparent; }
+  .graph-search-results:empty { display: none; }
+  .graph-search-result {
+    padding: 6px 8px; border-radius: 6px; cursor: pointer;
+    transition: background 0.1s; font-size: 12px; font-family: var(--mono);
+    color: var(--text-dim);
+  }
+  .graph-search-result:hover { background: var(--bg-hover); color: var(--text); }
+  .graph-link { stroke-opacity: 0.15; }
+  .graph-link.highlighted { stroke-opacity: 0.7; stroke-width: 2px !important; }
+  .graph-node circle { stroke-width: 1.5; cursor: pointer; transition: r 0.15s; }
+  .graph-node text { fill: var(--text-dim); font-size: 9px; pointer-events: none; font-family: var(--mono); }
+  .graph-node.dimmed circle { opacity: 0.15; }
+  .graph-node.dimmed text { opacity: 0.1; }
+  .graph-node.highlighted circle { stroke-width: 3; }
 </style>
 </head>
 <body>
@@ -597,9 +678,9 @@
     </div>
   </div>
 
-  <!-- Recent repos -->
+  <!-- Indexed repos -->
   <div class="recent-repos" id="recentRepos" style="display:none">
-    <div class="recent-label">Recent</div>
+    <div class="recent-label">Indexed</div>
     <div class="recent-list" id="recentList"></div>
   </div>
 
@@ -625,6 +706,7 @@
     <button class="tab" data-tool="dependents">Dependents</button>
     <button class="tab" data-tool="neighborhood">Neighborhood</button>
     <button class="tab" data-tool="structure">Structure</button>
+    <button class="tab" data-tool="graph">Graph</button>
   </div>
 
   <!-- Search area -->
@@ -653,9 +735,9 @@
 
   <!-- Results -->
   <div class="results" id="results">
-    <div class="empty-state">
+    <div class="empty-state" id="emptyState">
       <div class="icon">&#x1F4C2;</div>
-      <p>Drop a folder here, click <strong>Browse</strong>, or type a path above.<br>
+      <p id="emptyMsg">Drop a folder here, click <strong>Browse</strong>, or type a path above.<br>
       Then search symbols, explore the map, or trace callers.<br><br>
       <kbd>&#8984;O</kbd> browse &nbsp; <kbd>&#8984;K</kbd> focus search</p>
     </div>
@@ -670,6 +752,9 @@
 
 </div>
 
+<!-- Graph tooltip (needs to be outside .app for fixed positioning) -->
+<div class="graph-tooltip" id="graphTooltip"></div>
+
 <script>
 const $ = s => document.querySelector(s);
 const $$ = s => document.querySelectorAll(s);
@@ -722,11 +807,13 @@ function removeRecentRepo(path) {
   const recent = getRecentRepos().filter(r => r !== path);
   localStorage.setItem(RECENT_KEY, JSON.stringify(recent));
   renderRecentRepos();
+  updateEmptyState();
 }
 
 function clearRecentRepos() {
   localStorage.removeItem(RECENT_KEY);
   renderRecentRepos();
+  updateEmptyState();
 }
 
 function renderRecentRepos() {
@@ -1013,9 +1100,15 @@ $$('.tab').forEach(tab => {
     tab.classList.add('active');
     currentTool = tab.dataset.tool;
     currentPage = 0;
+
+    // Stop any running graph simulation when leaving graph tab
+    if (currentTool !== 'graph' && graphSimulation) {
+      graphSimulation.stop();
+    }
+
     updateSearchUI();
-    // Auto-run: map/structure run server query, others show pickers or run
-    if (['map', 'structure', 'symbols'].includes(currentTool)) {
+    // Auto-run: map/structure/graph run server query, others show pickers or run
+    if (['map', 'structure', 'symbols', 'graph'].includes(currentTool)) {
       runQuery();
     } else {
       queryInput.value = '';
@@ -1030,6 +1123,7 @@ function updateSearchUI() {
   const needsKind = ['search', 'symbols'].includes(currentTool);
 
   $('#searchArea').style.display = needsQuery ? 'block' : 'none';
+  pagination.style.display = currentTool === 'graph' ? 'none' : pagination.style.display;
   kindFilter.style.display = needsKind ? 'inline-block' : 'none';
 
   const placeholders = {
@@ -1118,6 +1212,9 @@ async function runQuery() {
       case 'structure':
         url = `${API}/api/structure?depth=4`;
         break;
+      case 'graph':
+        url = `${API}/api/graph?limit=500`;
+        break;
     }
 
     const res = await fetch(url);
@@ -1144,6 +1241,7 @@ function render(data) {
     case 'dependents': return renderFileList(data.results, data.total);
     case 'neighborhood': return renderNeighborhood(data);
     case 'structure': return renderPre(data.content);
+    case 'graph': return renderGraph(data);
   }
 }
 
@@ -1444,6 +1542,332 @@ document.addEventListener('keydown', (e) => {
 repoInput.onkeydown = (e) => {
   if (e.key === 'Enter') btnIndex.click();
 };
+
+// --- Graph visualization (inline) ---
+const graphTooltip = $('#graphTooltip');
+
+const GRAPH_PALETTE = [
+  '#3b82f6', '#a855f7', '#06b6d4', '#22c55e', '#f59e0b',
+  '#14b8a6', '#ec4899', '#eab308', '#f97316', '#f43f5e',
+  '#6366f1', '#84cc16', '#0ea5e9', '#d946ef', '#fb7185',
+];
+let graphCategoryColors = {};
+let graphData = null;
+let graphSimulation = null;
+let graphActiveCategories = new Set();
+let graphG = null;
+let graphZoom = null;
+let graphLinkGroup = null;
+let graphNodeGroup = null;
+
+function getCategoryColor(cat) {
+  if (!graphCategoryColors[cat]) {
+    const idx = Object.keys(graphCategoryColors).length % GRAPH_PALETTE.length;
+    graphCategoryColors[cat] = GRAPH_PALETTE[idx];
+  }
+  return graphCategoryColors[cat];
+}
+
+function renderGraph(data) {
+  totalResults = 0;
+  pagination.style.display = 'none';
+  graphData = data;
+
+  if (!data.nodes || data.nodes.length === 0) {
+    resultsEl.innerHTML = '<div class="empty-state"><p>No graph data. Index a repository first.</p></div>';
+    resultCount.textContent = '';
+    return;
+  }
+
+  resultCount.textContent = `${data.nodes.length} modules, ${data.edges.length} edges`;
+
+  // Assign category colors
+  graphCategoryColors = {};
+  const categories = [...new Set(data.nodes.map(n => n.category))].sort();
+  categories.forEach(c => getCategoryColor(c));
+  graphActiveCategories = new Set(categories);
+
+  // Build the inline graph HTML
+  resultsEl.innerHTML = `
+    <div class="graph-wrap" id="graphWrap">
+      <div class="graph-filters">
+        <div class="graph-filters-title">Categories</div>
+        <div class="graph-filter-badges" id="graphFilterBadges"></div>
+      </div>
+      <div class="graph-detail" id="graphDetail">
+        <div class="graph-detail-cat" id="graphDetailCat"></div>
+        <div class="graph-detail-name" id="graphDetailName"></div>
+        <div class="graph-detail-path" id="graphDetailPath"></div>
+        <div class="graph-detail-section">
+          <div class="graph-detail-section-title">Imports (<span id="graphDetailImportsCount">0</span>)</div>
+          <div id="graphDetailImports"></div>
+        </div>
+        <div class="graph-detail-section">
+          <div class="graph-detail-section-title">Imported By (<span id="graphDetailImportedByCount">0</span>)</div>
+          <div id="graphDetailImportedBy"></div>
+        </div>
+      </div>
+      <div class="graph-search">
+        <input type="text" id="graphSearchInput" placeholder="Search files..." autocomplete="off" spellcheck="false" />
+        <div class="graph-search-results" id="graphSearchResults"></div>
+      </div>
+      <svg id="graphSvg"></svg>
+    </div>
+  `;
+
+  // Build filter badges
+  const badgeContainer = $('#graphFilterBadges');
+  categories.forEach(cat => {
+    const badge = document.createElement('div');
+    badge.className = 'graph-badge active';
+    badge.dataset.cat = cat;
+    badge.innerHTML = `<span class="dot" style="background:${getCategoryColor(cat)}"></span>${esc(cat)}`;
+    badge.addEventListener('click', () => {
+      if (graphActiveCategories.has(cat)) {
+        graphActiveCategories.delete(cat);
+        badge.classList.remove('active');
+      } else {
+        graphActiveCategories.add(cat);
+        badge.classList.add('active');
+      }
+      updateGraphViz();
+    });
+    badgeContainer.appendChild(badge);
+  });
+
+  // SVG setup
+  const wrap = $('#graphWrap');
+  const width = wrap.clientWidth;
+  const height = wrap.clientHeight;
+  const svg = d3.select('#graphSvg').attr('width', width).attr('height', height);
+
+  graphG = svg.append('g');
+  graphZoom = d3.zoom()
+    .scaleExtent([0.05, 5])
+    .on('zoom', (e) => graphG.attr('transform', e.transform));
+  svg.call(graphZoom);
+
+  svg.append('defs').append('marker')
+    .attr('id', 'graph-arrow')
+    .attr('viewBox', '0 -3 6 6')
+    .attr('refX', 16).attr('refY', 0)
+    .attr('markerWidth', 5).attr('markerHeight', 5)
+    .attr('orient', 'auto')
+    .append('path')
+    .attr('d', 'M0,-3L6,0L0,3')
+    .attr('fill', '#555');
+
+  graphLinkGroup = graphG.append('g');
+  graphNodeGroup = graphG.append('g');
+
+  // Click empty space to dismiss detail
+  svg.on('click', () => {
+    const detail = $('#graphDetail');
+    if (detail) detail.classList.remove('visible');
+  });
+
+  updateGraphViz();
+
+  // Fit to view after simulation settles
+  setTimeout(() => {
+    if (!graphG || !graphG.node()) return;
+    const bounds = graphG.node().getBBox();
+    if (bounds.width === 0) return;
+    const dx = bounds.width, dy = bounds.height, x = bounds.x, y = bounds.y;
+    const scale = 0.85 / Math.max(dx / width, dy / height);
+    const translate = [width / 2 - scale * (x + dx / 2), height / 2 - scale * (y + dy / 2)];
+    svg.transition().duration(750).call(
+      graphZoom.transform,
+      d3.zoomIdentity.translate(translate[0], translate[1]).scale(scale)
+    );
+  }, 3000);
+
+  // Wire up inline search
+  const searchInput = $('#graphSearchInput');
+  const searchResultsEl = $('#graphSearchResults');
+  if (searchInput) {
+    searchInput.oninput = () => {
+      const q = searchInput.value.trim().toLowerCase();
+      if (!q || !graphData) {
+        searchResultsEl.innerHTML = '';
+        graphNodeGroup.selectAll('g.graph-node').classed('dimmed', false);
+        return;
+      }
+      const matches = graphData.nodes.filter(n => n.id.toLowerCase().includes(q)).slice(0, 20);
+      const matchIds = new Set(matches.map(m => m.id));
+      graphNodeGroup.selectAll('g.graph-node').classed('dimmed', n => !matchIds.has(n.id));
+      searchResultsEl.innerHTML = matches.map(m =>
+        `<div class="graph-search-result" data-id="${esc(m.id)}">${esc(m.id)}</div>`
+      ).join('');
+      searchResultsEl.querySelectorAll('.graph-search-result').forEach(el => {
+        el.onclick = () => {
+          const node = graphData.nodes.find(n => n.id === el.dataset.id);
+          if (!node || node.x == null) return;
+          const s = 1.5;
+          const t = [width / 2 - s * node.x, height / 2 - s * node.y];
+          svg.transition().duration(500).call(
+            graphZoom.transform, d3.zoomIdentity.translate(t[0], t[1]).scale(s)
+          );
+          onGraphNodeClick({ stopPropagation: () => {} }, node);
+        };
+      });
+    };
+  }
+}
+
+function updateGraphViz() {
+  if (!graphData) return;
+  const wrap = $('#graphWrap');
+  if (!wrap) return;
+  const width = wrap.clientWidth;
+  const height = wrap.clientHeight;
+
+  const nodes = graphData.nodes.filter(n => graphActiveCategories.has(n.category));
+  const nodeIds = new Set(nodes.map(n => n.id));
+  const edges = graphData.edges.filter(e =>
+    nodeIds.has(e.source?.id || e.source) && nodeIds.has(e.target?.id || e.target)
+  );
+
+  resultCount.textContent = `${nodes.length} modules, ${edges.length} edges`;
+
+  // In-degree for sizing
+  const inDegree = {};
+  edges.forEach(e => {
+    const tid = e.target?.id || e.target;
+    inDegree[tid] = (inDegree[tid] || 0) + 1;
+  });
+
+  // Links
+  const links = graphLinkGroup.selectAll('line').data(edges, d => `${d.source?.id||d.source}-${d.target?.id||d.target}`);
+  links.exit().remove();
+  links.enter().append('line')
+    .attr('class', 'graph-link')
+    .attr('stroke', '#555')
+    .attr('stroke-width', 1)
+    .attr('marker-end', 'url(#graph-arrow)');
+
+  // Nodes
+  const nodeData = graphNodeGroup.selectAll('g.graph-node').data(nodes, d => d.id);
+  nodeData.exit().remove();
+  const nodeEnter = nodeData.enter().append('g').attr('class', 'graph-node');
+
+  nodeEnter.append('circle')
+    .attr('r', d => Math.max(5, Math.min(14, 4 + (inDegree[d.id] || 0) * 1.5)))
+    .attr('fill', d => getCategoryColor(d.category))
+    .attr('stroke', d => d3.color(getCategoryColor(d.category)).brighter(0.5))
+    .on('mouseover', onGraphNodeHover)
+    .on('mouseout', onGraphNodeOut)
+    .on('click', onGraphNodeClick);
+
+  nodeEnter.append('text')
+    .attr('dx', d => Math.max(5, Math.min(14, 4 + (inDegree[d.id] || 0) * 1.5)) + 4)
+    .attr('dy', 3)
+    .text(d => d.label);
+
+  nodeData.select('circle')
+    .attr('r', d => Math.max(5, Math.min(14, 4 + (inDegree[d.id] || 0) * 1.5)))
+    .attr('fill', d => getCategoryColor(d.category));
+
+  nodeEnter.call(d3.drag()
+    .on('start', (e, d) => { if (!e.active) graphSimulation.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; })
+    .on('drag', (e, d) => { d.fx = e.x; d.fy = e.y; })
+    .on('end', (e, d) => { if (!e.active) graphSimulation.alphaTarget(0); d.fx = null; d.fy = null; })
+  );
+
+  const allLinks = graphLinkGroup.selectAll('line');
+  const allNodes = graphNodeGroup.selectAll('g.graph-node');
+
+  if (graphSimulation) graphSimulation.stop();
+  graphSimulation = d3.forceSimulation(nodes)
+    .force('link', d3.forceLink(edges).id(d => d.id).distance(80))
+    .force('charge', d3.forceManyBody().strength(-200))
+    .force('center', d3.forceCenter(width / 2, height / 2))
+    .force('collision', d3.forceCollide(25))
+    .on('tick', () => {
+      allLinks
+        .attr('x1', d => d.source.x).attr('y1', d => d.source.y)
+        .attr('x2', d => d.target.x).attr('y2', d => d.target.y);
+      allNodes.attr('transform', d => `translate(${d.x},${d.y})`);
+    });
+}
+
+function onGraphNodeHover(event, d) {
+  graphTooltip.style.display = 'block';
+  graphTooltip.style.left = (event.clientX + 12) + 'px';
+  graphTooltip.style.top = (event.clientY - 8) + 'px';
+  graphTooltip.textContent = d.id;
+
+  const connected = new Set([d.id]);
+  graphData.edges.forEach(e => {
+    const sid = e.source?.id || e.source;
+    const tid = e.target?.id || e.target;
+    if (sid === d.id) connected.add(tid);
+    if (tid === d.id) connected.add(sid);
+  });
+
+  graphNodeGroup.selectAll('g.graph-node')
+    .classed('dimmed', n => !connected.has(n.id))
+    .classed('highlighted', n => n.id === d.id);
+  graphLinkGroup.selectAll('line').classed('highlighted', e => {
+    const sid = e.source?.id || e.source;
+    const tid = e.target?.id || e.target;
+    return sid === d.id || tid === d.id;
+  });
+}
+
+function onGraphNodeOut() {
+  graphTooltip.style.display = 'none';
+  graphNodeGroup.selectAll('g.graph-node').classed('dimmed', false).classed('highlighted', false);
+  graphLinkGroup.selectAll('line').classed('highlighted', false);
+}
+
+function onGraphNodeClick(event, d) {
+  event.stopPropagation();
+  const detail = $('#graphDetail');
+  if (!detail) return;
+  detail.classList.add('visible');
+  $('#graphDetailCat').textContent = d.category;
+  $('#graphDetailCat').style.color = getCategoryColor(d.category);
+  $('#graphDetailName').textContent = d.label;
+  const pathEl = $('#graphDetailPath');
+  pathEl.textContent = d.id;
+  pathEl.onclick = () => openFile(d.id);
+
+  const imports = graphData.edges
+    .filter(e => (e.source?.id || e.source) === d.id)
+    .map(e => graphData.nodes.find(n => n.id === (e.target?.id || e.target)))
+    .filter(Boolean);
+  const importedBy = graphData.edges
+    .filter(e => (e.target?.id || e.target) === d.id)
+    .map(e => graphData.nodes.find(n => n.id === (e.source?.id || e.source)))
+    .filter(Boolean);
+
+  $('#graphDetailImportsCount').textContent = imports.length;
+  $('#graphDetailImports').innerHTML = imports.map(n =>
+    `<div class="graph-detail-item"><span class="dot" style="background:${getCategoryColor(n.category)}"></span>${esc(n.label)}</div>`
+  ).join('');
+  $('#graphDetailImportedByCount').textContent = importedBy.length;
+  $('#graphDetailImportedBy').innerHTML = importedBy.map(n =>
+    `<div class="graph-detail-item"><span class="dot" style="background:${getCategoryColor(n.category)}"></span>${esc(n.label)}</div>`
+  ).join('');
+}
+
+// --- Context-aware empty state ---
+function updateEmptyState() {
+  const emptyMsg = $('#emptyMsg');
+  if (!emptyMsg) return;
+  const hasRecent = getRecentRepos().length > 0;
+  if (hasRecent) {
+    emptyMsg.innerHTML = `Select an indexed repository above, or add a new one.<br>
+      Drop a folder, click <strong>Browse</strong>, or type a path.<br><br>
+      <kbd>&#8984;O</kbd> browse &nbsp; <kbd>&#8984;K</kbd> focus search`;
+  } else {
+    emptyMsg.innerHTML = `Drop a folder here, click <strong>Browse</strong>, or type a path above.<br>
+      Then search symbols, explore the map, or trace callers.<br><br>
+      <kbd>&#8984;O</kbd> browse &nbsp; <kbd>&#8984;K</kbd> focus search`;
+  }
+}
+updateEmptyState();
 </script>
 </body>
 </html>