Open a fix PR for broken links instead of only filing a report issue

Problem

Today the link checker ends at a report. generate-link-report.sh builds a markdown summary of errors, broken-anchor warnings, and redirects, and the consuming workflow files that summary as an issue (see set-issue-url.sh). Every fix after that is manual: open the issue, read a public URL, work out which source file in the docs repo produced that page, find the link in the markdown, edit it, repeat.

I think that is the expensive part, and it is also the part that reviews badly. A reviewer reading the issue sees a list of URLs with no diff. A reviewer reading a PR sees exactly which line in which file changed, can compare old target to new target side by side, and can approve or reject each change in the normal review flow.

Proposal

Add a step that turns the mechanically-safe subset of link findings into a branch and a pull request against the docs repo, and leaves the rest in the report issue as it works today.

Rough shape:

1. Keep generate-link-report.sh as the source of truth for findings, but have it emit a machine-readable companion file (JSON) alongside the markdown, with one record per finding: original URL, final or suggested URL, source page, and category (error, anchor warning, redirect).
2. Add a new script, maybe apply-link-fixes.sh, that reads that JSON, maps each built page back to its source markdown file, rewrites the links it can rewrite safely, and writes a summary of what it changed and what it skipped.
3. Have the calling workflow push the branch and open a PR, then link the PR from the report issue so the two stay connected.

What is safe to auto-fix, and what is not

My best guess at the split, though this is worth arguing about:

Probably safe

• Permanent redirects (301, 308) where the final URL is stable and the report already decided the redirect is genuine, not a version pointer. skip_redirect and is_version_pointer_redirect already encode most of that judgment, so the fixer can reuse it rather than reinventing it.
• Bare domain changes and path moves where the entire URL is a literal string in the source file.

Probably not safe, leave in the issue

• 404s with no suggested replacement. The tooling knows the link is dead, not where it should point.
• Broken anchors. Picking the right heading is an editorial call, and verify-anchors.sh already shows how often these are false positives.
• Anything inside a shortcode, a reused snippet, or a generated reference page. A fix applied to one of those changes many rendered pages at once, which is exactly the case a reviewer needs to see deliberately rather than buried in a bulk commit.

Known hard part

The report's "Found on" values are built page URLs or public/ paths, not source files. Reversing that mapping is the real work in this issue, and everything else is comparatively mechanical. A few options:

• Have the docs site emit a mapping file at build time. Hugo can produce a custom output format listing each page's .File.Path against its .Permalink, which makes the reverse lookup exact.
• Derive the source path from the URL by convention, reversing the slug logic that generate-link-report.sh already implements in PR mode. This is cheaper but wrong on aliases, custom slugs, multilingual paths, and version rebasing.
• Skip the mapping and grep the repo for the literal broken URL. Simple and surprisingly effective for full URLs, though it does not help for relative links and risks touching files the checker never flagged.

I lean toward the build-time mapping file because the other two fail quietly, and a link fixer that silently edits the wrong file is worse than no fixer. That said, grep-only might be a reasonable first cut to find out whether the workflow is useful at all before building the mapping.

Reasons this might be the wrong idea

• Volume. If a run finds a few hundred redirects, the resulting PR is a large mechanical diff that nobody reviews carefully, which is the same review problem in a different wrapper. Capping the PR size, or splitting per product, would help.
• Cross-repo permissions. This repo holds shared tooling, so the PR has to be opened against a consuming repo. That needs a token with write access there, and the existing cross-org token limits may block some consumers.
• Churn. Some redirects are stable and harmless. Rewriting them produces diff noise in pages that were not actually broken. It may be better to auto-fix only errors with known replacements and leave redirects alone.
• A scheduled job that opens PRs on its own needs an owner. Without one, these PRs go stale the same way report issues do.

Suggested first slice

Start narrow: permanent redirects only, one consuming repo, grep-based matching for full URLs, PR capped at a fixed number of changes, everything else still reported in the issue. That is small enough to tell us whether reviewing link fixes as a diff is actually better in practice, before committing to the build-time mapping work.

Start with generate-link-report.sh and set-issue-url.sh, then read the existing skip_redirect, is_version_pointer_redirect, and verify-anchors.sh logic. Trace the calling workflow and how report findings are produced before deciding how the suggested narrow slice fits. Done means permanent redirects can be matched, capped, summarized in a branch and PR, while unsupported findings remain in the report issue.