day-build 0.7.5

Declarative app development API using native UI toolkits
Documentation
// Copyright © The Daybrite Project
// SPDX-License-Identifier: MPL-2.0

use super::*;
use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Write as _;

/// Generate private crate/file catalogs into `day_locales.rs`.
///
/// Call from each reusable crate's build script, then `day_localization_ui::locales!()` in its lib.rs.
/// `resource/locales/<locale>/app.ftl` exposes `res::str::<key>()`;
/// `settings.ftl` exposes `res::settings::str::<key>()`, importing app.ftl's messages and terms.
/// This is independent of the legacy app-global `generate_resources()` API.
/// A library always reads its own resources, never the application's flavor overlay.
///
/// # Errors
///
/// Returns an error when `CARGO_MANIFEST_DIR`, `CARGO_PKG_NAME` or `OUT_DIR` is unset, when
/// [`render_crate_locales`] rejects the catalogs, or when the generated file cannot be written.
pub fn generate_locales() -> Result<(), String> {
    let root = PathBuf::from(env("CARGO_MANIFEST_DIR")?);
    let dir = root.join("resource/locales");
    let name = env("CARGO_PKG_NAME")?.replace('-', "_");
    let code = render_crate_locales(&dir, &name)?;
    std::fs::write(PathBuf::from(env("OUT_DIR")?).join("day_locales.rs"), code)
        .map_err(|e| format!("day-build: writing day_locales.rs: {e}"))?;
    // Watching the parent catches creation of the first locale directory as well.
    watch_resources(&root.join("resource"), "resource");
    if !root.join("resource").is_dir() {
        println!("cargo:rerun-if-changed=.");
    }
    println!("cargo:rerun-if-changed=Cargo.toml");
    Ok(())
}

/// Pure code-generation entry point for crate catalogs. `name` is their diagnostic/script namespace.
///
/// # Errors
///
/// Returns an error when `name` or a catalog file name is not a usable Rust identifier, a catalog
/// is not at `<locale>/<scope>.ftl`, or a catalog fails to parse or validate.
///
/// # Panics
///
/// Panics if the directory walk yields a path outside `dir` or one without a file stem, which would
/// be a bug in this crate.
pub fn render_crate_locales(dir: &Path, name: &str) -> Result<String, String> {
    if !is_rust_ident(name) {
        return Err(format!("day-build: invalid catalog namespace {name:?}"));
    }
    let mut files: BTreeMap<String, BTreeMap<String, PathBuf>> = BTreeMap::new();
    for path in ftl_files(dir) {
        let relative = path.strip_prefix(dir).unwrap();
        if relative.components().count() != 2 {
            return Err(format!(
                "day-build: {}: expected <locale>/<scope>.ftl",
                path.display()
            ));
        }
        let scope = path.file_stem().unwrap().to_string_lossy().to_string();
        if !is_rust_ident(&scope)
            || matches!(
                scope.as_str(),
                "str" | "locales" | "self" | "Self" | "super" | "crate"
            )
        {
            return Err(format!(
                "day-build: invalid or reserved locale file name {scope:?}"
            ));
        }
        validate_source(&path)?;
        files
            .entry(scope)
            .or_default()
            .insert(locale_of(&path), path);
    }
    // Even an empty crate has an empty root catalog and stable generated API.
    files.entry("app".into()).or_default();
    let mut out = "// @generated by day-build — private crate localization catalogs.\n".to_string();
    let app = &files["app"];
    render_scope(&mut out, name, app, &BTreeMap::new())?;
    for (scope, sources) in &files {
        if scope == "app" {
            continue;
        }
        let _ = writeln!(out, "pub mod {} {{", ident_token(scope));
        render_scope(&mut out, &format!("{name}::{scope}"), sources, app)?;
        out.push_str("}\n");
    }
    Ok(out)
}

fn validate_source(path: &Path) -> Result<BTreeSet<String>, String> {
    let source = std::fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display()))?;
    let ast = fluent_syntax::parser::parse(source.as_str()).map_err(|(_, errors)| {
        format!("day-build: {}: invalid Fluent: {errors:?}", path.display())
    })?;
    let mut names = BTreeSet::new();
    for entry in ast.body {
        use fluent_syntax::ast::Entry;
        let key = match entry {
            Entry::Message(m) => m.id.name.to_string(),
            Entry::Term(t) => format!("-{}", t.id.name),
            _ => continue,
        };
        if !names.insert(key.clone()) {
            return Err(format!(
                "day-build: {}: duplicate Fluent entry {key:?}",
                path.display()
            ));
        }
    }
    Ok(names)
}

