ra_usage.go

package ra

import (
	"fmt"
	"sort"
	"strings"

	"github.com/amterp/color"
)

var (
	greenBold  = color.New(color.FgGreen, color.Bold)
	cyan       = color.New(color.FgCyan)
	bold       = color.New(color.Bold)
	GreenBoldS = greenBold.SprintfFunc()
	CyanS      = cyan.SprintfFunc()
	BoldS      = bold.SprintfFunc()
)

func (c *Cmd) GenerateUsage(isLongHelp bool) string {
	return c.generateUsage(isLongHelp)
}

func (c *Cmd) GenerateShortUsage() string {
	return c.generateUsage(false)
}

func (c *Cmd) GenerateLongUsage() string {
	return c.generateUsage(true)
}

func (c *Cmd) GenerateDescription() string {
	return c.generateDescription()
}

func (c *Cmd) GenerateSynopsis(isLongHelp bool) string {
	return c.generateSynopsis(isLongHelp)
}

func (c *Cmd) GenerateShortSynopsis() string {
	return c.generateSynopsis(false)
}

func (c *Cmd) GenerateLongSynopsis() string {
	return c.generateSynopsis(true)
}

func (c *Cmd) GenerateCommandsSection(isLongHelp bool) string {
	return c.generateCommandsSection(isLongHelp)
}

func (c *Cmd) GenerateArgumentsSection(isLongHelp bool) string {
	return c.generateArgumentsSection(isLongHelp)
}

func (c *Cmd) GenerateGlobalOptionsSection(isLongHelp bool) string {
	return c.generateGlobalOptionsSection(isLongHelp)
}

func (c *Cmd) GenerateShortCommandsSection() string {
	return c.generateCommandsSection(false)
}

func (c *Cmd) GenerateLongCommandsSection() string {
	return c.generateCommandsSection(true)
}

func (c *Cmd) GenerateShortArgumentsSection() string {
	return c.generateArgumentsSection(false)
}

func (c *Cmd) GenerateLongArgumentsSection() string {
	return c.generateArgumentsSection(true)
}

func (c *Cmd) GenerateShortGlobalOptionsSection() string {
	return c.generateGlobalOptionsSection(false)
}

func (c *Cmd) GenerateLongGlobalOptionsSection() string {
	return c.generateGlobalOptionsSection(true)
}

func (c *Cmd) generateDescription() string {
	if c.description == "" {
		return ""
	}
	return c.description + "\n\n"
}

// isVisible reports whether this flag should appear in help output at the given
// help level. The command equivalent is (*Cmd).isVisible. Note completion uses
// base.Hidden directly instead, since HiddenInShortHelp does not affect completion.
func (b *BaseFlag) isVisible(isLongHelp bool) bool {
	if b.Hidden {
		return false
	}
	if !isLongHelp && b.HiddenInShortHelp {
		return false
	}
	return true
}

// isVisible reports whether this command should appear in help output at the
// given help level. Mirrors (*BaseFlag).isVisible.
func (c *Cmd) isVisible(isLongHelp bool) bool {
	if c.hidden {
		return false
	}
	if !isLongHelp && c.hiddenInShortHelp {
		return false
	}
	return true
}

func (c *Cmd) hasVisibleSubCmds(isLongHelp bool) bool {
	for _, subCmd := range c.subCmds {
		if subCmd.isVisible(isLongHelp) {
			return true
		}
	}
	return false
}

