From f952c437cdf1560f3905d9314d64fc65650585f5 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:42:48 +0000 Subject: [PATCH 1/2] fork seams: lower counts after a rebase, shrink lowers its ceiling, tip copies spent - fork-follow commits the list with each "pending" ceiling and "lost" count that fell after a rebase lowered (#325 item 1), checks it again, and names each change in the commit body and the run summary. It never raises one. - fork-seam-check --lowered-list (only with --from-upstream --after-rebase) writes that list; lowerList keeps comments and order and only lowers. - A pull request that removes lines from a "pending" file lowers its ceiling in its own list (#311 comment); its own list is read only for that. - A listed seam copy the base branch's tip has since the merge-base is spent (#311 item 3, as far as code goes). - A file named like an Object property is held to its "lost" count (#416 item 3); the announcement lookup reads own keys too. - Docs: the new rules, #416 item 2, and how the check behaves with a missing, empty or old list, renamed or deleted files, and after a rebase. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/fork-follow.sh | 35 +++- .github/scripts/fork-follow.test.sh | 28 +-- .github/scripts/fork-seam-check.cjs | 209 ++++++++++++++++++--- .github/scripts/fork-seam-check.test.cjs | 225 ++++++++++++++++++++++- docs/fork/updates.md | 65 +++++-- 5 files changed, 500 insertions(+), 62 deletions(-) diff --git a/.github/scripts/fork-follow.sh b/.github/scripts/fork-follow.sh index b9d317253d9ba..15194e40c51ca 100755 --- a/.github/scripts/fork-follow.sh +++ b/.github/scripts/fork-follow.sh @@ -193,11 +193,39 @@ schema_check "$base" "The series" # upstream commit, which --from-upstream says (the series' own list judges it, even when upstream # is a fork with a list of its own). After a rebase (--after-rebase), a "pending" ceiling or "lost" # count above the file's lines is only a note: upstream taking a fork line drops it in the rebase, -# and the next run (from the new base) refuses it. +# 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" +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" + [[ -z "${2:-}" ]] || lower=("$2" --lowered-list "$logs/seam-lowered.json") + node .github/scripts/fork-seam-check.cjs --from-upstream ${lower[@]+"${lower[@]}"} "$1" HEAD > "$logs/seam-check.log" 2>&1 || status=$? + return "$status" +} seam_check() { # seam_check BASE WHAT [--after-rebase] local status=0 - node .github/scripts/fork-seam-check.cjs --from-upstream ${3:+"$3"} "$1" HEAD > "$logs/seam-check.log" 2>&1 || status=$? + seam_run "$1" ${3:+"$3"} || status=$? + if ((status == 0)) && [[ -f "$logs/seam-lowered.json" ]]; then + local lowered + lowered="$(grep '^Lowered: ' "$logs/seam-check.log" | sed 's/^Lowered: /- /')" + cp "$logs/seam-lowered.json" .github/fork-seams.json + 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 + # 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." + fi + fi if ((status == 0)); then local notes notes="$(grep '^Note: ' "$logs/seam-check.log" || true)" @@ -206,7 +234,7 @@ seam_check() { # seam_check BASE WHAT [--after-rebase] # The log is seen only when the plan fails: the notes go to the run's summary too. if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then printf '%s\n' "### Seam check notes: $2" "" "$(sed 's/^Note: /- /' <<< "$notes")" "" \ - "A ceiling or count named here is refused by the next run; lower it with a pull request to main." \ + "A ceiling or count still named here (one fork-follow could not lower) is refused by the next run; fix it with a pull request to main (docs/fork/updates.md)." \ "" >> "$GITHUB_STEP_SUMMARY" fi return 0 @@ -555,6 +583,7 @@ candidate="$(git rev-parse HEAD)" # says what to do about a workflow. refuse_upstream_fork_named "$target" "$target_tag" "$candidate" seam_check "$target" "After rebasing onto $target_tag, the series" --after-rebase +candidate="$(git rev-parse HEAD)" # The seam check may have committed a lowered list. refuse_outside_workflows "$base" "$target" "$target_tag" "$candidate" dropped="$(comm -23 <(sort <<< "$before") <(git log --format=%s "$target..HEAD" | sort) | paste -sd ';' -)" diff --git a/.github/scripts/fork-follow.test.sh b/.github/scripts/fork-follow.test.sh index 3621ac97b01b2..6ff69d795020c 100755 --- a/.github/scripts/fork-follow.test.sh +++ b/.github/scripts/fork-follow.test.sh @@ -629,26 +629,32 @@ for yes in yes on 1; do done # Upstream adopts a "pending" fork line word for word: the rebase drops it, so the series is below -# its ceiling. Lowering the ceiling first fails the check on the old base, so after a rebase the -# ceiling is only a note; the next run, from the new base, refuses it (a pull request lowers it). +# its ceiling. Lowering the ceiling first fails the check on the old base, and left as it is the +# next run (from the new base) refuses it: so after a rebase the plan commits the lowered list into +# the series (#325), and the next run passes. new_upstream new_fork v0.1.10 -(cd "$root/work" && echo '{"files":{},"pending":{"u2.txt":1}}' > .github/fork-seams.json && echo "fork pending line" >> u2.txt \ - && git add -A && git commit -q --amend --no-edit && git push -q --force origin main) > /dev/null 2>&1 +(cd "$root/work" && echo '{"files":{},"pending":{"u2.txt":1}}' > .github/fork-seams.json \ + && echo "fork pending line" >> u2.txt && git add -A && git commit -q --amend --no-edit && git push -q --force origin main) > /dev/null 2>&1 up_release v0.1.11 'echo "fork pending line" >> u2.txt' summary_before="earlier step line" plan -check "plan: upstream taking a pending fork line rebases, noting the ceiling" \ - eval 'action_is rebase && grep -q "Note: u2.txt: \"pending\" with no fork lines left" "$root/out"' -# The plan log is seen only on a failure; the note also goes to the run's summary. -check "plan: the after-rebase note is also in the step summary" \ - eval 'has "u2.txt: \"pending\" with no fork lines left" "$root/summary.md" && has "lower it with a pull request to main" "$root/summary.md"' +lowered_list() { git -C "$root/work" show "$(out candidate):.github/fork-seams.json"; } +check "plan: upstream taking a pending fork line rebases, lowering the list in a commit of its own" \ + eval 'action_is rebase && grep -q "lowered the seam list" "$root/out" \ + && [[ "$(git -C "$root/work" log -1 --format=%s "$(out candidate)")" == "fork seams: lower counts after the rebase onto v0.1.11" ]] \ + && [[ "$(node -e "console.log(JSON.stringify(JSON.parse(process.argv[1])))" "$(lowered_list)")" == "{\"files\":{},\"pending\":{}}" ]]' +check "plan: the lowering commit names each change in its body" \ + eval 'grep -qx -- "- u2.txt: \"pending\" 1 removed (no fork line left)" <<< "$(git -C "$root/work" log -1 --format=%b "$(out candidate)")"' +# The plan log is seen only on a failure; what was lowered also goes to the run's summary. +check "plan: the lowered list is also in the step summary" \ + eval 'has "### Seam list lowered" "$root/summary.md" && has "u2.txt: \"pending\" 1 removed" "$root/summary.md" && hasnt "lower it with a pull request" "$root/summary.md"' # The runner's summary file may already hold lines: the notes are added, never written over. check "plan: the step summary notes are added after what was there" has "earlier step line" "$root/summary.md" work git reset -q --hard "$(out candidate)" work git push -q --force origin HEAD:main plan -check "plan: the next run from the new base refuses the ceiling, naming the fix" \ - eval 'has "u2.txt: \"pending\" with no fork lines left" "$root/report.md" && has "Lower each \"pending\" ceiling" "$root/report.md" && hasnt "a file of the fork" "$root/report.md" && [[ -z "$(out action)" ]]' +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"' in_candidate() { git -C "$root/work" cat-file -e "$(out candidate):.github/workflows/$1" 2> /dev/null; } diff --git a/.github/scripts/fork-seam-check.cjs b/.github/scripts/fork-seam-check.cjs index 230d836333fc3..44eedfe42fed7 100644 --- a/.github/scripts/fork-seam-check.cjs +++ b/.github/scripts/fork-seam-check.cjs @@ -1,9 +1,12 @@ -// Usage: [--config-ref ] | --from-upstream [--after-rebase] . +// Usage: [--config-ref ] | --from-upstream [--after-rebase [--lowered-list ]] . // Refuses 's upstream-file changes beyond .github/fork-seams.json. A pull request's list is -// 's (or --config-ref's), never 's; --from-upstream (fork-follow) reads 's, even if -// upstream has its own. --after-rebase: a ceiling above the count is a note. Reads git objects only. +// 's (or --config-ref's), never 's (its own is read only for "pending" ceilings it must +// lower); --from-upstream (fork-follow) reads 's, even if upstream has its own. --after-rebase: +// a ceiling above the count is a note, and --lowered-list writes the list with it lowered there. +// Reads git objects only (and writes only that file). const { execFileSync } = require("node:child_process"); +const fs = require("node:fs"); const CONFIG = ".github/fork-seams.json"; // Upstream workflow files the fork deletes (fork-follow.sh keeps them deleted): with upstream's @@ -151,9 +154,11 @@ function parseRemoved(text = "") { * Reasons for the seam files' lines: each listed line allows one copy more than `base` has (not from * upstream, `base` is main, whose copies spent it). On `today` (a pull request's run: the list's * commit date) an expired or dated-ahead announcement allows nothing: the copies it would allow in - * date go to `late`, any more to the reasons. + * date go to `late`, any more to the reasons. `atTip` (a pull request's run: the base branch's tip) + * spends the allowance too: two branches from one merge-base cannot each add the one listed copy, + * once the first has merged (#311 item 3). */ -function findSeamBreaches(files, { atBase, atHead, upstream = false, today, late }) { +function findSeamBreaches(files, { atBase, atHead, atTip, upstream = false, today, late }) { const reasons = []; const lateReasons = late ?? reasons; for (const [file, seam] of Object.entries(files)) { @@ -180,11 +185,19 @@ function findSeamBreaches(files, { atBase, atHead, upstream = false, today, late const allowed = lineCounts((expired ? seam.added : seamLines(seam)).join("\n")); const inDate = expired ? lineCounts(seamLines(seam).join("\n")) : allowed; const baseCounts = lineCounts(base); + const tip = upstream || atTip === undefined ? undefined : atTip(file); + const tipCounts = tip === undefined ? new Map() : lineCounts(tip); + const spent = (line) => Math.max(baseCounts.get(line) ?? 0, tipCounts.get(line) ?? 0); const leftOf = (counts, line) => { const allowance = counts.get(line) ?? 0; - return upstream ? allowance : Math.max(0, allowance - (baseCounts.get(line) ?? 0)); + return upstream ? allowance : Math.max(0, allowance - spent(line)); }; - const adds = (copies, line) => `${file}: adds ${copies === 1 ? "" : `${copies}× `}\`${line}\``; + const adds = (copies, line) => + `${file}: adds ${copies === 1 ? "" : `${copies}× `}\`${line}\`${ + (tipCounts.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)" + : "" + }`; for (const [line, added] of addedLines(base, head)) { const left = leftOf(allowed, line); const extra = added - left; @@ -243,16 +256,28 @@ function forkFileTest(patterns = []) { // The old base held the count exactly, so the rise came with the rebase (upstream's own change): // the operator's step, not a pull request author's (fork-follow cannot commit the raise itself). const AFTER_REBASE_RISE = - " after the rebase onto this base (upstream's own change did it, not a fork pull request): rebase by hand as docs/fork/updates.md says and raise the {count} in the rebased series before pushing it, or push it and then raise the {count} with a list-only pull request to main; fork-follow cannot raise it itself until #325 item 1."; + " after the rebase onto this base (upstream's own change did it, not a fork pull request): rebase by hand as docs/fork/updates.md says and raise the {count} in the rebased series before pushing it, or push it and then raise the {count} with a list-only pull request to main; fork-follow lowers a count after a rebase, but never raises one (raising one is the owner's review)."; /** * 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 after a rebase: `rises`, the operator's); on a PR it may change but not grow. + * `notes`; exceeded after a rebase: `rises`, the operator's); on a PR it may change but not grow, + * and one that shrinks lowers its ceiling in `ownPending` (the PR's own list) to match (#311). + * `lowered.pending` gets each ceiling a run from upstream finds too high: the count to lower it to. */ function findUnlistedChanges( config, - { changed, atBase, atHead, upstream, isForkFile, removed = new Set(), afterRebase = false }, + { + changed, + atBase, + atHead, + upstream, + isForkFile, + removed = new Set(), + afterRebase = false, + ownPending, + lowered, + }, ) { const reasons = []; const ceilings = []; @@ -307,7 +332,9 @@ function findUnlistedChanges( } else if (added < ceiling) { // A ceiling left too high is room to swap upstream lines for fork lines later, and a note // in the nightly log is never seen: refuse, naming the fix (only noted right after a - // rebase; the next run refuses it). + // rebase, where fork-follow commits the lowered list into the series: #325 item 1). Only a + // lower count goes to `lowered`: a rise is refused. + lowered?.pending.set(file, added); (afterRebase ? notes : ceilings).push( added === 0 ? `${file}: "pending" with no fork lines left; remove it from the list.` @@ -321,6 +348,23 @@ 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 (fork-follow holds it there), so a change that moves fork lines + // out lowers it too. Left as it is, the next run from upstream refuses main for it, and the + // room left over would let a later change swap an upstream line for a fork line. The + // change's own list is read only for a lower ceiling: that is never a wider gate. This run + // cannot tell the fork's lines from upstream's here, so the text says both; an upstream + // line that goes is refused by the run from upstream ("lost" counts are held 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)`; + 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}.`, + ); + } } } return { reasons, ceilings, rises, notes }; @@ -330,8 +374,9 @@ function findUnlistedChanges( * Upstream lines a seam or pending file lost: `lines` not kept in order, `gone` whose text is gone. * From upstream both are held to its "lost" entry (0 when unlisted); a rise after a rebase goes to * `rises`. On a PR only "added" lines may go: an announced line in main's file is upstream's. + * `lowered.lost` gets each entry a run from upstream finds too high: its counts ({0, 0}: remove it). */ -function findLostLines(config, { atBase, atHead, upstream, afterRebase = false }) { +function findLostLines(config, { atBase, atHead, upstream, afterRebase = false, lowered }) { const reasons = []; const ceilings = []; const rises = []; @@ -369,7 +414,8 @@ function findLostLines(config, { atBase, atHead, upstream, afterRebase = false } continue; } const counts = { lines, gone: total(gone) }; - const held = lost[file] ?? { lines: 0, gone: 0 }; + // Own keys only: a file named `constructor` would read Object's and never be refused. + const held = Object.hasOwn(lost, file) ? lost[file] : { lines: 0, gone: 0 }; const below = []; for (const key of ["lines", "gone"]) { const text = say(counts[key], what[key]); @@ -384,6 +430,7 @@ function findLostLines(config, { atBase, atHead, upstream, afterRebase = false } } } if (below.length > 0) { + lowered?.lost.set(file, counts); (afterRebase ? notes : ceilings).push( ...(lines === 0 ? [ @@ -524,7 +571,8 @@ function findAnnouncementWarnings(ownFiles, baseFiles, today) { const warnings = []; for (const [file, seam] of Object.entries(ownFiles)) { if (seam.announced === undefined) continue; - if (JSON.stringify(baseFiles[file]?.announced) === JSON.stringify(seam.announced)) continue; + const before = Object.hasOwn(baseFiles, file) ? baseFiles[file].announced : undefined; + if (JSON.stringify(before) === JSON.stringify(seam.announced)) continue; const { since } = seam.announced; const fix = 'set "since" to the day this pull request merges.'; const refused = dayAfter(since, ANNOUNCED_DAYS + 1); @@ -727,6 +775,58 @@ function ownListProblem(text) { } } +/** + * The list `text` with the ceilings and counts `lowered` names lowered ({ pending, lost }: Maps of + * file to count), 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 (removing it would leave + * the list malformed; the run after says so). Written with two-space JSON, as the list is, and + * 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); + const changes = []; + const lost = raw.lost ?? {}; + const counts = ({ lines, gone }) => `${lines}/${gone}`; + const lostAfter = Object.entries(lost).flatMap(([file, entry]) => { + const found = lowered.lost.get(file); + if (found === undefined) return [[file, entry]]; + // Each count only lowers: one that rose is refused, and nothing is written then. + const to = { + lines: Math.min(found.lines, entry.lines), + gone: Math.min(found.gone, entry.gone), + }; + if (to.lines === entry.lines && to.gone === entry.gone) return [[file, entry]]; + if (to.lines === 0) { + changes.push(`${file}: "lost" ${counts(entry)} removed (no upstream line lost)`); + return []; + } + changes.push(`${file}: "lost" ${counts(entry)} -> ${counts(to)}`); + return [[file, { lines: to.lines, gone: to.gone }]]; + }); + if (raw.lost !== undefined) raw.lost = Object.fromEntries(lostAfter); + const stillLost = new Set(lostAfter.map(([file]) => file)); + 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 === 0) { + changes.push(`${file}: "pending" ${ceiling} removed (no fork line left)`); + return []; + } + changes.push(`${file}: "pending" ${ceiling} -> ${to}`); + return [[file, to]]; + }), + ); + } + if (changes.length === 0) return undefined; + const lowerText = `${JSON.stringify(raw, null, 2)}\n`; + parseConfig(lowerText); + return { text: lowerText, changes }; +} + const hasConfig = (rev) => entryAt(rev, CONFIG)?.type === "blob"; /** Reads `:.github/fork-seams.json`; throws when that commit has none. */ @@ -745,17 +845,30 @@ function parseArgs(argv) { }; const fromUpstream = flag("--from-upstream"); const afterRebase = flag("--after-rebase"); - let configRef; - const at = args.indexOf("--config-ref"); - if (at !== -1) { - configRef = args[at + 1]; - if (!configRef || configRef.startsWith("--")) return undefined; + const option = (name) => { + const at = args.indexOf(name); + if (at === -1) return { value: undefined }; + const value = args[at + 1]; + if (!value || value.startsWith("--")) return undefined; args.splice(at, 2); - } + return { value }; + }; + const configRef = option("--config-ref"); + const loweredList = option("--lowered-list"); + if (!configRef || !loweredList) return undefined; if (args.length !== 2 || args.some((arg) => arg.startsWith("--"))) return undefined; // A pull request's run never runs from upstream; only a run from upstream has a rebase behind it. - if (fromUpstream ? configRef !== undefined : afterRebase) return undefined; - return { configRef, fromUpstream, afterRebase, base: args[0], head: args[1] }; + if (fromUpstream ? configRef.value !== undefined : afterRebase) return undefined; + // Only a run after a rebase lowers the list: fork-follow commits it into the rebased series. + if (loweredList.value !== undefined && !afterRebase) return undefined; + return { + configRef: configRef.value, + loweredList: loweredList.value, + fromUpstream, + afterRebase, + base: args[0], + head: args[1], + }; } function main(argv) { @@ -763,7 +876,7 @@ function main(argv) { if (!parsed) { console.error( "Usage: fork-seam-check.cjs [--config-ref ] \n" + - " fork-seam-check.cjs --from-upstream [--after-rebase] ", + " fork-seam-check.cjs --from-upstream [--after-rebase [--lowered-list ]] ", ); return 2; } @@ -794,6 +907,21 @@ function main(argv) { .split("\0") .filter(Boolean); const isForkFile = forkFileTest(config.forkFiles); + const ownList = textAt(head, CONFIG); + const editsList = !upstream && ownList !== textAt(mergeBase, CONFIG); + const listProblem = editsList ? ownListProblem(ownList) : undefined; + // 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; + if (!upstream && listProblem === undefined && ownList !== undefined) { + try { + ownPending = parseConfig(ownList).pending ?? {}; + } catch { + ownPending = undefined; // The list judged it is main's; a malformed own one is said below. + } + } + const lowered = + parsed.loweredList === undefined ? undefined : { pending: new Map(), lost: new Map() }; const unlisted = findUnlistedChanges(config, { changed, atBase, @@ -802,8 +930,16 @@ function main(argv) { isForkFile, removed, afterRebase: parsed.afterRebase, + ownPending, + lowered, + }); + const lost = findLostLines(config, { + atBase, + atHead, + upstream, + afterRebase: parsed.afterRebase, + lowered, }); - const lost = findLostLines(config, { atBase, atHead, upstream, afterRebase: parsed.afterRebase }); // A ceiling above the count is fixed by lowering it, not by moving lines: its own hint. A count // that rose with a rebase names the operator's step in its own text. const ceilings = [...unlisted.ceilings, ...lost.ceilings]; @@ -813,7 +949,16 @@ function main(argv) { const today = upstream ? undefined : commitDay(configRef); const late = []; const reasons = [ - ...findSeamBreaches(config.files, { atBase, atHead, upstream, today, late }), + // A pull request's base is its base branch's tip: a listed copy another change has merged + // there since this branch's merge-base is spent (#311 item 3). + ...findSeamBreaches(config.files, { + atBase, + atHead, + upstream, + today, + late, + atTip: upstream ? undefined : (file) => textAt(base, file), + }), ...lost.reasons, ...unlisted.reasons, ...(upstream @@ -836,9 +981,6 @@ function main(argv) { const from = parsed.configRef ? `--config-ref ${configRef}` : upstream ? "the head" : "the base"; const notes = [...findListedGone(config, { atBase, atHead }), ...unlisted.notes, ...lost.notes]; for (const note of notes) console.log(printable(`Note: ${note}`)); - const ownList = textAt(head, CONFIG); - const editsList = !upstream && ownList !== textAt(mergeBase, CONFIG); - const listProblem = editsList ? ownListProblem(ownList) : undefined; if (editsList) { console.log( `Note: this change edits ${CONFIG}; it is judged by the list in ${from}, not its own. ` + @@ -862,6 +1004,14 @@ function main(argv) { const refused = [...reasons, ...late, ...rises, ...ceilings, ...expired, ...landed]; if (refused.length === 0) { if (listProblem !== undefined) return 1; + if (lowered !== undefined) { + // After a rebase only: fork-follow commits the lowered list into the rebased series. + const lower = lowerList(textAt(configRef, CONFIG), lowered); + if (lower !== undefined) { + fs.writeFileSync(parsed.loweredList, lower.text); + for (const change of lower.changes) console.log(printable(`Lowered: ${change}`)); + } + } console.log( `Fork lines in upstream files: only the pinned seams (${counted}; list from ${from}).`, ); @@ -880,7 +1030,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} with a pull request to main.`, + `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.`, ); } if (late.length > 0) { @@ -916,6 +1066,7 @@ module.exports = { forkFileTest, lineCounts, lostLines, + lowerList, ownListProblem, parseConfig, parseRemoved, diff --git a/.github/scripts/fork-seam-check.test.cjs b/.github/scripts/fork-seam-check.test.cjs index f9ffc72e04930..2d5a1452f03f4 100644 --- a/.github/scripts/fork-seam-check.test.cjs +++ b/.github/scripts/fork-seam-check.test.cjs @@ -17,6 +17,7 @@ const { findUnlistedChanges, forkFileTest, lostLines, + lowerList, ownListProblem, parseConfig, parseRemoved, @@ -1324,9 +1325,12 @@ test("from upstream, deleting an upstream line already counted as re-indented is assert.equal(first.status, 0, first.stderr); git("checkout", "-q", "-b", "pr", main); const pr = commit({ "p.ts": reindented.replace(" return deny();\n", "") }, "delete it"); - // The pull request's run cannot tell upstream's lines from the fork's in a pending file ... - assert.equal(run(main, pr).status, 0); - // ... and the run from upstream refuses it: the line's text is gone. + // The pull request's run cannot tell upstream's lines from the fork's in a pending file, so it + // refuses a shrink that leaves the ceiling as it is (#311), saying to keep upstream's lines ... + const own = run(main, pr); + assert.equal(own.status, 1, own.stdout); + assert.match(own.stderr, /- p\.ts: "pending" with a ceiling of 1, .*keep upstream's lines/); + // ... and the run from upstream refuses it whatever the list says: the line's text is gone. const result = fromUpstream(upstream, pr); assert.equal(result.status, 1, result.stdout); assert.match( @@ -1522,7 +1526,7 @@ test("after a rebase, a count that rises names the operator's next step", () => assert.equal(reasons.length, 2); for (const reason of reasons) { if (afterRebase) { - assert.match(reason, /after the rebase .* rebase by hand .* #325/, reason); + assert.match(reason, /after the rebase .* rebase by hand .* never raises one/, reason); assert.doesNotMatch(reason, /a file of the fork's own/, reason); } else { assert.match(reason, /a file of the fork's own/, reason); @@ -1982,3 +1986,216 @@ test("the real list takes upstream's MarkdownFileLink.logic.test.ts for an upstr // The fork's other MarkdownFileLink files are upstream's already (in "pending"). assert.equal(isForkFile("apps/web/src/components/chat/MarkdownFileLink.logic.ts"), false); }); + +// A file named after an Object property read `lost[file]` from Object's prototype: its counts were +// undefined, nothing compares above undefined, and every upstream line it lost passed (#416 item 3). +test("from upstream, a file named like an Object property is held to a lost count of 0", () => { + for (const file of ["constructor", "toString", "__proto__"]) { + const config = { pending: { [file]: 1 } }; + const { reasons } = lostIn( + config, + { [file]: GUARD_BASE }, + { [file]: "import { x } from './x';\ndoSensitive();\nforkA();\n" }, + true, + ); + assert.equal(reasons.length, 2, `${file}: ${JSON.stringify(reasons)}`); + assert.match(reasons[0], /more than its "lost" lines count of 0/); + } +}); + +// 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 (#311). +const shrink = (pending, base, head, ownPending) => + findUnlistedChanges( + { files: {}, pending, forkFiles: [] }, + { + changed: Object.keys(head), + atBase: (file) => base[file], + atHead: (file) => head[file], + upstream: false, + isForkFile: () => false, + ownPending, + }, + ); +test("from main, a change that shrinks a pending file lowers its ceiling in its own list", () => { + const base = { "p.ts": `${UP}forkA();\nforkB();\nforkC();\n` }; + const head = { "p.ts": `${UP}forkA();\n` }; + const { ceilings } = shrink({ "p.ts": 3 }, base, head, { "p.ts": 3 }); + 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\.$/, + ); + assert.deepEqual(shrink({ "p.ts": 3 }, base, head, { "p.ts": 1 }), { + reasons: [], + ceilings: [], + rises: [], + 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/); + 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/, + ); + 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. + const swap = { "p.ts": `${UP}forkA();\nforkB();\nforkD();\n` }; + assert.deepEqual(shrink({ "p.ts": 3 }, base, swap, { "p.ts": 3 }).ceilings, []); + assert.deepEqual(shrink({ "p.ts": 3 }, base, head, undefined).ceilings, []); +}); + +test("the command line refuses a pull request that shrinks a pending file but keeps its ceiling", () => { + withRepo(({ git, commit, run }) => { + const config = { files: {}, pending: { "p.ts": 2 } }; + const main = commit({ ...seams(config), "p.ts": `${UP}forkA();\nforkB();\n` }, "main"); + git("checkout", "-q", "-b", "pr", main); + const pr = commit({ "p.ts": `${UP}forkA();\n` }, "move forkB out"); + const kept = run(main, pr); + 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/, + ); + assert.match( + kept.stderr, + /Lower each "pending" ceiling .* in this change's list where the line says so/, + ); + const lowered = commit(seams({ files: {}, pending: { "p.ts": 1 } }), "lower it"); + const result = run(main, lowered); + assert.equal(result.status, 0, result.stderr); + }); +}); + +// Two branches from one merge-base could each add the one listed copy of a seam line: each run +// judged its own branch from the merge-base, and main ended with two copies (#311 item 3). +test("from main, a listed copy the base branch already has since the merge-base is spent", () => { + const main = { "a.ts": BASE["a.ts"].replace(" a: 1,", " ...fork,\n a: 1,") }; + const options = (tip) => ({ + atBase: (file) => BASE[file], + atHead: (file) => main[file], + upstream: false, + atTip: (file) => tip[file], + }); + assert.deepEqual(findSeamBreaches(SEAM, options(BASE)), []); + assert.deepEqual(findSeamBreaches(SEAM, options(main)), [ + "a.ts: adds `...fork,` (the base branch has more copies than this branch's merge-base: update the branch from its 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 }), []); +}); + +test("the command line spends a seam copy another branch merged since the merge-base", () => { + withRepo(({ git, commit, run }) => { + const start = commit({ ...seams({ files: SEAM }), ...BASE }, "main"); + const withFork = { "a.ts": BASE["a.ts"].replace(" a: 1,", " ...fork,\n a: 1,") }; + git("checkout", "-q", "-b", "second", start); + const second = commit(withFork, "second branch adds it too"); + git("checkout", "-q", "--detach", start); + const first = commit(withFork, "first branch, merged"); + const result = run(first, second); + assert.equal(result.status, 1, result.stdout); + assert.match(result.stderr, /- a\.ts: adds `\.\.\.fork,` \(the base branch has more copies/); + assert.equal(run(start, second).status, 0); + }); +}); + +// Right after a rebase, fork-follow commits the list with each ceiling and count it found too high +// lowered (#325 item 1); it never raises one. +test("lowerList lowers and removes entries, keeps comments and order, and never raises", () => { + const text = `${JSON.stringify( + { + "//": "comment", + files: { "s.ts": { why: "w", added: ["x();"] } }, + pending: { "a.ts": 3, "b.ts": 2, "c.ts": 2, "e.ts": 4 }, + lost: { + "c.ts": { lines: 2, gone: 1 }, + "e.ts": { lines: 3, gone: 1 }, + "s.ts": { lines: 1, gone: 0 }, + }, + }, + null, + 2, + )}\n`; + const lowered = { + pending: new Map([ + ["a.ts", 1], + ["b.ts", 0], + ["c.ts", 0], + ["e.ts", 5], + ]), + lost: new Map([ + ["c.ts", { lines: 1, gone: 1 }], + ["e.ts", { lines: 4, gone: 0 }], + ["s.ts", { lines: 0, gone: 0 }], + ]), + }; + const result = lowerList(text, lowered); + 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 }, + // e.ts: only the count that fell is lowered. + lost: { "c.ts": { lines: 1, gone: 1 }, "e.ts": { lines: 3, gone: 0 } }, + }); + assert.equal(result.text, `${JSON.stringify(JSON.parse(result.text), null, 2)}\n`); + assert.deepEqual(result.changes, [ + 'c.ts: "lost" 2/1 -> 1/1', + 'e.ts: "lost" 3/1 -> 3/0', + 's.ts: "lost" 1/0 removed (no upstream line lost)', + 'a.ts: "pending" 3 -> 1', + 'b.ts: "pending" 2 removed (no fork line left)', + ]); + 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); +}); + +test("--lowered-list writes the lowered list after a rebase only, and only when it passes", () => { + withRepo(({ dir, commit, fromUpstream }) => { + const upstream = commit({ "p.ts": GUARD_BASE }, "upstream"); + const config = { files: {}, pending: { "p.ts": 3 }, lost: { "p.ts": { lines: 2, gone: 1 } } }; + const series = commit( + { ...seams(config), "p.ts": "import { x } from './x';\ndoSensitive();\nforkA();\n" }, + "fork series", + ); + const out = path.join(dir, "..", `${path.basename(dir)}-lowered.json`); + try { + const result = fromUpstream("--after-rebase", "--lowered-list", out, upstream, series); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /^Lowered: p\.ts: "lost" 2\/1 -> 1\/1$/m); + assert.match(result.stdout, /^Lowered: p\.ts: "pending" 3 -> 1$/m); + assert.deepEqual(JSON.parse(fs.readFileSync(out, "utf8")), { + files: {}, + pending: { "p.ts": 1 }, + lost: { "p.ts": { lines: 1, gone: 1 } }, + }); + // Committed, the next run has nothing to lower and writes nothing. + fs.rmSync(out); + const lowered = commit( + seams({ files: {}, pending: { "p.ts": 1 }, lost: { "p.ts": { lines: 1, gone: 1 } } }), + "lowered", + ); + const again = fromUpstream("--after-rebase", "--lowered-list", out, upstream, lowered); + assert.equal(again.status, 0, again.stderr); + assert.equal(fs.existsSync(out), false); + assert.doesNotMatch(again.stdout, /Lowered|Note/); + // A refused run writes nothing. + const rise = commit({ "p.ts": "doSensitive();\nforkA();\n" }, "loses another line"); + assert.equal(fromUpstream("--after-rebase", "--lowered-list", out, upstream, rise).status, 1); + assert.equal(fs.existsSync(out), false); + // Only after a rebase, from upstream, with a path. + for (const args of [ + ["--lowered-list", out, upstream, series], + ["--after-rebase", "--lowered-list", upstream, series], + ["--after-rebase", upstream, series, "--lowered-list"], + ]) { + assert.equal(fromUpstream(...args).status, 2, args.join(" ")); + } + assert.equal(fs.existsSync(out), false); + } finally { + fs.rmSync(out, { force: true }); + } + }); +}); diff --git a/docs/fork/updates.md b/docs/fork/updates.md index 304aa50acc8a5..3dea261fc36d8 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -59,12 +59,18 @@ watches; it changes nothing on the machine, and `0` turns it off. (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 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 - also lowers the ceiling in the same change). Right after a rebase, below the ceiling is only a - note in the run log and the run's summary: when upstream takes a fork line word for word, the - rebase drops it, and the ceiling could not have been lowered first. The next run, from the new - base, fails until a pull request lowers it. 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 + 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, + 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 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 @@ -75,9 +81,12 @@ watches; it changes nothing on the machine, and `0` turns it off. so keep each count small. Right after a rebase, a count or ceiling that rises came with the rebase, not a fork pull request: the refusal tells the operator to rebase by hand and raise it in the rebased series, or to push it and raise it with a list-only pull request to main - (fork-follow cannot commit it until #325 item 1). A pull request may drop a seam file's listed seam lines (no more - copies than listed) but lose no other line, and may not move a seam line: a moved copy of `}` - looks the same as upstream's (move one with two pull requests). In a pending file it cannot tell + (fork-follow lowers a count after a rebase, but never raises one). A pull request may drop a seam + file's listed seam lines (no more copies than listed) but lose no other line, and may not move a + seam line: a moved copy of `}` looks the same as upstream's (move one with two pull requests). + Dropped lines are counted by text, so where upstream has a listed line too (`}`), a pull request + may drop upstream's copy instead of the fork's and its run passes it; fork-follow, which counts + from upstream, refuses it unless the lines left read the same as with the fork's copy dropped. In a pending file it cannot tell upstream's lines from the fork's (moving a fork line out loses one), so there fork-follow counts them. A listed path that neither the base nor the head has (upstream renamed it) is a note: list both names until the old one is gone from the base. An upstream file @@ -91,8 +100,13 @@ watches; it changes nothing on the machine, and `0` turns it off. file as upstream's, also before the rebase that brings upstream's copy. For the same reason a pull request's run counts upstream's copies of a seam line against its allowance: a seam line upstream also has (`}`, `/**`) cannot be added by a pull request, only checked by - fork-follow, so keep seam lines specific. A branch made before fork-follow last rebased main - is refused with one "update the branch" error. Only `--from-upstream` (which fork-follow passes) + 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 + 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. - [`serverSettings.forkDefaults.test.ts`](../../apps/server/src/serverSettings.forkDefaults.test.ts) @@ -186,12 +200,33 @@ a list-only pull request to main once it is pushed (fork-follow's refusal says h rests on the owner's review, not on code: a pull request's own list is only parsed, so no check refuses one that adds a `pending` file or raises a ceiling or count. What the code does hold: -- A pull request's run is judged by main's list and reads no ceiling and no `lost` count: a pending - file may change but not grow, so a raised ceiling or count gives no pull request a line. A new +- A pull request's run is judged by main's list and reads no `lost` count, and a ceiling only to + refuse a change that shrinks a pending file without lowering it in its own list: a pending file + may change but not grow, so a raised ceiling or count gives no pull request a line. A new `pending` entry does loosen it: that file's lines may then change, though not grow in number. - From upstream, fork-follow refuses a ceiling or count above the real count ("lower it", or - "remove it" when none is left), so room nobody uses does not stay. Right after a rebase that is - only a note, and the next run refuses it. + "remove it" when none is left), so room nobody uses does not stay. Right after a rebase it lowers + it in a commit of its own on the rebased series instead (only lowers: a rise is refused). + +When the list or the files under it change, the check fails closed: + +- **No list, an empty one, or one it cannot read** (bad JSON, `{}` with no `files`, an unknown + key such as a newer check's): a pull request's run against a base without the list is refused + (open it against main); a branch whose merge-base has none is refused ("update the branch"); a + list it cannot read stops the run with a crash (exit 3), which fork-follow reports as a failed + check and pushes nothing. A pull request's own list that is malformed is refused too. +- **An old list** (from before `pending`, `lost` or `forkFiles` entries existed): a missing key is + empty, which is stricter, never looser: every fork line it does not list is refused. +- **An upstream file renamed or deleted**: a pull request that deletes or renames an upstream file + is refused (except the listed removed workflows); from upstream, a listed file upstream renamed or + deleted, which neither the base nor the series has any more, is a note (list both names until the + old one is gone from the base), and under its new + name it is an unlisted upstream file, held to no fork line; a `pending` file the base lacks is + refused. +- **Right after a rebase**: a ceiling or count that fell is lowered and committed into the series, + one that rose is refused with the operator's next step, and the next run judges the lowered list + from the new base. A re-run of the same rebase builds the same files (the lowering commit with + them), so it advances to a release an earlier run published from them. A pending file takes no new fork line (a pull request may change its lines but not add more, and a file cannot be in `files` and `pending`), so a new fork line goes in a seam file, after its lines From f0cb696ff7704a07f3a9748832a92a548a1beb8c Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:03:40 +0000 Subject: [PATCH 2/2] fork seams: shorten comments for the lint rule Co-Authored-By: Claude Opus 5.5 --- .github/scripts/fork-seam-check.cjs | 50 ++++++++++-------------- .github/scripts/fork-seam-check.test.cjs | 10 ++--- 2 files changed, 26 insertions(+), 34 deletions(-) diff --git a/.github/scripts/fork-seam-check.cjs b/.github/scripts/fork-seam-check.cjs index 44eedfe42fed7..d450a047a40e7 100644 --- a/.github/scripts/fork-seam-check.cjs +++ b/.github/scripts/fork-seam-check.cjs @@ -1,9 +1,7 @@ // Usage: [--config-ref ] | --from-upstream [--after-rebase [--lowered-list ]] . -// Refuses 's upstream-file changes beyond .github/fork-seams.json. A pull request's list is -// 's (or --config-ref's), never 's (its own is read only for "pending" ceilings it must -// lower); --from-upstream (fork-follow) reads 's, even if upstream has its own. --after-rebase: -// a ceiling above the count is a note, and --lowered-list writes the list with it lowered there. -// Reads git objects only (and writes only that file). +// Refuses 's upstream-file changes beyond .github/fork-seams.json: a PR uses 's list (its own only for +// "pending" ceilings it must lower); --from-upstream reads 's. --after-rebase notes a too-high ceiling and +// --lowered-list writes the lowered list. Reads git objects only (and writes only that file). const { execFileSync } = require("node:child_process"); const fs = require("node:fs"); @@ -151,12 +149,10 @@ function parseRemoved(text = "") { } /** - * Reasons for the seam files' lines: each listed line allows one copy more than `base` has (not from - * upstream, `base` is main, whose copies spent it). On `today` (a pull request's run: the list's - * commit date) an expired or dated-ahead announcement allows nothing: the copies it would allow in - * date go to `late`, any more to the reasons. `atTip` (a pull request's run: the base branch's tip) - * spends the allowance too: two branches from one merge-base cannot each add the one listed copy, - * once the first has merged (#311 item 3). + * Reasons for the seam files' lines: each listed line allows one copy more than `base` has (on a PR, main). + * On `today` (a PR's run: the list's commit date) an expired or dated-ahead announcement allows nothing; its + * in-date copies go to `late`. `atTip` (a PR's run: the base tip) spends the allowance too, so two branches + * from one merge-base cannot each add the one listed copy once the first has merged. */ function findSeamBreaches(files, { atBase, atHead, atTip, upstream = false, today, late }) { const reasons = []; @@ -259,11 +255,10 @@ const AFTER_REBASE_RISE = " after the rebase onto this base (upstream's own change did it, not a fork pull request): rebase by hand as docs/fork/updates.md says and raise the {count} in the rebased series before pushing it, or push it and then raise the {count} with a list-only pull request to main; fork-follow lowers a count after a rebase, but never raises one (raising one is the owner's review)."; /** - * 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 after a rebase: `rises`, the operator's); on a PR it may change but not grow, - * and one that shrinks lowers its ceiling in `ownPending` (the PR's own list) to match (#311). - * `lowered.pending` gets each ceiling a run from upstream finds too high: the count to lower it to. + * 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. */ function findUnlistedChanges( config, @@ -332,7 +327,7 @@ function findUnlistedChanges( } else if (added < ceiling) { // A ceiling left too high is room to swap upstream lines for fork lines later, and a note // in the nightly log is never seen: refuse, naming the fix (only noted right after a - // rebase, where fork-follow commits the lowered list into the series: #325 item 1). Only a + // rebase, where fork-follow commits the lowered list into the series). Only a // lower count goes to `lowered`: a rise is refused. lowered?.pending.set(file, added); (afterRebase ? notes : ceilings).push( @@ -349,12 +344,10 @@ function findUnlistedChanges( `${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 (fork-follow holds it there), so a change that moves fork lines - // out lowers it too. Left as it is, the next run from upstream refuses main for it, and the - // room left over would let a later change swap an upstream line for a fork line. The - // change's own list is read only for a lower ceiling: that is never a wider gate. This run - // cannot tell the fork's lines from upstream's here, so the text says both; an upstream - // line that goes is refused by the run from upstream ("lost" counts are held exact). + // 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)) { @@ -776,11 +769,10 @@ function ownListProblem(text) { } /** - * The list `text` with the ceilings and counts `lowered` names lowered ({ pending, lost }: Maps of - * file to count), 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 (removing it would leave - * the list malformed; the run after says so). Written with two-space JSON, as the list is, and - * parsed again before it is returned, so a lowered list is never one the check refuses. + * `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. */ function lowerList(text, lowered) { const raw = JSON.parse(text); @@ -950,7 +942,7 @@ function main(argv) { const late = []; const reasons = [ // A pull request's base is its base branch's tip: a listed copy another change has merged - // there since this branch's merge-base is spent (#311 item 3). + // there since this branch's merge-base is spent. ...findSeamBreaches(config.files, { atBase, atHead, diff --git a/.github/scripts/fork-seam-check.test.cjs b/.github/scripts/fork-seam-check.test.cjs index 2d5a1452f03f4..714e94697fa43 100644 --- a/.github/scripts/fork-seam-check.test.cjs +++ b/.github/scripts/fork-seam-check.test.cjs @@ -1326,7 +1326,7 @@ test("from upstream, deleting an upstream line already counted as re-indented is git("checkout", "-q", "-b", "pr", main); const pr = commit({ "p.ts": reindented.replace(" return deny();\n", "") }, "delete it"); // The pull request's run cannot tell upstream's lines from the fork's in a pending file, so it - // refuses a shrink that leaves the ceiling as it is (#311), saying to keep upstream's lines ... + // refuses a shrink that leaves the ceiling as it is, saying to keep upstream's lines ... const own = run(main, pr); assert.equal(own.status, 1, own.stdout); assert.match(own.stderr, /- p\.ts: "pending" with a ceiling of 1, .*keep upstream's lines/); @@ -1988,7 +1988,7 @@ test("the real list takes upstream's MarkdownFileLink.logic.test.ts for an upstr }); // A file named after an Object property read `lost[file]` from Object's prototype: its counts were -// undefined, nothing compares above undefined, and every upstream line it lost passed (#416 item 3). +// undefined, nothing compares above undefined, and every upstream line it lost passed. test("from upstream, a file named like an Object property is held to a lost count of 0", () => { for (const file of ["constructor", "toString", "__proto__"]) { const config = { pending: { [file]: 1 } }; @@ -2004,7 +2004,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 (#311). +// and the next run from upstream refused main for it. const shrink = (pending, base, head, ownPending) => findUnlistedChanges( { files: {}, pending, forkFiles: [] }, @@ -2069,7 +2069,7 @@ test("the command line refuses a pull request that shrinks a pending file but ke }); // Two branches from one merge-base could each add the one listed copy of a seam line: each run -// judged its own branch from the merge-base, and main ended with two copies (#311 item 3). +// judged its own branch from the merge-base, and main ended with two copies. test("from main, a listed copy the base branch already has since the merge-base is spent", () => { const main = { "a.ts": BASE["a.ts"].replace(" a: 1,", " ...fork,\n a: 1,") }; const options = (tip) => ({ @@ -2102,7 +2102,7 @@ test("the command line spends a seam copy another branch merged since the merge- }); // Right after a rebase, fork-follow commits the list with each ceiling and count it found too high -// lowered (#325 item 1); it never raises one. +// lowered; it never raises one. test("lowerList lowers and removes entries, keeps comments and order, and never raises", () => { const text = `${JSON.stringify( {