sqzass

 //! minijinja 템플릿 환경과 렌더 컨텍스트.
 
 use anyhow::{Context, Result, bail};
 use minijinja::{AutoEscape, Environment, Output, State, UndefinedBehavior, Value};
 use serde::Serialize;
 use std::collections::HashMap;
 use std::path::Path;
 use std::sync::Arc;
 use walkdir::WalkDir;
 
 pub const TEMPLATE_DIR: &str = "templates";
 const TEMPLATE_EXTENSIONS: &[&str] = &["html", "xml", "txt", "json", "jinja", "j2"];
 
 pub struct Templates {
     env: Environment<'static>,
     names: Vec<String>,
 }
 
 impl Templates {
     /// `templates/` 전체를 **메모리로 한 번에 읽어** 그 스냅샷에서만 템플릿을 해석한다.
     ///
     /// 이게 중요한 이유: minijinja의 로더는 `{% include %}` / `{% extends %}`를
     /// VM 레벨에서 가로챈다. 로더가 디스크를 직접 읽게 두면, 파일을 저장하는 도중에
     /// 리빌드가 걸렸을 때 **반쯤 쓰인 파셜**을 읽어들일 수 있다. 스냅샷에서 해석하면
     /// 한 번의 빌드가 항상 하나의 일관된 템플릿 상태를 본다.
     pub fn load(root: &Path) -> Result<Self> {
         let dir = root.join(TEMPLATE_DIR);
         if !dir.is_dir() {
             bail!("{} 디렉터리가 없습니다", dir.display());
         }
 
         let mut snapshot: HashMap<String, String> = HashMap::new();
         for entry in WalkDir::new(&dir).sort_by_file_name() {
             let entry = entry.context("templates/ 순회 실패")?;
             if !entry.file_type().is_file() {
                 continue;
             }
             let path = entry.path();
             let is_template = path
                 .extension()
                 .and_then(|e| e.to_str())
                 .is_some_and(|e| TEMPLATE_EXTENSIONS.contains(&e));
             if !is_template {
                 continue;
             }
 
             // 템플릿 이름은 확장자를 포함한 상대 경로다: `base.html`, `partials/nav.html`.
             // Jinja 관례를 그대로 따르므로 `{% extends "base.html" %}`가 자연스럽다.
             let name = path
                 .strip_prefix(&dir)
                 .unwrap_or(path)
                 .to_string_lossy()
                 .replace('\\', "/");
             let source = std::fs::read_to_string(path)
                 .with_context(|| format!("{}을(를) 읽을 수 없습니다", path.display()))?;
             snapshot.insert(name, source);
         }
 
         if snapshot.is_empty() {
             bail!("{}에 템플릿이 없습니다", dir.display());
         }
 
         let mut names: Vec<String> = snapshot.keys().cloned().collect();
         names.sort();
 
         let snapshot = Arc::new(snapshot);
         let mut env = Environment::new();
 
         {
             let snapshot = Arc::clone(&snapshot);
             env.set_loader(move |name| Ok(snapshot.get(name).cloned()));
         }
 
         // autoescape는 minijinja의 확장자 기반 기본 동작을 그대로 쓴다.
         // html/htm/xml → Html, json → Json, txt → None.
         //
         // "확장자가 없으면 AutoEscape::None이 되어 조용히 이스케이프가 꺼진다"는
         // 함정이 있지만, 우리 로더가 TEMPLATE_EXTENSIONS에 있는 파일만 받으므로
         // 확장자 없는 템플릿은 애초에 존재할 수 없다. 이름 없는 참조는 스냅샷에서
         // 못 찾아 명확한 에러가 된다 — 조용한 실패가 아니다.
         //
         // 여기서 None을 Html로 끌어올리면 안 된다. 우리 목록에서 None이 되는 건
         // `.txt`뿐인데, robots.txt / llms.txt를 HTML 이스케이프하면 `&`가 `&amp;`가
         // 되어 파일이 망가진다.
         env.set_auto_escape_callback(minijinja::default_auto_escape_callback);
 
         // Strict가 아니라 SemiStrict. Strict는 `{% if optional_field %}`까지 에러로
         // 만드는데, front matter의 선택적 필드를 존재 검사하는 게 SSG 템플릿의
         // 일상이라 쓸 수 없다. SemiStrict는 undefined의 출력/순회/속성 접근만 막는다.
         env.set_undefined_behavior(UndefinedBehavior::SemiStrict);
         env.set_formatter(format_value);
 
         Ok(Self { env, names })
     }
 
     /// 템플릿에서 `{{ asset("css/main.css") }}`로 해시가 붙은 실제 URL을 얻게 한다.
     ///
     /// 없는 에셋은 **에러**다. 조용히 원래 경로를 돌려주면 오타가 404 링크로 배포되고,
     /// minijinja 에러가 템플릿 이름과 줄 번호를 달고 나오므로 찾기도 쉽다.
     pub fn with_assets(mut self, manifest: std::collections::BTreeMap<String, String>) -> Self {
         self.env.add_function("asset", move |path: String| {
             manifest
                 .get(path.trim_start_matches('/'))
                 .cloned()
                 .ok_or_else(|| {
                     let mut known: Vec<&str> = manifest.keys().map(|s| s.as_str()).collect();
                     known.sort_unstable();
                     minijinja::Error::new(
                         minijinja::ErrorKind::InvalidOperation,
                         format!(
                             "에셋 '{path}'이(가) 없습니다. 사용 가능: {}",
                             known.join(", ")
                         ),
                     )
                 })
         });
         self
     }
 
     /// 템플릿에서 `{{ t("skip_to_content") }}`로 UI 문자열을 얻게 한다.
     ///
     /// 언어는 인자로 받지 않고 렌더 중인 컨텍스트의 `page.language`에서 읽는다.
     /// 호출하는 쪽이 매번 언어를 넘겨야 하면 언젠가 한 군데를 빠뜨리고, 그 페이지만
     /// 다른 언어로 나간다.
     pub fn with_i18n(mut self, catalog: crate::i18n::Catalog) -> Self {
         self.env.add_function("t", move |state: &State, key: &str| {
             let language = state
                 .lookup("page")
                 .and_then(|p| p.get_attr("language").ok())
                 .map(|v| v.to_string())
                 .unwrap_or_default();
 
             crate::i18n::lookup(&catalog, &language, key)
                 .map_err(|msg| minijinja::Error::new(minijinja::ErrorKind::InvalidOperation, msg))
         });
         self
     }
 
     pub fn has(&self, name: &str) -> bool {
         self.names.iter().any(|n| n == name)
     }
 
     pub fn names(&self) -> &[String] {
         &self.names
     }
 
     pub fn render(&self, name: &str, ctx: Value) -> Result<String> {
         let tmpl = self
             .env
             .get_template(name)
             .with_context(|| format!("템플릿 '{name}'을(를) 찾을 수 없습니다"))?;
         tmpl.render(ctx)
             .with_context(|| format!("템플릿 '{name}' 렌더 실패"))
     }
 }
 
 /// HTML 이스케이프. minijinja 기본 이스케이퍼와 딱 한 곳이 다르다: **`/`를 건드리지
 /// 않는다.**
 ///
 /// minijinja는 `/`를 `&#x2f;`로 바꾼다(`utils.rs`의 `b'/' => "&#x2f;"`). OWASP식
 /// belt-and-braces 조치인데, 노리는 건 `</script>` 탈출이고 그건 `<`를 이스케이프하는
 /// 것으로 이미 막힌다. 대가는 사이트의 **모든 URL**이 `href="https:&#x2f;&#x2f;…"`로
 /// 나가는 것이다. 유효한 HTML이고 브라우저는 디코드하지만 출력물을 읽을 수 없게 만든다.
 ///
 /// 참고로 **Jinja2 본가의 `escape()`도 `/`를 이스케이프하지 않는다.** 이 포매터는
 /// minijinja를 원본 Jinja2 의미론 쪽으로 되돌리는 것이다.
 ///
 /// (`v_htmlescape` 피처도 시도했으나 그쪽 역시 `/`를 이스케이프해서 우회가 안 됐다.)
 fn write_html_escaped(out: &mut Output, s: &str) -> Result<(), minijinja::Error> {
     let mut last = 0;
     for (i, ch) in s.char_indices() {
         let repl = match ch {
             '&' => "&amp;",
             '<' => "&lt;",
             '>' => "&gt;",
             '"' => "&quot;",
             '\'' => "&#x27;",
             _ => continue,
         };
         out.write_str(&s[last..i])?;
         out.write_str(repl)?;
         last = i + ch.len_utf8();
     }
     out.write_str(&s[last..])?;
     Ok(())
 }
 
 fn format_value(out: &mut Output, state: &State, value: &Value) -> Result<(), minijinja::Error> {
     // 이미 safe로 표시된 값과 HTML이 아닌 이스케이프 모드(.txt, .json)는
     // 기본 동작에 맡긴다. 문자열이 아닌 값도 마찬가지 — 이스케이프할 게 없다.
     if state.auto_escape() == AutoEscape::Html
         && !value.is_safe()
         && let Some(s) = value.as_str()
     {
         return write_html_escaped(out, s);
     }
     minijinja::escape_formatter(out, state, value)
 }
 
 #[derive(Debug, Clone, Serialize)]
 pub struct SiteCtx {
     pub title: String,
     pub description: String,
     /// 스킴과 호스트만. 절대 URL은 `site.origin ~ page.url`로 만든다 — 페이지 URL이
     /// 이미 서브경로를 품고 있어서, 설정한 `base_url`을 그대로 붙이면 두 번 들어간다.
     pub origin: String,
     /// 사이트가 도메인 루트가 아닐 때의 경로 접두사. 루트면 빈 문자열.
     /// 템플릿이 직접 쓰는 URL(홈 링크 등)에만 필요하다.
     pub base_path: String,
     /// 지금 렌더 중인 페이지의 언어.
     pub language: String,
     /// 이 언어의 최상위 섹션들, 언어당 한 번만 직렬화해 둔 minijinja 값.
     /// 사이드바는 여기서 만든다.
     ///
     /// `Vec<SectionCtx>`가 아닌 이유: 값 그대로 두면 minijinja가 **페이지마다**
     /// 전 섹션·전 페이지 트리를 다시 직렬화한다 — 페이지당 O(n), 빌드 전체 O(n²).
     /// minijinja는 `Value`를 직렬화 경계 너머로 그대로 통과시키므로, 미리 만든
     /// 값을 참조 카운트 복사로 나눠 주면 그 비용이 사라진다.
     pub sections: minijinja::Value,
     /// 이 언어의 Atom 피드 URL. 날짜 있는 페이지가 하나도 없으면 `None`이고,
     /// 그때 템플릿은 자동 발견 링크를 넣지 않으면 된다.
     pub feed: Option<String>,
     /// 이 언어의 검색 색인 URL. `[search] enabled = false`면 `None`이고,
     /// 그때 템플릿은 검색 UI를 넣지 않으면 된다 — `feed`와 같은 규칙이다.
     /// URL 조립을 템플릿에 맡기지 않는 이유이기도 하다: 색인 파일명은 엔진
     /// 지식이라, 템플릿이 손으로 만들면 끈 사이트에서 죽은 URL이 된다.
     pub search: Option<String>,
     /// 생성된 하이라이트 스타일시트 URL. 강조가 꺼져 있으면 `None`.
     pub highlight_css: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize)]
 pub struct PageCtx {
     pub title: String,
     pub description: String,
     pub url: String,
     pub permalink: String,
     /// 렌더된 HTML. autoescape가 켜져 있으므로 템플릿에서 `| safe`가 필요하다.
     pub content: String,
     pub weight: i64,
     pub draft: bool,
     /// front matter의 `toc` — 목차를 렌더할지에 대한 저자의 의사.
     pub toc: bool,
     /// 실제 목차 데이터. `toc = false`여도 채워진다(템플릿이 판단하게 둔다).
     pub toc_entries: Vec<crate::markdown::TocEntry>,
     pub language: String,
     /// 다른 언어판. **번역이 실제로 있을 때만** 채워진다.
     pub translations: Vec<crate::site::LanguageLink>,
     /// 섹션 페이지의 직속 자식. 일반 페이지에서는 비어 있다.
     pub children: Vec<crate::site::PageRefCtx>,
     /// 이 페이지가 속한 섹션. 최상위 페이지에는 없다 — 브레드크럼이 쓴다.
     pub section: Option<crate::site::PageRefCtx>,
     /// 같은 섹션의 이전/다음 페이지. 섹션이 정한 순서를 따른다.
     pub prev: Option<crate::site::PageRefCtx>,
     pub next: Option<crate::site::PageRefCtx>,
     /// 섹션 인덱스인지. 템플릿이 목록을 그릴지 판단한다.
     pub is_section: bool,
     /// front matter의 `[extra]`. sqzass는 여기를 읽지 않는다 — 템플릿이 읽는다.
     pub extra: toml::Table,
     /// 발행 날짜. 없으면 없다. 서식 필터 대신 조각을 준다 —
     /// `{{ page.date.year }}년 {{ page.date.month }}월` 처럼 템플릿이 조립한다.
     pub date: Option<crate::feed::PageDate>,
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
     use minijinja::context;
 
     /// 테스트가 병렬로 돌아도 겹치지 않도록 이름으로 구분한 임시 사이트 루트를 만든다.
     /// 반환값을 드롭할 때 디렉터리를 지운다.
     struct Site(std::path::PathBuf);
 
     impl Site {
         fn new(name: &str, files: &[(&str, &str)]) -> Self {
             let root =
                 std::env::temp_dir().join(format!("sqzass-test-{}-{name}", std::process::id()));
             let tdir = root.join(TEMPLATE_DIR);
             std::fs::create_dir_all(&tdir).unwrap();
             for (file, body) in files {
                 let path = tdir.join(file);
                 std::fs::create_dir_all(path.parent().unwrap()).unwrap();
                 std::fs::write(path, body).unwrap();
             }
             Self(root)
         }
 
         fn templates(&self) -> Templates {
             Templates::load(&self.0).unwrap()
         }
     }
 
     impl Drop for Site {
         fn drop(&mut self) {
             std::fs::remove_dir_all(&self.0).ok();
         }
     }
 
     #[test]
     fn resolves_extends_through_the_snapshot() {
         let site = Site::new(
             "extends",
             &[
                 ("base.html", "<main>{% block body %}{% endblock %}</main>"),
                 (
                     "page.html",
                     "{% extends \"base.html\" %}{% block body %}{{ page.title }}{% endblock %}",
                 ),
             ],
         );
         let out = site
             .templates()
             .render("page.html", context! { page => context!{ title => "Hi" } })
             .unwrap();
         assert_eq!(out, "<main>Hi</main>");
     }
 
     #[test]
     fn resolves_include_from_a_subdirectory() {
         let site = Site::new(
             "include",
             &[
                 ("partials/nav.html", "<nav>{{ site.title }}</nav>"),
                 ("page.html", "{% include \"partials/nav.html\" %}"),
             ],
         );
         let out = site
             .templates()
             .render(
                 "page.html",
                 context! { site => context!{ title => "sqzass" } },
             )
             .unwrap();
         assert_eq!(out, "<nav>sqzass</nav>");
     }
 
     #[test]
     fn autoescapes_html_by_default() {
         let site = Site::new("escape", &[("page.html", "{{ page.title }}")]);
         let out = site
             .templates()
             .render(
                 "page.html",
                 context! { page => context!{ title => "<script>" } },
             )
             .unwrap();
         assert!(!out.contains("<script>"), "이스케이프되지 않았다: {out}");
     }
 
     #[test]
     fn urls_keep_their_slashes() {
         // minijinja 기본 이스케이퍼는 `/`를 `&#x2f;`로 바꿔서 사이트의 모든 링크를
         // 읽을 수 없게 만든다. 커스텀 포매터로 되돌린 것을 고정한다.
         let site = Site::new(
             "slash",
             &[("page.html", r#"<a href="{{ page.url }}">x</a>"#)],
         );
         let out = site
             .templates()
             .render(
                 "page.html",
                 context! { page => context!{ url => "https://sqzass.sqzer.com/ko/start/" } },
             )
             .unwrap();
         assert_eq!(out, r#"<a href="https://sqzass.sqzer.com/ko/start/">x</a>"#);
     }
 
     #[test]
     fn dangerous_characters_are_still_escaped() {
         // `/`만 빼고 나머지는 그대로 이스케이프되어야 한다. 이게 깨지면 XSS다.
         let site = Site::new("danger", &[("page.html", "{{ page.t }}")]);
         let t = site.templates();
         for (input, expected) in [
             ("<script>", "&lt;script&gt;"),
             ("a & b", "a &amp; b"),
             ("say \"hi\"", "say &quot;hi&quot;"),
             ("it's", "it&#x27;s"),
             (
                 "</script><img onerror=x>",
                 "&lt;/script&gt;&lt;img onerror=x&gt;",
             ),
         ] {
             let out = t
                 .render("page.html", context! { page => context!{ t => input } })
                 .unwrap();
             assert_eq!(out, expected, "입력: {input}");
         }
     }
 
     #[test]
     fn safe_values_bypass_the_custom_formatter() {
         let site = Site::new("safebypass", &[("page.html", "{{ page.c | safe }}")]);
         let out = site
             .templates()
             .render(
                 "page.html",
                 context! { page => context!{ c => "<p>a &amp; b</p>" } },
             )
             .unwrap();
         assert_eq!(out, "<p>a &amp; b</p>");
     }
 
     #[test]
     fn plain_text_templates_are_not_html_escaped() {
         // robots.txt / llms.txt 같은 평문 출력은 이스케이프하면 안 된다.
         // `&`가 `&amp;`가 되면 파일이 망가진다.
         let site = Site::new("txt", &[("robots.txt", "{{ page.title }}")]);
         let out = site
             .templates()
             .render(
                 "robots.txt",
                 context! { page => context!{ title => "a & b" } },
             )
             .unwrap();
         assert_eq!(out, "a & b");
     }
 
     #[test]
     fn extensionless_templates_are_never_loaded() {
         // autoescape가 확장자 기반이라 확장자 없는 템플릿은 이스케이프가 꺼진다.
         // 로더가 애초에 안 받으므로 그 상황이 생길 수 없다는 걸 고정해둔다.
         let site = Site::new(
             "noext",
             &[("page.html", "ok"), ("bare", "{{ page.title }}")],
         );
         let t = site.templates();
         assert!(t.has("page.html"));
         assert!(!t.has("bare"), "확장자 없는 파일이 템플릿으로 로드됐다");
     }
 
     #[test]
     fn safe_filter_lets_rendered_html_through() {
         let site = Site::new("safe", &[("page.html", "{{ page.content | safe }}")]);
         let out = site
             .templates()
             .render(
                 "page.html",
                 context! { page => context!{ content => "<p>hi</p>" } },
             )
             .unwrap();
         assert_eq!(out, "<p>hi</p>");
     }
 
     #[test]
     fn undefined_attribute_access_is_an_error() {
         let site = Site::new("undef", &[("page.html", "{{ page.nope.deeper }}")]);
         let err = site
             .templates()
             .render("page.html", context! { page => context!{} });
         assert!(err.is_err(), "undefined 접근이 통과했다");
     }
 
     #[test]
     fn optional_field_existence_check_still_works() {
         // SemiStrict를 고른 이유. Strict였다면 이게 에러가 된다.
         let site = Site::new(
             "optional",
             &[(
                 "page.html",
                 "{% if page.missing %}yes{% else %}no{% endif %}",
             )],
         );
         let out = site
             .templates()
             .render("page.html", context! { page => context!{} })
             .unwrap();
         assert_eq!(out, "no");
     }
 }