es_fluent_cli/commands/

check.rs

//! Check command for validating FTL files against inventory-registered types.
//!
//! This module provides functionality to check FTL files by:
//! - Running a temp crate that collects inventory registrations (expected keys/variables)
//! - Parsing FTL files directly using fluent-syntax (for proper ParserError handling)
//! - Comparing FTL files against the expected keys and variables from Rust code
//! - Reporting missing keys as errors
//! - Reporting missing variables as warnings

use crate::commands::{WorkspaceArgs, WorkspaceCrates};
use crate::core::{
    CliError, CrateInfo, FtlSyntaxError, MissingKeyError, MissingVariableWarning, ValidationIssue,
    ValidationReport, find_key_span,
};
use crate::ftl::extract_variables_from_message;
use crate::generation::{prepare_monolithic_runner_crate, run_monolithic};
use crate::utils::{get_all_locales, ui};
use anyhow::{Context as _, Result};
use clap::Parser;
use es_fluent_toml::I18nConfig;
use fluent_syntax::ast;
use fluent_syntax::parser::{self, ParserError};
use miette::{NamedSource, SourceSpan};
use regex::Regex;
use serde::Deserialize;
use std::collections::{HashMap, HashSet};
use std::fs;
use std::path::Path;
use std::sync::LazyLock;

/// Expected key information from inventory (deserialized from temp crate output).
#[derive(Deserialize)]
struct ExpectedKey {
    key: String,
    variables: Vec<String>,
}

/// The inventory data output from the temp crate.
#[derive(Deserialize)]
struct InventoryData {
    expected_keys: Vec<ExpectedKey>,
}

/// Arguments for the check command.
#[derive(Debug, Parser)]
pub struct CheckArgs {
    #[command(flatten)]
    pub workspace: WorkspaceArgs,

    /// Check all locales, not just the fallback language.
    #[arg(long)]
    pub all: bool,

    /// Keys to ignore during validation. Can be specified multiple times
    /// (e.g., --ignore a --ignore b) or comma-separated (e.g., --ignore a,b).
    #[arg(long, value_delimiter = ',')]
    pub ignore: Vec<String>,
}

/// Run the check command.
pub fn run_check(args: CheckArgs) -> Result<(), CliError> {
    let workspace = WorkspaceCrates::discover(args.workspace)?;

    if !workspace.print_discovery(ui::print_check_header) {
        ui::print_no_crates_found();
        return Ok(());
    }

    // Convert ignore list to a HashSet for efficient lookups
    let ignore_keys: HashSet<String> = args.ignore.into_iter().collect();

    // Prepare monolithic temp crate once for all checks
    prepare_monolithic_runner_crate(&workspace.workspace_info)
        .map_err(|e| CliError::Other(e.to_string()))?;

    // First pass: collect all expected keys from all crates to validate ignore list
    let temp_dir = workspace.workspace_info.root_dir.join(".es-fluent");
    let mut all_known_keys: HashSet<String> = HashSet::new();

    let pb = ui::create_progress_bar(workspace.valid.len() as u64, "Collecting keys...");

    for krate in &workspace.valid {
        pb.set_message(format!("Scanning {}", krate.name));
        run_monolithic(&workspace.workspace_info, "check", &krate.name, &[])
            .map_err(|e| CliError::Other(e.to_string()))?;
        if let Ok(expected_keys) = read_inventory_file(&temp_dir, &krate.name) {
            all_known_keys.extend(expected_keys.into_keys());
        }
        pb.inc(1);
    }

    pb.finish_and_clear();

    // Validate that all ignore keys are known
    if !ignore_keys.is_empty() {
        let mut unknown_keys: Vec<&String> = ignore_keys
            .iter()
            .filter(|k| !all_known_keys.contains(*k))
            .collect();

        if !unknown_keys.is_empty() {
            // Sort for deterministic error messages
            unknown_keys.sort();

            return Err(CliError::Other(format!(
                "Unknown keys passed to --ignore: {}",
                unknown_keys
                    .iter()
                    .map(|k| format!("'{}'", k))
                    .collect::<Vec<_>>()
                    .join(", ")
            )));
        }
    }

    // Second pass: validate FTL files
    let mut all_issues: Vec<ValidationIssue> = Vec::new();

    let pb = ui::create_progress_bar(workspace.valid.len() as u64, "Checking crates...");

    for krate in &workspace.valid {
        pb.set_message(format!("Checking {}", krate.name));

        match validate_crate(krate, &temp_dir, args.all, &ignore_keys) {
            Ok(issues) => {
                all_issues.extend(issues);
            },
            Err(e) => {
                // If error, print above progress bar
                pb.suspend(|| {
                    ui::print_check_error(&krate.name, &e.to_string());
                });
            },
        }
        pb.inc(1);
    }

    pb.finish_and_clear();

    let error_count = all_issues
        .iter()
        .filter(|i| {
            matches!(
                i,
                ValidationIssue::MissingKey(_) | ValidationIssue::SyntaxError(_)
            )
        })
        .count();
    let warning_count = all_issues
        .iter()
        .filter(|i| matches!(i, ValidationIssue::MissingVariable(_)))
        .count();

    if all_issues.is_empty() {
        ui::print_check_success();
        Ok(())
    } else {
        Err(CliError::Validation(ValidationReport {
            error_count,
            warning_count,
            issues: all_issues,
        }))
    }
}

