Expose NearestBlockAncestor, add byte-identical pin test, fill pyramid

Addresses the two remaining self-review concerns and aligns the
package's tests with the test-pyramid rule that every production
function ships its dedicated unit test by name.

Concern #2 — drop the nearestBlockAncestor duplicate:

- Expose NearestBlockAncestor from pkg/markdown/flavor so external
  rewriters (and the rule adapter) share the helper instead of
  duplicating it. Replace the rule's private copy in fix.go with
  flavor.NearestBlockAncestor.
- Add it to the contract test, the markdown-library stable surface
  list, and a dedicated TestNearestBlockAncestorPublic test.

Concern #3 — byte-identical pin test:

- pkg/markdown/flavor/detect_pin_test.go adds a corpus-driven table
  test (pinCorpus) that maps each input to the exact Finding stream
  (feature + 1-based line + 1-based column, in document order).
  Plan 185 acceptance criterion "Table tests pin this" is now an
  explicit gate; any subtle reorder, drop, or shift in MDS034
  diagnostics will break the test with a side-by-side diff.

Test-pyramid alignment:

- TestNearestBlockAncestor (subtests for the skip-non-block and
  orphan branches) plus TestNearestBlockAncestorPublic for the
  exported wrapper.
- TestIsGitHubAlertPublic exercises both branches of IsGitHubAlert
  (alert blockquote / heading-first-child).
- TestLineColPublic pins the documented 1-based semantics of the
  exported LineCol wrapper.
- TestDualFindings covers the dualFindings helper I extracted from
  Detect in the previous commit, asserting both the keep-filter and
  the still-emits-other-features path.

Coverage in pkg/markdown/flavor stays at 100%; mdsmith check and
golangci-lint are clean.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

Author: claude

docs/development/markdown-library.md

@@ -233,7 +233,8 @@ The stable surface:
   `HeadingIDExtra` shapes, `Detect`, the four
   `NewParser*` / `NewPooledParser*`
   constructors, and the small rewriter helpers
