Improve D&D validation reliability

internal/modules/dnd/validate/spells/shape/validator.go

@@ -8,12 +8,13 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
 )
 
 const (
 	Key        = "extract/dnd/spells/shape"
 	ReasonCode = "invalid_spell_shape"
-	policy     = "dnd.spells.validator.shape.v1"
+	policy     = "dnd.spells.validator.shape.v2"
 )
 
 type Options struct{}
@@ -31,28 +32,69 @@ func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
 	return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
 }
 func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.SpellList]) (contracts.ValidationResult, error) {
-	if err := Validate(req.Value); err != nil {
-		return rejection(err.Error()), nil
+	assessment := assess(req.Value)
+	if len(assessment.issues) != 0 {
+		return rejection(assessment.message(), assessment.corrections.Guidance("Correct every rejected spell cast and return the complete replacement list")), nil
 	}
 	return contracts.ValidationResult{Approved: true}, nil
 }
 
 func Validate(value dnd.SpellList) error {
+	assessment := assess(value)
+	if len(assessment.issues) == 0 {
+		return nil
+	}
+	return fmt.Errorf("%s", assessment.message())
+}
+
+type validationAssessment struct {
+	issues      []string
+	corrections diagnostics.Corrections
+}
+
+func assess(value dnd.SpellList) validationAssessment {
+	var assessment validationAssessment
 	if value.SpellCasts == nil {
-		return fmt.Errorf("spell_casts must be present")
+		assessment.issues = append(assessment.issues, "spell_casts must be present")
+		assessment.corrections.Add("list", "Return a `spell_casts` array; use an empty array when the transcript establishes no spell casts.", "")
+		return assessment
 	}
 	for index, spell := range value.SpellCasts {
+		context := spellContext(spell)
 		if strings.TrimSpace(spell.Caster) == "" {
-			return fmt.Errorf("spell_casts[%d].caster must not be empty", index)
+			assessment.issues = append(assessment.issues, fmt.Sprintf("spell_casts[%d].caster must not be empty", index))
+			assessment.corrections.Add("caster", "Provide the contextual caster name for every spell cast.", context)
 		}
 		if strings.TrimSpace(spell.Spell) == "" {
-			return fmt.Errorf("spell_casts[%d].spell must not be empty", index)
+			assessment.issues = append(assessment.issues, fmt.Sprintf("spell_casts[%d].spell must not be empty", index))
+			assessment.corrections.Add("spell", "Provide the transcript-supported spell name for every spell cast.", context)
 		}
 		if len(spell.SourceRefs) == 0 {
-			return fmt.Errorf("spell_casts[%d].source_refs must not be empty", index)
+			assessment.issues = append(assessment.issues, fmt.Sprintf("spell_casts[%d].source_refs must not be empty", index))
+			assessment.corrections.Add("source-refs", "Provide at least one transcript source range that directly supports every spell cast.", context)
 		}
 	}
-	return nil
+	return assessment
+}
+
+func (assessment validationAssessment) message() string {
+	return diagnostics.Aggregate("invalid spell shape", assessment.issues)
+}
+
+func spellContext(spell dnd.SpellCast) string {
+	name := strings.TrimSpace(spell.Spell)
+	if name == "" {
+		name = "blank spell name"
+	} else {
+		name = "spell " + diagnostics.Quote(name)
+	}
+	caster := strings.TrimSpace(spell.Caster)
+	if caster == "" {
+		caster = "blank caster name"
+	} else {
+		caster = "caster " + diagnostics.Quote(caster)
+	}
+	return "Affected cast: " + name + " with " + caster + " " + diagnostics.SourceRange(spell.SourceRefs) + "."
 }
 
 func Spec() pipeline.ValidatorSpec {
@@ -74,6 +116,6 @@ func DecodeOptions(options map[string]any) (Options, error) {
 	return Options{}, nil
 }
 func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
-func rejection(message string) contracts.ValidationResult {
-	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: "Return a complete spell-cast list with a nonblank spell name and caster plus valid source references for every cast."}
+func rejection(message, guidance string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message, CorrectionGuidance: guidance}
 }

internal/modules/dnd/validate/spells/shape/validator_test.go

@@ -2,6 +2,7 @@ package shape
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
@@ -54,6 +55,30 @@ func TestValidatorRejectsMissingRequiredSpellFields(t *testing.T) {
 	}
 }
 
+func TestValidatorReportsAllSpellDefectsWithContextualGuidance(t *testing.T) {
+	value := dnd.SpellList{SpellCasts: []dnd.SpellCast{
+		{Caster: "", Spell: "Fire Bolt", SourceRefs: refsAt(4)},
+		{Caster: "Aria", Spell: "", SourceRefs: nil},
+	}}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(value))
+	if err != nil || result.Approved {
+		t.Fatalf("Validate() = %#v, %v; want rejection", result, err)
+	}
+	for _, want := range []string{"spell_casts[0].caster", "spell_casts[1].spell", "spell_casts[1].source_refs"} {
+		if !strings.Contains(result.Message, want) {
+			t.Fatalf("Message = %q, want %q", result.Message, want)
+		}
+	}
+	for _, want := range []string{"Fire Bolt", "source unit 4", "Aria", "complete replacement"} {
+		if !strings.Contains(result.CorrectionGuidance, want) {
+			t.Fatalf("CorrectionGuidance = %q, want %q", result.CorrectionGuidance, want)
+		}
+	}
+	if strings.Contains(result.CorrectionGuidance, "spell_casts[") {
+		t.Fatalf("CorrectionGuidance exposed operator path: %q", result.CorrectionGuidance)
+	}
+}
+
 func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
 	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != policy {
 		t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
@@ -77,3 +102,7 @@ func requestWithValue(value dnd.SpellList) contracts.TypedValidationRequest[dnd.
 func validSpellList() dnd.SpellList {
 	return dnd.SpellList{SpellCasts: []dnd.SpellCast{{Caster: "Aria", Spell: "Cure Wounds", SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}}}
 }
+
+func refsAt(unitID int) []source.SourceRef {
+	return []source.SourceRef{{SourceID: "session", StartUnitID: unitID, EndUnitID: unitID}}
+}