feat: make comment sort order configurable, newest-first by defaultHEADmain

I added pearl-comment-sort-order to choose how an issue's comments render under the Comments heading: newest-first (the default, most recent on top) or oldest-first (chronological, like an email thread). Both the render sort and the add-comment insertion point honor it, so a new comment lands at the top for newest-first and at the bottom for oldest-first.

2 files changed, 50 insertions, 26 deletions

diff --git a/tests/test-pearl-comments.el b/tests/test-pearl-comments.el
index d335132..85d1c84 100644
--- a/tests/test-pearl-comments.el
+++ b/tests/test-pearl-comments.el
@@ -20,9 +20,9 @@
 ;;; Commentary:
 
 ;; Tests for the comment thread: rendering a normalized comment and the
-;; oldest-first Comments subtree, including comments in the issue render, the
-;; commentCreate helper (stubbed at the HTTP boundary), the in-place append
-;; under the Comments subtree (creating it when absent), and the
+;; Comments subtree (ordered per `pearl-comment-sort-order'), including comments
+;; in the issue render, the commentCreate helper (stubbed at the HTTP boundary),
+;; the in-place append under the Comments subtree (creating it when absent), and the
 ;; `pearl-add-comment' command.
 
 ;;; Code:
@@ -64,12 +64,22 @@
   "No comments renders nothing (no empty Comments subtree)."
   (should (string= "" (pearl--format-comments nil))))
 
-(ert-deftest test-pearl-format-comments-oldest-first ()
-  "Comments render under a Comments heading, oldest first regardless of input order."
-  (let ((out (pearl--format-comments
-              '((:id "c2" :author "B" :created-at "2026-05-23T12:00:00.000Z" :body "second")
-                (:id "c1" :author "A" :created-at "2026-05-23T09:00:00.000Z" :body "first")))))
+(defconst test-pearl--two-comments
+  '((:id "c1" :author "A" :created-at "2026-05-23T09:00:00.000Z" :body "first")
+    (:id "c2" :author "B" :created-at "2026-05-23T12:00:00.000Z" :body "second"))
+  "Two comments, c1 older than c2, in input order regardless of render order.")
+
+(ert-deftest test-pearl-format-comments-newest-first ()
+  "With newest-first order, the most recent comment renders on top."
+  (let* ((pearl-comment-sort-order 'newest-first)
+         (out (pearl--format-comments test-pearl--two-comments)))
     (should (string-match-p "^\\*\\*\\* Comments$" out))
+    (should (< (string-match "second" out) (string-match "first" out)))))
+
+(ert-deftest test-pearl-format-comments-oldest-first ()
+  "With oldest-first order, comments render chronologically, oldest on top."
+  (let* ((pearl-comment-sort-order 'oldest-first)
+         (out (pearl--format-comments test-pearl--two-comments)))
     (should (< (string-match "first" out) (string-match "second" out)))))
 
 ;;; comments in the issue render
@@ -121,19 +131,32 @@
     (should (re-search-forward "^\\*\\*\\* Comments$" nil t))
     (should (re-search-forward "first comment" nil t))))
 
-(ert-deftest test-pearl-append-comment-after-existing ()
-  "A new comment appends after an existing one under the Comments subtree."
-  (test-pearl--in-org
-      "** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\nBody.\n*** Comments\n**** A — 2026-05-23T09:00:00.000Z\nfirst\n"
-    (pearl--append-comment-to-issue
-     '(:id "c2" :author "B" :created-at "2026-05-23T12:00:00.000Z" :body "second"))
-    (goto-char (point-min))
-    ;; only one Comments heading, and the new comment follows the first
-    (should (re-search-forward "^\\*\\*\\* Comments$" nil t))
-    (should-not (re-search-forward "^\\*\\*\\* Comments$" nil t))
-    (goto-char (point-min))
-    (should (< (progn (re-search-forward "first") (point))
-               (progn (re-search-forward "second") (point))))))
+(ert-deftest test-pearl-append-comment-newest-first-inserts-at-top ()
+  "With newest-first order, a new comment lands above the existing ones."
+  (let ((pearl-comment-sort-order 'newest-first))
+    (test-pearl--in-org
+        "** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\nBody.\n*** Comments\n**** A — 2026-05-23T09:00:00.000Z\nfirst\n"
+      (pearl--append-comment-to-issue
+       '(:id "c2" :author "B" :created-at "2026-05-23T12:00:00.000Z" :body "second"))
+      (goto-char (point-min))
+      ;; still exactly one Comments heading
+      (should (re-search-forward "^\\*\\*\\* Comments$" nil t))
+      (should-not (re-search-forward "^\\*\\*\\* Comments$" nil t))
+      (goto-char (point-min))
+      ;; the new comment is above the existing one
+      (should (< (progn (re-search-forward "second") (point))
+                 (progn (re-search-forward "first") (point)))))))
+
+(ert-deftest test-pearl-append-comment-oldest-first-appends-at-bottom ()
+  "With oldest-first order, a new comment appends after the existing ones."
+  (let ((pearl-comment-sort-order 'oldest-first))
+    (test-pearl--in-org
+        "** TODO [#B] Title\n:PROPERTIES:\n:LINEAR-ID: a\n:END:\nBody.\n*** Comments\n**** A — 2026-05-23T09:00:00.000Z\nfirst\n"
+      (pearl--append-comment-to-issue
+       '(:id "c2" :author "B" :created-at "2026-05-23T12:00:00.000Z" :body "second"))
+      (goto-char (point-min))
+      (should (< (progn (re-search-forward "first") (point))
+                 (progn (re-search-forward "second") (point)))))))
 
 ;;; pearl-add-comment
 
diff --git a/tests/test-pearl-list-comments.el b/tests/test-pearl-list-comments.el
index 630c712..be0880e 100644
--- a/tests/test-pearl-list-comments.el
+++ b/tests/test-pearl-list-comments.el
@@ -98,13 +98,14 @@
 
 ;;; --format-comments with a marker
 
-(ert-deftest test-pearl-format-comments-renders-marker-and-oldest-first ()
-  "With count-info, the Comments heading carries the marker; bodies stay oldest-first."
-  (let* ((comments (test-pearl--comments 5))     ; newest-first as fetched
+(ert-deftest test-pearl-format-comments-renders-marker-and-order ()
+  "With count-info the Comments heading carries the marker; bodies honor the sort order."
+  (let* ((pearl-comment-sort-order 'newest-first)
+         (comments (test-pearl--comments 5))     ; newest-first as fetched
          (out (pearl--format-comments comments '(:shown 5 :total 12 :overflow nil))))
     (should (string-match-p "^\\*\\*\\* Comments 💬 5/12$" out))
-    ;; oldest (comment 1) renders before newest (comment 5)
-    (should (< (string-match "comment 1\\b" out) (string-match "comment 5\\b" out)))))
+    ;; newest (comment 5) renders before oldest (comment 1)
+    (should (< (string-match "comment 5\\b" out) (string-match "comment 1\\b" out)))))
 
 (ert-deftest test-pearl-format-comments-no-marker-without-count ()
   "Without count-info (the single-issue thread), the heading has no marker."