feat:org-contacts: Enhance email parsing and add tests

Add a new function `cj/--parse-email-string` to parse email strings
with multiple formats and separators, ensuring robust handling of
real-world email variations. This commit also includes extensive
tests for the new parsing function, covering normal, edge, and
special cases, ensuring comprehensive test coverage and reliability.

2 files changed, 294 insertions, 80 deletions

diff --git a/modules/org-contacts-config.el b/modules/org-contacts-config.el
index 706412a2..df4e18f1 100644
--- a/modules/org-contacts-config.el
+++ b/modules/org-contacts-config.el
@@ -20,17 +20,17 @@
 
   ;; Add a wrapper function that ensures proper context
   (defun cj/org-contacts-anniversaries-safe ()
-	"Safely call org-contacts-anniversaries with required bindings."
-	(require 'diary-lib)
-	;; These need to be dynamically bound for diary functions
-	(defvar date)
-	(defvar entry)
-	(defvar original-date)
-	(let ((date (calendar-current-date))
-		  (entry "")
-		  (original-date (calendar-current-date)))
-	  (ignore-errors
-		(org-contacts-anniversaries))))
+    "Safely call org-contacts-anniversaries with required bindings."
+    (require 'diary-lib)
+    ;; These need to be dynamically bound for diary functions
+    (defvar date)
+    (defvar entry)
+    (defvar original-date)
+    (let ((date (calendar-current-date))
+          (entry "")
+          (original-date (calendar-current-date)))
+      (ignore-errors
+        (org-contacts-anniversaries))))
 
   ;; Use the safe wrapper instead
   (add-hook 'org-agenda-finalize-hook 'cj/org-contacts-anniversaries-safe))
