Take another swing at bb tasks

Babaska is finalizing its tasks implementation.
A good time for me to take them for another spin.

Direct benefits:
- A user can type bb tasks to get a list of available tasks with
  a short description of each.

Indirect benefits:
- Running tasks from a consistent launcher made me think about
  consistency. Actions I took:
  - All tasks now accept a --help arg
  - Tasks are somewhat (ish) more consistent in arg usage and validation
  - Tasks that take no args fail when args are provided

Observations:
- The fact that bb tasks shows tasks in the order they are defined
  in bb.edn is nice.
- My scripts usage help listed the script file in its help.
  For example "Usage: libs_tests.clj [check|gen-code]".
  I've adapted to focus on the args only, and now instead show:
  "Valid args: [check|gen-code]".
- bb's :enter and :leave and leave hooks are nice, they allow me
  to easily provide a title for each task and show when a task
  completed successfully.
  - For :leave to be called, I had to, of course, stop calling
    System/exit on success from one of my script

Other
- I've specified the new-ish :min-bb-version in bb.edn, folks using
  an older version of bb will not be able to take advantage of tasks.
- In testing I noticed that my clj-kondo rewrite-clj export config is
  being picked up when linting rewrite-clj. This is something we do not
  want/need, so I've adapted to exclude it for this operation.

Author: lread

bb.edn

@@ -1,9 +1,34 @@
-{:paths ["script"]
+{:min-bb-version "0.3.7"
+ :paths ["script"]
  :deps {org.clojure/data.zip {:mvn/version "1.0.0"}
         io.aviso/pretty {:mvn/version "0.1.37"}
         docopt/docopt {:git/url "https://github.com/nubank/docopt.clj"
                        :sha "98814f559d2e50fdf10f43cbe3b7da0ca3cca423"}
         doric/doric {:mvn/version "0.9.0"}
         version-clj/version-clj {:mvn/version "2.0.1"}
         lread/status-line {:git/url "https://github.com/lread/status-line.git"
-                           :sha "35ed39645038e81b42cb15ed6753b8462e60a06d"}}}
+                           :sha "35ed39645038e81b42cb15ed6753b8462e60a06d"}}
+ :tasks {;; setup
+         :requires ([lread.status-line :as status])
+         :enter (let [{:keys [name]} (current-task)] (status/line :head "TASK %s" name))
+         :leave (let [{:keys [name]} (current-task)] (status/line :detail "\nTASK %s done." name))
+         ;; commands
+         apply-import-vars {:task apply-import-vars/-main :doc "(check|gen-code) - export APIs statically from templates"}
+         lint              {:task lint/-main              :doc "[--rebuild-cache]"}
+         test-clj          {:task clj-tests/-main         :doc "[--clojure-version (1.9|1.10)]"}
+         test-cljs         {:task cljs-tests/-main        :doc "use --help for args"}
+         test-shadow-cljs  {:task shadow-cljs-test/-main}
+         test-native       {:task pure-native-test/-main  :doc "run rewrite-clj and tests after both compiled with GraalVM native-image"}
+         test-native-sci   {:task sci-native-test/-main   :doc "interpret rewrite-clj tests via sci from rewrite-clj native image"}
+         test-jvm-sci      {:task sci-jvm-test/-main      :doc "JVM only sanity test for test-native-sci"}
+         test-clj-watch    {:task clj-watch/-main         :doc "[kaocha args]"}
+         test-cljs-watch   {:task cljs-watch/-main        :doc "watch cljs test with fighweel main"}
+         test-coverage     {:task coverage/-main          :doc "generate code coverage reports for Clojure tests"}
+         test-doc          {:task doc-tests/-main         :doc "test doc code blocks"}
+         test-libs         {:task libs-tests/-main        :doc "(run|outdated) - verify taht libs using rewrite-clj* work with current rewrite-clj"}
+         outdated          {:task outdated/-main          :doc "report on outdated Clojure and npm dependencies"}
+         doc-api-diffs     {:task gen-api-diffs/-main     :doc "generate diff docs for rewrite-clj* APIs"}
+         doc-update-readme {:task update-readme/-main     :doc "honour our contributors in README"}
+         cljdoc-preview    {:task cljdoc-preview/-main    :doc "preview what docs will look like on cljdoc, use --help for args"}
+         ci-unit-tests     {:task ci-tests/-main}
+         ci-release        {:task release/-main           :doc "release tasks, use --help for args"}}}

deps.edn

@@ -20,6 +20,7 @@
 
            ;; linting
            :clj-kondo {:extra-deps {clj-kondo/clj-kondo {:mvn/version "2021.04.23"}}
+                       :replace-paths ["src"] ;; avoid including our exported clj-kondo config under resources
                        :main-opts ["-m" "clj-kondo.main"]}
 
 

