git-who-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Larsen Cundric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# git-who
+
+> Find who knows a file (or codebase) best. `git blame` + `git log` = actionable ownership insights.
+
+## Install
+
+```sh
+npm install -g git-who-cli
+```
+
+## Usage
+
+```sh
+# Who knows this repo best?
+git who
+
+# Who knows a specific file best?
+git who src/index.js
+
+# Who knows a directory best?
+git who src/
+
+# Show top 10 contributors
+git who -n 10
+```
+
+### Example output
+
+```
+git who src/utils.js ──────────────────────────────
+
+  Last modified by Alice 2d ago (Wed, Mar 12, 2025)
+
+  Top contributors:
+
+  ★  Alice    █████████████████████ 63% lines  47 commits  2d ago
+  2  Bob      ██████████           31% lines  23 commits  1w ago
+  3  Charlie  ██                    6% lines   4 commits  3mo ago
+
+  → Ask Alice — they own 63% of lines and made 47 commits
+    or Bob (31% lines, 23 commits)
+```
+
+### Directory / repo-wide view
+
+```
+git who . ──────────────────────────────────────────
+
+  Last modified by Alice 2d ago (Wed, Mar 12, 2025)
+
+  Top contributors:
+
+  ★  Alice    ██████████████████ 54% commits (127)  2d ago
+  2  Bob      ████████████       36% commits (85)   3d ago
+  3  Charlie  ███                10% commits (23)   2w ago
+
+  → Ask Alice — 54% of commits (127 total)
+    or Bob (36%, 85 commits)
+```
+
+## Features
+
+- **File mode**: Uses `git blame` to find line ownership + `git log` for commit history
+- **Directory mode**: Uses `git shortlog` for aggregate contributor stats
+- **Smart ranking**: 60% line ownership + 40% commit frequency (file mode)
+- **Beautiful output**: Color-coded bars, ranks, and "who to ask" suggestions
+- **Fast**: Single-pass blame parsing, no external dependencies beyond git
+
+## Requirements
+
+- Node.js >= 18
+- Git installed and accessible on your PATH
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "git-who-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Find who knows a file best. git blame + git log = actionable ownership insights.",
+  "bin": {
+    "git-who": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "keywords": ["git", "blame", "ownership", "cli", "contributor"],
+  "author": "Larsen Cundric",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larsencundric/git-who-cli.git"
+  },
+  "homepage": "https://github.com/larsencundric/git-who-cli#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "5.6.2",
+    "commander": "14.0.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { program } from 'commander';
+import { git, gitLines, symbols, header, fatal, isInsideGitRepo, getRepoRoot, relativeTime, formatDate } from './utils.js';
+
+program
+  .name('git-who')
+  .description('Show who knows a file or directory best — top contributors ranked by ownership and activity')
+  .argument('[path]', 'file or directory to inspect (default: current directory)', '.')
+  .option('-n, --top <number>', 'number of contributors to show', '5')
+  .addHelpText('after', `
+Examples:
+  git who                       Who knows this repo best?
+  git who src/index.js          Top contributors for a specific file
+  git who src/                  Top contributors for a directory
+  git who -n 10 .               Show top 10 contributors repo-wide`)
+  .version('1.0.0')
+  .action(run);
+
+program.parse();
+
+function runFile(file, top) {
+  // Check file exists in repo
+  try {
+    git(['ls-files', '--error-unmatch', file]);
+  } catch {
+    fatal(`File not tracked by git: ${file}`);
+  }
+
+  // Get blame data
+  let blameLines;
+  try {
+    blameLines = gitLines(['blame', '--line-porcelain', file]);
+  } catch {
+    fatal(`Cannot blame ${file} — is it a binary or empty file?`);
+  }
+
+  const authorLines = {};
+  let currentAuthor = null;
+  let totalLines = 0;
+
+  for (const line of blameLines) {
+    if (line.startsWith('author ')) {
+      currentAuthor = line.slice(7);
+      if (currentAuthor === 'Not Committed Yet') currentAuthor = null;
+    } else if (line.startsWith('\t')) {
+      if (currentAuthor) {
+        authorLines[currentAuthor] = (authorLines[currentAuthor] || 0) + 1;
+        totalLines++;
+      }
+    }
+  }
+
+  const logOutput = gitLines([
+    'log', '--format=%an%x00%aI%x00%s', '--follow', '--', file,
+  ]);
+
+  const authorCommits = {};
+  const authorLastDate = {};
+  let lastModifiedBy = null;
+  let lastModifiedDate = null;
+
+  for (const line of logOutput) {
+    const [name, date, ...msgParts] = line.split('\0');
+    if (!authorCommits[name]) authorCommits[name] = [];
+    authorCommits[name].push({ date });
+
+    if (!lastModifiedBy) {
+      lastModifiedBy = name;
+      lastModifiedDate = date;
+    }
+
+    if (!authorLastDate[name] || date > authorLastDate[name]) {
+      authorLastDate[name] = date;
+    }
+  }
+
+  // Build ranked list
+  const authors = Object.keys({ ...authorLines, ...authorCommits });
+  const ranked = authors.map((name) => {
+    const lines = authorLines[name] || 0;
+    const commits = (authorCommits[name] || []).length;
+    const pct = totalLines > 0 ? (lines / totalLines) * 100 : 0;
+    const lastDate = authorLastDate[name] || null;
+    return { name, lines, commits, pct, lastDate };
+  });
+
+  const maxLines = Math.max(...ranked.map((r) => r.lines), 1);
+  const maxCommits = Math.max(...ranked.map((r) => r.commits), 1);
+  ranked.forEach((r) => {
+    r.score = 0.6 * (r.lines / maxLines) + 0.4 * (r.commits / maxCommits);
+  });
+  ranked.sort((a, b) => b.score - a.score);
+
+  header(`git who ${chalk.white(file)}`);
+
+  if (lastModifiedBy) {
+    console.log(
+      `  ${chalk.dim('Last modified by')} ${chalk.yellow(lastModifiedBy)} ${chalk.dim(relativeTime(lastModifiedDate))} ${chalk.dim(`(${formatDate(lastModifiedDate)})`)}`
+    );
+    console.log();
+  }
+
+  console.log(chalk.bold('  Top contributors:\n'));
+
+  const display = ranked.slice(0, top);
+
+  if (display.length === 0) {
+    console.log(chalk.dim('  No contributors found.\n'));
+    return;
+  }
+
+  const maxNameLen = Math.max(...display.map((r) => r.name.length));
+
+  display.forEach((r, i) => {
+    const rank = i === 0 ? chalk.yellow('★') : chalk.dim(`${i + 1}`);
+    const name = r.name.padEnd(maxNameLen);
+    const barLen = Math.max(1, Math.round(r.pct / 3));
+    const bar = '█'.repeat(barLen);
+    const pctStr = `${r.pct.toFixed(0)}%`.padStart(4);
+    const color = i === 0 ? chalk.yellow : i === 1 ? chalk.white : chalk.dim;
+
+    console.log(
+      `  ${rank}  ${color(name)}  ${chalk.green(bar)} ${chalk.dim(pctStr)} lines  ${chalk.dim(`${r.commits} commits`)}  ${r.lastDate ? chalk.dim(relativeTime(r.lastDate)) : ''}`
+    );
+  });
+
+  console.log();
+  if (ranked.length > 0) {
+    const best = ranked[0];
+    console.log(
+      `  ${chalk.cyan(symbols.arrow)} ${chalk.dim('Ask')} ${chalk.bold.cyan(best.name)} ${chalk.dim('— they own')} ${chalk.white(`${best.pct.toFixed(0)}%`)} ${chalk.dim('of lines and made')} ${chalk.white(best.commits)} ${chalk.dim('commits')}`
+    );
+    if (ranked.length > 1 && ranked[1].score > 0.5) {
+      console.log(
+        `  ${chalk.dim('  or')} ${chalk.cyan(ranked[1].name)} ${chalk.dim(`(${ranked[1].pct.toFixed(0)}% lines, ${ranked[1].commits} commits)`)}`
+      );
+    }
+  }
+  console.log();
+}
+
+function runDirectory(dir, top) {
+  const displayPath = dir === '.' ? getRepoRoot().split('/').pop() : dir;
+
+  // Get contributor stats via shortlog
+  const shortlogLines = gitLines(['shortlog', '-sne', '--no-merges', 'HEAD', '--', dir]);
+
+  const authorCommits = {};
+  for (const line of shortlogLines) {
+    const match = line.match(/^\s*(\d+)\s+(.+?)\s+<(.+?)>\s*$/);
+    if (match) {
+      const [, count, name] = match;
+      authorCommits[name] = parseInt(count, 10);
+    }
+  }
+
+  // Get last activity per author
+  const logLines = gitLines(['log', '--format=%an%x00%aI', '--no-merges', '--', dir]);
+  const authorLastDate = {};
+  let lastModifiedBy = null;
+  let lastModifiedDate = null;
+
+  for (const line of logLines) {
+    const [name, date] = line.split('\0');
+    if (!lastModifiedBy) {
+      lastModifiedBy = name;
+      lastModifiedDate = date;
+    }
+    if (!authorLastDate[name]) {
+      authorLastDate[name] = date;
+    }
+  }
+
+  // Get total commits for percentage
+  const totalCommits = Object.values(authorCommits).reduce((a, b) => a + b, 0);
+
+  // Build ranked list
+  const ranked = Object.entries(authorCommits).map(([name, commits]) => ({
+    name,
+    commits,
+    pct: totalCommits > 0 ? (commits / totalCommits) * 100 : 0,
+    lastDate: authorLastDate[name] || null,
+  }));
+  ranked.sort((a, b) => b.commits - a.commits);
+
+  header(`git who ${chalk.white(displayPath + '/')}`);
+
+  if (lastModifiedBy) {
+    console.log(
+      `  ${chalk.dim('Last modified by')} ${chalk.yellow(lastModifiedBy)} ${chalk.dim(relativeTime(lastModifiedDate))} ${chalk.dim(`(${formatDate(lastModifiedDate)})`)}`
+    );
+    console.log();
+  }
+
+  console.log(chalk.bold('  Top contributors:\n'));
+
+  const display = ranked.slice(0, top);
+  const maxNameLen = Math.max(...display.map((r) => r.name.length), 1);
+
+  display.forEach((r, i) => {
+    const rank = i === 0 ? chalk.yellow('★') : chalk.dim(`${i + 1}`);
+    const name = r.name.padEnd(maxNameLen);
+    const barLen = Math.max(1, Math.round(r.pct / 3));
+    const bar = '█'.repeat(barLen);
+    const pctStr = `${r.pct.toFixed(0)}%`.padStart(4);
+    const color = i === 0 ? chalk.yellow : i === 1 ? chalk.white : chalk.dim;
+
+    console.log(
+      `  ${rank}  ${color(name)}  ${chalk.green(bar)} ${chalk.dim(pctStr)} commits (${chalk.white(r.commits)})  ${r.lastDate ? chalk.dim(relativeTime(r.lastDate)) : ''}`
+    );
+  });
+
+  console.log();
+  if (ranked.length > 0) {
+    const best = ranked[0];
+    console.log(
+      `  ${chalk.cyan(symbols.arrow)} ${chalk.dim('Ask')} ${chalk.bold.cyan(best.name)} ${chalk.dim('—')} ${chalk.white(`${best.pct.toFixed(0)}%`)} ${chalk.dim('of commits')} ${chalk.dim(`(${best.commits} total)`)}`
+    );
+    if (ranked.length > 1 && ranked[1].pct > 15) {
+      console.log(
+        `  ${chalk.dim('  or')} ${chalk.cyan(ranked[1].name)} ${chalk.dim(`(${ranked[1].pct.toFixed(0)}%, ${ranked[1].commits} commits)`)}`
+      );
+    }
+  }
+  console.log();
+}
+
+function run(pathArg, opts) {
+  if (!isInsideGitRepo()) fatal('Not inside a git repository');
+
+  const top = parseInt(opts.top, 10);
+  if (!Number.isFinite(top) || top < 1) fatal(`Invalid --top value: "${opts.top}" (must be a positive integer)`);
+  const resolvedPath = resolve(pathArg);
+
+  let isDir = false;
+  try {
+    isDir = statSync(resolvedPath).isDirectory();
+  } catch {
+    // Path might not exist on disk but could be a git-tracked file
+    // Try as a file
+  }
+
+  if (isDir) {
+    runDirectory(pathArg, top);
+  } else {
+    runFile(pathArg, top);
+  }
+}

