tix-tracker 0.6.0

use std::fmt::Write;

use crate::keybindings::{EffectiveBindings, InputContext, KeyBindings, TuiAction};
use crate::ui::nav::TopMode;

pub const MODE_BOARD: &str = "board";
pub const MODE_DETAIL: &str = "detail";
pub const MODE_HELP: &str = "help";
pub const MODE_COMMENT: &str = "comment";
pub const MODE_ASSET: &str = "asset";
pub const MODE_FILTER: &str = "filter";

const MAX_HINT_CHARS: usize = 80;

pub struct Cmd {
    pub key: &'static str,
    pub desc: &'static str,
    pub modes: &'static [&'static str],
    pub mode: &'static str,
}

pub const COMMANDS: &[Cmd] = &[
    Cmd {
        key: "j/k",
        desc: "move up/down",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "n",
        desc: "new issue",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "?",
        desc: "help",
        modes: &[MODE_BOARD, MODE_DETAIL],
        mode: "board/detail",
    },
    Cmd {
        key: "h/l",
        desc: "column",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "enter",
        desc: "open",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "d",
        desc: "delete",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "< / >",
        desc: "move",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "r",
        desc: "refresh",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "/",
        desc: "search",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "f",
        desc: "criteria",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "c",
        desc: "comment",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
    Cmd {
        key: "a",
        desc: "asset",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
];

fn actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::NewIssue,
            TuiAction::Help,
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Planning,
            // #1399: the sub-issue toggle, so the key is discoverable from the
            // footer rather than only from the help overlay.
            TuiAction::ToggleChildren,
            TuiAction::Quit,
        ],
        InputContext::Detail => &[
            TuiAction::Comment,
            TuiAction::Asset,
            // #1513: the related-issues keys, placed early because the hint bar
            // truncates at 80 columns — a key listed after the relationship group
            // would never be drawn.
            TuiAction::RelatedPicker,
            TuiAction::FollowRelated,
            TuiAction::NavBack,
            // #1359: the three mutating relationship operations and the cursor that
            // names which edge `E` and `d` act on. A binding that exists but is not
            // in the footer is a binding nobody finds.
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
            TuiAction::Edit,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
        ],
        // The remaining top-level modes' footers. Each names a handful of the
        // bindings effective in that mode, so the hint bar follows the active mode
        // (tui-mode-navigation) instead of always describing the board.
        InputContext::Triage => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        // The F3 Cycle mode's own keys: the cycle listing, the group jump, the
        // way into planning management, help, and the way out.
        InputContext::Cycle => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F5 Milestones mode's footer: the registry cursor and the planning
        // commands, whose labels come from the Milestones context.
        InputContext::Milestones => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Planning,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Help,
            TuiAction::Close,
        ],
        InputContext::Form | InputContext::PlanningForm => &[
            TuiAction::Submit,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::OpenPicker,
            TuiAction::Cancel,
        ],
        InputContext::FormPicker => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Create,
            TuiAction::Cancel,
        ],
        InputContext::PlanningManagement => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Next,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Close,
        ],
        InputContext::Settings => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::AddColumn,
            TuiAction::Submit,
            TuiAction::NewBoard,
            TuiAction::EditPlanningItem,
            TuiAction::Delete,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Close,
        ],
        // The shell's own switches, so the mode navigation is discoverable from the
        // footer too.
        InputContext::Shell => &[
            TuiAction::SwitchToBoard,
            TuiAction::SwitchToTriage,
            TuiAction::SwitchToCycle,
            TuiAction::SwitchToMilestones,
            TuiAction::SwitchToNewIssue,
            TuiAction::SwitchToConfig,
            TuiAction::ToggleNavigation,
        ],
        _ => &[],
    }
}

/// The context whose bindings the hint bar advertises for a top-level mode.
///
/// Hints follow the active mode (tui-mode-navigation). `Detail` is handled by the
/// caller: it is a board-mode surface, so it keeps its own context.
pub const fn hint_context_for_mode(mode: TopMode) -> InputContext {
    match mode {
        TopMode::Board => InputContext::Board,
        TopMode::Triage => InputContext::Triage,
        TopMode::Cycle => InputContext::Cycle,
        TopMode::Milestones => InputContext::Milestones,
        TopMode::NewIssue => InputContext::Form,
        TopMode::Config => InputContext::Settings,
    }
}

