fix(MDS020): anchor non-body diagnostics outside body line range

Address two Copilot review comments (validate.go:223 and the
suppressed-confidence comment on validate.go:1025): diagnostics
that don't correspond to a body line (filename/path-pattern
mismatches, missing required sections, FM compile failures,
fmDiagLine fallback) used to emit at body-coord line 1. In
front-matter-stripped mode, line 1 is the first body line, so
engine.filterGeneratedDiags could silently drop the diagnostic
if the document body started with a generated section.

Introduce schema.NonBodyDiagLine(f) returning `1 - f.LineOffset`
— a non-positive body coord in stripped mode that
filterGeneratedDiags cannot match against any generated line
range. The engine's AdjustDiagnostics adds the offset back so
the surfaced diagnostic still anchors at the file's first
line.

All "doesn't-belong-to-a-body-line" emit sites switch to the
new helper:

- schema.validateFrontmatterDiags: every early-return path
  (invalid CUE schema, json.Marshal failure, CompileBytes
  failure, validator fallback)
- schema.validateScopes: missing-section diagnostic
- schema.validateFilename: both invalid-pattern and mismatch
  paths
- schema.fmDiagLine: both fallback returns (empty keyLines,
  key absent from map)
- requiredstructure.missingSectionDiagLegacy: legacy file-
  schema path
- requiredstructure.readDocFrontMatterRaw: YAML alias-rejected
  and unmarshal-error paths
- requiredstructure.checkPathPatterns: path-pattern mismatch
- requiredstructure.checkFilenamePattern: both paths

Existing fixture tests use lint.NewFile (LineOffset == 0) so
they keep observing line 1 as before; the change only affects
the lint.NewFileFromSource(..., true) production path. New
TestNonBodyDiagLine_StrippedAndUnstripped pins the helper's
contract.

https://claude.ai/code/session_01QcXckX3yVwReho2kaq3qRK

Author: claude

internal/rules/requiredstructure/rule.go

@@ -1030,7 +1030,11 @@ func missingSectionDiagLegacy(
 		Expected:  "section to be present",
 		SchemaRef: ref,
 	}
-	return makeDiag(f.Path, 1, d.Format())
+	// Missing sections have no body line to point at; use the
+	// non-body anchor so the engine's filterGeneratedDiags can't
+	// drop the diagnostic when body line 1 sits inside a
+	// generated section.
+	return makeDiag(f.Path, schema.NonBodyDiagLine(f), d.Format())
 }
 
 // buildSchemaRefForLegacy returns the schema reference string
