sluuz 0.10.6

//! sluuz - a git superset. Binary: `slu`.
//!
//! Every git command passes straight through (`slu commit`, `slu push`, `slu
//! log`), and the extra verbs add cross-repo / history superpowers, each with an
//! interactive twin that `slu --help` lists as its own group.
//!
//! This file is the clap `Cmd` enum, the hand-built help template and the
//! dispatch match; what you can run is `slu --help`, which renders from the
//! manifest, those doc comments and `AFTER`, and is the only copy of that
//! list.

/// `print!` for a command's output, ending the process quietly once the
/// reader of stdout has gone (`slu scan | head`) where `print!` panics.
macro_rules! out {
    ($($arg:tt)*) => {
        $crate::emit(format_args!($($arg)*))
    };
}

/// `println!` the way `out!` is `print!`.
macro_rules! outln {
    () => {
        $crate::emit(format_args!("\n"))
    };
    ($($arg:tt)*) => {
        $crate::emit(format_args!("{}\n", format_args!($($arg)*)))
    };
}

mod app;
mod commands;
mod git;
mod history;
mod tui;

use clap::{Arg, ArgAction, CommandFactory, FromArgMatches, Parser, Subcommand};
use std::ffi::{OsStr, OsString};
use std::process::Command;

/// Shown at the bottom of `slu --help`: the one shape the command list can't
/// convey - that everything else is just git - and then what a script can and
/// cannot expect from stdout.
const AFTER: &str = concat!(
    "\
Ways to run it (not subcommands):
  slu <git command>                real git, passed straight through (`slu commit -m \"fix\"`, `slu push`)
  slu <git options> <git command>  git's options before the command reach git as typed (`slu --no-pager log`)

A passthrough is git itself, so the output and the exit code are git's own.
sluuz's own verbs print a table for people rather than data, except
`completions`, whose stdout is the script.
Run `slu <command> --help` for a command's details.",
    "\n\n",
    env!("CARGO_PKG_REPOSITORY"),
    "\ncontributors: ",
    env!("CARGO_PKG_AUTHORS"),
);

/// `-V` stays a bare version string for scripts; `--version` spells out the
/// license, where it lives, and who's contributed. Every field comes from
/// Cargo.toml, so none of it can drift from the manifest.
const LONG_VERSION: &str = concat!(
    env!("CARGO_PKG_VERSION"),
    "\n",
    env!("CARGO_PKG_LICENSE"),
    "  ",
    env!("CARGO_PKG_REPOSITORY"),
    "\ncontributors: ",
    env!("CARGO_PKG_AUTHORS"),
);

// `derive` lets clap generate all the argument parsing boilerplate from annotations.
#[derive(Parser)]
// The app is `sluuz` (shown in --version); the command you type is the shorter
// `slu` (shown in usage via bin_name).
#[command(
    name = "sluuz",
    bin_name = "slu",
    version,
    long_version = LONG_VERSION,
    about,
    after_help = AFTER,
    arg_required_else_help = true
)]
struct Cli {
    #[command(subcommand)]
    command: Cmd,
}

