fix(hygiene): use CommonMark for dead-link checks - #109

Summary

Closes #108.

Use the existing shared CommonMark parser for Hygiene dead-link checks. This covers reference-style, collapsed, shortcut, HTML-anchor, and Markdown-image destinations without treating code, comments, or non-navigation HTML as links. Local destination normalization is shared with quality scoring, and repeated equivalent destinations produce one finding per document.

The review follow-up keeps scheme classification before percent decoding, preserves invalid UTF-8 bytes without replacement-character aliasing, rejects Windows anchors after dot-segment normalization, contains frontmatter and per-target lookup failures, escapes and bounds diagnostics, and avoids repeated suffix scans for unclosed inline comments, processing instructions, CDATA, and declarations.

Behavior changes

• Root-absolute and protocol-relative URLs are skipped rather than interpreted as host paths.
• Diagnostics use the parser-normalized href with bounded, single-line escaping; duplicate normalized targets collapse to the first finding.
• Markdown images remain checked. Raw HTML <img src> remains outside scope, matching the old regex.
• Relative ../ targets retain their previous lookup behavior; containment is not changed by this PR.
• Invalid or inaccessible local destinations remain per-link errors instead of aborting the complete validation run.
• Relative URLs that gain an absolute or drive-relative anchor during decoding/normalization produce an Invalid local link finding without filesystem lookup; they are not silently skipped. Repeated identical invalid hrefs are reported once per document. Quality scoring retains the shared helper's default behavior.

Verification

• I am familiar with the Contributing Guidelines
• Added or updated focused tests
• Updated CHANGELOG.md
• Ran lint
• Ran the full test suite; environment failures are detailed below
• Built the sdist and wheel
• Did not add credentials, private datasets, or proprietary benchmark content

Results on the current candidate:

• Focused Markdown, Hygiene, and quality-score tests on Windows: 366 passed, 1 skipped (symlink privileges), rerun on fec0b96. The earlier combined run including upstream fix: scan Markdown headings for PII instead of skipping them #96's Security tests was 566 passed, 1 skipped.
• Expanded verification from the original validator-only run to the full Linux suite with all extras: 5343 passed, 51 skipped, 2 failed on merge head fec0b96. Both failures were also reproduced on unchanged upstream 5387261: the runtime-discovery test sees the host's /usr/bin/codex, and the legacy bridge-port test cannot bind the already occupied port 18080. No host services or installed tools were changed to work around these tests.
• Ruff check: passed.
• Python package build: passed (sdist and wheel).

The regressions exercise the run_validation boundary and CLI/Markdown reporting. Five new unsafe-anchor cases failed on the previous published behavior and now produce a finding while preserving the subsequent link check. A dedup regression checks repeated invalid hrefs across three link syntaxes in two documents. A 2,704-case comparison found no changes to the helper's default normalization results. Malformed-frontmatter tests assert that body links are still checked; unexpected lookup RuntimeErrors propagate. Truncation tests cover control characters at the display boundary, distinguishing the CLI's intentional SGR colors from injected control sequences. Their fixed-width console separates the message-escaping check from intentional terminal reflow.

Scaling checks cover all four unclosed HTML forms at 8/16/32/64 KiB using the cumulative suffix length passed to the HTML regex rule, not elapsed-time thresholds. The inline-source cache tests also fail under a deliberately stale-cache mutation: all four expose a hidden anchor that must remain suppressed.

Same-host timing

Linux / Intel Core i9-13900K / Python 3.13.13 / markdown-it-py 4.2.0 / PyYAML 6.0.3. Median of five samples after one warm-up per size; upstream samples batch 100 calls to reduce clock noise. The timed boundary is _check_dead_links, including file enumeration/read, parsing, lookup, and findings. No full test suite ran concurrently.

Input: '<a href="before.md">before</a>' + '<!--' * (kib * 256) in one guide.md. The repeated-openers payload is 8/16/32/64 KiB, plus the 30-byte anchor prefix.

Both PR versions preserve the preceding anchor. The upstream regex does not recognize HTML anchors, so its lower timing is not equivalent functionality. All measured calls stayed within a 15-second budget. Revised sample ranges were 9.017–9.192 / 18.928–19.415 / 41.902–42.350 / 100.643–100.906 ms.

The later merges of upstream #96 in 9f3e223 and #78 in fec0b96 resolved changelog-only conflicts by retaining both entries. Neither changed this PR's reviewed source/tests, or the Hygiene/Markdown implementation used for the timing comparison above.

The deterministic check measures 16,418 / 32,802 / 65,570 / 131,106 cumulative regex-input characters for the comment fixtures, at most twice the input length. The guard does four fixed-terminator rfind scans once per inline source (linear input work), then constant-size opener checks. The same bound holds for the tested processing-instruction, CDATA, and declaration families. This bounds the guard/regex-suffix work for these fixtures, not end-to-end parser time or all Markdown inputs.

Release Impact

• Updated CHANGELOG.md