proctolog 0.1.1 → 0.2.0

data/public/asking.js

@@ -18,11 +18,25 @@ const quoted = (text) =>
 		.join("\n");
 
 // Where a decision stands, its words, and the pictures it rests on that
-// the desk holds on this Mac.
-const about = ({ pr, title, url, branch, head, text, pictures: shots }) => {
+// the desk holds on this Mac. One nobody has opened yet has no address on
+// GitHub: its branch and the file its description is kept in stand there.
+const about = ({
+	pr,
+	title,
+	url,
+	branch,
+	base,
+	file,
+	head,
+	text,
+	pictures: shots,
+}) => {
 	const here = shots.filter((picture) => picture.file);
+	const where = file
+		? `not opened, on ${branch} at ${head.slice(0, 7)}, into ${base}, described in ${file}`
+		: `(${url}), on ${branch} at ${head.slice(0, 7)}`;
 	return [
-		`#${pr}, "${title}" (${url}), on ${branch} at ${head.slice(0, 7)}:`,
+		`#${pr}, "${title}" ${where}:`,
 		quoted(text),
 		here.length &&
 			`Its pictures, on this Mac:\n${here.map((picture) => `- ${picture.name}: ${pictures}/${picture.file}`).join("\n")}`,
@@ -31,6 +45,19 @@ const about = ({ pr, title, url, branch, head, text, pictures: shots }) => {
 		.join("\n\n");
 };
 
+// How to read the pull requests asked about: GitHub has the opened ones,
+// git and the store the rest.
+const reading = (decisions) =>
+	[
+		decisions.some((each) => !each.file) &&
+			"Read a pull request with `gh pr view` and `gh pr diff`.",
+		decisions.some((each) => each.file) &&
+			"A pull request not opened yet is not on GitHub: read its code with `git log` and `git diff` from its base to its branch, and its description in the file named here.",
+		"If one has moved on since the head named here, say so.",
+	]
+		.filter(Boolean)
+		.join(" ");
+
 export const askingPrompt = (ids, question) => {
 	const decisions = ids.map((id) => inventory.find((each) => each.id === id));
 	const which =
@@ -38,7 +65,7 @@ export const askingPrompt = (ids, question) => {
 			? "one of their decisions"
 			: `${decisions.length} of their decisions`;
 	return [
-		`I am reviewing pull requests in PRoctolog and have a question on ${which} before I choose. Answer it plainly, with evidence. Change nothing while you do: no edits, no commits, no checkout, nothing on GitHub. Read a pull request with \`gh pr view\` and \`gh pr diff\`; if one has moved on since the head named here, say so.`,
+		`I am reviewing pull requests in PRoctolog and have a question on ${which} before I choose. Answer it plainly, with evidence. Change nothing while you do: no edits, no commits, no checkout, nothing on GitHub. ${reading(decisions)}`,
 		...decisions.map(about),
 		`My question:\n${question.trim()}`,
 	].join("\n\n");

data/public/decisions.js

@@ -9,7 +9,7 @@ import {
 	prepareScreenshots,
 	toggleScreenshots,
 } from "./decision-screenshots.js";
-import { helping, keyOf, mode } from "./keys.js";
+import { helping, keyOf, mode, overThePage } from "./keys.js";
 import { withMentions } from "./mentions.js";
 import { prNumber } from "./pr-number.js";
 import {
@@ -1092,9 +1092,9 @@ document.addEventListener("click", (event) => {
 });
 
 document.addEventListener("focusin", (event) => {
-	// A panel over the page, a picture looked at closely, takes the focus
-	// without leaving the decision: its Esc comes back to it.
-	if (event.target.closest("dialog")) return;
+	// A picture looked at closely, or a note written in Grouse's overlay, takes
+	// the focus without leaving the decision: its Esc comes back to it.
+	if (overThePage(event.target)) return;
 	const box = event.target.closest("[data-decision]");
 	if (inline) {
 		// Deciding begins only when it is asked for (f, Enter, a click, a choice's

data/public/desk.js

@@ -27,14 +27,18 @@ const follow = (key) => {
 	if (link) location.assign(link.href + location.hash);
 };
 
-// Opens the next pull request with decisions still to review: the one the
-// cursor rests on when it has some, else the first after it, going round to
-// the top of the route. With none left anywhere, the cursor's row says so.
+// Opens the next pull request that asks for the owner, with blocking
+// decisions to review or something back from the agent (Standing#asks_for_owner?):
+// the one the cursor rests on when it asks, else the first after it, going
+// round to the top of the route. With none left anywhere, the cursor's row
+// says so.
 const openUnreviewed = () => {
 	const ahead = [...stops.slice(at), ...stops.slice(0, at)];
-	// The non-blocking wait for one gesture on their pull request's page.
-	const next = ahead.find((stop) => Number(stop.dataset.blockingLeft) > 0);
-	if (!next) return said("Every decision of this burst is reviewed.");
+	const next = ahead.find((stop) => stop.dataset.asks === "true");
+	if (!next)
+		return said(
+			"Nothing asks for you: every blocking decision is reviewed, and nothing is back from the agent.",
+		);
 	restOn(stops.indexOf(next));
 	location.assign(next.querySelector("a").href);
 };

data/public/keys.js

@@ -201,6 +201,12 @@ export const thisBlock = (hints = []) => {
 export const helping = () =>
 	!!document.querySelector("dialog[open], :popover-open");
 
+// Whether the focus went over the page rather than along it: into a picture
+// looked at closely, or into Grouse's overlay to write a note on the desk.
+// Either leaves the page where it was, a decision being decided included.
+export const overThePage = (target) =>
+	!!target.closest?.("dialog, grouse-widget");
+
 // `hints` are pairs of keys and what they do: [["j k", "move"], ["a", "leave as is"]].
 let shown;
 export const mode = (name, hints = []) => {

data/public/notes.js

@@ -8,7 +8,7 @@
 // written in a small form right under what it is about (respond.js).
 
 import { helping, keyOf } from "./keys.js";
-import { respond } from "./respond.js";
+import { putAway, respond, saveInPlace } from "./respond.js";
 import { toast } from "./toast.js";
 import { tryIt } from "./try.js";
 import { viewPictures } from "./viewer.js";
@@ -195,9 +195,111 @@ const placeOn = (figure, box) => ({
 	},
 });
 
-// A note on a pair's half is written under the pair.
-const notePicture = (figure, box = [0, 0, 1, 1]) =>
-	respond(slotAfter(figure.closest("figure.picture")), placeOn(figure, box));
+// A note on a picture is written under it (under the pair, for one of its
+// halves) and saved without leaving the page, which stays where it was and
+// draws the note there.
+const notePicture = (figure, box = [0, 0, 1, 1]) => {
+	const slot = slotAfter(figure.closest("figure.picture"));
+	const form = respond(slot, placeOn(figure, box));
+	saveInPlace(form, async ({ id }) => {
+		await redrawNotes();
+		putAway(form);
+		lightNote(id);
+	});
+};
+
+// The marks of a note on the page and its card, lit where they stand.
+const lightNote = (id) => {
+	for (const part of document.querySelectorAll(
+		`[data-note="${id}"], [data-card="${id}"]`,
+	))
+		light(part);
+};
+
+// The page as the desk has it now, or nothing when the desk does not answer.
+const freshCopy = async () => {
+	const address = new URL(location.href);
+	// The page as it is, not GitHub read again.
+	address.searchParams.delete("fresh");
+	address.hash = "";
+	const response = await fetch(address, {
+		headers: { Accept: "text/html" },
+	}).catch(() => undefined);
+	if (!response?.ok) return undefined;
+	return new DOMParser().parseFromString(await response.text(), "text/html");
+};
+
+// Ways to find a place of the page, which a page and its fresh copy answer
+// alike.
+const selecting = (selector) => (page) => page.querySelector(selector);
+
+// The count beside the heading of one of the page's own sections, not the
+// description's: the description may have a section of the same name.
+const sectionCount = (heading) =>
+	selecting(`.page > details[data-heading="${heading}"] > summary .count`);
+
+// The count on the outline's line for a section: the last line so named, as
+// the description's sections come first and may have the same name.
+const outlineCount = (name) => (page) =>
+	[...page.querySelectorAll("[data-outline] > *")]
+		.findLast((line) => line.querySelector(".name")?.textContent === name)
+		?.querySelector(".count");
+
+// Where the page shows what a saved note changes: where the pull request
+// stands, the Standing section, the cards of the notes, and the counts of what
+// is open, beside two headings and on the outline. The outline's other counts
+// are kept by the scripts that own them.
+const CHANGED_BY_NOTES = [
+	selecting("#standing"),
+	selecting("section.standing"),
+	sectionCount("Standing"),
+	outlineCount("Standing"),
+	selecting("aside.margin"),
+	sectionCount("Notes"),
+	outlineCount("Notes"),
+];
+
+// The fresh copy's element in place of the page's, when both have one.
+const swapIn = (now, was) => {
+	if (!now || !was) return;
+	was.replaceWith(now);
+	readable(now);
+};
+
+// The notes as the desk now has them, drawn without the page going anywhere:
+// the boxes on its pictures, then everything else that notes change, from a
+// fresh copy of the page.
+const redrawNotes = async () => {
+	const fresh = await freshCopy();
+	if (!fresh) return location.reload();
+	redrawRegions(fresh);
+	for (const find of CHANGED_BY_NOTES) swapIn(find(fresh), find(document));
+};
+
+// The pictures of the description that notes are drawn on, by their asset:
+// the same picture shown twice is the same picture twice, in order.
+const figuresByAsset = (page) =>
+	Map.groupBy(
+		page.querySelectorAll(
+			"main.description :is(figure.picture:not(.pair), figure.pair > .half)[data-asset]",
+		),
+		(figure) => figure.dataset.asset,
+	);
+
+const redrawRegions = (fresh) => {
+	const drawn = figuresByAsset(fresh);
+	for (const [asset, figures] of figuresByAsset(document))
+		figures.forEach((figure, index) => {
+			const now = drawn.get(asset)?.[index];
+			if (!now) return;
+			// The region being drawn for a note not yet saved stays.
+			for (const region of figure.querySelectorAll(
+				":scope > .region:not(.draft)",
+			))
+				region.remove();
+			figure.append(...now.querySelectorAll(":scope > .region"));
+		});
+};
 
 let pending;
 document.addEventListener("selectionchange", () => {
@@ -211,11 +313,26 @@ document.addEventListener("selectionchange", () => {
 			rect.right,
 			innerWidth - selectionButton.offsetWidth - 8,
 		);
-		selectionButton.style.left = `${Math.max(8, left) + scrollX}px`;
-		selectionButton.style.top = `${rect.top + scrollY - selectionButton.offsetHeight - 6}px`;
+		const origin = originOf(selectionButton);
+		selectionButton.style.left = `${Math.max(8, left) - origin.left}px`;
+		selectionButton.style.top = `${rect.top - origin.top - selectionButton.offsetHeight - 6}px`;
 	}, 120);
 });
 
+// Where an element placed absolutely counts its left and top from, on the
+// screen: the box of the nearest ancestor laid out on its own (the column
+// beside the burst's pane), or else the page.
+const originOf = (element) => {
+	const parent = element.offsetParent;
+	if (!parent || getComputedStyle(parent).position === "static")
+		return { left: -scrollX, top: -scrollY };
+	const box = parent.getBoundingClientRect();
+	return {
+		left: box.left + parent.clientLeft - parent.scrollLeft,
+		top: box.top + parent.clientTop - parent.scrollTop,
+	};
+};
+
 // Keeps the selection alive while the button is pressed.
 selectionButton.addEventListener("mousedown", (event) =>
 	event.preventDefault(),
@@ -353,14 +470,18 @@ document.addEventListener("pointercancel", () => {
 	drag = null;
 });
 
-// Reading has its own cursor; Tab still reaches every link and control.
-for (const element of document.querySelectorAll(
-	"h1, h2, h3, h4, summary, .conditions > li, li.scenario, [data-card]",
-)) {
-	if (element.closest("[data-desk]")) continue;
-	element.dataset.reading = "";
-	if (element.localName !== "summary") element.tabIndex = -1;
-}
+// Reading has its own cursor; Tab still reaches every link and control. What
+// the page draws again, a card or a condition, is read the same way.
+const readable = (root) => {
+	for (const element of root.querySelectorAll(
+		"h1, h2, h3, h4, summary, .conditions > li, li.scenario, [data-card]",
+	)) {
+		if (element.closest("[data-desk]")) continue;
+		element.dataset.reading = "";
+		if (element.localName !== "summary") element.tabIndex = -1;
+	}
+};
+readable(document);
 for (const body of document.querySelectorAll("[data-quotable]")) {
 	for (const block of blocksIn(body)) {
 		if (!block.matches("figure.picture") && !hasWords(block)) continue;
@@ -498,7 +619,10 @@ const keys = {
 	G: () => {
 		const link = document.querySelector('.whole a[data-key="G"]');
 		if (link) link.click();
-		else toast("Nobody has opened this pull request yet: GitHub has nothing of it.");
+		else
+			toast(
+				"Nobody has opened this pull request yet: GitHub has nothing of it.",
+			);
 	},
 };
 
@@ -539,10 +663,9 @@ const linkedShown = (preview) => {
 // A note on a place marked in the viewer is written beside it, and saved
 // without leaving it, so that the owner goes on looking where they were. A
 // note drawn there opens beside it the same way, with its words, to be
-// written over or withdrawn. The page comes back at the last of them once the
-// viewer closes. A note the desk would not take is sent as the page sends it,
-// which says why.
-let notedAt;
+// written over or withdrawn. Once the viewer closes, the page draws them
+// where it is.
+let notedHere = false;
 const notesAddress = document
 	.querySelector("#note-form")
 	?.content.querySelector("form")
@@ -552,7 +675,13 @@ const savedHere = new Map();
 const writtenNote = (id) => {
 	const card = document.querySelector(`[data-card="${id}"]`);
 	const said = savedHere.get(id) ?? card?.dataset;
-	return said && { address: `${notesAddress}/${id}`, kind: said.kind, text: said.text };
+	return (
+		said && {
+			address: `${notesAddress}/${id}`,
+			kind: said.kind,
+			text: said.text,
+		}
+	);
 };
 const noteInViewer = ({ figure }, box, beside, id) => {
 	if (!figure?.dataset.asset) {
@@ -564,46 +693,23 @@ const noteInViewer = ({ figure }, box, beside, id) => {
 		toast("That note is not on this page, so it cannot be opened here.");
 		return false;
 	}
-	respond(beside, { ...placeOn(figure, box), written });
-	const form = beside.querySelector("form");
-	if (form.dataset.inViewer === undefined) {
-		form.dataset.inViewer = "";
-		form.addEventListener("submit", async (event) => {
-			event.preventDefault();
-			const response = await fetch(form.action, {
-				method: "POST",
-				body: new FormData(form, event.submitter),
-				headers: { Accept: "application/json" },
-			}).catch(() => undefined);
-			if (!response?.headers.get("content-type")?.includes("json"))
-				return form.submit();
-			const saved = await response.json();
-			const withdrawn = event.submitter?.matches("[data-withdraw]") ?? false;
-			notedAt = saved.at;
-			savedHere.set(saved.id, {
-				kind: form.elements.kind.value,
-				text: form.elements.text.value.trim(),
-			});
-			beside.dispatchEvent(
-				new CustomEvent("noted", { detail: { id: saved.id, withdrawn } }),
-			);
+	const form = respond(beside, { ...placeOn(figure, box), written });
+	saveInPlace(form, ({ id: saved, withdrawn }) => {
+		notedHere = true;
+		savedHere.set(saved, {
+			kind: form.elements.kind.value,
+			text: form.elements.text.value.trim(),
 		});
-	}
+		beside.dispatchEvent(
+			new CustomEvent("noted", { detail: { id: saved, withdrawn } }),
+		);
+	});
 	return true;
 };
-const backAtNote = () => {
-	if (!notedAt) return;
-	const at = new URL(notedAt, location.href);
-	notedAt = undefined;
-	// A decision being decided keeps the page where it is: the page shows
-	// the note the next time it loads.
-	if (document.body.dataset.focus)
-		return toast(
-			"Your note is kept. The description shows it the next time the page loads.",
-		);
-	if (at.pathname !== location.pathname) return location.assign(at);
-	history.replaceState(history.state, "", at);
-	location.reload();
+const redrawSavedNotes = () => {
+	if (!notedHere) return;
+	notedHere = false;
+	redrawNotes();
 };
 // The pictures Space would open here, and which of them first; nothing when
 // the owner is not at a picture, and Space is the browser's to scroll with.
@@ -633,7 +739,7 @@ const lookClosely = (found = picturesHere(), first = found?.first) => {
 	if (found)
 		viewPictures(found.pictures, first, {
 			note: noteInViewer,
-			closed: backAtNote,
+			closed: redrawSavedNotes,
 		});
 };
 keys[" "] = lookClosely;

data/public/pick.css

@@ -97,3 +97,24 @@
 		margin-left: 10ch;
 	}
 }
+
+/* What to do here, before anything to pick: framed, so a first look lands on it. */
+.pick .start {
+	margin: 0 0 24px;
+	padding: 12px 16px;
+	border: 1px solid var(--rule-strong);
+	background: var(--surface);
+}
+
+.pick .start h2 {
+	margin-top: 0;
+}
+
+.pick .start p {
+	max-width: 72ch;
+	margin: 0 0 8px;
+}
+
+.pick .start p:last-child {
+	margin-bottom: 0;
+}

data/public/respond.css

@@ -109,6 +109,12 @@ li.card p {
 	font-size: 0.85rem;
 }
 
+/* Where a note answered in a handover is judged, in place of the buttons. */
+.card .moves .judged {
+	margin: 0;
+	color: var(--quiet);
+}
+
 .card[data-state="confirmed"],
 .card[data-state="withdrawn"] {
 	opacity: 0.7;

data/public/respond.js

@@ -15,10 +15,11 @@ const fill = (form, name, values) => {
 };
 
 // Opens the form in `slot`, or turns the one already there to this note,
-// keeping what was typed. `quote` and `picture` are the parts of a place;
-// `back` is the address to come back to once the note is saved, when the page
-// is not the pull request's own. `written`, a note already there by its
-// `address`, `kind` and `text`, opens it again to be written over or withdrawn.
+// keeping what was typed, and gives the form back. `quote` and `picture` are
+// the parts of a place; `back` is the address to come back to once the note is
+// saved, when the page is not the pull request's own. `written`, a note
+// already there by its `address`, `kind` and `text`, opens it again to be
+// written over or withdrawn.
 export const respond = (
 	slot,
 	{ kind = "change", action, on, quote, picture, back, written },
@@ -54,17 +55,60 @@ export const respond = (
 	// Written again from where it ends.
 	const end = form.elements.text.value.length;
 	if (written) form.elements.text.setSelectionRange(end, end);
+	return form;
 };
 
-const close = (holder) => {
+// The form taken away, its note saved or not: its slot says so by "closed".
+// It is given the form, or anything in it.
+export const putAway = (inside) => {
+	const holder = inside.closest(".respond");
 	const slot = holder.parentElement;
 	holder.remove();
 	slot.dispatchEvent(new CustomEvent("closed", { bubbles: true }));
 };
 
+// A note sent from `form` without leaving the page: `saved` is called with
+// what the desk answers, the note's `id` and `at`, the address that shows it,
+// and whether it was withdrawn. A note the desk would not take is sent as the
+// page sends it, which says why.
+export const saveInPlace = (form, saved) => {
+	// The form already in a slot is turned to each note opened there: it is
+	// listened to once.
+	if (form.dataset.inPlace !== undefined) return;
+	form.dataset.inPlace = "";
+	form.addEventListener("submit", async (event) => {
+		event.preventDefault();
+		const response = await fetch(form.action, {
+			method: "POST",
+			body: new FormData(form, event.submitter),
+			headers: { Accept: "application/json" },
+		}).catch(() => undefined);
+		if (!response?.headers.get("content-type")?.includes("json"))
+			return sendAsThePage(form, event.submitter);
+		saved({
+			...(await response.json()),
+			withdrawn: event.submitter?.matches("[data-withdraw]") ?? false,
+		});
+	});
+};
+
+// The form sent as the page sends it, with the button pressed, which
+// form.submit() leaves out: without it a withdrawal would go as an edit.
+const sendAsThePage = (form, button) => {
+	if (button?.name)
+		form.append(
+			Object.assign(document.createElement("input"), {
+				type: "hidden",
+				name: button.name,
+				value: button.value,
+			}),
+		);
+	form.submit();
+};
+
 document.addEventListener("click", (event) => {
 	const cancel = event.target.closest("[data-cancel]");
-	if (cancel) return close(cancel.closest(".respond"));
+	if (cancel) return putAway(cancel);
 
 	const action = event.target.closest("[data-respond]");
 	if (!action) return;
@@ -91,5 +135,5 @@ document.addEventListener("keydown", (event) => {
 
 	if (event.key === "Enter" && (event.metaKey || event.ctrlKey))
 		holder.querySelector("form").requestSubmit();
-	if (event.key === "Escape" && !event.target.value) close(holder);
+	if (event.key === "Escape" && !event.target.value) putAway(holder);
 });

data/public/review-drafts.js

@@ -447,11 +447,14 @@ export const progress = (pr) => {
 	const mine = (entry) => of(entry.decision.pr);
 	const picked = items.filter(chosen).length;
 	const ticked = items.filter((item) => !chosen(item) && item.ticked).length;
+	const blocking = items.filter((item) => item.grade !== "non_blocking");
 	return {
 		total: items.length,
 		chosen: picked,
 		ticked,
 		left: items.length - picked - ticked,
+		blocking: blocking.length,
+		blockingLeft: blocking.filter((item) => !reviewed(item)).length,
 		drafts: state.pending.filter(mine).length,
 		again: state.choices.filter(
 			(entry) =>
@@ -485,20 +488,55 @@ const changed = () => {
 };
 
 // The pane at the left counts the same choices: its rows follow them as they
-// are made, in the marks the server wrote them with.
+// are made, in beads as the server draws them (DeskHelper#decision_beads).
+const reviewedInWords = ({ name, total, left }) => {
+	const decisions = `${name} ${total === 1 ? "decision" : "decisions"}`;
+	const reviewed = total - left;
+	if (!left)
+		return total === 1
+			? `its one ${decisions} reviewed`
+			: `all ${total} ${decisions} reviewed`;
+	if (!reviewed) return `none of ${total} ${decisions} reviewed yet`;
+	return `${reviewed} of ${total} ${decisions} reviewed`;
+};
+const span = (properties, ...children) => {
+	const element = Object.assign(document.createElement("span"), properties);
+	element.append(...children);
+	return element;
+};
+const beadsOf = (now) =>
+	span(
+		{ className: "beads" },
+		...[
+			{ name: "blocking", total: now.blocking, left: now.blockingLeft },
+			{
+				name: "non-blocking",
+				total: now.total - now.blocking,
+				left: now.left - now.blockingLeft,
+			},
+		]
+			.filter((grade) => grade.total)
+			.map((grade) =>
+				span(
+					{
+						className: grade.name,
+						role: "img",
+						ariaLabel: reviewedInWords(grade),
+					},
+					...Array.from({ length: grade.total }, (_, at) =>
+						span({
+							className: at < grade.total - grade.left ? "bead reviewed" : "bead",
+						}),
+					),
+				),
+			),
+	);
 const side = () => {
 	const count = (number) => number.toLocaleString("en-US");
 	for (const row of document.querySelectorAll("[data-side-pr]")) {
 		const now = progress(prNumber(row.dataset.sidePr));
 		if (!now.total) continue;
-		const done = now.chosen + now.ticked;
-		row.querySelector("[data-side-mark]").textContent = !now.left
-			? "x"
-			: done
-				? "~"
-				: "";
-		row.querySelector("[data-side-fraction]").textContent =
-			`${done}/${now.total}`;
+		row.querySelector("[data-side-decisions]").replaceChildren(beadsOf(now));
 	}
 	const overall = document.querySelector("[data-side-overall]");
 	if (!overall || !inventory.length) return;