(feat)buffer: add unique option for org-roam-backlinks-section (#2121)

Prior to this commit, when we would render backlinks in the
`org-buffer`, we would render each reference.  This meant that if a
source file referenced the node 5 times, there would be 5 backlink
references in the `org-buffer` (one for each position of the reference).

With this change, we add a parameter that specifies that backlink
sources should be unique.  In the above example, that would mean instead
of 5 backlinks we'd see 1.  And, as a concession, we'd use the lowest
position (e.g. the first reference in the source).

Closes #2119

doc/org-roam.org

@@ -648,6 +648,15 @@ To configure what sections are displayed in the buffer, set ~org-roam-mode-secti
 
 Note that computing unlinked references may be slow, and has not been added in by default.
 
+Or, if you want to render unique sources for backlinks (and also keep rendering reference links), set ~org-roam-mode-section-functions~ as follows:
+
+#+begin_src emacs-lisp
+  (setq org-roam-mode-section-functions
+        (list
+         (lambda (node) (org-roam-backlinks-section node :unique t))
+         #'org-roam-reflinks-section))
+#+end_src
+
 ** Configuring the Org-roam buffer display
 
 Org-roam does not control how the pop-up buffer is displayed: this is left to

doc/org-roam.texi

@@ -988,6 +988,16 @@ To configure what sections are displayed in the buffer, set @code{org-roam-mode-
 
 Note that computing unlinked references may be slow, and has not been added in by default.
 
+Or, if you want to render unique sources for backlinks (and also keep rendering reference links), set @code{org-roam-mode-section-functions} as follows:
+
+@lisp
+  (setq org-roam-mode-section-functions
+        (list
+         (lambda (node) (org-roam-backlinks-section node :unique t))
+         #'org-roam-reflinks-section))
+@end lisp
+
+
 @node Configuring the Org-roam buffer display
 @section Configuring the Org-roam buffer display
 

org-roam-mode.el

@@ -459,14 +459,23 @@ headline, up to the next headline."
         (org-roam-populate (org-roam-backlink-target-node backlink)))
   backlink)
 
-(defun org-roam-backlinks-get (node)
-  "Return the backlinks for NODE."
-  (let ((backlinks (org-roam-db-query
-                    [:select [source dest pos properties]
-                     :from links
-                     :where (= dest $s1)
-                     :and (= type "id")]
-                    (org-roam-node-id node))))
+(cl-defun org-roam-backlinks-get (node &key unique)
+  "Return the backlinks for NODE.
+
+ When UNIQUE is nil, show all positions where references are found.
+ When UNIQUE is t, limit to unique sources."
+  (let* ((sql (if unique
+                  [:select :distinct [source dest pos properties]
+                   :from links
+                   :where (= dest $s1)
+                   :and (= type "id")
+                   :group :by source
+                   :having (funcall min pos)]
+                [:select [source dest pos properties]
+                 :from links
+                 :where (= dest $s1)
+                 :and (= type "id")]))
+         (backlinks (org-roam-db-query sql (org-roam-node-id node))))
     (cl-loop for backlink in backlinks
              collect (pcase-let ((`(,source-id ,dest-id ,pos ,properties) backlink))
                        (org-roam-populate
@@ -482,9 +491,12 @@ Sorts by title."
   (string< (org-roam-node-title (org-roam-backlink-source-node a))
            (org-roam-node-title (org-roam-backlink-source-node b))))
 
-(defun org-roam-backlinks-section (node)
-  "The backlinks section for NODE."
-  (when-let ((backlinks (seq-sort #'org-roam-backlinks-sort (org-roam-backlinks-get node))))
+(cl-defun org-roam-backlinks-section (node &key (unique nil))
+  "The backlinks section for NODE.
+
+When UNIQUE is nil, show all positions where references are found.
+When UNIQUE is t, limit to unique sources."
+  (when-let ((backlinks (seq-sort #'org-roam-backlinks-sort (org-roam-backlinks-get node :unique unique))))
     (magit-insert-section (org-roam-backlinks)
       (magit-insert-heading "Backlinks:")
       (dolist (backlink backlinks)