func (c *Cmd) generateCommandsSection(isLongHelp bool) string {
	if !c.hasVisibleSubCmds(isLongHelp) {
		return ""
	}

	var sb strings.Builder
	headers := c.getUsageHeaders()

	sb.WriteString("\n" + GreenBoldS(headers.Commands) + "\n")

	// Sort subcommand names for consistent output
	var subCmdNames []string
	for name := range c.subCmds {
		subCmdNames = append(subCmdNames, name)
	}
	sort.Strings(subCmdNames)

	// First pass: calculate maximum command name width (visible commands only)
	maxWidth := 0
	for _, name := range subCmdNames {
		if !c.subCmds[name].isVisible(isLongHelp) {
			continue
		}
		cmdWidth := len(name) + 2 // 2 for leading "  "
		if cmdWidth > maxWidth {
			maxWidth = cmdWidth
		}
	}

	// Add 3 spaces padding (same as flags formatting)
	maxWidth = maxWidth + 3

	// Second pass: generate aligned output
	for _, name := range subCmdNames {
		subCmd := c.subCmds[name]
		if !subCmd.isVisible(isLongHelp) {
			continue
		}
		cmdPart := fmt.Sprintf("  %s", name)
		sb.WriteString(cmdPart)

		// Mark the default so the command list explains itself. Rendered even
		// with no description, which the description branch below would skip -
		// an unmarked default is a command the user has no way to know they
		// can omit.
		trailer := ""
		if subCmd.description != "" {
			// Only show first line of description in command list for better readability
			trailer = strings.Split(subCmd.description, "\n")[0]
		}
		if name == c.defaultSubCmdName {
			if trailer != "" {
				trailer += " "
			}
			trailer += "(default)"
		}

		if trailer != "" {
			// Calculate padding to align descriptions
			padding := maxWidth - len(cmdPart)
			if padding < 1 {
				padding = 1
			}
			sb.WriteString(strings.Repeat(" ", padding))
			sb.WriteString(trailer)
		}
		sb.WriteString("\n")
	}

	return sb.String()
}

func (c *Cmd) separateScriptAndGlobalFlags() (scriptFlags, globalFlags []any) {
	// Use a map to keep track of added flags to avoid duplicates
	addedFlags := make(map[string]bool)

	// First, handle all script flags (positional and non-positional)
	// Process positional flags in registration order
	for _, name := range c.positional {
		if addedFlags[name] {
			continue
		}
		flag := c.flags[name]

		// Check if this is originally a global flag
		isOriginallyGlobal := false
		for _, gName := range c.globalFlags {
			if name == gName {
				isOriginallyGlobal = true
				break
			}
		}

		// Check if this flag represents a non-global override of a global flag
		isNonGlobalOverride := false
		if _, wasOverridden := c.overriddenGlobalFlags[name]; wasOverridden {
			// Check what type of override this is
			if _, hadNameShadowed := c.shadowedNameFlags[name]; hadNameShadowed {
				// Name shadowing case - the non-global flag took over the name
				// The flag stored under this name is the non-global flag
				isNonGlobalOverride = true
			} else if _, hadShortShadowed := c.shadowedShortFlags[name]; hadShortShadowed {
				// Short shadowing case - the global flag lost its short but kept its name
				// The flag stored under this name is still the global flag (modified)
				isNonGlobalOverride = false
			} else {
				// Complete override case - both name and short conflicted
				// The flag stored under this name is the non-global flag
				isNonGlobalOverride = true
			}
		}

		// Add to scriptFlags if:
		// 1. Not originally global, OR
		// 2. It's a non-global flag that overrode a global flag
		if !isOriginallyGlobal || isNonGlobalOverride {
			scriptFlags = append(scriptFlags, flag)
		}
		addedFlags[name] = true
	}

	// Process non-positional flags in registration order
	for _, name := range c.nonPositional {
		if addedFlags[name] {
			continue
		}
		flag := c.flags[name]

		// Check if this is originally a global flag
		isOriginallyGlobal := false
		for _, gName := range c.globalFlags {
			if name == gName {
				isOriginallyGlobal = true
				break
			}
		}

		// Check if this flag represents a non-global override of a global flag
		isNonGlobalOverride := false
		if _, wasOverridden := c.overriddenGlobalFlags[name]; wasOverridden {
			// Check what type of override this is
			if _, hadNameShadowed := c.shadowedNameFlags[name]; hadNameShadowed {
				// Name shadowing case - the non-global flag took over the name
				// The flag stored under this name is the non-global flag
				isNonGlobalOverride = true
			} else if _, hadShortShadowed := c.shadowedShortFlags[name]; hadShortShadowed {
				// Short shadowing case - the global flag lost its short but kept its name
				// The flag stored under this name is still the global flag (modified)
				isNonGlobalOverride = false
			} else {
				// Complete override case - both name and short conflicted
				// The flag stored under this name is the non-global flag
				isNonGlobalOverride = true
			}
		}

		// Add to scriptFlags if:
		// 1. Not originally global, OR
		// 2. It's a non-global flag that overrode a global flag
		if !isOriginallyGlobal || isNonGlobalOverride {
			scriptFlags = append(scriptFlags, flag)
		}
		addedFlags[name] = true
	}

	// Process global flags in their registration order to preserve ordering
	for _, globalFlagName := range c.globalFlags {
		// Check if this global flag was name-shadowed
		if _, hadNameShadowed := c.shadowedNameFlags[globalFlagName]; hadNameShadowed {
			// Add name-shadowed global flag (appears with only its short form)
			if originalFlag, exists := c.overriddenGlobalFlags[globalFlagName]; exists {
				if base := getBaseFlag(originalFlag); base != nil && base.Short != "" {
					// Look up the flag stored under its short key
					if shortFlag, shortExists := c.flags[base.Short]; shortExists {
						// Create a copy without the name for display
						flagCopy := deepCopyFlag(shortFlag)
						if baseCopy := getBaseFlag(flagCopy); baseCopy != nil {
							baseCopy.Name = "" // Remove name for display, keep only short
						}
						globalFlags = append(globalFlags, flagCopy)
					}
				}
			}
		} else {
			// Check if this global flag was completely overridden (both name and short conflicted)
			if _, wasOverridden := c.overriddenGlobalFlags[globalFlagName]; wasOverridden {
				// Check what type of override this was
				if _, hadShortShadowed := c.shadowedShortFlags[globalFlagName]; hadShortShadowed {
					// Short shadowing case - global flag lost its short but should still appear in Global options
					if flag, exists := c.flags[globalFlagName]; exists {
						globalFlags = append(globalFlags, flag)
					}
				} else {
					// Complete override case - global flag was completely replaced, don't show it
					// (the non-global override will appear in Arguments section)
					continue
				}
			} else {
				// Regular global flag - add if it exists
				if flag, exists := c.flags[globalFlagName]; exists {
					globalFlags = append(globalFlags, flag)
				}
			}
		}
	}

	return scriptFlags, globalFlags
}