/// Validate a single crate's FTL files using already-collected inventory data.
fn validate_crate(
    krate: &CrateInfo,
    temp_dir: &Path,
    check_all: bool,
    ignore_keys: &HashSet<String>,
) -> Result<Vec<ValidationIssue>> {
    // Read the inventory that was already collected in the first pass
    let mut expected_keys = read_inventory_file(temp_dir, &krate.name)?;

    // Filter out ignored keys
    for key in ignore_keys {
        expected_keys.remove(key);
    }

    // Validate FTL files against expected keys
    validate_ftl_files(krate, &expected_keys, check_all)
}

/// Read inventory data from the generated inventory.json file.
fn read_inventory_file(
    temp_dir: &std::path::Path,
    crate_name: &str,
) -> Result<HashMap<String, HashSet<String>>> {
    let inventory_path = temp_dir
        .join("metadata")
        .join(crate_name)
        .join("inventory.json");
    let json_str = fs::read_to_string(&inventory_path)
        .with_context(|| format!("Failed to read {}", inventory_path.display()))?;

    let data: InventoryData =
        serde_json::from_str(&json_str).context("Failed to parse inventory JSON")?;

    // Convert to HashMap for easier lookup
    let mut expected_keys = HashMap::new();
    for key_info in data.expected_keys {
        expected_keys.insert(key_info.key, key_info.variables.into_iter().collect());
    }

    Ok(expected_keys)
}

/// Result of loading an FTL file for a locale.
enum LocaleLoadResult {
    /// File doesn't exist.
    NotFound,
    /// Failed to read the file.
    ReadError(String),
    /// Successfully loaded.
    Loaded {
        content: String,
        resource: ast::Resource<String>,
        parse_errors: Vec<ParserError>,
    },
}

/// Load an FTL file for a locale.
fn load_locale_ftl(assets_dir: &Path, locale: &str, crate_name: &str) -> LocaleLoadResult {
    let ftl_file = assets_dir.join(locale).join(format!("{}.ftl", crate_name));

    if !ftl_file.exists() {
        return LocaleLoadResult::NotFound;
    }

    let content = match fs::read_to_string(&ftl_file) {
        Ok(c) => c,
        Err(e) => return LocaleLoadResult::ReadError(e.to_string()),
    };

    let (resource, parse_errors) = match parser::parse(content.clone()) {
        Ok(res) => (res, vec![]),
        Err((res, errors)) => (res, errors),
    };

    LocaleLoadResult::Loaded {
        content,
        resource,
        parse_errors,
    }
}

