notarius/internal/framework/pipeline/module.go

package pipeline

import (
	"fmt"
	"sort"
	"strings"

	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
)

type ModuleStage string

const (
	StageInput     ModuleStage = "input"
	StageChunk     ModuleStage = "chunk"
	StageExtract   ModuleStage = "extract"
	StageMerge     ModuleStage = "merge"
	StageNormalize ModuleStage = "normalize"
	StageValidate  ModuleStage = "validate"
	StageOutput    ModuleStage = "output"
)

type ModuleSpec struct {
	Key            string
	Stage          ModuleStage
	Provides       []string
	Requires       []string
	ReferenceSlots []contracts.ReferenceSlot
}

func defaultModuleSpec(key string, stage ModuleStage) ModuleSpec {
	return ModuleSpec{
		Key:   key,
		Stage: stage,
	}
}

func normalizeModuleSpec(spec ModuleSpec) ModuleSpec {
	return ModuleSpec{
		Key:            strings.TrimSpace(spec.Key),
		Stage:          spec.Stage,
		Provides:       normalizeCapabilities(spec.Provides),
		Requires:       normalizeCapabilities(spec.Requires),
		ReferenceSlots: normalizeReferenceSlots(spec.ReferenceSlots),
	}
}

func normalizeCapabilities(values []string) []string {
	if len(values) == 0 {
		return nil
	}

	seen := make(map[string]struct{}, len(values))
	for _, value := range values {
		normalized := strings.TrimSpace(value)
		if normalized == "" {
			continue
		}
		seen[normalized] = struct{}{}
	}
	if len(seen) == 0 {
		return nil
	}

	capabilities := make([]string, 0, len(seen))
	for value := range seen {
		capabilities = append(capabilities, value)
	}
	sort.Strings(capabilities)
	return capabilities
}

func cloneModuleSpec(spec ModuleSpec) ModuleSpec {
	return ModuleSpec{
		Key:            spec.Key,
		Stage:          spec.Stage,
		Provides:       append([]string(nil), spec.Provides...),
		Requires:       append([]string(nil), spec.Requires...),
		ReferenceSlots: cloneReferenceSlots(spec.ReferenceSlots),
	}
}

func validateModuleSpec(kind string, expectedStage ModuleStage, spec ModuleSpec) error {
	if spec.Key == "" {
		return fmt.Errorf("%s key must not be empty", kind)
	}
	if spec.Stage != expectedStage {
		return fmt.Errorf("%s %q must use %q stage, got %q", kind, spec.Key, expectedStage, spec.Stage)
	}
	if !referenceSlotStage(spec.Stage) && len(spec.ReferenceSlots) > 0 {
		return fmt.Errorf("%s %q must not declare reference slots", kind, spec.Key)
	}
	if err := validateReferenceSlots(spec.ReferenceSlots); err != nil {
		return fmt.Errorf("%s %q reference slots: %w", kind, spec.Key, err)
	}
	return nil
}

func referenceSlotStage(stage ModuleStage) bool {
	return stage == StageChunk || stage == StageExtract || stage == StageNormalize
}

func sortedRegistryKeys[C any](constructors map[string]C) []string {
	if len(constructors) == 0 {
		return nil
	}

	keys := make([]string, 0, len(constructors))
	for key := range constructors {
		keys = append(keys, key)
	}
	sort.Strings(keys)
	return keys
}

func normalizeReferenceSlots(slots []contracts.ReferenceSlot) []contracts.ReferenceSlot {
	if len(slots) == 0 {
		return nil
	}

	normalized := make([]contracts.ReferenceSlot, 0, len(slots))
	for _, slot := range slots {
		slot.Name = strings.TrimSpace(slot.Name)
		slot.Description = strings.TrimSpace(slot.Description)
		slot.AcceptedMediaTypes = normalizeStringSet(slot.AcceptedMediaTypes)
		normalized = append(normalized, slot)
	}
	sort.SliceStable(normalized, func(i, j int) bool {
		return normalized[i].Name < normalized[j].Name
	})
	return normalized
}

func normalizeStringSet(values []string) []string {
	if len(values) == 0 {
		return nil
	}
	seen := make(map[string]struct{}, len(values))
	for _, value := range values {
		normalized := strings.TrimSpace(value)
		if normalized == "" {
			continue
		}
		seen[normalized] = struct{}{}
	}
	if len(seen) == 0 {
		return nil
	}

	out := make([]string, 0, len(seen))
	for value := range seen {
		out = append(out, value)
	}
	sort.Strings(out)
	return out
}

func validateReferenceSlots(slots []contracts.ReferenceSlot) error {
	seen := make(map[string]struct{}, len(slots))
	for i, slot := range slots {
		if slot.Name == "" {
			return fmt.Errorf("slot[%d].name must not be empty", i)
		}
		if _, ok := seen[slot.Name]; ok {
			return fmt.Errorf("slot name %q is duplicated", slot.Name)
		}
		seen[slot.Name] = struct{}{}
		if slot.MaxBytes < 0 {
			return fmt.Errorf("slot %q max_bytes must not be negative", slot.Name)
		}
	}
	return nil
}

func cloneReferenceSlots(slots []contracts.ReferenceSlot) []contracts.ReferenceSlot {
	if len(slots) == 0 {
		return nil
	}
	out := make([]contracts.ReferenceSlot, 0, len(slots))
	for _, slot := range slots {
		slot.AcceptedMediaTypes = append([]string(nil), slot.AcceptedMediaTypes...)
		out = append(out, slot)
	}
	return out
}