molframe_core/diagnostic/

registry.rs

//! The diagnostic code registry.
//!
//! Declaring codes as data rather than as scattered string literals buys three
//! things: a remedy is structurally required rather than remembered, the whole
//! set can be enumerated for documentation, and a code's severity is decided in
//! one place instead of at each site that raises it.
//!
//! Entries are declared in sorted order — errors before warnings, then by
//! number — because lookup binary-searches this table. A test enforces it.

use super::code::{Code, Entry, Kind, Severity};

macro_rules! registry {
    ($($name:ident = $kind:ident $number:literal, $severity:ident, $cause:literal, $remedy:literal;)*) => {
        impl Code {
            $(
                #[doc = $cause]
                pub const $name: Self = Self::new(Kind::$kind, $number);
            )*
        }

        pub(super) static ENTRIES: &[Entry] = &[$(
            Entry {
                code: Code::new(Kind::$kind, $number),
                severity: Severity::$severity,
                cause: $cause,
                remedy: $remedy,
            },
        )*];
    };
}

registry! {
    E1001 = Error 1001, Breaking,
        "format could not be determined",
        "pass the format explicitly, or give the file an extension the reader recognises";
    E1101 = Error 1101, Breaking,
        "unterminated quoted value",
        "close the quote; a value containing a quote character must use the other quote style or a multi-line text field";
    E1102 = Error 1102, Breaking,
        "unterminated multi-line text field",
        "close the field with a semicolon at the start of a line";
    E1103 = Error 1103, Breaking,
        "loop_ row count is not a multiple of the column count",
        "count the values in the final row; an unquoted value containing a space parses as two values";
    E1104 = Error 1104, Invalidating,
        "duplicate tag within a category",
        "remove the repeated tag; the two values cannot both be the value of one item";
    E1105 = Error 1105, Breaking,
        "value outside any category",
        "precede the value with the tag it belongs to, or with a loop_ header";
    E1106 = Error 1106, Breaking,
        "missing data_ block header",
        "add a data_ line before the first category; a file with no block cannot be addressed";
    E1201 = Error 1201, Invalidating,
        "malformed fixed-column record",
        "check the record against its column layout; fields are positional, so one misplaced column shifts every field after it";
    E1202 = Error 1202, Invalidating,
        "unparseable numeric field",
        "correct the field, or read in recover mode to keep the rest of the file";
    E1203 = Error 1203, Invalidating,
        "atom serial exceeds format capacity and is not hybrid-36",
        "re-encode the serial in hybrid-36, or use a format without a five-column serial field";
    E1301 = Error 1301, Invalidating,
        "substructure pattern is not valid SMARTS",
        "correct the pattern at the reported position; only the primitives the pattern model represents are accepted";
    E1401 = Error 1401, Breaking,
        "declared length disagrees with the encoded payload",
        "the file is truncated or corrupt; fetch it again";
    E1402 = Error 1402, Breaking,
        "unknown column encoding",
        "the file uses an encoding this version does not implement; upgrade molframe";
    E1403 = Error 1403, Breaking,
        "codec chain type mismatch",
        "the encoding chain is inconsistent with itself; report it to whatever wrote the file";
    E1901 = Error 1901, Breaking,
        "resource limit exceeded",
        "raise the limit deliberately if the input is genuinely this large; the default guards against decompression bombs and absurd declared row counts";
    E1902 = Error 1902, Breaking,
        "source window exceeds the execution memory budget",
        "reduce the requested window or deliberately raise the execution memory budget";
    E1903 = Error 1903, Breaking,
        "source window cannot be represented on this host",
        "request a smaller window or use a host whose address space can represent it";
    E1904 = Error 1904, Breaking,
        "execution cancelled",
        "start a new execution with an uncancelled context when the result is still needed";
    E2001 = Error 2001, Invalidating,
        "required category absent",
        "add the category, or read with a strictness that tolerates its absence";
    E2002 = Error 2002, Invalidating,
        "required item absent",
        "add the item; without it the affected rows cannot be interpreted";
    E2003 = Error 2003, Strict,
        "value outside the declared enumeration",
        "use one of the enumerated values, or relax strictness to accept the file as deposited";
    E2004 = Error 2004, Invalidating,
        "value has the wrong type for its item",
        "correct the value; a numeric item cannot hold text";
    E2005 = Error 2005, Strict,
        "parent-child relationship violated",
        "add the missing parent row, or correct the child's reference";
    E2101 = Error 2101, Invalidating,
        "sequence, alphabet, tree or substitution data is invalid",
        "check the residue symbols against the alphabet, the tree text against its grammar and the scoring profile against its alphabet";
    E2201 = Error 2201, Invalidating,
        "reference table is malformed",
        "fix the line the message names; a table is accepted whole or not at all, and its header must give name, version, source and licence";
    E3001 = Error 3001, Invalidating,
        "column length disagrees with the chunk length",
        "report this as a molframe bug; a structure cannot be built this way from valid input";
    E3002 = Error 3002, Invalidating,
        "child range exceeds the child table",
        "report this as a molframe bug";
    E3003 = Error 3003, Invalidating,
        "overlapping child ranges",
        "report this as a molframe bug";
    E3004 = Error 3004, Invalidating,
        "atom belongs to no residue",
        "report this as a molframe bug";
    E3005 = Error 3005, Invalidating,
        "chain references a nonexistent entity",
        "check the entity identifiers the chains refer to";
    E3006 = Error 3006, Invalidating,
        "bond endpoint out of range",
        "check the connectivity records; they name an atom the file does not contain";
    E3007 = Error 3007, Invalidating,
        "self-bond",
        "remove the connectivity record bonding an atom to itself";
    E3008 = Error 3008, Invalidating,
        "non-finite coordinate without a validity mark",
        "correct the coordinate, or mark the atom's position as unrecorded";
    E3009 = Error 3009, Strict,
        "occupancy outside the zero-to-one range",
        "correct the occupancy; values outside the range make occupancy-weighted results meaningless";
    E3010 = Error 3010, Invalidating,
        "models share a coordinate set but not an atom count",
        "the models differ in composition and must be held as a ragged ensemble rather than as frames";
    E3011 = Error 3011, Invalidating,
        "custom annotation length disagrees with the atom count",
        "supply exactly one annotation row for every atom row";
    E3012 = Error 3012, Invalidating,
        "structures cannot share one merged model axis",
        "merge structures with equal dense model counts, or keep unlike models as a ragged ensemble";
    E3013 = Error 3013, Invalidating,
        "custom annotation types disagree across structures",
        "convert same-named annotation columns to one physical type before merging";
    E3014 = Error 3014, Invalidating,
        "domain extensions would be invalidated by a topology change",
        "explicitly clear extensions before editing topology or merging structures";
    E3015 = Error 3015, Invalidating,
        "residue boundary is not defined by the deposited identifiers",
        "repair the residue identifiers or explicitly select file-order boundary inference";
    E3201 = Error 3201, Invalidating,
        "bundled chemistry reference data is invalid",
        "reinstall molframe from a verified distribution";
    E3401 = Error 3401, Invalidating,
        "topology and coordinate atom counts disagree",
        "check that the coordinate source and the topology source describe the same system";
    E4001 = Error 4001, Invalidating,
        "selection syntax is invalid",
        "correct the selection at the reported token";
    E4002 = Error 4002, Invalidating,
        "selection value is incompatible with its column",
        "use a value of the column's declared type";
    E4003 = Error 4003, Invalidating,
        "selection requires data this structure does not carry",
        "provide the required annotations or choose a selector available for this structure";
    E4004 = Error 4004, Invalidating,
        "unknown selection keyword",
        "check the spelling against the keyword list; an annotation column can also be selected by its own name";
    E4005 = Error 4005, Invalidating,
        "named query is not defined",
        "define the name before referring to it, or check its spelling";
    E4006 = Error 4006, Invalidating,
        "named query definitions refer to each other in a cycle",
        "break the cycle so that every name eventually resolves to atoms rather than to itself";
    E4007 = Error 4007, Invalidating,
        "named query nesting is too deep",
        "flatten the chain of definitions; each name may refer to at most a bounded depth of other names";
    E4101 = Error 4101, Invalidating,
        "atom count exceeds legacy format capacity",
        "write mmCIF or BinaryCIF, or enable hybrid-36 serials explicitly";
    E4102 = Error 4102, Invalidating,
        "chain identifier cannot be represented in the target format",
        "write mmCIF or BinaryCIF, or supply an explicit chain mapping";
    E4103 = Error 4103, Invalidating,
        "residue number exceeds legacy format capacity",
        "write mmCIF or BinaryCIF, or enable hybrid-36 residue numbers explicitly";
    E4104 = Error 4104, Invalidating,
        "coordinate magnitude exceeds the target field width",
        "translate the structure towards the origin, or write a format with wider coordinate fields";
    E4105 = Error 4105, Invalidating,
        "the target format cannot express a required category",
        "write a format that models the data, or drop the category deliberately";
    E5001 = Error 5001, Invalidating,
        "superposition is undefined for fewer than three non-collinear atoms",
        "widen the selection until it spans three dimensions";
    E5002 = Error 5002, Invalidating,
        "degenerate frame from collinear reference atoms",
        "choose reference atoms that are not in a straight line";
    E5003 = Error 5003, Invalidating,
        "empty selection where atoms are required",
        "check the selection against the structure; a keyword that matches nothing here may match elsewhere";
    E5004 = Error 5004, Invalidating,
        "periodic query without a unit cell",
        "supply a cell, or ask for a non-periodic query";
    E5005 = Error 5005, Invalidating,
        "cutoff exceeds half the minimum box dimension under the minimum image convention",
        "reduce the cutoff, or use a periodic mode that considers more than the nearest image";
    E5101 = Error 5101, Invalidating,
        "numeric parameter is not finite or lies outside its valid range",
        "supply a finite value inside the documented range; no default is substituted for an invalid one";
    E5102 = Error 5102, Invalidating,
        "paired inputs do not correspond in length or shape",
        "give both inputs one entry per matched item, in the same order";
    E5103 = Error 5103, Invalidating,
        "too few points or items for the computation",
        "supply enough input for the operation, for instance three non-collinear points to superpose";
    E5104 = Error 5104, Invalidating,
        "the configuration is degenerate or the numerical method did not converge",
        "choose input that is not degenerate, or relax the explicit tolerance or sweep limit";
    E5105 = Error 5105, Invalidating,
        "no valid correspondence or alignment could be established",
        "check that the inputs share enough matching content, or lower the explicit identity threshold";
    E6001 = Error 6001, Invalidating,
        "unqualified identifier while the policy requires explicit namespaces",
        "qualify the selector, for instance auth_chain rather than chain";
    E6002 = Error 6002, Invalidating,
        "requested assembly does not exist",
        "list the assemblies the entry defines and choose one of them";
    E6003 = Error 6003, Invalidating,
        "requested model does not exist",
        "check the model count; models are addressed by position, not by deposited number";
    E6004 = Error 6004, Invalidating,
        "policy field combination is contradictory",
        "reconcile the two fields; the analysis cannot honour both";
    E6005 = Error 6005, Invalidating,
        "verdict profile not found",
        "list the registered profiles; profile names carry a version";
    E6006 = Error 6006, Invalidating,
        "requested chain does not exist",
        "check the chain count or resolve the chain label before editing";
    E6007 = Error 6007, Invalidating,
        "identifier is empty",
        "supply a non-empty identifier";
    E6008 = Error 6008, Invalidating,
        "a whole-ensemble coordinate edit requires shared topology",
        "edit each ragged model snapshot independently";
    E6009 = Error 6009, Invalidating,
        "an atom selected for editing does not exist",
        "restrict the selection to the structure atom range";
    E6010 = Error 6010, Invalidating,
        "assembly operator expression is malformed",
        "use comma-separated identifiers and integer ranges, with each product factor in parentheses";
    E6011 = Error 6011, Invalidating,
        "assembly operator expression exceeds the instance limit",
        "reduce the operator product or raise the explicit assembly limit";
    E6012 = Error 6012, Invalidating,
        "assembly category contains a malformed required value",
        "correct the named assembly category item and row";
    E6013 = Error 6013, Invalidating,
        "assembly generator references an unknown definition",
        "correct the referenced assembly, operator, or label-asym identifier";
    E6014 = Error 6014, Invalidating,
        "non-crystallographic symmetry operator is malformed",
        "correct the NCS identifier, given/generate code, matrix, or translation vector";
    E6015 = Error 6015, Invalidating,
        "crystallographic symmetry metadata or algebraic operation is malformed",
        "correct the space-group number, operation identifier, or fractional xyz expression";
    E6016 = Error 6016, Invalidating,
        "crystal neighbour search configuration is incomplete or invalid",
        "supply explicit symmetry operators, a valid model, and a positive finite cutoff";
    E6017 = Error 6017, Invalidating,
        "crystal neighbour search exceeds its candidate-image limit",
        "reduce the cutoff or raise the explicit search limit after reviewing the expected cost";
    E6018 = Error 6018, Invalidating,
        "space-group setting is unknown or the bundled catalogue is invalid",
        "supply a valid Hall symbol or International Tables number, or reinstall molframe";
    E6101 = Error 6101, Invalidating,
        "workflow graph is invalid",
        "check that every node's inputs exist, have the right types and form no cycle";
    E6102 = Error 6102, Invalidating,
        "execution context configuration is inconsistent",
        "give at least one worker, and a scratch or temporary-storage size that fits the memory budget";
    E6103 = Error 6103, Invalidating,
        "the requested operation is unsupported for this input or policy",
        "choose a supported input form, a source that offers the capability, or a policy this operation can represent";
    E6104 = Error 6104, Invalidating,
        "a policy value is not in the vocabulary of its decision",
        "use one of the documented words for that decision; names are kebab-case and an underscore is read as a hyphen";
    E7001 = Error 7001, Invalidating,
        "operation exceeds the execution memory budget",
        "raise the memory budget (Python ExecutionContext(memory_budget=...), Rust ExecutionContext::builder().memory_budget(MemoryBudget::new(..)?), CLI --memory-budget, or env MOLFRAME_MEMORY_BUDGET), narrow the selection, or process the input in smaller pieces";
    E7101 = Error 7101, Invalidating,
        "input could not be read",
        "check the path, permissions and that the file is complete and in the expected format";
    E7102 = Error 7102, Invalidating,
        "no reference table is available for the computation",
        "pass a table file, select a cache entry by name, or store one with `molframe data fetch <entry> --manifest <file>`; the library compiles in no table and never fetches during a computation";
    E7103 = Error 7103, Invalidating,
        "the reference table asked for conflicts with the one the policy names",
        "drop the table argument so the policy's table applies, or set the policy field to the table you pass";
    E7901 = Error 7901, Invalidating,
        "output could not be written",
        "check the destination, permissions and available storage, then retry";
    E9001 = Error 9001, Breaking,
        "internal invariant violated",
        "report this as a molframe bug with the input that produced it; no input should be able to cause this";
    W1001 = Warning 1001, Loose,
        "trailing content after the final block",
        "remove the trailing content, or ignore this if the file is deliberately concatenated";
    W1002 = Warning 1002, Info,
        "non-standard whitespace or line ending",
        "normalise the line endings if the file is meant to be portable";
    W1901 = Warning 1901, Info,
        "further findings were suppressed",
        "the retained findings describe the problem; raise the diagnostic ceiling only if you need every occurrence rather than every distinct cause";
    W2001 = Warning 2001, Info,
        "unknown category retained but not interpreted",
        "no action needed; the category survives a preserving write untouched";
    W2002 = Warning 2002, Info,
        "unknown item retained but not interpreted",
        "no action needed; the item survives a preserving write untouched";
    W2003 = Warning 2003, Loose,
        "deprecated item used",
        "migrate to the replacement item named in the dictionary";
    W3011 = Warning 3011, Info,
        "residue boundary was inferred from file order by explicit policy",
        "check the residue identifiers in this region; consecutive residues carry annotations that do not distinguish them";
    W3012 = Warning 3012, Loose,
        "an alternate location carries a different component identity",
        "no action needed; this is one residue modelled with two chemical identities, and both are retained";
    W3013 = Warning 3013, Loose,
        "connection partner lies on a symmetry image outside the asymmetric unit and was not lowered to a bond",
        "no action needed; the connection joins this molecule to a crystal neighbour, so the bond graph of one asymmetric unit has no atom to point at. The deposited row stays in the retained source document; analyse the crystallographic images to use it";
    W3014 = Warning 3014, Loose,
        "occupancy outside the zero-to-one range was clamped by explicit policy",
        "no action needed if clamping is intended; the deposited values are outside the range and the original file still holds them";
    W3015 = Warning 3015, Loose,
        "occupancies or B-factors differ between models of one ensemble; the first model's values are kept",
        "no action needed for coordinates, which are kept for every model; read per-model B-factors from the source file if they matter";
    W3016 = Warning 3016, Loose,
        "a connection record names an atom the file does not contain and was not lowered to a bond",
        "no action needed if the atom was filtered out on purpose; otherwise correct the record's chain, residue number, or atom name. The record itself is kept in the retained headers";
    W3201 = Warning 3201, Loose,
        "component not found in any chemical component provider",
        "layer the full wwPDB dictionary (components.cif.gz from files.wwpdb.org/pub/pdb/data/monomers) as the user dictionary or as the profile's `components:` cache entry, or embed chem_comp_atom and chem_comp_bond rows for this component in the input file; until then its atoms and bonds are not checked";
    W3202 = Warning 3202, Strict,
        "observed atoms are inconsistent with the component definition; file connectivity was used",
        "check the component's atom names against its definition";
    W3203 = Warning 3203, Loose,
        "element inferred from the atom name",
        "declare the element explicitly; the name-based rule is a convention that files are free to violate";
    W3204 = Warning 3204, Loose,
        "unusual valence",
        "check the connectivity and formal charge of the atom named";
    W3205 = Warning 3205, Info,
        "chirality was not assessed for a residue",
        "the reason is named in the finding: the component has no ideal coordinates, they do not align with the model, or its stereocentre geometry is degenerate; supply a dictionary with ideal coordinates to assess it. A centre that was assessed and disagrees is reported as a chirality outlier, not by this code";
    W3206 = Warning 3206, Loose,
        "the component definitions embedded in the file are malformed and were ignored",
        "the component is resolved from a dictionary instead; fix the chem_comp_atom and chem_comp_bond rows in the file, or supply a full dictionary";
    W3207 = Warning 3207, Loose,
        "bonds were not perceived because the profile names no bond-reach table",
        "add a `bond-reach: <name>` line to the profile with a `<name>.reach` table in the cache, or perceive explicitly with a table file; the library compiles in no reach table";
    W3301 = Warning 3301, Info,
        "atoms expected by the component definition are absent from the model",
        "no action needed; the shortfall is reported as coverage rather than hidden";
    W3302 = Warning 3302, Loose,
        "chain break detected within a polymer",
        "no action needed; the gap is unmodelled density and is reported rather than bridged";
    W4001 = Warning 4001, Loose,
        "unparenthesised mix of and and or",
        "parenthesise the expression; and binds more tightly than or, which may not be what was meant";
    W4002 = Warning 4002, Loose,
        "float equality comparison",
        "compare against a range instead; exact equality on a measured quantity rarely matches";
    W4003 = Warning 4003, Loose,
        "selection symbol not present in this structure",
        "check the spelling; the selection is valid but matches nothing here";
    W4101 = Warning 4101, Strict,
        "metadata dropped by the target format",
        "write a format that models the metadata if it matters";
    W4102 = Warning 4102, Strict,
        "identifier rewritten to stay unambiguous in the target format",
        "give each chain and residue its own normalised identifier before writing";
    W5001 = Warning 5001, Info,
        "neighbour list rebuilt more often than expected",
        "increase the skin distance to trade memory for rebuild frequency";
    W5002 = Warning 5002, Info,
        "distance matrix requested for a large selection",
        "use a neighbour query instead; a full matrix grows with the square of the selection";
    W6001 = Warning 6001, Strict,
        "per-atom highest occupancy may produce a conformation that was never modelled",
        "prefer a conformer-consistent altloc policy unless per-atom selection is genuinely intended";
    W6002 = Warning 6002, Info,
        "assembly generated multiple instances of a chain",
        "no action needed; instances carry their own identifiers and are distinguishable";
    W6003 = Warning 6003, Strict,
        "analysis returned an indeterminate result",
        "read the assumptions and coverage; no defensible single answer exists under this policy";
    W6004 = Warning 6004, Info,
        "a defaulted policy field materially affects this result",
        "set the field explicitly so the choice is recorded as yours rather than inherited";
}

#[cfg(test)]
#[path = "registry_tests.rs"]
mod tests;