Skip to content

Commit 61f197e

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): a conflict on a generated file reruns its generator (#1500)
## Problem A sync rebase stopped on a conflicted generated file (`pnpm-lock.yaml`, `apps/web/src/routeTree.gen.ts`) or on the license list both sides append to. Each stop cost a manual run, and a hand-merged lockfile could land. ## Change The stop loop routes these paths through `REGENERATION_ROUTES` in `scripts/fork-sync.ts`, in table order, once every other path in the stop resolves. | Path | Resolver | | --- | --- | | `pnpm-lock.yaml` | `vp install --lockfile-only` in the sync worktree | | `third-party-licenses.config.json` | merge by package name, then `vp fmt` | | `apps/web/src/routeTree.gen.ts` | `vp run fork:regenerate-route-tree <worktree>` from the trunk install | | Rule | Behavior | | --- | --- | | Generators | restore from `HEAD`, rerun, stage | | License merge | three-way union keyed on `name` (`scripts/lib/fork-license-merge.ts`) | | Entry order | upstream's, then the fork's additions | | Refusal | one entry changed on both sides, or deleted vs changed | | Failure | a `manual` row naming resolver and error | | Mixed stop | resume hint says rerun, not `rebase --continue` | | Runbook | `## Regenerable files` in `docs/fork/operations/fork-sync.md` | ## Scope and approval Closes #1488 - [ ] **Lockfile:** a conflicted fixture regenerates - [ ] **License list:** both appends survive - [ ] **Guard:** a test fails on an unrouted path - [ ] **Runbook:** lists every generated path Merge by package name was the maintainer's pick (option A) for the license list. ## Verification ```text vp test run --config vite.config.ts scripts/fork-sync.test.ts scripts/lib/fork-license-merge.test.ts → exit 0 (62 passed) vp test run --config vite.config.ts scripts/fork-gate-headers.test.ts → exit 0 vp run --filter @t3tools/scripts typecheck → exit 0 vp lint <touched scripts> → exit 0 (2 existing warnings) vp run fork:delta --check → exit 0 vp run fork:ci → exit 0 (705 scripts tests) ``` | Proof | Test | | --- | --- | | Lockfile | both sides relock; generator sees upstream's copy; rebase continues | | License list | both sides append; trunk keeps both | | Guard | an unrouted generated path the fork carries fails | | Runbook | table drift from the routes fails | | Mutation | dropping the route-tree route fails guard and parity | Model and harness: Claude Opus 5.5 in Claude Code (T3 Code). ## Fork trailers Squashes: - 930bc7d fix(fork-sync): a conflict on a generated file reruns its generator (#1500) (#1500) - 4f79876 fixup! fix(fork-sync): a conflict on a generated file reruns its generator (#1500) (#1500) Fork-Domain: fork-meta Fork-Tier: core Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent aafd1e1 commit 61f197e

7 files changed

Lines changed: 596 additions & 16 deletions

File tree

‎.agents/skills/fork-sync/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ Only a `manual` row stops the run.
9292

9393
In the rebase, resolve minimally: upstream's text stands, and a marked fork hook goes back verbatim.
9494
Upstream deleted and the fork edit is net-zero: the deletion stands.
95+
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates; when one is pending, skip `git rebase --continue` and rerun.
9596
Never adapt inside a replayed commit: the hook guard refuses it.
9697
Adaptation lands once, in one `Fork-Repair` commit at the tip; [`/fork-fold`](../fork-fold/SKILL.md) dissolves it afterward.
9798

‎docs/fork/operations/fork-sync.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,8 @@ Conflict resolution is machine-owned, in this order.
8383
| 1 | Local rerere replays resolutions within the run's rebase and stages them |
8484
| 2 | Hook re-apply re-inserts the marked fork hooks a conflicted file declares, from the fork side onto the upstream text |
8585
| 3 | An upstream delete of a path whose fork trunk blob still equals the base blob (a net-zero fork edit) is accepted with `git rm` |
86-
| 4 | Anything left is a `manual` row and stops the run |
86+
| 4 | A [regenerable file](#regenerable-files) regenerates once every other path in the stop resolves |
87+
| 5 | Anything left is a `manual` row and stops the run |
8788

8889
Only upstream moved: upstream's text stands.
8990
A marked fork hook goes back in verbatim.
@@ -113,6 +114,8 @@ Never post a block to `pingdotgg/t3code`.
113114
5. `git rebase --continue`.
114115
6. Rerun `vp run fork:sync <tag>`.
115116

117+
A pending regenerable file refuses step 5; skip it, and the rerun regenerates the file and continues.
118+
116119
Rerere replays content resolutions but records nothing for a delete/modify: the fix is a driver rule or a pre-adopt commit on `hyprws` (precedent `72666ffe19`, RSI-Software/t3code-hyprws#1227).
117120

118121
**Reshape.** Resolve minimally in the rebase: upstream's text plus marked hooks verbatim.
@@ -132,11 +135,18 @@ A run that fails on a non-blocked step (target, fetch, rebase, check, push, or a
132135

133136
## Regenerable files
134137

135-
A sync keeps the new base's version and reruns the generator after applying fork source inputs.
138+
On a conflict, the driver resolves each path and stages the result, in table order.
139+
A generator reruns over the resolved sources, from the path's `HEAD` copy.
140+
The package-name merge keeps both sides' entries: upstream's order, then the fork's additions.
141+
A failed resolver leaves a `manual` row naming the failure.
142+
143+
| Path | Resolver | Runs from |
144+
| ---------------------------------- | ----------------------------------- | ---------------------------- |
145+
| `pnpm-lock.yaml` | `vp install --lockfile-only` | The sync worktree |
146+
| `third-party-licenses.config.json` | merge by package name | The driver, then `vp fmt` |
147+
| `apps/web/src/routeTree.gen.ts` | `vp run fork:regenerate-route-tree` | The trunk checkout's install |
136148

137-
| Path | Generator | Rebase rule |
138-
| ---------------- | ---------------------------- | ----------------------------------------------------------------- |
139-
| `pnpm-lock.yaml` | `vp install --lockfile-only` | Restore from `HEAD`, resolve sources, regenerate, stage, continue |
149+
`REGENERATION_ROUTES` in `scripts/fork-sync.ts` owns the rows; a test fails when this table drifts from it, or when the fork carries a generated path neither routes.
140150

141151
On a branch that changes a package manifest, regenerate the lockfile before pushing, so a hand-merged lockfile fails there instead of costing a sync run.
142152

‎scripts/fork-sync.test.ts‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ import {
2121
realRunner,
2222
rebaseOnto,
2323
readReport,
24+
REGENERATION_ROUTES,
25+
resolverText,
2426
renderReport,
2527
reportPath,
2628
run,
@@ -32,6 +34,7 @@ import {
3234
import { deriveCiTestJobs, workflowJobIds } from "./lib/fork-ci-jobs.ts";
3335
import { FORK_CI_WORKFLOW_PATH } from "./lib/fork-ci-flags.ts";
3436
import { runCommand, type CommandResult } from "./lib/fork-command.ts";
37+
import { GENERATED_HOOK_PATH } from "./lib/fork-hook-guard.ts";
3538

3639
const ok = (stdout = ""): CommandResult => ({ status: 0, stdout, stderr: "" });
3740
const refused = (stderr: string): CommandResult => ({ status: 1, stdout: "", stderr });
@@ -85,6 +88,8 @@ const fixture = (options: {
8588
readonly upstreamContent: string;
8689
/** Base file both sides start from; defaults to the legacy line fixture. */
8790
readonly baseContent?: string;
91+
/** Further files the base commit carries, by repo-relative path. */
92+
readonly baseFiles?: Readonly<Record<string, string>>;
8893
/** The fork branches from the tagged upstream commit instead of its base. */
8994
readonly forkOnTag?: boolean;
9095
readonly nightlyTag?: boolean;
@@ -112,6 +117,8 @@ const fixture = (options: {
112117
options.baseContent ?? "line1\nline2\nline3\n",
113118
);
114119
writeWorkflow(repo);
120+
for (const [path, content] of Object.entries(options.baseFiles ?? {}))
121+
NodeFS.writeFileSync(NodePath.join(repo, path), content);
115122
git(["add", "."], repo);
116123
git(["commit", "--quiet", "-m", "base"], repo);
117124
git(["remote", "add", "origin", origin], repo);
@@ -639,6 +646,210 @@ it("still blocks when the fork side deleted the path and upstream modified it",
639646
);
640647
});
641648

649+
// ---------------------------------------------------------------------------
650+
// Regenerable files
651+
// ---------------------------------------------------------------------------
652+
653+
const LOCKFILE = "pnpm-lock.yaml";
654+
655+
const lockfileFixture = (shared: { readonly fork: string; readonly upstream: string }) =>
656+
({
657+
forkContent: shared.fork,
658+
upstreamContent: shared.upstream,
659+
baseFiles: { [LOCKFILE]: "lock: base\n" },
660+
}) as const;
661+
662+
/** The fork's newest commit and a new upstream tag `v2.0.0` each rewrite `path`. */
663+
const changeBothSides = (
664+
f: Fixture,
665+
path: string,
666+
sides: { readonly fork: string; readonly upstream: string },
667+
): void => {
668+
NodeFS.writeFileSync(NodePath.join(f.root, path), sides.fork);
669+
f.git(["commit", "--quiet", "--amend", "--no-edit", "-a"], f.root);
670+
f.git(["push", "--quiet", "--force", "origin", "hyprws"], f.root);
671+
f.git(["checkout", "--quiet", "main"], f.root);
672+
NodeFS.writeFileSync(NodePath.join(f.root, path), sides.upstream);
673+
f.git(["commit", "--quiet", "-am", `upstream rewrites ${path}`], f.root);
674+
f.git(["tag", "v2.0.0"], f.root);
675+
f.git(["push", "--quiet", "upstream", "main", "v2.0.0"], f.root);
676+
f.git(["checkout", "--quiet", "hyprws"], f.root);
677+
};
678+
679+
const relockBothSides = (f: Fixture): void =>
680+
changeBothSides(f, LOCKFILE, { fork: "lock: fork\n", upstream: "lock: upstream\n" });
681+
682+
/** A lockfile generator stub that records the text it regenerated from. */
683+
const lockfileGenerator = (f: Fixture, seen: string[]) => (args: ReadonlyArray<string>) => {
684+
if (args[0] !== "install" || args[1] !== "--lockfile-only") return ok();
685+
const path = NodePath.join(f.worktree, LOCKFILE);
686+
seen.push(NodeFS.readFileSync(path, "utf8"));
687+
NodeFS.writeFileSync(path, "lock: regenerated\n");
688+
return ok();
689+
};
690+
691+
it("regenerates a conflicted lockfile from HEAD and continues the rebase", () => {
692+
withFixture(
693+
lockfileFixture({ fork: "fork line1\nline2\nline3\n", upstream: "line1\nline2\nline3 up\n" }),
694+
(f) => {
695+
relockBothSides(f);
696+
const seen: string[] = [];
697+
const { runner } = exec({ vp: lockfileGenerator(f, seen) });
698+
const code = capture(() => run(["v2.0.0", "--dry-run"], { runner, root: f.root })).value;
699+
assert.strictEqual(code, 0);
700+
const report = readReport(f.root, "v2.0.0");
701+
assert.strictEqual(report.outcome, "applied");
702+
assert.deepStrictEqual(
703+
report.conflicts.map(({ path, via, reason }) => ({ path, via, reason })),
704+
[
705+
{
706+
path: LOCKFILE,
707+
via: "regenerate",
708+
reason: "regenerated by vp install --lockfile-only",
709+
},
710+
],
711+
);
712+
// The generator ran over upstream's lockfile, never a merged one.
713+
assert.deepStrictEqual(seen, ["lock: upstream\n"]);
714+
assert.strictEqual(
715+
f.git(["show", `${report.trunk.after}:${LOCKFILE}`], f.root),
716+
"lock: regenerated",
717+
);
718+
},
719+
);
720+
});
721+
722+
it("holds a generated path until the stop's manual paths resolve, then regenerates it", () => {
723+
withFixture(
724+
lockfileFixture({ fork: "line1\nline2 fork\nline3\n", upstream: "line1\nline2 up\nline3\n" }),
725+
(f) => {
726+
relockBothSides(f);
727+
const seen: string[] = [];
728+
const first = exec({ vp: lockfileGenerator(f, seen) });
729+
assert.strictEqual(
730+
capture(() => run(["v2.0.0", "--dry-run"], { runner: first.runner, root: f.root })).value,
731+
1,
732+
);
733+
const blocked = readReport(f.root, "v2.0.0");
734+
assert.deepStrictEqual(blocked.decision.paths, ["shared.txt"]);
735+
assert.notMatch(blocked.decision.resume, /rebase --continue/);
736+
assert.match(blocked.decision.resume, /the rerun regenerates pnpm-lock\.yaml/);
737+
assert.deepStrictEqual(seen, []);
738+
739+
NodeFS.writeFileSync(NodePath.join(f.worktree, "shared.txt"), "line1\nline2 both\nline3\n");
740+
f.git(["add", "shared.txt"], f.worktree);
741+
const second = exec({ vp: lockfileGenerator(f, seen) });
742+
assert.strictEqual(
743+
capture(() => run(["v2.0.0", "--dry-run"], { runner: second.runner, root: f.root })).value,
744+
0,
745+
);
746+
const applied = readReport(f.root, "v2.0.0");
747+
assert.deepStrictEqual(
748+
applied.conflicts.map(({ path, via }) => ({ path, via })),
749+
[{ path: LOCKFILE, via: "regenerate" }],
750+
);
751+
assert.strictEqual(
752+
f.git(["show", `${applied.trunk.after}:${LOCKFILE}`], f.root),
753+
"lock: regenerated",
754+
);
755+
},
756+
);
757+
});
758+
759+
it("blocks on a generated path whose generator fails, naming the failure", () => {
760+
withFixture(
761+
lockfileFixture({ fork: "fork line1\nline2\nline3\n", upstream: "line1\nline2\nline3 up\n" }),
762+
(f) => {
763+
relockBothSides(f);
764+
const { runner } = exec({
765+
vp: (args) =>
766+
args[1] === "--lockfile-only" ? refused("ERR_PNPM_NO_MATCHING_VERSION") : ok(),
767+
});
768+
assert.strictEqual(
769+
capture(() => run(["v2.0.0", "--dry-run"], { runner, root: f.root })).value,
770+
1,
771+
);
772+
const report = readReport(f.root, "v2.0.0");
773+
assert.deepStrictEqual(report.decision.paths, [LOCKFILE]);
774+
const row = report.conflicts[0]!;
775+
assert.strictEqual(row.via, "manual");
776+
assert.match(row.refuseReason ?? "", /^vp install --lockfile-only failed: ERR_PNPM/);
777+
},
778+
);
779+
});
780+
781+
const LICENSES = "third-party-licenses.config.json";
782+
783+
const licenseList = (...names: ReadonlyArray<string>): string =>
784+
`${JSON.stringify({ customNotices: names.map((name) => ({ name, license: "MIT" })) }, null, 2)}\n`;
785+
786+
it("merges both sides' license list appends by package name and continues the rebase", () => {
787+
withFixture(
788+
{
789+
forkContent: "fork line1\nline2\nline3\n",
790+
upstreamContent: "line1\nline2\nline3 up\n",
791+
baseFiles: { [LICENSES]: licenseList("base") },
792+
},
793+
(f) => {
794+
changeBothSides(f, LICENSES, {
795+
fork: licenseList("base", "fork-added"),
796+
upstream: licenseList("base", "upstream-added"),
797+
});
798+
const formatted: string[] = [];
799+
const { runner } = exec({
800+
vp: (args) => {
801+
if (args[0] === "fmt") formatted.push(args[1] ?? "");
802+
return ok();
803+
},
804+
});
805+
assert.strictEqual(
806+
capture(() => run(["v2.0.0", "--dry-run"], { runner, root: f.root })).value,
807+
0,
808+
);
809+
const report = readReport(f.root, "v2.0.0");
810+
assert.deepStrictEqual(
811+
report.conflicts.map(({ path, via, reason }) => ({ path, via, reason })),
812+
[{ path: LICENSES, via: "regenerate", reason: "merged by package name" }],
813+
);
814+
assert.deepStrictEqual(formatted, [LICENSES]);
815+
assert.strictEqual(
816+
f.git(["show", `${report.trunk.after}:${LICENSES}`], f.root) + "\n",
817+
licenseList("base", "upstream-added", "fork-added"),
818+
);
819+
},
820+
);
821+
});
822+
823+
it("routes every generated path the fork carries", () => {
824+
const root = NodePath.join(import.meta.dirname, "..");
825+
const git = (args: ReadonlyArray<string>): string => {
826+
const result = runCommand("git", args, { cwd: root });
827+
if (result.status !== 0) throw new Error(`git ${args.join(" ")}: ${result.stderr.trim()}`);
828+
return result.stdout.trim();
829+
};
830+
const base = git(["merge-base", "HEAD", "upstream/main"]);
831+
const routed = new Set(REGENERATION_ROUTES.map(({ path }) => path));
832+
const unrouted = git(["diff", "--name-only", "--no-renames", base, "HEAD"])
833+
.split("\n")
834+
.filter((path) => GENERATED_HOOK_PATH.test(path) && !routed.has(path));
835+
assert.deepStrictEqual(unrouted, []);
836+
});
837+
838+
it("lists every regeneration route in the runbook, in run order", () => {
839+
const runbook = NodeFS.readFileSync(
840+
NodePath.join(import.meta.dirname, "../docs/fork/operations/fork-sync.md"),
841+
"utf8",
842+
);
843+
const section = runbook.split("## Regenerable files")[1]?.split("\n## ")[0] ?? "";
844+
const rows = [...section.matchAll(/^\| `([^`]+)` +\| (`[^`]+`|[^|`]+?) +\|/gm)].map(
845+
([, path, resolver]) => ({ path, resolver: resolver?.replaceAll("`", "") }),
846+
);
847+
assert.deepStrictEqual(
848+
rows,
849+
REGENERATION_ROUTES.map((route) => ({ path: route.path, resolver: resolverText(route) })),
850+
);
851+
});
852+
642853
it("exits 0 with already applied when the fork sits on the tag", () => {
643854
withFixture(
644855
{

0 commit comments

Comments
 (0)