Skip to main content

powerio_dist/
convert.rs

1//! Distribution format dispatch.
2
3use crate::model::{DistSourceFormat, MulticonductorNetwork};
4
5/// Extra files an emitter generated beside the primary text payload.
6#[derive(Debug, Clone, PartialEq, Eq)]
7pub(crate) struct TextSidecar {
8    /// Relative file path the primary text refers to.
9    pub(crate) path: String,
10    /// File content.
11    pub(crate) text: String,
12}
13
14/// One format serializer's internal output before it commits to a destination.
15#[derive(Debug, Clone)]
16pub(crate) struct TextEmission {
17    pub(crate) text: String,
18    pub(crate) sidecars: Vec<TextSidecar>,
19    pub(crate) diagnostics: Vec<crate::diagnostics::Diagnostic>,
20    pub(crate) fidelity: powerio_core::Fidelity,
21}
22
23impl TextEmission {
24    pub(crate) fn new(
25        text: String,
26        sidecars: Vec<TextSidecar>,
27        diagnostics: crate::diagnostics::Diagnostics,
28    ) -> Self {
29        Self {
30            text,
31            sidecars,
32            diagnostics: diagnostics.into_records(),
33            fidelity: powerio_core::Fidelity::Canonical,
34        }
35    }
36
37    /// An emission that dropped nothing, e.g. a same format echo.
38    pub(crate) fn faithful(text: String) -> Self {
39        let mut emission = Self::new(text, Vec::new(), crate::diagnostics::Diagnostics::new());
40        emission.fidelity = powerio_core::Fidelity::ExactSameFormat;
41        emission
42    }
43
44    /// Record one finding after the writer has run.
45    pub(crate) fn push(
46        &mut self,
47        info: &'static crate::diagnostics::DiagnosticInfo,
48        message: impl Into<String>,
49    ) {
50        self.diagnostics
51            .push(crate::diagnostics::Diagnostic::of(info, message));
52    }
53
54    #[cfg(test)]
55    pub(crate) fn render_diagnostics(&self) -> Vec<String> {
56        crate::diagnostics::render_diagnostics(&self.diagnostics)
57    }
58}
59
60/// A writable distribution format.
61#[derive(Clone, Copy, Debug, PartialEq, Eq)]
62#[non_exhaustive]
63pub enum DistTargetFormat {
64    Dss,
65    BmopfJson,
66    PmdJson,
67    /// Distribution CIM: one CIM100 RDF/XML document, or a directory of them
68    /// on input.
69    CimDist,
70    Gridlabd,
71    GridlabdArras,
72    /// MG-RAVENS JSON, the multiconductor (distribution) profile of the
73    /// LANL CIM-derived interchange schema.
74    RavensJson,
75    /// PowerModelsDistribution MATHEMATICAL model JSON: index based, per
76    /// unit, with transformers lowered to ideal units and loss branches.
77    PmdMathJson,
78    /// pandapower JSON of a three-phase network. Emission only echoes the
79    /// retained source of a module read from pandapower JSON. The reader
80    /// lives in `powerio_tnd::formats::pandapower`.
81    PandapowerJson,
82}
83
84/// Format specific policies for distribution network emission.
85#[derive(Clone, Debug, Default, PartialEq)]
86#[non_exhaustive]
87pub struct EmitOptions {
88    pub dss: crate::dss::DssEmitOptions,
89    pub bmopf: crate::bmopf::BmopfEmitOptions,
90    pub pmd_math: crate::pmd::PmdMathEmitOptions,
91}
92
93impl EmitOptions {
94    fn is_default_for(&self, format: DistTargetFormat) -> bool {
95        match format {
96            DistTargetFormat::Dss => self.dss == crate::dss::DssEmitOptions::default(),
97            DistTargetFormat::BmopfJson => self.bmopf == crate::bmopf::BmopfEmitOptions::default(),
98            DistTargetFormat::PmdMathJson => {
99                self.pmd_math == crate::pmd::PmdMathEmitOptions::default()
100            }
101            DistTargetFormat::PmdJson
102            | DistTargetFormat::CimDist
103            | DistTargetFormat::Gridlabd
104            | DistTargetFormat::GridlabdArras
105            | DistTargetFormat::RavensJson
106            | DistTargetFormat::PandapowerJson => true,
107        }
108    }
109}
110
111/// Resolves common names and file extensions to a target format.
112pub fn parse_dist_target_format(name: &str) -> Option<DistTargetFormat> {
113    let key = canonical_key(name);
114    match key.as_str() {
115        "dss" | "opendss" => Some(DistTargetFormat::Dss),
116        "glm" | "gridlabd" | "gridlabdpnnl" => Some(DistTargetFormat::Gridlabd),
117        "gridlabdarras" => Some(DistTargetFormat::GridlabdArras),
118        "pmd" | "pmdjson" | "engineering" => Some(DistTargetFormat::PmdJson),
119        "pmdmath" | "pmdmathjson" | "mathematical" => Some(DistTargetFormat::PmdMathJson),
120        "bmopf" | "bmopfjson" => Some(DistTargetFormat::BmopfJson),
121        "cimdist" => Some(DistTargetFormat::CimDist),
122        "ravens" | "ravensjson" | "mgravens" | "mgravensjson" => Some(DistTargetFormat::RavensJson),
123        "pandapower" | "pandapowerjson" | "pp" => Some(DistTargetFormat::PandapowerJson),
124        _ => None,
125    }
126}
127
128impl std::str::FromStr for DistTargetFormat {
129    type Err = crate::Error;
130
131    /// [`parse_dist_target_format`] as a `Result`, matching the transmission
132    /// hub's `TargetFormat: FromStr`.
133    fn from_str(s: &str) -> crate::Result<Self> {
134        parse_dist_target_format(s).ok_or_else(|| crate::Error::UnknownFormat(s.to_string()))
135    }
136}
137
138impl DistTargetFormat {
139    /// The canonical format name, accepted
140    /// back by [`parse_dist_target_format`].
141    pub fn name(self) -> &'static str {
142        match self {
143            DistTargetFormat::Dss => "dss",
144            DistTargetFormat::Gridlabd => "gridlabd",
145            DistTargetFormat::GridlabdArras => "gridlabd-arras",
146            DistTargetFormat::PmdJson => "pmd-json",
147            DistTargetFormat::PmdMathJson => "pmd-math-json",
148            DistTargetFormat::BmopfJson => "bmopf-json",
149            DistTargetFormat::CimDist => "cim-dist",
150            DistTargetFormat::RavensJson => "ravens-json",
151            DistTargetFormat::PandapowerJson => "pandapower-json",
152        }
153    }
154}
155
156fn canonical_key(name: &str) -> String {
157    name.to_ascii_lowercase()
158        .chars()
159        .filter(|c| *c != '-' && *c != '_')
160        .collect()
161}
162
163/// Element tables that identify a distribution document beside its `bus`
164/// table.
165///
166/// `load`, `shunt`, and `switch` are shared with PowerModels, so on their own
167/// they cannot tell the two apart. They stay in the list all the same, because
168/// [`NOT_BMOPF_KEYS`] is what refuses a PowerModels document, and it refuses it
169/// whatever else the document holds. Dropping the shared names instead would
170/// refuse a real BMOPF feeder built only from them, which the reader parses
171/// and which this classifier used to accept.
172///
173/// These names do not separate BMOPF from PMD: the two share most of their
174/// element vocabulary. `data_model` does that, and it is checked first.
175const DISTRIBUTION_ELEMENT_TABLES: &[&str] = &[
176    "capacitor",
177    // `control_profile` and `ibr` are typed dispatch tables of the reader,
178    // though the first draft moved them under `extras`: a pre-draft document
179    // still declares them at the top level, and what the reader accepts the
180    // classifier must identify.
181    "control_profile",
182    "generator",
183    "ibr",
184    "line",
185    "linecode",
186    "load",
187    "meta",
188    "shunt",
189    "switch",
190    "terminal_conventions",
191    "transformer",
192    "voltage_source",
193];
194
195/// Top level keys no BMOPF document carries, and a PowerModels or MATPOWER
196/// derived document does. One of these refuses the BMOPF reading whatever
197/// else the document holds, so a name that a future BMOPF revision adds
198/// cannot make a PowerModels file classify.
199const NOT_BMOPF_KEYS: &[&str] = &[
200    "baseMVA",
201    "branch",
202    "dcline",
203    "gen",
204    "per_unit",
205    "source_type",
206    "source_version",
207    "storage",
208];
209
210/// Top level tables only an MG-RAVENS document carries: its equipment nests
211/// under the CIM class hierarchy root and its buses are connectivity nodes.
212const RAVENS_MARKERS: &[&str] = &["PowerSystemResource", "ConnectivityNode"];
213
214/// The PMD marker. Neither BMOPF nor PowerModels carries this key, so it
215/// identifies the ENGINEERING and MATHEMATICAL models on its own; the PMD
216/// reader then rejects MATHEMATICAL with its own message.
217const PMD_MARKER: &str = "data_model";
218
219/// What the top level of a document holds, for classification only.
220///
221/// The probe reads the top level keys and skips every value, so it never
222/// materializes the document. The old classifier built a whole
223/// `serde_json::Value` and dropped it, which doubled the peak memory of a
224/// parse and did the tokenizing work twice: the chosen reader parses the
225/// same text again. A case file is attacker controlled input, so a reader
226/// sized allocation that serves no purpose is worth removing.
227// Five independent presence flags, which is what a marker probe is. An
228// enum or a builder, the shapes this lint steers toward, would model a
229// choice; these are not exclusive.
230#[allow(clippy::struct_excessive_bools)]
231#[derive(Default)]
232struct TopLevel {
233    /// The document is a JSON object.
234    is_object: bool,
235    pmd_marker: bool,
236    /// The PMD marker's value names the MATHEMATICAL model.
237    pmd_mathematical: bool,
238    bus: bool,
239    /// A key from [`DISTRIBUTION_ELEMENT_TABLES`].
240    dist_table: bool,
241    /// A key from [`NOT_BMOPF_KEYS`].
242    not_bmopf: bool,
243    /// An MG-RAVENS table: the CIM class hierarchy root or the connectivity
244    /// node table, which neither PMD nor BMOPF carries.
245    ravens: bool,
246}
247
248impl<'de> serde::Deserialize<'de> for TopLevel {
249    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
250        struct Probe;
251
252        impl<'de> serde::de::Visitor<'de> for Probe {
253            type Value = TopLevel;
254
255            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
256                f.write_str("a JSON document")
257            }
258
259            fn visit_map<A: serde::de::MapAccess<'de>>(
260                self,
261                mut map: A,
262            ) -> Result<TopLevel, A::Error> {
263                let mut out = TopLevel {
264                    is_object: true,
265                    ..TopLevel::default()
266                };
267                // Keys arrive as borrowed or owned strings. Nothing is kept:
268                // each key sets a flag and each value is discarded, so the
269                // probe holds a constant amount of memory whatever the size
270                // of the document.
271                while let Some(key) = map.next_key::<std::borrow::Cow<'_, str>>()? {
272                    let key = key.as_ref();
273                    out.pmd_marker |= key == PMD_MARKER;
274                    out.bus |= key == "bus";
275                    out.dist_table |= DISTRIBUTION_ELEMENT_TABLES.contains(&key);
276                    out.not_bmopf |= NOT_BMOPF_KEYS.contains(&key);
277                    out.ravens |= RAVENS_MARKERS.contains(&key);
278                    if key == PMD_MARKER {
279                        // The marker's value picks the PMD model; anything
280                        // but a string reads as the ENGINEERING default.
281                        let value = map.next_value::<serde_json::Value>()?;
282                        out.pmd_mathematical = value
283                            .as_str()
284                            .is_some_and(|m| m.eq_ignore_ascii_case("MATHEMATICAL"));
285                        continue;
286                    }
287                    map.next_value::<serde::de::IgnoredAny>()?;
288                }
289                Ok(out)
290            }
291
292            // A valid document that is not an object cannot be either
293            // format. Record that and let the caller report it, rather than
294            // failing as a parse error, which would send it to the BMOPF
295            // fallback.
296            fn visit_bool<E>(self, _: bool) -> Result<TopLevel, E> {
297                Ok(TopLevel::default())
298            }
299            fn visit_i64<E>(self, _: i64) -> Result<TopLevel, E> {
300                Ok(TopLevel::default())
301            }
302            fn visit_u64<E>(self, _: u64) -> Result<TopLevel, E> {
303                Ok(TopLevel::default())
304            }
305            fn visit_f64<E>(self, _: f64) -> Result<TopLevel, E> {
306                Ok(TopLevel::default())
307            }
308            fn visit_str<E>(self, _: &str) -> Result<TopLevel, E> {
309                Ok(TopLevel::default())
310            }
311            fn visit_unit<E>(self) -> Result<TopLevel, E> {
312                Ok(TopLevel::default())
313            }
314            fn visit_none<E>(self) -> Result<TopLevel, E> {
315                Ok(TopLevel::default())
316            }
317            fn visit_seq<A: serde::de::SeqAccess<'de>>(
318                self,
319                mut seq: A,
320            ) -> Result<TopLevel, A::Error> {
321                while seq.next_element::<serde::de::IgnoredAny>()?.is_some() {}
322                Ok(TopLevel::default())
323            }
324        }
325
326        deserializer.deserialize_any(Probe)
327    }
328}
329
330/// Distribution parser policy for a `.json` input.
331///
332/// Classification is by positive marker, never by "everything else is
333/// BMOPF": an unmarked document used to fall through to the BMOPF reader
334/// and parse into a bogus near-empty network.
335///
336/// - PMD carries `data_model`, which no other family here carries. The marker
337///   decides on its own: every real PMD ENGINEERING document also carries the
338///   element tables BMOPF uses, so a document holding both is the normal case
339///   and not a contradiction.
340/// - BMOPF carries a `bus` table beside at least one distribution element
341///   table, and no key that marks a PowerModels or MATPOWER derived document.
342/// - Anything else is refused with a message naming both rules.
343///
344/// Malformed JSON still routes to BMOPF so its reader reports the parse
345/// error, which names the byte offset. The probe never materializes the
346/// document, so classification costs one pass and constant memory.
347pub fn classify_distribution_json(text: &str) -> crate::Result<DistTargetFormat> {
348    // A leading byte order mark would fail the parse here and silently send
349    // a PMD document down the BMOPF fallback; classify without it.
350    let text = text.trim_start_matches('\u{feff}');
351    let unrecognized = |detail: &str| crate::Error::Json {
352        format: "distribution",
353        message: format!(
354            "not a recognized distribution document: {detail}. PMD ENGINEERING JSON \
355             carries `data_model`; BMOPF JSON carries a `bus` table beside one of \
356             {DISTRIBUTION_ELEMENT_TABLES:?}. Pass the format explicitly to override."
357        ),
358    };
359
360    let Ok(top) = serde_json::from_str::<TopLevel>(text) else {
361        return Ok(DistTargetFormat::BmopfJson);
362    };
363    if !top.is_object {
364        return Err(unrecognized("the top level is not an object"));
365    }
366
367    // `data_model` is authoritative. PMD ENGINEERING and BMOPF share most
368    // of their element table names (`line`, `linecode`, `transformer`, and
369    // the rest), so the marker separates them, not the table set. The PMD
370    // reader is what judges the marker's value, and it rejects the
371    // MATHEMATICAL model with its own message.
372    if top.ravens {
373        return Ok(DistTargetFormat::RavensJson);
374    }
375    if top.pmd_marker {
376        return Ok(if top.pmd_mathematical {
377            DistTargetFormat::PmdMathJson
378        } else {
379            DistTargetFormat::PmdJson
380        });
381    }
382    if top.bus && top.dist_table && !top.not_bmopf {
383        return Ok(DistTargetFormat::BmopfJson);
384    }
385    Err(if top.bus && top.not_bmopf {
386        unrecognized(
387            "it carries a `bus` table with PowerModels keys beside it, so it is a \
388             transmission document; read it through the transmission hub",
389        )
390    } else if top.bus {
391        unrecognized("its `bus` table has no distribution element table beside it")
392    } else {
393        unrecognized("it carries no marker of either format")
394    })
395}
396
397/// Parse one source into a compiled distribution module. The typed
398/// [`MulticonductorNetwork`] is the module's value; the reader's findings are
399/// the module's diagnostics; the source itself is retained on the module, so
400/// a same format emission echoes the input bytes exactly.
401///
402/// The format comes from the source's declared format when one was selected,
403/// the `.dss` or `.glm` extension otherwise, and for `.json` from
404/// [`classify_distribution_json`]. GridLAB-D defaults to the PNNL 5.3 profile
405/// (`gridlabd`, aliases `glm` and `gridlabd-pnnl`); `gridlabd-arras` selects
406/// the Arras 4.3 profile explicitly. See [`crate::glm::parse`] for explicit
407/// preprocessing inputs and the supported electrical profile.
408/// XML documents and directories use distribution CIM detection.
409///
410/// # Errors
411/// The operation failure carries the reader's findings up to the failure and
412/// retains the source for span interpretation.
413///
414pub fn parse(
415    source: powerio_core::Source,
416) -> std::result::Result<powerio_core::PioModule<MulticonductorNetwork>, powerio_core::Error> {
417    parse_with_dss_limits(source, crate::dss::DssReadLimits::default())
418}
419
420/// [`parse`] with the limits an OpenDSS read works under set by the caller.
421/// A case with several hundred thousand lines and loads needs more than the
422/// defaults allow; see [`crate::dss::DssReadLimits`]. The limits apply when
423/// the source reads as OpenDSS and have no effect on any other format.
424///
425/// ```no_run
426/// use powerio_dist::dss::DssReadLimits;
427///
428/// let source = powerio_core::Source::open("region/Master.dss")?;
429/// let limits = DssReadLimits::default()
430///     .max_include_bytes(1 << 30)
431///     .max_properties(1 << 26);
432/// let module = powerio_dist::parse_with_dss_limits(source, limits)?;
433/// # Ok::<(), powerio_core::Error>(())
434/// ```
435///
436/// # Errors
437/// As [`parse`].
438pub fn parse_with_dss_limits(
439    source: powerio_core::Source,
440    dss_limits: crate::dss::DssReadLimits,
441) -> std::result::Result<powerio_core::PioModule<MulticonductorNetwork>, powerio_core::Error> {
442    if source
443        .format()
444        .is_some_and(|f| is_sincal_multiconductor_token(f.as_str()))
445    {
446        return Err(sincal_feature_disabled(&source));
447    }
448    let selected = source
449        .format()
450        .and_then(|id| parse_dist_target_format(id.as_str()));
451    if matches!(
452        selected,
453        Some(DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras)
454    ) || (source.format().is_none()
455        && std::path::Path::new(source.name())
456            .extension()
457            .is_some_and(|ext| ext.eq_ignore_ascii_case("glm")))
458    {
459        let dialect = if selected == Some(DistTargetFormat::GridlabdArras) {
460            crate::glm::GlmDialect::Arras4_3
461        } else {
462            crate::glm::GlmDialect::Pnnl5_3
463        };
464        return crate::glm::parse(
465            source,
466            crate::glm::PreprocessOptions {
467                dialect,
468                ..Default::default()
469            },
470        );
471    }
472    let mut warnings = crate::collect::Diagnostics::new();
473    let mut dss_replay = None;
474    match parse_to_network(&source, &mut warnings, &mut dss_replay, dss_limits) {
475        Ok((network, format)) => {
476            // Record the detected format before the common constructor builds
477            // descriptors and the coarse `/value` source map.
478            let source = match powerio_core::FormatId::new(format.name()) {
479                Ok(format) => source.with_format(format),
480                Err(_) => source,
481            };
482            let mut module =
483                powerio_core::PioModule::parsed(network, source, warnings.into_records())?;
484            if let Some(replay) = dss_replay {
485                module.insert_extension(
486                    "org.powerio.opendss",
487                    serde_json::json!({
488                        "version": 1, "absolute_dependency": replay.absolute_dependency,
489                        "dependencies": replay.dependencies.iter().map(powerio_core::SourceId::as_str).collect::<Vec<_>>(),
490                    }),
491                )?;
492            }
493            Ok(module)
494        }
495        Err(error) => {
496            let core = powerio_core::Error::new(error.code(), error.to_string());
497            Err(core
498                .with_diagnostics(warnings.into_records())
499                .with_cause(error)
500                .with_source(source))
501        }
502    }
503}
504
505/// The format dispatch behind [`parse`]: the network and the format it was
506/// read as.
507fn parse_to_network(
508    source: &powerio_core::Source,
509    warnings: &mut crate::collect::Diagnostics,
510    dss_replay: &mut Option<crate::dss::read::ReplayContext>,
511    dss_limits: crate::dss::DssReadLimits,
512) -> crate::Result<(MulticonductorNetwork, DistTargetFormat)> {
513    let declared = source
514        .format()
515        .map(powerio_core::FormatId::as_str)
516        .map(|name| {
517            parse_dist_target_format(name)
518                .ok_or_else(|| crate::Error::UnknownFormat(name.to_string()))
519        })
520        .transpose()?;
521    if source.is_directory() {
522        let cim = declared.map_or_else(
523            || crate::cim::source_looks_like_cim_dist(source),
524            |format| format == DistTargetFormat::CimDist,
525        );
526        if !cim {
527            return Err(crate::Error::UnknownFormat(format!(
528                "{} is a directory, and the only distribution format read from a directory is \
529                 a cim-dist document set; pass a case file",
530                source.name()
531            )));
532        }
533    }
534    let format = if let Some(format) = declared {
535        format
536    } else if source.is_directory() {
537        DistTargetFormat::CimDist
538    } else {
539        let ext = std::path::Path::new(source.name())
540            .extension()
541            .and_then(|e| e.to_str())
542            .unwrap_or_default()
543            .to_ascii_lowercase();
544        match ext.as_str() {
545            "dss" => DistTargetFormat::Dss,
546            "json" => {
547                let buffer = primary(source)?;
548                classify_distribution_json(source_text(&buffer)?)?
549            }
550            "xml" if crate::cim::looks_like_cim_dist(primary(source)?.content_bytes()) => {
551                DistTargetFormat::CimDist
552            }
553            other => return Err(crate::Error::UnknownFormat(other.to_string())),
554        }
555    };
556    let network = match format {
557        DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras => Err(
558            crate::Error::UnknownFormat("GLM project requires the project parser".into()),
559        ),
560        DistTargetFormat::Dss => {
561            crate::dss::read::parse_dss_collecting(source, warnings, dss_replay, dss_limits)
562        }
563        DistTargetFormat::BmopfJson => {
564            let buffer = primary(source)?;
565            crate::bmopf::read::parse_bmopf_collecting(source_text(&buffer)?, warnings)
566        }
567        DistTargetFormat::PmdJson => {
568            let buffer = primary(source)?;
569            crate::pmd::read::parse_pmd_collecting(source_text(&buffer)?, warnings)
570        }
571        DistTargetFormat::CimDist => crate::cim::parse_cim_collecting(source, warnings),
572        DistTargetFormat::RavensJson => {
573            let buffer = primary(source)?;
574            crate::ravens::read::parse_ravens_collecting(source_text(&buffer)?, warnings)
575        }
576        DistTargetFormat::PmdMathJson => {
577            let buffer = primary(source)?;
578            crate::pmd::math::read::parse_pmd_math_collecting(source_text(&buffer)?, warnings)
579        }
580        DistTargetFormat::PandapowerJson => Err(crate::Error::UnknownFormat(
581            "pandapower JSON is read by powerio_tnd::formats::pandapower or powerio::parse".into(),
582        )),
583    }?;
584    Ok((network, format))
585}
586
587/// The retained primary buffer of a file or in-memory source.
588pub(crate) fn primary(source: &powerio_core::Source) -> crate::Result<powerio_core::SourceBuffer> {
589    source
590        .primary_buffer()
591        .map_err(|error| crate::Error::FormatRead {
592            format: "case text",
593            message: error.to_string(),
594        })
595}
596
597/// The buffer's decode slice as UTF-8 text: the retained bytes with a leading
598/// byte order mark skipped, so the mark survives for the echo and never
599/// reaches a reader.
600pub(crate) fn source_text(buffer: &powerio_core::SourceBuffer) -> crate::Result<&str> {
601    std::str::from_utf8(buffer.content_bytes()).map_err(|e| crate::Error::FormatRead {
602        format: "case text",
603        message: format!("not valid UTF-8: {e}"),
604    })
605}
606
607impl DistTargetFormat {
608    fn matches(self, source: Option<DistSourceFormat>) -> bool {
609        matches!(
610            (self, source),
611            (DistTargetFormat::Dss, Some(DistSourceFormat::Dss))
612                | (
613                    DistTargetFormat::BmopfJson,
614                    Some(DistSourceFormat::BmopfJson)
615                )
616                | (DistTargetFormat::PmdJson, Some(DistSourceFormat::PmdJson))
617                | (
618                    DistTargetFormat::PmdMathJson,
619                    Some(DistSourceFormat::PmdMathJson)
620                )
621                | (DistTargetFormat::CimDist, Some(DistSourceFormat::CimDist))
622                | (
623                    DistTargetFormat::RavensJson,
624                    Some(DistSourceFormat::RavensJson)
625                )
626                | (
627                    DistTargetFormat::PandapowerJson,
628                    Some(DistSourceFormat::PandapowerJson)
629                )
630        )
631    }
632}
633
634/// Whether `name` spells the explicit conductor-resolved SINCAL profile.
635pub(crate) fn is_sincal_multiconductor_token(name: &str) -> bool {
636    name.chars()
637        .filter(|c| !matches!(c, '-' | '_' | ' '))
638        .collect::<String>()
639        .eq_ignore_ascii_case("sincalmulticonductor")
640}
641
642/// The refusal a SINCAL source meets in a build without the `sincal` feature.
643fn sincal_feature_disabled(source: &powerio_core::Source) -> powerio_core::Error {
644    powerio_core::Error::new(
645        &crate::diagnostics::codes::REQUEST_SINCAL_MULTICONDUCTOR_FEATURE_DISABLED,
646        "SINCAL adapters live in powerio-tnd; use powerio with its `sincal` feature or powerio_tnd::formats::sincal",
647    )
648    .with_source(source.clone())
649}
650
651/// Prepare exact retained-source text or validated canonical output.
652pub(crate) fn emit_text_with_options(
653    module: &powerio_core::PioModule<MulticonductorNetwork>,
654    format: DistTargetFormat,
655    options: &EmitOptions,
656) -> Result<TextEmission, powerio_core::Error> {
657    let mut output = if matches!(
658        format,
659        DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras
660    ) {
661        crate::glm::emit_glm_text(module.value())?
662    } else if options.is_default_for(format)
663        && let Some(text) = echo_text(module, format)
664    {
665        TextEmission::faithful(text)
666    } else {
667        crate::readiness::require_resolved_geometry(module.value())?;
668        if format != DistTargetFormat::Dss {
669            crate::readiness::require_earth_referenced_sources(module.value())?;
670        }
671        emit_value_text_with_options(module.value(), format, options)?
672    };
673    powerio_core::attach_retention_details(
674        module.diagnostics(),
675        &mut output.diagnostics,
676        "EMIT.DIST.SINCAL_RETAINED_SOURCE_OMITTED",
677    )?;
678    Ok(output)
679}
680
681/// The retained source text when emitting `module` back to its source format:
682/// the echo that reproduces the input byte for byte. `None` sends the emission
683/// down the semantic path.
684fn echo_text(
685    module: &powerio_core::PioModule<MulticonductorNetwork>,
686    target: DistTargetFormat,
687) -> Option<String> {
688    let source = module.source()?;
689    let buffer = source.primary_buffer().ok()?;
690    // Both the retained source's declared format and the value's own must be
691    // the target: a deserialized module retains the PowerIO IR document, not
692    // the case its value came from.
693    let declared = source
694        .format()
695        .and_then(|format| parse_dist_target_format(format.as_str()))?;
696    if declared != target || !target.matches(*module.value().source_format()) {
697        return None;
698    }
699    let text = std::str::from_utf8(buffer.bytes()).ok()?;
700    // PowerIO writes one BMOPF version: a document stating an earlier one,
701    // or none, is written fresh rather than echoed.
702    if target == DistTargetFormat::BmopfJson && !crate::bmopf::__states_written_version(text) {
703        return None;
704    }
705    Some(text.to_owned())
706}
707
708/// Serialize a typed network to `format` with no source echo.
709pub(crate) fn emit_value_text_with_options(
710    net: &MulticonductorNetwork,
711    format: DistTargetFormat,
712    options: &EmitOptions,
713) -> Result<TextEmission, powerio_core::Error> {
714    net.validate_component_locations()?;
715    let mut conv = match format {
716        DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras => {
717            return crate::glm::emit_glm_text(net);
718        }
719        DistTargetFormat::Dss => crate::dss::emit_validated_dss_text(net, &options.dss)?,
720        DistTargetFormat::BmopfJson => {
721            crate::bmopf::emit_bmopf_json_text_with_options(net, options.bmopf)
722        }
723        DistTargetFormat::PmdJson => crate::pmd::emit_pmd_json_text(net),
724        DistTargetFormat::PmdMathJson => {
725            crate::pmd::math::write::validate_emission(net)?;
726            crate::pmd::math::write::emit_pmd_math_json_text(net, &options.pmd_math)
727        }
728        DistTargetFormat::CimDist => {
729            crate::cim::require_phase_clocks(net)?;
730            crate::cim::emit_cim_dist_text(net)
731        }
732        DistTargetFormat::RavensJson => crate::ravens::emit_ravens_json_text(net)?,
733        DistTargetFormat::PandapowerJson => {
734            return Err(powerio_core::Error::new(
735                &crate::diagnostics::codes::EMIT_PANDAPOWER_UNSUPPORTED,
736                "pandapower JSON output only echoes the retained source of an unchanged module \
737                 read from pandapower JSON. No pandapower writer exists for other networks",
738            ));
739        }
740    };
741    // BMOPF writes component points and line routes as typed `geo` and
742    // reports the ones it cannot write itself.
743    let writes_geometry = format == DistTargetFormat::BmopfJson;
744    if !writes_geometry && !net.component_locations().is_empty() {
745        conv.push(&crate::diagnostics::codes::EMIT_DIST_COMPONENT_COORDINATES_DROPPED,
746            format!("{} component point(s) dropped: {} cannot carry their attachment, partial-axis and datum semantics",
747                net.component_locations().len(), format.name()));
748    }
749    if *net.source_format() == Some(DistSourceFormat::Sincal) {
750        conv.push(
751            &crate::diagnostics::codes::EMIT_SINCAL_MULTICONDUCTOR_RETAINED_SOURCE_OMITTED,
752            "Native SINCAL source-only data are omitted from the typed electrical conversion.",
753        );
754    }
755    // No other distribution format carries line routes; report the loss the
756    // way bus locations already do (`.pio.json` keeps them).
757    let routed = net
758        .lines()
759        .iter()
760        .filter(|line| line.route.is_some())
761        .count();
762    if routed > 0 && !writes_geometry {
763        conv.push(
764            &crate::diagnostics::codes::EMIT_MULTICONDUCTOR_ROUTE_DROPPED,
765            format!(
766                "{routed} line route(s) dropped: {} has no polyline field",
767                format.name()
768            ),
769        );
770    }
771    Ok(conv)
772}
773
774#[cfg(test)]
775pub(crate) fn emit_value_text(
776    net: &MulticonductorNetwork,
777    format: DistTargetFormat,
778) -> TextEmission {
779    emit_value_text_with_options(net, format, &EmitOptions::default())
780        .expect("test network is emittable")
781}
782
783/// Emit a parsed module to `format` through a destination.
784///
785/// The JSON and CIM targets commit a single artifact — a path destination names the
786/// exact file, a memory destination names the artifact. The dss target is a
787/// directory inventory: the destination names the output root, the case text
788/// commits as `case.dss`, and every companion file the emitter produced
789/// (OpenDSS `Buscoords` CSV) commits beside it, so nothing the case text
790/// refers to is missing from the output.
791/// GridLAB-D targets also write directory inventories. Unchanged modules
792/// replay every acquired buffer under its original relative path, preserving
793/// the entrypoint location and includes. Absolute includes cannot be relocated
794/// byte exactly and are refused. Fresh, edited, IR-restored and cross-profile
795/// modules write canonical `case.glm`; [`crate::glm::emit_canonical`] directly
796/// writes a single file from a network value.
797/// An unchanged multi-file DSS project retains the paths and bytes of every
798/// acquired file, dependencies and companions alike, beneath `source/`;
799/// `case.dss` redirects to its entry file. A remark
800/// (`EMIT.DSS.PROJECT_COMPANION_KEPT`) names the companions, the supplied
801/// files the deck never read.
802///
803/// # Errors
804/// Unsupported electrical features, nonportable retained projects, or the
805/// destination's own collision and staging failures.
806///
807/// # Panics
808/// Never on external input: the fixed artifact names are valid by
809/// construction.
810pub fn emit(
811    module: &powerio_core::PioModule<MulticonductorNetwork>,
812    format: DistTargetFormat,
813    destination: powerio_core::Destination,
814) -> std::result::Result<powerio_core::EmitResult, powerio_core::Error> {
815    emit_with_options(module, format, &EmitOptions::default(), destination)
816}
817
818/// [`emit`] with format specific policies.
819///
820/// # Errors
821/// The destination refused the output inventory.
822///
823/// # Panics
824/// Never on external input: the fixed artifact names are valid by
825/// construction.
826pub fn emit_with_options(
827    module: &powerio_core::PioModule<MulticonductorNetwork>,
828    format: DistTargetFormat,
829    options: &EmitOptions,
830    destination: powerio_core::Destination,
831) -> std::result::Result<powerio_core::EmitResult, powerio_core::Error> {
832    if matches!(
833        format,
834        DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras
835    ) && let Some(project) = crate::glm::retained_project(module, format)?
836    {
837        return destination.__commit_artifacts(
838            true,
839            powerio_core::Fidelity::ExactSameFormat,
840            project.artifacts,
841            project.diagnostics,
842        );
843    }
844    let conv = emit_text_with_options(module, format, options)?;
845    if format == DistTargetFormat::Dss
846        && options.is_default_for(format)
847        && let Some(project) = crate::dss::retained_project(module)?
848    {
849        let mut diagnostics = conv.diagnostics;
850        diagnostics.extend(project.diagnostics);
851        return destination.__commit_artifacts(true, conv.fidelity, project.artifacts, diagnostics);
852    }
853    match format {
854        DistTargetFormat::Gridlabd | DistTargetFormat::GridlabdArras => {
855            let artifact = powerio_core::MemoryArtifact::new(
856                powerio_core::ArtifactPath::new("case.glm")?,
857                conv.text.into_bytes(),
858            );
859            destination.__commit_artifacts(true, conv.fidelity, vec![artifact], conv.diagnostics)
860        }
861        DistTargetFormat::Dss => {
862            let mut artifacts = vec![powerio_core::MemoryArtifact::new(
863                powerio_core::ArtifactPath::new("case.dss")
864                    .expect("static name is a valid artifact path"),
865                conv.text.into_bytes(),
866            )];
867            for sidecar in conv.sidecars {
868                artifacts.push(powerio_core::MemoryArtifact::new(
869                    powerio_core::ArtifactPath::new(sidecar.path)?,
870                    sidecar.text.into_bytes(),
871                ));
872            }
873            destination.__commit_artifacts(true, conv.fidelity, artifacts, conv.diagnostics)
874        }
875        DistTargetFormat::BmopfJson
876        | DistTargetFormat::PmdJson
877        | DistTargetFormat::PmdMathJson
878        | DistTargetFormat::CimDist
879        | DistTargetFormat::RavensJson
880        | DistTargetFormat::PandapowerJson => {
881            let artifact = powerio_core::MemoryArtifact::new(
882                powerio_core::ArtifactPath::new("case")
883                    .expect("static name is a valid artifact path"),
884                conv.text.into_bytes(),
885            );
886            destination.__commit_artifacts(false, conv.fidelity, vec![artifact], conv.diagnostics)
887        }
888    }
889}
890
891#[cfg(test)]
892mod tests {
893    use super::*;
894
895    #[test]
896    fn distribution_json_classifier_preserves_pmd_marker_and_bmopf_fallback() {
897        for doc in [
898            r#"{"data_model": "ENGINEERING"}"#,
899            // The marker identifies the family whatever its value is; the
900            // PMD reader is what judges the value.
901            r#"{"data_model": 7}"#,
902            r#"{"data_model": null}"#,
903        ] {
904            assert_eq!(
905                classify_distribution_json(doc).unwrap(),
906                DistTargetFormat::PmdJson,
907                "{doc}"
908            );
909        }
910        // The one value that names the other PMD model routes to its reader.
911        assert_eq!(
912            classify_distribution_json(r#"{"data_model": "MATHEMATICAL"}"#).unwrap(),
913            DistTargetFormat::PmdMathJson
914        );
915        for doc in [
916            r#"{"bus": {}, "voltage_source": {}}"#,
917            // A pre-draft feeder fragment: no `voltage_source`, but the
918            // reader accepts it, so the classifier must too.
919            r#"{"bus": {}, "line": {}, "linecode": {}}"#,
920            r#"{"bus": {}, "transformer": {}}"#,
921            r#"{"bus": {}, "capacitor": {}}"#,
922            r#"{"bus": {}, "generator": {}}"#,
923            // The pre-draft top-level spellings of the tables the first draft moved
924            // under `extras`; the reader dispatches both.
925            r#"{"bus": {}, "ibr": {}}"#,
926            r#"{"bus": {}, "control_profile": {}}"#,
927        ] {
928            assert_eq!(
929                classify_distribution_json(doc).unwrap(),
930                DistTargetFormat::BmopfJson,
931                "{doc}"
932            );
933        }
934        // Malformed JSON still routes to BMOPF so its reader reports the
935        // parse error, which names the byte offset.
936        assert_eq!(
937            classify_distribution_json("{not json").unwrap(),
938            DistTargetFormat::BmopfJson
939        );
940        // A byte order mark must not push a PMD document down the BMOPF
941        // fallback.
942        assert_eq!(
943            classify_distribution_json("\u{feff}{\"data_model\": \"ENGINEERING\"}").unwrap(),
944            DistTargetFormat::PmdJson
945        );
946    }
947
948    #[test]
949    fn pandapower_json_is_an_echo_only_target() {
950        assert_eq!(
951            parse_dist_target_format("pandapower-json"),
952            Some(DistTargetFormat::PandapowerJson)
953        );
954        assert_eq!(DistTargetFormat::PandapowerJson.name(), "pandapower-json");
955        let error = emit_value_text_with_options(
956            &MulticonductorNetwork::named("fresh"),
957            DistTargetFormat::PandapowerJson,
958            &EmitOptions::default(),
959        )
960        .unwrap_err();
961        assert_eq!(
962            error.info().map(|info| info.code),
963            Some("EMIT.DIST.PANDAPOWER_UNSUPPORTED")
964        );
965        // The reader lives in powerio-tnd.
966        let source = powerio_core::Source::from_memory("case.json", b"{}".to_vec())
967            .unwrap()
968            .with_format(powerio_core::FormatId::new("pandapower-json").unwrap());
969        assert!(parse(source).is_err());
970    }
971
972    /// A PowerModels document shares `bus`, `load`, `shunt`, `switch`, and
973    /// `name` with BMOPF, so none of those can be the discriminator. This
974    /// is the exact document family that used to parse into a bogus
975    /// near-empty `MulticonductorNetwork`.
976    #[test]
977    fn a_powermodels_document_never_classifies_as_bmopf() {
978        // The real key set a powerio PowerModels write produces.
979        let powermodels = r#"{"baseMVA": 100.0, "branch": {}, "bus": {}, "dcline": {},
980            "gen": {}, "load": {}, "name": "case14", "per_unit": true, "shunt": {},
981            "source_type": "matpower", "source_version": "2", "storage": {},
982            "switch": {}}"#;
983        assert!(classify_distribution_json(powermodels).is_err());
984
985        // Each PowerModels marker refuses the BMOPF reading on its own, even
986        // beside a real BMOPF table. A future BMOPF revision that adds a
987        // colliding table name therefore cannot make this document classify.
988        for marker in NOT_BMOPF_KEYS {
989            let doc = format!("{{\"bus\": {{}}, \"linecode\": {{}}, \"{marker}\": 1}}");
990            assert!(
991                classify_distribution_json(&doc).is_err(),
992                "`{marker}` must refuse the BMOPF reading: {doc}"
993            );
994        }
995    }
996
997    /// The two rules pull in opposite directions and this classifier has
998    /// swung both ways: dropping the shared table names refuses real BMOPF
999    /// feeders, and keeping them without the veto reads PowerModels as BMOPF.
1000    /// Pin both ends together so neither correction can undo the other.
1001    #[test]
1002    fn shared_table_names_classify_as_bmopf_and_the_veto_still_refuses_powermodels() {
1003        // A BMOPF feeder built only from names PowerModels also uses. No
1004        // veto key is present, so the distribution reading stands.
1005        for doc in [
1006            r#"{"bus": {}, "load": {}}"#,
1007            r#"{"bus": {}, "shunt": {}}"#,
1008            r#"{"bus": {}, "switch": {}}"#,
1009            r#"{"bus": {}, "meta": {"frequency": 60}}"#,
1010        ] {
1011            assert_eq!(
1012                classify_distribution_json(doc).unwrap(),
1013                DistTargetFormat::BmopfJson,
1014                "{doc}"
1015            );
1016        }
1017        // The same shared names beside one veto key stay transmission.
1018        for doc in [
1019            r#"{"bus": {}, "load": {}, "baseMVA": 100.0}"#,
1020            r#"{"bus": {}, "shunt": {}, "branch": {}}"#,
1021            r#"{"bus": {}, "switch": {}, "per_unit": true}"#,
1022        ] {
1023            assert!(classify_distribution_json(doc).is_err(), "{doc}");
1024        }
1025    }
1026
1027    /// PMD ENGINEERING and BMOPF share most element table names, so a real
1028    /// PMD document carries `data_model` beside `line` and `linecode`. The
1029    /// marker must win, or every PMD file would be read as BMOPF.
1030    #[test]
1031    fn the_pmd_marker_wins_over_shared_element_tables() {
1032        let both = r#"{"data_model": "ENGINEERING", "bus": {}, "line": {}, "linecode": {}}"#;
1033        assert_eq!(
1034            classify_distribution_json(both).unwrap(),
1035            DistTargetFormat::PmdJson
1036        );
1037    }
1038
1039    #[test]
1040    fn unclassifiable_documents_are_refused_with_a_reason() {
1041        for (doc, needle) in [
1042            (
1043                r#"{"bus": {"data_model": {}}}"#,
1044                "no distribution element table",
1045            ),
1046            (r#"{"name": "data_model"}"#, "no marker of either format"),
1047            ("{}", "no marker of either format"),
1048            ("[]", "not an object"),
1049            ("null", "not an object"),
1050            ("3", "not an object"),
1051            (r#""a string""#, "not an object"),
1052            ("true", "not an object"),
1053        ] {
1054            let err = classify_distribution_json(doc).unwrap_err().to_string();
1055            assert!(err.contains(needle), "{doc}: got {err}");
1056        }
1057    }
1058
1059    /// The probe reads top level keys and skips values, so neither the size
1060    /// of a value nor the number of keys can make it allocate the document.
1061    /// A deeply nested value hits serde_json's own recursion limit, which
1062    /// surfaces as the malformed-JSON route rather than a stack overflow.
1063    #[test]
1064    fn the_probe_is_bounded_on_adversarial_shapes() {
1065        // A huge value under an ignored key: skipped, not materialized.
1066        let big = format!(
1067            r#"{{"bus": {{}}, "linecode": {{}}, "junk": [{}]}}"#,
1068            "0,".repeat(200_000) + "0"
1069        );
1070        assert_eq!(
1071            classify_distribution_json(&big).unwrap(),
1072            DistTargetFormat::BmopfJson
1073        );
1074
1075        // Many distinct top level keys: one flag per key, nothing stored.
1076        let mut keys = String::new();
1077        for i in 0..50_000 {
1078            use std::fmt::Write as _;
1079            let _ = write!(keys, "\"k{i}\":0,");
1080        }
1081        let many = format!(r#"{{{keys}"bus":{{}},"linecode":{{}}}}"#);
1082        assert_eq!(
1083            classify_distribution_json(&many).unwrap(),
1084            DistTargetFormat::BmopfJson
1085        );
1086
1087        // Deep nesting under an ignored key: `IgnoredAny` skips a value
1088        // without recursion, so depth costs no stack. The old classifier
1089        // built a `serde_json::Value`, whose recursive descent refuses past
1090        // 128 levels, so a legitimate document nested deeper than that used
1091        // to take the malformed route.
1092        let deep = format!(
1093            r#"{{"bus":{{}},"linecode":{{}},"junk":{}{}}}"#,
1094            "[".repeat(20_000),
1095            "]".repeat(20_000)
1096        );
1097        assert_eq!(
1098            classify_distribution_json(&deep).unwrap(),
1099            DistTargetFormat::BmopfJson
1100        );
1101
1102        // A duplicate marker key is still one marker.
1103        assert_eq!(
1104            classify_distribution_json(
1105                r#"{"data_model":"ENGINEERING","data_model":"ENGINEERING"}"#
1106            )
1107            .unwrap(),
1108            DistTargetFormat::PmdJson
1109        );
1110    }
1111
1112    /// The probe skips a value without recursion, so it accepts a document
1113    /// nested far deeper than the reader will take. The reader must then
1114    /// refuse that document with an error, never with a crash: the
1115    /// classifier is what decides which reader sees untrusted input.
1116    #[test]
1117    fn a_document_the_probe_accepts_is_refused_by_the_reader_not_a_crash() {
1118        for depth in [200usize, 20_000, 500_000] {
1119            let doc = format!(
1120                "{{\"bus\":{{}},\"linecode\":{{}},\"junk\":{}{}}}",
1121                "[".repeat(depth),
1122                "]".repeat(depth)
1123            );
1124            let format = classify_distribution_json(&doc).expect("markers are present");
1125            assert_eq!(format, DistTargetFormat::BmopfJson);
1126            let err = crate::testkit::parse_str(&doc, format.name())
1127                .expect_err("the reader refuses past its recursion limit");
1128            assert!(
1129                err.to_string().contains("recursion limit"),
1130                "depth {depth}: {err}"
1131            );
1132        }
1133    }
1134
1135    /// JSON keys are case sensitive and both formats are machine written,
1136    /// so a near miss must not classify. It would pick a reader that then
1137    /// fails on every table.
1138    #[test]
1139    fn marker_matching_is_case_sensitive() {
1140        for doc in [
1141            r#"{"Data_Model": "ENGINEERING"}"#,
1142            r#"{"DATA_MODEL": "ENGINEERING"}"#,
1143            r#"{"Bus": {}, "Linecode": {}}"#,
1144        ] {
1145            assert!(classify_distribution_json(doc).is_err(), "{doc}");
1146        }
1147    }
1148
1149    #[test]
1150    fn byte_order_mark_is_retained_and_echoed() {
1151        let dss = "\u{feff}clear\nnew circuit.c basekv=12.47 bus1=src\n";
1152        let net = crate::testkit::parse_dss_str(dss);
1153        assert_eq!(net.name().as_deref(), Some("c"));
1154        assert!(
1155            !net.warnings.iter().any(|w| w.contains("byte order mark")),
1156            "retaining the mark is not a loss: {:?}",
1157            net.warnings
1158        );
1159        // The echo returns the input bytes exactly, mark included; the
1160        // decode slice the reader saw was mark free.
1161        assert_eq!(net.emit(DistTargetFormat::Dss).text, dss);
1162        assert!(
1163            net.source
1164                .as_ref()
1165                .is_some_and(|s| !s.starts_with('\u{feff}'))
1166        );
1167    }
1168
1169    #[test]
1170    fn memory_and_file_sources_parse_the_same_fixture_alike() {
1171        let path = concat!(
1172            env!("CARGO_MANIFEST_DIR"),
1173            "/../tests/data/dist/micro/onephase_zip_load.dss"
1174        );
1175        let bytes = std::fs::read(path).unwrap();
1176        let from_bytes =
1177            crate::testkit::parse_str(std::str::from_utf8(&bytes).unwrap(), "dss").unwrap();
1178        let from_file = crate::testkit::parse_file(path, None).unwrap();
1179        assert_eq!(from_bytes.buses().len(), from_file.buses().len());
1180        assert_eq!(from_bytes.loads().len(), from_file.loads().len());
1181        assert_eq!(from_bytes.source, from_file.source);
1182    }
1183
1184    #[test]
1185    fn non_utf8_bytes_are_refused_and_name_the_encoding() {
1186        // 0xE9 is CP1252 é, the classic single byte a Windows editor leaves.
1187        let bytes: &[u8] = b"clear\nnew circuit.caf\xE9 basekv=12.47 bus1=src\n";
1188        let source = powerio_core::Source::from_memory("<memory>", bytes.to_vec())
1189            .unwrap()
1190            .with_format(powerio_core::FormatId::new("dss").unwrap());
1191        let err = parse(source).unwrap_err();
1192        assert!(err.to_string().contains("UTF-8"), "{err}");
1193    }
1194
1195    #[test]
1196    fn parse_rejects_unclassifiable_json() {
1197        // A PowerModels document used to fall through to the BMOPF reader
1198        // and parse into a bogus near-empty network.
1199        let dir = tempfile::tempdir().unwrap();
1200        let path = dir.path().join("case.json");
1201        std::fs::write(
1202            &path,
1203            r#"{"bus": {}, "branch": {}, "gen": {}, "baseMVA": 100.0}"#,
1204        )
1205        .unwrap();
1206        let err = crate::testkit::parse_file(&path, None).unwrap_err();
1207        assert!(
1208            err.to_string()
1209                .contains("not a recognized distribution document"),
1210            "{err}"
1211        );
1212        // An explicit format still overrides the classifier.
1213        assert!(crate::testkit::parse_file(&path, Some("bmopf-json")).is_ok());
1214    }
1215
1216    #[test]
1217    fn unknown_format_names_fail_before_any_work() {
1218        assert!(matches!(
1219            crate::testkit::parse_str("", "matpower"),
1220            Err(crate::Error::UnknownFormat(_))
1221        ));
1222        assert!(matches!(
1223            "matpower".parse::<DistTargetFormat>(),
1224            Err(crate::Error::UnknownFormat(_))
1225        ));
1226        assert!(matches!(
1227            crate::testkit::parse_file("missing.dss", Some("matpower")),
1228            Err(crate::Error::UnknownFormat(_))
1229        ));
1230    }
1231
1232    #[test]
1233    fn parse_diagnostics_remain_on_the_module_when_it_is_emitted() {
1234        let dss = "clear\nnew circuit.w basekv=12.47 bus1=src\n\
1235                   new line.l1 bus1=src bus2=b2 length=1 units=furlong\n";
1236        let source = powerio_core::Source::from_memory("<memory>", dss.as_bytes().to_vec())
1237            .unwrap()
1238            .with_format(powerio_core::FormatId::new("dss").unwrap());
1239        let module = parse(source).unwrap();
1240        let lines = crate::diagnostics::render_diagnostics(module.diagnostics());
1241        assert!(
1242            lines.iter().any(|w| w.contains("furlong")),
1243            "parse diagnostics stay on PioModule: {lines:?}"
1244        );
1245        emit(
1246            &module,
1247            DistTargetFormat::BmopfJson,
1248            powerio_core::Destination::memory("case.json").unwrap(),
1249        )
1250        .unwrap();
1251    }
1252
1253    #[test]
1254    fn canonical_format_bypasses_same_format_dss_echo() {
1255        let src = "Clear\n\
1256                   New Circuit.c basekv=12.47 bus1=sourcebus\n\
1257                   New Load.l1 bus1=sourcebus.1 phases=1 conn=wye kv=7.2 kw=10 kvar=2\n";
1258        let net = crate::testkit::parse_dss_str(src);
1259        assert_eq!(net.emit(DistTargetFormat::Dss).text, src);
1260
1261        let canonical = net.emit_value(DistTargetFormat::Dss);
1262        assert_ne!(canonical.text, src);
1263        assert!(
1264            canonical
1265                .text
1266                .lines()
1267                .any(|l| l.contains("Load.l1") && l.contains("vminpu=0")),
1268            "{}",
1269            canonical.text
1270        );
1271    }
1272}