fix(MDS004): distinguish blank-line-before-heading from missing heading - #82
Merged
Conversation
When the first AST child is a heading but not on line 1 (due to a leading blank line), report "found blank line" instead of the generic "first line should be a level N heading". This gives users an actionable hint — remove the blank line — instead of a confusing message that hides the real cause. Closes #80 https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
- Fix headingLine() returning 1 for empty headings after blank lines by checking HasBlankPreviousLines() as fallback - Add tests: multiple blank lines, empty heading, Level:0 default, ApplySettings level:0 boundary - Add message assertions to StartsWithParagraph and WrongLevel tests https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
HasBlankPreviousLines() is always true in goldmark, causing false positives on empty headings at line 1 (e.g. "# \n"). Replace with f.Source[0] == '\n' check. Add test for empty heading on line 1. https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
- Add \r check to headingLine fallback for Windows line endings - Add tests for setext headings (line 1 and after blank line) - Add test for heading with emphasis (# *Title*) https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
- Add test for heading with link markup (# [link](url)) - Add explanatory note in README for blank-line bad example where the leading blank line is invisible in the rendered code block https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
Contributor
There was a problem hiding this comment.
Pull request overview
Improves MDS004 diagnostics to explicitly report when the first heading is preceded by a leading blank line (rather than reporting a generic “missing heading” message), addressing confusion described in issue #80.
Changes:
- Update MDS004 rule logic to emit “found blank line” when the first AST child is a heading but not on line 1.
- Expand unit tests to cover more heading forms and the new diagnostic messaging.
- Add/extend rule documentation and fixtures to demonstrate the blank-line-before-heading case.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| internal/rules/firstlineheading/rule.go | Emits a more specific diagnostic when the first heading is not on line 1 and adds a fallback for empty headings. |
| internal/rules/firstlineheading/rule_test.go | Adds coverage for additional heading shapes and validates updated diagnostic messages. |
| internal/rules/MDS004-first-line-heading/bad/blank-line.md | Adds a bad fixture asserting the new “found blank line” diagnostic. |
| internal/rules/MDS004-first-line-heading/README.md | Documents the new diagnostic and adds an example for the blank-line-before-heading scenario. |
The fallback for empty headings only checked f.Source[0] for \n/\r, missing lines with only spaces/tabs before a newline (e.g. " \n# \n"). Scan horizontal whitespace up to the first line break to correctly detect all blank first lines. https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr
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
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.
When the first AST child is a heading but not on line 1 (due to a
leading blank line), report "found blank line" instead of the generic
"first line should be a level N heading". This gives users an
actionable hint — remove the blank line — instead of a confusing
message that hides the real cause.
Closes #80
https://claude.ai/code/session_01UVFoaMRowbWktK9pjCdTdr