fix: improve error messages for unclosed code fences (issue #31)

[jrepp]

Summary

Fixes confusing error messages when a code fence is left unclosed earlier in a document.

Problem (Issue #31)

When a code fence is left unclosed earlier in a markdown document, docuchango's error messages pointed to much later in the file and were confusing. The errors suggested that closing fences had "extra text" when they actually had language specifiers, making it difficult to diagnose the real issue.

Example of Confusing Errors (Before)

Given a file with:

• Line 100: markdown` (opening fence)
• Line 120: Missing closing
• Line 150: text` (new opening fence)
• Line 180: (closing fence)

Old error output:

Line 150: Closing code fence has extra text (```text), should be just ```
Line 180: Opening code fence missing language (use ```text for plain text)
Unclosed code block starting at line 180 (```<none>)

New error output:

Unclosed code block starting at line 100 (```markdown)
Line 150: This appears to be a new opening fence (```text), but was 
          interpreted as a closing fence due to the unclosed block above

Solution

The fix detects when a "closing fence with extra text" is actually an opening fence being misinterpreted:

1. Heuristic: If a "closing fence" has what looks like a language specifier (single word, <= 20 chars, no spaces), it's likely an opening fence
2. Report root cause first: Immediately report the unclosed block at its actual location
3. Explain cascading errors: Add helpful message about why subsequent fences are being misinterpreted
4. Recover state: Treat the fence as an opening fence and continue validation from there

Changes

• docuchango/validator.py: Enhanced code fence validation logic (lines 872-900)
• tests/test_validator.py: Added comprehensive test for issue Confusing error messages when code fence is unclosed earlier in document #31 scenario

Test Coverage

New test test_unclosed_code_fence_error_message verifies:

• ✅ Unclosed block is detected at the correct line
• ✅ Cascading error explanation is provided
• ✅ No confusing "extra text" errors without context

Test Status

✅ All 629 tests passing, 1 skipped

Closes #31

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 61.58%. Comparing base (f9a02a3) to head (7fb89fb).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
docuchango/validator.py	93.33%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #35      +/-   ##
==========================================
+ Coverage   61.01%   61.58%   +0.57%     
==========================================
  Files          18       23       +5     
  Lines        2193     2939     +746     
  Branches      378      545     +167     
==========================================
+ Hits         1338     1810     +472     
- Misses        812     1065     +253     
- Partials       43       64      +21     

Flag	Coverage Δ
unittests	61.58% <93.33%> (+0.57%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
docuchango/validator.py	45.24% <93.33%> (+0.27%)	⬆️

... and 6 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cc20b78...7fb89fb. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull Request Overview

This PR fixes confusing error messages when markdown code fences are left unclosed. Previously, unclosed fences caused cascading errors that pointed to wrong locations and suggested unrelated problems. The fix detects when a "closing fence with extra text" is actually an opening fence being misinterpreted, reports the root cause at the correct line, and explains the cascading effect.

Key Changes:

• Enhanced code fence validation logic to detect unclosed blocks earlier
• Improved error messaging to point to the actual unclosed fence location
• Added recovery mechanism to continue validation after detecting misinterpreted fences

Reviewed Changes

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

File	Description
docuchango/validator.py	Added heuristic detection for misinterpreted opening fences and improved error reporting for unclosed code blocks
tests/test_validator.py	Added comprehensive test case verifying correct detection and error messages for unclosed code fence scenarios

---

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

[jrepp]

✅ Addressed both review comments in commit 755da5c:

1. Changed not ' ' in remainder to ' ' not in remainder for better readability
2. Extracted magic number 18 as UNCLOSED_BLOCK_START_LINE constant with explanatory comment

All tests still passing. Thank you for the feedback!

[Copilot]

Pull Request Overview

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

---

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