chore: coverage, autoload fix, and internal cleanup for org-drill

A batch of test-coverage and hardening work, squashed from the test-work branch.

Tests: deduplicated a colliding leitner-capture test name so make test-name loads again. Added SM2 assert-failure cases, the six basic multicloze variant delegations, the three English-side spanish-verb branches, and org-drill-current-scope branch coverage.

Fix: the entry-point commands (org-drill itself, cram-tree, tree, directory, resume, relearn-item, strip-all-data, merge-buffers) carried no autoload cookies, so M-x failed from a fresh install until something pulled the file in. They're autoloaded now.

Perf: org-drill-shuffle was quadratic because it indexed a list with elt on every swap. It runs a linear Fisher-Yates pass over a vector now, and it checks its argument is a list.

Feat: added org-drill-version, a constant plus an interactive command, so a bug reporter doesn't have to open the file header.

Refactor: extracted org-drill--format-tense-mood, shared by the two verb-conjugation presenters that each carried a copy.

Docs: explained the SM8 magic numbers in the simple8 helpers as empirical fits rather than tunable knobs.

10 files changed, 277 insertions, 4 deletions

diff --git a/tests/test-org-drill-autoloads.el b/tests/test-org-drill-autoloads.el
new file mode 100644
index 0000000..5bfefce
--- /dev/null
+++ b/tests/test-org-drill-autoloads.el
@@ -0,0 +1,47 @@
+;;; test-org-drill-autoloads.el --- Autoload-cookie coverage  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; The user-facing entry-point commands must carry an `;;;###autoload' cookie
+;; so they work from a fresh package install before org-drill is loaded.
+;; Without it, `M-x org-drill-resume' (etc.) fails with "command not found"
+;; until something pulls the file in.
+;;
+;; This reads the source via `find-library-name' (the .el, not a compiled
+;; .elc which would have the cookies stripped) and checks each command.
+
+;;; Code:
+
+(require 'ert)
+(require 'org-drill)
+
+(defconst test-org-drill-autoloaded-commands
+  '("org-drill"
+    "org-drill-cram"
+    "org-drill-cram-tree"
+    "org-drill-tree"
+    "org-drill-directory"
+    "org-drill-again"
+    "org-drill-resume"
+    "org-drill-relearn-item"
+    "org-drill-strip-all-data"
+    "org-drill-merge-buffers")
+  "Entry-point commands that should be autoloaded.")
+
+(ert-deftest test-org-drill-entry-commands-carry-autoload-cookie ()
+  "Each user-facing entry-point command is preceded by an autoload cookie."
+  (let ((src (with-temp-buffer
+               (insert-file-contents (find-library-name "org-drill"))
+               (buffer-string))))
+    (dolist (cmd test-org-drill-autoloaded-commands)
+      (should (string-match-p
+               (concat ";;;###autoload\n(defun " (regexp-quote cmd) " ")
+               src)))))
+
+(ert-deftest test-org-drill-entry-commands-are-interactive ()
+  "Every command in the autoload list is actually an interactive command."
+  (dolist (cmd test-org-drill-autoloaded-commands)
+    (should (commandp (intern cmd)))))
+
+(provide 'test-org-drill-autoloads)
+
+;;; test-org-drill-autoloads.el ends here
diff --git a/tests/test-org-drill-current-scope.el b/tests/test-org-drill-current-scope.el
new file mode 100644
index 0000000..9743c5f
--- /dev/null
+++ b/tests/test-org-drill-current-scope.el
@@ -0,0 +1,48 @@
+;;; test-org-drill-current-scope.el --- Tests for org-drill-current-scope  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; org-drill-current-scope translates a drill scope into the scope argument
+;; org-map-entries expects, and org-drill-map-entries delegates to it.  The
+;; map-entries mapping itself and drill-match filtering are covered in
+;; test-org-drill.el (find-entries / find-tagged-entries); this file covers
+;; the scope-translation branches, which had no tests.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+(require 'org-drill)
+
+(ert-deftest test-org-drill-current-scope-file-returns-nil ()
+  "Scope `file' maps to nil — the current buffer, respecting narrowing."
+  (should (null (org-drill-current-scope 'file))))
+
+(ert-deftest test-org-drill-current-scope-file-no-restriction-returns-file ()
+  "Scope `file-no-restriction' maps to `file' — whole buffer, ignoring narrowing."
+  (should (eq 'file (org-drill-current-scope 'file-no-restriction))))
+
+(ert-deftest test-org-drill-current-scope-custom-symbol-passes-through ()
+  "An unrecognized scope such as `tree' is returned unchanged."
+  (should (eq 'tree (org-drill-current-scope 'tree))))
+
+(ert-deftest test-org-drill-current-scope-nil-falls-back-to-org-drill-scope ()
+  "A nil scope falls back to the value of `org-drill-scope'."
+  (let ((org-drill-scope 'tree))
+    (should (eq 'tree (org-drill-current-scope nil)))))
+
+(ert-deftest test-org-drill-current-scope-directory-lists-org-files ()
+  "Scope `directory' returns the .org files in the current file's directory."
+  (let (captured-dir)
+    (cl-letf (((symbol-function 'buffer-file-name)
+               (lambda (&rest _) "/tmp/deck/cards.org"))
+              ((symbol-function 'directory-files)
+               (lambda (dir _full _match)
+                 (setq captured-dir dir)
+                 '("/tmp/deck/a.org" "/tmp/deck/b.org"))))
+      (let ((result (org-drill-current-scope 'directory)))
+        (should (equal "/tmp/deck/" captured-dir))
+        (should (equal '("/tmp/deck/a.org" "/tmp/deck/b.org") result))))))
+
+(provide 'test-org-drill-current-scope)
+
+;;; test-org-drill-current-scope.el ends here
diff --git a/tests/test-org-drill-determine-next-interval-sm2.el b/tests/test-org-drill-determine-next-interval-sm2.el
index 622744d..3bf5cf3 100644
--- a/tests/test-org-drill-determine-next-interval-sm2.el
+++ b/tests/test-org-drill-determine-next-interval-sm2.el
@@ -417,5 +417,26 @@ Simulates inconsistent learning."
     (should (= interval-2 -1))
     (should (= failures-2 1))))
 
+;;; Error Cases - cl-assert invariant violations
+
+;; The function asserts (> n 0) and (and (>= quality 0) (<= quality 5)).
+;; n is normalized from 0 to 1 first, so only a negative n trips its assert.
+
+(ert-deftest test-org-drill-determine-next-interval-sm2-error-quality-above-max ()
+  "Quality above the 0-5 range trips the quality assertion."
+  (should-error (org-drill-determine-next-interval-sm2 1 2 2.5 6 0 4.0 1)
+                :type 'cl-assertion-failed))
+
+(ert-deftest test-org-drill-determine-next-interval-sm2-error-quality-below-min ()
+  "Quality below the 0-5 range trips the quality assertion."
+  (should-error (org-drill-determine-next-interval-sm2 1 2 2.5 -1 0 4.0 1)
+                :type 'cl-assertion-failed))
+
+(ert-deftest test-org-drill-determine-next-interval-sm2-error-negative-n ()
+  "A negative repeat count trips the (> n 0) assertion.  Note n=0 is
+normalized to 1 before the assert, so zero is not an error case."
+  (should-error (org-drill-determine-next-interval-sm2 1 -1 2.5 4 0 4.0 1)
+                :type 'cl-assertion-failed))
+
 (provide 'test-org-drill-determine-next-interval-sm2)
 ;;; test-org-drill-determine-next-interval-sm2.el ends here
diff --git a/tests/test-org-drill-final-helpers.el b/tests/test-org-drill-final-helpers.el
index c9cb0a3..b09efb7 100644
--- a/tests/test-org-drill-final-helpers.el
+++ b/tests/test-org-drill-final-helpers.el
@@ -111,8 +111,8 @@ matches leitner-tagged entries)."
         (should (null org-drill-leitner-boxed-entries))
         (should (null org-drill-leitner-unboxed-entries))))))
 
-(ert-deftest test-map-leitner-capture-non-drill-entry-skipped ()
-  "Non-drill entries (no :drill: tag inheritance) are skipped silently."
+(ert-deftest test-map-leitner-capture-untagged-heading-skipped ()
+  "A heading carrying no drill/leitner tag is skipped silently."
   (with-org-buffer "* Plain heading\n"
     (let ((session (org-drill-session))
           (org-drill-leitner-boxed-entries nil)
diff --git a/tests/test-org-drill-language-presenters.el b/tests/test-org-drill-language-presenters.el
index 6375b5f..da0a3a8 100644
--- a/tests/test-org-drill-language-presenters.el
+++ b/tests/test-org-drill-language-presenters.el
@@ -154,6 +154,25 @@
          (lambda (_) (setq reschedule-called t))))
       (should reschedule-called))))
 
+;;;; org-drill--format-tense-mood
+
+(ert-deftest test-org-drill-format-tense-mood-both ()
+  "With both tense and mood, the label names both."
+  (should (equal "past tense, subjunctive mood"
+                 (org-drill--format-tense-mood "past" "subjunctive"))))
+
+(ert-deftest test-org-drill-format-tense-mood-tense-only ()
+  "With only a tense, the label names the tense."
+  (should (equal "present tense" (org-drill--format-tense-mood "present" nil))))
+
+(ert-deftest test-org-drill-format-tense-mood-mood-only ()
+  "With only a mood, the label names the mood."
+  (should (equal "imperative mood" (org-drill--format-tense-mood nil "imperative"))))
+
+(ert-deftest test-org-drill-format-tense-mood-neither-is-nil ()
+  "With neither tense nor mood, there is no label."
+  (should (null (org-drill--format-tense-mood nil nil))))
+
 (provide 'test-org-drill-language-presenters)
 
 ;;; test-org-drill-language-presenters.el ends here
diff --git a/tests/test-org-drill-map-leitner-capture.el b/tests/test-org-drill-map-leitner-capture.el
index bc43c7d..114f51e 100644
--- a/tests/test-org-drill-map-leitner-capture.el
+++ b/tests/test-org-drill-map-leitner-capture.el
@@ -60,8 +60,8 @@
       (should (= 0 (length org-drill-leitner-boxed-entries)))
       (should (= 0 (length org-drill-leitner-unboxed-entries))))))
 
-(ert-deftest test-map-leitner-capture-non-drill-entry-skipped ()
-  "Non-drill heading is skipped entirely."
+(ert-deftest test-map-leitner-capture-no-headline-skipped ()
+  "A buffer with no headline at all is skipped entirely."
   (with-leitner-tempfile "Just text, no headlines\n"
     (let ((session (org-drill-session))
           (org-drill-question-tag org-drill-leitner-tag))
diff --git a/tests/test-org-drill-multicloze-dispatch.el b/tests/test-org-drill-multicloze-dispatch.el
index e871105..99861c7 100644
--- a/tests/test-org-drill-multicloze-dispatch.el
+++ b/tests/test-org-drill-multicloze-dispatch.el
@@ -138,6 +138,68 @@ piece is guaranteed not to be the first)."
                (args (cdr call)))
           (should (eq -1 (nth 1 args))))))))
 
+;;;; Basic variants — delegation contract
+;;
+;; hide1/hide2/hide-first/hide-last are thin wrappers.  The hiding
+;; mechanics they delegate to (hide-n / hide-nth) are exercised directly
+;; in test-org-drill-multicloze-hiding.el, so re-driving present-and-reveal
+;; here would just re-test those.  What's untested is the wiring: which
+;; delegate each variant calls and with what argument.
+
+(ert-deftest test-multicloze-hide1-delegates-to-hide-n-1 ()
+  "hide1 hides one piece: delegates to hide-n with number-to-hide = 1."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-n)
+                 (lambda (_session n &rest _) (setq recorded n) t)))
+        (org-drill-present-multicloze-hide1 (org-drill-session))
+        (should (eql 1 recorded))))))
+
+(ert-deftest test-multicloze-hide2-delegates-to-hide-n-2 ()
+  "hide2 hides two pieces: delegates to hide-n with number-to-hide = 2."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-n)
+                 (lambda (_session n &rest _) (setq recorded n) t)))
+        (org-drill-present-multicloze-hide2 (org-drill-session))
+        (should (eql 2 recorded))))))
+
+(ert-deftest test-multicloze-hide-first-delegates-to-hide-nth-1 ()
+  "hide-first hides the first piece: delegates to hide-nth with 1."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-nth)
+                 (lambda (_session nth &rest _) (setq recorded nth) t)))
+        (org-drill-present-multicloze-hide-first (org-drill-session))
+        (should (eql 1 recorded))))))
+
+(ert-deftest test-multicloze-hide-last-delegates-to-hide-nth-last ()
+  "hide-last hides the last piece: delegates to hide-nth with -1."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-nth)
+                 (lambda (_session nth &rest _) (setq recorded nth) t)))
+        (org-drill-present-multicloze-hide-last (org-drill-session))
+        (should (eql -1 recorded))))))
+
+(ert-deftest test-multicloze-show1-delegates-to-hide-n-minus-1 ()
+  "show1 reveals one piece (hides the rest): delegates to hide-n with -1."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-n)
+                 (lambda (_session n &rest _) (setq recorded n) t)))
+        (org-drill-present-multicloze-show1 (org-drill-session))
+        (should (eql -1 recorded))))))
+
+(ert-deftest test-multicloze-show2-delegates-to-hide-n-minus-2 ()
+  "show2 reveals two pieces: delegates to hide-n with -2."
+  (with-fresh-drill-entry
+    (let (recorded)
+      (cl-letf (((symbol-function 'org-drill-present-multicloze-hide-n)
+                 (lambda (_session n &rest _) (setq recorded n) t)))
+        (org-drill-present-multicloze-show2 (org-drill-session))
+        (should (eql -2 recorded))))))
+
 (provide 'test-org-drill-multicloze-dispatch)
 
 ;;; test-org-drill-multicloze-dispatch.el ends here
diff --git a/tests/test-org-drill-spanish-and-top-level.el b/tests/test-org-drill-spanish-and-top-level.el
index 61fc546..465d82f 100644
--- a/tests/test-org-drill-spanish-and-top-level.el
+++ b/tests/test-org-drill-spanish-and-top-level.el
@@ -88,6 +88,48 @@ hablo, hablas, ...
         (org-drill-present-spanish-verb (org-drill-session))
         (should (string-match-p "future perfect" shown-prompt))))))
 
