Context:
Identified during work on #11
PR: #12
Description:
internal/docscheck resolves only inline Markdown links. Several standard CommonMark/GFM constructs are invisible to it, so a dead link written in any of these forms passes silently:
| Form |
Example |
| Reference-style link |
[text][ref] with [ref]: docs/gone.md |
| Autolink |
<docs/gone.md> |
| Angle-bracket destination |
[text](<docs/gone file.md>) |
| Nested brackets in link text |
[text with [nested] brackets](docs/gone.md) |
| Indented (non-fenced) code block |
a 4-space-indented example is checked as a live claim |
None appear in this repository's documentation today — verified by grep during #12 — which is why they were left out rather than fixed. They are recorded in the internal/docscheck package comment under "Known limits" so silence is not mistaken for a guarantee.
CheckNamedPaths has a related, deliberate blind spot: a candidate must begin with a segment naming a real repository-root entry, so a wholly invented top-level directory (nonexistent/foo.md) goes unreported. That rule is what keeps github.com/sofired/tracedoc, actions/setup-go, and linux/amd64 from being flagged, and it is documented and tested in TestIsRepositoryPath.
Rationale:
Deferred from #12 as false negatives rather than false positives. A missed dead link is a gap; a reported live link breaks CI on correct documentation and is what gets a gate switched off. #12 prioritised eliminating the second class — three real false positives were found and fixed in review. Closing these gaps is only worth doing if the constructs start appearing, or if the heuristic can be tightened without adding noise.
Suggested trigger: adopt this work when a reference-style link or autolink is first added to the repository's docs, rather than pre-emptively.
Reference:
internal/docscheck/docscheck.go — package comment, "Known limits"internal/docscheck/docscheck.go — inlineLink, linkText, blankFencedCodeinternal/docscheck/docscheck_test.go — TestIsRepositoryPath
Acceptance Criteria:
Context:
Identified during work on #11
PR: #12
Description:
internal/docscheckresolves only inline Markdown links. Several standard CommonMark/GFM constructs are invisible to it, so a dead link written in any of these forms passes silently:[text][ref]with[ref]: docs/gone.md<docs/gone.md>[text](<docs/gone file.md>)[text with [nested] brackets](docs/gone.md)None appear in this repository's documentation today — verified by grep during #12 — which is why they were left out rather than fixed. They are recorded in the
internal/docscheckpackage comment under "Known limits" so silence is not mistaken for a guarantee.CheckNamedPathshas a related, deliberate blind spot: a candidate must begin with a segment naming a real repository-root entry, so a wholly invented top-level directory (nonexistent/foo.md) goes unreported. That rule is what keepsgithub.com/sofired/tracedoc,actions/setup-go, andlinux/amd64from being flagged, and it is documented and tested inTestIsRepositoryPath.Rationale:
Deferred from #12 as false negatives rather than false positives. A missed dead link is a gap; a reported live link breaks CI on correct documentation and is what gets a gate switched off. #12 prioritised eliminating the second class — three real false positives were found and fixed in review. Closing these gaps is only worth doing if the constructs start appearing, or if the heuristic can be tightened without adding noise.
Suggested trigger: adopt this work when a reference-style link or autolink is first added to the repository's docs, rather than pre-emptively.
Reference:
internal/docscheck/docscheck.go— package comment, "Known limits"internal/docscheck/docscheck.go—inlineLink,linkText,blankFencedCodeinternal/docscheck/docscheck_test.go—TestIsRepositoryPathAcceptance Criteria: