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.

16.2 KB
Raw Blame
import { type Author, sameAuthor } from "../author.js";
import type { Project } from "../schema/project.js";
import type { LineageNode, Session } from "../schema/session.js";
import {
  DATA_ELEMENT_ID,
  type LineageViewModel,
  type PageModel,
  type PanelSettings,
  type StatusCard,
  VIEW_SCHEMA,
  type ViewChatTurn,
  type ViewNode,
  type ViewPendingMessage,
  type ViewSession,
} from "./model.js";

/**
 * The session's user messages, flat and in the order they were sent (8.2). A
 * message hangs from the earlier message it reacts to; an explicit `null` in
 * the record makes a new root. Any other parent (a topic in an older record, a
 * forward or unknown id) falls back to the previous message, so an old record
 * renders as one chain and no message is ever dropped.
 */
export function buildMessages(
  nodes: LineageNode[],
  pending: ViewPendingMessage[] = [],
  commitSubjects?: ReadonlyMap<string, string>,
  commitFiles?: ReadonlyMap<string, string[]>,
): ViewNode[] {
  const recorded = nodes.filter((node) => node.kind === "message");
  // One row per message in send order; unrecorded messages are part of the same
  // order, so a session's labels (`m1`, `m2`, …) count both and line up with
  // `session show` (Story 8.5).
  type Row =
    | { kind: "recorded"; node: LineageNode; index: number }
    | { kind: "pending"; message: ViewPendingMessage; index: number };
  const combined: Row[] = [
    ...recorded.map((node, index): Row => ({ kind: "recorded", node, index })),
    ...pending.map(
      (message, index): Row => ({ kind: "pending", message, index: recorded.length + index }),
    ),
  ].sort(
    (a, b) =>
      ((a.kind === "recorded" ? a.node.at : a.message.at) ?? "").localeCompare(
        (b.kind === "recorded" ? b.node.at : b.message.at) ?? "",
      ) || a.index - b.index,
  );
  const idOf = (row: Row): string => (row.kind === "recorded" ? row.node.id : row.message.id);
  const known = new Set(combined.map(idOf));
  /** Position in send order: a parent or link must come before the message. */
  const order = new Map(combined.map((row, index) => [idOf(row), index]));
  const earlier = (other: string, id: string): boolean => {
    const otherAt = order.get(other);
    const selfAt = order.get(id);
    return otherAt !== undefined && selfAt !== undefined && otherAt < selfAt;
  };
  const out: ViewNode[] = [];
  let previous: string | null = null;

  const push = (message: ViewNode, parent: string | null): void => {
    message.parent = parent;
    message.label = `m${out.length + 1}`;
    out.push(message);
    previous = message.id;
  };

  for (const row of combined) {
    if (row.kind === "pending") {
      push(
        {
          id: row.message.id,
          kind: "message",
          title: row.message.title,
          at: row.message.at,
          unsummarized: true,
        },
        previous,
      );
      continue;
    }
    const node = row.node;
    // A `<sessionId>:<id>` parent points into another session's graph (8.6): it
    // stays on the node for the map to resolve, and the local layout sees no
    // parent (the message reads as a root of this session).
    const parentRef = node.parent ?? null;
    const cross = parentRef !== null && parentRef.includes(":");
    const parent =
      parentRef === null
        ? null
        : cross
          ? parentRef
          : known.has(parentRef) && earlier(parentRef, node.id)
            ? parentRef
            : previous;
    const links = (node.links ?? []).filter((link) => known.has(link) && earlier(link, node.id));
    push(
      {
        id: node.id,
        kind: node.kind,
        title: node.title,
        ...(node.summary === undefined ? {} : { summary: node.summary }),
        ...(node.why === undefined ? {} : { why: node.why }),
        ...(node.at === undefined ? {} : { at: node.at }),
        ...(node.decidedBy === undefined ? {} : { decidedBy: node.decidedBy }),
        ...(node.alternatives?.length ? { alternatives: node.alternatives } : {}),
        ...(node.commits?.length ? { commits: node.commits } : {}),
        // Story 10.3: the numstat totals the build attached to the record node.
        ...(node.change === undefined ? {} : { change: node.change }),
        ...(node.commits?.length
          ? {
              commitTags: node.commits.map((hash) => {
                const subject = commitSubjects?.get(hash);
                const files = commitFiles?.get(hash);
                return {
                  hash,
                  ...(subject === undefined ? {} : { subject }),
                  ...(files === undefined ? {} : { files }),
                };
              }),
            }
          : {}),
        ...(node.files?.length ? { files: node.files } : {}),
        ...(node.work?.length ? { work: node.work } : {}),
        ...(node.agentDecisions?.length ? { agentDecisions: node.agentDecisions } : {}),
        // Story 13.6: the Shape travels with the record, as written and validated.
        ...(node.shape === undefined ? {} : { shape: node.shape }),
        ...(node.addedAt === undefined ? {} : { addedAt: node.addedAt }),
        ...(node.touchedAt === undefined ? {} : { touchedAt: node.touchedAt }),
        ...(node.branch === undefined ? {} : { branch: node.branch }),
        ...(links.length ? { links } : {}),
      },
      parent,
    );
  }
  return out;
}

/** A session counts as active while it was updated within this window. */
export const ACTIVE_WINDOW_DAYS = 7;
const ACTIVE_WINDOW_MS = ACTIVE_WINDOW_DAYS * 24 * 60 * 60 * 1000;

/** Parsed timestamp, with `-Infinity` for a value the date parser rejects. */
function timestamp(value: string): number {
  const time = Date.parse(value);
  return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
}

function isActive(session: Session, now: string): boolean {
  const updated = timestamp(session.updatedAt);
  const reference = timestamp(now);
  if (updated === Number.NEGATIVE_INFINITY || reference === Number.NEGATIVE_INFINITY) return false;
  return reference - updated <= ACTIVE_WINDOW_MS;
}

/** Most recently updated first; the session id keeps equal timestamps deterministic. */
function byUpdatedAt(a: Session, b: Session): number {
  return timestamp(b.updatedAt) - timestamp(a.updatedAt) || a.sessionId.localeCompare(b.sessionId);
}

/** The timestamp the session was last active at, and that value as stored. */
interface Activity {
  value: string;
  time: number;
}

/**
 * Activity is message time, not record time (Story 9.5): fixing an old record
 * touches its `updatedAt`, which must not make the session look like it ran
 * until now. A session with no timed message falls back to `updatedAt`.
 */
function lastActivityOf(session: Session): Activity {
  let value = session.updatedAt;
  let time = Number.NEGATIVE_INFINITY;
  for (const node of session.nodes) {
    if (node.kind !== "message" || node.at === undefined) continue;
    const at = timestamp(node.at);
    if (at > time) {
      time = at;
      value = node.at;
    }
  }
  return { value, time: time === Number.NEGATIVE_INFINITY ? timestamp(value) : time };
}

/** When the session was last active; the newest message's time, else `updatedAt`. */
export function lastActive(session: Session): number {
  return lastActivityOf(session).time;
}

function hasStatus(session: Session): boolean {
  const { goal, done, pending, next } = session.status;
  return goal !== "" || next !== "" || done.length > 0 || pending.length > 0;
}

/**
 * The status card: goal, done, pending and next come from the most recently
 * updated session that recorded a status, so a newer session without one does not
 * blank the card; `needsUser` items are merged from every other session active
 * within `ACTIVE_WINDOW_DAYS`, newest first and deduplicated by text. Last
 * activity is the newest message time across every session (Story 9.5), not the
 * newest `updatedAt`. `now` is the build time the window is measured against.
 */
