refactor: normalize module package headers and enforce them

The first-line header on 33 modules named the file without its .el extension (;;; font-config --- ... rather than ;;; font-config.el --- ...), the form checkdoc and package-lint expect and the other modules already use. I normalized all 33 to the canonical ;;; name.el --- summary shape. The change is line 1 only.

A new test, test-meta-package-headers.el, locks the convention. It checks every module for the canonical first line, Commentary before Code, a provide footer, and no BOM, and unit-tests the checker against each malformed shape so the guard itself is proven.

34 files changed, 131 insertions, 33 deletions

diff --git a/modules/calibredb-epub-config.el b/modules/calibredb-epub-config.el
index 38aa0de05..a8b131be8 100644
--- a/modules/calibredb-epub-config.el
+++ b/modules/calibredb-epub-config.el
@@ -1,4 +1,4 @@
-;;; calibredb-epub-config --- Functionality for Ebook Management and Display -*- lexical-binding: t; coding: utf-8; -*-
+;;; calibredb-epub-config.el --- Functionality for Ebook Management and Display -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/config-utilities.el b/modules/config-utilities.el
index 0c98a896c..72427ef9b 100644
--- a/modules/config-utilities.el
+++ b/modules/config-utilities.el
@@ -1,4 +1,4 @@
-;;; config-utilities  --- Config Hacking Utilities -*- lexical-binding: t; coding: utf-8; -*-
+;;; config-utilities.el --- Config Hacking Utilities -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/elfeed-config.el b/modules/elfeed-config.el
index e5cbb36c0..dbc7e4a4b 100644
--- a/modules/elfeed-config.el
+++ b/modules/elfeed-config.el
@@ -1,4 +1,4 @@
-;;; elfeed-config --- Settings and Enhancements to the Elfeed RSS Feed Reader -*- lexical-binding: t; coding: utf-8; -*-
+;;; elfeed-config.el --- Settings and Enhancements to the Elfeed RSS Feed Reader -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/erc-config.el b/modules/erc-config.el
index 4eac812c4..57d4eb567 100644
--- a/modules/erc-config.el
+++ b/modules/erc-config.el
@@ -1,4 +1,4 @@
-;;; erc-config --- Preferences for Emacs Relay Chat (IRC Client) -*- lexical-binding: t; coding: utf-8; -*-
+;;; erc-config.el --- Preferences for Emacs Relay Chat (IRC Client) -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/eww-config.el b/modules/eww-config.el
index 3b0e22dcd..0ddebfe4f 100644
--- a/modules/eww-config.el
+++ b/modules/eww-config.el
@@ -1,4 +1,4 @@
-;;; eww-config --- EWW Text Browser Settings -*- lexical-binding: t; coding: utf-8; -*-
+;;; eww-config.el --- EWW Text Browser Settings -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/flycheck-config.el b/modules/flycheck-config.el
index 613817444..2a5a5e74f 100644
--- a/modules/flycheck-config.el
+++ b/modules/flycheck-config.el
@@ -1,4 +1,4 @@
-;;; flycheck-config --- Syntax/Grammar Check -*- lexical-binding: t; coding: utf-8; -*-
+;;; flycheck-config.el --- Syntax/Grammar Check -*- lexical-binding: t; coding: utf-8; -*-
 ;;  author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/font-config.el b/modules/font-config.el
