@mishasinitcyn/betterrank 0.1.8 → 0.2.0

package/README.md

@@ -16,6 +16,12 @@ npm install -g @mishasinitcyn/betterrank
 # Get a ranked overview of any project
 betterrank map --root /path/to/project
 
+# View a file's skeleton without reading the whole thing
+betterrank outline src/auth.py
+
+# Expand a specific function to see its full source
+betterrank outline src/auth.py authenticate_user
+
 # Search for symbols by name or parameter
 betterrank search auth --root /path/to/project
 
@@ -45,6 +51,42 @@ JavaScript, TypeScript, Python, Rust, Go, Java, Ruby, C, C++, C#, PHP
 
 ## Commands
 
+### `outline` — File skeleton with collapsed bodies
+
+View a file's structure without reading the entire thing. Function and class bodies are collapsed to `... (N lines)`. Expand specific symbols by name. **No `--root` required** — works on any file standalone.
+
+```bash
+# Skeleton view: imports, signatures, constants — bodies collapsed
+betterrank outline src/auth.py
+
+# Expand a specific function to see its full source
+betterrank outline src/auth.py authenticate_user
+
+# Expand multiple symbols
+betterrank outline src/auth.py validate,process
+
+# Resolve path relative to a root
+betterrank outline src/auth.py --root ./backend
+```
+
+**Example output:**
+```
+   1│ from fastapi import APIRouter, Depends
+   2│ from core.auth import verify_auth
+   3│
+   4│ router = APIRouter(prefix="/api")
+   5│
+   6│ @router.get("/users")
+   7│ async def list_users(db = Depends(get_db)):
+    │   ... (25 lines)
+  33│
+  34│ @router.post("/users")
+  35│ async def create_user(data: UserCreate, db = Depends(get_db)):
+    │   ... (40 lines)
+```
+
+Typical compression: **3-5x** (a 2000-line file becomes ~400 lines of outline).
+
 ### `map` — Repo map
 
 Summary of the most structurally important definitions, ranked by PageRank. Default limit is 50 symbols.
