Struct NormalizeConfig 

#[non_exhaustive]
pub struct NormalizeConfig {
    pub cross_boundaries: bool,
    pub error_config: ErrorConfig,
    pub window_size: u64,
    pub prevent_overlap: bool,
    /* private fields */
}

Configuration for variant normalization

Marked #[non_exhaustive] so adding a normalization knob is additive rather than breaking. Build it with NormalizeConfig::new (or the NormalizeConfig::strict / NormalizeConfig::lenient / NormalizeConfig::silent presets) plus the with_* builders, or from Default, rather than a struct literal; the fields stay pub, so anything the builders do not cover is still reachable by assigning to the field directly. Mirrors the attribute on its result-side counterpart crate::normalize::NormalizeResult, which #1033 marked for the same reason.

This is the type that carries the error mode — Default and NormalizeConfig::lenient both give it ErrorConfig::lenient(). Do not confuse it with crate::commands::NormalizeCommandConfig, which configures the batch run around a normalization (reference directory, progress, workers) and has no error mode at all. The two used to share the name NormalizeConfig, so NormalizeConfig::default() resolved to whichever one a single use line had brought into scope.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

cross_boundaries: bool

Whether to allow crossing exon-intron boundaries

error_config: ErrorConfig

Error handling configuration (controls reference validation behavior)

window_size: u64

Window size for reference sequence fetching

prevent_overlap: bool

Vestigial overlap-prevention flag retained for source compatibility.

Overlap is now prevented structurally: normalize_allele merges adjacent sub-variants before the per-variant pipeline runs, and merge_consecutive_edits uses a strict prev.end + 1 == next.start adjacency rule, so the normalizer cannot emit overlapping ranges from non-overlapping inputs. Detection of input-time overlap is handled unconditionally by detect_overlap_conflicts. This field has no effect and is preserved only so existing callers (notably with_overlap_prevention) keep compiling.

Implementations

impl NormalizeConfig

pub fn new() -> Self

Create a new config with default values

pub fn for_entry_point( direction: ShuffleDirection, error_config: ErrorConfig, ) -> Self

Build the configuration for an entry point — a seam where an error mode arrives from outside the library (the CLI, the PyO3 bindings, the web service).

The direction argument is always [ShuffleDirection::ThreePrime] at every such seam: no entry point accepts a direction from a caller any more. It is still a parameter so that the internal 3’/5’ differential can build an entry-point-shaped config, and so that the #1197 lint below keeps binding the error argument, which is what that constructor exists for.

Both settings are required arguments, which is the whole point: NormalizeConfig::default().with_direction(d) silently fills in every field the caller does not name, and error_config defaults to ErrorConfig::lenient. That is the shape that produced #1181 — the CLI built an ErrorConfig from --error-mode, passed it into run_normalize, and then constructed the normalizer’s config without it, so the flag (and --ignore / --reject with it) was inert from the initial commit through 678 commits and roughly five months. #1191 fixed that one call site; this constructor removes the shape (#1197).

Forgetting the error configuration in this call cannot compile, just as it cannot in the web service’s struct literal. Note the limit of that guarantee: it binds only callers who choose this constructor. default, new, the lenient/strict/silent presets and Normalizer::new all remain reachable and all supply an error configuration the caller never named, so a new entry point can still elide one and compile. What stops it is a lint, not the type system — tests/it/issue_1197_required_error_config.rs scans the entry-point seams for those shapes and fails the build.

Prefer this over the builder chain at every entry point; the builder remains for library callers that deliberately want the lenient default.

Example

use ferro_hgvs::error_handling::ErrorConfig;
use ferro_hgvs::normalize::{NormalizeConfig, ShuffleDirection};

let config =
    NormalizeConfig::for_entry_point(ShuffleDirection::ThreePrime, ErrorConfig::strict());
assert_eq!(config.shuffle_direction, ShuffleDirection::ThreePrime);
assert!(config.should_reject_ref_mismatch());

