dev_prune/commands/

man.rs

// Copyright 2026 VKrishna04
// SPDX-License-Identifier: Apache-2.0

// Handler for `devp man`.
//
// The pages are rendered from the same clap definition the binary parses arguments
// with — the same `long_about` texts `--help` prints — so a flag cannot exist in the
// manual and be missing from the program, or the other way round. That is the whole
// reason this is a subcommand rather than checked-in roff files that go stale.

use std::fs;
use std::io::{IsTerminal, Write};
use std::path::Path;

use anyhow::{Context, Result};
use clap::CommandFactory;
use clap_mangen::Man;
use colored::Colorize;

use crate::Cli;
use crate::help;
use crate::output;

/// Render the manual: a readable contents page on a terminal, one command's page when
/// a command is named, roff when redirected, and with `--dir` the full set of files —
/// `devp.1`, `dev-prune.1` (the same page under the binary's other name) and one
/// `devp-<command>.1` per subcommand.
pub fn run(command_name: Option<&str>, dir: Option<&str>, roff: bool) -> Result<()> {
    let mut command = Cli::command().name("devp");
    command.build();

    // A named command is a request to read one page, and it is the same page `--dir`
    // would write for it: roff when the output is going somewhere that formats roff,
    // that command's own long help when a person is reading it.
    if let Some(name) = command_name {
        let Some(sub) = command
            .get_subcommands()
            .find(|s| s.get_name() == name || s.get_all_aliases().any(|a| a == name))
            .cloned()
        else {
            let names: Vec<&str> = command
                .get_subcommands()
                .map(|s| s.get_name())
                .filter(|n| *n != "help")
                .collect();
            anyhow::bail!(
                "no such command: `{name}`. Try one of: {}",
                names.join(", ")
            );
        };
        if roff || !std::io::stdout().is_terminal() {
            let page = format!("devp-{name}");
            let mut out = Vec::new();
            Man::new(sub.name(page.leak() as &str)).render(&mut out)?;
            std::io::stdout().write_all(&out)?;
            return Ok(());
        }
        let mut sub = sub;
        sub.print_long_help()?;
        return Ok(());
    }

    let Some(dir) = dir else {
        // Someone who ran `devp man` at a prompt used to get raw troff — `.TH`,
        // `\fB\-\-dry\-run\fR` and the rest — because the output assumed a `man`
        // on the other end of a pipe. On Windows there is no `man` to pipe into at
        // all, so the markup was the whole experience. Redirected output still gets
        // roff, so `devp man > devp.1` and `devp man | man -l -` are unchanged.
        if roff || !std::io::stdout().is_terminal() {
            let mut out = Vec::new();
            Man::new(command).render(&mut out)?;
            std::io::stdout().write_all(&out)?;
            return Ok(());
        }

        // A contents page rather than the top-level long help. The long help is one
        // screen-and-a-half of prose followed by every subcommand's one-liner, which
        // is a reasonable answer to `devp --help` and a poor answer to "show me the
        // manual": nothing on it tells the reader where they are or how to get to the
        // page they actually want. This says both, in that order.
        print_contents();
        return Ok(());
    };

    let dir = Path::new(dir);
    fs::create_dir_all(dir)
        .with_context(|| format!("could not create {}", output::clean_path(dir)))?;

    let mut written = 0usize;
    let mut render_to = |name: &str, man: Man| -> Result<()> {
        let path = dir.join(format!("{name}.1"));
        let mut buf = Vec::new();
        man.render(&mut buf)?;
        fs::write(&path, buf)
            .with_context(|| format!("could not write {}", output::clean_path(&path)))?;
        written += 1;
        Ok(())
    };

    for sub in command.get_subcommands() {
        // `help` documents itself; a `devp-help.1` would be a page about a page.
        if sub.get_name() == "help" {
            continue;
        }
        let name = format!("devp-{}", sub.get_name());
        // clap's `Str` only converts from `&'static str` without its "string" feature;
        // leaking a dozen page names in a process about to exit is the honest trade.
        render_to(
            &name,
            Man::new(sub.clone().name(name.clone().leak() as &str)),
        )?;
    }
    render_to("devp", Man::new(command.clone()))?;
    // The same executable answers to both names, and `man dev-prune` should work for
    // the person who never learned the short one.
    render_to("dev-prune", Man::new(command.clone().name("dev-prune")))?;

    output::print_success(&format!(
        "{written} man pages written to {}",
        output::clean_path(dir)
    ));
    output::print_info(
        "Install them by copying into a directory on `manpath`, e.g. `/usr/local/share/man/man1/`.",
    );
    Ok(())
}

