Skip to content

Seam check: count pending-file text changes from upstream; refuse duplicate keys and dropped announcements (#796, #813) - #939

Merged
scuttletoby merged 3 commits into
mainfrom
fix/seam-check-796-813
Nov 22, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
fix/seam-check-796-813

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 22, 2026 •

Copy link
Copy Markdown
Owner

What and why

Three gaps in .github/scripts/fork-seam-check.cjs:

  1. Seam check: the pull request check let through a change the fork-follow check refuses #796: a pending-file swap got through. A pull request's run counted fork lines from upstream only when the PR edited the list. In a pending file whose ceiling (and lost entry) was already reached, a PR could swap an upstream line for a fork line with its list unchanged: every count stayed the same, the PR's run passed, and fork-follow refused main after the merge (fork lines and lost counts rose). Fix: a PR that changes a pending file's text is now counted from upstream in its own run (fork-checks), against main's ceiling and lost entry, even with its list unchanged. Untouched pending files still need no upstream fetch. --no-upstream (fork-tests) prints a note, as for list edits.
  2. Seam list: refuse duplicate keys and dropped announced lines; #804 leftovers #813 part 1: duplicate keys. JSON.parse keeps the last of two equal keys. Only the PR's own list was checked for duplicates. Main's list, the merge-base's list and fork-follow's head list were parsed without the check, so a duplicate there was silently halved. Fix: parseConfig itself refuses a duplicate key, so every list read is checked. A bad list read at a commit names that commit, e.g. .github/fork-seams.json at <sha12>: duplicate key "a.ts" (...): merge them into one entry.
  3. Seam list: refuse duplicate keys and dropped announced lines; #804 leftovers #813 part 2: dropped announcements. A list from a branch made before an announcement merged could drop that announcement unseen (how the HO5 lines went missing). Fix: a PR that changes a file and whose list drops a line main's list announces, still in date, is refused. The line must stay under announced or move to added in the change that adds it. A list-only PR may still withdraw one on purpose, and an expired announcement may go in any change. The count is per copy: it only refuses copies the merge-base already had (or main's, when the merge-base list cannot be read).

docs/fork/updates.md now describes all three.

Not covered here (#813 part 3): the Settings → Fork note for threads not loaded in this window, and the thread-menu step-2 pull request. Neither is seam-check work; both stay open as follow-ups.

Tests (each fails without its fix)

The three new tests in .github/scripts/fork-seam-check.test.cjs, run against main's script without this change: tests 3, pass 0, fail 3.

  • The pending swap: the PR's run exited 0 (expected 1).
  • The duplicate key on main's list: exited 1 with only an unrelated refusal (adds import ...), never naming the key (expected exit 3 naming it).
  • The dropped announcement: exited 0 (expected 1).

After the fix, the full file passes: tests 117, pass 117, fail 0. One existing passing case ("dropped" in the step-2 test) now keeps main's in-date announcement in its list, because it had dropped it by accident. The duplicate-key message test now matches the shorter text.

Other checks:

  • node .github/scripts/fork-seam-check.cjs --config-ref origin/main origin/main HEAD → exit 0.
  • vp fmt --check → clean.

Note: fork-checks runs main's copy of the checker (pull_request_target), so these checks apply to later pull requests once this merges. This PR is judged by today's rules.

State question

  • A list with duplicates already on main: every PR's seam check now stops with exit 3, naming the commit and the key. That is no worse than before: fork-checks' "Test the check" step already fails every PR on main's list (it checks main's tree with the duplicate check). The fix is a PR to main that merges the two entries; its checks also read main's list, so the owner merges it past them. Getting a duplicate onto main is now hard. Each PR's own list is refused, and strict up-to-date checks mean a second PR adding the same key is re-run on a list that holds both. fork-follow now stops before pushing a head list with one.
  • A config ref that is missing or old: a missing ref, or one without the list, crashes with exit 3 as before; nothing is judged. An old ref (a rerun after main moved, or a branch behind main) is judged by that ref's list and that ref's commit date. The required checks are strict, so a PR must re-run on current main before it merges. If the merge-base list cannot be read, the drop check counts against main's list (stricter, never looser). A config ref without .github/fork-upstream.json, or with a bad URL, refuses a PR that changes a pending file's text ("cannot be counted"), the same as it already refuses list edits.
  • A rerun: gives the same answer for the same commits. Dates come from the config-ref commit, not the clock. Upstream is fetched again each run into a temporary ref that is deleted afterwards. The check writes nothing to the repository, so a run that stops half-way leaves nothing behind.

General vs project

General: the seam checker, its tests and its doc are fork tooling for any fork that pins its seams this way. No project facts are added; the upstream URL still comes from .github/fork-upstream.json.

Fixes #796
Part of #813 (parts 1 and 2; part 3 stays open in #813)

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 22, 2026 10:29
…licate keys and dropped announcements (#796, #813)

- A pull request that changes a pending file's text is now counted from
  upstream in its run, against main's ceiling and lost entry, even with its
  list unchanged. Swapping an upstream line for a fork line kept every count
  the run could see, so it passed and fork-follow refused it after the merge.
- Every list the checker reads (main's, the merge-base's, fork-follow's head)
  now refuses a duplicate key, naming the commit and the key. Before, only the
  pull request's own list was checked.
- A pull request that changes a file and whose list drops an in-date
  announcement on main's list is refused. A list-only pull request may still
  withdraw one, and an expired one may go in any change.
- Tests for each fix (each fails without it); docs updated.

Fixes #796
Fixes #813

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

Lint: comments keep the reason, not the issue number; the JSDoc of
findDroppedAnnouncements fits in four lines; readConfigAt's rethrow keeps
the original error as its cause.

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

Copy link
Copy Markdown
Owner Author

lens: merge-path · reviewer: lens agent (Opus 5.5) · read at: 2a2d3b6
covered: the diff of .github/scripts/fork-seam-check.cjs, its test file and docs/fork/updates.md; main() and the counting helpers it calls (findListedNotFork, findLostNotUpstream, readConfigAt, parseConfig); fork-checks.yml, fork-tests.yml and fork-follow.sh's seam_run/seam_check; the main ruleset; #796 and #813; the open pull requests that edit the list (#928, #525, #40)
checks: ran .github/scripts/fork-seam-check.test.cjs on the head: tests 117, pass 117, fail 0. Ruleset on main: required checks are strict (strict_required_status_checks_policy true), so a mergeable head contains main and its merged tree is the head's tree.
agreement with fork-follow: none found either way. The pending-file count uses the same functions fork-follow uses (addedLines for the ceiling, lostLines/gone for "lost", exact match both ways) from the same upstream commit main sits on, and with strict checks the head's tree is the tree fork-follow then reads, so a pending swap is refused by both forms (the new test shows both messages). A duplicate key now stops both (exit 3: fork-follow's seam_check fails closed as "crashed", every PR run stops naming the commit). The dropped-announcement refusal has no fork-follow side: an announced line is not in code yet, so dropping it never makes fork-follow refuse main; it only refuses PRs, which is the intent.
state: runs again: same answer for the same commits (the date is the config-ref commit's, upstream goes to a temp ref, nothing is written). Stops half-way: writes nothing. PRs open at merge time: fork-checks runs main's script, so they meet the new rules on their next run, and strict checks force that run before a merge; #928 keeps all six in-date announcements and touches no pending file; #525 and #40 sit on a merge-base without the list and are refused as stale already. Missing --config-ref: exit 3 as before. Old --config-ref (a re-run of an older event): judged by that commit's list and date, and strict checks still force a run on current main before a merge. Main's list today has no duplicate (readConfigAt on main parses). A duplicate already on main stops every PR and fork-follow run with exit 3 until a fix PR merges (fails closed). Network: a PR that edits any of main's 61 pending files now needs the upstream fetch; a failed fetch refuses ("cannot be counted"), so it fails closed and a re-run clears it.
blocker: none
major: the PR body says "Fixes #813", which closes #813 on merge, but part 3 of #813 (the Settings -> Fork note for threads not loaded in the window, and the thread-menu step-2 pull request from branch fork/mcp-profile-thread-menu) is not done here, and no other issue or PR tracks it (searched: no issue mentions it, no PR from that branch). Merged as is, that work loses its only tracker. Fix: "Part of #813" (or "Fixes #813 parts 1-2" without the closing keyword form), or file a follow-up issue for part 3 first and link it in the body.
minor: the list-only exemption (.github/scripts/fork-seam-check.cjs:1728) treats every list-only PR as dropping an announcement on purpose. #813 part 2 asks for a drop only when "the PR says it removes it". A list-only announcement PR (the most common list-only kind, like #807) whose author kept an older copy while resolving a conflict still drops another PR's announcement with no refusal and no warning. It is not a merge-path breach (fork-follow never refuses over it, and the JSON diff shows the lost lines to a reviewer), but a printed Warning for a list-only drop would cover the case the issue names. #813 part 2's "and on main after a merge" half is also not added; strict checks make the PR-side check enough except for an owner merge past the checks.
minor: .github/scripts/fork-seam-check.cjs:1531: the silent catch around parseConfig(ownList) now also swallows a duplicate key in an own list the PR did not edit (one that came from a merge-base whose main had a duplicate). ownConfig then stays undefined, so pendingEdited and the list-edit counts are skipped instead of refused. Not reachable while the required checks are strict (the merge-base is then main, which already stops with exit 3); a fail-closed branch there (refuse when ownList is defined but unparseable) would not rely on that.

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent · read at: 2a2d3b6
verdict: safe to merge
covered: the full diff of .github/scripts/fork-seam-check.cjs, its test file and docs/fork/updates.md, plus the code around it that these refusals depend on (findUnlistedChanges' pending branch, findLostLines, findListedNotFork, findLostNotUpstream, upstreamBase, the main() wiring), and the PR body
checks: ran .github/scripts/fork-seam-check.test.cjs on the head: 117 pass, 0 fail. Ran the 3 new tests against the merge-base's script: 0 of 3 pass, so each one fails without its fix. Parsed origin/main's current list with the new parseConfig: no duplicate key, so merging this does not stop every PR. Traced these shapes by hand through the PR run and the fork-follow run: a swap, a moved line, a re-indent, a line split, a swap for a second copy of an existing fork line, CRLF, a rename, a delete, a swap paired with an own-list raise of "lost", an expired announcement, a list-only withdrawal, and a branch from before the announcement
state: runs again: the same answer. Dates come from the config-ref commit and upstream from main's merge-base with upstream, never the tip or the clock; the temporary ref is deleted. Stopped half-way: the check writes nothing. Existing state: main's list parses clean today, and fork-follow's last run was green. Old state: a branch behind a rebase is already refused as stale, and a pending text edit on a branch that lacks main's upstream commit is refused with "update the branch". Empty or unreadable state: an unreadable merge-base list makes the drop check count against main's list, which is stricter. One fail-open edge is listed below as a minor
blocker: none
major: none
minor: .github/scripts/fork-seam-check.cjs:1589 the new pending count is skipped when ownConfig is undefined. That now also happens when the PR does not edit its list and the merge-base's list has a duplicate key: parseConfig throws at :1531, which it did not do before this PR. That skips the old ownPending ceiling check at :382 too. So a branch made while main had a duplicate (fixed on main since), and not updated, can still swap an upstream line in a pending file. Strict up-to-date checks close this before merge. Falling back to main's config when the list is unedited, or refusing "update the branch", would close it in the check itself
minor: .github/scripts/fork-seam-check.cjs:1247 the duplicate-key error names only the key, not where it is. A repeated "why", "added" or "since" inside one entry says duplicate key "why" with no file. A key repeated under "files" reads the same as one repeated under "pending". Adding the path (for example files["a.ts"].why) would make it precise. The tests cover only file-name keys
minor: tests: no case covers the drop check when the merge-base list cannot be read (the main's-list fallback, :1088), a pending text edit that also edits the list's ceiling or "lost", or a pending text edit with an unparseable own list. The code paths look right by reading, but nothing pins them

@scuttletoby

Copy link
Copy Markdown
Owner Author

override for head 2a2d3b6: the merge-path lens's only major was the PR body's "Fixes #813"; the body now says "Part of #813" and #813 lists what is left (#813 (comment)). No code changed. The code lens is safe; both lenses' minors are on #813 or need no change (the up-to-date required checks close the skipped-count cases).

@scuttletoby
scuttletoby merged commit 45fcf05 into main Nov 22, 2026
40 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.

Seam check: the pull request check let through a change the fork-follow check refuses

1 participant