path: root/bin/main.ml

module D = Colitur_kernel.Date
module C = Colitur_kernel.Computus

let fmt d = Printf.sprintf "%04d-%02d-%02d" (D.year d) (D.month d) (D.day d)

let easter_report y =
  [ ("easter", C.gregorian_easter y);
    ("ash-wednesday", C.ash_wednesday y);
    ("palm-sunday", C.palm_sunday y);
    ("ascension", C.ascension y);
    ("pentecost", C.pentecost y);
    ("corpus-christi", C.corpus_christi y) ]
  |> List.iter (fun (name, d) -> Printf.printf "%s %s\n" name (fmt d))

let temporal_report y =
  let jan1 = match D.make ~year:y ~month:1 ~day:1 with
    | Ok t -> t
    | Error e -> failwith e
  in
  let dec31 = match D.make ~year:y ~month:12 ~day:31 with
    | Ok t -> t
    | Error e -> failwith e
  in
  (* [week] is "" for roughly 30 days a year (outside any numbered week);
     printed as-is, that collapses two of the seven space-separated fields
     into a double space, so naive field-position parsing (e.g. awk '{print
     $4}') silently reads the wrong column on those days. Emit "-" instead,
     so every line always has exactly seven single-space-separated fields. *)
  let field s = if s = "" then "-" else s in
  let d = ref jan1 in
  while D.compare !d dec31 <= 0 do
    let t = Rite_ef.Temporal_ef.temporal !d in
    let r =
      Colitur_kernel.Record.of_temporal ~rite:Rite_ef.Temporal_ef.id
        Rite_ef.Vocab_ef.vocab !d t
    in
    Printf.printf "%s %s %s %s %s %s %s\n" r.Colitur_kernel.Record.date
      r.Colitur_kernel.Record.weekday r.Colitur_kernel.Record.season
      (field r.Colitur_kernel.Record.week) r.Colitur_kernel.Record.slug
      r.Colitur_kernel.Record.rank r.Colitur_kernel.Record.colour;
    d := D.add_days !d 1
  done

(* Task 11: the fully resolved EF calendar (temporal AND sanctoral,
   occurrence and transfers applied), one line per civil-year day --
   "YYYY-MM-DD weekday season week slug rank colour [+commemoration-slug]...".
   [temporal_report] above only ever showed the temporal cycle in isolation
   ([Rite_ef.Temporal_ef.temporal] directly, no sanctoral layer, no
   [Precedence] contest); this is the first CLI path that runs every piece
   Plan 3 built -- [Colitur_kernel.Layer], [Overlay], [Precedence_ef],
   [Calendar] -- against real data. *)

