1use crate::handlers;
2use crate::parse::WordSet;
3
4pub struct CommandDoc {
5 pub name: &'static str,
6 pub kind: DocKind,
7 pub url: &'static str,
8 pub description: String,
9}
10
11pub enum DocKind {
12 Handler,
13}
14
15impl CommandDoc {
16 pub fn handler(name: &'static str, url: &'static str, description: impl Into<String>) -> Self {
17 let raw = description.into();
18 let description = raw
19 .lines()
20 .map(|line| {
21 if line.is_empty() || line.starts_with("- ") {
22 line.to_string()
23 } else {
24 format!("- {line}")
25 }
26 })
27 .collect::<Vec<_>>()
28 .join("\n");
29 Self { name, kind: DocKind::Handler, url, description }
30 }
31
32 pub fn wordset(name: &'static str, url: &'static str, words: &WordSet) -> Self {
33 Self::handler(name, url, doc(words).build())
34 }
35
36 pub fn wordset_multi(name: &'static str, url: &'static str, words: &WordSet, multi: &[(&str, WordSet)]) -> Self {
37 Self::handler(name, url, doc_multi(words, multi).build())
38 }
39
40
41}
42
43#[derive(Default)]
44pub struct DocBuilder {
45 subcommands: Vec<String>,
46 flags: Vec<String>,
47 sections: Vec<String>,
48}
49
50impl DocBuilder {
51 pub fn new() -> Self {
52 Self::default()
53 }
54
55 pub fn wordset(mut self, words: &WordSet) -> Self {
56 for item in words.iter() {
57 if item.starts_with('-') {
58 self.flags.push(item.to_string());
59 } else {
60 self.subcommands.push(item.to_string());
61 }
62 }
63 self
64 }
65
66 pub fn multi_word(mut self, multi: &[(&str, WordSet)]) -> Self {
67 for (prefix, actions) in multi {
68 for action in actions.iter() {
69 self.subcommands.push(format!("{prefix} {action}"));
70 }
71 }
72 self
73 }
74
75 pub fn triple_word(mut self, triples: &[(&str, &str, WordSet)]) -> Self {
76 for (a, b, actions) in triples {
77 for action in actions.iter() {
78 self.subcommands.push(format!("{a} {b} {action}"));
79 }
80 }
81 self
82 }
83
84 pub fn subcommand(mut self, name: impl Into<String>) -> Self {
85 self.subcommands.push(name.into());
86 self
87 }
88
89 pub fn section(mut self, text: impl Into<String>) -> Self {
90 let s = text.into();
91 if !s.is_empty() {
92 self.sections.push(s);
93 }
94 self
95 }
96
97 pub fn build(self) -> String {
98 let mut lines = Vec::new();
99 if !self.subcommands.is_empty() {
100 let mut subs = self.subcommands;
101 subs.sort();
102 lines.push(format!("- Subcommands: {}", subs.join(", ")));
103 }
104 if !self.flags.is_empty() {
105 lines.push(format!("- Flags: {}", self.flags.join(", ")));
106 }
107 for s in self.sections {
108 if s.starts_with("- ") {
109 lines.push(s);
110 } else {
111 lines.push(format!("- {s}"));
112 }
113 }
114 lines.join("\n")
115 }
116}
117
118pub fn doc(words: &WordSet) -> DocBuilder {
119 DocBuilder::new().wordset(words)
120}
121
122pub fn doc_multi(words: &WordSet, multi: &[(&str, WordSet)]) -> DocBuilder {
123 DocBuilder::new().wordset(words).multi_word(multi)
124}
125
126pub fn wordset_items(words: &WordSet) -> String {
127 let items: Vec<&str> = words.iter().collect();
128 items.join(", ")
129}
130
131
132pub fn all_command_docs() -> Vec<CommandDoc> {
133 let mut docs = handlers::handler_docs();
134 docs.sort_by_key(|d| d.name);
135 docs
136}
137
138pub fn render_markdown(docs: &[CommandDoc]) -> String {
139 let mut out = String::from(
140 "# Supported Commands\n\
141 \n\
142 Auto-generated by `safe-chains --list-commands`. These commands, subcommands, and flags are read-only and safe to run individually or in combination.\n\n",
143 );
144
145 for doc in docs {
146 out.push_str(&format!("### `{}` ({})\n\n{}\n\n", doc.name, doc.url, doc.description));
147 }
148
149 out
150}
151
152#[cfg(test)]
153mod tests {
154 use super::*;
155
156 #[test]
157 fn all_commands_have_url() {
158 for doc in all_command_docs() {
159 assert!(!doc.url.is_empty(), "{} has no documentation URL", doc.name);
160 assert!(
161 doc.url.starts_with("https://"),
162 "{} URL must use https: {}",
163 doc.name,
164 doc.url
165 );
166 }
167 }
168
169 #[test]
170 fn builder_two_sections() {
171 let ws = WordSet::new(&["--version", "list", "show"]);
172 assert_eq!(doc(&ws).build(), "- Subcommands: list, show\n- Flags: --version");
173 }
174
175 #[test]
176 fn builder_subcommands_only() {
177 let ws = WordSet::new(&["list", "show"]);
178 assert_eq!(doc(&ws).build(), "- Subcommands: list, show");
179 }
180
181 #[test]
182 fn builder_flags_only() {
183 let ws = WordSet::new(&["--check", "--version"]);
184 assert_eq!(doc(&ws).build(), "- Flags: --check, --version");
185 }
186
187 #[test]
188 fn builder_three_sections() {
189 let ws = WordSet::new(&["--version", "list", "show"]);
190 assert_eq!(
191 doc(&ws).section("Guarded: foo (bar only).").build(),
192 "- Subcommands: list, show\n- Flags: --version\n- Guarded: foo (bar only)."
193 );
194 }
195
196 #[test]
197 fn builder_multi_word_merged() {
198 let ws = WordSet::new(&["--version", "info", "show"]);
199 let multi: &[(&str, WordSet)] =
200 &[("config", WordSet::new(&["get", "list"]))];
201 assert_eq!(
202 doc_multi(&ws, multi).build(),
203 "- Subcommands: config get, config list, info, show\n- Flags: --version"
204 );
205 }
206
207 #[test]
208 fn builder_multi_word_with_extra_section() {
209 let ws = WordSet::new(&["--version", "show"]);
210 let multi: &[(&str, WordSet)] =
211 &[("config", WordSet::new(&["get", "list"]))];
212 assert_eq!(
213 doc_multi(&ws, multi).section("Guarded: foo.").build(),
214 "- Subcommands: config get, config list, show\n- Flags: --version\n- Guarded: foo."
215 );
216 }
217
218 #[test]
219 fn builder_no_flags_with_extra() {
220 let ws = WordSet::new(&["list", "show"]);
221 assert_eq!(
222 doc(&ws).section("Also: foo.").build(),
223 "- Subcommands: list, show\n- Also: foo."
224 );
225 }
226
227 #[test]
228 fn builder_custom_sections_only() {
229 assert_eq!(
230 DocBuilder::new()
231 .section("Read-only: foo.")
232 .section("Always safe: bar.")
233 .section("Guarded: baz.")
234 .build(),
235 "- Read-only: foo.\n- Always safe: bar.\n- Guarded: baz."
236 );
237 }
238
239 #[test]
240 fn builder_triple_word() {
241 let ws = WordSet::new(&["--version", "diff"]);
242 let triples: &[(&str, &str, WordSet)] =
243 &[("git", "remote", WordSet::new(&["list"]))];
244 assert_eq!(
245 doc(&ws).triple_word(triples).build(),
246 "- Subcommands: diff, git remote list\n- Flags: --version"
247 );
248 }
249
250 #[test]
251 fn builder_subcommand_method() {
252 let ws = WordSet::new(&["--version", "list"]);
253 assert_eq!(
254 doc(&ws).subcommand("plugin-list").build(),
255 "- Subcommands: list, plugin-list\n- Flags: --version"
256 );
257 }
258
259}