diff --git a/.github/scripts/fork-seam-check.cjs b/.github/scripts/fork-seam-check.cjs index 82253ad3af038..09de37461f842 100644 --- a/.github/scripts/fork-seam-check.cjs +++ b/.github/scripts/fork-seam-check.cjs @@ -741,11 +741,14 @@ function findListedNotFork( * `atUpstream` (`name`), as fork-follow counts them: a count set too high lets a later change swap * an upstream line for a fork line unseen; too low, or dropped, stops fork-follow. */ -function findLostNotUpstream(files, ownLost, { atUpstream, atHead, name }) { +function findLostNotUpstream(files, ownLost, { atUpstream, atHead, name, wasLost }) { const ceilings = []; for (const file of files) { const own = Object.hasOwn(ownLost, file) ? ownLost[file] : undefined; - const where = `${own === undefined ? "dropped from" : "set in"} "lost" in this change's ${CONFIG}`; + // `wasLost`: the files main's or the merge-base's list has in "lost" (unknown: all of them). + const verb = + own !== undefined ? "set in" : wasLost?.has(file) === false ? "not in" : "dropped from"; + const where = `${verb} "lost" in this change's ${CONFIG}`; const head = atHead(file); if (head === undefined) { if (own !== undefined) { @@ -1077,6 +1080,32 @@ function findAnnouncementWarnings(ownFiles, baseFiles, today) { return warnings; } +/** + * In-date announcements in main's list that this change's own list drops (neither announced nor in + * "added"), counting only copies the merge-base's list had (main's when unreadable). The caller + * skips list-only changes, which may withdraw one; expired ones may go with any change. + */ +function findDroppedAnnouncements(mainFiles, baseFiles, ownFiles, today) { + const reasons = []; + const counts = (files, file) => + Object.hasOwn(files, file) ? lineCounts(seamLines(files[file]).join("\n")) : new Map(); + for (const [file, seam] of Object.entries(mainFiles)) { + if (seam.announced === undefined) continue; + const { since } = seam.announced; + if (isExpired(since, today) || isAhead(since, today)) continue; + const before = baseFiles === undefined ? undefined : counts(baseFiles, file); + const own = counts(ownFiles, file); + for (const [line, count] of lineCounts(seam.announced.added.join("\n"))) { + const kept = Math.min(count, before === undefined ? count : (before.get(line) ?? 0)); + if ((own.get(line) ?? 0) >= kept) continue; + reasons.push( + `${file}: this change's ${CONFIG} drops the announced line \`${line}\` (main's list announces it since ${since}, in date): keep it under "announced", or move it to "added" in the change that adds it (a list from an older copy drops another change's announcement unseen). To withdraw it on purpose, drop it in a list-only pull request.`, + ); + } + } + return reasons; +} + const KINDS = ["files", "pending", "forkFiles", "lost"]; const SEAM_KEYS = ["why", "added", "announced"]; const ANNOUNCED_KEYS = ["since", "added"]; @@ -1210,6 +1239,14 @@ function parseConfig(text) { throw new Error(`${CONFIG}: "forkFiles": not a repository path pattern: ${pattern}`); } } + // Last: the structure above is JSON.parse's reading, which keeps only the last of two equal keys + // (two pull requests that each add an entry for one file): the other is shown but never applies. + const duplicate = findDuplicateKey(text); + if (duplicate !== undefined) { + throw new Error( + `${CONFIG}: duplicate key ${JSON.stringify(duplicate)} (JSON keeps only the last, so the other is shown but never applies): merge them into one entry`, + ); + } return { files, pending, forkFiles: config.forkFiles ?? [], lost }; } @@ -1255,11 +1292,11 @@ function ownListProblem(text) { if (text === undefined) return `${own}: this change deletes it.`; try { parseConfig(text); - const duplicate = findDuplicateKey(text); - if (duplicate === undefined) return undefined; - return printable(`${own} is malformed: duplicate key ${JSON.stringify(duplicate)}`); + return undefined; } catch (error) { - return printable(`${own} is malformed: ${error instanceof Error ? error.message : error}`); + const message = error instanceof Error ? error.message : String(error); + const reason = message.startsWith(`${CONFIG}: `) ? message.slice(CONFIG.length + 2) : message; + return printable(`${own} is malformed: ${reason}`); } } @@ -1380,11 +1417,22 @@ function isAncestor(a, b) { } } -/** Reads `:.github/fork-seams.json`; throws when that commit has none. */ +/** Reads `:.github/fork-seams.json`; throws when that commit has none or it is malformed. */ function readConfigAt(rev) { const text = textAt(rev, CONFIG); if (text === undefined) throw new Error(`${rev} has no ${CONFIG}`); - return parseConfig(text); + try { + return parseConfig(text); + } catch (error) { + // Names the commit: on a pull request main's list, the merge-base's and its own are all read. + const message = error instanceof Error ? error.message : String(error); + throw new Error( + message.startsWith(`${CONFIG}: `) + ? `${CONFIG} at ${rev.slice(0, 12)}: ${message.slice(CONFIG.length + 2)}` + : `${CONFIG} at ${rev.slice(0, 12)}: ${message}`, + { cause: error }, + ); + } } function parseArgs(argv) { @@ -1525,21 +1573,36 @@ function main(argv) { lowered, }); // Counts the own list changes (seam "added", "pending", "lost", "forkFiles", a move to "files") - // main's list cannot check: only upstream can. Every way the count cannot run refuses (fail + // and the pending files' text changes main's list cannot check: only upstream can. Every way the count cannot run refuses (fail // closed); fork-tests' run on the merge commit passes --no-upstream, as fork-checks' run counts. const promoted = upstream ? [] : promotedFiles(config, ownFiles, ownPending); const edits = upstream || ownConfig === undefined ? { files: [], pending: [], lost: [], forkFiles: false } : { files: listEditedFiles(baseFiles, ownFiles), ...listEditedCounts(baseList, ownConfig) }; - const toCount = [...new Set([...promoted, ...edits.files, ...edits.pending])].sort(); - const lostToCount = [...edits.lost].sort(); + // The "pending" files whose text this change edits. Main's tree cannot tell which line it drops + // is upstream's: a swapped upstream line (one out, one in) keeps every count it sees, and + // fork-follow then refuses main. Counted from upstream as fork-follow counts them: fork + // lines against the own ceiling, lost lines against the own "lost" entry. + const changedFiles = new Set(changed); + const pendingEdited = + upstream || ownConfig === undefined + ? [] + : Object.keys(config.pending).filter((file) => { + if (!changedFiles.has(file)) return false; + const [before, after] = [atBase(file), atHead(file)]; + return before !== undefined && after !== undefined && before !== after; + }); + const toCount = [ + ...new Set([...promoted, ...edits.files, ...edits.pending, ...pendingEdited]), + ].sort(); + const lostToCount = [...new Set([...edits.lost, ...pendingEdited])].sort(); const countedCeilings = []; const cannotCount = []; if (toCount.length > 0 || lostToCount.length > 0 || edits.forkFiles) { const seamEdited = edits.files.filter((file) => !promoted.includes(file)); const ceilingEdited = edits.pending.filter((file) => !promoted.includes(file)); - const does = [ + const listDoes = [ ...(promoted.length > 0 ? [`moves ${promoted.join(", ")} from "pending" to "files"`] : seamEdited.length > 0 @@ -1548,11 +1611,19 @@ function main(argv) { ...(ceilingEdited.length > 0 ? [`changes the "pending" ceiling of ${ceilingEdited.join(", ")}`] : []), - ...(lostToCount.length > 0 ? [`changes the "lost" entry of ${lostToCount.join(", ")}`] : []), + ...(edits.lost.length > 0 ? [`changes the "lost" entry of ${edits.lost.join(", ")}`] : []), ...(edits.forkFiles ? ['changes "forkFiles"'] : []), ]; + const does = [ + ...(listDoes.length > 0 ? [`${listDoes.join(", and ")} in its ${CONFIG}`] : []), + ...(pendingEdited.length > 0 + ? [ + `changes the text of the "pending" file${pendingEdited.length === 1 ? "" : "s"} ${pendingEdited.join(", ")} (a pull request's run cannot tell an upstream line from a fork line there)`, + ] + : []), + ]; const subjects = [...new Set([...toCount, ...lostToCount])].sort(); - const what = `${subjects.length > 0 ? subjects.join(", ") : '"forkFiles"'}: this change ${does.join(", and ")} in its ${CONFIG}`; + const what = `${subjects.length > 0 ? subjects.join(", ") : '"forkFiles"'}: this change ${does.join(", and ")}`; const named = parsed.noUpstream ? {} : parsed.upstreamUrl === undefined @@ -1594,7 +1665,15 @@ function main(argv) { ...Object.keys(baseList?.pending ?? {}), ]), }), - ...findLostNotUpstream(lostToCount, ownLost, { atUpstream, atHead, name }), + ...findLostNotUpstream(lostToCount, ownLost, { + atUpstream, + atHead, + name, + wasLost: + baseList === undefined + ? undefined + : new Set([...Object.keys(config.lost), ...Object.keys(baseList.lost)]), + }), ...(edits.forkFiles ? findOwnHiddenFiles( git(["ls-tree", "-r", "-z", "--name-only", found.rev]).split("\0").filter(Boolean), @@ -1645,6 +1724,12 @@ function main(argv) { : []), ]; const expired = upstream ? findExpiredAnnouncements(config.files, commitDay(head)) : []; + // A change that edits its list and something else keeps main's in-date announcements. + const listOnly = changed.every((file) => file === CONFIG); + const dropped = + editsList && ownFiles !== undefined && !listOnly + ? findDroppedAnnouncements(config.files, baseFiles, ownFiles, today) + : []; // Upstream added an announced line: pushed, main's tree fails the stale-list test that // fork-checks runs for every pull request (the fix's too). Stop before the push. const landed = upstream @@ -1681,7 +1766,7 @@ function main(argv) { `Fix the list in this change: merged, it is main's list, and a malformed one stops every later pull request and fork-follow run.`, ); } - const refused = [...reasons, ...late, ...rises, ...ceilings, ...expired, ...landed]; + const refused = [...reasons, ...late, ...rises, ...ceilings, ...expired, ...landed, ...dropped]; if (cannotCount.length > 0) { // Not a seam breach: the count could not run, so nothing in this change is known wrong yet. console.error( @@ -1757,6 +1842,7 @@ module.exports = { GENERATED, compileForkPattern, findAnnouncementWarnings, + findDroppedAnnouncements, findDuplicateKey, findExpiredAnnouncements, findHiddenUpstreamFiles, diff --git a/.github/scripts/fork-seam-check.test.cjs b/.github/scripts/fork-seam-check.test.cjs index 6875bd549c7a8..da0ce16965906 100644 --- a/.github/scripts/fork-seam-check.test.cjs +++ b/.github/scripts/fork-seam-check.test.cjs @@ -1814,7 +1814,10 @@ test("a pull request's own list with a duplicate key is refused", () => { // Equal once decoded. [`{"files": {}, "pending": {"p.ts": 1, "\\u0070.ts": 1}}`, "p.ts"], ]) { - assert.equal(ownListProblem(text), `${OWN} is malformed: duplicate key ${JSON.stringify(key)}`); + assert.ok( + ownListProblem(text).startsWith(`${OWN} is malformed: duplicate key ${JSON.stringify(key)} `), + text, + ); } // The same key in different objects, and keys inside strings, are not duplicates. for (const text of [ @@ -3753,9 +3756,16 @@ test("a seam count the pull request raises without the line, or lowers while the pr("step2", withAdded("a.ts", [...SEAM["a.ts"].added, "forkMore();"]), { "a.ts": `${SEAMED["a.ts"]}forkMore();\n`, }), - pr("dropped", withAdded("a.ts", ["import { fork } from './fork';"]), { - "a.ts": SEAMED["a.ts"].replace(" ...fork,\n", ""), - }), + // It keeps main's in-date announcement (a change that drops one is refused). + pr( + "dropped", + { + files: { + "a.ts": { why: "test", added: ["import { fork } from './fork';"], announced }, + }, + }, + { "a.ts": SEAMED["a.ts"].replace(" ...fork,\n", "") }, + ), ]; git("checkout", "-q", "-f", "-B", "spare", main); const spareMain = commit( @@ -4147,3 +4157,127 @@ test("fork-checks counts from upstream and fork-tests' shallow run passes --no-u assert.equal(tests.length, 1); assert.match(tests[0], /fork-seam-check\.cjs --no-upstream HEAD\^1 HEAD$/); }); + +// A pull request's run judged a "pending" file from the merge-base, where swapping an upstream +// line for a fork line keeps every count it sees (one line out, one in), so it passed while +// fork-follow's count from upstream refused main. Both forms now count the same lines. +test("a change that swaps an upstream line in a pending file whose counts are reached is refused by both forms", () => { + withRepo(({ git, commit, run, runBare, fromUpstream, publish }) => { + const up = commit({ "p.ts": "a();\nb();\nc();\n" }, "upstream"); + git("checkout", "-q", "-b", "fork"); + // One fork line where upstream's `b();` was: the ceiling and the "lost" counts are reached. + const list = { files: {}, pending: { "p.ts": 1 }, lost: { "p.ts": { lines: 1, gone: 1 } } }; + const main = commit({ ...seams(list), "p.ts": "a();\nforkB();\nc();\n" }, "main"); + publish(up); + assert.equal(fromUpstream(up, main).status, 0); + const swap = commit({ "p.ts": "a();\nforkB();\nforkC();\n" }, "swap upstream's c();"); + const follow = fromUpstream(up, swap); + assert.equal(follow.status, 1, follow.stdout); + assert.match( + follow.stderr, + /p\.ts: 2 upstream lines deleted, moved or re-indented, more than its "lost" lines count of 1/, + ); + assert.match(follow.stderr, /p\.ts: "pending" with 2 fork lines, more than its ceiling of 1/); + const pr = run("--config-ref", main, main, swap); + assert.equal(pr.status, 1, pr.stdout); + assert.match( + pr.stderr, + /- p\.ts: "pending" with a ceiling of 1 in this change's \.github\/fork-seams\.json, but the fork adds 2 lines over upstream \([0-9a-f]{12}\): set its ceiling to 2/, + ); + assert.match( + pr.stderr, + /- p\.ts: set in "lost" in this change's \.github\/fork-seams\.json \({"lines": 1, "gone": 1}\), but the fork loses 2 upstream lines over upstream \([0-9a-f]{12}\) .*: set it to {"lines": 2, "gone": 2}/, + ); + // Runs again: the same answer. + assert.equal(run("--config-ref", main, main, swap).stderr, pr.stderr); + // A change to a fork line only keeps both counts: counted from upstream, it passes both forms. + git("checkout", "-q", "-f", "-B", "reword", main); + const reword = commit({ "p.ts": "a();\nforkB2();\nc();\n" }, "reword the fork line"); + const ok = run("--config-ref", main, main, reword); + assert.equal(ok.status, 0, ok.stderr); + assert.match( + ok.stdout, + /^Note: p\.ts: this change changes the text of the "pending" file p\.ts.*counted from upstream/m, + ); + assert.equal(fromUpstream(up, reword).status, 0); + // With no upstream to count from, the edit is refused, not skipped; fork-tests' run says + // --no-upstream (fork-checks counts). + const bare = runBare("--config-ref", main, main, reword); + assert.equal(bare.status, 1, bare.stdout); + assert.match( + bare.stderr, + /p\.ts: this change changes the text of the "pending" file p\.ts.*cannot be counted/, + ); + assert.equal(run("--no-upstream", "--config-ref", main, main, reword).status, 0); + // A change that leaves the pending file alone fetches nothing. + git("checkout", "-q", "-f", "-B", "other", main); + const other = commit({ "fork-own.ts": "x();\n" }, "a fork file"); + assert.equal(runBare("--config-ref", main, main, other).status, 0); + }); +}); + +// JSON.parse keeps the last of two equal keys, so the other entry is shown but never applies. +// A pull request's own list was refused for one; main's list (merged around that check) and the +// head's list fork-follow reads were not. +test("a list with a duplicate key is refused wherever it is read: main's, the merge-base's or fork-follow's head", () => { + withRepo(({ git, commit, run, fromUpstream }) => { + const up = commit({ ...BASE }, "upstream"); + git("checkout", "-q", "-b", "fork"); + const entry = (added) => JSON.stringify({ why: "w", added }); + const dup = `{"files": {"a.ts": ${entry(["import { fork } from './fork';"])}, "a.ts": ${entry(["...fork,"])}}}\n`; + const main = commit({ [CONFIG]: dup, ...SEAMED }, "main with a duplicate key"); + // A malformed list stops the run (exit 3), as any other does: it never runs on half a list. + const follow = fromUpstream(up, main); + assert.equal(follow.status, 3, follow.stdout); + assert.match( + follow.stderr, + /\.github\/fork-seams\.json at [0-9a-f]{12}: duplicate key "a\.ts"/, + ); + const plain = commit({ "fork-own.ts": "x();\n" }, "a fork file"); + const pr = run("--config-ref", main, main, plain); + assert.equal(pr.status, 3, pr.stdout); + assert.match(pr.stderr, /\.github\/fork-seams\.json at [0-9a-f]{12}: duplicate key "a\.ts"/); + assert.throws(() => parseConfig(dup), /duplicate key "a\.ts"/); + }); +}); + +// A squash merge from a branch made before an announcement dropped its lines, and nothing noticed. A change +// that is not list-only keeps each in-date announcement main's list has (and its merge-base had): +// still announced, or moved to "added". +test("a change that drops another change's in-date announcement is refused, unless list-only or expired", () => { + withRepo(({ git, commit, run }) => { + const day = "2026-11-18T12:00:00Z"; + commit({ ...BASE, "n.ts": UP }, "upstream", day); + git("checkout", "-q", "-b", "fork"); + const main = commit({ ...seams(ANNOUNCED()), ...SEAMED }, "step 1", day); + const withList = (files, list = { files: SEAM }) => + commit({ ...files, ...seams(list) }, "change", day); + // A code change whose list came from an older copy: refused, naming the line. + git("checkout", "-q", "-f", "-B", "drop", main); + const drop = withList({ "fork-own.ts": "x();\n" }); + const refused = run("--config-ref", main, main, drop); + assert.equal(refused.status, 1, refused.stdout); + assert.match( + refused.stderr, + /- n\.ts: this change's \.github\/fork-seams\.json drops the announced line `forkNew\(\);` \(main's list announces it since 2026-11-18, in date\)/, + ); + assert.equal(run("--config-ref", main, main, drop).stderr, refused.stderr); + // The same drop in a list-only change says so: it passes. + git("checkout", "-q", "-f", "-B", "withdraw", main); + assert.equal(run("--config-ref", main, main, withList({})).status, 0); + // Kept, or still announced with another list edit: passes. + git("checkout", "-q", "-f", "-B", "keep", main); + const keep = withList({ "fork-own.ts": "x();\n" }, { ...ANNOUNCED(), pending: {} }); + assert.equal(run("--config-ref", main, main, keep).status, 0); + // Expired by main's commit date: may go with any change. + git("checkout", "-q", "-f", "-B", "late", main); + const lateMain = commit({ "late.txt": "x\n" }, "main, later", "2026-12-10T12:00:00Z"); + const late = withList({ "fork-own.ts": "x();\n" }); + assert.equal(run("--config-ref", lateMain, lateMain, late).status, 0); + // A branch from before the announcement does not have it yet: not this change's to keep. + git("checkout", "-q", "-f", "-B", "behind", main + "~1"); + const behind = withList({ "fork-own.ts": "x();\n" }, { files: SEAM, pending: {} }); + const result = run("--config-ref", main, main + "~1", behind); + assert.doesNotMatch(result.stderr, /drops the announced line/); + }); +}); diff --git a/docs/fork/updates.md b/docs/fork/updates.md index bb93b469df943..e536403450a12 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -57,7 +57,10 @@ watches; it changes nothing on the machine, and `0` turns it off. an unknown or duplicate key, a `files` or `pending` key that is not a plain repository path, a `lost` entry not in the form below, a line in both `added` and `announced`, or none) is refused (a repeated `"//"` comment key is a duplicate too: give each comment its own `//name` key), since once merged it would stop every - later run. `pending` maps upstream files + later run. Every list the checker reads (main's, the merge-base's, fork-follow's head) is parsed + the same way: one with a duplicate key stops the run (exit 3), naming the commit and the key, as + JSON keeps only the last of two equal keys and the other entry would be shown but never apply. + `pending` maps upstream files whose fork lines predate the rule to a ceiling: the most fork lines each may hold, counted from upstream (fork-follow fails above it and below it). So a pull request that moves fork lines out of a pending file lowers its ceiling in its own list, in the same change: its run refuses a @@ -107,7 +110,11 @@ watches; it changes nothing on the machine, and `0` turns it off. (a ceiling is 1 or more, and a `lost` entry needs its file in `files` or `pending`) is moved to `files` with `"added": []` in that commit, which holds it tighter: no fork line may come back, and a pull request may lose none of its lines. The run's summary lists the lowered counts once the - plan has finished; a run stopped after the lowering pushes nothing. A pull request may change a pending file but not grow it. Upstream lines a seam or pending file no longer has (deleted, moved below the code they + plan has finished; a run stopped after the lowering pushes nothing. A pull request may change a pending file but not grow it. A + pull request that changes a pending file's text is counted from upstream in its run + (fork-checks), against main's ceiling and `lost` entry, even with its list unchanged: within the + counts its run cannot tell an upstream line from a fork line, so a change that swaps an upstream + line for a fork line keeps every count it can see. Upstream lines a seam or pending file no longer has (deleted, moved below the code they guard, or re-indented) add no line, so they are counted too, two ways: `lines`, the upstream lines it does not keep in order and indentation, and `gone`, those whose text it no longer has at all, so deleting a line already counted as moved or re-indented raises `gone`. `lost` maps such @@ -206,6 +213,11 @@ seam entry together is refused. It takes two pull requests, each green: too, the list is malformed. Review where the line goes, not only the list edit: any pull request may spend an announced line, not only the one meant to. +A pull request that changes a file and whose list drops an announced line main's list has, in date +(from a branch made before the announcement merged, say), is refused: keep it under `announced`, +or move it to `added` in the change that adds it. Withdraw one on purpose with a list-only pull +request; an expired one may go in any change. + An announcement lasts 14 days. From upstream, fork-follow refuses one more than 14 days older than the head's commit date (or dated more than a day ahead of it): announce the lines again (set `since` to the day that pull request merges) or remove the announcement, with a list-only pull request to