canon

type Breakout struct {
	From   string `yaml:"from"`
	Plugin string `yaml:"plugin"`
	To     string `yaml:"to"`
	Since  string `yaml:"since"`
}

type Confirm struct {
	Flags []string  `yaml:"flags"`
	Plan  *PlanForm `yaml:"plan"`
}

type Entry struct {
	// Canon is the status (D4). Empty means subcommand at depth >= 2.
	Canon string `yaml:"canon"`
	// Target is the canonical path (without "nself ") a deprecated-shim runs.
	Target string `yaml:"target"`
	// SideEffect is the class of running the command with default flags (D5).
	SideEffect string `yaml:"side_effect"`
	// Output is the output kind (D6); empty means document.
	Output string `yaml:"output"`
	// JSON is the pre-contract JSON support, legacy or none (D7). "envelope"
	// is never declared: it is derived from the registered data types.
	JSON string `yaml:"json"`
	// ExitCodes documents state exit codes in v1.4 mode (keys "0".."125").
	ExitCodes map[string]string `yaml:"exit_codes"`
	// ExitCodesV15 documents state exit codes in v1.5 mode (D10).
	ExitCodesV15 map[string]string `yaml:"exit_codes_v15"`
	// Flags maps a flag name to the escalation it causes when set.
	Flags      map[string]FlagOverride `yaml:"flags"`
	Confirm    *Confirm                `yaml:"confirm"`
	Surface    string                  `yaml:"surface"`
	SecretArgs []string                `yaml:"secret_args"`
	// Mode is empty (the entry exists in both modes) or "v1.4" (it exists only
	// in v1.4 mode: break-outs, removed commands, shim and retired-hub sources).
	Mode string `yaml:"mode"`
}

type File struct {
	// SchemaVersion is the canon.yaml schema version (1).
	SchemaVersion int `yaml:"schema_version"`
	// Verbs lists the ADR 0016 core verbs in ADR order (at most MaxVerbs).
	Verbs []string `yaml:"verbs"`
	// Commands maps a command path without the leading "nself " to its entry.
	Commands map[string]Entry `yaml:"commands"`
	// Rows are the move rows of contract:cli.canon-fragments v1.
	Rows `yaml:",inline"`
	// contains filtered or unexported fields
}

type FlagOverride struct {
	// SideEffect escalates the command's class; it must outrank the command's.
	SideEffect string `yaml:"side_effect"`
	// JSON overrides the command's JSON support: legacy or none.
	JSON string `yaml:"json"`
	// Output is empty or "stream" (D6, invalidation 2026-09-30): the only
	// flag-level output value, allowed on a command whose output is document.
	Output  string `yaml:"output"`
	CLIOnly bool   `yaml:"cli_only"`
	Secret  bool   `yaml:"secret"`
}

type Fragment struct {
	SchemaVersion int              `yaml:"schema_version"`
	Commands      map[string]Entry `yaml:"commands"`
	Rows          `yaml:",inline"`
}

type Hub struct {
	Path    string `yaml:"path"`
	Summary string `yaml:"summary"`
}

type PlanForm struct {
	Flag   string `yaml:"flag"`
	IDFlag string `yaml:"id_flag"`
}

type Removed struct {
	From    string `yaml:"from"`
	Since   string `yaml:"since"`
	Message string `yaml:"message"`
}

type Row struct {
	From string `yaml:"from"`
	To   string `yaml:"to"`
	// Since is the release that introduces the new spelling (vX.Y.Z).
	Since string `yaml:"since"`
	// RemovalAt is the release that removes the old spelling (vX.Y.Z, after Since).
	RemovalAt string `yaml:"removal_at"`
	// Equivalence names the Go test proving a shim equals its target (shims only).
	Equivalence string `yaml:"equivalence"`
}

type Rows struct {
	// Hubs are non-runnable hubs the engine creates in v1.5 mode.
	Hubs []Hub `yaml:"hubs"`
	// Moves relocate a command with its subtree (From old path, To canonical).
	Moves []Row `yaml:"moves"`
	// Shims replace an old command with a forward to an equivalent command.
	Shims []Row `yaml:"shims"`
	// RetiredHubs turn an emptied old hub into a stub forwarding to To.
	RetiredHubs []Row `yaml:"retired_hubs"`
	// Builtins are hidden framework commands (canon builtin in v1.5).
	Builtins []string `yaml:"builtins"`
	// Breakouts leave the core tree for a plugin in v1.5 mode.
	Breakouts []Breakout `yaml:"breakouts"`
	// Removed lists commands removed in v1.5 with the message to print.
	Removed []Removed `yaml:"removed"`
}

type Table struct {
	Verbs       []string
	Moves       []TableRow
	Shims       []TableRow
	RetiredHubs []TableRow
	Hubs        []TableRow
	Builtins    [][]string
	Breakouts   []TableRow
	Removed     []TableRow
}

type TableRow struct {
	From      []string
	To        []string
	Since     string
	RemovalAt string
	Plugin    string // breakouts: the plugin that now owns the command
	Message   string // removed: the text E410 prints
	Summary   string // hubs: the one-line summary (From holds the hub path)
}

type ValidationError struct {
	// Problems are sorted, one per violated rule instance.
	Problems []string
}