func (c *Cmd) generateArgumentsSection(isLongHelp bool) string {
	return c.generateArgumentsSectionAs(c.getUsageHeaders().Arguments, isLongHelp)
}

// generateArgumentsSectionAs renders this command's args under a caller-chosen
// header, so a parent can show its default subcommand's args without claiming
// they are its own.
func (c *Cmd) generateArgumentsSectionAs(header string, isLongHelp bool) string {
	scriptFlags, _ := c.separateScriptAndGlobalFlags()

	if len(scriptFlags) == 0 || !c.hasVisibleFlags(scriptFlags, isLongHelp) {
		return ""
	}

	var sb strings.Builder

	sb.WriteString("\n" + GreenBoldS(header) + "\n")
	sb.WriteString(c.formatFlags(scriptFlags, isLongHelp))

	return sb.String()
}

func (c *Cmd) generateGlobalOptionsSection(isLongHelp bool) string {
	_, globalFlags := c.separateScriptAndGlobalFlags()

	if len(globalFlags) == 0 || !c.hasVisibleFlags(globalFlags, isLongHelp) {
		return ""
	}

	var sb strings.Builder
	headers := c.getUsageHeaders()

	sb.WriteString("\n" + GreenBoldS(headers.GlobalOptions) + "\n")
	sb.WriteString(c.formatFlags(globalFlags, isLongHelp))

	return sb.String()
}

