rituals 0.2.0

//! Building the `clap::Command` tree for a task, leaf or bundle, without
//! recursion, so nesting depth never becomes stack depth.

use super::{Body, Task};

/// One `clap::Command` still being built, paired with an iterator over the
/// children it has not yet attached — the state [`declare_tree`]'s explicit
/// stack carries per level of nesting.
struct Frame<'a> {
    command: clap::Command,
    remaining: std::slice::Iter<'a, (&'static str, Task)>,
}

/// Builds the `clap::Command` `task` mounts under `name` — recursively in
/// shape, iteratively in implementation: a leaf's command is built and
/// returned directly, and a bundle's tree is built with an explicit stack
/// of [`Frame`]s, post-order, rather than a recursive call per level.
///
/// The loop has no fixed iteration limit because it does not need one: the
/// tree it walks is finite by construction. A [`Task`]'s
/// children are owned, not shared — `Task` is neither `Clone` nor reachable
/// behind an `Rc` — so no task can contain itself, and each iteration either
/// attaches one already-built leaf command or consumes one child from a
/// finite, already-built `Vec` (`Task::group` collects `children` into a
/// `Vec` before this function ever sees it). There is no path through this
/// loop that does not shrink the work left to do.
pub(super) fn declare_tree(task: &Task, name: &'static str) -> clap::Command {
    let children = match &task.body {
        Body::Handler { augment, .. } => return declare_leaf(*augment, task.about, name),
        Body::Children(children) => children,
    };

    let root = clap::Command::new(name)
        .about(task.about)
        .subcommand_required(true)
        .arg_required_else_help(true);
    let mut stack = vec![Frame {
        command: root,
        remaining: children.iter(),
    }];

    loop {
        let Some(frame) = stack.last_mut() else {
            // The loop only ever returns, below, before the stack is
            // popped down to empty.
            unreachable!("declare_tree's stack is never left empty without returning first");
        };

        let Some((child_name, child_task)) = frame.remaining.next() else {
            // This frame's children are all attached: pop it and attach its
            // finished command to its parent frame, or return it directly
            // when it was the root (the stack is now empty).
            let finished = stack
                .pop()
                .unwrap_or_else(|| unreachable!("just matched Some(frame) on this same stack"));
            let Some(parent) = stack.last_mut() else {
                return finished.command;
            };
            parent.command = std::mem::take(&mut parent.command).subcommand(finished.command);
            continue;
        };

        match &child_task.body {
            Body::Handler { augment, .. } => {
                let child_command = declare_leaf(*augment, child_task.about, child_name);
                frame.command = std::mem::take(&mut frame.command).subcommand(child_command);
            }
            Body::Children(grandchildren) => {
                let child_command = clap::Command::new(*child_name)
                    .about(child_task.about)
                    .subcommand_required(true)
                    .arg_required_else_help(true);
                stack.push(Frame {
                    command: child_command,
                    remaining: grandchildren.iter(),
                });
            }
        }
    }
}

/// Builds a leaf task's own `clap::Command`: its declared arguments, named
/// `name`, whose only description is `about`, in `-h` and in `--help` alike.
///
/// `augment` runs first, and then `about` is applied and `long_about` is
/// cleared: the argument struct's doc comment is for readers of the code, yet
/// `#[derive(clap::Args)]` makes it the command's about and, when it has more
/// than one paragraph, its `long_about` too, which `--help` prefers to `about`.
fn declare_leaf(
    augment: fn(clap::Command) -> clap::Command,
    about: &'static str,
    name: &'static str,
) -> clap::Command {
    augment(clap::Command::new(name))
        .about(about)
        .long_about(None::<&str>)
}

#[cfg(test)]
mod tests {
    use super::declare_tree;
    use crate::task::Task;
    use crate::test_support::run_ok;

    #[test]
    fn declare_tree_on_a_leaf_is_unchanged_from_a_plain_command() {
        let task = Task::new("say hello", run_ok);
        let command = declare_tree(&task, "greet");
        assert_eq!(command.get_name(), "greet");
        assert_eq!(
            command.get_about().map(ToString::to_string),
            Some("say hello".to_string())
        );
        assert_eq!(command.get_subcommands().count(), 0);
    }

