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"
	"encoding/json"
	"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.npc_registry.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"
	IssueInvalidID          IssueCode = "invalid_id"
	IssueIDMismatch         IssueCode = "id_mismatch"
	IssueDuplicateCanonical IssueCode = "duplicate_canonical_identity"
	IssueDuplicateID        IssueCode = "duplicate_id"
)

// Issue is an inspectable identity validation problem.
type Issue struct {
	Code        IssueCode
	RecordIndex 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 ""
	}
	identity, err := json.Marshal([]string{Policy, key})
	if err != nil {
		return ""
	}
	digest := sha256.Sum256(identity)
	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 NPCRegistry is more convenient at the call site.
func ValidateRegistry(npcs []dnd.NPC) []Issue {
	issues := make([]Issue, 0)
	canonicalOwners := make(map[string][]int)
	idOwners := make(map[string][]int)

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

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

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

	return issues
}

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

// 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)
}