schema: add coverage for plan 156 helpers

Codecov flagged the patch coverage on PR #295. Add focused tests
for the new helpers introduced by plan 156:

- claimsLaterLiteral: cover all four branches (slot, preamble,
  optional, already-claimed) plus the no-match case.
- displayHeading: cover the three label-source paths (bare
  Heading, Matcher fallback, preamble empty).
- claimRun (wrong-level): exercise the level-mismatch path via
  a nested schema whose inner heading appears at the outer
  level.
- sequentialDiagMessage: cover the non-integer guard and the
  happy path.
- cachedMatcher / compileMatcher: nil and invalid-pattern
  early-error branches.
- matchHeading: nil-matcher branch and `digits` capture path.
- fmvarLookup: missing-field, nil-fm, empty-name returns.
- resolvePattern: passthrough literals and unknown-helper error.
- setMatcherRegex / setMatcherRepeat: type and bound guards.
- scopeMatchesHeading: nil-matcher branch.
- protoTokenRegex: literal, {n}, {field}, and mixed forms.
- Scope.Required and Repeat.Bounds: every branch.

Schema-package coverage moves from 95.4% to 96.8%.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

internal/schema/plan156_coverage_test.go

@@ -0,0 +1,292 @@
+package schema
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestClaimsLaterLiteral_Branches covers the four branches of
+// claimsLaterLiteral so an ambiguous matcher run (e.g. `regex: '.+'`
+// with `repeat: { min: 1 }`) yields to a later literal entry only
+// when one is actually present.
+func TestClaimsLaterLiteral_Branches(t *testing.T) {
+	scopes := []Scope{
+		// idx 0: preamble — never claims
+		{Preamble: true},
+		// idx 1: slot — never claims (no fixed identity)
+		slotScope(),
+		// idx 2: optional literal — present but not required, skipped
+		optionalScope("Optional"),
+		// idx 3: required literal that matches the heading
+		literalScope("References"),
+	}
+	claimed := map[int]bool{}
+	dh := DocHeading{Text: "References", Level: 2}
+	assert.True(t,
+		claimsLaterLiteral(scopes, 0, dh, claimed, nil),
+		"a heading whose text matches a later required literal must reserve for that literal")
+
+	// dh that doesn't match any later literal — no claim.
+	other := DocHeading{Text: "Trailing", Level: 2}
+	assert.False(t,
+		claimsLaterLiteral(scopes, 0, other, claimed, nil),
+		"a heading that matches no later required literal does not reserve")
+
+	// startIdx past the literal — none ahead, no claim.
+	assert.False(t,
+		claimsLaterLiteral(scopes, 4, dh, claimed, nil),
+		"no scopes at or after startIdx => no claim")
+
+	// Already-claimed literal — not eligible.
+	claimed[3] = true
+	assert.False(t,
+		claimsLaterLiteral(scopes, 0, dh, claimed, nil),
+		"a claimed later literal must not reserve again")
+}
+
+// TestDisplayHeading_Branches covers all three return paths.
+func TestDisplayHeading_Branches(t *testing.T) {
+	// Heading set — bare-string sugar path.
+	assert.Equal(t, "Overview", displayHeading(literalScope("Overview")))
+	// Heading empty, Matcher set — mapping-form fallback.
+	sc := Scope{Matcher: &Matcher{Regex: ".+"}}
+	assert.Equal(t, ".+", displayHeading(sc))
+	// Neither set — preamble label.
+	assert.Equal(t, "", displayHeading(Scope{Preamble: true}))
+}
+
+// TestClaimRun_WrongLevelMatch covers claimRun, which fires when
+// matchScope sees a shallower-than-expected heading that still
+// matches the matcher: the level-mismatch diagnostic is appended
+// and the run is claimed.
+func TestClaimRun_WrongLevelMatch(t *testing.T) {
+	// Nested schema: outer expects H2, inner expects H3. The doc
+	// emits the inner heading at H2 (shallower than expected).
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{
+				"heading": "Outer",
+				"sections": []any{
+					map[string]any{"heading": "Inner"},
+				},
+			},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## Outer\n\n## Inner\n\nx\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	var level bool
+	for _, d := range diags {
+		if d.Message == `heading level mismatch for "Inner": expected h3, got h2` {
+			level = true
+		}
+	}
+	assert.True(t, level, "claimRun should emit the level-mismatch diagnostic")
+}
+
+// TestSequentialDiagMessage_NonInteger covers the parse-error path
+// inside sequentialDiagMessage. The `digits` helper always matches
+// `[0-9]+` so this never trips in normal usage; exercising it
+// directly keeps the safety branch covered.
+func TestSequentialDiagMessage_NonInteger(t *testing.T) {
+	got := sequentialDiagMessage([]string{"abc"})
+	assert.Contains(t, got, "must be integers")
+}
+
+// TestSequentialDiagMessage_OK returns empty when the sequence is
+// strictly increasing.
+func TestSequentialDiagMessage_OK(t *testing.T) {
+	assert.Empty(t, sequentialDiagMessage([]string{"1", "2", "3"}))
+}
+
+// TestCachedMatcher_NilAndInvalid covers the two early-error
+// branches of cachedMatcher.
+func TestCachedMatcher_NilAndInvalid(t *testing.T) {
+	_, err := cachedMatcher(nil, nil)
+	require.Error(t, err)
+
+	_, err = cachedMatcher(&Matcher{Regex: "[unterminated"}, nil)
+	require.Error(t, err)
+}
+
+// TestMatchHeading_NilMatcher covers the early-return for a nil
+// matcher (the preamble's shape).
+func TestMatchHeading_NilMatcher(t *testing.T) {
+	matched, captured := matchHeading(nil, DocHeading{Text: "x"}, nil)
+	assert.False(t, matched)
+	assert.Empty(t, captured)
+}
+
+// TestMatchHeading_DigitsCapture verifies the captured group is
+// returned alongside the match.
+func TestMatchHeading_DigitsCapture(t *testing.T) {
+	m := &Matcher{Regex: `Step \#(digits)`}
+	matched, captured := matchHeading(m, DocHeading{Text: "Step 42"}, nil)
+	assert.True(t, matched)
+	assert.Equal(t, "42", captured)
+}
+
+// TestFmvarLookup_MissingField returns an empty string for a
+// missing field, leaving the validator to flag the mismatch via
+// the usual missing-section diagnostic.
+func TestFmvarLookup_MissingField(t *testing.T) {
+	assert.Empty(t, fmvarLookup(nil, "id"))
+	assert.Empty(t, fmvarLookup(map[string]any{}, "id"))
+	assert.Empty(t, fmvarLookup(map[string]any{"id": "X"}, ""))
+}
+
+// TestResolvePattern_PassesThroughLiterals leaves a pattern without
+// interpolations untouched.
+func TestResolvePattern_PassesThroughLiterals(t *testing.T) {
+	got, err := resolvePattern(`Step [0-9]+`, nil)
+	require.NoError(t, err)
+	assert.Equal(t, `Step [0-9]+`, got)
+}
+
+// TestResolvePattern_RejectsUnknownHelper surfaces the validator's
+// runtime-side guard (parse-time is covered separately via
+// resolvePatternForCheck).
+func TestResolvePattern_RejectsUnknownHelper(t *testing.T) {
+	_, err := resolvePattern(`\#(bogus)`, nil)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unknown helper")
+}
+
+// TestCompileMatcher_NilRejected protects against a nil-pointer
+// crash if a caller accidentally invokes the helper without a
+// matcher.
+func TestCompileMatcher_NilRejected(t *testing.T) {
+	_, err := compileMatcher(nil, nil)
+	require.Error(t, err)
+}
+
+// TestSetMatcherRegex_EmptyRejected covers the trim/empty guard.
+func TestSetMatcherRegex_EmptyRejected(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": map[string]any{"regex": "   "}},
+		},
+	}
+	_, err := ParseInline(raw, "kind x")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "empty pattern")
+}
+
+// TestSetMatcherRegex_NonStringRejected covers the type guard.
+func TestSetMatcherRegex_NonStringRejected(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": map[string]any{"regex": 42}},
+		},
+	}
+	_, err := ParseInline(raw, "kind x")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be a string")
+}
+
+// TestSetMatcherRepeat_NotAMapping covers the type guard.
+func TestSetMatcherRepeat_NotAMapping(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": map[string]any{
+				"regex":  "X",
+				"repeat": "nope",
+			}},
+		},
+	}
+	_, err := ParseInline(raw, "kind x")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be a mapping")
+}
+
+// TestSetMatcherRepeat_UnknownKey covers the unknown-key guard.
+func TestSetMatcherRepeat_UnknownKey(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": map[string]any{
+				"regex":  "X",
+				"repeat": map[string]any{"bogus": 1},
+			}},
+		},
+	}
+	_, err := ParseInline(raw, "kind x")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unknown key")
+}
+
+// TestSetMatcherRepeat_NegativeMin covers the bound-validation
+// path inside readIntBound.
+func TestSetMatcherRepeat_NegativeMin(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": map[string]any{
+				"regex":  "X",
+				"repeat": map[string]any{"min": -1},
+			}},
+		},
+	}
+	_, err := ParseInline(raw, "kind x")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "non-negative")
+}
+
+// TestScopeMatchesHeading_NilScope returns false rather than
+// panicking on the nil-matcher branch.
+func TestScopeMatchesHeading_NilScope(t *testing.T) {
+	assert.False(t, scopeMatchesHeading(Scope{}, DocHeading{Text: "x"}, nil))
+}
+
+// TestScope_Required covers the three branches of Scope.Required.
+func TestScope_Required(t *testing.T) {
+	// Preamble is never required.
+	assert.False(t, Scope{Preamble: true}.Required())
+	// Matcher absent → not required.
+	assert.False(t, Scope{}.Required())
+	// Optional matcher (min=0) → not required.
+	opt := Scope{Matcher: &Matcher{
+		Regex:  "X",
+		Repeat: Repeat{Set: true, Min: 0, Max: 1},
+	}}
+	assert.False(t, opt.Required())
+	// Default cardinality (1..1) → required.
+	assert.True(t, literalScope("X").Required())
+	// Min=2 → required.
+	bounded := Scope{Matcher: &Matcher{
+		Regex:  "X",
+		Repeat: Repeat{Set: true, Min: 2, Max: 5},
+	}}
+	assert.True(t, bounded.Required())
+}
+
+// TestRepeatBounds covers Repeat.Bounds and Repeat.Optional defaults.
+func TestRepeatBounds(t *testing.T) {
+	// Unset → (1, 1).
+	min, max := Repeat{}.Bounds()
+	assert.Equal(t, 1, min)
+	assert.Equal(t, 1, max)
+	assert.False(t, Repeat{}.Optional())
+	// Set with min=0 → optional.
+	r := Repeat{Set: true, Min: 0, Max: 0}
+	min, max = r.Bounds()
+	assert.Equal(t, 0, min)
+	assert.Equal(t, 0, max)
+	assert.True(t, r.Optional())
+}
+
+// TestProtoTokenRegex_AllTokens exercises the four desugaring
+// branches the proto.md parser uses.
+func TestProtoTokenRegex_AllTokens(t *testing.T) {
+	// Literal text — regex-escape only.
+	assert.Equal(t, `Step \(One\)`, protoTokenRegex(`Step (One)`))
+	// `{n}` → digits helper.
+	assert.Equal(t, `Step \#(digits)`, protoTokenRegex(`Step {n}`))
+	// `{field}` → fmvar helper.
+	assert.Equal(t, `\#(fmvar(id))`, protoTokenRegex(`{id}`))
+	// Mixed literal + fmvar.
+	assert.Equal(t, `\#(fmvar(id)): \#(fmvar(name))`,
+		protoTokenRegex(`{id}: {name}`))
+}