@mishasinitcyn/betterrank 0.1.9 → 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.9",
+  "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})
@@ -32,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.
@@ -230,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`);

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) {