Skip to main content

powerio_dist/
diagnostics.rs

1//! The codes this crate emits.
2//!
3//! The record itself lives in `powerio-core`, below this crate and below the
4//! `.pio.json` document model, so a distribution finding reaches a package
5//! without a translation step. What lives here is the distribution side
6//! registry: one [`DiagnosticInfo`] per code, declared once, so an emission
7//! site names an entry rather than a loose string.
8//!
9//! Codes are families, not one per site: what differs between two sites of a
10//! family is which object or property it was, which belongs in `details`.
11
12// The collector is crate-private implementation support, not API: each
13// emitting crate carries its own copy (src/collect.rs) and never exports it.
14pub(crate) use crate::collect::Diagnostics;
15
16pub use powerio_core::{
17    Diagnostic, DiagnosticCode, DiagnosticInfo, DiagnosticSeverity, DiagnosticStage,
18    check_registry, render_diagnostic, render_diagnostics,
19};
20
21pub mod codes {
22    powerio_core::diagnostic_codes! {
23        PARSE_SINCAL_MULTICONDUCTOR = "PARSE.DIST.SINCAL", Error,
24            "the selected conductor-resolved SINCAL profile cannot be parsed", category = Parse;
25        REQUEST_SINCAL_MULTICONDUCTOR_FEATURE_DISABLED = "REQUEST.DIST_FORMAT.SINCAL_FEATURE_DISABLED", Error,
26            "conductor-resolved SINCAL is not available through this build or entry point", category = Request;
27        READ_SINCAL_MULTICONDUCTOR_RETAINED_SOURCE_ONLY = "READ.DIST.SINCAL_RETAINED_SOURCE_ONLY", Remark,
28            "native data outside the selected conductor-resolved profile remain only in source";
29        READ_SINCAL_GEOMETRY = "READ.DIST.SINCAL_GEOMETRY", Warning,
30            "optional SINCAL drawing geometry retains native view metadata and reports mapping limits";
31        READ_SINCAL_UNCONNECTED_NODES = "READ.DIST.SINCAL_UNCONNECTED_NODES", Remark,
32            "native nodes with no declared conductors remain in network extras";
33        READ_SINCAL_ASSUMED_INACTIVE_SOURCE_CONTROLS = "READ.DIST.SINCAL_ASSUMED_INACTIVE_SOURCE_CONTROLS", Warning,
34            "legacy NULL source controls were explicitly assumed inactive";
35        EMIT_SINCAL_MULTICONDUCTOR_RETAINED_SOURCE_OMITTED = "EMIT.DIST.SINCAL_RETAINED_SOURCE_OMITTED", Warning,
36            "native SINCAL source-only data are omitted from cross-format emission";
37        EMIT_SINCAL_MULTICONDUCTOR_UNSUPPORTED = "EMIT.DIST.SINCAL_UNSUPPORTED", Error,
38            "invalid or unsupported candidate multiconductor SINCAL output", category = Output;
39        EMIT_SINCAL_MULTICONDUCTOR_EXPERIMENTAL = "EMIT.DIST.SINCAL_EXPERIMENTAL", Remark,
40            "candidate multiconductor output has no native SINCAL acceptance evidence";
41        EMIT_SINCAL_MULTICONDUCTOR_LOSS = "EMIT.DIST.SINCAL_LOSS", Warning,
42            "candidate multiconductor output canonicalizes topology or omits ancillary data";
43        // The pandapower three-phase (runpp_3ph) reader in powerio-tnd.
44        READ_PANDAPOWER_TABLE_UNSUPPORTED = "READ.DIST.PANDAPOWER_TABLE_UNSUPPORTED", Warning,
45            "a pandapower element table has no three-phase mapping and remains only in source";
46        READ_PANDAPOWER_ELEMENT_UNSUPPORTED = "READ.DIST.PANDAPOWER_ELEMENT_UNSUPPORTED", Warning,
47            "a pandapower element row has no three-phase mapping and remains only in source";
48        READ_PANDAPOWER_APPROXIMATED = "READ.DIST.PANDAPOWER_APPROXIMATED", Warning,
49            "a mapped pandapower element differs from the runpp_3ph model";
50        READ_PANDAPOWER_OUT_OF_SERVICE = "READ.DIST.PANDAPOWER_OUT_OF_SERVICE", Warning,
51            "an out-of-service pandapower element is kept with its status in extras";
52        READ_PANDAPOWER_RETAINED_SOURCE_ONLY = "READ.DIST.PANDAPOWER_RETAINED_SOURCE_ONLY", Remark,
53            "pandapower data runpp_3ph does not use remain in extras or the retained source";
54        EMIT_PANDAPOWER_UNSUPPORTED = "EMIT.DIST.PANDAPOWER_UNSUPPORTED", Error,
55            "pandapower JSON output exists only as the echo of an unchanged pandapower source",
56            category = Output;
57        // PARSE: the source text could not be decoded as given.
58        PARSE_DSS_SOURCE_MALFORMED = "PARSE.DSS.SOURCE_MALFORMED", Warning,
59            "a dss command, object spec, or property assignment does not parse";
60        PARSE_DIST_MALFORMED = "PARSE.DIST.MALFORMED", Error,
61            "a distribution document is not valid JSON for its format", category = Parse;
62        PARSE_DIST_SOURCE_MALFORMED = "PARSE.DIST.SOURCE_MALFORMED", Error,
63            "a distribution reader refused the source it was given", category = Parse;
64        PARSE_GLM_SYNTAX = "PARSE.GLM.SYNTAX", Error,
65            "a GLM source contains invalid or incomplete syntax", category = Parse;
66        PARSE_GLM_LIMIT_EXCEEDED = "PARSE.GLM.LIMIT_EXCEEDED", Error,
67            "a GLM source exceeds the bounded parser resources", category = Parse;
68        PARSE_GLM_PREPROCESSING = "PARSE.GLM.PREPROCESSING", Error,
69            "a GLM preprocessing operation is invalid or requires unsupported external semantics", category = Parse;
70        PARSE_GLM_OBJECT = "PARSE.GLM.OBJECT", Error,
71            "a GLM object identity, declaration or reference cannot be resolved", category = Parse;
72        PARSE_GLM_QUANTITY = "PARSE.GLM.QUANTITY", Error,
73            "a GLM quantity or unit cannot be interpreted in the static profile", category = Parse;
74        READ_GLM_UNIT_IGNORED = "READ.GLM.UNIT_IGNORED", Warning,
75            "native quantity conversion ignores a stated unit suffix";
76        READ_GLM_ELECTRICAL_UNSUPPORTED = "READ.GLM.ELECTRICAL_UNSUPPORTED", Error,
77            "a GLM electrical feature has no verified static mapping", category = Data;
78        READ_GLM_IMPLICIT_SOURCE = "READ.GLM.IMPLICIT_SOURCE", Remark,
79            "a connected directed FBS tree has one implicit upstream voltage source";
80        READ_GLM_SOURCE_ONLY = "READ.GLM.SOURCE_ONLY", Remark,
81            "non-electrical GLM data remains in the retained source";
82        READ_GLM_SWITCH_STATE_NORMALIZED = "READ.GLM.SWITCH_STATE_NORMALIZED", Remark,
83            "static switch status and banked initialization determine contact states";
84        READ_GLM_SWITCH_EQUIVALENT = "READ.GLM.SWITCH_EQUIVALENT", Remark,
85            "finite closed switch contacts use an exact static line equivalent";
86        READ_GLM_REDUCED_TRIPLEX = "READ.GLM.REDUCED_TRIPLEX", Warning,
87            "a direct triplex matrix does not specify physical neutral or ground current";
88        READ_GLM_LOAD_NORMALIZED = "READ.GLM.LOAD_NORMALIZED", Remark,
89            "native ZIP initialization defines the typed load voltage-law terms";
90        READ_GLM_BATTERY_IDLE = "READ.GLM.BATTERY_IDLE", Remark,
91            "Internal battery has zero fixed injection in constant-PF mode; energy and inactive control metadata remain in source";
92        READ_GLM_SOLAR_EQUIVALENT = "READ.GLM.SOLAR_EQUIVALENT", Remark,
93            "a static solar and inverter snapshot uses fixed typed inverter injections";
94        READ_GLM_REACTOR_EQUIVALENT = "READ.GLM.REACTOR_EQUIVALENT", Remark,
95            "a static reactor uses an exact line or ideal-contact equivalent";
96        READ_GLM_SUBSTATION_EQUIVALENT = "READ.GLM.SUBSTATION_EQUIVALENT", Remark,
97            "a standalone substation supplies initialized sequence-derived phase voltages";
98        READ_GLM_GENERATOR_EQUIVALENT = "READ.GLM.GENERATOR_EQUIVALENT", Remark,
99            "initialized static generator powers and ratings use phase-resolved records";
100        READ_GLM_REGULATOR_EQUIVALENT = "READ.GLM.REGULATOR_EQUIVALENT", Remark,
101            "fixed regulator phases use equivalent winding records on explicit normalization bases";
102        READ_GLM_TRANSFORMER_EQUIVALENT = "READ.GLM.TRANSFORMER_EQUIVALENT", Warning,
103            "native NR delta-delta transformer equations use an equivalent grounded-wye circuit";
104        READ_GLM_CONTROL_FROZEN = "READ.GLM.CONTROL_FROZEN", Warning,
105            "active control behavior is omitted while declared fixed electrical states are preserved";
106        READ_GLM_LINE_EQUIVALENT = "READ.GLM.LINE_EQUIVALENT", Remark,
107            "native FBS noncommuting line equations use an exact admittance equivalent";
108        READ_GLM_NATIVE_LINE_DISCREPANCY = "READ.GLM.NATIVE_LINE_DISCREPANCY", Warning,
109            "native line reporting and FBS solved states can differ from the physical pi-line model for noncommuting matrices";
110        READ_GLM_GEOMETRY_MATERIALIZED = "READ.GLM.GEOMETRY_MATERIALIZED", Remark,
111            "overhead conductor geometry is materialized as phase matrices with explicit reduction provenance";
112        EMIT_GLM_UNSUPPORTED = "EMIT.GLM.UNSUPPORTED", Error,
113            "the GLM writer cannot yet represent this electrical feature", category = Data;
114        EMIT_GLM_FIELD_DROPPED = "EMIT.GLM.FIELD_DROPPED", Warning,
115            "non-electrical metadata has no expression in canonical GLM output";
116        EMIT_GLM_VALUE_REBASED = "EMIT.GLM.VALUE_REBASED", Remark,
117            "a GLM nominal voltage or identity was materialized without changing electrical behavior";
118        EMIT_GLM_IDEAL_CONTACTS = "EMIT.GLM.IDEAL_CONTACTS", Remark,
119            "ideal contacts use source-oriented FBS with exact zero impedance and explicit phase grouping";
120        EMIT_GLM_TRANSFORMER_SHUNT_EQUIVALENT = "EMIT.GLM.TRANSFORMER_SHUNT_EQUIVALENT", Remark,
121            "a transformer terminal core shunt uses an exact admittance load";
122        EMIT_GLM_LINE_SHUNT_EQUIVALENT = "EMIT.GLM.LINE_SHUNT_EQUIVALENT", Remark,
123            "line end shunts use exact phase-pair and earth-return admittance loads";
124        EMIT_GLM_PROJECT_UNREPRESENTABLE = "EMIT.GLM.PROJECT_UNREPRESENTABLE", Error,
125            "retained GLM project bytes cannot be replayed as a portable output inventory", category = Output;
126        EMIT_GLM_REPLAY_CONTEXT_REQUIRED = "EMIT.GLM.REPLAY_CONTEXT_REQUIRED", Remark,
127            "exact GLM project replay requires the original explicit preprocessing inputs";
128        VALIDATE_DIST_COORDINATES_INVALID = "VALIDATE.DIST.COORDINATES_INVALID", Error,
129            "component geographic coordinates or their attachment identities are invalid", category = Data;
130        EMIT_DIST_COMPONENT_COORDINATES_DROPPED = "EMIT.DIST.COMPONENT_COORDINATES_DROPPED", Warning,
131            "the target cannot carry typed component geographic coordinates";
132
133        // READ.DSS: decoded, but not representable in the multiconductor model.
134        /// A `Redirect`/`Compile`/`Buscoords` include the reader refused
135        /// because it escapes the case directory, or the include root when
136        /// the caller widened one. Severity `Error`: the parse continued,
137        /// but the network is incomplete.
138        READ_DSS_INCLUDE_REFUSED = "READ.DSS.INCLUDE_REFUSED", Error,
139            "an include escaping the case directory or the configured include root was refused";
140        /// The reader stopped following includes because the case exceeded the
141        /// include budget. Severity `Error` for the same reason.
142        READ_DSS_INCLUDE_BUDGET = "READ.DSS.INCLUDE_BUDGET", Error,
143            "the reader stopped following includes at the case's include budget";
144        READ_DSS_VALUE_CLAMPED = "READ.DSS.VALUE_CLAMPED", Warning,
145            "a count or dimension beyond the supported maximum was clamped";
146        READ_DSS_VALUE_DEFAULTED = "READ.DSS.VALUE_DEFAULTED", Warning,
147            "a value the model needs was absent or unusable and was defaulted";
148        READ_DSS_VALUE_UNSUPPORTED = "READ.DSS.VALUE_UNSUPPORTED", Warning,
149            "a property value outside the modeled set was read as the nearest one";
150        READ_DSS_CONTROL_NOT_EXECUTED = "READ.DSS.CONTROL_NOT_EXECUTED", Warning,
151            "a control is retained without running it; equipment keeps its written settings";
152        READ_DSS_OBJECT_UNTYPED = "READ.DSS.OBJECT_UNTYPED", Warning,
153            "an object shape the model does not type yet is kept untyped";
154        /// `New` named a general object (a linecode, a loadshape, wire data
155        /// and the like) that already exists. OpenDSS edits the existing
156        /// object without a message, and so does the reader. Severity
157        /// `Remark`: the script is valid and nothing was lost.
158        READ_DSS_OBJECT_REDEFINED = "READ.DSS.OBJECT_REDEFINED", Remark,
159            "a second `New` for an existing general object edited it, as OpenDSS does";
160        READ_DSS_SOURCE_DISABLED = "READ.DSS.SOURCE_DISABLED", Remark,
161            "a disabled source is retained without electrical contributions";
162        EMIT_DSS_PROJECT_UNREPRESENTABLE = "EMIT.DSS.PROJECT_UNREPRESENTABLE", Error,
163            "retained DSS dependencies cannot be replayed as a portable project", category = Output;
164        EMIT_DSS_PROJECT_COMPANION_KEPT = "EMIT.DSS.PROJECT_COMPANION_KEPT", Remark,
165            "a supplied file the deck never read was copied into the retained project";
166        READ_DSS_LOADSHAPE_UNRESOLVED = "READ.DSS.LOADSHAPE_UNRESOLVED", Error,
167            "static UseActual loadshape power could not be resolved";
168        READ_DSS_SOURCE_UNRESOLVED = "READ.DSS.SOURCE_UNRESOLVED", Error,
169            "a voltage source is invalid or outside the qualified static profile", category = Data;
170        READ_DSS_FAULT_UNRESOLVED = "READ.DSS.FAULT_UNRESOLVED", Error,
171            "a fault switching state could not be resolved into the static electrical snapshot", category = Data;
172        READ_DSS_TRANSFORMER_UNRESOLVED = "READ.DSS.TRANSFORMER_UNRESOLVED", Error,
173            "a transformer definition could not be resolved into the static electrical snapshot";
174        READ_DSS_LINE_UNRESOLVED = "READ.DSS.LINE_UNRESOLVED", Error,
175            "a line is invalid or outside the qualified static electrical profile", category = Data;
176        READ_DSS_BATCH_UNRESOLVED = "READ.DSS.BATCH_UNRESOLVED", Error,
177            "a BatchEdit selector could not be executed faithfully", category = Data;
178        READ_DSS_PROPERTY_UNKNOWN = "READ.DSS.PROPERTY_UNKNOWN", Warning,
179            "a property this reader does not model is kept as written";
180        READ_DSS_REFERENCE_DROPPED = "READ.DSS.REFERENCE_DROPPED", Warning,
181            "a control or element reference names an object the case does not declare";
182        READ_DSS_RETAINED_SOURCE_ONLY = "READ.DSS.RETAINED_SOURCE_ONLY", Warning,
183            "a field survives in extras or the retained source rather than in a typed field";
184        READ_DSS_COORDINATE_SPACE_UNKNOWN = "READ.DSS.COORDINATE_SPACE_UNKNOWN", Remark,
185            "buscoords declare no coordinate reference system";
186        READ_DSS_INCLUDE_LOAD_FAILED = "READ.DSS.INCLUDE_LOAD_FAILED", Warning,
187            "an include the case names could not be loaded";
188        READ_DSS_INCLUDE_DEPTH_LIMIT = "READ.DSS.INCLUDE_DEPTH_LIMIT", Warning,
189            "the reader stopped following includes at the nesting depth limit";
190        READ_DSS_GEOMETRY_UNRESOLVED = "READ.DSS.GEOMETRY_UNRESOLVED", Error,
191            "line geometry remains source data without calculated conductor impedances";
192        BUILD_DIST_ELECTRICAL_INCOMPLETE = "BUILD.DIST.ELECTRICAL_INCOMPLETE", Error,
193            "distribution equipment lacks the electrical data required for numerical use", category = Data;
194        BUILD_DIST_TRANSFORMER_INVALID = "BUILD.DIST.TRANSFORMER_INVALID", Error,
195            "a transformer's nameplate, tap, terminal map, neutral or magnetizing data is not usable", category = Data;
196        BUILD_DIST_TRANSFORMER_UNSUPPORTED = "BUILD.DIST.TRANSFORMER_UNSUPPORTED", Error,
197            "a transformer's shape or stated property has no supported winding equations", category = Data;
198        TRANSFORM_DIST_LINDIST3FLOW_PREPARATION_FAILED =
199            "TRANSFORM.DIST.LINDIST3FLOW_PREPARATION_FAILED", Error,
200            "a distribution component cannot be prepared for LinDist3Flow", category = Data;
201        READ_DSS_LINECODE_UNKNOWN = "READ.DSS.LINECODE_UNKNOWN", Warning,
202            "a line names a linecode the case does not declare";
203
204        // EMIT.DSS: what the canonical dss writer cannot state.
205        EMIT_DSS_IDEAL_SWITCH_EQUIVALENT = "EMIT.DSS.IDEAL_SWITCH_EQUIVALENT", Remark,
206            "an ideal closed switch is emitted using exact impedance cancellation";
207        EMIT_DSS_IDEAL_TRANSFORMER_EQUIVALENT = "EMIT.DSS.IDEAL_TRANSFORMER_EQUIVALENT", Remark,
208            "an ideal transformer is emitted using exact leakage cancellation";
209        EMIT_DSS_SOURCE_EQUIVALENT = "EMIT.DSS.SOURCE_EQUIVALENT", Remark,
210            "an ideal source is emitted as an exact finite-impedance circuit equivalent";
211        EMIT_DSS_IMPEDANCE_EQUIVALENT = "EMIT.DSS.IMPEDANCE_EQUIVALENT", Remark,
212            "a conductor impedance is emitted as an exact zero-EMF source equivalent";
213        EMIT_DSS_FIELD_DROPPED = "EMIT.DSS.FIELD_DROPPED", Warning,
214            "a field the dss object model has no property for was dropped";
215        EMIT_DSS_RECORD_DROPPED = "EMIT.DSS.RECORD_DROPPED", Warning,
216            "an element the dss writer does not emit was dropped";
217        EMIT_DSS_VALUE_COLLAPSED = "EMIT.DSS.VALUE_COLLAPSED", Warning,
218            "structure was reduced to what one dss property can carry";
219        EMIT_DSS_VALUE_DEFAULTED = "EMIT.DSS.VALUE_DEFAULTED", Warning,
220            "a value the dss engine requires was synthesized";
221        EMIT_DSS_VALUE_SUBSTITUTED = "EMIT.DSS.VALUE_SUBSTITUTED", Warning,
222            "a stated value was replaced by one the dss engine reads back the same way";
223        EMIT_DSS_EXTRAS_DROPPED = "EMIT.DSS.EXTRAS_DROPPED", Warning,
224            "a passthrough extra the canonical dss writer does not regenerate was dropped";
225        /// OpenDSS reads a node list positionally, with a grounded return
226        /// conductor last. A uniquely grounded return in any other position
227        /// makes the emitted element address different conductors.
228        EMIT_DSS_TERMINAL_ORDER_UNREPRESENTABLE = "EMIT.DSS.TERMINAL_ORDER_UNREPRESENTABLE", Error,
229            "a grounded return conductor is not last in a positional dss node list";
230
231        // READ.PMD.
232        READ_PMD_VALUE_CLAMPED = "READ.PMD.VALUE_CLAMPED", Warning,
233            "a PMD dimension beyond the supported maximum was clamped";
234        READ_PMD_VALUE_COLLAPSED = "READ.PMD.VALUE_COLLAPSED", Warning,
235            "a per terminal or per phase PMD value was collapsed to one entry";
236        READ_PMD_VALUE_DEFAULTED = "READ.PMD.VALUE_DEFAULTED", Warning,
237            "a PMD value the model needs was absent or unusable and was defaulted";
238        READ_PMD_RETAINED_SOURCE_ONLY = "READ.PMD.RETAINED_SOURCE_ONLY", Warning,
239            "a PMD field survives in extras rather than in a typed field";
240        READ_PMD_SOURCE_MALFORMED = "READ.PMD.SOURCE_MALFORMED", Warning,
241            "a PMD value is not the shape its key declares";
242        READ_PMD_RECORD_DROPPED = "READ.PMD.RECORD_DROPPED", Warning,
243            "a PMD object beyond the modeled set was dropped";
244        READ_PMD_VALUE_INLINED = "READ.PMD.VALUE_INLINED", Remark,
245            "an inline PMD impedance was materialized as a named linecode";
246
247        // EMIT.PMD.
248        EMIT_PMD_FIELD_DROPPED = "EMIT.PMD.FIELD_DROPPED", Warning,
249            "a field the PMD schema has no key for was dropped";
250        EMIT_PMD_RECORD_DROPPED = "EMIT.PMD.RECORD_DROPPED", Warning,
251            "an element the ENGINEERING document does not model was dropped";
252        EMIT_PMD_VALUE_CLAMPED = "EMIT.PMD.VALUE_CLAMPED", Warning,
253            "a conductor count beyond the supported maximum was clamped";
254        EMIT_PMD_VALUE_DEFAULTED = "EMIT.PMD.VALUE_DEFAULTED", Warning,
255            "a value the ENGINEERING schema requires was synthesized";
256        EMIT_PMD_VALUE_SUBSTITUTED = "EMIT.PMD.VALUE_SUBSTITUTED", Warning,
257            "a stated value was replaced by one the PMD schema can hold";
258
259        // READ.BMOPF.
260        /// A BMOPF field the schema types as a number holds something else.
261        /// Severity `Error`: the field reads as `NaN`, which serializes on as
262        /// an unbounded limit, so the parse states a fact the source never gave.
263        READ_BMOPF_FIELD_NOT_A_NUMBER = "READ.BMOPF.FIELD_NOT_A_NUMBER", Error,
264            "a BMOPF field the schema types as a number holds something else";
265        READ_BMOPF_FIELD_DROPPED = "READ.BMOPF.FIELD_DROPPED", Warning,
266            "a BMOPF field with no canonical home was dropped";
267        READ_BMOPF_RECORD_DROPPED = "READ.BMOPF.RECORD_DROPPED", Warning,
268            "a BMOPF object or winding beyond the modeled set was dropped";
269        READ_BMOPF_CAPACITOR_LOWERED = "READ.BMOPF.CAPACITOR_LOWERED", Remark,
270            "a per-coil capacitor was represented exactly by a terminal shunt";
271        READ_BMOPF_VALUE_COLLAPSED = "READ.BMOPF.VALUE_COLLAPSED", Warning,
272            "a per phase or per terminal BMOPF value was collapsed to one entry";
273        READ_BMOPF_TRANSFORMER_OPEN_DELTA_SPLIT = "READ.BMOPF.TRANSFORMER_OPEN_DELTA_SPLIT", Warning,
274            "one open_delta_regulator object reads as its two regulating legs, the second under a synthesized name";
275        READ_BMOPF_VALUE_DEFAULTED = "READ.BMOPF.VALUE_DEFAULTED", Warning,
276            "a BMOPF value the model needs was absent or unusable and was defaulted";
277        READ_BMOPF_VALUE_UNSUPPORTED = "READ.BMOPF.VALUE_UNSUPPORTED", Warning,
278            "a BMOPF enumeration value outside the schema was read as the nearest one";
279        READ_BMOPF_VALUE_INFERRED = "READ.BMOPF.VALUE_INFERRED", Warning,
280            "a BMOPF structure the schema does not name was reconstructed";
281        READ_BMOPF_RETAINED_SOURCE_ONLY = "READ.BMOPF.RETAINED_SOURCE_ONLY", Warning,
282            "a BMOPF field outside the schema survives in extras or untyped";
283        READ_BMOPF_SOURCE_MALFORMED = "READ.BMOPF.SOURCE_MALFORMED", Warning,
284            "a BMOPF value is not the shape its key declares";
285        /// The document is an older BMOPF draft and was read as BMOPF, the one
286        /// schema PowerIO writes. Reported once per document: when it names
287        /// an older draft (including the `bmopf-report` drafts and the early
288        /// draft PowerIO 0.11 wrote), and when a document stating the current
289        /// schema uses an earlier spelling: `meta.$schema`, the bus bounds
290        /// `v_min`/`v_max`/`vn_max`, the regulators' `tap_ratio`, `cost` on a
291        /// source or inverter, `DSTATCOM`, `VA_FRACTION`, or a lowercase enum
292        /// value.
293        READ_BMOPF_SCHEMA_LEGACY = "READ.BMOPF.SCHEMA_LEGACY", Warning,
294            "an older BMOPF draft was read as BMOPF";
295        /// The document states neither `meta.schema_version` nor an earlier
296        /// `meta.$schema`, so the release it was written against is unknown;
297        /// it is read as BMOPF.
298        READ_BMOPF_SCHEMA_ABSENT = "READ.BMOPF.SCHEMA_ABSENT", Warning,
299            "a BMOPF document states no schema, so its version is unknown";
300        /// The document states a `meta.schema_version` that names no BMOPF
301        /// release PowerIO knows, or a `meta.$schema` that names no known
302        /// schema.
303        READ_BMOPF_SCHEMA_UNKNOWN = "READ.BMOPF.SCHEMA_UNKNOWN", Warning,
304            "a BMOPF document states a schema naming no known version";
305        READ_BMOPF_SEMANTIC_INVALID = "READ.BMOPF.SEMANTIC_INVALID", Error,
306            "the BMOPF document has inconsistent dimensions, references, or bounds";
307        READ_BMOPF_SCHEMA_MISMATCH = "READ.BMOPF.SCHEMA_MISMATCH", Error,
308            "the schema URI and explicit schema version disagree";
309
310        // EMIT.BMOPF: the general families beside the nineteen transformer
311        // codes the writer already publishes.
312        EMIT_BMOPF_FIELD_DROPPED = "EMIT.BMOPF.FIELD_DROPPED", Warning,
313            "a field the BMOPF schema has no slot for was dropped";
314        EMIT_BMOPF_RECORD_DROPPED = "EMIT.BMOPF.RECORD_DROPPED", Warning,
315            "an object the emitted BMOPF document does not reference was dropped";
316        EMIT_BMOPF_VALUE_DEFAULTED = "EMIT.BMOPF.VALUE_DEFAULTED", Warning,
317            "a value the BMOPF schema requires was synthesized";
318        EMIT_BMOPF_RETAINED_SOURCE_ONLY = "EMIT.BMOPF.RETAINED_SOURCE_ONLY", Warning,
319            "a field with no schema slot was written under extras";
320        EMIT_BMOPF_VALUE_CLAMPED = "EMIT.BMOPF.VALUE_CLAMPED", Warning,
321            "a matrix dimension beyond the supported maximum was clamped";
322        EMIT_BMOPF_VALUE_SUBSTITUTED = "EMIT.BMOPF.VALUE_SUBSTITUTED", Warning,
323            "a stated value was replaced by one the BMOPF schema can hold";
324        EMIT_BMOPF_SOURCE_COUNT = "EMIT.BMOPF.SOURCE_COUNT", Warning,
325            "the BMOPF formulation expects exactly one voltage source";
326
327
328        // EMIT.BMOPF: the writer's element specific codes, registered
329        // entries rather than loose string literals.
330        EMIT_BMOPF_AUTOTRANSFORMER_DROPPED = "EMIT.BMOPF.AUTOTRANSFORMER_DROPPED", Warning,
331            "an autotransformer the BMOPF schema cannot state was dropped";
332        EMIT_BMOPF_BUS_LOCATION_DROPPED = "EMIT.BMOPF.BUS_LOCATION_DROPPED", Warning,
333            "a bus location the BMOPF schema cannot state was dropped";
334        EMIT_BMOPF_REGCONTROL_DROPPED = "EMIT.BMOPF.REGCONTROL_DROPPED", Warning,
335            "a regulator control the BMOPF schema cannot state was dropped";
336        EMIT_BMOPF_TRANSFORMER_CENTER_TAP_LEAKAGE_UNREPRESENTABLE =
337            "EMIT.BMOPF.TRANSFORMER_CENTER_TAP_LEAKAGE_UNREPRESENTABLE", Warning,
338            "a centre tap transformer's leakage split has no BMOPF spelling";
339        EMIT_BMOPF_TRANSFORMER_CENTER_TAP_NEUTRAL_COLLAPSED =
340            "EMIT.BMOPF.TRANSFORMER_CENTER_TAP_NEUTRAL_COLLAPSED", Warning,
341            "a centre tap transformer's neutral was collapsed to one BMOPF winding";
342        EMIT_BMOPF_TRANSFORMER_CENTER_TAP_RATING_COLLAPSED =
343            "EMIT.BMOPF.TRANSFORMER_CENTER_TAP_RATING_COLLAPSED", Warning,
344            "a centre tap transformer's per leg ratings were collapsed to one";
345        EMIT_BMOPF_TRANSFORMER_CENTER_TAP_TAP_COLLAPSED =
346            "EMIT.BMOPF.TRANSFORMER_CENTER_TAP_TAP_COLLAPSED", Warning,
347            "a centre tap transformer's per leg taps were collapsed to one";
348        EMIT_BMOPF_TRANSFORMER_CONNECTION_LOSSY = "EMIT.BMOPF.TRANSFORMER_CONNECTION_LOSSY",
349            Warning, "a transformer connection reads back differently through BMOPF";
350        EMIT_BMOPF_TRANSFORMER_EXTRA_DROPPED = "EMIT.BMOPF.TRANSFORMER_EXTRA_DROPPED", Warning,
351            "a transformer passthrough extra with no BMOPF slot was dropped";
352        EMIT_BMOPF_TRANSFORMER_MISSING_XSC = "EMIT.BMOPF.TRANSFORMER_MISSING_XSC", Warning,
353            "a transformer states no short circuit reactance for BMOPF to carry";
354        EMIT_BMOPF_TRANSFORMER_N_WINDING_RATING_COLLAPSED =
355            "EMIT.BMOPF.TRANSFORMER_N_WINDING_RATING_COLLAPSED", Warning,
356            "an n winding transformer's per winding ratings were collapsed to one";
357        EMIT_BMOPF_TRANSFORMER_NEUTRAL_DROPPED = "EMIT.BMOPF.TRANSFORMER_NEUTRAL_DROPPED",
358            Warning, "a transformer neutral the BMOPF schema cannot state was dropped";
359        EMIT_BMOPF_TRANSFORMER_NO_LOAD_SHUNT_DROPPED =
360            "EMIT.BMOPF.TRANSFORMER_NO_LOAD_SHUNT_DROPPED", Warning,
361            "a transformer no load shunt the BMOPF schema cannot state was dropped";
362        EMIT_BMOPF_TRANSFORMER_NO_LOAD_SHUNT_UNCONVERTIBLE =
363            "EMIT.BMOPF.TRANSFORMER_NO_LOAD_SHUNT_UNCONVERTIBLE", Warning,
364            "a transformer no load shunt could not be converted to the BMOPF form";
365        EMIT_BMOPF_TRANSFORMER_OPEN_DELTA_MERGED = "EMIT.BMOPF.TRANSFORMER_OPEN_DELTA_MERGED",
366            Warning, "two regulator legs merged into one open_delta_regulator object";
367        EMIT_BMOPF_TRANSFORMER_PER_PHASE_TAP_COLLAPSED =
368            "EMIT.BMOPF.TRANSFORMER_PER_PHASE_TAP_COLLAPSED", Warning,
369            "a transformer's per phase taps were collapsed to one BMOPF tap";
370        EMIT_BMOPF_TRANSFORMER_TAP_DROPPED = "EMIT.BMOPF.TRANSFORMER_TAP_DROPPED", Warning,
371            "a transformer tap the BMOPF schema cannot state was dropped";
372        EMIT_BMOPF_TRANSFORMER_UNSUPPORTED = "EMIT.BMOPF.TRANSFORMER_UNSUPPORTED", Warning,
373            "a transformer shape the BMOPF schema has no subtype for";
374        EMIT_BMOPF_TRANSFORMER_WINDINGS_CLAMPED = "EMIT.BMOPF.TRANSFORMER_WINDINGS_CLAMPED",
375            Warning, "a transformer's winding count was clamped to what BMOPF carries";
376        EMIT_BMOPF_TRANSFORMER_WYE_WYE_DECOMPOSED = "EMIT.BMOPF.TRANSFORMER_WYE_WYE_DECOMPOSED",
377            Warning, "a wye-wye transformer was decomposed into BMOPF pairs";
378
379        // READ.CIM_DIST: distribution CIM decoded, but not representable in
380        // the multiconductor model.
381        READ_CIM_DIST_CLASS_UNMAPPED = "READ.CIM_DIST.CLASS_UNMAPPED", Warning,
382            "objects of a CIM class the distribution mapping does not read were not carried";
383        READ_CIM_DIST_CONTEXT_UNMAPPED = "READ.CIM_DIST.CONTEXT_UNMAPPED", Remark,
384            "containment, naming, or base voltage context the model has no field for was not carried";
385        READ_CIM_DIST_FIELD_UNMAPPED = "READ.CIM_DIST.FIELD_UNMAPPED", Warning,
386            "a property of a mapped CIM object has no model field and was not carried";
387        READ_CIM_DIST_RECORD_DROPPED = "READ.CIM_DIST.RECORD_DROPPED", Warning,
388            "a CIM equipment record could not be mapped and was dropped";
389        READ_CIM_DIST_VALUE_DEFAULTED = "READ.CIM_DIST.VALUE_DEFAULTED", Warning,
390            "a value the model needs was absent or unusable and was defaulted";
391        READ_CIM_DIST_VALUE_UNSUPPORTED = "READ.CIM_DIST.VALUE_UNSUPPORTED", Warning,
392            "a CIM value outside the mapped set was read as the nearest one";
393        READ_CIM_DIST_VALUE_COLLAPSED = "READ.CIM_DIST.VALUE_COLLAPSED", Warning,
394            "CIM structure was reduced to what one model field can carry";
395        READ_CIM_DIST_VALUE_CONFLICT = "READ.CIM_DIST.VALUE_CONFLICT", Warning,
396            "two statements of one CIM property disagree and the first was kept";
397        READ_CIM_DIST_REFERENCE_DROPPED = "READ.CIM_DIST.REFERENCE_DROPPED", Warning,
398            "a CIM reference names an object the document set does not define";
399        READ_CIM_DIST_IDENTIFIER_SUBSTITUTED = "READ.CIM_DIST.IDENTIFIER_SUBSTITUTED", Warning,
400            "a CIM name that is empty or repeats another was replaced by the object's mRID";
401        /// A segment states no impedance (no `PerLengthImpedance` and no
402        /// series values), typically because it is described by wire
403        /// geometry, which the reader does not calculate. Severity `Error`:
404        /// the parse continued, but the segment has no series impedance.
405        READ_CIM_DIST_IMPEDANCE_UNRESOLVED = "READ.CIM_DIST.IMPEDANCE_UNRESOLVED", Error,
406            "a line segment states no impedance the reader can carry";
407
408        // READ.PMD_MATH: the MATHEMATICAL model decoded, but not representable
409        // as stated.
410        READ_PMD_MATH_VALUE_DEFAULTED = "READ.PMD_MATH.VALUE_DEFAULTED", Warning,
411            "a value the model needs is absent from the MATHEMATICAL document and was defaulted";
412        READ_PMD_MATH_VALUE_SUBSTITUTED = "READ.PMD_MATH.VALUE_SUBSTITUTED", Warning,
413            "a MATHEMATICAL value was restated on a base or form the model carries";
414        READ_PMD_MATH_VALUE_COLLAPSED = "READ.PMD_MATH.VALUE_COLLAPSED", Warning,
415            "MATHEMATICAL structure was reduced to what one model field can carry";
416        READ_PMD_MATH_RECORD_DROPPED = "READ.PMD_MATH.RECORD_DROPPED", Warning,
417            "a MATHEMATICAL object could not be mapped and was dropped";
418        READ_PMD_MATH_RETAINED_SOURCE_ONLY = "READ.PMD_MATH.RETAINED_SOURCE_ONLY", Warning,
419            "a MATHEMATICAL object or field survives untyped or in extras rather than in a typed field";
420        READ_PMD_MATH_SOURCE_MALFORMED = "READ.PMD_MATH.SOURCE_MALFORMED", Warning,
421            "a MATHEMATICAL value is not the shape its key declares";
422        READ_PMD_MATH_REFERENCE_DROPPED = "READ.PMD_MATH.REFERENCE_DROPPED", Warning,
423            "a MATHEMATICAL object names a bus or map target the document does not define";
424
425        // EMIT.PMD_MATH: what the MATHEMATICAL writer cannot state.
426        EMIT_PMD_MATH_FIELD_DROPPED = "EMIT.PMD_MATH.FIELD_DROPPED", Warning,
427            "a field the MATHEMATICAL model has no key for was dropped";
428        EMIT_PMD_MATH_RECORD_DROPPED = "EMIT.PMD_MATH.RECORD_DROPPED", Warning,
429            "an element the MATHEMATICAL writer does not lower was dropped";
430        EMIT_PMD_MATH_VALUE_DEFAULTED = "EMIT.PMD_MATH.VALUE_DEFAULTED", Warning,
431            "a value the MATHEMATICAL model requires was synthesized";
432        EMIT_PMD_MATH_VALUE_SUBSTITUTED = "EMIT.PMD_MATH.VALUE_SUBSTITUTED", Warning,
433            "a stated value was replaced by one the MATHEMATICAL model can hold";
434
435        // READ.RAVENS: the multiconductor MG-RAVENS profile decoded, but
436        // not representable in the model as stated.
437        READ_RAVENS_DIST_CLASS_UNMAPPED = "READ.RAVENS_DIST.CLASS_UNMAPPED", Warning,
438            "MG-RAVENS objects of a class the distribution mapping does not read were kept untyped";
439        READ_RAVENS_DIST_FIELD_UNMAPPED = "READ.RAVENS_DIST.FIELD_UNMAPPED", Warning,
440            "a property of a mapped MG-RAVENS object has no model field and was not carried";
441        READ_RAVENS_DIST_RECORD_DROPPED = "READ.RAVENS_DIST.RECORD_DROPPED", Warning,
442            "an MG-RAVENS equipment record could not be mapped and was kept untyped";
443        READ_RAVENS_DIST_VALUE_DEFAULTED = "READ.RAVENS_DIST.VALUE_DEFAULTED", Warning,
444            "a value the model needs is absent from the MG-RAVENS document and was defaulted";
445        READ_RAVENS_DIST_VALUE_SUBSTITUTED = "READ.RAVENS_DIST.VALUE_SUBSTITUTED", Warning,
446            "an MG-RAVENS value outside the mapped set was read as the nearest one";
447        READ_RAVENS_DIST_VALUE_COLLAPSED = "READ.RAVENS_DIST.VALUE_COLLAPSED", Warning,
448            "MG-RAVENS structure was reduced to what one model field can carry";
449        READ_RAVENS_DIST_VALUE_CONFLICT = "READ.RAVENS_DIST.VALUE_CONFLICT", Warning,
450            "two MG-RAVENS statements of one value disagree and the first was kept";
451        READ_RAVENS_DIST_RETAINED_SOURCE_ONLY = "READ.RAVENS_DIST.RETAINED_SOURCE_ONLY", Warning,
452            "an MG-RAVENS object survives untyped: it round-trips to MG-RAVENS and is dropped elsewhere";
453
454        // EMIT.RAVENS: what the multiconductor MG-RAVENS writer cannot state.
455        EMIT_RAVENS_DIST_FIELD_DROPPED = "EMIT.RAVENS_DIST.FIELD_DROPPED", Warning,
456            "a field MG-RAVENS has no property for was dropped";
457        EMIT_RAVENS_DIST_RECORD_DROPPED = "EMIT.RAVENS_DIST.RECORD_DROPPED", Warning,
458            "an element the MG-RAVENS writer does not emit was dropped";
459        EMIT_RAVENS_DIST_EXTRAS_DROPPED = "EMIT.RAVENS_DIST.EXTRAS_DROPPED", Warning,
460            "a passthrough extra with no MG-RAVENS property was dropped";
461        EMIT_RAVENS_DIST_VALUE_COLLAPSED = "EMIT.RAVENS_DIST.VALUE_COLLAPSED", Warning,
462            "structure was reduced to what one MG-RAVENS property can carry";
463        EMIT_RAVENS_DIST_VALUE_SUBSTITUTED = "EMIT.RAVENS_DIST.VALUE_SUBSTITUTED", Warning,
464            "a stated value was replaced by one MG-RAVENS can hold";
465        EMIT_RAVENS_DIST_NOT_A_NUMBER = "EMIT.RAVENS_DIST.NOT_A_NUMBER", Warning,
466            "a non-finite value was written as 0, because JSON has no Inf or NaN";
467        EMIT_RAVENS_DIST_SOURCE_SPLIT = "EMIT.RAVENS_DIST.SOURCE_SPLIT", Warning,
468            "an unbalanced source is written as one single phase EnergySource per phase conductor, with the same terminal phasors";
469
470        // EMIT.CIM_DIST: what the distribution CIM writer cannot state.
471        EMIT_CIM_DIST_FIELD_DROPPED = "EMIT.CIM_DIST.FIELD_DROPPED", Warning,
472            "a field distribution CIM has no property for was dropped";
473        EMIT_CIM_DIST_RECORD_DROPPED = "EMIT.CIM_DIST.RECORD_DROPPED", Warning,
474            "an element the distribution CIM writer does not emit was dropped";
475        EMIT_CIM_DIST_EXTRAS_DROPPED = "EMIT.CIM_DIST.EXTRAS_DROPPED", Warning,
476            "a passthrough extra with no distribution CIM property was dropped";
477        EMIT_CIM_DIST_VALUE_COLLAPSED = "EMIT.CIM_DIST.VALUE_COLLAPSED", Warning,
478            "structure was reduced to what one CIM property can carry";
479        EMIT_CIM_DIST_VALUE_SUBSTITUTED = "EMIT.CIM_DIST.VALUE_SUBSTITUTED", Warning,
480            "an identifier or value was replaced by one distribution CIM can state";
481
482        // The multiconductor model itself.
483        READ_MULTICONDUCTOR_VALUE_DEFAULTED = "READ.MULTICONDUCTOR.VALUE_DEFAULTED", Warning,
484            "a value the document never states was defaulted while reading";
485        VALIDATE_MULTICONDUCTOR_REFERENCE_UNDEFINED =
486            "VALIDATE.MULTICONDUCTOR.REFERENCE_UNDEFINED", Warning,
487            "an element references a bus or linecode the document does not declare";
488        EMIT_MULTICONDUCTOR_ROUTE_DROPPED = "EMIT.MULTICONDUCTOR.ROUTE_DROPPED", Warning,
489            "a line polyline was dropped because the target has no polyline field";
490        EMIT_MULTICONDUCTOR_SIDECAR_DROPPED = "EMIT.MULTICONDUCTOR.SIDECAR_DROPPED", Warning,
491            "a companion file the case text refers to was not written";
492
493        // Same-family distribution network projections.
494        TRANSFORM_DIST_NEUTRAL_KRON_REDUCED = "TRANSFORM.DIST.NEUTRAL_KRON_REDUCED", Remark,
495            "an explicit grounded neutral was eliminated by Kron reduction";
496        TRANSFORM_DIST_NEUTRAL_KRON_FORCED_GROUND =
497            "TRANSFORM.DIST.NEUTRAL_KRON_FORCED_GROUND", Warning,
498            "a neutral was treated as ideally grounded before Kron reduction";
499        TRANSFORM_DIST_KRON_UNTYPED_RETAINED = "TRANSFORM.DIST.KRON_UNTYPED_RETAINED", Warning,
500            "untyped source objects were retained unchanged through neutral reduction";
501
502        // Failures.
503        READ_DIST_IO_FAILED = "READ.DIST.IO_FAILED", Error,
504            "a distribution case file could not be read", category = Io;
505        REQUEST_DIST_FORMAT_UNKNOWN = "REQUEST.DIST_FORMAT.UNKNOWN", Error,
506            "the named distribution format is not one powerio reads",
507            category = Request;
508        TRANSFORM_DIST_KRON_REDUCTION_FAILED = "TRANSFORM.DIST.KRON_REDUCTION_FAILED", Error,
509            "a neutral Kron projection could not preserve the network semantics",
510            category = Data;
511    }
512}
513
514/// Every code this crate declares.
515#[must_use]
516pub fn registry() -> Vec<&'static DiagnosticInfo> {
517    codes::ALL.to_vec()
518}
519
520/// Attach an input-derived locator, or record its loss on the finding when it
521/// cannot be stored. A locator is identity, so it is never shortened; when the
522/// input supplies one past the record bounds, the finding says a locator
523/// existed and how long it was instead of silently changing identity.
524pub(crate) fn attach_target(diagnostic: &mut Diagnostic, target: String) {
525    let byte_length = target.len();
526    if diagnostic.set_target(target).is_err() {
527        let marker =
528            diagnostic.insert_detail("dropped_target_bytes", serde_json::Value::from(byte_length));
529        debug_assert!(marker.is_ok(), "the drop marker fits an emitted finding");
530    }
531}
532
533#[cfg(test)]
534mod tests {
535    use super::*;
536
537    #[test]
538    fn the_registry_is_sound() {
539        let problems = check_registry(registry());
540        assert!(problems.is_empty(), "{problems:#?}");
541    }
542}