Skip to content

ci/redirects: Add Redirect check for PRs - #1880

Draft
marcleblanc2 wants to merge 29 commits into
check-links-pr-checkfrom
check-redirects
Draft

ci/redirects: Add Redirect check for PRs#1880
marcleblanc2 wants to merge 29 commits into
check-links-pr-checkfrom
check-redirects

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Linear FE-499: Fix doc site issues

Stacked on #1858 (base branch check-links-pr-check); merge that one first.

Problem

  • src/data/redirects.ts has ~900 entries that don't work: destination pages that no longer exist, #fragments in the source (browsers never send them, so the entry can never match), duplicates of an earlier source, chains to other redirects, /docs/ prefixes
  • Nothing checks the file, so PRs keep adding broken redirects, and PRs that move a page or rename a heading silently break the redirects pointing at it

Solution

  • dev/check-redirects.mjs validates every entry against the pages and headings in docs/
  • "Check redirects" PR check runs the script on the PR head and its merge base, and reports only what the PR introduced; the ~900 pre-existing problems are ignored
  • Runs in parallel with "Check links"
  • The comment groups findings by problem, and each section says how to fix its entries, so authors learn how to write a correct redirect:
    • Source overshadows a docs page that exists
    • Source has a #fragment, so this redirect can never match
    • Source or destination starts with /docs
    • Source already has an earlier entry, so this one is never used
    • Destination is another redirect (shows the final destination)
    • Destination page does not exist
    • Destination heading does not exist
  • Line numbers link to the entry in redirects.ts on the PR branch
  • The comment is created / updated in place, and once the PR is fixed, the PR check passes and the comment is updated to say so
  • A PR that never broke anything gets no comment
  • pnpm check-redirects runs it locally

Verification

PR check comment in test PR: #1896 (comment)

Check redirects PR comment listing 8 broken redirects grouped by problem

Related

Amp threads

@vercel

vercel Bot commented Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated
sourcegraph-docs Ready Ready Preview Sep 10, 2026 6:38am UTC

Request Review

@marcleblanc2 marcleblanc2 changed the title ci: fail PRs that break redirects ci: Fail PRs that break redirects Sep 9, 2026
@marcleblanc2 marcleblanc2 changed the title ci: Fail PRs that break redirects ci/redirects: Add PR check for broken redirects Sep 9, 2026
marcleblanc2 and others added 19 commits September 9, 2026 21:21
@marcleblanc2 @ampagent
ci: comment on PRs that break internal links or anchors
3b6cb2d 
Add a pull_request workflow that runs dev/check-links.mjs --check-anchors
on both the PR head and its merge base, and reports only the findings the
PR introduces: outbound links from changed pages, and inbound links from
other pages to a page or heading the PR removed or renamed. Pre-existing
broken anchors on main are ignored. The job comments on the PR and fails
when new breakage is found.

dev/check-links.mjs gains --root, --format (text|json|markdown) and
--baseline to support that diff, plus case-mismatch detection for routes
(links that resolve on macOS but 404 on Linux) and scanning of *.md files.
Only *.mdx files count as routes, matching contentlayer's filePathPattern.

Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
test: rename a linked heading to exercise the PR comment (will be rev…
fe64d7d 
…erted)

Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2
Revert "test: rename a linked heading to exercise the PR comment (wil…
2e1d6b3 
…l be reverted)"

This reverts commit 1edcff8.
@marcleblanc2 @ampagent
check-links: accept <a name> and id= attributes as anchor targets
386c618 
Generated pages such as admin/telemetry/protocol.mdx define anchors with
<a name="..."> rather than headings. Drops 132 false positives on main
(431 -> 299 with --check-anchors).

Amp-Thread-ID: https://ampcode.com/threads/T-01a0753f-0f4f-7478-b36c-87466e7c0261
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: detect case mismatches in public/ and docs/ asset links too
786135e 
Replace the fs.existsSync asset checks (case-insensitive on macOS, so they
hid links that 404 on the Linux build) with an enumerated lowercase -> real
path map of files under public/ and docs/, mirroring the route check.

