(feat): Add org-ref citation support (#374)

Adds support for org-ref cite: links to the backlinks buffer.

Requires a db-rebuild, since the db schema has changed.

CHANGELOG.md

@@ -8,6 +8,7 @@
 ### New Features
 * [#350][gh-350] Add `org-roam-db-location`
 * [#359][gh-359] Add `org-roam-verbose`
+* [#374][gh-374] Add support for `org-ref` `cite:` links
 * [#380][gh-380] Allow `org-roam-buffer-position` to also be `top` or `bottom`
 * [#385][gh-385] Add `org-roam-graph-node-extra-config` to configure Graphviz nodes
 
@@ -113,7 +114,8 @@ Mostly a documentation/cleanup release.
 * [#71][gh-71], [#78][gh-78]: Fixed `org-roam-insert` not inserting correct paths
 * [#82][gh-82]: Fixed nested Org-roam files not being detected as part of Org-roam
 
-[gh-62]: https://github.com/jethrokuan/org-roam/pull/66
+<!-- start links -->
+[gh-62]: https://github.com/jethrokuan/org-roam/pull/62
 [gh-66]: https://github.com/jethrokuan/org-roam/pull/66
 [gh-67]: https://github.com/jethrokuan/org-roam/pull/67
 [gh-68]: https://github.com/jethrokuan/org-roam/pull/68
@@ -140,15 +142,17 @@ Mostly a documentation/cleanup release.
 [gh-136]: https://github.com/jethrokuan/org-roam/pull/136
 [gh-138]: https://github.com/jethrokuan/org-roam/pull/138
 [gh-141]: https://github.com/jethrokuan/org-roam/pull/141
-[gh-142]: https://github.com/jethrokuan/org-roam/pull/142
 [gh-143]: https://github.com/jethrokuan/org-roam/pull/143
+[gh-145]: https://github.com/jethrokuan/org-roam/pull/145
 [gh-182]: https://github.com/jethrokuan/org-roam/pull/182
-[gh-188]: https://github.com/jethrokuan/org-roam/pull/188
 [gh-200]: https://github.com/jethrokuan/org-roam/pull/200
+[gh-203]: https://github.com/jethrokuan/org-roam/pull/203
 [gh-207]: https://github.com/jethrokuan/org-roam/pull/207
 [gh-216]: https://github.com/jethrokuan/org-roam/pull/216
 [gh-221]: https://github.com/jethrokuan/org-roam/pull/221
 [gh-230]: https://github.com/jethrokuan/org-roam/pull/230
+[gh-232]: https://github.com/jethrokuan/org-roam/pull/232
+[gh-233]: https://github.com/jethrokuan/org-roam/pull/233
 [gh-247]: https://github.com/jethrokuan/org-roam/pull/247
 [gh-257]: https://github.com/jethrokuan/org-roam/pull/257
 [gh-259]: https://github.com/jethrokuan/org-roam/pull/259
@@ -161,10 +165,11 @@ Mostly a documentation/cleanup release.
 [gh-296]: https://github.com/jethrokuan/org-roam/pull/296
 [gh-350]: https://github.com/jethrokuan/org-roam/pull/350
 [gh-359]: https://github.com/jethrokuan/org-roam/pull/359
+[gh-374]: https://github.com/jethrokuan/org-roam/pull/374
 [gh-380]: https://github.com/jethrokuan/org-roam/pull/380
 [gh-385]: https://github.com/jethrokuan/org-roam/pull/385
+<!-- end links -->
 
-
+<!-- Local Variables: -->
- # Local Variables:
+<!-- eval: (auto-fill-mode -1) -->
- # eval: (auto-fill-mode -1)
+<!-- End: -->
- # End:

doc/anatomy.md

@@ -36,5 +36,6 @@ Alternatively, add a ref for notes for a specific paper, using its
 #+ROAM_KEY: cite:chen18_neural_ordin_differ_equat
 ```
 
-In future, the backlinks buffer will also show notes with that
+The backlinks buffer will show any cites of this key: e.g.
-citation key.
+
+![org-ref-citelink](images/org-ref-citelink.png)

doc/org_export.md

@@ -9,7 +9,7 @@ in-built publishing or ox-hugo -- use the following snippet to add a
        (concat acc (format "- [[file:%s][%s]]\n"
                            (file-relative-name (car it) org-roam-directory)
 			                     (org-roam--get-title-or-slug (car it))))
-       "" (org-roam-sql [:select [file-from] :from file-links :where (= file-to $s1)] file))
+       "" (org-roam-sql [:select [from] :from links :where (= to $s1) :and (= from $s2)] file "roam"))
     ""))
 
 (defun my/org-export-preprocessor (backend)

org-roam-db.el

@@ -54,7 +54,7 @@ when used with multiple Org-roam instances."
   :type 'string
   :group 'org-roam)
 
-(defconst org-roam-db--version 1)
+(defconst org-roam-db--version 2)
 (defconst org-roam-db--sqlite-available-p
   (with-demoted-errors "Org-roam initialization: %S"
     (emacsql-sqlite-ensure-binary)
@@ -126,17 +126,16 @@ SQL can be either the emacsql vector representation, or a string."
   '((files
      [(file :unique :primary-key)
       (hash :not-null)
-      (last-modified :not-null)
+      (last-modified :not-null)])
-      ])
 
-    (file-links
+    (links
-     [(file-from :not-null)
+     [(from :not-null)
-      (file-to :not-null)
+      (to :not-null)
+      (type :not-null)
       (properties :not-null)])
 
     (titles
-     [
+     [(file :not-null)
-      (file :not-null)
       titles])
 
     (refs
@@ -154,7 +153,11 @@ SQL can be either the emacsql vector representation, or a string."
   "Upgrades the database schema for DB, if VERSION is old."
   (emacsql-with-transaction db
     'ignore
-    ;; Do nothing now
+    (when (= version 1)
+      (progn
+        (warn "No good way to perform a DB upgrade, rebuilding from scratch...")
+        (delete-file (org-roam-db--get))
+        (org-roam-db-build-cache)))
     version))
 
 (defun org-roam-db--close (&optional db)
@@ -193,7 +196,7 @@ the current `org-roam-directory'."
   (when (file-exists-p (org-roam-db--get))
     (org-roam-db-query [:delete :from files])
     (org-roam-db-query [:delete :from titles])
-    (org-roam-db-query [:delete :from file-links])
+    (org-roam-db-query [:delete :from links])
     (org-roam-db-query [:delete :from refs])))
 
 
@@ -206,8 +209,8 @@ This is equivalent to removing the node from the graph."
     (org-roam-db-query [:delete :from files
                         :where (= file $s1)]
                        file)
-    (org-roam-db-query [:delete :from file-links
+    (org-roam-db-query [:delete :from links
-                                :where (= file-from $s1)]
+                        :where (= from $s1)]
                        file)
     (org-roam-db-query [:delete :from titles
                         :where (= file $s1)]
@@ -220,7 +223,7 @@ This is equivalent to removing the node from the graph."
 (defun org-roam-db--insert-links (links)
   "Insert LINKS into the Org-roam cache."
   (org-roam-db-query
-   [:insert :into file-links
+   [:insert :into links
     :values $v1]
    links))
 
@@ -275,8 +278,8 @@ This is equivalent to removing the node from the graph."
 (defun org-roam-db--update-cache-links ()
   "Update the file links of the current buffer in the cache."
   (let ((file (file-truename (buffer-file-name))))
-    (org-roam-db-query [:delete :from file-links
+    (org-roam-db-query [:delete :from links
-                                :where (= file-from $s1)]
+                        :where (= from $s1)]
                        file)
     (when-let ((links (org-roam--extract-links)))
       (org-roam-db--insert-links links))))
@@ -332,7 +335,7 @@ This is equivalent to removing the node from the graph."
        all-files))
     (when all-links
       (org-roam-db-query
-       [:insert :into file-links
+       [:insert :into links
         :values $v1]
        all-links))
     (when all-titles

org-roam-graph.el

@@ -123,20 +123,20 @@ set WHERE to true if WHERE query already exists."
     (nreverse res)))
 
 (defun org-roam-graph--build ()
-  "Build the graph output string.
+  "Build the graphviz string.
-The Org-roam database titles table is read, to obtain the list of titles.
+The Org-roam database titles table is read, to obtain the list of
-The file-links table is then read to obtain all directed links, and formatted
+titles. The links table is then read to obtain all directed
-into a digraph."
+links, and formatted into a digraph."
   (org-roam-db--ensure-built)
   (org-roam--with-temp-buffer
     (let* ((node-query `[:select [file titles]
                                  :from titles
                                  ,@(org-roam-graph--expand-matcher 'file t)])
            (nodes (org-roam-db-query node-query))
-           (edges-query `[:select :distinct [file-to file-from]
+           (edges-query `[:select :distinct [to from]
-                                  :from file-links
+                                  :from links
-                                  ,@(org-roam-graph--expand-matcher 'file-to t)
+                                  ,@(org-roam-graph--expand-matcher 'to t)
-                                  ,@(org-roam-graph--expand-matcher 'file-from t t)])
+                                  ,@(org-roam-graph--expand-matcher 'from t t)])
            (edges (org-roam-db-query edges-query)))
       (insert "digraph \"org-roam\" {\n")
       (dolist (option org-roam-graph-extra-config)

org-roam.el

@@ -49,6 +49,9 @@
 (require 'org-roam-graph)
 (require 'org-roam-completion)
 
+;; To detect cite: links
+(require 'org-ref nil t)
+
 ;;;; Customizable Variables
 (defgroup org-roam nil
   "Roam Research replica in Org-mode."
@@ -234,7 +237,7 @@ The search terminates when the first property is encountered."
   "Extracts all link items within the current buffer.
 Link items are of the form:
 
-    [file-from file-to properties]
+    [from to type properties]
 
 This is the format that emacsql expects when inserting into the database.
 FILE-FROM is typically the buffer file path, but this may not exist, for example
@@ -244,11 +247,16 @@ it as FILE-PATH."
                        (file-truename (buffer-file-name)))))
     (org-element-map (org-element-parse-buffer) 'link
       (lambda (link)
-        (let ((type (org-element-property :type link))
+        (let* ((type (org-element-property :type link))
                (path (org-element-property :path link))
-              (start (org-element-property :begin link)))
+               (start (org-element-property :begin link))
-          (when (and (string= type "file")
+               (link-type (cond ((and (string= type "file")
                                       (org-roam--org-file-p path))
+                                 "roam")
+                                ((string= type "cite")
+                                 "cite")
+                                (t nil))))
+          (when link-type
             (goto-char start)
             (let* ((element (org-element-at-point))
                    (begin (or (org-element-property :content-begin element)
@@ -260,7 +268,11 @@ it as FILE-PATH."
                                      (org-element-property :end element)))))
                    (content (string-trim content)))
               (vector file-path
-                      (file-truename (expand-file-name path (file-name-directory file-path)))
+                      (cond ((string= link-type "roam")
+                             (file-truename (expand-file-name path (file-name-directory file-path))))
+                            ((string= link-type "cite")
+                             path))
+                      link-type
                       (list :content content :point begin)))))))))
 
 (defun org-roam--extract-titles ()
@@ -591,16 +603,69 @@ This function hooks into `org-open-at-point' via `org-open-at-point-functions'."
              (select-window org-roam-last-window))
     (find-file file)))
 
-(defun org-roam--get-backlinks (file)
+(defun org-roam--get-backlinks (target)
-  "Return the backlinks for FILE."
+  "Return the backlinks for TARGET.
-  (org-roam-db-query [:select [file-from, file-to, properties] :from file-links
+TARGET may be a file, for Org-roam file links, or a citation key,
-                              :where (= file-to $s1)
+for Org-ref cite links."
-                              :order-by (asc file-from)]
+  (org-roam-db-query [:select [from, to, properties] :from links
-                     file))
+                      :where (= to $s1)
+                      :order-by (asc from)]
+                     target))
 
 ;;;; Updating the org-roam buffer
+(defun org-roam--buffer-insert-backlinks (file-path)
+  "Insert the backlinks for FILE-PATH into the current buffer."
+  (if-let* ((file-backlinks (org-roam--get-backlinks file-path))
+              (grouped-backlinks (--group-by (nth 0 it) file-backlinks)))
+    (progn
+      (insert (format "\n\n* %d Backlinks\n"
+                      (length file-backlinks)))
+      (dolist (group grouped-backlinks)
+        (let ((file-from (car group))
+              (bls (cdr group)))
+          (insert (format "** [[file:%s][%s]]\n"
+                          file-from
+                          (org-roam--get-title-or-slug file-from)))
+          (dolist (backlink bls)
+            (pcase-let ((`(,file-from _ ,props) backlink))
+              (insert (propertize
+                       (s-trim (s-replace "\n" " "
+                                          (plist-get props :content)))
+                       'help-echo "mouse-1: visit backlinked note"
+                       'file-from file-from
+                       'file-from-point (plist-get props :point)))
+              (insert "\n\n"))))))
+    (insert "\n\n* No backlinks!")))
+
+(defun org-roam--buffer-insert-citelinks (file-path)
+  "Insert citation backlinks for FILE-PATH into the current buffer."
+  (if-let* ((roam-key (with-temp-buffer
+                        (insert-file-contents file-path)
+                        (org-roam--extract-ref)))
+            (key-backlinks (org-roam--get-backlinks (s-chop-prefix "cite:" roam-key)))
+            (grouped-backlinks (--group-by (nth 0 it) key-backlinks)))
+      (progn
+        (insert (format "\n\n* %d Cite backlinks\n"
+                        (length key-backlinks)))
+        (dolist (group grouped-backlinks)
+          (let ((file-from (car group))
+                (bls (cdr group)))
+            (insert (format "** [[file:%s][%s]]\n"
+                            file-from
+                            (org-roam--get-title-or-slug file-from)))
+            (dolist (backlink bls)
+              (pcase-let ((`(,file-from _ ,props) backlink))
+                (insert (propertize
+                         (s-trim (s-replace "\n" " "
+                                            (plist-get props :content)))
+                         'help-echo "mouse-1: visit backlinked note"
+                         'file-from file-from
+                         'file-from-point (plist-get props :point)))
+                (insert "\n\n"))))))
+    (insert "\n\n* No cite backlinks!")))
+
 (defun org-roam-update (file-path)
-  "Show the backlinks for given org file for file at `FILE-PATH'."
+  "Show the cite-backlinks for given org file for file at `FILE-PATH'."
   (org-roam-db--ensure-built)
   (let* ((source-org-roam-directory org-roam-directory))
     (let ((buffer-title (org-roam--get-title-or-slug file-path)))
@@ -626,27 +691,8 @@ This function hooks into `org-open-at-point' via `org-open-at-point-functions'."
           (setq org-return-follows-link t)
           (insert
            (propertize buffer-title 'font-lock-face 'org-document-title))
-          (if-let* ((backlinks (org-roam--get-backlinks file-path))
+          (org-roam--buffer-insert-backlinks file-path)
-                    (grouped-backlinks (--group-by (nth 0 it) backlinks)))
+          (org-roam--buffer-insert-citelinks file-path))
-              (progn
-                (insert (format "\n\n* %d Backlinks\n"
-                                (length backlinks)))
-                (dolist (group grouped-backlinks)
-                  (let ((file-from (car group))
-                        (bls (cdr group)))
-                    (insert (format "** [[file:%s][%s]]\n"
-                                    file-from
-                                    (org-roam--get-title-or-slug file-from)))
-                    (dolist (backlink bls)
-                      (pcase-let ((`(,file-from _ ,props) backlink))
-                        (insert (propertize
-                                 (s-trim (s-replace "\n" " "
-                                                    (plist-get props :content)))
-                                 'help-echo "mouse-1: visit backlinked note"
-                                 'file-from file-from
-                                 'file-from-point (plist-get props :point)))
-                        (insert "\n\n"))))))
-            (insert "\n\n* No backlinks!")))
         (read-only-mode 1)))))
 
 (cl-defun org-roam--maybe-update-buffer (&key redisplay)
@@ -793,10 +839,12 @@ Otherwise, behave as if called interactively."
              (not (auto-save-file-name-p new-file))
              (org-roam--org-roam-file-p new-file))
     (org-roam-db--ensure-built)
-    (let* ((files-to-rename (org-roam-db-query [:select :distinct [file-from]
+    (let* ((files-to-rename (org-roam-db-query [:select :distinct [from]
-                                                        :from file-links
+                                                :from links
-                                                        :where (= file-to $s1)]
+                                                :where (= to $s1)
-                                               file))
+                                                :and (= type $s2)]
+                                               file
+                                               "roam"))
            (path (file-truename file))
            (new-path (file-truename new-file))
            (slug (org-roam--get-title-or-slug file))

tests/test-org-roam.el

@@ -61,7 +61,7 @@
 
     ;; Cache
     (expect (caar (org-roam-db-query [:select (funcall count) :from files])) :to-be 8)
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links])) :to-be 5)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links])) :to-be 5)
     (expect (caar (org-roam-db-query [:select (funcall count) :from titles])) :to-be 8)
     (expect (caar (org-roam-db-query [:select (funcall count) :from titles
                                       :where titles :is-null])) :to-be 2)
@@ -69,23 +69,23 @@
 
     ;; TODO Test files
 
-    ;; Links -- File-from
+    ;; Links
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 1)
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "nested/bar.org"))) :to-be 2)
 
     ;; Links -- File-to
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
-                                              :where (= file-to $s1)]
+                                      :where (= to $s1)]
                                      (org-roam-test-abs-path "nested/foo.org"))) :to-be 1)
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
-                                              :where (= file-to $s1)]
+                                      :where (= to $s1)]
                                      (org-roam-test-abs-path "nested/bar.org"))) :to-be 1)
-    (expect (caar (org-roam-db-query [:select (funcall count) :from file-links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
-                                              :where (= file-to $s1)]
+                                      :where (= to $s1)]
                                      (org-roam-test-abs-path "unlinked.org"))) :to-be 0)
     ;; TODO Test titles
     (expect (org-roam-db-query [:select * :from titles])
@@ -171,20 +171,20 @@
                                       :where (= file $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0)
     (expect (caar (org-roam-db-query [:select (funcall count)
-                                              :from file-links
+                                      :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0)
 
     ;; Cache should be updated
-    (expect (org-roam-db-query [:select [file-to]
+    (expect (org-roam-db-query [:select [to]
-                                        :from file-links
+                                :from links
-                                        :where (= file-from $s1)]
+                                :where (= from $s1)]
                                (org-roam-test-abs-path "new_foo.org"))
             :to-have-same-items-as
             (list (list (org-roam-test-abs-path "bar.org"))))
-    (expect (org-roam-db-query [:select [file-from]
+    (expect (org-roam-db-query [:select [from]
-                                        :from file-links
+                                :from links
-                                        :where (= file-to $s1)]
+                                :where (= to $s1)]
                                (org-roam-test-abs-path "new_foo.org"))
             :to-have-same-items-as
             (list (list (org-roam-test-abs-path "nested/bar.org"))))
@@ -209,20 +209,20 @@
                                       :where (= file $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0)
     (expect (caar (org-roam-db-query [:select (funcall count)
-                                              :from file-links
+                                      :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0)
 
     ;; Cache should be updated
-    (expect (org-roam-db-query [:select [file-to]
+    (expect (org-roam-db-query [:select [to]
-                                        :from file-links
+                                :from links
-                                        :where (= file-from $s1)]
+                                :where (= from $s1)]
                                (org-roam-test-abs-path "foo with spaces.org"))
             :to-have-same-items-as
             (list (list (org-roam-test-abs-path "bar.org"))))
-    (expect (org-roam-db-query [:select [file-from]
+    (expect (org-roam-db-query [:select [from]
-                                        :from file-links
+                                :from links
-                                        :where (= file-to $s1)]
+                                :where (= to $s1)]
                                (org-roam-test-abs-path "foo with spaces.org"))
             :to-have-same-items-as
             (list (list (org-roam-test-abs-path "nested/bar.org"))))
@@ -239,12 +239,12 @@
                  (org-roam-test-abs-path "meaningful-title.org"))
     ;; File has no forward links
     (expect (caar (org-roam-db-query [:select (funcall count)
-                                              :from file-links
+                                      :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "no-title.org"))) :to-be 0)
     (expect (caar (org-roam-db-query [:select (funcall count)
-                                              :from file-links
+                                      :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "meaningful-title.org"))) :to-be 1)
 
     ;; Links are updated with the appropriate name
@@ -292,8 +292,8 @@
                                       :where (= file $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0)
     (expect (caar (org-roam-db-query [:select (funcall count)
-                                              :from file-links
+                                      :from links
-                                              :where (= file-from $s1)]
+                                      :where (= from $s1)]
                                      (org-roam-test-abs-path "foo.org"))) :to-be 0))
 
   (it "delete web_ref"