Improve command line experience

When running via -X or -T:
- args are now validated
- benefits from rich bb cli coercion support
- usage help shows using keyword :arg syntax

When running via -M:
- preserved existing behaviour
- support more coercions
- usage help shows using cli -arg syntax

General:
- Narrower, easier to read usage help
- Options relating only to dependency-check strategy are now grouped
under their own heading
- Some rewording/rewriting of descriptions for clarity
- Command line error styled in red for visibility
- Support for aligning multi-line argument descriptions
- File options fail fast if file does not exist
- More coercions to keywords happen at command parse time instead of
within code. Code adjusted appropriately.

Closes clj-holmes#77

CHANGELOG.md

@@ -1,5 +1,8 @@
 # CHANGELOG
 
+* Unreleased
+ * Improve command line experience [#77](https:/clj-holmes/clj-watson/issues/77)
+
 * v5.1.3 5812615 -- 2024-07-31
  * Address [#60](https:/clj-holmes/clj-watson/issues/60) by updating `org.owasp/dependency-check-core` to 10.0.3.
 

README.md

@@ -226,28 +226,34 @@ clojure -M:clj-watson -p deps.edn
 You can get a full list of the available options by running:
 
 ```bash
-clojure -M:clj-watson scan -\?
+clojure -M:clj-watson scan --help
 ```
 
 This produces:
 
 ```
-NAME:
- clj-watson scan - Performs a scan on a deps.edn file
+clj-watson
 
-USAGE:
- clj-watson scan [command options] [arguments...]
+ARG USAGE:
+ scan [options..]
 
 OPTIONS:
- -p, --deps-edn-path S* path of deps.edn to scan.
- -o, --output edn|json|sarif|stdout|stdout-simple stdout Output type.
- -a, --aliases S Specify a alias that will have the dependencies analysed alongside with the project deps.It's possible to provide multiple aliases. If a * is provided all the aliases are going to be analysed.
- -d, --dependency-check-properties S [ONLY APPLIED IF USING DEPENDENCY-CHECK STRATEGY] Path of a dependency-check properties file. If not provided uses resources/dependency-check.properties.
- -w, --clj-watson-properties S [ONLY APPLIED IF USING DEPENDENCY-CHECK STRATEGY] Path of an additional, optional properties file.
- -t, --database-strategy dependency-check|github-advisory dependency-check Vulnerability database strategy.
- -s, --[no-]suggest-fix false Suggest a new deps.edn file fixing all vulnerabilities found.
- -f, --[no-]fail-on-result false Enable or disable fail if results were found (useful for CI/CD).
- -?, --help
+ -p, --deps-edn-path <file> Path of deps.edn file to scan [*required*]
+ -o, --output <json|edn|stdout|stdout-simple|sarif> Output type for vulnerability findings [stdout]
+ -a, --aliases Include deps.edn aliases in analysis, specify '*' for all.
+ For multiple, repeat arg, ex: -a alias1 -a alias2
+ -t, --database-strategy <dependency-check|github-advisory> Vulnerability database strategy [dependency-check]
+ -s, --suggest-fix Include dependency remediation suggestions in vulnurability findings [false]
+ -f, --fail-on-result When enabled, exit with non-zero on any vulnerability findings
+ Useful for CI/CD [false]
+ -h, --help Show usage help
+
+OPTIONS valid when database-strategy is dependency-check:
+ -d, --dependency-check-properties <file> Path of a dependency-check properties file
+ If not provided uses resources/dependency-check.properties
+ -w, --clj-watson-properties <file> Path of an additional, optional properties file
+ Overrides values in dependency-check.properties
+ If not specified classpath is searched for cljwatson.properties
 ```
 
 By default, when using the DEPENDENCY-CHECK strategy, `clj-watson` will load

deps.edn

@@ -1,7 +1,7 @@
 {:deps {org.clojure/clojure {:mvn/version "1.11.1"}
+ org.babashka/cli {:mvn/version "0.8.60"}
  borkdude/edamame {:mvn/version "1.3.23"}
  cheshire/cheshire {:mvn/version "5.12.0"}
- cli-matic/cli-matic {:mvn/version "0.5.4"}
  clj-http/clj-http {:mvn/version "3.12.3"}
  clj-time/clj-time {:mvn/version "0.15.2"}
  org.apache.maven.resolver/maven-resolver-transport-http {:mvn/version "1.9.18"}
@@ -34,7 +34,8 @@
  nubank/mockfn {:mvn/version "0.7.0"}
  nubank/state-flow {:mvn/version "5.14.5"}}
  :main-opts ["-m" "kaocha.runner"]}
- ;; so we can run the recommended command from the README:
- :clj-watson {:replace-deps {io.github.clj-holmes/clj-watson
- {:git/tag "v5.1.1" :git/sha "ad5fe07"}}
- :main-opts ["-m" "clj-watson.cli" "scan"]}}}
+
+ ;; for dev: so we can run the recommended command from the README:
+ :clj-watson {:replace-deps {io.github.clj-holmes/clj-watson {:local/root "."}}
+ :main-opts ["-m" "clj-watson.cli"]
+ :ns-default clj-watson.entrypoint}}}

src/clj_watson/cli.clj

@@ -1,12 +1,10 @@
 (ns clj-watson.cli
  (:gen-class)
  (:require
- [cli-matic.core :as cli]
- [clj-watson.cli-spec :refer [CONFIGURATION]]
+ [clj-watson.cli-spec :as cli-spec]
  [clj-watson.entrypoint :as entrypoint]))
 
-(defn -main [& args]
- (cli/run-cmd args
- (update-in CONFIGURATION
- [:commands 0]
- assoc :runs entrypoint/scan)))
+(defn -main
+ "Entrypoint for -M cli usage"
+ [& args]
+ (entrypoint/do-scan (cli-spec/parse-args args)))