Skip to content

fork seam check: refuse spare seam copies (#311 items 7/8) - #621

Merged
scuttletoby merged 3 commits into
mainfrom
fix/311-seam-followups
Nov 20, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
fix/311-seam-followups

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Fixes #311

The last open point of #311 was items 7 and 8: the generic seam lines in apps/server/src/serverSettings.ts (};, settings = {, and so on). This PR closes the gap those lines left open. Items 1–6 and the comment were already fixed on main.

Status of each #311 point (checked against main)

Point Status
1. Deleted or moved lines in seam/pending files Already fixed by #380 (lost {lines, gone} counts, held exactly).
2. Indentation-only changes Already fixed by #380 (lines are compared with their indentation).
3. Two PRs from the same main point each use one allowance Already fixed by #506 (copies at the base tip are spent too).
4. Untested guards Already fixed by #380 and #436 (guard tests; mutation tests on the real list).
5. Upstream renames a listed file Already fixed by #380 (a listed path neither side has is a note).
6. Fork of this fork Already fixed by #380 (explicit --from-upstream, passed by fork-follow).
Comment: a shrinking pending file lowers its own ceiling Already fixed by #506 and #535 (exact ceiling in the same PR).
7 + 8. Generic pinned lines in serverSettings.ts Fixed here, by a new rule rather than by moving the code (see below).

What changed

The risk behind items 7 and 8 is that a generic listed line like }; is a free pass: the run lets the fork add as many copies as the list names. A listed copy the fork does not actually add is spare room, so a later change could add that line without announcing it.

  • From upstream (fork-follow's run): the run now refuses any listed added copy that the fork does not add over upstream. The refusal names the fix ("remove it from added" or "list it N×").
  • Right after a rebase: a spare copy is a note, not a refusal, because upstream may have taken the line word for word. fork-follow's lowering commit drops it (Lowered: a.ts: "added" 2 -> 1 lines (spare: ...)). It only ever lowers.
  • Pull request run: a PR that drops a listed seam line must drop it from its own list too, in the same change and exactly. Its own added must list main's copies less the copies it drops. Too many leaves spare room. Too few would fail the next run from upstream. Either way the refusal names the right count.
  • The list itself: main had exactly four spare copies in serverSettings.ts (};, settings = {, ...managed.defaults,, continueThreadsAfterServerUpdate: false,). They are removed, and the entry's why is updated. Main's list is now exact from upstream, and both --from-upstream <merge-base> HEAD and --config-ref origin/main origin/main HEAD exit 0.
  • Docs: docs/fork/updates.md describes the rule.

Why the serverSettings.ts lines are not moved out

State question (each case is tested)

  • Runs again: after the lowering commit, a rerun passes with no Lowered line and no Note.
  • Stopped half-way: the lowered list is committed only after the check on it passes. A run stopped earlier leaves the old list, and the next run refuses or lowers it again.
  • Old list with spare copies: refused from upstream, with the fix named. After a rebase it is lowered.
  • Empty or missing: a file missing on either side is skipped. A PR with no own list, or one that does not drop the line, is not judged by this rule. A listed announced line is never spare.

Tests that fail on the old code

Run against main's checker, 4 of the 91 tests fail; with this PR's checker all 91 pass:

  • the command-line test: main's checker lets fork-follow's run pass with a spare copy, and does not lower it after a rebase;
  • the three unit tests for findSpareSeamLines and the lowerList change, which do not exist on main.

Mutation checks: each new refusal and the lowering have a test that fails when the code is removed or loosened:

all 10 were killed:

  • no refusal from upstream;
  • a partial spare (2× listed, 1× added) let through;
  • the PR rule turned off, too few copies allowed, or too many copies allowed;
  • a line the PR does not drop judged anyway;
  • no lowering after a rebase;
  • a spare copy refused after a rebase instead of noted;
  • the refusals or notes not wired into main().

fork-follow.test.sh passes.

Overlap with #599 (#552)

#599 adds --upstream-base and changes findUnlistedChanges and main(). This PR adds a new function (findSpareSeamLines), a block in lowerList, an export, and a few lines plus the hint wording in main(). Expect small conflicts in main() and the hint text only. Neither PR changes the logic the other one adds.

No workflow files are changed.

General vs project

General: this is seam-check tooling that any fork using fork-seams.json gets. The only project-specific part is the list edit for this fork's serverSettings.ts.

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 20, 2026 07:07
- From upstream, a listed "added" copy the fork does not add over upstream
  is refused, naming the fix; right after a rebase it is a note and
  fork-follow's lowering commit drops it (only ever lowers).
- A pull request that drops a listed seam line drops it from its own list
  in the same change, exactly (main's copies less the dropped ones).
- fork-seams.json: the four spare serverSettings.ts copies go; the list is
  now exact from upstream.
- Docs and tests (unit, command line, after-rebase lowering, rerun).

Fixes #311

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Lens B review (read-only): SAFE to merge. The new rule only tightens the gate: it fails closed, it adds no upstream drift, and its refusals name the fix. There is one major gap. A spare copy can still reach main through a pull request, and it then stops fork-follow instead of being refused in that pull request. A follow-up is fine; it fits best with #599.

What I checked

  • CI: gh pr checks 621 is all green (the skips are the usual ones).
  • Tests: 91/91 pass. Against main's checker, exactly the 4 tests the PR names fail.
  • The 4 removed serverSettings.ts copies really are spare. At the upstream base of main (v0.1.11-nightly.20261119.4954), upstream has as many copies of each line as main does: }; 14/14, settings = { 1/1, ...managed.defaults, 1/1, continueThreadsAfterServerUpdate: false, 1/1. Main's list run through this PR's checker refuses exactly those 4. With the PR's list, --from-upstream <that tag> HEAD exits 0 and --config-ref origin/main origin/main HEAD exits 0. The generic lines that stay (}, ) {, /**, */) are each listed once, and the fork adds exactly one copy of each over upstream (71/70, 7/6, 1/0, 1/0).
  • Items 1–6 and the fork seam check: follow-ups from #277 round 2 (moved/deleted lines, indentation, rename, tests) #311 comment: fork seam check: #277 follow-ups (moved/deleted lines, indentation, guard tests, renames, --from-upstream) #380, fork seams: announce a new seam line, then add it; list guards and operator messages (#409, #432) #436, Refs #311, Fixes #325, Fixes #416: seam check follow-ups #506 and fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535 are merged on main, and the code is there: lost {lines, gone}, orderedLines keeps indentation, the atTip allowance, findListedGone, --from-upstream, the removed-workflows list read from the list's commit, and the exact pending ceiling.
  • Can a generic line still be added unannounced? No. In a PR run, a listed line's allowance is the listed count less main's (or the tip's) copies. With an exact list that is 0 for every line, and from upstream the count must now be exact. A moved or re-indented copy is still refused by lostLines. CRLF and blank lines are ignored by design (see minor 4).
  • fork-follow: the run before the rebase (seam_check "$base", no --after-rebase) refuses a spare copy. The run after the rebase notes it and lowers it. lowerList only removes added items, keeping the first used copies, and it skips files that are not its own keys. The lowered list is checked again, and the run stops if that check would lower anything more. The command-line test covers "runs again" (no Lowered, no Note).
  • Stops half-way: the list is written only on exit 0, and fork-follow commits it only after it is checked again. A run that stops leaves the old list, and the next run refuses it or lowers it again.
  • Missing files: a file missing on either side is skipped here and refused or noted elsewhere.
  • Mutants I tried myself: 7. 2 were killed: dropped taken as an absolute value, and over + 1 >= count. 5 survived. Two of those are equivalent: ?? Infinity → ?? 0, and Object.hasOwn → raw.files[file]. The other three are test gaps (minor 1).

Major

  1. A PR can still put a spare copy on main. Nothing refuses it until the next fork-follow, which then stops. .github/scripts/fork-seam-check.cjs:585: the PR rule checks only lines the change drops (if (dropped <= 0) continue;). A change that raises its own added without adding the line passes its own run. So does one that removes a line still in use from its list. findStaleSeamLines checks only that a line is present, and a generic line always is. I reproduced it in a scratch repo:

    • upstream has a.ts with };;
    • main lists forkA(); and adds it;
    • a list-only PR adds "};" to added → PR run exit 0;
    • --from-upstream <upstream> <pr head> → exit 1 ("added" lists \};`, but the fork adds no copy over upstream`).

    Before this PR that spare was silent slack. Now it fails closed, but it fails in the nightly fork-follow, not in the PR. That is the same "found one PR too late" pattern the fork seam check: follow-ups from #277 round 2 (moved/deleted lines, indentation, rename, tests) #311 comment asked to fix for ceilings. The PR body's line "Main's list is now exact from upstream" is kept true only by fork-follow, not by PR CI.

    A rule based only on the main→head delta cannot fix this: a list-only PR that fixes main's list is a legitimate change with no file delta. The clean fix needs the upstream base. Once fix(fork): check a moved seam entry's lines against upstream in CI #599 (--upstream-base, fetched only when the list is edited) lands, run the upstream branch of findSpareSeamLines (and the breach count) on the PR's own list against that base whenever the list is edited. Fine as a follow-up issue, ideally linked to fix(fork): check a moved seam entry's lines against upstream in CI #599.

Minor

  1. Untested branches; these mutants survive:
    • lowerList matching on item instead of item.trim() (fork-seam-check.cjs:1009). An indented added item would then never be lowered, and fork-follow would stop on "the list fork-follow lowered still lowers again". Add an indented item to the lowerList test.
    • Dropping the Math.max(0, …) in over (:566) and in want (:586). Only the messages change ("adds -1×", "list it -1×"), but no test covers the fork removing upstream copies of a listed line, or a PR dropping more copies than are listed.
  2. Stale branch: in a PR run, count comes from the list's commit (main's tip), while dropped and the own list come from the branch. If main's entry for that line changed after the branch's merge-base, the number in the message is right only after updating the branch, and the message does not say to update it. The serial merge chain updates branches, so the impact is low. A message like "(update the branch from main if main's list changed)", as findSeamBreaches already has, would help.
  3. Rollout to other forks: an older list that has spare copies is now refused by fork-follow's run before the rebase, which never lowers. Only the run after the rebase lowers. A fork that adopts this checker therefore gets one stopped run plus a list PR. That is fine, but say it in docs/fork/updates.md: run --from-upstream <upstream base> HEAD once and fix the list before updating the checker.
  4. Out of scope, but noted because the brief asked about blank lines: lineCounts and orderedLines ignore blank lines, so adding blank lines to any upstream file is never refused. This is by design for TS. In Markdown or YAML block scalars a blank line has meaning. No action needed in this PR.

