Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

5.3 KB
Raw Blame
/**
 * What a note says about where it came from: who wrote it, on which branch,
 * and which files the session changed. All from git, all best-effort: a
 * missing answer leaves the field out rather than guessing.
 */
import { execFileSync } from "node:child_process";
import { userInfo } from "node:os";

/** git's stdout, trimmed unless `raw` (porcelain status starts lines with a meaningful space). */
function git(repo: string, args: string[], raw = false): string | null {
  try {
    const out = execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
    return raw ? out : out.trim();
  } catch {
    return null;
  }
}

/** First name from `git config user.name`, capitalised; the OS user as a last resort. */
export function noteAuthor(repo: string): string {
  const name = git(repo, ["config", "user.name"]) || safeUser();
  const first = name.trim().split(/\s+/)[0] ?? "";
  return first ? first[0]!.toUpperCase() + first.slice(1) : "";
}

function safeUser(): string {
  try {
    return userInfo().username;
  } catch {
    return "";
  }
}

export function currentBranch(repo: string): string | undefined {
  const b = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]);
  return b && b !== "HEAD" ? b : undefined;
}

/** Paths that are the code map, agent wiring or the learnings themselves, never what a learning is about. */
export function ownPath(p: string): boolean {
  // .gitignore and .ignore too: `trail init` and the code map add their lines
  // to them, which is never what a session's note is about.
  return /^(graft|\.graft|\.claude|\.cursor|\.codex|\.trail)(\/|$)/.test(p) || p === ".mcp.json" || p === ".gitignore" || p === ".ignore";
}

/** Files the agent instructions live in: trail writes them, so editing them is setting trail up. */
const AGENT_FILES = new Set(["AGENTS.md", "CLAUDE.md", "GEMINI.md", ".github/copilot-instructions.md"]);

/** A repo path that is trail's or the agents' own (`ownPath`, plus AGENTS.md and the like): never what a learning is about. */
export function trailOwnPath(p: string): boolean {
  return ownPath(p) || AGENT_FILES.has(p);
}

/**
 * Files this session changed: uncommitted changes, plus files in commits made
 * since `since` (epoch ms). At most `limit`, in the order git lists them.
 * `uncommitted: false` leaves the working tree out, for when the session's own
 * transcript already says which files it changed: uncommitted files from
 * before the session (an untracked token file, a stray AGENTS.md) were
 * otherwise listed on every learning saved there.
 */
export function changedFiles(repo: string, since?: number, limit = 10, uncommitted = true): string[] {
  const out: string[] = [];
  const add = (p: string) => {
    const f = p.trim();
    if (f && !ownPath(f) && !out.includes(f)) out.push(f);
  };
  const status = uncommitted ? git(repo, ["status", "--porcelain", "--untracked-files=all"], true) : null;
  for (const line of (status ?? "").split("\n")) {
    if (!line.trim()) continue;
    // `XY path` or `XY old -> new`: the path now.
    const path = line.slice(3).split(" -> ").pop() ?? "";
    add(path.replace(/^"|"$/g, ""));
  }
  if (since !== undefined) {
    const log = git(repo, ["log", `--since=@${Math.floor(since / 1000)}`, "--name-only", "--pretty=format:"]);
    for (const p of (log ?? "").split("\n")) add(p);
  }
  return out.slice(0, limit);
}

/** How far back "works in this part of the codebase" looks. */
const TEAMMATE_DAYS = 180;

/**
 * The people who changed `files` (the whole repo when empty) in the last six
 * months, by first name, most commits first: the ones whose agents a learning
 * about those files would help. Never the person asking, and never a bot.
 */
export function teammatesOn(repo: string, files: string[] = []): string[] {
  const me = (git(repo, ["config", "user.email"]) ?? "").toLowerCase();
  const myName = (git(repo, ["config", "user.name"]) ?? "").toLowerCase();
  const out = git(repo, ["log", `--since=${TEAMMATE_DAYS}.days`, "--max-count=5000", "--format=%aN%x09%aE", "--", ...files]);
  if (!out) return [];
  const commits = new Map<string, { name: string; email: string; n: number }>();
  for (const line of out.split("\n")) {
    const [name = "", email = ""] = line.split("\t");
    const key = email.toLowerCase() || name.toLowerCase();
    if (!name || key === me || name.toLowerCase() === myName) continue;
    if (/\[bot\]|^(dependabot|github-actions|renovate)\b/i.test(name)) continue;
    const seen = commits.get(key);
    if (seen) seen.n++;
    else commits.set(key, { name, email, n: 1 });
  }
  const names: string[] = [];
  for (const { name, email } of [...commits.values()].sort((a, b) => b.n - a.n)) {
    const shown = firstName(name, email);
    if (shown && !names.includes(shown)) names.push(shown);
  }
  return names;
}

/**
 * A first name to show for a git author. Many commit under a handle
 * (`anaynanonets`), so when the name has no space a work email's local part
 * (`anay@…`) reads better; a noreply address has nothing to offer.
 */
function firstName(name: string, email: string): string {
  const n = name.trim();
  let word = /\s/.test(n) ? n.split(/\s+/)[0]! : "";
  if (!word && email && !/noreply/i.test(email)) word = email.split("@")[0]!.split(/[._+\-\d]+/)[0] ?? "";
  if (!word) word = n.split(/[._\-\d]+/)[0] ?? "";
  return word ? word[0]!.toUpperCase() + word.slice(1) : "";
}