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>...
1517
1618import { execFileSync } from "node:child_process" ;
1719import { writeFileSync } from "node:fs" ;
20+ import { parseFragment } from "./changelog.js" ;
1821
1922const 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+ / ^ c h a n g e s \/ [ ^ / ] + \. m d $ / . 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 ] + ) \. m d $ / . 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 */
192240function 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 ( / ^ C H A N G E L O G \. m d $ | ^ c h a n g e s \/ .* \. m d $ / ) ;
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 ( / ^ C H A N G E L O G \. m d $ / ) )
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]> } */
479504const 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 */
670693function 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 */
795832function 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 / ^ c h a n g e d / . 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