docs: readme: update contributors (#22)

Switch to using etaoin for generating contributor badges (mostly
borrowed from work I did on cljdoc).

.clj-kondo/etaoin/etaoin/config.edn

@@ -0,0 +1,32 @@
+{:linters
+ {:etaoin/with-x-action {:level :error}
+  :etaoin/binding-sym {:level :error}
+  :etaoin/opts-map-type {:level :error}
+  :etaoin/opts-map-pos {:level :error}
+  :etaoin/empty-opts {:level :warning}}
+ :hooks
+ {:analyze-call
+  {etaoin.api/with-chrome            etaoin.api/with-browser
+   etaoin.api/with-chrome-headless   etaoin.api/with-browser
+   etaoin.api/with-firefox           etaoin.api/with-browser
+   etaoin.api/with-firefox-headless  etaoin.api/with-browser
+   etaoin.api/with-edge              etaoin.api/with-browser
+   etaoin.api/with-edge-headless     etaoin.api/with-browser
+   etaoin.api/with-phantom           etaoin.api/with-browser
+   etaoin.api/with-safari            etaoin.api/with-browser
+
+   etaoin.api/with-driver            etaoin.api/with-driver
+   etaoin.api/with-key-down          etaoin.api/with-key-down
+   etaoin.api/with-pointer-btn-down  etaoin.api/with-pointer-btn-down
+
+   ;; api2 moves to a more conventional let-ish vector syntax
+   etaoin.api2/with-chrome           etaoin.api2/with-browser
+   etaoin.api2/with-chrome-headless  etaoin.api2/with-browser
+   etaoin.api2/with-edge             etaoin.api2/with-browser
+   etaoin.api2/with-edge-headless    etaoin.api2/with-browser
+   etaoin.api2/with-firefox          etaoin.api2/with-browser
+   etaoin.api2/with-firefox-headless etaoin.api2/with-browser
+   etaoin.api2/with-phantom          etaoin.api2/with-browser
+   etaoin.api2/with-safari           etaoin.api2/with-browser}}
+ :lint-as
+ {etaoin.api/with-pointer-left-btn-down clojure.core/->}}

.clj-kondo/etaoin/etaoin/etaoin/api.clj_kondo

@@ -0,0 +1,113 @@
+(ns etaoin.api
+  (:require [clj-kondo.hooks-api :as api]
+            [etaoin.hooks-util :as h]))
+
+(defn- nil-node? [n]
+  (and (api/token-node? n) (nil? (api/sexpr n))))
+
+(defn- with-bound-arg [node arg-offset]
+  (let [macro-args (rest (:children node))
+        leading-args (take arg-offset macro-args)
+        interesting-args (drop arg-offset macro-args)
+        [opts binding-sym & body] (if (h/symbol-node? (second interesting-args))
+                                    interesting-args
+                                    (cons nil interesting-args))]
+    ;; if the user has specified nil or {} for options we can suggest that is not necessary
+    (when (and opts
+               (or (and (api/map-node? opts) (not (seq (:children opts))))
+                   (nil-node? opts)))
+      (api/reg-finding! (assoc (meta opts)
+                               :message "Empty or nil driver options can be omitted"
+                               :type :etaoin/empty-opts)))
+
+    (cond
+      (not (h/symbol-node? binding-sym))
+      ;; it makes more sense here to report on the incoming node position instead of what we expect to be the binding-sym
+      (api/reg-finding! (assoc (meta node)
+                               :message "Expected binding symbol for driver"
+                               :type :etaoin/binding-sym))
+
+      ;; we don't want to explicitly expect a map because the map might come from
+      ;; an evalution, but we can do some checks
+      (and opts ;; we'll assume a list-node is a function call (eval)
+           (not (nil-node? opts)) ;; nil is actually old-v1 syntax acceptable
+           (not (api/list-node? opts)) ;; some fn call
+           (not (h/symbol-node? opts)) ;; from a binding maybe
+           ;; there are other eval node types... @(something) for example... maybe we'll add them in if folks ask
+           (not (api/map-node? opts)))
+      ;; we can report directly on the opts node, because at this point we know we expect
+      ;; this arg position to be an opts map
+      (api/reg-finding! (assoc (meta opts)
+                               :message "When specified, opts should be a map"
+                               :type :etaoin/opts-map-type))
+
+      ;; one last nicety, if the first form in body is a map, the user has accidentally swapped
+      ;; binding and opt args
+      (api/map-node? (first body))
+      (api/reg-finding! (assoc (meta (first body))
+                               :message "When specified, opts must appear before binding symbol"
+                               :type :etaoin/opts-map-pos))
+
+      :else
+      {:node (api/list-node
+               (list*
+                 (api/token-node 'let)
+                 ;; simulate the effect, macro is creating a new thing (driver for example)
+                 ;; via binding it. I don't think the bound value matters for the linting process
+                 (api/vector-node [binding-sym (api/map-node [])])
+                 ;; reference the other args so that they are not linted as unused
+                 (api/vector-node leading-args)
+                 opts ;; might be a binding, so ref it too
+                 body))})))
+
+(defn- with-x-down
+  "This is somewhat of a maybe an odd duck.
+  I think it is assumed to be used within a threading macro.
+  And itself employs a threadfirst macro.
+  So each body form need to have an action (dummy or not) threaded into it."
+  [node]
+  (let [macro-args (rest (:children node))
+        [input x & body] macro-args
+        dummy-action (api/map-node [])]
+    {:node (api/list-node
+            (apply list*
+                   (api/token-node 'do)
+                   ;; reference x and input just in case they contain something lint-relevant
+                   x input
+                   ;; dump the body, threading a dummy action in as first arg
+                   (map (fn [body-form]
+                          (cond
+                            ;; not certain this is absolutely what we want, but maybe close enough
+                            (h/symbol-node? body-form) (api/list-node (list* body-form dummy-action))
+                            (api/list-node? body-form) (let [children (:children body-form)]
+                                                         (assoc body-form :children (apply list*
+                                                                                           (first children)
+                                                                                           dummy-action
+                                                                                           (rest children))))
+                            :else
+                            (api/reg-finding! (assoc (meta body-form)
+                                                     :message "expected to be threaded through an action"
+                                                     :type :etaoin/with-x-action))))
+                        body)))}))
+
+(defn with-browser
+  "Covers etaoin.api/with-chrome and all its variants
+  [opt? bind & body]"
+  [{:keys [node]}]
+  (with-bound-arg node 0))
+
+(defn with-driver
+  "Very similar to with-browser but bound arg is 1 deeper
+  [type opt? bind & body]"
+  [{:keys [node]}]
+  (with-bound-arg node 1))
+
+(defn with-key-down
+  "[input key & body]"
+  [{:keys [node]}]
+  (with-x-down node))
+
+(defn with-pointer-btn-down
+  "[input button & body]"
+  [{:keys [node]}]
+  (with-x-down node))

.clj-kondo/etaoin/etaoin/etaoin/api2.clj_kondo

@@ -0,0 +1,27 @@
+(ns etaoin.api2
+  (:require [clj-kondo.hooks-api :as api]
+            [etaoin.hooks-util :as h]))
+
+(defn with-browser
+  "Newer variants for api2
+  [[bind & [options]] & body]"
+  [{:keys [node]}]
+  (let [macro-args (rest (:children node))
+        binding-like-vector (first macro-args)]
+    (if-not (api/vector-node? binding-like-vector)
+      ;; could use clj-kondo findings, but I think this is good for now
+      (throw (ex-info "Expected vector for first arg" {}))
+      (let [binding-sym (-> binding-like-vector :children first)]
+        (if-not (h/symbol-node? binding-sym)
+          (throw (ex-info "Expected binding symbol for first arg in vector" {}))
+          (let [other-args (rest binding-like-vector)
+                body (rest macro-args)]
+            {:node (api/list-node
+                    (list*
+                     (api/token-node 'let)
+                     ;; simulate the effect, macro is creating a new thing (driver for example)
+                     ;; via binding it. I don't think the bound value matters for the linting process
+                     (api/vector-node [binding-sym (api/map-node [])])
+                     ;; reference the other args so that they are not linted as unused
+                     (api/vector-node other-args)
+                     body))}))))))

.clj-kondo/etaoin/etaoin/etaoin/hooks_util.clj_kondo

@@ -0,0 +1,6 @@
+(ns etaoin.hooks-util
+  (:require [clj-kondo.hooks-api :as api]))
+
+(defn symbol-node? [node]
+  (and (api/token-node? node)
+       (symbol? (api/sexpr node))))

README.adoc

@@ -62,26 +62,26 @@ Test-doc-block versioning scheme is: `major`.`minor`.`patch`-`test-qualifier`
 // Contributors updated by script, do not edit
 // AUTO-GENERATED:CONTRIBUTORS-START
 :imagesdir: ./doc/generated/contributors
-[.float-group]
+[]
 --
-image:seancorfield.png[seancorfield,role="left",width=310,link="https://github.com/seancorfield"]
-image:MIJOTHY.png[MIJOTHY,role="left",width=310,link="https://github.com/MIJOTHY"]
-image:borkdude.png[borkdude,role="left",width=310,link="https://github.com/borkdude"]
-image:holyjak.png[holyjak,role="left",width=310,link="https://github.com/holyjak"]
-image:PEZ.png[PEZ,role="left",width=310,link="https://github.com/PEZ"]
-image:SevereOverfl0w.png[SevereOverfl0w,role="left",width=310,link="https://github.com/SevereOverfl0w"]
-image:sogaiu.png[sogaiu,role="left",width=310,link="https://github.com/sogaiu"]
-image:uochan.png[uochan,role="left",width=310,link="https://github.com/uochan"]
+image:seancorfield.png[seancorfield,width=273,link="https://github.com/seancorfield"]
+image:MIJOTHY.png[MIJOTHY,width=273,link="https://github.com/MIJOTHY"]
+image:borkdude.png[borkdude,width=273,link="https://github.com/borkdude"]
+image:holyjak.png[holyjak,width=273,link="https://github.com/holyjak"]
+image:PEZ.png[PEZ,width=273,link="https://github.com/PEZ"]
+image:SevereOverfl0w.png[SevereOverfl0w,width=273,link="https://github.com/SevereOverfl0w"]
+image:sogaiu.png[sogaiu,width=273,link="https://github.com/sogaiu"]
+image:uochan.png[uochan,width=273,link="https://github.com/uochan"]
 --
 // AUTO-GENERATED:CONTRIBUTORS-END
 
 === Current Maintainers
 // Maintainers updated by script, do not edit
 // AUTO-GENERATED:MAINTAINERS-START
 :imagesdir: ./doc/generated/contributors
-[.float-group]
+[]
 --
-image:lread.png[lread,role="left",width=310,link="https://github.com/lread"]
+image:lread.png[lread,width=273,link="https://github.com/lread"]
 --
 // AUTO-GENERATED:MAINTAINERS-END
 

bb.edn

@@ -3,7 +3,8 @@
  :deps {lread/status-line {:git/url "https://github.com/lread/status-line.git"
                            :sha "cf44c15f30ea3867227fa61ceb823e5e942c707f"}
         dev.nubank/docopt {:mvn/version "0.6.1-fix7"}
-        version-clj/version-clj {:mvn/version "2.0.2"}}
+        version-clj/version-clj {:mvn/version "2.0.2"}
+        etaoin/etaoin {:mvn/version "1.0.40"}}
 
  :tasks {;; setup
          :requires ([babashka.fs :as fs]