package/src/utils.js

@@ -0,0 +1,84 @@
+import { execFileSync } from 'node:child_process';
+import chalk from 'chalk';
+
+export function git(args, opts = {}) {
+  try {
+    return execFileSync('git', args, {
+      encoding: 'utf-8',
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...opts,
+    }).trim();
+  } catch (e) {
+    if (opts.allowFail) return '';
+    throw e;
+  }
+}
+
+export function gitLines(args, opts = {}) {
+  const out = git(args, opts);
+  return out ? out.split('\n') : [];
+}
+
+export function isInsideGitRepo() {
+  try {
+    git(['rev-parse', '--is-inside-work-tree']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getRepoRoot() {
+  return git(['rev-parse', '--show-toplevel']);
+}
+
+export const symbols = {
+  bullet: '●',
+  arrow: '→',
+  check: '✓',
+  cross: '✗',
+  warning: '⚠',
+  line: '─',
+};
+
+export function header(text) {
+  // Strip ANSI codes to get the visible length for alignment
+  const visibleLength = text.replace(/\u001b\[[0-9;]*[a-zA-Z]/g, '').length;
+  const line = symbols.line.repeat(Math.max(0, 50 - visibleLength));
+  console.log(`\n${chalk.bold.cyan(text)} ${chalk.dim(line)}\n`);
+}
+
+export function fatal(msg) {
+  console.error(`${chalk.red(symbols.cross)} ${msg}`);
+  process.exit(1);
+}
+
+export function relativeTime(dateStr) {
+  const date = new Date(dateStr);
+  if (isNaN(date.getTime())) return 'unknown';
+  const now = new Date();
+  const diffMs = now - date;
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+  const diffWeeks = Math.floor(diffDays / 7);
+  const diffMonths = Math.floor(diffDays / 30);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  if (diffWeeks < 5) return `${diffWeeks}w ago`;
+  return `${diffMonths}mo ago`;
+}
+
+export function formatDate(dateStr) {
+  const d = new Date(dateStr);
+  return d.toLocaleDateString('en-US', {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}