Add support to view printed exceptions in the stacktrace inspector

This PR adds the `cider-stacktrace-analyze-at-point` and
`cider-stacktrace-analyze-in-region` commands to view printed
exceptions in the stacktrace inspector.

Author: r0man

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### New features
 
 - [#3249](https://github.com/clojure-emacs/cider/pull/3249): Add support for Clojure Spec 2.
+- [#3247](https://github.com/clojure-emacs/cider/pull/3247) Add the `cider-stacktrace-analyze-at-point` and `cider-stacktrace-analyze-in-region` commands to view printed exceptions in the stacktrace inspector.
 
 ### Changes
 

cider-stacktrace.el

@@ -670,29 +670,30 @@ This associates text properties to enable filtering and source navigation."
                               'follow-link t
                               'action (lambda (x) (browse-url (button-get x 'url)))))
       (nrepl-dbind-response frame (file line flags class method name var ns fn)
-        (let ((flags (mapcar #'intern flags))) ; strings -> symbols
-          (insert-text-button (format "%26s:%5d  %s/%s"
-                                      (if (member 'repl flags) "REPL" file) line
-                                      (if (member 'clj flags) ns class)
-                                      (if (member 'clj flags) fn method))
-                              'var var 'class class 'method method
-                              'name name 'file file 'line line
-                              'flags flags 'follow-link t
-                              'action #'cider-stacktrace-navigate
-                              'help-echo (cider-stacktrace-tooltip
-                                          "View source at this location")
-                              'font-lock-face 'cider-stacktrace-face
-                              'type 'cider-plain-button)
-          (save-excursion
-            (let ((p4 (point))
-                  (p1 (search-backward " "))
-                  (p2 (search-forward "/"))
-                  (p3 (search-forward-regexp "[^/$]+")))
-              (put-text-property p1 p4 'font-lock-face 'cider-stacktrace-ns-face)
-              (put-text-property p2 p3 'font-lock-face 'cider-stacktrace-fn-face)
-              (put-text-property (line-beginning-position) (line-end-position)
-                                 'cider-stacktrace-frame t)))
-          (insert "\n"))))))
+        (when (or class file fn method ns name)
+          (let ((flags (mapcar #'intern flags))) ; strings -> symbols
+            (insert-text-button (format "%26s:%5d  %s/%s"
+                                        (if (member 'repl flags) "REPL" file) (or line -1)
+                                        (if (member 'clj flags) ns class)
+                                        (if (member 'clj flags) fn method))
+                                'var var 'class class 'method method
+                                'name name 'file file 'line line
+                                'flags flags 'follow-link t
+                                'action #'cider-stacktrace-navigate
+                                'help-echo (cider-stacktrace-tooltip
+                                            "View source at this location")
+                                'font-lock-face 'cider-stacktrace-face
+                                'type 'cider-plain-button)
+            (save-excursion
+              (let ((p4 (point))
+                    (p1 (search-backward " "))
+                    (p2 (search-forward "/"))
+                    (p3 (search-forward-regexp "[^/$]+")))
+                (put-text-property p1 p4 'font-lock-face 'cider-stacktrace-ns-face)
+                (put-text-property p2 p3 'font-lock-face 'cider-stacktrace-fn-face)
+                (put-text-property (line-beginning-position) (line-end-position)
+                                   'cider-stacktrace-frame t)))
+            (insert "\n")))))))
 
 (defun cider-stacktrace-render-compile-error (buffer cause)
   "Emit into BUFFER the compile error CAUSE, and enable jumping to it."
@@ -844,7 +845,8 @@ the NAME.  The whole group is prefixed by string INDENT."
               (goto-char (next-single-property-change (point) 'compile-error))
             (progn
               (while (cider-stacktrace-next-cause))
-              (goto-char (next-single-property-change (point) 'flags)))))))))
+              (when-let (position (next-single-property-change (point) 'flags))
+                (goto-char position)))))))))
 
 (defun cider-stacktrace-render (buffer causes &optional error-types)
   "Emit into BUFFER useful stacktrace information for the CAUSES.
@@ -876,6 +878,54 @@ through the `cider-stacktrace-suppressed-errors' variable."
     (cider-stacktrace-initialize causes)
     (font-lock-refresh-defaults)))
 
+(defun cider-stacktrace--analyze-stacktrace-op (stacktrace)
+  "Return the Cider NREPL op to analyze STACKTRACE."
+  (list "op" "analyze-stacktrace" "stacktrace" stacktrace))
+
+(defun cider-stacktrace--stacktrace-request (stacktrace)
+  "Return the Cider NREPL request to analyze STACKTRACE."
+  (thread-last
+    (map-merge 'list
+               (list (cider-stacktrace--analyze-stacktrace-op stacktrace))
+               (cider--nrepl-print-request-map fill-column))
+    (seq-mapcat #'identity)))
+
+(defun cider-stacktrace--analyze-render (causes)
+  "Render the CAUSES of the stacktrace analysis result."
+  (let ((buffer (get-buffer-create cider-error-buffer)))
+    (with-current-buffer buffer
+      (cider-stacktrace-mode)
+      (cider-stacktrace-render buffer (reverse causes))
+      (display-buffer buffer cider-jump-to-pop-to-buffer-actions))))
+
+(defun cider-stacktrace-analyze-string (stacktrace)
+  "Analyze the STACKTRACE string and show the result."
+  (when (stringp stacktrace)
+    (set-text-properties 0 (length stacktrace) nil stacktrace))
+  (let (causes)
+    (cider-nrepl-send-request
+     (cider-stacktrace--stacktrace-request stacktrace)
+     (lambda (response)
+       (setq causes (nrepl-dbind-response response (class status)
+                      (cond (class (cons response causes))
+                            ((and (member "done" status) causes)
+                             (cider-stacktrace--analyze-render causes)))))))))
+
+(defun cider-stacktrace-analyze-at-point ()
+  "Analyze the stacktrace at point."
+  (interactive)
+  (cond ((thing-at-point 'sentence)
+         (cider-stacktrace-analyze-string (thing-at-point 'sentence)))
+        ((thing-at-point 'paragraph)
+         (cider-stacktrace-analyze-string (thing-at-point 'paragraph)))
+        (t (cider-stacktrace-analyze-in-region (region-beginning) (region-end)))))
+
+(defun cider-stacktrace-analyze-in-region (beg end)
+  "Analyze the stacktrace in the region between BEG and END."
+  (interactive (list (region-beginning) (region-end)))
+  (let ((stacktrace (buffer-substring beg end)))
+    (cider-stacktrace-analyze-string stacktrace)))
+
 (provide 'cider-stacktrace)
 
 ;;; cider-stacktrace.el ends here

doc/modules/ROOT/pages/usage/dealing_with_errors.adoc

@@ -182,3 +182,95 @@ for instance:
 ----
 (setq cider-stacktrace-fill-column 80)
 ----
+
+=== Inspecting printed stacktraces
+
+Some of the errors you encounter as a Clojurists aren't necessarily
+evaluation errors that happened in your REPL. Many times, you see
+errors printed in a textual representation in other buffers as well,
+like log files or the REPL for example. Cider can parse and analyze
+some of those printed errors as well and show them in
+`cider-stacktrace-mode` with the following commands:
+
+* The `cider-stacktrace-analyze-at-point` command uses the `thingatpt`
+  library to extract the current stacktrace at point. It sends the
+  extracted stacktrace to the middleware in order to parse and analyze
+  it, and then shows the result in Cider's `cider-stacktrace-mode`.
+
+* The `cider-stacktrace-analyze-in-region` command does the same as
+  `cider-stacktrace-analyze-at-point`, but uses the current region to
+  extract the stacktrace.
+
+===== Examples
+
+Here is an example of a stacktrace printed with the Java
+`printStackTrace` method:
+
+[source,text]
+----
+clojure.lang.ExceptionInfo: BOOM-1 {:boom "1"}
+  at java.base/java.lang.Thread.run(Thread.java:829)
+----
+
+To open this stacktrace in the Cider stacktrace inspector, move point
+somewhere over the exception and run `M-x
+cider-stacktrace-analyze-at-point`.
+
+This also works to some extend for exceptions that are buried inside a
+string like the following exception:
+
+[source,text]
+----
+"clojure.lang.ExceptionInfo: BOOM-1 {:boom \"1\"}\n at java.base/java.lang.Thread.run(Thread.java:829)"
+----
+
+Those exceptions are often hard to read. The Cider stacktrace
+inspector can help you navigating exceptions even in those cases.
+
+===== Supported formats
+
+Cider recognizes stacktraces printed in the following formats:
+
+- `Aviso` - Exceptions printed with the
+  https://ioavisopretty.readthedocs.io/en/latest/exceptions.html[write-exception]
+  function of the https://github.com/AvisoNovate/pretty[Aviso]
+  library.
+
+- `clojure.repl` - Exceptions printed with the
+  https://clojure.github.io/clojure/branch-master/clojure.repl-api.html#clojure.repl/pst[clojure.repl/pst]
+  function.
+
+- `clojure.stacktrace` - Exceptions printed with the
+  https://clojure.github.io/clojure/branch-master/clojure.stacktrace-api.html#clojure.stacktrace/print-cause-trace[clojure.stacktrace/print-cause-trace]
+  function.
+
+- `Java` - Exceptions printed with the
+  https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html#printStackTrace--[Throwable/printStackTrace]
+  method.
+
+- `Tagged Literal` - Exceptions printed with the
+  https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/pr[clojure.core/pr]
+  function.
+
+===== Limitations
+
+- Cider only recognizes stacktraces that have been printed in one of
+  the supported formats.
+
+- The buffers in which `cider-stacktrace-analyze-at-point` or
+  `cider-stacktrace-analyze-in-region` are called in, must have a
+  Cider session associated with them. Tip: Use
+  `sesman-link-with-project` and friends in case the buffer containing
+  the exception is not linked to a Cider session.
+
+- Stacktraces are analyzed with the classpath of the Cider session the
+  buffer is associated with. If the stacktrace contains references to
+  classes not on this classpath, some information might be missing
+  from the analysis.
+
+- The `cider-stacktrace-analyze-at-point` function might not detect
+  the stacktrace at point in every situation. The thing at point might
+  be different depending on which major mode is active in a
+  buffer. When `cider-stacktrace-analyze-at-point` fails to detect the
+  stacktrace, `cider-stacktrace-analyze-in-region` can be used to
+  select the stacktrace manually.