fix(ci): repair lychee — broken since May, plus the 12 dead links it found - #124
fix(ci): repair lychee — broken since May, plus the 12 dead links it found#124WomB0ComB0 wants to merge 5 commits into
Conversation
The weekly lychee job has failed 14 consecutive scheduled runs (every
run since 2026-05-11). The cause is not external link flake, which the
workflow comment anticipates — lychee never checked a single link:
error: unexpected argument '--exclude-mail' found
Usage: lychee ... --include-mail[=<false|true>] [inputs]...
Upstream removed `--exclude-mail` and inverted it to `--include-mail`.
lychee-action is pinned by SHA but tracks the latest lychee binary
(0.24.2 today), so the flag vanished under a pinned action and the job
has aborted during argument parsing ever since.
Mail is now excluded by default (`--include-mail` = "Also check email
addresses", default false), so deleting the flag preserves the original
intent exactly rather than changing what gets checked.
Also pins actions/checkout and actions/cache to commit SHAs, and sets
`persist-credentials: false` on checkout. The pin is required by the
same blanket `unpinned-uses` policy that broke #117; the credentials
flag is needed because pinning edits the checkout line, which would
otherwise surface the pre-existing `artipacked` finding as a new alert
on a changed line. This job only reads files, so it never needs the
token persisted.
Verified: lychee 0.24.2 --help confirms --exclude-mail is gone and
--include-mail defaults to false. zizmor v1.29.0 on this file goes from
3 findings (2 high unpinned-uses, 1 artipacked) to 0. actionlint passes.
Note: #121 attempted to fix this by committing six .lycheecache entries.
That could not have worked — all six are 200s (caching successes cannot
suppress an argument-parsing abort) and --max-cache-age 1d expires them
within a day. Left in place as harmless; it is dead weight, not a fix.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
With the argument-parsing abort fixed, lychee ran for the first time
since May and failed with 11,529 errors out of 34,557 links. None were
external-link problems:
~11,380 file:// local links (mostly generated SDK API doc anchors)
148 root-relative links (/sdks/typescript) that cannot resolve
Both classes are internal links, which this workflow explicitly does not
own — see its own header: "Internal MDX link integrity is enforced by
`mint broken-links` in required.yml." lychee was walking every internal
link in the docs tree, including the generated Python/TS API reference,
and that was being misread as "external link flake" for months.
Two flags are needed, and both are required — neither works alone:
--scheme http/https confines checking to external URLs. Measured with
--dump over identical inputs: 16,257 links ->
2,984, zero file:// surviving the filter.
--root-dir root-relative links fail during *resolution*,
which happens before scheme filtering, so
--scheme alone cannot suppress them (confirmed:
--exclude '^/' has no effect either). --root-dir
lets them resolve to file:// URLs, which the
scheme filter then excludes. Verified repo-wide:
148 resolution errors -> 0.
--root-dir does not turn this into a second internal link checker: the
resolved file:// links are excluded, never fetched. Rejected --base-url,
which would instead point all 148 at the live site — locally that timed
out on all inputs and took 80s for one file.
Last verified CI run on this branch (31910818811) had all 2,972 external
links passing, with 148 resolution errors as the only remaining failure;
this commit removes those.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (13)
Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review. 📝 WalkthroughWalkthroughThe pull request pins Lychee workflow actions and updates link-checking arguments. Generated .NET, Rust, and TypeScript documentation now uses current API, repository, license, profiling, and package links. ChangesDocumentation and link maintenance
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to This PR repairs the link-checking workflow and updates documentation links; no actionable merge-blocking risk remains beyond normal checks and review. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Ralph verified: CI is green and the PR is mergeable — ready for your review/merge. |
The automated fix in #124 retargeted ResQ.Clients.CoordinationHceClient but missed the other two ResQ types mapped to learn.microsoft.com, and skipped ScenarioRunner.ValidateLocation entirely. Lychee on that branch went 12 -> 4 errors, with all four being the same generator bug: learn.microsoft.com/en-us/dotnet/api/resq.clients.infrastructureapiclient x2 learn.microsoft.com/en-us/dotnet/api/resq.core.location x2 Both are our own types; Microsoft does not document them, so both 404. Retargeted to the sibling generated pages, matching the relative-link form #124 already established. Both targets verified present in-tree. This is a stopgap, not the fix. These files are regenerated output -- api-docs.dotnet.yml clears sdks/dotnet/api/ before copying fresh output over it -- so this is discarded on the next api-docs run from resq-software/dotnet-sdk. The generator bug is filed as resq-software/dotnet-sdk#93. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
WomB0ComB0
changed the title
|
Retargeted this PR from What this actually fixesThe weekly Upstream removed The three-layer repair
Also pins Progression, each step measured
Final: 34,555 total, 2,976 external checked, 31,579 internal excluded, 0 errors. On the agent-generated commit
Warning The link fixes are a stopgap and will regress. Everything under Durable fixes filed upstream:
If those are not picked up, lychee goes red again on the next SDK regeneration — which is precisely how it sat broken for 14 weeks. |
2 participants
Automated CI fix from
ralph triage --fix-ciusing a local model. Failing run: https://github.com/resq-software/docs/actions/runs/31911555547Summary by CodeRabbit
Documentation
Chores