DOC-7104: Add a check for links left in bare, uncanonicalized form

[andy-stark-redis]

Summary

• migrate_shortcode_links.py's linkify stage correctly canonicalizes almost every converted link to /content/<path>.md[#anchor], but a link that gets a manual post-hoc text fix after the pipeline already ran (e.g. inserting a separator slash a relref-plus-literal-suffix concatenation was missing) never gets a second pass through linkify. The result is a bare /operate/... path that resolves to the exact same rendered href as the canonical form, so build/diff_rendered_hrefs.py — this migration's usual verification — is blind to it by construction.
• Found on PR DOC-7104: Migrate content/operate/rs/release-notes/ to render hooks #4086 (release-notes/ unit): human review manually flagged 8 malformed links; a corpus-wide grep for the same shape found 21 across 9 files (13 more than manual review caught), plus 8 more that turned out to be genuinely pre-existing dead links in the identical shape, invisible to any prior check since Hugo's relref shortcode only ever validated its own target, never text concatenated onto it afterward.
• build/check_uncanonicalized_links.py reuses migrate_shortcode_links.py's own resolver (_find_content_file) so a --fix run applies the exact same rewrite the pipeline would have. Three outcomes: FIXABLE (resolves, --fix rewrites it), MOUNT_ONLY (resolves only through a Hugo module mount — never auto-fixed, same rationale migrate_shortcode_links.py already documents for not following mounts on a rewrite), DEAD (doesn't resolve at all — reported only, never guessed).
• Verified against the pre-fix state of PR DOC-7104: Migrate content/operate/rs/release-notes/ to render hooks #4086: reproduces the exact same 21 FIXABLE / 8 DEAD split. A full-corpus scan of content/ elsewhere comes back to 3 unrelated hits, confirming it isn't noisy.

Test plan

• build/test_check_uncanonicalized_links.py — 7 cases (fixable, fixable-with-anchor, dead, already-canonical, external/anchor-only/mailto skipped, /commands/?group= exception, the exact PR DOC-7104: Migrate content/operate/rs/release-notes/ to render hooks #4086 shape), all passing (no pytest in this repo's venv, ran the test functions directly — matches this migration's other build/test_*.py scripts, none of which are wired into CI either)
• Reproduced PR DOC-7104: Migrate content/operate/rs/release-notes/ to render hooks #4086's exact pre-fix finding set (21 FIXABLE / 8 DEAD) by checking out that commit's release-notes/ content into the full corpus and scanning
• Full content/ scan: 3 unrelated hits elsewhere, all genuine (2 bare /commands/<cmd> links in already-converted oss_and_stack release notes, 1 in operate/rs/7.4/_index.md)

🤖 Generated with Claude Code

---

Note

Low Risk
Build-only tooling and tests; no runtime or published docs behavior unless someone runs --fix on markdown files.

Overview
Adds build/check_uncanonicalized_links.py, a corpus scanner that catches Markdown links still pointing at bare content mounts (/operate/, /develop/, /integrate/, /commands) instead of the migration’s canonical /content/<path>.md form—cases diff_rendered_hrefs.py misses because they render the same href.

Each hit is classified as FIXABLE (same resolver as migrate_shortcode_links; optional --fix rewrites in place), MOUNT_ONLY (report only), or DEAD (broken link, report only). /commands links with query/fragment (no slash before ?/#) are treated as fixable to /content/commands even without an on-disk _index.md.

build/test_check_uncanonicalized_links.py adds filesystem-backed tests for fixable/dead/skipped cases, anchors, the /commands?group= shape, and the PR #4086 relref-plus-suffix defect.

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

[github-actions]

DOC-7104

[github-actions]

🧠 Redis Memory

Found 9 related items from repository history (4 new this commit):

• PR — DOC-7104: Migrate content/operate/rs/release-notes/ to render hooks

  Summary

• PR — DOC-7104: Migrate content/operate/rs/clusters/ and top-level files to render hooks

  Summary

• PR — DOC-7074: Migrate use-cases/leaderboard+memory-layer+prefetch-cache to render hooks

  Summary

• PR — DOC-7104: Migrate content/operate/rs/7.8/ (excl. references) to render hooks

  Summary

• PR — DOC-7089: Migrate content/operate/oss_and_stack/install/ to render hooks

  Summary

• Commit — DOC-7104: Add a check for links left in bare, uncanonicalized form 🆕

  DOC-7104: Add a check for links left in bare, uncanonicalized form

• PR — DOC-7047: Formalize DOC-6909 shortcode migration tooling 🆕

  Summary

• PR — DOC-7059: Migrate develop/get-started+whats-new to render hooks 🆕

  Summary

• PR — DOC-7055: Migrate develop/data-types top-level pages to render hooks 🆕

  Summary

Memory updated at d2f6723

[dwdougherty]

Code skimmed. Approved.

[andy-stark-redis]

Thanks for your heroic review of all these PRs @dwdougherty ! Hopefully this check will prevent any more issues like the ones you've found.