notarius/internal/modules/dnd/npcs/identity/identity.go

// Package identity owns the stable identity policy for D&D non-player
// characters.
package identity

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"strings"

	"golang.org/x/text/cases"
	"golang.org/x/text/unicode/norm"

	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
)

const (
	// Policy identifies the complete identity comparison and ID derivation
	// policy. A future semantic change must use a new value.
	Policy = "dnd.npcs.identity.v1"
	// IdentityPolicy is an explicit alias for callers recording policy
	// fingerprints.
	IdentityPolicy = Policy
)

const idPrefix = "npc:sha256:"

// IssueCode identifies one deterministic registry identity problem.
type IssueCode string

const (
	IssueEmptyCanonicalName      IssueCode = "empty_canonical_name"
	IssueEmptyAlias              IssueCode = "empty_alias"
	IssueInvalidID               IssueCode = "invalid_id"
	IssueIDMismatch              IssueCode = "id_mismatch"
	IssueDuplicateCanonical      IssueCode = "duplicate_canonical_identity"
	IssueDuplicateID             IssueCode = "duplicate_id"
	IssueDuplicateAlias          IssueCode = "duplicate_alias"
	IssueOwnCanonicalAlias       IssueCode = "alias_matches_canonical_name"
	IssueAliasCanonicalCollision IssueCode = "alias_canonical_collision"
	IssueAliasOwnershipCollision IssueCode = "alias_owned_by_multiple_records"
)

// Issue is an inspectable identity validation problem. AliasIndex is -1 when
// the issue applies to an NPC as a whole rather than a particular alias.
type Issue struct {
	Code        IssueCode
	RecordIndex int
	AliasIndex  int
	Value       string
}

// NormalizeDisplay trims and collapses Unicode whitespace while retaining all
// other observed spelling and punctuation.
func NormalizeDisplay(value string) string {
	return strings.Join(strings.Fields(value), " ")
}

// ComparisonKey returns the stable key used for NPC identity comparisons.
func ComparisonKey(value string) string {
	value = norm.NFKC.String(value)
	value = strings.Map(func(r rune) rune {
		switch r {
		case '\u2018', '\u2019', '\u02bc':
			return '\''
		default:
			return r
		}
	}, value)
	value = strings.Join(strings.Fields(value), " ")
	return cases.Fold().String(value)
}

// DeriveID returns the deterministic ID for a canonical NPC name. Empty
// identity keys intentionally produce an empty ID so shape validation can
// report the missing identity instead of manufacturing one.
func DeriveID(name string) string {
	key := ComparisonKey(name)
	if key == "" {
		return ""
	}
	digest := sha256.Sum256([]byte(key))
	return idPrefix + hex.EncodeToString(digest[:])
}

// IDFor is a concise alias for DeriveID for callers that work with IDs as
// values rather than derivation operations.
func IDFor(name string) string { return DeriveID(name) }

// IsValidID reports whether value has the exact durable NPC ID syntax.
func IsValidID(value string) bool {
	if len(value) != len(idPrefix)+sha256.Size*2 || !strings.HasPrefix(value, idPrefix) {
		return false
	}
	for _, r := range value[len(idPrefix):] {
		if !(r >= '0' && r <= '9') && !(r >= 'a' && r <= 'f') {
			return false
		}
	}
	return true
}

// ValidID is an alias for IsValidID.
func ValidID(value string) bool { return IsValidID(value) }

