Skip to content

Commit 93a3aef

Browse files
cknittclaude
andcommitted
Mark the commits the last push added or edited
One comment shows every commit, so after a force push a reader can't tell what changed. With the head before the push, the comment marks each commit that push added (✨, "new") or whose message it edited under the same subject (✏️, "edited"); a rebase that changes no message marks nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AzPS5F8RDSGZ6dhfK6NdZp Signed-off-by: Christoph Knittel <ck@cca.io>
1 parent 08486bc commit 93a3aef

6 files changed

Lines changed: 169 additions & 16 deletions

File tree

‎.claude/skills/records/SKILL.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,8 @@ node scripts/commitRecords.js --out page.html [--pr <number>] [--title <text>] \
194194
`.github/workflows/semantic_diff.yml` renders each pull request's range
195195
and comments the records as Markdown (`--markdown <file> --url <page>`,
196196
scripts/recordMarkdown.js) with the page's link, one comment that each
197-
push updates to hold every commit.
197+
push updates to hold every commit, marking those the push added or
198+
edited (`--previous <previous head>`).
198199
- In prose, `#1234` and full pull request and issue URLs link as `#1234`,
199200
and the 9-character short sha of a commit on the page links to its card.
200201

‎.github/workflows/semantic_diff.yml‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ name: Semantic Diff
44
# as a review page on the CDN, and comments them on the pull request as
55
# Markdown (scripts/recordMarkdown.js) with the page's link. A pull request
66
# has one such comment, which each push updates in place to hold every
7-
# commit, so the pull request shows its current records in one place.
7+
# commit, so the pull request shows its current records in one place; the
8+
# comment marks the commits the last push added or edited.
89
#
910
# A pull request from a branch of this repository runs on pull_request, with
1011
# the workflow and renderer of its merge into the base branch: GitHub takes
@@ -42,6 +43,9 @@ jobs:
4243
PR_NUMBER: ${{ github.event.pull_request.number }}
4344
PR_TITLE: ${{ github.event.pull_request.title }}
4445
BASE_SHA: ${{ github.event.pull_request.base.sha }}
46+
# The head before a push; empty when the pull request is opened or
47+
# reopened.
48+
BEFORE_SHA: ${{ github.event.action == 'synchronize' && github.event.before || '' }}
4549
steps:
4650
- name: Checkout renderer
4751
uses: actions/checkout@v7
@@ -59,8 +63,16 @@ jobs:
5963
# The query string names the rendered commit, so each push gets a
6064
# URL that no cache has seen.
6165
url="https://cdn.rescript-lang.org/semantic-diff/pr-${PR_NUMBER}/index.html?v=${head}"
66+
# The comment marks what the push changed against the head before
67+
# it. A force push leaves that head on no branch, but GitHub still
68+
# serves it by its sha; when it can't be fetched, nothing is marked.
69+
previous=()
70+
if [ -n "$BEFORE_SHA" ] && { git cat-file -e "${BEFORE_SHA}^{commit}" 2>/dev/null ||
71+
git fetch --no-tags --filter=blob:none origin "$BEFORE_SHA" 2>/dev/null; }; then
72+
previous=(--previous "$BEFORE_SHA")
73+
fi
6274
mkdir -p semantic-diff
63-
node scripts/commitRecords.js --out semantic-diff/index.html --markdown semantic-diff/comment.md --url "$url" --pr "$PR_NUMBER" --title "$PR_TITLE" "${base}..pr-${PR_NUMBER}"
75+
node scripts/commitRecords.js --out semantic-diff/index.html --markdown semantic-diff/comment.md "${previous[@]}" --url "$url" --pr "$PR_NUMBER" --title "$PR_TITLE" "${base}..pr-${PR_NUMBER}"
6476
6577
- name: Setup Rclone
6678
uses: cometkim/rclone-actions/setup-rclone@8d9c6b95341f7698609deee65c3d62af42893288 # main, 2025-06-18

‎scripts/commitRecords.js‎

Lines changed: 67 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111
* node scripts/commitRecords.js --out review.html <base>..<tip>...
1212
* --pr <number> and --title <text> head the page with the pull request.
1313
* --markdown <file> also draws the records as the pull request's comment
14-
* (scripts/recordMarkdown.js), linking the page at --url <url>.
14+
* (scripts/recordMarkdown.js), linking the page at --url <url>. With
15+
* --previous <rev>, the pull request's head before the last push, the
16+
* comment marks the commits that push added or whose message it edited.
1517
*/
1618

