From 01b75599a500d6276a962b47744166abb25d846c Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Tue, 28 Apr 2026 19:13:05 -0500
Subject: refactor: switch gloss-fetch result to uniform plist shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous shape (:ok DEFS) | (:empty :no-defs (...) :failed (...)) was malformed as a plist. The :empty tag at position 0 shifted the plist alignment. plist-get on :no-defs or :failed returned nil. Tests had to use (plist-get (cdr result) ...) as a workaround.

The new shape is a uniform plist with all three keys always present: (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)). Consumers branch on whether :defs is non-empty. There is no tag. plist-get works uniformly across success and empty cases.

Updated gloss-fetch.el (rollup function and docstrings), 7 test files, and the design doc (docs/design/gloss.org § Error Handling).

Tested by `make test`. 65 tests pass in 0.36 seconds.
---
 tests/test-gloss-fetch--definitions-200-returns-ok.el | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'tests/test-gloss-fetch--definitions-200-returns-ok.el')

diff --git a/tests/test-gloss-fetch--definitions-200-returns-ok.el b/tests/test-gloss-fetch--definitions-200-returns-ok.el
index fee997b..7ac34b9 100644
--- a/tests/test-gloss-fetch--definitions-200-returns-ok.el
+++ b/tests/test-gloss-fetch--definitions-200-returns-ok.el
@@ -4,7 +4,7 @@
 
 ;;; Commentary:
 ;; Normal/Boundary cases: a 200 response with valid JSON returns
-;; (:ok DEFS) and each def is a plist with :source and :text.  Uses the
+;; non-empty :defs in the rollup, and each def is a plist with :source and :text.  Uses the
 ;; captured Wiktionary fixtures replayed through a mocked
 ;; `url-retrieve-synchronously'.
 
@@ -17,13 +17,13 @@
 (require 'testutil-gloss-fetch)
 
 (ert-deftest test-gloss-fetch-definitions-200-anaphora-returns-ok ()
-  "Normal: anaphora fixture (single English sense) returns (:ok DEFS)."
+  "Normal: anaphora fixture (single English sense) returns non-empty :defs."
   (let ((body (gloss-test--load-wiktionary-fixture "anaphora")))
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let* ((result (gloss-fetch-definitions "anaphora"))
-             (defs (plist-get result :ok)))
-        (should (eq (car result) :ok))
+             (defs (plist-get result :defs)))
+        (should (plist-get result :defs))
         (should (consp defs))
         (should (>= (length defs) 1))
         (let ((first (car defs)))
@@ -39,8 +39,8 @@
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let* ((result (gloss-fetch-definitions "SBIR"))
-             (defs (plist-get result :ok)))
-        (should (eq (car result) :ok))
+             (defs (plist-get result :defs)))
+        (should (plist-get result :defs))
         (should (>= (length defs) 1))
         (dolist (d defs)
           (should (eq (plist-get d :source) 'wiktionary))
-- 
cgit v1.2.3