pub fn strict() -> Self

Create a config with strict error handling (reject reference mismatches)

pub fn lenient() -> Self

Create a config with lenient error handling (warn on reference mismatches)

pub fn silent() -> Self

Create a config with silent error handling (ignore reference mismatches)

pub fn allow_crossing_boundaries(self) -> Self

Allow crossing boundaries

pub fn with_error_mode(self, mode: ErrorMode) -> Self

Set error handling mode

pub fn with_error_config(self, error_config: ErrorConfig) -> Self

Replace the entire error-handling configuration.

pub fn with_error_override( self, error_type: ErrorType, action: ErrorOverride, ) -> Self

Set a specific error type override

pub fn skip_validation(self) -> Self

👎Deprecated since 0.2.0:

Use with_error_mode(ErrorMode::Silent) instead

Disable reference validation (sets RefSeqMismatch to SilentCorrect)

pub fn with_overlap_prevention(self, prevent: bool) -> Self

Set the vestigial prevent_overlap flag.

This builder is retained only for source compatibility with existing callers. The flag has no runtime effect: overlap prevention is handled structurally by normalize_allele, merge_consecutive_edits, and detect_overlap_conflicts. See NormalizeConfig::prevent_overlap for details.

pub fn ref_mismatch_action(&self) -> ResolvedAction

Get the resolved action for reference sequence mismatch

pub fn should_reject_ref_mismatch(&self) -> bool

Returns true if reference mismatches should be rejected

pub fn should_warn_ref_mismatch(&self) -> bool

Returns true if reference mismatches should emit warnings

pub fn variant_exceeds_reference_action(&self) -> ResolvedAction

Get the resolved action for VariantExceedsReference (W5003) — fires when the provider returns fewer bytes than the HGVS interval span (the input violates HGVS spec refseq.md §43). Closes-after: #355.

pub fn should_reject_variant_exceeds_reference(&self) -> bool

Returns true if VariantExceedsReference should be rejected (strict mode default).

pub fn should_warn_variant_exceeds_reference(&self) -> bool

Returns true if VariantExceedsReference should emit a warning (lenient mode default; silent mode suppresses).

pub fn position_past_end_action(&self) -> ResolvedAction

Get the resolved action for PositionPastEnd (W4004).

pub fn should_reject_position_past_end(&self) -> bool

Returns true if past-end positions should be rejected (strict mode).

pub fn should_reject_reduced_capability(&self) -> bool

