Struct ValidationReport

Source

pub struct ValidationReport { /* private fields */ }

Expand description

A bounded collection of validation violations and skipped occurrences.

Reports retain structured violation metadata. Callers must ensure that violation parameters contain no rejected input or sensitive values derived from it.

§Examples

use qubit_validator::ValidationReport;
use qubit_validator::ValidatorId;
use qubit_validator::Violation;
use qubit_validator::ViolationCode;
use qubit_validator::ValidationOutcome;
use qubit_validator::ValidationOutcomeError;
use qubit_validator::ValidationPath;

let mut report = ValidationReport::new();
let violation = Violation::new(
    ValidatorId::new("example.non_empty"),
    ViolationCode::new("text.empty"),
);
let recorded = report.record_outcome(
    0,
    ValidationPath::root(),
    ValidationOutcome::invalid(vec![violation])?,
)?;
assert!(recorded.complete());
assert!(!report.is_valid());
assert_eq!(report.violations().len(), 1);

Implementations§

Source §

impl ValidationReport

Source

pub fn with_limits(limits: ValidationLimits) -> Self

Creates an empty report with explicit collection limits.

Limits apply only to retained violation and skipped-entry counts, not to validation work or total memory use. See crate::ValidationLimits for the resource boundaries callers must enforce separately.

§Parameters

limits: Independent limits for retained violations and skipped entries. None leaves the corresponding count unbounded.

§Returns

An empty, untruncated report configured with limits.

Source

pub fn new() -> Self

Creates an empty report without collection limits.

Both retained violation and skipped-entry counts are unbounded. Use Self::with_limits when either count needs an explicit limit.

§Returns

An empty, untruncated report with both collection limits set to None.

Source

pub fn mark_truncated(&mut self)

Marks that a caller stopped validation before it was exhaustive.

Use this when the execution policy stopped before the report’s own collection limits rejected an outcome.

Source

pub fn record_outcome( &mut self, occurrence: usize, path: ValidationPath, outcome: ValidationOutcome, ) -> Result<RecordedOutcome, ValidationOutcomeError>

Adds the result of one validation occurrence while preserving its invariants.

Occurrences must be submitted in non-decreasing order; multiple outcomes may use the same occurrence. Violations and skipped entries are stored in submission order and obey their respective report limits. The violation limit counts each retained invalid violation once; skipped outcomes refer to those failures by ID and consume no additional violation capacity. For an invalid outcome, path prefixes each relative violation path once.

§Parameters

occurrence: Non-decreasing position of this validation occurrence.
path: Path to the value for which the outcome was produced.
outcome: Validation result and any associated failure metadata.

§Errors

Returns an outcome shape error for malformed outcomes, duplicate prerequisite IDs, IDs not retained by this report, or an occurrence lower than the last successfully submitted occurrence. Such an error leaves this report unchanged.

For a valid outcome, the path is ignored and not retained. Callers may pass the root path to avoid cloning a field path. The occurrence still participates in the ordering check.

§Returns

Returns whether the whole outcome fits the configured limits and the IDs of failures retained from that outcome. A failed-prerequisite skip is retained only when every reference is valid and it fits the skip limit.

Source

pub fn is_valid(&self) -> bool

Returns whether the recorded report contains no failures and is not marked incomplete. This evaluates recorded content only; it cannot establish that the caller ran every intended check.

§Returns

Returns true when there are no recorded violations, no occurrence was skipped because of a failed prerequisite, and the report was not truncated. A newly created empty report therefore returns true.

Use this result as a basis for acceptance only after the caller has confirmed that the entire intended validation run completed successfully. A completed zero-rule plan may have an empty, valid report, but a newly created report alone does not prove completion. This method cannot know whether rules remain unsubmitted. If the caller stops validation early while checks may remain, it must call Self::mark_truncated so the report is marked incomplete. Capacity limits mark the report as truncated automatically only when an outcome cannot be retained in full. Merely filling the available capacity does not mark the report as truncated.

Source

pub fn violations(&self) -> &[Violation]

Returns all violations in occurrence order.

Source

pub fn failures(&self) -> impl Iterator<Item = &Violation> + '_

Iterates over retained original violations in occurrence order.

§Returns

Every retained original failure in the same count reported by Self::failure_count.

Source

pub const fn failure_count(&self) -> usize

Returns the number of retained original violations.

Source

pub fn failure(&self, id: FailureId) -> Option<&Violation>

Returns the violation associated with a failure ID from this report.

§Parameters

id: Failure identifier whose retained violation is requested.

§Returns

Returns Some when id was issued by this report and remains retained; otherwise returns None.

Source

pub fn failure_occurrence(&self, id: FailureId) -> Option<usize>

Returns the occurrence associated with a retained failure ID.

Only failures retained in this report have an occurrence. IDs from a different report and failures rejected by the violation capacity return None.

§Parameters

id: Failure identifier whose retained occurrence is requested.

§Examples

use qubit_validator::{ValidationOutcome, ValidationPath, ValidationReport};
use qubit_validator::{ValidatorId, Violation, ViolationCode};

let mut report = ValidationReport::new();
let violation = Violation::new(
    ValidatorId::new("example.required"),
    ViolationCode::new("value.missing"),
);
let receipt = report.record_outcome(
    2,
    ValidationPath::root(),
    ValidationOutcome::invalid(vec![violation])?,
)?;
let failure_id = receipt.failure_ids()[0];
assert_eq!(report.failure_occurrence(failure_id), Some(2));

Source

pub fn failures_with_occurrences( &self, ) -> impl Iterator<Item = (usize, &Violation)> + '_

Iterates over retained failures and their occurrences in report order.

The iterator contains only failures retained within the configured violation capacity. Multiple failures from one outcome share an occurrence, and separate outcomes may use the same occurrence.

Source