Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

17.5 KB
Raw Blame
import { execFile } from "node:child_process";
import { readFile, stat } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, sep } from "node:path";
import { promisify } from "node:util";
import { atomicWrite } from "./store/fs.js";

const exec = promisify(execFile);

/** Shared with the team through the repository, or kept on this machine. */
export type GitPolicy = "ignore" | "share";

/** Walks up from `dir` looking for `.git` (a directory, or a file in worktrees). */
export async function findGitRoot(dir: string): Promise<string | undefined> {
  for (let cur = dir; ; cur = dirname(cur)) {
    if (
      await stat(join(cur, ".git")).then(
        () => true,
        () => false,
      )
    )
      return cur;
    if (dirname(cur) === cur) return undefined;
  }
}

/** The full hash `ref` names (`HEAD`, a short hash), or undefined. */
export async function resolveCommit(root: string, ref: string): Promise<string | undefined> {
  try {
    const { stdout } = await exec("git", [
      "-C",
      root,
      "rev-parse",
      "--verify",
      "--quiet",
      `${ref}^{commit}`,
    ]);
    const hash = String(stdout).trim();
    return hash === "" ? undefined : hash;
  } catch {
    return undefined;
  }
}

const HEADER = "# cogit";

/** The root line that keeps the whole `.cogit/` out under the ignore policy. */
const IGNORE_ALL = "/.cogit/";

/**
 * What the root `.gitignore` needs for a policy. A shared project lists nothing:
 * the project's own `.cogit/.gitignore` keeps everything but the project marker
 * out. Under `ignore` a single line hides it all, and that line is what later
 * commands read the policy from.
 */
export function gitignoreLines(policy: GitPolicy): string[] {
  return policy === "ignore" ? [IGNORE_ALL] : [];
}

/**
 * Applies the policy to `<root>/.gitignore`: adds the ignore line, or removes it
 * when the project starts sharing. User lines are never touched. Returns the
 * lines added (none when sharing).
 */
export async function ensureGitignore(root: string, policy: GitPolicy): Promise<string[]> {
  const file = join(root, ".gitignore");
  const text = await readFile(file, "utf8").catch(() => "");
  if (policy === "share") {
    const lines = text.split(/\r?\n/);
    const kept = lines.filter((line) => line.trim() !== IGNORE_ALL);
    if (kept.length !== lines.length) await atomicWrite(file, kept.join("\n"));
    return [];
  }
  const present = new Set(text.split(/\r?\n/).map((l) => l.trim()));
  const missing = gitignoreLines(policy).filter((l) => !present.has(l));
  if (missing.length === 0) return [];
  const block = [present.has(HEADER) ? [] : [HEADER], missing].flat().join("\n");
  const sep = text === "" || text.endsWith("\n") ? "" : "\n";
  await atomicWrite(file, `${text}${sep}${block}\n`);
  return missing;
}

/** True when the root `.gitignore` hides all of `.cogit/` (the ignore policy). */
export async function cogitIgnored(root: string): Promise<boolean> {
  const text = await readFile(join(root, ".gitignore"), "utf8").catch(() => "");
  return text.split(/\r?\n/).some((line) => line.trim() === IGNORE_ALL);
}

/**
 * The `.cogit/.gitignore` of a shared project: only the marker that tells a clone
 * this project uses cogit is tracked. The sessions travel on their own refs
 * (record-sync.ts), and the file has to travel too: without it a clone would not
 * ignore the record, and one `git add -A` would commit it.
 */
export function cogitGitignore(): string {
  return [HEADER, "*", "!.gitignore", "!project.json", ""].join("\n");
}

/**
 * Writes `.cogit/.gitignore` for a shared project; a no-op under `ignore` (the
 * root already hides everything). Returns true when the file changed.
 */
export async function ensureCogitGitignore(root: string, policy: GitPolicy): Promise<boolean> {
  if (policy !== "share") return false;
  const file = join(root, ".cogit", ".gitignore");
  const content = cogitGitignore();
  if ((await readFile(file, "utf8").catch(() => undefined)) === content) return false;
  await atomicWrite(file, content);
  return true;
}

/**
 * Keeps an existing project's `.cogit/.gitignore` current: reads the policy from
 * the root ignore file, so a project set up by an older version gets the new rules
 * on its next build.
 */
export async function refreshCogitGitignore(root: string): Promise<boolean> {
  if ((await findGitRoot(root)) === undefined) return false;
  if (await cogitIgnored(root)) return false;
  return ensureCogitGitignore(root, "share");
}