Returns true if a reduced-capability (no-genomic-data) degradation should be rejected — i.e. strict mode. Unlike the registry-backed spec warnings, ReducedCapabilityNoGenome is an environmental limitation rather than an input defect, so it is not user-overridable per errors-axis; it is simply promoted to an error in strict mode and surfaced as a warning-plus-best-effort otherwise (#1012 item 2).

pub fn should_warn_position_past_end(&self) -> bool

Returns true if past-end positions should emit warnings (lenient mode).

pub fn intronic_bare_transcript_action(&self) -> ResolvedAction

Get the resolved action for IntronicOnBareTranscript (W4007) — fires when an intronic offset appears on a bare transcript reference (NM_ c. / NR_ n. with genomic_context: None). See #486 EINTRONIC.

pub fn should_reject_intronic_bare_transcript(&self) -> bool

Returns true if an intronic offset on a bare transcript should be rejected (strict mode default / errors-axis override).

pub fn should_warn_intronic_bare_transcript(&self) -> bool

Returns true if an intronic offset on a bare transcript should emit a warning (lenient mode default; silent suppresses).

pub fn overlap_conflict_action(&self) -> ResolvedAction

Get the resolved action for OverlapConflictingEdits (W5002).

pub fn should_reject_overlap_conflict(&self) -> bool

Returns true if cis-allele edits with coincident reference bounds should be rejected (strict mode default). Closes #395 item 6 — previously the overlap.rs:88 emit site unconditionally pushed the warning, bypassing the registry’s always_warn_if_not_rejected policy table that declared Strict→Reject.

pub fn unresolvable_centromere_action(&self) -> ResolvedAction

Get the resolved action for UnresolvableCentromere (W4005).

pub fn should_reject_unresolvable_centromere(&self) -> bool

Returns true if an unresolvable cen position should be rejected (strict mode default). A centromere is an assembly-annotated region with no sequence-derivable base, so it cannot be normalized; strict mode promotes the UnresolvableSpecialPosition warning to an error rather than silently echoing the input. See #488.

pub fn transcript_flank_action(&self) -> ResolvedAction

Get the resolved action for TranscriptFlankNotDescribable (W4006).

pub fn should_reject_transcript_flank(&self) -> bool

Returns true if a telomere marker resolving to a transcript-flank position on a genomic-reference c. should be rejected (strict default).

pub fn incomplete_cds_start_action(&self) -> ResolvedAction

Get the resolved action for IncompleteCdsStartReference (W5004) — fires when a c./p./r. variant is described against a transcript whose 5’ CDS is annotated incomplete (cds_start_NF). See #972 Task 5.

pub fn should_reject_incomplete_cds_start(&self) -> bool

Returns true if a c./p./r. variant against a cds_start_NF transcript should be rejected (strict mode default).

pub fn should_warn_incomplete_cds_start(&self) -> bool

Returns true if a c./p./r. variant against a cds_start_NF transcript should emit a warning (lenient mode default; silent suppresses).

pub fn initiator_met_canonicalization_action(&self) -> ResolvedAction

Get the resolved action for InitiatorMetCanonicalization (W3022) — fires when the canonical protein duplication form covers position 1, the initiator methionine. See #92.

pub fn should_warn_initiator_met_canonicalization(&self) -> bool

Returns true if the InitiatorMetCanonicalization advisory should be surfaced as a warning.

W3022 is advisory about ferro’s own output, not a defect in the input: p.Met1dup is spec-canonical — HGVS prioritization requires a duplicating insertion to be described as a duplication (general.md §56-57, protein/insertion.md §20), and the initiator carve-outs are scoped to substitutions that destroy the ATG (protein/substitution.md §49, checklist.md §65), which a dup does not. The normalizer emits the warning whenever the final edit is a Met1-covering duplication, including when the input already was one and nothing was rewritten.

So the base mode must never promote it to an error: strict mode would then refuse the very string strict mode emits, and normalization would stop being idempotent. Reject from the base mode therefore maps to “surface it”, which also keeps strict from being quieter than lenient (ResolvedAction::should_warn is true only for WarnCorrect, i.e. lenient).

Silent mode, and an override resolving to Accept/SilentCorrect (--ignore W3022), suppress it. Before #1196 the push was unconditional, so none of that worked. An explicit Reject override also surfaces it, because the rejection ladder in normalize_core promotes it from the warning list — the same should_warn_* || should_reject_* emission shape the PositionPastEnd and IncompleteCdsStartReference sites use.

pub fn should_reject_initiator_met_canonicalization(&self) -> bool

Returns true if the InitiatorMetCanonicalization advisory should be promoted to a hard error.

Only an explicit Reject override does this — --reject W3022 or [error-handling] reject = ["W3022"]. The base mode never does, for the reasons in Self::should_warn_initiator_met_canonicalization.

This is the one place the distinction matters. action_for collapses strict-mode Default and an explicit Reject into the same ResolvedAction::Reject, so without consulting ErrorConfig::explicit_override the --reject direction of the knob would be inert for this code — reintroducing, for W3022 alone, exactly the defect #1196 exists to remove.

Trait Implementations

impl Clone for NormalizeConfig

fn clone(&self) -> NormalizeConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NormalizeConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NormalizeConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for NormalizeConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for NormalizeConfig

impl PartialEq for NormalizeConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for NormalizeConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.