Skip to content

docs: badge row, and a test that the links in it are real - #7

Merged
darklordVirtual merged 1 commit into
mainfrom
docs/badges
Aug 6, 2026
Merged

darklordVirtual merged 1 commit into
mainfrom
docs/badges

Conversation

@darklordVirtual

Copy link
Copy Markdown
Owner

Four badges at the top of the README — CI, the research repository, the paper, and the licence — so a developer sees what this is built on before any prose. "Powered by REMORA" became a sentence that states the actual relationship: consumed as a hash-pinned release, not a dependency on its master.

The test is the interesting half

A dead link on a public front page reads as neglect of everything behind it, and the specific hazard here has already bitten once: docs/ARCHITECTURE.md and docs/architecture.md are the same file on Windows and two different files on the Linux host GitHub serves from. Three links resolved perfectly for the person who wrote them and would have 404'd for every reader.

test_readme_links.py checks every relative link in every document against the real directory listing, component by component.

The first version of it did not work — and failed in exactly the way it was written to prevent. It called Path.resolve(), which on Windows canonicalises a path to the real on-disk spelling, so docs/ARCHITECTURE.md came back as docs/architecture.md and the check validated the lookup rather than what was written.

Verified by deliberately breaking a link:

first version   24 passed          ← did not catch it
rewrite          1 failed, 23 passed
                 README.md->docs/ARCHITECTURE.md
restored        24 passed

It also asserts that a CI badge names a workflow that exists — a badge for a missing workflow renders as "no status" and reads as a broken build — and that no document is unreachable from the README.

Filesystem only: no network, no Docker, part of the fast gate. 95 contract tests pass.

Note on ordering

Branched from main so the badges can land without waiting on #6. #6 also touches the README; I will merge main into it once this lands so it stays mergeable.

Four badges, each pointing at something a developer wants before reading
prose: the CI workflow, the research repository, the paper, and the licence.
"Powered by REMORA" became a sentence that says what the relationship
actually is — consumed as a hash-pinned release, not a dependency on master.

## The test is the interesting half

A dead link on a public front page reads as neglect of everything behind it.
The specific hazard here has already bitten once: docs/ARCHITECTURE.md and
docs/architecture.md are the same file on Windows and two different files on
the Linux host GitHub serves from, so three links resolved perfectly for the
person who wrote them and would have 404'd for every reader.

test_readme_links.py checks every relative link in every document against
the real directory listing, component by component.

The first version of it did not work, and failed in exactly the way it was
meant to prevent. It called Path.resolve(), which on Windows canonicalises a
path to the real on-disk spelling — so docs/ARCHITECTURE.md came back as
docs/architecture.md and the check validated the lookup rather than what was
written. Verified by deliberately breaking a link: the first version passed
24/24, the rewrite fails on precisely that link and passes when it is
restored.

Also checks that a CI badge names a workflow that exists (a badge for a
missing workflow renders as "no status" and reads as a broken build), and
that no document is unreachable from the README.

Filesystem only: no network, no Docker, part of the fast gate.
@darklordVirtual
darklordVirtual merged commit 94240d5 into main Aug 6, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant