FE-1457: Point source links at the branch being built

[kube]

🌟 What is the purpose of this PR?

Every generated page links to the file that declared its layer, and the link target was hardcoded to main. On a preview build those links showed the pre-change file, or 404'd for a file the branch adds. The ref now comes from the build environment:

no environment   → https://github.com/hashintel/hash/blob/main/libs/…
GITHUB_HEAD_REF  → https://github.com/hashintel/hash/blob/cf/fe-1457-…/libs/…
GITHUB_SHA       → https://github.com/hashintel/hash/blob/deadbeef…/libs/…

In stack #9280, FE-1456 (#9266) sits below and FE-1455 (#9268) above.

🔗 Related links

• FE-1457 (internal): this PR
• FE-1418 (internal): the Vercel deployment whose previews this fixes

🔍 What does this change?

• src/source-url.ts (new): resolves the ref from the first variable that holds a value, in order PETRINAUT_ARCH_DOCS_SOURCE_REF, VERCEL_GIT_COMMIT_SHA, GITHUB_SHA, VERCEL_GIT_COMMIT_REF, GITHUB_HEAD_REF, GITHUB_REF_NAME, defaulting to main. A SHA beats a branch name because the link still resolves after the branch moves or is deleted. Slashes stay literal, since they separate path segments in a blob URL, while # and % are encoded.
• architecture.config.ts: sourceUrlPrefix calls the resolver. No literal main remains.
• turbo.json: the six variables are declared in doc:architecture's env, since Turborepo's strict env mode would otherwise hide them from the task.
• vercel-build.sh and the generator's "Wrote" line both name the resolved ref, so a preview build's log shows which commit its links point at.
• No workflow changes: nothing under .github/workflows/ builds the bundle, and GitHub Actions exports the variables the resolver reads.

Review fixes

• encodeRef drops empty and dot-only segments. Git refnames forbid them, so they can only arrive through a mistyped override, where blob//main/ or a traversing URL would be worse than a wrong ref.
• The README states that the branch-name fallbacks assume the branch lives in hashintel/hash: on a fork PR, GITHUB_HEAD_REF names a branch this repository does not have and the link 404s, while the SHA variables win when present and resolve regardless.
• REF_VARIABLES and turbo.json's env list cross-reference each other, with a comment on each side saying to keep the two lists identical.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR
  • The package README documents the variables, the precedence, and the default.

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• affected the execution graph, and the turbo.json's have been updated to reflect this
  • doc:architecture declares the ref variables. The task and its consumers are uncached, so a ref change cannot serve stale links.

🛡 What tests cover this?

• source-url.test.ts: the default, blank values skipped, SHA over branch for both providers, the local override over both, a branch name containing a slash, and # encoding.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs doc:architecture and grep a declaredInUrl in bundle/pages/architecture/cli.mdx: it points at blob/main/.
2. Repeat with GITHUB_HEAD_REF=<a branch>: the same link points at that branch. Adding GITHUB_SHA=<sha> switches it to the SHA.

🐾 Next steps

Two hand-written blob/main/... links remain in authored MDX. Those name specific files as references rather than being generated source links; giving them the same treatment needs a link helper in the authoring syntax.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 21, 2026 3:31pm
petrinaut	Ready	Preview	Aug 21, 2026 3:31pm
petrinaut-docs	Ready	Preview	Aug 21, 2026 3:31pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 21, 2026 3:31pm

[cursor]

PR Summary

Low Risk
Docs-generator URL construction only; no auth, data, or runtime behavior. Env-based ref encoding is covered by unit tests.

Overview
Generated Petrinaut architecture pages no longer hardcode GitHub links to main. sourceUrlPrefix is resolved from the build environment (override, then Vercel/GitHub SHA, then branch name, else main) so preview builds link to the commit they were built from.

turbo.json lists those env vars so strict mode does not hide them. The generator and Vercel build log the prefix used. Refs keep slashes as path segments, encode other characters, and drop empty/.. segments.

^{Reviewed by Cursor Bugbot for commit d13c8d3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.