pub fn hint_bar(active_modes: &[&str]) -> String {
    let bindings =
        KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
    for mode in active_modes {
        if let Some(context) = match *mode {
            MODE_BOARD => Some(InputContext::Board),
            MODE_DETAIL => Some(InputContext::Detail),
            _ => None,
        } {
            return hint_bar_for(&bindings, context);
        }
    }
    String::new()
}

pub fn hint_bar_for(bindings: &EffectiveBindings, context: InputContext) -> String {
    if context == InputContext::Board
        && bindings.label(context, TuiAction::MoveUp) == "Up / k"
        && bindings.label(context, TuiAction::MoveDown) == "Down / j"
    {
        return truncate(
            &format!(
                "j/k nav · {} new issue · {} help",
                bindings.label(context, TuiAction::NewIssue),
                bindings.label(context, TuiAction::Help),
            ),
            MAX_HINT_CHARS,
        );
    }
    let mut text = String::new();
    for action in actions(context) {
        let _ = write!(
            text,
            "{} {} · ",
            bindings.label(context, *action),
            action.description_in(context)
        );
    }
    truncate(text.trim_end_matches(" · "), MAX_HINT_CHARS)
}

/// The contexts the keybindings overlay documents, in reading order.
///
/// One list, shared with the completeness guard in this module's tests: a context
/// added to the overlay but not to the guard (or the reverse) is how a whole surface
/// becomes invisible in the help without anyone noticing. The overlay itself now
/// scopes its rows with [`contexts_for_mode`], so this list is the test-only record
/// of what must stay covered.
#[cfg(test)]
const HELP_CONTEXTS: [InputContext; 30] = [
    InputContext::Detail,
    InputContext::Board,
    InputContext::Rollover,
    InputContext::Form,
    InputContext::FormPicker,
    InputContext::ConfirmDelete,
    InputContext::MoveIntoDone,
    // WP04: the blocked-move prompt's keys belong in the help overlay too, or
    // a user who never guessed `y` has no way to learn it.
    InputContext::ConfirmBlockedMove,
    InputContext::Help,
    InputContext::HelpSearch,
    InputContext::ContextMenu,
    // #1513: the related-issues picker's keys. Listed here for the same reason
    // the other pickers are — a key nobody can discover is a key nobody uses.
    InputContext::RelatedPicker,
    InputContext::Filter,
    InputContext::FilterModal,
    InputContext::Settings,
    InputContext::SettingsPrompt,
    InputContext::PlanningManagement,
    InputContext::PlanningConfirm,
    InputContext::PlanningForm,
    InputContext::DatePicker,
    InputContext::Comment,
    InputContext::Asset,
    InputContext::LinkPrompt,
    InputContext::EditRepair,
    // #1510: the conflict prompt's keys, for the same reason the edit repair's
    // are listed — a key nobody can discover is a key nobody uses, and every one
    // of the three decisions is reachable only from this prompt.
    InputContext::EditConflict,
    // WP07: the batch surface's keys, for the same reason WP04 put the
    // blocked-move prompt's there — a key nobody can discover is a key nobody
    // uses, and the batch surface is entirely keyboard-driven.
    InputContext::BulkModal,
    // WP06: the triage inbox's keys, same reason. The `t` that opens it is
    // listed by the `board` rows below.
    InputContext::Triage,
    // The F3 Cycle mode's listing keys.
    InputContext::Cycle,
    // The F5 Milestones mode's listing keys.
    InputContext::Milestones,
    // The mode shell's switches and the navigation toggle (tui-mode-navigation).
    InputContext::Shell,
];

