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}
 }