index f00b8bf16..2be051ddc 100644
--- a/modules/font-config.el
+++ b/modules/font-config.el
@@ -1,4 +1,4 @@
-;;; font-config --- Font Defaults and Related Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; font-config.el --- Font Defaults and Related Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/help-config.el b/modules/help-config.el
index f8431aef2..4858abcf2 100644
--- a/modules/help-config.el
+++ b/modules/help-config.el
@@ -1,4 +1,4 @@
-;;; help-config --- Help Functionality Configuration -*- lexical-binding: t; coding: utf-8; -*-
+;;; help-config.el --- Help Functionality Configuration -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/help-utils.el b/modules/help-utils.el
index 3e31efffe..9792841a3 100644
--- a/modules/help-utils.el
+++ b/modules/help-utils.el
@@ -1,4 +1,4 @@
-;;; help-utils --- Help Integrations and Searches -*- lexical-binding: t; coding: utf-8; -*-
+;;; help-utils.el --- Help Integrations and Searches -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/httpd-config.el b/modules/httpd-config.el
index 60baf7e82..1a2a5c611 100644
--- a/modules/httpd-config.el
+++ b/modules/httpd-config.el
@@ -1,4 +1,4 @@
-;;; httpd-config --- Setup for a Simple HTTP Server -*- lexical-binding: t; coding: utf-8; -*-
+;;; httpd-config.el --- Setup for a Simple HTTP Server -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/keybindings.el b/modules/keybindings.el
index b61c3f2b3..7072cb9c2 100644
--- a/modules/keybindings.el
+++ b/modules/keybindings.el
@@ -1,4 +1,4 @@
-;;; keybindings --- General Keyboard Shortcuts -*- lexical-binding: t; coding: utf-8; -*-
+;;; keybindings.el --- General Keyboard Shortcuts -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/latex-config.el b/modules/latex-config.el
index f2a586704..2cc19171e 100644
--- a/modules/latex-config.el
+++ b/modules/latex-config.el
@@ -1,4 +1,4 @@
-;;; latex-config --- Setup for LaTeX and Related Software -*- lexical-binding: t; coding: utf-8; -*-
+;;; latex-config.el --- Setup for LaTeX and Related Software -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/mail-config.el b/modules/mail-config.el
index 1d8a98c97..84d5f029a 100644
--- a/modules/mail-config.el
+++ b/modules/mail-config.el
@@ -1,4 +1,4 @@
-;;; mail-config --- Settings for Mu4e Email -*- lexical-binding: t; coding: utf-8; -*-
+;;; mail-config.el --- Settings for Mu4e Email -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/markdown-config.el b/modules/markdown-config.el
index 424c09cc8..4b6c9947d 100644
--- a/modules/markdown-config.el
+++ b/modules/markdown-config.el
@@ -1,4 +1,4 @@
-;;; markdown-config --- Settings for Editing Markdown -*- lexical-binding: t; coding: utf-8; -*-
+;;; markdown-config.el --- Settings for Editing Markdown -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/modeline-config.el b/modules/modeline-config.el
index 61dcb69c6..2793cfae5 100644
--- a/modules/modeline-config.el
+++ b/modules/modeline-config.el
@@ -1,4 +1,4 @@
-;;; modeline-config --- Modeline Settings -*- lexical-binding: t; coding: utf-8; -*-
+;;; modeline-config.el --- Modeline Settings -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/org-agenda-config.el b/modules/org-agenda-config.el
index 9ccd21d7b..51f269090 100644
--- a/modules/org-agenda-config.el
+++ b/modules/org-agenda-config.el
@@ -1,4 +1,4 @@
-;;; org-agenda-config --- Org-Agenda/Todo Config -*- lexical-binding: t; coding: utf-8; -*-
+;;; org-agenda-config.el --- Org-Agenda/Todo Config -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/org-config.el b/modules/org-config.el
index f316ee0df..6f25752f4 100644
--- a/modules/org-config.el
+++ b/modules/org-config.el
@@ -1,4 +1,4 @@
-;;; org-config --- Settings and Enhancements to Org Mode -*- lexical-binding: t; coding: utf-8; -*-
+;;; org-config.el --- Settings and Enhancements to Org Mode -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;; Commentary:
 ;;
