mirador 0.15.0

//! Resolving `theme = "name"` into a [`Theme`].
//!
//! The `[theme]` table has always let you set every colour. What it could not
//! do is let you *keep* more than one set of them, or hand one to somebody
//! else. A theme is a file now: ten ship inside the binary, and anything in
//! `<config>/mirador/themes/<name>.toml` is found first, so a bundled theme can
//! be replaced without editing it in place.
//!
//! Six of the ten are ports of palettes from elsewhere — Nord, Gruvbox,
//! Dracula, Catppuccin Mocha, Tokyo Night, Solarized Dark. Each file cites the
//! upstream source its hex values came from, and each is a port rather than an
//! interpretation: someone who picks `nord` wants Nord, not mirador's opinion
//! of it. Adjust the *mapping* of a palette onto mirador's keys if it reads
//! badly; do not adjust the palette.
//!
//! Two things make a theme file short. `inherits` names another theme to start
//! from, so a variant is the handful of lines that differ rather than a copy of
//! all eighteen keys. And `[palette]` names colours once — `brass = "#d7af87"` —
//! after which any key can say `brass`, which is the difference between a theme
//! you can adjust and a theme you have to search and replace.
//!
//! Deliberately *not* built, and worth saying why rather than leaving the next
//! reader to wonder:
//!
//! - **Dotted-scope fallback** (`ui.border.focused` → `ui.border` → `ui`).
//!   Helix needs it because it has hundreds of syntax scopes and no chance of
//!   a theme naming them all. mirador has thirteen flat semantic keys, every
//!   one of which a theme can reasonably set, and `inherits` already covers the
//!   ones it does not. The machinery would be larger than the problem.
//! - **Full style objects** (`fg`/`bg`/modifiers per key). Every one of the
//!   ~240 places that reads a theme reads a flat `Color`, and nothing in the
//!   dashboard wants a themed background: panels draw on the terminal's own,
//!   which is what invariant 8 is about. Bold and reversed are decided by the
//!   widget that knows what it is emphasising, not by the palette.
//!
//! Both are additions rather than corrections if they are ever wanted.

use std::collections::{BTreeMap, HashSet};
use std::path::{Path, PathBuf};

use anyhow::{Context, Result, bail};

use crate::theme::Theme;

/// Themes compiled into the binary, so a fresh install has something to name.
///
/// `include_str!`-baked, with the same trap as `assets/default_config.toml`:
/// editing one does nothing until you rebuild.
const BUNDLED: &[(&str, &str)] = &[
    ("default", include_str!("../assets/themes/default.toml")),
    (
        "default-light",
        include_str!("../assets/themes/default-light.toml"),
    ),
    (
        "high-contrast",
        include_str!("../assets/themes/high-contrast.toml"),
    ),
    ("ansi", include_str!("../assets/themes/ansi.toml")),
    // The community palettes. These are ports, not originals — each file cites
    // the upstream source it took its hex values from, and none of them should
    // be "improved" away from it. Someone picking `nord` wants Nord.
    ("nord", include_str!("../assets/themes/nord.toml")),
    ("gruvbox", include_str!("../assets/themes/gruvbox.toml")),
    ("dracula", include_str!("../assets/themes/dracula.toml")),
    (
        "catppuccin-mocha",
        include_str!("../assets/themes/catppuccin-mocha.toml"),
    ),
    (
        "tokyo-night",
        include_str!("../assets/themes/tokyo-night.toml"),
    ),
    (
        "solarized-dark",
        include_str!("../assets/themes/solarized-dark.toml"),
    ),
];

/// How deep an `inherits` chain may go before it is treated as a mistake.
///
/// Cycles are caught by name, so this only bounds the honest-but-silly case.
const MAX_DEPTH: usize = 16;

/// The names that ship, for error messages.
pub fn bundled_names() -> Vec<&'static str> {
    BUNDLED.iter().map(|(name, _)| *name).collect()
}

/// Where a user's own themes live.
pub fn user_dir(config_path: &Path) -> Option<PathBuf> {
    config_path.parent().map(|dir| dir.join("themes"))
}

