Improve item occurrence holder corrections

internal/modules/dnd/validate/itemoccurrences/shape/validator_test.go

@@ -2,6 +2,7 @@ package shape
 
 import (
 	"context"
+	"fmt"
 	"reflect"
 	"strings"
 	"testing"
@@ -68,16 +69,94 @@ func TestValidatorRejectsOwnedSemanticBoundaries(t *testing.T) {
 	}
 }
 
+func TestValidatorProvidesActionableContextualHolderGuidance(t *testing.T) {
+	tests := []struct {
+		name         string
+		occurrence   dnd.ItemOccurrence
+		wantGuidance []string
+	}{
+		{
+			name:         "discovered",
+			occurrence:   dnd.ItemOccurrence{ItemID: "item:sha256:opaque", Name: "Ring", Kind: dnd.ItemOccurrenceKindDiscovered, From: "Aria", SourceRefs: refs(1, 2)},
+			wantGuidance: []string{"For `discovered` occurrences", "both `from` and `to` to JSON null"},
+		},
+		{
+			name:         "acquired",
+			occurrence:   dnd.ItemOccurrence{ItemID: "item:sha256:opaque", Name: "Ring", Kind: dnd.ItemOccurrenceKindAcquired, From: "Merchant", To: "party", SourceRefs: refs(1, 2)},
+			wantGuidance: []string{"For `acquired` occurrences", "`from` to JSON null", "named party member gaining possession"},
+		},
+		{
+			name:         "lost",
+			occurrence:   dnd.ItemOccurrence{ItemID: "item:sha256:opaque", Name: "Ring", Kind: dnd.ItemOccurrenceKindLost, From: "party", To: "Merchant", SourceRefs: refs(1, 2)},
+			wantGuidance: []string{"For `lost` occurrences", "named party member losing possession", "`to` to JSON null"},
+		},
+		{
+			name:         "consumed",
+			occurrence:   dnd.ItemOccurrence{ItemID: "item:sha256:opaque", Name: "Ring", Kind: dnd.ItemOccurrenceKindConsumed, SourceRefs: refs(1, 2)},
+			wantGuidance: []string{"For `consumed` occurrences", "named party member consuming the item", "`to` to JSON null"},
+		},
+		{
+			name:         "transferred",
+			occurrence:   dnd.ItemOccurrence{ItemID: "item:sha256:opaque", Name: "Ring", Kind: dnd.ItemOccurrenceKindTransferred, From: "party", To: "Borin", SourceRefs: refs(1, 2)},
+			wantGuidance: []string{"For `transferred` occurrences", "two distinct named party members", "never use `party`"},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.ItemOccurrenceList]{Value: listWith(test.occurrence)})
+			if err != nil || result.Approved {
+				t.Fatalf("Validate() = %#v, %v; want rejection", result, err)
+			}
+			for _, fragment := range append(test.wantGuidance, "item \"Ring\"", "source units 1-2") {
+				if !strings.Contains(result.CorrectionGuidance, fragment) {
+					t.Fatalf("CorrectionGuidance = %q, want %q", result.CorrectionGuidance, fragment)
+				}
+			}
+			for _, forbidden := range []string{test.occurrence.ItemID, "sha256", Key, ReasonCode, "occurrences[0]"} {
+				if strings.Contains(result.CorrectionGuidance, forbidden) {
+					t.Fatalf("CorrectionGuidance leaked implementation identifier %q: %q", forbidden, result.CorrectionGuidance)
+				}
+			}
+			if !strings.Contains(result.Message, "expected") || !strings.Contains(result.Message, "got from") {
+				t.Fatalf("operator message = %q, want expected and observed holders", result.Message)
+			}
+		})
+	}
+}
+
+func TestValidatorGroupsRepeatedHolderCorrectionsAndRetainsDistinctRules(t *testing.T) {
+	value := dnd.ItemOccurrenceList{Occurrences: []dnd.ItemOccurrence{
+		{ItemID: "item-1", Name: "Silver Pieces", Kind: dnd.ItemOccurrenceKindAcquired, From: "Orc", To: "party", SourceRefs: refs(1, 1)},
+		{ItemID: "item-2", Name: "Torch", Kind: dnd.ItemOccurrenceKindAcquired, From: "Chest", To: "Aria", SourceRefs: refs(2, 2)},
+		{ItemID: "item-3", Name: "Potion", Kind: dnd.ItemOccurrenceKindConsumed, SourceRefs: refs(3, 3)},
+	}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.ItemOccurrenceList]{Value: value})
+	if err != nil || result.Approved {
+		t.Fatalf("Validate() = %#v, %v; want rejection", result, err)
+	}
+	if strings.Count(result.CorrectionGuidance, "For `acquired` occurrences") != 1 || strings.Count(result.CorrectionGuidance, "For `consumed` occurrences") != 1 {
+		t.Fatalf("CorrectionGuidance = %q, want one rule per affected kind", result.CorrectionGuidance)
+	}
+	for _, fragment := range []string{"item \"Silver Pieces\"", "source unit 1", "item \"Torch\"", "source unit 2", "item \"Potion\"", "source unit 3"} {
+		if !strings.Contains(result.CorrectionGuidance, fragment) {
+			t.Fatalf("CorrectionGuidance = %q, want contextual fragment %q", result.CorrectionGuidance, fragment)
+		}
+	}
+}
+
 func TestValidatorAggregatesBoundedIndexedDiagnosticsAndRegistration(t *testing.T) {
 	value := dnd.ItemOccurrenceList{Occurrences: make([]dnd.ItemOccurrence, 24)}
 	for index := range value.Occurrences {
-		value.Occurrences[index] = dnd.ItemOccurrence{ItemID: "item", Name: " \n", Kind: "unsupported"}
+		value.Occurrences[index] = dnd.ItemOccurrence{ItemID: "item", Name: fmt.Sprintf("Item %d", index), Kind: "unsupported"}
 	}
 	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.ItemOccurrenceList]{Value: value})
 	if err != nil || result.Approved || result.ReasonCode != ReasonCode || len([]byte(result.Message)) > 4096 || !utf8.ValidString(result.Message) || !strings.Contains(result.Message, "occurrences[0]") || !strings.Contains(result.Message, "additional issue(s) omitted") {
 		t.Fatalf("Validate() = %#v, %v", result, err)
 	}
-	if value.Occurrences[0].Name != " \n" {
+	if len([]byte(result.CorrectionGuidance)) > 4096 || !utf8.ValidString(result.CorrectionGuidance) || !strings.Contains(result.CorrectionGuidance, "additional issue(s) omitted") {
+		t.Fatalf("CorrectionGuidance = %q, want bounded aggregate", result.CorrectionGuidance)
+	}
+	if value.Occurrences[0].Name != "Item 0" {
 		t.Fatal("Validate() mutated input")
 	}
 	if got := New(Options{}).CheckpointFingerprints(); !reflect.DeepEqual(got, []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}) {