diff --git a/modules/pdf-config.el b/modules/pdf-config.el
index 56b397df3..a5dc3c490 100644
--- a/modules/pdf-config.el
+++ b/modules/pdf-config.el
@@ -1,4 +1,4 @@
-;;; pdf-config --- PDF Viewer Setup -*- lexical-binding: t; coding: utf-8; -*-
+;;; pdf-config.el --- PDF Viewer Setup -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-c.el b/modules/prog-c.el
index 294375cb4..728df0181 100644
--- a/modules/prog-c.el
+++ b/modules/prog-c.el
@@ -1,4 +1,4 @@
-;;; prog-c --- C Programming Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-c.el --- C Programming Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-general.el b/modules/prog-general.el
index f22f89923..15bf40c41 100644
--- a/modules/prog-general.el
+++ b/modules/prog-general.el
@@ -1,4 +1,4 @@
-;;; prog-general --- General Programming Settings -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-general.el --- General Programming Settings -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-go.el b/modules/prog-go.el
index 4b09f29c3..7faf92a08 100644
--- a/modules/prog-go.el
+++ b/modules/prog-go.el
@@ -1,4 +1,4 @@
-;;; prog-go --- Golang Specific Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-go.el --- Golang Specific Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-lisp.el b/modules/prog-lisp.el
index 30c04ad7e..ba568c9c6 100644
--- a/modules/prog-lisp.el
+++ b/modules/prog-lisp.el
@@ -1,4 +1,4 @@
-;;; prog-lisp --- Lisp Specific Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-lisp.el --- Lisp Specific Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-lsp.el b/modules/prog-lsp.el
index 045dda248..1c74bcc10 100644
--- a/modules/prog-lsp.el
+++ b/modules/prog-lsp.el
@@ -1,4 +1,4 @@
-;;; prog-lsp --- Setup for LSP Mode -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-lsp.el --- Setup for LSP Mode -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-python.el b/modules/prog-python.el
index d8556c4d7..6354bd90c 100644
--- a/modules/prog-python.el
+++ b/modules/prog-python.el
@@ -1,4 +1,4 @@
-;;; prog-python --- Python Specific Setup and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-python.el --- Python Specific Setup and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-shell.el b/modules/prog-shell.el
index 45c0afbca..d7f97932b 100644
--- a/modules/prog-shell.el
+++ b/modules/prog-shell.el
@@ -1,4 +1,4 @@
-;;; prog-shell --- Shell Programming Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-shell.el --- Shell Programming Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/prog-yaml.el b/modules/prog-yaml.el
index e07cf510e..71f358c7f 100644
--- a/modules/prog-yaml.el
+++ b/modules/prog-yaml.el
@@ -1,4 +1,4 @@
-;;; prog-yaml --- YAML Settings -*- lexical-binding: t; coding: utf-8; -*-
+;;; prog-yaml.el --- YAML Settings -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/show-kill-ring.el b/modules/show-kill-ring.el
index a6c59e26c..e65d48b5f 100644
--- a/modules/show-kill-ring.el
+++ b/modules/show-kill-ring.el
@@ -1,4 +1,4 @@
-;;; show-kill-ring --- Displays Previous Kill Ring Entries -*- lexical-binding: t; coding: utf-8; -*-
+;;; show-kill-ring.el --- Displays Previous Kill Ring Entries -*- lexical-binding: t; coding: utf-8; -*-
 ;; Show Kill Ring
 ;; Stolen from Steve Yegge when he wasn't looking
 ;; enhancements and bugs added by Craig Jennings <c@cjennings.net>
diff --git a/modules/system-defaults.el b/modules/system-defaults.el
index 6d9c811a6..7230103cc 100644
--- a/modules/system-defaults.el
+++ b/modules/system-defaults.el
@@ -1,4 +1,4 @@
-;;; system-defaults --- Non-UI Preferences -*- lexical-binding: t; coding: utf-8-unix; -*-
+;;; system-defaults.el --- Non-UI Preferences -*- lexical-binding: t; coding: utf-8-unix; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/system-utils.el b/modules/system-utils.el
index b393aa33f..e779026a0 100644
--- a/modules/system-utils.el
+++ b/modules/system-utils.el
@@ -1,4 +1,4 @@
-;;; system-utils --- System-Wide Utilities -*- lexical-binding: t; coding: utf-8; -*-
+;;; system-utils.el --- System-Wide Utilities -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
diff --git a/modules/text-config.el b/modules/text-config.el
index 14e06f3e8..dd7bd3cac 100644
--- a/modules/text-config.el
+++ b/modules/text-config.el
@@ -1,4 +1,4 @@
-;;; text-config --- Text Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; text-config.el --- Text Settings and Functionality -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/ui-config.el b/modules/ui-config.el
index 32bd393f5..fbc3d91c1 100644
--- a/modules/ui-config.el
+++ b/modules/ui-config.el
@@ -1,4 +1,4 @@
-;;; ui-config --- User Interface Preferences -*- lexical-binding: t; coding: utf-8; -*-
+;;; ui-config.el --- User Interface Preferences -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/ui-navigation.el b/modules/ui-navigation.el
index 76dd686a6..7ec56e078 100644
--- a/modules/ui-navigation.el
+++ b/modules/ui-navigation.el
@@ -1,4 +1,4 @@
-;;; ui-navigation --- Managing Cursor Placement, Buffers, and Windows -*- lexical-binding: t; coding: utf-8; -*-
+;;; ui-navigation.el --- Managing Cursor Placement, Buffers, and Windows -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/modules/wrap-up.el b/modules/wrap-up.el
index 503d4a6b0..e28ba8458 100644
--- a/modules/wrap-up.el
+++ b/modules/wrap-up.el
@@ -1,4 +1,4 @@
-;;; wrapup --- Functions Run Before Init Completion -*- lexical-binding: t; coding: utf-8; -*-
+;;; wrap-up.el --- Functions Run Before Init Completion -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
diff --git a/tests/test-meta-package-headers.el b/tests/test-meta-package-headers.el
new file mode 100644
index 000000000..f9b57cbfc
--- /dev/null
+++ b/tests/test-meta-package-headers.el
@@ -0,0 +1,98 @@
+;;; test-meta-package-headers.el --- Enforce Elisp package-header conventions -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Checks that every owned active config module follows the standard Emacs
+;; Library Header conventions -- the part test-init-module-headers.el does not
+;; cover (it enforces the load-graph metadata block inside the Commentary):
+;;
+;;   1. First line is  ;;; NAME.el --- SUMMARY -*- ... -*-  (name carries the
+;;      .el, summary present, file-local-variable cookie present).
+;;   2. ;;; Commentary: appears before ;;; Code:.
+;;   3. A (provide 'NAME) footer, so the file is require-able.
+;;   4. No UTF-8 BOM before the header.
+;;
+;; Scope is modules/*.el, the owned active module set.  Vendored (custom/),
+;; generated (themes/, browser-choice.el), archived (archive/), and private
+;; (*.local.el) files are out of scope by design -- classifying those is the
+;; file-class policy task, not this test.  The checker reads files on disk
+;; without loading them, so it adds no startup or package dependency.
+
+;;; Code:
+
+(require 'ert)
+
+(defconst test-pkg-header--exempt '()
+  "Basenames under modules/ exempt from the package-header checks.
+Empty today.  Add a basename with a comment when a module is intentionally
+shaped differently, so the exemption is explicit rather than silent.")
+
+(defun test-pkg-header--check (name text)
+  "Return the list of violation symbols for module NAME given file TEXT.
+NAME is the basename (e.g. \"font-config.el\").  An empty list means the
+file is conformant.  Possible symbols: `bom', `header', `markers',
+`order', `provide'."
+  (let ((violations '()))
+    (when (string-prefix-p "" text)
+      (push 'bom violations))
+    (let ((first-line (car (split-string text "\n"))))
+      (unless (string-match-p
+               (concat "\\`;;; " (regexp-quote name) " --- .+-\\*-.*-\\*-")
+               first-line)
+        (push 'header violations)))
+    (let ((commentary (string-match "^;;; Commentary:" text))
+          (code (string-match "^;;; Code:" text)))
+      (cond ((or (null commentary) (null code)) (push 'markers violations))
+            ((>= commentary code) (push 'order violations))))
+    (let ((stem (file-name-sans-extension name)))
+      (unless (string-match-p (concat "^(provide '" (regexp-quote stem) ")") text)
+        (push 'provide violations)))
+    (nreverse violations)))
+
+(ert-deftest test-pkg-header-checker-flags-malformed ()
+  "Error: the checker catches each malformed shape."
+  (should (memq 'bom
+                (test-pkg-header--check
+                 "foo.el"
+                 ";;; foo.el --- x -*- lexical-binding: t; -*-\n;;; Commentary:\n;;; Code:\n(provide 'foo)")))
+  (should (memq 'header
+                (test-pkg-header--check
+                 "foo.el"
+                 ";;; foo --- x -*- lexical-binding: t; -*-\n;;; Commentary:\n;;; Code:\n(provide 'foo)")))
+  (should (memq 'order
+                (test-pkg-header--check
+                 "foo.el"
+                 ";;; foo.el --- x -*- lexical-binding: t; -*-\n;;; Code:\n;;; Commentary:\n(provide 'foo)")))
+  (should (memq 'provide
+                (test-pkg-header--check
+                 "foo.el"
+                 ";;; foo.el --- x -*- lexical-binding: t; -*-\n;;; Commentary:\n;;; Code:\n"))))
+
+(ert-deftest test-pkg-header-checker-passes-conformant ()
+  "Normal: a well-formed module yields no violations."
+  (should-not (test-pkg-header--check
+               "foo.el"
+               ";;; foo.el --- A thing -*- lexical-binding: t; -*-\n;;; Commentary:\n;; doc\n;;; Code:\n(provide 'foo)\n")))
+
+(ert-deftest test-pkg-header-checker-boundary-empty ()
+  "Boundary: empty file text reports every applicable violation, no crash."
+  (let ((v (test-pkg-header--check "foo.el" "")))
+    (should (memq 'header v))
+    (should (memq 'markers v))
+    (should (memq 'provide v))))
+
+(ert-deftest test-pkg-header-all-modules-conform ()
+  "Normal: every modules/*.el passes the package-header checks."
+  (let ((dir (expand-file-name "modules" user-emacs-directory))
+        (bad '()))
+    (dolist (file (directory-files dir t "\\.el\\'"))
+      (let ((name (file-name-nondirectory file)))
+        (unless (member name test-pkg-header--exempt)
+          (let* ((text (with-temp-buffer
+                         (insert-file-contents file)
+                         (buffer-string)))
+                 (violations (test-pkg-header--check name text)))
+            (when violations (push (cons name violations) bad))))))
+    (should-not bad)))
+
+(provide 'test-meta-package-headers)
+;;; test-meta-package-headers.el ends here