Add D&D scene description validation
This commit is contained in:
176
internal/modules/dnd/normalize/scenedescriptions/normalizer.go
Normal file
176
internal/modules/dnd/normalize/scenedescriptions/normalizer.go
Normal file
@@ -0,0 +1,176 @@
|
||||
// Package scenedescriptions normalizes merged D&D scene descriptions.
|
||||
package scenedescriptions
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"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"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/scenedescriptions/shape"
|
||||
)
|
||||
|
||||
const (
|
||||
Key = "dnd/scene-descriptions"
|
||||
normalizerPolicy = "dnd.scene_descriptions.normalizer.v1"
|
||||
)
|
||||
|
||||
var requiredCapabilities = []string{"merged"}
|
||||
var providedCapabilities = []string{"normalized"}
|
||||
|
||||
var _ contracts.Normalizer[dnd.SceneDescriptionList] = (*Normalizer)(nil)
|
||||
var _ contracts.ManifestMetadataProvider = (*Normalizer)(nil)
|
||||
var _ pipeline.CheckpointFingerprintProvider = (*Normalizer)(nil)
|
||||
|
||||
type Options struct{}
|
||||
type Normalizer struct{}
|
||||
|
||||
func New(Options) *Normalizer { return &Normalizer{} }
|
||||
|
||||
func (n *Normalizer) Key() string { return Key }
|
||||
|
||||
func (n *Normalizer) ReferenceSlots() []contracts.ReferenceSlot { return nil }
|
||||
|
||||
func (n *Normalizer) ManifestMetadata() map[string]any {
|
||||
if n == nil {
|
||||
return nil
|
||||
}
|
||||
return map[string]any{"normalizer_policy": normalizerPolicy}
|
||||
}
|
||||
|
||||
func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
|
||||
if n == nil {
|
||||
return nil
|
||||
}
|
||||
return []pipeline.CheckpointFingerprint{{Name: "normalizer_policy", Value: normalizerPolicy}}
|
||||
}
|
||||
|
||||
func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalizeRequest[dnd.SceneDescriptionList]) (contracts.TypedNormalizeResult[dnd.SceneDescriptionList], error) {
|
||||
if n == nil {
|
||||
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("normalizer must not be nil")
|
||||
}
|
||||
if ctx == nil {
|
||||
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("context must not be nil")
|
||||
}
|
||||
if err := ctx.Err(); err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("context error before normalize: %w", err)
|
||||
}
|
||||
value, err := normalizeList(req.MergeOutput.Value, req.Source)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{}, normalizerErrorf("normalize scenes: %w", err)
|
||||
}
|
||||
return contracts.TypedNormalizeResult[dnd.SceneDescriptionList]{Value: value}, nil
|
||||
}
|
||||
|
||||
func normalizeList(input dnd.SceneDescriptionList, doc *source.SourceDocument) (dnd.SceneDescriptionList, error) {
|
||||
if doc == nil {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("source document must not be nil")
|
||||
}
|
||||
if input.Scenes == nil {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes must be present")
|
||||
}
|
||||
if len(input.Scenes) == 0 {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes must not be empty")
|
||||
}
|
||||
|
||||
output := dnd.SceneDescriptionList{Scenes: make([]dnd.SceneDescription, len(input.Scenes))}
|
||||
for index, scene := range input.Scenes {
|
||||
scene.Title = strings.TrimSpace(scene.Title)
|
||||
scene.Summary = strings.TrimSpace(scene.Summary)
|
||||
if err := shape.Validate(dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{scene}}); err != nil {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes[%d]: %w", index, err)
|
||||
}
|
||||
if err := source.ValidateRef(doc, scene.SourceRef); err != nil {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("scenes[%d].source_ref: %s", index, diagnostics.Truncate(err.Error()))
|
||||
}
|
||||
output.Scenes[index] = scene
|
||||
}
|
||||
|
||||
sort.SliceStable(output.Scenes, func(left, right int) bool {
|
||||
leftStart, _ := source.UnitIndex(doc, output.Scenes[left].SourceRef.StartUnitID)
|
||||
rightStart, _ := source.UnitIndex(doc, output.Scenes[right].SourceRef.StartUnitID)
|
||||
if leftStart != rightStart {
|
||||
return leftStart < rightStart
|
||||
}
|
||||
return output.Scenes[left].ID < output.Scenes[right].ID
|
||||
})
|
||||
|
||||
unique := make([]dnd.SceneDescription, 0, len(output.Scenes))
|
||||
byID := make(map[string]dnd.SceneDescription, len(output.Scenes))
|
||||
byRange := make(map[source.SourceRef]dnd.SceneDescription, len(output.Scenes))
|
||||
for _, scene := range output.Scenes {
|
||||
if previous, ok := byID[scene.ID]; ok && !identical(previous, scene) {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("scene ID %s has conflicting records", diagnostics.Quote(scene.ID))
|
||||
}
|
||||
if previous, ok := byRange[scene.SourceRef]; ok && !sameModelContent(previous, scene) {
|
||||
return dnd.SceneDescriptionList{}, fmt.Errorf("source range %s has conflicting records", sourceRefLabel(scene.SourceRef))
|
||||
}
|
||||
if containsIdentical(unique, scene) {
|
||||
continue
|
||||
}
|
||||
byID[scene.ID] = scene
|
||||
byRange[scene.SourceRef] = scene
|
||||
unique = append(unique, scene)
|
||||
}
|
||||
output.Scenes = unique
|
||||
return output, nil
|
||||
}
|
||||
|
||||
func identical(left, right dnd.SceneDescription) bool {
|
||||
return left == right
|
||||
}
|
||||
|
||||
func sameModelContent(left, right dnd.SceneDescription) bool {
|
||||
return left.Kind == right.Kind && left.Title == right.Title && left.Summary == right.Summary
|
||||
}
|
||||
|
||||
func containsIdentical(scenes []dnd.SceneDescription, target dnd.SceneDescription) bool {
|
||||
for _, scene := range scenes {
|
||||
if identical(scene, target) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func sourceRefLabel(ref source.SourceRef) string {
|
||||
return fmt.Sprintf("%s:%d-%d", diagnostics.Quote(ref.SourceID), ref.StartUnitID, ref.EndUnitID)
|
||||
}
|
||||
|
||||
func ModuleSpec() pipeline.ModuleSpec {
|
||||
return pipeline.ModuleSpec{
|
||||
Key: Key,
|
||||
Stage: pipeline.StageNormalize,
|
||||
Requires: append([]string(nil), requiredCapabilities...),
|
||||
Provides: append([]string(nil), providedCapabilities...),
|
||||
ArtifactKind: dnd.SceneDescriptionListKind,
|
||||
}
|
||||
}
|
||||
|
||||
func Register(registry *pipeline.NormalizerRegistry) error {
|
||||
return pipeline.RegisterNormalizerBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Normalizer[dnd.SceneDescriptionList], 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{}, normalizerErrorf("%w", err)
|
||||
}
|
||||
return Options{}, nil
|
||||
}
|
||||
|
||||
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
|
||||
|
||||
func normalizerErrorf(format string, args ...any) error {
|
||||
return fmt.Errorf("dnd scene descriptions normalizer: "+format, args...)
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
package scenedescriptions
|
||||
|
||||
import (
|
||||
"context"
|
||||
"reflect"
|
||||
"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 TestNormalizeTrimsOrdersDeduplicatesAndOwnsOutput(t *testing.T) {
|
||||
doc := testDocument()
|
||||
input := dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{
|
||||
scene("later", 3, 3, dnd.SceneKindNarrative, " Return ", " The party returns. "),
|
||||
scene("first-b", 1, 1, dnd.SceneKindMeta, " Rules ", " The table checks rules. "),
|
||||
scene("first-a", 1, 1, dnd.SceneKindMeta, " Rules ", " The table checks rules. "),
|
||||
scene("later", 3, 3, dnd.SceneKindNarrative, " Return ", " The party returns. "),
|
||||
}}
|
||||
before := cloneList(input)
|
||||
result, err := New(Options{}).Normalize(context.Background(), normalizeRequest(input, doc))
|
||||
if err != nil {
|
||||
t.Fatalf("Normalize() error = %v, want nil", err)
|
||||
}
|
||||
want := []dnd.SceneDescription{
|
||||
scene("first-a", 1, 1, dnd.SceneKindMeta, "Rules", "The table checks rules."),
|
||||
scene("first-b", 1, 1, dnd.SceneKindMeta, "Rules", "The table checks rules."),
|
||||
scene("later", 3, 3, dnd.SceneKindNarrative, "Return", "The party returns."),
|
||||
}
|
||||
if !reflect.DeepEqual(result.Value.Scenes, want) {
|
||||
t.Fatalf("scenes = %#v, want %#v", result.Value.Scenes, want)
|
||||
}
|
||||
if !reflect.DeepEqual(input, before) {
|
||||
t.Fatalf("Normalize() mutated input: %#v", input)
|
||||
}
|
||||
result.Value.Scenes[0].Title = "changed"
|
||||
if input.Scenes[0].Title == "changed" {
|
||||
t.Fatal("normalized output aliases input storage")
|
||||
}
|
||||
}
|
||||
|
||||
func TestNormalizeRejectsInvalidCandidatesAndConflicts(t *testing.T) {
|
||||
doc := testDocument()
|
||||
valid := scene("one", 1, 1, dnd.SceneKindNarrative, "Arrival", "The party arrives.")
|
||||
for _, test := range []struct {
|
||||
name string
|
||||
input dnd.SceneDescriptionList
|
||||
}{
|
||||
{name: "nil list", input: dnd.SceneDescriptionList{}},
|
||||
{name: "empty list", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{}}},
|
||||
{name: "blank ID", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{{Kind: dnd.SceneKindNarrative, Title: "Arrival", Summary: "The party arrives.", SourceRef: valid.SourceRef}}}},
|
||||
{name: "invalid kind", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{{ID: "one", Kind: "other", Title: "Arrival", Summary: "The party arrives.", SourceRef: valid.SourceRef}}}},
|
||||
{name: "invalid range", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{{ID: "one", Kind: dnd.SceneKindNarrative, Title: "Arrival", Summary: "The party arrives.", SourceRef: source.SourceRef{SourceID: doc.ID, StartUnitID: 9, EndUnitID: 9}}}}},
|
||||
{name: "same ID conflict", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{valid, scene("one", 2, 2, dnd.SceneKindNarrative, "Departure", "The party leaves.")}}},
|
||||
{name: "same range conflict", input: dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{valid, scene("two", 1, 1, dnd.SceneKindCombat, "Ambush", "Bandits strike.")}}},
|
||||
} {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
if _, err := New(Options{}).Normalize(context.Background(), normalizeRequest(test.input, doc)); err == nil {
|
||||
t.Fatal("Normalize() error = nil, want rejection")
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestNormalizerContractAndCancellation(t *testing.T) {
|
||||
if _, err := DecodeOptions(nil); err != nil {
|
||||
t.Fatalf("DecodeOptions(nil) error = %v", err)
|
||||
}
|
||||
if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
|
||||
t.Fatal("DecodeOptions() accepted unknown options")
|
||||
}
|
||||
want := pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageNormalize, Requires: []string{"merged"}, Provides: []string{"normalized"}, ArtifactKind: dnd.SceneDescriptionListKind}
|
||||
if got := ModuleSpec(); !reflect.DeepEqual(got, want) {
|
||||
t.Fatalf("ModuleSpec() = %#v, want %#v", got, want)
|
||||
}
|
||||
registry := pipeline.NewNormalizerRegistry()
|
||||
if err := Register(registry); err != nil {
|
||||
t.Fatalf("Register() error = %v", err)
|
||||
}
|
||||
normalizer := New(Options{})
|
||||
if metadata := normalizer.ManifestMetadata(); metadata["normalizer_policy"] != normalizerPolicy {
|
||||
t.Fatalf("metadata = %#v", metadata)
|
||||
}
|
||||
if got, want := normalizer.CheckpointFingerprints(), []pipeline.CheckpointFingerprint{{Name: "normalizer_policy", Value: normalizerPolicy}}; !reflect.DeepEqual(got, want) {
|
||||
t.Fatalf("fingerprints = %#v, want %#v", got, want)
|
||||
}
|
||||
canceled, cancel := context.WithCancel(context.Background())
|
||||
cancel()
|
||||
if _, err := normalizer.Normalize(canceled, normalizeRequest(dnd.SceneDescriptionList{}, testDocument())); err == nil || !strings.Contains(err.Error(), "context") {
|
||||
t.Fatalf("canceled Normalize() error = %v", err)
|
||||
}
|
||||
if _, err := normalizer.Normalize(context.Background(), normalizeRequest(dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{scene("one", 1, 1, dnd.SceneKindNarrative, "Arrival", "The party arrives.")}}, nil)); err == nil || !strings.Contains(err.Error(), "source document") {
|
||||
t.Fatalf("nil source Normalize() error = %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func normalizeRequest(value dnd.SceneDescriptionList, doc *source.SourceDocument) contracts.TypedNormalizeRequest[dnd.SceneDescriptionList] {
|
||||
return contracts.TypedNormalizeRequest[dnd.SceneDescriptionList]{Source: doc, MergeOutput: contracts.MergeArtifact[dnd.SceneDescriptionList]{Value: value}}
|
||||
}
|
||||
|
||||
func testDocument() *source.SourceDocument {
|
||||
return &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Text: "Rules are discussed."}, {ID: 2, Text: "The party travels."}, {ID: 3, Text: "The party returns."}}}
|
||||
}
|
||||
|
||||
func scene(id string, start, end int, kind dnd.SceneKind, title, summary string) dnd.SceneDescription {
|
||||
return dnd.SceneDescription{ID: id, SourceRef: source.SourceRef{SourceID: "session", StartUnitID: start, EndUnitID: end}, Kind: kind, Title: title, Summary: summary}
|
||||
}
|
||||
|
||||
func cloneList(value dnd.SceneDescriptionList) dnd.SceneDescriptionList {
|
||||
if value.Scenes != nil {
|
||||
value.Scenes = append([]dnd.SceneDescription(nil), value.Scenes...)
|
||||
}
|
||||
return value
|
||||
}
|
||||
Reference in New Issue
Block a user