0.4.30 - documenting, renaming validate-unit-test to schema

build.clj

@@ -3,7 +3,7 @@
             [deps-deploy.deps-deploy :as dd]))
 
 (def lib 'org.clojars.some/depo)
-(def version "0.4.29")
+(def version "0.4.30")
 (def jar-file (format "target/%s-%s.jar" (name lib) version))
 (def class-dir "target/classes")
 (def url "https://github.com/somecho/depo")

src/depo/core.clj

@@ -40,7 +40,7 @@
 (def CONFIGURATION
   {:command "depo"
    :description "Manage dependencies for Clojure projects easily"
-   :version "0.4.29"
+   :version "0.4.30"
    :opts [{:as "path to configuration file"
            :default nil
            :option "file"

src/depo/dispatch.clj

@@ -1,4 +1,6 @@
 (ns depo.dispatch
+  "Functions related to the control flow of the CLI,
+  as well as IO operations, such as reading and writing the config."
   (:require [clojure.java.io :as io]
             [depo.schema :as schema]
             [depo.utils :as dutils]
@@ -8,11 +10,15 @@
             [zprint.core :as zp]))
 
 (defn skip-procedure
+  "Takes in a `depo.schema/PROCEDURE` map and returns it,
+  printing `reason` on the way."
   [{:keys [zloc]} & reason]
   (apply println (concat reason ["Skipping."]))
   zloc)
 
 (defn ignore-pass
+  "Takes in a `depo.schema/PROCEDURE` map and 
+  checks whether the operation `f` should be skipped."
   [{:keys [dep-data deps-type identifier]
     :as procedure} f]
   (case deps-type
@@ -25,6 +31,14 @@
     :vector (f)))
 
 (defn dispatch
+  "Takes in a `depo.schema/PROCEDURE` map and
+  dispatches the appropriate operations on it.
+  Returns a zipper object after the operation.
+  
+  Operations
+  - `:add`
+  - `:remove`
+  - `:update`"
   [{:keys [operation dep-exists identifier]
     :as procedure}]
   (case operation
@@ -41,6 +55,13 @@
               (skip-procedure procedure identifier "is not a dependency."))))
 
 (defn apply-operation
+  "Takes in a map containing
+  - `:config-path` - the path to the config file
+  - `:id` - the CLI argument 
+  - `:operation` - `:add`, `:update` or `:remove`
+ 
+  Creates a `depo.schema/PROCEDURE` map to dispatch operations.
+  It writes the resulting configuration into `config-path`. "
   [{:keys [config-path id operation]}]
   (let [config-zip (z/of-string (slurp config-path))
         project-type (dutils/get-project-type config-path)

src/depo/zoperations.clj

@@ -1,11 +1,12 @@
 (ns depo.zoperations
-  "Zipper based operations."
-  (:require [clojure.string :as str]
-            [depo.resolver :as r]
+  "Methods that operate on zipper objects created by
+  rewrite-clj."
+  (:require [depo.resolver :as r]
             [depo.utils :as dutils]
             [rewrite-clj.zip :as z]))
 
 (defn get-dependency-type
+  "TO DEPRECATE"
   [deps]
   (cond
     (map? deps) :map
@@ -27,6 +28,7 @@
       zloc)))
 
 (defn get-all-dependency-names
+  "TO REWRITE"
   [config-path]
   (let [zloc (z/of-string (slurp config-path))
         project-type (dutils/get-project-type config-path)
@@ -48,6 +50,11 @@
                 :vector (map #(str (first %)) vec-map))))))
 
 (defn get-deps
+  "- `zloc` - the configuration file parsed as a zipper object
+  - `keys` - a vector of keys to locate the dependencies in the configuration file
+  - `project-type` - either `:shadow`, `:lein` or `:default` 
+ 
+  Gets the dependency zipper object from `zloc`"
   [zloc keys project-type]
   (case project-type
     :lein (-> (z/find-value zloc z/next (first keys))
@@ -59,6 +66,11 @@
     (traverse-zip-map zloc keys)))
 
 (defn get-dependency-data
+  "Gets the corresponding data from a dependency zipper object.
+ 
+  This would return
+  - `{:mvn/version ...}` or `{:local/root}` if `zloc` is a map zipper
+  - the version number as a string if `zloc` is a vector zipper"
   [zloc identifier]
   (let [deps-type (cond
                     (z/map? zloc) :map
@@ -75,6 +87,8 @@
                     (recur (z/right cur))))))))
 
 (defn append-dependency
+  "Takes a map that satisfies the `depo.schema/PROCEDURE` spec.
+  Appends a dependency to the dependency zipper object and returns it."
   [{:keys [argument deps-type identifier zloc]}]
   (let [{:keys [version]} (r/conform-version argument)]
     (println "Adding" identifier version)
@@ -93,6 +107,8 @@
                   (z/append-child [identifier version])))))
 
 (defn update-dependency
+  "Takes a map that satisfies the `depo.schema/PROCEDURE` spec.
+  Updates a dependency in the dependency zipper object and returns it."
   [{:keys [argument deps-type identifier zloc dep-data]}]
   (let [{:keys [version]} (r/conform-version argument)
         current-version (case deps-type
@@ -110,6 +126,8 @@
                     (recur (z/right cur))))))))
 
 (defn remove-dependency
+  "Takes a map that satisfies the `depo.schema/PROCEDURE` spec.
+  Removes a dependency the dependency zipper object and returns it."
   [{:keys [deps-type identifier zloc]}]
   (println "Removing" identifier)
   (case deps-type

test/depo/schema_unit_test.clj

@@ -0,0 +1,49 @@
+(ns depo.schema-unit-test
+  (:require [clojure.test :refer  [testing deftest is]]
+            [depo.schema :refer [valid-id?
+                                 valid-version?
+                                 valid-dependency-map?]]))
+
+(deftest valid-id
+  (testing "alpha is valid" (is (valid-id? "alpha")))
+  (testing "com.cognitect is valid" (is (valid-id? "com.cognitect")))
+  (testing "org/clojure is not valid" (is (not (valid-id? "org/clojure"))))
+  (testing "org@clojure is not valid" (is (not (valid-id? "org@clojure"))))
+  (testing "an empty string is not valid" (is (not (valid-id? ""))))
+  (testing "s4lj.s4lj is valid" (is (valid-id? "s4lj.s4lj"))))
+
+(deftest valid-version
+  (testing "0.0.0 is valid" (is (valid-version? "0.0.0")))
+  (testing "0.0.0rc is valid" (is (valid-version? "0.0.0rc")))
+  (testing "0.0.0-rc is valid" (is (valid-version? "0.0.0-rc")))
+  (testing "0.0.0-beta1 is valid" (is (valid-version? "0.0.0-beta1")))
+  (testing "1 is not valid" (is (not (valid-version? "1"))))
+  (testing "alpha is not valid" (is (not (valid-version? "alpha"))))
+  (testing "an empty string is not valid" (is (not (valid-version? ""))))
+  (testing "0.0.0! is not valid" (is (not (valid-version? "0.0.0!"))))
+  (testing "0.0.0-- is not valid" (is (not (valid-version? "0.0.0--"))))
+  (testing ". is not valid" (is (not (valid-version? "."))))
+  (testing "... is not valid" (is (not (valid-version? "...")))))
+
+(deftest valid-dependency
+  (testing "reagent reagent nil is valid"
+    (is (valid-dependency-map? {:groupID "reagent"
+                                :artifactID "reagent"
+                                :version nil})))
+  (testing "com.cognitect anomalies 0.1.7 is valid"
+    (is (valid-dependency-map? {:groupID "com.cognitect"
+                                :artifactID "anomalies"
+                                :version "0.1.7"})))
+  (testing "org.clojure clojure 0.11.1-alpha is valid"
+    (is (valid-dependency-map? {:groupID "org.clojure"
+                                :artifactID "clojure"
+                                :version "0.11.1-alpha"})))
+  (testing "a missing groupID is not valid"
+    (is (not (valid-dependency-map? {:artifactID "clojure"
+                                     :version "0.11.1-alpha"}))))
+  (testing "a missing artifactID is not valid"
+    (is (not (valid-dependency-map? {:groupID "org.clojure"
+                                     :version "0.11.1-alpha"}))))
+  (testing "a missing version is valid"
+    (is (valid-dependency-map? {:groupID "reagent"
+                                :artifactID "reagent"}))))