refactor: migrate to clap2man and consolidate CLI metadata in src/cli.rs

Author: lpenz

Cargo.lock

@@ -32,6 +32,8 @@ tracing = { version = "0.1.44", features = ["log"] }
 url = "2.5.8"
 
 [build-dependencies]
+clap = { version = "4.6.0", features = ["derive"] }
+clap2man = "0.1.1"
 color-eyre = "0.6.3"
 man = "0.3.0"
 

Cargo.toml

@@ -2,69 +2,33 @@
 // This file is subject to the terms and conditions defined in
 // file 'LICENSE', which is part of this source code package.
 
-use color_eyre::{Result, eyre::eyre};
-use man::prelude::*;
+use clap::CommandFactory;
+use color_eyre::{eyre::eyre, eyre::Context, Result};
 use std::env;
 use std::fs::{self, File};
 use std::io::Write;
 use std::path;
 
+include!("src/cli.rs");
+
 fn generate_man_page<P: AsRef<path::Path>>(outdir: P) -> Result<()> {
     let outdir = outdir.as_ref();
     let man_path = outdir.join("github-workflows-update.1");
-    let manpage = Manual::new("github-workflows-update")
-        .about("Check github workflows for actions that can be updated")
-        .author(Author::new("Leandro Lisboa Penz").email("[email protected]"))
-        .flag(
-            Flag::new()
-                .short("-n")
-                .long("--dry-run")
-                .help("Don't update the workflows, just print what would be done"),
-        )
-        .option(
-            Opt::new("output-format")
-                .short("-f")
-                .long("--output-format")
-                .default_value("standard")
-                .help(
-                    "Output format for the outdated action messages; \
-                       one of \"standard\" or \"github-warning\"",
-                ),
-        )
-        .flag(
-            Flag::new()
-                .long("--error-on-outdated")
-                .help("Return error if any outdated actions are found"),
-        )
-        .flag(
-            Flag::new()
-                .short("-h")
-                .long("--help")
-                .help("Prints help information"),
-        )
-        .flag(
-            Flag::new()
-                .short("-V")
-                .long("--version")
-                .help("Prints version information"),
-        )
-        .arg(Arg::new("COMMAND"))
-        .arg(Arg::new("[ ARGS ]"))
-        .description(
-            "github-workflows-update reads all github workflow and checks the latest
-available versions of all github actions and workflow dispatches used, showing
-which ones can be updated and optionally updating them automatically.",
-        )
+    let cmd = Cli::command();
+    let manual: man::Manual = clap2man::Manual::try_from(&cmd)
+        .wrap_err("error converting clap command to manual")?
+        .into();
+    let manpage = manual
         .example(
-            Example::new()
+            man::prelude::Example::new()
                 .text(
                     "Update all actions used in all github workflows \
                        under the current repository",
                 )
                 .command("github-workflows-update"),
         )
         .example(
-            Example::new()
+            man::prelude::Example::new()
                 .text("Show outdated actions without updating them")
                 .command("github-workflows-update -n"),
         )

build.rs

@@ -0,0 +1,55 @@
+// Copyright (C) 2022 Leandro Lisboa Penz <[email protected]>
+// This file is subject to the terms and conditions defined in
+// file 'LICENSE', which is part of this source code package.
+
+use clap::Parser;
+use clap::ValueEnum;
+
+#[derive(Parser, Debug)]
+#[command(
+    author,
+    version,
+    about = "Check github workflows for actions that can be updated",
+    long_about = "github-workflows-update reads all github workflow and checks the latest
+available versions of all github actions and workflow dispatches used, showing
+which ones can be updated and optionally updating them automatically."
+)]
+pub struct Cli {
+    /// Don't update the workflows, just print what would be done
+    #[clap(short = 'n', long = "dry-run")]
+    pub dryrun: bool,
+    /// Output format for the outdated action messages
+    #[clap(short = 'f', long, value_enum, value_parser)]
+    pub output_format: Option<OutputFormat>,
+    /// Return error if any outdated actions are found
+    #[clap(long)]
+    pub error_on_outdated: bool,
+}
+
+#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Default, Debug)]
+pub enum OutputFormat {
+    #[default]
+    Standard,
+    /// Generate messages as github action warnings
+    GithubWarning,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::CommandFactory;
+
+    #[test]
+    fn test_cli() {
+        Cli::command().debug_assert();
+    }
+
+    #[test]
+    fn test_parse_args() {
+        let args =
+            Cli::parse_from(&["test", "-n", "-f", "github-warning", "--error-on-outdated"]);
+        assert!(args.dryrun);
+        assert_eq!(args.output_format, Some(OutputFormat::GithubWarning));
+        assert!(args.error_on_outdated);
+    }
+}

src/cli.rs

@@ -12,35 +12,13 @@ use tracing::Level;
 use tracing::event;
 
 use clap::Parser;
-use clap::ValueEnum;
-
+use crate::cli::Cli;
+use crate::cli::OutputFormat;
 use crate::proxy;
 
-#[derive(Parser, Debug)]
-#[command(author, version, about, long_about = None)]
-pub struct Args {
-    /// Don't update the workflows, just print what would be done
-    #[clap(short = 'n', long = "dry-run")]
-    pub dryrun: bool,
-    /// Output format for the outdated action messages
-    #[clap(short = 'f', long, value_enum, value_parser)]
-    pub output_format: Option<OutputFormat>,
-    /// Return error if any outdated actions are found
-    #[clap(long)]
-    pub error_on_outdated: bool,
-}
-
-#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Default, Debug)]
-pub enum OutputFormat {
-    #[default]
-    Standard,
-    /// Generate messages as github action warnings
-    GithubWarning,
-}
-
 #[tokio::main]
 pub async fn main() -> Result<()> {
-    let args = Args::parse();
+    let args = Cli::parse();
     env_logger::init();
     let proxy_server = proxy::Server::new();
     let futures = ReadDirStream::new(tokio::fs::read_dir(".github/workflows").await?)

src/cmd.rs

@@ -19,6 +19,7 @@
 //!   - [`proxy`]: a proxy [`proxy::Server`] that makes async
 //!     requests and caches the results.
 
+pub mod cli;
 pub mod cmd;
 pub mod error;
 pub mod processor;

src/lib.rs

@@ -10,7 +10,7 @@ use tracing::Level;
 use tracing::event;
 use tracing::instrument;
 
-use crate::cmd::OutputFormat;
+use crate::cli::OutputFormat;
 use crate::proxy;
 use crate::workflow::Workflow;