// Each enum variant holds its own Args struct, defined in the subcommand's
// module. `verbatim_doc_comment` keeps the second line (the options) on its own
// line in `slu --help` instead of being collapsed into the description.
#[derive(Subcommand)]
enum Cmd {
    /// Search history for a string (pickaxe)  <PATTERN>
    ///   -r        search every repo under the cwd
    ///   -l N      max commits shown per repo (20)
    #[command(verbatim_doc_comment)]
    Search(commands::search::Args),
    /// Scan repos for sensitive terms - secrets, tokens  [PATH]
    ///   -t TERMS  custom comma-separated terms
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Scan(commands::scan::Args),
    /// Show working-tree state across all repos  [PATH]
    ///   --dirty   only repos needing attention
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Repos(commands::repos::Args),
    /// Fetch (and optionally fast-forward) all repos  [PATH]
    ///   --pull    fast-forward the branch where safe
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Sync(commands::sync::Args),
    /// Find finished branches (upstream gone), safe to delete  [PATH]
    ///   -a        include already-clean repos
    ///   -p        drop remote branches the remote no longer has
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Tidy(commands::tidy::Args),
    /// Run any git command in every repo  <ARGS>...
    ///   slu each pull --ff-only
    #[command(verbatim_doc_comment)]
    Each(commands::each::Args),
    /// Show a prettier history view (aligned log)
    ///   -a        include all branches
    ///   -g        show git's commit graph
    ///   -n N      max commits (30)
    #[command(verbatim_doc_comment)]
    Trace(commands::trace::Args),
    /// Print a completion script that reuses git's own  <bash|zsh|fish>
    ///   --add     append the loader to your shell's rc file for you
    #[command(verbatim_doc_comment)]
    Completions(commands::completions::Args),
    /// Manage sluuz itself: `self update` reinstalls, `self check` looks for a newer release
    #[command(name = "self", subcommand)]
    Selfie(commands::selfcmd::Cmd),
    /// Interactive history search across repos (TUI)  [PATH]
    ///   type terms in the bar, enter runs the search
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Iscan(commands::iscan::Args),
    /// Interactive repo explorer (TUI)  [PATH]
    ///   repos → branches → commits → diff, enter drills in
    ///   --dirty   start on repos with uncommitted work
    ///   -d N      directory depth to scan (3)
    #[command(verbatim_doc_comment)]
    Irepos(commands::irepos::Args),
    /// Interactive branch explorer (TUI)
    ///   every branch with its push state · d deletes, s/S sync
    ///   -g        start on the finished ones (upstream gone)
    ///   -r        start on the remote's
    #[command(verbatim_doc_comment)]
    Ibranch(commands::ibranch::Args),
    /// Interactive tag explorer (TUI)
    ///   every tag against the remote · enter opens what went into it, d deletes
    #[command(verbatim_doc_comment)]
    Itag(commands::itag::Args),
    /// Interactive remote explorer (TUI)
    ///   every remote against this branch · p pushes, s/S sync, c/e/d manage
    #[command(verbatim_doc_comment)]
    Iremote(commands::iremote::Args),
    /// Interactive log explorer (TUI)  [PATH]...
    ///   commits on top, the selected commit's diff below
    ///   -a        include all branches
    ///   -n N      commits to load (200)
    #[command(verbatim_doc_comment)]
    Ilog(commands::ilog::Args),
    /// Interactive git status - stage/unstage + diffs (TUI)
    ///   this repo · h/l ←→ tabs · s/u/space stage · c commits · e edits
    #[command(verbatim_doc_comment)]
    Istatus(commands::istatus::Args),
    /// Interactive stash explorer (TUI)
    ///   every stash, its files and diffs · a applies, p pops, d deletes
    #[command(verbatim_doc_comment)]
    Istash(commands::istash::Args),
    /// Any other command is passed straight through to git
    #[command(external_subcommand)]
    Git(Vec<String>),
}

fn main() {
    let (dirs, globals, argv) = split_leading(std::env::args_os().collect());
    for dir in &dirs {
        enter(dir);
    }
    if !globals.is_empty() {
        let rest = &argv[1..];
        if let Some(name) = rest.first().and_then(|a| a.to_str()).filter(|n| is_own(n)) {
            eprintln!(
                "slu: `{}` is git's option and `{name}` is slu's own command; run `slu {name}` without it",
                globals[0].to_string_lossy()
            );
            std::process::exit(2);
        }
        let mut args = globals;
        args.extend_from_slice(rest);
        exit_like_git(&args, rest);
    }

    // The command list is rendered here rather than by clap, which has no way to
    // give one subcommand a different heading from another. Everything in it
    // still comes from clap's own metadata, so it cannot drift from the
    // commands that actually exist.
    let mut built = Cli::command();
    built.build();
    let template = help_template(&built);
    let matches = Cli::command()
        .help_template(template)
        .arg(
            Arg::new("dir")
                .short('C')
                .value_name("PATH")
                .action(ArgAction::Append)
                .help("Run as if slu was started in PATH; repeated, each is relative to the last"),
        )
        .get_matches_from(argv);
    let cli = match Cli::from_arg_matches(&matches) {
        Ok(cli) => cli,
        Err(e) => e.exit(),
    };

    match cli.command {
        Cmd::Search(args) => commands::search::run(args),
        Cmd::Scan(args) => commands::scan::run(args),
        Cmd::Repos(args) => commands::repos::run(args),
        Cmd::Sync(args) => commands::sync::run(args),
        Cmd::Tidy(args) => commands::tidy::run(args),
        Cmd::Each(args) => commands::each::run(args),
        Cmd::Trace(args) => commands::trace::run(args),
        Cmd::Ilog(args) => commands::ilog::run(args),
        Cmd::Irepos(args) => commands::irepos::run(args),
        Cmd::Ibranch(args) => commands::ibranch::run(args),
        Cmd::Itag(args) => commands::itag::run(args),
        Cmd::Iremote(args) => commands::iremote::run(args),
        Cmd::Iscan(args) => commands::iscan::run(args),
        Cmd::Istatus(args) => commands::istatus::run(args),
        Cmd::Istash(args) => commands::istash::run(args),
        Cmd::Selfie(cmd) => commands::selfcmd::run(cmd),
        Cmd::Completions(args) => commands::completions::run(args),
        Cmd::Git(args) => passthrough(&args),
    }
}

