@mishasinitcyn/betterrank 0.2.1 → 0.2.3

package/README.md

@@ -28,6 +28,9 @@ betterrank search auth --root /path/to/project
 # Who calls this function? (with call site context)
 betterrank callers authenticateUser --root /path/to/project --context
 
+# Everything about a function: source, types, deps, callers
+betterrank context calculate_bid --root /path/to/project
+
 # Trace the full call chain from entry point to function
 betterrank trace calculate_bid --root /path/to/project
 
@@ -152,6 +155,62 @@ src/api/serve.py:
      145│     bid = await run_auction(searched, publisher=pub_id)
 ```
 
+### `context` — Full function context in one shot
+
+Everything you need to understand a function: its source, the types in its signature (expanded inline), the functions it calls (with signatures), and a callers summary. Eliminates the multi-command chase.
+
+```bash
+betterrank context calculate_bid --root /path/to/project
+
+# Skip the source, just show deps/types/callers
+betterrank context calculate_bid --root /path/to/project --no-source
+```
+
+**Example output (`--no-source`):**
+```
+── calculate_bid (src/engine/bidding.py:489-718) ──
+
+Types:
+  AuctionData2 (src/engine/bidding.py:74)
+    publisher_id: str
+    campaign_metrics: Dict[str, CampaignMetrics]
+    time_remaining_pct: float
+
+References:
+  [function] def from_microdollars(microdollars) -> Decimal  (src/core/currency.py:108)
+  [function] def get_config() -> ValuePredictorConfig        (src/engine/predictor/config.py:316)
+  [function] def get_value_predictor() -> ValuePredictor      (src/engine/predictor/persistence.py:123)
+  [class]    class ValuePredictor                             (src/engine/predictor/predictor.py:43)
+
+Callers (1 file):
+  src/engine/bidding.py
+```
+
+### `history` — Git history of a specific function
+
+Shows only commits that touched a function's lines. Uses tree-sitter line ranges for accuracy (better than git's heuristic `:funcname:` detection). Add `--patch` to include function-scoped diffs.
+
+```bash
+# Commit list (compact)
+betterrank history calculate_bid --root /path/to/project
+
+# With function-scoped diffs
+betterrank history calculate_bid --root /path/to/project --patch --limit 3
+
+# Paginate through older commits
+betterrank history calculate_bid --root /path/to/project --offset 5 --limit 5
+```
+
+**Example output:**
+```
+calculate_bid (src/engine/bidding.py:489-718)
+
+  082b9d5  2026-02-24  fix: restore GSP auction pricing
+  c75f5ff  2026-02-14  fix: resolve lint errors from main merge
+  623429c  2026-02-13  hot fix
+  5d236d3  2026-02-06  feat: wire ad_position to ValuePredictor
+```
+
 ### `trace` — Recursive caller chain
 
 Walk UP the call graph from a symbol to see the full path from entry points to your function. At each hop, resolves which function in the caller file contains the call site.

package/package.json

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

@@ -18,6 +18,8 @@ Commands:
   structure   [--depth N]                           File tree with symbol counts (default depth: ${DEFAULT_DEPTH})
   symbols     [--file path] [--kind type]           List definitions (ranked by PageRank)
   callers     <symbol> [--file path] [--context]     All call sites (ranked, with context lines)
+  context     <symbol> [--file path]                 Full context: source, deps, types, callers
+  history     <symbol> [--file path]                Git history of a specific function
   trace       <symbol> [--depth N]                  Recursive caller chain (call tree)
   diff        [--ref <commit>]                      Git-aware blast radius (changed symbols + callers)
   deps        <file>                                What this file imports (ranked)
@@ -136,6 +138,41 @@ Examples:
   betterrank callers authenticateUser --root ./backend --context
   betterrank callers resolve --file src/utils.ts --root . --context 3`,
 
