Skip to content

fork seams: judge the route tree as generated output; announce the Fork settings page lines - #542

Merged
scuttletoby merged 4 commits into
mainfrom
fork-settings-page-gate
Nov 19, 2026
Merged

scuttletoby merged 4 commits into
mainfrom
fork-settings-page-gate

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

The fork's settings are moving to one Settings page, "Fork" (/settings/fork). This pull request clears the way for it. It is the gate pull request; the page itself comes in the stacked pull requests after it.

Problem

The seam check refuses a new settings route for two reasons:

  • The route tree. TanStack regenerates apps/web/src/routeTree.gen.ts. A fork route's block repeats lines upstream already has (getParentRoute: () => ChatSettingsRoute,, } as any)), and a pull request can never add a seam line that upstream also has.
  • The seam list. The new nav entry, label and search scope need seam lines. settingsSearch.ts was "pending" (it may not grow), and SettingsSidebarNav.tsx had no entry.

Fix

Route tree, judged as generated output. The seam check has a small GENERATED table: apps/web/src/routeTree.gen.ts → apps/web/src/routes/. In a change that also touches a route file, the tree is not judged line by line. In every other case the old rules still apply:

  • a change to the tree with no route change is a hand edit, refused line by line;
  • deleting the tree is still refused.

The skip also requires the proof test, apps/web/src/forkRouteTree.test.ts, to be present in the change. That test runs TanStack's real generator (the router plugin's own dependency) on the committed route files and requires the committed routeTree.gen.ts to match it byte for byte. So a hand edit to the tree fails CI even when a route file changed too.

The test reads both the routes and the tree from git HEAD, not the working tree. Every vite run, including the vitest run itself, rewrites the working-tree copy before any test reads it. I checked this: a hand edit in the working tree vanished at test start, and the same hand edit committed made the test red.

