feat(sql/ast): Add converter for SQL WHERE to AST with comprehensive tests

- Implement `chrondb.api.sql.execution.ast-converter` to translate SQL WHERE condition maps to unified AST query clauses used by Lucene.
- Support FTS, standard operators (=, !=, <>, >, <, >=, <=), LIKE (wildcards), IS [NOT] NULL, and number parsing for range queries.
- Gracefully handle unknown types and operators, always preserving immutability and fast failure semantics.
- Add unit tests for all major conversion and edge cases to `test/chrondb/api/sql/execution/ast_converter_test.clj`.
- Document AST composition and query helper contract in `docs/ast-queries.md`.
- Cross-link property-based test location in AGENT.md for better developer guidance.

This supports full protocol-level parity and reproducible query planning across ChronDB HTTP, Redis, and SQL endpoints.

Signed-off-by: Avelino <[email protected]>

Author: avelino

AGENT.md

@@ -54,6 +54,7 @@ ChronDB is a chronological key/value database implemented in Clojure and backed
 - Include integration tests that exercise Git-backed storage
 - Add regression tests for concurrency and conflict resolution
 - Prefer property-based tests when sequence ordering matters
+- Unit coverage for query AST helpers lives in `test/chrondb/query/ast_test.clj`
 
 ### Git Architecture Integration
 

docs/ast-queries.md

