feat(clojure-mode): Enhancement roadmap for Clojure language mode

[cxxxr]

Summary

This issue tracks planned enhancements for lem-clojure-mode, inspired by the comprehensive feature set of lem-lisp-mode. The initial implementation (#2068) provides syntax highlighting and LSP integration.

🎉 Implementation Status: COMPLETE

All phases of the roadmap have been implemented! See details below.

---

Phase 1: Basic Enhancements ✅ COMPLETE

1.1 Clojure-specific Indentation ✅

• Implement calc-indent-function for Clojure forms (clojure-calc-indent)
• Special indentation for fn, let, letfn, defn, cond, case, etc.
• Thread-first/last macro indentation (->, ->>, some->, cond->)
• Comprehensive indentation table with 40+ rules in clojure-mode.lisp

1.2 Rainbow Parentheses ✅

• Full rainbow parentheses implementation with 6 colors
• Support for (), [], {} bracket types
• Toggle command: toggle-clojure-paren-coloring

1.3 Namespace Detection ✅

• Parse (ns ...) form via clojure-guess-namespace
• Display namespace in modeline (clojure-mode-line)
• Cache namespace in buffer value
• Unit tests for namespace detection

1.4 Evaluation Highlighting ✅

• Visual feedback via eval-region-attribute
• Highlight/clear functions for evaluation regions

---

Phase 2: nREPL Integration ✅ COMPLETE

2.1 nREPL Client (nrepl-client.lisp) ✅

• Full Bencode implementation (bencode.lisp)
• Connection management (nrepl-connect, nrepl-disconnect)
• Session handling (nrepl-clone-session, nrepl-close-session)
• Async/sync message sending
• Background reader thread

2.2 REPL Mode (repl.lisp) ✅

• clojure-repl-mode with dedicated keymap
• REPL buffer with prompt handling
• History support via lem/listener-mode
• Namespace tracking in REPL

2.3 Evaluation Commands (commands.lisp) ✅

• clojure-eval-defun - Evaluate top-level form
• clojure-eval-last-sexp - Evaluate expression before point
• clojure-eval-region - Evaluate selected region
• clojure-eval-buffer - Evaluate entire buffer
• clojure-load-file - Load current file
• clojure-switch-to-repl - Switch to REPL buffer
• clojure-set-namespace - Change namespace

2.4 Keybindings (CIDER-compatible) ✅

C-c C-c    clojure-eval-defun
C-x C-e    clojure-eval-last-sexp
C-c C-e    clojure-eval-last-sexp
C-c C-r    clojure-eval-region
C-c C-k    clojure-load-file
C-c C-l    clojure-load-file
C-c C-z    clojure-switch-to-repl
C-c M-n    clojure-set-namespace-from-buffer

---

Phase 3: IDE Features ✅ COMPLETE

3.1 Macro Expansion (commands.lisp) ✅

• clojure-macroexpand-1 (C-c Return) - Single-step expansion
• clojure-macroexpand-all (C-c M-m) - Full expansion
• Popup buffer with syntax highlighting

3.2 Documentation (commands.lisp) ✅

• clojure-describe-symbol - Show docstring
• clojure-describe-symbol-at-point (C-c C-d d) - Doc at point
• Popup buffer for documentation display

3.3 Inspector (inspector.lisp) ✅

• clojure-inspector-mode with navigation
• clojure-inspect - Inspect arbitrary expression
• clojure-inspect-last-sexp (C-c I) - Inspect sexp
• History navigation (l/Backspace to go back)
• Refresh capability (g)

3.4 Test Runner (test-runner.lisp) ✅

• clojure-run-test-at-point (C-c C-t t) - Run test under cursor
• clojure-run-tests (C-c C-t n) - Run tests in namespace
• clojure-run-all-tests (C-c C-t a) - Run all tests
• clojure-rerun-last-test (C-c C-t l) - Rerun last test
• Color-coded pass/fail/error display
• Navigation between failures (n/p)

3.5 Stacktrace Navigation (stacktrace.lisp) ✅

• clojure-stacktrace-mode with keybindings
• clojure-show-last-exception (C-c C-x)
• Clickable stack frames to jump to source
• Toggle Java frames visibility (j)
• Frame navigation (n/p/Tab)

---

Phase 4: Advanced Features ✅ COMPLETE

4.1 Detective Integration (detective.lisp) ✅

• Regex patterns for all definition types:
  • Functions: defn, defn-, defmulti, defmethod
  • Macros: defmacro
  • Types: defprotocol, defrecord, deftype, definterface
  • Variables: def, defonce
  • Namespaces: ns
  • Tests: deftest, defspec
• Auto-setup via mode hook

4.2 Context Menu (tools.lisp) ✅

• Context menu with evaluation actions
• Items: Evaluate Expression, Evaluate Defun, Inspect Value, Run Test, Show Documentation
• Auto-setup via mode hook

4.3 ClojureScript Support ✅ (Partial)

• File type registration for .cljs, .cljc, .cljx, .edn
• Shadow-cljs integration (future enhancement)
• Figwheel support (future enhancement)

4.4 Refactoring Tools (tools.lisp) ✅

• clojure-align-let (C-c C-a l) - Align let bindings
• clojure-align-map (C-c C-a m) - Align map literals
• clojure-cycle-privacy (C-c C-p) - Toggle defn/defn-
• clojure-add-require (C-c C-a r) - Add require clause
• clojure-toggle-keyword-string (C-c C-') - Toggle :keyword/"string"
• clojure-thread-first - Convert to -> form

---

Additional Features Implemented

LSP Integration (lsp-config.lisp)

• clojure-lsp configuration
• Project detection via deps.edn, project.clj, build.boot, shadow-cljs.edn
• Installation instructions

Syntax Highlighting (clojure-mode.lisp)

• TextMate-style language definition
• Special forms (40+)
• Built-in functions (100+)
• Keywords, strings, regex literals
• Numeric literals (decimal, hex, ratios)
• Character literals
• Metadata and deref

Navigation

• clojure-beginning-of-defun / clojure-end-of-defun
• clojure-indent-sexp (C-M-q)

---

File Structure

extensions/clojure-mode/
├── lem-clojure-mode.asd   # System definition
├── clojure-mode.lisp      # Core mode: syntax, indentation, rainbow parens
├── lsp-config.lisp        # LSP configuration for clojure-lsp
├── bencode.lisp           # Bencode encoder/decoder for nREPL
├── nrepl-client.lisp      # nREPL protocol client
├── repl.lisp              # REPL mode and connection commands
├── commands.lisp          # Evaluation and documentation commands
├── inspector.lisp         # Value inspection interface
├── test-runner.lisp       # clojure.test integration
├── stacktrace.lisp        # Exception/stacktrace navigation
├── detective.lisp         # Definition navigation patterns
├── tools.lisp             # Refactoring and context menu
└── tests/main.lisp        # Unit tests

---

Dependencies

• lem/core
• lem-lsp-mode - LSP integration
• usocket - Network communication
• babel - Character encoding
• bordeaux-threads - Threading for nREPL reader

---

Related

• feat(clojure-mode): add comprehensive Clojure language support #2068 - Initial clojure-mode implementation (merged)
• feat: Add language modes for unsupported languages #2066 - Language modes tracking issue

Future Enhancements

While all planned phases are complete, potential future additions include:

• Shadow-cljs/Figwheel integration for ClojureScript
• CIDER-nREPL middleware support for enhanced features
• Interactive debugger with breakpoints
• Refactoring via clj-refactor style commands