+  context: `betterrank context <symbol> [--file path] [--root <path>]
+
+Everything you need to understand a function in one shot.
+
+Shows: the function's source, signatures of all functions/types it references,
+expanded type definitions from the signature, and a callers summary.
+
+Eliminates the multi-command chase of: outline → expand → search types → callers.
+
+Options:
+  --file <path>    Disambiguate when multiple symbols share a name
+  --no-source      Skip the function source (show only deps/types/callers)
+
+Examples:
+  betterrank context calculate_bid --root .
+  betterrank context Router --file src/llm.py --root .`,
+
+  history: `betterrank history <symbol> [--file path] [--patch] [--limit N] [--root <path>]
+
+Git history of a specific function. Uses the tree-sitter line range to
+show only commits that touched that function's lines.
+
+More accurate than git log -L :funcname: because betterrank knows the
+exact line range from tree-sitter, not git's heuristic function detection.
+
+Options:
+  --file <path>    Disambiguate when multiple symbols share a name
+  --patch, -p      Include function-scoped diffs (not just commit list)
+  --limit N        Max commits to show (default: 20)
+
+Examples:
+  betterrank history calculate_bid --root .
+  betterrank history calculate_bid --root . --patch --limit 3
+  betterrank history Router --file src/llm.py --root .`,
+
   trace: `betterrank trace <symbol> [--depth N] [--file path] [--root <path>]
 
 Recursive caller chain — walk UP the call graph from a symbol to see
@@ -509,6 +546,100 @@ async function main() {
       break;
     }
 
+    case 'context': {
+      const symbol = flags._positional[0];
+      if (!symbol) { console.error('Usage: betterrank context <symbol> [--file path]'); process.exit(1); }
+      const noSource = flags['no-source'] === true;
+      const result = await idx.context({ symbol, file: normalizeFilePath(flags.file) });
+      if (!result) {
+        console.log(`(symbol "${symbol}" not found)`);
+        break;
+      }
+
+      const def = result.definition;
+      const pad = Math.max(String(def.lineEnd).length, 4);
+
+      // Header
+      console.log(`── ${def.name} (${def.file}:${def.lineStart}-${def.lineEnd}) ──`);
+      console.log('');
+
+      // Source (or just the signature in --no-source mode)
+      if (!noSource) {
+        for (let i = 0; i < def.source.length; i++) {
+          console.log(`  ${String(def.lineStart + i).padStart(pad)}│ ${def.source[i]}`);
+        }
+        console.log('');
+      } else if (def.signature) {
+        console.log(`  ${def.signature}`);
+        console.log('');
+      }
+
+      // Type references from signature
+      if (result.typeRefs.length > 0) {
+        console.log('Types:');
+        for (const t of result.typeRefs) {
+          console.log(`  ${t.name} (${t.file}:${t.lineStart})`);
+          if (t.fields) {
+            for (const line of t.fields) {
+              console.log(`    ${line}`);
+            }
+          }
+          console.log('');
+        }
+      }
+
+      // Used symbols (functions/types referenced in the body)
+      if (result.usedSymbols.length > 0) {
+        console.log('References:');
+        for (const s of result.usedSymbols) {
+          const loc = s.file === def.file ? `line ${s.lineStart}` : `${s.file}:${s.lineStart}`;
+          console.log(`  [${s.kind}] ${s.signature || s.name}  (${loc})`);
+        }
+        console.log('');
+      }
+
+      // Callers
+      if (result.callers.length > 0) {
+        console.log(`Callers (${result.callers.length} file${result.callers.length === 1 ? '' : 's'}):`);
+        for (const f of result.callers) {
+          console.log(`  ${f}`);
+        }
+      } else {
+        console.log('Callers: (none detected)');
+      }
+      break;
+    }
+
+    case 'history': {
+      const symbol = flags._positional[0];
+      if (!symbol) { console.error('Usage: betterrank history <symbol> [--file path] [--patch]'); process.exit(1); }
+      const histLimit = flags.limit ? parseInt(flags.limit, 10) : 20;
+      const histOffset = flags.offset ? parseInt(flags.offset, 10) : 0;
+      const showPatch = flags.patch === true || flags.p === true;
+      const result = await idx.history({ symbol, file: normalizeFilePath(flags.file), offset: histOffset, limit: histLimit, patch: showPatch });
+      if (!result) {
+        console.log(`(symbol "${symbol}" not found)`);
+      } else if (result.error) {
+        console.error(result.error);
+      } else if (result.raw) {
+        // --patch mode: print git's full output
+        const def = result.definition;
+        console.log(`${def.name} (${def.file}:${def.lineStart}-${def.lineEnd})\n`);
+        console.log(result.raw);
+      } else {
+        const def = result.definition;
+        console.log(`${def.name} (${def.file}:${def.lineStart}-${def.lineEnd})\n`);
+        if (result.commits.length === 0) {
+          console.log('(no commits found)');
+        } else {
+          for (const line of result.commits) {
+            console.log(`  ${line}`);
+          }
+        }
+      }
+      break;
+    }
+
     case 'trace': {
       const symbol = flags._positional[0];
       if (!symbol) { console.error('Usage: betterrank trace <symbol> [--depth N]'); process.exit(1); }

package/src/index.js

@@ -996,6 +996,223 @@ class CodeIndex {
     return counts;
   }
 
+  /**
+   * One-shot context: everything needed to understand a function.
+   *
+   * Returns the function's source, the signatures of functions/types it
+   * references, and a callers summary — all from a single command.
+   *
+   * @param {object} opts
+   * @param {string} opts.symbol - Symbol name
+   * @param {string} [opts.file] - Disambiguate by file
+   * @returns {object|null} { definition, usedSymbols, typeRefs, callers }
+   */
+  async context({ symbol, file }) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph) return null;
+
+    // Find the target symbol (highest PageRank if multiple)
+    const candidates = [];
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'symbol') return;
+      if (attrs.name !== symbol) return;
+      if (file && attrs.file !== file) return;
+      candidates.push({ key: node, ...attrs });
+    });
+    if (candidates.length === 0) return null;
+
+    const ranked = this._getRanked();
+    const scoreMap = new Map(ranked);
+    candidates.sort((a, b) => (scoreMap.get(b.key) || 0) - (scoreMap.get(a.key) || 0));
+    const target = candidates[0];
+
+    // Read the source file
+    let source, lines;
+    try {
+      const absPath = join(this.projectRoot, target.file);
+      source = await readFile(absPath, 'utf-8');
+      lines = source.split('\n');
+    } catch {
+      return null;
+    }
+
+    // Extract the function body text
+    const bodyLines = lines.slice(target.lineStart - 1, target.lineEnd);
+    const bodyText = bodyLines.join('\n');
+
+    // Build a set of all symbol names in the graph (for matching)
+    const allSymbols = new Map(); // name -> [{ file, kind, signature, lineStart }]
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'symbol') return;
+      if (attrs.file === target.file && attrs.name === target.name) return; // skip self
+      if (!allSymbols.has(attrs.name)) allSymbols.set(attrs.name, []);
+      allSymbols.get(attrs.name).push({
+        file: attrs.file,
+        kind: attrs.kind,
+        signature: attrs.signature,
+        lineStart: attrs.lineStart,
+        lineEnd: attrs.lineEnd,
+      });
+    });
+
+    // Find symbols referenced in the body
+    // Use word-boundary matching for each known symbol name
+    // Skip very common names that cause false positives
+    const NOISE_NAMES = new Set([
+      'get', 'set', 'put', 'post', 'delete', 'head', 'patch',
+      'start', 'stop', 'run', 'main', 'init', 'setup', 'close',
+      'dict', 'list', 'str', 'int', 'bool', 'float', 'type',
+      'key', 'value', 'name', 'data', 'config', 'result', 'error',
+      'test', 'self', 'cls', 'app', 'log', 'logger',
+      'enabled', 'default', 'constructor', 'length', 'size',
+      'fetch', 'send', 'table', 'one', 'append', 'write', 'read',
+      'update', 'create', 'find', 'add', 'remove', 'index', 'map',
+      'filter', 'sort', 'join', 'split', 'trim', 'replace',
+      'push', 'pop', 'shift', 'reduce', 'keys', 'values', 'items',
+      'search', 'match', 'query', 'count', 'call', 'apply', 'bind',
+    ]);
+    const usedSymbols = [];
+    const seen = new Set();
+    for (const [name, defs] of allSymbols) {
+      if (name.length < 3) continue; // skip very short names
+      if (NOISE_NAMES.has(name)) continue;
+      if (seen.has(name)) continue;
+      const pattern = new RegExp(`(?<![a-zA-Z0-9_])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![a-zA-Z0-9_])`);
+      if (pattern.test(bodyText)) {
+        seen.add(name);
+        // Pick the best definition (same-file first, then highest PageRank)
+        const sameFile = defs.find(d => d.file === target.file);
+        const best = sameFile || defs[0];
+        usedSymbols.push({ name, ...best });
+      }
+    }
+    // Sort: functions first, then types, then by name
+    const kindOrder = { function: 0, class: 1, type: 2, variable: 3 };
+    usedSymbols.sort((a, b) => (kindOrder[a.kind] ?? 9) - (kindOrder[b.kind] ?? 9) || a.name.localeCompare(b.name));
+
+    // Resolve type annotations in the signature
+    // Extract type-like tokens from the signature (capitalized words, common patterns)
+    const typeRefs = [];
+    const sigText = target.signature || '';
+    const typePattern = /(?<![a-zA-Z0-9_])([A-Z][a-zA-Z0-9_]+)(?![a-zA-Z0-9_])/g;
+    const seenTypes = new Set();
+    let match;
+    while ((match = typePattern.exec(sigText)) !== null) {
+      const typeName = match[1];
+      if (seenTypes.has(typeName)) continue;
+      seenTypes.add(typeName);
+      const typeDefs = allSymbols.get(typeName);
+      if (!typeDefs) continue;
+      // Find the type definition and get its fields (expand its body)
+      const best = typeDefs.find(d => d.file === target.file) || typeDefs[0];
+      if (best.kind === 'class' || best.kind === 'type') {
+        let fields = null;
+        try {
+          const typeAbsPath = join(this.projectRoot, best.file);
+          const typeSource = await readFile(typeAbsPath, 'utf-8');
+          const typeLines = typeSource.split('\n');
+          // Extract the body lines (up to 15 lines to keep it compact)
+          const maxPreview = 15;
+          const bodyStart = best.lineStart; // 1-indexed
+          const bodyEnd = Math.min(best.lineEnd, best.lineStart + maxPreview - 1);
+          fields = typeLines.slice(bodyStart - 1, bodyEnd).map(l => l);
+          if (best.lineEnd > bodyEnd) {
+            fields.push(`    ... (${best.lineEnd - bodyEnd} more lines)`);
+          }
+        } catch { /* skip */ }
+        typeRefs.push({ name: typeName, file: best.file, lineStart: best.lineStart, kind: best.kind, fields });
+      }
+    }
+
+    // Get callers (external files only) — union across ALL same-name nodes
+    // to handle ambiguous graph resolution (same name in different files)
+    const callerFiles = new Set();
+    for (const c of candidates) {
+      graph.forEachInEdge(c.key, (_edge, attrs, src) => {
+        if (attrs.type !== 'REFERENCES') return;
+        const srcAttrs = graph.getNodeAttributes(src);
+        const sf = srcAttrs.file || src;
+        if (sf !== target.file) callerFiles.add(sf);
+      });
+    }
+
+    // Remove symbols already shown in typeRefs to avoid redundancy
+    const typeRefNames = new Set(typeRefs.map(t => t.name));
+    const filteredSymbols = usedSymbols.filter(s => !typeRefNames.has(s.name));
+
+    return {
+      definition: {
+        name: target.name,
+        kind: target.kind,
+        file: target.file,
+        lineStart: target.lineStart,
+        lineEnd: target.lineEnd,
+        signature: target.signature,
+        source: bodyLines,
+      },
+      usedSymbols: filteredSymbols,
+      typeRefs,
+      callers: [...callerFiles].sort(),
+    };
+  }
+
+  /**
+   * Git history of a specific function, using its tree-sitter line range.
+   *
+   * @param {object} opts
+   * @param {string} opts.symbol - Symbol name
+   * @param {string} [opts.file] - Disambiguate by file
+   * @param {number} [opts.offset=0] - Skip first N commits
+   * @param {number} [opts.limit=20] - Max commits to show
+   * @param {boolean} [opts.patch=false] - Include function-scoped diffs
+   * @returns {object|null} { definition, commits, raw? }
+   */
+  async history({ symbol, file, offset = 0, limit = 20, patch = false }) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph) return null;
+
+    const candidates = [];
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'symbol') return;
+      if (attrs.name !== symbol) return;
+      if (file && attrs.file !== file) return;
+      candidates.push(attrs);
+    });
+    if (candidates.length === 0) return null;
+
+    const ranked = this._getRanked();
+    const scoreMap = new Map(ranked);
+    candidates.sort((a, b) => {
+      const aKey = `${a.file}::${a.name}`;
+      const bKey = `${b.file}::${b.name}`;
+      return (scoreMap.get(bKey) || 0) - (scoreMap.get(aKey) || 0);
+    });
+    const target = candidates[0];
+
+    const { execSync } = await import('child_process');
+    try {
+      if (patch) {
+        // Full output with diffs — return raw text
+        const raw = execSync(
+          `git log -L ${target.lineStart},${target.lineEnd}:${target.file} --skip=${offset} -n ${limit}`,
+          { cwd: this.projectRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000 }
+        ).trim();
+        return { definition: target, commits: [], raw };
+      }
+      // Summary only
+      const output = execSync(
+        `git log -L ${target.lineStart},${target.lineEnd}:${target.file} --no-patch --format="%h  %ad  %s" --date=short --skip=${offset} -n ${limit}`,
+        { cwd: this.projectRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000 }
+      ).trim();
+      const commits = output ? output.split('\n').filter(Boolean) : [];
+      return { definition: target, commits };
+    } catch {
+      return { definition: target, commits: [], error: 'git log failed — is this a git repo?' };
+    }
+  }
+
   /**
    * Recursive caller chain — walk UP the call graph from a symbol.
    * At each hop, resolves which function in the caller file contains