@@ -1361,12 +1365,12 @@ func readDocFrontMatterRaw(f *lint.File) (map[string]any, []lint.Diagnostic) {
 	}
 
 	if err := yamlutil.RejectYAMLAliases(yamlBytes); err != nil {
-		return nil, []lint.Diagnostic{makeDiag(f.Path, 1,
+		return nil, []lint.Diagnostic{makeDiag(f.Path, schema.NonBodyDiagLine(f),
 			fmt.Sprintf("front matter: %v", err))}
 	}
 	var raw map[string]any
 	if err := yaml.Unmarshal(yamlBytes, &raw); err != nil {
-		return nil, []lint.Diagnostic{makeDiag(f.Path, 1,
+		return nil, []lint.Diagnostic{makeDiag(f.Path, schema.NonBodyDiagLine(f),
 			fmt.Sprintf("front matter: invalid YAML: %v", err))}
 	}
 	return raw, nil
@@ -1456,7 +1460,7 @@ func (r *Rule) checkPathPatterns(f *lint.File) []lint.Diagnostic {
 			Expected:  fmt.Sprintf("path matching glob %s", pp.Pattern),
 			SchemaRef: fmt.Sprintf("kinds[%s] / path-pattern", pp.Kind),
 		}
-		diags = append(diags, makeDiag(f.Path, 1, d.Format()))
+		diags = append(diags, makeDiag(f.Path, schema.NonBodyDiagLine(f), d.Format()))
 	}
 	return diags
 }
@@ -1493,6 +1497,11 @@ func checkFilenamePattern(
 	if pattern == "" {
 		return nil
 	}
+	// Filename diagnostics describe the document as a whole;
+	// use the non-body anchor so filterGeneratedDiags can't
+	// drop them when body line 1 sits inside a generated
+	// section.
+	anchor := schema.NonBodyDiagLine(f)
 	base := filepath.Base(f.Path)
 	matched, err := filepath.Match(pattern, base)
 	if err != nil {
@@ -1507,7 +1516,7 @@ func checkFilenamePattern(
 			Hint:      err.Error(),
 			SchemaRef: buildSchemaRefForLegacy(schemaSource),
 		}
-		return []lint.Diagnostic{makeDiag(f.Path, 1, d.Format())}
+		return []lint.Diagnostic{makeDiag(f.Path, anchor, d.Format())}
 	}
 	if !matched {
 		// `glob` keeps the wording aligned with schema.validateFilename
@@ -1518,7 +1527,7 @@ func checkFilenamePattern(
 			Expected:  fmt.Sprintf("filename matching glob %s", pattern),
 			SchemaRef: buildSchemaRefForLegacy(schemaSource),
 		}
-		return []lint.Diagnostic{makeDiag(f.Path, 1, d.Format())}
+		return []lint.Diagnostic{makeDiag(f.Path, anchor, d.Format())}
 	}
 	return nil
 }

internal/schema/validate.go

@@ -134,22 +134,23 @@ func validateFrontmatterDiags(
 		return nil
 	}
 	ctx := cuecontext.New()
+	anchor := nonBodyDiagLine(f)
 	schemaVal := ctx.CompileString(expr)
 	if err := schemaVal.Err(); err != nil {
-		return []lint.Diagnostic{mkDiag(f.Path, 1,
+		return []lint.Diagnostic{mkDiag(f.Path, anchor,
 			compileFailureDiag(sch, "schema", "valid schema CUE", err).Format())}
 	}
 	if docFM == nil {
 		docFM = map[string]any{}
 	}
 	data, err := json.Marshal(docFM)
 	if err != nil {
-		return []lint.Diagnostic{mkDiag(f.Path, 1,
+		return []lint.Diagnostic{mkDiag(f.Path, anchor,
 			compileFailureDiag(sch, "front matter", "JSON-marshalable front matter", err).Format())}
 	}
 	dataVal := ctx.CompileBytes(data)
 	if err := dataVal.Err(); err != nil {
-		return []lint.Diagnostic{mkDiag(f.Path, 1,
+		return []lint.Diagnostic{mkDiag(f.Path, anchor,
 			compileFailureDiag(sch, "front matter", "valid front matter", err).Format())}
 	}
 	merged := schemaVal.Unify(dataVal)
@@ -159,7 +160,7 @@ func validateFrontmatterDiags(
 	}
 	cueErrs := errors.Errors(verr)
 	if len(cueErrs) == 0 {
-		return []lint.Diagnostic{mkDiag(f.Path, 1,
+		return []lint.Diagnostic{mkDiag(f.Path, anchor,
 			SchemaDiagnostic{
 				Field:     "front matter",
 				Actual:    fmt.Sprintf("%v", verr),
@@ -188,6 +189,38 @@ func validateFrontmatterDiags(
 	return out
 }
 
+// NonBodyDiagLine returns the body-coord line value that, after
+// lint.File.AdjustDiagnostics adds f.LineOffset, lands on the
+// absolute first line of the file (typically the opening `---`
+// fence of stripped front matter). It is the canonical anchor
+// for diagnostics that do not correspond to a specific body
+// line — schema-level compile failures, filename pattern
+// violations, and structure diagnostics for sections that are
+// missing entirely.
+//
+// The previous "anchor at line 1" pattern landed on the first
+// body line in front-matter-stripped mode, which
+// engine.filterGeneratedDiags could mistakenly drop if the
+// document body started with a generated section (e.g. a
+// leading <?catalog?> directive). Using `1 - LineOffset`
+// produces a non-positive body-coord that filterGeneratedDiags
+// cannot match against any generated line range, and the
+// engine's AdjustDiagnostics adds the offset back so the
+// surfaced diagnostic still anchors at the file's first line.
+//
+// When f.LineOffset == 0 (the non-stripped path, used by tests
+// via lint.NewFile) the return value is just 1, matching the
+// previous behaviour.
+func NonBodyDiagLine(f *lint.File) int {
+	return 1 - f.LineOffset
+}
+
+// nonBodyDiagLine is the package-internal alias used inside the
+// schema package; external callers reach for NonBodyDiagLine.
+func nonBodyDiagLine(f *lint.File) int {
+	return NonBodyDiagLine(f)
+}
+
 // fmDiagLine returns the line to anchor a front-matter diagnostic
 // at, expressed in the body-line coordinate system the engine
 // uses before lint.File.AdjustDiagnostics fires. When the doc's
@@ -205,20 +238,25 @@ func validateFrontmatterDiags(
 // for the contract). In unstripped mode (LineOffset == 0) the
 // returned value already equals the absolute file line.
 //
-// When no per-key line is known the function falls back to line
-// 1 — the conventional "start of file" anchor, which the engine
-// also shifts to the first body line.
+// When no per-key line is known the function falls back to
+// nonBodyDiagLine(f) — a non-positive body coordinate in
+// stripped mode that AdjustDiagnostics resolves to the first
+// absolute line of the file. The fallback used to be a flat
+// "1", which landed on the first body line in stripped mode
+// and could be silently dropped by filterGeneratedDiags when
+// the document body started with a generated section
+// (PR #284 Copilot review).
 func fmDiagLine(f *lint.File, path []string, keyLines map[string]int) int {
 	if len(path) == 0 || len(keyLines) == 0 {
-		return 1
+		return nonBodyDiagLine(f)
 	}
 	line, ok := keyLines[path[0]]
 	if !ok {
 		// Top-level path may carry an optional-key suffix in the
 		// schema; the doc itself never does, so a miss here means
 		// the key was absent from the document (and therefore has
 		// no source line to point at).
-		return 1
+		return nonBodyDiagLine(f)
 	}
 	return line - f.LineOffset
 }
@@ -525,7 +563,11 @@ func validateScopes(
 		if found {
 			allowExtra = false
 		} else if !claimed[i] && sc.Required && !sc.Repeats {
-			diags = append(diags, mkDiag(f.Path, 1,
+			// Missing sections have no body line to point at;
+			// use the non-body anchor so filterGeneratedDiags
+			// can't drop the diagnostic if body line 1 sits
+			// inside a generated section.
+			diags = append(diags, mkDiag(f.Path, nonBodyDiagLine(f),
 				missingSectionDiag(formatHeading(expectedLevel, sc.Heading), sch).Format()))
 		}
 	}
@@ -1007,6 +1049,11 @@ func validateFilename(
 	if pattern == "" {
 		return nil
 	}
+	// Filename and path diagnostics describe the document as a
+	// whole, not a body line; use the non-body anchor so the
+	// engine's filterGeneratedDiags can't drop them when the
+	// document body starts with a generated section.
+	anchor := nonBodyDiagLine(f)
 	base := filepath.Base(f.Path)
 	matched, err := filepath.Match(pattern, base)
 	if err != nil {
@@ -1021,7 +1068,7 @@ func validateFilename(
 			Hint:      err.Error(),
 			SchemaRef: schemaRef(sch, ""),
 		}
-		return []lint.Diagnostic{mkDiag(f.Path, 1, d.Format())}
+		return []lint.Diagnostic{mkDiag(f.Path, anchor, d.Format())}
 	}
 	if !matched {
 		// `glob` makes the constraint syntax explicit: users
@@ -1036,7 +1083,7 @@ func validateFilename(
 			Expected:  fmt.Sprintf("filename matching glob %s", pattern),
 			SchemaRef: schemaRef(sch, ""),
 		}
-		return []lint.Diagnostic{mkDiag(f.Path, 1, d.Format())}
+		return []lint.Diagnostic{mkDiag(f.Path, anchor, d.Format())}
 	}
 	return nil
 }

internal/schema/validate_coverage_test.go

@@ -179,6 +179,24 @@ func TestCompileFailureDiag_FieldsRoundTrip(t *testing.T) {
 	assert.Equal(t, "kind t", d.SchemaRef)
 }
 
+// TestNonBodyDiagLine_StrippedAndUnstripped exercises the
+// helper directly: a file built with FM stripping returns
+// a non-positive body coord (so filterGeneratedDiags can't
+// match it), and a file built without stripping returns 1
+// unchanged.
+func TestNonBodyDiagLine_StrippedAndUnstripped(t *testing.T) {
+	stripped, err := lint.NewFileFromSource("doc.md",
+		[]byte("---\nfoo: 1\n---\n# Body\n"), true)
+	require.NoError(t, err)
+	require.Greater(t, stripped.LineOffset, 0)
+	assert.LessOrEqual(t, NonBodyDiagLine(stripped), 0)
+
+	unstripped, err := lint.NewFile("doc.md", []byte("# Body\n"))
+	require.NoError(t, err)
+	assert.Equal(t, 0, unstripped.LineOffset)
+	assert.Equal(t, 1, NonBodyDiagLine(unstripped))
+}
+
 // TestValidateFrontmatterDiags_JSONMarshalFailureCarriesRef
 // regresses the json.Marshal early-return path. A channel
 // value in docFM is non-marshalable, so the validator falls