export function statusCard(sessions: Session[], now: string): StatusCard {
  const ordered = [...sessions].sort(byUpdatedAt);
  const latest = ordered.find(hasStatus);

  const pending = (latest?.status.pending ?? []).map((item) => ({ ...item }));
  const seen = new Set(pending.map((item) => item.text));
  const others = ordered.filter((session) => session !== latest);
  for (const session of others) {
    if (!isActive(session, now)) continue;
    for (const item of session.status.pending) {
      if (!item.needsUser || seen.has(item.text)) continue;
      seen.add(item.text);
      pending.push({ ...item });
    }
  }

  const activity = ordered
    .map(lastActivityOf)
    .reduce<Activity | null>(
      (best, current) => (best === null || current.time > best.time ? current : best),
      null,
    );

  return {
    goal: latest?.status.goal ?? "",
    done: latest?.status.done ?? [],
    pending,
    next: latest?.status.next ?? "",
    lastActivity: activity?.value ?? null,
  };
}

/**
 * The title a session shows: its own, else its first message's, so a record the
 * recorder left untitled reads as what it is about instead of a bare id.
 */
export function sessionTitle(session: Pick<Session, "title" | "nodes">): string {
  const own = session.title.trim();
  if (own) return own;
  return session.nodes.find((node) => node.kind === "message")?.title.trim() ?? "";
}

/**
 * The messages the record does not hold yet join the end of the chain, so the
 * newest message is on the map before the agent summarizes it (8.2).
 */
function toViewSession(
  session: Session,
  transcripts?: ReadonlySet<string>,
  chat?: ViewChatTurn[],
  unrecorded?: number,
  pending?: ViewPendingMessage[],
  commitSubjects?: ReadonlyMap<string, string>,
  commitFiles?: ReadonlyMap<string, string[]>,
): ViewSession {
  return {
    sessionId: session.sessionId,
    agent: session.agent,
    title: sessionTitle(session),
    ...(session.author === undefined ? {} : { author: session.author }),
    ...(session.authorEmail === undefined ? {} : { authorEmail: session.authorEmail }),
    startedAt: session.startedAt,
    updatedAt: session.updatedAt,
    status: session.status,
    messages: buildMessages(session.nodes, pending, commitSubjects, commitFiles),
    // Undefined means the caller did not ask (fixtures, unit tests); then the
    // record is shown as resumable rather than pretending the transcript is gone.
    transcriptAvailable: transcripts === undefined ? true : transcripts.has(session.sessionId),
    ...(session.worktree ? { worktree: session.worktree } : {}),
    ...(unrecorded ? { unrecordedMessages: unrecorded } : {}),
    ...(chat ? { chat } : {}),
  };
}

/** Sessions in chronological order; the id keeps ties deterministic. */
function byStartedAt(a: Session, b: Session): number {
  return a.startedAt.localeCompare(b.startedAt) || a.sessionId.localeCompare(b.sessionId);
}

export interface ViewModelInput {
  project: Project;
  sessions: Session[];
  /** Absolute project path shown on the page. */
  path: string;
  generatedAt: string;
  /** Session ids whose Claude Code transcript still exists; omit to skip the check. */
  transcripts?: ReadonlySet<string>;
  /** Each session's conversation from its transcript, shown in the drill-down. */
  chats?: ReadonlyMap<string, ViewChatTurn[]>;
  /** Unrecorded message counts, shown while the catch-up is off. */
  unrecorded?: ReadonlyMap<string, number> | undefined;
  /** User messages with no node yet, drawn as not-yet-summarized cards. */
  pending?: ReadonlyMap<string, ViewPendingMessage[]> | undefined;
  /** Commit subjects read from git at build time (Story 8.8). */
  commitSubjects?: ReadonlyMap<string, string> | undefined;
  /** Project-relative files per commit, for the diff rows (Story 10.5). */
  commitFiles?: ReadonlyMap<string, string[]> | undefined;
  /** Settings embedded for the modal's `file://` view (Story 8.13). */
  settings?: PanelSettings | undefined;
  /** The git identity of whoever builds the page, to tell their sessions from others'. */
  viewer?: Author | undefined;
}

/**
 * Turns a `<sessionId>:<id>` parent into the `continues` mark the map draws and
 * leaves the message a root of its own session, so one session's graph never
 * leaks into another's (8.6). Runs once every session's labels are known.
 * A target the map no longer holds still gets the mark, with the raw id. A
 * session never continues another person's: such a parent (written before that
 * rule) leaves the message a plain root.
 */
export function resolveContinues(sessions: ViewSession[]): void {
  const byId = new Map(sessions.map((session) => [session.sessionId, session]));
  for (const session of sessions) {
    for (const message of session.messages) {
      const parent = message.parent;
      if (typeof parent !== "string") continue;
      const at = parent.indexOf(":");
      if (at === -1) continue;
      const otherId = parent.slice(0, at);
      const id = parent.slice(at + 1);
      const other = byId.get(otherId);
      const target = other?.messages.find((candidate) => candidate.id === id);
      message.parent = null;
      if (other && !sameAuthor(session, other)) continue;
      message.continues = {
        sessionId: otherId,
        sessionTitle: other?.title || otherId,
        id,
        ...(target?.label === undefined ? {} : { label: target.label }),
      };
    }
  }
}

/** Builds the page model: every session, by `startedAt`. */
export function buildViewModel(input: ViewModelInput): LineageViewModel {
  const sessions = [...input.sessions].sort(byStartedAt);
  const views: ViewSession[] = [];

  for (const session of sessions) {
    const view = toViewSession(
      session,
      input.transcripts,
      input.chats?.get(session.sessionId),
      input.unrecorded?.get(session.sessionId),
      input.pending?.get(session.sessionId),
      input.commitSubjects,
      input.commitFiles,
    );
    views.push(view);
  }
  resolveContinues(views);

  return {
    kind: "lineage",
    schema: VIEW_SCHEMA,
    project: { name: input.project.name, path: input.path, generatedAt: input.generatedAt },
    status: statusCard(sessions, input.generatedAt),
    sessions: views,
    ...(input.settings === undefined ? {} : { settings: input.settings }),
    ...(input.viewer === undefined ? {} : { viewer: viewerOf(input.viewer) }),
  };
}

function viewerOf(viewer: Author): NonNullable<LineageViewModel["viewer"]> {
  return {
    ...(viewer.author === undefined ? {} : { author: viewer.author }),
    ...(viewer.authorEmail === undefined ? {} : { authorEmail: viewer.authorEmail }),
  };
}

const EMPTY_DATA_ELEMENT = `<script id="${DATA_ELEMENT_ID}" type="application/json"></script>`;

/**
 * Escapes `<`, `>`, `&`, U+2028 and U+2029 inside the serialized JSON. The
 * escapes stay valid JSON (`<`), so a `</script>` in the data cannot end the
 * element, and the template can stay one file.
 */
export function escapeForScript(json: string): string {
  return json.replace(
    /[<>&\u2028\u2029]/g,
    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
  );
}

/** Fills the template's empty data element with the serialized model. */
/** The meta tag naming the cogit version that built a map page. */
export const BUILT_BY_META_NAME = "cogit-built-by";

/** Stamps the version that built the page, so a server of another version can rebuild it. */
export function markBuiltBy(html: string, version: string): string {
  const meta = `<meta name="${BUILT_BY_META_NAME}" content="${version}">`;
  return html.replace(/<head(\s[^>]*)?>/i, (head) => `${head}${meta}`);
}

/** The version that built a page, or null for a page built before the stamp. */
export function builtBy(html: string): string | null {
  const match = html.match(/<meta name="cogit-built-by" content="([^"]*)">/);
  return match?.[1] ?? null;
}

export function embedViewModel(template: string, model: PageModel): string {
  if (!template.includes(EMPTY_DATA_ELEMENT)) {
    throw new Error(`the template has no empty <script id="${DATA_ELEMENT_ID}"> element`);
  }
  // One value per line, so a text search in the project prints a line and not the
  // whole record. A string in JSON has no raw newline, so every one here is layout.
  const json = JSON.stringify(model, null, 1).replace(/\n +/g, "\n");
  const data = `<script id="${DATA_ELEMENT_ID}" type="application/json">${escapeForScript(json)}</script>`;
  // A function, not a string: a `$'` or `$&` in the data must not act as a replace pattern.
  return template.replace(EMPTY_DATA_ELEMENT, () => data);
}