// 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
	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
}

// 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
	CommandAliases []CommandAlias
	FlagAliases    []FlagAlias
}

// Failure is a neutral parsing or presentation failure.
type Failure struct {
	Message string
	Usage   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
	Operands      []string
	Failure       *Failure
}

// ParseOptions makes parser context and streams explicit.
type ParseOptions struct {
	Context     context.Context
	In          io.Reader
	Out         io.Writer
	Err         io.Writer
	FlagAliases []FlagAlias
}