feat(data): ship a worked example overlay calendar

`--overlay` shipped last week with nothing to point at. The only example
was a test fixture, explicitly labelled invented and living where no user
would find it, so "colitur supports local calendars" was true but
undemonstrated.

data/ef/examples/diocesan-example.sexp is installed to
<prefix>/share/colitur/examples/ and is runnable documentation: every
celebration in it is invented, with example- slugs that cannot collide,
and its header explains the four directives, the three date shapes, and
the field vocabularies before showing any of them.

It demonstrates the range deliberately rather than the minimum: a
fixed-date local patron with its own propers; a movable dedication on the
first Sunday of October, I class because a church's own dedication
anniversary is I class in that church and at III it would lose to the
Sunday every year; an Easter-relative commemoration; an Edit raising a
universal feast for local use; and a Suppress shown commented out,
because suppressing a universal feast is a real liturgical act and an
example should not invite it casually.

Two things the header says plainly, since this is the one file that lets
someone change what colitur computes: an overlay is applied ON TOP of the
shipped calendar and never instead of it, and an overlay is applied, NOT
validated -- the five test layers assert things about the shipped data
and cannot vouch for a user's file.

A test asserts it loads against the real EF rank vocabulary, still
demonstrates at least four directives, and applies with NO diagnostics.
The last matters most: a directive naming a slug the universal calendar
lacks would warn, and an example that warns teaches the wrong lesson. It
deliberately does not pin which days it produces -- those celebrations
are invented, and pinning their dates would make an illustrative file
behave like calendar data.

1 files changed, 30 insertions, 1 deletions

diff --git a/test/test_rite_ef.ml b/test/test_rite_ef.ml
index 4da6d73..f4991f3 100644
--- a/test/test_rite_ef.ml
+++ b/test/test_rite_ef.ml
@@ -526,9 +526,38 @@ let test_maurice_thomas_band_fidelity_end_to_end () =
     [ "maurice-and-companions-martyrs" ]
     (List.map (fun (c, _) -> slug_of c) day.LD.omitted)
 
+
+(* The SHIPPED example overlay (data/ef/examples/diocesan-example.sexp) is
+   documentation a user is invited to run and copy, and the man page names its
+   installed path. An example that silently stopped loading -- a directive
+   renamed, a Date_spec variant changed -- would be worse than shipping none,
+   because it would fail only for whoever tried it.
+
+   This asserts it PARSES against the REAL EF rank vocabulary and that it
+   still demonstrates the range it claims to. It deliberately does NOT assert
+   which days it produces: those celebrations are invented, and pinning their
+   dates would make an illustrative file behave like calendar data. *)
+let test_shipped_example_overlay_loads () =
+  let path = "../data/ef/examples/diocesan-example.sexp" in
+  match Overlay.load Rite_ef.Vocab_ef.rank_of_sexp path with
+  | Error e -> Alcotest.failf "the shipped example overlay must load: %s" e
+  | Ok o ->
+      Alcotest.(check string) "its id" "diocesan-example" o.Overlay.id;
+      Alcotest.(check bool) "it demonstrates at least four directives" true
+        (List.length o.Overlay.directives >= 4);
+      (* Applying it must be clean: a directive naming a slug the universal
+         calendar lacks would warn, and an EXAMPLE that warns teaches the
+         wrong lesson. *)
+      let layer = real_layer () in
+      let _, diagnostics = Overlay.apply layer o in
+      Alcotest.(check (list string)) "it applies with no diagnostics" []
+        (List.map Overlay.diagnostic_to_string diagnostics)
+
 let suite =
   ( "Rite_ef (real data: overlay-in-effect, domain-ceiling)",
-    [ Alcotest.test_case "the overlay suppression is observably in effect" `Quick
+    [ Alcotest.test_case "the shipped example overlay loads and applies cleanly" `Quick
+        test_shipped_example_overlay_loads;
+      Alcotest.test_case "the overlay suppression is observably in effect" `Quick
         test_vigil_of_christmas_suppressed;
       Alcotest.test_case "RG16(a) task: the two subject retags are in effect, the other four untouched"
         `Quick test_rg16a_subject_retag_in_effect;