interface CommitLine {
  full: string;
  short: string;
  subject: string;
}

/** `%H%x00%h%x00%s` lines from `git log` / `git show`, one commit each. */
function parseCommitLines(stdout: string): CommitLine[] {
  const out: CommitLine[] = [];
  for (const line of stdout.split("\n")) {
    const [full, short, subject] = line.split("\0");
    if (full === undefined || !/^[0-9a-f]{40}$/.test(full)) continue;
    out.push({ full, short: short ?? "", subject: subject ?? "" });
  }
  return out;
}

/** The recorded hash may be short or full; either way it names the same commit. */
function matches(recorded: string, commit: CommitLine): boolean {
  return commit.full.startsWith(recorded) || recorded.startsWith(commit.short);
}

/**
 * Subjects of the given commit hashes in the repository at `root`, keyed by the
 * hash the record holds (Story 8.8: commit tags on the map). Missing commits and
 * a missing git binary are not errors: the map shows those tags greyed. One
 * `git log` call covers the common case; a hash git no longer knows makes that
 * call fail, so the fallback asks for each hash alone and keeps the rest.
 */
export async function readCommitSubjects(
  root: string,
  hashes: Iterable<string>,
): Promise<Map<string, string>> {
  const wanted = [...new Set(hashes)];
  const out = new Map<string, string>();
  if (wanted.length === 0) return out;

  const remember = (entries: CommitLine[]): void => {
    for (const hash of wanted) {
      const commit = entries.find((entry) => matches(hash, entry));
      if (commit) out.set(hash, commit.subject);
    }
  };

  try {
    const { stdout } = await exec("git", [
      "-C",
      root,
      "log",
      "--no-walk=unsorted",
      "--format=%H%x00%h%x00%s",
      ...wanted,
    ]);
    remember(parseCommitLines(stdout));
  } catch {
    for (const hash of wanted) {
      try {
        const { stdout } = await exec("git", [
          "-C",
          root,
          "show",
          "-s",
          "--format=%H%x00%h%x00%s",
          hash,
        ]);
        remember(parseCommitLines(stdout));
      } catch {
        // gone from this repository (rebased away, or another checkout)
      }
    }
  }
  return out;
}

/** One commit with the files it changed, as `git log --name-only` printed it. */
interface CommitFiles {
  full: string;
  short: string;
  files: string[];
}

/**
 * Parses `%x00%H --name-only` output: a NUL-prefixed hash line starts a commit,
 * the file lines after it belong to that commit until the next hash line.
 */
function parseFileSections(stdout: string): CommitFiles[] {
  const out: CommitFiles[] = [];
  let current: CommitFiles | null = null;
  for (const line of stdout.split("\n")) {
    if (line.startsWith("\0")) {
      const full = line.slice(1).trim();
      current = /^[0-9a-f]{40}$/.test(full) ? { full, short: "", files: [] } : null;
      if (current) out.push(current);
      continue;
    }
    const file = line.trim();
    if (current !== null && file !== "") current.files.push(file);
  }
  return out;
}

/**
 * The files each given commit changed, keyed by the hash the record holds
 * (Story 8.15: the map's file history). Paths are relative to the repository
 * root. Missing commits and a missing git binary only drop entries, never fail
 * the build — same policy as `readCommitSubjects`.
 */
export async function readCommitFiles(
  root: string,
  hashes: Iterable<string>,
): Promise<Map<string, string[]>> {
  const wanted = [...new Set(hashes)];
  const out = new Map<string, string[]>();
  if (wanted.length === 0) return out;

  const remember = (entries: CommitFiles[]): void => {
    for (const hash of wanted) {
      const commit = entries.find(
        (entry) => entry.full.startsWith(hash) || hash.startsWith(commitShort(entry)),
      );
      if (commit && !out.has(hash)) out.set(hash, commit.files);
    }
  };

  try {
    const { stdout } = await exec("git", [
      "-C",
      root,
      "log",
      "--no-walk=unsorted",
      "--format=%x00%H",
      "--name-only",
      ...wanted,
    ]);
    remember(parseFileSections(stdout));
  } catch {
    for (const hash of wanted) {
      try {
        const { stdout } = await exec("git", [
          "-C",
          root,
          "show",
          "--format=%x00%H",
          "--name-only",
          hash,
        ]);
        remember(parseFileSections(stdout));
      } catch {
        // gone from this repository (rebased away, or another checkout)
      }
    }
  }
  return out;
}