/// Validate FTL files against expected keys using fluent-syntax directly.
fn validate_ftl_files(
    krate: &CrateInfo,
    expected_keys: &HashMap<String, HashSet<String>>,
    check_all: bool,
) -> Result<Vec<ValidationIssue>> {
    let config = I18nConfig::read_from_path(&krate.i18n_config_path)
        .with_context(|| format!("Failed to read {}", krate.i18n_config_path.display()))?;

    let assets_dir = krate.manifest_dir.join(&config.assets_dir);

    let locales: Vec<String> = if check_all {
        get_all_locales(&assets_dir)?
    } else {
        vec![config.fallback_language.clone()]
    };

    let mut issues = Vec::new();

    for locale in &locales {
        let file_name = format!("{}/{}.ftl", locale, krate.name);

        match load_locale_ftl(&assets_dir, locale, &krate.name) {
            LocaleLoadResult::NotFound => {
                issues.extend(missing_file_issues(expected_keys, locale, &krate.name));
                continue;
            },
            LocaleLoadResult::ReadError(err) => {
                issues.push(ValidationIssue::SyntaxError(FtlSyntaxError {
                    src: NamedSource::new(file_name.clone(), String::new()),
                    span: SourceSpan::new(0_usize.into(), 1_usize),
                    locale: locale.clone(),
                    file_name,
                    help: format!("Failed to read file: {}", err),
                }));
                continue;
            },
            LocaleLoadResult::Loaded {
                content,
                resource,
                parse_errors,
            } => {
                issues.extend(validate_loaded_ftl(
                    &content,
                    &resource,
                    &parse_errors,
                    expected_keys,
                    locale,
                    &file_name,
                    &krate.name,
                ));
            },
        }
    }

    Ok(issues)
}

/// Generate missing key issues when an FTL file doesn't exist.
fn missing_file_issues(
    expected_keys: &HashMap<String, HashSet<String>>,
    locale: &str,
    crate_name: &str,
) -> Vec<ValidationIssue> {
    expected_keys
        .keys()
        .map(|key| {
            ValidationIssue::MissingKey(MissingKeyError {
                src: NamedSource::new(format!("{}/{}.ftl", locale, crate_name), String::new()),
                key: key.clone(),
                locale: locale.to_string(),
                help: format!(
                    "Add translation for '{}' in {}/{}.ftl",
                    key, locale, crate_name
                ),
            })
        })
        .collect()
}

/// Validate a loaded FTL file against expected keys.
fn validate_loaded_ftl(
    content: &str,
    resource: &ast::Resource<String>,
    parse_errors: &[ParserError],
    expected_keys: &HashMap<String, HashSet<String>>,
    locale: &str,
    file_name: &str,
    crate_name: &str,
) -> Vec<ValidationIssue> {
    let mut issues = Vec::new();
    let mut keys_with_syntax_errors: HashSet<String> = HashSet::new();

    // Convert parse errors to issues
    for err in parse_errors {
        issues.push(parser_error_to_issue(
            err,
            content,
            locale,
            file_name,
            &mut keys_with_syntax_errors,
        ));
    }

    // Scan Junk entries to find keys with errors
    for entry in &resource.body {
        if let ast::Entry::Junk { content: junk } = entry
            && let Some(key) = extract_key_from_junk(junk)
        {
            keys_with_syntax_errors.insert(key);
        }
    }

    // Build map of actual keys and their variables
    let actual_keys: HashMap<String, HashSet<String>> = resource
        .body
        .iter()
        .filter_map(|entry| match entry {
            ast::Entry::Message(msg) => {
                Some((msg.id.name.clone(), extract_variables_from_message(msg)))
            },
            _ => None,
        })
        .collect();

    // Check for missing keys and variables
    for (key, expected_vars) in expected_keys {
        // Skip keys that have syntax errors - they're already reported
        if keys_with_syntax_errors.contains(key) {
            continue;
        }

        let Some(actual_vars) = actual_keys.get(key) else {
            // Key is missing
            issues.push(ValidationIssue::MissingKey(MissingKeyError {
                src: NamedSource::new(file_name, content.to_string()),
                key: key.clone(),
                locale: locale.to_string(),
                help: format!(
                    "Add translation for '{}' in {}/{}.ftl",
                    key, locale, crate_name
                ),
            }));
            continue;
        };

        // Check for missing variables
        for var in expected_vars {
            if actual_vars.contains(var) {
                continue;
            }
            let span = find_key_span(content, key)
                .unwrap_or_else(|| SourceSpan::new(0_usize.into(), 1_usize));

            issues.push(ValidationIssue::MissingVariable(MissingVariableWarning {
                src: NamedSource::new(file_name, content.to_string()),
                span,
                variable: var.clone(),
                key: key.clone(),
                locale: locale.to_string(),
                help: format!(
                    "The Rust code generated by es-fluent declares variable '${}' but the translation omits it",
                    var
                ),
            }));
        }
    }

    issues
}