/// The contexts whose bindings the help overlay shows for a top-level mode.
///
/// Each top-level mode owns the contexts reachable from it, so `?` in the Cycle
/// mode lists cycle keys and not the board's. The shell's switches appear in every
/// mode, so the way out of a mode is always listed.
pub const fn contexts_for_mode(mode: TopMode) -> &'static [InputContext] {
    match mode {
        // The board and every overlay reachable from it: the detail pane, the
        // delete/rollover/blocked prompts, filter and search, the batch and triage
        // decision surfaces, and the two text prompts. They are the board's keys
        // because the board is where they are opened from.
        TopMode::Board => &[
            InputContext::Shell,
            InputContext::Board,
            InputContext::Detail,
            InputContext::Rollover,
            InputContext::ConfirmDelete,
            InputContext::MoveIntoDone,
            InputContext::ConfirmBlockedMove,
            InputContext::Help,
            InputContext::HelpSearch,
            InputContext::ContextMenu,
            // #1513: the related picker is a detail-pane overlay, so its keys are
            // documented among the board's.
            InputContext::RelatedPicker,
            InputContext::Filter,
            InputContext::FilterModal,
            InputContext::Comment,
            InputContext::Asset,
            InputContext::LinkPrompt,
            InputContext::EditRepair,
            // #1510: the conflict prompt is reachable from the board (an editor
            // round trip) and from nothing else, so its keys are documented there.
            InputContext::EditConflict,
            InputContext::BulkModal,
        ],
        TopMode::Triage => &[InputContext::Shell, InputContext::Triage],
        TopMode::Cycle => &[
            InputContext::Shell,
            InputContext::Cycle,
            InputContext::PlanningManagement,
            InputContext::PlanningConfirm,
            InputContext::PlanningForm,
            InputContext::DatePicker,
        ],
        // The Milestones mode is the Config surface pinned to the milestones
        // section: its own keys, the planning surfaces `m` opens, and the
        // settings-confirm prompt a milestone delete raises.
        TopMode::Milestones => &[
            InputContext::Shell,
            InputContext::Milestones,
            InputContext::PlanningManagement,
            InputContext::PlanningConfirm,
            InputContext::PlanningForm,
            InputContext::DatePicker,
            InputContext::SettingsPrompt,
        ],
        TopMode::NewIssue => &[
            InputContext::Shell,
            InputContext::Form,
            InputContext::FormPicker,
        ],
        TopMode::Config => &[
            InputContext::Shell,
            InputContext::Settings,
            InputContext::SettingsPrompt,
        ],
    }
}

pub fn help_overlay(bindings: &EffectiveBindings, mode: TopMode) -> Vec<(String, String, String)> {
    let mut rows = Vec::new();
    // The pointer rows describe the board's mouse affordances; a non-board mode has
    // none to advertise, so they are scoped to the Board mode like every other row.
    if mode == TopMode::Board {
        rows.extend([
            (
                "mouse click".to_string(),
                "click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse double".to_string(),
                "double-click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse right".to_string(),
                "right-click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse drag".to_string(),
                "drag".to_string(),
                "board".to_string(),
            ),
        ]);
    }
    for context in contexts_for_mode(mode) {
        for action in all_actions(*context) {
            rows.push((
                bindings.label(*context, *action),
                action.description_in(*context).to_string(),
                context.as_str().to_string(),
            ));
        }
    }
    rows
}