/** A commit with its numstat totals and the files it changed. */
export interface CommitChange {
  /** The full hash, so two recorded hashes of one commit count once. */
  full: string;
  added: number;
  removed: number;
  /** Repository-relative paths, in git's order (a binary file counts as one). */
  files: string[];
}

interface ChangeSection {
  full: string;
  added: number;
  removed: number;
  files: string[];
}

/**
 * Parses `%x00%H` + `--numstat` output: a NUL-prefixed hash line starts a
 * commit, `added\tremoved\tpath` lines follow until the next hash. A binary file
 * prints `-` for both counts; it still counts as a file touched.
 */
function parseChangeSections(stdout: string): ChangeSection[] {
  const out: ChangeSection[] = [];
  let current: ChangeSection | null = null;
  for (const line of stdout.split("\n")) {
    if (line.startsWith("\0")) {
      const full = line.slice(1).trim();
      current = /^[0-9a-f]{40}$/.test(full) ? { full, added: 0, removed: 0, files: [] } : null;
      if (current) out.push(current);
      continue;
    }
    if (current === null) continue;
    const parts = line.split("\t");
    if (parts.length < 3) continue;
    const [added, removed, ...rest] = parts;
    const path = rest.join("\t").trim();
    if (path === "") continue;
    current.added += Number.parseInt(added ?? "", 10) || 0;
    current.removed += Number.parseInt(removed ?? "", 10) || 0;
    current.files.push(path);
  }
  return out;
}

/**
 * Lines added and removed, plus the files changed, for each given commit
 * (Story 10.3: how much code landed after a message). Keyed by the hash the
 * record holds; a commit git no longer knows is left out, never an error —
 * same policy as `readCommitSubjects` and `readCommitFiles`.
 */
export async function readCommitChanges(
  root: string,
  hashes: Iterable<string>,
): Promise<Map<string, CommitChange>> {
  const wanted = [...new Set(hashes)];
  const out = new Map<string, CommitChange>();
  if (wanted.length === 0) return out;

  const remember = (entries: ChangeSection[]): void => {
    for (const hash of wanted) {
      const commit = entries.find(
        (entry) => entry.full.startsWith(hash) || hash.startsWith(entry.full.slice(0, 7)),
      );
      if (commit && !out.has(hash))
        out.set(hash, {
          full: commit.full,
          added: commit.added,
          removed: commit.removed,
          files: commit.files,
        });
    }
  };

  try {
    const { stdout } = await exec("git", [
      "-C",
      root,
      "log",
      "--no-walk=unsorted",
      "--format=%x00%H",
      "--numstat",
      ...wanted,
    ]);
    remember(parseChangeSections(stdout));
  } catch {
    for (const hash of wanted) {
      try {
        const { stdout } = await exec("git", [
          "-C",
          root,
          "show",
          "--format=%x00%H",
          "--numstat",
          hash,
        ]);
        remember(parseChangeSections(stdout));
      } catch {
        // gone from this repository (rebased away, or another checkout)
      }
    }
  }
  return out;
}

/**
 * The patches of the given commits, concatenated and cut at `limit` characters
 * (Story 13.6: the side writer reads enough of the change to name its path). A
 * commit git no longer knows is skipped; `truncated` says the cut happened, so
 * the prompt can say so instead of pretending the diff is complete.
 */
export async function readCommitPatches(
  root: string,
  hashes: Iterable<string>,
  limit: number,
): Promise<{ diff: string; truncated: boolean }> {
  const wanted = [...new Set(hashes)];
  if (wanted.length === 0) return { diff: "", truncated: false };
  const chunks: string[] = [];
  let size = 0;
  let truncated = false;
  try {
    const { stdout } = await exec("git", [
      "-C",
      root,
      "log",
      "--no-walk=unsorted",
      "--format=commit %h %s",
      "--patch",
      "--no-color",
      "--unified=3",
      ...wanted,
    ]);
    const text = stdout.trim();
    if (text.length > limit) {
      return { diff: text.slice(0, limit), truncated: true };
    }
    return { diff: text, truncated: false };
  } catch {
    // One hash git no longer knows makes the batch fail; ask for each alone.
  }
  for (const hash of wanted) {
    if (size >= limit) {
      truncated = true;
      break;
    }
    try {
      const { stdout } = await exec("git", [
        "-C",
        root,
        "show",
        "--format=commit %h %s",
        "--patch",
        "--no-color",
        "--unified=3",
        hash,
      ]);
      const remaining = limit - size;
      const text = stdout.trim();
      chunks.push(text.length > remaining ? text.slice(0, remaining) : text);
      if (text.length > remaining) truncated = true;
      size += Math.min(text.length, remaining);
    } catch {
      // gone from this repository (rebased away, or another checkout)
    }
  }
  return { diff: chunks.join("\n\n"), truncated };
}

