@mishasinitcyn/betterrank 0.2.2 → 0.2.3

package/README.md

@@ -186,6 +186,31 @@ 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.2",
+  "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

@@ -19,6 +19,7 @@ Commands:
   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)
@@ -154,6 +155,24 @@ 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
@@ -591,6 +610,36 @@ async function main() {
       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

@@ -1157,6 +1157,62 @@ class CodeIndex {
     };
   }
 
+  /**
+   * 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