Merge pull request #4 from WendellXY/feature/plural-rules-engine

feat: plural rules engine, validation reports, CLI integration, and autofix

Author: WendellXY

README.md

@@ -61,6 +61,7 @@ This is a `0.4.0` release available on [crates.io](https://crates.io/crates/lang
 - Stats (JSON): `langcodec stats -i Localizable.xcstrings --json`
   - See full options: langcodec-cli/README.md#stats
   - Example output:
+  
     ```json
     {
       "summary": { "languages": 1, "unique_keys": 42 },

ROADMAP.md

@@ -22,10 +22,10 @@ Legend: [ ] todo, [x] done, [~] in progress
   - [x] Detect placeholder mismatches across languages; strict vs non‑strict modes
   - [x] Auto‑fix option for common cases (`normalize_placeholders_in_place`)
   - [x] Tests across singular and plural entries; cross‑language normalization
-- [ ] Plural rules engine
-  - [ ] CLDR‑driven required category sets per locale (few/many/etc.)
-  - [ ] Validation pass: flag missing categories per key+locale
-  - [ ] CLI: `view --check-plurals` and `validate` output
+- [~] Plural rules engine
+  - [x] CLDR‑driven required category sets per locale (few/many/etc.)
+  - [x] Validation pass: flag missing categories per key+locale
+  - [~] CLI: `view --check-plurals` and `validate` output
 - [ ] Strict vs. permissive parsing
   - [ ] Global setting in lib; CLI `--strict` flag
   - [ ] Consistent error surfaces with actionable context

langcodec-cli/Cargo.toml

@@ -12,7 +12,7 @@ categories = ["command-line-utilities", "internationalization", "localization"]
 documentation = "https://docs.rs/langcodec-cli"
 
 [dependencies]
-langcodec = "0.4.1"
+langcodec = { path = "../langcodec", version = "0.4.1" }
 clap = { version = "4", features = ["derive"] }
 clap_complete = "4"
 unicode-width = "0.2.1"

langcodec-cli/src/main.rs

@@ -74,6 +74,10 @@ enum Commands {
         /// Display full value without truncation (even in terminal)
         #[arg(long)]
         full: bool,
+
+        /// Validate plural completeness against CLDR category sets
+        #[arg(long, default_value_t = false)]
+        check_plurals: bool,
     },
 
     /// Merge multiple localization files into one output file with automatic format detection and conversion.
@@ -187,7 +191,12 @@ fn main() {
                 },
             );
         }
-        Commands::View { input, lang, full } => {
+        Commands::View {
+            input,
+            lang,
+            full,
+            check_plurals,
+        } => {
             // Create validation context
             let mut context = ValidationContext::new().with_input_file(input.clone());
 
@@ -223,6 +232,16 @@ fn main() {
             }
 
             print_view(&codec, &lang, full);
+
+            if check_plurals {
+                match codec.validate_plurals() {
+                    Ok(()) => println!("\n✅ Plural validation passed"),
+                    Err(e) => {
+                        eprintln!("\n❌ Plural validation failed: {}", e);
+                        std::process::exit(2);
+                    }
+                }
+            }
         }
         Commands::Merge {
             inputs,

langcodec-cli/src/stats.rs

@@ -1,4 +1,4 @@
-use langcodec::{Codec, types::EntryStatus};
+use langcodec::{Codec, collect_resource_plural_issues, types::EntryStatus};
 use serde_json::json;
 use std::collections::HashMap;
 
@@ -46,6 +46,10 @@ pub fn print_stats(codec: &Codec, lang_filter: &Option<String>, json_output: boo
             for e in &res.entries {
                 accumulate(&mut stats, &e.status);
             }
+            let plural_issues = collect_resource_plural_issues(res);
+            let missing_plural_entries = plural_issues.len();
+            let missing_plural_categories_total: usize =
+                plural_issues.iter().map(|r| r.missing.len()).sum();
             let percent = if stats.denominator == 0 {
                 100.0
             } else {
@@ -56,6 +60,8 @@ pub fn print_stats(codec: &Codec, lang_filter: &Option<String>, json_output: boo
                 "total": stats.total,
                 "by_status": stats.by_status,
                 "completion_percent": (percent * 100.0).round() / 100.0,
+                "missing_plural_entries": missing_plural_entries,
+                "missing_plural_categories_total": missing_plural_categories_total,
             }));
         }
         let summary = json!({
@@ -79,6 +85,10 @@ pub fn print_stats(codec: &Codec, lang_filter: &Option<String>, json_output: boo
         for e in &res.entries {
             accumulate(&mut stats, &e.status);
         }
+        let plural_issues = collect_resource_plural_issues(res);
+        let missing_plural_entries = plural_issues.len();
+        let missing_plural_categories_total: usize =
+            plural_issues.iter().map(|r| r.missing.len()).sum();
         let percent = if stats.denominator == 0 {
             100.0
         } else {
@@ -110,5 +120,9 @@ pub fn print_stats(codec: &Codec, lang_filter: &Option<String>, json_output: boo
             println!("    {}: {}", k, v);
         }
         println!("  Completion: {:.2}%", percent);
+        println!(
+            "  Missing plurals: {} (missing categories: {})",
+            missing_plural_entries, missing_plural_categories_total
+        );
     }
 }

langcodec-cli/tests/plural_validation_cli_tests.rs

@@ -0,0 +1,86 @@
+use std::fs;
+use std::process::Command;
+use tempfile::TempDir;
+
+#[test]
+fn test_cli_view_check_plurals_fails_on_missing() {
+    let temp_dir = TempDir::new().unwrap();
+    let input_file = temp_dir.path().join("strings.xml");
+
+    // English requires 'one' and 'other'; provide only 'other'
+    let xml = r#"
+        <resources>
+            <plurals name="apples" translatable="true">
+                <item quantity="other">%d apples</item>
+            </plurals>
+        </resources>
+    "#;
+    fs::write(&input_file, xml).unwrap();
+
+    let output = Command::new("cargo")
+        .args([
+            "run",
+            "--quiet",
+            "--",
+            "view",
+            "-i",
+            input_file.to_str().unwrap(),
+            "--lang",
+            "en",
+            "--check-plurals",
+        ])
+        .output()
+        .unwrap();
+
+    assert!(
+        !output.status.success(),
+        "CLI unexpectedly succeeded: {}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("Plural validation failed"),
+        "stderr: {}",
+        stderr
+    );
+}
+
+#[test]
+fn test_cli_view_check_plurals_passes_when_complete() {
+    let temp_dir = TempDir::new().unwrap();
+    let input_file = temp_dir.path().join("strings.xml");
+
+    // English: provide 'one' and 'other'
+    let xml = r#"
+        <resources>
+            <plurals name="apples" translatable="true">
+                <item quantity="one">One apple</item>
+                <item quantity="other">%d apples</item>
+            </plurals>
+        </resources>
+    "#;
+    fs::write(&input_file, xml).unwrap();
+
+    let output = Command::new("cargo")
+        .args([
+            "run",
+            "--quiet",
+            "--",
+            "view",
+            "-i",
+            input_file.to_str().unwrap(),
+            "--lang",
+            "en",
+            "--check-plurals",
+        ])
+        .output()
+        .unwrap();
+
+    assert!(
+        output.status.success(),
+        "CLI failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("✅ Plural validation passed"));
+}

langcodec/README.md

@@ -13,7 +13,7 @@ Universal localization file toolkit for Rust. Parse, write, convert, merge.
 langcodec = "0.4.0"
 ```
 
-Docs: https://docs.rs/langcodec
+Docs: <https://docs.rs/langcodec>
 
 ## Quick Start
 

langcodec/src/codec.rs

@@ -613,6 +613,60 @@ impl Codec {
         Ok(())
     }
 
+    /// Validates plural completeness per CLDR category sets for each locale.
+    ///
+    /// For each plural entry in each resource, checks that all required plural
+    /// categories for the language are present. Returns a Validation error with
+    /// aggregated details if any are missing.
+    pub fn validate_plurals(&self) -> Result<(), Error> {
+        use crate::plural_rules::collect_resource_plural_issues;
+
+        let mut reports = Vec::new();
+        for res in &self.resources {
+            reports.extend(collect_resource_plural_issues(res));
+        }
+
+        if reports.is_empty() {
+            return Ok(());
+        }
+
+        // Fold into an Error message for the validating API
+        let mut lines = Vec::new();
+        for r in reports {
+            let miss: Vec<String> = r.missing.iter().map(|k| format!("{:?}", k)).collect();
+            let have: Vec<String> = r.have.iter().map(|k| format!("{:?}", k)).collect();
+            lines.push(format!(
+                "lang='{}' key='{}': missing plural categories: [{}] (have: [{}])",
+                r.language,
+                r.key,
+                miss.join(", "),
+                have.join(", ")
+            ));
+        }
+        Err(Error::validation_error(lines.join("\n")))
+    }
+
+    /// Collects non-fatal plural validation reports across all resources.
+    pub fn collect_plural_issues(&self) -> Vec<crate::plural_rules::PluralValidationReport> {
+        use crate::plural_rules::collect_resource_plural_issues;
+        let mut reports = Vec::new();
+        for res in &self.resources {
+            reports.extend(collect_resource_plural_issues(res));
+        }
+        reports
+    }
+
+    /// Autofix: fill missing plural categories using 'other' and mark entries as NeedsReview.
+    /// Returns total categories added across all resources.
+    pub fn autofix_fill_missing_from_other(&mut self) -> usize {
+        use crate::plural_rules::autofix_fill_missing_from_other_resource;
+        let mut total = 0usize;
+        for res in &mut self.resources {
+            total += autofix_fill_missing_from_other_resource(res);
+        }
+        total
+    }
+
     /// Cleans up resources by removing empty resources and entries.
     pub fn clean_up_resources(&mut self) {
         self.resources
@@ -962,7 +1016,18 @@ impl Codec {
         path: P,
         format_type: FormatType,
     ) -> Result<(), Error> {
-        let language = crate::converter::infer_language_from_path(&path, &format_type)?;
+        let mut language = crate::converter::infer_language_from_path(&path, &format_type)?;
+        // Fallback to explicitly provided language if inference failed
+        if language.is_none() {
+            match &format_type {
+                FormatType::Strings(lang_opt) | FormatType::AndroidStrings(lang_opt) => {
+                    if let Some(l) = lang_opt {
+                        language = Some(l.clone());
+                    }
+                }
+                _ => {}
+            }
+        }
 
         let domain = path
             .as_ref()

langcodec/src/lib.rs

@@ -143,6 +143,7 @@ pub mod converter;
 pub mod error;
 pub mod formats;
 pub mod placeholder;
+pub mod plural_rules;
 pub mod traits;
 pub mod types;
 
@@ -158,6 +159,10 @@ pub use crate::{
     error::Error,
     formats::FormatType,
     placeholder::{extract_placeholders, normalize_placeholders, signature},
+    plural_rules::{
+        PluralValidationReport, autofix_fill_missing_from_other_resource,
+        collect_resource_plural_issues, required_categories_for_str, validate_resource_plurals,
+    },
     types::{
         ConflictStrategy, Entry, EntryStatus, Metadata, Plural, PluralCategory, Resource,
         Translation,