@@ -39,8 +39,8 @@
 
 (with-eval-after-load 'org-capture
   (add-to-list 'org-capture-templates
-			   '("C" "Contact" entry (file+headline contacts-file "Contacts")
-				 "* %(cj/org-contacts-template-name)
+               '("C" "Contact" entry (file+headline contacts-file "Contacts")
+                 "* %(cj/org-contacts-template-name)
 :PROPERTIES:
 :EMAIL: %(cj/org-contacts-template-email)
 :PHONE: %^{Phone(s) - separate multiple with commas}
@@ -57,31 +57,31 @@ Added: %U")))
 ;; duplicate?!?
 ;; (with-eval-after-load 'org-capture
 ;;   (add-to-list 'org-capture-templates
-;; 			   '("C" "Contact" entry (file+headline contacts-file "Contacts")
-;; 				 "* %(cj/org-contacts-template-name)
+;;             '("C" "Contact" entry (file+headline contacts-file "Contacts")
+;;               "* %(cj/org-contacts-template-name)
 ;; Added: %U")))
 
 (defun cj/org-contacts-template-name ()
   "Get name for contact template from context."
   (let ((name (when (boundp 'cj/contact-name) cj/contact-name)))
-	(or name
-		(when (eq major-mode 'mu4e-headers-mode)
-		  (mu4e-message-field (mu4e-message-at-point) :from-or-to))
-		(when (eq major-mode 'mu4e-view-mode)
-		  (mu4e-message-field mu4e~view-message :from-or-to))
-		(read-string "Name: "))))
+    (or name
+        (when (eq major-mode 'mu4e-headers-mode)
+          (mu4e-message-field (mu4e-message-at-point) :from-or-to))
+        (when (eq major-mode 'mu4e-view-mode)
+          (mu4e-message-field mu4e~view-message :from-or-to))
+        (read-string "Name: "))))
 
 (defun cj/org-contacts-template-email ()
   "Get email for contact template from context."
   (let ((email (when (boundp 'cj/contact-email) cj/contact-email)))
-	(or email
-		(when (eq major-mode 'mu4e-headers-mode)
-		  (let ((from (mu4e-message-field (mu4e-message-at-point) :from)))
-			(when from (cdr (car from)))))
-		(when (eq major-mode 'mu4e-view-mode)
-		  (let ((from (mu4e-message-field mu4e~view-message :from)))
-			(when from (cdr (car from)))))
-		(read-string "Email: "))))
+    (or email
+        (when (eq major-mode 'mu4e-headers-mode)
+          (let ((from (mu4e-message-field (mu4e-message-at-point) :from)))
+            (when from (cdr (car from)))))
+        (when (eq major-mode 'mu4e-view-mode)
+          (let ((from (mu4e-message-field mu4e~view-message :from)))
+            (when from (cdr (car from)))))
+        (read-string "Email: "))))
 
 ;;; ------------------------- Quick Contact Functions ---------------------------
 
@@ -91,13 +91,13 @@ Added: %U")))
   (find-file contacts-file)
   (goto-char (point-min))
   (let ((contact (completing-read "Contact: "
-								  (org-map-entries
-								   (lambda () (nth 4 (org-heading-components)))
-								   nil (list contacts-file)))))
-	(goto-char (point-min))
-	(search-forward contact)
-	(org-fold-show-entry)
-	(org-reveal)))
+                                  (org-map-entries
+                                   (lambda () (nth 4 (org-heading-components)))
+                                   nil (list contacts-file)))))
+    (goto-char (point-min))
+    (search-forward contact)
+    (org-fold-show-entry)
+    (org-reveal)))
 
 (defun cj/org-contacts-new ()
   "Create a new contact."
@@ -110,19 +110,6 @@ Added: %U")))
   (find-file contacts-file)
   (org-columns))
 
-;;; -------------------------- Org-Roam Integration -----------------------------
-
-;; (with-eval-after-load 'org-roam
-;;   (defun cj/org-contacts-link-to-roam ()
-;;  "Link current contact to an org-roam node."
-;;  (interactive)
-;;  (when (eq major-mode 'org-mode)
-;;    (let ((contact-name (org-entry-get (point) "ITEM")))
-;;      (org-set-property "ROAM_REFS"
-;;                        (org-roam-node-id
-;;                         (org-roam-node-read nil nil nil nil
-;;                                             :initial-input contact-name)))))))
-
 ;;; ----------------------------- Birthday Agenda --------------------------------
 
 (with-eval-after-load 'org-agenda
@@ -131,40 +118,48 @@ Added: %U")))
 
   ;; Custom agenda command for upcoming birthdays
   (add-to-list 'org-agenda-custom-commands
-			   '("b" "Birthdays and Anniversaries"
-				 ((tags-todo "BIRTHDAY|ANNIVERSARY"
-							 ((org-agenda-overriding-header "Upcoming Birthdays and Anniversaries")
-							  (org-agenda-sorting-strategy '(time-up))))))))
+               '("b" "Birthdays and Anniversaries"
+                 ((tags-todo "BIRTHDAY|ANNIVERSARY"
+                             ((org-agenda-overriding-header "Upcoming Birthdays and Anniversaries")
+                              (org-agenda-sorting-strategy '(time-up))))))))
 
 ;;; ---------------------------- Core Contact Data Functions ---------------------------
 
 (defun cj/org-contacts--props-matching (entry pattern)
   "Return all property values from ENTRY whose keys match PATTERN (a regexp)."
   (let ((props (nth 2 entry)))
-	(delq nil
-		  (mapcar (lambda (prop)
-					(when (string-match-p pattern (car prop))
-					  (cdr prop)))
-				  props))))
+    (delq nil
+          (mapcar (lambda (prop)
+                    (when (string-match-p pattern (car prop))
+                      (cdr prop)))
+                  props))))
+
+(defun cj/--parse-email-string (name email-string)
+  "Parse EMAIL-STRING and return formatted entries for NAME.
+EMAIL-STRING may contain multiple emails separated by commas, semicolons, or spaces.
+Returns a list of strings formatted as 'Name <email>'.
+Returns nil if EMAIL-STRING is nil or contains only whitespace."
+  (when (and email-string (string-match-p "[^[:space:]]" email-string))
+    (let ((emails (split-string email-string "[,;[:space:]]+" t)))
+      (mapcar (lambda (email)
+                (format "%s <%s>" name (string-trim email)))
+              emails))))
 
 (defun cj/get-all-contact-emails ()
   "Retrieve all contact emails from org-contacts database.
 Returns a list of formatted strings like \"Name <email@example.com>\".
 This is the core function used by the mu4e integration module."
   (let ((contacts (org-contacts-db)))
-	(delq nil
-		  (mapcan (lambda (e)
-					(let* ((name (car e))
-						   ;; This returns a LIST of email strings
-						   (email-strings (cj/org-contacts--props-matching e "EMAIL")))
-					  ;; Need mapcan here to handle the list
-					  (mapcan (lambda (email-str)
-								(when (and email-str (string-match-p "[^[:space:]]" email-str))
-								  (mapcar (lambda (email)
-											(format "%s <%s>" name (string-trim email)))
-										  (split-string email-str "[,;[:space:]]+" t))))
-							  email-strings)))
-				  contacts))))
+    (delq nil
+          (mapcan (lambda (e)
+                    (let* ((name (car e))
+                           ;; This returns a LIST of email strings
+                           (email-strings (cj/org-contacts--props-matching e "EMAIL")))
+                      ;; Process each email string using the extracted parser
+                      (mapcan (lambda (email-str)
+                                (cj/--parse-email-string name email-str))
+                              email-strings)))
+                  contacts))))
 
 ;; Simple insertion function for use outside of mu4e
 (defun cj/insert-contact-email ()
@@ -173,8 +168,8 @@ For use outside of mu4e compose buffers. In mu4e, the integration
 module provides more sophisticated completion."
   (interactive)
   (let* ((items (cj/get-all-contact-emails))
-		 (selected (completing-read "Contact: " items nil t)))
-	(insert selected)))
+         (selected (completing-read "Contact: " items nil t)))
+    (insert selected)))
 
 ;;; -------------------------------- Org Contacts --------------------------------
 
@@ -195,9 +190,9 @@ module provides more sophisticated completion."
 
   (setq mu4e-org-contacts-file contacts-file)
   (add-to-list 'mu4e-headers-actions
-			   '("org-contact-add" . mu4e-action-add-org-contact) t)
+               '("org-contact-add" . mu4e-action-add-org-contact) t)
   (add-to-list 'mu4e-view-actions
-			   '("org-contact-add" . mu4e-action-add-org-contact) t)
+               '("org-contact-add" . mu4e-action-add-org-contact) t)
 
   ;; Disable mu4e's built-in completion in favor of our custom solution
   (setq mu4e-compose-complete-addresses nil))
@@ -207,11 +202,11 @@ module provides more sophisticated completion."
 ;; Keymap for `org-contacts' commands
 (defvar cj/org-contacts-map
   (let ((map (make-sparse-keymap)))
-	(keymap-set map "f" #'cj/org-contacts-find)     ;; find contact
-	(keymap-set map "n" #'cj/org-contacts-new)      ;; new contact
-	(keymap-set map "e" #'cj/insert-contact-email)  ;; inserts email from org-contact
-	(keymap-set map "v" #'cj/org-contacts-view-all) ;; view all contacts
-	map)
+    (keymap-set map "f" #'cj/org-contacts-find)     ;; find contact
+    (keymap-set map "n" #'cj/org-contacts-new)      ;; new contact
+    (keymap-set map "e" #'cj/insert-contact-email)  ;; inserts email from org-contact
+    (keymap-set map "v" #'cj/org-contacts-view-all) ;; view all contacts
+    map)
   "Keymap for `org-contacts' commands.")
 
 ;; Bind the org-contacts map to the C-c C prefix
diff --git a/tests/test-org-contacts-parse-email.el b/tests/test-org-contacts-parse-email.el
new file mode 100644
index 00000000..37e79fba
--- /dev/null
+++ b/tests/test-org-contacts-parse-email.el
@@ -0,0 +1,219 @@
+;;; test-org-contacts-parse-email.el --- Tests for cj/--parse-email-string -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for the cj/--parse-email-string function from org-contacts-config.el
+;;
+;; This function parses a string containing one or more email addresses
+;; separated by commas, semicolons, or spaces, and formats them as
+;; "Name <email>" strings.
+;;
+;; Examples:
+;; Input:  name="John Doe", email-string="john@example.com"
+;; Output: '("John Doe <john@example.com>")
+;;
+;; Input:  name="Jane Smith", email-string="jane@work.com, jane@home.com"
+;; Output: '("Jane Smith <jane@work.com>" "Jane Smith <jane@home.com>")
+
+;;; Code:
+
+(require 'ert)
+(require 'testutil-general)
+
+;; Add modules directory to load path
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+
+;; Now load the actual production module
+(require 'org-contacts-config)
+
+;;; Test Helpers
+
+(defun test-parse-email (name email-string)
+  "Test cj/--parse-email-string with NAME and EMAIL-STRING.
+Returns the formatted email list."
+  (cj/--parse-email-string name email-string))
+
+;;; Normal Cases - Single Email
+
+(ert-deftest test-parse-single-email ()
+  "Should format single email address."
+  (let ((result (test-parse-email "John Doe" "john@example.com")))
+    (should (equal result '("John Doe <john@example.com>")))))
+
+(ert-deftest test-parse-single-email-with-subdomain ()
+  "Should handle email with subdomain."
+  (let ((result (test-parse-email "Jane Smith" "jane@mail.company.com")))
+    (should (equal result '("Jane Smith <jane@mail.company.com>")))))
+
+(ert-deftest test-parse-email-with-numbers ()
+  "Should handle email containing numbers."
+  (let ((result (test-parse-email "User 123" "user123@test.com")))
+    (should (equal result '("User 123 <user123@test.com>")))))
+
+(ert-deftest test-parse-email-with-dots ()
+  "Should handle email with dots in local part."
+  (let ((result (test-parse-email "Bob Jones" "bob.jones@example.com")))
+    (should (equal result '("Bob Jones <bob.jones@example.com>")))))
+
+(ert-deftest test-parse-email-with-hyphen ()
+  "Should handle email with hyphens."
+  (let ((result (test-parse-email "Alice Brown" "alice-brown@test-domain.com")))
+    (should (equal result '("Alice Brown <alice-brown@test-domain.com>")))))
+
+;;; Normal Cases - Multiple Emails with Different Separators
+
+(ert-deftest test-parse-two-emails-comma ()
+  "Should parse two emails separated by comma."
+  (let ((result (test-parse-email "John Doe" "john@work.com, john@home.com")))
+    (should (equal result '("John Doe <john@work.com>" "John Doe <john@home.com>")))))
+
+(ert-deftest test-parse-two-emails-semicolon ()
+  "Should parse two emails separated by semicolon."
+  (let ((result (test-parse-email "Jane Smith" "jane@work.com; jane@home.com")))
+    (should (equal result '("Jane Smith <jane@work.com>" "Jane Smith <jane@home.com>")))))
+
+(ert-deftest test-parse-two-emails-space ()
+  "Should parse two emails separated by space."
+  (let ((result (test-parse-email "Bob Jones" "bob@work.com bob@home.com")))
+    (should (equal result '("Bob Jones <bob@work.com>" "Bob Jones <bob@home.com>")))))
+
+(ert-deftest test-parse-three-emails-mixed-separators ()
+  "Should parse emails with mixed separators."
+  (let ((result (test-parse-email "Alice" "alice@a.com, alice@b.com; alice@c.com")))
+    (should (equal result '("Alice <alice@a.com>" "Alice <alice@b.com>" "Alice <alice@c.com>")))))
+
+(ert-deftest test-parse-multiple-emails-with-spaces ()
+  "Should parse comma-separated emails with spaces."
+  (let ((result (test-parse-email "User" "a@test.com , b@test.com , c@test.com")))
+    (should (equal result '("User <a@test.com>" "User <b@test.com>" "User <c@test.com>")))))
+
+;;; Normal Cases - Whitespace Handling
+
+(ert-deftest test-parse-email-leading-whitespace ()
+  "Should trim leading whitespace from email."
+  (let ((result (test-parse-email "John" "  john@example.com")))
+    (should (equal result '("John <john@example.com>")))))
+
+(ert-deftest test-parse-email-trailing-whitespace ()
+  "Should trim trailing whitespace from email."
+  (let ((result (test-parse-email "Jane" "jane@example.com  ")))
+    (should (equal result '("Jane <jane@example.com>")))))
+
+(ert-deftest test-parse-email-surrounding-whitespace ()
+  "Should trim surrounding whitespace from email."
+  (let ((result (test-parse-email "Bob" "  bob@example.com  ")))
+    (should (equal result '("Bob <bob@example.com>")))))
+
+(ert-deftest test-parse-emails-with-tabs ()
+  "Should handle emails separated by tabs."
+  (let ((result (test-parse-email "User" "a@test.com\tb@test.com")))
+    (should (equal result '("User <a@test.com>" "User <b@test.com>")))))
+
+;;; Edge Cases - Empty and Nil
+
+(ert-deftest test-parse-nil-email-string ()
+  "Should return nil for nil email string."
+  (let ((result (test-parse-email "John Doe" nil)))
+    (should (null result))))
+
+(ert-deftest test-parse-empty-email-string ()
+  "Should return nil for empty email string."
+  (let ((result (test-parse-email "Jane Smith" "")))
+    (should (null result))))
+
+(ert-deftest test-parse-whitespace-only ()
+  "Should return nil for whitespace-only string."
+  (let ((result (test-parse-email "Bob Jones" "   ")))
+    (should (null result))))
+
+(ert-deftest test-parse-tabs-only ()
+  "Should return nil for tabs-only string."
+  (let ((result (test-parse-email "Alice" "\t\t\t")))
+    (should (null result))))
+
+(ert-deftest test-parse-mixed-whitespace-only ()
+  "Should return nil for mixed whitespace."
+  (let ((result (test-parse-email "User" " \t \n ")))
+    (should (null result))))
+
+;;; Edge Cases - Multiple Consecutive Separators
+
+(ert-deftest test-parse-multiple-commas ()
+  "Should handle multiple consecutive commas."
+  (let ((result (test-parse-email "John" "john@a.com,,,john@b.com")))
+    (should (equal result '("John <john@a.com>" "John <john@b.com>")))))
+
+(ert-deftest test-parse-multiple-semicolons ()
+  "Should handle multiple consecutive semicolons."
+  (let ((result (test-parse-email "Jane" "jane@a.com;;;jane@b.com")))
+    (should (equal result '("Jane <jane@a.com>" "Jane <jane@b.com>")))))
+
+(ert-deftest test-parse-multiple-spaces ()
+  "Should handle multiple consecutive spaces."
+  (let ((result (test-parse-email "Bob" "bob@a.com    bob@b.com")))
+    (should (equal result '("Bob <bob@a.com>" "Bob <bob@b.com>")))))
+
+(ert-deftest test-parse-mixed-multiple-separators ()
+  "Should handle mixed consecutive separators."
+  (let ((result (test-parse-email "User" "a@test.com , ; b@test.com")))
+    (should (equal result '("User <a@test.com>" "User <b@test.com>")))))
+
+;;; Edge Cases - Special Name Formats
+
+(ert-deftest test-parse-name-with-title ()
+  "Should handle name with title."
+  (let ((result (test-parse-email "Dr. John Smith" "john@example.com")))
+    (should (equal result '("Dr. John Smith <john@example.com>")))))
+
+(ert-deftest test-parse-name-with-suffix ()
+  "Should handle name with suffix."
+  (let ((result (test-parse-email "John Doe Jr." "john@example.com")))
+    (should (equal result '("John Doe Jr. <john@example.com>")))))
+
+(ert-deftest test-parse-name-with-special-chars ()
+  "Should handle name with special characters."
+  (let ((result (test-parse-email "O'Brien, Patrick" "patrick@example.com")))
+    (should (equal result '("O'Brien, Patrick <patrick@example.com>")))))
+
+(ert-deftest test-parse-unicode-name ()
+  "Should handle Unicode characters in name."
+  (let ((result (test-parse-email "José García" "jose@example.com")))
+    (should (equal result '("José García <jose@example.com>")))))
+
+;;; Edge Cases - Special Email Formats
+
+(ert-deftest test-parse-email-with-plus ()
+  "Should handle email with plus sign."
+  (let ((result (test-parse-email "User" "user+tag@example.com")))
+    (should (equal result '("User <user+tag@example.com>")))))
+
+(ert-deftest test-parse-email-with-underscore ()
+  "Should handle email with underscore."
+  (let ((result (test-parse-email "User" "user_name@example.com")))
+    (should (equal result '("User <user_name@example.com>")))))
+
+(ert-deftest test-parse-very-long-email ()
+  "Should handle very long email address."
+  (let* ((long-local (make-string 50 ?a))
+         (email (concat long-local "@example.com"))
+         (result (test-parse-email "User" email)))
+    (should (equal result (list (format "User <%s>" email))))))
+
+;;; Integration Tests
+
+(ert-deftest test-parse-realistic-contact ()
+  "Should parse realistic contact with multiple emails."
+  (let ((result (test-parse-email "John Doe" "john.doe@company.com, jdoe@personal.com")))
+    (should (equal result '("John Doe <john.doe@company.com>" "John Doe <jdoe@personal.com>")))))
+
+(ert-deftest test-parse-messy-input ()
+  "Should handle messy real-world input."
+  (let ((result (test-parse-email "Jane Smith" "  jane@work.com ;  jane@home.com,jane@mobile.com  ")))
+    (should (equal result '("Jane Smith <jane@work.com>" "Jane Smith <jane@home.com>" "Jane Smith <jane@mobile.com>")))))
+
+(ert-deftest test-parse-single-with-extra-separators ()
+  "Should handle single email with trailing separators."
+  (let ((result (test-parse-email "Bob" "bob@example.com;;;")))
+    (should (equal result '("Bob <bob@example.com>")))))
+
+(provide 'test-org-contacts-parse-email)
+;;; test-org-contacts-parse-email.el ends here