1719
import { execFileSync } from "node:child_process";
@@ -37,6 +39,12 @@ const utc = (/** @type {Date} */ d) => {
3739
return `${MONTHS[d.getUTCMonth()]} ${two(d.getUTCDate())}, ${d.getUTCFullYear()}, ${two(d.getUTCHours())}:${two(d.getUTCMinutes())} UTC`;
3840
};
3941

42+
/** A commit's message, trimmed. @param {string} rev */
43+
const message = rev => git(["show", "-s", "--format=%B", rev]).trim();
44+
45+
/** The messages of the records read, by short hash. */
46+
const messages = new Map();
47+
4048
/**
4149
* The record of one commit: its short hash, author, author date (in UTC,
4250
* to the minute) and message.
@@ -46,12 +54,61 @@ const utc = (/** @type {Date} */ d) => {
4654
function readRecord(rev) {
4755
const show = (/** @type {string[]} */ ...format) =>
4856
git(["show", "-s", ...format, rev]);
49-
return parseRecord({
57+
const record = parseRecord({
5058
sha: show("--format=%h", "--abbrev=9").trim(),
5159
author: show("--format=%an").trim(),
5260
date: utc(new Date(show("--format=%aI").trim())),
5361
message: show("--format=%B"),
5462
});
63+
messages.set(record.sha, message(rev));
64+
return record;
65+
}
66+
67+
/**
68+
* What the last push changed, against the head before it: the records it
69+
* added (`new`) or whose message it edited under the same subject
70+
* (`edited`), by short hash. The previous commits are those of `previous`
71+
* that the range's base lacks.
72+
* @param {CommitRecord[]} records
73+
* @param {string} base
74+
* @param {string} previous
75+
*/
76+
function lastPush(records, base, previous) {
77+
const before = git([
78+
"rev-list",
79+
"--no-merges",
80+
previous,
81+
`^${git(["merge-base", base, previous]).trim()}`,
82+
])
83+
.split("\n")
84+
.filter(Boolean)
85+
.map(message);
86+
const subject = (/** @type {string} */ m) => m.split("\n")[0];
87+
const kept = new Set(before);
88+
const subjects = new Set(before.map(subject));
89+
/** @type {Map<string, "new" | "edited">} */
90+
const changes = new Map();
91+
for (const r of records) {
92+
const m = messages.get(r.sha) ?? "";
93+
if (!kept.has(m))
94+
changes.set(r.sha, subjects.has(subject(m)) ? "edited" : "new");
95+
}
96+
return changes;
97+
}
98+
99+
/**
100+
* The comment's marks of the last push, or none when the previous head
101+
* can't be read, so that the comment is still drawn.
102+
* @param {CommitRecord[]} records
103+
* @param {string} base
104+
* @param {string} previous
105+
*/
106+
function marks(records, base, previous) {
107+
try {
108+
return { changes: lastPush(records, base, previous) };
109+
} catch {
110+
return {};
111+
}
55112
}
56113

57114
/**
@@ -74,7 +131,9 @@ const options = {};
74131
const targets = [];
75132
for (let i = 0; i < args.length; i++) {
76133
if (
77-
["--out", "--pr", "--title", "--markdown", "--url"].includes(args[i]) &&
134+
["--out", "--pr", "--title", "--markdown", "--url", "--previous"].includes(
135+
args[i],
136+
) &&
78137
i + 1 < args.length
79138
)
80139
options[args[i].slice(2)] = args[++i];
@@ -83,7 +142,7 @@ for (let i = 0; i < args.length; i++) {
83142
const outFile = options.out;
84143
if (!outFile) {
85144
console.error(
86-
"usage: commitRecords.js --out <page.html> [--pr <number>] [--title <text>] [--markdown <comment.md> [--url <page url>]] <rev | base..tip>...",
145+
"usage: commitRecords.js --out <page.html> [--pr <number>] [--title <text>] [--markdown <comment.md> [--url <page url>] [--previous <rev>]] <rev | base..tip>...",
87146
);
88147
process.exit(1);
89148
}
@@ -95,12 +154,16 @@ const groups = targets.map(group);
95154
const body = pageBody(groups, heading);
96155
if (options.markdown) {
97156
const [base, tip] = targets[targets.length - 1].split("..");
157+
const records = groups.flatMap(g => g.records);
98158
writeFileSync(
99159
options.markdown,
100160
commentMarkdown(groups, {
101161
url: options.url,
102162
head: git(["rev-parse", "--short=9", tip ?? base]).trim(),
103163
updated: utc(new Date()),
164+
...(options.previous && tip
165+
? marks(records, base, options.previous)
166+
: {}),
104167
}),
105168
);
106169
console.log(options.markdown);

‎scripts/commitRecords.test.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -865,3 +865,43 @@ test("--markdown draws every commit into the comment, with the page's link", asy
865865
has(comment, "First change");
866866
has(comment, "Second change");
867867
});
868+
869+
test("--previous marks the commits the last push added or edited", async () => {
870+
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "commit-records-"));
871+
const git = (/** @type {string[]} */ ...a) =>
872+
execFileSync("git", a, { cwd: dir, encoding: "utf8" }).trim();
873+
git("init", "-q", "-b", "main");
874+
git("config", "user.name", "A Person");
875+
git("config", "user.email", "a@example.com");
876+
await commit(git, dir, { "a.txt": "a\n" }, "base");
877+
const base = git("rev-parse", "HEAD");
878+
await commit(git, dir, {}, `Kept\n\n${SIGNED}`);
879+
await commit(git, dir, {}, `Edited\n\nFirst words.\n\n${SIGNED}`);
880+
await commit(git, dir, {}, `Dropped\n\n${SIGNED}`);
881+
const previous = git("rev-parse", "HEAD");
882+
// A force push: the last commit dropped, the one below reworded, one added.
883+
git("reset", "-q", "--hard", "HEAD~2");
884+
await commit(git, dir, {}, `Edited\n\nOther words.\n\n${SIGNED}`);
885+
await commit(git, dir, {}, `Added\n\n${SIGNED}`);
886+
const md = path.join(dir, "comment.md");
887+
const r = spawnSync(
888+
"node",
889+
[
890+
script,
891+
...["--out", path.join(dir, "page.html"), "--markdown", md],
892+
...["--previous", previous, `${base}..HEAD`],
893+
],
894+
{ cwd: dir, encoding: "utf8" },
895+
);
896+
assert.equal(r.status, 0, r.stderr);
897+
const comment = await fs.readFile(md, "utf8");
898+
has(comment, "<summary><b>Kept</b></summary>");
899+
const marked = (/** @type {string} */ subject) =>
900+
comment.split("<details").find(d => d.includes(`<b>${subject}</b>`)) ?? "";
901+
lacks(marked("Kept"), "✨");
902+
lacks(marked("Kept"), "✏️");
903+
has(marked("Edited"), "<summary>✏️ <b>Edited</b></summary>");
904+
has(marked("Edited"), " · edited</sub>");
905+
has(marked("Added"), "<summary>✨ <b>Added</b></summary>");
906+
has(marked("Added"), " · new</sub>");
907+
});

