cobre-io 0.1.1

Case directory loading and validation for the Cobre power systems ecosystem
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! Parsers for extension data files in the `system/` subdirectory.
//!
//! Extension files carry tabular data that augments the core entity registries
//! but is stored separately because it is multi-row per entity (e.g., VHA
//! curves for hydro plants, FPHA hyperplanes).
//!
//! ## Parsing convention
//!
//! Parquet parsers follow the canonical pattern:
//!
//! 1. Open the file with `std::fs::File::open`.
//! 2. Build a `ParquetRecordBatchReaderBuilder` and consume all record batches.
//! 3. Extract typed columns by name; return `SchemaError` for missing or wrong-type columns.
//! 4. Validate per-row constraints; return `SchemaError` on violation.
//! 5. Sort the output by the documented sort key and return.
//!
//! JSON parsers follow the four-step pipeline:
//!
//! 1. Read the file with `std::fs::read_to_string`.
//! 2. Deserialize with `serde_json::from_str` through intermediate raw types.
//! 3. Validate with a `validate_raw` function.
//! 4. Convert raw types to public types and sort the output.
//!
//! Cross-reference validation (checking that referenced entity IDs exist in
//! their registries) is deferred to Layer 3 (Epic 06). Monotonicity and other
//! multi-row semantic constraints are deferred to Layer 5 (Epic 06).

pub mod fpha_hyperplanes;
pub mod hydro_geometry;
pub mod production_models;

pub use fpha_hyperplanes::{FphaHyperplaneRow, parse_fpha_hyperplanes};
pub use hydro_geometry::{HydroGeometryRow, parse_hydro_geometry};
pub use production_models::{
    FittingWindow, FphaConfig, ProductionModelConfig, SeasonConfig, SelectionMode, StageRange,
    parse_production_models,
};

use crate::LoadError;
use std::path::Path;

/// Load `system/hydro_production_models.json` when the path is known, or return
/// an empty `Vec` when the file is absent (optional file).
///
/// This wrapper is the standard entry point used by the loading pipeline. When
/// `path` is `None` (the structural validation step found no file at the expected
/// location), it returns `Ok(Vec::new())` without touching the filesystem.
///
/// # Errors
///
/// Propagates [`LoadError`] from [`parse_production_models`] when `path` is `Some`.
///
/// # Examples
///
/// ```
/// use cobre_io::extensions::load_production_models;
///
/// // No file present — returns empty vec.
/// let models = load_production_models(None).expect("no file is fine");
/// assert!(models.is_empty());
/// ```
pub fn load_production_models(
    path: Option<&Path>,
) -> Result<Vec<ProductionModelConfig>, LoadError> {
    match path {
        None => Ok(Vec::new()),
        Some(p) => parse_production_models(p),
    }
}

/// Load `system/fpha_hyperplanes.parquet` when the path is known, or return
/// an empty `Vec` when the file is absent (optional file).
///
/// This wrapper is the standard entry point used by the loading pipeline. When
/// `path` is `None` (the structural validation step found no file at the expected
/// location), it returns `Ok(Vec::new())` without touching the filesystem.
///
/// # Errors
///
/// Propagates [`LoadError`] from [`parse_fpha_hyperplanes`] when `path` is `Some`.
///
/// # Examples
///
/// ```
/// use cobre_io::extensions::load_fpha_hyperplanes;
///
/// // No file present — returns empty vec.
/// let rows = load_fpha_hyperplanes(None).expect("no file is fine");
/// assert!(rows.is_empty());
/// ```
pub fn load_fpha_hyperplanes(path: Option<&Path>) -> Result<Vec<FphaHyperplaneRow>, LoadError> {
    match path {
        None => Ok(Vec::new()),
        Some(p) => parse_fpha_hyperplanes(p),
    }
}

#[cfg(test)]
#[allow(clippy::doc_markdown, clippy::unwrap_used, clippy::panic)]
mod tests {
    use super::*;

    /// `load_production_models(None)` returns `Ok(Vec::new())` without I/O.
    #[test]
    fn test_load_production_models_none_returns_empty() {
        let result = load_production_models(None).unwrap();
        assert!(result.is_empty(), "expected empty vec for None path");
    }

    /// `load_fpha_hyperplanes(None)` returns `Ok(Vec::new())` without I/O.
    #[test]
    fn test_load_fpha_hyperplanes_none_returns_empty() {
        let result = load_fpha_hyperplanes(None).unwrap();
        assert!(result.is_empty(), "expected empty vec for None path");
    }
}