Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import type { ViewNode } from "../../cli/src/view/model.js";
/**
* Lays a git graph out (Stories 8.2 and 8.7): one row per item in send order,
* one lane per branch, branch starts curving out of the item they react to.
* Pure: the React component draws exactly what this returns.
*
* The same code lays out both levels: a session's messages (a message is a
* commit, `parent` is the message it reacts to) and the project's sessions (a
* session is a commit, `parent` is the session it continues). Git terms: a root
* starts something new, and a branch is a chain of items with only one child
* each. A message's `links` stay in the record and the details panel; the map
* does not draw them, since a branch already shows the return.
*/
/**
* What the layout reads from a row. `ViewNode` (a message) satisfies this, and
* the session level maps each session onto it, so there is one layout engine.
*/
export interface GitNode {
id: string;
label?: string | undefined;
title: string;
summary?: string | undefined;
at?: string | undefined;
parent?: string | null | undefined;
branch?: ViewNode["branch"];
continues?: ViewNode["continues"];
commits?: string[] | undefined;
commitTags?: ViewNode["commitTags"];
/** Numstat totals of the linked commits (Story 10.3). */
change?: ViewNode["change"];
unsummarized?: true | undefined;
/**
* When the item stops occupying its lane, as a timestamp. Session level only:
* two sessions that overlap in time must get parallel lanes even when their
* dots sit on different rows.
*/
until?: string | undefined;
}
/** One message per row; long branches fold into first / ⋮ N more / last. */
export const ROW_HEIGHT = 30;
/** A branch with more messages than this starts folded. */
export const FOLD_LIMIT = 4;
/** Extra space above a new root, so a fresh start reads as a break. */
export const ROOT_GAP = 24;
/** Distance between lanes; also the dot column spacing. */
export const LANE_GAP = 20;
const LANE_PAD = 10;
const LANE_TAIL = 6;
/** Width reserved for the row text right of the dots. */
export const ROW_WIDTH = 520;
const ROW_GAP = 8;
/**
* The narrowest a title may get (Story 9.2). The chips around it shrink or
* truncate instead, so a row with a branch label and a "continues" mark never
* squeezes its title into a one-letter column. `styles.css` pins the same
* value on `.git-title`; a test keeps the two in step.
*/
export const TITLE_MIN_WIDTH = 180;
/** How far the user may drag an open session's message rows narrower or wider. */
export const ROW_WIDTH_MIN = 360;
export const ROW_WIDTH_MAX = 1600;
/** A dragged or stored row width, kept in range; junk falls back to `ROW_WIDTH`. */
export function clampRowWidth(value: unknown): number {
if (typeof value !== "number" || !Number.isFinite(value)) return ROW_WIDTH;
return Math.round(Math.min(ROW_WIDTH_MAX, Math.max(ROW_WIDTH_MIN, value)));
}
/** How many lane colours the page defines (`--l0` … `--l5`). */
export const LANE_COLORS = 6;
export interface GitBranch {
title: string;
asked: string;
outcome: string;
open: string;
/** First and last message of the branch, for the "m33–m36" range. */
fromId: string;
toId: string;
/** The labels `m33` / `m36` the user reads; the ids are stable keys. */
fromLabel: string;
toLabel: string;
count: number;
firstAt?: string;
lastAt?: string;
}
export interface GitSegment {
/** The branch's first message id; stable across rebuilds, so UI state uses it. */
id: string;
ids: string[];
/** The message the branch starts from; null for a new root. */
parentId: string | null;
parentSegmentId: string | null;
lane: number;
/** Lane of the branch this one starts from; null for a root. */
parentLane: number | null;
colorIndex: number;
branch: GitBranch;
/** Row y of the branch's first message and of the message it reacts to. */
startY: number;
parentY: number | null;
}
/** One commit chip on a message row (Story 8.8). */
export interface GitCommitTag {
/** The hash as the record holds it; a stable key. */
hash: string;
/** The short hash the chip shows. */
short: string;
/** The commit's subject, when git still knows the commit. */
subject?: string;
/** True when git no longer knows the commit: the chip is drawn greyed. */
missing: boolean;
}
/** The message's commits as chips, from the build's subjects or the bare hashes. */
function tagsOf(message: GitNode): GitCommitTag[] {
const tags: GitCommitTag[] =
message.commitTags && message.commitTags.length > 0
? message.commitTags.map((commit) =>
commit.subject === undefined
? { hash: commit.hash, short: commit.hash.slice(0, 7), missing: true }
: {
hash: commit.hash,
short: commit.hash.slice(0, 7),
subject: commit.subject,
missing: false,
},
)
: (message.commits ?? []).map((hash) => ({
hash,
short: hash.slice(0, 7),
missing: true,
}));
return tags;
}
export interface GitMessageRow {
kind: "message";
message: GitNode;
segmentId: string;
colorIndex: number;
/** Centre of the row on the canvas. */
y: number;
/** First item of its branch: hollow ring and branch label. */
first: boolean;
/** A new root starts here, with a gap above it. */
gap: boolean;
/** Code commits the record lists for this message; empty for most rows. */
tags: GitCommitTag[];
/** "left off here": the newest message or session. */
head: boolean;
/** Row height: titles wrap instead of being cut, so long ones get taller rows. */
height: number;
/**
* Top of the space reserved below this row (`spaceAfter`), where the project
* map draws an opened session's messages, accordion-style.
*/
spaceTop?: number;
}
export interface GitMoreRow {
kind: "more";
segmentId: string;
colorIndex: number;
y: number;
height: number;
/** The messages the fold hides. */
hidden: string[];
}
export type GitRow = GitMessageRow | GitMoreRow;
export interface GitLayout {
segments: GitSegment[];
rows: GitRow[];
/** Dot x per lane. */
laneX: number[];
/** Width of the lanes area; the row text starts after it. */
graphWidth: number;
/** Width of the row text right of the dots. */
rowWidth: number;
/** Whole box: graph width, gap, then the row text. */
width: number;
height: number;
headId: string | null;
}
export interface GitLayoutOptions {
/** Branch ids the user has unfolded. */
unfolded?: ReadonlySet<string>;
/** The "Unfold all" toggle. */
openAll?: boolean;
/** Message that carries "left off here"; defaults to the newest message. */
headId?: string | null;
/**
* Fold long branches (default true). The session level passes false: one dot
* per session, and folding a chain of sessions would hide sessions.
*/
fold?: boolean;
/**
* Where an item stops occupying its lane, in send-order index space. Session
* level only: a session keeps its lane until `updatedAt`, so a session that
* starts while another is still running gets a parallel lane even when the
* two dots are not adjacent rows.
*/
itemEnd?: (item: GitNode) => number | null;
/** Width of the row text area; defaults to `ROW_WIDTH`. */
rowWidth?: number;
/**
* Extra height to leave below an item's row, by item id: the project map opens
* a session in place by reserving room for its messages under the session's
* row; the rows below move down and lanes run on through the space.
*/
spaceAfter?: ReadonlyMap<string, number>;
}
interface RawRow {
kind: "message" | "more";
/** Position in send order; a folded row sits just after its first message. */
index: number;
segment: GitSegment;
id?: string;
hidden?: string[];
y: number;
height: number;
gap: boolean;
spaceTop?: number;
}
/** Average glyph widths at the row's font sizes; a rough estimate is enough. */
const TITLE_CHAR = 6.4;
const TITLE_LINE = 16;
/**
* Commit tags stand in a block of at most this many per line and wrap below
* instead of being clipped; keep in step with `.git-tags` in `styles.css`.
*/
export const TAGS_PER_LINE = 2;
const TAG_WIDTH = 56;
const TAG_LINE = 18;
/** Padding, the time column and the gaps around it. */
const ROW_FIXED = 106;
/**
* Height of a message row whose title (and branch label) wrap instead of being
* cut with an ellipsis: the width left for the title after the fixed parts of
* the row decides how many lines it needs.
*/
export function rowHeight(
message: GitNode,
row: { tags: number; head: boolean },
rowWidth = ROW_WIDTH,
): number {
const fixed =
ROW_FIXED +
(message.label ?? message.id).length * 7 +
Math.min(row.tags, TAGS_PER_LINE) * TAG_WIDTH +
(row.head ? 92 : 0) +
(message.unsummarized ? 116 : 0);
const room = Math.max(TITLE_MIN_WIDTH, rowWidth - fixed);
const titleLines = Math.max(1, Math.ceil((message.title.length * TITLE_CHAR) / room));
const tagLines = Math.ceil(row.tags / TAGS_PER_LINE);
return Math.max(ROW_HEIGHT, 12 + Math.max(titleLines * TITLE_LINE, tagLines * TAG_LINE));
}
/** Parent ids that point forward, at themselves or outside the session become roots. */
function parentOf(message: GitNode, index: Map<string, number>): string | null {
const parent = message.parent;
if (typeof parent !== "string") return null;
const self = index.get(message.id) ?? 0;
const at = index.get(parent);
return at !== undefined && at < self ? parent : null;
}
function branchOf(ids: string[], byId: Map<string, GitNode>): GitBranch {
const first = byId.get(ids[0] ?? "");
const last = byId.get(ids[ids.length - 1] ?? "");
return {
title: (first?.branch?.title ?? first?.title ?? ids[0] ?? "").slice(0, 80),
asked: first?.branch?.asked ?? "",
outcome: first?.branch?.outcome ?? first?.summary ?? "",
open: first?.branch?.open ?? "",
fromId: ids[0] ?? "",
toId: ids[ids.length - 1] ?? "",
fromLabel: first?.label ?? ids[0] ?? "",
toLabel: last?.label ?? ids[ids.length - 1] ?? "",
count: ids.length,
...(first?.at === undefined ? {} : { firstAt: first.at }),
...(last?.at === undefined ? {} : { lastAt: last.at }),
};
}
export function layoutGitGraph(messages: GitNode[], options: GitLayoutOptions = {}): GitLayout {
const rowWidth = options.rowWidth ?? ROW_WIDTH;
const index = new Map(messages.map((message, at) => [message.id, at]));
const byId = new Map(messages.map((message) => [message.id, message]));
const kids = new Map<string | null, string[]>();
const parents = new Map<string, string | null>();
for (const message of messages) {
const parent = parentOf(message, index);
parents.set(message.id, parent);
const list = kids.get(parent) ?? [];
list.push(message.id);
kids.set(parent, list);
}
const children = (id: string | null): string[] => kids.get(id) ?? [];
// A branch runs while each message has exactly one child; every child of its
// last message starts a new branch hanging from it.
const segments: GitSegment[] = [];
const segOf = new Map<string, GitSegment>();
const build = (start: string, parentSegment: GitSegment | null): GitSegment => {
const ids = [start];
let cur = start;
while (children(cur).length === 1) {
cur = children(cur)[0] as string;
ids.push(cur);
}
const last = ids[ids.length - 1] as string;
const segment: GitSegment = {
id: start,
ids,
parentId: parents.get(start) ?? null,
parentSegmentId: parentSegment?.id ?? null,
lane: 0,
parentLane: null,
colorIndex: segments.length % LANE_COLORS,
branch: branchOf(ids, byId),
startY: 0,
parentY: null,
};
segments.push(segment);
for (const id of ids) segOf.set(id, segment);
// The last message id and branch id agree only by accident; keep the map
// from the last message's children as the branch points.
for (const child of children(last)) build(child, segment);
return segment;
};
for (const root of children(null)) build(root, null);
// No `headId` key: the newest message is HEAD. An explicit null means this
// session holds no HEAD (it is not the newest one), so its long branches fold.
const headId = "headId" in options ? options.headId : (messages[messages.length - 1]?.id ?? null);
const unfolded = options.unfolded ?? new Set<string>();
const openAll = options.openAll ?? false;
const fold = options.fold ?? true;
const raw: RawRow[] = [];
for (const segment of segments) {
const folded =
fold &&
segment.ids.length > FOLD_LIMIT &&
!openAll &&
!unfolded.has(segment.id) &&
!(headId !== null && segment.ids.includes(headId));
if (folded) {
const first = segment.ids[0] as string;
const last = segment.ids[segment.ids.length - 1] as string;
const hidden = segment.ids.slice(1, -1);
raw.push({
kind: "message",
index: index.get(first) ?? 0,
segment,
id: first,
y: 0,
height: ROW_HEIGHT,
gap: false,
});
raw.push({
kind: "more",
index: (index.get(first) ?? 0) + 0.5,
segment,
hidden,
y: 0,
height: ROW_HEIGHT,
gap: false,
});
raw.push({
kind: "message",
index: index.get(last) ?? 0,
segment,
id: last,
y: 0,
height: ROW_HEIGHT,
gap: false,
});
} else {
for (const id of segment.ids) {
raw.push({
kind: "message",
index: index.get(id) ?? 0,
segment,
id,
y: 0,
height: ROW_HEIGHT,
gap: false,
});
}
}
}
raw.sort((a, b) => a.index - b.index);
// Rows in time order; a new root gets a gap above it.
let cursor = ROW_HEIGHT / 2;
const rowOf = new Map<string, RawRow>();
raw.forEach((row, at) => {
row.gap =
at > 0 &&
row.kind === "message" &&
row.segment.parentId === null &&
row.segment.ids[0] === row.id;
if (row.gap) cursor += ROOT_GAP;
const message = row.kind === "message" ? byId.get(row.id ?? "") : undefined;
row.height = message
? rowHeight(
message,
{
tags: tagsOf(message).length,
head: message.id === headId,
},
rowWidth,
)
: ROW_HEIGHT;
row.y = cursor + row.height / 2;
cursor += row.height;
const space = row.kind === "message" ? options.spaceAfter?.get(row.id ?? "") : undefined;
if (space !== undefined && space > 0) {
row.spaceTop = cursor;
cursor += space;
}
if (row.kind === "message" && row.id) rowOf.set(row.id, row);
for (const hidden of row.hidden ?? []) rowOf.set(hidden, row);
});
// Lanes: a branch may reuse its parent's lane once the parent is done, and
// any lane whose earlier occupants no longer span this row. Spans are in
// send-order index space (monotonic with y), so both levels share this code;
// `itemEnd` lets the session level keep a lane busy until `updatedAt`.
const segById = new Map(segments.map((segment) => [segment.id, segment]));
const occupancy = new Map<number, [number, number][]>();
const ordered = [...segments].sort((a, b) => (index.get(a.id) ?? 0) - (index.get(b.id) ?? 0));
for (const segment of ordered) {
const first = rowOf.get(segment.ids[0] ?? "");
const last = rowOf.get(segment.ids[segment.ids.length - 1] ?? "");
if (!first || !last) continue;
const parentIndex = segment.parentId === null ? null : (index.get(segment.parentId) ?? null);
const start = parentIndex ?? index.get(segment.ids[0] ?? "") ?? 0;
let end = (index.get(segment.ids[segment.ids.length - 1] ?? "") ?? 0) + 0.1;
if (options.itemEnd) {
for (const id of segment.ids) {
const item = byId.get(id);
const custom = item ? options.itemEnd(item) : null;
if (custom !== null) end = Math.max(end, custom);
}
}
const span: [number, number] = [start, end];
const free = (lane: number): boolean =>
!(occupancy.get(lane) ?? []).some(([a, b]) => a < span[1] && span[0] < b);
const parent = segment.parentSegmentId === null ? null : segById.get(segment.parentSegmentId);
let lane = parent && free(parent.lane) ? parent.lane : 0;
while (!free(lane)) lane += 1;
segment.lane = lane;
segment.parentLane = parent?.lane ?? null;
segment.startY = first.y;
segment.parentY = (segment.parentId === null ? null : rowOf.get(segment.parentId)?.y) ?? null;
const list = occupancy.get(lane) ?? [];
list.push(span);
occupancy.set(lane, list);
}
const laneCount = Math.max(0, ...segments.map((segment) => segment.lane + 1));
const laneX = Array.from(
{ length: Math.max(laneCount, 1) },
(_, lane) => LANE_PAD + lane * LANE_GAP,
);
const graphWidth = LANE_PAD + Math.max(laneCount, 1) * LANE_GAP + LANE_TAIL;
const rows: GitRow[] = raw.map((row): GitRow => {
if (row.kind === "more") {
return {
kind: "more",
segmentId: row.segment.id,
colorIndex: row.segment.colorIndex,
y: row.y,
height: row.height,
hidden: row.hidden ?? [],
};
}
const message = byId.get(row.id ?? "");
if (!message) throw new Error(`message ${String(row.id)} vanished from the layout`);
return {
kind: "message",
message,
segmentId: row.segment.id,
colorIndex: row.segment.colorIndex,
y: row.y,
first: row.segment.ids[0] === message.id,
gap: row.gap,
tags: tagsOf(message),
head: message.id === headId,
height: row.height,
...(row.spaceTop === undefined ? {} : { spaceTop: row.spaceTop }),
};
});
return {
segments,
rows,
laneX,
graphWidth,
rowWidth,
width: graphWidth + ROW_GAP + rowWidth,
height: cursor,
headId,
};
}
/** The curve a branch start draws from its parent's dot into its lane. */
export function branchPath(segment: GitSegment, laneX: number[]): string {
const x = laneX[segment.lane] ?? 0;
const y0 = segment.parentY;
if (y0 === null) return "";
const px = segment.parentLane === null ? x : (laneX[segment.parentLane] ?? x);
if (px === x) return `M${x},${y0} L${x},${segment.startY}`;
return [
`M${px},${y0}`,
`C${px},${y0 + ROW_HEIGHT * 0.7} ${x},${y0 + ROW_HEIGHT * 0.3} ${x},${y0 + ROW_HEIGHT}`,
`L${x},${segment.startY}`,
].join(" ");
}