Skip to content

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

Introduce module `:friends` (#67292)

Cam Saulee9ba6576247
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 26564317c22..c934bb8575d 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -10,7 +10,7 @@
;; ## `team`:
;;
;; The team that owns this module. This has to match one of the team names in `.github/team.json` EXACTLY. You can
-;; run [metabase.core.modules-test/all-modules-have-teams-test]] to make sure you did this correctly.
+;; run [[metabase.core.modules-test/all-modules-have-teams-test]] to make sure you did this correctly.
;;
;; ## `api`:
;;
@@ -39,6 +39,17 @@
;; 2. A set of module symbols. This is the list of modules that are allowed to be referenced. An empty set means no
;; other modules are allowed to be referenced; this is the default for any modules that aren't listed here.
;;
+;; ## `friends`:
+;;
+;; 'Friend' in the C++ sense; set of modules that are allowed free access into the internals of this module including
+;; namespaces that are not `:api` namespaces. This is useful when writing modules that are 'extensions' of other
+;; modules, for example `enterprise/search` might be enterprise extensions of `search`, or `search-rest` might be the
+;; REST API component for `search`.
+;;
+;; search
+;; {...
+;; :friends #{enterprise/search search-rest}}
+;;
;; ## Tips
;;
;; PRO TIP: Check out the [[dev.deps-graph]] namespace for helpful tools to see where a module is used externally, and
@@ -704,19 +715,13 @@
lib
{:team "Querying"
:api #{metabase.lib.binning
- metabase.lib.binning.util
- metabase.lib.card
- metabase.lib.computed ; temporarily so that `qp.compile` can use it as lib memoization evolves
metabase.lib.convert ; Only so [[metabase.queries.models.card]] can set dynamic vars.
metabase.lib.core
metabase.lib.equality
metabase.lib.field
- metabase.lib.field.resolution
- metabase.lib.filter
metabase.lib.filter.desugar.jvm ; only so [[metabase.legacy-mbql.jvm-util]] can use defined regexes
metabase.lib.hierarchy
metabase.lib.init
- metabase.lib.join.util
metabase.lib.metadata
metabase.lib.metadata.cached-provider
metabase.lib.metadata.column
@@ -744,7 +749,6 @@
metabase.lib.schema.metadata
metabase.lib.schema.metadata.fingerprint
metabase.lib.schema.middleware-options
- metabase.lib.schema.order-by
metabase.lib.schema.parameter
metabase.lib.schema.ref
metabase.lib.schema.settings
@@ -761,7 +765,8 @@
graph
legacy-mbql
types
- util}}
+ util}
+ :friends #{query-processor}}
lib-be
{:team "Querying"
diff --git a/.clj-kondo/src/hooks/common/modules.clj b/.clj-kondo/src/hooks/common/modules.clj
index 3d90e5ad832..ddd30d4db7f 100644
--- a/.clj-kondo/src/hooks/common/modules.clj
+++ b/.clj-kondo/src/hooks/common/modules.clj
@@ -31,7 +31,7 @@
second
symbol))))
-(defn module-api-namespaces
+(defn- module-api-namespaces
"Set of API namespace symbols for a given module. `:any` means you can use anything, there are no API namespaces for
this module (yet). If unspecified, the default is just the `<module>.core` namespace."
[config module]
@@ -51,6 +51,12 @@
(symbol (str ns-prefix ".core"))
(symbol (str ns-prefix ".init"))}))))
+(defn- module-friends
+ [config module]
+ "Set of modules that are `:friends` of `module`, i.e. allowed to use *any* namespace from the module, not just the
+ designated [[module-api-namespaces]]."
+ (set (get-in config [:metabase/modules module :friends])))
+
(defn allowed-modules
"Set of namespace symbols that `module` is allowed to use. `:any` means it's allowed to use anything."
[config module]
@@ -61,11 +67,13 @@
(or (= allowed-modules :any)
(contains? (set allowed-modules) required-module))))
-(defn allowed-module-namespace? [config ns-symb]
+(defn- allowed-module-namespace? [config current-module ns-symb]
(let [module (module ns-symb)
- module-api-namespaces (module-api-namespaces config module)]
+ module-api-namespaces (module-api-namespaces config module)
+ module-friends (module-friends config module)]
(or (empty? module-api-namespaces)
- (contains? module-api-namespaces ns-symb))))
+ (contains? module-api-namespaces ns-symb)
+ (contains? module-friends current-module))))
(defn usage-error
"Find usage errors when a `required-namespace` is required in the `current-module`. Returns a string describing the
@@ -81,7 +89,7 @@
current-module
current-module)
- (not (allowed-module-namespace? config required-namespace))
+ (not (allowed-module-namespace? config current-module required-namespace))
(format "Namespace %s is not an allowed external API namespace for the %s module. [:metabase/modules %s :api]"
required-namespace
required-module
diff --git a/.clj-kondo/test/hooks/clojure/core/ns_test.clj b/.clj-kondo/test/hooks/clojure/core/ns_test.clj
index 5cbda354092..f196ed75517 100644
--- a/.clj-kondo/test/hooks/clojure/core/ns_test.clj
+++ b/.clj-kondo/test/hooks/clojure/core/ns_test.clj
@@ -43,6 +43,17 @@
'{:metabase/modules {api {:uses #{search}}
search {:api #{metabase.search.core}}}}))))
+(deftest ^:parallel module-checker-friends-test
+ (is (= []
+ (lint-modules
+ '(ns metabase.search-rest.api
+ (:require
+ [metabase.search.config :as search.config]
+ [metabase.search.core :as search]))
+ '{:metabase/modules {search {:api #{metabase.search.core}
+ :friends #{search-rest}}
+ search-rest {:uses #{search}}}}))))
+
(deftest ^:parallel module-checker-api-namespaces-ignore-test
(is (empty? (lint-modules
'(ns metabase.api.search
diff --git a/dev/src/dev/deps_graph.clj b/dev/src/dev/deps_graph.clj
index db63f0c5177..7bf544a7805 100644
--- a/dev/src/dev/deps_graph.clj
+++ b/dev/src/dev/deps_graph.clj
@@ -313,13 +313,28 @@
[k (into (sorted-set) (map :namespace) v)]))
(group-by :depends-on-namespace (external-usages deps module-symb)))))
-(defn externally-used-namespaces
- "All namespaces from a module that are used outside that module."
+(defn module-friends
+ "`:friends` of the module from the Kondo config -- these are allowed to freely use all namespaces in the module, not
+ just `:api` ones.
+
+ (module-friends (kondo-config) 'lib)
+ ;; => #{query-processor}"
+ [kondo-config module-symb]
+ (get-in kondo-config [module-symb :friends]))
+
+(declare kondo-config)
+
+(defn externally-used-namespaces-ignoring-friends
+ "All namespaces from a module that are used outside that module, excluding usages by `:friends` of the module."
([module-symb]
- (externally-used-namespaces (dependencies) module-symb))
+ (externally-used-namespaces-ignoring-friends (dependencies) (kondo-config) module-symb))
- ([deps module-symb]
- (into (sorted-set) (map :depends-on-namespace) (external-usages deps module-symb))))
+ ([deps kondo-config module-symb]
+ (let [friends (module-friends kondo-config module-symb)]
+ (into (sorted-set)
+ (comp (remove #(contains? friends (:module %)))
+ (map :depends-on-namespace))
+ (external-usages deps module-symb)))))
(defn module-dependencies
"Build a graph of module => set of modules it directly depends on."
@@ -412,12 +427,12 @@
(defn generate-config
"Generate the Kondo config that should go in `.clj-kondo/config/modules/config.edn`."
([]
- (generate-config (dependencies)))
+ (generate-config (dependencies) (kondo-config)))
- ([deps]
+ ([deps kondo-config]
(into (sorted-map)
(map (fn [[module uses]]
- [module {:api (externally-used-namespaces deps module)
+ [module {:api (externally-used-namespaces-ignoring-friends deps kondo-config module)
:uses uses}]))
(module-dependencies deps))))
@@ -447,12 +462,13 @@
(kondo-config-diff (dependencies)))
([deps]
- (-> (ddiff/diff
- (update-vals (kondo-config) #(dissoc % :team))
- (generate-config deps))
- ddiff/minimize
- kondo-config-diff-ignore-any
- ddiff/minimize)))
+ (let [kondo-config (kondo-config)]
+ (-> (ddiff/diff
+ (update-vals kondo-config #(dissoc % :team :friends))
+ (generate-config deps kondo-config))
+ ddiff/minimize
+ kondo-config-diff-ignore-any
+ ddiff/minimize))))
(defn print-kondo-config-diff
"Print the diff between how the config would look if regenerated with [[generate-config]] versus how it looks in
diff --git a/test/metabase/core/modules_test.clj b/test/metabase/core/modules_test.clj
index 89c85b4b925..851afc36908 100644
--- a/test/metabase/core/modules_test.clj
+++ b/test/metabase/core/modules_test.clj
@@ -141,7 +141,7 @@
(testing (str "Please update .clj-kondo/config/modules/config.edn 🥰\n"
"[Pro Tip: use (dev.deps-graph/print-kondo-config-diff) to see the changes you need to make in a nicer format]\n")
(let [deps (dev.deps-graph/dependencies)
- expected (dev.deps-graph/generate-config deps)
+ expected (dev.deps-graph/generate-config deps (dev.deps-graph/kondo-config))
actual (dev.deps-graph/kondo-config)
modules (set/union (set (keys expected))
(set (keys actual)))]