/// `slu --help` with the commands split in two: the ones that print and exit,
/// then the ones that take over the terminal. The pairs line up across the two
/// groups (`scan`/`iscan`, `repos`/`irepos`, `trace`/`ilog`, `tag`/`itag`),
/// which is the shape of the tool.
fn help_template(cmd: &clap::Command) -> String {
    let subs: Vec<&clap::Command> = cmd.get_subcommands().filter(|c| !c.is_hide_set()).collect();
    // One column width across both groups, or the two lists would not line up
    // with each other and the pairing would stop being visible.
    let width = subs
        .iter()
        .map(|c| c.get_name().chars().count())
        .max()
        .unwrap_or(0);
    let (tui, plain): (Vec<&&clap::Command>, Vec<&&clap::Command>) =
        subs.iter().partition(|c| is_interactive(c));

    // Rendering the list by hand means also painting it by hand: clap only
    // styles what it renders itself, and every other crate's help has bold
    // headings and bold command names. The styles come from clap so this list
    // is painted with the same palette as the `{options}` block below it.
    let styles = cmd.get_styles();
    let header = styles.get_header();
    let literal = styles.get_literal();

    let mut list = String::new();
    for (heading, group) in [("Commands:", plain), ("Interactive (TUI):", tui)] {
        list.push_str(&format!("{header}{heading}{header:#}\n"));
        for c in group {
            list.push_str(&entry(c, width, literal));
        }
        list.push('\n');
    }

    format!(
        "{{about-with-newline}}\n{{usage-heading}} {{usage}}\n\n{list}{header}Options:{header:#}\n{{options}}{{after-help}}\n"
    )
}

/// One command's row: its name, then its description, whose extra lines are
/// indented to the same column so a multi-line one still reads as one entry.
fn entry(cmd: &clap::Command, width: usize, literal: &clap::builder::styling::Style) -> String {
    let about = cmd.get_about().map(ToString::to_string).unwrap_or_default();
    let mut lines = about.lines();
    let name = cmd.get_name();
    // The name is padded outside its own styling: escape codes are zero-width
    // to a reader and full-width to `{:<width$}`, so styling the padded string
    // would push every description off the column.
    let pad = " ".repeat(width - name.chars().count());
    let mut row = format!(
        "  {literal}{name}{literal:#}{pad}  {}\n",
        lines.next().unwrap_or("")
    );
    for line in lines {
        row.push_str(&format!("  {:<width$}  {line}\n", ""));
    }
    row
}

/// A command is interactive when its name starts with `i`, which is already the
/// rule the verbs are named by (`iscan`, `irepos`, `ilog`, …) rather than a
/// second list kept beside them for the help to read. Nothing here can drift:
/// a command named to the house rule is grouped by it.
fn is_interactive(cmd: &clap::Command) -> bool {
    cmd.get_name().starts_with('i')
}

/// git's options that go before the command, taken off the command line before
/// clap reads it: the `-C` directories in order, then every other option with
/// its value, then what is left. Scanning stops at the first word that is not
/// an option, and at `-h`, `-V` and a `-C` with no directory, which are clap's.
fn split_leading(mut argv: Vec<OsString>) -> (Vec<OsString>, Vec<OsString>, Vec<OsString>) {
    let (mut dirs, mut globals) = (Vec::new(), Vec::new());
    // Each option found is drained, so the next one is always at 1.
    while let Some(arg) = argv.get(1).and_then(|a| a.to_str()) {
        if !arg.starts_with('-') || matches!(arg, "-h" | "--help" | "-V" | "--version") {
            break;
        }
        if arg == "-C" {
            let Some(dir) = argv.get(2) else { break };
            // git skips an empty `-C ""`, which scripts lean on.
            if !dir.is_empty() {
                dirs.push(dir.clone());
            }
            argv.drain(1..3);
            continue;
        }
        let takes_next = matches!(
            arg,
            "-c" | "--git-dir" | "--work-tree" | "--namespace" | "--config-env" | "--attr-source"
        );
        let end = (2 + usize::from(takes_next)).min(argv.len());
        globals.extend(argv.drain(1..end));
    }
    (dirs, globals, argv)
}

