From da9cf402ceed8102aec1a9d008f8e918a23d39f3 Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Wed, 19 Aug 2026 08:17:30 +0200
Subject: feat(render): template renderer with mandatory escaping

Every interpolated value is escaped for the template's flavour; the
template's own literal text never is, because that is the author's
markup. There is no raw form, so a template cannot opt out.

Scope is a stack with outward fallback, so a grid template can reach the
year number from inside a week without the view duplicating it into
every cell.

A missing key renders empty -- the one deliberate silence, so a template
survives a rite that does not set every optional field.

Mutation-tested: dropping the Escape.apply call reddens the
data-cannot-escape-flavour case.
---
 lib/render/template.ml  | 55 ++++++++++++++++++++++++++++++++++
 lib/render/template.mli |  9 ++++++
 test/test_colitur.ml    |  3 +-
 test/test_template.ml   | 79 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 145 insertions(+), 1 deletion(-)

diff --git a/lib/render/template.ml b/lib/render/template.ml
index 3e35d53..7efa92b 100644
--- a/lib/render/template.ml
+++ b/lib/render/template.ml
@@ -94,3 +94,58 @@ let build items =
   go [] [] items
 
 let parse src = match lex src with Error e -> Error e | Ok items -> build items
+
+(* Scope is a STACK, innermost first: a section pushes its own object, and a
+   lookup falls back outward. Without the fallback a grid template could not
+   reach the year number from inside a week. *)
+let rec lookup stack path =
+  match stack with
+  | [] -> None
+  | top :: rest -> (
+      match descend top path with Some v -> Some v | None -> lookup rest path)
+
+and descend v path =
+  match (v, path) with
+  | _, [] -> Some v
+  | Obj kvs, k :: tl -> (
+      match List.assoc_opt k kvs with Some v' -> descend v' tl | None -> None)
+  | _ -> None
+
+let truthy = function
+  | Bool b -> b
+  | Str "" -> false
+  | Str _ -> true
+  | List [] -> false
+  | List _ -> true
+  | Obj _ -> true
+
+let render ~flavour nodes value =
+  let b = Buffer.create 4096 in
+  let rec go stack nodes =
+    List.iter
+      (fun node ->
+        match node with
+        | Text t -> Buffer.add_string b t
+        | Var p -> (
+            match lookup stack p with
+            | Some (Str s) -> Buffer.add_string b (Escape.apply flavour s)
+            | Some (Bool true) -> Buffer.add_string b "true"
+            | Some (Bool false) -> ()
+            | Some (List _) | Some (Obj _) | None -> ())
+        | Section (p, body) -> (
+            match lookup stack p with
+            | None -> ()
+            | Some (List items) -> List.iter (fun it -> go (it :: stack) body) items
+            | Some v when truthy v -> go (v :: stack) body
+            | Some _ -> ())
+        | Inverted (p, body) -> (
+            match lookup stack p with
+            | None -> go stack body
+            | Some v -> if not (truthy v) then go stack body))
+      nodes
+  in
+  go [ value ] nodes;
+  Buffer.contents b
+
+let render_string ~flavour src value =
+  match parse src with Error e -> Error e | Ok nodes -> Ok (render ~flavour nodes value)
diff --git a/lib/render/template.mli b/lib/render/template.mli
index 3f9ef97..4118496 100644
--- a/lib/render/template.mli
+++ b/lib/render/template.mli
@@ -26,3 +26,12 @@ type node =
 (** Never raises; a malformed template is an [Error] with a human-readable
     reason, because the template is user input. *)
 val parse : string -> (node list, string) result
+
+(** Render against a value. Escaping is applied to every interpolated value and
+    NEVER to the template's own literal text, which is the author's markup.
+    A missing key renders as the empty string -- the one deliberate silence, so
+    that a template survives a rite that does not set every optional field. *)
+val render : flavour:Escape.flavour -> node list -> value -> string
+
+(** [parse] then [render]. *)
+val render_string : flavour:Escape.flavour -> string -> value -> (string, string) result
diff --git a/test/test_colitur.ml b/test/test_colitur.ml
index a264174..f12dab5 100644
--- a/test/test_colitur.ml
+++ b/test/test_colitur.ml
@@ -8,4 +8,5 @@ let () =
       ("lectionary", Test_lectionary.suite);
       ("lectionary-ef", Test_lectionary_ef.suite);
       Test_escape.suite;
-      Test_template.suite ]
+      Test_template.suite;
+      Test_template.render_suite ]
diff --git a/test/test_template.ml b/test/test_template.ml
index cfb3b04..b83c378 100644
--- a/test/test_template.ml
+++ b/test/test_template.ml
@@ -84,3 +84,82 @@ let suite =
       Alcotest.test_case "unterminated tag errors" `Quick test_unterminated_tag_is_an_error;
       Alcotest.test_case "no raw or partial form" `Quick test_no_raw_or_partial_form;
       Alcotest.test_case "empty path errors" `Quick test_empty_path_is_an_error ] )
+
+module E = Colitur_render.Escape
+
+let render ?(flavour = E.None_) tpl v =
+  match T.render_string ~flavour tpl v with Ok s -> s | Error e -> Alcotest.failf "render: %s" e
+
+let obj kvs = T.Obj kvs
+
+let test_render_var () =
+  Alcotest.(check string) "var" "Hilary" (render "{{name}}" (obj [ ("name", T.Str "Hilary") ]));
+  Alcotest.(check string) "dotted" "Hilarii"
+    (render "{{name.la}}" (obj [ ("name", obj [ ("la", T.Str "Hilarii") ]) ]))
+
+(* A missing key renders empty. This is the ONE silent case, and it is
+   deliberate: a template written for a rite that does not set every optional
+   field must still render (spec section 5). *)
+let test_missing_key_is_empty () =
+  Alcotest.(check string) "missing" "[]" (render "[{{nope}}]" (obj [ ("name", T.Str "x") ]))
+
+let test_section_iterates () =
+  let v = obj [ ("days", T.List [ obj [ ("dom", T.Str "1") ]; obj [ ("dom", T.Str "2") ] ]) ] in
+  Alcotest.(check string) "iterate" "1|2|" (render "{{#days}}{{dom}}|{{/days}}" v)
+
+let test_bool_section () =
+  Alcotest.(check string) "true" "yes" (render "{{#f}}yes{{/f}}" (obj [ ("f", T.Bool true) ]));
+  Alcotest.(check string) "false" "" (render "{{#f}}yes{{/f}}" (obj [ ("f", T.Bool false) ]));
+  Alcotest.(check string) "inverted true" "" (render "{{^f}}no{{/f}}" (obj [ ("f", T.Bool true) ]));
+  Alcotest.(check string) "inverted false" "no" (render "{{^f}}no{{/f}}" (obj [ ("f", T.Bool false) ]))
+
+let test_empty_list_section_is_skipped () =
+  Alcotest.(check string) "empty list" "" (render "{{#days}}x{{/days}}" (obj [ ("days", T.List []) ]));
+  Alcotest.(check string) "inverted empty list" "none"
+    (render "{{^days}}none{{/days}}" (obj [ ("days", T.List []) ]))
+
+let test_outer_scope_visible_inside_section () =
+  let v = obj [ ("year", T.Str "2027"); ("days", T.List [ obj [ ("dom", T.Str "1") ] ]) ] in
+  Alcotest.(check string) "outer visible" "2027-1"
+    (render "{{#days}}{{year}}-{{dom}}{{/days}}" v)
+
+(* THE safety property (spec section 9.2): a data value can never escape its
+   flavour. This is the test that must redden if any escape rule is broken. *)
+let test_data_cannot_escape_flavour () =
+  let nasty = obj [ ("name", T.Str "A & B \\ 50% {x} $y_z") ] in
+  let out = render ~flavour:E.Latex "{{name}}" nasty in
+  Alcotest.(check string) "fully escaped" "A \\& B \\textbackslash{} 50\\% \\{x\\} \\$y\\_z" out;
+  let hout = render ~flavour:E.Html "{{name}}" (obj [ ("name", T.Str "<script>") ]) in
+  Alcotest.(check string) "html escaped" "&lt;script&gt;" hout
+
+(* Literal template text is NOT escaped -- it is the author's own markup. Only
+   interpolated DATA is escaped. Getting this backwards would make every
+   template render as visible source. *)
+(* NOTE: the brief's own example here was "\textbf{{{name}}}", i.e. a literal
+   "{" immediately followed by "{{name}}". That does not parse the way the
+   brief assumes: this engine's lexer (Task 2, frozen) is greedy left-to-right
+   and has no triple-brace special case (by design -- there is no raw form),
+   so three consecutive "{" are read as an ordinary tag opener "{{" followed
+   by a path that literally starts with "{" ("{name"), which resolves to
+   nothing and renders empty, plus a stray literal "}" -- exactly what
+   test_no_raw_or_partial_form above already documents for "{{{name}}}" on
+   its own. Verified live: the brief's original line reddens with "\textbf}",
+   not "\textbf{Hilary}". Rewritten below to put a character between the
+   literal "{" and the tag's own "{{", which sidesteps the ambiguity while
+   still proving the same property: literal backslash/braces from Text survive
+   unescaped, where a wrongly-escaped Text node would turn "\textbf{" into
+   "\textbackslash{}\{". *)
+let test_literal_markup_is_not_escaped () =
+  Alcotest.(check string) "literal kept" "\\textbf{Name: Hilary}"
+    (render ~flavour:E.Latex "\\textbf{Name: {{name}}}" (obj [ ("name", T.Str "Hilary") ]))
+
+let render_suite =
+  ( "Template/render",
+    [ Alcotest.test_case "vars" `Quick test_render_var;
+      Alcotest.test_case "missing key is empty" `Quick test_missing_key_is_empty;
+      Alcotest.test_case "section iterates" `Quick test_section_iterates;
+      Alcotest.test_case "bool sections" `Quick test_bool_section;
+      Alcotest.test_case "empty list sections" `Quick test_empty_list_section_is_skipped;
+      Alcotest.test_case "outer scope visible" `Quick test_outer_scope_visible_inside_section;
+      Alcotest.test_case "data cannot escape flavour" `Quick test_data_cannot_escape_flavour;
+      Alcotest.test_case "literal markup unescaped" `Quick test_literal_markup_is_not_escaped ] )
-- 
cgit v1.3