From a1f884e57692454e46ad69b245c86b846dcb5253 Mon Sep 17 00:00:00 2001
From: Arne Brasseur <arne@arnebrasseur.net>
Date: Mon, 23 Dec 2024 09:15:30 +0100
Subject: [PATCH] Add provenance tracking

---
 CHANGELOG.md                   |  7 +++---
 src/lambdaisland/cli.clj       | 39 +++++++++++++++++++---------------
 test/lambdaisland/cli_test.clj |  9 +++++---
 3 files changed, 32 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b2392f..8636ec7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,9 +2,10 @@
 
 ## Added
 
-## Fixed
-
-## Changed
+- Add provenance tracking, `:lambdaisland.cli/sources` is a map from options key
+  to human readable description of where that key came from, e.g. `--foo command
+  line flag`, or `positional command line argument idx=0`. See
+  [lambdaisland/config](https://github.com/lambdaisland/config) for a use case.
 
 # 0.18.74 (2024-08-05 / 14b74ba)
 
diff --git a/src/lambdaisland/cli.clj b/src/lambdaisland/cli.clj
index cb46222..eb52978 100644
--- a/src/lambdaisland/cli.clj
+++ b/src/lambdaisland/cli.clj
@@ -133,21 +133,23 @@
                 (cmd
                  (if handler
                    (apply call-handler handler opts args)
-                   (assoc opts
-                          (:key flagspec)
-                          (cond
-                            (= 0 (count args))
-                            (if (contains? flagspec :value)
-                              (:value flagspec)
-                              ((fnil inc 0) (get opts (:key flagspec))))
-                            (= 1 (count args))
-                            (if (:coll? flagspec)
-                              ((fnil conj []) (get opts (:key flagspec)) (first args))
-                              (first args))
-                            :else
-                            (if (:coll? flagspec)
-                              ((fnil into []) (get opts (:key flagspec)) args)
-                              (vec args)))))))))))))
+                   (-> opts
+                       (assoc
+                         (:key flagspec)
+                         (cond
+                           (= 0 (count args))
+                           (if (contains? flagspec :value)
+                             (:value flagspec)
+                             ((fnil inc 0) (get opts (:key flagspec))))
+                           (= 1 (count args))
+                           (if (:coll? flagspec)
+                             ((fnil conj []) (get opts (:key flagspec)) (first args))
+                             (first args))
+                           :else
+                           (if (:coll? flagspec)
+                             ((fnil into []) (get opts (:key flagspec)) args)
+                             (vec args))))
+                       (assoc-in [::sources (:key flagspec)] (str (:flag flagspec) " command line flag"))))))))))))
 
 (defn default-parse [s]
   (cond
@@ -294,7 +296,9 @@
                   (h opts (if (and (string? d) (:parse flagspec))
                             ((:parse flagspec default-parse) d)
                             d)))
-                (assoc opts (:key flagspec) d))
+                (-> opts
+                    (assoc (:key flagspec) d)
+                    (assoc-in [::sources (:key flagspec)] (str (:flagstr flagspec) " (default value)"))))
               opts))
           init
           (map second flagpairs)))
@@ -436,7 +440,8 @@
               (merge (when-let [i (:init cmdspec)]
                        (if (or (fn? i) (var? i)) (i) i)))
               (merge (zipmap argnames pos-args))
-              ))
+              (update ::sources merge (zipmap argnames (map (fn [idx] (str "positional command line argument idx=" idx))
+                                                            (range (count pos-args)))))))
 
          (or (nil? command-match)
              (:help opts)
diff --git a/test/lambdaisland/cli_test.clj b/test/lambdaisland/cli_test.clj
index a2d4aec..153cebb 100644
--- a/test/lambdaisland/cli_test.clj
+++ b/test/lambdaisland/cli_test.clj
@@ -23,9 +23,12 @@
     (are [input args expected]
         (is (= expected (cli/dispatch* input args)))
       (cmdspec-1 false) []           {:lambdaisland.cli/argv []}
-      (cmdspec-1 true)  ["-x"]       {:lambdaisland.cli/argv [] :x 1}
-      (cmdspec-n false) ["run"]      {:lambdaisland.cli/argv [] :lambdaisland.cli/command ["run"]}
-      (cmdspec-n true)  ["run" "-x"] {:lambdaisland.cli/argv [] :lambdaisland.cli/command ["run"] :x 1}))
+      (cmdspec-1 true)  ["-x"]       {:lambdaisland.cli/argv [] :x 1
+                                      :lambdaisland.cli/sources {:x "-x command line flag"}}
+      (cmdspec-n false) ["run"]      {:lambdaisland.cli/argv [] :lambdaisland.cli/command ["run"]
+                                      :lambdaisland.cli/sources {}}
+      (cmdspec-n true)  ["run" "-x"] {:lambdaisland.cli/argv [] :lambdaisland.cli/command ["run"] :x 1
+                                      :lambdaisland.cli/sources {:x "-x command line flag"}}))
 
   (testing "help exit"
     (are [input args expected]