fix(gate): collect README links from the prose, not from the code fences - #72
Merged
Conversation
The published-surface gate verified every link in the README, including the ones
inside fenced code blocks. An `<a href="${url}">` in an example email template is
a string the example builds at runtime, not a link a reader can click, and the
checker tried to resolve the placeholder as a repository path — reporting
`${url} does not exist in the repository` and failing the build for a link that
does not exist.
Collection now starts from the prose, as the heading/anchor check in the same
file already did. The snippet extractor still reads the full README: the fences
are exactly what it compiles.
Found in @bymax-one/nest-auth, where a README example tripped it; applied here so
the gate does not fail this repository for the same non-reason the day its README
gains an HTML anchor inside an example.
There was a problem hiding this comment.
Pull request overview
Updates the check:published gate’s README link validation to ignore fenced code blocks, so runtime placeholder strings inside examples (e.g., ${url} in HTML snippets) don’t get misinterpreted as real repository paths.
Changes:
- Collects clickable README links from
README_PROSE(README with fenced blocks removed) instead of the fullREADME. - Collects internal
#anchorlinks fromREADME_PROSEfor consistency with the existing heading/anchor extraction logic.
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
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.
What was wrong
scripts/check-published-surface.mjsverifies that every link in the READMEresolves — and it was collecting them from the whole README, code fences
included. An HTML anchor inside an example is not a link a reader can click; it is
a string the example builds at runtime:
The checker read that as a repository path and failed the build with
${url} does not exist in the repository.The fix
Collection now starts from
README_PROSE— the README with fenced blocks removed —which is what the heading/anchor check in the same file already used, for the same
reason its own comment gives: a
# Using pnpminside a ```bash fence is a shellcomment, not a heading.
The snippet extractor is deliberately left reading the full
README: the fences areexactly what it compiles against
dist/. Pointing it at the prose would have made itfind zero snippets and pass in silence.
Why here
Found in
@bymax-one/nest-auth, where a README example tripped it(bymaxone/nest-auth#64). This repository's README has no HTML anchor inside a code
block today, so the gate passes either way — the change is so it keeps passing for
the right reason the day one is added.
Verification
pnpm check:publishedpasses, and still finds this README's links and snippets —the counts it reports are unchanged apart from anything that only ever existed
inside a fence.