bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/review-app/src/kit/finish.tsx

@@ -0,0 +1,274 @@
+// The end of the review. On a PR: the reviewer's pending comments on GitHub, each with its lines and editable here, and a
+// panel with how far they got, a summary and a verdict, submitted.
+// On local changes: what went to the developer's agent, and telling it the reviewer is done.
+import { useEffect, useRef, useState } from "react";
+import { Body, Composer, dropComment, editComment, finishReview, openCount, rowAt, useComments, type ReviewComment } from "./comments";
+import { highlight, isReviewed } from "./code";
+import { diffs, rows, type Row } from "./pr";
+import { liveVerdict, saveVerdict, useLive, type Verdict } from "./live";
+import { pr } from "./pr";
+import { seenChapters, useNav } from "./review";
+import { Section } from "./ui";
+
+const VERDICTS: { event: NonNullable<Verdict["event"]>; name: string; hint: string }[] = [
+  { event: "COMMENT", name: "Comment", hint: "Feedback without a verdict." },
+  { event: "APPROVE", name: "Approve", hint: "Ready to merge." },
+  { event: "REQUEST_CHANGES", name: "Request changes", hint: "Needs another pass before it merges." },
+];
+
+// the lines a comment is on, as the diff shows them; a few at most
+function linesOf(c: ReviewComment): Row[] {
+  if (!c.path || !c.side || !c.line) return [];
+  const all = rows(diffs[c.path] ?? "");
+  const end = rowAt(all, c.side, c.line);
+  const start = c.startLine ? rowAt(all, c.startSide ?? c.side, c.startLine) : end;
+  return start < 0 || end < 0 ? [] : all.slice(Math.max(start, end - 5), end + 1);
+}
+
+// a comment of the reviewer's on GitHub, with its lines; pending ones are edited or deleted right here
+function Card({ c }: { c: ReviewComment }) {
+  const [editing, setEditing] = useState(false);
+  const [error, setError] = useState<string>();
+  const lines = linesOf(c);
+  const pending = c.github?.state === "pending";
+  return (
+    <div className={`fin-c${pending ? "" : " posted"}`}>
+      {lines.length > 0 && (
+        <div className="fin-snip">
+          {lines.map((r, i) => <div key={i} className={r.t === "c" ? "" : r.t}><span className="n">{r.t === "d" ? r.o : r.n}</span><span className="s">{highlight(r.s)}{r.s ? "" : " "}</span></div>)}
+        </div>
+      )}
+      {editing ? (
+        <Composer edit initial={c.body} onCancel={() => setEditing(false)} onSave={async (b) => { const e = await editComment(c.id, b); if (!e) setEditing(false); return e; }} />
+      ) : (
+        <>
+          <Body text={c.body} />
+          <div className="fin-bar">
+            <span className="fin-tags">
+              <span className={`note-tag${pending ? " pending" : ""}`}>{pending ? "Pending" : "Posted"}</span>
+              {c.agent && <span className="note-tag">Drafted by the agent</span>}
+              {c.inReplyTo && <span className="note-tag">Reply</span>}
+            </span>
+            {pending ? (
+              <>
+                <button className="btn ghost sm" onClick={() => setEditing(true)}>Edit</button>
+                <button className="btn ghost sm" onClick={async () => setError(await dropComment(c.id))}>Delete</button>
+              </>
+            ) : c.github?.url ? <a className="link" href={c.github.url} target="_blank" rel="noreferrer">On GitHub</a> : null}
+          </div>
+        </>
+      )}
+      {error && <div className="composer-error" role="alert">{error}</div>}
+    </div>
+  );
+}
+
+export function Finish() {
+  const all = useComments();
+  if (!pr.number) return <LocalFinish />;
+  const mine = all.filter((c) => c.by === "reviewer" && c.to === "github");
+  const files = [...new Set(mine.map((c) => c.path!))];
+  return (
+    <section className="view fin">
+      <div className="fin-main">
+        <h1 className="title">Finish the review</h1>
+        {files.length ? files.map((f) => (
+          <div className="fin-file" key={f}>
+            <div className="fin-fh"><b>{f.split("/").pop()}</b><span>{mine.filter((c) => c.path === f).length}</span></div>
+            {mine.filter((c) => c.path === f).map((c) => <Card key={c.id} c={c} />)}
+          </div>
+        )) : <p className="prose">No comments yet. In Changes, press the + next to a line, or drag it over several.</p>}
+      </div>
+      <Submit pending={openCount(all)} />
+    </section>
+  );
+}
+
+// how far the reviewer got: chapters opened, and files marked reviewed in Changes
+function Meters() {
+  const { review } = useNav();
+  const seen = review.chapters.filter((c) => seenChapters.has(c.id)).length;
+  const done = (path: string) => {
+    const gs = review.groups.filter((g) => g.file === path);
+    return gs.length ? gs.every((g) => isReviewed(g.id)) : isReviewed(`file-${path}`);
+  };
+  const reviewed = pr.files.filter((f) => done(f.path)).length;
+  const meter = (n: number, of: number, label: string) => (
+    <div className="meter">
+      <div>{n} / {of} {label}</div>
+      <div className="track">{Array.from({ length: of }, (_, i) => <i key={i} className={i < n ? "on" : ""} />)}</div>
+    </div>
+  );
+  return <div className="meters">{meter(seen, review.chapters.length, "chapters")}{meter(reviewed, pr.files.length, "files")}</div>;
+}
+
+// the summary saves as it is written; a summary saved elsewhere fills an empty field
+function useSummary() {
+  const { verdict } = useLive();
+  const [body, setBody] = useState(verdict.body ?? "");
+  const typed = useRef(false);
+  useEffect(() => {
+    if (!typed.current) setBody(verdict.body ?? "");
+  }, [verdict.body]);
+  useEffect(() => {
+    if (!typed.current) return;
+    // onto the verdict as it is when the save lands, so a verdict chosen meanwhile is kept
+    const t = setTimeout(() => void saveVerdict({ ...liveVerdict(), body: body || undefined }), 400);
+    return () => clearTimeout(t);
+  }, [body]);
+  return { body, setBody: (b: string) => ((typed.current = true), setBody(b)), verdict };
+}
+
+async function post(path: string): Promise<{ ok: true; data: any } | { ok: false; error: string }> {
+  try {
+    const r = await fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+    const data = await r.json().catch(() => ({}));
+    return r.ok ? { ok: true, data } : { ok: false, error: (data as { errors?: string[] }).errors?.join(", ") ?? `The review server answered ${r.status}.` };
+  } catch {
+    return { ok: false, error: "The review server is not answering." };
+  }
+}
+
+// submitting takes a second click: it publishes the review under the reviewer's name
+function Submit({ pending }: { pending: number }) {
+  const { body, setBody, verdict } = useSummary();
+  const [busy, setBusy] = useState(false);
+  const [confirm, setConfirm] = useState(false);
+  const [done, setDone] = useState<string>();
+  const [error, setError] = useState<string>();
+  const ref = useRef<HTMLTextAreaElement>(null);
+  // the summary grows with what is written
+  useEffect(() => {
+    const t = ref.current;
+    if (t) {
+      t.style.height = "auto";
+      t.style.height = `${Math.max(t.scrollHeight, 96)}px`;
+    }
+  }, [body]);
+  const chosen = VERDICTS.find((v) => v.event === verdict.event);
+  const go = async () => {
+    setBusy(true);
+    setError(undefined);
+    await saveVerdict({ ...verdict, body: body || undefined });
+    const r = await post("api/submit");
+    setBusy(false);
+    setConfirm(false);
+    if (r.ok) setDone(r.data.url);
+    else setError(r.error);
+  };
+  if (done)
+    return (
+      <aside className="fin-panel">
+        <h2>Submitted{chosen ? ` as ${chosen.name}` : ""}</h2>
+        <p className="prose">Your comments and summary are on the PR. <a className="link" href={done} target="_blank" rel="noreferrer">Open it on GitHub</a></p>
+      </aside>
+    );
+  return (
+    <aside className="fin-panel">
+      <h2>Finish your review</h2>
+      <Meters />
+      <textarea ref={ref} className="field" value={body} placeholder="Leave a summary" aria-label="Summary" onChange={(e) => setBody(e.target.value)} />
+      <div className="vswitch" role="radiogroup" aria-label="Verdict">
+        {VERDICTS.map((v) => (
+          <button key={v.event} role="radio" aria-checked={verdict.event === v.event} title={v.hint} onClick={() => { setConfirm(false); void saveVerdict({ ...verdict, body: body || undefined, event: v.event }); }}>{v.name}</button>
+        ))}
+      </div>
+      {error && <p className="prose post-error" role="alert">{error}</p>}
+      <div className="fin-actions">
+        {confirm ? (
+          <>
+            <button className="btn" disabled={busy} onClick={() => setConfirm(false)}>Cancel</button>
+            <button className="btn primary" disabled={busy} onClick={() => void go()}>{busy ? "Submitting" : `Yes, submit as ${chosen?.name}`}</button>
+          </>
+        ) : (
+          <button className="btn primary" disabled={!chosen} title={chosen ? undefined : "Choose a verdict first"} onClick={() => setConfirm(true)}>Submit review{pending > 0 && <span className="count">{pending}</span>}</button>
+        )}
+      </div>
+    </aside>
+  );
+}
+
+
+// a message on one line, as plain text: code blocks folded, markdown marks and list bullets dropped
+const gist = (text: string) => text.replace(/```[\s\S]*?```/g, "(code)").replace(/^\s*(?:[-*+]|\d+\.|>|#+)\s+/gm, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim();
+const ASKED = { sent: "Sent", working: "Working on it", done: "Answered", stopped: "Stopped" } as const;
+
+// local changes: what the developer's agent did after the reviewer asked, then telling it they are done
+function LocalFinish() {
+  const all = useComments();
+  const { updates } = useLive();
+  const asked = all.filter((c) => c.by === "reviewer" && c.to === "agent");
+  const answerOf = (c: ReviewComment) => all.find((x) => x.by === "agent" && x.replyTo === c.id);
+  return (
+    <section className="view fin">
+      <div className="fin-main">
+        <h1 className="title">Finish the review</h1>
+        {updates.length > 0 && (
+          <Section label="Updates" count={updates.length}>
+            <div className="rows">
+              {[...updates].reverse().map((u) => (
+                <div key={u.n} className="row">
+                  <span className="grow">{u.note}</span>
+                  <span className={`note-tag${u.refreshed ? "" : " pending"}`}>{u.refreshed ? "In the tour" : "Updating the tour"}</span>
+                </div>
+              ))}
+            </div>
+          </Section>
+        )}
+        {asked.length ? (
+          <div className="rows">
+            {asked.map((c) => {
+              const a = answerOf(c);
+              return (
+                <div key={c.id} className="row fin-ask">
+                  <span className="grow">
+                    <span className="fin-q">{gist(c.body)}</span>
+                    {a && <span className="fin-a">{gist(a.body)}</span>}
+                  </span>
+                  <span className={`note-tag agent ${c.status}`}>{ASKED[c.status ?? "sent"]}</span>
+                </div>
+              );
+            })}
+          </div>
+        ) : <p className="prose">Nothing asked yet. The Agent button in the footer opens the chat.</p>}
+      </div>
+      <Done />
+    </section>
+  );
+}
+
+// tells the developer's agent the reviewer is done, with a last word
+function Done() {
+  const { body, setBody } = useSummary();
+  const [state, setState] = useState<"idle" | "busy" | "done">("idle");
+  const [error, setError] = useState<string>();
+  const { agent } = useLive();
+  const finish = async () => {
+    setState("busy");
+    const e = await finishReview(body.trim() || undefined);
+    setError(e);
+    setState(e ? "idle" : "done");
+  };
+  if (state === "done")
+    return (
+      <aside className="fin-panel">
+        <h2>Done</h2>
+        <p className="prose">{agent.listening ? "Your agent has been told you are done." : "Your agent hears it the next time it waits."}</p>
+      </aside>
+    );
+  return (
+    <aside className="fin-panel">
+      <h2>Finish your review</h2>
+      <Meters />
+      <textarea className="field" value={body} placeholder="A note for your agent, e.g. commit it and open a PR" aria-label="Note for your agent" onChange={(e) => setBody(e.target.value)} />
+      <Listening />
+      {error && <p className="prose post-error" role="alert">{error}</p>}
+      <div className="fin-actions"><button className="btn primary" disabled={state === "busy"} onClick={() => void finish()}>Looks good</button></div>
+    </aside>
+  );
+}
+
+export function Listening() {
+  const { agent } = useLive();
+  return <span className={`listening${agent.listening ? " on" : ""}`}><span className="lamp" />{agent.listening ? "Your agent is listening" : "No agent is listening"}</span>;
+}

package/review-app/src/kit/flow.tsx

@@ -0,0 +1,184 @@
+// A diagram of the parts a change runs through, lit by review hook events as a step runs.
+import { useEffect, useMemo, useRef } from "react";
+import type { ReviewEvent, Status } from "./live";
+import type { Instance } from "./review";
+
+export interface FlowDef {
+  id: string;
+  title: string;
+  // nodes sit on a grid, col and row from 0
+  nodes: { id: string; title: string; sub?: string; col: number; row: number }[];
+  edges: [string, string][];
+  // the nodes this PR changes, drawn dashed
+  changed?: string[];
+}
+
+type P = { x: number; y: number };
+const R = 8;
+// an edge between two nodes: straight along a row or column, otherwise out sideways and around one rounded corner
+function route(a: P, b: P, wa: number, wb: number, h: number): { d: string; tip: string } {
+  if (a.y === b.y) {
+    const [x1, x2, dir] = b.x > a.x ? [a.x + wa, b.x - 2, 1] : [a.x, b.x + wb + 2, -1];
+    const y = a.y + h / 2;
+    return { d: `M${x1} ${y} H${x2}`, tip: `M${x2} ${y} l${-5 * dir} -3.5 v7 z` };
+  }
+  const down = b.y > a.y ? 1 : -1;
+  if (a.x === b.x) {
+    const x = a.x + wa / 2, y1 = down > 0 ? a.y + h : a.y, y2 = down > 0 ? b.y - 2 : b.y + h + 2;
+    return { d: `M${x} ${y1} V${y2}`, tip: `M${x} ${y2} l-3.5 ${-5 * down} h7 z` };
+  }
+  // leave from the side facing the target, turn once, enter from above or below
+  const right = b.x > a.x ? 1 : -1;
+  const x1 = right > 0 ? a.x + wa : a.x, y1 = a.y + h / 2, x2 = b.x + wb / 2, y2 = down > 0 ? b.y - 2 : b.y + h + 2;
+  return {
+    d: `M${x1} ${y1} H${x2 - R * right} Q${x2} ${y1} ${x2} ${y1 + R * down} V${y2}`,
+    tip: `M${x2} ${y2} l-3.5 ${-5 * down} h7 z`,
+  };
+}
+
+// text width in the page's font, to size columns and cut what does not fit
+let ctx: CanvasRenderingContext2D | null | undefined;
+function measure(text: string, font: string): number {
+  ctx ??= document.createElement("canvas").getContext("2d");
+  if (!ctx) return text.length * 7;
+  const css = getComputedStyle(document.documentElement);
+  ctx.font = font.replace("SANS", css.getPropertyValue("--sans")).replace("MONO", css.getPropertyValue("--mono"));
+  return ctx.measureText(text).width;
+}
+function fit(text: string, font: string, max: number): string {
+  if (measure(text, font) <= max) return text;
+  let lo = 0, hi = text.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (measure(text.slice(0, mid) + "\u2026", font) <= max) lo = mid;
+    else hi = mid - 1;
+  }
+  return text.slice(0, lo).trimEnd() + "\u2026";
+}
+const TITLE = "500 13px SANS", SUB = "400 12px MONO", LAB = "500 12px SANS";
+const PAD = 12, MIN = 120, MAX = 220, GAP = 48, NH = 58, ROWGAP = 30;
+
+// the latest state each node reported in these events
+function useNodeState(mine: ReviewEvent[]) {
+  return useMemo(() => {
+    const s: Record<string, { status?: Status; label?: string }> = {};
+    for (const e of mine) if (e.flow?.node) s[e.flow.node] = { status: e.flow.status ?? s[e.flow.node]?.status, label: e.flow.label ?? s[e.flow.node]?.label };
+    return s;
+  }, [mine.length]);
+}
+
+// the latest state of each node, and whether anything reached it, in one instance's events
+function nodeStates(events: ReviewEvent[], flow: string) {
+  const s: Record<string, { status?: Status; label?: string; reached?: boolean }> = {};
+  for (const e of events) {
+    if (e.flow?.id !== flow) continue;
+    if (e.flow.edge) s[e.flow.edge[1]] = { ...s[e.flow.edge[1]], reached: true };
+    if (e.flow.node) s[e.flow.node] = { reached: true, status: e.flow.status ?? s[e.flow.node]?.status, label: e.flow.label ?? s[e.flow.node]?.label };
+  }
+  return s;
+}
+
+// beside a chapter's text: the flow's parts down the side, joined by a line, and a column per instance with what
+// happened at each part, so base and head compare row by row
+export function FlowCompare({ def, here, instances, events }: { def: FlowDef; here?: string; instances: Instance[]; events: ReviewEvent[] }) {
+  const nodes = [...def.nodes].sort((a, b) => a.col - b.col || a.row - b.row);
+  const states = Object.fromEntries(instances.map((i) => [i.id, nodeStates(events.filter((e) => e.instance === i.id), def.id)]));
+  return (
+    <div className="fcmp" role="table" aria-label={def.title} style={{ gridTemplateColumns: `minmax(0, 1.25fr) repeat(${instances.length}, minmax(0, 1fr))` }}>
+      <div role="row" className="fcmp-row fcmp-head">
+        <span role="columnheader" />
+        {instances.map((i) => <span role="columnheader" key={i.id}>{i.label}</span>)}
+      </div>
+      {nodes.map((n, k) => (
+        <div role="row" key={n.id} className={`fcmp-row${here === n.id ? " here" : ""}${k === 0 ? " first" : ""}${k === nodes.length - 1 ? " last" : ""}`}>
+          <span role="rowheader" className={`fcmp-node${def.changed?.includes(n.id) ? " changed" : ""}`} title={def.changed?.includes(n.id) ? `${n.title}, changed by this PR` : n.title}>
+            <i aria-hidden="true" />
+            <span>{n.title}</span>
+          </span>
+          {instances.map((i) => {
+            const s = states[i.id][n.id];
+            return (
+              <span role="cell" key={i.id} className={`fcmp-cell ${s?.status ?? ""}`} title={s?.label}>
+                {s?.label ? <span key={s.label}>{s.label}</span> : s?.reached ? <b key="reached" aria-label="reached" /> : null}
+              </span>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// events for this flow from one instance: a packet along an edge, a node's state and label
+export function Flow(props: { def: FlowDef; here?: string; events?: ReviewEvent[] }) {
+  return <FlowDiagram def={props.def} here={props.here} mine={(props.events ?? []).filter((e) => e.flow?.id === props.def.id)} />;
+}
+
+// the full diagram: each column as wide as its longest title or sub, up to a cap, so labels arriving never move it;
+// what does not fit is cut and shown on hover
+function FlowDiagram({ def, here, mine }: { def: FlowDef; here?: string; mine: ReviewEvent[] }) {
+  const state = useNodeState(mine);
+  const cols = Math.max(...def.nodes.map((n) => n.col)) + 1;
+  const widths = Array.from({ length: cols }, (_, c) => {
+    const texts = def.nodes.filter((n) => n.col === c).flatMap((n) => [measure(n.title, TITLE), n.sub ? measure(n.sub, SUB) : 0]);
+    return Math.min(MAX, Math.max(MIN, Math.ceil(Math.max(...texts)) + PAD * 2));
+  });
+  const xs = widths.reduce<number[]>((acc, _, i) => [...acc, i ? acc[i - 1] + widths[i - 1] + GAP : 0], []);
+  const pos = Object.fromEntries(def.nodes.map((n) => [n.id, { x: xs[n.col], y: n.row * (NH + ROWGAP) }]));
+  const nw = (id: string) => widths[def.nodes.find((n) => n.id === id)!.col];
+  const w = xs[cols - 1] + widths[cols - 1];
+  const h = Math.max(...def.nodes.map((n) => n.row)) * (NH + ROWGAP) + NH;
+  const lit = new Set(mine.filter((e) => e.flow?.edge).map((e) => e.flow!.edge!.join(">")));
+
+  // a packet runs along an edge for each new edge event
+  const svg = useRef<SVGSVGElement>(null);
+  const seen = useRef(0);
+  useEffect(() => {
+    for (const e of mine.slice(seen.current)) {
+      const path = e.flow?.edge && svg.current?.querySelector<SVGPathElement>(`[data-e="${e.flow.edge.join(">")}"]`);
+      if (!path || matchMedia("(prefers-reduced-motion: reduce)").matches) continue;
+      const dot = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+      dot.setAttribute("r", "3");
+      dot.setAttribute("class", "packet");
+      svg.current!.append(dot);
+      const len = path.getTotalLength(), t0 = performance.now();
+      const tick = (t: number) => {
+        const k = Math.min(1, (t - t0) / 460);
+        const p = path.getPointAtLength(len * (1 - (1 - k) ** 3));
+        dot.setAttribute("cx", String(p.x));
+        dot.setAttribute("cy", String(p.y));
+        k < 1 ? requestAnimationFrame(tick) : dot.remove();
+      };
+      requestAnimationFrame(tick);
+    }
+    seen.current = mine.length;
+  }, [mine.length]);
+
+  return (
+    <svg ref={svg} className="flow" viewBox={`-1 -1 ${w + 2} ${h + 2}`} style={{ maxWidth: w + 2 }} role="img" aria-label={def.title}>
+      {def.edges.map(([a, b]) => {
+        const { d, tip } = route(pos[a], pos[b], nw(a), nw(b), NH);
+        return (
+          <g key={`${a}>${b}`}>
+            <path className={`fedge${lit.has(`${a}>${b}`) ? " lit" : ""}`} data-e={`${a}>${b}`} d={d} />
+            <path className="arrow" d={tip} />
+          </g>
+        );
+      })}
+      {def.nodes.map((n) => {
+        const s = state[n.id];
+        const cls = ["fnode", def.changed?.includes(n.id) && "changed", here === n.id && "here", s?.status].filter(Boolean).join(" ");
+        const room = nw(n.id) - PAD * 2;
+        const second = s?.label ? { cls: "lab", text: s.label, font: LAB } : n.sub ? { cls: "sub", text: n.sub, font: SUB } : undefined;
+        return (
+          <g key={n.id} className={cls} transform={`translate(${pos[n.id].x},${pos[n.id].y})`}>
+            <title>{[n.title, s?.label ?? n.sub].filter(Boolean).join(": ")}</title>
+            <rect width={nw(n.id)} height={NH} rx={9} />
+            <text x={PAD} y={25}>{fit(n.title, TITLE, room)}</text>
+            {second && <text className={second.cls} x={PAD} y={42}>{fit(second.text, second.font, room)}</text>}
+          </g>
+        );
+      })}
+    </svg>
+  );
+}

package/review-app/src/kit/index.ts

@@ -0,0 +1,10 @@
+// Everything a review is built from. Use these first; write your own components next to them when they do not fit.
+export { defineReview, useNav, useChapter, outcomeOf, type Review, type Instance, type ChapterDef, type Group, type Target } from "./review";
+export { pr, shortTitle, diffs } from "./pr";
+export { Overview, Lead, BeforeAfter, Attention, Card, type AttentionItem, type HeldClaim } from "./overview";
+export { Chapter, Outcome } from "./chapter";
+export { Flow, type FlowDef } from "./flow";
+export { Live, Shot, Compare, Clip } from "./media";
+export { Diff, Changes, highlight } from "./code";
+export { Section, Label, Row, Rows, FileLine, Stat, Icon, InstanceName } from "./ui";
+export { useLive, runStep, resetEvents, useUrl, file, type ReviewEvent, type Status } from "./live";