Move var metadata to public APIs only

Rewrite-clj v1 exposes its public API through code generation using
an import-vars like technique, but statically.

Internal functions that were promoted to the public API were
specifying :deprecated metadata. The meant that the deprecated
public API would delegate to an internal deprecated fn.

The ClojureScript compiler, by default, warns on calls to deprecated
functions. Users of rewrite-clj were seeing warnings from the cljs
compiler for our internal deprecated calls. This is admittedly kinda
sloppy.

This was not an issue for rewrite-cljs, because it used no form of
import-vars at all. It is not an issue with using rewrite-clj (v0
also used import-vars - the potemkim load time variant) under
Clojure because it does not issue any warning for deprecated calls.

To solve this issue, we now only specify :deprecated metadata on our
public API by specifying fn metadata not at the source, but in our
import definitions.

For consistency I've also moved :added metadata that existed on
other promoted fns to our import definitions.

Fixes #153

Author: lread

CHANGELOG.adoc

@@ -17,6 +17,7 @@ For a list of breaking changes see link:#v1-breaking[breaking changes].
 === Unreleased
 
 * rewrite-clj now exports clj-kondo config for its public API https://github.com/clj-commons/rewrite-clj/issues/146[#146]
+* ClojureScript compiler should no longer emit invalid deprecated warnings https://github.com/clj-commons/rewrite-clj/issues/153[#153]
 * Internal rewrite-clj developer facing:
   * Switched from babashka scripts to babashka tasks, developer guide updated accordingly
 

doc/02-developer-guide.adoc

@@ -130,6 +130,18 @@ Is expressed in our templates as:
            [my.ns2 my-var4 my-var5]]}}
 ----
 
+Any `:added` and `:deprecated` metadata should be defined in the template and not on the reference var.
+This keeps the metadata on the public API vars only and avoids having the ClojureScript compiler warn about deprecated calls on internal sources within rewrite-clj:
+
+//:test-doc-blocks/skip
+[source,clojure]
+----
+#_{:import-vars/import
+   {:from [[my.ns1
+            ^{:deprecated "1.2.3"} obsolete-fn
+            ^{:added "1.2.4"} new-fn]]}}
+----
+
 We also carry over rewrite-cljc support for `:import-vars/import-with-mods`, via an optional `:opts`.
 See `template/rewrite_clj/zip.cljc` for example usage.
 

doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc

@@ -626,7 +626,9 @@ We'll start `./src` using, otherwise using same template filename.
 Extension will match template (clj vs cljc for us).
 
 Ok, so what code should we be generating?
-We want to definitely bring over the docstring (sometimes altered) and some metadata (`:added` `:deprecated`).
+We want to definitely bring over the docstring (sometimes altered).
+We'll have the import definition specify `:added` and `:deprecated` metadata.
+(Original version had this metadata specified on internal source var, cljs compiler warned about calls to internal deprecated fns from public API, which was not nice for folks using rewrite-clj under cljs).
 For the var itself we have choices.
 
 . We could simply point to the source var.

script/lread/apply_import_vars.clj

