Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add custom Kondo linter to enforce idiomatic var names for `def` and friends (#68969)

Cam Sauld39acdcb967d
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn
index cd5abf82220..d8d3719f43b 100644
--- a/.clj-kondo/config.edn
+++ b/.clj-kondo/config.edn
@@ -50,13 +50,15 @@
;; disabled linters
;;
- :redundant-ignore {:level :off} ; lots of false positives, see https://github.com/clj-kondo/clj-kondo/issues/2414
+ :redundant-ignore {:level :off} ; lots of false positives, see https://github.com/clj-kondo/clj-kondo/issues/2414
:unexpected-recur {:level :off} ; TODO (cam): I think we just need to tell it how to handle MBQL match and we can enable this?
;;
;; globally-enabled custom linters
;;
:metabase/check-defmulti-arglists {:level :warning}
+ :metabase/check-def-check-not-uppercase-name {:level :warning}
+ :metabase/check-def-no-underscores {:level :warning}
:metabase/check-me-humanize {:level :warning}
:metabase/defsetting-must-specify-export {:level :warning}
:metabase/defsetting-namespace {:level :warning}
@@ -67,7 +69,6 @@
:metabase/namespace-name {:level :warning}
:metabase/no-jsqlparser-imports {:level :warning}
:metabase/require-shape-checker {:level :warning}
- :metabase/test-helpers-use-non-thread-safe-functions {:level :warning} ; more config in `.clj-kondo/config/test-helpers/config.edn`
:metabase/tests-must-live-in-known-modules {:level :warning}
:metabase/validate-defendpoint-route-uses-kebab-case {:level :warning}
:metabase/validate-defendpoint-query-params-use-kebab-case {:level :warning}
@@ -519,7 +520,16 @@
{cljs.test/deftest hooks.clojure.test/deftest
cljs.test/is hooks.clojure.test/is
cljs.test/use-fixtures hooks.clojure.test/use-fixtures
+ clojure.core/def hooks.clojure.core.def/lint-def
+ clojure.core/definterface hooks.clojure.core.def/lint-def
+ clojure.core/defmacro hooks.clojure.core.defmacro/lint-defmacro
clojure.core/defmulti hooks.clojure.core.defmulti/lint-defmulti
+ clojure.core/defn hooks.clojure.core.defn/lint-defn
+ clojure.core/defn- hooks.clojure.core.defn/lint-defn
+ clojure.core/defonce hooks.clojure.core.def/lint-def
+ clojure.core/defprotocol hooks.clojure.core.def/lint-def
+ clojure.core/defrecord hooks.clojure.core.def/lint-def
+ clojure.core/deftype hooks.clojure.core.def/lint-def
clojure.core/ns hooks.clojure.core.ns/lint-ns
clojure.core/require hooks.clojure.core.require/lint-require
clojure.core/requiring-resolve hooks.clojure.core.require/lint-requiring-resolve
@@ -769,22 +779,17 @@
:config-in-ns
{test-namespaces
{:linters
- {:inline-def {:level :off}
- :missing-docstring {:level :off}
- :private-call {:level :off}
- :metabase/defsetting-must-specify-export {:level :off}
- :metabase/defsetting-namespace {:level :off}
+ {:inline-def {:level :off}
+ :missing-docstring {:level :off}
+ :private-call {:level :off}
+ :metabase/defsetting-must-specify-export {:level :off}
+ :metabase/defsetting-namespace {:level :off}
+ :metabase/test-helpers-use-non-thread-safe-functions {:level :warning} ; more config in `.clj-kondo/config/test-helpers/config.edn
:discouraged-var
{metabase.driver/database-supports? {:level :off}
metabase.lib.convert/->legacy-MBQL {:level :off}
- metabase.lib.core/->legacy-MBQL {:level :off}}}
-
- :hooks
- {:analyze-call
- {clojure.core/defmacro hooks.clojure.core.defn/non-thread-safe-form-should-end-with-exclamation
- clojure.core/defn hooks.clojure.core.defn/non-thread-safe-form-should-end-with-exclamation
- clojure.core/defn- hooks.clojure.core.defn/non-thread-safe-form-should-end-with-exclamation}}}
+ metabase.lib.core/->legacy-MBQL {:level :off}}}}
source-namespaces
{:linters
diff --git a/.clj-kondo/src/hooks/clojure/core.clj b/.clj-kondo/src/hooks/clojure/core.clj
new file mode 100644
index 00000000000..05839ee5a41
--- /dev/null
+++ b/.clj-kondo/src/hooks/clojure/core.clj
@@ -0,0 +1,38 @@
+(ns hooks.clojure.core
+ (:require
+ [clj-kondo.hooks-api :as hooks]
+ [clojure.string :as str]))
+
+(defn- all-uppercase? [symb]
+ (let [s (str symb)]
+ (= s #_{:clj-kondo/ignore [:discouraged-var]} (str/upper-case s))))
+
+(defn- has-underscores? [symb]
+ (str/includes? (str symb) "_"))
+
+(defn- check-symbol-is-kebab-case [symbol-node]
+ (let [symb (hooks/sexpr symbol-node)]
+ (when (or (all-uppercase? symb)
+ (has-underscores? symb))
+ (hooks/reg-finding! (assoc (meta symbol-node)
+ :message "Use kebab-case for function and variable names; don't use special notation for constants."
+ :type :metabase/check-def-kebab-case)))))
+
+(defn lint-def* [{:keys [node]}]
+ (let [[_def & args] (:children node)
+ name-symbol (some (fn [arg]
+ (when (and (hooks/token-node? arg)
+ (symbol? (hooks/sexpr arg)))
+ arg))
+ args)]
+ (check-symbol-is-kebab-case name-symbol)))
+
+(defn lint-def [x]
+ (lint-def* x)
+ x)
+
+(comment
+ (defn x []
+ (let [node (-> "(def ^:private TYPE->MODEL {\"document\" :model/Document})"
+ hooks/parse-string)]
+ (lint-def {:node node}))))
diff --git a/.clj-kondo/src/hooks/clojure/core/def.clj b/.clj-kondo/src/hooks/clojure/core/def.clj
new file mode 100644
index 00000000000..2557f02eda6
--- /dev/null
+++ b/.clj-kondo/src/hooks/clojure/core/def.clj
@@ -0,0 +1,52 @@
+(ns hooks.clojure.core.def
+ (:require
+ [clj-kondo.hooks-api :as hooks]
+ [clojure.string :as str]))
+
+(defn- uppercase-name?
+ "Whether the symbol is clearly an uppercase name like `TYPE-CONSTANTS` or `SOME_CONSTANT` or `TYPE->MODEL`."
+ [s]
+ (and (re-find #"[A-Z0-9]+(?:[-_]>?[A-Z0-9]+)+" s)
+ ;; ignore stuff like `->SCREAMING_SNAKE_CASE`... this is ok
+ (not (str/includes? s "SCREAMING_SNAKE_CASE"))))
+
+(defn- has-underscores? [s]
+ (and (str/includes? s "_")
+ ;; ignore stuff like `->snake_case` and `->SCREAMING_SNAKE_CASE`
+ (not (str/includes? s "snake_case"))
+ (not (str/includes? s "SCREAMING_SNAKE_CASE"))))
+
+(defn- check-symbol-is-kebab-case [symbol-node]
+ (let [symb (hooks/sexpr symbol-node)
+ s (str symb)]
+ (cond
+ (uppercase-name? s)
+ (hooks/reg-finding!
+ (assoc (meta symbol-node)
+ :message "Use lower-case names for functions and variables; don't use special notation for constants. [:metabase/check-def-check-not-all-uppercase]"
+ :type :metabase/check-def-check-not-uppercase-name))
+
+ (has-underscores? s)
+ (hooks/reg-finding!
+ (assoc (meta symbol-node)
+ :message "Use kebab-case names for functions and variables. [:metabase/check-def-no-underscores]"
+ :type :metabase/check-def-no-underscores)))))
+
+(defn lint-def* [{:keys [node]}]
+ (let [[_def & args] (:children node)
+ name-symbol (some (fn [arg]
+ (when (and (hooks/token-node? arg)
+ (symbol? (hooks/sexpr arg)))
+ arg))
+ args)]
+ (check-symbol-is-kebab-case name-symbol)))
+
+(defn lint-def [x]
+ (lint-def* x)
+ x)
+
+(comment
+ (defn x []
+ (let [node (-> "(def ^:private TYPE->MODEL {\"document\" :model/Document})"
+ hooks/parse-string)]
+ (lint-def {:node node}))))
diff --git a/.clj-kondo/src/hooks/clojure/core/defmacro.clj b/.clj-kondo/src/hooks/clojure/core/defmacro.clj
new file mode 100644
index 00000000000..3cf8624ec16
--- /dev/null
+++ b/.clj-kondo/src/hooks/clojure/core/defmacro.clj
@@ -0,0 +1,7 @@
+(ns hooks.clojure.core.defmacro
+ (:require
+ [hooks.clojure.core.def]))
+
+(defn lint-defmacro [x]
+ (hooks.clojure.core.def/lint-def* x)
+ x)
diff --git a/.clj-kondo/src/hooks/clojure/core/defmulti.clj b/.clj-kondo/src/hooks/clojure/core/defmulti.clj
index dcea6eed860..0daef5dc76b 100644
--- a/.clj-kondo/src/hooks/clojure/core/defmulti.clj
+++ b/.clj-kondo/src/hooks/clojure/core/defmulti.clj
@@ -2,6 +2,7 @@
(:require
[clj-kondo.hooks-api :as hooks]
[clojure.string :as str]
+ [hooks.clojure.core.def]
[hooks.common]))
(defn- check-arglists [report-node arglists]
@@ -49,4 +50,5 @@
(defn lint-defmulti [x]
(defmulti-check-for-arglists-metadata (:node x))
+ (hooks.clojure.core.def/lint-def* x)
x)
diff --git a/.clj-kondo/src/hooks/clojure/core/defn.clj b/.clj-kondo/src/hooks/clojure/core/defn.clj
index fdced383937..dbe9ec28643 100644
--- a/.clj-kondo/src/hooks/clojure/core/defn.clj
+++ b/.clj-kondo/src/hooks/clojure/core/defn.clj
@@ -2,6 +2,7 @@
(:require
[clj-kondo.hooks-api :as hooks]
[clojure.string :as str]
+ [hooks.clojure.core.def]
[hooks.common]))
(defn- end-with-exclamation?
@@ -50,6 +51,11 @@
(non-thread-safe-form-should-end-with-exclamation* node config))
{:node node})
+(defn lint-defn [x]
+ (non-thread-safe-form-should-end-with-exclamation x)
+ (hooks.clojure.core.def/lint-def* x)
+ x)
+
(comment
(require '[clj-kondo.core :as clj-kondo])
(def form (str '(defmacro a
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/util.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/util.clj
index 8774ea73396..d81cba0d16f 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/util.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/util.clj
@@ -26,7 +26,7 @@
;;; AI SDK support
-(def TYPE-PREFIX
+(def type-prefix
"AI SDK type to prefix, same names as in FE or ai-service"
;; NOTE: if we ever get prefix longer than 2 chars, you need to fix parsing to be more generic
{:TEXT "0:"
@@ -38,13 +38,13 @@
:TOOL_CALL "9:"
:TOOL_RESULT "a:"})
-(def PREFIX-TYPE "AI SDK prefix to type" (set/map-invert TYPE-PREFIX))
+(def prefix-type "AI SDK prefix to type" (set/map-invert type-prefix))
(defn aisdk->messages
"Convert AI SDK line format into an array of parsed messages."
[role lines]
(into [] (comp
- (map (fn [line] [(get PREFIX-TYPE (subs line 0 2)) (json/decode+kw (subs line 2))]))
+ (map (fn [line] [(get prefix-type (subs line 0 2)) (json/decode+kw (subs line 2))]))
(partition-by first)
(mapcat (fn [block]
(let [type (ffirst block)]
diff --git a/src/metabase/comments/api.clj b/src/metabase/comments/api.clj
index fcc7ce4e404..abeaf925796 100644
--- a/src/metabase/comments/api.clj
+++ b/src/metabase/comments/api.clj
@@ -20,7 +20,7 @@
[toucan2.core :as t2]))
;;; TODO (Cam 10/28/25) -- don't capitalize constants https://guide.clojure.style/#naming-constants
-(def ^:private TYPE->MODEL
+(def ^:private type->model
{"document" :model/Document})
(defn- entity-archived?
@@ -107,7 +107,7 @@
(if (analytics/embedding-context? (get-in req [:headers "x-metabase-client"]))
{:disabled true
:comments []}
- (let [_entity (api/read-check (TYPE->MODEL target_type) target_id)
+ (let [_entity (api/read-check (type->model target_type) target_id)
comments (-> (t2/select :model/Comment
{:where [:and
[:= :target_type target_type]
@@ -121,7 +121,7 @@
[{:keys [target_type target_id parent_comment_id] :as comment}
& [{:keys [entity parent]
;; if you don't pass them we'll try to fetch them
- :or {entity (t2/select-one (TYPE->MODEL target_type) :id target_id)
+ :or {entity (t2/select-one (type->model target_type) :id target_id)
parent (when parent_comment_id
(t2/select-one :model/Comment :id parent_comment_id))}}]]
(let [clause (if parent_comment_id
@@ -167,7 +167,7 @@
[_route-params
_query-params
{:keys [target_type target_id child_target_id parent_comment_id content html]} :- CreateComment]
- (let [entity (-> (api/read-check (TYPE->MODEL target_type) target_id)
+ (let [entity (-> (api/read-check (type->model target_type) target_id)
(u/prog1 (api/check-400 (not (entity-archived? <>))
"Cannot comment on archived entities")))
;; If this is a reply, validate the parent comment exists and belongs to same entity
@@ -205,7 +205,7 @@
_query-params
{:keys [content html is_resolved]} :- UpdateComment]
(let [comment (api/check-404 (t2/select-one :model/Comment :id comment-id))
- entity (-> (api/read-check (TYPE->MODEL (:target_type comment)) (:target_id comment))
+ entity (-> (api/read-check (type->model (:target_type comment)) (:target_id comment))
(u/prog1 (api/check-400 (not (entity-archived? <>))
"Cannot edit comments on archived entities")))]
@@ -243,7 +243,7 @@
_query-params]
(let [comment (api/check-404 (t2/select-one :model/Comment :id comment-id))]
- (-> (api/read-check (TYPE->MODEL (:target_type comment)) (:target_id comment))
+ (-> (api/read-check (type->model (:target_type comment)) (:target_id comment))
(u/prog1 (api/check-400 (not (entity-archived? <>))
"Cannot delete comments on archived entities")))
@@ -275,7 +275,7 @@
(api/check-400 (not (:deleted_at comment))
"Cannot react to deleted comments")
- (-> (api/read-check (TYPE->MODEL (:target_type comment)) (:target_id comment))
+ (-> (api/read-check (type->model (:target_type comment)) (:target_id comment))
(u/prog1 (api/check-400 (not (entity-archived? <>))
"Cannot react to comments on archived entities")))
diff --git a/src/metabase/dashboards/autoplace.clj b/src/metabase/dashboards/autoplace.clj
index 2d1eeefd539..cd32d0f57ec 100644
--- a/src/metabase/dashboards/autoplace.clj
+++ b/src/metabase/dashboards/autoplace.clj
@@ -7,7 +7,7 @@
(def ^:constant default-grid-width
"The default grid width."
- dashboard.constants/GRID_WIDTH)
+ dashboard.constants/grid-width)
(defn- intersects? [a b]
(not (or
diff --git a/src/metabase/dashboards/constants.cljc b/src/metabase/dashboards/constants.cljc
index 9929433ae39..aa407101f87 100644
--- a/src/metabase/dashboards/constants.cljc
+++ b/src/metabase/dashboards/constants.cljc
@@ -1,8 +1,6 @@
(ns metabase.dashboards.constants)
-;;; TODO -- doesn't seem to actually be used outside of this namespace, seems to be redefined in
-;;; `frontend/src/metabase/lib/dashboard_grid.js`
-(def ^:export GRID_WIDTH
+(def grid-width
"Default width of a dashboard"
24)
@@ -30,7 +28,7 @@
:map {:min {:width 4 :height 3} :default {:width 12 :height 6}}
:object {:min {:width 4 :height 3} :default {:width 12 :height 9}}
:row {:min {:width 4 :height 3} :default {:width 12 :height 6}}
- :heading {:min {:width 1 :height 1} :default {:width GRID_WIDTH :height 1}}
+ :heading {:min {:width 1 :height 1} :default {:width grid-width :height 1}}
:text {:min {:width 1 :height 1} :default {:width 12 :height 3}}})
#?(:cljs (def ^:export CARD_SIZE_DEFAULTS_JSON
diff --git a/src/metabase/lib/binning.cljc b/src/metabase/lib/binning.cljc
index 34112253b0c..99ae55053e4 100644
--- a/src/metabase/lib/binning.cljc
+++ b/src/metabase/lib/binning.cljc
@@ -217,9 +217,9 @@
:min-value value
:max-value (+ value bin-width)})))))
-(defn- binning_info->binning-options
- [binning_info]
- (-> binning_info
+(defn- binning-info->binning-options
+ [binning-info]
+ (-> binning-info
u/normalize-map
(set/rename-keys {:binning-strategy :strategy})))
@@ -245,6 +245,6 @@
[column]
(if (:binning_info column)
(update column :display_name #(ensure-ends-with-binning %1
- (binning_info->binning-options (:binning_info column))
+ (binning-info->binning-options (:binning_info column))
(:semantic_type column)))
column))
diff --git a/src/metabase/notification/payload/execute.clj b/src/metabase/notification/payload/execute.clj
index 58e47f6d9c6..643947ff80a 100644
--- a/src/metabase/notification/payload/execute.clj
+++ b/src/metabase/notification/payload/execute.clj
@@ -124,7 +124,7 @@
[dashcard parameters]
(let [text (-> dashcard :visualization_settings :text)
parameter-mappings (:parameter_mappings dashcard)
- tag-names (shared.params/tag_names text)
+ tag-names (shared.params/tag-names text)
param-id->param (into {} (map (juxt :id identity) parameters))
tag-name->param-id (into {} (map (juxt (comp second :target) :parameter_id) parameter-mappings))
tag->param (reduce (fn [m tag-name]
diff --git a/src/metabase/parameters/shared.cljc b/src/metabase/parameters/shared.cljc
index df6ecd72281..2d435e00a9d 100644
--- a/src/metabase/parameters/shared.cljc
+++ b/src/metabase/parameters/shared.cljc
@@ -300,7 +300,7 @@
str/join)]
(str/replace s non-optional-block-regex second)))
-(defn ^:export tag_names
+(defn ^:export tag-names
"Given the content of a text dashboard card, return a set of the unique names of template tags in the text."
[text]
(let [tag-names (->> (re-seq template-tag-regex (or text ""))
diff --git a/src/metabase/types/core.cljc b/src/metabase/types/core.cljc
index 84793f11f98..dc542cc87e4 100644
--- a/src/metabase/types/core.cljc
+++ b/src/metabase/types/core.cljc
@@ -528,7 +528,7 @@
(select-keys (coercion-hierarchies/non-descending-strategies) [base-type]))
not-empty)))
-(defn ^:export is_coerceable
+(defn ^:export is-coerceable
"Returns a boolean of whether a field base-type has any coercion strategies available."
[base-type]
(boolean (not-empty (coercion-possibilities (keyword base-type)))))
@@ -538,7 +538,7 @@
[coercion]
(coercion-hierarchies/effective-type-for-strategy coercion))
-(defn ^:export coercions_for_type
+(defn ^:export coercions-for-type
"Coercions available for a type. In cljs will return a js array of strings like [\"Coercion/ISO8601->Time\" ...]. In
clojure will return a sequence of keywords."
[base-type]
diff --git a/test/metabase/parameters/shared_test.cljc b/test/metabase/parameters/shared_test.cljc
index 0ef1a8d24d2..d73195beaf1 100644
--- a/test/metabase/parameters/shared_test.cljc
+++ b/test/metabase/parameters/shared_test.cljc
@@ -7,7 +7,7 @@
(defn- tag-names
[text]
- (let [result (params/tag_names text)]
+ (let [result (params/tag-names text)]
#?(:clj result
:cljs (set (js->clj result)))))