+(ert-deftest test-present-spanish-verb-branch-1-present-tense-conjugate ()
+  "Branch 1 reveals the English side and asks to conjugate the present tense."
+  (with-card-buffer "* Verb :drill:\n** Infinitive\nhablar\n** English\nto speak\n** Present Tense\nfoo\n"
+    (let ((shown-prompt nil))
+      (cl-letf (((symbol-function 'cl-random) (lambda (_) 1))
+                ((symbol-function 'org-drill-presentation-prompt)
+                 (lambda (_session &optional prompt &rest _)
+                   (setq shown-prompt prompt) t))
+                ((symbol-function 'org-drill--show-latex-fragments) #'ignore)
+                ((symbol-function 'org-display-inline-images) #'ignore))
+        (org-drill-present-spanish-verb (org-drill-session))
+        (should (string-match-p "present.* tense" shown-prompt))
+        (should (string-match-p "English verb" shown-prompt))))))
+
+(ert-deftest test-present-spanish-verb-branch-3-past-tense-conjugate ()
+  "Branch 3 reveals the English side and asks to conjugate the past tense."
+  (with-card-buffer "* Verb :drill:\n** Infinitive\nhablar\n** English\nto speak\n** Past Tense\nfoo\n"
+    (let ((shown-prompt nil))
+      (cl-letf (((symbol-function 'cl-random) (lambda (_) 3))
+                ((symbol-function 'org-drill-presentation-prompt)
+                 (lambda (_session &optional prompt &rest _)
+                   (setq shown-prompt prompt) t))
+                ((symbol-function 'org-drill--show-latex-fragments) #'ignore)
+                ((symbol-function 'org-display-inline-images) #'ignore))
+        (org-drill-present-spanish-verb (org-drill-session))
+        (should (string-match-p "past.* tense" shown-prompt))
+        (should (string-match-p "English verb" shown-prompt))))))
+
+(ert-deftest test-present-spanish-verb-branch-5-future-perfect-conjugate ()
+  "Branch 5 reveals the English side and asks to conjugate the future perfect."
+  (with-card-buffer "* Verb :drill:\n** Infinitive\nhablar\n** English\nto speak\n** Future Perfect Tense\nfoo\n"
+    (let ((shown-prompt nil))
+      (cl-letf (((symbol-function 'cl-random) (lambda (_) 5))
+                ((symbol-function 'org-drill-presentation-prompt)
+                 (lambda (_session &optional prompt &rest _)
+                   (setq shown-prompt prompt) t))
+                ((symbol-function 'org-drill--show-latex-fragments) #'ignore)
+                ((symbol-function 'org-display-inline-images) #'ignore))
+        (org-drill-present-spanish-verb (org-drill-session))
+        (should (string-match-p "future perfect" shown-prompt))
+        (should (string-match-p "English verb" shown-prompt))))))
+
 ;;;; org-drill-cram and friends
 
 (ert-deftest test-org-drill-cram-passes-cram-flag ()
diff --git a/tests/test-org-drill-utilities-and-leitner.el b/tests/test-org-drill-utilities-and-leitner.el
index cc0157c..02761a2 100644
--- a/tests/test-org-drill-utilities-and-leitner.el
+++ b/tests/test-org-drill-utilities-and-leitner.el
@@ -61,6 +61,12 @@
 (ert-deftest test-org-drill-shuffle-single-element-unchanged ()
   (should (equal '(42) (org-drill-shuffle (list 42)))))
 
+(ert-deftest test-org-drill-shuffle-rejects-non-list ()
+  "The argument must be a list.  A non-list (number, vector) is rejected
+with a clear type error rather than silently coerced."
+  (should-error (org-drill-shuffle 42) :type 'wrong-type-argument)
+  (should-error (org-drill-shuffle [1 2 3]) :type 'wrong-type-argument))
+
 ;;;; org-drill-pop-random (macro)
 
 (ert-deftest test-org-drill-pop-random-removes-one-element ()
diff --git a/tests/test-org-drill-version.el b/tests/test-org-drill-version.el
new file mode 100644
index 0000000..4dc71d3
--- /dev/null
+++ b/tests/test-org-drill-version.el
@@ -0,0 +1,28 @@
+;;; test-org-drill-version.el --- Tests for org-drill-version  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; org-drill-version is both a constant (the package version string) and an
+;; interactive command that reports it, so bug reporters don't have to open
+;; the file header.
+
+;;; Code:
+
+(require 'ert)
+(require 'org-drill)
+
+(ert-deftest test-org-drill-version-is-a-version-string ()
+  "The constant is a non-empty dotted version string."
+  (should (stringp org-drill-version))
+  (should (string-match-p "\\`[0-9]+\\.[0-9]+" org-drill-version)))
+
+(ert-deftest test-org-drill-version-command-returns-the-version ()
+  "Calling the command returns the version string."
+  (should (equal org-drill-version (org-drill-version))))
+
+(ert-deftest test-org-drill-version-command-is-interactive ()
+  "The version reporter is an interactive command."
+  (should (commandp 'org-drill-version)))
+
+(provide 'test-org-drill-version)
+
+;;; test-org-drill-version.el ends here