‎scripts/recordMarkdown.js‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -387,20 +387,26 @@ function section(s, parts, full) {
387387
return out.join("\n\n");
388388
}
389389

390+
/** The sign before a commit's subject that marks what the last push did. */
391+
const SIGNS = { new: "✨", edited: "✏️" };
392+
390393
/**
391394
* A commit as a collapsible block: its subject, identity and message drawn;
392-
* without `full`, its forms are left to the page.
395+
* without `full`, its forms are left to the page. A `change` (`new` or
396+
* `edited`), what the last push did to it, puts a sign before the subject
397+
* and the word in the identity line.
393398
* @param {CommitRecord} r
394399
* @param {boolean} full
400+
* @param {string} [change]
395401
*/
396-
export function commitMarkdown(r, full) {
402+
export function commitMarkdown(r, full, change = "") {
397403
const pr = /\(#(\d+)\)\s*$/.exec(r.subject)?.[1] ?? "";
398404
const subject = r.subject.replace(/\s*\(#\d+\)\s*$/, "");
399405
const joined = (/** @type {Section} */ s) =>
400406
[...s.text, ...s.block.map(l => l.trim())].join(" ").trim();
401407
const out = [
402-
`<details open><summary><b>${inlineHtml(subject)}</b></summary>`,
403-
`<sub>${esc(r.sha)} · ${inline(byline(r))}${r.date ? ` · ${esc(r.date)}` : ""}${pr ? ` · #${pr}` : ""}</sub>`,
408+
`<details open><summary>${change ? `${SIGNS[/** @type {keyof typeof SIGNS} */ (change)] ?? ""} ` : ""}<b>${inlineHtml(subject)}</b></summary>`,
409+
`<sub>${esc(r.sha)} · ${inline(byline(r))}${r.date ? ` · ${esc(r.date)}` : ""}${pr ? ` · #${pr}` : ""}${change ? ` · ${esc(change)}` : ""}</sub>`,
404410
...sectionGroups(r.sections.filter(s => !BELOW.has(s.name))).map(g =>
405411
section(g.section, g.parts, full),
406412
),
@@ -425,13 +431,20 @@ export function commitMarkdown(r, full) {
425431
* characters are drawn without their forms, and if that is not enough, the
426432
* last commits are left to the page. The heading names the commit drawn up
427433
* to (`head`, which GitHub links) and when (`updated`), since the comment is
428-
* edited in place on each push.
434+
* edited in place on each push; the commits the last push added or edited
435+
* (`changes`) are marked.
429436
* @param {Group[]} groups
430-
* @param {{ url?: string, budget?: number, head?: string, updated?: string }} [options]
437+
* @param {{ url?: string, budget?: number, head?: string, updated?: string, changes?: Map<string, string> }} [options]
431438
*/
432439
export function commentMarkdown(
433440
groups,
434-
{ url = "", budget = BUDGET, head: tip = "", updated = "" } = {},
441+
{
442+
url = "",
443+
budget = BUDGET,
444+
head: tip = "",
445+
updated = "",
446+
changes = new Map(),
447+
} = {},
435448
) {
436449
const records = groups.flatMap(g => g.records);
437450
const n = records.length;
@@ -443,14 +456,15 @@ export function commentMarkdown(
443456
]
444457
.filter(Boolean)
445458
.join(" · ")}`;
446-
const drawn = records.map(r => commitMarkdown(r, true));
459+
const change = (/** @type {CommitRecord} */ r) => changes.get(r.sha) ?? "";
460+
const drawn = records.map(r => commitMarkdown(r, true, change(r)));
447461
const size = () => drawn.reduce((t, d) => t + d.length + 2, head.length);
448462
const order = drawn
449463
.map((d, k) => ({ k, length: d.length }))
450464
.sort((x, y) => y.length - x.length);
451465
for (const { k } of order) {
452466
if (size() <= budget) break;
453-
drawn[k] = commitMarkdown(records[k], false);
467+
drawn[k] = commitMarkdown(records[k], false, change(records[k]));
454468
}
455469
let left = 0;
456470
while (drawn.length && size() > budget) {

‎scripts/recordMarkdown.test.js‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,29 @@ ${SIGNED}
237237
has(tiny, "more commit");
238238
});
239239

240+
test("the commits the last push added or edited carry a dot and the word", () => {
241+
const message = (/** @type {string} */ subject) =>
242+
`${subject}\n\n${SIGNED}\n`;
243+
const md = comment([message("Kept"), message("Edited"), message("Added")], {
244+
changes: new Map([
245+
["aaaaaaaa1", "edited"],
246+
["aaaaaaaa2", "new"],
247+
]),
248+
});
249+
has(
250+
md,
251+
"<summary><b>Kept</b></summary>\n\n<sub>aaaaaaaa0 · A Person · Oct 22, 2026</sub>",
252+
);
253+
has(
254+
md,
255+
"<summary>✏️ <b>Edited</b></summary>\n\n<sub>aaaaaaaa1 · A Person · Oct 22, 2026 · edited</sub>",
256+
);
257+
has(
258+
md,
259+
"<summary>✨ <b>Added</b></summary>\n\n<sub>aaaaaaaa2 · A Person · Oct 22, 2026 · new</sub>",
260+
);
261+
});
262+
240263
test("an assistant co-author is drawn by its short name, others as written", () => {
241264
const md = comment([
242265
`Fix it\n\nCo-Authored-By: Claude Sonnet 5.5 <NoReply@Anthropic.com>\nCo-Authored-By: Claude Person <claude@example.com>\nCo-Authored-By: No Email\n${SIGNED}\n`,

0 commit comments

Comments
 (0)