documentor

type BuildData struct {
	// CanBuild maps a builder's UnitName → the raw ordered list of
	// canbuild units from sidedata.tdf (unannotated).
	CanBuild map[string][]string

	// MenuEntries is the flat list of every [MENUENTRY] across every
	// download/*.tdf, preserving the source filename for tracing.
	MenuEntries []MenuEntry

	// Slots is the merged builder → slot list (page/button derived).
	Slots map[string][]BuildSlot
}

type BuildPage struct {
	Page  int               // 1-indexed page number
	Slots map[int]BuildSlot // button (0..5) → slot
}

type BuildSideView struct {
	Side       string
	Label      string
	SideAnchor string
	Total      int
	Tiers      []BuildTierGroup
}

type BuildSlot struct {
	Page   int // 1-indexed
	Button int // 0..5
	Unit   string
	Source string
}

type BuildTierGroup struct {
	Key      CategoryKey
	Heading  string // e.g. "Arm — Commander"
	Anchor   string // GitHub slug for the heading
	Builders []BuilderView
}

type BuildTreeView struct {
	TotalBuilders int
	TotalPairs    int
	DownloadPairs int
	Sides         []BuildSideView
	Reverse       []ReverseSideView
	Unbuildable   []string // unit names that no builder reaches

	// UnitByKey lets slot-rendering helpers in the template resolve a
	// slot's UnitName to its display data without threading the map
	// through every nested call.
	UnitByKey map[string]Unit
}

type BuilderView struct {
	Builder       string
	Unit          Unit
	Pages         []BuildPage // sorted by Page
	Total         int
	DownloadCount int
}

type CategoryGroup struct {
	Key     CategoryKey
	Heading string // full heading text, e.g. "ARM — Commander"
	Anchor  string // GitHub-style slug for the heading
	Units   []Unit
}

type CategoryKey struct {
	Sort  string // e.g. "00", "10", … (controls render order)
	Label string // section heading
}

type Dataset struct {
	Game      Game
	Units     []Unit
	UnitByKey map[string]Unit // keyed by uppercased UnitName

	Weapons     []Weapon
	WeaponByKey map[string]Weapon // keyed by uppercased NameKey

	Build BuildData
}

type Game string

type MenuEntry struct {
	Builder string // UNITMENU=
	Menu    int    // MENU= (1-indexed page)
	Button  int    // BUTTON= (0..5)
	Unit    string // UNITNAME=
	Source  string // basename of the file the entry came from
}

type Options struct {
	// Game selects which title to document. Default: GameTotalA.
	Game Game

	// Source is the path to the flattened install (the same shape
	// "kbot mount --flatten" produces).
	Source string

	// Target is the root of the reference repo to write into.
	// <prefix>-*.md files land at Target/; portraits at
	// Target/img/<prefix>-units/. Prefix is "ta" or "tak" per game.
	Target string

	// SkipPortraits disables the unitpics/*.pcx → PNG batch step.
	SkipPortraits bool

	// PortraitsSkipExisting avoids re-converting portraits that already
	// exist at the destination. Default true; pass false to force a
	// fresh batch.
	PortraitsSkipExisting bool

	// Logger writes one-line progress messages.  Pass nil to silence.
	Logger func(format string, args ...any)
}

type PortraitResult struct {
	Converted int
	Skipped   int // already present and Skip mode enabled
	Failed    int
}

type ReverseEntry struct {
	Unit     Unit   // the buildable target
	Builders []Unit // resolved builder Unit records
}

type ReverseSideView struct {
	Side    string
	Label   string
	Total   int
	Entries []ReverseEntry
}

type SideView struct {
	Side       string // "ARM" / "CORE" / "OTHER"
	Label      string // "Arm" / "Core" / "Other"
	SideAnchor string // GitHub-style anchor for the side heading
	Total      int
	Groups     []CategoryGroup // already sorted by Key.Sort
}

type Unit struct {
	File        string
	UnitName    string
	Side        string
	Name        string
	Description string
	Designation string
	Objectname  string
	Category    string
	TEDClass    string

	// TA dual-resource cost (empty on TA:K).
	BuildMetal  string
	BuildEnergy string
	// TA:K single-resource cost (empty on TA).
	BuildCost string

	BuildTime string
	MaxDamage string

	// TA-style weapon name refs (empty on TA:K which inlines weapons).
	Weapon1 string
	Weapon2 string
	Weapon3 string

	// TA:K inline weapons (empty on TA).
	InlineWeapons []Weapon

	IsFeature string
	Commander string
}

type UnitsView struct {
	TotalUnits int
	Sides      []SideView
}

type Weapon struct {
	File          string // source filename
	NameKey       string // [SECTION_NAME] — the key units refer to (TA) or "[WEAPONn]" (TA:K)
	Display       string // "name=" field
	ID            string
	Range         string
	Reload        string
	Velocity      string
	AOE           string
	DefaultDamage string
	Archetypes    []string // ballistic, lineofsight, … (TA); or just "type=" (TA:K)
	RenderType    string

	// Owner is the UnitName whose FBI carries this weapon as an inline
	// sub-section. Empty for TA weapons (which live in their own TDFs).
	Owner string
}

type WeaponGroup struct {
	Key     CategoryKey
	Weapons []Weapon
}

type WeaponUserMap map[string][]string

type WeaponsView struct {
	TotalWeapons    int
	UnitsWithWeapon int
	Groups          []WeaponGroup
	UserMap         WeaponUserMap   // key → sorted list of unit names
	UserKeys        []string        // sorted keys of UserMap
	Defined         map[string]bool // weapon key → defined-here flag
}