vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

ci: gate documentation pointers so a dead one fails the build

Browse source 
Pointing at a doc instead of duplicating its prose next to the code is what
the comment-block lint pushes people toward, and nothing checked that the
pointers still resolve. The reorg that prompted the preceding commit broke
41 references and every one of them merged green.

Two arms: repo-root-relative `docs/` paths, and relative markdown links
resolved against the linking file. Scope is every tracked file rather than a
type list — the dead references were in css, html and an ignore file as well
as in markdown and nix.

Three controls, because a link checker whose extractor quietly matches
nothing passes forever while checking nothing: each arm must have found
candidates, and at least one pointer must have resolved. Any of those failing
exits non-zero and says the script is broken rather than the tree.

Escape hatch is the `lint:allow` marker the tracker-tag lint already uses.
Its only current users are in reference-docs.nix, where a path naming a file
the derivation synthesizes into $out is correct precisely because the repo
does not have it.

Also runs in the pre-push hook alongside the other two.
This commit is contained in:
atlas 2026-09-02 02:16:44 +02:00 • committed by mara
commit 54daf9ac60
4 changed files with 127 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

8
nix/packages/reference-docs.nix
View file

@ -17,6 +17,12 @@
# `docs.nix` (website repo) needs no changes to pick either up — it
# already walks every subdirectory generically.
#
# For crates that is `$out/crates/<crate>.md`, one per workspace crate
# with a README.md (mara's ask: "behaves as if hive-core/README.md lives
# at docs/crates/hive-core.md" — lint:allow, a path this derivation
# creates in $out, so the repo has no such file). The crate's own README
# stays the single source of truth.
#
# Output layout:
# $out/ — the repo docs/ tree verbatim
# $out/crates/<crate>.md — one per workspace crate README
@ -74,7 +80,7 @@ stdenv.mkDerivation {
# Rewrite relative links that were correct from the crate's own
# position in the repo tree but aren't once the file is
# virtually one level under docs/ instead:
# ../docs/x.md (crate root -> repo docs/) -> ../x.md
# ../docs/x.md (crate root -> repo docs/) -> ../x.md lint:allow (stand-in name)
# (crates/ -> docs/ is one directory shallower than
# <crate>/ -> docs/ was, so the leading docs/ segment drops)
# ../<sibling-crate> (that crate's own directory, no file)