Update D&D schemas to require integer unit_id values

internal/modules/sharedassets/dnd/unit_refs.go

@@ -0,0 +1,133 @@
+package dnd
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+)
+
+type UnitRef struct {
+	value      string
+	fromNumber bool
+	number     int
+}
+
+type SourceRefResponse struct {
+	SourceID    string  `json:"source_id"`
+	StartUnitID UnitRef `json:"start_unit_id"`
+	EndUnitID   UnitRef `json:"end_unit_id"`
+}
+
+func UnitRefFromString(value string) UnitRef {
+	return UnitRef{value: value}
+}
+
+func UnitRefFromInt(value int) UnitRef {
+	return UnitRef{
+		value:      strconv.Itoa(value),
+		fromNumber: true,
+		number:     value,
+	}
+}
+
+func (ref UnitRef) String() string {
+	return ref.value
+}
+
+func (ref *UnitRef) UnmarshalJSON(raw []byte) error {
+	raw = bytes.TrimSpace(raw)
+	if len(raw) == 0 {
+		return fmt.Errorf("unit ref must be a string or integer")
+	}
+	if raw[0] == '"' {
+		var value string
+		if err := json.Unmarshal(raw, &value); err != nil {
+			return err
+		}
+		*ref = UnitRefFromString(value)
+		return nil
+	}
+
+	number, err := strconv.Atoi(string(raw))
+	if err != nil {
+		return fmt.Errorf("unit ref must be a string or integer")
+	}
+	*ref = UnitRefFromInt(number)
+	return nil
+}
+
+func (ref UnitRef) MarshalJSON() ([]byte, error) {
+	if ref.fromNumber {
+		return []byte(strconv.Itoa(ref.number)), nil
+	}
+	return json.Marshal(ref.value)
+}
+
+func ResolveUnitID(doc *source.SourceDocument, field string, ref UnitRef) (string, error) {
+	value := strings.TrimSpace(ref.value)
+	if value == "" {
+		return "", fmt.Errorf("%s must not be empty", field)
+	}
+	if id, ok := canonicalUnitID(doc, value); ok {
+		return id, nil
+	}
+	if number, ok := unitNumber(value); ok {
+		if id, ok := unitIDByNumber(doc, number); ok {
+			return id, nil
+		}
+		return "", fmt.Errorf("%s %d was not found as a source-unit ID or 1-based unit number", field, number)
+	}
+	return "", fmt.Errorf("%s %q was not found", field, value)
+}
+
+func SourceRefCandidate(doc *source.SourceDocument, ref SourceRefResponse) source.SourceRef {
+	return source.SourceRef{
+		SourceID:    strings.TrimSpace(ref.SourceID),
+		StartUnitID: unitIDCandidate(doc, ref.StartUnitID),
+		EndUnitID:   unitIDCandidate(doc, ref.EndUnitID),
+	}
+}
+
+func unitIDCandidate(doc *source.SourceDocument, ref UnitRef) string {
+	value := strings.TrimSpace(ref.value)
+	if id, ok := canonicalUnitID(doc, value); ok {
+		return id
+	}
+	if number, ok := unitNumber(value); ok {
+		if id, ok := unitIDByNumber(doc, number); ok {
+			return id
+		}
+	}
+	return value
+}
+
+func canonicalUnitID(doc *source.SourceDocument, value string) (string, bool) {
+	if doc == nil {
+		return "", false
+	}
+	for _, unit := range doc.Units {
+		if unit.ID == value {
+			return unit.ID, true
+		}
+	}
+	return "", false
+}
+
+func unitIDByNumber(doc *source.SourceDocument, number int) (string, bool) {
+	if doc == nil || number < 1 || number > len(doc.Units) {
+		return "", false
+	}
+	return doc.Units[number-1].ID, true
+}
+
+func unitNumber(value string) (int, bool) {
+	number, err := strconv.Atoi(value)
+	if err != nil {
+		return 0, false
+	}
+	return number, true
+}

internal/modules/sharedassets/dnd/unit_refs_test.go

