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.

14.6 KB
Raw Blame
import { execFile } from "node:child_process";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { promisify } from "node:util";
import { beforeEach, describe, expect, it } from "vitest";
import { configSet } from "../src/commands/config.js";
import { init } from "../src/commands/init.js";
import {
  collectWhy,
  collectWhyLine,
  formatWhy,
  nearestProjectDir,
  rejectedItems,
  TRY_BEFORE_MAX_CHARS,
  TRY_BEFORE_MAX_ITEMS,
  tryBeforeNote,
  type WhyHit,
  why,
} from "../src/commands/why.js";
import { runHook } from "../src/hooks/run.js";
import { createProgram } from "../src/program.js";
import type { Session } from "../src/schema/session.js";
import { projectPaths } from "../src/store/paths.js";
import { envFor, fakeIo, noGitDir, noGitProject, T0, tempDir } from "./helpers.js";

const run = promisify(execFile);

const A = "h111111111111";
const B = "h222222222222";

function session(over: Partial<Session> = {}): Session {
  return {
    schema: 1,
    sessionId: "s1",
    agent: "claude-code",
    title: "Ship the parser",
    startedAt: "2026-10-20T09:00:00.000Z",
    updatedAt: "2026-10-20T10:00:00.000Z",
    status: { goal: "", done: [], pending: [], next: "" },
    nodes: [],
    ...over,
  };
}

function hit(over: Partial<WhyHit> = {}): WhyHit {
  return {
    sessionId: "s1",
    sessionTitle: "Ship the parser",
    messageId: A,
    label: "m1",
    at: "2026-10-20T09:00:00.000Z",
    title: "Parse the file",
    decisions: [
      {
        title: "Parse the file",
        why: "",
        alternatives: [{ option: "Keep the loop", why: "It loses data." }],
      },
    ],
    ...over,
  };
}

