Skip to content

Commit 186aff6

Browse files
cknittclaude
andcommitted
Read the semantic diff's changelog from changes/ fragments
The `changes/<name>.<category>.md` fragment is the single source of truth for a change's changelog category and entry. Records drop the `Changelog` trailer and the `Changelog entry` section, and the review page reads the fragments from the diff: card pills and entries, the summary column, the draft, and checks for invalid fragments and `CHANGELOG.md` edits. Area: scripts docs tests Output: unchanged Tests: ~scripts/commitRecords.test.js Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S1QKRDTRtNPeF6NB68yuGc Signed-off-by: Christoph Knittel <ck@cca.io>
1 parent 735a485 commit 186aff6

4 files changed

Lines changed: 154 additions & 77 deletions

File tree

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

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,10 @@ or the snapshot file in the diff>
3232
3333
Breaking: <what existing code or tooling stops working, and the migration>
3434
35-
Changelog entry: <the exact bullet of the changes/<name>.<category>.md fragment>
36-
3735
Review: <a question a reviewer raised or will raise, and its answer; repeat>
3836
3937
Area: syntax printer frontend typechecker lambda codegen runtime rewatch
4038
analysis reanalyze gentype tools playground scripts ci docs tests
41-
Changelog: breaking | feature | fix | docs | polish | internal | none
4239
Output: unchanged | changed <which programs>, <evidence>
4340
Formatting: unchanged | changed <which source shapes>
4441
Formats: none | <bumped magic numbers: ast cmi cmt cmj>
@@ -61,7 +58,11 @@ Signed-off-by: <Name> <email>
6158
- **The final block is git trailers**: `Key: value` lines, continuation lines
6259
indented by one space, nothing after them. `git interpret-trailers --parse`
6360
must read every key. `Signed-off-by` (DCO) is required on every commit.
64-
- **Required keys**: `Area`, `Changelog`, `Output`, `Tests`. `Formatting`, `Formats`,
61+
- **No changelog in the record**: the `changes/<name>.<category>.md`
62+
fragment the commit adds is the single source of truth for its changelog
63+
category and entry (see `changes/README.md`). The record repeats neither;
64+
the review page reads the fragment from the diff.
65+
- **Required keys**: `Area`, `Output`, `Tests`. `Formatting`, `Formats`,
6566
`PPX` and `Editor` are required whenever the change touches the syntax
6667
library, the parsetree, the typed tree or Lambda. Omit the others when they
6768
do not apply.
@@ -79,7 +80,6 @@ Signed-off-by: <Name> <email>
7980
| Field | What the record states |
8081
| --- | --- |
8182
| `Area` | The layers the change touches. They decide who reviews it and which suites apply; a parsetree or typed-tree change also reaches editor analysis. |
82-
| `Changelog` + `Changelog entry` | Whether the change is user-facing, and its category: `breaking` when existing code or tooling must adapt, `internal` when nothing user-visible changes. The entry is one short line ending in the PR link, identical to the fragment's bullet. |
8383
| `Output` + `Before`/`After (js)` | The generated JavaScript for the example before and after, and which existing programs compile differently. `unchanged` holds when no committed generated JS changes, or when a rebuild of the test suites is byte-identical. |
8484
| `Formatting` + `Before`/`After (rescript)` | Whether `rescript format` rewrites existing code, and whether formatted output parses back to the same tree with its comments. |
8585
| `Formats` | The magic numbers bumped in `compiler/ext/config.ml`. Any change to the marshaled parsetree, typed tree (`.cmi`, `.cmt`) or `.cmj` layout, constructor order included, bumps the matching number. |
@@ -107,10 +107,13 @@ node scripts/commitRecords.js --out review.html --pr 1234 --title "<PR title>" <
107107