-  (`FindHeadingID`, `IsGitHubAlert`, `LineCol`).
+  (`FindHeadingID`, `IsGitHubAlert`, `LineCol`,
+  `NearestBlockAncestor`).
 - Sub-package `pkg/markdown/flavor/ext`: the
   five custom extension Extender singletons
   (`Superscript`, `Subscript`, `MathBlock`,

internal/rules/markdownflavor/fix.go

@@ -147,7 +147,7 @@ func delimiterPairEdits(n ast.Node, markerLen int) []edit {
 // The dual parser places every TaskCheckBox at the start of a
 // TextBlock so block.Lines().At(0).Start always points at '['.
 func taskCheckBoxEdits(f *lint.File, n *extast.TaskCheckBox) []edit {
-	block := nearestBlockAncestor(n)
+	block := flavor.NearestBlockAncestor(n)
 	start := block.Lines().At(0).Start
 	end := start + 3
 	if end < len(f.Source) && f.Source[end] == ' ' {
@@ -156,21 +156,6 @@ func taskCheckBoxEdits(f *lint.File, n *extast.TaskCheckBox) []edit {
 	return []edit{{start: start, end: end}}
 }
 
-// nearestBlockAncestor walks up from n and returns the first block-
-// typed ancestor with non-empty Lines(). Mirrors the helper in
-// pkg/markdown/flavor; duplicated here to keep that helper internal.
-func nearestBlockAncestor(n ast.Node) ast.Node {
-	for p := n.Parent(); p != nil; p = p.Parent() {
-		if p.Type() != ast.TypeBlock {
-			continue
-		}
-		if lines := p.Lines(); lines != nil && lines.Len() > 0 {
-			return p
-		}
-	}
-	return nil
-}
-
 // wrapBareURL wraps a bare URL in angle brackets so the renderer
 // treats it as a CommonMark autolink. The detector reports a precise
 // span via fin.Start / fin.End.

pkg/markdown/flavor/contract_test.go

@@ -120,13 +120,14 @@ func TestContract_ParserConstructors(t *testing.T) {
 }
 
 // TestContract_Rewriters covers the small surface needed by external
-// rewriters: FindHeadingID, IsGitHubAlert, LineCol.
+// rewriters: FindHeadingID, IsGitHubAlert, LineCol, NearestBlockAncestor.
 func TestContract_Rewriters(t *testing.T) {
 	source := []byte("# h\n")
 	h := ast.NewHeading(1)
 	_, _ = flavor.FindHeadingID(source, h)
 	_ = flavor.IsGitHubAlert(ast.NewBlockquote(), source)
 	_, _ = flavor.LineCol(source, 0)
+	_ = flavor.NearestBlockAncestor(h)
 }
 
 // TestContract_ExtensionExtenders pins the five custom extension

pkg/markdown/flavor/detect.go

@@ -483,6 +483,15 @@ func LineCol(source []byte, offset int) (line, col int) {
 	return lineCol(source, offset)
 }
 
+// NearestBlockAncestor walks up from n and returns the first block-
+// typed ancestor with a non-empty Lines() segment, or nil when none
+// exists. Exposed for rewriters that hold an inline AST node and
+// need the block context that owns its source position (e.g. to
+// anchor a line-level edit on the containing paragraph).
+func NearestBlockAncestor(n ast.Node) ast.Node {
+	return nearestBlockAncestor(n)
+}
+
 // findHeadingID locates the trailing "{#id}" attribute block that the
 // goldmark attribute parser consumed. The Heading node's Lines segment
 // only covers the inner text, so we scan the raw line in source from

pkg/markdown/flavor/detect_edge_test.go

@@ -121,25 +121,121 @@ func TestNodeByteRangeClampsNegativeStart(t *testing.T) {
 	assert.Equal(t, 0, end)
 }
 
-// TestNearestBlockAncestorSkipsNonBlockAncestors exercises the
-// "parent is not a block" branch in nearestBlockAncestor: when we
-// walk through an inline ancestor on the way up, the helper skips
-// it and keeps climbing.
-func TestNearestBlockAncestorSkipsNonBlockAncestors(t *testing.T) {
-	// Build: Paragraph (block, has Lines) → Emphasis (inline) →
-	// FootnoteLink (inline). Walking up from the FootnoteLink must
-	// skip Emphasis and return the Paragraph.
+// TestNearestBlockAncestor exercises the "parent is not a block"
+// branch in nearestBlockAncestor: when the walk encounters an
+// inline ancestor on the way up, the helper skips it and keeps
+// climbing. Also covers the nil-parent return when an orphan node
+// has no ancestor at all.
+func TestNearestBlockAncestor(t *testing.T) {
+	t.Run("skips non-block ancestors", func(t *testing.T) {
+		// Paragraph (block, has Lines) → Emphasis (inline) →
+		// FootnoteLink (inline). Walking up from the FootnoteLink must
+		// skip Emphasis and return the Paragraph.
+		p := ast.NewParagraph()
+		// Append a line so findingFromBlock can resolve a position
+		// later (not needed here, but keeps the block well-formed).
+		p.Lines().Append(text.NewSegment(0, 1))
+		em := ast.NewEmphasis(1)
+		link := extast.NewFootnoteLink(1)
+		p.AppendChild(p, em)
+		em.AppendChild(em, link)
+		assert.Same(t, ast.Node(p), nearestBlockAncestor(link))
+	})
+
+	t.Run("returns nil for orphan node", func(t *testing.T) {
+		assert.Nil(t, nearestBlockAncestor(extast.NewFootnoteLink(1)))
+	})
+}
+
+// TestNearestBlockAncestorPublic is the dedicated unit test for the
+// public NearestBlockAncestor wrapper. The wrapper delegates to the
+// unexported helper, so this confirms the surface forwards without
+// re-implementing the walk.
+func TestNearestBlockAncestorPublic(t *testing.T) {
 	p := ast.NewParagraph()
-	// Append a line so findingFromBlock can resolve a position
-	// later (not needed here, but keeps the block well-formed).
 	p.Lines().Append(text.NewSegment(0, 1))
-	em := ast.NewEmphasis(1)
 	link := extast.NewFootnoteLink(1)
-	p.AppendChild(p, em)
-	em.AppendChild(em, link)
+	p.AppendChild(p, link)
+	assert.Same(t, ast.Node(p), NearestBlockAncestor(link))
+	assert.Nil(t, NearestBlockAncestor(extast.NewFootnoteLink(1)))
+}
+
+// TestIsGitHubAlertPublic exercises the public IsGitHubAlert wrapper
+// on both branches of the underlying isGitHubAlert helper: a
+// well-formed alert blockquote returns true; a blockquote whose
+// first child is not a paragraph returns false.
+func TestIsGitHubAlertPublic(t *testing.T) {
+	t.Run("recognises alert blockquote", func(t *testing.T) {
+		src := []byte("> [!NOTE]\n> body\n")
+		root := mkDoc(t, string(src))
+		var bq *ast.Blockquote
+		_ = ast.Walk(root.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+			if !entering {
+				return ast.WalkContinue, nil
+			}
+			if b, ok := n.(*ast.Blockquote); ok {
+				bq = b
+				return ast.WalkStop, nil
+			}
+			return ast.WalkContinue, nil
+		})
+		require.NotNil(t, bq, "expected the CommonMark parse to produce a *ast.Blockquote")
+		assert.True(t, IsGitHubAlert(bq, src))
+	})
 
-	got := nearestBlockAncestor(link)
-	assert.Same(t, ast.Node(p), got)
+	t.Run("rejects non-paragraph first child", func(t *testing.T) {
+		// A blockquote whose first child is a heading short-circuits
+		// the type assertion inside isGitHubAlert.
+		src := []byte("> # heading\n")
+		root := mkDoc(t, string(src))
+		var bq *ast.Blockquote
+		_ = ast.Walk(root.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+			if !entering {
+				return ast.WalkContinue, nil
+			}
+			if b, ok := n.(*ast.Blockquote); ok {
+				bq = b
+				return ast.WalkStop, nil
+			}
+			return ast.WalkContinue, nil
+		})
+		require.NotNil(t, bq)
+		assert.False(t, IsGitHubAlert(bq, src))
+	})
+}
+
+// TestLineColPublic is the dedicated unit test for the public
+// LineCol wrapper. The contract test exercises the call shape; this
+// test pins the documented "1-based" semantics on real input.
+func TestLineColPublic(t *testing.T) {
+	src := []byte("hello\nworld\n")
+	line, col := LineCol(src, 6) // start of "world"
+	assert.Equal(t, 2, line)
+	assert.Equal(t, 1, col)
+}
+
+// TestDualFindings exercises the pooled-parser helper extracted from
+// Detect. The accept predicate must filter findings at the helper's
+// own seam — a keep callback that rejects FeatureTables must not
+// emit a Tables finding even though the dual AST contains a Table.
+func TestDualFindings(t *testing.T) {
+	src := []byte("| a | b |\n| - | - |\n| 1 | 2 |\n\n~~old~~\n")
+	rejectTables := func(feat Feature) bool {
+		return feat != FeatureTables
+	}
+	got := dualFindings(src, rejectTables)
+	for _, f := range got {
+		assert.NotEqual(t, FeatureTables, f.Feature,
+			"keep predicate must suppress FeatureTables findings")
+	}
+	// Strikethrough is still kept, so the helper still does real work.
+	found := false
+	for _, f := range got {
+		if f.Feature == FeatureStrikethrough {
+			found = true
+		}
+	}
+	assert.True(t, found, "expected at least one Strikethrough finding")
 }
 
 // TestFindHeadingIDHandlesMissingLines exercises the

pkg/markdown/flavor/detect_pin_test.go

@@ -0,0 +1,146 @@
+package flavor
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/jeduden/mdsmith/pkg/markdown"
+)
+
+// pinCase is one row in the byte-identical Detect corpus.
+type pinCase struct {
+	name string
+	src  string
+	want []findingShape
+}
+
+// pinCorpus is the representative input corpus mapped to its
+// byte-exact Finding stream (feature, line, column for every emit,
+// in document order). Any code path that subtly reorders, drops,
+// duplicates, or shifts a finding will break TestDetectByteIdenticalPin
+// — that is the plan-185 byte-stable guarantee against MDS034
+// diagnostic drift. Start and End byte anchors are not pinned here:
+// they are exercised individually by the per-feature TestDetect*
+// tests and have less stable cross-feature semantics (some are
+// line-start anchors, some are zero-length).
+var pinCorpus = []pinCase{
+	{
+		name: "plain commonmark emits nothing",
+		src:  "# Heading\n\nA paragraph.\n\n- one\n- two\n",
+		want: nil,
+	},
+	{
+		name: "tables and bare URLs sort by start",
+		src: "See https://example.com.\n\n" +
+			"| a | b |\n| - | - |\n| 1 | 2 |\n",
+		want: []findingShape{
+			{FeatureBareURLAutolinks, 1, 5},
+			{FeatureTables, 3, 1},
+		},
+	},
+	{
+		name: "every feature in one document",
+		src: "# Title {#top}\n\n" +
+			"- [ ] task\n\n" +
+			"| a | b |\n| - | - |\n| 1 | 2 |\n\n" +
+			"~~old~~ https://example.com\n\n" +
+			"text^sup^ and H~2~O\n\n" +
+			"$x+1$ inline\n\n" +
+			"$$\nblock\n$$\n\n" +
+			"*[API]: Application Programming Interface\n\n" +
+			"Use API here.[^1]\n\n" +
+			"[^1]: footnote body\n\n" +
+			"term\n:   definition\n\n" +
+			"> [!NOTE]\n> Something.\n",
+		want: []findingShape{
+			{FeatureHeadingIDs, 1, 9},
+			{FeatureTaskLists, 3, 3},
+			{FeatureTables, 5, 1},
+			{FeatureStrikethrough, 9, 1},
+			{FeatureBareURLAutolinks, 9, 9},
+			{FeatureSuperscript, 11, 5},
+			{FeatureSubscript, 11, 16},
+			{FeatureMathInline, 13, 1},
+			{FeatureMathBlock, 15, 1},
+			{FeatureAbbreviations, 19, 1},
+			{FeatureFootnotes, 21, 1},
+			{FeatureAbbreviations, 21, 5},
+			{FeatureFootnotes, 23, 1},
+			{FeatureDefinitionLists, 25, 1},
+			{FeatureGitHubAlerts, 28, 1},
+		},
+	},
+	{
+		name: "github alert variants in order",
+		src: "> [!NOTE]\n> n.\n\n" +
+			"> [!TIP]\n> t.\n\n" +
+			"> [!WARNING]\n> w.\n",
+		want: []findingShape{
+			{FeatureGitHubAlerts, 1, 1},
+			{FeatureGitHubAlerts, 4, 1},
+			{FeatureGitHubAlerts, 7, 1},
+		},
+	},
+}
+
+// TestDetectByteIdenticalPin runs Detect over pinCorpus and asserts
+// the exact Finding stream for every entry.
+func TestDetectByteIdenticalPin(t *testing.T) {
+	for _, tc := range pinCorpus {
+		t.Run(tc.name, func(t *testing.T) {
+			doc := markdown.Parse([]byte(tc.src))
+			got := Detect(doc, nil)
+			var gotShapes []findingShape
+			for _, f := range got {
+				gotShapes = append(gotShapes,
+					findingShape{f.Feature, f.Line, f.Column})
+			}
+			assert.Equalf(t, tc.want, gotShapes,
+				"finding stream drift; want vs got:\n%s\n",
+				diffShapes(tc.want, gotShapes))
+		})
+	}
+}
+
+// findingShape is the byte-identical pin tuple: the three Finding
+// fields whose stability is the documented MDS034 contract.
+type findingShape struct {
+	Feature Feature
+	Line    int
+	Column  int
+}
+
+// diffShapes renders a side-by-side report of expected vs actual
+// findings to make a drift-test failure self-diagnostic. assert's
+// default diff prints opaque struct dumps; this format mirrors the
+// stats-line style the rest of the test suite uses.
+func diffShapes(want, got []findingShape) string {
+	var sb strings.Builder
+	max := len(want)
+	if len(got) > max {
+		max = len(got)
+	}
+	sb.WriteString("idx | want feature line:col | got feature line:col\n")
+	for i := 0; i < max; i++ {
+		var w, g string
+		if i < len(want) {
+			w = fmt.Sprintf("%s %d:%d", want[i].Feature.Name(), want[i].Line, want[i].Column)
+		} else {
+			w = "(none)"
+		}
+		if i < len(got) {
+			g = fmt.Sprintf("%s %d:%d", got[i].Feature.Name(), got[i].Line, got[i].Column)
+		} else {
+			g = "(none)"
+		}
+		marker := " "
+		if w != g {
+			marker = "*"
+		}
+		fmt.Fprintf(&sb, "%s%3d | %-30s | %s\n", marker, i, w, g)
+	}
+	return sb.String()
+}