implement positional arg files

begin pre-commit support

Author: 2bndy5

.gitattributes

@@ -25,3 +25,4 @@
 *.code-workspace text eol=lf
 *.clang-tidy text eol=lf
 *.clang-format text eol=lf
+justfile text eol=lf

cpp-linter-lib/src/cli.rs

@@ -28,18 +28,18 @@ pub fn get_arg_parser() -> Command {
                 .short('v')
                 .default_value("info")
                 .value_parser(["debug", "info"])
-                .long_help(
+                .help(
                     "This controls the action's verbosity in the workflow's logs.
 This option does not affect the verbosity of resulting
-thread comments or file annotations.",
+thread comments or file annotations.\n\n",
                 ),
         )
         .arg(
             Arg::new("database")
                 .long("database")
                 .short('p')
                 .help_heading("clang-tidy options")
-                .long_help(
+                .help(
             "The path that is used to read a compile command database.
 For example, it can be a CMake build directory in which a file named
 compile_commands.json exists (set `CMAKE_EXPORT_COMPILE_COMMANDS` to `ON`).
@@ -54,13 +54,13 @@ for an example of setting up Clang Tooling on a source tree.",
                 .long("style")
                 .default_value("llvm")
                 .help_heading("clang-format options")
-                .long_help(
+                .help(
                     "The style rules to use.
 
 - Set this to `file` to have clang-format use the closest relative
   .clang-format file.
 - Set this to a blank string (`''`) to disable using clang-format
-  entirely.",
+  entirely.\n\n",
                 ),
         )
         .arg(
@@ -71,7 +71,7 @@ for an example of setting up Clang Tooling on a source tree.",
                     "boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*",
                 )
                 .help_heading("clang-tidy options")
-                .long_help(
+                .help(
                     "A comma-separated list of globs with optional `-` prefix.
 Globs are processed in order of appearance in the list.
 Globs without `-` prefix add checks with matching names to the set,
@@ -84,7 +84,7 @@ option in a .clang-tidy file (if any).
 - It is also possible to rely solely on a .clang-tidy config file by
   specifying this option as a blank string (`''`).
 
-See also clang-tidy docs for more info.",
+See also clang-tidy docs for more info.\n\n",
                 ),
         )
         .arg(
@@ -95,15 +95,15 @@ See also clang-tidy docs for more info.",
                 .num_args(0..=1)
                 .require_equals(true)
                 .default_value("")
-                .long_help(
+                .help(
                     "The desired version of the clang tools to use. Accepted options are
 strings which can be 8, 9, 10, 11, 12, 13, 14, 15, 16, 17.
 
 - Set this option to a blank string (`''`) to use the
   platform's default installed version.
 - This value can also be a path to where the clang tools are
   installed (if using a custom install location). All paths specified
-  here are converted to absolute.",
+  here are converted to absolute.\n\n",
                 ),
         )
         .arg(
@@ -112,19 +112,19 @@ strings which can be 8, 9, 10, 11, 12, 13, 14, 15, 16, 17.
                 .long("extensions")
                 .value_delimiter(',')
                 .default_value("c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx")
-                .help_heading("source options")
-                .long_help("A comma-separated list of file extensions to analyze."),
+                .help_heading("Source options")
+                .help("A comma-separated list of file extensions to analyze.\n"),
         )
         .arg(
             Arg::new("repo-root")
                 .short('r')
                 .long("repo-root")
                 .default_value(".")
-                .help_heading("source options")
-                .long_help(
+                .help_heading("Source options")
+                .help(
                     "The relative path to the repository root directory. This path is
 relative to the runner's `GITHUB_WORKSPACE` environment variable (or
-the current working directory if not using a CI runner).",
+the current working directory if not using a CI runner).\n\n",
                 ),
         )
         .arg(
@@ -133,8 +133,8 @@ the current working directory if not using a CI runner).",
                 .long("ignore")
                 .value_delimiter('|')
                 .default_value(".github|target")
-                .help_heading("source options")
-                .long_help(
+                .help_heading("Source options")
+                .help(
                     "Set this option with path(s) to ignore (or not ignore).
 
 - In the case of multiple paths, you can use `|` to separate each path.
@@ -147,7 +147,7 @@ the current working directory if not using a CI runner).",
 - Prefix a path with `!` to explicitly not ignore it. This can be
   applied to a submodule's path (if desired) but not hidden directories.
 - Glob patterns are not supported here. All asterisk characters (`*`)
-  are literal.",
+  are literal.\n\n",
                 ),
         )
         .arg(
@@ -157,9 +157,9 @@ the current working directory if not using a CI runner).",
                 .value_delimiter('|')
                 .default_value("")
                 .help_heading("clang-tidy options")
-                .long_help(
+                .help(
                     "Similar to [`--ignore`](#-i---ignore) but applied
-exclusively to files analyzed by clang-tidy.",
+exclusively to files analyzed by clang-tidy.\n\n",
                 ),
         )
         .arg(
@@ -169,9 +169,9 @@ exclusively to files analyzed by clang-tidy.",
                 .value_delimiter('|')
                 .default_value("")
                 .help_heading("clang-format options")
-                .long_help(
+                .help(
                     "Similar to [`--ignore`](#-i---ignore) but applied
-exclusively to files analyzed by clang-format.",
+exclusively to files analyzed by clang-format.\n\n",
                 ),
         )
         .arg(
@@ -180,15 +180,15 @@ exclusively to files analyzed by clang-format.",
                 .long("lines-changed-only")
                 .value_parser(["true", "false", "diff"])
                 .default_value("true")
-                .help_heading("source options")
-                .long_help(
+                .help_heading("Source options")
+                .help(
                     "This controls what part of the files are analyzed.
 The following values are accepted:
 
 - `false`: All lines in a file are analyzed.
 - `true`: Only lines in the diff that contain additions are analyzed.
 - `diff`: All lines in the diff are analyzed (including unchanged
-  lines but not subtractions).",
+  lines but not subtractions).\n\n",
                 ),
         )
         .arg(
@@ -198,8 +198,8 @@ The following values are accepted:
                 .default_value_if("lines-changed-only", ArgPredicate::Equals("true".into()), "true")
                 .default_value("false")
                 .value_parser(FalseyValueParser::new())
-                .help_heading("source options")
-                .long_help(
+                .help_heading("Source options")
+                .help(
                     "Set this option to false to analyze any source files in the repo.
 This is automatically enabled if
 [`--lines-changed-only`](#-l---lines-changed-only) is enabled.
@@ -210,7 +210,7 @@ This is automatically enabled if
 > does not not have the privilege to list the changed files for an event.
 >
 > See [Authenticating with the `GITHUB_TOKEN`](
-> https://docs.github.com/en/actions/reference/authentication-in-a-workflow).",
+> https://docs.github.com/en/actions/reference/authentication-in-a-workflow).\n\n",
                 ),
         )
         .arg(
@@ -219,7 +219,7 @@ This is automatically enabled if
                 .short('x')
                 .action(ArgAction::Append)
                 .help_heading("clang-tidy options")
-                .long_help(
+                .help(
                     "A string of extra arguments passed to clang-tidy for use as
 compiler arguments. This can be specified more than once for each
 additional argument. Recommend using quotes around the value and
@@ -237,7 +237,7 @@ cpp-linter --extra-arg=\"-std=c++17\" --extra-arg=\"-Wall\"
                 .value_parser(["true", "false", "updated"])
                 .default_value("false")
                 .help_heading("feedback options")
-                .long_help(
+                .help(
                     "Set this option to true to enable the use of thread comments as feedback.
 Set this to `update` to update an existing comment if one exists;
 the value 'true' will always delete an old comment and post a new one if necessary.
@@ -248,7 +248,7 @@ the value 'true' will always delete an old comment and post a new one if necessa
 > variable.
 >
 > See [Authenticating with the `GITHUB_TOKEN`](
-> https://docs.github.com/en/actions/reference/authentication-in-a-workflow).",
+> https://docs.github.com/en/actions/reference/authentication-in-a-workflow).\n\n",
                 ),
         )
         .arg(
@@ -258,13 +258,13 @@ the value 'true' will always delete an old comment and post a new one if necessa
                 .value_parser(FalseyValueParser::new())
                 .default_value("true")
                 .help_heading("feedback options")
-                .long_help(
+                .help(
                     "Set this option to true or false to enable or disable the use of a
 thread comment that basically says 'Looks Good To Me' (when all checks pass).
 
 > [!important]
 > The [`--thread-comments`](#-g---thread-comments)
-> option also notes further implications.",
+> option also notes further implications.\n\n",
                 ),
         )
         .arg(
@@ -274,9 +274,9 @@ thread comment that basically says 'Looks Good To Me' (when all checks pass).
                 .value_parser(FalseyValueParser::new())
                 .default_value("false")
                 .help_heading("feedback options")
-                .long_help(
+                .help(
                     "Set this option to true or false to enable or disable the use of
-a workflow step summary when the run has concluded.",
+a workflow step summary when the run has concluded.\n\n",
                 ),
         )
         .arg(
@@ -286,11 +286,21 @@ a workflow step summary when the run has concluded.",
                 .value_parser(FalseyValueParser::new())
                 .default_value("true")
                 .help_heading("feedback options")
-                .long_help(
+                .help(
                     "Set this option to false to disable the use of
-file annotations as feedback.",
+file annotations as feedback.\n\n",
                 ),
             )
+            .arg(
+                Arg::new("files")
+                    .action(ArgAction::Append)
+                    .help(
+                        "An explicit path to a file.
+This can be specified zero or more times, resulting in a list of files.
+The list of files is appended to the internal list of 'not ignored' files.
+Further filtering can still be applied (see [Source options](#source-options)).",
+                )
+            )
             .groups([
                 ArgGroup::new("Clang-tidy options")
                     .args(["tidy-checks", "database", "extra-arg", "ignore-tidy"]),
@@ -301,6 +311,7 @@ file annotations as feedback.",
                     "thread-comments", "no-lgtm", "step-summary", "file-annotations"
                 ]),
             ])
+            .next_line_help(true)
 }
 
 /// Converts the parsed value of the `--extra-arg` option into an optional vector of strings.

cpp-linter-lib/src/common_fs/file_filter.rs

@@ -4,9 +4,9 @@ use super::FileObj;
 
 #[derive(Debug, Clone)]
 pub struct FileFilter {
-    ignored: Vec<String>,
-    not_ignored: Vec<String>,
-    extensions: Vec<String>,
+    pub ignored: Vec<String>,
+    pub not_ignored: Vec<String>,
+    pub extensions: Vec<String>,
 }
 impl FileFilter {
     pub fn new(ignore: &[&str], extensions: Vec<String>) -> Self {

cpp-linter-lib/src/rest_api/github_api.rs

@@ -191,7 +191,11 @@ impl RestApiClient for GithubApiClient {
         }
     }
 
-    async fn post_feedback(&self, files: &[Arc<Mutex<FileObj>>], user_inputs: FeedbackInput) {
+    async fn post_feedback(
+        &self,
+        files: &[Arc<Mutex<FileObj>>],
+        user_inputs: FeedbackInput,
+    ) -> u64 {
         let format_checks_failed = tally_format_advice(files);
         let tidy_checks_failed = tally_tidy_advice(files);
         let mut comment = None;
@@ -268,6 +272,7 @@ impl RestApiClient for GithubApiClient {
                 }
             }
         }
+        format_checks_failed + tidy_checks_failed
     }
 }
 

cpp-linter-lib/src/rest_api/mod.rs

@@ -124,7 +124,7 @@ pub trait RestApiClient {
         &self,
         files: &[Arc<Mutex<FileObj>>],
         user_inputs: FeedbackInput,
-    ) -> impl Future<Output = ()>;
+    ) -> impl Future<Output = u64>;
 }
 
 fn make_format_comment(

cpp-linter-lib/src/run.rs

@@ -100,6 +100,13 @@ pub async fn run_main(args: Vec<String>) -> i32 {
         .collect::<Vec<_>>();
     let mut file_filter = FileFilter::new(&ignore, extensions.clone());
     file_filter.parse_submodules();
+    if let Some(files) = args.get_many::<Vec<String>>("files") {
+        for list in files {
+            file_filter
+                .not_ignored
+                .extend(list.iter().map(|v| v.to_string()).collect::<Vec<String>>());
+        }
+    }
 
     let lines_changed_only = match args
         .get_one::<String>("lines-changed-only")
@@ -166,8 +173,11 @@ pub async fn run_main(args: Vec<String>) -> i32 {
     };
     capture_clang_tools_output(&mut arc_files, version, &mut clang_params).await;
     start_log_group(String::from("Posting feedback"));
-    rest_api_client.post_feedback(&arc_files, user_inputs).await;
+    let checks_failed = rest_api_client.post_feedback(&arc_files, user_inputs).await;
     end_log_group();
+    if env::var("PRE_COMMIT").is_ok_and(|v| v == "1") {
+        return (checks_failed > 1) as i32;
+    }
     0
 }
 

docs/src/main.rs

@@ -99,6 +99,13 @@ mod cli_gen_lib {
                     format!("{}\n", &cmd.get_about().unwrap().to_string().trim()).as_str(),
                 );
             }
+            out.push_str("## Arguments\n");
+            for arg in command.get_positionals() {
+                out.push_str(format!("\n### `{}`\n\n", arg.get_id().as_str()).as_str());
+                if let Some(help) = arg.get_help() {
+                    out.push_str(format!("{}\n", help.to_string().trim()).as_str());
+                }
+            }
             let arg_groups = if let Some(groups) = groups_order {
                 eprintln!("ordering groups into {:?}", groups);
                 let mut ordered = Vec::with_capacity(command.get_groups().count());
@@ -146,9 +153,9 @@ mod cli_gen_lib {
                                 .as_str(),
                         );
                     }
-                    out.push_str(
-                        format!("{}\n", &arg.get_long_help().unwrap().to_string().trim()).as_str(),
-                    );
+                    if let Some(help) = &arg.get_help() {
+                        out.push_str(format!("{}\n", help.to_string().trim()).as_str());
+                    }
                 }
             }
             out