/// Resolve `name` into a theme, following `inherits` and applying `[palette]`.
///
/// `themes_dir` is searched before the bundled set, so a theme called `default`
/// on disk wins — replacing a shipped theme should not require a different name
/// for it.
pub fn resolve(name: &str, themes_dir: Option<&Path>) -> Result<Theme> {
    // Root first, so that each document in turn overwrites what it inherited.
    let mut chain: Vec<toml::Table> = Vec::new();
    let mut seen: HashSet<String> = HashSet::new();
    let mut next = Some(name.to_string());

    while let Some(current) = next.take() {
        if !seen.insert(current.clone()) {
            bail!(
                "theme `{current}` inherits from itself, directly or through \
                 another theme. Break the loop by removing one `inherits`."
            );
        }
        if chain.len() >= MAX_DEPTH {
            bail!("theme `{name}` inherits through more than {MAX_DEPTH} files");
        }

        let mut table = read(&current, themes_dir)?;
        check_palette_ordering(&current, &table)?;
        if let Some(parent) = table.remove("inherits") {
            let toml::Value::String(parent) = parent else {
                bail!("`inherits` in theme `{current}` must be a theme name in quotes");
            };
            next = Some(parent);
        }
        chain.push(table);
    }
    chain.reverse();

    // Merge, child over parent, keeping palettes separate until the end: a
    // child that redefines `brass` must recolour the keys its *parent* set with
    // it, which merging them together as we go would not do.
    let mut palette: BTreeMap<String, toml::Value> = BTreeMap::new();
    let mut merged = toml::Table::new();
    for mut table in chain {
        if let Some(toml::Value::Table(entries)) = table.remove("palette") {
            palette.extend(entries);
        }
        merged.extend(table);
    }

    substitute(&mut merged, &palette);

    Theme::deserialize_table(merged)
        .with_context(|| format!("in theme `{name}`"))
        .map(|theme| theme.named(name))
}

/// Whether a theme name is a name rather than a path.
///
/// `theme = "../../elsewhere"` used to resolve, reading and parsing a file
/// outside the themes directory. Nothing is escalated by it — the config is the
/// user's own, and so is anything it could reach — but a theme name is not a
/// path and letting it act like one means error messages quoting arbitrary
/// files, and a name whose meaning depends on where the config happens to live.
///
/// Letters, digits, dash and underscore. That admits every bundled name and
/// every convention a theme is likely to use; it excludes separators, `..`, and
/// the empty string.
fn is_plain_name(name: &str) -> bool {
    !name.is_empty()
        && name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
}

/// Whether a file in the themes directory can be offered in the picker.
///
/// The same rule [`read`] enforces, exposed so the picker can leave a file out
/// rather than list it and fail on selection. A name mirador cannot look up is
/// not a theme the user has; it is a file they will have to rename.
pub fn is_listable(name: &str) -> bool {
    is_plain_name(name)
}

/// Read one theme document, preferring the user's copy.
fn read(name: &str, themes_dir: Option<&Path>) -> Result<toml::Table> {
    if !is_plain_name(name) {
        bail!(
            "`{name}` is not a theme name. Use letters, digits, dashes and \
             underscores — a theme is looked up by name in your themes \
             directory, not by path."
        );
    }

    if let Some(path) = themes_dir.map(|dir| dir.join(format!("{name}.toml")))
        && path.exists()
    {
        let raw = std::fs::read_to_string(&path)
            .with_context(|| format!("reading theme {}", path.display()))?;
        return toml::from_str(&raw).with_context(|| format!("parsing theme {}", path.display()));
    }

    if let Some((_, raw)) = BUNDLED.iter().find(|(bundled, _)| *bundled == name) {
        return toml::from_str(raw).with_context(|| format!("parsing the bundled `{name}` theme"));
    }

    let mut known = bundled_names();
    known.sort_unstable();
    let where_to_put_it = themes_dir.map_or_else(
        || "your themes directory".to_string(),
        |dir| dir.display().to_string(),
    );
    bail!(
        "no theme called `{name}`. Built in: {}. For anything else, put \
         `{name}.toml` in {where_to_put_it}.",
        known.join(", ")
    )
}