func (c *Cmd) generateUsage(isLongHelp bool) string {
	var sb strings.Builder
	headers := c.getUsageHeaders()

	description := c.generateDescription()
	if description != "" {
		sb.WriteString(description)
	}

	sb.WriteString(GreenBoldS(headers.Usage) + "\n  ")
	sb.WriteString(c.generateSynopsis(isLongHelp))
	sb.WriteString("\n")

	// A second synopsis line for the default subcommand, naming its equivalent.
	// The `(default)` tag in the command list says which command it is; this
	// says what you can actually type. Skipped when the default takes no
	// positionals, since the line would otherwise repeat the first one.
	if def := c.defaultCmd(); def != nil && def.hasPositionalArgs(isLongHelp) {
		sb.WriteString("  ")
		sb.WriteString(def.generateSynopsisAs(c.name, isLongHelp))
		sb.WriteString(CyanS("   (same as: %s %s)", c.name, def.name))
		sb.WriteString("\n")
	}

	commandsSection := c.generateCommandsSection(isLongHelp)
	if commandsSection != "" {
		sb.WriteString(commandsSection)
	}

	argumentsSection := c.generateArgumentsSection(isLongHelp)
	if argumentsSection != "" {
		sb.WriteString(argumentsSection)
	}

	// The default's own args, after this command's, because the page is about
	// this command and those are borrowed.
	if def := c.defaultCmd(); def != nil {
		if section := def.generateArgumentsSectionAs(
			fmt.Sprintf("Args for default command '%s':", def.name), isLongHelp); section != "" {
			sb.WriteString(section)
		}
	}

	globalOptionsSection := c.generateGlobalOptionsSection(isLongHelp)
	if globalOptionsSection != "" {
		sb.WriteString(globalOptionsSection)
	}

	return sb.String()
}

// writeSynopsisArg renders one arg placeholder and reports whether it ends the
// positional sequence. Both list forms take several values, so both get "...";
// only a positional-capable one absorbs positionals and truncates what follows.
func (c *Cmd) writeSynopsisArg(sb *strings.Builder, name string, flag any) bool {
	collects := absorbsPositionals(flag)
	argName := name
	if collects || isVariadicFlag(flag) {
		argName = name + "..."
	}
	// A variadic is never required, whatever else its declaration says.
	if c.shouldFlagBeOptionalInSynopsis(flag) || isVariadicFlag(flag) {
		sb.WriteString(" " + CyanS("[%s]", argName))
	} else {
		sb.WriteString(" " + CyanS("<%s>", argName))
	}
	return collects
}

func (c *Cmd) generateSynopsis(isLongHelp bool) string {
	return c.generateSynopsisAs(c.name, isLongHelp)
}

// generateSynopsisAs renders this command's synopsis under a different leading
// name. The default-subcommand line needs it: the args are the default's, but
// the invocation the reader types is the parent's.
func (c *Cmd) generateSynopsisAs(name string, isLongHelp bool) string {
	var sb strings.Builder
	sb.WriteString(BoldS(name))

	// Prepend the [subcommand] placeholder when subcommands are visible at this
	// help level (none visible - because none exist or all are hidden - means no
	// placeholder). Either way we fall through to render the command's own flags
	// below, so a required flag appears consistently regardless of whether the
	// placeholder is shown.
	if c.hasVisibleSubCmds(isLongHelp) {
		headers := c.getUsageHeaders()
		sb.WriteString(" " + CyanS("[%s]", headers.SubcommandPlaceholder))
	}

	// First pass: collect positional-only flags
	var positionalOnlyFlags []string
	var nonPositionalFlags []string

	for _, name := range c.positional {
		flag := c.flags[name]
		base := getBaseFlag(flag)
		if !base.isVisible(isLongHelp) {
			continue
		}

		if isBoolFlag(flag) {
			continue // Bools never appear in synopsis
		}

		if base.PositionalOnly {
			positionalOnlyFlags = append(positionalOnlyFlags, name)
		} else {
			// If a flag is in the positional list, it should appear in synopsis
			// regardless of whether it's optional or not
			nonPositionalFlags = append(nonPositionalFlags, name)
		}
	}

	// Add non-positional flags from nonPositional list (they might not be in positional)
	for _, name := range c.nonPositional {
		flag := c.flags[name]
		base := getBaseFlag(flag)
		if !base.isVisible(isLongHelp) {
			continue
		}

		// Skip global flags - they don't appear in synopsis
		isGlobal := false
		for _, gName := range c.globalFlags {
			if name == gName {
				isGlobal = true
				break
			}
		}
		if isGlobal {
			continue
		}

		if isBoolFlag(flag) || base.Optional {
			continue // Bools and optional flags never appear in synopsis
		}

		// Check if already added
		found := false
		for _, existing := range nonPositionalFlags {
			if existing == name {
				found = true
				break
			}
		}
		if !found {
			nonPositionalFlags = append(nonPositionalFlags, name)
		}
	}

	// A collector absorbs every remaining positional, so it ends the sequence:
	// anything declared after it can only be set by name.
	for _, name := range positionalOnlyFlags {
		if c.writeSynopsisArg(&sb, name, c.flags[name]) {
			sb.WriteString(" " + CyanS("[OPTIONS]"))
			return sb.String()
		}
	}

	for _, name := range nonPositionalFlags {
		if c.writeSynopsisArg(&sb, name, c.flags[name]) {
			sb.WriteString(" " + CyanS("[OPTIONS]"))
			return sb.String()
		}
	}

	sb.WriteString(" " + CyanS("[OPTIONS]"))
	return sb.String()
}

