From bb4def1a5c3adb157d699ebb932d0de34fecd66d Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Wed, 29 Oct 2025 09:38:53 -0500
Subject: feat: add debug infrastructure for config modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit establishes a pattern for organizing debug code in separate
files that can be enabled/disabled via a central toggle.

## Changes

**1. Added debug toggle to user-constants.el**

New variable `cj/debug-modules` controls which modules load debug functions:
- Set to nil (default): No debug functions loaded
- Set to list of symbols: Load debug for specific modules
  Example: (setq cj/debug-modules '(org-agenda mail))
- Set to t: Load all debug modules
  Example: (setq cj/debug-modules t)

Placed early in user-constants.el so it's available before other modules load.

**2. Created org-agenda-config-debug.el**

New debug file contains:
- `cj/org-agenda-debug-dump-files` - Shows all org-agenda-files with status,
  file sizes, and modification times
- `cj/org-agenda-debug-rebuild-timing` - Measures rebuild performance and
  reports detailed timing statistics
- `cj/log-silently` - Helper function to write to *Messages* without echo

All functions use ;;;###autoload for easy invocation before explicit loading.

**3. Added conditional require to org-agenda-config.el**

Checks `cj/debug-modules` and conditionally loads org-agenda-config-debug.el:
```elisp
(when (or (eq cj/debug-modules t)
          (memq 'org-agenda cj/debug-modules))
  (require 'org-agenda-config-debug ...))
```

## Benefits

**Cleaner separation of concerns:**
- Production code stays in main config files
- Debug code isolated in *-debug.el files
- Easy to enable/disable debugging per module

**Reusable pattern:**
- Can be applied to any config module (mail, chime, etc.)
- Consistent naming: <module>-debug.el
- Consistent namespace: cj/<module>-debug-*

**Zero overhead when disabled:**
- Debug files not loaded unless explicitly enabled
- No performance impact on normal usage

## Usage

To enable org-agenda debug functions:
```elisp
;; In user-constants.el or early-init.el
(setq cj/debug-modules '(org-agenda))
```

Then restart Emacs and run:
- M-x cj/org-agenda-debug-dump-files
- M-x cj/org-agenda-debug-rebuild-timing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 modules/user-constants.el | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'modules/user-constants.el')

diff --git a/modules/user-constants.el b/modules/user-constants.el
index 59129697..bcb34bcc 100644
--- a/modules/user-constants.el
+++ b/modules/user-constants.el
@@ -20,6 +20,15 @@
 ;;
 ;;; Code:
 
+;; -------------------------------- Debug Toggle -------------------------------
+
+(defvar cj/debug-modules nil
+  "List of modules with debug functions enabled.
+Possible values: org-agenda, mail, chime, etc.
+Set to t to enable all debug modules.
+Example: (setq cj/debug-modules '(org-agenda mail))
+         (setq cj/debug-modules t)  ; Enable all")
+
 ;; -------------------------------- Contact Info -------------------------------
 
 (defvar user-whole-name "Craig Jennings"
-- 
cgit v1.2.3