script/apply_import_vars.clj

@@ -5,13 +5,25 @@
             [helper.shell :as shell]
             [lread.status-line :as status]))
 
+(def arg-usage (str "Valid args: (gen-code|check|--help)\n"
+                    "\n"
+                    " gen-code Generate API sources from templates\n"
+                    " check    Fail if API sources are stale as compared to templates\n"
+                    " --help   Show this help"))
+
 (defn -main[& args]
   (env/assert-min-versions)
   (let [cmd (first args)]
-    (when (not (#{"gen-code" "check"} cmd))
-      (status/die 1 "Usage: apply-import-vars [gen-code|check]"))
-    (status/line :head (str "Running apply import vars " cmd))
-    (shell/command ["clojure" "-X:apply-import-vars:script" cmd])
+    (cond
+      (= "--help" cmd)
+      (status/line :detail arg-usage)
+
+      (not (#{"gen-code" "check"} cmd))
+      (status/die 1 arg-usage)
+
+      :else
+      (do (status/line :head (str "Running apply import vars " cmd))
+          (shell/command ["clojure" "-X:apply-import-vars:script" cmd])))
     nil))
 
 (env/when-invoked-as-script

script/ci_tests.clj

@@ -3,6 +3,7 @@
 (ns ci-tests
   (:require [helper.env :as env]
             [helper.fs :as fs]
+            [helper.main :as main]
             [helper.shell :as shell]
             [lread.status-line :as status]))
 
@@ -36,17 +37,20 @@
     (shell/command ["bb" "./script/cljs_tests.clj" "--env" "planck" "--optimizations" "none"])
     (status/line :warn "skipping planck tests, they can only be run on linux and macOS")) )
 
-(defn -main[]
-  (env/assert-min-versions)
-  (clean)
-  (check-import-vars)
-  (lint)
-  (doc-tests)
-  (clojure-tests)
-  (cljs-tests)
-  (shadow-cljs-tests)
-  (cljs-bootstrap-tests)
+(defn -main [& args]
+  (main/run-argless-cmd
+   args
+   (fn []
+     (env/assert-min-versions)
+     (clean)
+     (check-import-vars)
+     (lint)
+     (doc-tests)
+     (clojure-tests)
+     (cljs-tests)
+     (shadow-cljs-tests)
+     (cljs-bootstrap-tests)))
   nil)
 
 (env/when-invoked-as-script
- (-main))
+ (-main *command-line-args*))

script/clj_tests.clj

@@ -18,21 +18,28 @@
    ["-h" "--help"]])
 
 (defn usage [options-summary]
-  (->> ["Usage: cljs_test.clj <options>"
+  (->> ["Valid args: <options>"
         options-summary]
        (string/join "\n")))
 
-(defn error-msg [errors]
-  (string/join "\n" errors))
+(defn error-msg [summary errors]
+  (str (string/join "\n" errors)
+       "\n\n"
+       (usage summary)))
 
 (defn validate-args [args]
-  (let [{:keys [options errors summary]} (cli/parse-opts args cli-options)]
+  (let [{:keys [options arguments errors summary]} (cli/parse-opts args cli-options)]
     (cond
       (:help options)
       {:exit-message (usage summary) :exit-code 0}
 
+      (seq arguments)
+      {:exit-message (error-msg summary (map #(str "unexpected argument: " %) arguments))
+       :exit-code 1}
+
       errors
-      {:exit-message (error-msg errors) :exit-code 1}
+      {:exit-message (error-msg summary errors)
+       :exit-code 1}
 
       :else
       {:options options})))

script/clj_watch.clj

@@ -5,10 +5,10 @@
             [helper.shell :as shell]
             [lread.status-line :as status]))
 
-(defn -main []
+(defn -main [& args]
   (env/assert-min-versions)
   (status/line :head "launching kaocha watch on clojure sources")
-  (shell/command (concat ["clojure" "-M:test-common:kaocha" "--watch"] *command-line-args*)))
+  (shell/command (concat ["clojure" "-M:test-common:kaocha" "--watch"] args)))
 
 (env/when-invoked-as-script
- (-main))
+ (-main *command-line-args*))

script/cljdoc_preview.clj

@@ -136,7 +136,7 @@
   (status/line :head "Waiting for %s to become available" (:name container))
   (when (= "down" (status-server container))
     (status/die 1
-                "%s does not seem to be running.\nDid you run this script with the start command yet?"
+                "%s does not seem to be running.\nDid you run the start command yet?"
                 (:name container)))
   (status/line :detail "%s container is running" (:name container))
   (let [url (str "http://localhost:" (:port container))]
@@ -195,7 +195,7 @@
 (defn view-in-browser [url]
   (status/line :head "opening %s in browser" url)
   (when (not= 200 (:status (curl/get url {:throw false})))
-    (status/die 1 "Could not reach:\n%s\nDid you run this script with ingest command yet?" url))
+    (status/die 1 "Could not reach:\n%s\nDid you run the ingest command yet?" url))
   (browse/browse-url url))
 
 
@@ -215,12 +215,28 @@
 (defn cleanup-resources []
   (fs/delete-file-recursively cljdoc-db-dir true))
 
+(def usage (string/join "\n"
+                        ["Valid args: [start|ingest|view|stop|status]"
+                         ""
+                         " start  - start docker containers supporting cljdoc preview"
+                         " ingest - locally publishes your project for cljdoc preview"
+                         " view   - opens cljdoc preview in your default browser"
+                         " stop   - stops docker containers supporting cljdoc preview"
+                         " status - status of docker containers supporting cljdoc preview"
+                         ""
+                         " --help - show this help"
+                         ""
+                         "Must be run from project root directory."]))
+
 (defn -main [& args]
 
   (check-prerequisites)
 
   (let [command (first args)]
     (case command
+      "--help"
+      (status/line :detail usage)
+
       "start"
       (do
         (start-cljdoc-server cljdoc-container)
@@ -249,16 +265,7 @@
         nil)
 
       ;; else
-      (do (println "Usage: bb script/cljdoc_preview.clj [start|ingest|view|stop|status]")
-          (println "")
-          (println " start  - start docker containers supporting cljdoc preview")
-          (println " ingest - locally publishes your project for cljdoc preview")
-          (println " view   - opens cljdoc preview in your default browser")
-          (println " stop   - stops docker containers supporting cljdoc preview")
-          (println " status - status of docker containers supporting cljdoc preview")
-          (println "")
-          (println "Must be run from project root directory.")
-          (System/exit 1)))))
+      (status/die 1 usage))))
 
 (env/when-invoked-as-script
  (apply -main *command-line-args*))