fn all_actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::Open,
            TuiAction::Edit,
            TuiAction::View,
            TuiAction::Agent,
            TuiAction::ToggleColumn,
            TuiAction::FilterModal,
            TuiAction::BulkModal,
            TuiAction::Triage,
            TuiAction::Mark,
            TuiAction::Unmark,
            TuiAction::MovePrevious,
            TuiAction::MoveNext,
            // The page keys (#1442): bound on the board, and until this guard existed
            // they were the only way to reach a card the column had scrolled past —
            // documented nowhere.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::NewIssue,
            // The two board keys added after this list was written: the overlay's list
            // is hand-written, so a binding it does not name is a key that works and
            // cannot be discovered. `every_bound_action_appears_in_the_overlay` is the
            // guard, and it is what found these.
            TuiAction::CloneIssue,
            TuiAction::ToggleArchived,
            // #1399: sub-issue visibility. The overlay's list is hand-written, so a
            // binding it does not name is a key that works and cannot be discovered;
            // `every_bound_action_appears_in_the_overlay` is the guard.
            TuiAction::ToggleChildren,
            TuiAction::Delete,
            TuiAction::Refresh,
            TuiAction::Settings,
            TuiAction::Planning,
            TuiAction::NewBoard,
            TuiAction::Help,
            TuiAction::Quit,
            TuiAction::TextFilter,
            TuiAction::ReorderUp,
            TuiAction::ReorderDown,
        ],
        InputContext::Detail => &[
            // The pane's own list, not the footer's: `close` is how you get back, and a
            // key that returns you is not one to leave out of the reference.
            TuiAction::Close,
            TuiAction::Edit,
            TuiAction::View,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
            TuiAction::Comment,
            TuiAction::Asset,
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
            // #1513: the related-issues surface. The overlay's list is hand-written,
            // so a binding it does not name is a key that works and cannot be
            // discovered; `every_bound_action_appears_in_the_overlay` is the guard.
            TuiAction::RelatedPicker,
            TuiAction::FollowRelated,
            TuiAction::NavBack,
        ],
        InputContext::RelatedPicker => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
        ],
        InputContext::Rollover => &[TuiAction::Submit, TuiAction::Previous, TuiAction::Cancel],
        InputContext::Form | InputContext::PlanningForm => &[
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::OpenPicker,
        ],
        InputContext::FormPicker => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Create,
        ],
        InputContext::ConfirmDelete
        | InputContext::PlanningConfirm
        | InputContext::ConfirmBlockedMove => &[TuiAction::Confirm, TuiAction::Cancel],
        InputContext::MoveIntoDone
        | InputContext::Filter
        | InputContext::Comment
        | InputContext::Asset
        | InputContext::LinkPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::Help => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            // #1496: the search key, so the overlay names the way to search it.
            TuiAction::TextFilter,
            // #1441/#1442: the overlay's page keys. These are the overlay's *rows*, not
            // a footer — the footer for this context is the hint bar `render_help` draws
            // underneath, which is the board's or the pane's.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Submit,
        ],
        InputContext::ContextMenu => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
        ],
        // Free text: `Esc` leaves the line (and clears it), `Enter` keeps the query.
        InputContext::HelpSearch => &[TuiAction::Cancel, TuiAction::Submit],
        InputContext::BulkModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        // WP06: only what the context actually binds. The inbox's decision keys
        // (`a`, `d`, `u`, `f`, `p`, `y`) are deliberately unbound so they stay
        // typeable in a reason field, so they cannot appear here as chords —
        // they are named by the modal's own footer instead, which is how the
        // batch surface names its unbound keys too.
        InputContext::Triage => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        InputContext::Cycle => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        InputContext::FilterModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Reset,
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::OpenPicker,
        ],
        // The F5 Milestones mode: the same registry keys the Cycle listing uses,
        // plus the create/edit/delete commands the planning rows support.
        InputContext::Milestones => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Submit,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        InputContext::Settings => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::AddColumn,
            TuiAction::Submit,
            TuiAction::NewBoard,
            TuiAction::EditPlanningItem,
            TuiAction::Delete,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Close,
        ],
        InputContext::SettingsPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::PlanningManagement => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Next,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Close,
        ],
        InputContext::DatePicker => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::PreviousMonth,
            TuiAction::NextMonth,
            TuiAction::PreviousYear,
            TuiAction::NextYear,
            TuiAction::Submit,
            TuiAction::Reset,
            TuiAction::Cancel,
        ],
        // #1506: the repair prompt's five decisions. `confirm` applies the
        // proposed fix (which for an unknown key is the declaration), `declare_key`
        // writes `[custom_attributes]` explicitly, `reedit` reopens the editor on
        // the retained copy, `ignore` acknowledges and keeps it, and `discard`
        // removes it behind a second confirmation. The modal's own footer
        // advertises them too, but the overlay is where a key nobody guessed
        // becomes discoverable.
        InputContext::EditRepair => &[
            TuiAction::Confirm,
            TuiAction::DeclareKey,
            TuiAction::Reedit,
            TuiAction::Ignore,
            TuiAction::Discard,
        ],
        // #1510: the conflict prompt's three decisions. Same actions as the edit
        // warning because they are the same kinds of decision, different words
        // because they do different things here (see `description_in`).
        InputContext::EditConflict => &[TuiAction::Reedit, TuiAction::Ignore, TuiAction::Confirm],
        InputContext::Shell => &[
            TuiAction::SwitchToBoard,
            TuiAction::SwitchToTriage,
            TuiAction::SwitchToCycle,
            TuiAction::SwitchToMilestones,
            TuiAction::SwitchToNewIssue,
            TuiAction::SwitchToConfig,
            TuiAction::ToggleNavigation,
        ],
    }
}