@@ -99,6 +141,14 @@ betterrank neighborhood src/auth.ts --root /path/to/project --count
 betterrank neighborhood src/auth.ts --root /path/to/project --hops 2 --limit 10
 ```
 
+### `orphans` — Find disconnected files/symbols
+
+```bash
+betterrank orphans --root /path/to/project                          # orphan files
+betterrank orphans --level symbol --root /path/to/project           # orphan symbols
+betterrank orphans --level symbol --kind function --root /path/to/project
+```
+
 ### `structure` — File tree with symbol counts
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mishasinitcyn/betterrank",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "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/cli.js

@@ -2,6 +2,7 @@
 
 import { CodeIndex } from './index.js';
 import { resolve, relative, isAbsolute } from 'path';
+import { readFile } from 'fs/promises';
 
 const DEFAULT_LIMIT = 50;
 const DEFAULT_DEPTH = 3;
@@ -11,6 +12,7 @@ betterrank <command> [options]
 
 Commands:
   ui          [--port N]                            Launch web UI (default port: 3333)
+  outline     <file> [symbol1,symbol2]              File skeleton with collapsed bodies
   map         [--focus file1,file2]                 Repo map (ranked by PageRank)
   search      <query> [--kind type]                 Substring search on symbol names + signatures (ranked by PageRank)
   structure   [--depth N]                           File tree with symbol counts (default depth: ${DEFAULT_DEPTH})
@@ -19,6 +21,7 @@ Commands:
   deps        <file>                                What this file imports (ranked)
   dependents  <file>                                What imports this file (ranked)
   neighborhood <file> [--hops N] [--max-files N]    Local subgraph (ranked by PageRank)
+  orphans     [--level file|symbol] [--kind type]   Find disconnected files/symbols
   reindex                                           Force full rebuild
   stats                                             Index statistics
 
@@ -31,6 +34,26 @@ Global flags:
 `.trim();
 
 const COMMAND_HELP = {
+  outline: `betterrank outline <file> [symbol1,symbol2,...] [--root <path>]
+
+View a file's structure with function/class bodies collapsed, or expand
+specific symbols to see their full source.
+
+Without symbol names: shows the file skeleton — imports, constants, and
+function/class signatures with bodies replaced by "... (N lines)".
+
+With symbol names (comma-separated): shows the full source of those
+specific functions/classes with line numbers.
+
+Options:
+  --root <path>   Resolve file path relative to this directory
+
+Examples:
+  betterrank outline src/auth.py
+  betterrank outline src/auth.py authenticate_user
+  betterrank outline src/auth.py validate,process
+  betterrank outline src/handlers.ts --root ./backend`,
+
   map: `betterrank map [--focus file1,file2] [--root <path>]
 
 Aider-style repo map: the most structurally important definitions ranked by PageRank.
@@ -146,6 +169,30 @@ Examples:
   betterrank neighborhood src/auth/handlers.ts --root ./backend
   betterrank neighborhood src/api/bid.js --hops 3 --max-files 20 --root .`,
 
+  orphans: `betterrank orphans [--level file|symbol] [--kind type] [--root <path>]
+
+Find disconnected files or symbols — the "satellites" in the graph UI.
+
+Levels:
+  file     Files with zero cross-file imports (default)
+  symbol   Symbols never referenced from outside their own file (dead code candidates)
+
+Options:
+  --level <type>   "file" or "symbol" (default: file)
+  --kind <type>    Filter symbols: function, class, type, variable (only with --level symbol)
+  --count          Return count only
+  --offset N       Skip first N results
+  --limit N        Max results (default: ${DEFAULT_LIMIT})
+
+False positives (entry points, config files, tests, framework hooks, dunders,
+etc.) are automatically excluded.
+
+Examples:
+  betterrank orphans --root ./backend
+  betterrank orphans --level symbol --root .
+  betterrank orphans --level symbol --kind function --root .
+  betterrank orphans --count --root .`,
+
   reindex: `betterrank reindex [--root <path>]
 
 Force a full rebuild of the index. Use after branch switches, large merges,
@@ -205,6 +252,34 @@ async function main() {
     return; // Keep process alive (server is listening)
   }
 
+  // Outline command — standalone, no CodeIndex needed
+  if (command === 'outline') {
+    const filePath = flags._positional[0];
+    if (!filePath) {
+      console.error('Usage: betterrank outline <file> [symbol1,symbol2]');
+      process.exit(1);
+    }
+    const expandSymbols = flags._positional[1] ? flags._positional[1].split(',') : [];
+
+    const root = flags.root ? resolve(flags.root) : process.cwd();
+    const absPath = isAbsolute(filePath) ? filePath : resolve(root, filePath);
+
+    let source;
+    try {
+      source = await readFile(absPath, 'utf-8');
+    } catch (err) {
+      console.error(`Cannot read file: ${absPath}`);
+      console.error(err.message);
+      process.exit(1);
+    }
+
+    const relPath = relative(root, absPath);
+    const { buildOutline } = await import('./outline.js');
+    const result = buildOutline(source, relPath, expandSymbols);
+    console.log(result);
+    return;
+  }
+
   const projectRoot = resolve(flags.root || process.cwd());
   if (!flags.root) {
     process.stderr.write(`⚠ No --root specified, using cwd: ${projectRoot}\n`);
@@ -465,6 +540,55 @@ async function main() {
       break;
     }
 
+    case 'orphans': {
+      const level = flags.level || 'file';
+      if (level !== 'file' && level !== 'symbol') {
+        console.error(`Unknown level: "${level}". Use "file" or "symbol".`);
+        process.exit(1);
+      }
+      const effectiveLimit = countMode ? undefined : (userLimit !== undefined ? userLimit : DEFAULT_LIMIT);
+      const result = await idx.orphans({ level, kind: flags.kind, count: countMode, offset, limit: effectiveLimit });
+
+      if (countMode) {
+        console.log(`total: ${result.total}`);
+      } else if (level === 'file') {
+        for (const f of result) {
+          console.log(`${f.file}  (${f.symbolCount} symbols)`);
+        }
+        if (result.length === 0) {
+          console.log('(no orphan files found)');
+        } else {
+          const total = await idx.orphans({ level, count: true });
+          if (result.length < total.total) {
+            console.log(`\nShowing ${result.length} of ${total.total} orphan files (use --limit N for more)`);
+          }
+        }
+      } else {
+        // symbol level — group by file like map output
+        const byFile = new Map();
+        for (const s of result) {
+          if (!byFile.has(s.file)) byFile.set(s.file, []);
+          byFile.get(s.file).push(s);
+        }
+        for (const [file, syms] of byFile) {
+          console.log(`${file}:`);
+          for (const s of syms) {
+            console.log(`  ${String(s.lineStart).padStart(4)}│ [${s.kind}] ${s.signature}`);
+          }
+          console.log('');
+        }
+        if (result.length === 0) {
+          console.log('(no orphan symbols found)');
+        } else {
+          const total = await idx.orphans({ level, kind: flags.kind, count: true });
+          if (result.length < total.total) {
+            console.log(`Showing ${result.length} of ${total.total} orphan symbols across ${byFile.size} files (use --limit N for more)`);
+          }
+        }
+      }
+      break;
+    }
+
     case 'reindex': {
       const t0 = Date.now();
       const result = await idx.reindex();

package/src/index.js

@@ -3,6 +3,132 @@ import { join, dirname, relative, sep, basename } from 'path';
 import { CodeIndexCache } from './cache.js';
 import { rankedSymbols } from './graph.js';
 
+// ── Orphan false-positive filters ──────────────────────────────────────────
+//
+// Orphan detection finds files/symbols with no cross-file connections.
+// Many of these are false positives: entry points, config, tests, framework
+// hooks, etc. that are invoked by runtimes, not by other source files.
+// These filters aggressively exclude them (at the cost of some true positives).
+
+// File basenames (without extension) that are runtime entry points, config,
+// or package markers — they have no incoming IMPORTS because the runtime
+// loads them directly, not because they're dead.
+const ORPHAN_EXCLUDED_BASENAMES = new Set([
+  'index', 'main', 'app', 'server', 'cli', 'mod', 'lib',
+  'manage', 'wsgi', 'asgi', 'handler', 'lambda',
+  '__init__', '__main__',
+  'config', 'settings', 'conf', 'conftest', 'setup',
+  'gulpfile', 'gruntfile', 'makefile', 'rakefile', 'taskfile',
+]);
+
+// Path segments indicating test/spec directories
+const TEST_PATH_SEGMENTS = [
+  '/test/', '/tests/', '/__tests__/', '/spec/', '/specs/',
+  '/testing/', '/fixtures/', '/mocks/', '/e2e/', '/cypress/',
+];
+
+function isTestFile(filePath) {
+  const lower = '/' + filePath.toLowerCase();
+  for (const seg of TEST_PATH_SEGMENTS) {
+    if (lower.includes(seg)) return true;
+  }
+  const stem = basename(filePath).replace(/\.[^.]+$/, '').toLowerCase();
+  return (
+    stem.startsWith('test_') || stem.startsWith('test.') ||
+    stem.endsWith('.test') || stem.endsWith('.spec') ||
+    stem.endsWith('_test') || stem.endsWith('_spec')
+  );
+}
+
+function isOrphanFalsePositiveFile(filePath) {
+  const base = basename(filePath);
+  const stem = base.replace(/\.[^.]+$/, '').toLowerCase();
+
+  if (ORPHAN_EXCLUDED_BASENAMES.has(stem)) return true;
+
+  // Dotfiles are always config (.eslintrc, .prettierrc, etc.)
+  if (base.startsWith('.')) return true;
+
+  // Type definition files (.d.ts) — consumed by the compiler, not by imports
+  if (filePath.endsWith('.d.ts')) return true;
+
+  // Config files with compound names (vite.config.ts, jest.config.js, etc.)
+  if (/[./]config$/i.test(stem) || /\.rc$/i.test(stem)) return true;
+
+  // Test/spec files — invoked by test runners
+  if (isTestFile(filePath)) return true;
+
+  return false;
+}
+
+// Symbol names that are entry points, lifecycle hooks, or framework-called.
+const FRAMEWORK_INVOKED_SYMBOLS = new Set([
+  'main', 'run', 'start', 'serve', 'handler', 'execute', 'app',
+  'setup', 'teardown', 'setUp', 'tearDown',
+  'beforeAll', 'afterAll', 'beforeEach', 'afterEach', 'before', 'after',
+  'constructor', 'init', 'initialize', 'configure', 'register',
+  'middleware', 'plugin', 'default', 'module', 'exports',
+]);
+
+/**
+ * Detect if a function signature is likely a class/instance method rather
+ * than a standalone function. Method calls (obj.method()) are intentionally
+ * not tracked as references (too noisy without type info), so all methods
+ * appear orphaned. We exclude them to avoid flooding the results.
+ */
+function isLikelyMethod(signature, filePath) {
+  if (!signature) return false;
+  const s = signature.trimStart();
+
+  const ext = filePath.substring(filePath.lastIndexOf('.'));
+
+  // JS/TS: standalone functions always use the `function` keyword.
+  // Class methods don't: `async ensure()`, `getGraph()`, `constructor()`.
+  // Arrow functions assigned to vars are kind='variable', not 'function',
+  // so they don't reach this check.
+  if (['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'].includes(ext)) {
+    return !/^(export\s+)?(default\s+)?(async\s+)?function[\s(]/.test(s);
+  }
+
+  // Python: methods have self or cls as first parameter
+  if (ext === '.py') {
+    return /\(\s*(self|cls)\s*[,)]/.test(s);
+  }
+
+  // Java/C#/Go: harder to detect without parent context — don't filter
+  return false;
+}
+
+function isOrphanFalsePositiveSymbol(name, kind, filePath, signature) {
+  if (FRAMEWORK_INVOKED_SYMBOLS.has(name)) return true;
+
+  // Python dunders — called implicitly by the runtime
+  if (name.startsWith('__') && name.endsWith('__')) return true;
+
+  // Test functions — called by test runners
+  if (name.startsWith('test_') || name.startsWith('Test') ||
+      name.startsWith('spec_') || name.startsWith('Spec')) return true;
+
+  // Very short names — too generic, ambiguity cap probably suppressed real refs
+  if (name.length <= 2) return true;
+
+  // Class/instance methods — obj.method() calls aren't tracked as references,
+  // so every method appears orphaned. Filter them out.
+  if (kind === 'function' && isLikelyMethod(signature, filePath)) return true;
+
+  // Symbols in test files — all invoked by the test runner
+  if (isTestFile(filePath)) return true;
+
+  // Symbols in entry point / config files — reachable via runtime
+  if (isOrphanFalsePositiveFile(filePath)) return true;
+
+  // Symbol name matches file basename — likely the primary export
+  const fileBase = basename(filePath).replace(/\.[^.]+$/, '');
+  if (name === fileBase || name.toLowerCase() === fileBase.toLowerCase()) return true;
+
+  return false;
+}
+
 /**
  * Find file nodes in the graph that look similar to the given path.
  * Uses basename matching and substring matching on the full path.
@@ -635,6 +761,98 @@ class CodeIndex {
     };
   }
 
+  /**
+   * Find orphaned files or symbols — nodes with no cross-file connections.
+   *
+   * level='file': files with zero IMPORTS edges (neither importing nor imported).
+   *   These are the "satellites" in the graph UI.
+   *
+   * level='symbol': symbols with no incoming REFERENCES from outside their own file.
+   *   Dead code candidates — defined but never used cross-file.
+   *
+   * False positives (entry points, config files, test files, framework hooks,
+   * dunders, etc.) are excluded by default.
+   *
+   * @param {object} [opts]
+   * @param {'file'|'symbol'} [opts.level='file'] - Granularity
+   * @param {string} [opts.kind] - Filter symbols by kind (only for level='symbol')
+   * @param {number} [opts.offset] - Skip first N results
+   * @param {number} [opts.limit] - Max results to return
+   * @param {boolean} [opts.count=false] - If true, return only { total }
+   * @returns {Array|{total: number}}
+   */
+  async orphans({ level = 'file', kind, offset, limit, count = false } = {}) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph || graph.order === 0) return count ? { total: 0 } : [];
+
+    if (level === 'file') {
+      const results = [];
+      graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'file') return;
+
+        // Skip false positives: entry points, config, tests
+        if (isOrphanFalsePositiveFile(node)) return;
+
+        // Check for any IMPORTS edge (in or out)
+        let hasImport = false;
+        graph.forEachEdge(node, (_edge, edgeAttrs) => {
+          if (!hasImport && edgeAttrs.type === 'IMPORTS') hasImport = true;
+        });
+
+        if (!hasImport) {
+          results.push({ file: node, symbolCount: attrs.symbolCount || 0 });
+        }
+      });
+
+      // Meatier files first — more likely to be real orphans worth investigating
+      results.sort((a, b) => b.symbolCount - a.symbolCount);
+      if (count) return { total: results.length };
+      return paginate(results, { offset, limit }).items;
+    }
+
+    if (level === 'symbol') {
+      const results = [];
+      graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'symbol') return;
+        if (kind && attrs.kind !== kind) return;
+
+        // Skip false positives: framework hooks, dunders, test funcs, methods, etc.
+        if (isOrphanFalsePositiveSymbol(attrs.name, attrs.kind, attrs.file, attrs.signature)) return;
+
+        // Check for any incoming REFERENCES from a different file
+        let hasExternalRef = false;
+        graph.forEachInEdge(node, (_edge, edgeAttrs, source) => {
+          if (hasExternalRef) return;
+          if (edgeAttrs.type !== 'REFERENCES') return;
+          try {
+            const sourceFile = graph.getNodeAttribute(source, 'file') || source;
+            if (sourceFile !== attrs.file) hasExternalRef = true;
+          } catch {
+            if (source !== attrs.file) hasExternalRef = true;
+          }
+        });
+
+        if (!hasExternalRef) {
+          results.push({
+            name: attrs.name,
+            kind: attrs.kind,
+            file: attrs.file,
+            lineStart: attrs.lineStart,
+            signature: attrs.signature,
+          });
+        }
+      });
+
+      // Group by file, then by line within file
+      results.sort((a, b) => a.file.localeCompare(b.file) || a.lineStart - b.lineStart);
+      if (count) return { total: results.length };
+      return paginate(results, { offset, limit }).items;
+    }
+
+    throw new Error(`Unknown level: "${level}". Use "file" or "symbol".`);
+  }
+
   /**
    * File-level dependency graph for visualization.
    * Returns nodes (files) ranked by PageRank and IMPORTS edges between them.

package/src/outline.js

@@ -0,0 +1,139 @@
+import { parseFile, SUPPORTED_EXTENSIONS } from './parser.js';
+import { extname } from 'path';
+
+const MIN_COLLAPSE_LINES = 2;
+
+/**
+ * Build an outline view of a source file.
+ *
+ * Without expandSymbols: returns a skeleton with function/class bodies collapsed.
+ * With expandSymbols: returns the full source of the specified symbols.
+ *
+ * @param {string} source - File contents
+ * @param {string} filePath - File path (for language detection)
+ * @param {string[]} expandSymbols - Symbol names to expand (empty = outline mode)
+ * @returns {string} Formatted output with line numbers
+ */
+export function buildOutline(source, filePath, expandSymbols = []) {
+  const lines = source.split('\n');
+  const pad = Math.max(String(lines.length).length, 4);
+
+  const ext = extname(filePath);
+  if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+    return rawView(lines, pad);
+  }
+
+  const parsed = parseFile(filePath, source);
+  if (!parsed || parsed.definitions.length === 0) {
+    return rawView(lines, pad);
+  }
+
+  // Deduplicate definitions by lineStart (decorated_definition can cause dupes)
+  const seenLines = new Set();
+  const defs = parsed.definitions
+    .filter(d => {
+      if (seenLines.has(d.lineStart)) return false;
+      seenLines.add(d.lineStart);
+      return true;
+    })
+    .sort((a, b) => a.lineStart - b.lineStart);
+
+  if (expandSymbols.length > 0) {
+    return expandMode(lines, defs, filePath, expandSymbols, pad);
+  }
+  return outlineMode(lines, defs, pad);
+}
+
+function rawView(lines, pad) {
+  return lines.map((l, i) => `${String(i + 1).padStart(pad)}│ ${l}`).join('\n');
+}
+
+function expandMode(lines, defs, filePath, expandSymbols, pad) {
+  const output = [];
+
+  for (const symName of expandSymbols) {
+    const matches = defs.filter(d => d.name === symName);
+
+    if (matches.length === 0) {
+      output.push(`Symbol "${symName}" not found in ${filePath}`);
+      const similar = [...new Set(
+        defs.filter(d => d.name.toLowerCase().includes(symName.toLowerCase()))
+          .map(d => d.name)
+      )].slice(0, 5);
+      if (similar.length > 0) {
+        output.push(`Did you mean: ${similar.join(', ')}`);
+      } else {
+        output.push(`Available: ${defs.map(d => d.name).join(', ')}`);
+      }
+      continue;
+    }
+
+    for (const def of matches) {
+      if (matches.length > 1 || expandSymbols.length > 1) {
+        output.push(`── ${def.name} (${filePath}:${def.lineStart}-${def.lineEnd}) ──`);
+      }
+      for (let i = def.lineStart; i <= def.lineEnd; i++) {
+        output.push(`${String(i).padStart(pad)}│ ${lines[i - 1]}`);
+      }
+      if (matches.length > 1) output.push('');
+    }
+  }
+
+  return output.join('\n').trimEnd();
+}
+
+function outlineMode(lines, defs, pad) {
+  // Detect containers: definitions that have child definitions inside them
+  const containers = new Set();
+  for (const def of defs) {
+    for (const other of defs) {
+      if (other === def) continue;
+      if (other.lineStart > def.lineStart && other.lineEnd <= def.lineEnd) {
+        containers.add(def);
+        break;
+      }
+    }
+  }
+
+  // Build collapse ranges for leaf definitions with sufficient body size
+  const collapseRanges = [];
+  for (const def of defs) {
+    if (containers.has(def)) continue;
+    if (!def.bodyStartLine) continue;
+    if (def.bodyStartLine > def.lineEnd) continue;
+
+    const bodyLineCount = def.lineEnd - def.bodyStartLine + 1;
+    if (bodyLineCount < MIN_COLLAPSE_LINES) continue;
+
+    collapseRanges.push({
+      start: def.bodyStartLine,
+      end: def.lineEnd,
+      lineCount: bodyLineCount,
+    });
+  }
+
+  collapseRanges.sort((a, b) => a.start - b.start);
+
+  // Walk lines, skipping collapsed ranges
+  const output = [];
+  let lineNum = 1;
+  let rangeIdx = 0;
+
+  while (lineNum <= lines.length) {
+    if (rangeIdx < collapseRanges.length && collapseRanges[rangeIdx].start === lineNum) {
+      const range = collapseRanges[rangeIdx];
+      // Use the indent of the first body line for natural alignment
+      const bodyLine = lines[lineNum - 1];
+      const indent = bodyLine ? bodyLine.match(/^\s*/)[0] : '';
+      output.push(`${' '.repeat(pad)}│ ${indent}... (${range.lineCount} lines)`);
+      lineNum = range.end + 1;
+      rangeIdx++;
+      continue;
+    }
+
+    output.push(`${String(lineNum).padStart(pad)}│ ${lines[lineNum - 1]}`);
+    lineNum++;
+  }
+
+  return output.join('\n');
+}

package/src/parser.js

@@ -246,6 +246,26 @@ const KIND_MAP = {
   decorated_definition: 'function',
 };
 
+/**
+ * Find the body/block node of a definition, drilling into wrappers like
+ * lexical_declaration → variable_declarator → arrow_function → body.
+ */
+function findBodyNode(node) {
+  let body = node.childForFieldName('body');
+  if (body) return body;
+
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    body = child.childForFieldName('body');
+    if (body) return body;
+    for (let j = 0; j < child.namedChildCount; j++) {
+      body = child.namedChild(j).childForFieldName('body');
+      if (body) return body;
+    }
+  }
+  return null;
+}
+
 function nodeKind(nodeType) {
   return KIND_MAP[nodeType] || 'other';
 }
@@ -309,6 +329,17 @@ function parseFile(filePath, source) {
         if (!nameCapture) continue;
         const defNode = defCapture || nameCapture;
 
+        // Compute where body content starts (for outline collapsing)
+        const bodyNode = findBodyNode(defNode.node);
+        let bodyStartLine = null;
+        if (bodyNode) {
+          const bodyRow = bodyNode.startPosition.row;    // 0-indexed
+          const defRow = defNode.node.startPosition.row; // 0-indexed
+          // If body opens on same line as def (JS: `function foo() {`),
+          // content starts on next line. Otherwise body IS the content.
+          bodyStartLine = bodyRow === defRow ? bodyRow + 2 : bodyRow + 1; // 1-indexed
+        }
+
         definitions.push({
           name: nameCapture.node.text,
           kind: nodeKind(defNode.node.type),
@@ -316,6 +347,7 @@ function parseFile(filePath, source) {
           lineStart: defNode.node.startPosition.row + 1,
           lineEnd: defNode.node.endPosition.row + 1,
           signature: extractSignature(defNode.node, langName),
+          bodyStartLine,
         });
       }
     } catch (e) {

package/src/server.js

@@ -257,6 +257,24 @@ const routes = {
     json(res, result);
   },
 
+  'GET /api/orphans': async (req, res) => {
+    if (!requireIndex(res)) return;
+    const p = params(req.url);
+    const level = p.get('level', 'file');
+    const results = await currentIndex.orphans({
+      level,
+      kind: p.get('kind', undefined),
+      offset: p.getInt('offset', undefined),
+      limit: p.getInt('limit', 50),
+    });
+    const total = await currentIndex.orphans({
+      level,
+      kind: p.get('kind', undefined),
+      count: true,
+    });
+    json(res, { results, total: total.total });
+  },
+
   'GET /api/structure': async (req, res) => {
     if (!requireIndex(res)) return;
     const p = params(req.url);