Also register docs/index.mdx as the / route. It was never in the path map
(the /index strip needed a leading slash), and existsSync('public/') was
masking that by accepting any '/' link. Six pre-existing broken /#anchor
links on the homepage are now reported.

Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links workflow: never comment on a clean PR
d5874ca 
A green run posts nothing. If an earlier run left a report and the PR has
since been fixed, delete that comment instead of editing it to a checkmark.

Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links workflow: say what the resolved comment actually means
365e492 
The checkmark comment only ever appears after an earlier run reported
breakage, so word it that way instead of "introduces no broken links".
Keeps the comment (reverts the delete from the previous commit).

Amp-Thread-ID: https://ampcode.com/threads/T-01a07597-43c0-751b-8c49-6e5809e714d2
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: strip fences line by line, first file wins a route, same…
8fda853 
…-page anchors use own headings

Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
Add verify-links-live: prove a branch's changed links resolve on a de…
0ac55b2 
…ployed site

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a
@marcleblanc2 @ampagent
check-links: slug the full heading text when a heading contains a lin…
eb4c248 
…k, matching rehype-slug

Amp-Thread-ID: https://ampcode.com/threads/T-01a07623-9d65-7356-96b8-2bebb31ffa5a
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: state that redirects do not satisfy the PR check
a3fa71f 
The checker resolves links against docs/**/*.mdx routes only and never
reads src/data/redirects.ts, so a redirect added alongside a page move
still leaves inbound links reported. Say so in the PR comment and in
AGENTS.md so contributors update the links instead.

Amp-Thread-ID: https://ampcode.com/threads/T-01a085bf-fe07-77a1-a4e2-55bff4679bcc
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: reword the inbound-link guidance in the PR comment
aa98024 
Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: split the inbound-link guidance and say why redirects do…
6780dac 
… not count

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: link each file path in the PR comment to the file on the…
5531c04 
… PR branch

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
check-links: install only github-slugger in CI, link line numbers to …
b6bdbcb 
…the source view

Drop glob in favour of fs.readdirSync(recursive) so the PR check needs one
package instead of the whole site, and skip the pnpm/setup-node steps.
Every finding now links to the file and line on the PR branch, in the
?plain=1 code view where #L anchors work.

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2
check-links: split the PR comment into outbound and inbound broken links
7e827bc 
Outbound findings are in files the PR changed (it added or edited a bad
link); inbound ones are elsewhere (the PR renamed or removed a link
target). The workflow passes git diff --name-only against the merge base.
@marcleblanc2 @ampagent
check-links: export listFiles and routeFor for check-redirects, cance…
c6d0c22 
…l superseded runs

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
ci: fail PRs that break redirects
506485c 
Add dev/check-redirects.mjs, which validates every entry in
src/data/redirects.ts: the destination page exists under docs/ (following
chains through other redirects), a #fragment destination names a heading
that exists on that page, and the source does not shadow an existing page.

Add a Check redirects workflow that runs the script on the PR head and on
the merge base and fails only on findings the PR introduces, so the 227
redirects already broken on main do not block unrelated PRs. It comments
the report on the PR and updates that comment on later pushes, matching
the Check links workflow.

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a07e6f-db41-74af-bbeb-f8952e637289
@marcleblanc2 @ampagent
check-redirects: share heading extraction with check-links, install o…
38c3748 
…nly github-slugger, link report lines, rename to Redirect check

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 marcleblanc2 changed the title ci/redirects: Add PR check for broken redirects ci/redirects: Add Redirect check for PRs Sep 10, 2026
@marcleblanc2
marcleblanc2 changed the base branch from main to check-links-pr-check September 10, 2026 03:26
@marcleblanc2 marcleblanc2 mentioned this pull request Sep 10, 2026
Closed
@marcleblanc2 @ampagent
check-redirects: group findings by problem, flag #fragment sources th…
d3f3ef2 
…at can never match, new comment text

Amp-Thread-ID: https://ampcode.com/threads/T-01a088d9-b8fd-76fd-ba93-3a416c5829a3
Co-authored-by: Amp <amp@ampcode.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@marcleblanc2