@@ -0,0 +1,117 @@
+package dnd
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+)
+
+func TestUnitRefUnmarshalAcceptsIntegerAndString(t *testing.T) {
+	var integerRef UnitRef
+	if err := json.Unmarshal([]byte(`12`), &integerRef); err != nil {
+		t.Fatalf("Unmarshal(integer) error = %v, want nil", err)
+	}
+	if got := integerRef.String(); got != "12" {
+		t.Fatalf("integer ref = %q, want 12", got)
+	}
+
+	var stringRef UnitRef
+	if err := json.Unmarshal([]byte(`"seg-001"`), &stringRef); err != nil {
+		t.Fatalf("Unmarshal(string) error = %v, want nil", err)
+	}
+	if got := stringRef.String(); got != "seg-001" {
+		t.Fatalf("string ref = %q, want seg-001", got)
+	}
+}
+
+func TestUnitRefUnmarshalRejectsNonIntegerTypes(t *testing.T) {
+	for _, raw := range []string{`true`, `null`, `1.5`, `{}`} {
+		t.Run(raw, func(t *testing.T) {
+			var ref UnitRef
+			err := json.Unmarshal([]byte(raw), &ref)
+			if err == nil {
+				t.Fatal("Unmarshal() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), "string or integer") {
+				t.Fatalf("Unmarshal() error = %q, want type context", err.Error())
+			}
+		})
+	}
+}
+
+func TestResolveUnitIDPrefersExactSourceUnitID(t *testing.T) {
+	doc := unitRefSourceDocument("2", "10")
+
+	got, err := ResolveUnitID(doc, "start_unit_id", UnitRefFromInt(2))
+	if err != nil {
+		t.Fatalf("ResolveUnitID() error = %v, want nil", err)
+	}
+	if got != "2" {
+		t.Fatalf("ResolveUnitID() = %q, want exact source unit ID", got)
+	}
+}
+
+func TestResolveUnitIDFallsBackToOneBasedUnitNumber(t *testing.T) {
+	doc := unitRefSourceDocument("seg-001", "seg-002")
+
+	got, err := ResolveUnitID(doc, "end_unit_id", UnitRefFromInt(2))
+	if err != nil {
+		t.Fatalf("ResolveUnitID() error = %v, want nil", err)
+	}
+	if got != "seg-002" {
+		t.Fatalf("ResolveUnitID() = %q, want second source unit ID", got)
+	}
+}
+
+func TestResolveUnitIDRejectsMissingUnit(t *testing.T) {
+	doc := unitRefSourceDocument("seg-001")
+
+	_, err := ResolveUnitID(doc, "start_unit_id", UnitRefFromInt(9))
+	if err == nil {
+		t.Fatal("ResolveUnitID() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "start_unit_id 9") {
+		t.Fatalf("ResolveUnitID() error = %q, want field and value context", err.Error())
+	}
+}
+
+func TestSourceRefCandidateCanonicalizesValidRefsAndPreservesInvalidRefs(t *testing.T) {
+	doc := unitRefSourceDocument("seg-001", "seg-002")
+
+	valid := SourceRefCandidate(doc, SourceRefResponse{
+		SourceID:    " session-alpha ",
+		StartUnitID: UnitRefFromInt(1),
+		EndUnitID:   UnitRefFromInt(2),
+	})
+	if valid != (source.SourceRef{SourceID: "session-alpha", StartUnitID: "seg-001", EndUnitID: "seg-002"}) {
+		t.Fatalf("valid candidate = %#v, want canonical source ref", valid)
+	}
+
+	invalid := SourceRefCandidate(doc, SourceRefResponse{
+		SourceID:    "session-alpha",
+		StartUnitID: UnitRefFromInt(9),
+		EndUnitID:   UnitRefFromString("missing"),
+	})
+	if invalid != (source.SourceRef{SourceID: "session-alpha", StartUnitID: "9", EndUnitID: "missing"}) {
+		t.Fatalf("invalid candidate = %#v, want unresolved values for validator", invalid)
+	}
+}
+
+func unitRefSourceDocument(ids ...string) *source.SourceDocument {
+	doc := &source.SourceDocument{
+		ID:     "session-alpha",
+		Kind:   "transcript",
+		Format: "application/json",
+		Digest: "sha256:test",
+	}
+	for _, id := range ids {
+		doc.Units = append(doc.Units, source.SourceUnit{
+			ID:   id,
+			Kind: "transcript_segment",
+			Text: "text",
+		})
+	}
+	return doc
+}