func (c *Cmd) hasVisibleFlags(flags []any, isLongHelp bool) bool {
	for _, flag := range flags {
		if getBaseFlag(flag).isVisible(isLongHelp) {
			return true
		}
	}
	return false
}

func (c *Cmd) formatFlags(flags []any, isLongHelp bool) string {
	// Use flags in the order they were passed (already correctly ordered by generateUsage)
	allFlags := flags

	// First pass: calculate maximum width for alignment
	maxWidth := 0
	var flagParts []string

	for _, flag := range allFlags {
		base := getBaseFlag(flag)
		if !base.isVisible(isLongHelp) {
			flagParts = append(flagParts, "")
			continue
		}

		var flagPart string
		if base.PositionalOnly {
			// Positional-only flags show without dashes
			flagPart = fmt.Sprintf("  %s", base.Name)
		} else if base.Name == "" && base.Short != "" {
			// Name-shadowed flag - show only short form
			flagPart = fmt.Sprintf("  -%s", base.Short)
		} else if base.Short != "" && base.Name != "" {
			// Normal flag with both short and name
			flagPart = fmt.Sprintf("  -%s, --%s", base.Short, base.Name)
		} else if base.Name != "" {
			// Flag with only name (no short)
			flagPart = fmt.Sprintf("      --%s", base.Name)
		} else {
			// Shouldn't happen - flag with neither name nor short
			flagPart = fmt.Sprintf("  (unnamed flag)")
		}

		typeStr := getFlagType(flag)
		if typeStr != "bool" {
			flagPart = fmt.Sprintf("%s %s", flagPart, typeStr)
		}

		flagParts = append(flagParts, flagPart)
		if len(flagPart) > maxWidth {
			maxWidth = len(flagPart)
		}
	}

	// Use dynamic alignment: longest left side + 3 spaces
	maxWidth = maxWidth + 3

	// Second pass: generate aligned output
	var sb strings.Builder
	for i, flag := range allFlags {
		flagPart := flagParts[i]
		if flagPart == "" {
			continue // hidden flag
		}

		base := getBaseFlag(flag)
		sb.WriteString(flagPart)

		// Check if we have usage text or constraints to display
		hasUsage := base.Usage != ""
		constraints := c.getConstraintString(flag)
		hasConstraints := constraints != ""

		if hasUsage || hasConstraints {
			// Calculate padding to align descriptions
			padding := maxWidth - len(flagPart)
			if padding < 1 {
				padding = 1
			}
			sb.WriteString(strings.Repeat(" ", padding))

			// Add optional marker for flags that should be optional
			// but not for variadic flags (their type already indicates optionality)
			isVariadic := false
			switch f := flag.(type) {
			case *StringSliceFlag:
				isVariadic = f.Variadic
			case *IntSliceFlag:
				isVariadic = f.Variadic
			case *Int64SliceFlag:
				isVariadic = f.Variadic
			case *Float64SliceFlag:
				isVariadic = f.Variadic
			case *BoolSliceFlag:
				isVariadic = f.Variadic
			}

			// Show status markers for non-variadic flags:
			// For positional-only flags: show (optional) if explicitly optional, otherwise no marker
			// For other flags: (optional) if explicitly optional AND no default, (required) if required AND no default
			hasDefault := c.flagHasDefault(flag)
			var shouldShowOptional bool
			if base.PositionalOnly {
				shouldShowOptional = base.Optional
			} else {
				shouldShowOptional = base.Optional && !hasDefault
			}

			if shouldShowOptional && !isVariadic {
				sb.WriteString("(optional) ")
			}

			// Add usage text if it exists
			if hasUsage {
				usage := base.Usage
				sb.WriteString(usage)
				// Add period after usage text if there are constraints and usage doesn't end with period
				if hasConstraints {
					if !strings.HasSuffix(usage, ".") {
						sb.WriteString(". ")
					} else {
						sb.WriteString(" ")
					}
				}
			}

			// Add constraints (including defaults)
			if hasConstraints {
				if !hasUsage {
					// If no usage text, don't add extra space
					sb.WriteString(constraints)
				} else {
					// Usage text already added period and space above
					sb.WriteString(constraints)
				}
			}
		}
		sb.WriteString("\n")
	}
	return sb.String()
}

