Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Who to tag on a pull request: the people whose fingerprints are on the areas
* this diff changes or can affect.
*
* The blast report already answers "what does this reach"; the author's next
* question is "who do I ask about it", and git has the answer without a single
* API call. One `git log` per area over that area's OWN files, scored by recency,
* ranked, capped.
*
* Two rules keep the output honest, and both exist because a wrong name here is
* worse than no name:
*
* - A handle is only ever printed when git actually carries one (the GitHub
* noreply address, which anything merged through the web UI has). With no
* handle the display name is printed unlinked — a guessed `@mention` pings a
* stranger, and there is no cheap way to verify a guess.
* - An owner has to hold {@link MIN_SHARE} of an area's weight to be named. That
* drops a drive-by typo fix next to a real owner, and keeps it when the
* drive-by is all the history there is.
*
* Everything here is best-effort: no git, no repository, a detached tarball
* checkout or a shallow clone leaves the report exactly as it was and the comment
* simply says nothing about people.
*/
import { spawnSync } from "node:child_process";
import { resolve } from "node:path";
import type { BlastReport } from "./blast.js";
/** One person's claim on one area. */
export interface Owner {
/** Display name as git reports it, with `.mailmap` already applied. */
name: string;
/** GitHub handle, when the commit email carries one. Never guessed. */
handle?: string;
/** Commits of theirs that touched this area's files. */
commits: number;
/** Recency-weighted weight of those commits — the ranking key. */
score: number;
/** Their most recent commit here, ms since the epoch. */
last: number;
}
/** One person's claim across the whole report: what the tag line prints. */
export interface Reviewer extends Owner {
/** Area labels they own, heaviest first. */
areas: string[];
}
export interface OwnerOptions {
/** Logins, names or emails to drop — the PR author, so they are not told to
* tag themselves. Matched case-insensitively against all three. */
exclude?: string[];
/** Clock, so a test can plant history at a fixed distance from "now". */
now?: number;
}
/**
* Recency half-life. A commit from four months ago counts half as much as one
* from today, so the person who rewrote a module last month outranks the person
* who created it two years ago and moved on — which is the reviewer an author
* actually wants.
*/
const HALF_LIFE_MS = 120 * 24 * 60 * 60 * 1000;
/**
* History window and commit cap, per area.
*
* Both are bounds on the walk, not on the answer: at 36 months a commit is worth
* 0.002 of a fresh one, so nothing outside the window could survive the share
* floor anyway, and the pair keeps one `git log` off a large repo's full history.
*/
const SINCE = "36.months";
const MAX_COMMITS = 400;
/** Files passed to one `git log`. A very wide area is sampled rather than blowing
* the argument list; the sample is the area's own sorted file list, so it is
* stable between runs rather than whichever files git happened to yield. */
const MAX_PATHSPEC = 80;
/** Share of an area's total weight an owner must hold to be named. */
const MIN_SHARE = 0.15;
/** Names listed per area, and in the tag line. */
export const MAX_PER_AREA = 2;
export const MAX_REVIEWERS = 3;
/**
* Weight of an area a diff only *reaches*, against one it edits.
*
* Not zero, because the person whose code your change can break is exactly the
* reviewer the diff alone would never surface — that is what the blast radius is
* for. Not one either: the author of the code you edited knows it better.
*/
const AFFECTED_WEIGHT = 0.6;
/**
* A GitHub handle out of a commit email, or null.
*
* Both noreply forms are accepted: the modern `12345+name@` and the legacy bare
* `name@`. The character class is GitHub's own username rule (alphanumerics and
* interior hyphens, 39 max) so an address that merely ends in the right domain
* cannot smuggle something unmentionable into a comment body.
*/
export function githubHandle(email: string): string | null {
const m = /^(?:\d+\+)?([A-Za-z0-9](?:-?[A-Za-z0-9]){0,38})@users\.noreply\.github\.com$/i.exec(email.trim());
return m ? m[1] : null;
}
/** Bots write commits and are never reviewers. */
function isBot(name: string, email: string): boolean {
return /\[bot\]/i.test(name) || /\[bot\]@/i.test(email) || /^(github-actions|dependabot|renovate)(\[bot\])?$/i.test(name.trim());
}
/** Run git in `root`, or null when git fails — not a repo, no git, no history. */
function git(root: string, args: string[]): string | null {
const res = spawnSync("git", ["-c", "core.quotePath=false", ...args], {
cwd: root,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
maxBuffer: 64 * 1024 * 1024,
});
if (res.error || res.status !== 0 || typeof res.stdout !== "string") return null;
return res.stdout;
}
/**
* The people behind `files`, best first.
*
* `--no-merges` because a merge commit's author is whoever pressed the button,
* not whoever wrote the code. `%aN`/`%aE` rather than `%an`/`%ae` so git applies
* the repository's `.mailmap` for us — which is the supported way to give a
* contributor whose work address has no handle a noreply one, at no new config
* cost to graft.
*/
export function ownersFor(root: string, files: string[], opts: OwnerOptions = {}): Owner[] {
const paths = [...files].sort().slice(0, MAX_PATHSPEC);
if (paths.length === 0) return [];
const now = opts.now ?? Date.now();
const out = git(resolve(root), [
"log",
"--no-merges",
`--since=${SINCE}`,
"-n",
String(MAX_COMMITS),
"--format=\x01%H\x02%aI\x02%aN\x02%aE",
"--name-only",
"--",
...paths,
]);
if (out === null) return [];
const wanted = new Set(paths);
const people = new Map<string, Owner & { seen: Set<string> }>();
let commit: { hash: string; at: number; weight: number; name: string; email: string } | null = null;
for (const line of out.split("\n")) {
if (line.startsWith("\x01")) {
const [hash, iso, name, email] = line.slice(1).split("\x02");
const at = Date.parse(iso ?? "");
commit = Number.isFinite(at)
? { hash, at, weight: Math.pow(0.5, (now - at) / HALF_LIFE_MS), name: name ?? "", email: email ?? "" }
: null;
continue;
}
// A pathspec'd `git log --name-only` already lists only matching files, but
// the set is re-checked here so a future flag change cannot silently start
// crediting whoever touched an unrelated file in the same commit.
if (commit === null || !wanted.has(line)) continue;
if (isBot(commit.name, commit.email)) continue;
const handle = githubHandle(commit.email) ?? undefined;
const key = (handle ?? commit.email).toLowerCase();
const prev = people.get(key);
if (!prev) {
people.set(key, {
name: commit.name, handle, commits: 1, score: commit.weight, last: commit.at,
seen: new Set([commit.hash]),
});
continue;
}
// One commit touching six files in the area is one commit, not six.
if (prev.seen.has(commit.hash)) continue;
prev.seen.add(commit.hash);
prev.commits += 1;
prev.score += commit.weight;
prev.last = Math.max(prev.last, commit.at);
}
const excluded = new Set((opts.exclude ?? []).map((e) => e.trim().toLowerCase()).filter(Boolean));
const isExcluded = (o: Owner, email: string) =>
excluded.has(email.toLowerCase()) ||
excluded.has(o.name.toLowerCase()) ||
(o.handle !== undefined && excluded.has(o.handle.toLowerCase()));
const kept = [...people].filter(([email, o]) => !isExcluded(o, email)).map(([, o]) => o);
// The floor is a SHARE of what is left after the author is dropped, not of the
// whole area. On a repo where one person wrote everything, their own PR would
// otherwise leave every remaining contributor under the floor and report nobody.
const total = kept.reduce((n, o) => n + o.score, 0);
return kept
.filter((o) => total === 0 || o.score / total >= MIN_SHARE)
.sort((a, b) => b.score - a.score || b.commits - a.commits || a.name.localeCompare(b.name))
.slice(0, MAX_PER_AREA)
.map(({ name, handle, commits, score, last }) => ({ name, handle, commits, score, last }));
}
/**
* Everyone who authored a commit in `base...HEAD` — the people whose work this
* pull request IS.
*
* This is the exclusion that actually fires in CI. The obvious source for "who
* opened this" is `pull_request.user.email` from the webhook, but GitHub almost
* never populates it, so excluding on the login alone leaves anyone whose commits
* carry a work address being suggested as a reviewer of their own PR. The commits
* in the range carry exactly the name and email git will match on later.
*
* Co-authors count too: a pair-programmed commit has two people on it and neither
* of them is a reviewer of it.
*/
export function diffAuthors(root: string, base: string): string[] {
const out = git(resolve(root), ["log", "--format=%aN%n%aE%n%(trailers:key=Co-authored-by,valueonly)", `${base}...HEAD`]);
if (out === null) return [];
const names = new Set<string>();
for (const raw of out.split("\n")) {
const line = raw.trim();
if (line === "") continue;
// A co-author trailer is `Name <email>`; both halves are worth excluding.
const m = /^(.*?)\s*<([^>]+)>$/.exec(line);
if (m) {
if (m[1]) names.add(m[1]);
names.add(m[2]);
continue;
}
names.add(line);
}
return [...names];
}
/**
* Whoever git would sign a commit as, here and now.
*
* The local counterpart of {@link diffAuthors}. `graft blast` with no `--base`
* compares the working tree against HEAD, so there is no commit range to read
* authors from — and without this, the one person guaranteed to have written the
* change being examined is also the top name in its own "who to tag" list.
*/
export function localIdentity(root: string): string[] {
const dir = resolve(root);
const out = [git(dir, ["config", "user.name"]), git(dir, ["config", "user.email"])];
return out.map((v) => v?.trim() ?? "").filter((v) => v !== "");
}
/**
* Fill in `owners` on every area and module, and rank the report's `reviewers`.
*
* Called AFTER `--name`, because a reviewer's reason cites area labels and the
* naming pass is what gives an area its final label.
*/
export function attachOwners(root: string, report: BlastReport, opts: OwnerOptions = {}): void {
const ranked = new Map<string, Reviewer & { weighted: number }>();
const visit = (label: string, files: string[], weight: number): Owner[] => {
const owners = ownersFor(root, files, opts);
for (const o of owners) {
const key = (o.handle ?? o.name).toLowerCase();
const prev = ranked.get(key);
if (!prev) {
ranked.set(key, { ...o, areas: [label], weighted: o.score * weight });
continue;
}
prev.areas.push(label);
prev.commits += o.commits;
prev.score += o.score;
prev.weighted += o.score * weight;
prev.last = Math.max(prev.last, o.last);
// A handle found on any one area is the handle: a contributor who has some
// commits from the web UI and some from a laptop should still be taggable.
if (prev.handle === undefined && o.handle !== undefined) prev.handle = o.handle;
}
return owners;
};
for (const area of report.areas) area.owners = visit(area.label, area.files, 1);
for (const mod of report.modules) mod.owners = visit(mod.label, mod.files, AFFECTED_WEIGHT);
report.reviewers = [...ranked.values()]
.sort((a, b) => b.weighted - a.weighted || b.commits - a.commits || a.name.localeCompare(b.name))
.slice(0, MAX_REVIEWERS)
.map(({ weighted: _weighted, ...r }) => r);
}
/** `9d ago`, `3mo ago` — how a comment says when someone was last in here. */
export function sinceLabel(last: number, now: number = Date.now()): string {
const days = Math.max(0, Math.round((now - last) / (24 * 60 * 60 * 1000)));
if (days < 1) return "today";
if (days === 1) return "yesterday";
if (days < 31) return `${days}d ago`;
const months = Math.round(days / 30);
return months < 24 ? `${months}mo ago` : `${Math.round(days / 365)}y ago`;
}
/** `@handle`, or the bare name when git carries no handle for them. */
export function mention(o: Owner): string {
return o.handle !== undefined ? `@${o.handle}` : o.name;
}
/** ISO day, for an exported page that has to stay truthful when opened later. */
export function isoDay(ms: number): string {
return new Date(ms).toISOString().slice(0, 10);
}