refactor: switch gloss-fetch result to uniform plist shapeHEADmain

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.

7 files changed, 39 insertions, 39 deletions

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))
diff --git a/tests/test-gloss-fetch--definitions-404-returns-no-defs.el b/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
index 28587ac..1700e79 100644
--- a/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
+++ b/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
@@ -15,24 +15,24 @@
 (require 'testutil-gloss-fetch)
 
 (ert-deftest test-gloss-fetch-definitions-404-rolls-up-to-empty-no-defs ()
-  "Normal: a 404 from the only source rolls up to (:empty :no-defs (wiktionary) :failed nil)."
+  "Normal: a 404 from the only source rolls up with :no-defs = (wiktionary), :failed and :defs = nil."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 404 Not Found"
                                            "{\"detail\":\"Page not found\"}"))
     (let ((result (gloss-fetch-definitions "asdf-not-a-word")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :no-defs)))
-      (should-not (plist-get (cdr result) :failed)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :no-defs)))
+      (should-not (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-definitions-200-empty-rolls-up-to-empty-no-defs ()
   "Boundary: a 200 with an empty JSON object also maps to :no-defs."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) (gloss-fetch-test--ok-response "{}"))
     (let ((result (gloss-fetch-definitions "term")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :no-defs)))
-      (should-not (plist-get (cdr result) :failed)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :no-defs)))
+      (should-not (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-definitions-200-no-english-rolls-up-to-no-defs ()
   "Boundary: a 200 response with only non-English keys maps to :no-defs."
@@ -41,8 +41,8 @@
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let ((result (gloss-fetch-definitions "term")))
-        (should (eq (car result) :empty))
-        (should (member 'wiktionary (plist-get (cdr result) :no-defs)))))))
+        (should-not (plist-get result :defs))
+        (should (member 'wiktionary (plist-get result :no-defs)))))))
 
 (provide 'test-gloss-fetch--definitions-404-returns-no-defs)
 ;;; test-gloss-fetch--definitions-404-returns-no-defs.el ends here
diff --git a/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el b/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
index cd2d2d4..84e6f49 100644
--- a/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
+++ b/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
@@ -20,9 +20,9 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 429 Too Many Requests" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-429-tracked-separately-internally ()
   "Boundary: per-source status taxonomy distinguishes :rate-limited from :server-error.
diff --git a/tests/test-gloss-fetch--definitions-500-returns-server-error.el b/tests/test-gloss-fetch--definitions-500-returns-server-error.el
index 20e988b..54664f3 100644
--- a/tests/test-gloss-fetch--definitions-500-returns-server-error.el
+++ b/tests/test-gloss-fetch--definitions-500-returns-server-error.el
@@ -21,9 +21,9 @@
         (gloss-fetch-test--status-response "HTTP/1.1 500 Internal Server Error"
                                            "Server is sad."))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-503-rolls-up-to-failed ()
   "Normal: HTTP 503 maps the source to :server-error (in :failed)."
@@ -31,16 +31,16 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 503 Service Unavailable" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (ert-deftest test-gloss-fetch-definitions-malformed-json-rolls-up-to-failed ()
   "Boundary: a 200 with non-JSON body also maps to :server-error."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) (gloss-fetch-test--ok-response "<html>not json</html>"))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (ert-deftest test-gloss-fetch-definitions-400-rolls-up-to-failed ()
   "Error: HTTP 400 (4xx other than 404/429) maps to :server-error (in :failed)."
@@ -48,8 +48,8 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 400 Bad Request" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (provide 'test-gloss-fetch--definitions-500-returns-server-error)
 ;;; test-gloss-fetch--definitions-500-returns-server-error.el ends here
diff --git a/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el b/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
index 8067dde..8bd0019 100644
--- a/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
+++ b/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
@@ -19,9 +19,9 @@
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) nil)
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-timeout-marks-source-unreachable ()
   "Boundary: per-source status is :unreachable, distinct from :server-error."
diff --git a/tests/test-gloss-fetch--libxml-probe.el b/tests/test-gloss-fetch--libxml-probe.el
index 758c185..1d8b7ed 100644
--- a/tests/test-gloss-fetch--libxml-probe.el
+++ b/tests/test-gloss-fetch--libxml-probe.el
@@ -57,8 +57,8 @@
       (gloss-fetch-test--with-mocked-url
           (lambda (_url) (gloss-fetch-test--ok-response "{}"))
         (let ((result (gloss-fetch-definitions "term")))
-          (should (eq (car result) :empty))
-          (should (member 'wiktionary (plist-get (cdr result) :no-defs))))))))
+          (should-not (plist-get result :defs))
+          (should (member 'wiktionary (plist-get result :no-defs))))))))
 
 (provide 'test-gloss-fetch--libxml-probe)
 ;;; test-gloss-fetch--libxml-probe.el ends here
diff --git a/tests/test-gloss-fetch--multi-source-walks-registry.el b/tests/test-gloss-fetch--multi-source-walks-registry.el
index cb2b730..482cc40 100644
--- a/tests/test-gloss-fetch--multi-source-walks-registry.el
+++ b/tests/test-gloss-fetch--multi-source-walks-registry.el
@@ -42,12 +42,12 @@
                        (list :source 'beta :status :server-error :reason "HTTP 503")))))
          (gloss-fetch-sources '(alpha beta))
          (result (gloss-fetch-definitions "x")))
-    (should (eq (car result) :empty))
-    (should (member 'alpha (plist-get (cdr result) :no-defs)))
-    (should (member 'beta (plist-get (cdr result) :failed)))))
+    (should-not (plist-get result :defs))
+    (should (member 'alpha (plist-get result :no-defs)))
+    (should (member 'beta (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-rollup-any-ok-yields-ok ()
-  "Boundary: if any source returns :ok with defs, the rollup is (:ok DEFS)."
+  "Boundary: if any source returns :ok with defs, the rollup has non-empty :defs."
   (let* ((gloss-fetch--sources
           `((alpha . ,(lambda (_term)
                         (list :source 'alpha :status :no-defs :reason "404")))
@@ -56,9 +56,9 @@
                              (list (list :source 'beta :text "got it")))))))
          (gloss-fetch-sources '(alpha beta))
          (result (gloss-fetch-definitions "x")))
-    (should (eq (car result) :ok))
-    (should (= 1 (length (plist-get result :ok))))
-    (should (equal "got it" (plist-get (car (plist-get result :ok)) :text)))))
+    (should (plist-get result :defs))
+    (should (= 1 (length (plist-get result :defs))))
+    (should (equal "got it" (plist-get (car (plist-get result :defs)) :text)))))
 
 (ert-deftest test-gloss-fetch-collect-skips-source-not-in-defcustom ()
   "Error: a source registered in `gloss-fetch--sources' but not in `gloss-fetch-sources' is skipped."