func isBoolFlag(flag any) bool {
	_, ok := flag.(*BoolFlag)
	return ok
}

func getFlagType(flag any) string {
	// Check for custom type override first
	if base := getBaseFlag(flag); base != nil && base.CustomUsageType != "" {
		return base.CustomUsageType
	}

	switch f := flag.(type) {
	case *BoolFlag:
		return "bool"
	case *StringFlag:
		return "str"
	case *IntFlag:
		return "int"
	// int64 is a Go-side width, not something a caller types differently: the
	// placeholder tells them what to write, and that is digits either way.
	// A caller who does want the distinction can set a custom usage type.
	case *Int64Flag:
		return "int"
	case *Float64Flag:
		return "float"
	case *BoolSliceFlag:
		if f.Variadic {
			return "[bools...]"
		}
		return "bools"
	case *StringSliceFlag:
		if f.Variadic {
			return "[strs...]"
		}
		return "strs"
	case *IntSliceFlag:
		if f.Variadic {
			return "[ints...]"
		}
		return "ints"
	case *Int64SliceFlag:
		if f.Variadic {
			return "[ints...]"
		}
		return "ints"
	case *Float64SliceFlag:
		if f.Variadic {
			return "[floats...]"
		}
		return "floats"
	}
	return ""
}

func (c *Cmd) getConstraintString(flag any) string {
	var parts []string

	// Add range constraints
	if rangeStr := c.getRangeString(flag); rangeStr != "" {
		parts = append(parts, "Range: "+rangeStr)
	}

	// Add enum and regex constraints (both can be present)
	if enumStr := c.getEnumString(flag); enumStr != "" {
		parts = append(parts, "Valid values: "+enumStr)
	}

	if regexStr := c.getRegexString(flag); regexStr != "" {
		parts = append(parts, "Regex: "+regexStr)
	}

	if lenStr := c.getLenString(flag); lenStr != "" {
		parts = append(parts, "Length: "+lenStr)
	}

	// Add separator for slices
	if sepStr := c.getSeparatorString(flag); sepStr != "" {
		parts = append(parts, "Separator: "+sepStr)
	}

	// Add relationship constraints
	if reqStr := c.getRequiresString(flag); reqStr != "" {
		parts = append(parts, "Requires: "+reqStr)
	}

	if exclStr := c.getExcludesString(flag); exclStr != "" {
		parts = append(parts, "Excludes: "+exclStr)
	}

	// Join constraint parts with periods
	constraintStr := strings.Join(parts, ". ")

	// Add default value last (if present)
	if defaultStr := c.getDefaultString(flag); defaultStr != "" {
		if constraintStr != "" {
			constraintStr += " " + fmt.Sprintf("(default %s)", defaultStr)
		} else {
			constraintStr = fmt.Sprintf("(default %s)", defaultStr)
		}
	}

	return constraintStr
}
func (c *Cmd) getDefaultString(flag any) string {
	switch f := flag.(type) {
	case *StringFlag:
		if f.Default != nil {
			return *f.Default
		}
	case *IntFlag:
		if f.Default != nil {
			return fmt.Sprintf("%d", *f.Default)
		}
	case *Int64Flag:
		if f.Default != nil {
			return fmt.Sprintf("%d", *f.Default)
		}
	case *Float64Flag:
		if f.Default != nil {
			return fmt.Sprintf("%g", *f.Default)
		}
	case *BoolFlag:
		if f.Default != nil && *f.Default {
			return "true" // Show (default true) but not (default false)
		}
		return ""
	case *StringSliceFlag:
		if f.Default != nil && len(*f.Default) > 0 {
			return fmt.Sprintf("[%s]", strings.Join(*f.Default, ", "))
		}
	case *IntSliceFlag:
		if f.Default != nil && len(*f.Default) > 0 {
			var strs []string
			for _, v := range *f.Default {
				strs = append(strs, fmt.Sprintf("%d", v))
			}
			return fmt.Sprintf("[%s]", strings.Join(strs, ", "))
		}
	case *Int64SliceFlag:
		if f.Default != nil && len(*f.Default) > 0 {
			var strs []string
			for _, v := range *f.Default {
				strs = append(strs, fmt.Sprintf("%d", v))
			}
			return fmt.Sprintf("[%s]", strings.Join(strs, ", "))
		}
	case *Float64SliceFlag:
		if f.Default != nil && len(*f.Default) > 0 {
			var strs []string
			for _, v := range *f.Default {
				strs = append(strs, fmt.Sprintf("%g", v))
			}
			return fmt.Sprintf("[%s]", strings.Join(strs, ", "))
		}
	case *BoolSliceFlag:
		if f.Default != nil && len(*f.Default) > 0 {
			var strs []string
			for _, v := range *f.Default {
				strs = append(strs, fmt.Sprintf("%t", v))
			}
			return fmt.Sprintf("[%s]", strings.Join(strs, ", "))
		}
	}
	return ""
}

