rule_test.go

package catalog

import (
	"os"
	"path/filepath"
	"strings"
	"testing"
	"testing/fstest"

	"github.com/jeduden/mdsmith/internal/lint"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

// helper creates a *lint.File with the given source and attaches the given FS.
func newTestFile(t *testing.T, path, source string, fs ...fstest.MapFS) *lint.File {
	t.Helper()
	f, err := lint.NewFile(path, []byte(source))
	require.NoError(t, err)
	if len(fs) > 0 {
		f.FS = fs[0]
	}
	return f
}

// expectDiags asserts the number of diagnostics and returns them.
func expectDiags(t *testing.T, diags []lint.Diagnostic, count int) {
	t.Helper()
	if len(diags) != count {
		msgs := make([]string, len(diags))
		for i, d := range diags {
			msgs[i] = d.Message
		}
		t.Fatalf("expected %d diagnostic(s), got %d: %v", count, len(diags), msgs)
	}
}

// expectDiagMsg asserts the first diagnostic has the given message substring.
func expectDiagMsg(t *testing.T, diags []lint.Diagnostic, msg string) {
	t.Helper()
	if len(diags) == 0 {
		t.Fatalf("expected diagnostic with message %q, got none", msg)
	}
	assert.Contains(t, diags[0].Message, msg,
		"expected diagnostic message containing %q, got %q", msg, diags[0].Message)
}

// expectDiagLine asserts the first diagnostic is on the given line.
func expectDiagLine(t *testing.T, diags []lint.Diagnostic, line int) {
	t.Helper()
	if len(diags) == 0 {
		t.Fatalf("expected diagnostic on line %d, got none", line)
	}
	if diags[0].Line != line {
		t.Errorf("expected diagnostic on line %d, got line %d (message: %s)", line, diags[0].Line, diags[0].Message)
	}
}

// =====================================================================
// Rule metadata
// =====================================================================

func TestRule_ID(t *testing.T) {
	r := &Rule{}
	if r.ID() != "MDS019" {
		t.Errorf("expected ID MDS019, got %s", r.ID())
	}
}

func TestRule_Name(t *testing.T) {
	r := &Rule{}
	if r.Name() != "catalog" {
		t.Errorf("expected Name catalog, got %s", r.Name())
	}
}

// =====================================================================
// Core rendering
// =====================================================================

func TestRendering_MinimalMode(t *testing.T) {
	// Minimal mode (glob only) produces plain bullet list with basenames as link text.
	src := `<?catalog
glob: "docs/*.md"
?>
- [api.md](docs/api.md)
- [guide.md](docs/guide.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("# API\n")},
		"docs/guide.md": {Data: []byte("# Guide\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_ListTemplateWithFrontMatter(t *testing.T) {
	// List template renders per-file with front matter fields.
	src := `<?catalog
glob: "docs/*.md"
row: "- [{title}]({filename}) -- {description}"
?>
- [API Reference](docs/api.md) -- Complete API docs
- [Getting Started](docs/guide.md) -- How to get started
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\ntitle: API Reference\ndescription: Complete API docs\n---\n# API\n")},
		"docs/guide.md": {Data: []byte("---\ntitle: Getting Started\ndescription: How to get started\n---\n# Guide\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_TableHeaderRows(t *testing.T) {
	// Table template renders static header + per-file rows.
	src := `<?catalog
glob: "docs/*.md"
header: |
  | Title | Description |
  |-------|-------------|
row: "| [{title}]({filename}) | {description} |"
?>
| Title                            | Description        |
|----------------------------------|--------------------|
| [API Reference](docs/api.md)     | Complete API docs  |
| [Getting Started](docs/guide.md) | How to get started |
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\ntitle: API Reference\ndescription: Complete API docs\n---\n# API\n")},
		"docs/guide.md": {Data: []byte("---\ntitle: Getting Started\ndescription: How to get started\n---\n# Guide\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_MultilineRowPipe(t *testing.T) {
	// Multi-line `row` value with YAML `|` produces multi-line output per file.
	// YAML `|` clips trailing newline to one.
	src := `<?catalog
glob: "docs/*.md"
row: |
  ### {title}
  {description}
?>
### API
Complete API docs
### Guide
How to get started
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\ntitle: API\ndescription: Complete API docs\n---\n")},
		"docs/guide.md": {Data: []byte("---\ntitle: Guide\ndescription: How to get started\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_MultilineRowPipePlus(t *testing.T) {
	// Multi-line `row` value with YAML `|+` preserves trailing blank lines between entries.
	src := `<?catalog
glob: "docs/*.md"
row: |+
  ### [{title}]({filename})

  {description}

?>
### [API](docs/api.md)

Complete API docs

### [Guide](docs/guide.md)

How to get started

<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\ntitle: API\ndescription: Complete API docs\n---\n")},
		"docs/guide.md": {Data: []byte("---\ntitle: Guide\ndescription: How to get started\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_PipeStripImplicitNewline(t *testing.T) {
	// YAML `|-` strips trailing newlines; implicit `\n` rule adds one back.
	src := `<?catalog
glob: "*.md"
row: |-
  - {filename}
?>
- a.md
- b.md
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
		"b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_EachValueTerminatedByNewline(t *testing.T) {
	// Each rendered value (header, row, footer, empty) is terminated by implicit trailing `\n`.
	src := `<?catalog
glob: "*.md"
header: "| Title |"
row: "| {filename} |"
footer: "---"
?>
| Title |
| a.md |
---
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_FooterRendersAfterRows(t *testing.T) {
	// `footer` renders static content after rows.
	src := `<?catalog
glob: "*.md"
header: |
  | Title | Description |
  |-------|-------------|
row: "| [{title}]({filename}) | {description} |"
footer: |

  ---
?>
| Title       | Description |
|-------------|-------------|
| [API](a.md) | docs        |

---
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: API\ndescription: docs\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_EmptyFallbackRendersWhenNoMatches(t *testing.T) {
	// `empty` renders fallback text when glob matches zero files.
	src := `<?catalog
glob: "nonexistent/*.md"
empty: No documents found.
?>
No documents found.
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_EmptyAloneWithoutRowIsValid(t *testing.T) {
	// `empty` alone without `row` is valid (no diagnostic).
	src := `<?catalog
glob: "nonexistent/*.md"
empty: No documents found.
?>
No documents found.
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_EmptyPlusHeaderWithoutRowProducesDiag(t *testing.T) {
	// `empty` + `header` without `row` produces missing-row diagnostic.
	src := `<?catalog
glob: "*.md"
empty: No docs.
header: |
  | Title |
  |-------|
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `generated section template missing required "row" key`)
}

func TestRendering_EmptyValueGetsTrailingNewline(t *testing.T) {
	// `empty` value gets trailing `\n`.
	src := `<?catalog
glob: "nonexistent/*.md"
empty: "Nothing here"
?>
Nothing here
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_NoEmptyNoMatchesEmptyContent(t *testing.T) {
	// No `empty` + no matches produces empty content between markers.
	src := `<?catalog
glob: "nonexistent/*.md"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_WhenEmptyRendersHeaderFooterNotIncluded(t *testing.T) {
	// When `empty` renders, `header`/`footer` are not included.
	src := `<?catalog
glob: "nonexistent/*.md"
header: "| Title |"
row: "| {filename} |"
footer: "---"
empty: No documents.
?>
No documents.
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_WhenGlobMatchesFilesEmptyIgnored(t *testing.T) {
	// When glob matches files and `empty` is defined, `empty` is ignored.
	src := `<?catalog
glob: "*.md"
row: "- {filename}"
empty: No documents.
?>
- a.md
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Diagnostics
// =====================================================================

func TestDiag_OrphanedEndMarker(t *testing.T) {
	src := `Some text
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "unexpected generated section end marker")
	// Orphaned end markers are reported on the end marker line.
	expectDiagLine(t, diags, 2)
}

func TestDiag_NestedStartMarkers(t *testing.T) {
	// Unbalanced nesting: inner start marker consumes the only end
	// marker, leaving the outer pair unclosed.
	src := `<?catalog
glob: "*.md"
?>
<?catalog
glob: "other/*.md"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	found := false
	for _, d := range diags {
		if strings.Contains(d.Message, "no closing marker") {
			found = true
			if d.Line != 1 {
				t.Errorf("expected unclosed marker diagnostic on line 1, got %d", d.Line)
			}
			break
		}
	}
	assert.True(t, found, "expected 'no closing marker' diagnostic for unbalanced nesting")
}

func TestDiag_NonStringYAMLValues(t *testing.T) {
	src := `<?catalog
glob: 42
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	found := false
	for _, d := range diags {
		if strings.Contains(d.Message, `non-string value for key "glob"`) {
			found = true
			break
		}
	}
	assert.True(t, found, "expected non-string value diagnostic for glob, got %v", diags)
}

func TestDiag_NonStringMultipleKeys(t *testing.T) {
	// Non-string YAML values produce diagnostic per key.
	src := `<?catalog
glob: 42
sort: true
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	nonStringCount := 0
	for _, d := range diags {
		if strings.Contains(d.Message, "non-string value for key") {
			nonStringCount++
		}
	}
	if nonStringCount < 2 {
		t.Errorf("expected at least 2 non-string value diagnostics, got %d", nonStringCount)
	}
}

// =====================================================================
// Sort
// =====================================================================

// =====================================================================
// Template fields
// =====================================================================

func TestFields_FilenameResolvesToRelativePath(t *testing.T) {
	// `{filename}` resolves to path relative to linted file's directory, never has leading `./`.
	src := `<?catalog
glob: "docs/*.md"
row: "- {filename}"
?>
- docs/api.md
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md": {Data: []byte("# API\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestFields_MissingFrontMatterFieldsEmpty(t *testing.T) {
	// Files without front matter resolve fields to empty string.
	src := `<?catalog
glob: "*.md"
row: "- [{title}]({filename})"
?>
- [](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# No front matter\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestFields_HeaderFooterContainTemplateLiterals(t *testing.T) {
	// `header`/`footer` containing `{...}` render literally (no template expansion).
	src := `<?catalog
glob: "*.md"
header: "{title} header"
row: "- {filename}"
footer: "{footer} end"
?>
{title} header
- a.md
{footer} end
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestFields_EmptyContainsTemplateLiterals(t *testing.T) {
	// `empty` containing `{...}` renders literally.
	src := `<?catalog
glob: "nonexistent/*.md"
empty: "{something} no data"
?>
{something} no data
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Nested front-matter access (CUE paths)
// =====================================================================

func TestRendering_NestedFrontMatter(t *testing.T) {
	src := `<?catalog
glob: "docs/*.md"
row: "- [{params.subtitle}]({filename})"
?>
- [Overview](docs/api.md)
- [Intro](docs/guide.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\nparams:\n  subtitle: Overview\n---\n# API\n")},
		"docs/guide.md": {Data: []byte("---\nparams:\n  subtitle: Intro\n---\n# Guide\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_QuotedKeyFrontMatter(t *testing.T) {
	src := `<?catalog
glob: "docs/*.md"
row: '- [{"my-key"}]({filename})'
?>
- [value](docs/a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("---\nmy-key: value\n---\n# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_DeepNestedFrontMatter(t *testing.T) {
	src := `<?catalog
glob: "docs/*.md"
row: "- {a.b.c}"
?>
- deep
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("---\na:\n  b:\n    c: deep\n---\n# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestRendering_MissingNestedFieldEmpty(t *testing.T) {
	src := `<?catalog
glob: "docs/*.md"
row: "- [{params.missing}]({filename})"
?>
- [](docs/a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("---\nparams:\n  subtitle: Overview\n---\n# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestDiag_YAMLFlowMappingConflict(t *testing.T) {
	src := `<?catalog
glob: "*.md"
row: {title}
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "quote")
}

// =====================================================================
// Fix behavior
// =====================================================================

func TestFix_IdempotentOnFreshContent(t *testing.T) {
	src := `<?catalog
glob: "*.md"
?>
- [a.md](a.md)
- [b.md](b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
		"b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	result := r.Fix(f)
	if string(result) != src {
		t.Errorf("Fix on fresh content should be idempotent.\nExpected:\n%s\nGot:\n%s", src, string(result))
	}
}

func TestFix_LeavesTemplateErrorSectionsUnchanged(t *testing.T) {
	// Invalid template syntax -> fix leaves section unchanged.
	src := `<?catalog
glob: "*.md"
row: "{title"
?>
old content
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	result := r.Fix(f)
	if string(result) != src {
		t.Errorf("Fix should leave template-error sections unchanged.\nExpected:\n%s\nGot:\n%s", src, string(result))
	}
}

func TestFix_FullCycleIdempotent(t *testing.T) {
	// First fix generates content, second fix should leave it unchanged.
	src := `<?catalog
glob: "*.md"
row: "- [{title}]({filename})"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Alpha\n---\n# A\n")},
		"b.md": {Data: []byte("---\ntitle: Beta\n---\n# B\n")},
	}

	// First fix.
	f1 := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	result1 := r.Fix(f1)

	// Second fix on the result of the first fix.
	f2 := newTestFile(t, "index.md", string(result1), mapFS)
	result2 := r.Fix(f2)

	if string(result1) != string(result2) {
		t.Errorf("Fix is not idempotent.\nFirst:\n%s\nSecond:\n%s", string(result1), string(result2))
	}
}

func TestFix_MultipleMarkerPairs(t *testing.T) {
	src := `<?catalog
glob: "a/*.md"
?>
old
<?/catalog?>

<?catalog
glob: "b/*.md"
?>
old
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a/one.md": {Data: []byte("# One\n")},
		"b/two.md": {Data: []byte("# Two\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	result := r.Fix(f)

	assert.Contains(t, string(result), "- [one.md](a/one.md)", "Fix should regenerate first section with a/one.md")
	assert.Contains(t, string(result), "- [two.md](b/two.md)", "Fix should regenerate second section with b/two.md")
}

// =====================================================================
// Edge cases
// =====================================================================

func TestEdge_MarkersInsideFencedCodeBlock(t *testing.T) {
	src := "```\n<?catalog\nglob: \"*.md\"\n?>\n<?/catalog?>\n```\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_MarkersInsideIndentedCodeBlock(t *testing.T) {
	// Indented code blocks (4-space indent) should also ignore markers.
	src := "Paragraph before.\n\n" +
		"    <?catalog\n    glob: \"*.md\"\n    ?>\n" +
		"    <?/catalog?>\n\nParagraph after.\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_MarkersInsideHTMLBlock(t *testing.T) {
	// goldmark treats <div>...</div> as an HTML block.
	src := "<div>\n<?catalog\nglob: \"*.md\"\n?>\n<?/catalog?>\n</div>\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_MarkersInsideHTMLBlockWithClosure(t *testing.T) {
	// HTML block type 6 with a closing blank line as closure.
	// <table> is recognized as an HTML block that includes content until a blank line.
	src := "<table>\n<tr><td><?catalog\nglob: \"*.md\"\n?></td></tr>\n</table>\n\nText after.\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	// Markers inside HTML block should be ignored. No structural errors expected.
	for _, d := range diags {
		if strings.Contains(d.Message, "no closing marker") ||
			strings.Contains(d.Message, "unexpected") {
			t.Errorf("markers inside HTML block should be ignored: %s", d.Message)
		}
	}
}

func TestEdge_MarkersInsidePreBlock(t *testing.T) {
	// goldmark HTML block type 1 (<pre>) has explicit closure (</pre>).
	// Markers inside should be ignored.
	src := "<pre>\n<?catalog\nglob: \"*.md\"\n?>\n<?/catalog?>\n</pre>\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_MarkersInsideScriptBlock(t *testing.T) {
	// goldmark HTML block type 1 (<script>) has explicit closure (</script>).
	src := "<script>\n<?catalog\nglob: \"*.md\"\n?>\n<?/catalog?>\n</script>\n"
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_TerminatorAllowsLeadingTrailingWhitespace(t *testing.T) {
	// `?>` terminator allows leading/trailing whitespace.
	src := `<?catalog
glob: "*.md"
  ?>
- [a.md](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# Hello\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_EndMarkerWithWhitespace(t *testing.T) {
	src := `<?catalog
glob: "*.md"
?>
- [a.md](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# Hello\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_SingleLineStartMarker(t *testing.T) {
	// Single-line start marker has empty YAML body (triggers missing-parameter diagnostic).
	src := `<?catalog?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `missing required "glob" parameter`)
}

func TestEdge_StdinInputSkipsRule(t *testing.T) {
	// Stdin input skips the rule (`f.FS == nil`).
	src := `<?catalog
glob: "*.md"
?>
stale content
<?/catalog?>
`
	f := newTestFile(t, "index.md", src) // no FS set -> nil
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_StdinInputFixReturnsSourceUnchanged(t *testing.T) {
	src := `<?catalog
glob: "*.md"
?>
stale content
<?/catalog?>
`
	f := newTestFile(t, "index.md", src) // no FS set -> nil
	r := &Rule{}
	result := r.Fix(f)
	if string(result) != src {
		t.Errorf("Fix with nil FS should return source unchanged")
	}
}

func TestEdge_GlobMatchingDirectorySkipped(t *testing.T) {
	// Directories matched by glob should be silently skipped.
	src := `<?catalog
glob: "*"
?>
- [a.md](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md":    {Data: []byte("# A\n")},
		"subdir/": {Data: []byte("")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_MultipleMarkerPairsIndependent(t *testing.T) {
	// Multiple marker pairs in one file processed independently.
	src := `<?catalog
glob: "a/*.md"
?>
- [one.md](a/one.md)
<?/catalog?>

Text between sections.

<?catalog
glob: "b/*.md"
?>
- [two.md](b/two.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a/one.md": {Data: []byte("# One\n")},
		"b/two.md": {Data: []byte("# Two\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_AllDiagnosticsReportColumn1(t *testing.T) {
	tests := []struct {
		name string
		src  string
	}{
		{
			"stale",
			"<?catalog\nglob: \"*.md\"\n?>\nold\n<?/catalog?>\n",
		},
		{
			"unclosed",
			"<?catalog\nglob: \"*.md\"\n?>\nold\n",
		},
		{
			"orphaned",
			"<?/catalog?>\n",
		},
		{
			"missing glob",
			"<?catalog\nsort: path\n?>\n<?/catalog?>\n",
		},
		{
			"empty glob",
			"<?catalog\nglob: \"\"\n?>\n<?/catalog?>\n",
		},
		{
			"empty sort",
			"<?catalog\nglob: \"*.md\"\nsort: \"\"\n?>\n<?/catalog?>\n",
		},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			mapFS := fstest.MapFS{
				"a.md": {Data: []byte("# A\n")},
			}
			f := newTestFile(t, "index.md", tc.src, mapFS)
			r := &Rule{}
			diags := r.Check(f)
			for _, d := range diags {
				if d.Column != 1 {
					t.Errorf("expected column 1, got %d for message: %s", d.Column, d.Message)
				}
			}
		})
	}
}

func TestEdge_RecursiveGlobPatterns(t *testing.T) {
	// Recursive `**` glob patterns are supported.
	src := `<?catalog
glob: "**/*.md"
?>
- [deep.md](a/b/c/deep.md)
- [top.md](top.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"top.md":        {Data: []byte("# Top\n")},
		"a/b/c/deep.md": {Data: []byte("# Deep\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_UnknownYAMLKeysIgnored(t *testing.T) {
	// Unknown YAML keys are silently ignored.
	src := `<?catalog
glob: "*.md"
unknown_key: something
another: value
?>
- [a.md](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# Hello\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	for _, d := range diags {
		assert.NotContains(t, d.Message, "unknown_key",
			"unknown YAML keys should be silently ignored, got: %s", d.Message)
		assert.NotContains(t, d.Message, "another",
			"unknown YAML keys should be silently ignored, got: %s", d.Message)
	}
}

func TestEdge_DuplicateYAMLKeysRejected(t *testing.T) {
	// gopkg.in/yaml.v3 rejects duplicate keys as invalid YAML.
	src := `<?catalog
glob: "nonexistent/*.md"
glob: "*.md"
?>
- [a.md](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# Hello\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "invalid YAML")
}

func TestEdge_InvalidFrontMatterTreatedAsNone(t *testing.T) {
	// Matched file with invalid front matter treated as no front matter.
	src := `<?catalog
glob: "*.md"
row: "- [{title}]({filename})"
?>
- [](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ninvalid: [yaml\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_DotfilesMatchedByStar(t *testing.T) {
	// The doublestar library matches dotfiles with `*` by default.
	// Both visible.md and .hidden.md are matched.
	src := `<?catalog
glob: "*.md"
?>
- [.hidden.md](.hidden.md)
- [visible.md](visible.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"visible.md": {Data: []byte("# Visible\n")},
		".hidden.md": {Data: []byte("# Hidden\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_NoFrontMatterFilenameWorks(t *testing.T) {
	src := `<?catalog
glob: "*.md"
row: "{filename}"
?>
a.md
b.md
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("no front matter here\n")},
		"b.md": {Data: []byte("also no front matter\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestEdge_InvalidYAMLShortCircuits(t *testing.T) {
	// Invalid YAML should prevent template/glob validation.
	src := `<?catalog
glob: [invalid
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "invalid YAML")
}

func TestEdge_NonStringValuesShortCircuit(t *testing.T) {
	// Non-string values should prevent further validation.
	src := `<?catalog
glob: 42
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	// Should get non-string error but NOT a missing glob error.
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "non-string value")
}

// =====================================================================
// Table-driven diagnostic scenarios
// =====================================================================

// diagScenario is a test case for diagnostic scenario table tests.
type diagScenario struct {
	name      string
	src       string
	fs        fstest.MapFS
	wantCount int
	wantMsg   string
}

// runDiagScenarios runs a slice of diagnostic test scenarios.
func runDiagScenarios(t *testing.T, tests []diagScenario) {
	t.Helper()
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			f := newTestFile(t, "index.md", tc.src, tc.fs)
			r := &Rule{}
			diags := r.Check(f)
			expectDiags(t, diags, tc.wantCount)
			if tc.wantMsg != "" && len(diags) > 0 {
				expectDiagMsg(t, diags, tc.wantMsg)
			}
		})
	}
}

func TestCheck_StructuralErrors(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name: "valid pair no errors",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [a.md](a.md)\n<?/catalog?>\n",
			fs:        fstest.MapFS{"a.md": {Data: []byte("# A\n")}},
			wantCount: 0,
		},
		{
			name:      "unclosed start",
			src:       "<?catalog\nglob: \"*.md\"\n?>\ncontent\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "no closing marker",
		},
		{
			name:      "orphaned end",
			src:       "text\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "unexpected generated section end marker",
		},
		{
			name: "stale section",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [a.md](a.md)\n<?/catalog?>\n",
			fs:        fstest.MapFS{"a.md": {Data: []byte("# A\n")}, "b.md": {Data: []byte("# B\n")}},
			wantCount: 1,
			wantMsg:   "generated section is out of date",
		},
	})
}

func TestCheck_DirectiveErrors(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name:      "invalid YAML",
			src:       "<?catalog\n: invalid : yaml ::: [\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid YAML",
		},
	})
}

func TestCheck_GlobErrors(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name:      "empty glob",
			src:       "<?catalog\nglob: \"\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `empty "glob" parameter`,
		},
		{
			name:      "absolute glob",
			src:       "<?catalog\nglob: /etc/files/*.md\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "absolute glob path",
		},
		{
			name:      "glob with ..",
			src:       "<?catalog\nglob: \"../*.md\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `".." path traversal`,
		},
		{
			name:      "missing glob",
			src:       "<?catalog\nsort: path\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `missing required "glob" parameter`,
		},
		{
			name:      "invalid glob pattern",
			src:       "<?catalog\nglob: \"[invalid\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid glob pattern",
		},
	})
}

func TestCheck_TemplateErrors(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name:      "empty row",
			src:       "<?catalog\nglob: \"*.md\"\nrow: \"\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `empty "row" value`,
		},
		{
			name: "header without row",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"header: \"| T |\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `missing required "row" key`,
		},
		{
			name: "footer without row",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"footer: \"---\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `missing required "row" key`,
		},
		{
			name: "header and footer without row",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"header: \"| Title |\"\nfooter: \"---\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `missing required "row" key`,
		},
		{
			name: "invalid template syntax",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"row: \"{title\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid template",
		},
	})
}

func TestCheck_SortErrors(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name:      "empty sort",
			src:       "<?catalog\nglob: \"*.md\"\nsort: \"\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   `empty "sort" value`,
		},
		{
			name:      "sort dash only",
			src:       "<?catalog\nglob: \"*.md\"\nsort: \"-\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid sort value",
		},
		{
			name: "sort with whitespace",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: \"foo bar\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid sort key",
		},
		{
			name: "sort with tab",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: \"foo\tbar\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 1,
			wantMsg:   "invalid sort key",
		},
	})
}

// =====================================================================
// Table-driven content generation tests
// =====================================================================

func TestCheck_ContentGeneration_MinimalMode(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name: "up to date",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [hello.md](hello.md)\n<?/catalog?>\n",
			fs:        fstest.MapFS{"hello.md": {Data: []byte("# Hello\n")}},
			wantCount: 0,
		},
		{
			name: "stale",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [old.md](old.md)\n<?/catalog?>\n",
			fs:        fstest.MapFS{"new.md": {Data: []byte("# New\n")}},
			wantCount: 1,
		},
	})
}

func TestCheck_ContentGeneration_TemplateAndEmpty(t *testing.T) {
	runDiagScenarios(t, []diagScenario{
		{
			name: "template mode with front matter up to date",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"row: \"- [{title}]({filename})\"\n?>\n" +
				"- [My Title](a.md)\n<?/catalog?>\n",
			fs:        fstest.MapFS{"a.md": {Data: []byte("---\ntitle: My Title\n---\n# A\n")}},
			wantCount: 0,
		},
		{
			name: "empty fallback up to date",
			src: "<?catalog\n" +
				"glob: \"nonexistent/*.md\"\nempty: No files found.\n?>\n" +
				"No files found.\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 0,
		},
		{
			name:      "no empty no matches empty content",
			src:       "<?catalog\nglob: \"nonexistent/*.md\"\n?>\n<?/catalog?>\n",
			fs:        fstest.MapFS{},
			wantCount: 0,
		},
	})
}

// =====================================================================
// Table-driven Fix tests
// =====================================================================

func TestFix_Scenarios(t *testing.T) {
	tests := []struct {
		name     string
		src      string
		fs       fstest.MapFS
		contains []string
	}{
		{
			name: "regenerate stale minimal",
			src: `<?catalog
glob: "*.md"
?>
<?/catalog?>
`,
			fs:       fstest.MapFS{"a.md": {Data: []byte("# A\n")}},
			contains: []string{"- [a.md](a.md)"},
		},
		{
			name: "regenerate stale template",
			src: `<?catalog
glob: "*.md"
row: "- [{title}]({filename})"
?>
<?/catalog?>
`,
			fs:       fstest.MapFS{"a.md": {Data: []byte("---\ntitle: Hello\n---\n")}},
			contains: []string{"- [Hello](a.md)"},
		},
		{
			name: "fix with empty fallback",
			src: `<?catalog
glob: "nonexistent/*.md"
empty: Nothing here.
?>
old content
<?/catalog?>
`,
			fs:       fstest.MapFS{},
			contains: []string{"Nothing here."},
		},
	}

	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			f := newTestFile(t, "index.md", tc.src, tc.fs)
			r := &Rule{}
			result := string(r.Fix(f))
			for _, sub := range tc.contains {
				assert.Contains(t, result, sub, "Fix result missing %q.\nGot:\n%s", sub, result)
			}
		})
	}
}

// =====================================================================
// Table-driven Sort tests
// =====================================================================

// sortScenario is a test case for sort behavior validation (expects 0 diagnostics).
type sortScenario struct {
	name string
	src  string
	fs   fstest.MapFS
}

// runSortScenarios runs a slice of sort scenarios, each expecting zero diagnostics.
func runSortScenarios(t *testing.T, tests []sortScenario) {
	t.Helper()
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			f := newTestFile(t, "index.md", tc.src, tc.fs)
			r := &Rule{}
			diags := r.Check(f)
			expectDiags(t, diags, 0)
		})
	}
}

func TestSort_PathAndFilename(t *testing.T) {
	threeFiles := fstest.MapFS{
		"c.md": {Data: []byte("# C\n")},
		"a.md": {Data: []byte("# A\n")},
		"b.md": {Data: []byte("# B\n")},
	}
	runSortScenarios(t, []sortScenario{
		{
			name: "path ascending (default)",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [a.md](a.md)\n- [b.md](b.md)\n- [c.md](c.md)\n<?/catalog?>\n",
			fs: threeFiles,
		},
		{
			name: "path descending",
			src: "<?catalog\nglob: \"*.md\"\nsort: -path\n?>\n" +
				"- [c.md](c.md)\n- [b.md](b.md)\n- [a.md](a.md)\n<?/catalog?>\n",
			fs: threeFiles,
		},
		{
			name: "by filename (basename)",
			src: "<?catalog\nglob: \"**/*.md\"\nsort: filename\n?>\n" +
				"- [apple.md](z/apple.md)\n- [banana.md](a/banana.md)\n<?/catalog?>\n",
			fs: fstest.MapFS{
				"a/banana.md": {Data: []byte("# Banana\n")},
				"z/apple.md":  {Data: []byte("# Apple\n")},
			},
		},
		{
			name: "filename descending",
			src: "<?catalog\nglob: \"**/*.md\"\nsort: -filename\n?>\n" +
				"- [beta.md](a/beta.md)\n- [alpha.md](z/alpha.md)\n<?/catalog?>\n",
			fs: fstest.MapFS{
				"z/alpha.md": {Data: []byte("# Alpha\n")},
				"a/beta.md":  {Data: []byte("# Beta\n")},
			},
		},
		{
			name: "case-insensitive path sort",
			src: "<?catalog\nglob: \"*.md\"\n?>\n" +
				"- [AAA.md](AAA.md)\n- [bbb.md](bbb.md)\n<?/catalog?>\n",
			fs: fstest.MapFS{
				"bbb.md": {Data: []byte("# B\n")},
				"AAA.md": {Data: []byte("# A\n")},
			},
		},
	})
}

func TestSort_FrontMatterKey(t *testing.T) {
	twoFiles := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Zulu\n---\n")},
		"b.md": {Data: []byte("---\ntitle: Alpha\n---\n")},
	}
	runSortScenarios(t, []sortScenario{
		{
			name: "title ascending",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: title\nrow: \"- [{title}]({filename})\"\n?>\n" +
				"- [Alpha](b.md)\n- [Zulu](a.md)\n<?/catalog?>\n",
			fs: twoFiles,
		},
		{
			name: "title descending",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: -title\nrow: \"- [{title}]({filename})\"\n?>\n" +
				"- [Zulu](a.md)\n- [Alpha](b.md)\n<?/catalog?>\n",
			fs: twoFiles,
		},
		{
			name: "front matter key in minimal mode",
			src: "<?catalog\nglob: \"*.md\"\nsort: title\n?>\n" +
				"- [b.md](b.md)\n- [a.md](a.md)\n<?/catalog?>\n",
			fs: twoFiles,
		},
	})
}

func TestSort_TiebreakerAndCaseInsensitive(t *testing.T) {
	runSortScenarios(t, []sortScenario{
		{
			name: "tiebreaker when values equal",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: title\nrow: \"- [{title}]({filename})\"\n?>\n" +
				"- [Same](a.md)\n- [Same](b.md)\n<?/catalog?>\n",
			fs: fstest.MapFS{
				"a.md": {Data: []byte("---\ntitle: Same\n---\n")},
				"b.md": {Data: []byte("---\ntitle: Same\n---\n")},
			},
		},
		{
			name: "case-insensitive title",
			src: "<?catalog\nglob: \"*.md\"\n" +
				"sort: title\nrow: \"- [{title}]({filename})\"\n?>\n" +
				"- [alpha](a.md)\n- [Beta](b.md)\n<?/catalog?>\n",
			fs: fstest.MapFS{
				"a.md": {Data: []byte("---\ntitle: alpha\n---\n")},
				"b.md": {Data: []byte("---\ntitle: Beta\n---\n")},
			},
		},
	})
}

// =====================================================================
// Internal function tests
// =====================================================================

func TestParseSort_Default(t *testing.T) {
	key, desc := parseSort(map[string]string{})
	if key != "path" || desc {
		t.Errorf("expected (path, false), got (%s, %v)", key, desc)
	}
}

func TestParseSort_Ascending(t *testing.T) {
	key, desc := parseSort(map[string]string{"sort": "title"})
	if key != "title" || desc {
		t.Errorf("expected (title, false), got (%s, %v)", key, desc)
	}
}

func TestParseSort_Descending(t *testing.T) {
	key, desc := parseSort(map[string]string{"sort": "-title"})
	if key != "title" || !desc {
		t.Errorf("expected (title, true), got (%s, %v)", key, desc)
	}
}

func TestParseSort_EmptyValue(t *testing.T) {
	key, desc := parseSort(map[string]string{"sort": ""})
	if key != "path" || desc {
		t.Errorf("expected (path, false) for empty, got (%s, %v)", key, desc)
	}
}

func TestParseRowTemplate_Valid(t *testing.T) {
	err := parseRowTemplate("- [{title}]({filename})")
	require.NoError(t, err, "unexpected error: %v", err)
}

func TestParseRowTemplate_Invalid(t *testing.T) {
	err := parseRowTemplate("{title")
	require.Error(t, err, "expected error for invalid template")
}

func TestContainsDotDot(t *testing.T) {
	tests := []struct {
		pattern string
		want    bool
	}{
		{"../foo", true},
		{"foo/../bar", true},
		{"foo/bar/..", true},
		{"foo/bar", false},
		{"foo..bar", false},
		{"...", false},
		{"..", true},
	}
	for _, tc := range tests {
		t.Run(tc.pattern, func(t *testing.T) {
			got := containsDotDot(tc.pattern)
			assert.Equal(t, tc.want, got, "containsDotDot(%q) = %v, want %v", tc.pattern, got, tc.want)
		})
	}
}

func TestEnsureTrailingNewline(t *testing.T) {
	tests := []struct {
		input string
		want  string
	}{
		{"hello", "hello\n"},
		{"hello\n", "hello\n"},
		{"", "\n"},
		{"\n", "\n"},
		{"a\nb\n", "a\nb\n"},
		{"a\nb", "a\nb\n"},
	}
	for _, tc := range tests {
		got := ensureTrailingNewline(tc.input)
		assert.Equal(t, tc.want, got, "ensureTrailingNewline(%q) = %q, want %q", tc.input, got, tc.want)
	}
}

func TestSplitLines(t *testing.T) {
	input := []byte("a\nb\nc")
	lines := splitLines(input)
	require.Len(t, lines, 3, "expected 3 lines, got %d", len(lines))
	if string(lines[0]) != "a" {
		t.Errorf("line 0: got %q", string(lines[0]))
	}
	if string(lines[1]) != "b" {
		t.Errorf("line 1: got %q", string(lines[1]))
	}
	if string(lines[2]) != "c" {
		t.Errorf("line 2: got %q", string(lines[2]))
	}
}

func TestSplitLines_Empty(t *testing.T) {
	lines := splitLines([]byte(""))
	require.Len(t, lines, 1, "expected 1 line for empty input, got %d", len(lines))
	if string(lines[0]) != "" {
		t.Errorf("expected empty line, got %q", string(lines[0]))
	}
}

func TestSplitLines_SingleNewline(t *testing.T) {
	lines := splitLines([]byte("\n"))
	require.Len(t, lines, 2, "expected 2 lines for single newline, got %d", len(lines))
	if string(lines[0]) != "" {
		t.Errorf("expected empty first line, got %q", string(lines[0]))
	}
	if string(lines[1]) != "" {
		t.Errorf("expected empty second line, got %q", string(lines[1]))
	}
}

func TestSplitLines_TrailingNewline(t *testing.T) {
	lines := splitLines([]byte("a\nb\n"))
	require.Len(t, lines, 3, "expected 3 lines, got %d", len(lines))
	if string(lines[0]) != "a" {
		t.Errorf("line 0: got %q", string(lines[0]))
	}
	if string(lines[1]) != "b" {
		t.Errorf("line 1: got %q", string(lines[1]))
	}
	if string(lines[2]) != "" {
		t.Errorf("line 2: expected empty, got %q", string(lines[2]))
	}
}

func TestRenderMinimal(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "docs/api.md"}},
		{fields: map[string]any{"filename": "docs/guide.md"}},
	}
	got := renderMinimal(entries)
	expected := "- [api.md](docs/api.md)\n- [guide.md](docs/guide.md)\n"
	assert.Equal(t, expected, got, "renderMinimal mismatch.\nExpected:\n%s\nGot:\n%s", expected, got)
}

func TestRenderEmpty_WithValue(t *testing.T) {
	got := renderEmpty(map[string]string{"empty": "No files found."})
	if got != "No files found.\n" {
		t.Errorf("expected 'No files found.\\n', got %q", got)
	}
}

func TestRenderEmpty_NoKey(t *testing.T) {
	got := renderEmpty(map[string]string{})
	assert.Equal(t, "", got, "expected empty string, got %q", got)
}

func TestRenderEmpty_EmptyValue(t *testing.T) {
	got := renderEmpty(map[string]string{"empty": ""})
	assert.Equal(t, "", got, "expected empty string, got %q", got)
}

func TestRenderTemplate_HeaderRowFooter(t *testing.T) {
	params := map[string]string{
		"header": "| Title |\n|-------|",
		"row":    "| {title} |",
		"footer": "---",
	}
	entries := []fileEntry{
		{fields: map[string]any{"title": "A", "filename": "a.md"}},
		{fields: map[string]any{"title": "B", "filename": "b.md"}},
	}
	got, err := renderTemplate(params, entries)
	require.NoError(t, err)
	expected := "| Title |\n|-------|\n| A |\n| B |\n---\n"
	assert.Equal(t, expected, got, "renderTemplate mismatch.\nExpected:\n%s\nGot:\n%s", expected, got)
}

func TestRenderTemplate_RowOnly(t *testing.T) {
	params := map[string]string{
		"row": "- {filename}",
	}
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md"}},
	}
	got, err := renderTemplate(params, entries)
	require.NoError(t, err)
	expected := "- a.md\n"
	assert.Equal(t, expected, got, "renderTemplate mismatch.\nExpected:\n%s\nGot:\n%s", expected, got)
}

func TestRenderTemplate_FooterOnly(t *testing.T) {
	params := map[string]string{
		"row":    "- {filename}",
		"footer": "---",
	}
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md"}},
	}
	got, err := renderTemplate(params, entries)
	require.NoError(t, err)
	expected := "- a.md\n---\n"
	assert.Equal(t, expected, got, "renderTemplate mismatch.\nExpected:\n%s\nGot:\n%s", expected, got)
}

func TestParseRowTemplate_UnclosedBraceReturnsError(t *testing.T) {
	err := parseRowTemplate("{title")
	require.Error(t, err, "expected error for unclosed placeholder")
}

func TestParseRowTemplate_EmptyPlaceholderReturnsError(t *testing.T) {
	err := parseRowTemplate("{}")
	require.Error(t, err, "expected error for empty placeholder")
}

func TestSortEntries_PathAscending(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "c.md"}},
		{fields: map[string]any{"filename": "a.md"}},
		{fields: map[string]any{"filename": "b.md"}},
	}
	sortEntries(entries, "path", false)
	if entries[0].fields["filename"] != "a.md" {
		t.Errorf("expected first entry a.md, got %s", entries[0].fields["filename"])
	}
	if entries[2].fields["filename"] != "c.md" {
		t.Errorf("expected last entry c.md, got %s", entries[2].fields["filename"])
	}
}

func TestSortEntries_PathDescending(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md"}},
		{fields: map[string]any{"filename": "c.md"}},
		{fields: map[string]any{"filename": "b.md"}},
	}
	sortEntries(entries, "path", true)
	if entries[0].fields["filename"] != "c.md" {
		t.Errorf("expected first entry c.md, got %s", entries[0].fields["filename"])
	}
	if entries[2].fields["filename"] != "a.md" {
		t.Errorf("expected last entry a.md, got %s", entries[2].fields["filename"])
	}
}

func TestSortEntries_FrontMatterKey(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md", "title": "Zulu"}},
		{fields: map[string]any{"filename": "b.md", "title": "Alpha"}},
	}
	sortEntries(entries, "title", false)
	if entries[0].fields["title"] != "Alpha" {
		t.Errorf("expected Alpha first, got %s", entries[0].fields["title"])
	}
}

func TestSortEntries_Tiebreaker(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "b.md", "title": "Same"}},
		{fields: map[string]any{"filename": "a.md", "title": "Same"}},
	}
	sortEntries(entries, "title", false)
	if entries[0].fields["filename"] != "a.md" {
		t.Errorf("expected a.md first (tiebreaker), got %s", entries[0].fields["filename"])
	}
}

func TestSortEntries_TiebreakerDescending(t *testing.T) {
	// Even when descending, the tiebreaker is path ascending.
	entries := []fileEntry{
		{fields: map[string]any{"filename": "b.md", "title": "Same"}},
		{fields: map[string]any{"filename": "a.md", "title": "Same"}},
	}
	sortEntries(entries, "title", true)
	if entries[0].fields["filename"] != "a.md" {
		t.Errorf("expected a.md first (tiebreaker ascending), got %s", entries[0].fields["filename"])
	}
}

func TestSortEntries_FilenameDescending(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a/alpha.md"}},
		{fields: map[string]any{"filename": "z/zulu.md"}},
	}
	sortEntries(entries, "filename", true)
	if entries[0].fields["filename"] != "z/zulu.md" {
		t.Errorf("expected z/zulu.md first (filename descending), got %s", entries[0].fields["filename"])
	}
}

func TestSortValue_Path(t *testing.T) {
	e := fileEntry{fields: map[string]any{"filename": "docs/a.md"}}
	if v := sortValue(e, "path"); v != "docs/a.md" {
		t.Errorf("expected docs/a.md, got %s", v)
	}
}

func TestSortValue_Filename(t *testing.T) {
	e := fileEntry{fields: map[string]any{"filename": "docs/a.md"}}
	if v := sortValue(e, "filename"); v != "a.md" {
		t.Errorf("expected a.md, got %s", v)
	}
}

func TestSortValue_FrontMatterField(t *testing.T) {
	e := fileEntry{fields: map[string]any{"filename": "a.md", "title": "Hello"}}
	if v := sortValue(e, "title"); v != "Hello" {
		t.Errorf("expected Hello, got %s", v)
	}
}

func TestSortValue_MissingField(t *testing.T) {
	e := fileEntry{fields: map[string]any{"filename": "a.md"}}
	if v := sortValue(e, "title"); v != "" {
		t.Errorf("expected empty string for missing field, got %q", v)
	}
}

// =====================================================================
// readFrontMatter
// =====================================================================

func TestReadFrontMatter_Valid(t *testing.T) {
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\ndescription: World\n---\n# Content\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	if fm["title"] != "Hello" {
		t.Errorf("expected title Hello, got %q", fm["title"])
	}
	if fm["description"] != "World" {
		t.Errorf("expected description World, got %q", fm["description"])
	}
}

func TestReadFrontMatter_NoFrontMatter(t *testing.T) {
	fs := fstest.MapFS{
		"a.md": {Data: []byte("# No front matter\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	assert.Nil(t, fm, "expected nil for no front matter, got %v", fm)
}

func TestReadFrontMatter_InvalidYAML(t *testing.T) {
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ninvalid: [yaml\n---\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	assert.Nil(t, fm, "expected nil for invalid YAML, got %v", fm)
}

func TestReadFrontMatter_NonStringValue(t *testing.T) {
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\ncount: 42\n---\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	if fm["title"] != "Hello" {
		t.Errorf("expected title Hello, got %q", fm["title"])
	}
	if fm["count"] != 42 {
		t.Errorf("expected count 42, got %v", fm["count"])
	}
}

func TestReadFrontMatter_UnreadableFile(t *testing.T) {
	fs := fstest.MapFS{}
	fm, err := readFrontMatter(fs, "missing.md", 0)
	assert.Nil(t, fm, "expected nil for missing file, got %v", fm)
	assert.Error(t, err, "expected error for missing file")
}

func TestReadFrontMatter_SizeLimitExceeded(t *testing.T) {
	fs := fstest.MapFS{
		"big.md": {Data: []byte("---\ntitle: Big\n---\n" + strings.Repeat("x", 200))},
	}
	fm, err := readFrontMatter(fs, "big.md", 10)
	assert.Nil(t, fm, "expected nil for oversized file")
	assert.Error(t, err, "expected error for oversized file")
	assert.Contains(t, err.Error(), "file too large")
}

func TestReadFrontMatter_EmptyFile(t *testing.T) {
	fs := fstest.MapFS{
		"empty.md": {Data: []byte("")},
	}
	fm, err := readFrontMatter(fs, "empty.md", 0)
	assert.Nil(t, fm, "expected nil for empty file, got %v", fm)
	assert.NoError(t, err, "empty file should not cause error")
}

func TestReadFrontMatter_OnlyOpeningDelimiter(t *testing.T) {
	// File starts with --- but has no closing ---.
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	assert.Nil(t, fm, "expected nil for unclosed front matter, got %v", fm)
}

func TestReadFrontMatter_BooleanValue(t *testing.T) {
	// Boolean YAML values should be converted via fmt.Sprintf.
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\ndraft: true\n---\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	if fm["draft"] != true {
		t.Errorf("expected draft true, got %v", fm["draft"])
	}
}

func TestReadFrontMatter_ListValue(t *testing.T) {
	// List values in front matter should be converted via fmt.Sprintf.
	fs := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\ntags: [go, lint]\n---\n")},
	}
	fm, _ := readFrontMatter(fs, "a.md", 0)
	if fm["title"] != "Hello" {
		t.Errorf("expected title Hello, got %q", fm["title"])
	}
	// List value is formatted as a Go slice string.
	if fm["tags"] == "" {
		t.Error("expected non-empty tags value")
	}
}

// =====================================================================
// extractContent and replaceContent
// =====================================================================

func TestExtractContent_Normal(t *testing.T) {
	src := `line1
line2
line3
line4
line5
`
	f := newTestFile(t, "test.md", src)
	mp := markerPair{
		StartLine:   1,
		EndLine:     5,
		ContentFrom: 2,
		ContentTo:   4,
	}
	content := extractContent(f, mp)
	assert.Equal(t, "line2\nline3\nline4\n", content, "expected 'line2\\nline3\\nline4\\n', got %q", content)
}

func TestExtractContent_Empty(t *testing.T) {
	src := `start
end
`
	f := newTestFile(t, "test.md", src)
	mp := markerPair{
		StartLine:   1,
		EndLine:     2,
		ContentFrom: 2,
		ContentTo:   1,
	}
	content := extractContent(f, mp)
	assert.Equal(t, "", content, "expected empty content, got %q", content)
}

func TestExtractContent_SingleLine(t *testing.T) {
	src := `start
middle
end
`
	f := newTestFile(t, "test.md", src)
	mp := markerPair{
		StartLine:   1,
		EndLine:     3,
		ContentFrom: 2,
		ContentTo:   2,
	}
	content := extractContent(f, mp)
	assert.Equal(t, "middle\n", content, "expected 'middle\\n', got %q", content)
}

func TestReplaceContent_Normal(t *testing.T) {
	src := "start\nold1\nold2\nend\ntrailing\n"
	f := newTestFile(t, "test.md", src)
	mp := markerPair{
		StartLine:   1,
		EndLine:     4,
		ContentFrom: 2,
		ContentTo:   3,
	}
	result := replaceContent(f, mp, "new1\nnew2\n")
	expected := "start\nnew1\nnew2\nend\ntrailing\n"
	if string(result) != expected {
		t.Errorf("replaceContent mismatch.\nExpected:\n%s\nGot:\n%s", expected, string(result))
	}
}

func TestReplaceContent_EmptyContent(t *testing.T) {
	src := "start\nold\nend\n"
	f := newTestFile(t, "test.md", src)
	mp := markerPair{
		StartLine:   1,
		EndLine:     3,
		ContentFrom: 2,
		ContentTo:   2,
	}
	result := replaceContent(f, mp, "")
	expected := "start\nend\n"
	if string(result) != expected {
		t.Errorf("replaceContent with empty content mismatch.\nExpected:\n%s\nGot:\n%s", expected, string(result))
	}
}

// =====================================================================
// Integration scenarios
// =====================================================================

func TestIntegration_FullTableWithSortAndEmpty(t *testing.T) {
	src := `# Project Index

<?catalog
glob: "rules/*/README.md"
sort: title
header: |
  | Rule | Description |
  |------|-------------|
row: "| [{title}]({filename}) | {description} |"
empty: No rules defined yet.
?>
| Rule                                   | Description        |
|----------------------------------------|--------------------|
| [First Heading](rules/tm001/README.md) | Checks headings    |
| [Line Length](rules/tm002/README.md)   | Checks line length |
<?/catalog?>

Some trailing text.
`
	mapFS := fstest.MapFS{
		"rules/tm002/README.md": {Data: []byte(
			"---\ntitle: Line Length\ndescription: Checks line length\n---\n# Rule\n")},
		"rules/tm001/README.md": {Data: []byte(
			"---\ntitle: First Heading\ndescription: Checks headings\n---\n# Rule\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Task 8: High-priority missing spec tests
// =====================================================================

func TestSpec_BraceExpansionSupported(t *testing.T) {
	// The doublestar library supports brace expansion `{a,b}`.
	// (The spec originally said "not supported" but the implementation
	// delegates to doublestar which handles braces natively.)
	src := `<?catalog
glob: "*.{md,txt}"
?>
- [a.md](a.md)
- [b.txt](b.txt)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md":  {Data: []byte("# A\n")},
		"b.txt": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_WindowsCRLFLineEndingsFlaggedAsStale(t *testing.T) {
	// Windows \r\n line endings in existing content are flagged as stale
	// since generated content uses \n.
	src := "<?catalog\nglob: \"*.md\"\n?>\n- [a.md](a.md)\r\n<?/catalog?>\n"
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "generated section is out of date")
}

func TestSpec_GlobMatchingLintedFileIncluded(t *testing.T) {
	// Glob matching the linted file itself includes it in output.
	src := `<?catalog
glob: "*.md"
?>
- [index.md](index.md)
- [other.md](other.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"index.md": {Data: []byte(src)},
		"other.md": {Data: []byte("# Other\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_BinaryNonMarkdownMatchedFiles(t *testing.T) {
	// Binary/non-Markdown matched files: {filename} resolves, no front matter extracted.
	src := `<?catalog
glob: "*"
row: "- [{title}]({filename})"
?>
- [](data.bin)
- [Hello](readme.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"data.bin":  {Data: []byte{0x00, 0x01, 0x02, 0xFF}},
		"readme.md": {Data: []byte("---\ntitle: Hello\n---\n# Hi\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_YAMLAnchorsAliasesSupported(t *testing.T) {
	// YAML anchors, aliases, and merge keys are supported.
	src := `<?catalog
glob: "docs/*.md"
row: "- {filename}"
?>
- docs/a.md
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_DescendingSort(t *testing.T) {
	// `sort: -priority` means descending by key `priority`.
	src := `<?catalog
glob: "*.md"
sort: -priority
row: "- [{title}]({filename})"
?>
- [High](b.md)
- [Low](a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Low\npriority: \"1\"\n---\n")},
		"b.md": {Data: []byte("---\ntitle: High\npriority: \"2\"\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_UnreadableMatchedFilesSilentlySkipped(t *testing.T) {
	// Unreadable matched files are silently skipped (end-to-end via Check).
	// We simulate this by having an FS that lists a file but fails to read it.
	// fstest.MapFS won't do this naturally, but we can test via a file
	// that is a directory entry in the FS that Stats ok but can't be read.
	// Instead, test that the rendering logic correctly excludes files that
	// can't have front matter read (the readFrontMatter returns nil).
	src := `<?catalog
glob: "*.md"
row: "- [{title}]({filename})"
?>
- [Hello](good.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"good.md": {Data: []byte("---\ntitle: Hello\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Task 9: Medium-priority missing spec tests
// =====================================================================

func TestSpec_TemplateOutputNotHTMLEscaped(t *testing.T) {
	// Template output is not HTML-escaped: <, >, & appear literally.
	src := `<?catalog
glob: "*.md"
row: "- {title}"
?>
- <b>Bold & "quoted"</b>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: '<b>Bold & \"quoted\"</b>'\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// assertDiagOnLine checks that at least one diagnostic matches the message
// substring and is on the expected line.
func assertDiagOnLine(t *testing.T, diags []lint.Diagnostic, wantMsg string, wantLine int) {
	t.Helper()
	if len(diags) == 0 {
		t.Fatal("expected at least one diagnostic")
	}
	for _, d := range diags {
		if strings.Contains(d.Message, wantMsg) {
			if d.Line != wantLine {
				t.Errorf("expected diagnostic on line %d, got line %d (message: %s)", wantLine, d.Line, d.Message)
			}
			return
		}
	}
	t.Errorf("expected diagnostic with message containing %q", wantMsg)
}

func diagLineNumberCases() []struct {
	name     string
	src      string
	wantLine int
	wantMsg  string
} {
	return []struct {
		name     string
		src      string
		wantLine int
		wantMsg  string
	}{
		{
			"stale section on start marker line",
			"prefix\n<?catalog\nglob: \"*.md\"\n?>\n" +
				"old\n<?/catalog?>\n",
			2, "out of date",
		},
		{
			"unclosed on start marker line",
			"prefix\n<?catalog\nglob: \"*.md\"\n?>\n" +
				"content\n",
			2, "no closing marker",
		},
		{
			"orphaned on end marker line",
			"prefix\ntext\n<?/catalog?>\n",
			3, "unexpected generated section end marker",
		},
		{
			"missing glob on start marker line",
			"prefix\n<?catalog\nsort: path\n?>\n" +
				"<?/catalog?>\n",
			2, `missing required "glob" parameter`,
		},
		{
			"invalid YAML on start marker line",
			"prefix\n<?catalog\n: [invalid\n?>\n" +
				"<?/catalog?>\n",
			2, "invalid YAML",
		},
		{
			"nested unclosed on outer start line",
			"<?catalog\nglob: \"*.md\"\n?>\n" +
				"prefix\n<?catalog\nglob: \"*.md\"\n?>\n" +
				"<?/catalog?>\n",
			1, "no closing marker",
		},
	}
}

func TestSpec_DiagnosticLineNumbers(t *testing.T) {
	twoFiles := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
		"b.md": {Data: []byte("# B\n")},
	}
	for _, tc := range diagLineNumberCases() {
		t.Run(tc.name, func(t *testing.T) {
			f := newTestFile(t, "index.md", tc.src, twoFiles)
			r := &Rule{}
			diags := r.Check(f)
			assertDiagOnLine(t, diags, tc.wantMsg, tc.wantLine)
		})
	}
}

func TestSpec_MissingFrontMatterValuesSortAsEmptyString(t *testing.T) {
	// Missing front matter values sort as empty string (end-to-end).
	// Empty string sorts before any non-empty string, so files without
	// the sort field come first in ascending order.
	src := `<?catalog
glob: "*.md"
sort: priority
row: "- [{title}]({filename})"
?>
- [No Priority](a.md)
- [High](b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: No Priority\n---\n")},
		"b.md": {Data: []byte("---\ntitle: High\npriority: zzz\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_NonStringFrontMatterRenderedThroughTemplate(t *testing.T) {
	// Non-string front matter values are converted via fmt.Sprintf and rendered.
	src := `<?catalog
glob: "*.md"
row: "- {title} (count: {count})"
?>
- Hello (count: 42)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("---\ntitle: Hello\ncount: 42\n---\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_EmptyPlusFooterWithoutRowProducesDiag(t *testing.T) {
	// `empty` + `footer` without `row` produces missing-row diagnostic.
	src := `<?catalog
glob: "*.md"
empty: No docs.
footer: "---"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `generated section template missing required "row" key`)
}

func TestIntegration_EmptyFallbackWithFullTemplate(t *testing.T) {
	src := `<?catalog
glob: "nonexistent/*.md"
header: |
  | Title |
  |-------|
row: "| {title} |"
footer: "---"
empty: No documents.
?>
No documents.
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// --- Multi-glob list tests ---

func TestSpec_MultiGlobYAMLBlockList(t *testing.T) {
	// A YAML block-style list of glob patterns matches files from all patterns.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "plan/*.md"
?>
- [a.md](docs/a.md)
- [b.md](plan/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"plan/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_MultiGlobInlineList(t *testing.T) {
	// An inline YAML list of glob patterns matches files from all patterns.
	src := `<?catalog
glob: ["docs/*.md", "plan/*.md"]
?>
- [a.md](docs/a.md)
- [b.md](plan/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"plan/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_MultiGlobDeduplication(t *testing.T) {
	// When multiple patterns match the same file, it appears only once.
	src := `<?catalog
glob:
  - "*.md"
  - "a.md"
?>
- [a.md](a.md)
- [b.md](b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
		"b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_MultiGlobSortAcrossPatterns(t *testing.T) {
	// Files from multiple patterns are sorted together by the sort key.
	src := `<?catalog
glob:
  - "plan/*.md"
  - "docs/*.md"
sort: path
?>
- [a.md](docs/a.md)
- [b.md](plan/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"plan/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_MultiGlobEmptyElement(t *testing.T) {
	// A list containing an empty string element produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - ""
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `empty "glob" parameter`)
}

func TestSpec_MultiGlobAbsolutePath(t *testing.T) {
	// A list containing an absolute path produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "/etc/passwd"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "absolute glob path")
}

func TestSpec_MultiGlobDotDot(t *testing.T) {
	// A list containing ".." path traversal produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "../secret/*.md"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `".." path traversal`)
}

func TestSpec_MultiGlobInvalidPattern(t *testing.T) {
	// A list containing an invalid glob pattern produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "[invalid"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "invalid glob pattern")
}

func TestSpec_MultiGlobNonStringElement(t *testing.T) {
	// A list containing a non-string element (a number) produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - 42
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "non-string")
}

func TestSpec_SingleGlobStringStillWorks(t *testing.T) {
	// Existing single-string glob continues to work (backward compatibility).
	src := `<?catalog
glob: "docs/*.md"
?>
- [a.md](docs/a.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Catalog include-cycle detection
// =====================================================================

func TestCheck_CatalogIncludeCycle(t *testing.T) {
	// A catalog in index.md globs for docs/*.md.
	// docs/guide.md includes index.md via <?include?>, creating a cycle.
	guide := "# Guide\n\n<?include\nfile: ../index.md\n?>\nold\n<?/include?>\n"
	src := "# Index\n\n<?catalog\nglob: \"docs/*.md\"\n?>\n- [docs/guide.md](docs/guide.md)\n<?/catalog?>\n"
	mapFS := fstest.MapFS{
		"index.md":      {Data: []byte(src)},
		"docs/guide.md": {Data: []byte(guide)},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiagMsg(t, diags, "creating a cycle")
}

func TestCheck_CatalogNoCycleWhenNoInclude(t *testing.T) {
	// Matched file does not include the catalog owner — no cycle.
	src := "# Index\n\n<?catalog\nglob: \"docs/*.md\"\n?>\n- [guide.md](docs/guide.md)\n<?/catalog?>\n"
	mapFS := fstest.MapFS{
		"index.md":      {Data: []byte(src)},
		"docs/guide.md": {Data: []byte("# Guide\n\nJust content.\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Case-mismatch "did you mean?" hints
// =====================================================================

func TestExtractPlaceholderFields(t *testing.T) {
	fields := extractPlaceholderFields("- [{Title}]({filename})")
	assert.Equal(t, []string{"Title", "filename"}, fields)
}

func TestExtractPlaceholderFields_Duplicates(t *testing.T) {
	fields := extractPlaceholderFields("{title} and {title}")
	assert.Equal(t, []string{"title"}, fields)
}

func TestExtractPlaceholderFields_NoFields(t *testing.T) {
	fields := extractPlaceholderFields("plain text")
	assert.Empty(t, fields)
}

func TestCheckFieldCaseMismatches_Exact(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md", "title": "A"}},
	}
	diags := checkFieldCaseMismatches("index.md", 5, "{title}", entries)
	assert.Empty(t, diags, "exact match should produce no diagnostic")
}

func TestCheckFieldCaseMismatches_CaseMismatch(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md", "title": "A"}},
	}
	diags := checkFieldCaseMismatches("index.md", 5, "{Title}", entries)
	require.Len(t, diags, 1)
	assert.Contains(t, diags[0].Message, `field "Title" not found`)
	assert.Contains(t, diags[0].Message, `did you mean "title"`)
}

func TestCheckFieldCaseMismatches_Deduplication(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md", "title": "A"}},
		{fields: map[string]any{"filename": "b.md", "title": "B"}},
	}
	diags := checkFieldCaseMismatches("index.md", 5, "{Title}", entries)
	require.Len(t, diags, 1, "should deduplicate across entries")
}

func TestCheckFieldCaseMismatches_InconsistentCasing(t *testing.T) {
	// Some files have "Title", others "title" — template uses {Title}.
	// The exact match exists in some entries, but different casing in others
	// should surface an inconsistency warning.
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md", "Title": "A"}},
		{fields: map[string]any{"filename": "b.md", "title": "B"}},
	}
	diags := checkFieldCaseMismatches("index.md", 5, "{Title}", entries)
	require.Len(t, diags, 1)
	assert.Contains(t, diags[0].Message, "inconsistent casing")
	assert.Contains(t, diags[0].Message, `"Title"`)
	assert.Contains(t, diags[0].Message, `"title"`)
}

func TestCheckFieldCaseMismatches_BuiltinFilename(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{"filename": "a.md"}},
	}
	diags := checkFieldCaseMismatches("index.md", 5, "{filename}", entries)
	assert.Empty(t, diags, "filename is built-in and always present")
}

// =====================================================================
// Negated glob patterns (!-prefix exclusion)
// =====================================================================

func TestSpec_ExcludeSinglePattern(t *testing.T) {
	// A !-prefixed glob pattern excludes matching files.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "!docs/internal.md"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":      {Data: []byte("# API\n")},
		"docs/internal.md": {Data: []byte("# Internal\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeMultiplePatterns(t *testing.T) {
	// Multiple !-prefixed patterns exclude files from several directories.
	src := `<?catalog
glob:
  - "**/*.md"
  - "!docs/internal.md"
  - "!draft/*.md"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":      {Data: []byte("# API\n")},
		"docs/internal.md": {Data: []byte("# Internal\n")},
		"draft/wip.md":     {Data: []byte("# WIP\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeWithGlobWildcard(t *testing.T) {
	// Exclusion patterns support glob wildcards.
	src := `<?catalog
glob:
  - "**/*.md"
  - "!draft/**"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":  {Data: []byte("# API\n")},
		"draft/wip.md": {Data: []byte("# WIP\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeAbsolutePath(t *testing.T) {
	// Absolute paths in !-prefixed patterns produce a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "!/etc/passwd"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "absolute glob path")
}

func TestSpec_ExcludeDotDot(t *testing.T) {
	// ".." path traversal in !-prefixed patterns produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "!../secret/*.md"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `".." path traversal`)
}

func TestSpec_ExcludeInvalidPattern(t *testing.T) {
	// Invalid glob pattern in !-prefixed patterns produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "![invalid"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, "invalid glob pattern")
}

func TestSpec_ExcludeEmptyAfterBang(t *testing.T) {
	// A "!" with nothing after it produces a diagnostic.
	src := `<?catalog
glob:
  - "*.md"
  - "!"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `empty "glob" parameter`)
}

func TestSpec_ExcludeOnlyNoBareGlob(t *testing.T) {
	// A glob list with only !-prefixed patterns (no include) produces a diagnostic.
	src := `<?catalog
glob:
  - "!draft/*.md"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `must include at least one non-negated pattern`)
}

func TestSpec_ExcludeNoMatchStillWorks(t *testing.T) {
	// Exclusion pattern that matches nothing doesn't cause errors.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "!nonexistent/*.md"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md": {Data: []byte("# API\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeIncludeExcludeOrdering(t *testing.T) {
	// Pattern: include, exclude, include — the second include does NOT
	// re-add the file because includes and excludes are collected into
	// separate lists; a file matching any exclude pattern is excluded
	// regardless of ordering.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "!docs/a.md"
  - "docs/a.md"
?>
- [b.md](docs/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"docs/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeBeforeInclude(t *testing.T) {
	// Pattern: exclude, include — the exclude still filters the include
	// because pattern order does not affect semantics.
	src := `<?catalog
glob:
  - "!docs/a.md"
  - "docs/*.md"
?>
- [b.md](docs/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"docs/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_IncludeThenExclude(t *testing.T) {
	// Pattern: include, exclude — the standard case; file matching the
	// exclude pattern is filtered out.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "!docs/a.md"
?>
- [b.md](docs/b.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/a.md": {Data: []byte("# A\n")},
		"docs/b.md": {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_ExcludeWithRowTemplate(t *testing.T) {
	// Exclusion works with row templates and front matter.
	src := `<?catalog
glob:
  - "docs/*.md"
  - "!docs/draft.md"
row: "- [{title}]({filename})"
?>
- [API Reference](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md":   {Data: []byte("---\ntitle: API Reference\n---\n# API\n")},
		"docs/draft.md": {Data: []byte("---\ntitle: Draft\n---\n# Draft\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// =====================================================================
// Gitignore parameter
// =====================================================================

func TestSpec_GitignoreInvalidValue(t *testing.T) {
	// Non-boolean gitignore value produces a diagnostic.
	src := `<?catalog
glob: "*.md"
gitignore: "maybe"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 1)
	expectDiagMsg(t, diags, `invalid "gitignore" value`)
}

func TestSpec_GitignoreFalseExplicit(t *testing.T) {
	// gitignore: "false" is accepted without diagnostic.
	src := `<?catalog
glob: "docs/*.md"
gitignore: "false"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md": {Data: []byte("# API\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_GitignoreTrueExplicit(t *testing.T) {
	// gitignore: "true" is accepted without diagnostic.
	src := `<?catalog
glob: "docs/*.md"
gitignore: "true"
?>
- [api.md](docs/api.md)
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/api.md": {Data: []byte("# API\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_GitignoreFiltersMatchedFiles(t *testing.T) {
	// Behavioral test: files matched by .gitignore are excluded from catalog.
	dir := t.TempDir()

	// Create .gitignore that ignores "ignored/" directory and "*.tmp" files.
	writeFile(t, dir, ".gitignore", "ignored/\n*.tmp\n")
	writeFile(t, dir, "visible.md", "# Visible\n")
	writeFile(t, dir, "notes.tmp", "# Tmp\n")
	mkdirAll(t, dir, "ignored")
	writeFile(t, dir, "ignored/secret.md", "# Secret\n")
	mkdirAll(t, dir, "sub")
	writeFile(t, dir, "sub/ok.md", "# OK\n")

	indexPath := filepath.Join(dir, "index.md")
	src := "<?catalog\nglob: \"**/*.md\"\n?>\n- [ok.md](sub/ok.md)\n- [visible.md](visible.md)\n<?/catalog?>\n"
	f, err := lint.NewFile(indexPath, []byte(src))
	require.NoError(t, err)
	f.FS = os.DirFS(dir)
	d := dir // capture for closure
	f.GitignoreFunc = func() *lint.GitignoreMatcher { return lint.NewGitignoreMatcher(d) }

	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_GitignoreFalseIncludesIgnoredFiles(t *testing.T) {
	// gitignore: "false" disables filtering; ignored files appear in catalog.
	dir := t.TempDir()

	writeFile(t, dir, ".gitignore", "ignored/\n")
	writeFile(t, dir, "visible.md", "# Visible\n")
	mkdirAll(t, dir, "ignored")
	writeFile(t, dir, "ignored/secret.md", "# Secret\n")

	indexPath := filepath.Join(dir, "index.md")
	src := "<?catalog\nglob: \"**/*.md\"\ngitignore: \"false\"\n?>\n" +
		"- [secret.md](ignored/secret.md)\n- [visible.md](visible.md)\n<?/catalog?>\n"
	f, err := lint.NewFile(indexPath, []byte(src))
	require.NoError(t, err)
	f.FS = os.DirFS(dir)
	d := dir // capture for closure
	f.GitignoreFunc = func() *lint.GitignoreMatcher { return lint.NewGitignoreMatcher(d) }

	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

func TestSpec_GitignoreNegationReIncludes(t *testing.T) {
	// Gitignore negation patterns re-include previously ignored files.
	dir := t.TempDir()

	// Ignore files in drafts/ except important.md.
	// Per gitignore rules, "drafts/*" ignores files inside the directory
	// (not the directory itself), allowing negation to re-include a file.
	writeFile(t, dir, ".gitignore", "drafts/*\n!drafts/important.md\n")
	mkdirAll(t, dir, "drafts")
	writeFile(t, dir, "drafts/wip.md", "# WIP\n")
	writeFile(t, dir, "drafts/important.md", "# Important\n")
	writeFile(t, dir, "visible.md", "# Visible\n")

	indexPath := filepath.Join(dir, "index.md")
	src := "<?catalog\nglob: \"**/*.md\"\n?>\n" +
		"- [important.md](drafts/important.md)\n- [visible.md](visible.md)\n<?/catalog?>\n"
	f, err := lint.NewFile(indexPath, []byte(src))
	require.NoError(t, err)
	f.FS = os.DirFS(dir)
	d := dir // capture for closure
	f.GitignoreFunc = func() *lint.GitignoreMatcher { return lint.NewGitignoreMatcher(d) }

	r := &Rule{}
	diags := r.Check(f)
	expectDiags(t, diags, 0)
}

// writeFile creates a file with the given content inside dir.
func writeFile(t *testing.T, dir, name, content string) {
	t.Helper()
	require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
}

// mkdirAll creates a directory inside dir.
func mkdirAll(t *testing.T, dir, sub string) {
	t.Helper()
	require.NoError(t, os.MkdirAll(filepath.Join(dir, sub), 0o755))
}

func TestSpec_DidYouMeanCaseMismatch(t *testing.T) {
	mapFS := fstest.MapFS{
		"docs/a.md": &fstest.MapFile{Data: []byte("---\ntitle: A\n---\n# A\n")},
	}
	src := "# Index\n\n<?catalog\nglob: \"docs/*.md\"\nrow: \"- [{Title}]({filename})\"\n?>\n<?/catalog?>\n"
	f := newTestFile(t, "index.md", src, mapFS)
	r := &Rule{}
	diags := r.Check(f)
	// Should have at least 1 diagnostic for the case mismatch.
	found := false
	for _, d := range diags {
		if strings.Contains(d.Message, "did you mean") {
			found = true
			break
		}
	}
	assert.True(t, found, "expected 'did you mean' diagnostic, got: %v", diags)
}

func TestReadFrontMatter_AnchorReturnsNil(t *testing.T) {
	mapFS := fstest.MapFS{
		"doc.md": {Data: []byte(
			"---\nbase: &base\n  id: 1\n---\n# Title\n")},
	}
	result, _ := readFrontMatter(mapFS, "doc.md", 0)
	assert.Nil(t, result)
}

// =====================================================================
// Catalog injection warnings
// =====================================================================

func TestCatalogInjection_NewlineInFrontMatter(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{
			"filename": "a.md",
			"summary":  "line1\nline2",
		}},
	}
	diags := checkCatalogInjection("index.md", 5, entries)
	require.Len(t, diags, 1)
	assert.Contains(t, diags[0].Message, "embedded newlines")
	assert.Equal(t, lint.Warning, diags[0].Severity)
}

func TestCatalogInjection_LinkSequenceInFrontMatter(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{
			"filename": "a.md",
			"summary":  "click](http://evil.com)",
		}},
	}
	diags := checkCatalogInjection("index.md", 5, entries)
	require.Len(t, diags, 1)
	assert.Contains(t, diags[0].Message, "](")
}

func TestCatalogInjection_CleanValue(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{
			"filename": "a.md",
			"summary":  "A clean summary without issues",
		}},
	}
	diags := checkCatalogInjection("index.md", 5, entries)
	assert.Empty(t, diags)
}

func TestCatalogInjection_BothNewlineAndLink(t *testing.T) {
	entries := []fileEntry{
		{fields: map[string]any{
			"filename": "a.md",
			"summary":  "evil\n](http://evil.com)",
		}},
	}
	diags := checkCatalogInjection("index.md", 5, entries)
	assert.Len(t, diags, 2, "should report both newline and ]( issues")
}

// =====================================================================
// source-dir: glob resolution from included file's directory (#133)
// =====================================================================

func TestCatalog_SourceDirResolvesGlobFromSubdir(t *testing.T) {
	// When source-dir is set, globs should resolve relative to that
	// directory, not the file's own directory. This supports catalog
	// directives transplanted by include expansion.
	src := `<?catalog
glob: "*.md"
source-dir: "docs/dev"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/dev/api.md":   {Data: []byte("# API\n")},
		"docs/dev/guide.md": {Data: []byte("# Guide\n")},
		"README.md":         {Data: []byte("# Root\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// Filenames should be prefixed with the source-dir so links
	// resolve correctly from the including file.
	assert.Contains(t, result, "docs/dev/api.md")
	assert.Contains(t, result, "docs/dev/guide.md")
	assert.NotContains(t, result, "README.md")
}

func TestCatalog_SourceDirWithFrontMatter(t *testing.T) {
	// source-dir should also read front matter from the correct directory.
	src := `<?catalog
glob: "*.md"
source-dir: "sub"
row: "- [{title}]({filename})"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"sub/one.md": {Data: []byte("---\ntitle: One\n---\n# One\n")},
		"sub/two.md": {Data: []byte("---\ntitle: Two\n---\n# Two\n")},
	}
	f := newTestFile(t, "root.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	assert.Contains(t, result, "- [One](sub/one.md)")
	assert.Contains(t, result, "- [Two](sub/two.md)")
}

func TestCatalog_SourceDirExcludePatterns(t *testing.T) {
	// Exclude patterns should work relative to source-dir.
	src := `<?catalog
glob:
  - "*.md"
  - "!internal.md"
source-dir: "docs"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/public.md":   {Data: []byte("# Public\n")},
		"docs/internal.md": {Data: []byte("# Internal\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	assert.Contains(t, result, "docs/public.md")
	// The excluded file should not appear as a link in the generated content.
	assert.NotContains(t, result, "[internal.md](docs/internal.md)")
}

func TestCatalog_SourceDirRoot(t *testing.T) {
	// source-dir: "." means globs resolve from the project root.
	// This happens when a subdirectory file includes a root-level file.
	src := `<?catalog
glob: "*.md"
source-dir: "."
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"api.md":        {Data: []byte("# API\n")},
		"guide.md":      {Data: []byte("# Guide\n")},
		"docs/other.md": {Data: []byte("# Other\n")},
	}
	f := newTestFile(t, "docs/index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// From docs/index.md, root files need a ../ prefix.
	assert.Contains(t, result, "../api.md")
	assert.Contains(t, result, "../guide.md")
	assert.NotContains(t, result, "other.md")
}

func TestCatalog_SourceDirFromSubdirIncluder(t *testing.T) {
	// When the catalog-owning file is in a subdirectory and source-dir
	// points to a sibling subdirectory, the prefix should be relative.
	src := `<?catalog
glob: "*.md"
source-dir: "docs/dev"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/dev/api.md": {Data: []byte("# API\n")},
		"README.md":       {Data: []byte("# Root\n")},
	}
	f := newTestFile(t, "docs/intro.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// From docs/intro.md, docs/dev/api.md is at dev/api.md.
	assert.Contains(t, result, "dev/api.md")
	assert.NotContains(t, result, "docs/dev/api.md")
}

func TestCatalog_SourceDirRootFromRootFile(t *testing.T) {
	// source-dir: "." with file at root → relPrefix is ".", so no prefix.
	src := `<?catalog
glob: "*.md"
source-dir: "."
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"alpha.md": {Data: []byte("# A\n")},
		"beta.md":  {Data: []byte("# B\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// File is at root, source-dir is root → no prefix needed.
	assert.Contains(t, result, "[alpha.md](alpha.md)")
	assert.Contains(t, result, "[beta.md](beta.md)")
}

func TestCatalog_SourceDirSameAsFileDir(t *testing.T) {
	// source-dir matches the file's own directory → relPrefix is ".".
	src := `<?catalog
glob: "*.md"
source-dir: "docs"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"docs/one.md": {Data: []byte("# One\n")},
	}
	f := newTestFile(t, "docs/index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// No prefix needed since source-dir == file dir.
	assert.Contains(t, result, "[one.md](one.md)")
}

func TestCatalog_SourceDirNoRootFS(t *testing.T) {
	// Without RootFS, source-dir is ignored and globs use f.FS.
	src := `<?catalog
glob: "*.md"
source-dir: "sub"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"top.md": {Data: []byte("# Top\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	// Deliberately not setting f.RootFS.
	r := &Rule{}
	result := string(r.Fix(f))

	assert.Contains(t, result, "top.md")
}

func TestCatalog_SourceDirRelPrefixError(t *testing.T) {
	// filepath.Rel fails when one path is absolute and the other
	// relative. resolveGlobFS should fall back to f.FS.
	src := `<?catalog
glob: "*.md"
source-dir: "sub"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"top.md":   {Data: []byte("# Top\n")},
		"sub/a.md": {Data: []byte("# A\n")},
	}
	f := newTestFile(t, "/absolute/path/index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	// Falls back to f.FS since Rel fails.
	assert.Contains(t, result, "top.md")
}

func TestCatalog_SourceDirInvalidSubFS(t *testing.T) {
	// fs.Sub rejects paths starting with "/". When both file path
	// and source-dir are absolute, filepath.Rel succeeds but fs.Sub
	// fails. resolveGlobFS should fall back to f.FS.
	src := `<?catalog
glob: "*.md"
source-dir: "/proj/sub"
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"fallback.md": {Data: []byte("# Fallback\n")},
	}
	f := newTestFile(t, "/proj/index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	result := string(r.Fix(f))

	assert.Contains(t, result, "fallback.md")
}

func TestCatalog_SourceDirTraversalIgnored(t *testing.T) {
	// source-dir with ".." should not escape the project root for
	// gitignore resolution. resolveGlobFS rejects it via fs.Sub;
	// resolveGitignore must also reject it.
	src := `<?catalog
glob: "*.md"
source-dir: ".."
?>
<?/catalog?>
`
	mapFS := fstest.MapFS{
		"top.md": {Data: []byte("# Top\n")},
	}
	f := newTestFile(t, "index.md", src, mapFS)
	f.RootFS = mapFS
	r := &Rule{}
	// Should not panic or escape; falls back to f.FS.
	result := string(r.Fix(f))
	assert.Contains(t, result, "top.md")
}

// =====================================================================
// buildCatalogEntries error diagnostics (file-size limit)
// =====================================================================

func TestBuildCatalogEntries_SizeLimit_EmitsDiagnostic(t *testing.T) {
	bigContent := strings.Repeat("x", 100)
	fsys := fstest.MapFS{
		"big.md": &fstest.MapFile{
			Data: []byte("---\ntitle: Big\n---\n" + bigContent),
		},
	}
	f := &lint.File{
		Path:          "index.md",
		FS:            fsys,
		MaxInputBytes: 20,
	}
	params := map[string]string{
		"glob": "big.md",
		"row":  "- [{title}](big.md)",
	}

	entries, diags := buildCatalogEntries(f, params, "index.md", 1)
	assert.Empty(t, entries, "entry skipped due to read failure")
	require.Len(t, diags, 1, "expected one diagnostic")
	assert.Contains(t, diags[0].Message, "cannot read front matter")
	assert.Contains(t, diags[0].Message, "file too large")
}

func TestBuildCatalogEntries_Normal_NoDiagnostics(t *testing.T) {
	fsys := fstest.MapFS{
		"a.md": &fstest.MapFile{
			Data: []byte("---\ntitle: A\n---\n# A\n"),
		},
	}
	f := &lint.File{
		Path:          "index.md",
		FS:            fsys,
		MaxInputBytes: 1000,
	}
	params := map[string]string{
		"glob": "a.md",
		"row":  "- [{title}](a.md)",
	}

	entries, diags := buildCatalogEntries(f, params, "index.md", 1)
	assert.Len(t, entries, 1, "entry should be kept")
	assert.Empty(t, diags)
	assert.Equal(t, "A", entries[0].fields["title"])
}

// =====================================================================
// Phase 4 coverage: Rule.Category
// =====================================================================

func TestRule_Category(t *testing.T) {
	r := &Rule{}
	assert.Equal(t, "meta", r.Category())
}

// =====================================================================
// Phase 4 coverage: resolveGitignore param variations
// =====================================================================

func TestResolveGitignore_DisabledByParam(t *testing.T) {
	f := newTestFile(t, "index.md", "")
	matcher, base := resolveGitignore(f, map[string]string{"gitignore": "false"})
	assert.Nil(t, matcher)
	assert.Equal(t, "", base)
}

func TestResolveGitignore_NoMatcherAvailable(t *testing.T) {
	f := newTestFile(t, "index.md", "")
	// GitignoreFunc is nil → GetGitignore returns nil
	matcher, base := resolveGitignore(f, map[string]string{})
	assert.Nil(t, matcher)
	assert.Equal(t, "", base)
}

func TestResolveGitignore_WithMatcherAndSourceDir(t *testing.T) {
	dir := t.TempDir()
	stub := &lint.GitignoreMatcher{}
	f := &lint.File{
		Path:    filepath.Join(dir, "index.md"),
		RootDir: dir,
		GitignoreFunc: func() *lint.GitignoreMatcher {
			return stub
		},
	}
	params := map[string]string{"source-dir": "docs"}
	matcher, base := resolveGitignore(f, params)
	assert.Same(t, stub, matcher)
	assert.NotEmpty(t, base)
	assert.True(t, filepath.IsAbs(base))
}

// =====================================================================
// Phase 4 coverage: scanIncludesForTarget fallback paths
// =====================================================================

func TestScanIncludesForTarget_MaxDepthExceeded(t *testing.T) {
	// Pass depth > maxIncludeDepth to immediately return false.
	fsys := fstest.MapFS{
		"a.md": &fstest.MapFile{Data: []byte("# A\n")},
	}
	visited := map[string]bool{}
	result := scanIncludesForTarget(fsys, "a.md", "target.md", visited, maxIncludeDepth+1, 1000)
	assert.False(t, result)
}

func TestScanIncludesForTarget_FileReadError(t *testing.T) {
	// File does not exist in FS → read error → returns false.
	fsys := fstest.MapFS{}
	visited := map[string]bool{}
	result := scanIncludesForTarget(fsys, "nonexistent.md", "target.md", visited, 0, 1000)
	assert.False(t, result)
}

func TestScanIncludesForTarget_NoIncludes(t *testing.T) {
	// File exists but has no <?include?> directives → returns false.
	fsys := fstest.MapFS{
		"a.md": &fstest.MapFile{Data: []byte("# A\n\nNo includes here.\n")},
	}
	visited := map[string]bool{}
	result := scanIncludesForTarget(fsys, "a.md", "target.md", visited, 0, 1000)
	assert.False(t, result)
}

func TestScanIncludesForTarget_DirectMatch(t *testing.T) {
	// File directly includes target → returns true.
	fsys := fstest.MapFS{
		"a.md": &fstest.MapFile{
			Data: []byte("<?include\nfile: target.md\n?>\nsome content\n<?/include?>"),
		},
	}
	visited := map[string]bool{"a.md": true}
	result := scanIncludesForTarget(fsys, "a.md", "target.md", visited, 0, 1000)
	assert.True(t, result)
}

func TestScanIncludesForTarget_VisitedCycleSkipped(t *testing.T) {
	// File includes itself (visited) → should not recurse, returns false.
	fsys := fstest.MapFS{
		"a.md": &fstest.MapFile{
			Data: []byte("<?include\nfile: b.md\n?>\ncontent\n<?/include?>"),
		},
	}
	// Mark b.md as already visited to prevent recursion.
	visited := map[string]bool{"a.md": true, "b.md": true}
	result := scanIncludesForTarget(fsys, "a.md", "target.md", visited, 0, 1000)
	assert.False(t, result)
}