Skip fenced code blocks in the link check, and report unclosed fences (#202)

[realmarcin]

Closes #202.

The bug

check_markdown_links scanned line by line with no notion of fenced code, so a link written as an example inside a fence was treated as a real link:

```markdown
see [the docs](docs/example.md)
```

Nothing is affected today — the repo reports 0 findings. But pr-sanity now runs unfiltered on every PR (#201), so the first person to document a link pattern would have had an unrelated PR blocked by a link that was never broken.

Fence handling

Follows the CommonMark rules that actually matter here:

• an opening fence is 3+ backticks or tildes, indented at most 3 spaces
• a closing fence is the same character, at least as long, with no info string
• therefore a ````-fence can contain a ```-fence — which is how one documents a fenced block at all, including in pr-sanity's link check does not skip fenced code blocks #202 itself
• a tilde fence does not close a backtick fence

Inline code spans are blanked as well, since `[x](y.md)` is prose about a link rather than a link.

The real risk here was over-correcting

Skipping too much would silently stop verifying real links. That is worse than the false positive being removed, and it is exactly the failure this script exists to catch — a check that reports "all clear" because it stopped looking.

Two guards:

Measured coverage before and after against the live corpus, with an explicit diff of which links changed status:

	in-repo links verified
before	26
after	26
no longer checked	0

Unterminated fences are now their own finding. Without that, a single stray opening fence would make every later line in the file invisible to all checks while the run still printed "all clear". Now it says so and fails.

Testing

8 new tests: nested ````/``` fences, tilde fences, fences indented under list items, backtick-vs-tilde non-closing, inline code spans, the unterminated case, and a broken link inside a fence correctly not firing.

25 tests for this script, 177 total, just qc green. Runtime still 0.27s — it has to stay cheap enough that nobody is ever tempted to put it behind a paths: filter, which is the failure it exists to prevent.

🤖 Generated with Claude Code

[realmarcin]

Review

Adversarial pass over my own diff. Nothing to fix; one limitation filed.

The over-correction risk was the real one, and it is measured

The bug being fixed is a false positive. The dangerous fix is one that skips too much and silently stops verifying real links — worse than the false positive, and the exact failure this script exists to catch.

So the load-bearing evidence here is not "tests pass", it is the before/after coverage diff against the live corpus: 26 in-repo links verified before, 26 after, 0 changed status. If fence handling had swallowed real links, that number would have dropped and the diff would have named them.

Probed the parser rather than trusting it

input	behaviour	correct?
`` (two backticks)	not a fence, line still scanned	yes — needs 3+
```js as a closing attempt	does not close; info strings are opening-only	yes
~~~ inside a ``` block	does not close it	yes
```` wrapping ```	inner does not close outer	yes — this is how #202 itself is written
fence indented under a list item	opens a block	yes — up to 3 spaces
unmatched single `	left alone, link still checked	yes — conservative, does not over-strip
two adjacent inline spans	both blanked	yes

Filed, not fixed — #208

4-space indented code blocks are still scanned. CommonMark has two code-block forms; this PR handles fences, not indentation. Zero live instances, so no impact today.

I stopped short deliberately. Indented code is ambiguous with list continuation content — four spaces under a list item is indentation, not code — so a naive indent rule would silently skip real links inside lists. That is precisely the over-correction this PR's coverage measurement exists to prevent, and it would have dropped the 26. Doing it properly needs block-level parsing that tracks list context, or a real Markdown parser.

A parser (markdown-it-py) would subsume both #202 and #208 and be correct by construction. The cost is a dependency in a script whose whole selling point is being stdlib-only and 0.27s, so nobody is ever tempted to put it behind a paths: filter. If this class of bug shows up a third time, that trade flips — noted in the issue.

State

All four checks pass (pr-sanity 19s, qc, pytest, vendored-sync). 25 tests for this script, 177 total. Runtime 0.27s, unchanged.

Not merging — your call.

[Copilot]

Pull request overview

This PR updates scripts/pr_sanity.py’s Markdown link checker to understand fenced code blocks and inline code spans, preventing false-positive broken-link findings from links shown as examples. It also adds a new finding type for unterminated fences to avoid silently skipping the remainder of a file.

Changes:

• Add fence-aware line filtering (prose_lines) so fenced code blocks are skipped during link checks.
• Blank inline code spans before link extraction so prose about links isn’t treated as links.
• Report UNTERMINATED_FENCE when a fence is opened but never closed, and add targeted tests for these behaviors.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
scripts/pr_sanity.py	Introduces fenced-code/inline-code handling for link scanning and adds UNTERMINATED_FENCE reporting.
tests/test_pr_sanity.py	Adds tests for nested/tilde/indented fences, inline code spans, and unterminated fence reporting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.