/// Convert a fluent-syntax ParserError to a ValidationIssue.
fn parser_error_to_issue(
    err: &ParserError,
    content: &str,
    locale: &str,
    file_name: &str,
    keys_with_syntax_errors: &mut HashSet<String>,
) -> ValidationIssue {
    // Try to extract message key from the junk slice if available
    if let Some(ref slice) = err.slice {
        let junk_content = &content[slice.clone()];
        if let Some(key) = extract_key_from_junk(junk_content) {
            keys_with_syntax_errors.insert(key);
        }
    }

    // Calculate span from ParserError position
    let span_len = if err.pos.end > err.pos.start {
        err.pos.end - err.pos.start
    } else {
        1
    };

    ValidationIssue::SyntaxError(FtlSyntaxError {
        src: NamedSource::new(file_name, content.to_string()),
        span: SourceSpan::new(err.pos.start.into(), span_len),
        locale: locale.to_string(),
        file_name: file_name.to_string(),
        help: err.kind.to_string(),
    })
}

/// Try to extract a message key from junk content.
/// Junk typically starts with the message identifier like "message-key = ..."
fn extract_key_from_junk(junk: &str) -> Option<String> {
    static KEY_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^[a-zA-Z0-9_-]+").unwrap());

    KEY_REGEX
        .find(junk.trim_start())
        .map(|m| m.as_str().to_string())
}

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

    #[test]
    fn test_find_key_span() {
        let source = "## Comment\nhello = Hello\nworld = World";
        let span = find_key_span(source, "hello").unwrap();
        assert_eq!(span.offset(), 11);
        assert_eq!(span.len(), 5);
    }

    #[test]
    fn test_find_key_span_not_found() {
        let source = "hello = Hello";
        let span = find_key_span(source, "goodbye");
        assert!(span.is_none());
    }

    #[test]
    fn test_extract_key_from_junk() {
        assert_eq!(
            extract_key_from_junk("my-key = some value"),
            Some("my-key".to_string())
        );
        assert_eq!(
            extract_key_from_junk("  spaced-key = value"),
            Some("spaced-key".to_string())
        );
        assert_eq!(extract_key_from_junk("# comment"), None);
        assert_eq!(extract_key_from_junk(""), None);
    }

    #[test]
    fn test_extract_variables() {
        let content = "hello = Hello { $name }, you have { $count } messages";
        let resource = parser::parse(content.to_string()).unwrap();

        if let ast::Entry::Message(msg) = &resource.body[0] {
            let vars = extract_variables_from_message(msg);
            assert!(vars.contains("name"));
            assert!(vars.contains("count"));
            assert_eq!(vars.len(), 2);
        } else {
            panic!("Expected a message");
        }
    }
}