fn render_scope(
    out: &mut String,
    name: &str,
    own: &BTreeMap<String, PathBuf>,
    shared: &BTreeMap<String, PathBuf>,
) -> Result<(), String> {
    let paths: Vec<_> = own.values().chain(shared.values()).cloned().collect();
    let strings = plan_strings_from_files(&paths)?;
    let mut tags: BTreeSet<_> = own.keys().chain(shared.keys()).cloned().collect();
    if tags.is_empty() {
        tags.insert("en".into());
    }
    let locales: Vec<_> = tags
        .into_iter()
        .map(|locale| {
            let sources = shared
                .get(&locale)
                .into_iter()
                .chain(own.get(&locale))
                .cloned()
                .collect();
            LocaleEntry { locale, sources }
        })
        .collect();
    // app.ftl is an import, not an override. Reject collisions rather than silently dropping a
    // translation; sibling scopes can reuse keys freely. Terms are checked too.
    for locale in &locales {
        let mut names = BTreeSet::new();
        for path in &locale.sources {
            for key in validate_source(path)? {
                if !names.insert(key.clone()) {
                    return Err(format!(
                        "day-build: {name}/{}: duplicate imported key {key}",
                        locale.locale
                    ));
                }
            }
        }
    }
    render_locales_for(out, &locales, Some(name));
    render_strings_for(
        out,
        &strings,
        "day_localization_ui",
        "day_localization_ui::tr_in(&super::locales::SCOPE, ",
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    struct Fixture(PathBuf);
    impl Fixture {
        fn new() -> Self {
            static NEXT: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
            let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            let path = std::env::temp_dir().join(format!("day-scoped-{}-{id}", std::process::id()));
            std::fs::create_dir_all(&path).unwrap();
            Self(path)
        }
        fn write(&self, path: &str, source: &str) {
            let path = self.0.join(path);
            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
            std::fs::write(path, source).unwrap();
        }
        fn render(&self) -> Result<String, String> {
            render_crate_locales(&self.0, "my_crate")
        }
    }
    impl Drop for Fixture {
        fn drop(&mut self) {
            std::fs::remove_dir_all(&self.0).unwrap();
        }
    }

    #[test]
    fn app_imports_and_sibling_files_have_distinct_typed_namespaces() {
        let f = Fixture::new();
        f.write("en/app.ftl", "-brand = Day\nclose = Close\n");
        f.write(
            "en/board.ftl",
            "game_title = { -brand } Board\ncount = { NUMBER($n) } tiles\n",
        );
        f.write(
            "fr/board.ftl",
            "game_title = Plateau\ncount = { $n } cases\n",
        );
        f.write("en/menu.ftl", "game_title = Menu\n");
        let code = f.render().unwrap();
        assert!(code.contains("pub mod board {"));
        assert!(code.contains("pub mod menu {"));
        assert!(code.contains("name: \"my_crate::board\""));
        assert!(code.contains("name: \"my_crate::menu\""));
        assert_eq!(code.matches("pub fn close(").count(), 3);
        assert_eq!(code.matches("pub fn game_title(").count(), 2);
        assert!(code.contains("n: impl day_localization_ui::IntoNumberFArg<M0>"));
        assert!(
            code.contains("day_localization_ui::tr_in(&super::locales::SCOPE, \"game_title\")")
        );
        assert!(!code.contains("day::"));
        assert!(!code.contains("pub fn install"));
        assert_eq!(code, f.render().unwrap(), "output must be deterministic");
    }

    #[test]
    fn diagnoses_collisions_syntax_and_parameter_drift() {
        for (first, second, expected) in [
            ("same = Root\n", "same = File\n", "duplicate imported key"),
            ("-term = Root\n", "-term = File\n", "duplicate imported key"),
        ] {
            let f = Fixture::new();
            f.write("en/app.ftl", first);
            f.write("en/ui.ftl", second);
            assert!(f.render().unwrap_err().contains(expected));
        }
        let f = Fixture::new();
        f.write("en/app.ftl", "hello = Hello { $name }\n");
        f.write("fr/app.ftl", "hello = Bonjour { $other }\n");
        assert!(f.render().unwrap_err().contains("different parameters"));
        f.write("fr/app.ftl", "hello = {\n");
        assert!(f.render().unwrap_err().contains("invalid Fluent"));
        f.write("fr/app.ftl", "hello = A\nhello = B\n");
        assert!(f.render().unwrap_err().contains("duplicate Fluent entry"));
    }

    #[test]
    fn invalid_scope_names_and_ambiguous_attributes_fail() {
        for name in [
            "str", "locales", "self", "Self", "super", "crate", "bad-name",
        ] {
            let f = Fixture::new();
            f.write(&format!("en/{name}.ftl"), "hello = Hello\n");
            assert!(f.render().unwrap_err().contains("locale file name"));
        }
        let f = Fixture::new();
        f.write(
            "en/ui.ftl",
            "menu = Menu\n    .key = m\nmenu_key = Collision\n",
        );
        assert!(f.render().unwrap_err().contains("both generate"));
    }

    #[test]
    fn empty_crates_and_files_without_app_have_valid_catalogs() {
        let f = Fixture::new();
        assert!(f.render().unwrap().contains("(\"en\", \"\")"));
        f.write("fr/ui.ftl", "bonjour = Bonjour\n");
        let code = f.render().unwrap();
        assert!(code.contains("DEFAULT: &str = \"fr\""));
        assert!(code.contains("pub fn bonjour()"));
    }
}