diff --git a/.github/scripts/fork-follow.sh b/.github/scripts/fork-follow.sh index 15194e40c51ca..44d97ad58595d 100755 --- a/.github/scripts/fork-follow.sh +++ b/.github/scripts/fork-follow.sh @@ -196,6 +196,9 @@ schema_check "$base" "The series" # and the next run (from the new base) would refuse it. So the series gets a commit that lowers each # one (#325); a count that rose is still refused, as raising one is the owner's review. seam_refusal="Fork changes to upstream files must stay within the seam lines" +# What a lowering commit changed, for the run's summary: written only once the plan has finished, +# as a later check can still stop it and then nothing is pushed. +lowered_summary=() seam_run() { # seam_run BASE [--after-rebase]: the check's exit status; its output in seam-check.log local status=0 lower=() rm -f "$logs/seam-lowered.json" @@ -213,17 +216,15 @@ seam_check() { # seam_check BASE WHAT [--after-rebase] git add -- .github/fork-seams.json as_fork commit -q -m "fork seams: lower counts after the rebase onto $target_tag" -m "$lowered" printf '%s\n' "$2 lowered the seam list (.github/fork-seams.json) in a commit of its own:" "$lowered" >&2 - if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then - printf '%s\n' "### Seam list lowered: $2" "" "$lowered" "" \ - "Committed into the series; the fork lines or upstream lines these counted are gone." \ - "" >> "$GITHUB_STEP_SUMMARY" - fi + lowered_summary=("### Seam list lowered: $2" "" "$lowered" "" \ + "Committed on top of the rebased series (the candidate); the fork lines or upstream lines these counted are gone." "") # The lowered list is judged again: it must pass and lower nothing more. status=0 seam_run "$1" ${3:+"$3"} || status=$? if ((status == 0)) && [[ -f "$logs/seam-lowered.json" ]]; then - fail "The seam list fork-follow lowered still lowers again, so it was not committed as checked:" \ - "$(quoted "$(cat "$logs/seam-check.log")")" "" "The series was left as it is." + fail "$2 needed a lower seam list, and the list fork-follow lowered still lowers again, so the run stopped:" \ + "$(quoted "$lowered")" "" "The check of the lowered list said:" \ + "$(quoted "$(cat "$logs/seam-check.log")")" "" "The lowering commit was made in this run's checkout only; the series was left as it is." fi fi if ((status == 0)); then @@ -617,3 +618,7 @@ new_workflows "$base" "$target" echo "own_workflows=$own_list" echo "new_workflows=$new_list" } >> "$OUTPUT" +# The plan has finished: the lowering commit is in the candidate it hands on. +if ((${#lowered_summary[@]})) && [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then + printf '%s\n' "${lowered_summary[@]}" >> "$GITHUB_STEP_SUMMARY" +fi diff --git a/.github/scripts/fork-follow.test.sh b/.github/scripts/fork-follow.test.sh index 6ff69d795020c..33bbca97338fe 100755 --- a/.github/scripts/fork-follow.test.sh +++ b/.github/scripts/fork-follow.test.sh @@ -656,6 +656,85 @@ plan check "plan: the next run from the new base passes the lowered list" \ eval 'action_is release && [[ ! -e "$root/report.md" ]] && hasnt "Note: " "$root/out"' +# #510: the same rebase again. An earlier run published the candidate with its lowering commit, +# then could not move the series: the next run lowers again (a new commit, the same files) and +# advances to that release instead of building another. +adopted() { # the fork's pending line in u2.txt, which upstream v0.1.11 adopts word for word + new_upstream + new_fork v0.1.10 + amend_fork '{"files":{},"pending":{"u2.txt":1}}' 'echo "fork pending line" >> u2.txt' + up_release v0.1.11 'echo "fork pending line" >> u2.txt' +} +amend_fork() { # amend_fork LIST CMD: the fork's commit gets LIST as its seam list and the change CMD makes + (cd "$root/work" && printf '%s\n' "$1" > .github/fork-seams.json && eval "$2" \ + && git add -A && git commit -q --amend --no-edit && git push -q --force origin main) > /dev/null 2>&1 +} +adopted +plan +released="$(out candidate)" +fork_tag v0.1.11-fork.1 "$released" +work git checkout -q main && work git reset -q --hard "$(series)" +plan +check "plan: re-run of a rebase that lowered the list -> the same files, advance to the earlier release" \ + eval 'action_is advance && [[ "$(out candidate)" == "$released" ]] && grep -q "lowered the seam list" "$root/out"' + +# The lowered list is checked again and must lower nothing more. A seam check that always lowers +# (in the fork's series, which the plan runs) stops the plan: the report says what was lowered, and +# the run's summary claims no commit, as nothing goes on from here. +adopted +fork_commit "fork: a seam check that always lowers" "cat > .github/scripts/fork-seam-check.cjs << 'JS' +const fs = require('node:fs'); +const at = process.argv.indexOf('--lowered-list'); +if (at !== -1) { + fs.writeFileSync(process.argv[at + 1], fs.readFileSync('.github/fork-seams.json', 'utf8') + ' '); + console.log('Lowered: u2.txt: always'); +} +JS" +summary_before="earlier step line" plan +check "plan: a lowered list that still lowers again stops the plan, naming what was lowered" \ + eval '[[ -z "$(out action)" ]] && has "still lowers again" "$root/report.md" && has "^ - u2.txt: always" "$root/report.md" \ + && has "in this run.s checkout only; the series was left as it is" "$root/report.md"' +check "plan: a plan stopped after the lowering puts no lowered list in the step summary" \ + eval 'has "earlier step line" "$root/summary.md" && hasnt "Seam list lowered" "$root/summary.md"' + +# One count lowered and another raised in the same run: refused, and nothing is lowered or +# committed. m.txt is pending (one fork line) with its "c" moved to the end ("lost" 1/0); upstream +# deletes its own "c", so the moved copy becomes a second fork line and the moved line is gone. +new_upstream +up_release v0.1.11 'printf "%s\n" a b c d e f g h i j k l > m.txt' +new_fork v0.1.11 +amend_fork '{"files":{},"pending":{"m.txt":1},"lost":{"m.txt":{"lines":1,"gone":0}}}' \ + 'printf "%s\n" a b d e f g h i j k l c "fork line" > m.txt' +up_release v0.1.12 'sed -i "/^c$/d" m.txt' +before="$(work_head)" +plan +check "plan: a count lowered and one raised in one run is refused, committing and lowering nothing" \ + eval '[[ -z "$(out action)" ]] && has "m.txt: \"pending\" with 2 fork lines, more than its ceiling of 1 after the rebase" "$root/report.md" \ + && hasnt "^Lowered: " "$root/out" && hasnt "Seam list lowered" "$root/summary.md" \ + && [[ "$(git -C "$root/work" log -1 --format=%s)" != "fork seams: lower counts"* && "$(series)" == "$before" ]]' + +# A "lost" count lowered through fork-follow, and a pending file left with no fork line that "lost" +# still names: it moves to "files" with no seam line (#510), and the next run passes. The fork +# deletes "c" and "h" and adds one line; upstream deletes "c" too and adopts the fork's line. +new_upstream +up_release v0.1.11 'printf "%s\n" a b c d e f g h i j k l > m.txt' +new_fork v0.1.11 +amend_fork '{"files":{},"pending":{"m.txt":1},"lost":{"m.txt":{"lines":2,"gone":2}}}' \ + 'printf "%s\n" a b d e f g i j k l "fork line" > m.txt' +up_release v0.1.12 'sed -i "/^c$/d" m.txt && echo "fork line" >> m.txt' +plan +check "plan: a lost count and a pending file with no fork line left are lowered in the lowering commit" \ + eval 'action_is rebase \ + && grep -qx -- "- m.txt: \"lost\" 2/2 -> 1/1" <<< "$(git -C "$root/work" log -1 --format=%b "$(out candidate)")" \ + && grep -q -- "- m.txt: \"pending\" 1 moved to \"files\" with no seam line" <<< "$(git -C "$root/work" log -1 --format=%b "$(out candidate)")" \ + && [[ "$(node -e "const l = JSON.parse(process.argv[1]); console.log(JSON.stringify([l.pending, l.files[\"m.txt\"].added, l.lost]))" "$(lowered_list)")" == "[{},[],{\"m.txt\":{\"lines\":1,\"gone\":1}}]" ]] \ + && has "### Seam list lowered" "$root/summary.md"' +work git reset -q --hard "$(out candidate)" +work git push -q --force origin HEAD:main +plan +check "plan: the next run passes the list with the file moved to files" \ + eval 'action_is release && [[ ! -e "$root/report.md" ]] && hasnt "Note: " "$root/out"' + in_candidate() { git -C "$root/work" cat-file -e "$(out candidate):.github/workflows/$1" 2> /dev/null; } new_upstream diff --git a/.github/scripts/fork-seam-check.cjs b/.github/scripts/fork-seam-check.cjs index d450a047a40e7..f287ef7140e2e 100644 --- a/.github/scripts/fork-seam-check.cjs +++ b/.github/scripts/fork-seam-check.cjs @@ -188,9 +188,14 @@ function findSeamBreaches(files, { atBase, atHead, atTip, upstream = false, toda const allowance = counts.get(line) ?? 0; return upstream ? allowance : Math.max(0, allowance - spent(line)); }; - const adds = (copies, line) => + // The hint only where the base branch's newer copies alone make these too many: judged from + // the merge-base (the copies the announcement allows in date), the branch would pass. + // `counts` is the allowance the copies are judged by: in date for `late`, else `allowed` (an + // expired announcement allows nothing from the merge-base either, so updating would not help). + const adds = (copies, line, added, counts) => `${file}: adds ${copies === 1 ? "" : `${copies}× `}\`${line}\`${ - (tipCounts.get(line) ?? 0) > (baseCounts.get(line) ?? 0) + (tipCounts.get(line) ?? 0) > (baseCounts.get(line) ?? 0) && + added <= (counts.get(line) ?? 0) - (baseCounts.get(line) ?? 0) ? " (the base branch has more copies than this branch's merge-base: update the branch from its base)" : "" }`; @@ -206,10 +211,10 @@ function findSeamBreaches(files, { atBase, atHead, atTip, upstream = false, toda ? "is dated after" : `is more than ${ANNOUNCED_DAYS} days before`; lateReasons.push( - `${adds(lateCopies, line)} (its announcement of ${since} ${when} ${today}, the list's commit date: announce it again with a list-only pull request)`, + `${adds(lateCopies, line, added, inDate)} (its announcement of ${since} ${when} ${today}, the list's commit date: announce it again with a list-only pull request)`, ); } - if (extra > lateCopies) reasons.push(adds(extra - lateCopies, line)); + if (extra > lateCopies) reasons.push(adds(extra - lateCopies, line, added, allowed)); } } return reasons; @@ -256,9 +261,9 @@ const AFTER_REBASE_RISE = /** * Changed files outside the seams. An unlisted upstream file may not change or go (unless `removed` names it). - * A "pending" one holds its ceiling from upstream (too high: `ceilings`, after a rebase `notes`; exceeded: - * `rises`); on a PR it may not grow, and a shrink lowers its ceiling in `ownPending` to match. - * `lowered.pending` gets the count each too-high ceiling from upstream lowers to. + * A "pending" one holds its ceiling from upstream (too high: `ceilings`, after a rebase `notes`; exceeded: `rises`; + * `lowered.pending` gets the lowered count). On a PR it may not grow, and a change sets its `ownPending` ceiling to + * exactly what is left, counting upstream lines put back from `ownLost` (none left: it moves to `ownFiles`). */ function findUnlistedChanges( config, @@ -271,6 +276,8 @@ function findUnlistedChanges( removed = new Set(), afterRebase = false, ownPending, + ownFiles = {}, + ownLost = {}, lowered, }, ) { @@ -332,7 +339,7 @@ function findUnlistedChanges( lowered?.pending.set(file, added); (afterRebase ? notes : ceilings).push( added === 0 - ? `${file}: "pending" with no fork lines left; remove it from the list.` + ? `${file}: "pending" with no fork lines left; remove it from the list${Object.hasOwn(config.lost ?? {}, file) ? ' (to "files" with "added": [] while "lost" names it)' : ""}.` : `${file}: "pending" with ${added} fork lines, fewer than its ceiling of ${ceiling}; lower it to ${added}.`, ); } @@ -343,21 +350,51 @@ function findUnlistedChanges( reasons.push( `${file}: "pending" (fork lines to move out), and this change adds ${grows} more line${grows === 1 ? "" : "s"} than it removes.`, ); - } else if (grows < 0 && ownPending !== undefined) { - // Main sits at its ceiling, so a change that moves fork lines out must lower it too, or the next - // run from upstream refuses main and the spare room could later admit a fork line. The change's - // own list is read only for a lower ceiling (never a wider gate). This run cannot tell fork lines - // from upstream's, so the text names both; the run from upstream holds "lost" counts exact. - const want = ceiling + grows; - const own = Object.hasOwn(ownPending, file) ? ownPending[file] : 0; - if (own > Math.max(want, 0)) { - const removes = `${-grows} more line${grows === -1 ? "" : "s"} than it adds (keep upstream's lines; if they are fork lines moved out)`; + continue; + } + if (ownPending === undefined) continue; + // A change sets the ceiling to exactly what is left (too high admits a fork line later; too low + // fails the run from upstream). Fork lines change by lines gained less the change in "gone" (an + // upstream line put back is a fork line fewer); that run holds both "gone" counts exact. The own + // list only refuses, never widens; a list-only change (text unchanged) is not held: it may fix main. + const goneOf = (lost) => + lost !== undefined && Object.hasOwn(lost, file) ? lost[file].gone : 0; + const mainGone = goneOf(config.lost); + const ownGone = goneOf(ownLost); + const moved = Object.hasOwn(ownFiles, file) && !Object.hasOwn(ownPending, file); + const edited = base !== head; + if (!edited && !moved) continue; + const want = Math.max(edited ? ceiling + grows + ownGone - mainGone : ceiling, 0); + const parts = []; + if (grows < 0) { + parts.push( + `removes ${-grows} more line${grows === -1 ? "" : "s"} than it adds (keep upstream's lines; if they are fork lines moved out)`, + ); + } + if (ownGone !== mainGone) { + parts.push( + `its own "lost" names ${ownGone} upstream line${ownGone === 1 ? "" : "s"} gone where main's names ${mainGone} (an upstream line put back is a fork line fewer)`, + ); + } + const does = parts.length > 0 ? parts.join(", and ") : "changes its lines"; + if (moved) { + // In "files" with "added": [] it may hold no fork line: only an empty file may move there. + if (want > 0) { ceilings.push( - want > 0 - ? `${file}: "pending" with a ceiling of ${ceiling}, and this change removes ${removes}: lower it to ${want} in this change's ${CONFIG}.` - : `${file}: "pending" with a ceiling of ${ceiling}, and this change removes ${removes}: remove it from "pending" in this change's ${CONFIG}.`, + `${file}: "pending" with a ceiling of ${ceiling}, and this change ${does}, but moves it to "files" in this change's ${CONFIG} while ${want} fork line${want === 1 ? " is" : "s are"} left: keep it in "pending" with a ceiling of ${want} (only a file with no fork line left moves to "files").`, ); } + continue; + } + const listed = Object.hasOwn(ownPending, file); + const own = listed ? ownPending[file] : 0; + if (own !== want) { + const has = listed ? `its list has ${own}` : "its list drops it"; + ceilings.push( + want > 0 + ? `${file}: "pending" with a ceiling of ${ceiling}, and this change ${does}: set it to ${want} in this change's ${CONFIG} (${has}; main holds its ceiling exactly).` + : `${file}: "pending" with a ceiling of ${ceiling}, and this change ${does}: remove it from "pending" in this change's ${CONFIG} (${has}).`, + ); } } return { reasons, ceilings, rises, notes }; @@ -768,11 +805,15 @@ function ownListProblem(text) { } } +// The "why" of a pending file fork-follow moves to "files" (see lowerList). +const MOVED_WHY = + 'Was "pending": fork-follow moved it here once it had no fork line left, as its "lost" entry still counts upstream lines it loses. No seam line: a fork line goes in a file of the fork\'s own.'; + /** * `text` with the counts in `lowered` ({ pending, lost }: Maps of file to count) lowered, as { text, changes }, - * or undefined when nothing changes. Only lowers; a count at 0 removes the entry, except a "pending" one a - * "lost" entry still names (that would leave the list malformed). Two-space JSON, parsed again before it is - * returned, so a lowered list is never one the check refuses. + * or undefined when nothing changes. Only lowers; a count at 0 removes the entry. A "pending" file with no fork + * line left that "lost" still names moves to "files" with no seam line (no fork line may come back, no line may + * be lost). Two-space JSON, parsed again before it is returned, so a lowered list is never one the check refuses. */ function lowerList(text, lowered) { const raw = JSON.parse(text); @@ -797,12 +838,18 @@ function lowerList(text, lowered) { }); if (raw.lost !== undefined) raw.lost = Object.fromEntries(lostAfter); const stillLost = new Set(lostAfter.map(([file]) => file)); + const moved = []; if (raw.pending !== undefined) { raw.pending = Object.fromEntries( Object.entries(raw.pending).flatMap(([file, ceiling]) => { const to = lowered.pending.get(file); - if (to === undefined || to >= ceiling || (to === 0 && stillLost.has(file))) { - return [[file, ceiling]]; + if (to === undefined || to >= ceiling) return [[file, ceiling]]; + if (to === 0 && stillLost.has(file)) { + changes.push( + `${file}: "pending" ${ceiling} moved to "files" with no seam line (no fork line left; "lost" still counts its upstream lines)`, + ); + moved.push(file); + return []; } if (to === 0) { changes.push(`${file}: "pending" ${ceiling} removed (no fork line left)`); @@ -813,6 +860,15 @@ function lowerList(text, lowered) { }), ); } + // Appended through defineProperty: a file named `__proto__` stays an own key. + for (const file of moved) { + Object.defineProperty(raw.files, file, { + value: { why: MOVED_WHY, added: [] }, + enumerable: true, + writable: true, + configurable: true, + }); + } if (changes.length === 0) return undefined; const lowerText = `${JSON.stringify(raw, null, 2)}\n`; parseConfig(lowerText); @@ -905,9 +961,11 @@ function main(argv) { // A pull request that moves fork lines out of a "pending" file lowers its ceiling in its own // list (read only for that: a lower ceiling never widens the gate). let ownPending; + let ownFiles; + let ownLost; if (!upstream && listProblem === undefined && ownList !== undefined) { try { - ownPending = parseConfig(ownList).pending ?? {}; + ({ pending: ownPending, files: ownFiles, lost: ownLost } = parseConfig(ownList)); } catch { ownPending = undefined; // The list judged it is main's; a malformed own one is said below. } @@ -923,6 +981,8 @@ function main(argv) { removed, afterRebase: parsed.afterRebase, ownPending, + ownFiles, + ownLost, lowered, }); const lost = findLostLines(config, { @@ -1022,7 +1082,7 @@ function main(argv) { } if (ceilings.length > 0) { console.error( - `Lower each "pending" ceiling and "lost" count named above (or remove the entry) in ${CONFIG}: in this change's list where the line says so, otherwise with a pull request to main.`, + `Lower each "pending" ceiling and "lost" count named above (or remove the entry, or set the value its line names) in ${CONFIG}: in this change's list where the line says so, otherwise with a pull request to main.`, ); } if (late.length > 0) { diff --git a/.github/scripts/fork-seam-check.test.cjs b/.github/scripts/fork-seam-check.test.cjs index 714e94697fa43..433c2d7335bb7 100644 --- a/.github/scripts/fork-seam-check.test.cjs +++ b/.github/scripts/fork-seam-check.test.cjs @@ -16,6 +16,7 @@ const { findStaleSeamLines, findUnlistedChanges, forkFileTest, + lineCounts, lostLines, lowerList, ownListProblem, @@ -2005,7 +2006,7 @@ test("from upstream, a file named like an Object property is held to a lost coun // A pull request that moved fork lines out of a "pending" file left main's ceiling above its count, // and the next run from upstream refused main for it. -const shrink = (pending, base, head, ownPending) => +const shrink = (pending, base, head, ownPending, ownFiles) => findUnlistedChanges( { files: {}, pending, forkFiles: [] }, { @@ -2015,6 +2016,7 @@ const shrink = (pending, base, head, ownPending) => upstream: false, isForkFile: () => false, ownPending, + ownFiles, }, ); test("from main, a change that shrinks a pending file lowers its ceiling in its own list", () => { @@ -2024,7 +2026,7 @@ test("from main, a change that shrinks a pending file lowers its ceiling in its assert.deepEqual(ceilings.length, 1); assert.match( ceilings[0], - /^p\.ts: "pending" with a ceiling of 3, and this change removes 2 more lines than it adds .*: lower it to 1 in this change's \.github\/fork-seams\.json\.$/, + /^p\.ts: "pending" with a ceiling of 3, and this change removes 2 more lines than it adds .*: set it to 1 in this change's \.github\/fork-seams\.json \(its list has 3; main holds its ceiling exactly\)\.$/, ); assert.deepEqual(shrink({ "p.ts": 3 }, base, head, { "p.ts": 1 }), { reasons: [], @@ -2033,17 +2035,226 @@ test("from main, a change that shrinks a pending file lowers its ceiling in its notes: [], }); // Still 2 is still too high; with no fork line left, the entry goes. - assert.match(shrink({ "p.ts": 3 }, base, head, { "p.ts": 2 }).ceilings[0], /lower it to 1/); + assert.match(shrink({ "p.ts": 3 }, base, head, { "p.ts": 2 }).ceilings[0], /set it to 1 .*has 2/); const none = { "p.ts": UP }; assert.match( shrink({ "p.ts": 3 }, base, none, { "p.ts": 1 }).ceilings[0], - /removes 3 more lines .*: remove it from "pending" in this change's/, + /removes 3 more lines .*: remove it from "pending" in this change's .* \(its list has 1\)\.$/, ); assert.deepEqual(shrink({ "p.ts": 3 }, base, none, {}).ceilings, []); - // A change that swaps one line for another, or grows, or has no own list read: not this rule. + // Removing more lines than the ceiling (upstream's too) still only asks for the entry to go. + const fewer = { "p.ts": "forkA();\n" }; + assert.deepEqual( + shrink({ "p.ts": 1 }, { "p.ts": `${UP}forkA();\n` }, { "p.ts": "" }, {}).ceilings, + [], + ); + assert.deepEqual(shrink({ "p.ts": 3 }, base, fewer, {}).ceilings, []); + // Exact, not only at most. A ceiling set below the lines left, or an entry dropped while + // lines remain, passes here but the next run from upstream refuses main. + assert.deepEqual(shrink({ "p.ts": 3 }, base, head, { "p.ts": 1, "q.ts": 1 }).ceilings, []); + const twoLeft = { "p.ts": `${UP}forkA();\nforkB();\n` }; + assert.match( + shrink({ "p.ts": 3 }, base, twoLeft, { "p.ts": 1 }).ceilings[0], + /removes 1 more line than it adds .*: set it to 2 in this change's .* \(its list has 1; /, + ); + assert.match( + shrink({ "p.ts": 3 }, base, twoLeft, {}).ceilings[0], + /: set it to 2 in this change's .* \(its list drops it; /, + ); + // A change that swaps one line for another keeps the ceiling; one that grows is refused + // elsewhere; with no own list read, nothing is held. const swap = { "p.ts": `${UP}forkA();\nforkB();\nforkD();\n` }; assert.deepEqual(shrink({ "p.ts": 3 }, base, swap, { "p.ts": 3 }).ceilings, []); + assert.match( + shrink({ "p.ts": 3 }, base, swap, { "p.ts": 2 }).ceilings[0], + /this change changes its lines: set it to 3 .*\(its list has 2; /, + ); assert.deepEqual(shrink({ "p.ts": 3 }, base, head, undefined).ceilings, []); + // A list-only change (the file's text unchanged) is not held: it may correct main's ceiling. + assert.deepEqual(shrink({ "p.ts": 3 }, base, base, { "p.ts": 2 }).ceilings, []); +}); + +// Moving a pending file to "files" (where "added": [] allows no fork line) is the +// same as dropping the entry, so only a file with no fork line left may move. +test('from main, a pending file moves to "files" only once no fork line is left', () => { + const base = { "p.ts": `${UP}forkA();\nforkB();\nforkC();\n` }; + const twoLeft = { "p.ts": `${UP}forkA();\nforkB();\n` }; + const moved = { "p.ts": { why: "w", added: [] } }; + assert.deepEqual(shrink({ "p.ts": 3 }, base, twoLeft, {}, moved).ceilings, [ + `p.ts: "pending" with a ceiling of 3, and this change removes 1 more line than it adds (keep upstream's lines; if they are fork lines moved out), but moves it to "files" in this change's .github/fork-seams.json while 2 fork lines are left: keep it in "pending" with a ceiling of 2 (only a file with no fork line left moves to "files").`, + ]); + // A list-only move holds main's ceiling, so it is refused too. + assert.match( + shrink({ "p.ts": 3 }, base, base, {}, moved).ceilings[0], + /changes its lines, but moves it to "files" .* while 3 fork lines are left: keep it in "pending" with a ceiling of 3 /, + ); + // None left: the move is the fix (kept in "pending" it must go). + assert.deepEqual(shrink({ "p.ts": 3 }, base, { "p.ts": UP }, {}, moved).ceilings, []); + // Listed in both (a malformed list is refused elsewhere): judged as "pending". + assert.deepEqual(shrink({ "p.ts": 3 }, base, twoLeft, { "p.ts": 2 }, moved).ceilings, []); +}); + +// The pending lines a run from upstream counts, as fork-follow's check before the rebase does. +const fromUpstream = (list, upstream, head) => { + const options = { + atBase: (file) => upstream[file], + atHead: (file) => head[file], + upstream: true, + }; + const unlisted = findUnlistedChanges(list, { + ...options, + changed: Object.keys(head), + isForkFile: () => false, + }); + const lost = findLostLines(list, options); + return [ + ...findSeamBreaches(list.files, options), + ...unlisted.reasons, + ...unlisted.ceilings, + ...lost.reasons, + ...lost.ceilings, + ]; +}; +// The pull request's run: main's list judges, the change's own list only refuses. +const fromMain = (list, own, main, head) => { + const unlisted = findUnlistedChanges(list, { + changed: Object.keys(head), + atBase: (file) => main[file], + atHead: (file) => head[file], + upstream: false, + isForkFile: () => false, + ownPending: own.pending ?? {}, + ownFiles: own.files, + ownLost: own.lost, + }); + return [...unlisted.reasons, ...unlisted.ceilings]; +}; + +// A pending file's fork lines change by the lines gained less the change in "gone", +// so a change that puts an upstream line back has one fork line fewer than its line count says. +test("from main, a change that puts an upstream line back counts it in the exact ceiling", () => { + const upstream = { "p.ts": "a();\nb(x);\nc();\n" }; + const main = { "p.ts": "a();\nb(x, fork);\nforkG();\nforkH();\nc();\n" }; + const head = { "p.ts": "a();\nb(x);\nforkH();\nc();\n" }; + const mainList = { files: {}, pending: { "p.ts": 3 }, lost: { "p.ts": { lines: 1, gone: 1 } } }; + assert.deepEqual(fromUpstream(mainList, upstream, main), []); + const own = (ceiling) => ({ files: {}, pending: { "p.ts": ceiling }, lost: {} }); + // Revert b(x, fork) and move forkG() out: 1 fork line is left. + assert.deepEqual(fromUpstream(own(1), upstream, head), []); + assert.deepEqual(fromMain(mainList, own(1), main, head), []); + assert.deepEqual(fromMain(mainList, own(2), main, head), [ + `p.ts: "pending" with a ceiling of 3, and this change removes 1 more line than it adds (keep upstream's lines; if they are fork lines moved out), and its own "lost" names 0 upstream lines gone where main's names 1 (an upstream line put back is a fork line fewer): set it to 1 in this change's .github/fork-seams.json (its list has 2; main holds its ceiling exactly).`, + ]); + assert.match(fromUpstream(own(2), upstream, head)[0], /fewer than its ceiling of 2/); + // A pure revert (as many lines as before) is held too. + const revert = { "p.ts": "a();\nb(x);\nforkG();\nforkH();\nc();\n" }; + assert.deepEqual(fromMain(mainList, own(2), main, revert), []); + assert.match(fromMain(mainList, own(3), main, revert)[0], /set it to 2 .*its list has 3/); +}); + +// Whatever a pull request's run accepts for a pending file, fork-follow's check before the +// rebase accepts too, when the change's "lost" entry is the one that run holds (a wrong one is +// refused there whatever the ceiling); and the right ceiling always passes the pull request. +test("property: a pending ceiling the pull request accepts passes the run from upstream", () => { + let seed = 510; + const random = (n) => { + seed = (seed * 1103515245 + 12345) % 2147483648; + return Math.floor((seed / 2147483648) * n); + }; + const UPSTREAM_LINES = ["a();", "b();", "c();", "}"]; + const FORK_LINES = ["f();", "g();", "a(fork);", "}"]; + const pick = (lines) => lines[random(lines.length)]; + // Delete, replace with a fork or upstream line, insert one, or put an upstream line back. + const edit = (lines, up) => { + const out = [...lines]; + for (let step = random(3) + 1; step > 0; step--) { + const at = random(out.length + 1); + switch (random(4)) { + case 0: + if (out.length > 0) out.splice(Math.min(at, out.length - 1), 1); + break; + case 1: + if (out.length > 0) out[Math.min(at, out.length - 1)] = pick(FORK_LINES); + break; + case 2: + out.splice(at, 0, pick(random(2) === 0 ? FORK_LINES : UPSTREAM_LINES)); + break; + default: + out.splice(at, 0, pick(up)); + } + } + return out; + }; + const text = (lines) => lines.map((line) => `${line}\n`).join(""); + const split = (file) => file.split("\n").filter(Boolean); + // Copies `head` has over `base`, per line text, summed. + const over = (base, head) => { + const counts = lineCounts(base); + let sum = 0; + for (const [line, count] of lineCounts(head)) + sum += Math.max(0, count - (counts.get(line) ?? 0)); + return sum; + }; + // The list a run from upstream holds exact for this head (the lines it counts). + const exact = (upstream, head) => { + const added = over(upstream["p.ts"], head["p.ts"]); + const lines = lostLines(split(upstream["p.ts"]), split(head["p.ts"])); + const gone = over(head["p.ts"], upstream["p.ts"]); + return { added, lost: lines > 0 ? { "p.ts": { lines, gone } } : {} }; + }; + let checked = 0; + for (let round = 0; round < 3000; round++) { + const up = Array.from({ length: random(4) + 2 }, () => pick(UPSTREAM_LINES)); + const upstream = { "p.ts": text(up) }; + const main = { "p.ts": text(edit(up, up)) }; + const atMain = exact(upstream, main); + if (atMain.added === 0) continue; // Not a pending file. + const mainList = { files: {}, pending: { "p.ts": atMain.added }, lost: atMain.lost }; + assert.deepEqual(fromUpstream(mainList, upstream, main), []); + const head = { "p.ts": text(edit(split(main["p.ts"]), up)) }; + if (head["p.ts"] === main["p.ts"]) continue; + const atHead = exact(upstream, head); + const lists = [ + { files: {}, lost: atHead.lost }, // dropped + { files: { "p.ts": { why: "w", added: [] } }, lost: atHead.lost }, // moved + ...Array.from({ length: atMain.added + 3 }, (_, n) => ({ + files: {}, + pending: { "p.ts": n + 1 }, + lost: atHead.lost, + })), + ]; + for (const own of lists) { + try { + parseConfig(JSON.stringify(own)); + } catch { + continue; // Refused as a malformed list. + } + if (fromMain(mainList, own, main, head).length > 0) continue; + checked++; + const config = { forkFiles: [], ...own, pending: own.pending ?? {} }; + assert.deepEqual( + fromUpstream(config, upstream, head), + [], + JSON.stringify({ main, head, own }), + ); + } + // The right list passes the pull request (unless it grows, which is refused anyway). + const right = + atHead.added > 0 + ? { files: {}, pending: { "p.ts": atHead.added }, lost: atHead.lost } + : { + files: Object.keys(atHead.lost).length > 0 ? { "p.ts": { why: "w", added: [] } } : {}, + lost: atHead.lost, + }; + const grows = over(main["p.ts"], head["p.ts"]) - over(head["p.ts"], main["p.ts"]); + if (grows <= 0) + assert.deepEqual( + fromMain(mainList, right, main, head), + [], + JSON.stringify({ main, head, right }), + ); + } + assert.ok(checked > 500, `only ${checked} accepted lists checked`); }); test("the command line refuses a pull request that shrinks a pending file but keeps its ceiling", () => { @@ -2056,7 +2267,7 @@ test("the command line refuses a pull request that shrinks a pending file but ke assert.equal(kept.status, 1, kept.stdout); assert.match( kept.stderr, - /- p\.ts: "pending" with a ceiling of 2, .* lower it to 1 in this change's/, + /- p\.ts: "pending" with a ceiling of 2, .* set it to 1 in this change's/, ); assert.match( kept.stderr, @@ -2084,6 +2295,22 @@ test("from main, a listed copy the base branch already has since the merge-base ]); // From upstream there is no base branch tip: each listed line is one copy over upstream's. assert.deepEqual(findSeamBreaches(SEAM, { ...options(main), upstream: true }), []); + // Two copies are too many from the merge-base too, so updating would not help: no hint. + const twice = { "a.ts": BASE["a.ts"].replace(" a: 1,", " ...fork,\n ...fork,\n a: 1,") }; + assert.deepEqual(findSeamBreaches(SEAM, { ...options(main), atHead: (file) => twice[file] }), [ + "a.ts: adds 2× `...fork,`", + ]); + // An expired announcement allows no copy from the merge-base either: no hint. + const fresh = { + "a.ts": { why: "t", added: [], announced: { since: "2026-01-01", added: ["...fork,"] } }, + }; + const late = []; + const reasons = findSeamBreaches(fresh, { ...options(main), today: "2026-11-19", late }); + assert.deepEqual([...reasons, ...late], ["a.ts: adds `...fork,`"]); + // In date, the same copy is the base branch's newer one: the hint stays. + assert.deepEqual(findSeamBreaches(fresh, { ...options(main), today: "2026-01-05" }), [ + "a.ts: adds `...fork,` (the base branch has more copies than this branch's merge-base: update the branch from its base)", + ]); }); test("the command line spends a seam copy another branch merged since the merge-base", () => { @@ -2132,11 +2359,14 @@ test("lowerList lowers and removes entries, keeps comments and order, and never ]), }; const result = lowerList(text, lowered); + const moved = JSON.parse(result.text).files["c.ts"]; + assert.match(moved.why, /^Was "pending": fork-follow moved it here/); assert.deepEqual(JSON.parse(result.text), { "//": "comment", - files: { "s.ts": { why: "w", added: ["x();"] } }, - // c.ts keeps its ceiling: "lost" still names it (the run after says so). - pending: { "a.ts": 1, "c.ts": 2, "e.ts": 4 }, + // c.ts has no fork line left, but "lost" still names it (and a ceiling is 1 or more): it + // moves to "files" with no seam line, which holds it tighter. + files: { "s.ts": { why: "w", added: ["x();"] }, "c.ts": { why: moved.why, added: [] } }, + pending: { "a.ts": 1, "e.ts": 4 }, // e.ts: only the count that fell is lowered. lost: { "c.ts": { lines: 1, gone: 1 }, "e.ts": { lines: 3, gone: 0 } }, }); @@ -2147,6 +2377,7 @@ test("lowerList lowers and removes entries, keeps comments and order, and never 's.ts: "lost" 1/0 removed (no upstream line lost)', 'a.ts: "pending" 3 -> 1', 'b.ts: "pending" 2 removed (no fork line left)', + 'c.ts: "pending" 2 moved to "files" with no seam line (no fork line left; "lost" still counts its upstream lines)', ]); assert.equal(lowerList(text, { pending: new Map([["e.ts", 9]]), lost: new Map() }), undefined); assert.equal(lowerList(text, { pending: new Map(), lost: new Map() }), undefined); diff --git a/docs/fork/updates.md b/docs/fork/updates.md index 3dea261fc36d8..579b1f32dab64 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -60,17 +60,23 @@ watches; it changes nothing on the machine, and `0` turns it off. later run. `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 one - that removes more lines than it adds and leaves its own ceiling above main's minus that many (it - reads its own list only for that, as a lower ceiling never widens the gate). Right after a rebase, + of a pending file lowers its ceiling in its own list, in the same change: its run refuses a + change to the file unless its own ceiling is exactly main's, plus the lines it adds, less the + lines it removes, less the upstream lines it puts back (main's `lost` `gone` less its own), since + per line text fork lines less gone ones is the copies over upstream's. With none left the entry + goes, or moves to `files` with `"added": []` (only then: a move while fork lines are left is + refused). Left higher, the next run from upstream refuses main for the spare room; set lower or + dropped, for the lines still there. It reads its own list only to refuse, never to widen the + gate, and does not hold a list-only change (the file's text unchanged), which may correct main. Right after a rebase, below the ceiling is not refused: when upstream takes a fork line word for word, the rebase drops it, and the ceiling could not have been lowered first. fork-follow then lowers it itself, in a commit of its own on the rebased series ("fork seams: lower counts after the rebase onto …", each change in its body and in the run's summary), and checks the lowered list again before it goes - on. It never raises one. The one ceiling it cannot lower is a pending file with no fork line left - that a `lost` entry still names (a ceiling is 1 or more, and a `lost` entry needs its file in - `files` or `pending`): that stays a note, the next run refuses it, and a pull request moves the - file to `files` with `"added": []`. 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 + on. It never raises one. A pending file with no fork line left that a `lost` entry still names + (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 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 @@ -103,9 +109,10 @@ watches; it changes nothing on the machine, and `0` turns it off. fork-follow, so keep seam lines specific. A listed copy main's tip already has is spent too, not only one the branch's merge-base has: two branches from one main that each add the one listed copy are each green, and once one merges the other is refused ("update the branch from its - base"). The ruleset does not require a branch to be up to date before it merges, so two changes - that are fine apart but not together (a seam line in both, or a pending file each shrinks) still - need the later one updated from main to be judged together. A branch made before fork-follow last + base"). Neither seam check runs on `merge_group`. Two changes that are fine apart but not together + (a seam line in both, or a pending file each shrinks) are judged together because main's ruleset + requires a branch to be up to date with main before it merges (#444): the later one is updated + from main, and that update runs both checks again. A branch made before fork-follow last rebased main is refused with one "update the branch" error. Only `--from-upstream` (which fork-follow passes) runs it from an upstream commit and reads the head's list; without it a base with no list is refused, and an upstream that is itself a fork with a list is still judged by this fork's list.