[#3973] Add a namespace load-state indicator to the mode line

Surface, right in the `cider-mode` lighter, whether the current buffer's
namespace is actually loaded into the REPL and whether it's still in sync
with what was loaded. The lighter shows ` not-loaded` for a namespace the
runtime doesn't know about and ` stale` once you've edited the buffer since
the last load - the common "why is my change not taking effect" trap.

State is cached buffer-locally and never queried during redisplay, so the
lighter stays cheap. It's refreshed when CIDER loads a file, on demand via
`cider-ns-refresh-load-state`, and once per buffer when you focus it (via a
buffer-local hook installed by `cider-mode`, so unrelated buffers pay
nothing). We deliberately avoid querying at connection time.

Without cider-nrepl the `cider/ns-list` op is absent, so the state simply
stays unknown (the lighter shows nothing) rather than misreporting every
namespace as not loaded.

Author: bbatsov

CHANGELOG.md

@@ -13,6 +13,7 @@
 - [#3976](https://github.com/clojure-emacs/cider/pull/3976): Underline the further-expandable sub-forms while inline macro stepping and move between them with `n`/`p` in `cider-macrostep-mode` (`cider-macrostep-highlight-expandable`).
 - [#3977](https://github.com/clojure-emacs/cider/pull/3977): Colorize the gensyms introduced by an inline macro expansion, each distinct gensym in its own color, so an introduced binding can be tracked (`cider-macrostep-color-gensyms`).
 - [#3978](https://github.com/clojure-emacs/cider/pull/3978): Add `cider-macrostep-expand-all` (`a` in `cider-macrostep-mode`) to fully expand the form at point inline in one step, instead of stepping level by level.
+- [#3973](https://github.com/clojure-emacs/cider/pull/3973): Show a namespace load-state indicator in the `cider-mode` lighter (` not-loaded` / ` stale`), making it obvious when the current buffer's namespace hasn't been loaded into the REPL or has been edited since it was last loaded (`cider-show-ns-load-state`).
 
 ### Bugs fixed
 

lisp/cider-mode.el

@@ -33,6 +33,7 @@
 
 (require 'clojure-mode)
 (require 'cider-eval)
+(require 'cider-ns-state)
 (require 'cider-inspiration)
 (require 'cider-test) ; required only for the menu
 (require 'cider-eldoc)
@@ -71,7 +72,8 @@ Info contains the connection type, project name and host:port endpoint."
 
 ;;;###autoload
 (defcustom cider-mode-line
-  '(:eval (format " cider[%s]" (cider--modeline-info)))
+  '(:eval (concat (format " cider[%s]" (cider--modeline-info))
+                  (cider-ns-state--lighter)))
   "Mode line lighter for cider mode.
 
 The value of this variable is a mode line template as in
@@ -1125,6 +1127,7 @@ property."
       (progn
         (setq-local sesman-system 'CIDER)
         (cider-eldoc-setup)
+        (cider-ns-state-setup)
         (add-hook 'completion-at-point-functions #'cider-complete-at-point nil t)
         (font-lock-add-keywords nil cider--static-font-lock-keywords)
         (cider-refresh-dynamic-font-lock)
@@ -1148,6 +1151,7 @@ property."
         (cider-enable-cider-completion-style 1)
         (setq next-error-function #'cider-jump-to-compilation-error))
     ;; Mode cleanup
+    (cider-ns-state-teardown)
     (mapc #'kill-local-variable '(next-error-function
                                   x-gtk-use-system-tooltips
                                   font-lock-fontify-region-function

lisp/cider-ns-state.el

@@ -0,0 +1,188 @@
+;;; cider-ns-state.el --- Namespace load-state tracking -*- lexical-binding: t -*-
+
+;; Copyright © 2026  Bozhidar Batsov and CIDER contributors
+
+;; Author: Bozhidar Batsov <bozhidar@batsov.dev>
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Track whether a source buffer's namespace has been loaded into the running
+;; REPL, and whether the buffer has been edited since it was last loaded.  The
+;; state is surfaced via the `cider-mode' mode-line lighter, so it's obvious
+;; when you're about to operate on a namespace that the runtime doesn't know
+;; about (or that is out of sync).
+;;
+;; This is intentionally coarse (namespace granularity).  Per-form staleness
+;; (extending the fringe indicators) is a separate, future effort.
+
+;;; Code:
+
+(require 'subr-x)
+
+(require 'cider-client)
+(require 'cider-eval)
+(require 'nrepl-dict)
+
+(defcustom cider-show-ns-load-state t
+  "Whether to show the namespace load-state in the `cider-mode' lighter.
+When non-nil, a marker appears in the mode line when the current buffer's
+namespace has not been loaded into the REPL, or has been edited since it was
+last loaded."
+  :type 'boolean
+  :group 'cider
+  :package-version '(cider . "1.23.0"))
+
+(defface cider-ns-load-state-face
+  '((t :inherit warning))
+  "Face for the namespace load-state marker in the mode line."
+  :group 'cider
+  :package-version '(cider . "1.23.0"))
+
+(defvar-local cider-ns-state--loaded nil
+  "Cached load state of the current buffer's namespace.
+One of nil (unknown / not checked yet), t (loaded), or the symbol
+`not-loaded'.  Updated asynchronously by `cider-ns-state--refresh' and
+on `cider-file-loaded-hook'.")
+
+(defvar-local cider-ns-state--loaded-tick nil
+  "Value of `buffer-chars-modified-tick' when the buffer was last loaded.
+Used to detect that the buffer has been edited since (out of sync).  Only set
+when CIDER itself loaded the buffer, since otherwise there is no reliable sync
+baseline.")
+
+(defun cider-ns-load-state ()
+  "Return the load/sync state of the current buffer's namespace.
+One of `loaded', `not-loaded', `out-of-sync', or nil when the state is unknown
+or not applicable (no connection, not a Clojure source buffer, or no
+namespace).
+
+Cheap by design (it never queries the REPL) so it is safe to call from the
+mode line on every redisplay: when the state hasn't been determined yet
+`cider-ns-state--loaded' is nil and we bail out before any connection lookup."
+  (when (and cider-ns-state--loaded
+             (derived-mode-p 'clojure-mode 'clojure-ts-mode)
+             (cider-connected-p))
+    (cond
+     ((eq cider-ns-state--loaded 'not-loaded) 'not-loaded)
+     ((and cider-ns-state--loaded-tick
+           (/= cider-ns-state--loaded-tick (buffer-chars-modified-tick)))
+      'out-of-sync)
+     (t 'loaded))))
+
+(defun cider-ns-state--lighter ()
+  "Return the mode-line marker for the current buffer's namespace state.
+Empty unless the namespace is not loaded or is out of sync.  Any error is
+swallowed and rendered as an empty marker, since this runs during redisplay."
+  (if (not cider-show-ns-load-state)
+      ""
+    (pcase (ignore-errors (cider-ns-load-state))
+      ('not-loaded
+       (propertize " not-loaded" 'face 'cider-ns-load-state-face
+                   'help-echo "This namespace has not been loaded into the REPL.
+Load the buffer with `cider-load-buffer' (C-c C-k)."))
+      ('out-of-sync
+       (propertize " stale" 'face 'cider-ns-load-state-face
+                   'help-echo "This buffer has been edited since it was last loaded.
+Reload it with `cider-load-buffer' (C-c C-k)."))
+      (_ ""))))
+
+(defun cider-ns-state--list-async (callback)
+  "Fetch the list of namespaces loaded in the REPL and pass it to CALLBACK.
+CALLBACK is invoked only when the response actually carried a namespace list,
+so a failed or unsupported op leaves the load-state unknown rather than
+falsely reporting every namespace as not loaded."
+  (let ((loaded-nss nil))
+    (cider-nrepl-send-request
+     `("op" "cider/ns-list"
+       "exclude-regexps" ,cider-filtered-namespaces-regexps)
+     (lambda (response)
+       (nrepl-dbind-response response (ns-list status)
+         (when ns-list
+           (setq loaded-nss ns-list))
+         (when (and loaded-nss (member "done" status))
+           (funcall callback loaded-nss)))))))
+
+(defun cider-ns-state--set-from-list (buffer loaded-nss)
+  "Update BUFFER's cached load-state from LOADED-NSS, the loaded namespaces."
+  (when (buffer-live-p buffer)
+    (with-current-buffer buffer
+      (when-let* ((ns (cider-current-ns 'no-default)))
+        (setq-local cider-ns-state--loaded
+                    (if (member ns loaded-nss) t 'not-loaded))))))
+
+(defun cider-ns-state--refresh (&optional buffer)
+  "Asynchronously refresh the cached namespace load-state for BUFFER.
+BUFFER defaults to the current buffer.  Does nothing when there is no
+connection or the buffer has no namespace."
+  (let ((buf (or buffer (current-buffer))))
+    (when (with-current-buffer buf
+            (and (cider-connected-p)
+                 (cider-nrepl-op-supported-p "cider/ns-list" nil 'skip-ensure)
+                 (cider-current-ns 'no-default)))
+      (cider-ns-state--list-async
+       (lambda (loaded-nss) (cider-ns-state--set-from-list buf loaded-nss))))))
+
+(defun cider-ns-refresh-load-state ()
+  "Re-check whether the current buffer's namespace is loaded in the REPL."
+  (interactive)
+  (cider-ns-state--refresh))
+
+(defun cider-ns-state--refresh-on-focus (&optional _frame)
+  "Refresh the load-state of the focused Clojure buffer if it's unknown.
+Intended for `window-selection-change-functions': when you select a connected
+Clojure buffer whose state hasn't been determined yet, check it once.  This
+deliberately avoids querying at connection time (which is fragile)."
+  (when cider-show-ns-load-state
+    (ignore-errors
+      (let ((buf (window-buffer (selected-window))))
+        (with-current-buffer buf
+          (when (and (derived-mode-p 'clojure-mode 'clojure-ts-mode)
+                     (null cider-ns-state--loaded)
+                     (cider-connected-p))
+            (cider-ns-state--refresh buf)))))))
+
+(defun cider-ns-state--mark-loaded ()
+  "Mark the current buffer's namespace as loaded and in sync.
+Intended for `cider-file-loaded-hook'."
+  (when (derived-mode-p 'clojure-mode 'clojure-ts-mode)
+    (setq-local cider-ns-state--loaded t
+                cider-ns-state--loaded-tick (buffer-chars-modified-tick))))
+
+(defun cider-ns-state-setup ()
+  "Enable namespace load-state tracking in the current buffer.
+Registers a buffer-local focus hook so the state is checked when you switch
+to the buffer.  Intended to be called when `cider-mode' is enabled."
+  (add-hook 'window-selection-change-functions
+            #'cider-ns-state--refresh-on-focus nil 'local))
+
+(defun cider-ns-state-teardown ()
+  "Disable namespace load-state tracking in the current buffer.
+Intended to be called when `cider-mode' is disabled."
+  (remove-hook 'window-selection-change-functions
+               #'cider-ns-state--refresh-on-focus 'local)
+  (kill-local-variable 'cider-ns-state--loaded)
+  (kill-local-variable 'cider-ns-state--loaded-tick))
+
+;; `cider-file-loaded-hook' is cheap and only fires on CIDER loads, so it stays
+;; global; the focus hook is per-buffer (see `cider-ns-state-setup') to avoid
+;; running on every window selection change in unrelated buffers.
+(add-hook 'cider-file-loaded-hook #'cider-ns-state--mark-loaded)
+
+(provide 'cider-ns-state)
+
+;;; cider-ns-state.el ends here

test/cider-ns-state-tests.el

@@ -0,0 +1,137 @@
+;;; cider-ns-state-tests.el  -*- lexical-binding: t; -*-
+
+;; Copyright © 2026 Bozhidar Batsov
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or
+;; modify it under the terms of the GNU General Public License as
+;; published by the Free Software Foundation, either version 3 of the
+;; License, or (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see `http://www.gnu.org/licenses/'.
+
+;;; Commentary:
+
+;; Tests for the namespace load-state tracking.
+
+;;; Code:
+
+(require 'buttercup)
+(require 'clojure-mode)
+(require 'nrepl-dict)
+(require 'cider-ns-state)
+
+;; Please, for each `describe', ensure there's an `it' block, so that its execution is visible in CI.
+
+(describe "cider-ns-load-state"
+  ;; stub the connection check so the logic runs offline
+  (before-each (spy-on 'cider-connected-p :and-return-value t))
+
+  (it "is nil when the load state hasn't been determined"
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (expect (cider-ns-load-state) :to-be nil)))
+  (it "is not-loaded when the namespace is absent from the REPL"
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (setq-local cider-ns-state--loaded 'not-loaded)
+      (expect (cider-ns-load-state) :to-equal 'not-loaded)))
+  (it "is loaded when loaded and unchanged since"
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (setq-local cider-ns-state--loaded t
+                  cider-ns-state--loaded-tick (buffer-chars-modified-tick))
+      (expect (cider-ns-load-state) :to-equal 'loaded)))
+  (it "is out-of-sync when the buffer was edited since loading"
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (setq-local cider-ns-state--loaded t
+                  cider-ns-state--loaded-tick (buffer-chars-modified-tick))
+      (insert " ;; edit")
+      (expect (cider-ns-load-state) :to-equal 'out-of-sync)))
+  (it "is nil in non-Clojure buffers"
+    (with-temp-buffer
+      (fundamental-mode)
+      (setq-local cider-ns-state--loaded 'not-loaded)
+      (expect (cider-ns-load-state) :to-be nil))))
+
+(describe "cider-ns-state--lighter"
+  (before-each (spy-on 'cider-connected-p :and-return-value t))
+
+  (it "marks not-loaded and stale, and is empty when loaded/unknown"
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (expect (cider-ns-state--lighter) :to-equal "")            ; unknown
+      (setq-local cider-ns-state--loaded 'not-loaded)
+      (expect (string-trim (cider-ns-state--lighter)) :to-equal "not-loaded")
+      (setq-local cider-ns-state--loaded t
+                  cider-ns-state--loaded-tick (buffer-chars-modified-tick))
+      (expect (cider-ns-state--lighter) :to-equal "")            ; loaded
+      (insert " x")
+      (expect (string-trim (cider-ns-state--lighter)) :to-equal "stale")))
+  (it "is empty when disabled via `cider-show-ns-load-state'"
+    (let ((cider-show-ns-load-state nil))
+      (with-temp-buffer
+        (clojure-mode)
+        (setq-local cider-ns-state--loaded 'not-loaded)
+        (expect (cider-ns-state--lighter) :to-equal "")))))
+
+(describe "cider-ns-state--refresh"
+  (it "does nothing when the cider/ns-list op is unsupported (e.g. no cider-nrepl)"
+    (spy-on 'cider-connected-p :and-return-value t)
+    (spy-on 'cider-nrepl-op-supported-p :and-return-value nil)
+    (spy-on 'cider-ns-state--list-async)
+    (with-temp-buffer
+      (clojure-mode)
+      (insert "(ns foo)")
+      (cider-ns-state--refresh)
+      (expect 'cider-ns-state--list-async :not :to-have-been-called)
+      (expect cider-ns-state--loaded :to-be nil))))
+
+(describe "cider-ns-state--list-async"
+  (it "leaves the state unknown when the response carries no ns-list"
+    ;; e.g. an unknown-op error reply - it must not mark the ns not-loaded
+    (spy-on 'cider-nrepl-send-request :and-call-fake
+            (lambda (_req handler &rest _)
+              (funcall handler (nrepl-dict "status" '("done")))))
+    (let (called)
+      (cider-ns-state--list-async (lambda (_) (setq called t)))
+      (expect called :to-be nil)))
+  (it "invokes the callback with the namespace list on success"
+    (spy-on 'cider-nrepl-send-request :and-call-fake
+            (lambda (_req handler &rest _)
+              (funcall handler (nrepl-dict "ns-list" '("foo" "bar") "status" '("done")))))
+    (let (result)
+      (cider-ns-state--list-async (lambda (nss) (setq result nss)))
+      (expect result :to-equal '("foo" "bar")))))
+
+(describe "cider-ns-state setup/teardown"
+  (it "adds a buffer-local focus hook and tears it down with the cached state"
+    (with-temp-buffer
+      (clojure-mode)
+      (cider-ns-state-setup)
+      (expect (memq #'cider-ns-state--refresh-on-focus
+                    window-selection-change-functions)
+              :to-be-truthy)
+      (setq-local cider-ns-state--loaded t)
+      (cider-ns-state-teardown)
+      (expect (memq #'cider-ns-state--refresh-on-focus
+                    window-selection-change-functions)
+              :to-be nil)
+      (expect (local-variable-p 'cider-ns-state--loaded) :to-be nil))))
+
+(provide 'cider-ns-state-tests)
+
+;;; cider-ns-state-tests.el ends here