fn truncate(value: &str, max_chars: usize) -> String {
    if max_chars == 0 || value.chars().count() <= max_chars {
        return value.to_string();
    }
    let take = max_chars.saturating_sub(1);
    let head: String = value.chars().take(take).collect();
    format!("{}…", head.trim_end())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every action a documented context binds must appear in the overlay.
    ///
    /// `all_actions` is written by hand per context, so a binding can be added to the
    /// keymap and never appear in the help — the worst of both worlds, because the key
    /// works and nobody can discover it. It had already happened twice before this
    /// guard existed (`clone_issue` and `toggle_archived`, both added while this list
    /// was not).
    #[test]
    fn every_bound_action_appears_in_the_overlay() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let mut missing: Vec<String> = Vec::new();
        for context in HELP_CONTEXTS {
            let listed = all_actions(context);
            for action in bindings.bound_actions(context) {
                if !listed.contains(&action) {
                    missing.push(format!("{} — {}", context.as_str(), action.as_str()));
                }
            }
        }
        assert!(
            missing.is_empty(),
            "the overlay does not list these bound actions, so nothing in the help \
             would tell a user they exist:\n  {}",
            missing.join("\n  ")
        );
    }

    /// Every row a mode's help draws comes from a context that mode owns, and the
    /// union over all modes still covers every documented context.
    #[test]
    fn the_overlay_and_its_guard_cover_the_same_contexts() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let drawn: Vec<(String, String, String)> = TopMode::ALL
            .iter()
            .flat_map(|mode| help_overlay(&bindings, *mode))
            .collect();
        for context in HELP_CONTEXTS {
            let scope = context.as_str();
            assert!(
                drawn.iter().any(|(_, _, listed)| listed == scope),
                "`{scope}` is in HELP_CONTEXTS but contributes no rows to any mode's overlay"
            );
        }
    }

    /// Help is scoped to the active mode: every row's scope belongs to that mode's
    /// contexts, and a binding only the board has is absent elsewhere.
    #[test]
    fn help_is_scoped_to_the_active_mode() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        for mode in TopMode::ALL {
            let allowed: Vec<&str> = contexts_for_mode(mode).iter().map(|c| c.as_str()).collect();
            for (key, description, scope) in help_overlay(&bindings, mode) {
                assert!(
                    allowed.contains(&scope.as_str()),
                    "{mode:?} help shows `{key} {description}` from out-of-scope `{scope}`"
                );
            }
        }
        // `toggle column` is a board-only action; the cycle mode's help must not
        // offer it.
        let cycle = help_overlay(&bindings, TopMode::Cycle);
        assert!(
            !cycle
                .iter()
                .any(|(_, description, _)| description == "toggle column"),
            "cycle help must not list board bindings: {cycle:?}"
        );
        // …while the board's own help does list it.
        let board = help_overlay(&bindings, TopMode::Board);
        assert!(
            board
                .iter()
                .any(|(_, description, _)| description == "toggle column")
        );
        // The navigation switch is part of every mode's help.
        for mode in TopMode::ALL {
            let rows = help_overlay(&bindings, mode);
            assert!(
                rows.iter()
                    .any(|(_, description, _)| description == "toggle navigation"),
                "{mode:?} help must list the navigation control"
            );
        }
    }

    #[test]
    fn dynamic_hint_uses_effective_aliases() {
        let mut overrides = KeyBindings::default();
        overrides.board.new_issue = Some(vec!["ctrl+n".into(), "f4".into()]);
        overrides.board.help = Some(vec!["f1".into()]);
        let bindings = KeyBindings::resolve(&overrides).unwrap();
        let hint = hint_bar_for(&bindings, InputContext::Board);
        assert!(hint.contains("Ctrl+n / F4 new issue"), "got {hint:?}");
        assert!(hint.contains("F1 help"), "got {hint:?}");
    }

    /// The hint bar follows the active mode rather than always describing the board.
    #[test]
    fn hints_follow_the_active_mode() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let board = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Board));
        let triage = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Triage));
        let config = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Config));
        assert!(board.contains("new issue"), "got {board:?}");
        assert!(
            triage.contains("toggle") && !triage.contains("new issue"),
            "triage hint should describe triage, got {triage:?}"
        );
        assert!(
            config.contains("add column") && !config.contains("new issue"),
            "config hint should describe settings, got {config:?}"
        );
    }

    #[test]
    fn help_covers_every_configured_action() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        let rows: Vec<(String, String, String)> = TopMode::ALL
            .iter()
            .flat_map(|mode| help_overlay(&bindings, *mode))
            .collect();
        for context in InputContext::ALL {
            for action in all_actions(*context) {
                assert!(
                    rows.iter().any(|(_, description, mode)| description
                        == action.description_in(*context)
                        && mode == context.as_str()),
                    "{} / {} is not listed by any mode's help",
                    context.as_str(),
                    action.as_str()
                );
            }
        }
    }
}