describe("cogit why", () => {
  let dir: string;
  let root: string;
  let env: NodeJS.ProcessEnv;
  let secondCommit: string;
  const git = async (...args: string[]) => run("git", ["-C", root, ...args]);

  const edit = (extra: Record<string, unknown> = {}) =>
    runHook(
      "pretooluse",
      JSON.stringify({
        session_id: "s1",
        cwd: root,
        tool_name: "Edit",
        tool_input: { file_path: join(root, "a.txt") },
        ...extra,
      }),
      env,
      T0,
      () => {},
    );

  beforeEach(async () => {
    dir = await tempDir();
    root = join(dir, "proj");
    env = envFor(dir);
    await mkdir(root);
    await init(root, { name: "proj", retention: "keep", language: "auto" }, fakeIo(env));
    await git("init", "-q");
    await git("config", "user.email", "[email protected]");
    await git("config", "user.name", "T");

    await writeFile(join(root, "a.txt"), "one\n");
    await git("add", "a.txt");
    // The first commit names its message only through the trailer (Story 9.4).
    await git("commit", "-q", "-m", "feat: add a", "-m", `Thought: ${A}`);

    await writeFile(join(root, "a.txt"), "one\ntwo\n");
    await git("add", "a.txt");
    await git("commit", "-q", "-m", "feat: extend a", "-m", `Thought: ${B}`);
    secondCommit = (await git("rev-parse", "--short", "HEAD")).stdout.trim();

    const record = session({
      nodes: [
        {
          id: A,
          parent: null,
          kind: "message",
          title: "Parse the file",
          at: "2026-10-20T09:00:00.000Z",
          // No `commits`: only the trailer links this message to the commit.
          why: "The old loop ate one line.",
          alternatives: [{ option: "Keep the loop", why: "It loses data." }],
          agentDecisions: [
            {
              title: "Kept the parser",
              why: "It works.",
              alternatives: [{ option: "Rewrite", why: "Too slow." }],
            },
          ],
        },
        {
          id: B,
          parent: A,
          kind: "message",
          title: "Extend the parser",
          at: "2026-10-20T10:00:00.000Z",
          commits: [secondCommit],
          alternatives: [{ option: "Split the module", why: "Extra files." }],
        },
      ],
    });
    await writeFile(projectPaths(root).session("s1"), JSON.stringify(record));
  });

  it("follows a trailer-linked commit to its thought, newest first", async () => {
    const hits = await collectWhy(root, "a.txt", env);
    expect(hits.map((entry) => entry.messageId)).toEqual([B, A]);
    const older = hits[1];
    expect(older).toMatchObject({ label: "m1", title: "Parse the file" });
    expect(older?.decisions.flatMap((decision) => decision.alternatives)).toEqual([
      { option: "Keep the loop", why: "It loses data." },
      { option: "Rewrite", why: "Too slow." },
    ]);
    expect(older?.decisions.map((decision) => decision.title)).toEqual([
      "Parse the file",
      "Kept the parser",
    ]);
    // Without an env the lookup still runs (git uses the process environment).
    expect(await collectWhy(root, "a.txt")).toHaveLength(2);
  });

  it("prints each thought with its hash, label, date and rejected options", async () => {
    const lines = formatWhy(await collectWhy(root, "a.txt", env));
    expect(lines[0]).toContain("h2222222  m2");
    expect(lines[0]).toContain("Extend the parser");
    expect(lines.join("\n")).toContain("not: Split the module — Extra files.");
    expect(lines.join("\n")).toContain("h1111111  m1");
    expect(lines.join("\n")).toContain("not: Keep the loop — It loses data.");
    expect(lines.join("\n")).toContain("decision: Parse the file — The old loop ate one line.");
    expect(lines.join("\n")).toContain("decision: Kept the parser — It works.");
  });

  it("prints the lookup, or a plain line when nothing was recorded", async () => {
    const io = fakeIo(env);
    const hits = await why({ dir: root, file: "a.txt", io });
    expect(hits).toHaveLength(2);
    const text = io.lines.join("\n");
    expect(text).toContain("h2222222  m2");
    expect(text).toContain("not: Split the module — Extra files.");
    expect(text).toContain(
      "`cogit show <hash>` opens the thought; the record is the agent's summary.",
    );

    await writeFile(join(root, "loose.txt"), "x\n");
    const none = fakeIo(env);
    await why({ dir: root, file: "loose.txt", io: none });
    expect(none.lines).toEqual(["No decisions or rejected alternatives recorded for loose.txt."]);
  });

  it("finds the project above the directory you are in, with the file relative to it", async () => {
    const sub = join(root, "sub", "deeper");
    await mkdir(sub, { recursive: true });
    const io = fakeIo(env);
    expect(await why({ cwd: sub, file: "../../a.txt", io })).toHaveLength(2);
    expect(await why({ cwd: root, file: "a.txt", io: fakeIo(env) })).toHaveLength(2);
    expect(await nearestProjectDir(sub)).toBe(root);
    const outside = await noGitDir();
    expect(await nearestProjectDir(outside)).toBeUndefined();
    await expect(why({ cwd: outside, file: "a.txt", io: fakeIo(env) })).rejects.toThrow(
      /not initialized/,
    );
  });

  it("refuses an uninitialized project, a non-repository and a missing file", async () => {
    const bare = join(dir, "bare");
    await mkdir(bare);
    await expect(why({ dir: bare, file: "a.txt", io: fakeIo(env) })).rejects.toThrow(
      /not initialized/,
    );

    const plain = await noGitProject(env);
    await expect(why({ dir: plain, file: "a.txt", io: fakeIo(env) })).rejects.toThrow(
      /not inside a git repository/,
    );
    await expect(why({ dir: root, file: "missing.txt", io: fakeIo(env) })).rejects.toThrow(
      /does not exist/,
    );
  });

  it("treats a repository with no commits as nothing known", async () => {
    const empty = join(dir, "empty");
    await mkdir(empty);
    await init(empty, { name: "empty", retention: "keep", language: "auto" }, fakeIo(env));
    await run("git", ["-C", empty, "init", "-q"]);
    await writeFile(join(empty, "a.txt"), "x\n");
    expect(await collectWhy(empty, "a.txt", env)).toEqual([]);
  });

  it("says plainly when the thoughts recorded no decisions", async () => {
    const record = session({
      nodes: [
        {
          id: A,
          parent: null,
          kind: "message",
          title: "Parse the file",
          at: "2026-10-20T09:00:00.000Z",
        },
      ],
    });
    await writeFile(projectPaths(root).session("s1"), JSON.stringify(record));
    expect(await collectWhy(root, "a.txt", env)).toEqual([]);
    expect(tryBeforeNote("a.txt", [])).toBeUndefined();
  });

  it("ignores a file no thought links to a commit", async () => {
    await writeFile(join(root, "other.txt"), "x\n");
    await git("add", "other.txt");
    await git("commit", "-q", "-m", "chore: other");
    expect(await collectWhy(root, "other.txt", env)).toEqual([]);
    // Outside the project, or a file that never existed.
    expect(await collectWhy(root, "../outside.txt", env)).toEqual([]);
    expect(await collectWhy(root, "missing.txt", env)).toEqual([]);
  });

  it("narrows to the thought behind one line (13.2)", async () => {
    // Line 1 came from the first commit (thought A), line 2 from the second (B).
    expect((await collectWhyLine(root, "a.txt", 1, env)).map((entry) => entry.messageId)).toEqual([
      A,
    ]);
    expect((await collectWhyLine(root, "a.txt", 2, env)).map((entry) => entry.messageId)).toEqual([
      B,
    ]);

    const io = fakeIo(env);
    expect(await why({ dir: root, file: "a.txt:1", io })).toHaveLength(1);
    const text = io.lines.join("\n");
    expect(text).toContain("decision: Parse the file — The old loop ate one line.");
    expect(text).toContain("not: Keep the loop — It loses data.");
    expect(text).not.toContain("Extend the parser");

    // `--line` takes the same path as the `:line` suffix.
    const flag = fakeIo(env);
    expect(await why({ dir: root, file: "a.txt", line: 2, io: flag })).toHaveLength(1);
    expect(flag.lines.join("\n")).toContain("Extend the parser");
    expect(flag.lines.join("\n")).not.toContain("Parse the file");

    const cliIo = fakeIo(env);
    const program = createProgram(() => cliIo);
    await program.parseAsync(["why", "a.txt", "--line", "1", "-C", root], { from: "user" });
    expect(cliIo.lines.join("\n")).toContain("h1111111  m1");
  });

  it("falls back to the file's other thoughts when the line has none (13.2)", async () => {
    await writeFile(join(root, "a.txt"), "one\ntwo\nthree\n");
    await git("add", "a.txt");
    await git("commit", "-q", "-m", "chore: third line");
    expect(await collectWhyLine(root, "a.txt", 3, env)).toEqual([]);

    const io = fakeIo(env);
    await why({ dir: root, file: "a.txt:3", io });
    const text = io.lines.join("\n");
    expect(io.lines[0]).toBe("No thought recorded for a.txt:3.");
    expect(text).toContain("Thoughts behind the rest of the file:");
    expect(text).toContain("h2222222  m2");
    expect(text).toContain("h1111111  m1");
  });

  it("reports a line git cannot blame (13.2)", async () => {
    await expect(why({ dir: root, file: "a.txt:99", io: fakeIo(env) })).rejects.toThrow(
      /git could not read a\.txt:99/,
    );
    await expect(why({ dir: root, file: "a.txt", line: 0, io: fakeIo(env) })).rejects.toThrow(
      /positive line number/,
    );
  });

  it("says plainly when a file has no thought for a line or anywhere else (13.2)", async () => {
    await writeFile(join(root, "plain.txt"), "x\n");
    await git("add", "plain.txt");
    await git("commit", "-q", "-m", "chore: plain");
    const io = fakeIo(env);
    await why({ dir: root, file: "plain.txt:1", io });
    expect(io.lines).toEqual(["No decisions or rejected alternatives recorded for plain.txt."]);
  });

  it("writes one note per file per session and then stays quiet", async () => {
    const first = await edit();
    expect(first).toBeDefined();
    const text = (JSON.parse(first ?? "") as { hookSpecificOutput: { additionalContext: string } })
      .hookSpecificOutput.additionalContext;
    expect(text).toContain("Earlier, for this file:");
    expect(text).toContain('"Keep the loop" was considered and rejected (h1111111,');
    expect(text).toContain("It loses data.");
    expect(text).toContain("Decide knowingly.");
    // A second edit of the same file in the same session: no second note.
    expect(await edit()).toBeUndefined();
    expect(JSON.parse(await readFile(projectPaths(root).state("s1"), "utf8"))).toMatchObject({
      notedFiles: ["a.txt"],
    });
  });

  it("does not note a file with nothing to say, and remembers the lookup", async () => {
    await writeFile(join(root, "other.txt"), "x\n");
    await git("add", "other.txt");
    await git("commit", "-q", "-m", "chore: other");
    expect(await edit({ tool_input: { file_path: join(root, "other.txt") } })).toBeUndefined();
    expect(JSON.parse(await readFile(projectPaths(root).state("s1"), "utf8"))).toMatchObject({
      notedFiles: ["other.txt"],
    });
  });

  it("stays quiet when the setting is off, for other tools, and outside the project", async () => {
    await configSet("tryBeforeNotes", "false", fakeIo(env));
    expect(await edit()).toBeUndefined();
    await configSet("tryBeforeNotes", "true", fakeIo(env));
    expect(await edit({ tool_name: "Bash", tool_input: { command: "ls" } })).toBeUndefined();
    expect(await edit({ tool_input: { file_path: join(dir, "outside.txt") } })).toBeUndefined();
    // Nothing was claimed by the skipped calls.
    expect(await edit()).toBeDefined();
  });

  it("keeps the note within five items and 600 characters", () => {
    const many: WhyHit[] = Array.from({ length: 9 }, (_, index) =>
      hit({
        messageId: `h${String(index + 1).repeat(12)}`,
        decisions: [
          {
            title: "d",
            why: "",
            alternatives: [{ option: `Option ${index}`, why: "it did not fit" }],
          },
        ],
      }),
    );
    const note = tryBeforeNote("a.txt", many);
    expect(note).toBeDefined();
    expect(note?.length).toBeLessThanOrEqual(TRY_BEFORE_MAX_CHARS);
    expect(note?.split("\n").filter((line) => line.startsWith("- "))).toHaveLength(
      TRY_BEFORE_MAX_ITEMS,
    );
    expect(note).toContain("`cogit why a.txt` for more.");

    const oneLong = tryBeforeNote("a.txt", [
      hit({
        decisions: [
          {
            title: "d",
            why: "",
            alternatives: [{ option: "A very long option", why: "y".repeat(500) }],
          },
        ],
      }),
    ]);
    expect(oneLong).toBeDefined();
    expect(oneLong?.length).toBeLessThanOrEqual(TRY_BEFORE_MAX_CHARS);
    expect(oneLong).toContain("Decide knowingly.");
  });

  it("counts every rejected option once", () => {
    expect(rejectedItems([hit(), hit()])).toHaveLength(2);
  });

  it("never throws when the hook's state cannot be written", async () => {
    // A regular file where the state directory belongs makes the state write fail.
    await writeFile(join(projectPaths(root).base, "state"), "not a directory");
    await expect(edit()).resolves.toBeUndefined();
  });
});