/// The manual's contents page: what this is, what every command does in one line each,
/// and the one command that opens any of them.
///
/// Grouped rather than alphabetical. `devp --help` already lists them in definition
/// order, and definition order answers "what exists"; a reader who opens the manual is
/// usually asking "which one do I want", and that is a question about what a command is
/// *for*.
fn print_contents() {
    output::print_header("dev-prune manual");
    println!();
    output::print_wrapped(
        "  ",
        "Every page below is generated from the definitions the binary parses arguments \
         with, so the manual cannot describe a flag the program does not have.",
    );
    println!();
    println!("  {}", "Read one page:".bold());
    println!("    devp man <command>          e.g. `devp man run`, `devp man config`");
    println!("    devp <command> --help       the same text, from the command itself");
    println!();

    for (title, entries) in help::COMMAND_GROUPS {
        println!("  {}", title.bold());
        for (name, line) in entries {
            println!("    {:<12}  {line}", name.cyan());
        }
        println!();
    }

    // Named separately because they are the ones that go *before* the subcommand, and
    // that is the mistake everyone makes once.
    println!("  {}", "Flags that go before the command".bold());
    println!("    --dry-run                   simulate, delete nothing");
    println!("    --ignore-idle               prune repositories you are still working in");
    println!("    --yes / -y                  answer yes to confirmations");
    println!();
    println!("  {}", "Exit codes".bold());
    println!("    0 success    1 failure    2 usage error");
    println!();
    output::print_info(
        "`devp man --roff` prints the roff source; `devp man --dir <DIR>` writes the full set of pages.",
    );
}

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

    #[test]
    fn the_full_set_covers_every_subcommand() {
        let tmp = tempfile::tempdir().unwrap();
        run(None, Some(tmp.path().to_str().unwrap()), false).unwrap();

        // One page per visible subcommand, plus the two top-level names.
        let mut command = Cli::command();
        command.build();
        for sub in command.get_subcommands() {
            if sub.get_name() == "help" {
                continue;
            }
            let page = tmp.path().join(format!("devp-{}.1", sub.get_name()));
            assert!(page.exists(), "missing {}", page.display());
        }
        assert!(tmp.path().join("devp.1").exists());
        assert!(tmp.path().join("dev-prune.1").exists());
    }

    #[test]
    fn a_page_carries_the_long_about_text() {
        let tmp = tempfile::tempdir().unwrap();
        run(None, Some(tmp.path().to_str().unwrap()), false).unwrap();
        let run_page = fs::read_to_string(tmp.path().join("devp-run.1")).unwrap();
        // A phrase from help::RUN_LONG — the proof the manual and --help are one text.
        assert!(run_page.contains("gauntlet"), "{run_page}");
    }

    #[test]
    fn the_contents_page_names_every_command_and_no_others() {
        // The grouping is hand-written, so it is the one part of this file that can
        // drift from the CLI. A command added without a group would be missing from
        // the manual's only navigable page, which is exactly the failure this whole
        // command exists to fix.
        let mut command = Cli::command();
        command.build();
        let real: Vec<&str> = command
            .get_subcommands()
            .map(|s| s.get_name())
            .filter(|n| *n != "help")
            .collect();
        let listed: Vec<&str> = help::COMMAND_GROUPS
            .iter()
            .flat_map(|(_, e)| e.iter().map(|(n, _)| *n))
            .collect();

        for name in &real {
            assert!(listed.contains(name), "`{name}` is in no manual group");
        }
        for name in &listed {
            assert!(
                real.contains(name),
                "manual lists `{name}`, which is not a command"
            );
        }
    }

    #[test]
    fn a_named_command_renders_its_own_page() {
        // Not a terminal under `cargo test`, so this is the roff branch — which is
        // the one that has to name the right page.
        let mut command = Cli::command().name("devp");
        command.build();
        let sub = command
            .get_subcommands()
            .find(|s| s.get_name() == "run")
            .cloned()
            .unwrap();
        let mut out = Vec::new();
        Man::new(sub.name("devp-run")).render(&mut out).unwrap();
        let page = String::from_utf8(out).unwrap();
        assert!(page.contains("devp"), "{page}");
        assert!(page.contains("gauntlet"), "{page}");
    }

    #[test]
    fn an_unknown_command_lists_the_real_ones() {
        let err = run(Some("nosuchthing"), None, false)
            .unwrap_err()
            .to_string();
        assert!(err.contains("no such command"), "{err}");
        assert!(err.contains("run"), "{err}");
    }
}