commandkit/command.go

package commandkit

import (
	"errors"
	"fmt"
	"strings"
	"unicode"

	internalcobra "gitea.maximumdirect.net/eric/CommandKit/internal/cobra"
)

// Command is an opaque, reusable declaration captured by NewCommand, Group,
// RootGroup, or an integration.
type Command struct{ record *commandRecord }

type commandRecord struct {
	name        string
	summary     string
	description string
	children    []Command
	payload     commandPayload
	issues      []error
	rootOnly    bool
	absent      bool
	invalid     bool
}

// Supplied carries a value and whether it was explicitly provided.
type Supplied[T any] struct {
	// Value is the associated value.
	Value T
	// Set reports whether a caller explicitly supplied the value.
	Set bool
}

// FlagMeta describes a command flag.
type FlagMeta struct {
	// Name is the flag name without leading dashes.
	Name string
	// Short is an optional one-byte spelling.
	Short string
	// Usage briefly describes the flag.
	Usage string
	// Required reports whether execution requires the flag to be supplied.
	Required bool
}

// ArgumentMeta describes a positional command argument.
type ArgumentMeta struct {
	// Name is the argument name shown in command help.
	Name string
	// Usage briefly describes the argument.
	Usage string
}

// Flag represents a typed binding for a command flag.
type Flag[I any] struct {
	binding flagBinding[I]
}

type bindingIdentity struct{ marker byte }

type preparedValue[I any] struct {
	identity *bindingIdentity
	supplied bool
	apply    func(*I)
}

type flagBinding[I any] struct {
	identity    *bindingIdentity
	meta        FlagMeta
	defaultText string
	repeated    bool
	boolean     bool
	prepare     func([]string) (preparedValue[I], error)
	clear       func(*I)
	valid       bool
}

// Argument represents a typed binding for a positional command argument.
type Argument[I any] struct {
	binding argumentBinding[I]
}

type argumentBinding[I any] struct {
	identity *bindingIdentity
	meta     ArgumentMeta
	min      int
	max      int
	prepare  func([]string) (preparedValue[I], error)
	valid    bool
}

// CommandSpec declares one command using typed input and handler callbacks.
type CommandSpec[I any] struct {
	// Name is one command path component.
	Name string
	// Summary is a short description of the command.
	Summary string
	// Description provides additional command detail.
	Description string
	// Children are relative child declarations captured with this command.
	Children []Command
	// NewInput creates an input value for execution. A nil factory uses a fresh
	// zero value.
	NewInput func() I
	// Flags declares the command's local flags.
	Flags []Flag[I]
	// Arguments declares the command's positional inputs.
	Arguments []Argument[I]
	// CheckInput validates declared combinations of parsed inputs.
	CheckInput func(I) error
	// Run handles an invocation. It may be nil for a command used as a group.
	Run func(Invocation, I) Outcome
}

type commandPayload interface {
	validate() error
	hasRun() bool
	bridgeFlags() []internalcobra.Flag
	bridgeArguments() []internalcobra.Argument
	prepare([][]string, []string, bool) (func() any, error)
	checkInput(any) error
	run(Invocation, any) Outcome
}

type typedCommand[I any] struct {
	spec CommandSpec[I]
}

func (c typedCommand[I]) validate() error {
	return validateBindings(c.spec.Flags, c.spec.Arguments)
}

func (c typedCommand[I]) hasRun() bool {
	return c.spec.Run != nil
}

func (c typedCommand[I]) bridgeFlags() []internalcobra.Flag {
	flags := make([]internalcobra.Flag, len(c.spec.Flags))
	for index, flag := range c.spec.Flags {
		binding := flag.binding
		flags[index] = internalcobra.Flag{
			Name:     binding.meta.Name,
			Short:    binding.meta.Short,
			Usage:    binding.meta.Usage,
			Default:  binding.defaultText,
			Boolean:  binding.boolean,
			Repeated: binding.repeated,
			Required: binding.meta.Required,
		}
	}
	return flags
}

func (c typedCommand[I]) bridgeArguments() []internalcobra.Argument {
	arguments := make([]internalcobra.Argument, len(c.spec.Arguments))
	for index, argument := range c.spec.Arguments {
		binding := argument.binding
		arguments[index] = internalcobra.Argument{
			Name:  binding.meta.Name,
			Usage: binding.meta.Usage,
			Min:   binding.min,
			Max:   binding.max,
		}
	}
	return arguments
}

func (c typedCommand[I]) prepare(flagValues [][]string, operands []string, enforceRequired bool) (func() any, error) {
	prepared, err := prepareInput(c.spec, flagValues, operands, enforceRequired)
	if err != nil {
		return nil, err
	}
	return func() any {
		input := prepared.build()
		return &input
	}, nil
}

func (c typedCommand[I]) run(invocation Invocation, input any) Outcome {
	return c.spec.Run(invocation, *input.(*I))
}

func (c typedCommand[I]) checkInput(input any) error {
	if c.spec.CheckInput == nil {
		return nil
	}
	return c.spec.CheckInput(*input.(*I))
}

// NewCommand captures a typed command declaration. Construction issues are
// retained and reported when the declaration is installed.
func NewCommand[I any](spec CommandSpec[I]) Command {
	copySpec := spec
	copySpec.Flags = append([]Flag[I](nil), spec.Flags...)
	copySpec.Arguments = append([]Argument[I](nil), spec.Arguments...)
	copySpec.Children = append([]Command(nil), spec.Children...)
	payload := typedCommand[I]{spec: copySpec}
	record := &commandRecord{
		name: spec.Name, summary: spec.Summary, description: spec.Description,
		children: copySpec.Children, payload: payload,
	}
	if err := payload.validate(); err != nil {
		record.issues = append(record.issues, fmt.Errorf("command %q: %w", spec.Name, err))
	}
	captureComposition(record)
	return Command{record: record}
}