    /// A group's `clap::Command` lists its children as subcommands, in the
    /// order they were given to `Task::group`, each carrying its own about
    /// text — not the bundle's.
    #[test]
    fn declare_tree_on_a_group_lists_its_children_in_order_with_their_own_about() {
        let bundle = Task::group(
            "a bundle",
            [
                ("first", Task::new("the first child", run_ok)),
                ("second", Task::new("the second child", run_ok)),
            ],
        );
        let command = declare_tree(&bundle, "bundle");

        let names: Vec<&str> = command
            .get_subcommands()
            .map(clap::Command::get_name)
            .collect();
        assert_eq!(names, ["first", "second"]);

        let abouts: Vec<Option<String>> = command
            .get_subcommands()
            .map(|subcommand| subcommand.get_about().map(ToString::to_string))
            .collect();
        assert_eq!(
            abouts,
            [
                Some("the first child".to_string()),
                Some("the second child".to_string()),
            ]
        );
    }

    /// A leaf whose argument struct's doc comment has two paragraphs. Those
    /// docs are for readers of the code, yet `derive(clap::Args)` makes the
    /// first the command's `about` and, because there is a second, the whole
    /// doc its `long_about`.
    fn documented_command() -> clap::Command {
        /// The first paragraph of the argument struct's doc.
        ///
        /// The second paragraph of the argument struct's doc, which makes clap
        /// set a long description as well as a short one.
        #[derive(clap::Args)]
        struct TwoParagraphArguments {
            /// A value to carry.
            #[arg(long)]
            value: Option<String>,
        }
        let task = Task::new(
            "the task's own about",
            |_arguments: TwoParagraphArguments| Ok(()),
        );
        declare_tree(&task, "greet")
    }

    /// Verifies a leaf's description is the task's `about` and nothing else:
    /// declares a leaf whose argument struct has a two-paragraph doc comment,
    /// renders both `-h` (short) and `--help` (long) help, and asserts the
    /// description line is the task's about and no word of the struct doc
    /// appears. Long help is the case a multi-paragraph doc reaches, because it also
    /// sets `long_about`, which `--help` prefers to `about`.
    #[test]
    fn a_leafs_help_describes_the_task_and_never_its_argument_structs_doc() {
        let task_about = "the task's own about";
        for (label, render) in [
            (
                "-h",
                clap::Command::render_help as fn(&mut clap::Command) -> _,
            ),
            ("--help", clap::Command::render_long_help),
        ] {
            let mut command = documented_command();
            let rendered = render(&mut command).to_string();
            assert_eq!(
                rendered.lines().next(),
                Some(task_about),
                "expected `{label}` to open with the task's about and nothing else; \
                 it was:\n{rendered}"
            );
            for leaked in [
                "first paragraph",
                "second paragraph",
                "argument struct's doc",
            ] {
                assert!(
                    !rendered.contains(leaked),
                    "expected `{label}` not to carry the argument struct's doc ({leaked:?}); \
                     it was:\n{rendered}"
                );
            }
        }
    }

    /// Nesting is not limited to one level: a grandchild's command is
    /// attached under its own parent, not under the outer bundle directly.
    #[test]
    fn declare_tree_on_a_two_level_group_puts_the_grandchild_under_the_child() {
        let inner = Task::group("inner bundle", [("leaf", Task::new("a leaf", run_ok))]);
        let outer = Task::group("outer bundle", [("inner", inner)]);
        let command = declare_tree(&outer, "outer");

        let top_names: Vec<&str> = command
            .get_subcommands()
            .map(clap::Command::get_name)
            .collect();
        assert_eq!(top_names, ["inner"]);

        let inner_command = command
            .get_subcommands()
            .find(|subcommand| subcommand.get_name() == "inner");
        assert!(inner_command.is_some(), "expected an `inner` subcommand");
        if let Some(inner_command) = inner_command {
            let grandchild_names: Vec<&str> = inner_command
                .get_subcommands()
                .map(clap::Command::get_name)
                .collect();
            assert_eq!(grandchild_names, ["leaf"]);
        }
    }
}