Merge PR #828: perf: five hot-path fixes from a high-performance-go audit

Author: merge-queue-bot

internal/rules/MDS060-occurrence/bad/nested-sections.md

@@ -0,0 +1,29 @@
+---
+settings:
+  tokens:
+    - process
+  scope: section
+  count: each
+  max: 3
+diagnostics:
+  - line: 1
+    column: 1
+    message: '"process" appears 8 time(s) in section (max 3)'
+  - line: 5
+    column: 1
+    message: '"process" appears 4 time(s) in section (max 3)'
+  - line: 9
+    column: 1
+    message: '"process" appears 4 time(s) in section (max 3)'
+---
+# A
+
+process process process process.
+
+## B
+
+process process process process.
+
+# C
+
+process process process process.

internal/rules/MDS075-over-repetition/bad/nested-sections.md

@@ -0,0 +1,27 @@
+---
+settings:
+  scope: section
+  max: 3
+  min-length: 4
+diagnostics:
+  - line: 1
+    column: 1
+    message: '"process" repeated 8 time(s) in section (max 3)'
+  - line: 5
+    column: 1
+    message: '"process" repeated 4 time(s) in section (max 3)'
+  - line: 9
+    column: 1
+    message: '"process" repeated 4 time(s) in section (max 3)'
+---
+# A
+
+process process process process.
+
+## B
+
+process process process process.
+
+# C
+
+process process process process.

internal/rules/astutil/astutil.go

