summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-05-24 16:26:06 -0500
committerCraig Jennings <c@cjennings.net>2026-05-24 16:26:06 -0500
commit67d8040ad19461cf2a393af95268f92b784d7ece (patch)
tree3f5898216a5af91f78366bbd94b9496b7e532ee1
parent504a87abe8baf70b2734988ff23f2c5e48b2f77e (diff)
downloaddotemacs-67d8040ad19461cf2a393af95268f92b784d7ece.tar.gz
dotemacs-67d8040ad19461cf2a393af95268f92b784d7ece.zip
docs(load-graph): classify core libraries and command modules
Third classification batch: the remaining core and library command modules from init.el's early block — external-open, media-utils, auth-config, keyboard-macros, system-utils, text-config, undead-buffers. I annotated each with the load-graph header contract, added a Batch 3 table to the inventory, and extended the validation allowlist. 23 of 102 modules are now classified. No new hidden dependencies in this batch. auth-config stays eager because other modules need credentials early; the command libraries (external-open, media-utils, keyboard-macros) are eager only by init order and flagged as Phase 4 deferral candidates.
-rw-r--r--docs/design/module-inventory.org27
-rw-r--r--modules/auth-config.el9
-rw-r--r--modules/external-open.el9
-rw-r--r--modules/keyboard-macros.el9
-rw-r--r--modules/media-utils.el9
-rw-r--r--modules/system-utils.el10
-rw-r--r--modules/text-config.el9
-rw-r--r--modules/undead-buffers.el10
-rw-r--r--tests/test-init-module-headers.el10
9 files changed, 92 insertions, 10 deletions
diff --git a/docs/design/module-inventory.org b/docs/design/module-inventory.org
index f7657951..f5a5294a 100644
--- a/docs/design/module-inventory.org
+++ b/docs/design/module-inventory.org
@@ -25,7 +25,8 @@ This inventory is independent from the helper inventory owned by
- Phase 1 (Inventory and Contracts), in progress.
- Batch 1 (Foundation, Layer 1): classified. 7 modules.
- Batch 2 (Text/editing command modules, Layer 2): classified. 9 modules.
-- 16 of 102 modules classified.
+- Batch 3 (Core libraries and command modules): classified. 7 modules.
+- 23 of 102 modules classified.
- No load-order changes have been made; =init.el= keeps its current eager order.
* Legend
@@ -82,6 +83,21 @@ are deferral candidates for Phase 3 (registration API) and Phase 4
| =custom-text-enclose= | 2 | L/C | eager | command | keybindings (change-inner on demand) | cj/enclose-map under C-; s | yes |
| =custom-whitespace= | 2 | L/C | eager | command | keybindings | cj/whitespace-map under C-; w | yes |
+** Batch 3 — Core libraries and command modules
+
+The remainder of init.el's early/core block: shared command libraries and a few
+eager side-effect owners.
+
+| Module | Layer | Cat | Current | Target | Runtime requires | Top-level side effects | Direct load |
+|--------+-------+-----+---------+--------+------------------+------------------------+-------------|
+| =external-open= | 2 | L/D | eager | command | host-environment, system-lib, external-open-lib, cl-lib | none | yes |
+| =media-utils= | 3 | D/L | eager | command | system-lib | none | yes |
+| =auth-config= | 1 | F/D | eager | eager | system-lib, user-constants | auth-source/epa config | yes |
+| =keyboard-macros= | 2 | C/L | eager | command | subr-x, user-constants | none | yes |
+| =system-utils= | 2 | L/C/S | eager | eager | system-lib, external-open-lib | 3 global keys, 1 startup hook | yes |
+| =text-config= | 2 | C/P | eager | eager | none | 3 add-hook, package config | yes |
+| =undead-buffers= | 2 | C | eager | eager | none | 3 global keys (kill-buffer remap) | yes |
+
* Hidden dependencies found
Discoveries that belong to Phase 2 (make dependencies explicit). Recorded here,
@@ -104,7 +120,7 @@ not fixed here.
* Pending classification
-The remaining 86 modules required by =init.el=, awaiting per-module inspection.
+The remaining 79 modules required by =init.el=, awaiting per-module inspection.
Each batch reads these against their source and moves them into [[*Classified
modules][Classified modules]] with a load-graph header. Suggested batch order
follows the spec: text/editing command modules, then UI, then programming, then
@@ -112,7 +128,6 @@ Org, then optional integrations.
- [ ] ai-config
- [ ] ai-vterm
-- [ ] auth-config
- [ ] browser-config
- [ ] calendar-sync
- [ ] calibredb-epub-config
@@ -128,7 +143,6 @@ Org, then optional integrations.
- [ ] erc-config
- [ ] eshell-config
- [ ] eww-config
-- [ ] external-open
- [ ] flycheck-config
- [ ] flyspell-and-abbrev
- [ ] font-config
@@ -139,14 +153,12 @@ Org, then optional integrations.
- [ ] httpd-config
- [ ] hugo-config
- [ ] jumper
-- [ ] keyboard-macros
- [ ] latex-config
- [ ] linear-config
- [ ] local-repository
- [ ] lorem-optimum
- [ ] mail-config
- [ ] markdown-config
-- [ ] media-utils
- [ ] modeline-config
- [ ] mousetrap-mode
- [ ] music-config
@@ -181,16 +193,13 @@ Org, then optional integrations.
- [ ] selection-framework
- [ ] slack-config
- [ ] system-commands
-- [ ] system-utils
- [ ] telega-config
- [ ] test-runner
-- [ ] text-config
- [ ] tramp-config
- [ ] transcription-config
- [ ] ui-config
- [ ] ui-navigation
- [ ] ui-theme
-- [ ] undead-buffers
- [ ] vc-config
- [ ] video-audio-recording
- [ ] vterm-config
diff --git a/modules/auth-config.el b/modules/auth-config.el
index 02fc7858..7f729f02 100644
--- a/modules/auth-config.el
+++ b/modules/auth-config.el
@@ -3,6 +3,15 @@
;;; Commentary:
;;
+;; Layer: 1 (Foundation).
+;; Category: F/D.
+;; Load shape: eager.
+;; Eager reason: auth-source and GPG/epa setup that other modules rely on for
+;; credentials early in the session.
+;; Top-level side effects: auth-source/epa configuration via use-package and setq.
+;; Runtime requires: system-lib, user-constants.
+;; Direct test load: yes (configuration only).
+;;
;; Configuration for Emacs authentication and GPG integration:
;; • auth-source
diff --git a/modules/external-open.el b/modules/external-open.el
index 57cffadc..22e56a29 100644
--- a/modules/external-open.el
+++ b/modules/external-open.el
@@ -3,6 +3,15 @@
;;
;;; Commentary:
;;
+;; Layer: 2 (Core UX).
+;; Category: L/D.
+;; Load shape: eager.
+;; Eager reason: command library with no side effects; eager only by init order.
+;; A deferral candidate (autoload commands) for Phase 4.
+;; Top-level side effects: none.
+;; Runtime requires: host-environment, system-lib, external-open-lib, cl-lib.
+;; Direct test load: yes (pure command helpers).
+;;
;; This library provides a simple mechanism for opening files with specific
;; extensions using your operating system’s default application rather than
;; visiting them in an Emacs buffer. It offers:
diff --git a/modules/keyboard-macros.el b/modules/keyboard-macros.el
index 5cd89f21..4e801096 100644
--- a/modules/keyboard-macros.el
+++ b/modules/keyboard-macros.el
@@ -3,6 +3,15 @@
;;; Commentary:
;;
+;; Layer: 2 (Core UX).
+;; Category: C/L.
+;; Load shape: eager.
+;; Eager reason: lightweight keyboard-macro commands; eager only by init order.
+;; A deferral candidate (autoload commands) for Phase 4.
+;; Top-level side effects: none.
+;; Runtime requires: subr-x, user-constants.
+;; Direct test load: yes.
+;;
;; This library provides a simple, end-user–focused interface for
;; creating, naming, saving, and replaying keyboard macros in Emacs.
;; All commands are built on top of the built-in =kmacro= machinery, but
diff --git a/modules/media-utils.el b/modules/media-utils.el
index db66a71f..685530d8 100644
--- a/modules/media-utils.el
+++ b/modules/media-utils.el
@@ -2,6 +2,15 @@
;;
;;; Commentary:
;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/L.
+;; Load shape: eager.
+;; Eager reason: command library with no side effects; eager only by init order.
+;; Downloads and players should run by command, so a Phase 4 deferral candidate.
+;; Top-level side effects: none.
+;; Runtime requires: system-lib.
+;; Direct test load: yes (pure command helpers).
+;;
;; This library provides reusable Emacs methods for working with online and
;; local media, to support media download and playback from Emacs.
;;
diff --git a/modules/system-utils.el b/modules/system-utils.el
index 43200403..7cf95867 100644
--- a/modules/system-utils.el
+++ b/modules/system-utils.el
@@ -3,6 +3,16 @@
;;
;;; Commentary:
;;
+;; Layer: 2 (Core UX).
+;; Category: L/C/S.
+;; Load shape: eager.
+;; Eager reason: registers global keys (C-c b, C-<f10>, list-buffers remap) and
+;; a startup hook for its enhanced commands.
+;; Top-level side effects: three keymap-global-set, one emacs-startup-hook, plus
+;; use-package configuration.
+;; Runtime requires: system-lib, external-open-lib.
+;; Direct test load: yes.
+;;
;; A "system-util" is an enhancement to common a Emacs command, or the extension
;; of an existing command. Perhaps this group can be better named.
;;
diff --git a/modules/text-config.el b/modules/text-config.el
index 4e9208bc..5a946d52 100644
--- a/modules/text-config.el
+++ b/modules/text-config.el
@@ -3,6 +3,15 @@
;;; Commentary:
;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: general text-editing defaults and mode hooks the first session
+;; relies on.
+;; Top-level side effects: three add-hook plus use-package package configuration.
+;; Runtime requires: none (configures packages via use-package).
+;; Direct test load: yes.
+;;
;; Configuration for text editing features including:
;; - Basic text mode settings (visual line mode, indentation, spacing)
;; - Text manipulation (move-text, expand-region, change-inner)
diff --git a/modules/undead-buffers.el b/modules/undead-buffers.el
index c85bde94..fe43575e 100644
--- a/modules/undead-buffers.el
+++ b/modules/undead-buffers.el
@@ -2,6 +2,16 @@
;;; Commentary:
;;
+;; Layer: 2 (Core UX).
+;; Category: C.
+;; Load shape: eager.
+;; Eager reason: global kill-buffer remap and window-kill bindings wanted from
+;; the first session.
+;; Top-level side effects: three keymap-global-set (remaps kill-buffer; binds
+;; M-S-o, M-S-m).
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
;; This library allows for "burying" selected buffers instead of killing them.
;; Since they won't be killed, I'm calling them "undead buffers".
;; The main function cj/kill-buffer-or-bury-alive replaces kill-buffer.
diff --git a/tests/test-init-module-headers.el b/tests/test-init-module-headers.el
index 86b083ae..f8085fc7 100644
--- a/tests/test-init-module-headers.el
+++ b/tests/test-init-module-headers.el
@@ -38,7 +38,15 @@
"custom-misc"
"custom-ordering"
"custom-text-enclose"
- "custom-whitespace")
+ "custom-whitespace"
+ ;; Batch 3 — Core libraries and command modules (Layer 1-3)
+ "external-open"
+ "media-utils"
+ "auth-config"
+ "keyboard-macros"
+ "system-utils"
+ "text-config"
+ "undead-buffers")
"Modules annotated with the load-graph header contract.
Grows one batch at a time. Parity with the init.el require set is the
Phase 1 exit criterion.")