/** A commit's short hash, computed when git printed only the full one. */ function commitShort(
  commit: CommitFiles,
): string {
  return commit.short === "" ? commit.full.slice(0, 7) : commit.short;
}

/**
 * Rebases repository-relative file paths onto the project root and drops the
 * files outside it, so the map compares commit files with the paths the records
 * hold (Story 8.15). A project at the repository root passes through unchanged.
 */
export function projectFiles(
  gitRoot: string,
  root: string,
  files: ReadonlyMap<string, string[]>,
): Map<string, string[]> {
  if (gitRoot === root) return new Map(files);
  const out = new Map<string, string[]>();
  for (const [hash, list] of files) {
    const kept = list.flatMap((file) => {
      const rel = relative(root, join(gitRoot, file));
      if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return [];
      return [rel.split(sep).join("/")];
    });
    if (kept.length > 0) out.set(hash, kept);
  }
  return out;
}

/**
 * Full hashes git blames for `file`; `file:line` asks about one line and a bare
 * file means every commit that touched it (Story 8.8). `file` is relative to
 * `root`, the repository's worktree.
 */ export async function blameCommitHashes(
  root: string,
  file: string,
  line?: number,
): Promise<string[]> {
  const args =
    line === undefined
      ? ["-C", root, "log", "--format=%H", "--", file]
      : ["-C", root, "blame", "--porcelain", "-L", `${line},${line}`, "--", file];
  const { stdout } = await exec("git", args);
  const out = new Set<string>();
  for (const row of stdout.split("\n")) {
    const hash = row.slice(0, 40);
    if (!/^[0-9a-f]{40}$/.test(hash)) continue;
    // `blame --porcelain` rows continue with the line numbers; a bare `git log`
    // row is the hash alone.
    if (row.length === 40 || /^[0-9a-f]{40} \d+ \d+/.test(row)) out.add(hash);
  }
  return [...out];
}

/** The name a commit in this repository would carry; undefined outside git or unset. */
export async function gitUserName(
  root: string,
  env: NodeJS.ProcessEnv = process.env,
): Promise<string | undefined> {
  return gitConfig(root, "user.name", env);
}

/** `git config user.email`; undefined when it is not set. */
export async function gitUserEmail(
  root: string,
  env: NodeJS.ProcessEnv = process.env,
): Promise<string | undefined> {
  return gitConfig(root, "user.email", env);
}

async function gitConfig(
  root: string,
  key: string,
  env: NodeJS.ProcessEnv,
): Promise<string | undefined> {
  try {
    const { stdout } = await exec("git", ["-C", root, "config", key], { env });
    const value = stdout.trim();
    return value === "" ? undefined : value;
  } catch {
    return undefined;
  }
}

/**
 * True when this repository has a commit made between two moments (Story 9.5).
 * The transcript only shows that a `git commit` command ran; this asks git
 * whether one actually landed here, so a failed or other-repository commit is
 * not a hint. A missing git, an uninitialized repository or bad dates are all
 * "no commit": a hint must never fail the command it decorates.
 */
export async function commitBetween(
  root: string,
  from: string,
  to: string,
  env: NodeJS.ProcessEnv = process.env,
): Promise<boolean> {
  try {
    const { stdout } = await exec(
      "git",
      ["-C", root, "log", "--max-count=1", "--format=%H", `--since=${from}`, `--until=${to}`],
      { env },
    );
    return stdout.trim() !== "";
  } catch {
    return false;
  }
}

/** The hooks directory git really uses here: `core.hooksPath`, Husky and worktrees included. */
export async function gitHooksDir(root: string): Promise<string | undefined> {
  try {
    const { stdout } = await exec("git", ["-C", root, "rev-parse", "--git-path", "hooks"]);
    const path = stdout.trim();
    if (path === "") return undefined;
    return isAbsolute(path) ? path : join(root, path);
  } catch {
    return undefined;
  }
}