check-links: verify relative Markdown links resolve to real files - #14
Closed
sergiobuilds wants to merge 2 commits into
Closed
check-links: verify relative Markdown links resolve to real files#14sergiobuilds wants to merge 2 commits into
sergiobuilds wants to merge 2 commits into
Conversation
New scripts/check-links.sh — catches the second most common drift shape after skill renames: a relative link left behind when a file is moved or renamed. Scope: - Every SKILL.md, every docs/*.md, every top-level *.md. - Relative link targets only. External (http, https), protocol-relative, mailto, tel, and in-page anchors are out of scope by design. - Fragment and query strings are stripped before resolving; a link to a section still counts as a link to a file. Empirically clean on the current catalog: 30 scanned files, 0 broken links. Pairs with check-skill-refs.sh (typos and orphans) and validate-skills.sh (catalog shape). The three together cover: the shape of each skill, the resolution of names between them, and the resolution of paths between docs.
Three defects called out in cold-read: 1. `grep | sed | while read` piped the loop body into a subshell, so `fail=1` set by `err` never made it back to the final exit-code decision. Switch to `while read ... done < <(...)` so the loop stays in the current shell and `fail` propagates. `count` also stops being lost. 2. The `[text](target)` scan matched `` too, so a missing image would be flagged as a broken link. Strip well-formed `` from a working buffer before the inline scan. 3. Reference links (`[text][ref]` with `[ref]: target`) were not scanned at all. Build a per-file `ref → target` map from `[ref]: target` definitions and resolve each `[text][ref]` usage against it; unresolved references get flagged with a clear "no matching definition" message. Also guards the empty-files-array case so it fails fast instead of returning a green success with zero occurrences, and documents the intentionally unsupported edge cases (collapsed refs, `)` in inline targets, quoted-target definitions with whitespace) in the header comment. Verified locally across seven scenarios: clean repo, broken inline link, missing image (must be ignored), broken reference target, undefined reference name, anchor-only link, and full restore — exit codes match the intent in every case.
Contributor
Author
|
Cold-read flagged three defects: subshell bug swallowed failures, image links were treated as inline links, and reference-form links were not scanned at all. Pushed fix (c236dde):
Also guards empty-files-array (fails fast instead of green-with-zero) and documents the intentionally unsupported edge cases (collapsed refs, Local verification, seven scenarios:
Ready for another look. |
Owner
|
Landed in |
LilMGenius
approved these changes
Jul 17, 2026
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
2 participants
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.
New `scripts/check-links.sh` — catches the second most common drift shape after skill renames: a relative link left behind when a file is moved or renamed.
Scope
Verification
```
$ bash scripts/check-links.sh
✓ relative links resolve (scanned 30 files)
```
Empirically clean on the current catalog.
Pairs with the other checks
The three together cover: the shape of each skill, the resolution of names between them, and the resolution of paths between docs.
CI wiring — one line
Not wired into CI in this PR (OAuth workflow scope). Suggested addition to `.github/workflows/ci.yml`:
```yaml
run: bash scripts/check-links.sh
```