Test against popular libaries

Add script/lib_tests.clj to test rewrite-clj against popular libraries.

Reworked release script a tad so that I could reuse its version
calculation support.

Includes stab at GitHub Actions libs-test workflow.

Closes #124

.github/workflows/libs-test.yml

@@ -0,0 +1,45 @@
+name: Libs Test
+
+on: push
+
+jobs:
+  libs-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Clojure deps cache
+      uses: actions/cache@v2
+      with:
+        path: |
+          ~/.m2/repository
+          ~/.gitlibs
+        # base cache on libs_test.clj script for now... lib deps are embedded in it
+        key: $${ runner.os }}-clj-libs-deps-${{ hashFiles('script/libs_tests.clj') }}
+        restore-keys: $${ runner.os }}-clj-libs-deps-
+
+    - name: Setup Java
+      uses: actions/setup-java@v1
+      with:
+        java-version: 11
+
+    - name: Install Babashka
+      run: curl -s https://raw.githubusercontent.com/borkdude/babashka/master/install | sudo bash
+
+    - name: Install Clojure
+      run: curl -s https://download.clojure.org/install/linux-install-1.10.1.763.sh | sudo bash
+
+    - name: Tools versions
+      run: |
+        echo "bb --version"
+        bb --version
+        echo "java -version"
+        java -version
+        echo "clojure -Sdescribe"
+        clojure -Sdescribe
+        echo "lein --version"
+        lein --version
+
+    - name: Run Libs Tests
+      run: bb ./script/libs_tests.clj

CHANGELOG.adoc

@@ -80,6 +80,7 @@ Rewrite-cljs users migrating to rewrite-clj v1 are now at, and will remain at, f
 * Now testing rewrite-clj compiled under GraalVM native-image in two variants:
 ** In a pure form where library and tests are compiled
 ** Via sci where a sci exposed rewrite-clj is compiled, then tests are interpreted.
+* Now automatically testing rewrite-clj against popular libs https://github.com/clj-commons/rewrite-clj/issues/124[#124]
 * Now linting source with clj-kondo, added some custom hooks for our variations on import-vars
 * Code coverage reports now generated for Clojure unit test run and sent to codecov.io
 * Can now preview for cljdoc locally via `script/cljdoc_preview.clj`

deps.edn

@@ -63,7 +63,7 @@
                     :extra-deps {org.clojure/tools.namespace {:mvn/version "1.1.0"}
                                  cli-matic/cli-matic {:mvn/version "0.4.3"}}}
 
-           :apply-import-vars {:extra-deps { metosin/malli {:mvn/version "0.2.1"}}
+           :apply-import-vars {:extra-deps {metosin/malli {:mvn/version "0.2.1"}}
                                :ns-default lread.apply-import-vars}
 
            ;;
@@ -117,4 +117,12 @@
                                    }
                       :main-opts ["-m" "antq.core"
                                   "--exclude=borkdude/sci.impl.reflector" ;; does not follow normal versioning conventions at this time
-                                  ]}}}
+                                  ]}
+
+           ;;
+           ;; 3rd party lib testing support
+           ;;
+
+           :deps-patcher {:extra-paths ["script"]
+                          :ns-default lread.deps-patcher}}}
+

doc/02-developer-guide.adoc

@@ -179,10 +179,13 @@ This generates tests for doc code blocks and then runs them under Clojure and Cl
 == Testing Before a Push
 Before pushing, you likely want to mimic what is run on each push via GitHub Actions.
 
+=== Unit tests
 Unit tests are run via:
 ----
 bb ./script/ci_tests.clj
 ----
+
+=== Native image tests
 We also verify that rewrite-clj functions as expected when compiled via Graal's `native-image`.
 
 1. Tests and library natively compiled:
@@ -196,6 +199,41 @@ bb ./script/pure_native_test.clj
 bb ./script/sci_native_test.clj
 ----
 
+=== Libs test
+To try to ensure our changes to rewrite-clj do not inadvertently break existing popular libraries, we run their tests, or a portion thereof, against rewrite-clj.
+
+----
+bb ./script/libs_tests.clj
+----
+
+Current libs we test against:
+
+* antq
+* carve
+* cljfmt
+* clojure-lsp
+* mranderson
+* rewrite-edn
+* refactor-nrepl
+* zprint
+
+Additional libs are welcome.
+
+If you are troubleshooting locally, and want to only run specific tests, you can specify which ones you'd like to run. For example:
+
+----
+bb ./script/libs_tests.clj cljfmt zprint
+----
+
+Notes:
+
+* `libs_tests.clj` was developped on macOS and is run on CI under Linux only under JDK 11 only.
+We can expand variations at some later date if there is any value to it.
+* We test the current HEAD of rewrite-clj v1 against specific versions (latest at the time of this writing) of libs.
+* We patch lib deps and sometimes code (ex. `require` for `rewrite-cljc` becomes `rewrite-clj`).
+* As folks migrate to rewrite-clj v1, the need for current patches will lessen.
+* Updating what versions we test against is currently a manual, but not an overly burdensome, task.
+
 == Checking for Outdated Dependencies
 
 To see what new dependencies are available, run:

doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc

@@ -51,120 +51,148 @@ We'll happily continue with `rewrite-clj` for rewrite-clj v1 work:
 . rewrite-clj v1 will carry on in clj-commons/rewrite-clj
 . we'll continue to use the existing rewrite-clj v0 clojar maven coordinates `xsc/rewrite-clj` for rewrite-clj v1
 
