You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`scripts/gen-selfhost-env-reference.mjs` generates `apps/gittensory-ui/src/lib/selfhost-env-reference.ts`, embedding the exact `file:line` of each env var's first source reference into the committed output. Any PR that adds/removes lines anywhere above such a reference shifts that line number, so two concurrent PRs touching the same source file (e.g. both editing `src/selfhost/ai.ts`) produce two different regenerated versions of the SAME row and collide on rebase — a merge conflict in a file no human is meant to hand-edit.
Confirmed real, repeated churn from git history, not a theoretical risk:
`eec83fd3 chore(selfhost): regenerate env-reference after rebase (again)` (note the "again")
`a4132113 chore(selfhost): regenerate env-reference doc after ai.ts line shifts`
`ae0faa8e ci(workflows): enforce generated-artifact drift checks in CI...` — added specifically because this kept happening
Most recently hit PR #3625, which needed a manual conflict resolution + regeneration before it could merge.
Fix
Drop the embedded line number; `firstReference` is now just the file path (e.g. `"src/selfhost/ai.ts"` instead of `"src/selfhost/ai.ts:1149"`). The file path only changes when a read is actually added/removed/moved to a different file — the only case that should ever require regenerating this doc. Updated the generator, the generated output, the test suite (plus a new regression test proving line shifts no longer change the output), and the three docs (`AGENTS.md`/`CLAUDE.md`, the contributing skill's `SKILL.md` and `reference.md`) that documented the old `file:line`-triggers-regeneration behavior.
An accompanying audit confirmed this is the only generated file in the repo with this failure mode — `worker-configuration.d.ts`, `openapi.json`, `routeTree.gen.ts`, and `command-reference.ts` all extract by symbol/content, not by AST position, and DB migration numbering already has dedicated collision-prevention tooling (`scripts/check-migrations.mjs`).
Problem
`scripts/gen-selfhost-env-reference.mjs` generates `apps/gittensory-ui/src/lib/selfhost-env-reference.ts`, embedding the exact `file:line` of each env var's first source reference into the committed output. Any PR that adds/removes lines anywhere above such a reference shifts that line number, so two concurrent PRs touching the same source file (e.g. both editing `src/selfhost/ai.ts`) produce two different regenerated versions of the SAME row and collide on rebase — a merge conflict in a file no human is meant to hand-edit.
Confirmed real, repeated churn from git history, not a theoretical risk:
Most recently hit PR #3625, which needed a manual conflict resolution + regeneration before it could merge.
Fix
Drop the embedded line number; `firstReference` is now just the file path (e.g. `"src/selfhost/ai.ts"` instead of `"src/selfhost/ai.ts:1149"`). The file path only changes when a read is actually added/removed/moved to a different file — the only case that should ever require regenerating this doc. Updated the generator, the generated output, the test suite (plus a new regression test proving line shifts no longer change the output), and the three docs (`AGENTS.md`/`CLAUDE.md`, the contributing skill's `SKILL.md` and `reference.md`) that documented the old `file:line`-triggers-regeneration behavior.
An accompanying audit confirmed this is the only generated file in the repo with this failure mode — `worker-configuration.d.ts`, `openapi.json`, `routeTree.gen.ts`, and `command-reference.ts` all extract by symbol/content, not by AST position, and DB migration numbering already has dedicated collision-prevention tooling (`scripts/check-migrations.mjs`).