/// Catch colour keys that have fallen inside `[palette]`.
///
/// In TOML every key after a table header belongs to that table, so a file
/// written in the obvious order —
///
/// ```text
/// [palette]
/// brass = "#d7af87"
///
/// accent = "brass"
/// ```
///
/// puts `accent` *in the palette*, where it sets nothing. Nothing is
/// misspelled and nothing fails to parse; the theme simply comes out as the
/// defaults, which is the silent-ignore failure this crate refuses to ship.
///
/// I wrote the shipped `default.toml` this way and did not notice, because the
/// test comparing it against `Theme::default()` passed: with no keys set, the
/// result *was* the default. Hence both this check and a drift test that can
/// actually fail.
fn check_palette_ordering(name: &str, table: &toml::Table) -> Result<()> {
    let Some(toml::Value::Table(palette)) = table.get("palette") else {
        return Ok(());
    };
    let mut stray: Vec<&str> = palette
        .keys()
        .map(String::as_str)
        .filter(|key| Theme::KEYS.contains(key))
        .collect();
    if stray.is_empty() {
        return Ok(());
    }
    stray.sort_unstable();
    bail!(
        "theme `{name}` has {} inside `[palette]`, where {} nothing. In TOML \
         every key after a table header belongs to that table, so the colour \
         keys have to come *before* `[palette]`, not after it.",
        stray.join(", "),
        if stray.len() == 1 {
            "it sets"
        } else {
            "they set"
        }
    )
}