@@ -219,3 +219,4 @@ The AST system replaces the legacy query format:
 ```
 
 Both are supported during migration, but new code should use AST.
+

src/chrondb/api/sql/execution/ast_converter.clj

@@ -89,6 +89,3 @@
         (if (= (count clauses) 1)
           (first clauses)
           (apply ast/and clauses))))))
-
-
-

test/chrondb/api/sql/execution/ast_converter_test.clj

@@ -0,0 +1,117 @@
+ (ns chrondb.api.sql.execution.ast-converter-test
+  (:require [clojure.test :refer [deftest is testing]]
+            [chrondb.api.sql.execution.ast-converter :as converter]
+            [chrondb.query.ast :as ast]))
+
+(deftest condition->ast-clause-fts-test
+  (is (= (ast/fts :content "time travel")
+         (converter/condition->ast-clause
+          {:type :fts-match
+           :field "content"
+           :op "MATCH"
+           :query "time travel"}))))
+
+(deftest condition->ast-clause-standard-test
+  (testing "Equality removes surrounding quotes"
+    (let [condition {:type :standard
+                     :field "name"
+                     :op "="
+                     :value "'Alice'"}
+          expected (ast/term :name "Alice")]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Not equal delegates to ast/not"
+    (let [condition {:type :standard
+                     :field "status"
+                     :op "!="
+                     :value "archived"}
+          expected (ast/not (ast/term :status "archived"))]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Alternate not equal operator <> behaves the same"
+    (let [condition {:type :standard
+                     :field "status"
+                     :op "<>"
+                     :value "archived"}
+          expected (ast/not (ast/term :status "archived"))]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Greater than parses longs"
+    (let [condition {:type :standard
+                     :field "age"
+                     :op ">"
+                     :value "30"}
+          expected (ast/range-long :age 30 nil {:include-lower? false})]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Greater than parses doubles"
+    (let [condition {:type :standard
+                     :field "price"
+                     :op ">"
+                     :value "42.5"}
+          expected (ast/range-double :price 42.5 nil {:include-lower? false})]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Greater than falls back to string range when numeric parse fails"
+    (let [condition {:type :standard
+                     :field "code"
+                     :op ">"
+                     :value "'A'"}
+          expected (ast/range :code "A" nil {:include-lower? false})]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Less-than-or-equal builds inclusive upper bound"
+    (let [condition {:type :standard
+                     :field "age"
+                     :op "<="
+                     :value "65"}
+          expected (ast/range-long :age nil 65 {:include-upper? true})]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "LIKE converts SQL wildcards to Lucene wildcards"
+    (let [condition {:type :standard
+                     :field "title"
+                     :op "LIKE"
+                     :value "report-%Q1%"}
+          expected (ast/wildcard :title "report-*Q1*")]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "IS NULL returns missing clause"
+    (let [condition {:type :standard
+                     :field "deleted_at"
+                     :op "IS NULL"}
+          expected (ast/missing :deleted_at)]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "IS NOT NULL returns exists clause"
+    (let [condition {:type :standard
+                     :field "deleted_at"
+                     :op "IS NOT NULL"}
+          expected (ast/exists :deleted_at)]
+      (is (= expected (converter/condition->ast-clause condition)))))
+
+  (testing "Unknown condition type returns nil"
+    (is (nil? (converter/condition->ast-clause
+               {:type :unsupported
+                :field "name"
+                :op "="
+                :value "Alice"})))))
+
+(deftest conditions->ast-clauses-test
+  (testing "Empty conditions produce nil"
+    (is (nil? (converter/conditions->ast-clauses []))))
+
+  (testing "Single condition returns clause without wrapping"
+    (let [condition {:type :standard :field "age" :op ">" :value "30"}
+          expected (converter/condition->ast-clause condition)]
+      (is (= expected (converter/conditions->ast-clauses [condition])))))
+
+  (testing "Multiple conditions combine with AND and drop nil clauses"
+    (let [cond-a {:type :standard :field "age" :op ">" :value "30"}
+          cond-b {:type :standard :field "status" :op "=" :value "active"}
+          cond-nil {:type :unsupported :field "ignored" :op "=" :value "nope"}
+          expected (ast/and (converter/condition->ast-clause cond-a)
+                            (converter/condition->ast-clause cond-b))]
+      (is (= expected
+             (converter/conditions->ast-clauses [cond-a cond-b cond-nil]))))))
+

test/chrondb/query/ast_test.clj

@@ -0,0 +1,226 @@
+ (ns chrondb.query.ast-test
+   (:require [clojure.test :refer [deftest is testing]]
+             [chrondb.query.ast :as ast]))
+
+ (deftest match-and-term-clauses-test
+   (testing "match-all returns the expected clause"
+     (is (= {:type :match-all}
+            (ast/match-all))))
+
+   (testing "term clauses require both field and value"
+    (is (= {:type :term :field "status" :value "active"}
+           (ast/term :status "active")))
+    (is (= {:type :term :field "score" :value "42"}
+           (ast/term :score 42)))
+     (is (nil? (ast/term nil "active")))
+     (is (nil? (ast/term :status nil))))
+
+   (testing "wildcard clauses normalize field and value"
+     (is (= {:type :wildcard :field "name" :value "foo"}
+            (ast/wildcard :name "foo")))
+     (is (nil? (ast/wildcard :name nil))))
+
+   (testing "prefix delegates to wildcard with appended asterisk"
+     (is (= (ast/wildcard :path "logs*")
+            (ast/prefix :path "logs")))
+     (is (nil? (ast/prefix :path nil))))
+
+   (testing "full-text search clauses include analyzer metadata"
+     (is (= {:type :fts :field "content" :value "history" :analyzer :fts}
+            (ast/fts :content "history")))
+     (is (nil? (ast/fts :content nil))))
+
+   (testing "exists and missing clauses reject nil fields"
+     (is (= {:type :exists :field "updated_at"}
+            (ast/exists :updated_at)))
+     (is (nil? (ast/exists nil)))
+     (is (= {:type :missing :field "deleted_at"}
+            (ast/missing :deleted_at)))
+     (is (nil? (ast/missing nil)))))
+
+ (deftest range-clauses-test
+   (testing "default range is inclusive with stringified bounds"
+     (is (= {:type :range
+             :field "timestamp"
+             :lower "10"
+             :upper "20"
+             :include-lower? true
+             :include-upper? true
+             :value-type nil}
+            (ast/range :timestamp 10 20))))
+
+   (testing "range supports open bounds and option overrides"
+     (is (= {:type :range
+             :field "created_at"
+             :lower nil
+             :upper "100"
+             :include-lower? false
+             :include-upper? false
+             :value-type :string}
+            (ast/range :created_at nil 100
+                       {:include-lower? false
+                        :include-upper? false
+                        :type :string}))))
+
+   (testing "numeric helper ranges set the value type"
+     (is (= {:type :range
+             :field "age"
+             :lower "18"
+             :upper "65"
+             :include-lower? true
+             :include-upper? false
+             :value-type :long}
+            (ast/range-long :age 18 65 {:include-upper? false})))
+     (is (= {:type :range
+             :field "score"
+             :lower "0.1"
+             :upper "0.9"
+             :include-lower? true
+             :include-upper? true
+             :value-type :double}
+            (ast/range-double :score 0.1 0.9 {})))))
+
+ (deftest boolean-node-test
+   (testing "empty boolean collapses to match-all"
+     (is (= (ast/match-all)
+            (ast/boolean {}))))
+
+   (testing "single should clause collapses to the clause itself"
+     (let [clause (ast/term :status "active")]
+       (is (= clause
+              (ast/boolean {:should [clause]})))))
+
+   (testing "must-not clauses receive an implicit match-all must"
+     (let [clause (ast/term :status "inactive")]
+       (is (= {:type :boolean
+               :must [(ast/match-all)]
+               :should []
+               :must-not [clause]
+               :filter []}
+              (ast/boolean {:must []
+                             :should []
+                             :must-not [clause]
+                             :filter []})))))
+
+   (testing "general boolean vectorizes inputs and removes nils"
+     (let [must-a (ast/term :status "active")
+           should-a (ast/term :role "admin")
+           result (ast/boolean {:must [must-a nil]
+                                :should [nil should-a]
+                                :must-not [nil]
+                                :filter nil})]
+       (is (= {:type :boolean
+               :must [must-a]
+               :should [should-a]
+               :must-not []
+               :filter []}
+              result)))))
+
+ (deftest logical-combinators-test
+   (testing "and collapses edge cases"
+     (let [clause (ast/term :status "active")]
+       (is (= (ast/match-all) (ast/and)))
+       (is (= clause (ast/and clause)))
+       (is (= {:type :boolean
+               :must [clause (ast/match-all)]
+               :should []
+               :must-not []
+               :filter []}
+              (ast/and clause nil (ast/match-all))))))
+
+   (testing "or collapses edge cases"
+     (let [clause (ast/term :role "admin")]
+       (is (= (ast/match-all) (ast/or)))
+       (is (= clause (ast/or clause)))
+       (is (= {:type :boolean
+               :must []
+               :should [clause (ast/match-all)]
+               :must-not []
+               :filter []}
+              (ast/or clause nil (ast/match-all))))))
+
+   (testing "not wraps the clause with must-not and implicit must"
+     (let [clause (ast/term :status "inactive")]
+       (is (= {:type :boolean
+               :must [(ast/match-all)]
+               :should []
+               :must-not [clause]
+               :filter []}
+              (ast/not clause))))
+
+   (testing "not defaults to match-all when clause is nil"
+     (is (= {:type :boolean
+             :must [(ast/match-all)]
+             :should []
+             :must-not [(ast/match-all)]
+             :filter []}
+            (ast/not nil)))))
+
+ (deftest sort-and-query-metadata-test
+   (testing "sort descriptors infer defaults"
+     (is (= {:field "timestamp" :direction :asc :type :string}
+            (ast/sort-by :timestamp)))
+     (is (= {:field "timestamp" :direction :desc :type :string}
+            (ast/sort-by :timestamp :desc)))
+     (is (= {:field "timestamp" :direction :desc :type :long}
+            (ast/sort-by :timestamp :desc :long))))
+
+   (testing "query wraps clauses and optional metadata"
+     (let [clause (ast/term :status "active")
+           sort-desc (ast/sort-by :timestamp :desc :long)
+           query (ast/query [clause]
+                            {:sort [sort-desc]
+                             :limit 25
+                             :offset 10
+                             :branch "feature"
+                             :hints {:refresh true}
+                             :after {:doc 42}})]
+       (is (= {:clauses [clause]
+               :sort [sort-desc]
+               :limit 25
+               :offset 10
+               :branch "feature"
+               :hints {:refresh true}
+               :after {:doc 42}}
+              query))))
+
+   (testing "query vectorizes sort descriptors when provided"
+     (let [clause (ast/match-all)
+           sort-desc (ast/sort-by :timestamp)
+           query (ast/query [clause] {:sort [sort-desc]})]
+       (is (= [sort-desc] (:sort query))))))
+
+(deftest query-transformers-test
+  (let [base-query (ast/query [(ast/match-all)])
+        sort-desc (ast/sort-by :timestamp :desc :long)]
+    (testing "with-branch replaces the branch"
+      (is (= "main"
+             (:branch (ast/with-branch base-query "main")))))
+
+    (testing "with-hints merges successive hint maps"
+      (is (= {:refresh true :track-total-hits true}
+             (:hints (-> base-query
+                         (ast/with-hints {:refresh true})
+                         (ast/with-hints {:track-total-hits true})))))
+      (is (nil? (:hints (ast/with-hints base-query nil)))))
+
+    (testing "with-search-after attaches the cursor"
+      (is (= {:doc 9 :score 0.42}
+             (:after (ast/with-search-after base-query {:doc 9 :score 0.42})))))
+
+    (testing "with-pagination conditionally sets pagination keys"
+      (is (= {:limit 100 :offset 20 :after {:doc 1}}
+             (select-keys (ast/with-pagination base-query
+                                              {:limit 100
+                                               :offset 20
+                                               :after {:doc 1}})
+                          [:limit :offset :after])))
+      (is (= base-query (ast/with-pagination base-query {}))))
+
+    (testing "with-sort vectorizes descriptors"
+      (is (= [sort-desc]
+             (:sort (ast/with-sort base-query sort-desc))))
+      (is (= [sort-desc]
+             (:sort (ast/with-sort base-query [sort-desc]))))))
+))
+