safe_chains/

docs.rs

use crate::handlers;
use crate::parse::WordSet;

pub struct CommandDoc {
    pub name: &'static str,
    pub kind: DocKind,
    pub description: String,
}

pub enum DocKind {
    Handler,
}

impl CommandDoc {
    pub fn handler(name: &'static str, description: impl Into<String>) -> Self {
        let raw = description.into();
        let description = raw
            .lines()
            .map(|line| {
                if line.is_empty() || line.starts_with("- ") {
                    line.to_string()
                } else {
                    format!("- {line}")
                }
            })
            .collect::<Vec<_>>()
            .join("\n");
        Self { name, kind: DocKind::Handler, description }
    }

    pub fn wordset(name: &'static str, words: &WordSet) -> Self {
        Self::handler(name, doc(words).build())
    }

    pub fn wordset_multi(name: &'static str, words: &WordSet, multi: &[(&str, WordSet)]) -> Self {
        Self::handler(name, doc_multi(words, multi).build())
    }


}

#[derive(Default)]
pub struct DocBuilder {
    subcommands: Vec<String>,
    flags: Vec<String>,
    sections: Vec<String>,
}

impl DocBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn wordset(mut self, words: &WordSet) -> Self {
        for item in words.iter() {
            if item.starts_with('-') {
                self.flags.push(item.to_string());
            } else {
                self.subcommands.push(item.to_string());
            }
        }
        self
    }

    pub fn multi_word(mut self, multi: &[(&str, WordSet)]) -> Self {
        for (prefix, actions) in multi {
            for action in actions.iter() {
                self.subcommands.push(format!("{prefix} {action}"));
            }
        }
        self
    }

    pub fn triple_word(mut self, triples: &[(&str, &str, WordSet)]) -> Self {
        for (a, b, actions) in triples {
            for action in actions.iter() {
                self.subcommands.push(format!("{a} {b} {action}"));
            }
        }
        self
    }

    pub fn subcommand(mut self, name: impl Into<String>) -> Self {
        self.subcommands.push(name.into());
        self
    }

    pub fn section(mut self, text: impl Into<String>) -> Self {
        let s = text.into();
        if !s.is_empty() {
            self.sections.push(s);
        }
        self
    }

    pub fn build(self) -> String {
        let mut lines = Vec::new();
        if !self.subcommands.is_empty() {
            let mut subs = self.subcommands;
            subs.sort();
            lines.push(format!("- Subcommands: {}", subs.join(", ")));
        }
        if !self.flags.is_empty() {
            lines.push(format!("- Flags: {}", self.flags.join(", ")));
        }
        for s in self.sections {
            if s.starts_with("- ") {
                lines.push(s);
            } else {
                lines.push(format!("- {s}"));
            }
        }
        lines.join("\n")
    }
}

pub fn doc(words: &WordSet) -> DocBuilder {
    DocBuilder::new().wordset(words)
}

pub fn doc_multi(words: &WordSet, multi: &[(&str, WordSet)]) -> DocBuilder {
    DocBuilder::new().wordset(words).multi_word(multi)
}

pub fn wordset_items(words: &WordSet) -> String {
    let items: Vec<&str> = words.iter().collect();
    items.join(", ")
}


pub fn all_command_docs() -> Vec<CommandDoc> {
    let mut docs = handlers::handler_docs();
    docs.sort_by_key(|d| d.name);
    docs
}

pub fn render_markdown(docs: &[CommandDoc]) -> String {
    let mut out = String::from(
        "# Supported Commands\n\
         \n\
         Auto-generated by `safe-chains --list-commands`.\n\
         \n\
         Any command with only `--version` or `--help` as its sole argument is always allowed.\n\
         \n\
         ## Handled Commands\n\n\
         These commands are allowed with specific subcommands or flags.\n\n",
    );

    for doc in docs {
        out.push_str(&format!("### `{}`\n\n{}\n\n", doc.name, doc.description));
    }

    out
}

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

    #[test]
    fn builder_two_sections() {
        let ws = WordSet::new(&["--version", "list", "show"]);
        assert_eq!(doc(&ws).build(), "- Subcommands: list, show\n- Flags: --version");
    }

    #[test]
    fn builder_subcommands_only() {
        let ws = WordSet::new(&["list", "show"]);
        assert_eq!(doc(&ws).build(), "- Subcommands: list, show");
    }

    #[test]
    fn builder_flags_only() {
        let ws = WordSet::new(&["--check", "--version"]);
        assert_eq!(doc(&ws).build(), "- Flags: --check, --version");
    }

    #[test]
    fn builder_three_sections() {
        let ws = WordSet::new(&["--version", "list", "show"]);
        assert_eq!(
            doc(&ws).section("Guarded: foo (bar only).").build(),
            "- Subcommands: list, show\n- Flags: --version\n- Guarded: foo (bar only)."
        );
    }

    #[test]
    fn builder_multi_word_merged() {
        let ws = WordSet::new(&["--version", "info", "show"]);
        let multi: &[(&str, WordSet)] =
            &[("config", WordSet::new(&["get", "list"]))];
        assert_eq!(
            doc_multi(&ws, multi).build(),
            "- Subcommands: config get, config list, info, show\n- Flags: --version"
        );
    }

    #[test]
    fn builder_multi_word_with_extra_section() {
        let ws = WordSet::new(&["--version", "show"]);
        let multi: &[(&str, WordSet)] =
            &[("config", WordSet::new(&["get", "list"]))];
        assert_eq!(
            doc_multi(&ws, multi).section("Guarded: foo.").build(),
            "- Subcommands: config get, config list, show\n- Flags: --version\n- Guarded: foo."
        );
    }

    #[test]
    fn builder_no_flags_with_extra() {
        let ws = WordSet::new(&["list", "show"]);
        assert_eq!(
            doc(&ws).section("Also: foo.").build(),
            "- Subcommands: list, show\n- Also: foo."
        );
    }

    #[test]
    fn builder_custom_sections_only() {
        assert_eq!(
            DocBuilder::new()
                .section("Read-only: foo.")
                .section("Always safe: bar.")
                .section("Guarded: baz.")
                .build(),
            "- Read-only: foo.\n- Always safe: bar.\n- Guarded: baz."
        );
    }

    #[test]
    fn builder_triple_word() {
        let ws = WordSet::new(&["--version", "diff"]);
        let triples: &[(&str, &str, WordSet)] =
            &[("git", "remote", WordSet::new(&["list"]))];
        assert_eq!(
            doc(&ws).triple_word(triples).build(),
            "- Subcommands: diff, git remote list\n- Flags: --version"
        );
    }

    #[test]
    fn builder_subcommand_method() {
        let ws = WordSet::new(&["--version", "list"]);
        assert_eq!(
            doc(&ws).subcommand("plugin-list").build(),
            "- Subcommands: list, plugin-list\n- Flags: --version"
        );
    }

}