/// Changes into `dir` the way `git -C` does, exiting with git's code for it when
/// that fails.
fn enter(dir: &OsStr) {
    if let Err(e) = std::env::set_current_dir(dir) {
        let why = match e.kind() {
            std::io::ErrorKind::NotFound => "there is no such directory",
            std::io::ErrorKind::NotADirectory => "it is not a directory",
            std::io::ErrorKind::PermissionDenied => "permission denied",
            _ => "it could not be entered",
        };
        eprintln!(
            "slu: cannot run in `{}`: {why}; check the path after `-C`",
            dir.to_string_lossy()
        );
        std::process::exit(128);
    }
}

/// Whether `name` is one of slu's own commands rather than git's.
fn is_own(name: &str) -> bool {
    Cli::command()
        .get_subcommands()
        .any(|c| c.get_name() == name || c.get_all_aliases().any(|a| a == name))
}

/// Forward to real `git`, inheriting stdio so editors, pagers, prompts, and
/// colors all work, then exit with git's own status code.
fn passthrough(args: &[String]) -> ! {
    let args: Vec<OsString> = args.iter().map(OsString::from).collect();
    exit_like_git(&args, &args);
}

/// Runs git with `args` and exits with its code. `command` is the part of
/// `args` from git's command word on, without the options before it.
fn exit_like_git(args: &[OsString], command: &[OsString]) -> ! {
    let code = git_status(args);
    // `git <cmd> --help` hands over to man, which only says "No manual entry"
    // where git's manual is not installed; the usage behind `-h` is built into git.
    if code != 0 && command.get(1).is_some_and(|a| a == "--help") {
        eprintln!(
            "slu: no manual to open, so this is `git {} -h`; install git's man pages for the full one",
            command[0].to_string_lossy()
        );
        let options = &args[..args.len() - command.len()];
        let mut usage = options.to_vec();
        usage.extend([command[0].clone(), OsString::from("-h")]);
        std::process::exit(git_status(&usage));
    }
    std::process::exit(code);
}

/// Runs git with our stdio and returns its exit code, exiting 127 when git
/// cannot be started at all.
fn git_status(args: &[OsString]) -> i32 {
    match Command::new("git").args(args).status() {
        Ok(status) => status.code().unwrap_or(1),
        Err(e) => {
            eprintln!("slu: could not run git: {e}");
            std::process::exit(127);
        }
    }
}

/// What `out!` and `outln!` expand to.
fn emit(args: std::fmt::Arguments) {
    use std::io::Write;
    match std::io::stdout().lock().write_fmt(args) {
        Ok(()) => {}
        Err(e) if e.kind() == std::io::ErrorKind::BrokenPipe => std::process::exit(0),
        Err(_) => {
            eprintln!("error: could not write the output; is the disk it goes to full?");
            std::process::exit(1);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{Cli, help_template};
    use clap::CommandFactory;

    #[test]
    fn every_interactive_command_is_listed_under_its_own_heading() {
        // `slu --help` promises two groups, and which group a command lands in
        // is decided by the `i` its name is meant to start with. Reading the
        // rendered list back is what catches a command named against that rule,
        // which would otherwise only be visible to whoever next read the help.
        let mut built = Cli::command();
        built.build();
        let rendered = help_template(&built);
        let (plain, interactive) = rendered
            .split_once("Interactive (TUI):")
            .expect("the list is split into two groups");

        let literal = built.get_styles().get_literal();
        for sub in built.get_subcommands() {
            let name = sub.get_name();
            // The name carries its own styling, so anchoring on it also pins
            // that the hand-rendered list is painted like clap's own.
            let row = format!("\n  {literal}{name}{literal:#}");
            let (half, group) = if name.starts_with('i') {
                (interactive, "interactive")
            } else {
                (plain, "plain")
            };
            assert!(
                half.contains(&row),
                "`{name}` is missing from the {group} group"
            );
        }
    }
}