@@ -79,7 +79,8 @@
 (defn- syms-to-import [import-vecs]
   (for [[ns-sym & ns-vars] import-vecs
         ns-var ns-vars]
-    (symbol (str ns-sym) (str ns-var))))
+    (with-meta (symbol (str ns-sym) (str ns-var))
+               (meta ns-var))))
 
 (defn- imported-var-name [var-metadata opts]
   (if-let [sym-pattern (:sym-to-pattern opts)]
@@ -123,7 +124,7 @@
 (defn- assert-sym-meta [ctx var-meta]
   (doseq [al (:arglists var-meta)]
     (when (not (every? symbol? al))
-      (throw (ex-info (format "appply-import-vars: args expected to be symbols only (no destructuring), found: %s\nfor var: %s\nin ns: %s\n%s" 
+      (throw (ex-info (format "appply-import-vars: args expected to be symbols only (no destructuring), found: %s\nfor var: %s\nin ns: %s\n%s"
                               al (:name var-meta) (:ns var-meta) ctx) {})))))
 
 (defn- delegator-nodes [var-meta]
@@ -153,18 +154,18 @@
                          (zraw/insert-left (nseq/list-node
                                             (concat (list (if (:macro vm) 'defmacro 'defn)
                                                           (nws/spaces 1)
-                                                          (let [target-meta (select-keys vm [:deprecated :added])
+                                                          (let [target-meta (meta import-sym)
                                                                 name (imported-var-name vm opts)]
                                                             (if (seq target-meta)
                                                               (nmeta/meta-node target-meta name)
                                                               name))
                                                           (nws/newlines 1)
                                                           (nws/spaces 2)
-                                                          ;; mimic what parser does 
+                                                          ;; mimic what parser does
                                                           (nstring/string-node (some->> (imported-docstring vm opts)
                                                                                         string/split-lines
                                                                                         ;; TODO: this escaping seems too awkward
-                                                                                        (map #(-> % 
+                                                                                        (map #(-> %
                                                                                                   (string/replace "\\" "\\\\")
                                                                                                   (string/replace "\"" "\\\"")))
                                                                                         (into []))))
@@ -213,8 +214,8 @@
         stale-cnt (->> (process-templates)
                        (reduce (fn [stale-cnt {:keys [template-filename target-filename changed?]}]
                                  (println "Template:" template-filename)
-                                 (println (if changed? "X" " ") "Target:" target-filename (if changed? 
-                                                                                            (-> "STALE" ansi/bold-red-bg ansi/black) 
+                                 (println (if changed? "X" " ") "Target:" target-filename (if changed?
+                                                                                            (-> "STALE" ansi/bold-red-bg ansi/black)
                                                                                             "(no changes)"))
                                  (if changed? (inc stale-cnt) stale-cnt))
                                0))]
@@ -226,10 +227,10 @@
         update-cnt (->> templates
                         (reduce (fn [update-cnt {:keys [template-filename target-filename changed? target-clj]}]
                                   (println "Template:" template-filename)
-                                  (println "  Target:" target-filename (if changed? 
+                                  (println "  Target:" target-filename (if changed?
                                                                          (-> "UPDATE"
                                                                              ansi/bold-green-bg
-                                                                             ansi/black) 
+                                                                             ansi/black)
                                                                          "(no changes detected)"))
                                   (if changed?
                                     (do

src/rewrite_clj/node.cljc

@@ -3,12 +3,12 @@
   "Create, update, convert and integorate nodes.
 
   All nodes represent Clojure/ClojureScript/EDN.
-   
+
   Because this API contains many functions, we offer the following categorized listing:
-   
+
   **Node creation**
   [[comma-node]]
-  [[comment-node]] 
+  [[comment-node]]
   [[deref-node]]
   [[eval-node]]
   [[fn-node]]
@@ -38,7 +38,7 @@
   **Whitespace creation convenience**
   [[spaces]]
   [[newlines]]
-  [[comma-separated]]  
+  [[comma-separated]]
   [[line-separated]]
   [[whitespace-nodes]]
 
@@ -52,7 +52,7 @@
   [[child-sexprs]]
 
   **Convert node to string**
-  [[string]]   
+  [[string]]
 
   **Node interogation**
   [[tag]]
@@ -63,13 +63,13 @@
   [[printable-only?]]
 
   **Update node**
-  [[replace-children]]  
-  
+  [[replace-children]]
+
   **Namespaced map element support**
   [[map-context-apply]]
   [[map-context-clear]]
 
-  **Test type** 
+  **Test type**
   [[node?]]
   [[comment?]]
   [[whitespace-or-comment?]]
@@ -158,7 +158,7 @@
 
   Optional `opts` can specify:
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
-   
+
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
   ([node] (rewrite-clj.node.protocols/sexpr node))
   ([node opts] (rewrite-clj.node.protocols/sexpr node opts)))
@@ -174,7 +174,7 @@
 
   Optional `opts` can specify:
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
-   
+
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
   ([nodes] (rewrite-clj.node.protocols/sexprs nodes))
   ([nodes opts] (rewrite-clj.node.protocols/sexprs nodes opts)))

src/rewrite_clj/node/protocols.cljc

@@ -41,7 +41,7 @@
 
   Optional `opts` can specify:
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
-   
+
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
   ([node] (sexpr node {}))
   ([node opts] (sexpr* node opts)))
@@ -51,7 +51,7 @@
 
   Optional `opts` can specify:
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
-   
+
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
   ([nodes]
    (sexprs nodes {}))
@@ -222,7 +222,7 @@
   [form]
   (apply dissoc (meta form) [:line :column :end-line :end-column]))
 
-(defn ^{:deprecated "0.4.0"} value
+(defn value
   "DEPRECATED: Get first child as a pair of tag/sexpr (if inner node),
    or just the node's own sexpr. (use explicit analysis of `children`
    `child-sexprs` instead) "
@@ -232,4 +232,4 @@
             (first)
             ((juxt tag sexpr)))
     (sexpr node)))
- 
+

src/rewrite_clj/zip.cljc

@@ -134,7 +134,7 @@
   [[postwalk]]
   [[subedit->]]
   [[subedit->>]]
- 
+
   **Sequence operations**
   [[map]]
   [[map-keys]]
@@ -737,7 +737,7 @@
 
    Pre-order traversal visits root before children.
    For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is:
-  
+
    1. `(1 (2 3 (4 5) 6 (7 8)) 9)`
    2. `1`
    3. `(2 3 (4 5) 6 (7 8))`
@@ -780,16 +780,16 @@
 
    Pre-order traversal visits children before root.
    For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is:
-  
+
    1. `1`
    2. `2`
-   3. `3` 
+   3. `3`
    4. `4`
    5. `5`
    6. `(4 5)`
    7. `6`
    8. `7`
-   9. `8` 
+   9. `8`
    10. `(7 8)`
    11. `(2 3 (4 5) 6 (7 8))`
    12. `9`
@@ -904,7 +904,7 @@
   ([zloc n] (rewrite-clj.zip.whitespace/append-newline zloc n))
   ([zloc] (rewrite-clj.zip.whitespace/append-newline zloc)))
 ;; TODO: clj-kondo barfs on an empty reader cond
-#?(:clj 
+#?(:clj
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
 (defn of-file

src/rewrite_clj/zip/base.cljc

@@ -69,7 +69,7 @@
   ([zloc]
    (some-> zloc zraw/node (node/sexpr (get-opts zloc)))))
 
-(defn ^{:added "0.4.4"} child-sexprs
+(defn child-sexprs
   "Return s-expression (the Clojure forms) of children of current node in `zloc`.
 
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
@@ -81,7 +81,7 @@
   [zloc]
   (or (some-> zloc zraw/node node/length) 0))
 
-(defn ^{:deprecated "0.4.0"} value
+(defn value
   "DEPRECATED. Return a tag/s-expression pair for inner nodes, or
    the s-expression itself for leaves."
   [zloc]
@@ -111,22 +111,22 @@
 
 ;; ## Write
 
-(defn ^{:added "0.4.0"} string
+(defn string
   "Return string representing the current node in `zloc`."
   [zloc]
   (some-> zloc zraw/node node/string))
 
-(defn ^{:deprecated "0.4.0"} ->string
+(defn ->string
   "DEPRECATED. Renamed to [[string]]."
   [zloc]
   (string zloc))
 
-(defn ^{:added "0.4.0"} root-string
+(defn root-string
   "Return string representing the zipped-up `zloc` zipper."
   [zloc]
   (some-> zloc zraw/root node/string))
 
-(defn ^{:deprecated "0.4.0"} ->root-string
+(defn ->root-string
   "DEPRECATED. Renamed to [[root-string]]."
   [zloc]
   (root-string zloc))

src/rewrite_clj/zip/walk.cljc

@@ -28,7 +28,7 @@
 
    Pre-order traversal visits root before children.
    For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is:
-  
+
    1. `(1 (2 3 (4 5) 6 (7 8)) 9)`
    2. `1`
    3. `(2 3 (4 5) 6 (7 8))`
@@ -80,21 +80,21 @@
             :else
             loc))))
 
-(defn ^{:added "0.4.9"} postwalk
+(defn postwalk
   "Return zipper modified by an isolated depth-first post-order traversal.
 
    Pre-order traversal visits children before root.
    For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is:
-  
+
    1. `1`
    2. `2`
-   3. `3` 
+   3. `3`
    4. `4`
    5. `5`
    6. `(4 5)`
    7. `6`
    8. `7`
-   9. `8` 
+   9. `8`
    10. `(7 8)`
    11. `(2 3 (4 5) 6 (7 8))`
    12. `9`

src/rewrite_clj/zip/whitespace.cljc

@@ -62,7 +62,7 @@
 
 ;; ## Insertion
 
-(defn ^{:added "0.5.0"} insert-space-left
+(defn insert-space-left
   "Return zipper with `n` space whitespace node inserted to the left of the current node in `zloc`, without moving location.
    `n` defaults to 1."
   ([zloc] (insert-space-left zloc 1))
@@ -72,7 +72,7 @@
      (zraw/insert-left zloc (nwhitespace/spaces n))
      zloc)))
 
-(defn ^{:added "0.5.0"} insert-space-right
+(defn insert-space-right
   "Return zipper with `n` space whitespace node inserted to the right of the current node in `zloc`, without moving location.
    `n` defaults to 1."
   ([zloc] (insert-space-right zloc 1))
@@ -82,14 +82,14 @@
      (zraw/insert-right zloc (nwhitespace/spaces n))
      zloc)))
 
-(defn ^{:added "0.5.0"} insert-newline-left
+(defn insert-newline-left
   "Return zipper with `n` newlines node inserted to the left of the current node in `zloc`, without moving location.
    `n` defaults to 1."
   ([zloc] (insert-newline-left zloc 1))
   ([zloc n]
    (zraw/insert-left zloc (nwhitespace/newlines n))))
 
-(defn ^{:added "0.5.0"} insert-newline-right
+(defn insert-newline-right
   "Return zipper with `n` newlines node inserted to the right of the current node in `zloc`, without moving location.
    `n` defaults to 1."
   ([zloc] (insert-newline-right zloc 1))
@@ -98,28 +98,28 @@
 
 ;; ## Deprecated Functions
 
-(defn ^{:deprecated "0.5.0"} prepend-space
+(defn prepend-space
    "DEPRECATED: renamed to [[insert-space-left]]."
   ([zloc n]
    (insert-space-left zloc (or n 1)))
   ([zloc]
    (prepend-space zloc nil)))
 
-(defn ^{:deprecated "0.5.0"} append-space
+(defn append-space
    "DEPRECATED: renamed to [[insert-space-right]]."
   ([zloc n]
    (insert-space-right zloc (or n 1)))
   ([zloc]
    (append-space zloc nil)))
 
-(defn ^{:deprecated "0.5.0"} prepend-newline
+(defn prepend-newline
    "DEPRECATED: renamed to [[insert-newline-left]]."
   ([zloc n]
    (insert-newline-left zloc (or n 1)))
   ([zloc]
    (prepend-newline zloc nil)))
 
-(defn ^{:deprecated "0.5.0"} append-newline
+(defn append-newline
    "DEPRECATED: renamed to [[insert-newline-right]]."
   ([zloc n]
    (insert-newline-right zloc (or n 1)))