use super::*;
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum DiagnosticSeverity {
Warning,
Error,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ComparisonDiagnostic {
pub code: String,
pub severity: DiagnosticSeverity,
}
impl ComparisonDiagnostic {
#[must_use]
pub fn message(&self) -> &'static str {
match self.code.as_str() {
"MissingName" => "set a non-empty comparison plan name",
"MissingTarget" => "configure a target source or selector",
"MissingAgainst" => "configure at least one comparison source or selector",
"MissingComparator" => "configure at least one comparator",
"FutureWindowExcluded" => "advance known-at or provide an earlier-available window",
"MissingEventTime" => {
"provide event timestamps or choose processing-position normalization"
}
"TemporalAxisMismatch" => "align the plan axis with the recorded window axis",
"SelfComparison" => "make target and comparison selectors disjoint",
"RuntimeNonSerializablePlan" => "use serializable selectors for portable execution",
_ => "inspect the prepared artifact and plan fields for the invalid contract",
}
}
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ComparatorSummary {
#[serde(rename = "comparatorName")]
pub comparator_name: String,
#[serde(rename = "rowCount")]
pub row_count: usize,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct RowRange {
pub start: i64,
pub end: i64,
pub axis: TemporalAxis,
pub clock: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct RowPoint {
pub axis: TemporalAxis,
pub magnitude: i64,
pub clock: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum ComparisonSide {
Target,
Against,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum ContainmentStatus {
Contained,
NotContained,
LeftOverhang,
RightOverhang,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum LeadLagTransition {
Start,
End,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum LeadLagDirection {
Equal,
TargetLeads,
TargetLags,
MissingComparison,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct LeadLagSummary {
#[serde(rename = "transition")]
pub transition: LeadLagTransition,
#[serde(rename = "axis")]
pub axis: TemporalAxis,
#[serde(rename = "toleranceMagnitude")]
pub tolerance_magnitude: i64,
#[serde(rename = "rowCount")]
pub row_count: usize,
#[serde(rename = "targetLeadCount")]
pub target_lead_count: usize,
#[serde(rename = "targetLagCount")]
pub target_lag_count: usize,
#[serde(rename = "equalCount")]
pub equal_count: usize,
#[serde(rename = "missingComparisonCount")]
pub missing_comparison_count: usize,
#[serde(rename = "outsideToleranceCount")]
pub outside_tolerance_count: usize,
#[serde(rename = "minimumDeltaMagnitude")]
pub minimum_delta_magnitude: Option<i64>,
#[serde(rename = "maximumDeltaMagnitude")]
pub maximum_delta_magnitude: Option<i64>,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct CoverageSummary {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
#[serde(rename = "targetMagnitude")]
pub target_magnitude: f64,
#[serde(rename = "targetMagnitudeExact")]
pub target_magnitude_exact: i128,
#[serde(rename = "coveredMagnitude")]
pub covered_magnitude: f64,
#[serde(rename = "coveredMagnitudeExact")]
pub covered_magnitude_exact: i128,
#[serde(rename = "coverageRatio")]
pub coverage_ratio: f64,
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum ComparisonRowKind {
Overlap,
Residual,
Missing,
Coverage,
Gap,
SymmetricDifference,
Containment,
LeadLag,
AsOf,
}
impl ComparisonRowKind {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Overlap => "overlap",
Self::Residual => "residual",
Self::Missing => "missing",
Self::Coverage => "coverage",
Self::Gap => "gap",
Self::SymmetricDifference => "symmetricDifference",
Self::Containment => "containment",
Self::LeadLag => "leadLag",
Self::AsOf => "asOf",
}
}
}
impl std::fmt::Display for ComparisonRowKind {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error("unsupported comparison row kind '{0}'")]
pub struct ComparisonRowKindParseError(String);
impl std::str::FromStr for ComparisonRowKind {
type Err = ComparisonRowKindParseError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
match value {
"overlap" => Ok(Self::Overlap),
"residual" => Ok(Self::Residual),
"missing" => Ok(Self::Missing),
"coverage" => Ok(Self::Coverage),
"gap" => Ok(Self::Gap),
"symmetricDifference" | "symmetric-difference" => Ok(Self::SymmetricDifference),
"containment" => Ok(Self::Containment),
"leadLag" | "lead-lag" => Ok(Self::LeadLag),
"asOf" | "asof" => Ok(Self::AsOf),
_ => Err(ComparisonRowKindParseError(value.to_owned())),
}
}
}
#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub enum ComparisonFinality {
Final,
Provisional,
Revised,
Retracted,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ComparisonRowFinality {
#[serde(rename = "rowType")]
pub row_type: String,
#[serde(rename = "rowId")]
pub row_id: String,
pub finality: ComparisonFinality,
pub reason: String,
pub version: u32,
#[serde(rename = "supersedesRowId")]
pub supersedes_row_id: Option<String>,
}
impl ComparisonRowFinality {
pub fn row_kind(&self) -> Result<ComparisonRowKind, ComparisonRowKindParseError> {
self.row_type.parse()
}
}
#[derive(Clone, Copy, Debug)]
pub struct ComparisonRowWithFinality<'a, R> {
pub row: &'a R,
pub metadata: &'a ComparisonRowFinality,
}
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error(
"inconsistent {family:?} row metadata at index {metadata_index}: expected \
{expected_count} {expected_kind:?} records, found {actual_count}; actual \
kind: {actual_kind:?}"
)]
pub struct ComparisonRowMetadataError {
pub family: ComparisonRowKind,
pub metadata_index: usize,
pub expected_count: usize,
pub actual_count: usize,
pub expected_kind: ComparisonRowKind,
pub actual_kind: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum AsOfDirection {
Previous,
Next,
Nearest,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub enum AsOfMatchStatus {
Exact,
Matched,
NoMatch,
FutureRejected,
Ambiguous,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct OverlapRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
#[serde(rename = "againstRecordIds")]
pub against_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ResidualRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct MissingRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
#[serde(rename = "againstRecordIds")]
pub against_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct CoverageRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
#[serde(rename = "targetMagnitude")]
pub target_magnitude: i64,
#[serde(rename = "coveredMagnitude")]
pub covered_magnitude: i64,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
#[serde(rename = "againstRecordIds")]
pub against_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct GapRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SymmetricDifferenceRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
pub side: ComparisonSide,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
#[serde(rename = "againstRecordIds")]
pub against_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ContainmentRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub range: RowRange,
pub status: ContainmentStatus,
#[serde(rename = "targetRecordIds")]
pub target_record_ids: Vec<String>,
#[serde(rename = "containerRecordIds")]
pub container_record_ids: Vec<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct LeadLagRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub transition: LeadLagTransition,
pub axis: TemporalAxis,
#[serde(rename = "targetPoint")]
pub target_point: RowPoint,
#[serde(rename = "comparisonPoint")]
pub comparison_point: Option<RowPoint>,
#[serde(rename = "deltaMagnitude")]
pub delta_magnitude: Option<i64>,
#[serde(rename = "toleranceMagnitude")]
pub tolerance_magnitude: i64,
#[serde(rename = "isWithinTolerance")]
pub is_within_tolerance: bool,
pub direction: LeadLagDirection,
#[serde(rename = "targetRecordId")]
pub target_record_id: String,
#[serde(rename = "comparisonRecordId")]
pub comparison_record_id: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct AsOfRow {
#[serde(rename = "windowName")]
pub window_name: String,
pub key: String,
pub partition: Option<String>,
pub axis: TemporalAxis,
pub direction: AsOfDirection,
#[serde(rename = "targetPoint")]
pub target_point: RowPoint,
#[serde(rename = "matchedPoint")]
pub matched_point: Option<RowPoint>,
#[serde(rename = "distanceMagnitude")]
pub distance_magnitude: Option<i64>,
#[serde(rename = "toleranceMagnitude")]
pub tolerance_magnitude: i64,
pub status: AsOfMatchStatus,
#[serde(rename = "targetRecordId")]
pub target_record_id: String,
#[serde(rename = "matchedRecordId")]
pub matched_record_id: Option<String>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ComparisonRows {
pub overlap: Arc<Vec<OverlapRow>>,
pub residual: Arc<Vec<ResidualRow>>,
pub missing: Arc<Vec<MissingRow>>,
pub coverage: Arc<Vec<CoverageRow>>,
pub gap: Arc<Vec<GapRow>>,
#[serde(rename = "symmetricDifference")]
pub symmetric_difference: Arc<Vec<SymmetricDifferenceRow>>,
pub containment: Arc<Vec<ContainmentRow>>,
#[serde(rename = "leadLag")]
pub lead_lag: Arc<Vec<LeadLagRow>>,
#[serde(rename = "asOf")]
pub as_of: Arc<Vec<AsOfRow>>,
}
impl Default for ComparisonRows {
fn default() -> Self {
Self {
overlap: Arc::new(Vec::new()),
residual: Arc::new(Vec::new()),
missing: Arc::new(Vec::new()),
coverage: Arc::new(Vec::new()),
gap: Arc::new(Vec::new()),
symmetric_difference: Arc::new(Vec::new()),
containment: Arc::new(Vec::new()),
lead_lag: Arc::new(Vec::new()),
as_of: Arc::new(Vec::new()),
}
}
}
#[derive(Default)]
pub(super) struct RowAccumulator {
pub(super) overlap: Vec<OverlapRow>,
pub(super) residual: Vec<ResidualRow>,
pub(super) missing: Vec<MissingRow>,
pub(super) coverage: Vec<CoverageRow>,
pub(super) gap: Vec<GapRow>,
pub(super) symmetric_difference: Vec<SymmetricDifferenceRow>,
pub(super) containment: Vec<ContainmentRow>,
pub(super) lead_lag: Vec<LeadLagRow>,
pub(super) as_of: Vec<AsOfRow>,
}
impl RowAccumulator {
pub(super) fn into_shared(self) -> ComparisonRows {
ComparisonRows {
overlap: Arc::new(self.overlap),
residual: Arc::new(self.residual),
missing: Arc::new(self.missing),
coverage: Arc::new(self.coverage),
gap: Arc::new(self.gap),
symmetric_difference: Arc::new(self.symmetric_difference),
containment: Arc::new(self.containment),
lead_lag: Arc::new(self.lead_lag),
as_of: Arc::new(self.as_of),
}
}
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct ComparisonResult {
pub schema: String,
#[serde(rename = "schemaVersion")]
pub schema_version: u32,
pub artifact: String,
#[serde(skip)]
pub plan: ComparisonPlan,
#[serde(rename = "planName")]
pub plan_name: String,
#[serde(rename = "isValid")]
pub is_valid: bool,
pub diagnostics: Vec<ComparisonDiagnostic>,
pub prepared: Option<Value>,
pub aligned: Option<Value>,
#[serde(rename = "knownAt")]
pub known_at: Option<RowPoint>,
#[serde(rename = "evaluationHorizon")]
pub evaluation_horizon: Option<RowPoint>,
#[serde(rename = "comparatorSummaries")]
pub comparator_summaries: Vec<ComparatorSummary>,
#[serde(rename = "coverageSummaries")]
pub coverage_summaries: Vec<CoverageSummary>,
pub rows: ComparisonRows,
#[serde(skip)]
pub overlap_rows: Arc<Vec<OverlapRow>>,
#[serde(skip)]
pub residual_rows: Arc<Vec<ResidualRow>>,
#[serde(skip)]
pub missing_rows: Arc<Vec<MissingRow>>,
#[serde(skip)]
pub coverage_rows: Arc<Vec<CoverageRow>>,
#[serde(skip)]
pub gap_rows: Arc<Vec<GapRow>>,
#[serde(skip)]
pub symmetric_difference_rows: Arc<Vec<SymmetricDifferenceRow>>,
#[serde(skip)]
pub containment_rows: Arc<Vec<ContainmentRow>>,
#[serde(skip)]
pub lead_lag_rows: Arc<Vec<LeadLagRow>>,
#[serde(skip)]
pub lead_lag_summaries: Vec<LeadLagSummary>,
#[serde(skip)]
pub as_of_rows: Arc<Vec<AsOfRow>>,
#[serde(rename = "rowFinalities")]
pub row_finalities: Vec<ComparisonRowFinality>,
#[serde(rename = "extensionMetadata")]
pub extension_metadata: Vec<ComparisonExtensionMetadata>,
}
impl ComparisonResult {
pub fn overlap_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, OverlapRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::Overlap,
self.rows.overlap.as_slice(),
)
}
pub fn residual_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, ResidualRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::Residual,
self.rows.residual.as_slice(),
)
}
pub fn missing_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, MissingRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::Missing,
self.rows.missing.as_slice(),
)
}
pub fn coverage_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, CoverageRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::Coverage,
self.rows.coverage.as_slice(),
)
}
pub fn gap_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, GapRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(self, ComparisonRowKind::Gap, self.rows.gap.as_slice())
}
pub fn symmetric_difference_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, SymmetricDifferenceRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::SymmetricDifference,
self.rows.symmetric_difference.as_slice(),
)
}
pub fn containment_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, ContainmentRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::Containment,
self.rows.containment.as_slice(),
)
}
pub fn lead_lag_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, LeadLagRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(
self,
ComparisonRowKind::LeadLag,
self.rows.lead_lag.as_slice(),
)
}
pub fn as_of_rows_with_finality(
&self,
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'_, AsOfRow>>,
ComparisonRowMetadataError,
> {
row_finality_pairs(self, ComparisonRowKind::AsOf, self.rows.as_of.as_slice())
}
fn row_family_layouts(&self) -> [(ComparisonRowKind, usize); 9] {
[
(ComparisonRowKind::Overlap, self.rows.overlap.len()),
(ComparisonRowKind::Residual, self.rows.residual.len()),
(ComparisonRowKind::Missing, self.rows.missing.len()),
(ComparisonRowKind::Coverage, self.rows.coverage.len()),
(ComparisonRowKind::Gap, self.rows.gap.len()),
(
ComparisonRowKind::SymmetricDifference,
self.rows.symmetric_difference.len(),
),
(ComparisonRowKind::Containment, self.rows.containment.len()),
(ComparisonRowKind::LeadLag, self.rows.lead_lag.len()),
(ComparisonRowKind::AsOf, self.rows.as_of.len()),
]
}
fn row_family_bounds(&self, kind: ComparisonRowKind) -> (usize, usize) {
let mut start = 0;
for (candidate, count) in self.row_family_layouts() {
if candidate == kind {
return (start, count);
}
start += count;
}
unreachable!("all comparison row kinds have a canonical layout")
}
fn validate_row_metadata_layout(&self) -> Result<(), ComparisonRowMetadataError> {
let layouts = self.row_family_layouts();
let expected_total = layouts.iter().map(|(_, count)| count).sum::<usize>();
let actual_total = self.row_finalities.len();
let mut start = 0;
for (kind, count) in layouts {
let end = start + count;
let available_end = end.min(actual_total);
let metadata = &self.row_finalities[start.min(actual_total)..available_end];
if let Some((relative_index, actual)) = metadata
.iter()
.enumerate()
.find(|(_, item)| item.row_kind().ok() != Some(kind))
{
return Err(ComparisonRowMetadataError {
family: kind,
metadata_index: start + relative_index,
expected_count: count,
actual_count: metadata
.iter()
.filter(|item| item.row_kind().ok() == Some(kind))
.count(),
expected_kind: kind,
actual_kind: Some(actual.row_type.clone()),
});
}
if available_end < end {
return Err(ComparisonRowMetadataError {
family: kind,
metadata_index: available_end,
expected_count: count,
actual_count: available_end.saturating_sub(start),
expected_kind: kind,
actual_kind: None,
});
}
start = end;
}
if actual_total > expected_total {
let (family, expected_count) = layouts[layouts.len() - 1];
let family_start = expected_total - expected_count;
return Err(ComparisonRowMetadataError {
family,
metadata_index: expected_total,
expected_count,
actual_count: actual_total - family_start,
expected_kind: family,
actual_kind: self
.row_finalities
.get(expected_total)
.map(|metadata| metadata.row_type.clone()),
});
}
Ok(())
}
}
fn row_finality_pairs<'a, R>(
result: &'a ComparisonResult,
kind: ComparisonRowKind,
rows: &'a [R],
) -> Result<
impl ExactSizeIterator<Item = ComparisonRowWithFinality<'a, R>> + 'a,
ComparisonRowMetadataError,
> {
result.validate_row_metadata_layout()?;
let (start, count) = result.row_family_bounds(kind);
debug_assert_eq!(rows.len(), count);
let metadata = &result.row_finalities[start..start + count];
Ok(rows
.iter()
.zip(metadata)
.map(|(row, metadata)| ComparisonRowWithFinality { row, metadata }))
}
#[cfg(test)]
mod tests {
use super::ComparisonRowKind;
#[test]
fn row_kinds_parse_canonical_labels_and_rust_0_1_0_aliases() {
let cases = [
("overlap", ComparisonRowKind::Overlap, "overlap"),
("residual", ComparisonRowKind::Residual, "residual"),
("missing", ComparisonRowKind::Missing, "missing"),
("coverage", ComparisonRowKind::Coverage, "coverage"),
("gap", ComparisonRowKind::Gap, "gap"),
(
"symmetricDifference",
ComparisonRowKind::SymmetricDifference,
"symmetricDifference",
),
(
"symmetric-difference",
ComparisonRowKind::SymmetricDifference,
"symmetricDifference",
),
("containment", ComparisonRowKind::Containment, "containment"),
("leadLag", ComparisonRowKind::LeadLag, "leadLag"),
("lead-lag", ComparisonRowKind::LeadLag, "leadLag"),
("asOf", ComparisonRowKind::AsOf, "asOf"),
("asof", ComparisonRowKind::AsOf, "asOf"),
];
for (label, expected_kind, canonical_label) in cases {
let kind = label.parse::<ComparisonRowKind>().expect("known row kind");
assert_eq!(kind, expected_kind, "label {label}");
assert_eq!(kind.as_str(), canonical_label, "label {label}");
}
assert!("lead_lag".parse::<ComparisonRowKind>().is_err());
}
}