analyze.go

package strut

import (
	"errors"
	"fmt"
	"reflect"
	"regexp"
	"strings"
)

// Discord limits. Exceeding any of these is rejected at registration.
const (
	maxOptions      = 25
	maxModalFields  = 5
	maxNameLen      = 32
	maxDescLen      = 100
	maxStringLength = 6000
	maxNesting      = 2
)

// mode selects which rules apply, since command options and modal inputs
// share the tag grammar but not its valid settings.
type mode uint8

const (
	modeCommand mode = iota
	modeModal
	modeComponent
)

// fieldSpec is one analysed struct field.
type fieldSpec struct {
	// Index is a path, so fields promoted from an embedded struct can be
	// reached with reflect.Value.FieldByIndex.
	Index    []int
	GoName   string
	Tag      tag
	Kind     kind
	Type     reflect.Type // after unwrapping Option
	Optional bool

	ChoiceElem   reflect.Type // non-nil when the type has a Choices method
	Autocomplete bool         // type has a valid Autocomplete method

	// Variadic marks a slice field, which soaks up every remaining argument.
	// Discord has no repeatable option, so it is prefix only.
	Variadic bool
}

// structSpec is an analysed command or modal struct.
type structSpec struct {
	Type   reflect.Type
	Mode   mode
	Fields []fieldSpec // leaf options or modal inputs
	Subs   []fieldSpec // nested subcommands; mutually exclusive with Fields

	// Context menu targets, filled from the interaction rather than parsed.
	UserTarget    *fieldSpec
	MessageTarget *fieldSpec
}

// nameRe matches Discord's chat input name grammar. Uppercase is rejected
// separately so the error can say why.
var nameRe = regexp.MustCompile(`^[-_\p{L}\p{N}]{1,32}$`)

func validName(s string) error {
	if !nameRe.MatchString(s) {
		return fmt.Errorf("must be 1-%d chars of letters, digits, - or _", maxNameLen)
	}
	if s != strings.ToLower(s) {
		return errors.New("must be lowercase")
	}
	return nil
}

// analyze walks a command or modal struct and reports every problem it finds
// rather than stopping at the first.
func analyze(t reflect.Type, m mode) (*structSpec, error) {
	for t.Kind() == reflect.Ptr {
		t = t.Elem()
	}
	if t.Kind() != reflect.Struct {
		return nil, fmt.Errorf("strut: %s: must be a struct", t)
	}

	spec := &structSpec{Type: t, Mode: m}
	var errs []error
	seen := map[string]string{}
	optionalAt := -1
	restAt := -1

	var walk func(t reflect.Type, path []int)
	walk = func(t reflect.Type, path []int) {
		for i := range t.NumField() {
			f := t.Field(i)
			if !f.IsExported() {
				continue
			}
			index := append(append([]int{}, path...), i)

			tg, err := parseTag(string(f.Tag), f.Name)
			if err != nil {
				errs = append(errs, fmt.Errorf("%s.%s: %w", t.Name(), f.Name, err))
				continue
			}
			if tg.Skip {
				continue
			}

			// A slice soaks up the remaining arguments, so it is classified by
			// its element type.
			ft, variadic := f.Type, false
			if ft.Kind() == reflect.Slice && ft.Elem().Kind() != reflect.Uint8 {
				ft, variadic = ft.Elem(), true
			}

			k, inner, opt := classify(ft)

			// An embedded struct strut does not otherwise recognise contributes
			// its own fields, so option groups can be shared between commands.
			if k == kindInvalid && f.Anonymous && f.Type.Kind() == reflect.Struct {
				walk(f.Type, index)
				continue
			}

			fs := fieldSpec{
				Index: index, GoName: f.Name, Tag: tg,
				Kind: k, Type: inner, Optional: opt, Variadic: variadic,
			}
			if elem, ok := choicesOf(inner); ok {
				fs.ChoiceElem = elem
			}
			fs.Autocomplete = autocompleterOf(inner)

			fail := func(format string, a ...any) {
				errs = append(errs, fmt.Errorf("%s.%s: %s", t.Name(), f.Name, fmt.Sprintf(format, a...)))
			}

			if k == kindInvalid && m != modeComponent {
				fail("unsupported option type %s", f.Type)
				continue
			}

			// Targets are checked before naming rules: they are filled from the
			// interaction, so they have no option name to validate.
			if k == kindUserTarget || k == kindMessageTarget {
				if m == modeModal {
					fail("context menu targets are not valid in a modal")
					continue
				}
				spec.addTarget(fs, fail)
				continue
			}

			if err := validName(tg.Name); err != nil {
				fail("option name %q: %v", tg.Name, err)
			}
			if prev, dup := seen[tg.Name]; dup {
				fail("option name %q already used by %s", tg.Name, prev)
			}
			seen[tg.Name] = f.Name

			if m == modeModal {
				validateModalField(&fs, fail)
				spec.Fields = append(spec.Fields, fs)
				continue
			}

			// Component state carries no Discord option semantics; the codec
			// checks which types it can store.
			if m == modeComponent {
				spec.Fields = append(spec.Fields, fs)
				continue
			}

			if k == kindSub {
				if opt {
					fail("subcommands cannot be optional")
				}
				spec.Subs = append(spec.Subs, fs)
				continue
			}

			validateCommandField(&fs, fail)

			// Ordering rules only make sense once a field is otherwise sound.
			if opt {
				if optionalAt < 0 {
					optionalAt = len(spec.Fields)
				}
			} else if optionalAt >= 0 {
				fail("required option after optional %q; Discord requires optional options last",
					spec.Fields[optionalAt].Tag.Name)
			}
			if restAt >= 0 {
				fail("option after %q, which takes everything left", spec.Fields[restAt].Tag.Name)
			}
			if tg.Rest || variadic {
				restAt = len(spec.Fields)
			}

			spec.Fields = append(spec.Fields, fs)
		}
	}

	walk(t, nil)
	errs = append(errs, spec.validateShape()...)
	return spec, errors.Join(errs...)
}