func (c *Cmd) getRangeString(flag any) string {
	switch f := flag.(type) {
	case *IntFlag:
		if f.min != nil || f.max != nil {
			var left, right string

			if f.min != nil {
				inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
				if inclusive {
					left = fmt.Sprintf("[%d", *f.min)
				} else {
					left = fmt.Sprintf("(%d", *f.min)
				}
			} else {
				left = "("
			}

			if f.max != nil {
				inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
				if inclusive {
					right = fmt.Sprintf("%d]", *f.max)
				} else {
					right = fmt.Sprintf("%d)", *f.max)
				}
			} else {
				right = ")"
			}

			return left + ", " + right
		}
	case *Int64Flag:
		if f.min != nil || f.max != nil {
			var left, right string

			if f.min != nil {
				inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
				if inclusive {
					left = fmt.Sprintf("[%d", *f.min)
				} else {
					left = fmt.Sprintf("(%d", *f.min)
				}
			} else {
				left = "("
			}

			if f.max != nil {
				inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
				if inclusive {
					right = fmt.Sprintf("%d]", *f.max)
				} else {
					right = fmt.Sprintf("%d)", *f.max)
				}
			} else {
				right = ")"
			}

			return left + ", " + right
		}
	case *Float64Flag:
		if f.min != nil || f.max != nil {
			var left, right string

			if f.min != nil {
				inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
				if inclusive {
					left = fmt.Sprintf("[%g", *f.min)
				} else {
					left = fmt.Sprintf("(%g", *f.min)
				}
			} else {
				left = "("
			}

			if f.max != nil {
				inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
				if inclusive {
					right = fmt.Sprintf("%g]", *f.max)
				} else {
					right = fmt.Sprintf("%g)", *f.max)
				}
			} else {
				right = ")"
			}

			return left + ", " + right
		}
	case *SliceFlag[int]:
		return f.rangeString()
	case *SliceFlag[int64]:
		return f.rangeString()
	case *SliceFlag[float64]:
		return f.rangeString()
	}
	return ""
}

func (c *Cmd) getEnumString(flag any) string {
	switch f := flag.(type) {
	case *StringFlag:
		if f.EnumConstraint != nil && len(*f.EnumConstraint) > 0 {
			return fmt.Sprintf("[%s]", strings.Join(*f.EnumConstraint, ", "))
		}
	case *SliceFlag[string]:
		if f.EnumConstraint != nil && len(*f.EnumConstraint) > 0 {
			return fmt.Sprintf("[%s]", strings.Join(*f.EnumConstraint, ", "))
		}
	}
	return ""
}

func (c *Cmd) getRegexString(flag any) string {
	switch f := flag.(type) {
	case *StringFlag:
		if f.RegexConstraint != nil {
			return f.RegexConstraint.String()
		}
	case *SliceFlag[string]:
		if f.RegexConstraint != nil {
			return f.RegexConstraint.String()
		}
	}
	return ""
}

