test+docs: spec coverage for migratus-enablement fixes; list migratus

Adds spec/conformance coverage for everything landed enabling migratus:
- conformance corpus (runs interpret/compile/self-host): def 3-arg docstring,
  def/defn ^{:map} name meta, defmacro arity-clause + docstring, defmulti
  docstring, assoc-nil/assoc-in real maps, try multi-body + finally-on-success,
  current-ns restore after a caught throw, cross-ns methods visibility.
- spec suites: host-interop (exception ctors, Character/Thread/Long, Timestamp/
  SimpleDateFormat, java.io.File model + File-aware file-seq, clojure.tools.logging),
  regex (Pattern statics + MULTILINE + quote, String .matches/.replaceAll/
  .replaceFirst), maps (assoc on nil), multimethods (defmulti docstring +
  value-based methods/get-method), macros (defmacro arity-clause + name meta).

Rewrote clojure.tools.logging/spy as a single variadic arity (jolt defmacro
takes only the first clause of a multi-arity macro — jolt-q8l).

docs/libraries.md: add migratus and the next.jdbc compatibility layer, with the
janet-lang/sqlite3 int64 caveat for 14-digit timestamp ids.

Full gate green; conformance 350/350 x3 modes.

docs/libraries.md

@@ -20,3 +20,13 @@ Libraries confirmed to load and pass their conformance checks on Jolt
   (select/insert/update/delete/joins/:inline), loaded unmodified from git
 * [clojure.jdbc](https://github.com/yogthos/clojure.jdbc) — as [jolt-lang/db](https://github.com/jolt-lang/db)'s
   `jdbc.core`, reimplemented over janet sqlite3/pq drivers (SQLite + PostgreSQL)
+* [next.jdbc](https://github.com/seancorfield/next-jdbc) — a compatibility layer in
+  [jolt-lang/db](https://github.com/jolt-lang/db) (`next.jdbc`, `next.jdbc.sql`,
+  `next.jdbc.prepare`, `next.jdbc.transaction`) over `jdbc.core`, for libraries
+  that target the next.jdbc API
+* [migratus](https://github.com/yogthos/migratus) — database migrations; loads
+  unmodified and runs filesystem SQL/EDN migrations against SQLite through the
+  next.jdbc layer above. `migrate`/`rollback` round-trip end to end. Caveat:
+  migration ids are 14-digit timestamps, and the janet-lang/sqlite3 driver
+  currently truncates INTEGER columns to 32 bits, so completion tracking needs
+  the one-line upstream fix (`sqlite3_column_int64`); ids under 2^31 work as is.

src/jolt/clojure/tools/logging.clj

@@ -65,9 +65,11 @@
 
 (defmacro spy
   "Evaluate expr, log it at the given level (default :debug) as expr => value,
-  and return the value."
+  and return the value. Single variadic arity (jolt defmacro takes only the
-  ([expr] `(spy :debug ~expr))
+  first clause of a multi-arity macro), dispatching on arg count."
-  ([level expr]
+  [& args]
-   `(let [a# ~expr]
+  (let [level (if (= 1 (count args)) :debug (first args))
-      (logp ~level (print-str '~expr "=>" (pr-str a#)))
+        expr  (if (= 1 (count args)) (first args) (second args))]
-      a#)))
+    `(let [a# ~expr]
+       (logp ~level (print-str '~expr "=>" (pr-str a#)))
+       a#)))

test/integration/conformance-test.janet

@@ -462,6 +462,39 @@
    ["not-any?"               "true"  "(not-any? even? [1 3 5])"]
    ["take-last"              "[3 4]" "(take-last 2 [1 2 3 4])"]
    ["replace nil val"        "[1 nil 3]" "(replace {2 nil} [1 2 3])"]
+
+   ### ---- migratus enablement: def/defmacro/defmulti forms, assoc, try, ns ----
+   # (def name docstring value): the value is the 3rd form, not the docstring
+   # (jolt-6ym — the analyzer used to bind the docstring as the value).
+   ["def 3-arg docstring"     "42"   "(do (def dd \"the doc\" 42) dd)"]
+   ["def docstring value type" "true" "(do (def ds \"doc\" [1 2]) (vector? ds))"]
+   # ^{:map} metadata on a def/defn name reads as a with-meta form (jolt-8w2);
+   # def/defn/defmacro unwrap it instead of choking.
+   ["def ^{:map} name"        "5"    "(do (def ^{:private true} mmv 5) mmv)"]
+   ["defn ^{:map} name"       "25"   "(do (defn ^{:private true} sqf [x] (* x x)) (sqf 5))"]
+   # defmacro arity-clause form (jolt-whp) and a leading docstring (with-store shape)
+   ["defmacro arity-clause"   "10"   "(do (defmacro m2c ([x] (list (quote *) x 2))) (m2c 5))"]
+   ["defmacro doc + arity"    "30"   "(do (defmacro m3c \"doc\" ([x] (list (quote *) x 3))) (* (m3c 5) 2))"]
+   # defmulti drops a leading docstring (jolt-es4 — it used to be the dispatch fn)
+   ["defmulti docstring"      "\"A\"" "(do (defmulti gmm \"the doc\" identity) (defmethod gmm :a [_] \"A\") (gmm :a))"]
+   # (assoc nil k v) yields a real map (jolt-w4s); assoc-in nests real maps
+   ["assoc nil is a map"      "1"    "(count (assoc nil :a 1))"]
+   ["assoc-in nested is a map" "1"   "(count (:a (assoc-in {} [:a :b] 1)))"]
+   ["assoc-in deep get"       "9"    "(get-in (assoc-in {} [:a :b :c] 9) [:a :b :c])"]
+   # try: a multi-form body and finally that runs on the SUCCESS path with a
+   # catch present (jolt-0z9 — body forms past the first were dropped and
+   # finally was skipped on success).
+   ["try multi-body last"     "3"    "(try 1 2 3 (catch :default e 0))"]
+   ["try finally on ok+catch" "9"    "(let [a (atom 0)] (try 1 2 (catch :default e :c) (finally (reset! a 9))) @a)"]
+   ["try finally on throw"    "9"    "(let [a (atom 0)] (try (throw (ex-info \"x\" {})) (catch :default e nil) (finally (reset! a 9))) @a)"]
+   # current-ns is restored after a caught throw (jolt-96m): the alias/ns seen by
+   # code after the catch is the one at the catch site, not the thrower's.
+   ["ns restored after catch" "\"user\""
+    "(do (ns cf.boom) (defn bz [] (throw (Exception. \"e\"))) (in-ns (quote user)) (try (cf.boom/bz) (catch :default e nil)) (str *ns*))"]
+   # methods sees cross-ns defmethods through a bare multifn ref in its defining
+   # ns (jolt-9pu — it used to see an empty table).
+   ["cross-ns methods visible" "[:sql]"
+    "(do (ns cf.mm) (defmulti ext identity) (defmethod ext :default [_] :d) (defn allk [] (vec (for [[k v] (methods ext) :when (not= k :default)] k))) (ns cf.mmi) (defmethod cf.mm/ext :sql [_] :s) (in-ns (quote user)) (cf.mm/allk))"]
   ])
 
 # Run every case under a given context factory and return the failures. The same

test/spec/host-interop-spec.janet

@@ -223,3 +223,50 @@
    "(do (def prev (__reader-features)) (__reader-features-set! [\"clj\" \"jolt\" \"default\"]) (def r (contains? (set (__reader-features)) \"clj\")) (__reader-features-set! prev) r)"]
   ["restore returns to default" "false"
    "(do (def prev (__reader-features)) (__reader-features-set! [\"clj\"]) (__reader-features-set! prev) (contains? (set (__reader-features)) \"clj\"))"])
+
+# JVM class shims migratus relies on. Exception constructors resolve as bare
+# class symbols (jolt-6xk) and carry a message; Character/Thread/Long statics;
+# java.sql.Timestamp is the millis number; SimpleDateFormat formats UTC.
+(defspec "host-interop / migratus class shims"
+  ["Exception. message"        "\"boom\""
+   "(try (throw (Exception. \"boom\")) (catch Throwable e (.getMessage e)))"]
+  ["IllegalArgumentException."  "\"bad\""
+   "(try (throw (IllegalArgumentException. \"bad\")) (catch Exception e (.getMessage e)))"]
+  ["InterruptedException."      "\"stop\""
+   "(try (throw (InterruptedException. \"stop\")) (catch Throwable e (.getMessage e)))"]
+  ["Character/isUpperCase"      "true"   "(Character/isUpperCase \\A)"]
+  ["Character/isLowerCase"      "true"   "(Character/isLowerCase \\a)"]
+  ["Character/isUpperCase neg"  "false"  "(Character/isUpperCase \\a)"]
+  ["Thread/interrupted"         "false"  "(Thread/interrupted)"]
+  ["Long/valueOf"               "42"     "(Long/valueOf \"42\")"]
+  ["Timestamp is millis"        "1000"   "(.getTime (java.util.Date. (java.sql.Timestamp. 1000)))"]
+  ["SimpleDateFormat UTC"       "\"19700101000000\""
+   "(let [f (doto (java.text.SimpleDateFormat. \"yyyyMMddHHmmss\") (.setTimeZone (java.util.TimeZone/getTimeZone \"UTC\")))] (.format f (java.util.Date. 0)))"])
+
+# java.io.File model (jolt-hjw): io/file builds a value that answers
+# (instance? File _) so migratus's File-vs-jar branch takes the filesystem path;
+# the method surface and a File-aware file-seq back it; str/slurp coerce to path.
+(defspec "host-interop / java.io.File"
+  ["instance? File"      "true"   "(do (require '[clojure.java.io :as io]) (instance? java.io.File (io/file \"/a/b\")))"]
+  ["str is the path"     "\"/a/b\"" "(do (require '[clojure.java.io :as io]) (str (io/file \"/a/b\")))"]
+  ["getName"             "\"c.txt\"" "(do (require '[clojure.java.io :as io]) (.getName (io/file \"/a/b/c.txt\")))"]
+  ["getPath joins"       "\"/a/b\"" "(do (require '[clojure.java.io :as io]) (.getPath (io/file \"/a\" \"b\")))"]
+  ["isDirectory of repo dir" "true" "(do (require '[clojure.java.io :as io]) (.isDirectory (io/file \"docs\")))"]
+  ["isFile of repo file" "true"    "(do (require '[clojure.java.io :as io]) (.isFile (io/file \"project.janet\")))"]
+  ["exists is false off-disk" "false" "(do (require '[clojure.java.io :as io]) (.exists (io/file \"/no/such/path/xyz\")))"]
+  ["file-seq yields File values" "true"
+   "(do (require '[clojure.java.io :as io]) (every? (fn [f] (instance? java.io.File f)) (file-seq (io/file \"docs\"))))"]
+  ["file-seq finds files"  "true"
+   "(do (require '[clojure.java.io :as io]) (pos? (count (filter (fn [f] (.isFile f)) (file-seq (io/file \"docs\"))))))"])
+
+# clojure.tools.logging shim (jolt-nzg): the macro surface works, debug/trace
+# are suppressed (no-op nil) by default, and the impl protocol layer is present.
+(defspec "host-interop / clojure.tools.logging"
+  ["info returns nil"   "nil"  "(do (require '[clojure.tools.logging :as log]) (log/info \"hi\" 42))"]
+  ["debug suppressed"   "nil"  "(do (require '[clojure.tools.logging :as log]) (log/debug \"x\"))"]
+  ["debug skips args"   "0"    "(do (require '[clojure.tools.logging :as log]) (let [a (atom 0)] (log/debug (reset! a 9)) @a))"]
+  ["enabled? info"      "true" "(do (require '[clojure.tools.logging :as log]) (log/enabled? :info))"]
+  ["enabled? debug"     "false" "(do (require '[clojure.tools.logging :as log]) (log/enabled? :debug))"]
+  ["spy returns value"  "3"    "(do (require '[clojure.tools.logging :as log]) (log/spy :info (+ 1 2)))"]
+  ["impl factory name"  "\"jolt/stderr\""
+   "(do (require '[clojure.tools.logging.impl :as impl]) (impl/name (impl/find-factory)))"])

test/spec/macros-spec.janet

@@ -85,3 +85,11 @@
   ["with-redefs-fn"      "42"     "(do (defn wr-i [] 1) (with-redefs-fn {(var wr-i) (fn [] 42)} (fn [] (wr-i))))"]
   ["macroexpand full"    "true"   "(let [e (macroexpand (quote (when-not false 1)))] (= (quote if) (first e)))"]
   ["macroexpand non-macro" "[1 2]" "(macroexpand (quote [1 2]))"])
+
+# defmacro accepts the arity-clause form (defmacro name ([params] body...)), a
+# leading docstring, and ^{:map} metadata on the name (jolt-whp, jolt-8w2).
+(defspec "macros / defmacro arity-clause & name metadata"
+  ["arity-clause form"    "10"  "(do (defmacro tw ([x] (list (quote *) x 2))) (tw 5))"]
+  ["docstring + arity"    "15"  "(do (defmacro th \"triple\" ([x] (list (quote *) x 3))) (th 5))"]
+  ["^{:map} name meta"    "7"   "(do (defmacro ^{:private true} pm [] 7) (pm))"]
+  ["multi-form body"      "6"   "(do (defmacro mb ([a b] (list (quote +) a b))) (mb 2 4))"])

test/spec/maps-spec.janet

@@ -177,3 +177,13 @@
   ["empty? lazy nil elem" "false"     "(empty? (cons nil nil))"]
   ["empty? sorted"   "[true false]"   "[(empty? (sorted-map)) (empty? (sorted-set 1))]"]
   ["empty? number throws" :throws     "(empty? 5)"])
+
+# (assoc nil k v) yields a real immutable map, not a raw host table, so
+# assoc-in into absent keys nests countable/seqable maps (jolt-w4s).
+(defspec "map / assoc on nil"
+  ["assoc nil is a map"        "{:a 1}" "(assoc nil :a 1)"]
+  ["count of assoc nil"        "1"      "(count (assoc nil :a 1))"]
+  ["assoc-in nested countable" "1"      "(count (:a (assoc-in {} [:a :b] 1)))"]
+  ["assoc-in deep get"         "9"      "(get-in (assoc-in {} [:a :b :c] 9) [:a :b :c])"]
+  ["seq over assoc-nil map"    ":a"     "(ffirst (seq (assoc nil :a 1)))"]
+  ["keys of assoc-nil map"     "[:a]"   "(vec (keys (assoc nil :a 1)))"])

test/spec/multimethods-spec.janet

@@ -54,3 +54,17 @@
    "(do (defmulti pm5 identity) (defmethod pm5 :a [x] 1) (defmethod pm5 :b [x] 2) (prefer-method pm5 :a :b) (contains? (get (prefers pm5) :a) :b))"]
   ["exact match needs no preference" ":exact"
    "(do (derive :t/sq :t/rect) (defmulti pm6 identity) (defmethod pm6 :t/sq [x] :exact) (defmethod pm6 :t/rect [x] :parent) (pm6 :t/sq))"])
+
+# defmulti drops a leading docstring/attr-map (jolt-es4 — it used to be taken as
+# the dispatch fn). methods/get-method take the multimethod VALUE and recover
+# the table, so a bare multifn ref works even when defmethods live elsewhere
+# (jolt-9pu).
+(defspec "multimethods / docstring & value-based table ops"
+  ["defmulti docstring"   "\"A\""
+   "(do (defmulti gd \"the dispatcher\" identity) (defmethod gd :a [_] \"A\") (gd :a))"]
+  ["defmulti doc+default" "\"d\""
+   "(do (defmulti gx \"doc\" identity) (defmethod gx :default [_] \"d\") (gx :anything))"]
+  ["methods on value"     "2"
+   "(do (defmulti gm identity) (defmethod gm 1 [_] :one) (defmethod gm 2 [_] :two) (count (methods gm)))"]
+  ["get-method on value"  "true"
+   "(do (defmulti gg identity) (defmethod gg :a [_] :x) (fn? (get-method gg :a)))"])

test/spec/regex-spec.janet

@@ -47,3 +47,18 @@
   ["p{Ps}/p{Pe}"     "\"(x)\""   `(re-matches #"^\p{Ps}x\p{Pe}$" "(x)")`]
   ["(?u) accepted"   "\"hi\""    `(re-matches #"(?u)^hi$" "hi")`]
   ["unknown class throws" :throws `(re-pattern "\p{Greek}")`])
+
+# java.util.regex.Pattern statics (jolt-47b): compile returns jolt's native
+# regex value (so .split / str-ops accept it), MULTILINE maps to (?m), quote
+# escapes metachars. Plus the regex String methods migratus uses.
+(defspec "regex / Pattern statics & String regex methods"
+  ["Pattern/compile is a regex" "true" "(regex? (Pattern/compile \"a.c\"))"]
+  ["compiled .split"     "[\"a\" \"b\" \"c\"]" "(.split (Pattern/compile \",\") \"a,b,c\")"]
+  ["str/replace w/ Pattern" "\"ab\"" "(do (require '[clojure.string :as s]) (s/replace \"a1b2\" (Pattern/compile \"[0-9]\") \"\"))"]
+  ["Pattern/MULTILINE ^"  "true"  "(boolean (re-find (Pattern/compile \"^x\" Pattern/MULTILINE) \"y\\nx\"))"]
+  ["Pattern/quote literal" "true" "(boolean (re-find (re-pattern (Pattern/quote \"a.c\")) \"za.cy\"))"]
+  ["Pattern/quote not meta" "false" "(boolean (re-find (re-pattern (Pattern/quote \"a.c\")) \"zabcy\"))"]
+  [".matches whole string" "true"  "(.matches \"abc\" \"a.c\")"]
+  [".matches partial -> false" "false" "(.matches \"abcd\" \"a.c\")"]
+  [".replaceAll regex"   "\"a-b-c\"" "(.replaceAll \"a_b_c\" \"_\" \"-\")"]
+  [".replaceFirst regex" "\"a-b_c\"" "(.replaceFirst \"a_b_c\" \"_\" \"-\")"])