chore(elisp): clear byte-compile warnings (mail, dashboard, eshell, erc)

Add declare-function/defvar declarations for lazily-loaded package functions and variables so each module compiles cleanly standalone, reflow over-long docstrings, and swap the obsolete erc-server-buffer-p for its named replacement erc-server-or-unjoined-channel-buffer-p (obsolete since 30.1). No behavior change. Two erc setq targets (erc-unique-buffers, erc-generate-buffer-name-function) appear not to be real ERC variables — declared to silence the warning with a NOTE flagging that the intended buffer-naming may not be taking effect.

Claude-Session: https://claude.ai/code/session_01BqrdWUo9GcznYX2pZr76gZ

5 files changed, 175 insertions, 29 deletions

diff --git a/modules/dashboard-config.el b/modules/dashboard-config.el
index 38510e801..2629fe0e0 100644
--- a/modules/dashboard-config.el
+++ b/modules/dashboard-config.el
@@ -23,6 +23,56 @@
 (autoload 'cj/make-buffer-undead "undead-buffers" nil t)
 (declare-function ghostel "ghostel" (&optional arg))
 
+;; ------------------------------ Declarations -------------------------------
+;; These functions and variables belong to lazily-loaded packages or to other
+;; cj modules; declaring them keeps the byte-compiler quiet without forcing an
+;; eager require.  Behavior is unchanged -- the symbols still resolve at runtime
+;; once their owning package/module loads.
+
+;; dashboard package internals used by the bookmark-insertion override.
+(declare-function dashboard-insert-section "dashboard")
+(declare-function dashboard-subseq "dashboard")
+(declare-function dashboard-get-shortcut "dashboard")
+(declare-function dashboard-shorten-path "dashboard")
+(declare-function dashboard--align-length-by-type "dashboard")
+(declare-function dashboard--generate-align-format "dashboard")
+(declare-function dashboard-refresh-buffer "dashboard")
+(declare-function dashboard-open "dashboard")
+(defvar dashboard-bookmarks-show-path)
+(defvar dashboard--bookmarks-cache-item-format)
+
+;; bookmark.el (required at runtime inside `dashboard-insert-bookmarks').
+(declare-function bookmark-all-names "bookmark")
+(declare-function bookmark-get-filename "bookmark")
+
+;; recentf.el (required at runtime inside the exclude helper).
+(defvar recentf-exclude)
+
+;; nerd-icons glyph functions used in the launcher table.
+(declare-function nerd-icons-faicon "nerd-icons")
+(declare-function nerd-icons-devicon "nerd-icons")
+(declare-function nerd-icons-mdicon "nerd-icons")
+(declare-function nerd-icons-octicon "nerd-icons")
+
+;; user-constants.el provides the home-directory constant.
+(defvar user-home-dir)
+
+;; Launcher actions defined in other cj modules.
+(declare-function cj/main-agenda-display "org-agenda-config")
+(declare-function cj/elfeed-open "elfeed-config")
+(declare-function cj/drill-start "org-drill-config")
+(declare-function cj/music-playlist-toggle "music-config")
+(declare-function cj/music-playlist-load "music-config")
+(declare-function cj/erc-switch-to-buffer-with-completion "erc-config")
+(declare-function cj/telega "telega-config")
+(declare-function cj/slack-start "slack-config")
+(declare-function cj/signel-message "signal-config")
+(declare-function cj/kill-all-other-buffers-and-windows "undead-buffers")
+
+;; External package commands invoked by launchers.
+(declare-function mu4e "mu4e")
+(declare-function pearl-list-issues "pearl")
+
 ;; ------------------------ Dashboard Bookmarks Override -----------------------
 ;; overrides the bookmark insertion from the dashboard package to provide an
 ;; option that only shows the bookmark name, avoiding the path. Paths are often
@@ -35,8 +85,11 @@
 
 ;; `el' is bound dynamically by dashboard's section-insertion machinery, which the
 ;; override below plugs into.  Declare it so the byte-compiler reads the
-;; references as that special variable rather than a free variable.
-(defvar el)
+;; references as that special variable rather than a free variable.  The name is
+;; dashboard's, not ours, so the missing-prefix lint is suppressed rather than
+;; renamed (renaming would break the dynamic binding dashboard supplies).
+(with-suppressed-warnings ((lexical el))
+  (defvar el))
 
 (defun dashboard-insert-bookmarks (list-size)
   "Add the list of LIST-SIZE items of bookmarks."
diff --git a/modules/erc-config.el b/modules/erc-config.el
index c89e46bb3..3e98a66a3 100644
--- a/modules/erc-config.el
+++ b/modules/erc-config.el
@@ -33,6 +33,33 @@
 ;; is read at load time below (erc-user-full-name), so a standalone .elc needs it.
 (require 'user-constants)
 
+;; ERC loads lazily (use-package :commands), so these symbols aren't bound at
+;; this file's compile time.  Declare them to keep the byte-compiler quiet
+;; without forcing an eager require.
+
+;; Functions provided by the erc package.
+(declare-function erc-buffer-list "erc")
+(declare-function erc-server-process-alive "erc")
+(declare-function erc-server-or-unjoined-channel-buffer-p "erc")
+(declare-function erc-current-nick "erc")
+(declare-function erc-join-channel "erc")
+(declare-function erc-part-from-channel "erc")
+(declare-function erc-quit-server "erc")
+
+;; Variables read/set in the use-package :config block below.
+(defvar erc-log-channels-directory)
+(defvar erc-track-exclude-types)
+(defvar erc-track-exclude-server-buffer)
+(defvar erc-track-visibility)
+(defvar erc-track-switch-direction)
+(defvar erc-track-showcount)
+;; NOTE: erc-unique-buffers and erc-generate-buffer-name-function are not ERC
+;; variables in Emacs 30.x (no defcustom/defvar in the package); the setq below
+;; only creates inert globals.  Declared here to silence the warning without
+;; changing the existing (no-op) behavior -- see the SUSPICIOUS note.
+(defvar erc-unique-buffers)
+(defvar erc-generate-buffer-name-function)
+
 ;; ------------------------------------ ERC ------------------------------------
 ;; Server definitions and connection settings
 
@@ -99,7 +126,7 @@ Change this value to use a different nickname.")
   (let ((server-buffers '()))
 	(dolist (buf (erc-buffer-list))
 	  (with-current-buffer buf
-		(when (and (erc-server-buffer-p) (erc-server-process-alive))
+		(when (and (erc-server-or-unjoined-channel-buffer-p) (erc-server-process-alive))
 		  (unless (member (buffer-name) server-buffers)
 			(push (buffer-name) server-buffers)))))
 
@@ -132,7 +159,7 @@ Buffer names are shown with server context for clarity."
   "Return t if the current buffer is an active ERC server buffer."
   (and (derived-mode-p 'erc-mode)
 	   (erc-server-process-alive)
-	   (erc-server-buffer-p)))
+	   (erc-server-or-unjoined-channel-buffer-p)))
 
 
 (defun cj/erc-get-channels-for-current-server ()
@@ -158,7 +185,7 @@ Auto-adds # prefix if missing.  Offers completion from configured channels."
 		(let ((server-buffers (cl-remove-if-not
 							   (lambda (buf)
 								 (with-current-buffer buf
-								   (and (erc-server-buffer-p)
+								   (and (erc-server-or-unjoined-channel-buffer-p)
 										(erc-server-process-alive))))
 							   (erc-buffer-list))))
 		  (if server-buffers
diff --git a/modules/eshell-config.el b/modules/eshell-config.el
index d3c8ccdfd..723a7e61e 100644
--- a/modules/eshell-config.el
+++ b/modules/eshell-config.el
@@ -26,6 +26,32 @@
 
 (require 'system-utils)
 
+;; Eshell is loaded lazily (:commands eshell), so its vars and functions are
+;; not defined when this file is byte-compiled standalone. Declare them to
+;; silence compile-time free-variable / undefined-function warnings.
+(defvar eshell-banner-message)
+(defvar eshell-scroll-to-bottom-on-input)
+(defvar eshell-error-if-no-glob)
+(defvar eshell-hist-ignoredups)
+(defvar eshell-save-history-on-exit)
+(defvar eshell-prefer-lisp-functions)
+(defvar eshell-destroy-buffer-when-process-dies)
+(defvar eshell-prompt-function)
+(defvar eshell-cmpl-cycle-completions)
+(defvar eshell-modules-list)
+(defvar eshell-hist-mode-map)
+(defvar eshell-visual-commands)
+(defvar eshell-visual-subcommands)
+(defvar eshell-visual-options)
+(defvar eshell-history-ring)
+(defvar eshell-preoutput-filter-functions)
+(defvar eshell-output-filter-functions)
+
+(declare-function ring-elements "ring")
+(declare-function eshell-send-input "esh-mode")
+(declare-function eshell/pwd "em-dirs")
+(declare-function eshell/alias "em-alias")
+
 (defgroup cj/eshell nil
   "Personal Eshell configuration."
   :group 'eshell)
diff --git a/modules/mail-config.el b/modules/mail-config.el
index 08f50b12f..1d8a98c97 100644
--- a/modules/mail-config.el
+++ b/modules/mail-config.el
@@ -50,6 +50,31 @@
 
 (declare-function mu4e-message-field "mu4e-message")
 
+;; ----------------------------- Declarations ----------------------------------
+;; mu4e/org-msg load lazily, so the byte-compiler can't see these package
+;; functions and variables when this module is compiled standalone.  Declare
+;; them to silence free-variable / undefined-function warnings without forcing
+;; an eager require (which would defeat lazy loading).  The cj/... entries are
+;; forward references: defined later in this file's `:config' block, or in
+;; mu4e-org-contacts-integration (required at load time inside that block).
+
+(declare-function mu4e-headers-mark-for-each-if "mu4e-mark")
+(declare-function mu4e-search "mu4e-search")
+(declare-function mu4e-view-refresh "mu4e-view")
+(declare-function message-add-header "message")
+(declare-function org-msg-edit-mode "org-msg")
+(declare-function no-auto-fill "mail-config")
+(declare-function cj/disable-company-in-mu4e-compose "mail-config")
+(declare-function cj/disable-ispell-in-email-headers "mail-config")
+(declare-function cj/activate-mu4e-org-contacts-integration
+                  "mu4e-org-contacts-integration")
+
+;; Package variables assigned in the lazy `:config' blocks below.
+(defvar mu4e-compose-keep-self-cc)
+(defvar mu4e-root-maildir)
+(defvar mu4e-show-images)
+(defvar org-msg-extra-css)
+
 ;; Refile (archive) target dispatch.  A per-context `mu4e-refile-folder' string
 ;; is unsafe: mu4e context :vars are sticky, so a value set when one context is
 ;; active leaks into a later context that doesn't set its own -- archiving one
@@ -197,12 +222,16 @@ Prompts user for the action when executing."
 
   ;; (setq mu4e-compose-format-flowed t)                                       ;; plain text mails must flow correctly for recipients
   (setq mu4e-compose-keep-self-cc t)                                      ;; keep me in the cc list
-  (setq mu4e-compose-signature-auto-include nil)                          ;; don't include signature by default
+  (with-suppressed-warnings ((obsolete mu4e-compose-signature-auto-include)
+                             (free-vars mu4e-compose-signature-auto-include))
+    (setq mu4e-compose-signature-auto-include nil))                       ;; don't include signature by default
   (setq mu4e-confirm-quit nil)                                            ;; don't ask when quitting
   (setq mu4e-context-policy 'pick-first)                                  ;; start with the first (default) context
   (setq mu4e-headers-auto-update nil)                                     ;; updating headers buffer on email is too jarring
   (setq mu4e-root-maildir mail-dir)                                       ;; root directory for all email accounts
-  (setq mu4e-maildir mail-dir)                                            ;; same as above (for newer mu4e)
+  (with-suppressed-warnings ((obsolete mu4e-maildir)
+                             (free-vars mu4e-maildir))
+    (setq mu4e-maildir mail-dir))                                         ;; same as above (for newer mu4e)
   (setq mu4e-sent-messages-behavior 'delete)                              ;; don't save to "Sent", IMAP does this already
   (setq mu4e-show-images t)                                               ;; show embedded images
   ;; (setq mu4e-update-interval 600)                                      ;; check for new mail every 10 minutes (600 seconds)
@@ -214,12 +243,16 @@ Prompts user for the action when executing."
   ;; This will be automatically disabled when org-msg is active
   (setq mu4e-compose-format-flowed t)
 
-  (setq mu4e-html2text-command 'mu4e-shr2text)  ;; email conversion to html via shr2text
+  (with-suppressed-warnings ((obsolete mu4e-html2text-command)
+                             (free-vars mu4e-html2text-command))
+    (setq mu4e-html2text-command 'mu4e-shr2text))  ;; email conversion to html via shr2text
   (setq mu4e-mu-binary (executable-find "mu"))
   (setq mu4e-get-mail-command (cj/mail--mbsync-command))                  ;; command to sync mail
-  (setq mu4e-user-mail-address-list '("c@cjennings.net"
-                                      "craigmartinjennings@gmail.com"
-                                      "craig.jennings@deepsat.com"))
+  (with-suppressed-warnings ((obsolete mu4e-user-mail-address-list)
+                             (free-vars mu4e-user-mail-address-list))
+    (setq mu4e-user-mail-address-list '("c@cjennings.net"
+                                        "craigmartinjennings@gmail.com"
+                                        "craig.jennings@deepsat.com")))
   (setq mu4e-index-update-error-warning nil) ;; don't warn me about spurious sync issues
 
   ;; ------------------------------ Mu4e Contexts ------------------------------
@@ -295,7 +328,7 @@ Prompts user for the action when executing."
                  :key ?d)))
 
   (defun no-auto-fill ()
-    "Turn off \'auto-fill-mode\'."
+    "Turn off `auto-fill-mode'."
     (auto-fill-mode -1))
   (add-hook 'mu4e-compose-mode-hook #'no-auto-fill)
 
@@ -317,19 +350,23 @@ Prompts user for the action when executing."
   ;; also see org-msg below
 
   ;; Prefer HTML over plain text when both are available
-  (setq mu4e-view-prefer-html t)
+  (with-suppressed-warnings ((obsolete mu4e-view-prefer-html)
+                             (free-vars mu4e-view-prefer-html))
+    (setq mu4e-view-prefer-html t))
 
   ;; Use a better HTML renderer with more control
-  (setq mu4e-html2text-command
-		(cond
-		 ;; Best option: pandoc (if available)
-		 ((executable-find "pandoc")
-		  "pandoc -f html -t plain --reference-links")
-		 ;; Good option: w3m (better tables/formatting)
-		 ((executable-find "w3m")
-		  "w3m -dump -T text/html -cols 72 -o display_link_number=true")
-		 ;; Fallback: built-in shr
-		 (t 'mu4e-shr2text)))
+  (with-suppressed-warnings ((obsolete mu4e-html2text-command)
+                             (free-vars mu4e-html2text-command))
+    (setq mu4e-html2text-command
+		  (cond
+		   ;; Best option: pandoc (if available)
+		   ((executable-find "pandoc")
+		    "pandoc -f html -t plain --reference-links")
+		   ;; Good option: w3m (better tables/formatting)
+		   ((executable-find "w3m")
+		    "w3m -dump -T text/html -cols 72 -o display_link_number=true")
+		   ;; Fallback: built-in shr
+		   (t 'mu4e-shr2text))))
 
   ;; Configure shr (built-in HTML renderer) for better display
   (setq shr-use-colors nil)          ; Don't use colors in terminal
@@ -339,8 +376,10 @@ Prompts user for the action when executing."
   (setq shr-bullet "• ")             ; Nice bullet points
 
   ;; Block remote images by default (privacy/security)
-  (setq mu4e-view-show-images t)
-  (setq mu4e-view-image-max-width 800)
+  (with-suppressed-warnings ((obsolete mu4e-view-show-images mu4e-view-image-max-width)
+                             (free-vars mu4e-view-show-images mu4e-view-image-max-width))
+    (setq mu4e-view-show-images t)
+    (setq mu4e-view-image-max-width 800))
 
   ;; ------------------------------- View Actions ------------------------------
   ;; define view and article menus
diff --git a/tests/test-erc-config-connected-servers.el b/tests/test-erc-config-connected-servers.el
index 7d4540d68..394367c3e 100644
--- a/tests/test-erc-config-connected-servers.el
+++ b/tests/test-erc-config-connected-servers.el
@@ -5,8 +5,9 @@
 ;; process.  The original test compared a buffer's own erc-server-process to the
 ;; same buffer-local value inside `with-current-buffer', which is always true, so
 ;; it returned every ERC buffer (channels, queries, dead connections).  These
-;; tests stub `erc-buffer-list' and the two ERC predicates so the classification
-;; is exercised without a real IRC connection.
+;; tests stub `erc-buffer-list' and the two ERC predicates
+;; (`erc-server-or-unjoined-channel-buffer-p' and `erc-server-process-alive')
+;; so the classification is exercised without a real IRC connection.
 
 ;;; Code:
 
@@ -25,7 +26,7 @@ returned; a channel buffer and a dead-connection server buffer are excluded."
     (unwind-protect
         (cl-letf (((symbol-function 'erc-buffer-list)
                    (lambda (&rest _) (list b-server b-channel b-dead)))
-                  ((symbol-function 'erc-server-buffer-p)
+                  ((symbol-function 'erc-server-or-unjoined-channel-buffer-p)
                    (lambda (&rest _) (memq (current-buffer) (list b-server b-dead))))
                   ((symbol-function 'erc-server-process-alive)
                    (lambda (&rest _) (eq (current-buffer) b-server))))
@@ -39,7 +40,7 @@ returned; a channel buffer and a dead-connection server buffer are excluded."
     (unwind-protect
         (cl-letf (((symbol-function 'erc-buffer-list)
                    (lambda (&rest _) (list b-channel)))
-                  ((symbol-function 'erc-server-buffer-p) (lambda (&rest _) nil))
+                  ((symbol-function 'erc-server-or-unjoined-channel-buffer-p) (lambda (&rest _) nil))
                   ((symbol-function 'erc-server-process-alive) (lambda (&rest _) nil)))
           (should (null (cj/erc-connected-servers))))
       (kill-buffer b-channel))))