// ValidateRegistry checks all identity invariants without changing the input.
// It accepts the NPC slice used by typed pipeline artifacts. Use ValidateList
// when the enclosing NPCList is more convenient at the call site.
func ValidateRegistry(npcs []dnd.NPC) []Issue {
	type record struct {
		canonical string
		aliases   []string
	}

	records := make([]record, len(npcs))
	issues := make([]Issue, 0)
	canonicalOwners := make(map[string][]int)
	idOwners := make(map[string][]int)
	aliasOwners := make(map[string][]int)

	for recordIndex, npc := range npcs {
		canonical := ComparisonKey(npc.Name)
		records[recordIndex].canonical = canonical
		if canonical == "" {
			issues = append(issues, Issue{Code: IssueEmptyCanonicalName, RecordIndex: recordIndex, AliasIndex: -1, Value: npc.Name})
		} else {
			canonicalOwners[canonical] = append(canonicalOwners[canonical], recordIndex)
		}

		if !IsValidID(npc.ID) {
			issues = append(issues, Issue{Code: IssueInvalidID, RecordIndex: recordIndex, AliasIndex: -1, Value: npc.ID})
		} else if expected := DeriveID(npc.Name); npc.ID != expected {
			issues = append(issues, Issue{Code: IssueIDMismatch, RecordIndex: recordIndex, AliasIndex: -1, Value: npc.ID})
		}
		if npc.ID != "" {
			idOwners[npc.ID] = append(idOwners[npc.ID], recordIndex)
		}

		seenAliases := make(map[string]int, len(npc.Aliases))
		for aliasIndex, alias := range npc.Aliases {
			key := ComparisonKey(alias)
			records[recordIndex].aliases = append(records[recordIndex].aliases, key)
			if key == "" {
				issues = append(issues, Issue{Code: IssueEmptyAlias, RecordIndex: recordIndex, AliasIndex: aliasIndex, Value: alias})
				continue
			}
			if _, ok := seenAliases[key]; ok {
				issues = append(issues, Issue{Code: IssueDuplicateAlias, RecordIndex: recordIndex, AliasIndex: aliasIndex, Value: alias})
			} else {
				seenAliases[key] = aliasIndex
			}
			if key == canonical {
				issues = append(issues, Issue{Code: IssueOwnCanonicalAlias, RecordIndex: recordIndex, AliasIndex: aliasIndex, Value: alias})
			}
			aliasOwners[key] = append(aliasOwners[key], recordIndex)
		}
	}

	for recordIndex, record := range records {
		if record.canonical != "" && len(canonicalOwners[record.canonical]) > 1 && canonicalOwners[record.canonical][0] != recordIndex {
			issues = append(issues, Issue{Code: IssueDuplicateCanonical, RecordIndex: recordIndex, AliasIndex: -1, Value: npcs[recordIndex].Name})
		}
		if id := npcs[recordIndex].ID; id != "" && len(idOwners[id]) > 1 && idOwners[id][0] != recordIndex {
			issues = append(issues, Issue{Code: IssueDuplicateID, RecordIndex: recordIndex, AliasIndex: -1, Value: id})
		}
	}

	seenAliasKeys := make(map[string]struct{})
	for _, record := range records {
		for _, alias := range record.aliases {
			if alias == "" {
				continue
			}
			if _, alreadyProcessed := seenAliasKeys[alias]; alreadyProcessed {
				continue
			}
			seenAliasKeys[alias] = struct{}{}
			owners := uniqueIndexes(aliasOwners[alias])
			if len(owners) > 1 {
				for _, recordIndex := range owners {
					issues = append(issues, Issue{Code: IssueAliasOwnershipCollision, RecordIndex: recordIndex, AliasIndex: aliasIndexFor(records[recordIndex].aliases, alias), Value: alias})
				}
			}
			for _, recordIndex := range owners {
				for _, canonicalOwner := range canonicalOwners[alias] {
					if canonicalOwner != recordIndex {
						issues = append(issues, Issue{Code: IssueAliasCanonicalCollision, RecordIndex: recordIndex, AliasIndex: aliasIndexFor(records[recordIndex].aliases, alias), Value: alias})
						break
					}
				}
			}
		}
	}

	return issues
}

// ValidateList validates the identity members of list.
func ValidateList(list dnd.NPCList) []Issue { return ValidateRegistry(list.NPCs) }

// Validate is a convenience alias for ValidateList.
func Validate(list dnd.NPCList) []Issue { return ValidateList(list) }

func uniqueIndexes(values []int) []int {
	seen := make(map[int]struct{}, len(values))
	unique := make([]int, 0, len(values))
	for _, value := range values {
		if _, ok := seen[value]; ok {
			continue
		}
		seen[value] = struct{}{}
		unique = append(unique, value)
	}
	return unique
}

func aliasIndexFor(aliases []string, key string) int {
	for index, alias := range aliases {
		if alias == key {
			return index
		}
	}
	return -1
}

// Error makes an issue useful in simple callers while preserving its
// structured fields for aggregate diagnostics.
func (i Issue) Error() string {
	return fmt.Sprintf("%s at record %d", i.Code, i.RecordIndex)
}