Add standalone D&D combat turn extraction

internal/modules/dnd/validate/combatturns/source_refs/validator.go

@@ -0,0 +1,84 @@
+package sourcerefs
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"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"
+	combatshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/combatturns/shape"
+)
+
+const (
+	Key        = "extract/dnd/combat-turns/source_refs"
+	ReasonCode = "invalid_combat_turn_source_refs"
+	policy     = "dnd.combat_turns.validator.source_refs.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.CombatTurnList] = (*Validator)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Validator)(nil)
+
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
+}
+
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.CombatTurnList]) (contracts.ValidationResult, error) {
+	if err := combatshape.Validate(req.Value); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	issues := sourceRefIssues(req.Source, req.Value)
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    diagnostics.Aggregate("invalid combat turn source references", issues),
+	}, nil
+}
+
+func sourceRefIssues(doc *source.SourceDocument, value dnd.CombatTurnList) []string {
+	issues := make([]string, 0)
+	for turnIndex, turn := range value.CombatTurns {
+		for refIndex, ref := range turn.SourceRefs {
+			if err := source.ValidateRef(doc, ref); err != nil {
+				issues = append(issues, fmt.Sprintf("combat_turns[%d].source_refs[%d]: %s", turnIndex, refIndex, diagnostics.Truncate(err.Error())))
+			}
+		}
+	}
+	return issues
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.CombatTurnListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.CombatTurnList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
+	})
+}
+
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, err
+	}
+	return Options{}, nil
+}
+
+func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }

internal/modules/dnd/validate/combatturns/source_refs/validator_test.go

@@ -0,0 +1,87 @@
+package sourcerefs
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+)
+
+func TestValidatorApprovesValidSourceReferences(t *testing.T) {
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.CombatTurnList]{Source: validDocument(), Value: validCombatTurnList()})
+	if err != nil || !result.Approved || result.ReasonCode != "" {
+		t.Fatalf("Validate() = %#v, %v; want approval", result, err)
+	}
+}
+
+func TestValidatorRejectsInvalidSourceIdentityExistenceAndOrder(t *testing.T) {
+	tests := []struct {
+		name string
+		ref  source.SourceRef
+		want string
+	}{
+		{name: "missing document", ref: source.SourceRef{SourceID: "session", StartUnitID: 1, EndUnitID: 1}, want: "source document must not be nil"},
+		{name: "wrong source identity", ref: source.SourceRef{SourceID: "other", StartUnitID: 1, EndUnitID: 1}, want: "does not match document"},
+		{name: "missing start", ref: source.SourceRef{SourceID: "session", StartUnitID: 99, EndUnitID: 99}, want: "start_unit_id 99 was not found"},
+		{name: "backward range", ref: source.SourceRef{SourceID: "session", StartUnitID: 3, EndUnitID: 1}, want: "appears after end_unit_id"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			value := validCombatTurnList()
+			value.CombatTurns[0].SourceRefs[0] = test.ref
+			req := contracts.TypedValidationRequest[dnd.CombatTurnList]{Source: validDocument(), Value: value}
+			if test.name == "missing document" {
+				req.Source = nil
+			}
+			result, err := New(Options{}).Validate(context.Background(), req)
+			if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, test.want) {
+				t.Fatalf("Validate() = %#v, %v; want source-reference rejection containing %q", result, err, test.want)
+			}
+		})
+	}
+}
+
+func TestValidatorDefersMalformedShape(t *testing.T) {
+	value := dnd.CombatTurnList{CombatTurns: []dnd.CombatTurn{{Actor: "Aria"}}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.CombatTurnList]{Source: validDocument(), Value: value})
+	if err != nil || !result.Approved || len(result.Warnings) != 0 {
+		t.Fatalf("shape deferral = %#v, %v; want approval without source warning", result, err)
+	}
+}
+
+func TestSpecRegisterOptionsAndPolicy(t *testing.T) {
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != policy {
+		t.Fatalf("CheckpointFingerprints() = %#v, want source-reference policy", got)
+	}
+	if Spec().Key != Key || Spec().ExecutionClass != contracts.ExecutionClassDeterministic {
+		t.Fatalf("Spec() = %#v, want deterministic source-reference validator", Spec())
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func validCombatTurnList() dnd.CombatTurnList {
+	resolution := "The goblin is wounded."
+	return dnd.CombatTurnList{CombatTurns: []dnd.CombatTurn{{
+		Actor: "Aria", TurnKind: dnd.CombatTurnKindTurn,
+		Actions: []dnd.CombatAction{{Category: dnd.CombatActionCategoryAttack, Declaration: "Aria attacks", Targets: []string{}, Resolution: &resolution}},
+		Summary: "Aria attacks.", SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
+	}}}
+}
+
+func validDocument() *source.SourceDocument {
+	return &source.SourceDocument{ID: "session", Kind: "transcript", Format: "application/json", Digest: "sha256:session", Units: []source.SourceUnit{
+		{ID: 1, Kind: "message", Text: "Aria attacks."},
+		{ID: 2, Kind: "message", Text: "The goblin reels."},
+		{ID: 3, Kind: "message", Text: "Borin retreats."},
+	}}
+}