script/cljs_tests.clj

@@ -26,21 +26,28 @@
    ["-h" "--help"]])
 
 (defn usage [options-summary]
-  (->> ["Usage: cljs_test.clj <options>"
+  (->> ["Valid args: <options>"
         options-summary]
        (string/join "\n")))
 
-(defn error-msg [errors]
-  (string/join "\n" errors))
+(defn error-msg [summary errors]
+  (str (string/join "\n" errors)
+       "\n\n"
+       (usage summary)))
 
 (defn validate-args [args]
-  (let [{:keys [options errors summary]} (cli/parse-opts args cli-options)]
+  (let [{:keys [options arguments errors summary]} (cli/parse-opts args cli-options)]
     (cond
       (:help options)
       {:exit-message (usage summary) :exit-code 0}
 
+      (seq arguments)
+      {:exit-message (error-msg summary (map #(str "unexpected argument: " %) arguments))
+       :exit-code 1}
+
       errors
-      {:exit-message (error-msg errors) :exit-code 1}
+      {:exit-message (error-msg summary errors)
+       :exit-code 1}
 
       :else
       {:options options})))

script/cljs_watch.clj

@@ -2,13 +2,17 @@
 
 (ns cljs-watch
   (:require [helper.env :as env]
+            [helper.main :as main]
             [helper.shell :as shell]
             [lread.status-line :as status]))
 
-(defn -main []
-  (env/assert-min-versions)
-  (status/line :detail "compiling code, then opening repl, afterwich your web browser will automatically open to figwheel test run summary")
-  (shell/command ["clojure" "-M:test-common:cljs:fig-test"]))
+
+(defn -main [& args]
+  (main/run-argless-cmd
+   args
+   (fn []
+     (status/line :detail "compiling code, then opening repl, afterwich your web browser will automatically open to figwheel test run summary")
+     (shell/command ["clojure" "-M:test-common:cljs:fig-test"]))))
 
 (env/when-invoked-as-script
- (-main))
+ (-main *command-line-args*))

script/coverage.clj

@@ -2,6 +2,7 @@
 
 (ns coverage
   (:require [helper.env :as env]
+            [helper.main :as main]
             [helper.shell :as shell]
             [lread.status-line :as status]))
 
@@ -17,11 +18,13 @@
                   "--no-randomize"
                   "--reporter" "documentation"]))
 
-(defn -main []
-  (env/assert-min-versions)
-  (generate-doc-tests)
-  (run-clj-doc-tests)
+(defn -main [& args]
+  (main/run-argless-cmd
+   args
+   (fn []
+     (generate-doc-tests)
+     (run-clj-doc-tests)))
   nil)
 
 (env/when-invoked-as-script
- (-main))
+ (-main *command-line-args*))