// addTarget records a context menu target field, rejecting a second one of
// the same kind. A struct may hold one of each so a single command can serve
// both menu surfaces.
func (s *structSpec) addTarget(fs fieldSpec, fail func(string, ...any)) {
	if fs.Optional {
		fail("context menu targets cannot be optional; they are always supplied")
		return
	}

	slot := &s.UserTarget
	if fs.Kind == kindMessageTarget {
		slot = &s.MessageTarget
	}
	if *slot != nil {
		fail("duplicate %s; %s already declares one", fs.Kind, (*slot).GoName)
		return
	}
	*slot = &fs
}

func validateCommandField(fs *fieldSpec, fail func(string, ...any)) {
	tg := &fs.Tag

	if fs.Variadic {
		switch {
		case fs.Optional:
			fail("a variadic option is already empty when nothing is given, so it cannot be optional")
		case tg.Rest:
			fail("rest and a variadic option both take everything left")
		case tg.Flag:
			fail("flag does not apply to a variadic option")
		}
	}

	if tg.Desc == "" {
		tg.Desc = tg.Name
	}
	if n := len([]rune(tg.Desc)); n > maxDescLen {
		fail("description is %d chars, max %d", n, maxDescLen)
	}
	if tg.Label != "" || tg.Placeholder != "" || tg.Paragraph {
		fail("label, placeholder and paragraph apply to modal fields only")
	}

	bounded, isLength := fs.Kind.bounded()
	switch {
	case !bounded && (tg.Min.Present() || tg.Max.Present()):
		fail("min and max do not apply to %s options", fs.Kind)
	case isLength:
		checkLengthBound(tg.Min, "min", fail)
		checkLengthBound(tg.Max, "max", fail)
	}
	if lo, ok := tg.Min.Load(); ok {
		if hi, ok := tg.Max.Load(); ok && lo > hi {
			fail("min %v is greater than max %v", lo, hi)
		}
	}

	if len(tg.Channels) > 0 && fs.Kind != kindChannel {
		fail("channels applies to channel options only, got %s", fs.Kind)
	}

	if tg.Autocomplete {
		switch fs.Kind {
		case kindString, kindInt, kindFloat:
		default:
			fail("autocomplete applies to string, integer and number options only, got %s", fs.Kind)
		}
		if !fs.Autocomplete {
			fail("tagged autocomplete but %s has no Autocomplete(*Event[D], strut.Partial) []Choice[%s] method",
				fs.Type, fs.Type)
		}
		if fs.ChoiceElem != nil {
			fail("cannot use autocomplete together with a Choices method")
		}
	} else if fs.Autocomplete {
		fail("%s has an Autocomplete method but the field is not tagged autocomplete", fs.Type)
	}

	if tg.Flag && fs.Kind != kindBool {
		fail("flag applies to boolean options only, got %s", fs.Kind)
	}
	if tg.Rest && fs.Kind != kindString {
		fail("rest applies to string options only, got %s", fs.Kind)
	}
	if tg.Lazy && !fs.Optional {
		fail("lazy applies to optional options only")
	}
}

func validateModalField(fs *fieldSpec, fail func(string, ...any)) {
	tg := &fs.Tag

	if fs.Kind != kindString {
		fail("modal fields must be string or Option[string], got %s", fs.Type)
	}
	if fs.ChoiceElem != nil && tg.Paragraph {
		fail("a modal field with choices is a select menu, so paragraph does not apply")
	}
	if tg.Label == "" {
		tg.Label = tg.Name
	}
	if tg.Desc != "" {
		fail("modal fields use label, not desc")
	}
	if tg.Autocomplete || len(tg.Channels) > 0 || tg.Rest || tg.Lazy || tg.Flag {
		fail("autocomplete, channels, rest, lazy and flag do not apply to modal fields")
	}
	checkLengthBound(tg.Min, "min", fail)
	checkLengthBound(tg.Max, "max", fail)
	if lo, ok := tg.Min.Load(); ok {
		if hi, ok := tg.Max.Load(); ok && lo > hi {
			fail("min %v is greater than max %v", lo, hi)
		}
	}
}

func checkLengthBound(v Option[float64], name string, fail func(string, ...any)) {
	n, ok := v.Load()
	if !ok {
		return
	}
	if n != float64(int(n)) || n < 0 || n > maxStringLength {
		fail("%s must be a whole number between 0 and %d, got %v", name, maxStringLength, n)
	}
}

func (s *structSpec) validateShape() []error {
	var errs []error
	name := s.Type.Name()

	if s.Mode == modeComponent {
		return nil
	}
	if s.Mode == modeModal {
		if n := len(s.Fields); n > maxModalFields {
			errs = append(errs, fmt.Errorf("%s: %d modal fields, max %d", name, n, maxModalFields))
		}
		if len(s.Fields) == 0 {
			errs = append(errs, fmt.Errorf("%s: modal has no fields", name))
		}
		return errs
	}

	// Discord allows a command to hold either options or subcommands, never both.
	if len(s.Subs) > 0 && len(s.Fields) > 0 {
		errs = append(errs, fmt.Errorf("%s: cannot mix options and subcommands", name))
	}
	if n := len(s.Fields); n > maxOptions {
		errs = append(errs, fmt.Errorf("%s: %d options, max %d", name, n, maxOptions))
	}
	if n := len(s.Subs); n > maxOptions {
		errs = append(errs, fmt.Errorf("%s: %d subcommands, max %d", name, n, maxOptions))
	}
	return errs
}