datasynth_core/country/
mod.rs

1//! Pluggable country-pack architecture.
2//!
3//! Loads country-specific configuration (holidays, names, tax rates, phone
4//! formats, address data, payroll rules, etc.) from JSON files.  Built-in
5//! packs are compiled in via `include_str!`; external packs can be loaded
6//! from a directory at runtime.
7
8pub mod easter;
9pub mod error;
10pub mod lunar;
11pub mod merge;
12pub mod schema;
13
14pub use error::CountryPackError;
15pub use schema::CountryPack;
16
17use std::collections::HashMap;
18use std::fmt;
19use std::path::Path;
20
21use merge::{apply_override, deep_merge};
22
23// ---------------------------------------------------------------------------
24// Embedded packs
25// ---------------------------------------------------------------------------
26
27const DEFAULT_PACK_JSON: &str = include_str!("../../country-packs/_default.json");
28const US_PACK_JSON: &str = include_str!("../../country-packs/US.json");
29const DE_PACK_JSON: &str = include_str!("../../country-packs/DE.json");
30const GB_PACK_JSON: &str = include_str!("../../country-packs/GB.json");
31const FR_PACK_JSON: &str = include_str!("../../country-packs/FR.json");
32const JP_PACK_JSON: &str = include_str!("../../country-packs/JP.json");
33const CN_PACK_JSON: &str = include_str!("../../country-packs/CN.json");
34const IN_PACK_JSON: &str = include_str!("../../country-packs/IN.json");
35const IT_PACK_JSON: &str = include_str!("../../country-packs/IT.json");
36const ES_PACK_JSON: &str = include_str!("../../country-packs/ES.json");
37const CA_PACK_JSON: &str = include_str!("../../country-packs/CA.json");
38
39// ---------------------------------------------------------------------------
40// CountryCode
41// ---------------------------------------------------------------------------
42
43/// Validated ISO 3166-1 alpha-2 country code (or `_DEFAULT`).
44#[derive(Debug, Clone, PartialEq, Eq, Hash)]
45pub struct CountryCode(String);
46
47impl CountryCode {
48    /// Create a `CountryCode`, validating that it is exactly 2 uppercase ASCII
49    /// letters or the special `_DEFAULT` sentinel.
50    pub fn new(code: &str) -> Result<Self, CountryPackError> {
51        let code = code.trim().to_uppercase();
52        if code == "_DEFAULT" {
53            return Ok(Self(code));
54        }
55        if code.len() == 2 && code.chars().all(|c| c.is_ascii_uppercase()) {
56            Ok(Self(code))
57        } else {
58            Err(CountryPackError::InvalidCountryCode(code))
59        }
60    }
61
62    pub fn as_str(&self) -> &str {
63        &self.0
64    }
65}
66
67impl fmt::Display for CountryCode {
68    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69        f.write_str(&self.0)
70    }
71}
72
73// ---------------------------------------------------------------------------
74// CountryPackRegistry
75// ---------------------------------------------------------------------------
76
77/// Central registry that owns all loaded country packs and provides merged
78/// access keyed by country code.
79pub struct CountryPackRegistry {
80    default_pack: CountryPack,
81    packs: HashMap<CountryCode, CountryPack>,
82}
83
84impl CountryPackRegistry {
85    /// Build a registry from embedded packs, optionally loading additional
86    /// packs from `external_dir` and applying per-country `overrides`.
87    pub fn new(
88        external_dir: Option<&Path>,
89        overrides: &HashMap<String, serde_json::Value>,
90    ) -> Result<Self, CountryPackError> {
91        let mut registry = Self::builtin_only()?;
92
93        // Load external packs if a directory is provided.
94        if let Some(dir) = external_dir {
95            registry.load_external_dir(dir)?;
96        }
97
98        // Apply per-country overrides.
99        for (code_str, value) in overrides {
100            let code = CountryCode::new(code_str)?;
101            if let Some(pack) = registry.packs.get_mut(&code) {
102                apply_override(pack, value)?;
103            } else {
104                // Create a new pack by merging default + override.
105                let mut pack = registry.default_pack.clone();
106                pack.country_code = code_str.to_uppercase();
107                apply_override(&mut pack, value)?;
108                registry.packs.insert(code, pack);
109            }
110        }
111
112        Ok(registry)
113    }
114
115    /// Build a registry from the embedded (built-in) packs only.
116    pub fn builtin_only() -> Result<Self, CountryPackError> {
117        let default_pack: CountryPack = serde_json::from_str(DEFAULT_PACK_JSON)
118            .map_err(|e| CountryPackError::parse(format!("_default.json: {e}")))?;
119
120        let mut packs = HashMap::new();
121
122        for (json, label) in [
123            (US_PACK_JSON, "US.json"),
124            (DE_PACK_JSON, "DE.json"),
125            (GB_PACK_JSON, "GB.json"),
126            (FR_PACK_JSON, "FR.json"),
127            (JP_PACK_JSON, "JP.json"),
128            (CN_PACK_JSON, "CN.json"),
129            (IN_PACK_JSON, "IN.json"),
130            (IT_PACK_JSON, "IT.json"),
131            (ES_PACK_JSON, "ES.json"),
132            (CA_PACK_JSON, "CA.json"),
133        ] {
134            let pack = Self::parse_and_merge(&default_pack, json, label)?;
135            let code = CountryCode::new(&pack.country_code)?;
136            packs.insert(code, pack);
137        }
138
139        Ok(Self {
140            default_pack,
141            packs,
142        })
143    }
144
145    /// Look up a pack by `CountryCode`. Falls back to the default pack for
146    /// unknown codes.
147    pub fn get(&self, code: &CountryCode) -> &CountryPack {
148        self.packs.get(code).unwrap_or(&self.default_pack)
149    }
150
151    /// Convenience: look up by a raw country-code string (case-insensitive).
152    /// Returns the default pack if the code is invalid or unknown.
153    pub fn get_by_str(&self, code: &str) -> &CountryPack {
154        match CountryCode::new(code) {
155            Ok(cc) => self.get(&cc),
156            Err(_) => &self.default_pack,
157        }
158    }
159
160    /// List all country codes that have explicit packs (excludes `_DEFAULT`).
161    pub fn available_countries(&self) -> Vec<&CountryCode> {
162        self.packs.keys().collect()
163    }
164
165    /// Access the default (fallback) pack.
166    pub fn default_pack(&self) -> &CountryPack {
167        &self.default_pack
168    }
169
170    // -- internal helpers ---------------------------------------------------
171
172    /// Parse a country JSON string and deep-merge it on top of the default.
173    fn parse_and_merge(
174        default: &CountryPack,
175        json: &str,
176        label: &str,
177    ) -> Result<CountryPack, CountryPackError> {
178        let country_value: serde_json::Value = serde_json::from_str(json)
179            .map_err(|e| CountryPackError::parse(format!("{label}: {e}")))?;
180
181        let mut base_value = serde_json::to_value(default)
182            .map_err(|e| CountryPackError::parse(format!("serialize default: {e}")))?;
183
184        deep_merge(&mut base_value, &country_value);
185
186        serde_json::from_value(base_value)
187            .map_err(|e| CountryPackError::parse(format!("{label} merge: {e}")))
188    }
189
190    /// Scan an external directory for `*.json` files and load each as a
191    /// country pack, merging on top of the default.
192    fn load_external_dir(&mut self, dir: &Path) -> Result<(), CountryPackError> {
193        let entries = std::fs::read_dir(dir)
194            .map_err(|e| CountryPackError::directory(format!("{}: {e}", dir.display())))?;
195
196        for entry in entries {
197            let entry = entry
198                .map_err(|e| CountryPackError::directory(format!("{}: {e}", dir.display())))?;
199            let path = entry.path();
200
201            if path.extension().and_then(|e| e.to_str()) != Some("json") {
202                continue;
203            }
204
205            // Skip _default.json in external dirs (only embedded default is used).
206            if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
207                if stem == "_default" {
208                    continue;
209                }
210            }
211
212            let json = std::fs::read_to_string(&path)
213                .map_err(|e| CountryPackError::directory(format!("{}: {e}", path.display())))?;
214
215            let label = path
216                .file_name()
217                .and_then(|n| n.to_str())
218                .unwrap_or("unknown");
219
220            let pack = Self::parse_and_merge(&self.default_pack, &json, label)?;
221            let code = CountryCode::new(&pack.country_code)?;
222            self.packs.insert(code, pack);
223        }
224
225        Ok(())
226    }
227}
228
229impl fmt::Debug for CountryPackRegistry {
230    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
231        f.debug_struct("CountryPackRegistry")
232            .field("default", &self.default_pack.country_code)
233            .field(
234                "countries",
235                &self.packs.keys().map(|c| c.as_str()).collect::<Vec<_>>(),
236            )
237            .finish()
238    }
239}
240
241#[cfg(test)]
242mod tests {
243    use super::*;
244
245    #[test]
246    fn test_country_code_valid() {
247        assert!(CountryCode::new("US").is_ok());
248        assert!(CountryCode::new("de").is_ok()); // lowercased → DE
249        assert!(CountryCode::new("GB").is_ok());
250        assert!(CountryCode::new("_DEFAULT").is_ok());
251    }
252
253    #[test]
254    fn test_country_code_invalid() {
255        assert!(CountryCode::new("").is_err());
256        assert!(CountryCode::new("USA").is_err());
257        assert!(CountryCode::new("1A").is_err());
258        assert!(CountryCode::new("A").is_err());
259    }
260
261    #[test]
262    fn test_builtin_only() {
263        let reg = CountryPackRegistry::builtin_only().expect("should load");
264        assert!(reg.available_countries().len() >= 3);
265
266        let us = reg.get_by_str("US");
267        assert_eq!(us.country_code, "US");
268        assert!(!us.holidays.fixed.is_empty());
269
270        let de = reg.get_by_str("DE");
271        assert_eq!(de.country_code, "DE");
272
273        let gb = reg.get_by_str("GB");
274        assert_eq!(gb.country_code, "GB");
275    }
276
277    #[test]
278    fn test_all_ten_packs_load() {
279        let reg = CountryPackRegistry::builtin_only().expect("should load");
280        assert_eq!(reg.available_countries().len(), 10);
281
282        for code in ["US", "DE", "GB", "FR", "JP", "CN", "IN", "IT", "ES", "CA"] {
283            let pack = reg.get_by_str(code);
284            assert_eq!(pack.country_code, code, "country_code mismatch for {code}");
285            assert!(
286                !pack.holidays.fixed.is_empty(),
287                "{code} has no fixed holidays"
288            );
289            assert!(
290                !pack.names.cultures.is_empty(),
291                "{code} has no name cultures"
292            );
293        }
294    }
295
296    #[test]
297    fn test_fr_pack_loads() {
298        let reg = CountryPackRegistry::builtin_only().expect("should load");
299        let fr = reg.get_by_str("FR");
300        assert_eq!(fr.country_code, "FR");
301        assert_eq!(fr.locale.default_currency, "EUR");
302        assert_eq!(fr.locale.default_timezone, "Europe/Paris");
303        assert!(fr.tax.vat.standard_rate > 0.19);
304    }
305
306    #[test]
307    fn test_jp_pack_loads() {
308        let reg = CountryPackRegistry::builtin_only().expect("should load");
309        let jp = reg.get_by_str("JP");
310        assert_eq!(jp.country_code, "JP");
311        assert_eq!(jp.locale.default_currency, "JPY");
312        assert_eq!(jp.locale.currency_decimal_places, 0);
313        assert_eq!(jp.locale.fiscal_year.start_month, 4);
314    }
315
316    #[test]
317    fn test_cn_pack_loads() {
318        let reg = CountryPackRegistry::builtin_only().expect("should load");
319        let cn = reg.get_by_str("CN");
320        assert_eq!(cn.country_code, "CN");
321        assert_eq!(cn.locale.default_currency, "CNY");
322        assert_eq!(cn.locale.default_timezone, "Asia/Shanghai");
323    }
324
325    #[test]
326    fn test_in_pack_loads() {
327        let reg = CountryPackRegistry::builtin_only().expect("should load");
328        let india = reg.get_by_str("IN");
329        assert_eq!(india.country_code, "IN");
330        assert_eq!(india.locale.default_currency, "INR");
331        assert_eq!(india.locale.number_format.grouping, vec![3, 2]);
332        assert_eq!(india.locale.fiscal_year.start_month, 4);
333    }
334
335    #[test]
336    fn test_it_pack_loads() {
337        let reg = CountryPackRegistry::builtin_only().expect("should load");
338        let it = reg.get_by_str("IT");
339        assert_eq!(it.country_code, "IT");
340        assert_eq!(it.locale.default_currency, "EUR");
341        assert!(it.payroll.thirteenth_month);
342    }
343
344    #[test]
345    fn test_es_pack_loads() {
346        let reg = CountryPackRegistry::builtin_only().expect("should load");
347        let es = reg.get_by_str("ES");
348        assert_eq!(es.country_code, "ES");
349        assert_eq!(es.locale.default_currency, "EUR");
350        assert_eq!(es.locale.default_timezone, "Europe/Madrid");
351    }
352
353    #[test]
354    fn test_ca_pack_loads() {
355        let reg = CountryPackRegistry::builtin_only().expect("should load");
356        let ca = reg.get_by_str("CA");
357        assert_eq!(ca.country_code, "CA");
358        assert_eq!(ca.locale.default_currency, "CAD");
359        assert!(!ca.tax.payroll_tax.income_tax_brackets.is_empty());
360    }
361
362    #[test]
363    fn test_fallback_to_default() {
364        let reg = CountryPackRegistry::builtin_only().expect("should load");
365        let unknown = reg.get_by_str("ZZ");
366        assert_eq!(unknown.country_code, "_DEFAULT");
367    }
368
369    #[test]
370    fn test_default_pack_parses() {
371        let pack: CountryPack =
372            serde_json::from_str(DEFAULT_PACK_JSON).expect("default pack should parse");
373        assert_eq!(pack.country_code, "_DEFAULT");
374        assert_eq!(pack.schema_version, "1.0");
375    }
376
377    #[test]
378    fn test_registry_with_overrides() {
379        let mut overrides = HashMap::new();
380        overrides.insert(
381            "US".to_string(),
382            serde_json::json!({"country_name": "USA Override"}),
383        );
384        let reg = CountryPackRegistry::new(None, &overrides).expect("should load");
385        let us = reg.get_by_str("US");
386        assert_eq!(us.country_name, "USA Override");
387    }
388}
datasynth_core/country/mod.rs

datasynth_core/country/
mod.rs
