ra_usage_test.go

package ra

import (
	"regexp"
	"strings"
	"testing"

	"github.com/amterp/color"

	"github.com/stretchr/testify/assert"
)

func init() {
	color.NoColor = true
}

// withColorsEnabled is a helper for tests that need to test color output
func withColorsEnabled(testFunc func()) {
	oldNoColor := color.NoColor
	color.NoColor = false
	defer func() {
		color.NoColor = oldNoColor
	}()
	testFunc()
}

func Test_Usage_DefaultHeaders(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Test default headers")

	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	subCmd := NewCmd("subcmd")
	subCmd.SetDescription("A subcommand")
	_, err = cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	_, err = NewString("global").SetUsage("Global flag").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	assert.Contains(t, usage, "Usage:")
	assert.Contains(t, usage, "Commands:")
	assert.Contains(t, usage, "Arguments:")
	assert.Contains(t, usage, "Global options:")
}

func Test_Usage_CustomHeaders(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Test custom headers")

	headers := UsageHeaders{
		Usage:         "How to use:",
		Commands:      "Available commands:",
		Arguments:     "Parameters:",
		GlobalOptions: "Global flags:",
	}
	cmd.SetUsageHeaders(headers)

	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	subCmd := NewCmd("subcmd")
	subCmd.SetDescription("A subcommand")
	_, err = cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	_, err = NewString("global").SetUsage("Global flag").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	assert.Contains(t, usage, "How to use:")
	assert.Contains(t, usage, "Available commands:")
	assert.Contains(t, usage, "Parameters:")
	assert.Contains(t, usage, "Global flags:")

	// Verify old headers are not present
	assert.NotContains(t, usage, "Usage:")
	assert.NotContains(t, usage, "Commands:")
	assert.NotContains(t, usage, "Arguments:")
	assert.NotContains(t, usage, "Global options:")
}

func Test_Usage_ColoredHeaders(t *testing.T) {
	withColorsEnabled(func() {
		cmd := NewCmd("myapp")
		cmd.SetDescription("Test colored headers")

		_, err := NewString("input").SetUsage("Input file").Register(cmd)
		assert.NoError(t, err)

		subCmd := NewCmd("subcmd")
		subCmd.SetDescription("A subcommand")
		_, err = cmd.RegisterCmd(subCmd)
		assert.NoError(t, err)

		_, err = NewString("global").SetUsage("Global flag").Register(cmd, WithGlobal(true))
		assert.NoError(t, err)

		usage := cmd.GenerateUsage(false)

		// Check for ANSI color codes in headers (green bold = \033[32;1m)
		assert.Contains(t, usage, "\033[32;1mUsage:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mCommands:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mArguments:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mGlobal options:\033[0;22m")
	})
}

func Test_Usage_CustomColoredHeaders(t *testing.T) {
	withColorsEnabled(func() {
		cmd := NewCmd("myapp")
		cmd.SetDescription("Test custom colored headers")

		headers := UsageHeaders{
			Usage:         "How to use:",
			Commands:      "Available commands:",
			Arguments:     "Parameters:",
			GlobalOptions: "Global flags:",
		}
		cmd.SetUsageHeaders(headers)

		_, err := NewString("input").SetUsage("Input file").Register(cmd)
		assert.NoError(t, err)

		subCmd := NewCmd("subcmd")
		subCmd.SetDescription("A subcommand")
		_, err = cmd.RegisterCmd(subCmd)
		assert.NoError(t, err)

		_, err = NewString("global").SetUsage("Global flag").Register(cmd, WithGlobal(true))
		assert.NoError(t, err)

		usage := cmd.GenerateUsage(false)

		// Check for ANSI color codes with custom headers
		assert.Contains(t, usage, "\033[32;1mHow to use:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mAvailable commands:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mParameters:\033[0;22m")
		assert.Contains(t, usage, "\033[32;1mGlobal flags:\033[0;22m")
	})
}

func Test_Usage_ColoredSynopsis(t *testing.T) {
	withColorsEnabled(func() {
		cmd := NewCmd("myapp")
		cmd.SetDescription("Test colored synopsis")

		_, err := NewString("input").SetUsage("Input file").Register(cmd)
		assert.NoError(t, err)

		_, err = NewString("output").SetUsage("Output file").SetOptional(true).Register(cmd)
		assert.NoError(t, err)

		usage := cmd.GenerateUsage(false)
		t.Logf("Test_Usage_ColoredSynopsis output:\n%s", usage)

		// Check for bold command name and cyan argument types
		assert.Contains(t, usage, "\033[1mmyapp\033[22m")     // Bold command name
		assert.Contains(t, usage, "\033[36m<input>\033[0m")   // Cyan required arg
		assert.Contains(t, usage, "\033[36m[output]\033[0m")  // Cyan optional arg - NOW appears thanks to fix!
		assert.Contains(t, usage, "\033[36m[OPTIONS]\033[0m") // Cyan options
	})
}

func Test_Usage_OptionalPositionalArgsShouldAppear(t *testing.T) {
	withColorsEnabled(func() {
		cmd := NewCmd("myapp")

		// Required positional arg
		_, err := NewString("required").SetUsage("Required input").Register(cmd)
		assert.NoError(t, err)

		// Optional positional arg - this should appear in synopsis!
		_, err = NewString("optional").SetUsage("Optional input").SetOptional(true).Register(cmd)
		assert.NoError(t, err)

		usage := cmd.GenerateUsage(false)
		t.Logf("Current usage output:\n%s", usage)

		// Both required and optional positional args should appear in synopsis
		assert.Contains(t, usage, "<required>", "required positional arg should appear with <brackets>")
		assert.Contains(t, usage, "[optional]", "optional positional arg should appear with [brackets]")
	})
}

func Test_Usage_DocumentationExample(t *testing.T) {
	cmd := NewCmd("mycommand")
	cmd.SetDescription("Example for documentation")

	// Required positional arg
	_, err := NewString("required-arg").SetUsage("A required argument").Register(cmd)
	assert.NoError(t, err)

	// Optional positional arg
	_, err = NewString("optional-arg").SetUsage("An optional argument").SetOptional(true).Register(cmd)
	assert.NoError(t, err)

	// Another optional positional arg
	_, err = NewString("other-optional").SetUsage("Another optional argument").SetOptional(true).Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)
	t.Logf("Documentation example output:\n%s", usage)

	// Verify the synopsis shows all positional args
	assert.Contains(t, usage, "mycommand <required-arg> [optional-arg] [other-optional] [OPTIONS]")
}

func Test_Usage_ExamplesmdPattern(t *testing.T) {
	// Test based on EXAMPLES.md pattern: mycmd aaa --arg2 bbb -c ddd -f
	cmd := NewCmd("mycmd")
	cmd.SetDescription("Example matching EXAMPLES.md dual nature")

	// arg1: can be positional or --arg1
	_, err := NewString("arg1").SetUsage("First argument").Register(cmd)
	assert.NoError(t, err)

	// arg2: can be positional or --arg2
	_, err = NewString("arg2").SetUsage("Second argument").Register(cmd)
	assert.NoError(t, err)

	// arg3: can be positional or --arg3/-c
	_, err = NewString("arg3").SetShort("c").SetUsage("Third argument").Register(cmd)
	assert.NoError(t, err)

	// arg4: bool flag, not positional
	_, err = NewBool("arg4").SetShort("f").SetUsage("Fourth argument (bool)").Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)
	t.Logf("EXAMPLES.md pattern usage output:\n%s", usage)
}

