// Package commandmeta owns the neutral metadata exchanged by CommandKit and
// its command-line backend.
package commandmeta

import (
	"context"
	"io"
)

// Key identifies one command inside one routing snapshot.
type Key uint64

// Command describes one node in a neutral command tree.
type Command struct {
	Key         Key
	Name        string
	Summary     string
	Description string
	Runnable    bool
	Flags       []Flag
	// CoreFlags are parsed by CommandKit but do not occupy consumer binding indexes.
	CoreFlags []Flag
	Arguments []Argument
	Children  []*Command
}

// Argument describes one positional input for usage rendering.
type Argument struct {
	Name  string
	Usage string
	Min   int
	Max   int
}

// Flag describes one local option without exposing a backend value.
type Flag struct {
	Name     string
	Short    string
	Usage    string
	Default  string
	Boolean  bool
	Repeated bool
	Required bool
}

var reportingFlags = [...]Flag{
	{Name: "quiet", Usage: "suppress substantive output and optional messages; keep failures visible", Default: "false", Boolean: true},
	{Name: "verbose", Usage: "show warning and informational messages", Default: "false", Boolean: true},
	{Name: "debug", Usage: "show debugging messages", Default: "false", Boolean: true},
	{Name: "progress", Usage: "show progress messages", Default: "false", Boolean: true},
}

// ReportingFlags returns the flags shared by CommandKit's invocation reporter.
func ReportingFlags() []Flag { return append([]Flag(nil), reportingFlags[:]...) }

// IsReportingFlag reports whether name is reserved for a shared reporting flag.
func IsReportingFlag(name string) bool {
	for _, flag := range reportingFlags {
		if flag.Name == name {
			return true
		}
	}
	return false
}

// FlagAlias maps one option spelling to a canonical flag spelling.
type FlagAlias struct {
	Source string
	Target string
}

// CommandAlias describes one explicitly declared command route for help.
type CommandAlias struct {
	Source []string
	Target []string
}

// HelpView selects a canonical or alias-only command help presentation.
type HelpView struct {
	EnteredPath    []string
	CanonicalPath  []string
	Discovery      bool
	CoreFlags      []Flag
	CommandAliases []CommandAlias
	FlagAliases    []FlagAlias
}

// Failure is a neutral parsing or presentation failure.
type Failure struct {
	Message string
	Usage   bool
}

// FlagOccurrence records one parsed spelling and its unconverted value.
type FlagOccurrence struct {
	Name     string // canonical flag name
	Spelling string // entered long spelling or individual short spelling
	RawValue string // unconverted value collected by the parser
}

// ReportingMode selects visibility for shared reporting messages.
type ReportingMode uint8

const (
	ReportingModeNormal ReportingMode = iota
	ReportingModeQuiet
	ReportingModeVerbose
	ReportingModeDebug
)

// ReportingSelection contains the resolved reporting options for one parse.
type ReportingSelection struct {
	Mode        ReportingMode
	Progress    bool
	ProgressSet bool
}

// Result contains the selected command and raw input collected by the adapter.
type Result struct {
	Key             Key
	Path            []string
	HelpRequested   bool
	FlagValues      [][]string
	FlagSpellings   [][]string
	FlagOccurrences []FlagOccurrence
	Reporting       ReportingSelection
	Operands        []string
	Failure         *Failure
}

// ParseOptions makes parser context and streams explicit.
type ParseOptions struct {
	// FlagAliasesForPath selects aliases for the actual parser context when
	// routing has not already selected one. It overrides FlagAliases when set.
	FlagAliasesForPath func([]string) []FlagAlias
	Context            context.Context
	In                 io.Reader
	Out                io.Writer
	Err                io.Writer
	FlagAliases        []FlagAlias
}