Why not regenerate inside the seam check? The seam check runs on bare checkouts with no node_modules (fork-checks and fork-tests' workflow job), so it cannot load the generator. Splitting the job keeps the seam check git-only, and the proof runs where dependencies are installed: the web unit tests.

Seam list. These are step 1 (announce) for the page's lines:

  • settingsSearch.ts moves from pending to a seam entry. Its two existing lines stay in added, and six lines are announced: the import, the SettingsPath member, the label, the nav entry in the Agents group, the search scope, and the reworded comment on the fork items' spread.
  • SettingsSidebarNav.tsx gets an entry announcing GitForkIcon, and its icon-table line.
  • forkFiles adds the page's route file, apps/web/src/routes/_chat.settings.fork.tsx, and the Review rules panel files. Those panel files are not fork-named, so until now a fix to them was judged as an upstream file.

docs/fork/updates.md says how the route tree is judged and what to do on a rebase conflict in it: take either side, regenerate, commit.

Tests

  • fork-seam-check.test.cjs gets a new case, "the route tree is judged as generated output…". It covers the upstream run and the PR run: a route change with the proof passes; a tree change alone is refused as 3 fork lines; a route change without the proof is refused; a deleted tree is refused. The case was red before the script change (the forked lines were refused) and is green after.
  • forkRouteTree.test.ts is green on main's routes and red on a committed hand edit (checked locally).
  • vp run check:changed: format, lint, knip, typecheck (42 packages) and the touched tests all pass. The seam check run as CI runs it (--config-ref origin/main origin/main HEAD) passes.

Upstream fit

No upstream source file changes. The changed files are the fork's CI script, its list, its docs and one new fork test. Upstream's routeTree.gen.ts stays generator output; this only stops the check from treating generated lines as hand-written ones.

General vs project

Nothing here is a setting. The page's own settings follow in the stacked pull requests.

Screenshot

None: no visible change.

State question

  • Runs again: the check reads git objects only; the same commits give the same answer.
  • Stops half-way: the test writes only to its own temp folder and removes it.
  • Old or empty state: a branch with no route change judges the tree exactly as before. A list without the new entries (an older main) refuses the new lines, as any unlisted line.

Stacked after this: PR A (the Fork page, the moved sections and usage pacing), then PR B (updates, handoff, playtest).

🤖 Generated with Claude Code

@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Head reviewed: 24fa692e. Read-only review: no pushes. Everything below was run in a fresh clone.

Verdict: 1 blocking finding. The seam-check side is correct, and the proof test does what it says. But the PR itself controls the proof's contents, so a PR can switch off its own guard.

BLOCKING

B1. A PR can weaken the proof test and hand-edit the route tree in the same change, and both gates pass. .github/scripts/fork-seam-check.cjs:302-304

fork-checks runs the seam script and the seam list from main (--config-ref "$DEFAULT_SHA"), so a PR cannot loosen the rules it is judged by. The new skip breaks that rule. It only checks that apps/web/src/forkRouteTree.test.ts exists at the PR head (atHead(generated.proof) === undefined). The PR head can edit that file, and the seam check does not judge it because the name is fork-named.

Reproduced on top of this branch. Each scenario is a branch with a hand edit getParentRoute: () => ChatSettingsRoute, // hand in routeTree.gen.ts, plus one new file apps/web/src/routes/-notes.md as the "route change" (TanStack ignores - files):

Scenario Seam check (--config-ref pr542 pr542 HEAD) vp test run src/forkRouteTree.test.ts
proof unchanged pass (rc=0) red: diff shows // hand (good)
proof changed to it.skip(...) pass (rc=0) 1 skipped: green
proof replaced with it("ok", () => {}) pass (rc=0) 1 passed: green
proof deleted refused (good) n/a

So "hand edit + token route file + neutered proof" merges with every check green.

The impact is limited: vite rewrites the working-tree copy, so the edit never reaches a build. It does leave a committed upstream file that is not generator output, which this PR says cannot happen. The fix is a few lines and keeps the main-pinned model.

Fix: on a PR run, take the skip only when the proof is unchanged against main. Otherwise judge the tree line by line, or refuse with "change forkRouteTree.test.ts in its own PR". For example:

if (atHead(generated.proof) === undefined || (!upstream && atBase(generated.proof) !== atHead(generated.proof))) reasons.push(...)

The upstream run has no proof at its base, so it keeps the presence check. There it judges the head's own script and list anyway. Add a case to the new test: route change + changed proof → refused.

(Residual, not counted: a PR can also edit fork-tests.yml to drop Test Web. That trust model already covers every fork test, but before this PR the seam check did not depend on any of them. A follow-up could pin the proof's job the way fork-contracts.test.py pins others.)

SHOULD-FIX

S1. The test copies the router plugin's options instead of reading them. apps/web/src/forkRouteTree.test.ts:54-61 vs apps/web/vite.config.ts:334 (tanstackRouter({ autoCodeSplitting: true }))

The test builds its config from three hard-coded keys and the generator's defaults. Dev and builds use whatever vite.config.ts passes. Today they agree: green on this head and on #543.

Failure scenario: upstream adds a tree-shaping option such as quoteStyle, semicolons or routeFileIgnorePattern. After the nightly rebase, vp run dev and the build write one tree, the test expects another, and main's Test Web goes red. Every PR touching web is then red. The documented fix, "regenerate (vp run dev), commit", reproduces the tree the test rejects.

Either read the plugin's options from the vite config, or have the test also fail with a clear message when vite.config.ts's tanstackRouter(...) call differs from the options it assumes.

S2. The state question "generator bump / clean rebase" is not covered by the docs. docs/fork/updates.md:100

The docs only cover a rebase conflict in the tree. When upstream bumps @tanstack/router-plugin and changes the generator's output, the fork's route block can rebase cleanly in the old shape. fork-follow then pushes after the seam check only, which passes because the tree is skipped. forkRouteTree.test.ts goes red on main, not on a PR. This fails closed, which is right, but main stays red until someone regenerates.

Add to the same paragraph: "also when forkRouteTree.test.ts fails after a rebase or a router bump: regenerate and commit, in a list-free PR". If fork-follow can run this single test before pushing, even better.

NIT

N1. The new seam-check case does not pin the trailing slash of source. .github/scripts/fork-seam-check.test.cjs:213

Mutation test: changing other.startsWith(generated.source) to startsWith("apps/web/src/routes") (no slash) keeps the case green. Then a hand edit plus a token file in apps/web/src/routes-x/ would take the skip. The real script refuses that today (checked: hand edit + src/routes-x/a.ts → refused, rc=1), but nothing would catch a regression. Add a sibling-folder change that must still be judged line by line.

N2. settingsSearch.ts's added keeps two lines that #543 replaces. .github/fork-seams.json:177-179

The old import and ...FORK_SETTINGS_SEARCH_ITEMS, // Fork: waits and agent slots. go away in #543, so after it they are listed-but-gone (a note). Fine for the announce step; drop them when the announced lines move into added.

Checked and fine

  • Seam-check tests: node --test .github/scripts/fork-seam-check.test.cjs: 75/75 pass.
  • Seam check as CI runs it:
  • Seam-check mutations: all go red except N1:
    • removing the proof refusal;
    • dropping the "route changed" condition;
    • deleting the whole skip.
  • Refusals that hold:
    • a tree hand edit alone → refused as a fork line;
    • a hand edit + token edit in an upstream route → the route edit itself is refused;
    • a deleted tree → refused;
    • a deleted proof → refused;
    • a src/routes-x/ sibling → judged line by line.
  • forkRouteTree.test.ts runs:
  • The test runs in a required job:
    • it is matched by the unit project (src/**/*.test.ts);
    • Test Web runs whenever @t3tools/web changes, so on any routes/ change;
    • Test Web is part of fork-ci-result;
    • on a PR, the checkout's HEAD is the merge commit, so the merged result is tested.
  • Seam list is minimal:
  • State question:
    • runs again: git objects only, so the same answer;
    • stops half-way: the test's temp folder is removed in finally;
    • empty state: on main without the test file, any route + tree change is refused with a clear message;
    • a PR that only deletes a route takes the skip, and the test judges the result.

Blocking findings: 1

@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix round for the review above. Head: dafa4c76.

  • B1 (blocking): fixed. On a pull request the tree is skipped only while forkRouteTree.test.ts is byte-identical to main's copy, meaning the list's commit (--config-ref, which is github.sha in fork-checks). Otherwise the tree is judged by the normal line rules, and the refusal says why ("…is not main's, so it proves nothing"). From upstream only the presence check stays, because upstream has no proof to compare with. New cases: route + weakened proof → refused; a branch made before main changed the proof → refused until updated. Plus a command-line case that pins main()'s wiring. All of these were red before the fix, and they are red again under each mutation: comparison removed, compared with the merge-base, wiring dropped.
  • S1: fixed. The test reads the options from the tanstackRouter(...) call in vite.config.ts and from tsr.config.json if one is committed. It passes them through the plugin's own getConfig, the one vite uses. It also checks that the seam check's GENERATED table names the same tree and routes folder. Checked: adding quoteStyle: "double" with a stale tree → red; regenerated → green; a non-literal tanstackRouter(routerOptions) → red with a clear message.
  • S2: fixed in docs/fork/updates.md. One correction: fork-follow does not push to main after the seam check alone. Its release runs every Linux job, Test Web included, before the series branch moves. So a router bump stops the run on this test and main stays green. The fix: rebase by hand, regenerate, commit into the series. A PR that changes only the tree would be refused line by line. I also added the test to the runbook's pre-push list.
  • N1: fixed. A sibling apps/web/src/routes-x/ change is judged line by line. Dropping the slash turns the case red.
  • N2: left as is. Both settingsSearch.ts lines are still on this branch, so neither is stale yet. They go stale when feat(web): Settings page "Fork" with the fork's agent and review settings, and usage pacing rows #543 merges; drop them then.

State question:

  • Runs again: git objects only, so the same answer.
  • Stops half-way: only the test's temp folder is written, and it is removed in finally.
  • Old/empty state: main without the proof (before this PR merges) has no skip at all. The first PR after the merge passes while it leaves the proof alone. From upstream, only the presence check applies.

Run: seam-check tests 76/76; seam check as CI runs it (main's list and this branch's list) and --from-upstream 8cf97b5f, all pass; vp run check:changed (format, lint, knip, typecheck, touched tests) passes.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Fixed the red Lint check (fork-owned-reads.test.py: app code read .github/scripts/fork-seam-check.cjs). That's a real read, so it doesn't belong in NOT_READS: a fork-only change to the script would skip the app job that reads it. The check that GENERATED names the right route tree and routes folder now lives in fork-seam-check.test.cjs. That test reads apps/web/vite.config.ts's tanstackRouter(...) options, and tsr.config.json if present, and also checks that the files and proof exist and the folder ends with /. forkRouteTree.test.ts no longer opens the script. It now pins the plugin's resolved paths as literals. The rest is unchanged: the main-identical proof gate, settings read from vite.config.ts, and the trailing-slash pin. Run locally and passing: fork-owned-reads.test.py, seam-check tests (77), the proof test, lint, vp check, knip, typecheck. Head 73796c2.

scuttletoby and others added 3 commits November 19, 2026 19:19
…rk settings page lines

A fork route makes TanStack's generator add lines to apps/web/src/routeTree.gen.ts that repeat
upstream's own (`} as any)`), which no seam entry can list. The seam check now skips that file's
line rules when the same change touches apps/web/src/routes/, and a new fork test,
apps/web/src/forkRouteTree.test.ts, runs the generator on the committed routes and requires the
committed tree to match, so a hand edit is still refused. A tree change without a route change is
judged line by line as before, and the skip needs the proof test in the change.

The list announces the lines the Fork settings page needs: settingsSearch.ts moves from "pending"
to a seam entry (its two lines kept, six announced), SettingsSidebarNav.tsx gets an entry for its
icon, and the page's route file and the Review rules panel files become fork files.

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

On a pull request the seam check skipped routeTree.gen.ts whenever the proof test existed at the
head, so a change could hand-edit the tree and weaken forkRouteTree.test.ts in the same commit.
The skip now also needs the proof to be byte-identical to the list's commit (main); otherwise the
tree is judged line by line and the refusal says why. From upstream the presence check stays.

forkRouteTree.test.ts reads the router plugin's options from vite.config.ts's tanstackRouter(...)
call (and tsr.config.json) through the plugin's own getConfig, and checks that the seam check's
GENERATED table names the same tree and routes folder. A call that is not a plain literal fails
with a clear message.

docs/fork/updates.md: a router bump or a new option that rebases cleanly but stops fork-follow's
release tests on this test; the fix is regenerating in the rebased series, not a tree-only PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The route-tree proof test read .github/scripts/fork-seam-check.cjs to compare its
GENERATED table with the router plugin's paths. App code must not read a fork-owned
file (fork-owned-reads.test.py): a fork-only change to the script would skip the app
job that reads it. That is a real read, not a name NOT_READS may excuse.

So fork-seam-check.test.cjs now reads apps/web/vite.config.ts (and tsr.config.json if
present), resolves the routes folder and tree, and checks GENERATED names them, that
the files and proof exist and the folder ends with /. The proof test no longer opens
the script; it pins what the plugin resolves vite.config.ts's options to
(apps/web/src/routes/, apps/web/src/routeTree.gen.ts), so a change to either side
fails the test its own jobs run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby
scuttletoby force-pushed the fork-settings-page-gate branch from 73796c2 to c50b20a Compare November 19, 2026 18:39
@scuttletoby

Copy link
Copy Markdown
Owner Author

Rebased onto main (after #535 and #540); #543 and #544 rebased on top with --onto. New heads: #542 c50b20a8ed, #543 b184d4f4b8, #544 44db49be6d.

Text conflicts

Semantic conflict with #535 (not fixed here, needs a decision)
Main's seam check refuses this PR:

settingsSearch.ts: "pending" with a ceiling of 2 … moves it to "files" … 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").

#535 lets a pending file move to "files" only when it has no fork line left, even when the new seam entry lists those lines in added, as this one does. #543 can't grow a pending file, and a file can't be in both lists. So no change to the list alone can pass. The checker's rule on main has to allow moving a file that is pinned with its lines listed, or #542 has to be merged over this one check.

Route tree
routeTree.gen.ts is covered. I ran main's script the way CI does, with this branch as main. #543 (base: this branch) and #544 then pass "Fork lines in upstream files": the tree is skipped as generated because #543 changes a route and leaves forkRouteTree.test.ts as it is.

Local checks on all three branches: typecheck, lint, vp fmt --check, the seam/schema/upstream-files node tests, forkRouteTree.test.ts, and the changed unit tests (settings/fork, settings, forkReport, contracts). All pass. I didn't run the browser tests.

@scuttletoby
scuttletoby merged commit 83f76bd into main Nov 19, 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.

1 participant