// Group captures a non-runnable command group and its relative children.
func Group(name, summary string, children ...Command) Command {
	record := &commandRecord{name: name, summary: summary, children: append([]Command(nil), children...)}
	captureComposition(record)
	return Command{record: record}
}

// RootGroup captures a group that may only be installed at the application root.
func RootGroup(name, summary string, children ...Command) Command {
	command := Group(name, summary, children...)
	command.record.rootOnly = true
	return command
}

// WithError returns a declaration that also retains err for installation.
func WithError(command Command, err error) Command {
	if err == nil {
		return command
	}
	var record commandRecord
	if command.record == nil {
		record.invalid = true
	} else {
		record = *command.record
		record.issues = append([]error(nil), record.issues...)
	}
	record.issues = append(record.issues, err)
	return Command{record: &record}
}

// NoCommand explicitly represents an absent optional declaration.
func NoCommand() Command { return Command{record: &commandRecord{absent: true}} }

func captureComposition(record *commandRecord) {
	if err := validateCommandName(record.name); err != nil {
		record.issues = append(record.issues, err)
	}
	seen := make(map[string]struct{}, len(record.children))
	for _, child := range record.children {
		if child.record == nil {
			record.issues = append(record.issues, fmt.Errorf("command %q has an invalid child declaration", record.name))
			continue
		}
		if child.record.absent {
			continue
		}
		name := child.record.name
		if _, exists := seen[name]; exists {
			record.issues = append(record.issues, fmt.Errorf("duplicate child command %q under %q", name, record.name))
		}
		seen[name] = struct{}{}
	}
}

func validateCommandDeclaration(command Command) error {
	var issues []error
	collectDeclarationIssues(command, nil, &issues)
	return errors.Join(issues...)
}

func collectDeclarationIssues(command Command, parents []string, issues *[]error) {
	if command.record == nil {
		*issues = append(*issues, errors.New("invalid zero command declaration"))
		return
	}
	record := command.record
	path := append(append([]string(nil), parents...), record.name)
	label := strings.Join(path, " ")
	for _, issue := range record.issues {
		if label != "" {
			*issues = append(*issues, fmt.Errorf("command %q: %w", label, issue))
		} else {
			*issues = append(*issues, issue)
		}
	}
	if record.invalid || record.absent {
		return
	}
	for _, child := range record.children {
		if child.record == nil {
			continue
		}
		collectDeclarationIssues(child, path, issues)
	}
}

func validateCommandName(name string) error {
	fields := strings.Fields(name)
	if len(fields) != 1 || fields[0] != name || strings.HasPrefix(name, "-") || name == "--" {
		return fmt.Errorf("command name %q must be one non-option token", name)
	}
	return nil
}

func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
	flagNames := make(map[string]struct{}, len(flags))
	shortNames := make(map[string]struct{}, len(flags))
	for _, flag := range flags {
		binding := flag.binding
		if !validFlagName(binding.meta.Name) {
			return fmt.Errorf("flag name %q must use lowercase hyphen-separated words", binding.meta.Name)
		}
		if binding.meta.Name == "help" {
			return fmt.Errorf("flag name %q is reserved for help", binding.meta.Name)
		}
		if _, exists := flagNames[binding.meta.Name]; exists {
			return fmt.Errorf("duplicate flag name %q", binding.meta.Name)
		}
		flagNames[binding.meta.Name] = struct{}{}
		if binding.meta.Short != "" {
			if len(binding.meta.Short) != 1 || binding.meta.Short == "-" {
				return fmt.Errorf("short spelling %q must be one byte", binding.meta.Short)
			}
			if binding.meta.Short == "h" {
				return fmt.Errorf("short spelling %q is reserved for help", binding.meta.Short)
			}
			if _, exists := shortNames[binding.meta.Short]; exists {
				return fmt.Errorf("duplicate short spelling %q", binding.meta.Short)
			}
			shortNames[binding.meta.Short] = struct{}{}
		}
		if binding.identity == nil || !binding.valid || binding.prepare == nil {
			return fmt.Errorf("flag %q is missing parser or setter wiring", binding.meta.Name)
		}
	}

	for _, argument := range arguments {
		binding := argument.binding
		if binding.meta.Name == "" {
			return fmt.Errorf("argument name must not be empty")
		}
		if binding.min < 0 || binding.max < -1 || (binding.max >= 0 && binding.min > binding.max) {
			return fmt.Errorf("argument %q has invalid bounds %d..%d", binding.meta.Name, binding.min, binding.max)
		}
		if binding.identity == nil || !binding.valid || binding.prepare == nil {
			return fmt.Errorf("argument %q is missing parser or setter wiring", binding.meta.Name)
		}
	}
	return nil
}

func validFlagName(name string) bool {
	if name == "" || name[0] == '-' || name[len(name)-1] == '-' {
		return false
	}
	segmentHasCharacter := false
	for _, character := range name {
		if character == '-' {
			if !segmentHasCharacter {
				return false
			}
			segmentHasCharacter = false
			continue
		}
		if !unicode.IsLower(character) && !unicode.IsDigit(character) {
			return false
		}
		segmentHasCharacter = true
	}
	return segmentHasCharacter
}