feat(cli): audit markdown cross-references, including the ones that fail silently - #698
Merged
Conversation
…ail silently Six dead links had accumulated across this repo's documentation before anyone looked, and the class that motivated this was invisible: an anchor into another document. A wrong `#fragment` does not 404 — the browser scrolls to the top, so the link looks like it worked. A stale section number degrades the same way. `codefast audit links` reports three shapes: a relative path that does not exist, an in-document anchor with no matching heading or `<a id>`, and a cross-document anchor the target does not offer. External URLs are skipped as somebody else's to verify; so are links inside fenced code, which are examples rather than references — checking those would fail the audit on documentation doing its job. It defaults to the repo root rather than a configured target: a scan scoped to one package cannot see cross-package references, which are the ones most likely to rot. It gates CI, so a link that rots is a red build. The extraction is pure and lives in `domain/`, so the rules are testable without a filesystem; existence checks and the per-document anchor cache sit in the run layer. All three breakage shapes were seeded against the real repo before the green result was trusted, and the three valid controls beside them — a good cross-document anchor, a good local one, an external URL — stayed unflagged.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Merged
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Six dead links had accumulated across this repo's documentation before anyone
looked. The class that motivated this is worse, because it is invisible: an
anchor into another document. A wrong
#fragmentdoes not 404 — the browserscrolls to the top, so the link looks like it worked. A stale
SPEC §4.8degradesthe same way, which is how one survived here pointing at a section that never
existed.
codefast audit linksreports three shapes:<a id>External URLs are skipped as somebody else's to verify. So are links inside fenced
code — those are examples, and checking them would fail the audit on documentation
that is doing its job.
It defaults to the repo root rather than a configured target: a scan scoped to
one package cannot see the cross-package references, which are exactly the ones
most likely to rot. It runs in the packages gate, so a link that rots is a red
build rather than a discovery months later.
Verification
pnpm --filter @codefast/cli test:unit && pnpm --filter @codefast/cli check-types pnpm cli:audit:linkscheck-typesclean,lint --deny-warningsandformat:checkclean.✓ 233 repo-local link(s) across 152 document(s) all resolve.pnpm cli:mirrorleaves no diff, so the CI exports check stays green.Seeded before trusted
A clean result from a checker nobody has made fail is worth nothing, so all three
breakage shapes were seeded into a real file in this repo:
The three valid controls sitting beside them in the same file — a good
cross-document anchor, a good local anchor, and an external URL — stayed
unflagged, along with a link inside a fenced block.
One assertion I got wrong on the first run is worth noting: I expected
linkCount: 3for a document with three links, one of them external. The count is repo-local
references, so 2 was correct — but the presenter said "N link(s) all resolve", which
overclaims. It now says "repo-local link(s)".
Design
The extraction is pure and lives in
domain/markdown-links.ts, so the rules aretestable with no filesystem; existence checks and the per-document anchor cache sit
in
run-links.ts. That follows the boundaryARCHITECTURE.mdalready states forthis package.
Checklist
minor, nevermajorwhile on 0.xtests/unit/**mirroring thesrc/path (audit/domain/,audit/)@sincetags — new exports carry none;codefast tagstamps them at releasepackage.json#exports—@codefast/cliisfalsein the mirror config, andpnpm cli:mirrorconfirms no diffaudit linksmirrorsaudit rtl, and the result/prelude types follow the existingRtl*shapes