Overlap with #599

The textual conflicts are only in main()'s argument plumbing and the hint text, as the PR body says. Neither PR changes logic the other adds. The two fit together: #599's exact added count for a file moved from pending uses the same counting as this PR's spare rule. That makes #599 the natural place for the major above.

🤖 Generated with Claude Code

@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (lens A, read-only): SAFE. Nothing blocking and nothing major. Three minor points and one note follow; none needs to hold the merge.

What I checked (head 77e3042)

  • fork seam check: follow-ups from #277 round 2 (moved/deleted lines, indentation, rename, tests) #311 items 1–6 and the follow-up comment are fixed on main by fork seam check: #277 follow-ups (moved/deleted lines, indentation, guard tests, renames, --from-upstream) #380, fork seams: announce a new seam line, then add it; list guards and operator messages (#409, #432) #436, Refs #311, Fixes #325, Fixes #416: seam check follow-ups #506 and fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535 (all merged). The code is there: lost counts, indent-aware orderedLines, the atTip spend, findListedGone, --from-upstream, and the exact pending ceiling in the same PR. Each has its own tests.
  • The 4 serverSettings.ts lines removed from the list really are spare. Counted (trimmed) at the upstream merge-base vs the PR head: }; 14/14, settings = { 1/1, ...managed.defaults, 1/1, continueThreadsAfterServerUpdate: false, 1/1, so the fork adds 0 of each. The other generic lines are exact: } +1, ) { +1, /** +1, */ +1, each listed once.
  • Real repo: with the PR's checker, --from-upstream <merge-base> HEAD and --config-ref origin/main origin/main HEAD both exit 0. --from-upstream <merge-base> origin/main (the old list) exits 1 and names exactly those 4 lines. No other seam file has a spare.
  • Tests: all 91 pass. With main's checker, exactly the 4 new tests fail. fork-follow.test.sh passes locally; CI runs it only in fork-follow.yml, not on PRs.
  • Mutants (each run against the whole test file): 9 tried, 8 killed. Killed: tolerate one spare, lower nothing, lowerList stops counting copies, a missing own entry read as main's, judge lines the PR does not drop, accept too few copies, refuse instead of note after a rebase, never set lowered.added. The one that survived is minor 3.
  • Generic lines (};, }, import …): with an exact list, a PR cannot add one. Its allowance is the listed count minus the copies already in the file, which is 0. From upstream, every copy over upstream must be listed. Blank lines are still ignored everywhere, as before this PR, and they carry no meaning outside block scalars and multi-line strings.
  • The lowering commit only removes lines. lowerList filters seam.added, and a line with no used entry is kept (?? Infinity). It never touches announced. fork-follow checks the lowered list again and stops if it would lower again.
  • State: fork-follow's pre-rebase run (no --after-rebase) still refuses a spare that main already has, so the after-rebase lowering only drops copies that the rebase itself removed. A rerun after the lowering commit is clean (tested). If fork-follow stops half-way, nothing is pushed. A missing or renamed file is skipped here, and the other checks still refuse or note it. Trailing whitespace and CRLF are trimmed the same way by lineCounts and lowerList. Duplicates are counted.

Minor

  1. .github/scripts/fork-seam-check.cjs:585: at PR time, only lowering added is checked, never raising it. Two kinds of PR can still leave main with a spare copy:

    • a step-2 PR that moves an announced line listed 2× into added but adds only 1 copy;
    • a list-only PR that puts a line straight into added.

    findStaleSeamLines (:661) only checks that each listed line is in the file at least once. Until the next fork-follow, any PR can spend that spare copy without announcing anything (allowance = listed minus copies in the file). If nobody spends it, fork-follow's pre-rebase run refuses main. Both lines were owner-reviewed, so the risk is small. Fix: where the PR's own added lists a line more often than main's list does, require the increase to equal the copies the change adds (head minus base). Or check against upstream with fix(fork): check a moved seam entry's lines against upstream in CI #599's --upstream-base.

  2. :584: drops are counted from the merge-base, but main's count comes from the tip. Suppose a branch drops the same copy that main already dropped (a cherry-pick or duplicate fix). fork-checks then asks for one copy too few. If the merge keeps the branch's list, main lists 0 but still has 1 copy. fork-tests' run on the merge commit does not notice (0 dropped vs HEAD^1), and the next fork-follow refuses main. Rare, and it fails closed. Fix: when the seam file at the base tip differs from the merge-base, ask the author to update the branch (as findSeamBreaches already hints), or count drops from the tip.

  3. :566: the Math.max(0, …) is untested (the one mutant that survived). Without it, a fork that removes more upstream copies than it adds gets "list it -1×" instead of "remove it". It only changes the message.

Note

CI: all required checks are green (gh pr checks 621).

🤖 Generated with Claude Code

@scuttletoby
scuttletoby merged commit ad3c0ae into main Nov 20, 2026
37 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fork seam check: follow-ups from #277 round 2 (moved/deleted lines, indentation, rename, tests)

1 participant