Merge pull request #82 from jeduden/claude/plan-issue-80-bYJmI

fix(MDS004): distinguish blank-line-before-heading from missing heading

Author: jeduden

internal/rules/MDS004-first-line-heading/README.md

@@ -50,7 +50,7 @@ rules:
 
 ## Examples
 
-### Bad
+### Bad — content before heading
 
 <?include
 file: bad/default.md
@@ -65,6 +65,23 @@ Some content here.
 
 <?/include?>
 
+### Bad — blank line before heading
+
+The file below has a blank line between the frontmatter closing
+`---` and `# Title`. The blank line is not visible in the code
+block but triggers the diagnostic.
+
+<?include
+file: bad/blank-line.md
+wrap: markdown
+?>
+
+```markdown
+# Title
+```
+
+<?/include?>
+
 ### Good
 
 <?include
@@ -82,7 +99,8 @@ Some content here.
 
 ## Diagnostics
 
-| Message                                        | Condition                                   |
-|------------------------------------------------|---------------------------------------------|
-| `first line should be a level {level} heading`   | Line 1 is missing or not a heading          |
-| `first heading should be level {level}, got {n}` | First heading on line 1 has the wrong level |
+| Message                                                        | Condition                                           |
+|----------------------------------------------------------------|-----------------------------------------------------|
+| `first line should be a level {level} heading`                   | Line 1 is missing or not a heading                  |
+| `first line should be a level {level} heading, found blank line` | First child is a heading but preceded by blank line |
+| `first heading should be level {level}, got {n}`                 | First heading on line 1 has the wrong level         |

internal/rules/MDS004-first-line-heading/bad/blank-line.md

@@ -0,0 +1,8 @@
+---
+diagnostics:
+  - line: 1
+    column: 1
+    message: "first line should be a level 1 heading, found blank line"
+---
+
+# Title

internal/rules/firstlineheading/rule.go

@@ -50,7 +50,7 @@ func (r *Rule) Check(f *lint.File) []lint.Diagnostic {
 	}
 
 	if headingLine(heading, f) != 1 {
-		return r.diag(f, missingMsg)
+		return r.diag(f, fmt.Sprintf("first line should be a level %d heading, found blank line", level))
 	}
 
 	if heading.Level != level {
@@ -125,5 +125,19 @@ func headingLine(heading *ast.Heading, f *lint.File) int {
 			return f.LineOfOffset(t.Segment.Start)
 		}
 	}
+	// Empty headings (e.g. "# \n") have no text segments.
+	// Detect whether the first line is blank (only spaces/tabs
+	// before a newline). Markdown treats such lines as blank,
+	// so a heading on the following line starts on line 2.
+	for i := 0; i < len(f.Source); i++ {
+		b := f.Source[i]
+		if b == ' ' || b == '\t' {
+			continue
+		}
+		if b == '\n' || b == '\r' {
+			return 2
+		}
+		return 1
+	}
 	return 1
 }

internal/rules/firstlineheading/rule_test.go

@@ -17,6 +17,43 @@ func TestCheck_FirstLineH1_NoViolation(t *testing.T) {
 	require.Len(t, diags, 0, "expected 0 diagnostics, got %d: %+v", len(diags), diags)
 }
 
+func TestCheck_SetextHeading_NoViolation(t *testing.T) {
+	src := []byte("Title\n=====\n\nSome text\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 0, "setext heading on line 1 should pass, got %d: %+v", len(diags), diags)
+}
+
+func TestCheck_EmphasisHeading_NoViolation(t *testing.T) {
+	src := []byte("# *Title*\n\nSome text\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 0, "heading with emphasis on line 1 should pass, got %d: %+v", len(diags), diags)
+}
+
+func TestCheck_LinkHeading_NoViolation(t *testing.T) {
+	src := []byte("# [link](url)\n\nSome text\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 0, "heading with link on line 1 should pass, got %d: %+v", len(diags), diags)
+}
+
+func TestCheck_BlankLineSetextHeading(t *testing.T) {
+	src := []byte("\nTitle\n=====\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 1, "setext heading after blank line should fail, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading, found blank line", diags[0].Message)
+}
+
 func TestCheck_EmptyFile(t *testing.T) {
 	src := []byte("")
 	f, err := lint.NewFile("test.md", src)
@@ -36,6 +73,7 @@ func TestCheck_StartsWithParagraph(t *testing.T) {
 	r := &Rule{Level: 1}
 	diags := r.Check(f)
 	require.Len(t, diags, 1, "expected 1 diagnostic, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading", diags[0].Message)
 }
 
 func TestCheck_BlankLineThenHeading(t *testing.T) {
@@ -45,6 +83,57 @@ func TestCheck_BlankLineThenHeading(t *testing.T) {
 	r := &Rule{Level: 1}
 	diags := r.Check(f)
 	require.Len(t, diags, 1, "expected 1 diagnostic for heading not on line 1, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading, found blank line", diags[0].Message)
+}
+
+func TestCheck_MultipleBlankLinesThenHeading(t *testing.T) {
+	src := []byte("\n\n\n# Title\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 1, "expected 1 diagnostic, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading, found blank line", diags[0].Message)
+}
+
+func TestCheck_WhitespaceBlankLineThenEmptyHeading(t *testing.T) {
+	src := []byte("   \n# \n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 1,
+		"whitespace-only blank line before empty heading should trigger, got %d: %+v",
+		len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading, found blank line", diags[0].Message)
+}
+
+func TestCheck_BlankLineThenEmptyHeading(t *testing.T) {
+	src := []byte("\n# \n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 1, "expected 1 diagnostic for empty heading after blank line, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first line should be a level 1 heading, found blank line", diags[0].Message)
+}
+
+func TestCheck_EmptyHeadingOnLine1(t *testing.T) {
+	src := []byte("# \n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 1}
+	diags := r.Check(f)
+	require.Len(t, diags, 0, "empty heading on line 1 should not trigger diagnostic, got %d: %+v", len(diags), diags)
+}
+
+func TestCheck_LevelZeroDefault(t *testing.T) {
+	src := []byte("# Title\n")
+	f, err := lint.NewFile("test.md", src)
+	require.NoError(t, err)
+	r := &Rule{Level: 0}
+	diags := r.Check(f)
+	require.Len(t, diags, 0, "Level 0 should default to 1; expected 0 diagnostics, got %d: %+v", len(diags), diags)
 }
 
 func TestCheck_WrongLevel(t *testing.T) {
@@ -54,6 +143,7 @@ func TestCheck_WrongLevel(t *testing.T) {
 	r := &Rule{Level: 1}
 	diags := r.Check(f)
 	require.Len(t, diags, 1, "expected 1 diagnostic, got %d: %+v", len(diags), diags)
+	require.Equal(t, "first heading should be level 1, got 2", diags[0].Message)
 }
 
 func TestCheck_Level2Config(t *testing.T) {
@@ -103,6 +193,12 @@ func TestApplySettings_LevelOutOfRange(t *testing.T) {
 	require.Error(t, err, "expected error for level > 6")
 }
 
+func TestApplySettings_LevelZero(t *testing.T) {
+	r := &Rule{Level: 1}
+	err := r.ApplySettings(map[string]any{"level": 0})
+	require.Error(t, err, "expected error for level 0")
+}
+
 func TestApplySettings_UnknownKey(t *testing.T) {
 	r := &Rule{Level: 1}
 	err := r.ApplySettings(map[string]any{"unknown": true})