Unify escape/date helper API; fix current_date_text caching

Make the template.source.sh escape/date helper family follow one
consistent shape: each escaper now has a nameref <name>_to form (hot
path, writes a named variable) plus a thin printf wrapper <name> that
delegates to it. The leading "_" now exclusively marks private
helpers; the public escape API (called from sibling modules) is
unprefixed.

- current_date_text now delegates to current_date_text_to so both
  forms share the SHURIKEN_CURRENT_DATE_TEXT cache; the printf form no
  longer silently re-execs `date` on every direct call. Output
  unchanged.
- Drop the misleading "_" prefix on the public escape API and update
  all callers: _html_escape->html_escape, _css_string_escape->
  css_string_escape, _json_string->json_string, _json_bool->json_bool,
  _json_string_escape->json_string_escape.
- Add the missing JSON nameref forms: json_string_escape_to,
  json_string_to, json_bool_to (printf wrappers delegate to them).
- Add tests: JSON printf-vs-nameref parity and a current_date_text
  caching + nameref-parity check.

No escaping/encoding or date output changes -- API-shape/perf only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 22 insertions, 22 deletions

diff --git a/src/lib/generation-metadata.source.sh b/src/lib/generation-metadata.source.sh
index b75af1b..931bd92 100644
--- a/src/lib/generation-metadata.source.sh
+++ b/src/lib/generation-metadata.source.sh
@@ -5,7 +5,7 @@
 # presentation that stays in the album module. The collector depends on the file
 # counters (count_files / count_incoming_images / count_tree_files, now in
 # image.source.sh), current_timestamp_iso (template.source.sh) and the JSON
-# helpers (_json_string / _json_bool, template.source.sh); all are sourced before
+# helpers (json_string / json_bool, template.source.sh); all are sourced before
 # this module, and these are runtime calls anyway, so source order documents the
 # dependency without affecting availability. Behaviour and signatures are
 # unchanged by the move.
@@ -47,23 +47,23 @@ _generation_metadata_json() {
     printf '{\n'
     printf '  "generator": {\n'
     printf '    "name": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["generator_name"]}")"
+        "$(json_string "${_GENERATION_METADATA["generator_name"]}")"
     printf '    "version": %s\n' \
-        "$(_json_string "${_GENERATION_METADATA["generator_version"]}")"
+        "$(json_string "${_GENERATION_METADATA["generator_version"]}")"
     printf '  },\n'
     printf '  "generated_at": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["generated_at"]}")"
+        "$(json_string "${_GENERATION_METADATA["generated_at"]}")"
     printf '  "config_source": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["config_source"]}")"
+        "$(json_string "${_GENERATION_METADATA["config_source"]}")"
     printf '  "template": {\n'
     printf '    "name": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["template_name"]}")"
+        "$(json_string "${_GENERATION_METADATA["template_name"]}")"
     printf '    "directory": %s\n' \
-        "$(_json_string "${_GENERATION_METADATA["template_directory"]}")"
+        "$(json_string "${_GENERATION_METADATA["template_directory"]}")"
     printf '  },\n'
     printf '  "source": {\n'
     printf '    "incoming_dir": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["source_incoming_dir"]}")"
+        "$(json_string "${_GENERATION_METADATA["source_incoming_dir"]}")"
     printf '    "image_count": %s\n' \
         "${_GENERATION_METADATA["source_image_count"]}"
     printf '  },\n'
@@ -77,35 +77,35 @@ _generation_metadata_json() {
     printf '  },\n'
     printf '  "tarball": {\n'
     printf '    "included": %s,\n' \
-        "$(_json_bool "${_GENERATION_METADATA["tarball_included"]}")"
+        "$(json_bool "${_GENERATION_METADATA["tarball_included"]}")"
     printf '    "file": %s\n' \
-        "$(_json_string "${_GENERATION_METADATA["tarball_file"]}")"
+        "$(json_string "${_GENERATION_METADATA["tarball_file"]}")"
     printf '  },\n'
     printf '  "settings": {\n'
     printf '    "title": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_title"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_title"]}")"
     printf '    "height": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_height"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_height"]}")"
     printf '    "thumbheight": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_thumbheight"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_thumbheight"]}")"
     printf '    "maxpreviews": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_maxpreviews"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_maxpreviews"]}")"
     printf '    "subdivide_percent": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_subdivide_percent"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_subdivide_percent"]}")"
     printf '    "feature_percent": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_feature_percent"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_feature_percent"]}")"
     printf '    "image_jobs": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_image_jobs"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_image_jobs"]}")"
     printf '    "random_seed": %s,\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_random_seed"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_random_seed"]}")"
     printf '    "shuffle": %s,\n' \
-        "$(_json_bool "${_GENERATION_METADATA["settings_shuffle"]}")"
+        "$(json_bool "${_GENERATION_METADATA["settings_shuffle"]}")"
     printf '    "splash_page": %s,\n' \
-        "$(_json_bool "${_GENERATION_METADATA["settings_splash_page"]}")"
+        "$(json_bool "${_GENERATION_METADATA["settings_splash_page"]}")"
     printf '    "stats_page": %s,\n' \
-        "$(_json_bool "${_GENERATION_METADATA["settings_stats_page"]}")"
+        "$(json_bool "${_GENERATION_METADATA["settings_stats_page"]}")"
     printf '    "original_basepath": %s\n' \
-        "$(_json_string "${_GENERATION_METADATA["settings_original_basepath"]}")"
+        "$(json_string "${_GENERATION_METADATA["settings_original_basepath"]}")"
     printf '  }\n'
     printf '}\n'
 }