From 3122917872a63878025bc5a0211d1009db70be03 Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Mon, 13 Oct 2025 17:22:04 +0200
Subject: [PATCH] :sparkles: Add more file-grained validation for tokens lib
 migration helpers

---
 common/src/app/common/types/tokens_lib.cljc   | 73 ++++++++++---------
 .../common_tests/types/tokens_lib_test.cljc   |  2 +-
 2 files changed, 39 insertions(+), 36 deletions(-)

diff --git a/common/src/app/common/types/tokens_lib.cljc b/common/src/app/common/types/tokens_lib.cljc
index 9191aa3a2f..572669fa12 100644
--- a/common/src/app/common/types/tokens_lib.cljc
+++ b/common/src/app/common/types/tokens_lib.cljc
@@ -27,6 +27,10 @@
 
 ;; === Common
 
+(defprotocol IValidation
+  (valid? [_] "check if this data structure is valid, returns true or false")
+  (check [_] "check if this data structure is valid, raises exception or self"))
+
 (defprotocol INamedItem
   "Protocol for items that have an id, a name, a description and a modified date."
   (get-id [_] "Get the id of the item.")
@@ -536,12 +540,6 @@
    [:fn d/ordered-map?]
    [:fn not-repeated-ids]])
 
-(def ^:private check-token-sets
-  (sm/check-fn schema:token-sets :hint "expected valid token sets"))
-
-(def ^:private valid-token-sets?
-  (sm/validator schema:token-sets))
-
 ;; === TokenTheme
 
 (defprotocol ITokenTheme
@@ -770,21 +768,9 @@
              [:fn d/ordered-map?]]]
    [:fn d/ordered-map?]])
 
-(def ^:private check-token-themes
-  (sm/check-fn schema:token-themes :hint "expected valid token themes"))
-
-(def ^:private valid-token-themes?
-  (sm/validator schema:token-themes))
-
 (def ^:private schema:active-themes
   [:set :string])
 
-(def ^:private check-active-themes
-  (sm/check-fn schema:active-themes :hint "expected valid active themes"))
-
-(def ^:private valid-active-token-themes?
-  (sm/validator schema:active-themes))
-
 (defn walk-sets-tree-seq
   "Walk sets tree as a flat list.
 
@@ -900,6 +886,8 @@
 ;; === Tokens Lib
 
 (declare make-tokens-lib)
+(declare ^:private check-tokens-lib-map)
+(declare ^:private valid-tokens-lib-map?)
 
 (defprotocol ITokensLib
   "A library of tokens, sets and themes."
@@ -920,8 +908,7 @@ Will return a value that matches this schema:
 `:partial` Mixed active state of nested sets")
   (get-tokens-in-active-sets [_] "set of set names that are active in the the active themes")
   (get-all-tokens [_] "all tokens in the lib")
-  (get-tokens [_ set-id] "return a map of tokens in the set, indexed by token-name")
-  (validate [_]))
+  (get-tokens [_ set-id] "return a map of tokens in the set, indexed by token-name"))
 
 (declare parse-multi-set-dtcg-json)
 (declare export-dtcg-json)
@@ -1323,10 +1310,13 @@ Will return a value that matches this schema:
             (get-set set-id)
             (get-tokens-)))
 
-  (validate [_]
-    (and (valid-token-sets? sets)
-         (valid-token-themes? themes)
-         (valid-active-token-themes? active-themes))))
+  IValidation
+  (valid? [this]
+    (valid-tokens-lib-map? (datafy this)))
+
+  (check [this]
+    (check-tokens-lib-map (datafy this))
+    this))
 
 (defmethod pp/simple-dispatch TokensLib
   [^TokensLib obj]
@@ -1355,10 +1345,23 @@ Will return a value that matches this schema:
      cljs.core/IEncodeJS
      (-clj->js [this] (clj->js (datafy this)))))
 
+(def ^:private schema:tokens-lib-map
+  "Internal data structure schema"
+  [:map {:title "TokensLib"}
+   [:sets schema:token-sets]
+   [:themes schema:token-themes]
+   [:active-themes schema:active-themes]])
+
+(def ^:private valid-tokens-lib-map?
+  (sm/lazy-validator schema:tokens-lib-map))
+
+(def ^:private check-tokens-lib-map
+  (sm/check-fn schema:tokens-lib-map :hint "invalid tokens-lib internal data structure"))
+
 (defn valid-tokens-lib?
   [o]
   (and (instance? TokensLib o)
-       (validate o)))
+       (valid? o)))
 
 (defn- ensure-hidden-theme
   "A helper that is responsible to ensure that the hidden theme always
@@ -1379,15 +1382,14 @@ Will return a value that matches this schema:
 
 (defn make-tokens-lib
   "Make a new instance of TokensLib from a map and validates the input"
-  [& {:keys [sets themes active-themes]}]
-  (let [sets          (or sets (d/ordered-map))
-        themes        (-> (or themes (d/ordered-map))
-                          (ensure-hidden-theme))
-        active-themes (or active-themes #{hidden-theme-path})]
-    (TokensLib.
-     (check-token-sets sets)
-     (check-token-themes themes)
-     (check-active-themes active-themes))))
+  [& {:as params}]
+  (-> params
+      (update :sets #(or % (d/ordered-map)))
+      (update :themes #(-> (or % (d/ordered-map))
+                           (ensure-hidden-theme)))
+      (update :active-themes #(or % #{hidden-theme-path}))
+      (check-tokens-lib-map)
+      (map->tokens-lib)))
 
 (defn ensure-tokens-lib
   [tokens-lib]
@@ -1902,7 +1904,8 @@ Will return a value that matches this schema:
     (some-> tokens-lib
             (-> (datafy)
                 (update :sets d/update-vals migrate-set-node)
-                (map->tokens-lib)))))
+                (map->tokens-lib)
+                (check)))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; SERIALIZATION (FRESIAN)
diff --git a/common/test/common_tests/types/tokens_lib_test.cljc b/common/test/common_tests/types/tokens_lib_test.cljc
index 4b86480e12..f036c821df 100644
--- a/common/test/common_tests/types/tokens_lib_test.cljc
+++ b/common/test/common_tests/types/tokens_lib_test.cljc
@@ -241,7 +241,7 @@
 
 (t/deftest make-invalid-tokens-lib
   (let [params {:sets {} :themes {}}]
-    (t/is (thrown-with-msg? #?(:cljs js/Error :clj Exception) #"expected valid token sets"
+    (t/is (thrown-with-msg? #?(:cljs js/Error :clj Exception) #"invalid tokens-lib internal data structure"
                             (ctob/make-tokens-lib params)))))
 
 (t/deftest add-token-set-to-token-lib