@@ -374,9 +374,7 @@ func SectionBodies(headings []SectionHeading, paragraphs []SectionParagraph, sou
 	for i := range headings {
 		start := headings[i].Line
 		end := SectionEnd(headings, i, totalLines)
-		for lo < len(paragraphs) && paragraphs[lo].Line < start {
-			lo++
-		}
+		lo = AdvancePastLine(paragraphs, lo, start)
 		parts = parts[:0]
 		for j := lo; j < len(paragraphs) && paragraphs[j].Line < end; j++ {
 			parts = append(parts, paragraphs[j].ExtractText(source))
@@ -386,6 +384,35 @@ func SectionBodies(headings []SectionHeading, paragraphs []SectionParagraph, sou
 	return bodies
 }
 
+// AdvancePastLine returns the first index at or after lo whose entry's
+// Line is not less than start. paragraphs must be in ascending Line
+// order.
+//
+// Safe to thread lo across a sequence of calls with non-decreasing
+// start values over the same paragraphs slice (as a per-heading loop
+// over ascending headings does): a paragraph this call skips has a
+// Line below start, hence below every later, higher-or-equal start
+// too, so it can never be needed by a later call in such a sequence.
+//
+// This only advances past the skipped prefix — it does not also
+// advance past the paragraphs a caller goes on to collect from the
+// returned index onward, unlike SectionBody's binary search (which
+// looks up both ends of its range independently and has no cursor to
+// share). A hierarchical section model (see SectionEnd) lets a later,
+// deeper heading's window overlap an earlier, shallower one's, so
+// those paragraphs may need to be collected again by a later call, as
+// SectionBodies (which shares this helper) relies on; a caller whose
+// windows form a true non-overlapping partition (not SectionEnd's)
+// may still choose to advance its own cursor past its collected
+// range, since AdvancePastLine only handles the shared skip half of
+// that trade-off.
+func AdvancePastLine(paragraphs []SectionParagraph, lo, start int) int {
+	for lo < len(paragraphs) && paragraphs[lo].Line < start {
+		lo++
+	}
+	return lo
+}
+
 // HeadingLine returns the 1-based source line of a heading node.
 // Setext headings expose their line via Lines(); ATX headings are found
 // by walking inline descendants until the first text segment. Returns 1

internal/rules/maxsectionlength/countsection_bench_test.go

@@ -0,0 +1,28 @@
+package maxsectionlength
+
+import (
+	"testing"
+
+	"github.com/jeduden/mdsmith/internal/lint"
+)
+
+// BenchmarkCheck_ManySections pins docs/development/high-performance-go.md's
+// "Skip work you don't need" guideline: countSection used to rescan the
+// *entire* paragraphs slice from index 0 for every heading, making
+// Check's per-heading loop O(headings * paragraphs) instead of
+// O(headings + paragraphs). This benchmark's n scales both headings and
+// paragraphs together, so the quadratic term dominates unless the
+// forward-cursor fix is in place.
+func BenchmarkCheck_ManySections(b *testing.B) {
+	f, err := lint.NewFile("test.md", []byte(manySectionsDoc(600)))
+	if err != nil {
+		b.Fatal(err)
+	}
+	r := &Rule{MaxWords: 1000, MaxParagraphs: 1000}
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = r.Check(f)
+	}
+}

internal/rules/maxsectionlength/rule.go

@@ -106,13 +106,25 @@ func (r *Rule) Check(f *lint.File) []lint.Diagnostic {
 	}
 
 	var diags []lint.Diagnostic
+	// paragraphPos is a forward-only cursor into paragraphs, shared
+	// across every heading's window. Heading windows are contiguous,
+	// non-overlapping, and ascending (headings and paragraphs are both
+	// in source-line order), so a paragraph consumed — or skipped as
+	// belonging to an earlier window — by one heading can never be
+	// needed by a later one. Threading the cursor through turns the
+	// whole loop into a single O(headings + paragraphs) pass instead of
+	// re-scanning all of paragraphs from index 0 per heading. See
+	// docs/development/high-performance-go.md's "Skip work you don't
+	// need" — the same forward-cursor pattern astutil.SectionBodies
+	// already uses for MDS057/MDS058.
+	paragraphPos := 0
 	for i, h := range headings {
 		end := totalLines
 		if i+1 < len(headings) {
 			end = headings[i+1].line - 1
 		}
 		diags = append(diags, r.checkLineLimit(f, h, end)...)
-		diags = append(diags, r.checkWordAndParagraphLimits(f, h, end, paragraphs)...)
+		diags = append(diags, r.checkWordAndParagraphLimits(f, h, end, paragraphs, &paragraphPos)...)
 	}
 	return diags
 }
@@ -138,12 +150,12 @@ func (r *Rule) checkLineLimit(f *lint.File, h heading, end int) []lint.Diagnosti
 }
 
 func (r *Rule) checkWordAndParagraphLimits(
-	f *lint.File, h heading, end int, paragraphs []paragraph,
+	f *lint.File, h heading, end int, paragraphs []paragraph, paragraphPos *int,
 ) []lint.Diagnostic {
 	if r.MaxWords <= 0 && r.MinWords <= 0 && r.MaxParagraphs <= 0 {
 		return nil
 	}
-	words, paraCount := countSection(paragraphs, h.line, end)
+	words, paraCount := countSection(paragraphs, paragraphPos, h.line, end)
 	var diags []lint.Diagnostic
 	if r.MaxWords > 0 && words > r.MaxWords {
 		diags = append(diags, lint.Diagnostic{
@@ -347,16 +359,27 @@ func collectParagraphs(f *lint.File) []paragraph {
 	return out
 }
 
-// countSection sums words and paragraphs for paragraphs whose start
-// line falls within [start, end].
-func countSection(paragraphs []paragraph, start, end int) (words, count int) {
-	for _, p := range paragraphs {
-		if p.line < start || p.line > end {
-			continue
-		}
-		words += p.words
+// countSection sums the words and paragraph count of every entry in
+// paragraphs whose line falls in [start, end]. paragraphs must be in
+// ascending line order (astutil.CollectSectionParagraphs guarantees
+// this). *pos is a forward-only cursor: callers processing a sequence
+// of non-overlapping, ascending [start, end] windows over the same
+// paragraphs slice (as Check's per-heading loop does) should thread
+// the same pos through every call, since a paragraph this call skips
+// or consumes can never belong to a later, higher-numbered window —
+// letting the whole sequence of calls run in O(len(paragraphs)) total
+// instead of O(len(headings) * len(paragraphs)).
+func countSection(paragraphs []paragraph, pos *int, start, end int) (words, count int) {
+	for *pos < len(paragraphs) && paragraphs[*pos].line < start {
+		*pos++
+	}
+	i := *pos
+	for i < len(paragraphs) && paragraphs[i].line <= end {
+		words += paragraphs[i].words
 		count++
+		i++
 	}
+	*pos = i
 	return words, count
 }
 

internal/rules/maxsectionlength/rule_test.go

@@ -20,6 +20,28 @@ func mustFile(t *testing.T, src string) *lint.File {
 	return f
 }
 
+// TestCountSection_SkipsPrecedingParagraphs exercises countSection's
+// pos-advance loop directly: a paragraph strictly before the window's
+// start must be skipped (not counted), and the cursor must carry
+// forward correctly into a second call for a later, higher window —
+// the shape Check's per-heading loop drives it with.
+func TestCountSection_SkipsPrecedingParagraphs(t *testing.T) {
+	paragraphs := []paragraph{
+		{line: 2, words: 3}, // preceding paragraph, must be skipped for [5, 10]
+		{line: 6, words: 4},
+		{line: 12, words: 5},
+	}
+	var pos int
+
+	words, count := countSection(paragraphs, &pos, 5, 10)
+	assert.Equal(t, 4, words, "only the line-6 paragraph falls in [5, 10]")
+	assert.Equal(t, 1, count)
+
+	words, count = countSection(paragraphs, &pos, 11, 20)
+	assert.Equal(t, 5, words, "cursor must still reach the line-12 paragraph")
+	assert.Equal(t, 1, count)
+}
+
 func TestCheck_NoHeadings_NoDiagnostic(t *testing.T) {
 	f := mustFile(t, "just some text\nand more\n")
 	r := &Rule{Max: 5}

internal/rules/noundefinedreferencelabels/nextbracket_bench_test.go

@@ -0,0 +1,37 @@
+package noundefinedreferencelabels
+
+import (
+	"strings"
+	"testing"
+)
+
+// proseWithoutBrackets builds n lines of ordinary prose containing no
+// '[' at all — the worst case for nextBracket's forward scan, since
+// every byte in the file must be inspected before the scanner can
+// report EOF.
+func proseWithoutBrackets(lines int) []byte {
+	var b strings.Builder
+	for i := 0; i < lines; i++ {
+		b.WriteString("The quick brown fox jumps over the lazy dog again and again.\n")
+	}
+	return []byte(b.String())
+}
+
+// BenchmarkNextBracket_NoBrackets pins the doc's "bytes.IndexByte over
+// a hand-rolled byte loop" guideline
+// (docs/development/high-performance-go.md#strings-and-bytes):
+// collectBrackets calls nextBracket to scan the *entire* file source
+// once, byte by byte, looking for '['. On a file with no reference-style
+// links at all (the common case — most files don't use them) the loop
+// must inspect every byte before reporting EOF, so this is exactly the
+// "big Source scan" case the guideline calls out as worth vectorizing.
+func BenchmarkNextBracket_NoBrackets(b *testing.B) {
+	source := proseWithoutBrackets(200)
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_, _, _, _, ok := nextBracket(source, 0)
+		if ok {
+			b.Fatal("expected no bracket to be found")
+		}
+	}
+}

internal/rules/noundefinedreferencelabels/rule.go

@@ -245,11 +245,12 @@ func advanceBracket(brs []bracket, i, pos int) int {
 // task 7. Empty contents (`[]`) return contentStart == contentEnd;
 // the caller decides whether that is valid for the pattern.
 func nextBracket(source []byte, pos int) (open, contentStart, contentEnd, closeAfter int, ok bool) {
-	for pos < len(source) {
-		if source[pos] != '[' {
-			pos++
-			continue
+	for {
+		idx := bytes.IndexByte(source[pos:], '[')
+		if idx < 0 {
+			return 0, 0, 0, 0, false
 		}
+		pos += idx
 		open = pos
 		contentStart = pos + 1
 		i := contentStart
@@ -263,7 +264,6 @@ func nextBracket(source []byte, pos int) (open, contentStart, contentEnd, closeA
 		// advance past the orphan `[` and keep scanning.
 		pos++
 	}
-	return 0, 0, 0, 0, false
 }
 
 // scanFullRefs walks source for `[text][label]` patterns. The byte

internal/rules/occurrence/checksections_bench_test.go

@@ -0,0 +1,39 @@
+package occurrence
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/jeduden/mdsmith/internal/lint"
+)
+
+// manySectionsDoc builds a document with n level-2 headings, each
+// followed by one short paragraph — the shape that drives
+// checkSections's per-heading loop and, through it, the paragraph
+// range scans.
+func manySectionsDoc(n int) string {
+	var b strings.Builder
+	for i := 0; i < n; i++ {
+		b.WriteString("## Section\n\nA short paragraph with a foo token in it.\n\n")
+	}
+	return b.String()
+}
+
+// BenchmarkCheck_ManySections pins docs/development/high-performance-go.md's
+// "Skip work you don't need" guideline: checkSections's range helpers used
+// to rescan the *entire* paragraphs slice from index 0 for every heading,
+// making the section-scope Check O(headings * paragraphs) instead of
+// O(headings + paragraphs).
+func BenchmarkCheck_ManySections(b *testing.B) {
+	f, err := lint.NewFile("test.md", []byte(manySectionsDoc(600)))
+	if err != nil {
+		b.Fatal(err)
+	}
+	r := &Rule{Scope: "section", Count: "each", Tokens: []string{"foo"}, CaseSensitive: true}
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = r.Check(f)
+	}
+}