diff --git a/internal/modules/dnd/codec/scenedescriptions/assets/schemas/dnd_scene_descriptions.v1.json b/internal/modules/dnd/codec/scenedescriptions/assets/schemas/dnd_scene_descriptions.v1.json new file mode 100644 index 0000000..2490142 --- /dev/null +++ b/internal/modules/dnd/codec/scenedescriptions/assets/schemas/dnd_scene_descriptions.v1.json @@ -0,0 +1,54 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "notarius.dnd.scene_descriptions", + "type": "object", + "additionalProperties": false, + "required": ["scenes"], + "properties": { + "scenes": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["id", "source_ref", "kind", "title", "summary"], + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source_ref": { + "type": "object", + "additionalProperties": false, + "required": ["source_id", "start_unit_id", "end_unit_id"], + "properties": { + "source_id": { + "type": "string", + "minLength": 1 + }, + "start_unit_id": { + "type": "integer", + "minimum": 1 + }, + "end_unit_id": { + "type": "integer", + "minimum": 1 + } + } + }, + "kind": { + "type": "string", + "enum": ["combat", "narrative", "recap", "meta"] + }, + "title": { + "type": "string", + "minLength": 1 + }, + "summary": { + "type": "string", + "minLength": 1 + } + } + } + } + } +} diff --git a/internal/modules/dnd/codec/scenedescriptions/codec.go b/internal/modules/dnd/codec/scenedescriptions/codec.go new file mode 100644 index 0000000..1f52fbf --- /dev/null +++ b/internal/modules/dnd/codec/scenedescriptions/codec.go @@ -0,0 +1,134 @@ +package scenedescriptions + +import ( + "bytes" + "embed" + "encoding/json" + "fmt" + "io" + "strings" + + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" +) + +const ( + SchemaID = "notarius.dnd.scene_descriptions" + SchemaName = "notarius_dnd_scene_descriptions_v1" + SchemaVersion = "v1" + MediaType = "application/json" +) + +//go:embed assets/schemas/dnd_scene_descriptions.v1.json +var schemaAssets embed.FS + +var _ contracts.ArtifactCodec[dnd.SceneDescriptionList] = (*Codec)(nil) + +type Codec struct{} + +func New() *Codec { return &Codec{} } + +func (c *Codec) Kind() contracts.ArtifactKind { return dnd.SceneDescriptionListKind } + +func (c *Codec) Schema() contracts.ArtifactSchema { + raw, err := schemaAssets.ReadFile("assets/schemas/dnd_scene_descriptions.v1.json") + if err != nil { + return contracts.ArtifactSchema{} + } + return contracts.ArtifactSchema{ + ID: SchemaID, + Name: SchemaName, + Version: SchemaVersion, + JSONSchema: append([]byte(nil), raw...), + } +} + +func (c *Codec) MediaType() string { return MediaType } + +func (c *Codec) Metadata(value dnd.SceneDescriptionList) map[string]any { + return map[string]any{"scene_count": len(value.Scenes)} +} + +func (c *Codec) Encode(value dnd.SceneDescriptionList) ([]byte, error) { + if err := validate(value); err != nil { + return nil, fmt.Errorf("encode dnd scene description list: %w", err) + } + return c.EncodeCandidate(value) +} + +// EncodeCandidate provides the durable representation before typed validators +// have approved a value. +func (c *Codec) EncodeCandidate(value dnd.SceneDescriptionList) ([]byte, error) { + content, err := json.Marshal(value) + if err != nil { + return nil, fmt.Errorf("encode dnd scene description list: %w", err) + } + return content, nil +} + +func (c *Codec) Decode(content []byte) (dnd.SceneDescriptionList, error) { + value, err := c.DecodeCandidate(content) + if err != nil { + return dnd.SceneDescriptionList{}, err + } + if err := validate(value); err != nil { + return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: %w", err) + } + return value, nil +} + +// DecodeCandidate reads one strict durable JSON value before typed validators +// have approved it. +func (c *Codec) DecodeCandidate(content []byte) (dnd.SceneDescriptionList, error) { + decoder := json.NewDecoder(bytes.NewReader(content)) + decoder.DisallowUnknownFields() + var value dnd.SceneDescriptionList + if err := decoder.Decode(&value); err != nil { + return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: %w", err) + } + var trailing any + if err := decoder.Decode(&trailing); err != io.EOF { + return dnd.SceneDescriptionList{}, fmt.Errorf("decode dnd scene description list: multiple JSON values") + } + return value, nil +} + +func validate(value dnd.SceneDescriptionList) error { + if value.Scenes == nil { + return fmt.Errorf("scenes must be present") + } + for index, scene := range value.Scenes { + prefix := fmt.Sprintf("scenes[%d]", index) + if strings.TrimSpace(scene.ID) == "" { + return fmt.Errorf("%s.id must not be empty", prefix) + } + if !validSceneKind(scene.Kind) { + return fmt.Errorf("%s.kind must be supported", prefix) + } + if strings.TrimSpace(scene.Title) == "" { + return fmt.Errorf("%s.title must not be empty", prefix) + } + if strings.TrimSpace(scene.Summary) == "" { + return fmt.Errorf("%s.summary must not be empty", prefix) + } + if strings.TrimSpace(scene.SourceRef.SourceID) == "" { + return fmt.Errorf("%s.source_ref.source_id must not be empty", prefix) + } + if scene.SourceRef.StartUnitID <= 0 { + return fmt.Errorf("%s.source_ref.start_unit_id must be positive", prefix) + } + if scene.SourceRef.EndUnitID <= 0 { + return fmt.Errorf("%s.source_ref.end_unit_id must be positive", prefix) + } + } + return nil +} + +func validSceneKind(value dnd.SceneKind) bool { + switch value { + case dnd.SceneKindCombat, dnd.SceneKindNarrative, dnd.SceneKindRecap, dnd.SceneKindMeta: + return true + default: + return false + } +} diff --git a/internal/modules/dnd/codec/scenedescriptions/codec_test.go b/internal/modules/dnd/codec/scenedescriptions/codec_test.go new file mode 100644 index 0000000..22735ec --- /dev/null +++ b/internal/modules/dnd/codec/scenedescriptions/codec_test.go @@ -0,0 +1,161 @@ +package scenedescriptions + +import ( + "bytes" + "encoding/json" + "os" + "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 validList() dnd.SceneDescriptionList { + return dnd.SceneDescriptionList{Scenes: []dnd.SceneDescription{{ + ID: "chunk-000001", + SourceRef: source.SourceRef{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 2}, + Kind: dnd.SceneKindNarrative, + Title: "At the city gate", + Summary: "The party enters the city after speaking with its guard.", + }}} +} + +func TestCodecMatchesMaintainedDurableFixture(t *testing.T) { + raw, err := os.ReadFile("testdata/dnd_scene_descriptions.v1.json") + if err != nil { + t.Fatal(err) + } + codec := New() + value, err := codec.Decode(raw) + if err != nil { + t.Fatalf("Decode() error = %v", err) + } + if want := validList(); !reflect.DeepEqual(value, want) { + t.Fatalf("Decode() = %#v, want %#v", value, want) + } + encoded, err := codec.Encode(value) + if err != nil { + t.Fatalf("Encode() error = %v", err) + } + var compact bytes.Buffer + if err := json.Compact(&compact, raw); err != nil { + t.Fatal(err) + } + if !bytes.Equal(encoded, compact.Bytes()) { + t.Fatalf("Encode() = %s, want %s", encoded, compact.Bytes()) + } +} + +func TestCodecOwnsDurableSchemaAndMetadata(t *testing.T) { + codec := New() + schema := codec.Schema() + if codec.Kind() != dnd.SceneDescriptionListKind || codec.MediaType() != MediaType { + t.Fatalf("codec identity = %q/%q", codec.Kind(), codec.MediaType()) + } + if schema.ID != SchemaID || schema.Name != SchemaName || schema.Version != SchemaVersion || !json.Valid(schema.JSONSchema) { + t.Fatalf("schema = %#v", schema) + } + registry := pipeline.NewArtifactCodecRegistry() + if err := pipeline.RegisterArtifactCodec(registry, codec); err != nil { + t.Fatal(err) + } + spec, ok := registry.Spec(dnd.SceneDescriptionListKind) + if !ok || spec.SchemaDigest != contracts.DigestArtifactSchema(schema) { + t.Fatalf("registered spec = %#v, %t", spec, ok) + } + schema.JSONSchema[0] = '[' + if next := codec.Schema(); !json.Valid(next.JSONSchema) || next.JSONSchema[0] == '[' { + t.Fatal("Schema() returned shared bytes") + } + metadata := codec.Metadata(validList()) + metadata["other"] = true + if next := codec.Metadata(validList()); len(next) != 1 || next["scene_count"] != 1 { + t.Fatalf("Metadata() = %#v", next) + } + encoded, err := codec.Encode(validList()) + if err != nil { + t.Fatal(err) + } + encoded[0] = '[' + if next, err := codec.Encode(validList()); err != nil || !json.Valid(next) || next[0] == '[' { + t.Fatalf("Encode() returned shared bytes: %s, %v", next, err) + } +} + +func TestCodecStrictlyRejectsInvalidDurableBoundaries(t *testing.T) { + validJSON := `{"scenes":[{"id":"chunk-000001","source_ref":{"source_id":"session","start_unit_id":1,"end_unit_id":1},"kind":"narrative","title":"Arrival","summary":"The party arrives."}]}` + tests := []struct{ name, raw, want string }{ + {"malformed", `{`, "decode dnd scene description list"}, + {"unknown top-level", `{"scenes":[],"unexpected":true}`, "unknown field"}, + {"unknown scene field", strings.Replace(validJSON, `"kind":"narrative"`, `"kind":"narrative","unexpected":true`, 1), "unknown field"}, + {"unknown source field", strings.Replace(validJSON, `"end_unit_id":1`, `"end_unit_id":1,"unexpected":true`, 1), "unknown field"}, + {"trailing", `{"scenes":[]} {}`, "multiple JSON values"}, + {"missing scenes", `{}`, "scenes must be present"}, + {"invalid kind", strings.Replace(validJSON, `"kind":"narrative"`, `"kind":"other"`, 1), "kind must be supported"}, + {"blank title", strings.Replace(validJSON, `"title":"Arrival"`, `"title":" "`, 1), "title must not be empty"}, + {"blank summary", strings.Replace(validJSON, `"summary":"The party arrives."`, `"summary":" "`, 1), "summary must not be empty"}, + {"blank ID", strings.Replace(validJSON, `"id":"chunk-000001"`, `"id":" "`, 1), "id must not be empty"}, + {"blank source ID", strings.Replace(validJSON, `"source_id":"session"`, `"source_id":" "`, 1), "source_id must not be empty"}, + {"invalid source start", strings.Replace(validJSON, `"start_unit_id":1`, `"start_unit_id":0`, 1), "start_unit_id must be positive"}, + {"invalid source end", strings.Replace(validJSON, `"end_unit_id":1`, `"end_unit_id":0`, 1), "end_unit_id must be positive"}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + if _, err := New().Decode([]byte(test.raw)); err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("Decode() error = %v, want %q", err, test.want) + } + }) + } +} + +func TestCodecCandidatePreservesValidatorOwnedValues(t *testing.T) { + candidates := []dnd.SceneDescriptionList{ + {}, + {Scenes: []dnd.SceneDescription{}}, + {Scenes: []dnd.SceneDescription{{ID: " ", Kind: "unsupported", Title: " ", Summary: " ", SourceRef: source.SourceRef{}}}}, + {Scenes: []dnd.SceneDescription{{ID: " ", Kind: "unsupported", Title: " ", Summary: " ", SourceRef: source.SourceRef{StartUnitID: 0, EndUnitID: -1}}}}, + } + for _, candidate := range candidates { + content, err := New().EncodeCandidate(candidate) + if err != nil || !json.Valid(content) { + t.Fatalf("EncodeCandidate() = %s, %v", content, err) + } + decoded, err := New().DecodeCandidate(content) + if err != nil || !reflect.DeepEqual(decoded, candidate) { + t.Fatalf("DecodeCandidate() = %#v, %v; want %#v", decoded, err, candidate) + } + } +} + +func TestCodecRejectsRequiredApprovedValues(t *testing.T) { + tests := []struct { + name string + value dnd.SceneDescriptionList + want string + }{ + {"nil scenes", dnd.SceneDescriptionList{}, "scenes must be present"}, + {"empty ID", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].ID = " " }), "id must not be empty"}, + {"unsupported kind", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Kind = "unsupported" }), "kind must be supported"}, + {"empty title", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Title = " " }), "title must not be empty"}, + {"empty summary", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].Summary = " " }), "summary must not be empty"}, + {"empty source ID", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.SourceID = " " }), "source_id must not be empty"}, + {"non-positive start", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.StartUnitID = 0 }), "start_unit_id must be positive"}, + {"non-positive end", mutate(validList(), func(value *dnd.SceneDescriptionList) { value.Scenes[0].SourceRef.EndUnitID = 0 }), "end_unit_id must be positive"}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + if _, err := New().Encode(test.value); err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("Encode() error = %v, want %q", err, test.want) + } + }) + } +} + +func mutate(value dnd.SceneDescriptionList, change func(*dnd.SceneDescriptionList)) dnd.SceneDescriptionList { + change(&value) + return value +} diff --git a/internal/modules/dnd/codec/scenedescriptions/testdata/dnd_scene_descriptions.v1.json b/internal/modules/dnd/codec/scenedescriptions/testdata/dnd_scene_descriptions.v1.json new file mode 100644 index 0000000..52e8158 --- /dev/null +++ b/internal/modules/dnd/codec/scenedescriptions/testdata/dnd_scene_descriptions.v1.json @@ -0,0 +1 @@ +{"scenes":[{"id":"chunk-000001","source_ref":{"source_id":"session-alpha","start_unit_id":1,"end_unit_id":2},"kind":"narrative","title":"At the city gate","summary":"The party enters the city after speaking with its guard."}]} diff --git a/internal/modules/dnd/types.go b/internal/modules/dnd/types.go index 4b9883a..f03238e 100644 --- a/internal/modules/dnd/types.go +++ b/internal/modules/dnd/types.go @@ -14,6 +14,8 @@ const CombatTurnListKind contracts.ArtifactKind = "dnd/combat-turn-list" const NPCInteractionListKind contracts.ArtifactKind = "dnd/npc-interaction-list" +const SceneDescriptionListKind contracts.ArtifactKind = "dnd/scene-description-list" + type SpellList struct { SpellCasts []SpellCast `json:"spell_casts"` } @@ -74,3 +76,24 @@ type NPCInteraction struct { Kind NPCInteractionKind `json:"kind"` SourceRefs []source.SourceRef `json:"source_refs"` } + +type SceneKind string + +const ( + SceneKindCombat SceneKind = "combat" + SceneKindNarrative SceneKind = "narrative" + SceneKindRecap SceneKind = "recap" + SceneKindMeta SceneKind = "meta" +) + +type SceneDescriptionList struct { + Scenes []SceneDescription `json:"scenes"` +} + +type SceneDescription struct { + ID string `json:"id"` + SourceRef source.SourceRef `json:"source_ref"` + Kind SceneKind `json:"kind"` + Title string `json:"title"` + Summary string `json:"summary"` +}