feat: pearl — manage Linear issues from org-mode

Pearl fetches Linear issues into an org file and syncs edits back. It covers list / custom views / saved queries, per-issue and bulk rendering with comments inline, conflict-aware sync of descriptions, titles, and comments, field commands for priority / state / assignee / labels, and a transient dispatch menu. The render folds to a scannable outline and nests issues under a sortable parent.

Based on and inspired by Gael Blanchemain's linear-emacs.

1 files changed, 153 insertions, 0 deletions

diff --git a/tests/test-pearl-fields.el b/tests/test-pearl-fields.el
new file mode 100644
index 0000000..7322e4f
--- /dev/null
+++ b/tests/test-pearl-fields.el
@@ -0,0 +1,153 @@
+;;; test-pearl-fields.el --- Tests for command-managed drawer fields -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2026 Craig Jennings
+
+;; Author: Craig Jennings <c@cjennings.net>
+
+;; 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 command-managed drawer fields that need no name->id
+;; resolution helper: set-priority and set-state.  Covers the generic
+;; issueUpdate helper (stubbed at the HTTP boundary), the heading cookie and
+;; keyword/drawer mutators, and the two commands' push + buffer-update paths.
+
+;;; Code:
+
+(require 'test-bootstrap (expand-file-name "test-bootstrap.el"))
+(require 'testutil-request (expand-file-name "testutil-request.el"))
+(require 'cl-lib)
+
+(defmacro test-pearl--in-org (content &rest body)
+  "Run BODY in an org-mode temp buffer holding CONTENT, default mapping bound."
+  (declare (indent 1))
+  `(let ((pearl-state-to-todo-mapping
+          '(("Todo" . "TODO") ("In Progress" . "IN-PROGRESS") ("Done" . "DONE")))
+         (org-todo-keywords '((sequence "TODO" "IN-PROGRESS" "|" "DONE"))))
+     (with-temp-buffer
+       (insert ,content)
+       (org-mode)
+       (goto-char (point-min))
+       ,@body)))
+
+;;; --update-issue-async (generic issueUpdate)
+
+(ert-deftest test-pearl-update-issue-async-success ()
+  "A successful generic issueUpdate reports success and the timestamp."
+  (testutil-linear-with-response
+      '((data (issueUpdate (success . t) (issue (id . "a") (updatedAt . "t1")))))
+    (let (result)
+      (pearl--update-issue-async "a" '(("priority" . 2)) (lambda (r) (setq result r)))
+      (should (eq t (plist-get result :success)))
+      (should (string= "t1" (plist-get result :updated-at))))))
+
+(ert-deftest test-pearl-update-issue-async-soft-fail ()
+  "A non-success generic issueUpdate reports failure rather than erroring."
+  (testutil-linear-with-response
+      '((data (issueUpdate (success . :json-false) (issue . nil))))
+    (let ((called nil) result)
+      (pearl--update-issue-async "a" '(("priority" . 2)) (lambda (r) (setq called t result r)))
+      (should called)
+      (should-not (plist-get result :success)))))
+
+;;; --set-priority-cookie
+
+(ert-deftest test-pearl-set-priority-cookie-replaces ()
+  "Setting a priority rewrites the heading cookie."
+  (test-pearl--in-org "*** TODO [#C] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\n"
+    (pearl--set-priority-cookie 1)
+    (goto-char (point-min))
+    (should (string-match-p "^\\*\\*\\* TODO \\[#A\\] Title" (thing-at-point 'line t)))))
+
+(ert-deftest test-pearl-set-priority-cookie-low ()
+  "Low priority renders the #D cookie."
+  (test-pearl--in-org "*** TODO [#C] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\n"
+    (pearl--set-priority-cookie 4)
+    (goto-char (point-min))
+    (should (string-match-p "^\\*\\*\\* TODO \\[#D\\] Title" (thing-at-point 'line t)))))
+
+(ert-deftest test-pearl-set-priority-cookie-none-removes ()
+  "Priority None removes the cookie."
+  (test-pearl--in-org "*** TODO [#C] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\n"
+    (pearl--set-priority-cookie 0)
+    (goto-char (point-min))
+    (should (string-match-p "^\\*\\*\\* TODO Title" (thing-at-point 'line t)))
+    (should-not (string-match-p "\\[#" (thing-at-point 'line t)))))
+
+;;; pearl-set-priority
+
+(ert-deftest test-pearl-set-priority-pushes-and-updates-cookie ()
+  "Setting priority pushes the numeric value and rewrites the cookie."
+  (let ((pushed nil))
+    (test-pearl--in-org "*** TODO [#C] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\n"
+      (cl-letf (((symbol-function 'pearl--update-issue-async)
+                 (lambda (_id input cb) (setq pushed input) (funcall cb '(:success t)))))
+        (re-search-forward "Title")
+        (pearl-set-priority "High")
+        (should (equal 2 (cdr (assoc "priority" pushed))))
+        (goto-char (point-min))
+        (should (string-match-p "\\[#B\\]" (thing-at-point 'line t)))))))
+
+(ert-deftest test-pearl-set-priority-not-on-issue-errors ()
+  "Setting priority outside a Linear issue heading signals a user error."
+  (test-pearl--in-org "* Plain heading\nno id\n"
+    (should-error (pearl-set-priority "High") :type 'user-error)))
+
+;;; --set-heading-state
+
+(ert-deftest test-pearl-set-heading-state-updates-keyword-and-drawer ()
+  "Setting the heading state updates the TODO keyword and the LINEAR-STATE drawer."
+  (test-pearl--in-org
+      "*** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:LINEAR-STATE-ID: old\n:LINEAR-STATE-NAME: Todo\n:END:\n"
+    (pearl--set-heading-state "In Progress" "s2")
+    (goto-char (point-min))
+    (should (string-match-p "^\\*\\*\\* IN-PROGRESS " (thing-at-point 'line t)))
+    (should (string= "In Progress" (org-entry-get nil "LINEAR-STATE-NAME")))
+    (should (string= "s2" (org-entry-get nil "LINEAR-STATE-ID")))))
+
+(ert-deftest test-pearl-set-heading-state-does-not-fire-sync-hook ()
+  "Setting the keyword must not trigger the Linear org-todo sync hook."
+  (let ((fired nil))
+    (test-pearl--in-org
+        "*** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\n"
+      (let ((org-after-todo-state-change-hook (list (lambda () (setq fired t)))))
+        (pearl--set-heading-state "Done" "s3")
+        (should-not fired)))))
+
+;;; pearl-set-state
+
+(ert-deftest test-pearl-set-state-pushes-id-and-updates-heading ()
+  "Setting state resolves the name to an id, pushes it, and updates the heading."
+  (let ((pushed nil))
+    (test-pearl--in-org
+        "*** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:LINEAR-TEAM-ID: team-1\n:END:\n"
+      (cl-letf (((symbol-function 'pearl--team-states)
+                 (lambda (_team) '(((id . "s1") (name . "Todo"))
+                                   ((id . "s2") (name . "In Progress")))))
+                ((symbol-function 'pearl--update-issue-async)
+                 (lambda (_id input cb) (setq pushed input) (funcall cb '(:success t)))))
+        (pearl-set-state "In Progress")
+        (should (string= "s2" (cdr (assoc "stateId" pushed))))
+        (goto-char (point-min))
+        (should (string-match-p "^\\*\\*\\* IN-PROGRESS " (thing-at-point 'line t)))
+        (should (string= "In Progress" (org-entry-get nil "LINEAR-STATE-NAME")))))))
+
+(ert-deftest test-pearl-set-state-not-on-issue-errors ()
+  "Setting state outside a Linear issue heading signals a user error."
+  (test-pearl--in-org "* Plain heading\nno id\n"
+    (should-error (pearl-set-state "Done") :type 'user-error)))
+
+(provide 'test-pearl-fields)
+;;; test-pearl-fields.el ends here