ci: validate repository links before merge

[rwgk]

Lychee currently checks repository links against remote main. When a PR adds or moves a path and updates documentation to link to its new location on main, that target does not exist yet. This creates a chicken-and-egg problem: the link check needs the PR to merge before it can pass, while the PR needs a passing link check before merge.

For example, #3116 renames cuda_bindings/ to cuda_bindings_13/. Its intended repository link is:

https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings_13

That link should be checked against the proposed directory layout before it reaches main.

Solution

Validate these repository links against the checkout being tested, while keeping the intended main URLs in source files and published documentation.

• CI: The dedicated link-check action invokes lycheeverse/lychee-action directly, using Lychee's native --remap to change the validation target to the actual checked-out commit in the CI repository. Authored and rendered documentation checks, including retries, use the same remapping. GitHub's file and directory views are preserved, so rendered checks retain their existing fragment validation.
• pre-commit: A small Python helper, invoked through Lychee's --preprocess, maps the same links to files and directories in the working tree. This also covers uncommitted or unpushed paths. Source files are not rewritten, and local checks retain their existing policy of not checking fragments. (Pre-commit in CI skips Lychee.)

For the example above, CI checks tree/<checked-commit>/cuda_bindings_13; pre-commit checks the checkout's cuda_bindings_13/ directory. Missing targets still fail.

Scope

Remapping applies only to canonical https://github.com/NVIDIA/cuda-python/blob/main/ and tree/main/ links. Links to tags, explicit commits, other branches, and other repositories keep their existing targets.

This PR prepares the link-checking infrastructure for #3116. The source-directory rename remains in that separate PR.

Validation

• Fresh CUDA 13.4 TestVenv build and full QA suite.
• 245 CI-tool tests plus 36 subtests; 17 regression probes using the pinned Lychee version; full pre-commit.
• CI passed, including authored and rendered link checks.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

/ok to test 8934e74

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-3118/
https://nvidia.github.io/cuda-python/pr-preview/pr-3118/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-3118/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-3118/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 94ce501b-1f10-44df-89ee-764257651bd8

📥 Commits

Reviewing files that changed from the base of the PR and between 1f41281 and 8934e74.

📒 Files selected for processing: 6

• .github/actions/check-doc-links/action.yml
• .pre-commit-config.yaml
• ci/README.md
• ci/tools/preprocess_repo_links.py
• ci/tools/tests/test_preprocess_repo_links.py
• ci/tools/tests/test_repo_link_check_action.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

📝 Summary

Summary by CodeRabbit

• Bug Fixes
  • Repository links to files added or moved in the same pull request are now checked against the current checkout, both in CI and with local pre-commit checks.
  • Missing link targets continue to fail validation; unrelated links are checked as before.
• Documentation
  • Added guidance on how repository links are validated in CI and locally.

The link-checking setup now resolves canonical blob/main and tree/main links against local checkout content during pre-commit checks and against the checked-out commit during CI checks.

Changes: Repository link validation

Layer / File(s)	Summary
Local link preprocessing ci/tools/preprocess_repo_links.py, ci/tools/tests/test_preprocess_repo_links.py, .pre-commit-config.yaml, ci/README.md	The preprocessing script converts matching repository links to file URLs rooted at the checkout. The pre-commit hook runs the script, and tests cover URL formats, preserved content, and CLI errors. The README documents local preprocessing and CI link checks.
CI commit-specific remaps .github/actions/check-doc-links/action.yml, ci/tools/tests/test_repo_link_check_action.py	The action resolves the checkout commit and remaps canonical blob/main and tree/main links to matching views in the current repository at that commit. The integration test checks the generated remaps and their boundaries.

Priority: ⬇️ Low

Change: Feature

Merge Risk: ⚪ Minimal · up to 8934e

This change lets repository links be validated against the checkout under test. It affects only CI and local link checks, not runtime behavior, and no merge-blocking risk was identified.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}