// getLenString renders a slice flag's element-count bounds. Scalars have no
// equivalent, so there are no cases for them.
func (c *Cmd) getLenString(flag any) string {
	switch f := flag.(type) {
	case *SliceFlag[string]:
		return f.lenString()
	case *SliceFlag[int]:
		return f.lenString()
	case *SliceFlag[int64]:
		return f.lenString()
	case *SliceFlag[float64]:
		return f.lenString()
	case *SliceFlag[bool]:
		return f.lenString()
	}
	return ""
}

func (c *Cmd) getSeparatorString(flag any) string {
	switch f := flag.(type) {
	case *StringSliceFlag:
		if f.Separator != nil {
			return fmt.Sprintf("\"%s\"", *f.Separator)
		}
	case *IntSliceFlag:
		if f.Separator != nil {
			return fmt.Sprintf("\"%s\"", *f.Separator)
		}
	case *Int64SliceFlag:
		if f.Separator != nil {
			return fmt.Sprintf("\"%s\"", *f.Separator)
		}
	case *Float64SliceFlag:
		if f.Separator != nil {
			return fmt.Sprintf("\"%s\"", *f.Separator)
		}
	case *BoolSliceFlag:
		if f.Separator != nil {
			return fmt.Sprintf("\"%s\"", *f.Separator)
		}
	}
	return ""
}

func (c *Cmd) getRequiresString(flag any) string {
	base := getBaseFlag(flag)
	if base != nil && base.Requires != nil && len(*base.Requires) > 0 {
		return strings.Join(*base.Requires, ", ")
	}
	return ""
}

func (c *Cmd) getExcludesString(flag any) string {
	base := getBaseFlag(flag)
	if base != nil && base.Excludes != nil && len(*base.Excludes) > 0 {
		return strings.Join(*base.Excludes, ", ")
	}
	return ""
}

func (c *Cmd) shouldFlagBeOptionalInSynopsis(flag any) bool {
	base := getBaseFlag(flag)

	// Check if flag has a default value (makes it optional)
	hasDefault := false
	switch f := flag.(type) {
	case *StringFlag:
		hasDefault = f.Default != nil
	case *IntFlag:
		hasDefault = f.Default != nil
	case *Int64Flag:
		hasDefault = f.Default != nil
	case *Float64Flag:
		hasDefault = f.Default != nil
	case *BoolFlag:
		hasDefault = f.Default != nil
	case *StringSliceFlag:
		hasDefault = f.Default != nil
	case *IntSliceFlag:
		hasDefault = f.Default != nil
	case *Int64SliceFlag:
		hasDefault = f.Default != nil
	case *Float64SliceFlag:
		hasDefault = f.Default != nil
	case *BoolSliceFlag:
		hasDefault = f.Default != nil
	}

	// Flag is optional if it has a default OR was explicitly set optional
	if hasDefault || base.Optional {
		return true
	}

	return false
}

func (c *Cmd) flagHasDefault(flag any) bool {
	switch f := flag.(type) {
	case *StringFlag:
		return f.Default != nil
	case *IntFlag:
		return f.Default != nil
	case *Int64Flag:
		return f.Default != nil
	case *Float64Flag:
		return f.Default != nil
	case *BoolFlag:
		return true // Boolean flags have implicit default of false
	case *StringSliceFlag:
		return f.Default != nil
	case *IntSliceFlag:
		return f.Default != nil
	case *Int64SliceFlag:
		return f.Default != nil
	case *Float64SliceFlag:
		return f.Default != nil
	case *BoolSliceFlag:
		return true // Boolean slice flags have implicit default of empty slice
	}
	return false
}

// hasPositionalArgs reports whether this command takes any visible positional
// argument, which is what decides whether a default-subcommand synopsis line
// would say anything the first line didn't.
func (c *Cmd) hasPositionalArgs(isLongHelp bool) bool {
	for _, name := range c.positional {
		flag := c.flags[name]
		if base := getBaseFlag(flag); base != nil && !base.FlagOnly && base.isVisible(isLongHelp) {
			return true
		}
	}
	return false
}