ci: check relative Markdown links and anchors

[Jay (jay23606)]

Fixes #563

Summary

• scripts/check_markdown_links.py resolves every relative link and image target in tracked Markdown outside openvmm/, and every anchor against GitHub's heading slugs, ignoring fenced and inline code.
• Runs in .github/actions/check-quality with its unit tests (scripts/test_check_markdown_links.py).
• Fixes the one broken anchor it finds: aci_edge_sandboxes/README.md linked #native-proxy-and-forwarded-ports, a heading renamed to "Native proxy and host loopback".

Test

• python scripts/check_markdown_links.py passes on this branch.
• python -m unittest discover -s scripts -p test_check_markdown_links.py passes (6 tests).
• ruff check/format and pyright (strict, Linux and Windows) are clean.
• Links into openvmm/ are skipped: it is vendored and was not checked out in my clone, so two links into it could not be verified here.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Parsing defects can silently miss broken links or fail CI on valid documentation.

6 open findings

• Fence tracking ignores delimiter character and length · New
• Setext headings are missing from anchor generation · New
• Code span parsing fails for multi-backtick delimiters · New
• Heading slugs retain Markdown formatting · New
• Generated heading slugs can collide with existing slugs · New
• Inline link scan misses multiline and reference-style links · New

What changed in this PR

Adds Markdown link validation to the quality gate to catch broken documentation paths and anchors, addressing #563.

Changes:

• Adds a dependency-free checker and unit tests.
• Runs both in the quality action.
• Corrects the sandbox README’s native-proxy anchor.

File	Description
scripts/​test_check_markdown_links.py	Tests slug generation, anchors, and target extraction.
scripts/​check_markdown_links.py	Checks relative Markdown targets and anchors outside vendored files.
aci_edge_sandboxes/​README.md	Fixes the native-proxy anchor destination.
.github/​actions/​check-quality/​action.yml	Runs the checker and its tests.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Verified parsing and resolution errors reject valid documentation links and allow broken links to pass.

1 open finding

• Restrict code span matching to inline Markdown blocks · New

6 resolved since last review

• Inline link scan misses multiline and reference-style links
• Generated heading slugs can collide with existing slugs
• Heading slugs retain Markdown formatting
• Code span parsing fails for multi-backtick delimiters
• Setext headings are missing from anchor generation
• Fence tracking ignores delimiter character and length

Previously missed (4)

In code that hasn't changed since last review

Parse Markdown destinations with titles and balanced parentheses

scripts/​check_markdown_links.py:33

This expression misses or truncates valid Markdown destinations. [guide](missing.md 'Guide') and [guide](<missing guide.md>) produce no targets, so broken links pass CI. [guide](guide(v2).md) produces guide(v2, so an existing file is reported missing. Parse angle-delimited destinations, balanced/escaped parentheses, and Markdown title delimiters, and add regression cases for these forms.

Decode HTML entities before generating heading slugs

scripts/​check_markdown_links.py:93

HTML entities are not decoded before generating heading slugs. For example, # Fish & Chips renders with anchor fish--chips, but this checker generates fish-amp-chips. It therefore rejects the valid anchor and accepts an incorrect one. Decode entities after processing heading markup but before restoring stashed code spans, so entity text inside code remains literal, and add regression cases for both forms.

Preserve inline-code-only Setext heading anchors

scripts/​check_markdown_links.py:104

A Setext heading containing only inline code, such as a line containing Setup in backticks followed by =====, loses its anchor: masking turns the heading text into whitespace, so the blank-line check discards it. GitHub generates setup, but this checker rejects links to it. Use nonblank placeholders for code spans during heading detection, while still masking fences, and add a regression case.

Strip query strings before resolving link paths

scripts/​check_markdown_links.py:165

Query strings are treated as part of the filesystem path. Valid links such as README.md?plain=1 or image.png?raw=true are reported missing even when the file exists, causing the quality job to reject valid documentation. Strip the query before resolving the path, while retaining the fragment for anchor validation.

🧠 Review effort: Balanced