/// Replace palette names with the colours they stand for.
///
/// Only strings that are palette *keys* change; everything else is left for the
/// colour parser to accept or reject, so a typo still produces "`brss` is not a
/// colour" rather than being silently dropped.
/// Recursion here is bounded by the TOML parser rather than by anything below:
/// a document nested deeply enough to matter is refused before it becomes a
/// `Table`. Checked with fifty thousand nested inline tables, which `toml`
/// rejects outright. Worth knowing, because the bound lives in a dependency and
/// would leave with it.
fn substitute(table: &mut toml::Table, palette: &BTreeMap<String, toml::Value>) {
    for (_, value) in table.iter_mut() {
        // Taken by value and put back, because a palette hit replaces the whole
        // entry rather than editing the string in place.
        let replacement = match value {
            toml::Value::String(text) => palette.get(text.as_str()).cloned(),
            // One level down is enough: gradients are the only nested tables a
            // theme has, and their stops are plain strings.
            toml::Value::Table(nested) => {
                substitute(nested, palette);
                None
            }
            _ => None,
        };
        if let Some(resolved) = replacement {
            *value = resolved;
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct TempDir(PathBuf);

    impl Drop for TempDir {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.0);
        }
    }

    fn themes_dir(name: &str) -> (PathBuf, TempDir) {
        let dir =
            std::env::temp_dir().join(format!("mirador-themes-{}-{name}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("test directory");
        (dir.clone(), TempDir(dir))
    }

    fn write(dir: &Path, name: &str, body: &str) {
        std::fs::write(dir.join(format!("{name}.toml")), body).expect("writing a theme");
    }

    /// A theme name is a name, not a path. `theme = "../../elsewhere"` used to
    /// resolve — reading and parsing a file outside the themes directory.
    /// Nothing escalates, since the config and anything it reaches are the
    /// user's own, but a name whose meaning depends on where the config sits is
    /// not a name, and the error messages quote whatever it reached.
    #[test]
    fn a_theme_name_cannot_reach_outside_the_themes_directory() {
        let (dir, _g) = themes_dir("traversal");
        let outside = dir.parent().expect("has a parent").join("outside.toml");
        std::fs::write(&outside, "accent = \"#010203\"\n").expect("write");

        for name in ["../outside", "/etc/passwd", "sub/theme", "..", ""] {
            let err = resolve(name, Some(&dir))
                .err()
                .unwrap_or_else(|| panic!("`{name}` was accepted as a theme name"));
            let message = format!("{err:#}");
            assert!(
                message.contains("not a theme name") || message.contains("no theme called"),
                "`{name}` refused for the wrong reason: {message}"
            );
        }

        // And an ordinary name still works.
        write(&dir, "nord", "accent = \"#88c0d0\"\n");
        assert!(resolve("nord", Some(&dir)).is_ok());
        let _ = std::fs::remove_file(&outside);
    }

    /// The palette substitution recurses through nested tables, and the bound
    /// on that recursion lives in the TOML parser rather than here — a document
    /// nested deeply enough to overflow a stack never becomes a `Table` at all.
    /// Pinned because the bound would leave with the dependency.
    #[test]
    fn a_deeply_nested_theme_is_refused_before_it_can_be_walked() {
        let (dir, _g) = themes_dir("deep");
        let depth = 50_000;
        let mut deep = String::from("accent = \"#010203\"\n\nnest = ");
        deep.push_str(&"{ a = ".repeat(depth));
        deep.push('1');
        deep.push_str(&" }".repeat(depth));
        deep.push('\n');
        write(&dir, "deep", &deep);

        assert!(
            resolve("deep", Some(&dir)).is_err(),
            "{depth} levels of nesting were walked rather than refused"
        );
    }

    #[test]
    fn every_bundled_theme_resolves() {
        for name in bundled_names() {
            resolve(name, None).unwrap_or_else(|e| panic!("bundled `{name}` failed: {e:#}"));
        }
    }

    /// The Rust `Theme::default()` and the shipped `default.toml` are reached
    /// by different routes — a config with no `theme` key takes the first, and
    /// `theme = "default"` takes the second — so they have to be pinned
    /// together. The layout has the same hazard and the same kind of test; when
    /// those two drifted, a config without a `[layout]` section silently lost
    /// three panels.
    #[test]
    fn the_bundled_default_theme_matches_the_rust_default() {
        let from_file = resolve("default", None).expect("resolves");
        let built_in = Theme::default();
        assert_eq!(
            from_file.colours(),
            built_in.colours(),
            "assets/themes/default.toml has drifted from Theme::default()"
        );
    }

    /// The comparison above cannot fail on its own, and for a while it did not.
    /// Every colour key in `default.toml` had fallen inside `[palette]`, so the
    /// file set *nothing*, the resolved theme was therefore the default, and
    /// the equality passed while the file was meaningless. Comparing against
    /// the default cannot detect that — the file resolving to the default is
    /// the whole point — so the property has to be checked on the file: a
    /// standalone theme names every key it is responsible for.
    #[test]
    fn a_standalone_theme_sets_every_key_rather_than_leaning_on_defaults() {
        // `high-contrast` is excluded on purpose: it inherits `ansi` and is
        // meant to be the handful of lines that differ.
        for name in ["default", "default-light", "ansi"] {
            let (_, raw) = BUNDLED
                .iter()
                .find(|(bundled, _)| *bundled == name)
                .expect("bundled");
            let table: toml::Table = toml::from_str(raw).expect("parses");

            let missing: Vec<&str> = Theme::KEYS
                .iter()
                .copied()
                .filter(|key| !table.contains_key(*key))
                .collect();
            assert!(
                missing.is_empty(),
                "`{name}.toml` never sets: {}",
                missing.join(", ")
            );
        }
    }

    /// The trap that produced the bug above. It is silent by construction —
    /// nothing is misspelled and nothing fails to parse — so it has to be
    /// caught rather than left for the theme author to puzzle over.
    #[test]
    fn colour_keys_that_fell_inside_the_palette_are_reported() {
        let (dir, _g) = themes_dir("ordering");
        write(
            &dir,
            "t",
            "[palette]\nbrass = \"#d7af87\"\naccent = \"brass\"\nborder = \"brass\"\n",
        );

        let err = format!("{:#}", resolve("t", Some(&dir)).expect_err("must fail"));
        assert!(err.contains("accent"), "names the key: {err}");
        assert!(err.contains("border"), "and every key: {err}");
        assert!(err.contains("before"), "and says what to do: {err}");
    }

    /// A palette entry that merely *shares a name* with nothing in the theme is
    /// fine; the check must not fire on an ordinary palette.
    #[test]
    fn an_ordinary_palette_is_left_alone() {
        let (dir, _g) = themes_dir("ordinary");
        write(
            &dir,
            "t",
            "accent = \"brass\"\n\n[palette]\nbrass = \"#010203\"\n",
        );
        resolve("t", Some(&dir)).expect("a well-ordered theme resolves");
    }

    #[test]
    fn a_theme_on_disk_wins_over_the_bundled_one_of_the_same_name() {
        let (dir, _g) = themes_dir("override");
        write(&dir, "default", "accent = \"#010203\"\n");

        let theme = resolve("default", Some(&dir)).expect("resolves");
        assert_eq!(theme.accent, ratatui::style::Color::Rgb(1, 2, 3));
    }

    #[test]
    fn inherits_starts_from_the_parent_and_the_child_overrides_it() {
        let (dir, _g) = themes_dir("inherits");
        write(
            &dir,
            "child",
            "inherits = \"default\"\naccent = \"#010203\"\n",
        );

        let child = resolve("child", Some(&dir)).expect("resolves");
        let parent = Theme::default();
        assert_eq!(
            child.accent,
            ratatui::style::Color::Rgb(1, 2, 3),
            "overridden"
        );
        assert_eq!(child.border, parent.border, "and the rest is inherited");
    }

    /// Without this the loop runs until the depth cap and reports the wrong
    /// thing, which sends someone looking for a file that is fine.
    #[test]
    fn a_cycle_is_named_rather_than_run_until_it_gives_up() {
        let (dir, _g) = themes_dir("cycle");
        write(&dir, "a", "inherits = \"b\"\n");
        write(&dir, "b", "inherits = \"a\"\n");

        let err = format!("{:#}", resolve("a", Some(&dir)).expect_err("must fail"));
        assert!(err.contains("inherits from itself"), "got: {err}");
    }

    /// A child that redefines a palette entry has to recolour the keys its
    /// *parent* set with it. Merging each document's palette as it is read
    /// would leave the parent's keys holding the parent's colour.
    #[test]
    fn a_redefined_palette_colour_reaches_the_keys_the_parent_set_with_it() {
        let (dir, _g) = themes_dir("palette");
        // The parent sets `accent` from the palette; the child changes only
        // what `brass` means.
        write(
            &dir,
            "base",
            "accent = \"brass\"\n\n[palette]\nbrass = \"#d7af87\"\n",
        );
        write(
            &dir,
            "child",
            "inherits = \"base\"\n\n[palette]\nbrass = \"#010203\"\n",
        );

        let theme = resolve("child", Some(&dir)).expect("resolves");
        assert_eq!(
            theme.accent,
            ratatui::style::Color::Rgb(1, 2, 3),
            "the parent's `accent = brass` follows the child's redefinition"
        );
    }

    #[test]
    fn an_unknown_name_lists_what_is_available() {
        // Deliberately not the name of a real palette. This test used to ask
        // for `nord`, which stopped being unknown the day nord shipped.
        let err = format!(
            "{:#}",
            resolve("no-such-theme", None).expect_err("must fail")
        );
        assert!(
            err.contains("no theme called `no-such-theme`"),
            "got: {err}"
        );
        for name in bundled_names() {
            assert!(err.contains(name), "`{name}` missing from: {err}");
        }
    }

    /// A palette name that is not in the palette must still reach the colour
    /// parser, so the message names the offending word.
    #[test]
    fn a_misspelled_palette_name_is_reported_as_a_bad_colour() {
        let (dir, _g) = themes_dir("typo");
        write(
            &dir,
            "t",
            "accent = \"brss\"\n\n[palette]\nbrass = \"#d7af87\"\n",
        );

        let err = format!("{:#}", resolve("t", Some(&dir)).expect_err("must fail"));
        assert!(err.contains("brss"), "the message names the typo: {err}");
    }

    #[test]
    fn a_misspelled_key_in_a_theme_file_is_refused() {
        let (dir, _g) = themes_dir("badkey");
        write(&dir, "t", "acent = \"#010203\"\n");

        let err = format!("{:#}", resolve("t", Some(&dir)).expect_err("must fail"));
        assert!(err.contains("acent"), "the message names the key: {err}");
    }
}