Add D&D NPC extraction and validation

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

@@ -0,0 +1,79 @@
+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/validate/npcs/diagnostics"
+	npcshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/shape"
+)
+
+const (
+	Key        = "extract/dnd/npcs/source_refs"
+	ReasonCode = "invalid_npc_source_refs"
+	policy     = "dnd.npcs.validator.source_refs.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCList] = (*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.NPCList]) (contracts.ValidationResult, error) {
+	if err := npcshape.Validate(req.Value); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	issues := make([]string, 0)
+	for npcIndex, npc := range req.Value.NPCs {
+		for refIndex, ref := range npc.SourceRefs {
+			if err := source.ValidateRef(req.Source, ref); err != nil {
+				issues = append(issues, fmt.Sprintf("npcs[%d].source_refs[%d]: %s", npcIndex, refIndex, diagnostics.Truncate(err.Error())))
+			}
+		}
+	}
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return rejection(diagnostics.Aggregate("invalid NPC source references", issues)), nil
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.NPCListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.NPCList], 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 }
+
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message}
+}

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

@@ -0,0 +1,88 @@
+package sourcerefs
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"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(), requestWithValue(validDocument(), validNPCList()))
+	if err != nil || !result.Approved || len(result.Warnings) != 0 {
+		t.Fatalf("Validate() = %#v, %v; want approval", result, err)
+	}
+}
+
+func TestValidatorRejectsInvalidSourceReferences(t *testing.T) {
+	value := validNPCList()
+	value.NPCs[0].SourceRefs = []source.SourceRef{
+		{SourceID: "foreign", StartUnitID: 1, EndUnitID: 1},
+		{SourceID: "session", StartUnitID: 2, EndUnitID: 1},
+		{SourceID: "session", StartUnitID: 99, EndUnitID: 99},
+	}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "npcs[0].source_refs[0]") {
+		t.Fatalf("Validate() = %#v, %v; want source-reference rejection", result, err)
+	}
+}
+
+func TestValidatorDefersMalformedShape(t *testing.T) {
+	value := dnd.NPCList{NPCs: []dnd.NPC{{Name: "Mira Thorn"}}}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), value))
+	if err != nil || !result.Approved || result.ReasonCode != "" || result.Message != "" {
+		t.Fatalf("Validate() = %#v, %v; want shape deferral", result, err)
+	}
+}
+
+func TestValidatorBoundsDiagnosticsAndHandlesMissingDocument(t *testing.T) {
+	value := validNPCList()
+	value.NPCs[0].SourceRefs = make([]source.SourceRef, 24)
+	for index := range value.NPCs[0].SourceRefs {
+		value.NPCs[0].SourceRefs[index] = source.SourceRef{SourceID: strings.Repeat("火", 220) + "\n\t", StartUnitID: index + 1, EndUnitID: index + 1}
+	}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(nil, value))
+	if err != nil || result.Approved || len([]byte(result.Message)) > 4096 || !utf8.ValidString(result.Message) {
+		t.Fatalf("Validate() = %#v, %v; want bounded missing-document rejection", result, err)
+	}
+	if !strings.Contains(result.Message, "additional issue(s) omitted") || !strings.Contains(result.Message, fmt.Sprintf("npcs[0].source_refs[%d]", 19)) {
+		t.Fatalf("message = %q, want bounded aggregate diagnostics", result.Message)
+	}
+}
+
+func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npcs.validator.source_refs.v1" {
+		t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
+	}
+	if Spec().ExecutionClass != contracts.ExecutionClassDeterministic {
+		t.Fatalf("Spec() = %#v, want deterministic 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 requestWithValue(doc *source.SourceDocument, value dnd.NPCList) contracts.TypedValidationRequest[dnd.NPCList] {
+	return contracts.TypedValidationRequest[dnd.NPCList]{Source: doc, Value: value}
+}
+
+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: "Mira Thorn enters."},
+		{ID: 2, Kind: "message", Text: "The ranger watches."},
+	}}
+}
+
+func validNPCList() dnd.NPCList {
+	return dnd.NPCList{NPCs: []dnd.NPC{{ID: "candidate", Name: "Mira Thorn", Aliases: []string{"The Greencloak"}, Description: "A ranger.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 2}}}}}
+}