func Test_Usage_SimpleCommand(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("A simple application for testing")

	flag1, err := NewString("config").
		SetShort("c").
		SetUsage("Configuration file path.").
		SetDefault("/etc/myapp.conf").
		Register(cmd)
	assert.NoError(t, err)

	flag2, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Enable verbose output.").
		Register(cmd)
	assert.NoError(t, err)

	flag3, err := NewInt("timeout").
		SetUsage("Request timeout in seconds.").
		SetMin(1, true).
		SetMax(300, true).
		SetDefault(30).
		Register(cmd)
	assert.NoError(t, err)

	_ = flag1
	_ = flag2
	_ = flag3

	usage := cmd.GenerateUsage(false)

	expected := `A simple application for testing

Usage:
  myapp [config] [timeout] [OPTIONS]

Arguments:
  -c, --config str    Configuration file path. (default /etc/myapp.conf)
      --timeout int   Request timeout in seconds. Range: [1, 300] (default 30)
  -v, --verbose       Enable verbose output.
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_WithPositionalArgs(t *testing.T) {
	cmd := NewCmd("processor")
	cmd.SetDescription("Process input files")

	// Positional arguments
	input, err := NewString("input-file").
		SetUsage("Path to input file").
		SetPositionalOnly(true).
		Register(cmd)
	assert.NoError(t, err)

	output, err := NewString("output-dir").
		SetUsage("Output directory").
		SetPositionalOnly(true).
		SetOptional(true).
		Register(cmd)
	assert.NoError(t, err)

	// Named options
	format, err := NewString("format").
		SetShort("f").
		SetUsage("Output format").
		SetEnumConstraint([]string{"json", "yaml", "xml"}).
		SetDefault("json").
		Register(cmd)
	assert.NoError(t, err)

	concurrent, err := NewInt("jobs").
		SetShort("j").
		SetUsage("Number of concurrent jobs").
		SetMin(1, true).
		SetMax(16, false).
		Register(cmd)
	assert.NoError(t, err)

	_ = input
	_ = output
	_ = format
	_ = concurrent

	usage := cmd.GenerateUsage(false)

	expected := `Process input files

Usage:
  processor <input-file> [output-dir] [format] <jobs> [OPTIONS]

Arguments:
  input-file str     Path to input file
  output-dir str     (optional) Output directory
  -f, --format str   Output format. Valid values: [json, yaml, xml] (default json)
  -j, --jobs int     Number of concurrent jobs. Range: [1, 16)
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_WithSubcommands(t *testing.T) {
	cmd := NewCmd("git-like")
	cmd.SetDescription("A git-like version control system")

	// Global options
	verbose, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Enable verbose output").
		Register(cmd)
	assert.NoError(t, err)

	config, err := NewString("config").
		SetUsage("Path to config file").
		SetDefault("~/.gitlike/config").
		Register(cmd)
	assert.NoError(t, err)

	// Add subcommand
	addCmd := NewCmd("add")
	addCmd.SetDescription("Add files to the staging area")

	addAll, err := NewBool("all").
		SetShort("A").
		SetUsage("Add all modified files").
		Register(addCmd)
	assert.NoError(t, err)

	addFiles, err := NewStringSlice("files").
		SetUsage("Files to add").
		SetPositionalOnly(true).
		SetVariadic(true).
		Register(addCmd)
	assert.NoError(t, err)

	// Commit subcommand
	commitCmd := NewCmd("commit")
	commitCmd.SetDescription("Record changes to the repository")

	message, err := NewString("message").
		SetShort("m").
		SetUsage("Commit message").
		SetRegexConstraint(regexp.MustCompile(`^.{1,72}$`)).
		Register(commitCmd)
	assert.NoError(t, err)

	amend, err := NewBool("amend").
		SetUsage("Amend the previous commit").
		SetExcludes([]string{"message"}).
		Register(commitCmd)
	assert.NoError(t, err)

	_, err = cmd.RegisterCmd(addCmd)
	assert.NoError(t, err)
	_, err = cmd.RegisterCmd(commitCmd)
	assert.NoError(t, err)

	_ = verbose
	_ = config
	_ = addAll
	_ = addFiles
	_ = message
	_ = amend

	usage := cmd.GenerateUsage(false)

	expected := `A git-like version control system

Usage:
  git-like [subcommand] [config] [OPTIONS]

Commands:
  add      Add files to the staging area
  commit   Record changes to the repository

Arguments:
      --config str   Path to config file. (default ~/.gitlike/config)
  -v, --verbose      Enable verbose output
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_SubcommandWithArgs(t *testing.T) {
	cmd := NewCmd("git-like")
	addCmd := NewCmd("add")
	addCmd.SetDescription("Add files to the staging area")

	// Add subcommand options
	all, err := NewBool("all").
		SetShort("A").
		SetUsage("Add all modified files").
		SetExcludes([]string{"force"}).
		Register(addCmd)
	assert.NoError(t, err)

	force, err := NewBool("force").
		SetShort("f").
		SetUsage("Force add ignored files").
		Register(addCmd)
	assert.NoError(t, err)

	files, err := NewStringSlice("files").
		SetUsage("Files to add").
		SetPositionalOnly(true).
		SetVariadic(true).
		SetOptional(true).
		Register(addCmd)
	assert.NoError(t, err)

	_, err = cmd.RegisterCmd(addCmd)
	assert.NoError(t, err)

	_ = all
	_ = force
	_ = files

	usage := addCmd.GenerateUsage(false)

	expected := `Add files to the staging area

Usage:
  add [files...] [OPTIONS]

Arguments:
  files [strs...]   Files to add
  -A, --all         Add all modified files. Excludes: force
  -f, --force       Force add ignored files
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_ComplexConstraints(t *testing.T) {
	cmd := NewCmd("complex")
	cmd.SetDescription("Command with various constraint types")

	// Range constraints
	port, err := NewInt("port").
		SetShort("p").
		SetUsage("Server port").
		SetMin(1024, true).
		SetMax(65535, true).
		SetDefault(8080).
		Register(cmd)
	assert.NoError(t, err)

	rate, err := NewFloat64("rate").
		SetUsage("Processing rate").
		SetMin(0.0, false).
		SetMax(100.0, true).
		Register(cmd)
	assert.NoError(t, err)

	unbounded, err := NewInt("retries").
		SetUsage("Number of retries").
		SetMin(0, true).
		Register(cmd)
	assert.NoError(t, err)

	// Enum constraint
	format, err := NewString("format").
		SetUsage("Output format").
		SetEnumConstraint([]string{"json", "yaml", "xml", "csv"}).
		SetDefault("json").
		Register(cmd)
	assert.NoError(t, err)

	// Regex constraint
	name, err := NewString("name").
		SetUsage("Resource name").
		SetRegexConstraint(regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9_-]*$`)).
		Register(cmd)
	assert.NoError(t, err)

	// Slice with custom separator
	tags, err := NewStringSlice("tags").
		SetUsage("Resource tags").
		SetSeparator("|").
		SetRequires([]string{"name"}).
		Register(cmd)
	assert.NoError(t, err)

	// Multiple relationships
	debug, err := NewBool("debug").
		SetUsage("Enable debug mode").
		SetExcludes([]string{"quiet", "silent"}).
		Register(cmd)
	assert.NoError(t, err)

	quiet, err := NewBool("quiet").
		SetShort("q").
		SetUsage("Suppress output").
		SetExcludes([]string{"debug", "verbose"}).
		Register(cmd)
	assert.NoError(t, err)

	_ = port
	_ = rate
	_ = unbounded
	_ = format
	_ = name
	_ = tags
	_ = debug
	_ = quiet

	usage := cmd.GenerateUsage(false)

	expected := `Command with various constraint types

Usage:
  complex [port] <rate> <retries> [format] <name> <tags...> [OPTIONS]

Arguments:
  -p, --port int      Server port. Range: [1024, 65535] (default 8080)
      --rate float    Processing rate. Range: (0, 100]
      --retries int   Number of retries. Range: [0, )
      --format str    Output format. Valid values: [json, yaml, xml, csv] (default json)
      --name str      Resource name. Regex: ^[a-zA-Z][a-zA-Z0-9_-]*$
      --tags strs     Resource tags. Separator: "|". Requires: name
      --debug         Enable debug mode. Excludes: quiet, silent
  -q, --quiet         Suppress output. Excludes: debug, verbose
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_MixedPositionalAndOptions(t *testing.T) {
	cmd := NewCmd("deploy")
	cmd.SetDescription("Deploy application to target environment")

	// Required positional
	app, err := NewString("app-name").
		SetUsage("Application name").
		SetPositionalOnly(true).
		Register(cmd)
	assert.NoError(t, err)

	// Optional positional
	env, err := NewString("environment").
		SetUsage("Target environment").
		SetPositionalOnly(true).
		SetOptional(true).
		SetDefault("staging").
		Register(cmd)
	assert.NoError(t, err)

	// Named options
	force, err := NewBool("force").
		SetShort("f").
		SetUsage("Force deployment even if checks fail").
		Register(cmd)
	assert.NoError(t, err)

	timeout, err := NewInt("timeout").
		SetUsage("Deployment timeout").
		SetMin(30, true).
		SetDefault(300).
		Register(cmd)
	assert.NoError(t, err)

	rollback, err := NewBool("no-rollback").
		SetUsage("Disable automatic rollback on failure").
		SetExcludes([]string{"force"}).
		Register(cmd)
	assert.NoError(t, err)

	_ = app
	_ = env
	_ = force
	_ = timeout
	_ = rollback

	usage := cmd.GenerateUsage(false)

	expected := `Deploy application to target environment

Usage:
  deploy <app-name> [environment] [timeout] [OPTIONS]

Arguments:
  app-name str        Application name
  environment str     (optional) Target environment. (default staging)
      --timeout int   Deployment timeout. Range: [30, ) (default 300)
  -f, --force         Force deployment even if checks fail
      --no-rollback   Disable automatic rollback on failure. Excludes: force
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_HiddenAndLongHelpFlags(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Testing hidden flag behavior")

	// Regular flag
	regular, err := NewString("config").
		SetUsage("Configuration file").
		Register(cmd)
	assert.NoError(t, err)

	// Hidden flag - should never appear
	hidden, err := NewString("secret").
		SetUsage("Secret flag").
		SetHidden(true).
		Register(cmd)
	assert.NoError(t, err)

	// Hidden in short help - should only appear in long help
	longOnly, err := NewString("debug-info").
		SetUsage("Debug information").
		SetHiddenInShortHelp(true).
		Register(cmd)
	assert.NoError(t, err)

	_ = regular
	_ = hidden
	_ = longOnly

	// Test short help (should exclude longOnly flag)
	shortUsage := cmd.GenerateUsage(false)
	expectedShort := `Testing hidden flag behavior

Usage:
  myapp <config> [OPTIONS]

Arguments:
      --config str   Configuration file
`

	assert.Equal(t, strings.TrimSpace(expectedShort), strings.TrimSpace(shortUsage))

	// Test long help (should include longOnly flag)
	longUsage := cmd.GenerateUsage(true)
	expectedLong := `Testing hidden flag behavior

Usage:
  myapp <config> <debug-info> [OPTIONS]

Arguments:
      --config str       Configuration file
      --debug-info str   Debug information
`

	assert.Equal(t, strings.TrimSpace(expectedLong), strings.TrimSpace(longUsage))
}

func Test_Usage_HiddenCommands(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Testing hidden command behavior")

	cmd.RegisterCmd(NewCmd("build").SetDescription("Build the project"))
	cmd.RegisterCmd(NewCmd("secret-cmd").SetDescription("Secret command").SetHidden(true))
	cmd.RegisterCmd(NewCmd("debug-cmd").SetDescription("Debug command").SetHiddenInShortHelp(true))

	// Short help excludes both the fully hidden and the hidden-in-short commands.
	shortUsage := cmd.GenerateUsage(false)
	expectedShort := `Testing hidden command behavior

Usage:
  myapp [subcommand] [OPTIONS]

Commands:
  build   Build the project
`
	assert.Equal(t, strings.TrimSpace(expectedShort), strings.TrimSpace(shortUsage))

	// Long help includes the hidden-in-short command but still excludes the fully hidden one.
	longUsage := cmd.GenerateUsage(true)
	expectedLong := `Testing hidden command behavior

Usage:
  myapp [subcommand] [OPTIONS]

Commands:
  build       Build the project
  debug-cmd   Debug command
`
	assert.Equal(t, strings.TrimSpace(expectedLong), strings.TrimSpace(longUsage))
}

func Test_Usage_AllHiddenCommands(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("All hidden commands")

	cmd.RegisterCmd(NewCmd("alpha").SetDescription("Alpha command").SetHidden(true))
	cmd.RegisterCmd(NewCmd("beta").SetDescription("Beta command").SetHidden(true))

	// With every subcommand hidden, neither the Commands section nor the
	// [subcommand] synopsis placeholder should appear.
	expected := `All hidden commands

Usage:
  myapp [OPTIONS]
`
	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(cmd.GenerateUsage(false)))
	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(cmd.GenerateUsage(true)))
}

func Test_Usage_AllHiddenInShortHelpCommands(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Commands hidden in short help")

	cmd.RegisterCmd(NewCmd("alpha").SetDescription("Alpha command").SetHiddenInShortHelp(true))
	cmd.RegisterCmd(NewCmd("beta").SetDescription("Beta command").SetHiddenInShortHelp(true))

	// Short help: every command is hidden at this level, so the Commands section
	// and the [subcommand] placeholder both drop out.
	expectedShort := `Commands hidden in short help

Usage:
  myapp [OPTIONS]
`
	assert.Equal(t, strings.TrimSpace(expectedShort), strings.TrimSpace(cmd.GenerateUsage(false)))

	// Long help: both commands reappear, along with the placeholder.
	expectedLong := `Commands hidden in short help

Usage:
  myapp [subcommand] [OPTIONS]

Commands:
  alpha   Alpha command
  beta    Beta command
`
	assert.Equal(t, strings.TrimSpace(expectedLong), strings.TrimSpace(cmd.GenerateUsage(true)))
}

// A parent command's own required flags must appear in its synopsis consistently,
// whether or not the [subcommand] placeholder is present. Previously the synopsis
// took a reduced "subcommand branch" that dropped non-positional flags, so a
// required flag-only arg could appear in -h but vanish from --help (or vice versa)
// depending on subcommand visibility.
func Test_Usage_SubcommandSynopsisIncludesRequiredFlags(t *testing.T) {
	cmd := NewCmd("myapp")

	_, err := NewString("target").SetFlagOnly(true).SetUsage("Deploy target").Register(cmd)
	assert.NoError(t, err)

	cmd.RegisterCmd(NewCmd("sub").SetDescription("A subcommand").SetHiddenInShortHelp(true))

	// Short help: subcommand is hidden at this level, so no placeholder - but the
	// required flag must still appear.
	assert.Equal(t, "myapp <target> [OPTIONS]", cmd.GenerateShortSynopsis())

	// Long help: placeholder appears AND the required flag still appears.
	assert.Equal(t, "myapp [subcommand] <target> [OPTIONS]", cmd.GenerateLongSynopsis())
}

func Test_Usage_GlobalFlagsInSubCommand(t *testing.T) {
	cmd := NewCmd("parent")
	cmd.SetDescription("Parent command with global flags")

	// Global flags
	verbose, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Enable verbose output").
		Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	debug, err := NewString("log-level").
		SetUsage("Set log level").
		SetDefault("info").
		Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	// Create subcommand
	subCmd := NewCmd("sub")
	subCmd.SetDescription("Sub command inherits global flags")

	// Subcommand-specific flag
	input, err := NewString("input").
		SetUsage("Input file").
		Register(subCmd)
	assert.NoError(t, err)

	_, err = cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	_ = verbose
	_ = debug
	_ = input

	// Subcommand should show both its own flags and global flags
	usage := subCmd.GenerateUsage(false)
	expected := `Sub command inherits global flags

Usage:
  sub <input> [OPTIONS]

Arguments:
      --input str   Input file

Global options:
  -v, --verbose         Enable verbose output
      --log-level str   Set log level. (default info)
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_FlagOrderingNonBoolFirst(t *testing.T) {
	cmd := NewCmd("ordering")
	cmd.SetDescription("Test flag ordering: non-bool first, then bool")

	// Register in mixed order to test sorting
	bool1, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Enable verbose mode").
		Register(cmd)
	assert.NoError(t, err)

	str1, err := NewString("config").
		SetUsage("Config file path").
		Register(cmd)
	assert.NoError(t, err)

	bool2, err := NewBool("force").
		SetShort("f").
		SetUsage("Force operation").
		Register(cmd)
	assert.NoError(t, err)

	int1, err := NewInt("timeout").
		SetUsage("Timeout value").
		Register(cmd)
	assert.NoError(t, err)

	bool3, err := NewBool("quiet").
		SetShort("q").
		SetUsage("Quiet mode").
		Register(cmd)
	assert.NoError(t, err)

	_ = bool1
	_ = str1
	_ = bool2
	_ = int1
	_ = bool3

	usage := cmd.GenerateUsage(false)
	expected := `Test flag ordering: non-bool first, then bool

Usage:
  ordering <config> <timeout> [OPTIONS]

Arguments:
      --config str    Config file path
      --timeout int   Timeout value
  -v, --verbose       Enable verbose mode
  -f, --force         Force operation
  -q, --quiet         Quiet mode
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_VariadicSliceFormats(t *testing.T) {
	cmd := NewCmd("slices")
	cmd.SetDescription("Testing various slice configurations")

	// Positional-only variadic slice (must come first)
	files, err := NewStringSlice("files").
		SetUsage("Input files").
		SetPositionalOnly(true).
		SetVariadic(true).
		SetOptional(true).
		Register(cmd)
	assert.NoError(t, err)

	// Required variadic slice
	tags, err := NewStringSlice("tags").
		SetUsage("Resource tags").
		SetVariadic(true).
		Register(cmd)
	assert.NoError(t, err)

	// Optional variadic slice
	includes, err := NewStringSlice("include").
		SetUsage("Include patterns").
		SetVariadic(true).
		SetOptional(true).
		Register(cmd)
	assert.NoError(t, err)

	// Regular slice with separator
	ports, err := NewIntSlice("ports").
		SetUsage("Port numbers").
		SetSeparator(",").
		Register(cmd)
	assert.NoError(t, err)

	_ = tags
	_ = includes
	_ = ports
	_ = files

	usage := cmd.GenerateUsage(false)
	expected := `Testing various slice configurations

Usage:
  slices [files...] [OPTIONS]

Arguments:
  files [strs...]           Input files
      --tags [strs...]      Resource tags
      --include [strs...]   Include patterns
      --ports ints          Port numbers. Separator: ","
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_ComplexRelationshipsAndConstraints(t *testing.T) {
	cmd := NewCmd("complex")
	cmd.SetDescription("Complex example with all constraint types")

	// String with regex and enum (should show both constraints)
	mode, err := NewString("mode").
		SetUsage("Operation mode").
		SetRegexConstraint(regexp.MustCompile(`^(dev|prod|test)$`)).
		SetEnumConstraint([]string{"dev", "prod", "test"}).
		Register(cmd)
	assert.NoError(t, err)

	// Float with exclusive bounds
	rate, err := NewFloat64("rate").
		SetUsage("Processing rate").
		SetMin(0.0, false).
		SetMax(1.0, false).
		SetDefault(0.5).
		Register(cmd)
	assert.NoError(t, err)

	// Multiple requires/excludes
	verbose, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Verbose output").
		SetExcludes([]string{"quiet", "silent"}).
		SetRequires([]string{"mode"}).
		Register(cmd)
	assert.NoError(t, err)

	quiet, err := NewBool("quiet").
		SetShort("q").
		SetUsage("Quiet mode").
		SetExcludes([]string{"verbose"}).
		Register(cmd)
	assert.NoError(t, err)

	silent, err := NewBool("silent").
		SetUsage("Silent mode").
		SetExcludes([]string{"verbose"}).
		Register(cmd)
	assert.NoError(t, err)

	// Slice with separator and requires
	configs, err := NewStringSlice("config-files").
		SetUsage("Configuration files").
		SetSeparator(":").
		SetRequires([]string{"mode"}).
		SetOptional(true).
		SetVariadic(true).
		Register(cmd)
	assert.NoError(t, err)

	_ = mode
	_ = rate
	_ = verbose
	_ = quiet
	_ = silent
	_ = configs

	usage := cmd.GenerateUsage(false)
	expected := `Complex example with all constraint types

Usage:
  complex <mode> [rate] [config-files...] [OPTIONS]

Arguments:
      --mode str                 Operation mode. Valid values: [dev, prod, test]. Regex: ^(dev|prod|test)$
      --rate float               Processing rate. Range: (0, 1) (default 0.5)
      --config-files [strs...]   Configuration files. Separator: ":". Requires: mode
  -v, --verbose                  Verbose output. Requires: mode. Excludes: quiet, silent
  -q, --quiet                    Quiet mode. Excludes: verbose
      --silent                   Silent mode. Excludes: verbose
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_PositionalOnlyAfterVariadicError(t *testing.T) {
	cmd := NewCmd("test")

	// Register a variadic positional flag first
	_, err := NewStringSlice("files").
		SetUsage("Input files").
		SetVariadic(true).
		Register(cmd)
	assert.NoError(t, err)

	// Attempting to register a positional-only flag after should error
	_, err = NewString("output").
		SetUsage("Output file").
		SetPositionalOnly(true).
		Register(cmd)
	assert.Equal(
		t,
		`cannot register positional-only flag "output" after list positional flag "files" `+
			`(a list positional absorbs all remaining positional args)`,
		err.Error(),
	)
}

func Test_Usage_SynopsisStopsAfterVariadic(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test synopsis stopping after variadic")

	// Register flags in order: regular, variadic, another regular
	_, err := NewString("first").
		SetUsage("First arg").
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewStringSlice("variadic").
		SetUsage("Variadic arg").
		SetVariadic(true).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewString("after").
		SetUsage("After variadic").
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)
	expected := `Test synopsis stopping after variadic

Usage:
  test <first> [variadic...] [OPTIONS]

Arguments:
      --first str            First arg
      --variadic [strs...]   Variadic arg
      --after str            After variadic`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_RequiredFlagMarker(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test required flag marker")

	// Required flag (no default, not optional)
	_, err := NewString("required").
		SetUsage("Required flag").
		SetFlagOnly(true).
		Register(cmd)
	assert.NoError(t, err)

	// Optional flag
	_, err = NewString("optional").
		SetUsage("Optional flag").
		SetFlagOnly(true).
		SetOptional(true).
		Register(cmd)
	assert.NoError(t, err)

	// Flag with default (effectively optional)
	_, err = NewString("with-default").
		SetUsage("Flag with default").
		SetFlagOnly(true).
		SetDefault("defaultval").
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)
	expected := `Test required flag marker

Usage:
  test <required> [with-default] [OPTIONS]

Arguments:
      --required str       Required flag
      --optional str       (optional) Optional flag
      --with-default str   Flag with default. (default defaultval)`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_BoolFlag_DefaultFalse_NoDisplay(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test bool flag with default false behavior")

	// Explicit default false
	verbose, err := NewBool("verbose").
		SetShort("v").
		SetUsage("Enable verbose output").
		SetDefault(false).
		Register(cmd)
	assert.NoError(t, err)

	// Implicit default false (no SetDefault call)
	debug, err := NewBool("debug").
		SetUsage("Enable debug mode").
		Register(cmd)
	assert.NoError(t, err)

	_ = verbose
	_ = debug

	usage := cmd.GenerateUsage(false)

	// Should not contain "(default false)" anywhere
	assert.NotContains(t, usage, "(default false)")

	// But should still contain the descriptions
	assert.Contains(t, usage, "Enable verbose output")
	assert.Contains(t, usage, "Enable debug mode")
}

func Test_BoolFlag_DefaultTrue_ShowsDefault(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test bool flag with default true shows (default true)")

	// Explicit default true
	enabled, err := NewBool("enabled").
		SetShort("e").
		SetUsage("Feature is enabled by default").
		SetDefault(true).
		Register(cmd)
	assert.NoError(t, err)

	_ = enabled

	usage := cmd.GenerateUsage(false)

	// Should contain "(default true)"
	assert.Contains(t, usage, "(default true)")
	assert.Contains(t, usage, "Feature is enabled by default")

	// Should NOT contain "(default false)"
	assert.NotContains(t, usage, "(default false)")
}

func Test_BoolFlag_MixedDefaults(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test mixed boolean defaults")

	trueFlag, err := NewBool("true-flag").
		SetUsage("Defaults to true").
		SetDefault(true).
		Register(cmd)
	assert.NoError(t, err)

	falseFlag, err := NewBool("false-flag").
		SetUsage("Defaults to false").
		SetDefault(false).
		Register(cmd)
	assert.NoError(t, err)

	implicitFalse, err := NewBool("implicit").
		SetUsage("Implicitly false").
		Register(cmd)
	assert.NoError(t, err)

	_ = trueFlag
	_ = falseFlag
	_ = implicitFalse

	usage := cmd.GenerateUsage(false)

	// Should show (default true) but not (default false)
	assert.Contains(t, usage, "(default true)")
	assert.NotContains(t, usage, "(default false)")

	// All descriptions should be present
	assert.Contains(t, usage, "Defaults to true")
	assert.Contains(t, usage, "Defaults to false")
	assert.Contains(t, usage, "Implicitly false")
}

func Test_ExplicitHelpFlags_OutputToStdout(t *testing.T) {
	// Test --help flag
	t.Run("--help outputs to stdout", func(t *testing.T) {
		cleanup, exitCode, stdout, stderr := mockExit(t)
		defer cleanup()

		assert.Panics(t, func() {
			cmd := NewCmd("test")
			cmd.ParseOrExit([]string{"--help"})
		})

		assert.Equal(t, 0, *exitCode, "should exit with code 0 for help")
		assert.Contains(t, stdout.String(), "Usage:", "help output should go to stdout")
		assert.Empty(t, stderr.String(), "stderr should be empty for help request")
	})

	// Test -h flag
	t.Run("-h outputs to stdout", func(t *testing.T) {
		cleanup, exitCode, stdout, stderr := mockExit(t)
		defer cleanup()

		assert.Panics(t, func() {
			cmd := NewCmd("test")
			cmd.ParseOrExit([]string{"-h"})
		})

		assert.Equal(t, 0, *exitCode, "should exit with code 0 for help")
		assert.Contains(t, stdout.String(), "Usage:", "help output should go to stdout")
		assert.Empty(t, stderr.String(), "stderr should be empty for help request")
	})
}

func Test_AutoHelp_OutputToStdout(t *testing.T) {
	cleanup, exitCode, stdout, stderr := mockExit(t)
	defer cleanup()

	cmd := NewCmd("test")
	cmd.SetAutoHelpOnNoArgs(true)

	// Add a required flag to trigger auto-help
	_, err := NewString("required-flag").Register(cmd)
	assert.NoError(t, err)

	// Call with no args - should trigger auto-help
	assert.Panics(t, func() {
		cmd.ParseOrExit([]string{})
	})

	assert.Equal(t, 0, *exitCode, "should exit with code 0 for auto-help")
	assert.Contains(t, stdout.String(), "Usage:", "auto-help output should go to stdout")
	assert.Contains(t, stdout.String(), "required-flag", "should show required flag")
	assert.Empty(t, stderr.String(), "stderr should be empty for auto-help")
}

func Test_ErrorTriggeredUsage_OutputToStderr(t *testing.T) {
	cleanup, exitCode, stdout, stderr := mockExit(t)
	defer cleanup()

	cmd := NewCmd("test")

	// Add a required flag
	_, err := NewString("required-flag").Register(cmd)
	assert.NoError(t, err)

	// Call with no args and auto-help disabled - should trigger error
	assert.Panics(t, func() {
		cmd.ParseOrExit([]string{})
	})

	assert.Equal(t, 1, *exitCode, "should exit with code 1 for error")
	assert.Empty(t, stdout.String(), "stdout should be empty for error")
	assert.Contains(t, stderr.String(), "Missing required arguments", "error message should go to stderr")
	assert.Contains(t, stderr.String(), "Usage:", "error-triggered usage should go to stderr")
}

func Test_CustomUsage_RespectsStdoutStderrRouting(t *testing.T) {
	// Test custom usage with --help (should go to stdout)
	t.Run("custom usage with --help goes to stdout", func(t *testing.T) {
		cleanup, exitCode, stdout, stderr := mockExit(t)
		defer cleanup()

		// Track custom usage calls
		var customUsageCalled bool
		var customUsageIsLongHelp bool

		cmd := NewCmd("test")
		cmd.SetCustomUsage(func(isLongHelp bool) {
			customUsageCalled = true
			customUsageIsLongHelp = isLongHelp
			// Custom usage should write to the same destination as the regular usage would
			// For help requests, this should still result in stdout output
			if isLongHelp {
				stdoutWriter.Write([]byte("Custom long help"))
			} else {
				stdoutWriter.Write([]byte("Custom short help"))
			}
		})

		assert.Panics(t, func() {
			cmd.ParseOrExit([]string{"--help"})
		})

		assert.Equal(t, 0, *exitCode, "should exit with code 0 for help")
		assert.True(t, customUsageCalled, "should call custom usage function")
		assert.True(t, customUsageIsLongHelp, "should call custom usage with isLongHelp=true")
		assert.Contains(t, stdout.String(), "Custom long help", "custom help output should go to stdout")
		assert.Empty(t, stderr.String(), "stderr should be empty for help request")
	})

	// Test custom usage with -h (should go to stdout)
	t.Run("custom usage with -h goes to stdout", func(t *testing.T) {
		cleanup, exitCode, stdout, stderr := mockExit(t)
		defer cleanup()

		// Track custom usage calls
		var customUsageCalled bool
		var customUsageIsLongHelp bool

		cmd := NewCmd("test")
		cmd.SetCustomUsage(func(isLongHelp bool) {
			customUsageCalled = true
			customUsageIsLongHelp = isLongHelp
			// Custom usage should write to the same destination as the regular usage would
			// For help requests, this should still result in stdout output
			if isLongHelp {
				stdoutWriter.Write([]byte("Custom long help"))
			} else {
				stdoutWriter.Write([]byte("Custom short help"))
			}
		})

		assert.Panics(t, func() {
			cmd.ParseOrExit([]string{"-h"})
		})

		assert.Equal(t, 0, *exitCode, "should exit with code 0 for help")
		assert.True(t, customUsageCalled, "should call custom usage function")
		assert.False(t, customUsageIsLongHelp, "should call custom usage with isLongHelp=false")
		assert.Contains(t, stdout.String(), "Custom short help", "custom help output should go to stdout")
		assert.Empty(t, stderr.String(), "stderr should be empty for help request")
	})
}

func Test_DefaultValues_DisplayWithoutUsageText(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Test default values display without usage text")

	// Flags with defaults but no usage text - these should still show default values
	_, err := NewString("stringArg").
		SetDefault("alice").
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewInt64("intArg").
		SetUsage("An int."). // This one has usage text, should show default
		SetDefault(1).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewFloat64("floatArg").
		SetDefault(1.1).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewBool("boolArg").
		SetDefault(true).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewStringSlice("stringListArg").
		SetDefault([]string{"bob", "charlie"}).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewIntSlice("intListArg").
		SetDefault([]int{2, 3}).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewFloat64Slice("floatListArg").
		SetDefault([]float64{2.1, 3.1}).
		Register(cmd)
	assert.NoError(t, err)

	_, err = NewBoolSlice("boolListArg").
		SetDefault([]bool{true, false}).
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	// All flags should show their default values, even without usage text
	expected := `Test default values display without usage text

Usage:
  myapp [stringArg] [intArg] [floatArg] [stringListArg...] [OPTIONS]

Arguments:
      --stringArg str         (default alice)
      --intArg int            An int. (default 1)
      --floatArg float        (default 1.1)
      --stringListArg strs    (default [bob, charlie])
      --intListArg ints       (default [2, 3])
      --floatListArg floats   (default [2.1, 3.1])
      --boolListArg bools     (default [true, false])
      --boolArg               (default true)
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_VariadicBoolSliceFlag_Synopsis(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test variadic bool slice flag in synopsis")

	_, err := NewBoolSlice("flags").
		SetUsage("Boolean flags").
		SetVariadic(true).
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	// Variadic bool slice should appear in synopsis with [bools...] type
	expected := `Test variadic bool slice flag in synopsis

Usage:
  test [flags...] [OPTIONS]

Arguments:
      --flags [bools...]   Boolean flags
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_CustomUsageType_DoesNotAffectSynopsisLogic(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test that CustomUsageType only affects display, not synopsis logic")

	// BoolFlag with custom type - should still be excluded from synopsis (logic unchanged)
	_, err := NewBool("verbose").
		SetUsage("Enable verbose output").
		SetCustomUsageType("toggle").
		Register(cmd)
	assert.NoError(t, err)

	// StringFlag with "bool" custom type - should still appear in synopsis (logic unchanged)
	_, err = NewString("mode").
		SetUsage("Operation mode").
		SetCustomUsageType("bool").
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	expected := `Test that CustomUsageType only affects display, not synopsis logic

Usage:
  test <mode> [OPTIONS]

Arguments:
      --mode             Operation mode
      --verbose toggle   Enable verbose output
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_RA_COLOR_Environment_Variable_Auto(t *testing.T) {
	// Test RA_COLOR=auto behavior (should let color library decide)
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	// Set environment variable
	t.Setenv("RA_COLOR", "auto")

	// Create a command and trigger parsing (which calls initializeColorFromEnv)
	cmd := NewCmd("test")
	_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
	assert.NoError(t, err)

	// Parse to trigger color initialization
	err = cmd.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	// For auto mode, color.NoColor should remain at its library-determined value
	// Since we can't easily test terminal detection, we verify the function doesn't explicitly set it
}

func Test_RA_COLOR_Environment_Variable_Always(t *testing.T) {
	// Test RA_COLOR=always behavior (should force color on)
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	// Set environment variable
	t.Setenv("RA_COLOR", "always")

	// Create a command and trigger parsing
	cmd := NewCmd("test")
	_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
	assert.NoError(t, err)

	// Parse to trigger color initialization
	err = cmd.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	// For always mode, color.NoColor should be false
	assert.False(t, color.NoColor, "RA_COLOR=always should set color.NoColor=false")
}

func Test_RA_COLOR_Environment_Variable_Never(t *testing.T) {
	// Test RA_COLOR=never behavior (should disable color)
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	// Set environment variable
	t.Setenv("RA_COLOR", "never")

	// Create a command and trigger parsing
	cmd := NewCmd("test")
	_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
	assert.NoError(t, err)

	// Parse to trigger color initialization
	err = cmd.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	// For never mode, color.NoColor should be true
	assert.True(t, color.NoColor, "RA_COLOR=never should set color.NoColor=true")
}

func Test_RA_COLOR_Environment_Variable_CaseInsensitive(t *testing.T) {
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	testCases := []struct {
		value    string
		expected bool
		desc     string
	}{
		{"Auto", false, "Auto should work like auto"},
		{"ALWAYS", false, "ALWAYS should work like always"},
		{"Never", true, "Never should work like never"},
		{"NEVER", true, "NEVER should work like never"},
		{"always", false, "always should work like always"},
		{"auto", false, "auto should work like auto"},
	}

	for _, tc := range testCases {
		t.Run(tc.desc, func(t *testing.T) {
			t.Setenv("RA_COLOR", tc.value)

			cmd := NewCmd("test")
			_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
			assert.NoError(t, err)

			err = cmd.ParseOrError([]string{"value"})
			assert.NoError(t, err)

			if tc.value == "Auto" || tc.value == "auto" {
				// For auto mode, we can't easily test the exact behavior
				// but we verify the function completes without error
			} else {
				assert.Equal(t, tc.expected, color.NoColor, "Case insensitive %s should work", tc.value)
			}
		})
	}
}

func Test_RA_COLOR_Environment_Variable_InvalidValues(t *testing.T) {
	// Test that invalid values gracefully default to auto behavior
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	invalidValues := []string{
		"invalid",
		"true",
		"false",
		"1",
		"0",
		"yes",
		"no",
		"on",
		"off",
		"",
		"   ", // whitespace only
	}

	for _, invalidValue := range invalidValues {
		t.Run("invalid_value_"+invalidValue, func(t *testing.T) {
			t.Setenv("RA_COLOR", invalidValue)

			cmd := NewCmd("test")
			_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
			assert.NoError(t, err)

			// Parse should not fail even with invalid values
			err = cmd.ParseOrError([]string{"value"})
			assert.NoError(t, err)

			// Invalid values should be treated as auto (graceful degradation)
			// We can't easily test what auto does, but we verify no panic/error occurs
		})
	}
}

func Test_RA_COLOR_Environment_Variable_AffectsActualColorOutput(t *testing.T) {
	// Test that RA_COLOR settings actually affect the color output in usage text
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	cmd := NewCmd("test")
	cmd.SetDescription("Test color output")
	_, err := NewString("arg").SetUsage("Test argument").Register(cmd)
	assert.NoError(t, err)

	// Test with RA_COLOR=always (should include ANSI codes)
	t.Setenv("RA_COLOR", "always")
	err = cmd.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)
	assert.Contains(t, usage, "\033[32;1m", "RA_COLOR=always should produce ANSI color codes")
	assert.Contains(t, usage, "\033[36m", "RA_COLOR=always should produce cyan color codes")

	// Test with RA_COLOR=never (should not include ANSI codes)
	t.Setenv("RA_COLOR", "never")
	// Need to create new command to trigger re-initialization
	cmd2 := NewCmd("test")
	cmd2.SetDescription("Test color output")
	_, err = NewString("arg").SetUsage("Test argument").Register(cmd2)
	assert.NoError(t, err)

	err = cmd2.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	usage2 := cmd2.GenerateUsage(false)
	assert.NotContains(t, usage2, "\033[32;1m", "RA_COLOR=never should not produce ANSI color codes")
	assert.NotContains(t, usage2, "\033[36m", "RA_COLOR=never should not produce cyan color codes")
	assert.Contains(t, usage2, "Usage:", "RA_COLOR=never should still show usage text")
}

func Test_RA_COLOR_Environment_Variable_WithWhitespace(t *testing.T) {
	// Test that values with surrounding whitespace are handled correctly
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	testCases := []struct {
		value    string
		expected bool
		desc     string
	}{
		{"  never  ", true, "never with spaces should work"},
		{"\talways\t", false, "always with tabs should work"},
		{" auto ", false, "auto with spaces should work"},
		{"\n never \n", true, "never with newlines should work"},
	}

	for _, tc := range testCases {
		t.Run(tc.desc, func(t *testing.T) {
			t.Setenv("RA_COLOR", tc.value)

			cmd := NewCmd("test")
			_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
			assert.NoError(t, err)

			err = cmd.ParseOrError([]string{"value"})
			assert.NoError(t, err)

			if strings.TrimSpace(strings.ToLower(tc.value)) == "auto" {
				// For auto mode, we can't easily test the exact behavior
			} else {
				assert.Equal(t, tc.expected, color.NoColor, "Whitespace handling for %q should work", tc.value)
			}
		})
	}
}

func Test_RA_COLOR_Environment_Variable_Unset(t *testing.T) {
	// Test that when RA_COLOR is not set, behavior is unchanged (auto mode)
	originalColor := color.NoColor
	defer func() { color.NoColor = originalColor }()

	// Ensure RA_COLOR is not set
	t.Setenv("RA_COLOR", "")

	cmd := NewCmd("test")
	_, err := NewString("arg").SetUsage("Test arg").Register(cmd)
	assert.NoError(t, err)

	err = cmd.ParseOrError([]string{"value"})
	assert.NoError(t, err)

	// When unset (empty string), should behave like auto mode
	// We can't easily test what auto does, but we verify no panic/error occurs
}

func Test_IndividualUsageChunks_Description(t *testing.T) {
	// Test with description
	cmd := NewCmd("test")
	cmd.SetDescription("This is a test command")

	desc := cmd.GenerateDescription()
	expected := "This is a test command\n\n"
	assert.Equal(t, expected, desc)

	// Test without description
	cmdNoDesc := NewCmd("test2")
	descEmpty := cmdNoDesc.GenerateDescription()
	assert.Equal(t, "", descEmpty)
}

func Test_IndividualUsageChunks_Synopsis(t *testing.T) {
	cmd := NewCmd("test")

	// Add some flags to test synopsis generation
	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	_, err = NewBool("verbose").SetShort("v").SetUsage("Verbose mode").Register(cmd)
	assert.NoError(t, err)

	// Test short synopsis
	shortSynopsis := cmd.GenerateShortSynopsis()
	assert.Contains(t, shortSynopsis, "test")
	assert.Contains(t, shortSynopsis, "<input>")
	assert.Contains(t, shortSynopsis, "[OPTIONS]")

	// Test long synopsis (should be same in this case)
	longSynopsis := cmd.GenerateLongSynopsis()
	assert.Equal(t, shortSynopsis, longSynopsis)

	// Test explicit isLongHelp parameter
	synopsis := cmd.GenerateSynopsis(false)
	assert.Equal(t, shortSynopsis, synopsis)

	synopsis = cmd.GenerateSynopsis(true)
	assert.Equal(t, longSynopsis, synopsis)
}

func Test_IndividualUsageChunks_CommandsSection(t *testing.T) {
	cmd := NewCmd("parent")

	// Test without subcommands
	commandsSection := cmd.GenerateCommandsSection(false)
	assert.Equal(t, "", commandsSection)

	// Add subcommands
	subCmd1 := NewCmd("sub1")
	subCmd1.SetDescription("First subcommand")
	_, err := cmd.RegisterCmd(subCmd1)
	assert.NoError(t, err)

	subCmd2 := NewCmd("sub2")
	subCmd2.SetDescription("Second subcommand")
	_, err = cmd.RegisterCmd(subCmd2)
	assert.NoError(t, err)

	// Test with subcommands
	commandsSection = cmd.GenerateShortCommandsSection()
	assert.Contains(t, commandsSection, "Commands:")
	assert.Contains(t, commandsSection, "sub1")
	assert.Contains(t, commandsSection, "First subcommand")
	assert.Contains(t, commandsSection, "sub2")
	assert.Contains(t, commandsSection, "Second subcommand")

	// Test convenience methods
	assert.Equal(t, commandsSection, cmd.GenerateLongCommandsSection())
}

func Test_IndividualUsageChunks_ArgumentsSection(t *testing.T) {
	cmd := NewCmd("test")

	// Test without arguments
	argsSection := cmd.GenerateArgumentsSection(false)
	assert.Equal(t, "", argsSection)

	// Add some script-level flags
	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	_, err = NewBool("verbose").SetShort("v").SetUsage("Verbose mode").Register(cmd)
	assert.NoError(t, err)

	// Test with arguments
	argsSection = cmd.GenerateShortArgumentsSection()
	assert.Contains(t, argsSection, "Arguments:")
	assert.Contains(t, argsSection, "--input str")
	assert.Contains(t, argsSection, "Input file")
	assert.Contains(t, argsSection, "-v, --verbose")
	assert.Contains(t, argsSection, "Verbose mode")

	// Test convenience methods
	longArgsSection := cmd.GenerateLongArgumentsSection()
	assert.Equal(t, argsSection, longArgsSection)

	// Test explicit isLongHelp parameter
	assert.Equal(t, argsSection, cmd.GenerateArgumentsSection(false))
	assert.Equal(t, longArgsSection, cmd.GenerateArgumentsSection(true))
}

func Test_IndividualUsageChunks_GlobalOptionsSection(t *testing.T) {
	cmd := NewCmd("test")

	// Test without global options
	globalSection := cmd.GenerateGlobalOptionsSection(false)
	assert.Equal(t, "", globalSection)

	// Add global flags
	_, err := NewBool("debug").SetShort("d").SetUsage("Debug mode").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	_, err = NewString("config").SetUsage("Config file").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	// Test with global options
	globalSection = cmd.GenerateShortGlobalOptionsSection()
	assert.Contains(t, globalSection, "Global options:")
	assert.Contains(t, globalSection, "-d, --debug")
	assert.Contains(t, globalSection, "Debug mode")
	assert.Contains(t, globalSection, "--config str")
	assert.Contains(t, globalSection, "Config file")

	// Test convenience methods
	longGlobalSection := cmd.GenerateLongGlobalOptionsSection()
	assert.Equal(t, globalSection, longGlobalSection)

	// Test explicit isLongHelp parameter
	assert.Equal(t, globalSection, cmd.GenerateGlobalOptionsSection(false))
	assert.Equal(t, longGlobalSection, cmd.GenerateGlobalOptionsSection(true))
}

func Test_IndividualUsageChunks_HiddenFlags(t *testing.T) {
	cmd := NewCmd("test")

	// Add regular flag
	_, err := NewString("visible").SetUsage("Visible flag").Register(cmd)
	assert.NoError(t, err)

	// Add hidden flag
	_, err = NewString("hidden").SetUsage("Hidden flag").SetHidden(true).Register(cmd)
	assert.NoError(t, err)

	// Add flag hidden in short help only
	_, err = NewString("long-only").SetUsage("Long help only").SetHiddenInShortHelp(true).Register(cmd)
	assert.NoError(t, err)

	// Test short help - should exclude long-only flag
	shortArgs := cmd.GenerateShortArgumentsSection()
	assert.Contains(t, shortArgs, "visible")
	assert.NotContains(t, shortArgs, "hidden")
	assert.NotContains(t, shortArgs, "long-only")

	// Test long help - should include long-only flag but not hidden
	longArgs := cmd.GenerateLongArgumentsSection()
	assert.Contains(t, longArgs, "visible")
	assert.NotContains(t, longArgs, "hidden")
	assert.Contains(t, longArgs, "long-only")
}

func Test_IndividualUsageChunks_CombinedOutputMatchesOriginal(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Test application for comparing outputs")

	// Add various types of flags and subcommands
	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	_, err = NewBool("verbose").SetShort("v").SetUsage("Verbose mode").Register(cmd)
	assert.NoError(t, err)

	_, err = NewString("config").SetUsage("Config file").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	subCmd := NewCmd("sub")
	subCmd.SetDescription("A subcommand")
	_, err = cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	// Generate original usage
	originalShort := cmd.GenerateShortUsage()
	originalLong := cmd.GenerateLongUsage()

	// Generate using individual chunks
	var sb strings.Builder

	desc := cmd.GenerateDescription()
	if desc != "" {
		sb.WriteString(desc)
	}

	headers := cmd.getUsageHeaders()
	sb.WriteString(GreenBoldS(headers.Usage) + "\n  ")
	sb.WriteString(cmd.GenerateShortSynopsis())
	sb.WriteString("\n")

	commandsSection := cmd.GenerateShortCommandsSection()
	if commandsSection != "" {
		sb.WriteString(commandsSection)
	}

	argsSection := cmd.GenerateShortArgumentsSection()
	if argsSection != "" {
		sb.WriteString(argsSection)
	}

	globalSection := cmd.GenerateShortGlobalOptionsSection()
	if globalSection != "" {
		sb.WriteString(globalSection)
	}

	combinedShort := sb.String()

	// Test they match
	assert.Equal(t, originalShort, combinedShort)

	// Test long version too
	var sbLong strings.Builder

	desc = cmd.GenerateDescription()
	if desc != "" {
		sbLong.WriteString(desc)
	}

	sbLong.WriteString(GreenBoldS(headers.Usage) + "\n  ")
	sbLong.WriteString(cmd.GenerateLongSynopsis())
	sbLong.WriteString("\n")

	commandsSection = cmd.GenerateLongCommandsSection()
	if commandsSection != "" {
		sbLong.WriteString(commandsSection)
	}

	argsSection = cmd.GenerateLongArgumentsSection()
	if argsSection != "" {
		sbLong.WriteString(argsSection)
	}

	globalSection = cmd.GenerateLongGlobalOptionsSection()
	if globalSection != "" {
		sbLong.WriteString(globalSection)
	}

	combinedLong := sbLong.String()
	assert.Equal(t, originalLong, combinedLong)
}

func Test_IndividualUsageChunks_CustomHeaders(t *testing.T) {
	cmd := NewCmd("test")

	// Set custom headers
	customHeaders := UsageHeaders{
		Usage:         "How to use:",
		Commands:      "Available commands:",
		Arguments:     "Parameters:",
		GlobalOptions: "Global flags:",
	}
	cmd.SetUsageHeaders(customHeaders)

	// Add content to test headers
	_, err := NewString("input").SetUsage("Input file").Register(cmd)
	assert.NoError(t, err)

	_, err = NewString("global").SetUsage("Global flag").Register(cmd, WithGlobal(true))
	assert.NoError(t, err)

	subCmd := NewCmd("sub")
	subCmd.SetDescription("A subcommand")
	_, err = cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	// Test that custom headers appear in individual sections
	argsSection := cmd.GenerateArgumentsSection(false)
	assert.Contains(t, argsSection, "Parameters:")

	globalSection := cmd.GenerateGlobalOptionsSection(false)
	assert.Contains(t, globalSection, "Global flags:")

	commandsSection := cmd.GenerateCommandsSection(false)
	assert.Contains(t, commandsSection, "Available commands:")
}

func Test_Usage_RequiredArgWithEnumAndRegexConstraints(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test required arg with enum and regex constraints")

	// Required argument with both enum and regex constraints
	_, err := NewString("name").
		SetRegexConstraint(regexp.MustCompile(`^[A-Z][a-z]*$`)).
		SetEnumConstraint([]string{"Alice", "Bob"}).
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	// Should show enum values first, then regex pattern
	expected := `Test required arg with enum and regex constraints

Usage:
  test <name> [OPTIONS]

Arguments:
      --name str   Valid values: [Alice, Bob]. Regex: ^[A-Z][a-z]*$
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_StringFlagWithDefaultAndEnumConstraints_OrderingBehavior(t *testing.T) {
	cmd := NewCmd("test")
	cmd.SetDescription("Test ordering of default and enum constraints")

	// String flag with both default and enum constraints to confirm current behavior
	_, err := NewString("color").
		SetUsage("Control output colorization").
		SetDefault("auto").
		SetEnumConstraint([]string{"auto", "always", "never"}).
		Register(cmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	// Expected behavior: enum first, then default
	expected := `Test ordering of default and enum constraints

Usage:
  test [color] [OPTIONS]

Arguments:
      --color str   Control output colorization. Valid values: [auto, always, never] (default auto)
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
}

func Test_Usage_CustomSubcommandPlaceholder(t *testing.T) {
	cmd := NewCmd("myapp")
	cmd.SetDescription("Test custom subcommand placeholder")

	cmd.SetUsageHeaders(UsageHeaders{
		Usage:                 "Usage:",
		Commands:              "Commands:",
		Arguments:             "Arguments:",
		GlobalOptions:         "Global options:",
		SubcommandPlaceholder: "command",
	})

	subCmd := NewCmd("serve")
	subCmd.SetDescription("Start the server")
	_, err := cmd.RegisterCmd(subCmd)
	assert.NoError(t, err)

	usage := cmd.GenerateUsage(false)

	expected := `Test custom subcommand placeholder

Usage:
  myapp [command] [OPTIONS]

Commands:
  serve   Start the server
`

	assert.Equal(t, strings.TrimSpace(expected), strings.TrimSpace(usage))
	assert.NotContains(t, usage, "[subcommand]")
}

func Test_Usage_SynopsisTruncatesAfterCollectingPositional(t *testing.T) {
	// A list positional absorbs every remaining bare value, so the synopsis stops
	// there: "after" is real, but it can only be set by name.
	cmd := NewCmd("test")
	NewString("first").Register(cmd)
	NewStringSlice("tags").Register(cmd)
	NewString("after").Register(cmd)

	assert.Equal(t, "test <first> <tags...> [OPTIONS]", cmd.GenerateSynopsis(false))
}

func Test_Usage_FlagOnlyListDoesNotTruncateSynopsis(t *testing.T) {
	// A flag-only list takes no positionals, so it absorbs nothing and whatever
	// follows stays reachable. The variadic still shows "..." - it is greedy
	// after its own flag token.
	cmd := NewCmd("test")
	NewStringSlice("options").SetVariadic(true).SetFlagOnly(true).Register(cmd)
	NewString("target").SetFlagOnly(true).Register(cmd)

	assert.Equal(t, "test [options...] <target> [OPTIONS]", cmd.GenerateSynopsis(false))
}