(* [data/ef/sanctoral.sexp] and [data/ef/adjustments.sexp] are located
   relative to the BUILD TREE, not the process's own cwd: cwd varies with
   how the binary is invoked (a user's shell for `dune exec colitur --`, a
   dune cram test's own sandboxed temp directory for `test/cli.t`) and
   nothing in this project's build pins it to the repository root. A
   build-time constant substituted via dune's [%{workspace_root}] was tried
   first and rejected: it is resolved RELATIVE TO THE BUILD ACTION'S OWN
   directory (empirically "." here, not an absolute path -- dune keeps
   build actions relocatable), so it silently reproduces the same
   cwd-dependence this is trying to eliminate, just baked in at build time
   instead of read at run time; confirmed by the resulting `colitur day`
   failing to find its own data outside the exact directory the build
   happened to run in.

   [Sys.executable_name] does not have that problem -- on Linux it resolves
   through /proc/self/exe, which the kernel always reports as the
   executable's own canonical absolute path, even when the process was
   launched through a symlink (verified against dune's own cram sandbox,
   which places exactly such a symlink; see the task report). dune's default
   ("no [(sandbox ...)] declared") build context mirrors the ENTIRE source
   tree under _build/default/, unconditionally, so climbing from
   _build/default/bin/main.exe up two directories and back down into data/
   always finds both files, regardless of the caller's own cwd.

   RESOLVED: the "known limitation" this comment used to end on -- that a
   `dune install`-style deployment (executable copied to a prefix with no
   adjacent _build/default/data/) had no resolution strategy, and would exit 2
   unable to find sanctoral.sexp -- is now handled by probing candidates in
   order rather than computing one path and hoping. data/dune installs the
   four runtime files into <prefix>/share/colitur/ef/.

   Two layouts are probed, and one override short-circuits both:

     [COLITUR_DATA_DIR], when set and non-blank -- an explicit override. It
     NEVER falls through: if it is set and does not contain the data, that is
     an error naming the directory, not a reason to quietly use different
     data. A packager or operator who names a directory has stated an
     intent, and silently calendaring off some other copy because theirs was
     wrong is precisely the silent substitution this project refuses
     everywhere else (CLAUDE.md's first binding decision: divergence is
     flagged LOUDLY, never silently swallowed). Getting this wrong is not
     hypothetical -- the first version of this function did fall through, and
     a deliberately bogus COLITUR_DATA_DIR produced a full, plausible,
     entirely un-flagged year off the build tree's data.

     Otherwise, in order:
     1. <exedir>/../share/colitur/ef -- the INSTALLED layout, from an opam or
        `dune install` prefix where the binary sits at <prefix>/bin/colitur.
        data/dune puts the four runtime files there.
     2. <exedir>/../data/ef -- the BUILD TREE, which is what `dune exec` and
        the cram tests use.

   A candidate is accepted only if sanctoral.sexp is actually readable inside
   it, not merely because the directory exists: an empty or half-populated
   share/colitur/ef (a failed install, a partially removed package) falls
   through to a working build tree rather than shadowing it and then failing
   at load time with a confusing per-file error. Verified by simulation, not
   assumed.

   Environment reads are fine HERE and only here: this is bin/, not the
   kernel, whose contract forbids them (CLAUDE.md, "Kernel is total &
   deterministic: no wall-clock, randomness, or environment reads"). Nothing
   below the CLI ever learns where the data came from -- the loaders take a
   path. *)
let data_dir () =
  let has_data d = Sys.file_exists (Filename.concat d "sanctoral.sexp") in
  let prefix = Filename.dirname (Filename.dirname Sys.executable_name) in
  let installed = List.fold_left Filename.concat prefix [ "share"; "colitur"; "ef" ] in
  let build_tree = Filename.concat prefix (Filename.concat "data" "ef") in
  match Sys.getenv_opt "COLITUR_DATA_DIR" with
  | Some d when String.trim d <> "" ->
      if has_data d then d
      else begin
        Printf.eprintf
          "colitur: COLITUR_DATA_DIR is set to %s, which contains no sanctoral.sexp\n\
           colitur: refusing to fall back to another data directory -- unset it, or point it at one\n"
          d;
        exit 2
      end
  | _ -> if has_data installed then installed else build_tree

(* [lang_dir] mirrors [data_dir]'s own probe order exactly -- installed
   prefix first, then the build tree -- because a language file must resolve
   the same way calendar data does, or an installed binary could find one
   and not the other (exactly the defect a prior fix round found: lang/ had
   no install rule at all, and the installed binary silently fell back to
   raw slugs with no error). Accepted only if la.ini is actually readable
   there, matching [data_dir]'s own "a candidate counts only if the data is
   really there" discipline. *)
let lang_dir () =
  let prefix = Filename.dirname (Filename.dirname Sys.executable_name) in
  let installed = List.fold_left Filename.concat prefix [ "share"; "colitur"; "lang" ] in
  if Sys.file_exists (Filename.concat installed "la.ini") then installed
  else Filename.concat prefix "lang"

(* Loads the universal sanctoral layer and applies the one hand-authored
   overlay over it (data/ef/adjustments.sexp -- see that file's own header):
   [Overlay.apply]'s diagnostics are never silently dropped (Overlay.mli),
   so any that come back -- expected to be none in the committed data; see
   the overlay file's own comment on when one WOULD fire -- are printed to
   stderr, loudly, without aborting the run. *)
(* [user_overlays] are applied AFTER the shipped adjustments, in the order
   given, never instead of them. That ordering is the whole point: the shipped
   overlay carries RG 110's own 30 June companion, the Major Litanies, St
   Barbara and Rogation Wednesday, and a user file that REPLACED it would
   silently drop all four while looking like it had merely added a local
   feast. {!Overlay.merge}'s last-writer-wins is what lets a local calendar
   still override a universal entry deliberately, by naming its slug.

   Diagnostics stay loud but non-fatal, and that matters more for a user file
   than for the shipped one: a directive naming a slug that does not exist (a
   typo in a diocesan calendar) prints to stderr and the run continues, rather
   than the entry silently doing nothing. A file that fails to LOAD is fatal,
   exactly as the shipped overlay is -- a malformed calendar is not something
   to carry on past. *)
let load_ef_layer ?(user_overlays = []) () =
  let dir = data_dir () in
  let sanctoral_path = Filename.concat dir "sanctoral.sexp" in
  let adjustments_path = Filename.concat dir "adjustments.sexp" in
  let load_overlay path =
    match Colitur_kernel.Overlay.load Rite_ef.Vocab_ef.rank_of_sexp path with
    | Error e -> Error (Printf.sprintf "failed to load %s: %s" path e)
    | Ok o -> Ok o
  in
  let rec load_all acc = function
    | [] -> Ok (List.rev acc)
    | p :: rest -> ( match load_overlay p with Error e -> Error e | Ok o -> load_all (o :: acc) rest)
  in
  match Colitur_kernel.Layer.load Rite_ef.Vocab_ef.rank_of_sexp sanctoral_path with
  | Error e -> Error (Printf.sprintf "failed to load %s: %s" sanctoral_path e)
  | Ok layer -> (
      match load_all [] (adjustments_path :: user_overlays) with
      | Error e -> Error e
      | Ok overlays ->
          (* Diagnostics come back to the caller rather than being printed
             here: `day`/`readings` want them on stderr beside a year of
             output, while `check` wants them on stdout, attributed to the
             overlay that produced them, and counted. Printing at the source
             made the second impossible. *)
          Ok (Colitur_kernel.Overlay.merge layer overlays))

(* Sibling to [load_ef_layer] above, same reasoning: [Rite_ef.context] now
   takes [~lectionary] rather than loading data/ef/lectionary.sexp itself
   (fix round 1, coordinator review -- a prior version had [Rite_ef]'s own
   [context] load the file as a side effect of being linked, which killed
   `colitur easter <year>` -- no lectionary data touched at all -- the
   moment that file was missing from a bare `dune build`'s own default
   target). Routed through the same [result] failure path as
   [load_ef_layer], so a missing/malformed file is reported via
   `colitur: %s` and `exit 2`, never an uncaught exception -- restoring the
   promise [Lectionary.load]'s own .mli makes ("failures come back as
   [Error], never as an exception"), which the reverted version broke by
   re-wrapping it in [failwith] at module init where no caller could catch
   it. *)
let load_ef_lectionary () =
  let path = Filename.concat (data_dir ()) "lectionary.sexp" in
  match Colitur_kernel.Lectionary.load path with
  | Error e -> Error (Printf.sprintf "failed to load %s: %s" path e)
  | Ok lectionary -> Ok lectionary

(* Sibling to [load_ef_lectionary] above, same reasoning and the same
   [result] failure path: data/ef/commons.sexp holds the Commons of the
   1962 Missal plus the per-saint assignments that route a readingless
   class-3 feast to one, and [Rite_ef.context] takes it as [~commons]
   rather than reading it itself. Its own loader validates the file
   (duplicate ids, empty formularies, assignments naming a common that does
   not exist) and reports every failure as [Error]. *)
let load_ef_commons () =
  let path = Filename.concat (data_dir ()) "commons.sexp" in
  match Rite_ef.Lectionary_ef.Commons.load path with
  | Error e -> Error (Printf.sprintf "failed to load %s: %s" path e)
  | Ok commons -> Ok commons

(* [~lang] resolves the observed slug to a display NAME, appended as a new
   LAST field rather than substituted into the slug's own position: a name
   contains spaces (Latin and English both), and inserting it where the slug
   used to sit would break every fixed-position field after it (rank,
   colour, the commemoration tail) for anyone parsing this line by column --
   the same reasoning that keeps `readings` a separate command rather than
   extra columns on `day`. [slug] itself is therefore untouched by [lang] in
   this row, exactly as [Colitur_render.View]'s own [slug] field is.

   The trailing field is present only when the resolved name actually
   DIFFERS from the slug -- not gated on [--raw] as a special case, but as a
   direct consequence of [Lang.raw] being the identity table (lang.mli):
   under [--raw], [name = slug] always, so the field is always absent and
   this row is BYTE-IDENTICAL to what it printed before this feature
   existed, with no `if raw then ...` branch anywhere in this function. The
   same holds for any language file that has genuinely no entry for a given
   slug -- a miss also returns the slug (lang.mli), so an untranslated day
   quietly gets no trailing field rather than a field that redundantly
   repeats the slug it already printed. *)
let day_line ~lang (d : (Rite_ef.Vocab_ef.season, Rite_ef.Vocab_ef.rank) Colitur_kernel.Liturgical_day.t)
    =
  let t = d.Colitur_kernel.Liturgical_day.temporal in
  let cel = d.Colitur_kernel.Liturgical_day.observed in
  let week =
    match t.Colitur_kernel.Temporal.week with Some n -> string_of_int n | None -> "-"
  in
  let commemoration_suffix (c, _) =
    " +" ^ Colitur_kernel.Slug.to_string c.Colitur_kernel.Celebration.slug
  in
  let commemorations =
    String.concat "" (List.map commemoration_suffix d.Colitur_kernel.Liturgical_day.commemorations)
  in
  let slug_s = Colitur_kernel.Slug.to_string cel.Colitur_kernel.Celebration.slug in
  let name = Colitur_naming.Lang.celebration lang slug_s in
  let name_suffix = if name = slug_s then "" else " " ^ name in
  Printf.printf "%s %s %s %s %s %s %s%s%s\n" (D.to_iso8601 d.Colitur_kernel.Liturgical_day.date)
    (D.weekday_to_string t.Colitur_kernel.Temporal.weekday)
    (Rite_ef.Vocab_ef.season_to_string t.Colitur_kernel.Temporal.season)
    week slug_s
    (Rite_ef.Vocab_ef.rank_to_string cel.Colitur_kernel.Celebration.rank)
    (Colitur_kernel.Colour.to_string cel.Colitur_kernel.Celebration.colour)
    commemorations name_suffix

(* The reading citations for a day, as its own row shape rather than extra
   columns on [day_line]'s.

   A SEPARATE COMMAND, not a widening of `colitur day`, and the reason is
   mechanical rather than aesthetic: a citation contains spaces and commas
   ("Ezech 34:11-16", "Ecclus 51:1-8, 12"), while [day_line]'s row is
   space-separated with a variable-length "+slug" commemoration tail.
   Appending citations there would leave the row unsplittable -- no [awk]/
   [cut] field number could recover where the Epistle ends -- which is the
   opposite of the composability the row is shaped for. So `day` keeps its
   format byte-identical (nothing downstream of it changes at all) and the
   citations get a row whose own fields are " | "-delimited, safe for values
   containing spaces.

   This is deliberately a stopgap, and should not be mistaken for the
   project's answer to output formatting: the design calls for one schema
   rendered through a logic-less template engine (CSV/JSON/S-expression),
   which is where this belongs eventually. Two ad-hoc column formats are
   easier to retire later than one overloaded format with parsing rules
   nobody wrote down.

   "-" for an absent part, matching [temporal_report]'s own [field]
   convention for an empty column. On the EF data as it stands no day can
   actually print "-" -- {!Colitur_kernel.Validate}'s "citations"/
   "citations-unresolved" checks assert exactly one First and one Gospel on
   every day of every year 1583..9999 -- but the CLI must not assume a
   guarantee the kernel makes about DATA rather than about types. *)
(* [~lang]: same append-only rule as [day_line] above, using this row's own
   " | " field separator (chosen there precisely because a citation may
   contain spaces or commas) rather than a plain space -- a resolved name
   can equally contain spaces, and " | " is what already keeps this row's
   fields unambiguous. Present only when the resolved name differs from the
   slug, for the identical reason [day_line] gives: under [--raw] this row
   is therefore byte-identical to what it printed before. *)
let readings_line ~lang (d : (Rite_ef.Vocab_ef.season, Rite_ef.Vocab_ef.rank) Colitur_kernel.Liturgical_day.t)
    =
  let cel = d.Colitur_kernel.Liturgical_day.observed in
  let part_ref p =
    match
      List.find_opt
        (fun (c : Colitur_kernel.Citation.t) -> c.Colitur_kernel.Citation.part = p)
        d.Colitur_kernel.Liturgical_day.citations
    with
    | Some c -> c.Colitur_kernel.Citation.reference
    | None -> "-"
  in
  let slug_s = Colitur_kernel.Slug.to_string cel.Colitur_kernel.Celebration.slug in
  let name = Colitur_naming.Lang.celebration lang slug_s in
  let name_suffix = if name = slug_s then "" else " | " ^ name in
  Printf.printf "%s %s | %s | %s%s\n"
    (D.to_iso8601 d.Colitur_kernel.Liturgical_day.date)
    slug_s
    (part_ref Colitur_kernel.Citation.First)
    (part_ref Colitur_kernel.Citation.Gospel)
    name_suffix

(* One civil year, Jan 1 - Dec 31, matching [temporal_report]'s own scan --
   NOT one liturgical year: [Colitur_kernel.Calendar.year] resolves a single
   Advent-anchored liturgical year, which straddles two civil years, so a
   civil year's worth of output needs the tail of the liturgical year that
   opened the PREVIOUS civil year (covers roughly 1 Jan - 28 Nov) plus the
   liturgical year that opens within this one (roughly 29 Nov - 31 Dec).
   Both are computed once each -- not once per day via [Calendar.day], which
   would recompute the whole (~365-day) placement pass up to 365 times over
   for the days sharing one liturgical year (calendar.mli's own "pays it
   once" cost model assumes exactly this usage: call [year], not [day] in a
   loop). *)
(* The three data files this subcommand needs, loaded once and reported
   through ONE failure path. Flattened out of the nested [match] this used
   to be when a third loader (the Commons, Task 6) joined the first two:
   each additional caller-supplied table would otherwise add a level of
   indentation and a third verbatim copy of the same two-line error-and-exit
   block. Every loader already returns [(_, string) result] (never raises,
   never reads at module-initialisation time -- see [load_ef_lectionary]),
   so chaining them costs nothing and keeps that promise intact. *)
let load_ef_data ?(user_overlays = []) () =
  match
    Result.map
      (fun (layer, diagnostics) ->
        List.iter
          (fun d -> Printf.eprintf "colitur: %s\n" (Colitur_kernel.Overlay.diagnostic_to_string d))
          diagnostics;
        layer)
      (load_ef_layer ~user_overlays ())
  with
  | Error msg -> Error msg
  | Ok layer -> (
      match load_ef_lectionary () with
      | Error msg -> Error msg
      | Ok lectionary -> (
          match load_ef_commons () with
          | Error msg -> Error msg
          | Ok commons -> Ok (layer, lectionary, commons)))

(* The resolved-year walk, shared by [day_report], [readings_report] and
   [emit_report] (Task 8): they differ only in what happens to each day, and
   the two-liturgical-year indexing below (with its own reasoning about
   civil-vs-liturgical spans) is exactly the part that must not be duplicated
   and drift. [resolved_year_days] owns that walk and returns the resolved
   days, in date order, for one civil year; every caller layers its own
   handling (a line-printer, an accumulator for a whole-year [Template.value])
   on top rather than repeating the indexing. *)
let resolved_year_days ~overlays y =
  match load_ef_data ~user_overlays:overlays () with
  | Error msg ->
      Printf.eprintf "colitur: %s\n" msg;
      exit 2
  | Ok (layer, lectionary, commons) ->
      let context = Rite_ef.context ~lectionary ~commons in
      let module Cal = Colitur_kernel.Calendar in
      let by_rata : (int, (Rite_ef.Vocab_ef.season, Rite_ef.Vocab_ef.rank) Colitur_kernel.Liturgical_day.t) Hashtbl.t =
        Hashtbl.create 400
      in
      let index days =
        Array.iter
          (fun (d : (Rite_ef.Vocab_ef.season, Rite_ef.Vocab_ef.rank) Colitur_kernel.Liturgical_day.t) ->
            Hashtbl.replace by_rata (D.to_rata d.Colitur_kernel.Liturgical_day.date) d)
          days
      in
      index (Cal.year context layer (y - 1));
      index (Cal.year context layer y);
      let jan1 = match D.make ~year:y ~month:1 ~day:1 with Ok t -> t | Error e -> failwith e in
      let dec31 = match D.make ~year:y ~month:12 ~day:31 with Ok t -> t | Error e -> failwith e in
      let d = ref jan1 in
      let acc = ref [] in
      while D.compare !d dec31 <= 0 do
        (match Hashtbl.find_opt by_rata (D.to_rata !d) with
        | Some day -> acc := day :: !acc
        | None ->
            (* Unreachable for any [y] in 1583..9999: the two indexed
               liturgical years jointly cover [year_start (y-1), year_start
               (y+1)), which contains all of civil year [y]
               (calendar.mli). Not a [failwith] -- an out-of-domain [d]
               inside this loop is impossible by construction (jan1/dec31
               are themselves validated in range, and [add_days] only ever
               advances within the same civil year here) -- but a silent
               skip would violate the same "never silently dropped"
               standard the kernel holds itself to, so a gap surfaces
               loudly on stderr rather than as a quietly short year. *)
            Printf.eprintf "colitur: internal error: no resolved day for %s\n" (D.to_iso8601 !d));
        d := D.add_days !d 1
      done;
      List.rev !acc

let resolved_year_report ~line ~overlays y =
  List.iter line (resolved_year_days ~overlays y)

let day_report ~lang ~overlays y = resolved_year_report ~line:(day_line ~lang) ~overlays y
let readings_report ~lang ~overlays y = resolved_year_report ~line:(readings_line ~lang) ~overlays y

(* Task 8: `colitur emit` -- the five template-family emitters built in
   Tasks 5-7, wired to a year RANGE rather than a single year, because a
   published feed (ics) or a data export (csv/json/xml) is usually wanted
   for more than one civil year at a time. Reuses [resolved_year_days]
   rather than re-walking the two-liturgical-year index: see that
   function's own comment.

   CSV is the one format that spans years in a single stream deliberately
   printed as ONE header followed by every year's rows: emitting a fresh
   header per year would make `wc -l` and `awk 'NR>1'` both wrong on a
   multi-year run, and nothing about RFC 4180 requires a header per file
   rather than per stream. json/xml/sexp/ics are printed once per year
   instead -- concatenating whole JSON objects or VCALENDARs into one
   stream is what each of those formats itself expects a multi-document
   feed to look like (SEXP: printed one form per line, matching the
   sexp-per-day shape [Liturgical_day.t] already uses elsewhere in this
   file; XML: one document per year, the schema's own root is a single
   year; ICS: one VCALENDAR per year, valid to concatenate for a
   subscriber that reads multiple files). *)
(* [--dtstamp] is the only user string that reaches [emit]/[publish] output
   unescaped and unvalidated (it becomes an ICS DTSTAMP: property value
   directly, Colitur_render.Emit_ics.year's own [dtstamp] parameter) --
   every OTHER interpolated value in this project's output is either
   escaped (Escape.apply) or engine-computed, never raw user input placed
   straight into a line-oriented format. RFC 5545 section 3.3.5 defines
   DATE-TIME's UTC form as exactly 8 digits, "T", 6 digits, "Z"
   (e.g. "20270101T000000Z"); rejecting anything else is what stops
   "--dtstamp hello" from silently emitting a malformed "DTSTAMP:hello" AND
   what stops a value carrying its own CRLF (e.g. "X\r\nBEGIN:VEVENT\r\n...")
   from being injected verbatim into every VEVENT -- a value shaped exactly
   like the real form cannot contain either character. *)
let dtstamp_well_formed s =
  let is_digit c = c >= '0' && c <= '9' in
  String.length s = 16
  && String.for_all is_digit (String.sub s 0 8)
  && s.[8] = 'T'
  && String.for_all is_digit (String.sub s 9 6)
  && s.[15] = 'Z'

let check_dtstamp = function
  | None -> ()
  | Some s when dtstamp_well_formed s -> ()
  | Some s ->
      Printf.eprintf
        "colitur: --dtstamp %S is not RFC 5545 UTC form (want 8 digits, 'T', 6 digits, 'Z', e.g. \
         20270101T000000Z)\n"
        s;
      exit 2

let emit_report ~lang ~format ~overlays ~dtstamp ~from_y ~to_y =
  check_dtstamp dtstamp;
  if from_y > to_y then begin
    Printf.eprintf "colitur: --from %d is after --to %d\n" from_y to_y;
    exit 2
  end;
  for y = from_y to to_y do
    let days = resolved_year_days ~overlays y in
    let v =
      Colitur_render.View.of_days ~lang ~vocab:Rite_ef.Vocab_ef.vocab ~rite:"ef" ~year:y days
    in
    match format with
    | "csv" ->
        (* One header for the whole run, not one per year. *)
        let body = Colitur_render.Emit_csv.year v in
        if y = from_y then print_string body
        else
          print_string
            (match String.index_opt body '\n' with
             | Some i -> String.sub body (i + 1) (String.length body - i - 1)
             | None -> body)
    | "json" -> print_string (Colitur_render.Emit_json.year v)
    | "xml" -> print_string (Colitur_render.Emit_xml.year v)
    | "ics" -> print_string (Colitur_render.Emit_ics.year ?dtstamp v)
    | "sexp" ->
        List.iter
          (fun d ->
            print_string
              (Sexplib.Sexp.to_string_hum
                 (Colitur_kernel.Liturgical_day.sexp_of_t
                    Rite_ef.Vocab_ef.sexp_of_season Rite_ef.Vocab_ef.sexp_of_rank d));
            print_newline ())
          days
    | other ->
        Printf.eprintf "colitur: unknown format %S (want csv, json, sexp, xml or ics)\n" other;
        exit 2
  done

(* Task 9: `colitur table` and `colitur render` -- compute a year and render it
   through a user-supplied template, in ONE process.

   The design's own sketch was `compute | render` as a Unix pipe, with `render`
   reading a serialised view back from stdin. That is deliberately NOT built:
   honouring the pipe would need a JSON *parser*, purely to re-read the view
   this same process just serialised -- a second hand-rolled component, and a
   second place for the published contract to drift, for no benefit over
   calling [View.of_days] directly. So `table --year Y --template F` computes
   and renders in one process (the command that actually gets used), and
   `render --template F --year Y` is the identical operation under the name
   the design used, kept so that documented vocabulary still works. There is
   no stdin-fed `render`; `colitur emit --format json | jq` still composes for
   real pipe use, because JSON there is the OUTPUT, never something colitur
   itself has to parse back in. *)

(* The open is guarded separately from the read: a missing file fails at
   [open_in_bin] with a plain, path-only message (matching the wording this
   project already uses for every other "no such file" case), while a file
   that opens but cannot be READ -- a directory, a device node, anything
   whose length or content changes between [open] and [read] -- fails inside
   the [Fun.protect]'d body instead, carrying the raised exception's own text
   (mirrors {!Colitur_kernel.Layer.load}/{!Colitur_kernel.Overlay.load}'s own
   catch-all shape, lib/kernel/layer.ml and lib/kernel/overlay.ml). Either
   way the channel is closed on EVERY path -- success, exception, or an
   early return -- because [close_in_noerr] runs in [~finally], which
   [Fun.protect] guarantees runs even when the protected function raises; a
   bare [close_in] after [really_input_string] only ever ran on the success
   path, leaking the descriptor on every failure. The whole read is inside
   the [try], not only [open_in_bin], because [in_channel_length] and
   [really_input_string] can themselves raise [Sys_error] (a directory opens
   fine but is not readable as bytes) -- a template is user input, and this
   project's own rule is that user input must never crash the program. *)
let read_file path =
  match open_in_bin path with
  | exception Sys_error _ -> Error ("cannot read template " ^ path)
  | ic -> (
      try
        Fun.protect
          ~finally:(fun () -> close_in_noerr ic)
          (fun () ->
            let n = in_channel_length ic in
            let s = really_input_string ic n in
            Ok s)
      with exn -> Error (Printf.sprintf "cannot read template %s: %s" path (Printexc.to_string exn)))

(* The config file supplies DEFAULTS for --lang, --overlay, --template and
   --format when the corresponding flag is absent -- Colitur_naming.Config
   owns precedence (flag > config > default). Location follows the XDG base
   directory convention: $XDG_CONFIG_HOME/colitur/config.ini, or
   ~/.config/colitur/config.ini when that variable is unset or blank. An
   unresolvable HOME (neither variable set) means no config path at all --
   [load_config] below treats that exactly like a missing file, not an
   error, since colitur without any config must keep working. *)
let config_path () =
  match Sys.getenv_opt "XDG_CONFIG_HOME" with
  | Some d when String.trim d <> "" -> Filename.concat d "colitur/config.ini"
  | _ -> (
      match Sys.getenv_opt "HOME" with
      | Some h -> Filename.concat h ".config/colitur/config.ini"
      | None -> "")

(* A config file is OPTIONAL: none at [config_path ()] behaves exactly as
   colitur always has (Colitur_naming.Config.empty). A file that EXISTS but
   fails to read or parse is fatal -- a config the user wrote and colitur
   cannot honour is not something to silently carry on past. An unknown key
   or section is reported but never fatal (Config.mli's own contract): a
   config written for a newer colitur must still work on an older one, but a
   silently-ignored typo is how a setting the user believes is active quietly
   does nothing. Two separate warnings, not one, so a misspelled SECTION
   (e.g. [deafults]) reads differently from a misspelled KEY inside a
   recognised one -- Config.mli documents exactly this distinction. *)
let load_config () =
  let p = config_path () in
  if p = "" || not (Sys.file_exists p) then Colitur_naming.Config.empty
  else
    match read_file p with
    | Error _ ->
        Printf.eprintf "colitur: cannot read config file %s\n" p;
        exit 2
    | Ok text -> (
        match Colitur_naming.Config.of_string text with
        | Error msg ->
            Printf.eprintf "colitur: %s: %s\n" p msg;
            exit 2
        | Ok c ->
            List.iter
              (fun k -> Printf.eprintf "colitur: %s: unknown setting %S (ignored)\n" p k)
              (Colitur_naming.Config.unknown_keys c);
            List.iter
              (fun s -> Printf.eprintf "colitur: %s: unknown section [%s] (ignored)\n" p s)
              (Colitur_naming.Config.unknown_sections c);
            c)

(* An unknown language is an ERROR naming what is available, never a silent
   fallback to Latin: a booklet quietly printed in the wrong language is
   worse than one that refuses to print. [raw] takes priority
   unconditionally and short-circuits everything else -- [--raw] IS
   [Lang.raw], the identity table, handed to the caller directly, rather
   than a second "is this raw" case threaded through every call site
   downstream (View.of_days, day_line, readings_line all just take a
   [Lang.t] and do not know or care whether it came from [--raw] or a real
   file). *)
let load_lang ~raw ~flag ~config =
  if raw then Colitur_naming.Lang.raw
  else
    let code, _src = Colitur_naming.Config.resolve ~flag ~config ~default:"la" in
    let path =
      if String.contains code '/' || Filename.check_suffix code ".ini" then code
      else Filename.concat (lang_dir ()) (code ^ ".ini")
    in
    match read_file path with
    | Error _ ->
        Printf.eprintf "colitur: no language %S (looked in %s); try: colitur lang --list\n" code
          (lang_dir ());
        exit 2
    | Ok text -> (
        match Colitur_naming.Lang.of_string text with
        | Error msg ->
            Printf.eprintf "colitur: %s: %s\n" path msg;
            exit 2
        | Ok t -> (
            (* Chain to the declared fallback, so a partial translation shows
               its fallback language rather than bare slugs. A fallback that
               itself fails to load or parse does not take [t] down with it
               -- [t] is already a good table; losing only the fallback field
               is better than losing the whole language over a defect in a
               file [t] merely NAMES. *)
            match Colitur_naming.Lang.fallback_code t with
            | None -> t
            | Some fb -> (
                match read_file (Filename.concat (lang_dir ()) (fb ^ ".ini")) with
                | Error _ -> t
                | Ok ftext -> (
                    match Colitur_naming.Lang.of_string ftext with
                    | Error _ -> t
                    | Ok base -> Colitur_naming.Lang.with_fallback t base))))

let extension path =
  match String.rindex_opt path '.' with
  | Some i -> String.sub path i (String.length path - i)
  | None -> ""

(* An unknown extension with no [--flavour] is an ERROR, never a silent
   fallback to [Escape.None_]: guessing the flavour wrong produces malformed
   output (unescaped LaTeX/HTML metacharacters) that looks fine until it does
   not -- the same "never silently substitute" discipline [data_dir]'s own
   [COLITUR_DATA_DIR] handling documents above.

   Both error messages below list the flavours by walking [Escape.all]
   rather than a hand-typed literal, on purpose: a hand-typed list is
   exactly the kind of call site the design claims does not exist outside
   escape.ml (spec section 5) -- adding Typst as a seventh flavour found
   this one had drifted from that claim (it silently still said "the six
   flavours" until then), so this is now future-proof against the same
   drift the next flavour would otherwise reintroduce. *)
let flavour_names_comma () =
  match List.map Colitur_render.Escape.to_string Colitur_render.Escape.all with
  | [] -> ""
  | [ x ] -> x
  | xs -> (
      match List.rev xs with
      | last :: rest -> String.concat ", " (List.rev rest) ^ " or " ^ last
      | [] -> "")

let flavour_names_bar () =
  String.concat "|" (List.map Colitur_render.Escape.to_string Colitur_render.Escape.all)

let table_report ~lang ~template ~flavour_opt ~overlays y =
  let flavour =
    match flavour_opt with
    | Some name -> (
        match Colitur_render.Escape.of_string name with
        | Some f -> f
        | None ->
            Printf.eprintf "colitur: unknown flavour %S (want %s)\n" name (flavour_names_comma ());
            exit 2)
    | None -> (
        match Colitur_render.Escape.of_extension (extension template) with
        | Some f -> f
        | None ->
            Printf.eprintf "colitur: cannot infer a flavour from %S; pass --flavour %s\n"
              (extension template) (flavour_names_bar ());
            exit 2)
  in
  match read_file template with
  | Error msg ->
      Printf.eprintf "colitur: %s\n" msg;
      exit 2
  | Ok src -> (
      let days = resolved_year_days ~overlays y in
      let v = Colitur_render.View.of_days ~lang ~vocab:Rite_ef.Vocab_ef.vocab ~rite:"ef" ~year:y days in
      match Colitur_render.Template.render_string ~flavour src v with
      | Error e ->
          (* The template is user input; a parse failure is reported with the
             parser's OWN reason and exits 2, never an uncaught exception. *)
          Printf.eprintf "colitur: template %s: %s\n" template e;
          exit 2
      | Ok out -> print_string out)

(* Task 12: `colitur publish` -- writes the static tree that IS this
   project's API: a set of files any web server or git repo can serve as-is,
   computed once, with nothing running at request time.

   Two properties matter more than anything else here:

   DETERMINISTIC -- publishing the same year range twice must produce a
   byte-identical tree. That is what makes publishing into a git repo safe:
   `git status` shows only genuine change, and a human reviews a real diff
   before pushing. Nothing below reads a wall clock; [dtstamp] is threaded
   through as a plain parameter all the way to
   {!Colitur_render.Emit_ics.year}, exactly as `emit --format ics` already
   requires (see that command's own comment above).

   NON-DESTRUCTIVE -- publish writes only files it owns, names every one of
   them in a manifest ([.colitur-manifest], one relative path per line,
   itself never subject to pruning), and [--prune] removes only entries
   THAT MANIFEST lists which this run did not rewrite. A file the caller put
   in the output directory themselves is never in the manifest, so it is
   never touched, with or without [--prune] -- asserted in both directions
   in test/cli.t. *)

let rec mkdir_p path =
  if path <> "" && path <> "/" && not (Sys.file_exists path) then begin
    mkdir_p (Filename.dirname path);
    try Unix.mkdir path 0o755 with Unix.Unix_error (Unix.EEXIST, _, _) -> ()
  end

let write_file path contents =
  mkdir_p (Filename.dirname path);
  let oc = open_out_bin path in
  output_string oc contents;
  close_out oc

let manifest_name = ".colitur-manifest"

(* [read_file] rather than a second hand-rolled reader -- see its own
   comment above for why the whole read, not only the open, is guarded. A
   missing manifest (the very first publish into a fresh directory) is not
   an error here: it just means there is nothing yet to prune against. *)
let read_manifest out =
  match read_file (Filename.concat out manifest_name) with
  | Error _ -> []
  | Ok contents -> String.split_on_char '\n' contents |> List.filter (fun l -> l <> "")

(* Fix round 1 (coordinator review), CRITICAL: a manifest entry is
   UNTRUSTED input the moment [--prune] reads it back. The manifest is a
   plain-text file that lives INSIDE the very tree this feature exists to
   have committed into a git repo -- an ordinary bad merge or a hand-edit is
   enough to put an arbitrary path in it, no attacker required. Without a
   check, an entry like "../outside/CANARY.txt" resolves, via
   [Filename.concat out entry], to a path OUTSIDE [out], and the prune loop
   below would [Sys.remove] it -- deleting a file [publish] never wrote,
   breaking the "never deletes a file it does not own" contract outright.

   Two independent checks, deliberately, because either alone is easy to
   regress later without anyone noticing in review:

   1. STRUCTURAL ([manifest_entry_is_safe]) -- reject an entry that is
      absolute, or that has a ".." path component anywhere. Split on '/'
      and compare COMPONENTS, never a bare substring test: substring-
      matching ".." would wrongly reject a legitimate name like
      "foo..bar", which contains the two characters but has no ".."
      component of its own.
   2. CONTAINMENT ([resolves_under]) -- even an entry that passes check 1
      is not trusted until the path it actually resolves to, symlinks
      included, is verified to sit under [out]. [Unix.realpath] resolves
      symlinks as well as "..", so this also catches an entry that a
      symlink planted inside [out] could use to defeat check 1 alone. A
      plain string-prefix compare is not enough by itself either:
      "/tmp/pub1" is a byte-prefix of "/tmp/pub1-evil", a directory that is
      not nested inside it at all, so [is_under] insists the character
      right after the prefix is the path separator (or that the paths are
      identical). *)
let manifest_entry_is_safe entry =
  entry <> ""
  && entry.[0] <> '/'
  && not (List.mem ".." (String.split_on_char '/' entry))

let is_under ~root path =
  let root =
    if String.length root > 1 && root.[String.length root - 1] = '/' then
      String.sub root 0 (String.length root - 1)
    else root
  in
  String.equal path root
  || (String.length path > String.length root
     && String.sub path 0 (String.length root) = root
     && path.[String.length root] = '/')

(* [Unix.realpath] requires the path to exist, which is fine here: every
   caller below checks [Sys.file_exists]/[Sys.readdir] first. Any failure
   (missing path, dangling symlink, permission error) is treated as "not
   contained" -- refuse to act rather than guess. *)
let resolves_under out p =
  match Unix.realpath out with
  | exception (Unix.Unix_error _ | Sys_error _) -> false
  | out_real -> (
      match Unix.realpath p with
      | exception (Unix.Unix_error _ | Sys_error _) -> false
      | p_real -> is_under ~root:out_real p_real)

(* [--prune] deletes the FILES a stale manifest entry names, but that alone
   can leave their parent directories (ef/<year>/<mm>/, then ef/<year>/)
   empty behind them -- and an empty directory still makes `test -d
   out/ef/<year>` true, which is exactly the check a caller uses to confirm
   an old year is gone. Walk upward from each deleted file's own directory,
   removing it while it is empty, stopping at (never including) [out]
   itself: [out] is the caller's own directory, never ours to remove, even
   when it is empty. The same containment discipline as the file deletions
   above applies here too ([resolves_under]), not only structurally (this
   function is only ever reached via a [p] the file-deletion path already
   validated, but re-checking each directory step is the belt to that
   entry's braces -- see the two-layer reasoning above). *)
let rec prune_empty_dirs ~out dir =
  if
    dir <> out
    && String.length dir > String.length out
    && Sys.file_exists dir
    && resolves_under out dir
  then
    match Sys.readdir dir with
    | [||] ->
        (try Unix.rmdir dir with Unix.Unix_error _ -> ());
        prune_empty_dirs ~out (Filename.dirname dir)
    | _ -> ()
    | exception Sys_error _ -> ()

(* schema/day-v1.json is resolved the same prefix-relative way [data_dir]
   above resolves data/ef/*.sexp -- NOT from the process's own cwd, which
   would break an installed binary invoked from an arbitrary directory. Two
   candidates, installed then build-tree, the same shape as [data_dir]; a
   candidate counts only if the file is actually there. No COLITUR_DATA_DIR
   override here: that variable's whole contract is about the directory
   holding sanctoral.sexp, and schema/ is not nested inside it.

   The installed candidate assumes schema/ lands at
   <prefix>/share/colitur/schema/day-v1.json, mirroring data/dune's own ef/
   layout. Adding that install rule is explicitly Task 13's job, not this
   one -- this function only has to be ready to find the file once the rule
   exists, which is why it is PROBED rather than assumed, exactly like
   [data_dir]'s own installed candidate. *)
let schema_path () =
  let prefix = Filename.dirname (Filename.dirname Sys.executable_name) in
  let installed =
    List.fold_left Filename.concat prefix [ "share"; "colitur"; "schema"; "day-v1.json" ]
  in
  let build_tree = List.fold_left Filename.concat prefix [ "schema"; "day-v1.json" ] in
  if Sys.file_exists installed then Some installed else if Sys.file_exists build_tree then Some build_tree else None

(* An ordinary OCaml string, NOT a template: it describes the TREE, not the
   calendar, so it has no business in the template vocabulary. *)
let index_html ~from_y ~to_y =
  let b = Buffer.create 4096 in
  Buffer.add_string b
    "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">\n\
     <title>colitur</title>\n\
     <style>body{font-family:sans-serif;max-width:40em;margin:2em auto;line-height:1.5}\n\
     code{background:#f4f4f4;padding:.1em .3em}</style></head><body>\n\
     <h1>colitur</h1>\n\
     <p>Liturgical calendar of the 1962 Missale Romanum. Citations only \xe2\x80\x94 never scripture text.</p>\n";
  Buffer.add_string b "<h2>Subscribe</h2>\n<ul>\n";
  for y = from_y to to_y do
    Buffer.add_string b (Printf.sprintf "<li><a href=\"ef/%d.ics\">ef/%d.ics</a></li>\n" y y)
  done;
  Buffer.add_string b "</ul>\n<h2>Data</h2>\n<ul>\n";
  for y = from_y to to_y do
    Buffer.add_string b
      (Printf.sprintf
         "<li>%d: <a href=\"ef/%d.json\">json</a> <a href=\"ef/%d.csv\">csv</a> \
          <a href=\"ef/%d.xml\">xml</a> \xe2\x80\x94 per-day at <code>ef/%d/MM/DD.json</code></li>\n"
         y y y y y)
  done;
  Buffer.add_string b
    "</ul>\n<p>Contract: <a href=\"schema/day-v1.json\">schema/day-v1.json</a></p>\n\
     </body></html>\n";
  Buffer.contents b

let publish_report ~lang ~from_y ~to_y ~out ~overlays ~dtstamp ~prune =
  check_dtstamp dtstamp;
  if from_y > to_y then begin
    Printf.eprintf "colitur: --from %d is after --to %d\n" from_y to_y;
    exit 2
  end;
  (* Resolved and read BEFORE any file is written, so a missing/unreadable
     schema fails fast, before the output directory has anything half-
     written in it. [read_file]'s own error text says "cannot read
     template ..." (it was built for Task 9's template reads) -- accurate
     about the mechanism, wrong about the noun, so the message here is
     rebuilt rather than printed verbatim. *)
  let schema =
    match schema_path () with
    | None ->
        Printf.eprintf
          "colitur: cannot find schema/day-v1.json (looked in the installed and build-tree locations)\n";
        exit 2
    | Some p -> (
        match read_file p with
        | Error _ ->
            Printf.eprintf "colitur: cannot read schema %s\n" p;
            exit 2
        | Ok s -> s)
  in
  let written = ref [] in
  let emit rel contents =
    write_file (Filename.concat out rel) contents;
    written := rel :: !written
  in
  for y = from_y to to_y do
    let days = resolved_year_days ~overlays y in
    let v = Colitur_render.View.of_days ~lang ~vocab:Rite_ef.Vocab_ef.vocab ~rite:"ef" ~year:y days in
    let ys = string_of_int y in
    emit ("ef/" ^ ys ^ ".json") (Colitur_render.Emit_json.year v);
    emit ("ef/" ^ ys ^ ".csv") (Colitur_render.Emit_csv.year v);
    emit ("ef/" ^ ys ^ ".xml") (Colitur_render.Emit_xml.year v);
    emit ("ef/" ^ ys ^ ".ics") (Colitur_render.Emit_ics.year ?dtstamp v);
    (* One file per day: the static equivalent of a per-day endpoint.
       [View.of_days] with a one-day list yields 12 months, 11 empty, one
       populated -- exactly the shape a single day's own page needs. *)
    List.iter
      (fun d ->
        let iso = D.to_iso8601 d.Colitur_kernel.Liturgical_day.date in
        let mm = String.sub iso 5 2 and dd = String.sub iso 8 2 in
        let one = Colitur_render.View.of_days ~lang ~vocab:Rite_ef.Vocab_ef.vocab ~rite:"ef" ~year:y [ d ] in
        emit (Printf.sprintf "ef/%s/%s/%s.json" ys mm dd) (Colitur_render.Emit_json.year one))
      days
  done;
  emit "schema/day-v1.json" schema;
  emit "index.html" (index_html ~from_y ~to_y);
  let now = List.sort compare !written in
  (* Every stale entry is validated TWICE before anything is removed --
     see [manifest_entry_is_safe]/[resolves_under]'s own comment above for
     why both layers exist. A rejected entry is skipped and warned about on
     stderr, never fatal: a corrupt or hand-mangled manifest must not make
     `publish` itself unusable -- it completes, having refused to act on
     the bad line. *)
  if prune then
    List.iter
      (fun old ->
        if not (List.mem old now) then
          if not (manifest_entry_is_safe old) then
            Printf.eprintf
              "colitur: refusing to prune manifest entry %S (absolute path or .. component)
" old
          else begin
            let p = Filename.concat out old in
            if Sys.file_exists p then
              if resolves_under out p then begin
                Sys.remove p;
                prune_empty_dirs ~out (Filename.dirname p)
              end
              else
                Printf.eprintf "colitur: refusing to prune %s (resolves outside %s)
" p out
          end)
      (read_manifest out);
  write_file (Filename.concat out manifest_name) (String.concat "\n" now ^ "\n");
  Printf.printf "colitur: wrote %d files to %s\n" (List.length now) out

(* Help and usage are deliberately DIFFERENT things, and the difference is the
   Unix convention rather than a preference: asking for help is a request that
   SUCCEEDED, so [--help] prints to stdout and exits 0 (it can be piped into a
   pager or grepped); being invoked wrongly is an error, so [usage] prints a
   one-liner to stderr and exits 2, keeping stdout clean for whatever the
   caller was really trying to capture. *)
(* Kept in lockstep with dune-project's own [(version ...)] by `make release`,
   which bumps BOTH and refuses to proceed if either edit did not take. Two
   places rather than one because dune's watermarking (`dune subst`) only
   substitutes in a release tarball, not in a plain `dune build` from a
   checkout, so a binary built the ordinary way would report a placeholder.
   A constant edited by the release target is what lectio does too, for the
   same reason. Deliberately NOT embedded in [help_text]: the cram test pins
   help's first line, and a version in it would make every release edit a
   test expectation for no gain. *)
let version = "0.7.0"

let help_text =
  {|colitur -- deterministic liturgical calendar engine (Roman rite, 1962)

usage:
  colitur easter <year>      Easter, and the movable feasts anchored to it
  colitur temporal <year>    the temporal cycle, one line per day
  colitur day <year>         the resolved day identity, one line per day
  colitur readings <year>    the Mass reading citations, one line per day
  colitur day|readings <year> [--overlay FILE ...] [--lang CODE|FILE] [--raw]
  colitur emit --format csv|json|sexp|xml|ics --from Y --to Y
              [--overlay FILE ...] [--dtstamp S] [--lang CODE|FILE] [--raw]
              render a resolved year range through one of five emitters
  colitur table --year Y --template FILE [--flavour X] [--overlay FILE ...]
              [--lang CODE|FILE] [--raw]
  colitur render --template FILE --year Y [--flavour X] [--overlay FILE ...]
              [--lang CODE|FILE] [--raw]
              compute year Y and render it through FILE, a logic-less
              Mustache-family template; table and render are the same
              operation, two names (see "rendering" below)
  colitur publish --from Y --to Y --out DIR [--overlay FILE ...] [--prune]
              [--dtstamp S] [--lang CODE|FILE] [--raw]
              write the static tree: per-year csv/json/xml/ics, one JSON
              file per day, the schema and a generated index (see
              "publish" below)
  colitur lang --list        which language files this build can find
  colitur lang --dump CODE   a language's full key set, in INI form, on stdout
  colitur lang --check FILE  what a language file is missing, and any typo'd key
  colitur config --show      every setting, its value and where it came from
  colitur new-overlay        print a starter overlay file to stdout
  colitur convert FILE.ini   flat INI overlay -> S-expression, on stdout
  colitur check FILE ...     load an overlay, say what it does, exit 2 if not
  colitur -h, --help         this help
  colitur -V, --version      print the version and exit

<year> is a civil year, 1583..9999 inclusive. Each report covers 1 January to
31 December of that year, not a liturgical year.

output formats:
  day       date weekday season week slug rank colour [+commemoration ...] [name]
            2026-04-05 sunday paschaltide 1 ef-easter-sunday class-1 white
  readings  date slug | Epistle | Gospel [| name]
            2026-12-25 ef-nativity | Heb 1:1-12 | John 1:1-14

  A citation contains spaces, so readings uses " | " between its fields while
  day stays space-separated; that is why they are separate commands rather
  than extra columns. The same reasoning is why the resolved display NAME,
  present by default (see "naming" below), is appended as the LAST field
  rather than substituted for the slug shown above: a name may itself
  contain spaces, and inserting it earlier in the row would break every
  fixed-position field that follows it. It is present only when it differs
  from the slug already shown -- under --raw, or any language with no entry
  for that particular day, the trailing field is simply absent, which is
  what makes --raw byte-identical to this program's pre-naming output.

  emit      one schema (season, week, slug, rank, colour, subject, names,
            citations, commemorations), rendered five ways: csv (RFC 4180,
            one header for the whole run), json, sexp, xml (schema/colitur-
            v1.xsd) and ics (RFC 5545). --from/--to give a civil-year range,
            inclusive. --dtstamp fixes the ics DTSTAMP so two runs over the
            same data are byte-identical -- the engine reads no clock.

overlays:
  --overlay FILE (repeatable, ordered; -o) applies a user calendar ON TOP of
            the shipped universal one, never instead of it, so local feasts
            add to it rather than replacing it. Later files win over earlier
            ones, and over the universal calendar, when they name the same
            slug. Accepted on `day`, `readings`, `emit`, `table`, `render` and
            `publish` -- `easter` and `temporal` read no sanctoral data, so
            the flag is refused there rather than silently ignored.

            An overlay is applied, NOT validated: colitur's test layers assert
            things about the shipped calendar and cannot vouch for a file you
            supply. A directive naming a slug that does not exist warns on
            stderr and the run continues; a file that fails to load is fatal.

            To write one:

              colitur new-overlay > my-parish.sexp   # a commented starter
              $EDITOR my-parish.sexp
              colitur check my-parish.sexp           # parses? every directive hit?
              colitur day 2026 --overlay my-parish.sexp

            `check` reports what each directive targets and exits 2 if a file
            will not load or a directive matched nothing, so it fits a
            Makefile or a pre-commit hook. It does not check a calendar
            against the rubrics -- nothing here can.

            A flatter INI form exists for simple calendars, converted with
            `colitur convert`, which verifies its own output before emitting
            it. See colitur-overlay(5) for both forms.

            In an added celebration, `citations` and `layer` may be omitted:
            they default to empty and to the overlay's own id. Dates may be
            (Fixed (month M) (day D)), (Easter_offset N) signed, or
            (Nth_weekday (month M) (nth N) (weekday W)) with N negative to
            count from the end of the month.

naming:
  --lang CODE|FILE applies to `day`, `readings`, `emit`, `table`, `render`
            and `publish`. A CODE (e.g. `la`, `en`) is looked up as
            <lang-dir>/CODE.ini; a value containing '/' or ending ".ini" is
            read as a literal path instead. Default `la`, overridable by a
            config file (see below). An unknown language is a hard ERROR
            naming what is available (try `colitur lang --list`), never a
            silent fallback to Latin -- a booklet quietly printed in the
            wrong language is worse than one that refuses to print. A
            language file may declare `fallback = CODE` in its [meta]
            section, so a partial translation shows its fallback language
            for the keys it does not itself carry, rather than bare slugs.

  --raw     restores every command's pre-naming output: `name` (and every
            other localised field `emit`'s schema carries) equals the bare
            machine slug, exactly as if no language had ever been resolved.
            This is not a special case threaded through the naming code --
            it is `colitur lang`'s own identity table, under which every
            lookup echoes its key back unchanged.

  colitur lang --list         which language files this build can find, and
                               each one's own declared fallback, if any.
  colitur lang --dump CODE    the named language's full key set, in INI
                               form, on stdout -- a starting point for a new
                               translation, or a way to diff two versions of
                               one.
  colitur lang --check FILE   what a language file is MISSING (a real slug
                               with no entry) and, separately, any entry
                               naming a slug that does not exist at all (a
                               typo, silently dead otherwise) -- exits 1 if
                               anything is unknown, so it fits a Makefile or
                               a pre-commit hook.
  colitur config --show       every effective setting -- lang, overlay,
                               template, format -- its resolved value, and
                               where it came from: `flag`, `config` or
                               `default`. See colitur-config(5) for the
                               config file's location and full precedence.

rendering:
  --template FILE (required on `table`/`render`) is a logic-less Mustache-
            family template: {{placeholder}}, {{#section}}...{{/section}},
            {{^inverted}}...{{/inverted}}, {{!comment}} -- nothing else. It is
            DATA, never a program: no partials, no lambdas, no expression
            evaluation, no filesystem or process access, and no "raw" or
            triple-brace form that could opt out of escaping. The value it
            renders against is the same schema `emit` uses (season, week,
            slug, rank, colour, subject, names, citations, commemorations),
            reshaped into a booklet (`days`) and a month grid (`weeks`, with
            padding cells for the leading/trailing blanks); see
            colitur-templates(5) for the full field list, the syntax, and
            the one remaining scope hazard (`num` -- both a month and a week
            carry it, and only the innermost one is ever meant). `name` is a
            plain resolved string, not a lang-keyed object, so it carries no
            equivalent hazard of its own.

  --flavour X selects how interpolated VALUES are escaped (never the
            template's own literal markup, which is the author's). One of:

              latex   typst   groff   html   xml   ics   none

            Inferred from --template's extension when --flavour is omitted:

              .tex              -> latex
              .typ              -> typst
              .ms .mom .me      -> groff
              .html .htm        -> html
              .xml              -> xml
              .ics              -> ics
              .md .adoc .txt    -> none (no metacharacters are escaped;
                                   Markdown/AsciiDoc/plain text have no fixed
                                   metacharacter set, so escaping them here
                                   would produce worse output than leaving
                                   them alone)

            An extension colitur does not recognise is a hard ERROR naming
            the seven flavours above, never a silent fallback to `none`:
            guessing wrong produces output that looks fine until the
            metacharacters it silently failed to escape show up.

  `table` and `render` are the SAME operation under two names. The design
            this project followed originally sketched `compute | render` as a
            Unix pipe, with `render` reading a serialised view back from
            stdin. That is deliberately not built: honouring the pipe would
            need a JSON *parser*, purely so this program could re-read a view
            it had just serialised itself -- a second hand-rolled component,
            and a second place for the published contract to drift, for no
            benefit over calling the view builder directly in the same
            process. There is therefore no stdin-fed `render`; `colitur emit
            --format json | jq` still composes for real pipe use, because
            that JSON is the OUTPUT, never something colitur itself parses
            back in.

publish:
  --out DIR (required) writes the static tree that IS this program's API:
            any web server or git repo can serve it as-is, and nothing runs
            at request time.

              ef/<year>.{json,csv,xml,ics}   one civil year, all days
              ef/<year>/<mm>/<dd>.json       one file per day
              schema/day-v1.json             the published JSON contract
              index.html                     a generated index page
              .colitur-manifest              every path this run wrote

            Deterministic: publishing the same --from/--to range twice
            produces a byte-identical tree (--dtstamp behaves exactly as on
            `emit`). That is what makes publishing into a git repo safe --
            `git status` shows only real change, and you review an actual
            diff before pushing.

            Non-destructive: publish writes only files it owns, and records
            every one in .colitur-manifest. A file you put in the output
            directory yourself is never in that manifest, so it is never
            touched, whether or not --prune is given. --prune additionally
            removes manifest entries from a PREVIOUS run that this run did
            not rewrite (e.g. an earlier year's per-day files, when you
            publish a different range into the same directory) -- never
            anything the manifest does not name.

environment:
  COLITUR_DATA_DIR
            Read the calendar data from this directory instead of the
            installed (<prefix>/share/colitur/ef) or build-tree location.
            If it is set and holds no sanctoral.sexp, colitur exits 2 rather
            than silently falling back to a different copy of the data.

exit status:
  0  success
  2  bad usage, year out of range, or the calendar data could not be read

Reading references only (e.g. "Jn 3:16"); never scripture text.
See colitur(1) for the full description and the sources it computes against,
colitur-overlay(5) for the overlay file format in full,
colitur-templates(5) for the template format in full -- the syntax, the
remaining scope hazard, the seven flavours' escaping, and the full view-model
field reference -- and colitur-config(5) for the config file's location and
precedence in full.|}

let print_help () =
  print_endline help_text;
  exit 0

let usage () =
  prerr_endline
    "colitur: usage: colitur easter <year> | colitur temporal <year> | colitur day <year> | colitur \
     readings <year> | colitur emit --format FMT --from Y --to Y | colitur table --year Y --template \
     FILE | colitur render --template FILE --year Y | colitur publish --from Y --to Y --out DIR | \
     colitur lang --list|--dump CODE|--check FILE | colitur config --show | colitur check FILE | \
     colitur new-overlay  (try: colitur --help)";
  exit 2

let with_year ys f =
  match int_of_string_opt ys with
  | Some y when y >= 1583 && y <= 9999 -> f y
  | Some y ->
      Printf.eprintf "colitur: year %d out of range 1583..9999\n" y;
      exit 2
  | None -> usage ()

(* Flags are stripped first, then the remaining words are matched as
   command + year. The alternative -- extending the exact-array patterns
   below -- does not survive a REPEATABLE flag: [--overlay a --overlay b] is a
   different array shape from [--overlay a], and every additional flag would
   multiply the patterns again. Hand-rolled because the dependency list is
   frozen and this is fifteen lines.

   [--overlay] accumulates in the order given, and that order is load-bearing
   ({!Overlay.merge} is last-writer-wins), so the list is reversed exactly
   once at the end rather than callers guessing.

   [--format]/[--from]/[--to]/[--dtstamp] (Task 8, `emit`) are each single-
   valued, unlike [--overlay], so they are plain [string option] fields
   rather than accumulating lists. *)
(* [year]/[template]/[flavour] (Task 9, `table`/`render`) are each single-
   valued, the same shape as [format]/[from_y]/[to_y]/[dtstamp] above --
   `table`/`render` take one year and one template file, never a range or a
   repeatable list. *)
(* [out] (Task 12, `publish`) is single-valued like [format]/[year]/etc.
   [prune] is a plain boolean flag -- every other field up to here takes a
   value, but [--prune] does not, so it cannot reuse the `"--flag" :: v ::
   rest` shape the value-taking flags share below. *)
(* [lang]/[raw] (Task 6): [lang] is single-valued like [format]/[template]/
   etc (a language CODE or a file path); [raw] is a second plain boolean,
   the same shape as [prune]. [dump]/[check]/[list]/[show] (Task 7,
   `colitur lang`/`colitur config`) follow the identical two shapes --
   [dump]/[check] each take one value, [list]/[show] are bare. *)
type parsed_args = {
  overlays : string list;
  format : string option;
  from_y : string option;
  to_y : string option;
  dtstamp : string option;
  year : string option;
  template : string option;
  flavour : string option;
  out : string option;
  prune : bool;
  lang : string option;
  raw : bool;
  dump : string option;
  check : string option;
  list : bool;
  show : bool;
  positional : string list;
}

let parse_args argv =
  let rec go acc = function
    | [] -> Ok { acc with overlays = List.rev acc.overlays; positional = List.rev acc.positional }
    | ("--overlay" | "-o") :: path :: rest -> go { acc with overlays = path :: acc.overlays } rest
    | [ ("--overlay" | "-o") ] -> Error "--overlay needs a file path"
    | "--format" :: v :: rest -> go { acc with format = Some v } rest
    | [ "--format" ] -> Error "--format needs a value"
    | "--from" :: v :: rest -> go { acc with from_y = Some v } rest
    | [ "--from" ] -> Error "--from needs a value"
    | "--to" :: v :: rest -> go { acc with to_y = Some v } rest
    | [ "--to" ] -> Error "--to needs a value"
    | "--dtstamp" :: v :: rest -> go { acc with dtstamp = Some v } rest
    | [ "--dtstamp" ] -> Error "--dtstamp needs a value"
    | "--year" :: v :: rest -> go { acc with year = Some v } rest
    | [ "--year" ] -> Error "--year needs a value"
    | "--template" :: v :: rest -> go { acc with template = Some v } rest
    | [ "--template" ] -> Error "--template needs a value"
    | "--flavour" :: v :: rest -> go { acc with flavour = Some v } rest
    | [ "--flavour" ] -> Error "--flavour needs a value"
    | "--out" :: v :: rest -> go { acc with out = Some v } rest
    | [ "--out" ] -> Error "--out needs a directory path"
    | "--prune" :: rest -> go { acc with prune = true } rest
    | "--lang" :: v :: rest -> go { acc with lang = Some v } rest
    | [ "--lang" ] -> Error "--lang needs a language code or file path"
    | "--raw" :: rest -> go { acc with raw = true } rest
    | "--dump" :: v :: rest -> go { acc with dump = Some v } rest
    | [ "--dump" ] -> Error "--dump needs a language code"
    | "--check" :: v :: rest -> go { acc with check = Some v } rest
    | [ "--check" ] -> Error "--check needs a file path"
    | "--list" :: rest -> go { acc with list = true } rest
    | "--show" :: rest -> go { acc with show = true } rest
    (* The recognised bare flags pass through as positional words for the
       dispatch below to match; anything else beginning with '-' is rejected
       rather than silently treated as a command or a year. *)
    | arg :: _
      when String.length arg > 1
           && arg.[0] = '-'
           && not (List.mem arg [ "-h"; "--help"; "-V"; "--version" ]) ->
        Error (Printf.sprintf "unknown option %s" arg)
    | arg :: rest -> go { acc with positional = arg :: acc.positional } rest
  in
  go
    { overlays = []; format = None; from_y = None; to_y = None; dtstamp = None; year = None;
      template = None; flavour = None; out = None; prune = false; lang = None; raw = false;
      dump = None; check = None; list = false; show = false; positional = [] }
    argv

(* Sibling to [reject_overlays_for]: `emit`'s own four flags have no meaning
   on any other command (they take a single [<year>] positional, not a
   [--from]/[--to] range), so accepting and silently dropping them would be
   the same failure mode `--overlay` already refuses on `easter`/`temporal`. *)
let reject_emit_flags_for cmd ~format ~from_y ~to_y ~dtstamp =
  if format <> None || from_y <> None || to_y <> None || dtstamp <> None then begin
    Printf.eprintf
      "colitur: --format/--from/--to/--dtstamp have no effect on `%s`; refusing rather than ignoring them\n"
      cmd;
    exit 2
  end

(* [easter] reads no calendar data at all, and [temporal] deliberately runs the
   temporal cycle BEFORE any sanctoral layer exists, so an overlay could not
   affect either. Accepting the flag there and silently ignoring it is the
   failure mode this project refuses everywhere else -- it is an error. *)
let reject_overlays_for cmd overlays =
  if overlays <> [] then begin
    Printf.eprintf "colitur: --overlay has no effect on `%s` (it reads no sanctoral data); refusing rather than ignoring it\n" cmd;
    exit 2
  end

(* Sibling to [reject_emit_flags_for]/[reject_overlays_for]: `table`/`render`'s
   own three flags (Task 9) have no meaning on any other command, so accepting
   and silently dropping them would be the same failure mode this project
   already refuses everywhere else. *)
let reject_table_flags_for cmd ~year ~template ~flavour =
  if year <> None || template <> None || flavour <> None then begin
    Printf.eprintf
      "colitur: --year/--template/--flavour have no effect on `%s`; refusing rather than ignoring them\n"
      cmd;
    exit 2
  end

(* Sibling to [reject_emit_flags_for]/[reject_table_flags_for]: `--format`
   has no meaning on `publish` (it always writes all four whole-year
   formats plus the per-day JSON tree, never a single chosen one), so
   accepting and silently dropping it would be the same failure mode this
   project already refuses everywhere else. Narrower than
   [reject_emit_flags_for] on purpose -- `publish` legitimately takes
   --from/--to/--dtstamp, so that blanket check cannot be reused here. *)
let reject_format_for cmd format =
  if format <> None then begin
    Printf.eprintf "colitur: --format has no effect on `%s`; refusing rather than ignoring it\n" cmd;
    exit 2
  end

(* Sibling to the three rejectors above: `--out`/`--prune` (Task 12) have no
   meaning on any command except `publish`. *)
let reject_publish_flags_for cmd ~out ~prune =
  if out <> None || prune then begin
    Printf.eprintf "colitur: --out/--prune have no effect on `%s`; refusing rather than ignoring them\n" cmd;
    exit 2
  end

(* Sibling to the four rejectors above: `--lang`/`--raw` (Task 6) have
   meaning only on the commands that resolve display names --
   `day`/`readings`/`emit`/`table`/`render`/`publish` -- and not on
   `easter`/`temporal` (read no sanctoral data, exactly like `--overlay`),
   `check`/`convert`/`new-overlay` (operate on overlay files, not a
   rendered calendar), or `lang`/`config` themselves (which take their OWN
   flags, `--dump`/`--check`/`--list`/`--show`, disjoint from these). *)
let reject_lang_for cmd ~lang ~raw =
  if lang <> None || raw then begin
    Printf.eprintf "colitur: --lang/--raw have no effect on `%s`; refusing rather than ignoring them\n" cmd;
    exit 2
  end

(* Sibling again: `--dump`/`--check`/`--list`/`--show` (Task 7) belong only
   to `colitur lang` and `colitur config` respectively. *)
let reject_lang_subcommand_flags_for cmd ~dump ~check ~list ~show =
  if dump <> None || check <> None || list || show then begin
    Printf.eprintf
      "colitur: --dump/--check/--list/--show have no effect on `%s`; refusing rather than ignoring them\n"
      cmd;
    exit 2
  end

(* `colitur check FILE...` -- load a user overlay, apply it to the real
   shipped calendar, and say what it did, without printing a year of output.

   The gap this closes: an overlay is APPLIED, NOT VALIDATED (the man page says
   so, and it remains true -- the five test layers assert things about the
   SHIPPED calendar and cannot vouch for a user's file). Before this, the only
   way to find out whether your file did what you meant was to generate a whole
   year and grep for your own slug, and the only way to learn that a directive
   matched nothing was to notice a warning scroll past among 365 lines.

   This does not validate a calendar against the rubrics -- it cannot, and
   claiming otherwise would be the overclaim this project avoids elsewhere. It
   answers three narrower questions: does the file parse, does every directive
   find its target, and what does the merged result contain. *)
let check_report paths =
  let ok = ref true in
  List.iter
    (fun path ->
      match Colitur_kernel.Overlay.load Rite_ef.Vocab_ef.rank_of_sexp path with
      | Error e ->
          Printf.printf "%s: FAILED TO LOAD\n  %s\n" path e;
          ok := false
      | Ok o ->
          let n_add, n_sup, n_rep, n_edit =
            List.fold_left
              (fun (a, s, r, e) -> function
                | Colitur_kernel.Overlay.Add _ -> (a + 1, s, r, e)
                | Colitur_kernel.Overlay.Suppress _ -> (a, s + 1, r, e)
                | Colitur_kernel.Overlay.Replace _ -> (a, s, r + 1, e)
                | Colitur_kernel.Overlay.Edit _ -> (a, s, r, e + 1))
              (0, 0, 0, 0) o.Colitur_kernel.Overlay.directives
          in
          Printf.printf "%s: ok -- overlay %s, %d directive(s): %d add, %d suppress, %d replace, %d edit\n"
            path o.Colitur_kernel.Overlay.id
            (List.length o.Colitur_kernel.Overlay.directives) n_add n_sup n_rep n_edit;
          (* Apply it to the REAL shipped calendar, so "matched nothing" is
             judged against the data the user will actually run against, not
             against an empty layer where every Suppress would trivially fail. *)
          (match load_ef_layer ~user_overlays:[ path ] () with
           | Error e ->
               Printf.printf "  applying to the shipped calendar failed: %s\n" e;
               ok := false
           | Ok (_, diagnostics) ->
               let mine =
                 List.filter
                   (fun (d : Colitur_kernel.Overlay.diagnostic) ->
                     String.equal d.Colitur_kernel.Overlay.overlay o.Colitur_kernel.Overlay.id)
                   diagnostics
               in
               if mine = [] then print_endline "  every directive found its target"
               else begin
                 ok := false;
                 List.iter
                   (fun d ->
                     Printf.printf "  MATCHED NOTHING: %s\n"
                       (Colitur_kernel.Overlay.diagnostic_to_string d))
                   mine
               end);
          List.iter
            (function
              | Colitur_kernel.Overlay.Add e ->
                  Printf.printf "  add      %s\n"
                    (Colitur_kernel.Slug.to_string
                       e.Colitur_kernel.Layer.cel.Colitur_kernel.Celebration.slug)
              | Colitur_kernel.Overlay.Suppress s ->
                  Printf.printf "  suppress %s\n" (Colitur_kernel.Slug.to_string s)
              | Colitur_kernel.Overlay.Replace (s, _) ->
                  Printf.printf "  replace  %s\n" (Colitur_kernel.Slug.to_string s)
              | Colitur_kernel.Overlay.Edit (s, _) ->
                  Printf.printf "  edit     %s\n" (Colitur_kernel.Slug.to_string s))
            o.Colitur_kernel.Overlay.directives)
    paths;
  exit (if !ok then 0 else 2)

(* `colitur convert FILE.ini` -- the flat INI form to the S-expression one,
   on stdout for redirection.

   A separate step rather than teaching --overlay to sniff the extension, and
   deliberately so: the user gets to SEE what their INI became. When a date
   form was mistyped or an edit silently dropped, "what did the engine
   actually get" is the question, and an invisible transpile cannot answer it.

   {!Overlay_ini.convert} verifies its own output before returning it -- see
   that function's own comment. Nothing is written if the round trip fails. *)
let convert_report path =
  match
    (try Ok (In_channel.with_open_text path In_channel.input_all)
     with Sys_error e -> Error e)
  with
  | Error e ->
      Printf.eprintf "colitur: %s\n" e;
      exit 2
  | Ok text -> (
      match
        Colitur_kernel.Overlay_ini.convert ~rank_of_string:Rite_ef.Vocab_ef.rank_of_string
          ~rank_to_sexp:Rite_ef.Vocab_ef.sexp_of_rank ~rank_of_sexp:Rite_ef.Vocab_ef.rank_of_sexp text
      with
      | Error e ->
          Printf.eprintf "colitur: %s: %s\n" path e;
          exit 2
      | Ok sexp ->
          print_string sexp;
          exit 0)

(* `colitur lang --list` -- what language files this build can find, from
   [lang_dir ()], the same probe [load_lang] itself uses. Each is opened and
   parsed (not merely listed by filename) so a malformed file is flagged
   here rather than only failing later when someone actually tries to use
   it. *)
let lang_list () =
  let dir = lang_dir () in
  match Sys.readdir dir with
  | exception Sys_error _ ->
      Printf.eprintf "colitur: no language directory at %s\n" dir;
      exit 2
  | files ->
      Array.sort compare files;
      Array.iter
        (fun f ->
          if Filename.check_suffix f ".ini" then begin
            let code = Filename.remove_extension f in
            match read_file (Filename.concat dir f) with
            | Ok t -> (
                match Colitur_naming.Lang.of_string t with
                | Ok l ->
                    Printf.printf "%-6s %s\n" code
                      (match Colitur_naming.Lang.fallback_code l with
                       | Some fb -> "(falls back to " ^ fb ^ ")"
                       | None -> "")
                | Error e -> Printf.printf "%-6s (unreadable: %s)\n" code e)
            | Error e -> Printf.printf "%-6s (unreadable: %s)\n" code e
          end)
        files

(* Every slug the engine can actually emit -- the observed office AND every
   commemoration/transfer, exactly the four-field walk
   test/test_lang_coverage.ml's own [slugs_of_day] performs -- over the same
   2020-2045 window that test measures against. This is [colitur lang
   --check]'s own reference set: a language file is judged against what the
   engine can really produce, not against an arbitrarily chosen sample. *)
let all_known_slugs () =
  match load_ef_data () with
  | Error msg ->
      Printf.eprintf "colitur: %s\n" msg;
      exit 2
  | Ok (layer, lectionary, commons) ->
      let context = Rite_ef.context ~lectionary ~commons in
      let slug (c : _ Colitur_kernel.Celebration.t) =
        Colitur_kernel.Slug.to_string c.Colitur_kernel.Celebration.slug
      in
      let slugs_of_day
          (d : (Rite_ef.Vocab_ef.season, Rite_ef.Vocab_ef.rank) Colitur_kernel.Liturgical_day.t) =
        slug d.Colitur_kernel.Liturgical_day.observed
        :: List.map (fun (c, _priv) -> slug c) d.Colitur_kernel.Liturgical_day.commemorations
        @ (match d.Colitur_kernel.Liturgical_day.transferred_in with
           | None -> []
           | Some c -> [ slug c ])
        @ List.map (fun (c, _date) -> slug c) d.Colitur_kernel.Liturgical_day.transferred_out
      in
      let seen = Hashtbl.create 1024 in
      for y = 2020 to 2045 do
        Array.iter
          (fun d -> List.iter (fun s -> Hashtbl.replace seen s ()) (slugs_of_day d))
          (Colitur_kernel.Calendar.year context layer y)
      done;
      Hashtbl.fold (fun k () acc -> k :: acc) seen [] |> List.sort compare

(* `colitur lang --dump CODE` -- the named language's full key set, in INI
   form, on stdout for redirection. [Lang.keys] already returns every
   (section-qualified key, value) pair SORTED as one flat list (lang.mli):
   because every key sharing a section also shares that section's own
   string prefix, and no two section names are a prefix of one another, the
   sort keeps every section's own keys contiguous -- so a single pass
   emitting a fresh `[section]` header each time the prefix changes
   reconstructs proper INI blocks, in a FIXED (alphabetical) order, with no
   second grouping step. Two dumps of the same table are therefore
   byte-identical, which is what makes `--dump` diffable across two
   versions of a translation. *)
let lang_dump code =
  let path = Filename.concat (lang_dir ()) (code ^ ".ini") in
  match read_file path with
  | Error _ ->
      Printf.eprintf "colitur: no language %S (looked in %s); try: colitur lang --list\n" code
        (lang_dir ());
      exit 2
  | Ok text -> (
      match Colitur_naming.Lang.of_string text with
      | Error msg ->
          Printf.eprintf "colitur: %s: %s\n" path msg;
          exit 2
      | Ok t ->
          Printf.printf "[meta]\nlang = %s\n" (Colitur_naming.Lang.code t);
          (match Colitur_naming.Lang.fallback_code t with
           | Some fb -> Printf.printf "fallback = %s\n" fb
           | None -> ());
          let cur = ref "" in
          List.iter
            (fun (qk, v) ->
              match String.index_opt qk '.' with
              | None -> ()
              | Some i ->
                  let section = String.sub qk 0 i in
                  let key = String.sub qk (i + 1) (String.length qk - i - 1) in
                  if section <> !cur then begin
                    print_newline ();
                    Printf.printf "[%s]\n" section;
                    cur := section
                  end;
                  Printf.printf "%s = %s\n" key v)
            (Colitur_naming.Lang.keys t))

(* `colitur lang --check FILE` -- the difference between "you may write a
   language file" and "you can": without this, a translator has to
   reverse-engineer the key set from source. Reports what is MISSING
   (a real slug the file has no entry for) AND what is UNKNOWN (a
   [celebration] key matching no real slug at all -- a typo, or a slug from
   a version of colitur this file was not written against) -- a key
   matching nothing is silently dead, and its author would otherwise never
   learn why their translation does not appear. Exits 2 only on UNKNOWN: a
   partial file (some slugs missing) is exactly the shippable, in-progress
   state [Lang.with_fallback] exists for, but a typo naming nothing is
   always worth flagging as a failure, the same "never silently dead"
   standard [Config.unknown_keys] holds a config file to. *)
let lang_check path =
  match read_file path with
  | Error msg ->
      Printf.eprintf "colitur: %s\n" msg;
      exit 2
  | Ok text -> (
      match Colitur_naming.Lang.of_string text with
      | Error msg ->
          Printf.eprintf "colitur: %s: %s\n" path msg;
          exit 2
      | Ok t ->
          let known = all_known_slugs () in
          let have =
            List.filter_map
              (fun (k, _) ->
                match String.index_opt k '.' with
                | Some i when String.sub k 0 i = "celebration" ->
                    Some (String.sub k (i + 1) (String.length k - i - 1))
                | _ -> None)
              (Colitur_naming.Lang.keys t)
          in
          let missing = List.filter (fun s -> not (List.mem s have)) known in
          let unknown = List.filter (fun s -> not (List.mem s known)) have in
          List.iter (fun s -> Printf.printf "missing: %s\n" s) (List.sort compare missing);
          List.iter (fun s -> Printf.printf "unknown slug: %s\n" s) (List.sort compare unknown);
          Printf.printf "%s: %d of %d celebrations named, %d missing, %d unknown\n" path
            (List.length known - List.length missing)
            (List.length known) (List.length missing) (List.length unknown);
          if unknown <> [] then exit 1)

(* `colitur config --show` -- each effective setting, its resolved value,
   and where it came from (`flag`/`config`/`default`), via
   [Config.resolve]. There is deliberately no separate "provenance"
   function: [resolve] already returns the source alongside the value
   (config.mli), and a second entry point recomputing it independently
   would let the two disagree. [lang]/[template]/[format] are scalars, each
   resolved the same way `colitur day`/`table`/`emit` would resolve them
   given these SAME command-line flags (so `config --show --lang fr` shows
   exactly what a real `--lang fr` run would use); [overlay] is a list, so
   it has no single "value" to resolve -- shown as one line per effective
   entry instead, with its own source. *)
let config_show ~lang_flag ~template_flag ~format_flag ~overlays_flag config =
  let cpath = config_path () in
  Printf.printf "config file: %s (%s)\n" cpath
    (if cpath <> "" && Sys.file_exists cpath then "exists" else "not found");
  let scalar name flag cfgval default =
    let v, src = Colitur_naming.Config.resolve ~flag ~config:cfgval ~default in
    Printf.printf "%-10s %-24s (%s)\n" name v src
  in
  scalar "lang" lang_flag (Colitur_naming.Config.lang config) "la";
  scalar "template" template_flag (Colitur_naming.Config.template config) "(none)";
  scalar "format" format_flag (Colitur_naming.Config.format config) "(none)";
  (match overlays_flag with
   | _ :: _ as l -> List.iter (fun o -> Printf.printf "%-10s %-24s (%s)\n" "overlay" o "flag") l
   | [] -> (
       match Colitur_naming.Config.overlays config with
       | [] -> Printf.printf "%-10s %-24s (%s)\n" "overlay" "(none)" "default"
       | l -> List.iter (fun o -> Printf.printf "%-10s %-24s (%s)\n" "overlay" o "config") l))

(* `colitur new-overlay` -- a starter file on stdout, for redirection.
   Deliberately printed rather than written: the user picks the path, and a
   command that creates files where it likes is a worse citizen. Every value is
   a placeholder that WILL show up in output if left unedited, so a
   half-finished overlay is visible rather than silently inert. *)
let new_overlay_template =
  {template|; A colitur overlay: a local calendar applied ON TOP of the universal 1962
; one, never instead of it. Save this, edit it, then:
;
;   colitur check   my-parish.sexp        -- does it parse, does it apply
;   colitur day 2026 --overlay my-parish.sexp
;
; Directives are Add, Suppress, Replace and Edit, applied in the order written.
; Last writer wins, so a later file may override an earlier one -- or a
; universal entry -- by naming its slug.
((id my-parish)
  (directives
    ; A fixed-date local feast. `citations` and `layer` may be omitted: they
    ; default to empty and to this overlay's own id.
    ((Add
       ((date (Fixed (month 5) (day 20)))
         (cel
           ((slug my-local-patron)
             (names ((la "Sancti Patroni Nostri") (en "Our Local Patron")))
             ; rank:   Class1 | Class2 | Class3 | Class4
             ; status: Feast | Commemoration_only
             ; colour: White | Red | Violet | Green | Black | Rose
             ; subject: Lord | Bvm | Saint | Temporal
             (rank Class3) (status Feast) (colour White) (subject Saint)))))
     ; A MOVABLE feast: the first Sunday of October. `nth` may be negative to
     ; count from the end of the month (-1 is the last).
     (Add
       ((date (Nth_weekday (month 10) (nth 1) (weekday Sun)))
         (cel
           ((slug my-dedication)
             (names ((en "Dedication of Our Church")))
             ; A church's own dedication anniversary is I class IN THAT CHURCH
             ; (RG 91 entry 4). At III class it would lose to the Sunday it
             ; lands on every year.
             (rank Class1) (status Feast) (colour White) (subject Saint)))))
     ; A feast reckoned from Easter: Easter_offset counts days, signed.
     ; (Easter itself is 0; Ash Wednesday is -46; Corpus Christi is +60.)
     ; (Add
     ;   ((date (Easter_offset 60))
     ;     (cel ((slug my-easter-relative) (names ((en "Example")))
     ;           (rank Class3) (status Feast) (colour White) (subject Saint)))))
     ;
     ; Remove a universal entry your calendar does not keep:
     ; (Suppress some-universal-slug)
     ;
     ; Keep the entry but change one field:
     ; (Edit some-universal-slug ((Set_colour Red)))
     )))
|template}

let () =
  match parse_args (List.tl (Array.to_list Sys.argv)) with
  | Error msg ->
      Printf.eprintf "colitur: %s\n" msg;
      usage ()
  | Ok { overlays; format; from_y; to_y; dtstamp; year; template; flavour; out; prune; lang;
         raw; dump; check; list; show; positional } -> (
      let reject_emit = reject_emit_flags_for ~format ~from_y ~to_y ~dtstamp in
      let reject_table = reject_table_flags_for ~year ~template ~flavour in
      let reject_publish = reject_publish_flags_for ~out ~prune in
      let reject_lang = reject_lang_for ~lang ~raw in
      let reject_lang_sub = reject_lang_subcommand_flags_for ~dump ~check ~list ~show in
      (* Loaded once, unconditionally: a config file the user wrote and
         colitur cannot honour (missing HOME aside, [load_config] treats
         that as "no config" rather than an error) is worth surfacing on
         EVERY invocation, `--help` included, not only the commands that
         happen to consult it -- the same "never silently ignored"
         discipline [COLITUR_DATA_DIR] already gets. *)
      let config = load_config () in
      (* Resolved only inside the branches that actually consume it, as a
         thunk rather than eagerly here: [load_lang] can [exit 2] (an
         unknown language, a malformed file), and a command that never asked
         for naming at all (`easter`, `check`, ...) must not be able to fail
         on account of a language it never uses -- those commands reject
         [--lang]/[--raw] outright instead, via [reject_lang] above. *)
      let resolved_lang () = load_lang ~raw ~flag:lang ~config:(Colitur_naming.Config.lang config) in
      (* Config supplies a DEFAULT overlay list only when NO --overlay was
         given at all -- not merged with a partial CLI list -- so the
         precedence stays exactly flag > config > default, the same
         direction every other setting resolves in, rather than a list
         merge whose ordering nothing documents. *)
      let effective_overlays =
        if overlays = [] then Colitur_naming.Config.overlays config else overlays
      in
      match positional with
      | [ ("-h" | "--help" | "help") ] ->
          reject_overlays_for "--help" overlays;
          reject_emit "--help";
          reject_table "--help";
          reject_publish "--help";
          reject_lang "--help";
          reject_lang_sub "--help";
          print_help ()
      | [ ("-V" | "--version" | "version") ] ->
          reject_overlays_for "--version" overlays;
          reject_emit "--version";
          reject_table "--version";
          reject_publish "--version";
          reject_lang "--version";
          reject_lang_sub "--version";
          print_endline version;
          exit 0
      | [ "easter"; ys ] ->
          reject_overlays_for "easter" overlays;
          reject_emit "easter";
          reject_table "easter";
          reject_publish "easter";
          reject_lang "easter";
          reject_lang_sub "easter";
          with_year ys easter_report
      | [ "temporal"; ys ] ->
          reject_overlays_for "temporal" overlays;
          reject_emit "temporal";
          reject_table "temporal";
          reject_publish "temporal";
          reject_lang "temporal";
          reject_lang_sub "temporal";
          with_year ys temporal_report
      | "check" :: (_ :: _ as files) ->
          reject_overlays_for "check" overlays;
          reject_emit "check";
          reject_table "check";
          reject_publish "check";
          reject_lang "check";
          reject_lang_sub "check";
          check_report files
      | [ "convert"; path ] ->
          reject_overlays_for "convert" overlays;
          reject_emit "convert";
          reject_table "convert";
          reject_publish "convert";
          reject_lang "convert";
          reject_lang_sub "convert";
          convert_report path
      | [ "new-overlay" ] ->
          reject_overlays_for "new-overlay" overlays;
          reject_emit "new-overlay";
          reject_table "new-overlay";
          reject_publish "new-overlay";
          reject_lang "new-overlay";
          reject_lang_sub "new-overlay";
          print_string new_overlay_template;
          exit 0
      | [ "lang" ] -> (
          reject_overlays_for "lang" overlays;
          reject_emit "lang";
          reject_table "lang";
          reject_publish "lang";
          reject_lang "lang";
          if show then begin
            Printf.eprintf "colitur: --show has no effect on `lang`; refusing rather than ignoring it\n";
            exit 2
          end;
          match (list, dump, check) with
          | true, None, None -> lang_list ()
          | false, Some code, None -> lang_dump code
          | false, None, Some path -> lang_check path
          | false, None, None ->
              Printf.eprintf "colitur: lang requires one of --list, --dump CODE or --check FILE\n";
              exit 2
          | _ ->
              Printf.eprintf "colitur: lang takes only one of --list, --dump CODE or --check FILE\n";
              exit 2)
      | [ "config" ] ->
          (* Unlike every other subcommand's own rejector, `config --show`
             deliberately ACCEPTS --lang/--template/--format/--overlay: they
             are the very settings it previews the resolution of (so
             `config --show --lang fr` reports exactly what a real `--lang
             fr` run on any other command would resolve to), so none of
             [reject_lang]/[reject_overlays_for]/the format half of
             [reject_emit] apply here. Everything with no meaning for a
             config preview is still refused, not silently ignored. *)
          reject_table "config";
          reject_publish "config";
          if from_y <> None || to_y <> None || dtstamp <> None then begin
            Printf.eprintf
              "colitur: --from/--to/--dtstamp have no effect on `config`; refusing rather than ignoring them\n";
            exit 2
          end;
          if raw then begin
            Printf.eprintf "colitur: --raw has no effect on `config`; refusing rather than ignoring it\n";
            exit 2
          end;
          if dump <> None || check <> None || list then begin
            Printf.eprintf
              "colitur: --dump/--check/--list have no effect on `config`; refusing rather than ignoring them\n";
            exit 2
          end;
          if not show then begin
            Printf.eprintf "colitur: config requires --show\n";
            exit 2
          end;
          config_show ~lang_flag:lang ~template_flag:template ~format_flag:format ~overlays_flag:overlays
            config
      | [ "day"; ys ] ->
          reject_emit "day";
          reject_table "day";
          reject_publish "day";
          reject_lang_sub "day";
          with_year ys (day_report ~lang:(resolved_lang ()) ~overlays:effective_overlays)
      | [ "readings"; ys ] ->
          reject_emit "readings";
          reject_table "readings";
          reject_publish "readings";
          reject_lang_sub "readings";
          with_year ys (readings_report ~lang:(resolved_lang ()) ~overlays:effective_overlays)
      | [ "emit" ] -> (
          reject_table "emit";
          reject_publish "emit";
          reject_lang_sub "emit";
          match (match format with Some f -> Some f | None -> Colitur_naming.Config.format config) with
          | None ->
              Printf.eprintf "colitur: emit requires --format csv|json|sexp|xml|ics\n";
              exit 2
          | Some format -> (
              match (from_y, to_y) with
              | None, _ | _, None ->
                  Printf.eprintf "colitur: emit requires --from YEAR and --to YEAR\n";
                  exit 2
              | Some from_ys, Some to_ys ->
                  let lang_t = resolved_lang () in
                  with_year from_ys (fun from_y ->
                      with_year to_ys (fun to_y ->
                          emit_report ~lang:lang_t ~format ~overlays:effective_overlays ~dtstamp ~from_y
                            ~to_y))))
      | [ ("table" | "render") as cmd ] -> (
          reject_emit cmd;
          reject_publish cmd;
          reject_lang_sub cmd;
          match (match template with Some t -> Some t | None -> Colitur_naming.Config.template config) with
          | None ->
              Printf.eprintf "colitur: %s requires --year YEAR and --template FILE\n" cmd;
              exit 2
          | Some template -> (
              match year with
              | None ->
                  Printf.eprintf "colitur: %s requires --year YEAR and --template FILE\n" cmd;
                  exit 2
              | Some ys ->
                  let lang_t = resolved_lang () in
                  with_year ys (fun y ->
                      table_report ~lang:lang_t ~template ~flavour_opt:flavour ~overlays:effective_overlays y)
              ))
      | [ "publish" ] -> (
          reject_table "publish";
          reject_format_for "publish" format;
          reject_lang_sub "publish";
          match out with
          | None ->
              Printf.eprintf "colitur: publish requires --out DIR\n";
              exit 2
          | Some out -> (
              match (from_y, to_y) with
              | None, _ | _, None ->
                  Printf.eprintf "colitur: publish requires --from YEAR and --to YEAR\n";
                  exit 2
              | Some from_ys, Some to_ys ->
                  let lang_t = resolved_lang () in
                  with_year from_ys (fun from_y ->
                      with_year to_ys (fun to_y ->
                          (* [publish_report] writes many files across a whole
                             year range ([mkdir_p]/[write_file], both above) --
                             an unwritable [--out] parent (EACCES) or an [--out]
                             that names an existing plain file (ENOTDIR) raises
                             from deep inside that loop, same defect class as
                             the template read this project already guards
                             (commit 6bd741b): "--out" is user input too, and
                             the WHOLE call is guarded here rather than each
                             [write_file] site individually, for the same
                             reason that fix guarded the whole read and not
                             only the open. [Unix.mkdir] raises
                             [Unix.Unix_error] directly; [open_out_bin]
                             (stdlib, not the Unix module) wraps the same
                             underlying errno in [Sys_error] instead -- both
                             are real on this path, so both are caught. *)
                          try
                            publish_report ~lang:lang_t ~from_y ~to_y ~out ~overlays:effective_overlays
                              ~dtstamp ~prune
                          with
                          | Unix.Unix_error (e, fn, arg) ->
                              Printf.eprintf "colitur: %s: %s: %s\n" fn arg (Unix.error_message e);
                              exit 2
                          | Sys_error e ->
                              Printf.eprintf "colitur: %s\n" e;
                              exit 2))))
      | _ -> usage ())