+[#rewrite-clj-legacy-libs]
 == Projects Using rewrite-clj v0 and/or rewrite-cljs
 I've tried to make note of popular/active projects that make use of rewrite-clj v0 and rewrite-cljs.
 I've linked where I've explicitly verified a migration to rewrite-clj v1.
 
 [cols="15%,20%,20%,15%,30%"]
 |===
-| Project | rewrite‑clj? | rewrite‑cljs? | Migration Verification.footnote:[rewrite-cljc forks will be reverified for rewrite-clj v1] | Notes
+| Project | rewrite‑clj? | rewrite‑cljs? | link:#canary-testing[Canary Tested?] | Notes
 
 | https://github.com/mauricioszabo/atom-chlorine[chlorine]
-| no
+|
 | yes
-| -
+|
 | REPL support for Atom editor
 
 | https://github.com/borkdude/clj-kondo[clj-kondo]
 | custom version
-| no
-| -
+|
+|
 | uses an internal custom version of rewrite-clj
 
 | https://github.com/weavejester/cljfmt[cljfmt]
 | yes
 | yes
-| https://github.com/lread/cljfmt/commits/lread-rewrite-cljc-test[rewrite-cljc fork]
+| yes
 | source code formatter
 
 | https://github.com/greglook/cljstyle[cljstyle]
 | yes
-| no
-| -
+|
+|
 | source code formatter based on cljfmt
 
 | https://github.com/snoe/clojure-lsp[clojure-lsp]
 | yes
-| no
-| https://github.com/lread/clojure-lsp/commits/lread-rewrite-cljc-test[rewrite-cljc fork]
+|
+| yes
 | language server for Clojure
 
 | https://github.com/Olical/depot[depot]
 | yes
-| no
-| -
+|
+|
 | find newer versions of your deps.edn dependencies
 
 | https://github.com/jonase/kibit[kibit]
 | yes
-| no
-| -
+|
+|
 | Finds non-idiomatic Clojure code
 
 | https://github.com/xsc/lein-ancient[lein-ancient]
 | yes
-| no
-| -
+|
+|
 | find newer versions of your lein dependencies
 
 | https://github.com/benedekfazekas/mranderson[MrAnderson]
 | yes
-| no
-| -
+|
+| yes
 | Dependency inliner
 
 | https://github.com/jstepien/mutant[mutant]
 | yes
-| no
-| -
+|
+|
 | Source code mutator
 
 | https://github.com/juxt/pack.alpha[pack (alpha)]
 | yes
-| no
-| -
+|
+|
 | Clojure project packager
 
 | https://github.com/bhauman/rebel-readline[rebel-readline]
 | indirectly via cljfmt
-| no
-| -
+|
+|
 | smart editing at at the REPL terminal, optionally used in conjunction with https://github.com/bhauman/figwheel-main[figwheel-main]
 
 | https://github.com/cognitect-labs/REBL-distro[REBL]
 | indirectly via cljfmt
-| no
-| -
+|
+|
 | graphical interactive tool for browsing Clojure data
 
 | https://github.com/clojure-emacs/refactor-nrepl[refactor-nrepl]
 | yes
-| no
-| https://github.com/lread/refactor-nrepl/commits/lread-rewrite-cljc-test[rewrite-cljc fork]
+|
+| yes
 | refactoring support used in conjunction with https://github.com/clojure-emacs/cider[cider]
 
 | https://github.com/mauricioszabo/repl-tooling[repl-tooling]
-| no
+|
 | yes
-| -
+|
 | base package for Clojure editor tooling. Interesting: uses rewrite-clj.reader directly.
 
 | https://github.com/atomist-skills/update-leiningen-dependencies-skill[update-leiningen-dependencies-skill]
-| no
+|
 | yes
-| https://github.com/lread/update-leiningen-dependencies-skill/commits/lread-rewrite-cljc-test[rewrite-cljc fork]
+|
 | dependency version tracker, great for a migration test of a project that uses shadow-cljs
 
 | https://github.com/kkinnear/zprint[zprint]
 | yes
 | yes
-| https://github.com/lread/zprint/commits/lread-rewrite-cljc-test[rewrite-cljc fork]
+| yes
 | source code formatter
 
 |===
 
+[#rewrite-clj-v1-libs]
 == Projects Using rewrite-clj v1
-We have at least one early adopter!: https://github.com/borkdude/carve[carve]
+We have at least three early adopters, for all of which we do link:#canary-testing[canary testing]:
+
+* https://github.com/liquidz/antq[antq]
+* https://github.com/borkdude/carve[carve]
+* https://github.com/borkdude/rewrite-edn[rewrite-edn]
+
+[#canary-testing]
+== Canary Testing
+I'm not sure if canary testing is exactly the right term here.
+My goal is to know when changes to rewrite-clj v1 break popular libraries.
+
+This would mean running these libraries' tests against rewrite-clj v1 master.
+
+After some experimentation, my general strategy is to:
+
+. Install rewrite-clj HEAD to the local maven repository under a "canary" version
+. For each library we want to test:
+.. Grab the a specified release of a project from GitHub via zip download
+.. Patch deps to
+... Point to rewrite-clj canary release
+... Adjust Clojure version if necessary (we are 1.9 and above)
+.. Adjust sources as necessary
+... Ex. rewrite-cljc -> rewrite-clj namespace
+... At the time of the writing only zprint v1.1.1. needed a src code hack to get its tests passing.
+It is the only lib that digs into namespaced maps, and things changed a tad here for rewrite-clj v1
+.. Run any necessary library test prep steps
+.. Run libraries tests (or a subset of them)
 
 == Tooling