feat: Add mailmap.edn for canonical display names at export

Author: bzg

.gitignore

@@ -8,6 +8,7 @@ data/
 .clj-kondo/
 config.edn
 config_history/
+mailmap.edn
 todo.org
 public/
 logs/

README.org

@@ -252,6 +252,18 @@ The full tenure history (active and closed) is exported in
 command processing on archived emails even when maintainers have
 changed over time.
 
+*** Canonical display names (=mailmap.edn=)
+
+To unify display names across addresses belonging to the same person,
+create =mailmap.edn= at the repo root:
+
+#+begin_src clojure
+{"Bastien Guerry" ["bzg@gnu.org" "bzg@bzg.fr"]}
+#+end_src
+
+Applied at export time only (DB untouched) to maintainers, authors,
+and owners.  Unlisted emails keep their last observed =From:= name.
+
 For sources whose maintainer list or vocabulary evolved over time,
 declare the history inline via =:periods= on the source (see
 =docs/bark-manual.org §Source periods=).

scripts/bark-docs.clj

@@ -19,7 +19,7 @@
          '[bark.common :refer [default-labels default-commands
                                resolve-labels-map resolve-commands-map
                                resolve-command-syntax
-                               parse-cli-args load-config db-path build-source-map
+                               parse-cli-args load-config load-mailmap db-path build-source-map
                                format-date-iso bark-schema lead-maintainer]]
          '[bark.common-bb :refer [load-datalevin-pod! get-tenures]]
          '[bark.html-bb :refer [pico-cdn resolved-theme set-theme!
@@ -394,7 +394,8 @@
   (when source-name
     (let [tenures     (get-tenures db source-name)
           lead        (lead-maintainer tenures)
-          names       (participant-names-for-source db source-name)
+          names       (merge (participant-names-for-source db source-name)
+                             (load-mailmap))
           ;; Sort: lead first, then alphabetical by email (case-insensitive).
           sort-key    (fn [{:keys [email to]}]
                         [(if (and (nil? to) (= email lead)) 0 1)

scripts/bark-export.clj

@@ -53,7 +53,7 @@
                                format-date format-date-iso
                                report-priority report-status report-descendant-count
                                parse-cli-args parse-delay parse-cutoff-date
-                               load-config db-path build-source-map
+                               load-config load-mailmap db-path build-source-map
                                bark-schema bark-format
                                report-type-spec type->plural
                                votes-by-report vote-counts
@@ -426,7 +426,8 @@
   (reset! export-ctx {:db           db
                       :votes        votes
                       :config       config
-                      :author-names (build-author-names db)}))
+                      :author-names (merge (build-author-names db)
+                                           (load-mailmap))}))
 
 (defn- ctx-db [] (:db @export-ctx))
 (defn- ctx-votes [] (:votes @export-ctx))
@@ -505,6 +506,8 @@
                      (fetch-attachment-data db (:report/message-id report))))
         att-email   (delay (:report/email @att-data))
         from        (or (:email/author-address email) "")
+        from-name   (or (get (ctx-author-names) (str/lower-case from))
+                        (:email/author-name email))
         arch        (archive-url report email source-map)
         src-type    (get-in source-map [source-name :source-type])
         relations   (group-relations report src-type)
@@ -526,7 +529,7 @@
         (assoc-from-addresses report)
         (assoc-owned-name (ctx-author-names))
         (cond->
-         (:email/author-name email)      (assoc :from-name (:email/author-name email))
+         from-name                       (assoc :from-name from-name)
           role                            (assoc :role role)
           (:report/message-id report)     (assoc :message-id (:report/message-id report))
           (:report/version report)        (assoc :version (:report/version report))

src/bark/common.clj

@@ -680,6 +680,26 @@
      (when (.exists f)
        (edn/read-string (slurp f))))))
 
+(defn load-mailmap
+  "Load ./mailmap.edn (or `path`) and return `{email-lc -> canonical-name}`.
+  Input shape: `{\"Canonical Name\" [\"e1@x\" \"e2@y\"]}`.  Multiple
+  emails per person are inverted to a flat lookup.  Returns `{}` if
+  the file is absent.  Used at export time only -- never read by the
+  ingest path, so the DB stays the single source of truth for what
+  each address sent under what name."
+  ([] (load-mailmap "mailmap.edn"))
+  ([path]
+   (let [f (io/file path)]
+     (if (.exists f)
+       (let [m (edn/read-string (slurp f))]
+         (reduce-kv
+          (fn [acc nm emails]
+            (reduce (fn [a e] (assoc a (str/lower-case e) nm))
+                    acc
+                    emails))
+          {} m))
+       {}))))
+
 (defn db-path
   "Resolve the Datalevin DB path: prefer :db {:path …} from the
   config, fall back to BARK_DB env var, then default \"data/bark-db\"."