108108
- A revision renders one card. A range renders a summary row, a changelog
109109
draft grouped by category, its commits as cards, and the files more than
110-
one commit (or more than one range) changes.
111-
- Each card checks the record against its diff: a changelog category with no
112-
new `changes/` fragment (or a `Changelog entry` that differs from the
113-
fragment's bullet), modified generated `.mjs`, `.cjs` and `.res.js` files under
110+
one commit (or more than one range) changes. The changelog category, the
111+
entries and the draft come from the `changes/` fragments in the diff: a
112+
card shows the fragments its commit adds or changes, and a range's draft
113+
shows the fragments the range leaves, in their last version.
114+
- Each card checks the record against its diff: a `changes/` fragment that
115+
`yarn changelog:check` rejects (such as one still carrying the placeholder
116+
PR link), an edit to `CHANGELOG.md`, modified generated `.mjs`, `.cjs` and `.res.js` files under
114117
`Output: unchanged` (new ones from new tests are counted, not flagged), a
115118
magic number bumped in `compiler/ext/config.ml` that
116119
`Formats` does not name, a parsetree change with no ast-mapping fixture, a
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Read the semantic diff page's changelog from the `changes/` fragments, the single source of truth, instead of commit message trailers. https://github.com/rescript-lang/rescript/pull/XXXX

‎scripts/commitRecords.js‎

Lines changed: 92 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
/* Renders commit records as a review page. A record is a commit message (or a
66
* note on refs/notes/records, which takes precedence) in the format of
77
* .claude/skills/records/SKILL.md: a subject, prose sections, code sections
8-
* such as "Before (js):" and git trailers.
8+
* such as "Before (js):" and git trailers. The changelog comes from the
9+
* changes/<description>.<category>.md fragments the commits add, not from the
10+
* record.
911
*
1012
* node scripts/commitRecords.js --out review.html <rev>...
1113
* node scripts/commitRecords.js --out review.html <base>..<branch>...
@@ -15,6 +17,7 @@
1517

1618
import { execFileSync } from "node:child_process";
1719
import { writeFileSync } from "node:fs";
20+
import { parseFragment } from "./changelog.js";
1821

1922
const REPO_URL = "https://github.com/rescript-lang/rescript";
2023

@@ -156,10 +159,12 @@ function codeLines(lines, lang, other, mark) {
156159
/**
157160
* @typedef {{ name: string, lang: string, text: string[], block: string[] }} Section
158161
* @typedef {{ status: string, path: string, added: number, removed: number }} FileChange
162+
* @typedef {{ path: string, category: string, text: string, error: string }} Fragment
159163
* @typedef {{
160164
* sha: string, author: string, date: string, subject: string,
161165
* sections: Section[], trailers: Map<string, string>, message: string,
162-
* coauthors: string[], files: FileChange[], patch: string, noted: boolean
166+
* coauthors: string[], files: FileChange[], fragments: Fragment[],
167+
* patch: string, noted: boolean
163168
* }} CommitRecord
164169
*/
165170

@@ -188,6 +193,49 @@ function pushProse(sections) {
188193
return s;
189194
}
190195

196+
/** @param {string} path */
197+
const isFragment = path =>
198+
/^changes\/[^/]+\.md$/.test(path) && path !== "changes/README.md";
199+
200+
/**
201+
* The changelog fragments a commit adds or changes, as they stand in its tree.
202+
* A fragment that fails validation (such as one with the placeholder PR link)
203+
* keeps the category from its name and records the error.
204+
* @param {string} rev
205+
* @param {FileChange[]} files
206+
* @returns {Fragment[]}
207+
*/
208+
function fragmentsOf(rev, files) {
209+
return files
210+
.filter(f => f.status !== "D" && isFragment(f.path))
211+
.map(f => {
212+
const name = f.path.slice("changes/".length);
213+
const content = git(["show", `${rev}:${f.path}`]);
214+
try {
215+
const { category, text } = parseFragment(name, content);
216+
return { path: f.path, category, text, error: "" };
217+
} catch (e) {
218+
return {
219+
path: f.path,
220+
category: /\.([a-z]+)\.md$/.exec(name)?.[1] ?? "?",
221+
text: content.trim(),
222+
error: e instanceof Error ? e.message : String(e),
223+
};
224+
}
225+
});
226+
}
227+
228+
/**
229+
* The bullets of a fragment, without their "- " and with continuation lines
230+
* joined.
231+
* @param {string} text
232+
*/
233+
const bullets = text =>
234+
text
235+
.split(/\n(?=- )/)
236+
.map(b => b.replace(/^-\s+/, "").replace(/\n\s+/g, " "))
237+
.filter(Boolean);
238+
191239
/** @param {string} rev */
192240
function readRecord(rev) {
193241
let text = "";
@@ -296,14 +344,13 @@ function readRecord(rev) {
296344
),
297345
],
298346
files: [...files.values()],
347+
fragments: fragmentsOf(rev, [...files.values()]),
299348
patch: git([
300349
"show",
301350
"--format=",
302351
"-U0",
303352
rev,
304353
"--",
305-
"CHANGELOG.md",
306-
"changes",
307354
"compiler/ext/config.ml",
308355
]),
309356
};
@@ -362,39 +409,17 @@ function checks(r) {
362409
/** @type {[boolean, string][]} */
363410
const out = [];
364411
const has = (/** @type {RegExp} */ re) => r.files.some(f => re.test(f.path));
365-
const category = r.trailers.get("Changelog");
366-
const changelogTouched = has(/^CHANGELOG\.md$|^changes\/.*\.md$/);
367-
if (category !== undefined) {
368-
if (category === "none")
369-
out.push([
370-
!changelogTouched,
371-
changelogTouched
372-
? "Changelog: none, but the diff changes the changelog"
373-
: "No changelog entry, as recorded",
374-
]);
375-
else if (!changelogTouched)
376-
out.push([
377-
false,
378-
`Changelog: ${category}, but the diff adds no changelog entry`,
379-
]);
380-
else {
381-
const entry = r.sections.find(s => s.name === "Changelog entry");
382-
const added = r.patch
383-
.split("\n")
384-
.filter(l => l.startsWith("+") && !l.startsWith("+++"))
385-
.join("\n");
386-
const text = entry
387-
? [...entry.text, ...entry.block].join(" ").trim()
388-
: "";
389-
if (text)
390-
out.push(
391-
added.replace(/\s+/g, " ").includes(text.replace(/\s+/g, " "))
392-
? [true, "Changelog entry matches the line the diff adds"]
393-
: [false, "Changelog entry differs from the line the diff adds"],
394-
);
395-
else out.push([true, `Changelog: ${category}; the diff adds an entry`]);
396-
}
397-
} else out.push([false, "No Changelog trailer"]);
412+
for (const f of r.fragments)
413+
out.push(
414+
f.error
415+
? [false, `${f.path}: ${f.error.replace(/^[^:]*: /, "")}`]
416+
: [true, `Changelog fragment ${f.path}`],
417+
);
418+
if (has(/^CHANGELOG\.md$/))
419+
out.push([
420+
false,
421+
"Edits CHANGELOG.md; a changes/ fragment carries the entry outside release PRs",
422+
]);
398423

399424
const testsValue = r.trailers.get("Tests");
400425
const testFiles = r.files.filter(f =>
@@ -478,9 +503,7 @@ function checks(r) {
478503
/** @type {Record<string, [string, string]>} */
479504
const CATEGORIES = {
480505
breaking: ["💥", "Breaking change"],
481-
spec: ["👓", "Spec compliance"],
482506
feature: ["🚀", "New feature"],
483-
bugfix: ["🐛", "Bug fix"],
484507
fix: ["🐛", "Bug fix"],
485508
docs: ["📝", "Documentation"],
486509
polish: ["💅", "Polish"],
@@ -595,7 +618,7 @@ function renderSections(sections) {
595618
const out = [];
596619
for (let i = 0; i < sections.length; i++) {
597620
const s = sections[i];
598-
if (["Breaking", "Changelog entry", "Review"].includes(s.name)) continue;
621+
if (["Breaking", "Review"].includes(s.name)) continue;
599622
const next = sections[i + 1];
600623
if (
601624
s.name === "Before" &&
@@ -668,22 +691,22 @@ const langName = lang =>
668691

669692
/** @param {CommitRecord} r */
670693
function card(r) {
671-
const category = r.trailers.get("Changelog") ?? "";
694+
const categories = [...new Set(r.fragments.map(f => f.category))];
672695
const pr = (
673696
r.trailers.get("PR") ??
674697
/\(#(\d+)\)\s*$/.exec(r.subject)?.[0] ??
675698
""
676699
).replace(/\D/g, "");
677700
const subject = r.subject.replace(/\s*\(#\d+\)\s*$/, "");
678701
const out = [
679-
`<article class="card${category === "breaking" ? " breaking" : ""}" id="c-${r.sha}">`,
702+
`<article class="card${categories.includes("breaking") ? " breaking" : ""}" id="c-${r.sha}">`,
680703
];
681704
out.push(
682705
`<header><div class="meta"><code>${r.sha}</code> · ${esc(r.author)} · ${esc(r.date)}${
683706
pr ? ` · <a href="${REPO_URL}/pull/${pr}">#${pr} discussion ↗</a>` : ""
684707
}${r.noted ? ' · <span title="record from refs/notes/records">note</span>' : ""}</div>` +
685708
`<h3>${inline(subject)}</h3>` +
686-
`<div class="chips">${category ? changelogPill(category) : ""}${words(
709+
`<div class="chips">${categories.map(changelogPill).join("")}${words(
687710
r,
688711
"Area",
689712
)
@@ -696,10 +719,9 @@ function card(r) {
696719
`<div class="banner"><strong>Breaking</strong> ${inline([...breaking.text, ...breaking.block].join(" "))}</div>`,
697720
);
698721
out.push(renderSections(r.sections));
699-
const entry = r.sections.find(s => s.name === "Changelog entry");
700-
if (entry)
722+
for (const f of r.fragments)
701723
out.push(
702-
`<div class="entry">${category ? changelogPill(category) : ""}<span>${inline([...entry.text, ...entry.block].join(" "))}</span></div>`,
724+
`<div class="entry">${changelogPill(f.category)}<span>${bullets(f.text).map(inline).join("<br>")}</span></div>`,
703725
);
704726
const reviews = r.sections.filter(s => s.name === "Review");
705727
if (reviews.length)
@@ -791,16 +813,30 @@ function group(arg) {
791813
};
792814
}
793815

816+
/**
817+
* The fragments a range leaves in changes/: the last version of each one its
818+
* commits add or change, minus those a later commit deletes.
819+
* @param {Group} g
820+
*/
821+
function rangeFragments(g) {
822+
/** @type {Map<string, Fragment>} */
823+
const byPath = new Map();
824+
for (const r of g.records) {
825+
for (const f of r.files) if (f.status === "D") byPath.delete(f.path);
826+
for (const f of r.fragments) byPath.set(f.path, f);
827+
}
828+
return [...byPath.values()];
829+
}
830+
794831
/** @param {Group[]} groups */
795832
function summary(groups) {
796833
const ranges = groups.filter(g => g.range);
797834
if (!ranges.length) return "";
798835
const rows = ranges.map(g => {
799836
const cats = new Map();
800-
for (const r of g.records) {
801-
const c = r.trailers.get("Changelog") ?? "?";
802-
cats.set(c, (cats.get(c) ?? 0) + 1);
803-
}
837+
for (const f of rangeFragments(g))
838+
cats.set(f.category, (cats.get(f.category) ?? 0) + 1);
839+
if (!cats.size) cats.set("none", 1);
804840
const areas = [...new Set(g.records.flatMap(r => words(r, "Area")))];
805841
const js = g.records.filter(r =>
806842
/^changed/.test(r.trailers.get("Output") ?? ""),
@@ -840,15 +876,11 @@ function summary(groups) {
840876
/** @type {Map<string, string[]>} */
841877
const draft = new Map();
842878
for (const g of ranges)
843-
for (const r of g.records) {
844-
const c = r.trailers.get("Changelog");
845-
const entry = r.sections.find(s => s.name === "Changelog entry");
846-
if (c && c !== "none" && entry)
847-
draft.set(c, [
848-
...(draft.get(c) ?? []),
849-
[...entry.text, ...entry.block].join(" ").replace(/^-\s+/, ""),
850-
]);
851-
}
879+
for (const f of rangeFragments(g))
880+
draft.set(f.category, [
881+
...(draft.get(f.category) ?? []),
882+
...bullets(f.text),
883+
]);
852884
const order = Object.keys(CATEGORIES);
853885
return (
854886
`<section><h2>Summary</h2><div class="table-wrap"><table><thead><tr><th>Range</th><th>Commits</th><th>Changelog</th><th>Areas</th><th>JS output changes</th><th>Formats</th><th>Failed checks</th></tr></thead><tbody>${rows.join("")}</tbody></table></div>` +
@@ -906,7 +938,7 @@ code { font:12.5px/1.5 var(--mono); background:var(--code-bg); padding:1px 4px;
906938
.chips { display:flex; flex-wrap:wrap; gap:6px; align-items:center }
907939
.chip { font:500 12px/1 var(--body); border:1px solid var(--rule); border-radius:99px; padding:5px 9px; color:var(--muted) }
908940
.pill { font:600 12px/1 var(--body); padding:6px 10px; border-radius:99px; white-space:nowrap; background:var(--same-bg); color:var(--same) }
909-
.pill.cat-breaking { background:var(--accent); color:#fff } .pill.cat-bugfix, .pill.cat-fix { background:var(--warn-bg); color:var(--warn) }
941+
.pill.cat-breaking { background:var(--accent); color:#fff } .pill.cat-fix { background:var(--warn-bg); color:var(--warn) }
910942
.pill.cat-feature { background:var(--ok-bg); color:var(--ok) } .pill.cat-polish { background:var(--diff-bg); color:var(--diff) }
911943
.banner { background:var(--accent-soft); border-left:4px solid var(--accent); padding:10px 14px; border-radius:6px; margin:4px 0 }
912944
.banner strong { color:var(--accent); margin-right:6px; text-transform:uppercase; font-size:12px; letter-spacing:.06em }

0 commit comments

Comments
 (0)