Skip to main content

dataprof_runtime/
quality_gate.rs

1//! Declarative quality gates over a [`ProfileReport`].
2//!
3//! A pipeline that wants to stop on a bad extract has to turn a report into a
4//! decision. Doing that by hand means re-deciding, at every call site, what an
5//! absent metric means, whether a sampled scan can answer a question about the
6//! whole source, and which number belongs in the log line. This module makes
7//! that decision data: a [`QualityPolicy`] states the requirements and
8//! [`QualityPolicy::evaluate`] returns a [`GateResult`] describing what was
9//! checked and what happened.
10//!
11//! Evaluation never exits the process, prints, or mutates the report.
12//!
13//! # Verdicts and evidence
14//!
15//! The verdict is three-valued, because a decision and the evidence behind it
16//! are separate facts. A requirement about the full source cannot be *passed*
17//! by a truncated or sampled scan: nothing was observed that rules the failure
18//! out. It can still be *failed* by one, when the scan witnessed a violation
19//! that more scanning cannot retract. So:
20//!
21//! - [`Verdict::Fail`] — at least one requirement was conclusively violated.
22//! - [`Verdict::Inconclusive`] — nothing was violated, and at least one
23//!   requirement could not be evaluated (a metric was not analyzed, a column
24//!   was not profiled, the evidence does not reach as far as the requirement).
25//! - [`Verdict::Pass`] — every requirement was evaluated and met.
26//!
27//! `Fail` wins over `Inconclusive`: a witnessed violation is a decision.
28//!
29//! # Baseline-relative rules
30//!
31//! [`QualityPolicy::evaluate_against`] also reads a saved baseline, through the
32//! [`ReportDelta`] between it and the report, and evaluates rules about change:
33//! how far the overall score or a dimension score may drop, and how far a
34//! column's null percentage may rise, in points, how far a column's
35//! distinct count may fall, in percent of the baseline's (#1026), and how far
36//! the row count may fall or grow, in percent of the baseline's (#1291). A
37//! change is decided only when both sides measured the same thing the same
38//! way. Otherwise the rule is left unevaluated, naming what differs:
39//!
40//! - for the validity score, and for the overall score when validity is
41//!   assessed on one side only, pattern detection run on one side only
42//!   ([`NotEvaluated::SettingChanged`] on `metric_packs`): validity scores
43//!   the detected patterns. This names the cause ahead of the reasons below
44//!   that name its effect, and needs both sides to record their packs;
45//! - a value the baseline does not carry ([`NotEvaluated::NotInBaseline`]);
46//! - for a distinct count, an estimate on either side, or a count either
47//!   side did not record as exact ([`NotEvaluated::ApproximateCount`]);
48//! - for a score or the row count, a different column set
49//!   ([`NotEvaluated::SchemaChanged`]). A dataset-level rule has the columns
50//!   as its subject, so a column that appeared or vanished changes what is
51//!   measured, not how good it is. A
52//!   column's own rules stay decisive, and a new column has no baseline rule
53//!   until a policy names it;
54//! - for the overall score, a different set of assessed dimensions
55//!   ([`NotEvaluated::DimensionsChanged`]), since it averages those;
56//! - a measurement definition the rule depends on that the two sides do not
57//!   both record identically ([`NotEvaluated::DefinitionNotComparable`]);
58//! - a setting that moves the score on unchanged data, such as the score
59//!   weights or a semantic hint, that differs or that either side did not
60//!   record ([`NotEvaluated::SettingChanged`],
61//!   [`NotEvaluated::SettingUnrecorded`]). The declared temporal pairs are
62//!   compared as pairs when both sides record them (0.14+), and otherwise
63//!   agree only when neither side declared any. The timeliness clock is such
64//!   a setting too: two
65//!   reports measured against different reference dates are comparable only
66//!   when the policy declares a rolling clock
67//!   ([`QualityPolicy::timeliness_clock`]);
68//! - under [`PolicyScope::FullSource`], evidence on either side that does not
69//!   cover the whole source. The row count rules are the exception: a scan
70//!   that stopped early read a lower bound of its source's rows, so it still
71//!   settles the outcome that more rows could not reverse, as
72//!   [`QualityPolicy::min_rows`] does (see
73//!   [`QualityPolicy::max_row_count_drop`]). A score drop rule reads a score
74//!   computed over a retained sample of a fully read source as its recorded
75//!   whole-source interval, as the minimum score rules do, and decides when
76//!   the change those intervals allow lies wholly on one side of the
77//!   allowance (see [`QualityPolicy::max_quality_score_drop`]).
78//!
79//! A schema change from the baseline is reported as a [`Diagnostic`] in the
80//! result's `baseline.diagnostics`, whatever the policy states: a column added,
81//! removed, retyped while holding values on both sides, or holding only nulls
82//! where the baseline had values. A diagnostic is a warning, never a fourth
83//! verdict, and does not move the verdict.
84//!
85//! Rules about the column set decide on whether a column is there.
86//! [`QualityPolicy::require_columns`] names columns the report must have;
87//! [`QualityPolicy::forbid_removed_columns`] requires every baseline column,
88//! and [`QualityPolicy::forbid_added_columns`] allows no column the baseline
89//! lacked. A missing column fails such a rule only when the side without it
90//! shows its source lacks it: that side recorded its column selection, the
91//! selection included the column, and its column set covers the whole source.
92//! A source that declares its columns up front (a CSV header, a Parquet
93//! schema, a DataFrame, a query result) covers it however few rows were read;
94//! for JSON, JSONL and streams the columns are the keys of the records read,
95//! so only a scan of every record does. Otherwise the rule is unevaluated:
96//! [`NotEvaluated::SettingChanged`] or [`NotEvaluated::SettingUnrecorded`] on
97//! the setting `columns`, [`NotEvaluated::ColumnNotProfiled`] for a required
98//! column the run did not select, or [`NotEvaluated::EvidenceIncomplete`].
99//!
100//! # Unique columns
101//!
102//! [`QualityPolicy::unique_columns`] fails a column whose non-null values
103//! repeat, such as a reused business key (#904). It reads the column's exact
104//! distinct count against its non-null values, so a repeat the scan witnessed
105//! fails whatever the scan missed, and none passes under
106//! [`PolicyScope::FullSource`] only on a scan that covered the source. An
107//! estimated distinct count settles neither direction
108//! ([`NotEvaluated::ApproximateCount`]).
109//!
110//! # Freshness
111//!
112//! [`QualityPolicy::max_date_age`] fails a column whose newest date lies too
113//! many days before the timeliness reference date the report recorded
114//! (#1290): a feed that stopped moving keeps passing every rule above, since
115//! the same rows keep their counts, nulls and scores. A newest date read on
116//! part of a source can only be overtaken by a newer one, so a fresh date
117//! passes on any scan of a column whose source declared a date type. A
118//! column typed from text passes only on a scan that read every row, since
119//! rows left unread could type it as text (#1333). A stale one fails only
120//! when the values behind it cover the column, which a report computing its
121//! date statistics over every value read does on a complete scan (#1297).
122//! Slash dates are the exception:
123//! their day and month order is decided from the values read, so a fresh one
124//! read on part of a column passes only once that order cannot change.
125//!
126//! [`QualityPolicy::max_date_gap`] fails a column whose dates hold a hole
127//! inside their range (#1300): a daily file that lost a period from its
128//! middle keeps its newest date and most of its rows. The values that were
129//! not read can fill a hole the read ones show, or open one at the edge of
130//! the range, so under [`PolicyScope::FullSource`] the rule decides only on a
131//! scan that covered the column.
132//!
133//! # Forbidden findings
134//!
135//! [`QualityPolicy::forbid_findings`] turns a findings code into a rule: the
136//! report must hold no finding with it (#1066). The findings are derived as
137//! [`ProfileReport::findings`] derives them, and a failed check carries them,
138//! column and evidence included. How far a partial scan answers the rule
139//! under [`PolicyScope::FullSource`] depends on what the finding is about:
140//!
141//! - how the source was read (`partial_scan`, `delimiter_ambiguous`,
142//!   `header_not_split`): decided whatever the scan covered;
143//! - something rows witness (`duplicate_rows`, `key_duplicates`,
144//!   `future_dates`, `temporal_order_violations`, `ragged_rows`,
145//!   `records_skipped`, `unterminated_quote`): a finding fails, and no finding
146//!   passes only a scan that covered the source, as with `max_duplicate_rows`;
147//! - a share of a column's values (`null_heavy`, `all_null`,
148//!   `constant_column`, `mixed_types`, `locale_numbers`, `sensitive_pattern`):
149//!   decided only on a scan that covered the source, as with the score rules.
150//!   `mixed_types`, `locale_numbers` and `sensitive_pattern` read each
151//!   column's retained value sample, so on a source larger than the sample
152//!   they stay `quality_sampled` even when every row was read.
153//!
154//! A findings rule that could not look at all of the report and found nothing
155//! leaves the check [`NotEvaluated::FindingNotEvaluated`], carrying the
156//! rule's own reasons.
157//!
158//! # Example
159//!
160//! ```no_run
161//! use dataprof_runtime::{ProfileReport, QualityPolicy, Verdict};
162//!
163//! fn gate(report: &ProfileReport) -> Result<bool, Box<dyn std::error::Error>> {
164//!     let result = QualityPolicy::new()
165//!         .min_quality_score(90.0)
166//!         .max_null_count("customer_id", 0)
167//!         .max_null_percentage_any(20.0)
168//!         .require_quality()
169//!         .evaluate(report)?;
170//!
171//!     if result.verdict != Verdict::Pass {
172//!         for violation in result.violations() {
173//!             eprintln!("{}: {}", violation.code, violation.message);
174//!         }
175//!     }
176//!     Ok(result.passed())
177//! }
178//! ```
179
180use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
181use std::fmt;
182
183use dataprof_core::serde_helpers::rounded_2;
184use dataprof_core::{
185    ColumnProfile, ColumnStats, DataType, DateStatistics, ExecutionMetadata, MetricPack,
186    NativeType, QualityDimension, SlashDateOrder,
187};
188use dataprof_metrics::{
189    QualityAssessment, ScoreBounds, ScoreInterval, TimelinessClock, TimelinessClockMode,
190};
191use serde::Serialize;
192
193use crate::findings::{
194    Finding, FindingCode, FindingPolicy, FindingsInput, FindingsResult, NotEvaluatedReason,
195    UnevaluatedRule,
196};
197use crate::profile_report::{
198    ColumnSelection, MetricSemantics, ProfileReport, QualityAnalysisStatus, ReportGenerator,
199    SourceIdentity,
200};
201use crate::report_delta::{
202    ColumnChange, ColumnSide, ConfigurationComparison, RecordedHints, ReportDelta, ReportPair,
203    ReportSide, SchemaChange, ScoreChange, Sides,
204};
205
206/// Scores and percentages in a report live on a 0..=100 scale, and so do the
207/// thresholds compared against them.
208const PERCENTAGE_MAX: f64 = 100.0;
209
210/// A policy that cannot be evaluated as written.
211///
212/// Raised before any requirement is checked: an unsatisfiable threshold is a
213/// configuration mistake, and reporting it as a failed gate would blame the
214/// data for it.
215#[derive(Debug, Clone, PartialEq)]
216#[non_exhaustive]
217pub enum PolicyError {
218    /// A threshold on the 0..=100 percentage scale fell outside it, or was not
219    /// a finite number. Quality scores and null percentages are percentages,
220    /// not 0..1 ratios. A row count growth threshold has no upper end, so for
221    /// [`CheckCode::MaxRowCountGrowth`] only a negative or non-finite value
222    /// is out of range.
223    #[non_exhaustive]
224    ThresholdOutOfRange {
225        /// The requirement that carried it.
226        code: CheckCode,
227        /// The column or dimension the requirement names, when it names one.
228        subject: Option<String>,
229        /// The value as supplied.
230        value: f64,
231    },
232    /// The policy states no requirement at all. An empty policy passes every
233    /// report, which is never what a gate is for.
234    NoRequirements,
235    /// The policy states a rule about change, and was evaluated without a
236    /// baseline to measure the change from. Use
237    /// [`QualityPolicy::evaluate_against`].
238    BaselineRequired,
239}
240
241impl fmt::Display for PolicyError {
242    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
243        match self {
244            Self::ThresholdOutOfRange {
245                code,
246                subject,
247                value,
248            } => {
249                write!(f, "{code} threshold ")?;
250                if let Some(subject) = subject {
251                    write!(f, "for `{subject}` ")?;
252                }
253                if *code == CheckCode::MaxRowCountGrowth {
254                    write!(f, "must be a percentage of at least 0, got {value}")
255                } else {
256                    write!(
257                        f,
258                        "must be a percentage between 0 and {PERCENTAGE_MAX}, got {value}"
259                    )
260                }
261            }
262            Self::NoRequirements => write!(
263                f,
264                "policy states no requirement; a gate must check something"
265            ),
266            Self::BaselineRequired => write!(
267                f,
268                "policy states a rule about change, which needs a baseline report to compare \
269                 against"
270            ),
271        }
272    }
273}
274
275impl std::error::Error for PolicyError {}
276
277/// How a rule about change reads the timeliness clocks of the two reports
278/// (#1024).
279///
280/// The timeliness score counts dates later than a reference date and dates
281/// older than a maximum age before it, so the same data scores differently
282/// against another date. Every report records its clock, and the policy
283/// states which difference between two clocks still measures the same thing.
284#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize)]
285#[serde(rename_all = "snake_case")]
286#[non_exhaustive]
287pub enum TimelinessClockRule {
288    /// Both reports must record the same reference date, time zone and
289    /// maximum age. The default, and what a pipeline that passes a fixed
290    /// `reference_date` to every run wants.
291    #[default]
292    Fixed,
293    /// Each report measures against its own run date: when both read a
294    /// rolling clock, in the same time zone and with the same maximum age,
295    /// their reference dates may differ and the scores are compared as
296    /// measured. A fixed clock on either side still needs the same date on
297    /// both.
298    Rolling,
299}
300
301impl fmt::Display for TimelinessClockRule {
302    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
303        match self {
304            Self::Fixed => write!(f, "fixed"),
305            Self::Rolling => write!(f, "rolling"),
306        }
307    }
308}
309
310impl std::str::FromStr for TimelinessClockRule {
311    type Err = String;
312
313    fn from_str(s: &str) -> Result<Self, Self::Err> {
314        match s {
315            "fixed" => Ok(Self::Fixed),
316            "rolling" => Ok(Self::Rolling),
317            _ => Err(format!(
318                "Unknown timeliness clock: {s}. Valid clocks: fixed, rolling"
319            )),
320        }
321    }
322}
323
324/// What the requirements in a policy are statements about.
325///
326/// A profiler reads what it is given. Whether that supports a claim about the
327/// whole source depends on what is being claimed, so the policy says which
328/// question it asks rather than letting the evaluator guess.
329#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize)]
330#[serde(rename_all = "snake_case")]
331#[non_exhaustive]
332pub enum PolicyScope {
333    /// The entire source. A requirement is evaluated only when the evidence
334    /// covers it, or when the observed data already witnesses a violation that
335    /// further scanning cannot retract.
336    #[default]
337    FullSource,
338    /// Whatever the metric actually measured — the scanned rows, the retained
339    /// quality sample, the profiled columns. Always evaluable, and says
340    /// nothing about the rows that were not read.
341    Observed,
342}
343
344impl fmt::Display for PolicyScope {
345    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
346        match self {
347            Self::FullSource => write!(f, "full_source"),
348            Self::Observed => write!(f, "observed"),
349        }
350    }
351}
352
353impl std::str::FromStr for PolicyScope {
354    type Err = String;
355
356    fn from_str(s: &str) -> Result<Self, Self::Err> {
357        match s {
358            "full_source" => Ok(Self::FullSource),
359            "observed" => Ok(Self::Observed),
360            _ => Err(format!(
361                "Unknown policy scope: {s}. Valid scopes: full_source, observed"
362            )),
363        }
364    }
365}
366
367/// Why the data behind a number falls short of the whole source.
368#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
369#[serde(rename_all = "snake_case")]
370#[non_exhaustive]
371pub enum EvidenceGap {
372    /// Profiling stopped before the source was exhausted.
373    Truncated,
374    /// Rows were sampled rather than all read.
375    Sampled,
376    /// Records were skipped because they could not be turned into rows.
377    RecordsSkipped,
378    /// Every row was scanned, but this metric was computed from a retained
379    /// sample of them.
380    QualitySampled,
381    /// The report does not record how its numbers were obtained: which quality
382    /// components were sampled, or, in a flat summary from an older release,
383    /// whether the scan read the whole source. Only reachable for a report
384    /// read back from a document written before dataprof recorded it; a
385    /// profiling run always records it. Unknown coverage is not full
386    /// coverage, so a full-source requirement is left unevaluated.
387    CoverageUnrecorded,
388}
389
390impl fmt::Display for EvidenceGap {
391    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
392        match self {
393            Self::Truncated => write!(f, "truncated"),
394            Self::Sampled => write!(f, "sampled"),
395            Self::RecordsSkipped => write!(f, "records_skipped"),
396            Self::QualitySampled => write!(f, "quality_sampled"),
397            Self::CoverageUnrecorded => write!(f, "coverage_unrecorded"),
398        }
399    }
400}
401
402/// Whether the data behind a number covers the whole source.
403#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
404#[serde(tag = "coverage", rename_all = "snake_case")]
405#[non_exhaustive]
406pub enum Evidence {
407    /// Every row of the source is behind the number.
408    Complete,
409    /// Some of the source is not, for this reason.
410    #[non_exhaustive]
411    Incomplete {
412        /// The gap between what was read and the whole source.
413        reason: EvidenceGap,
414    },
415}
416
417impl Evidence {
418    /// True when the whole source is behind the number.
419    pub fn is_complete(self) -> bool {
420        matches!(self, Self::Complete)
421    }
422
423    /// The gap, when there is one.
424    pub fn gap(self) -> Option<EvidenceGap> {
425        match self {
426            Self::Complete => None,
427            Self::Incomplete { reason } => Some(reason),
428        }
429    }
430
431    /// The weaker of two evidence statements: a number is only as complete as
432    /// the least complete input behind it. The left-hand gap wins a tie, so
433    /// the scan's gap is named ahead of the quality sample's.
434    pub(crate) fn and(self, other: Self) -> Self {
435        match self {
436            Self::Complete => other,
437            incomplete => incomplete,
438        }
439    }
440}
441
442/// Stable identifier for the requirement a check came from.
443///
444/// Part of the serialized contract: a CI system matches on these, so they do
445/// not change when the prose does.
446#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
447#[serde(rename_all = "snake_case")]
448#[non_exhaustive]
449pub enum CheckCode {
450    /// The scan must have read at least the threshold's number of rows.
451    MinRows,
452    /// The overall quality score must be at least the threshold.
453    MinQualityScore,
454    /// One ISO 25012 dimension score must be at least the threshold.
455    MinDimensionScore,
456    /// A column's null percentage must be at most the threshold.
457    MaxNullPercentage,
458    /// A column's null count must be at most the threshold.
459    MaxNullCount,
460    /// The duplicate-row count must be at most the threshold.
461    MaxDuplicateRows,
462    /// No non-null value of a column may occur more than once.
463    UniqueColumn,
464    /// A column's newest date may lie at most the threshold's number of days
465    /// before the timeliness reference date.
466    MaxDateAge,
467    /// The largest gap between a column's consecutive distinct days may be
468    /// at most the threshold's number of days.
469    MaxDateGap,
470    /// A metric must have been analyzed at all.
471    RequireMetric,
472    /// The overall quality score may drop at most the threshold's number of
473    /// points below the baseline's.
474    MaxQualityScoreDrop,
475    /// One dimension score may drop at most the threshold's number of points
476    /// below the baseline's.
477    MaxDimensionScoreDrop,
478    /// The row count may fall at most the threshold's percentage of the
479    /// baseline's.
480    MaxRowCountDrop,
481    /// The row count may grow at most the threshold's percentage of the
482    /// baseline's.
483    MaxRowCountGrowth,
484    /// A column's null percentage may rise at most the threshold's number of
485    /// points above the baseline's.
486    MaxNullPercentageIncrease,
487    /// A column's distinct count may fall at most the threshold's percentage
488    /// of the baseline's, unless its distinct share of non-null values held.
489    MaxDistinctDrop,
490    /// A named column must be profiled.
491    RequireColumn,
492    /// A column the baseline profiled must still be profiled.
493    ForbidRemovedColumn,
494    /// A column the report profiled must be one the baseline profiled.
495    ForbidAddedColumn,
496    /// The report must hold no finding with the named code.
497    ForbidFinding,
498}
499
500impl fmt::Display for CheckCode {
501    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
502        match self {
503            Self::MinRows => write!(f, "min_rows"),
504            Self::MinQualityScore => write!(f, "min_quality_score"),
505            Self::MinDimensionScore => write!(f, "min_dimension_score"),
506            Self::MaxNullPercentage => write!(f, "max_null_percentage"),
507            Self::MaxNullCount => write!(f, "max_null_count"),
508            Self::MaxDuplicateRows => write!(f, "max_duplicate_rows"),
509            Self::UniqueColumn => write!(f, "unique_column"),
510            Self::MaxDateAge => write!(f, "max_date_age"),
511            Self::MaxDateGap => write!(f, "max_date_gap"),
512            Self::RequireMetric => write!(f, "require_metric"),
513            Self::MaxQualityScoreDrop => write!(f, "max_quality_score_drop"),
514            Self::MaxDimensionScoreDrop => write!(f, "max_dimension_score_drop"),
515            Self::MaxRowCountDrop => write!(f, "max_row_count_drop"),
516            Self::MaxRowCountGrowth => write!(f, "max_row_count_growth"),
517            Self::MaxNullPercentageIncrease => write!(f, "max_null_percentage_increase"),
518            Self::MaxDistinctDrop => write!(f, "max_distinct_drop"),
519            Self::RequireColumn => write!(f, "require_column"),
520            Self::ForbidRemovedColumn => write!(f, "forbid_removed_column"),
521            Self::ForbidAddedColumn => write!(f, "forbid_added_column"),
522            Self::ForbidFinding => write!(f, "forbid_finding"),
523        }
524    }
525}
526
527/// A number a check read, or a threshold it compared against.
528///
529/// Percentages follow the report's 2dp serialization convention; counts are
530/// whole numbers and are not widened into rounded floats.
531#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]
532#[serde(untagged)]
533#[non_exhaustive]
534pub enum MetricValue {
535    /// A count of rows or values.
536    Count(usize),
537    /// A 0..=100 percentage or score, or a change in one, in points.
538    Percentage(#[serde(serialize_with = "dataprof_core::serde_helpers::round_2")] f64),
539    /// A number of whole days. An age is negative when the date lies after
540    /// the reference date.
541    Days(i64),
542}
543
544impl fmt::Display for MetricValue {
545    /// For logs and messages, not for the serialized contract: percentages
546    /// print at the report's 2dp convention, counts as whole numbers.
547    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
548        match self {
549            Self::Count(count) => write!(f, "{count}"),
550            Self::Percentage(value) => write!(f, "{value:.2}"),
551            Self::Days(days) => write!(f, "{days}"),
552        }
553    }
554}
555
556/// The constraint a check applied.
557#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]
558#[serde(tag = "comparison", rename_all = "snake_case")]
559#[non_exhaustive]
560pub enum Expectation {
561    /// The observed value must be at least `value`.
562    #[non_exhaustive]
563    AtLeast {
564        /// The threshold.
565        value: MetricValue,
566    },
567    /// The observed value must be at most `value`.
568    #[non_exhaustive]
569    AtMost {
570        /// The threshold.
571        value: MetricValue,
572    },
573    /// The metric must have been analyzed. No number is compared.
574    Analyzed,
575    /// The change from the baseline, `observed` minus the baseline's value,
576    /// must be at least `value` points. A permitted drop is a negative value.
577    #[non_exhaustive]
578    ChangeAtLeast {
579        /// The threshold, in points.
580        value: MetricValue,
581    },
582    /// The change from the baseline must be at most `value` points.
583    #[non_exhaustive]
584    ChangeAtMost {
585        /// The threshold, in points.
586        value: MetricValue,
587    },
588    /// The change from the baseline as a percentage of the baseline's value,
589    /// `(observed - baseline) / baseline * 100`, must be at least `value`. A
590    /// permitted drop is a negative value.
591    #[non_exhaustive]
592    RelativeChangeAtLeast {
593        /// The threshold, in percent of the baseline's value.
594        value: MetricValue,
595    },
596    /// The change from the baseline as a percentage of the baseline's value
597    /// must be at most `value`.
598    #[non_exhaustive]
599    RelativeChangeAtMost {
600        /// The threshold, in percent of the baseline's value.
601        value: MetricValue,
602    },
603    /// The column must be profiled. No number is compared.
604    Present,
605    /// The column must be one the baseline profiled. No number is compared.
606    InBaseline,
607}
608
609impl fmt::Display for Expectation {
610    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
611        match self {
612            Self::AtLeast { value } => write!(f, "at least {value}"),
613            Self::AtMost { value } => write!(f, "at most {value}"),
614            Self::Analyzed => write!(f, "analyzed"),
615            Self::ChangeAtLeast { value } => write!(f, "a change of at least {value}"),
616            Self::ChangeAtMost { value } => write!(f, "a change of at most {value}"),
617            Self::RelativeChangeAtLeast { value } => {
618                write!(f, "a relative change of at least {value}%")
619            }
620            Self::RelativeChangeAtMost { value } => {
621                write!(f, "a relative change of at most {value}%")
622            }
623            Self::Present => write!(f, "present"),
624            Self::InBaseline => write!(f, "in the baseline"),
625        }
626    }
627}
628
629/// Why a requirement was not evaluated.
630///
631/// Absence is never read as zero and never as a pass. Each variant names a
632/// different thing a caller may want to fix: a run that did not ask for the
633/// metric, a dimension with nothing to measure, a column that was not
634/// profiled, or a scan that does not reach as far as the requirement does.
635#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
636#[serde(tag = "reason", rename_all = "snake_case")]
637#[non_exhaustive]
638pub enum NotEvaluated {
639    /// The report carries no quality assessment, for this recorded reason.
640    #[non_exhaustive]
641    QualityUnavailable {
642        /// The report's `quality_status` state, verbatim.
643        quality_status: String,
644    },
645    /// Quality was computed, but this dimension had nothing to assess — no
646    /// numeric values, no dates, no confidently detected pattern — or it was
647    /// withheld because the run profiled a subset of columns.
648    NotAssessed,
649    /// The report holds no profile for the named column, and its column
650    /// selection does not show the source lacks it: the run's `columns=`
651    /// selection left it out, or the report predates the record of its
652    /// selection. On a check with no column, the run profiled a `columns=`
653    /// selection, which may have left source columns out.
654    ColumnNotProfiled,
655    /// The requirement asks about the full source, the evidence does not reach
656    /// that far, and nothing observed settles it regardless.
657    #[non_exhaustive]
658    EvidenceIncomplete {
659        /// The gap between the evidence and the requirement's scope.
660        gap: EvidenceGap,
661    },
662    /// The baseline carries no value to measure a change from: it did not
663    /// assess the metric, did not profile the column, or read no values for
664    /// it.
665    NotInBaseline,
666    /// A distinct count the requirement reads is an estimate on at least one
667    /// side, because the exact set of values spilled into its sketch, or the
668    /// side does not record whether it is exact. An estimate falling is not a
669    /// column collapsing, and an estimate below the value count witnesses no
670    /// repeated value, so the requirement decides on exact counts only.
671    ApproximateCount,
672    /// The two reports profiled different column sets, and the requirement
673    /// is about a dataset-level score, whose subject is the column set. The
674    /// result's `baseline.schema` names the columns that differ.
675    SchemaChanged,
676    /// The overall score averages a different set of assessed dimensions on
677    /// each side, because a dimension was requested, or had something to
678    /// assess, on one side only.
679    DimensionsChanged,
680    /// A measurement definition the requirement depends on is not recorded
681    /// identically on both sides: one side predates the record, or the two
682    /// differ. Either way the same data may measure differently.
683    #[non_exhaustive]
684    DefinitionNotComparable {
685        /// The `metric_semantics` key.
686        definition: String,
687    },
688    /// A setting that moves the score on unchanged data differs between the
689    /// two reports.
690    #[non_exhaustive]
691    SettingChanged {
692        /// The configuration field that differs.
693        setting: String,
694    },
695    /// A setting that moves the score on unchanged data is not recorded on
696    /// at least one side, so it cannot be shown to be the same.
697    #[non_exhaustive]
698    SettingUnrecorded {
699        /// The configuration field that is unrecorded.
700        setting: String,
701    },
702    /// The findings rule a `forbid_finding` check reads could not look at
703    /// all of the report, and found nothing where it did look.
704    #[non_exhaustive]
705    FindingNotEvaluated {
706        /// The rule's entries in [`FindingsResult::not_evaluated`], each with
707        /// its own reason and the columns it covers.
708        rules: Vec<UnevaluatedRule>,
709    },
710}
711
712/// What happened to one requirement.
713#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
714#[serde(tag = "status", rename_all = "snake_case")]
715#[non_exhaustive]
716pub enum CheckStatus {
717    /// Evaluated and met.
718    Passed,
719    /// Evaluated and violated.
720    Failed,
721    /// Not evaluated, for this reason.
722    NotEvaluated(NotEvaluated),
723}
724
725/// One requirement and what the report said about it.
726#[derive(Debug, Clone, PartialEq, serde::Serialize)]
727#[non_exhaustive]
728pub struct Check {
729    /// Which requirement this is.
730    pub code: CheckCode,
731    /// The column it concerns, when it concerns one.
732    #[serde(skip_serializing_if = "Option::is_none")]
733    pub column: Option<String>,
734    /// The quality dimension it concerns, when it concerns one.
735    #[serde(skip_serializing_if = "Option::is_none")]
736    pub dimension: Option<QualityDimension>,
737    /// The findings code a `forbid_finding` check concerns. Absent on every
738    /// other rule.
739    #[serde(skip_serializing_if = "Option::is_none")]
740    pub finding: Option<FindingCode>,
741    /// The constraint applied.
742    pub expected: Expectation,
743    /// The value read from the report. Absent when nothing was read: every
744    /// unevaluated check, and every `require_metric` check.
745    #[serde(skip_serializing_if = "Option::is_none")]
746    pub observed: Option<MetricValue>,
747    /// What the requirement is a statement about.
748    pub scope: PolicyScope,
749    /// Whether the data behind `observed` covers the whole source.
750    pub evidence: Evidence,
751    /// Where the whole-source value lies, when `observed` came from a retained
752    /// sample and the report bounds it. A full-source requirement is decided
753    /// on this interval rather than on `observed`: it passes when the whole
754    /// interval meets the requirement, fails when none of it does, and is
755    /// otherwise not evaluated.
756    #[serde(skip_serializing_if = "Option::is_none")]
757    pub bounds: Option<CheckBounds>,
758    /// The baseline's side of a rule about change. Absent on every other
759    /// rule.
760    #[serde(skip_serializing_if = "Option::is_none")]
761    pub baseline: Option<BaselineReading>,
762    /// The findings a `forbid_finding` check found, each with its column and
763    /// evidence, in the order [`FindingsResult::findings`] lists them. Empty,
764    /// and not serialized, when there are none and on every other rule.
765    #[serde(skip_serializing_if = "Vec::is_empty")]
766    pub findings: Vec<Finding>,
767    /// Passed, failed, or not evaluated.
768    #[serde(flatten)]
769    pub status: CheckStatus,
770    /// A fixed sentence naming the outcome.
771    ///
772    /// Deliberately free of numbers: `observed` and `expected` carry those, so
773    /// the prose is identical wherever a value would have been formatted and
774    /// the Rust and Python implementations cannot drift on rounding inside a
775    /// string.
776    pub message: String,
777}
778
779impl Check {
780    /// True when the check was evaluated and violated.
781    pub fn is_violation(&self) -> bool {
782        matches!(self.status, CheckStatus::Failed)
783    }
784
785    /// Why the check was not evaluated, if it was not.
786    pub fn not_evaluated(&self) -> Option<&NotEvaluated> {
787        match &self.status {
788            CheckStatus::NotEvaluated(reason) => Some(reason),
789            _ => None,
790        }
791    }
792}
793
794/// What the baseline said about the metric a rule about change reads.
795#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]
796#[non_exhaustive]
797pub struct BaselineReading {
798    /// The baseline's value, or `None` when it carries none.
799    pub observed: Option<MetricValue>,
800    /// Whether the data behind the baseline's value covers its whole source.
801    pub evidence: Evidence,
802    /// The check's `observed` minus the baseline's, at the report's
803    /// serialized precision: in points, or, for a rule on a relative change
804    /// such as `max_distinct_drop` and the row count rules, in percent of the
805    /// baseline's value.
806    /// `None` when either side has no value.
807    pub change: Option<MetricValue>,
808    /// Where the baseline's whole-source score lies, when its score came
809    /// from a retained sample and the baseline bounds it, and a full-source
810    /// score drop rule was decided on it. Absent otherwise.
811    #[serde(skip_serializing_if = "Option::is_none")]
812    pub bounds: Option<CheckBounds>,
813}
814
815/// The two reports a baseline-relative evaluation compared, and how their
816/// column sets differ.
817#[derive(Debug, Clone, PartialEq, serde::Serialize)]
818#[non_exhaustive]
819pub struct BaselineComparison {
820    /// `a` is the baseline and `b` the report evaluated, as in a
821    /// [`ReportDelta`] between them, with whether one build wrote both.
822    pub reports: ReportPair,
823    /// Columns added, removed and shared.
824    pub schema: SchemaChange,
825    /// The schema changes from the baseline, whatever the policy states. A
826    /// diagnostic never moves the verdict. Empty when nothing changed.
827    pub diagnostics: Vec<Diagnostic>,
828    /// The clock rule the timeliness and overall score rules read.
829    pub timeliness_clock: TimelinessClockRule,
830}
831
832/// Stable identifier for a kind of schema change.
833///
834/// Part of the serialized contract, like [`CheckCode`].
835#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
836#[serde(rename_all = "snake_case")]
837#[non_exhaustive]
838pub enum DiagnosticCode {
839    /// The report profiled a column the baseline did not. Without a reason,
840    /// the baseline profiled every column it selected that its source had,
841    /// and this was not among them.
842    ColumnAdded,
843    /// The baseline profiled a column the report did not. Without a reason,
844    /// the report's selection included it, so it was not in what the report
845    /// read. With one, the report's column selection left it out or was not
846    /// recorded.
847    ColumnRemoved,
848    /// The column holds values on both sides and its inferred type differs.
849    /// A column whose values are all null on a side establishes no type there.
850    ColumnTypeChanged,
851    /// The column held values in the baseline, and every value read for it
852    /// in the report is null.
853    ColumnAllNull,
854}
855
856impl fmt::Display for DiagnosticCode {
857    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
858        match self {
859            Self::ColumnAdded => write!(f, "column_added"),
860            Self::ColumnRemoved => write!(f, "column_removed"),
861            Self::ColumnTypeChanged => write!(f, "column_type_changed"),
862            Self::ColumnAllNull => write!(f, "column_all_null"),
863        }
864    }
865}
866
867/// A schema change between the baseline and the report.
868///
869/// A warning, not a fourth verdict: it is reported whatever the policy
870/// states, and no rule decides on it. A requirement that would fail on it is
871/// a policy entry of its own.
872#[derive(Debug, Clone, PartialEq, serde::Serialize)]
873#[non_exhaustive]
874pub struct Diagnostic {
875    /// What changed.
876    pub code: DiagnosticCode,
877    /// The column it changed in.
878    pub column: String,
879    /// The inferred type on each side, `a` being the baseline. Present on
880    /// [`DiagnosticCode::ColumnTypeChanged`] only.
881    #[serde(
882        skip_serializing_if = "Option::is_none",
883        serialize_with = "serialize_data_types"
884    )]
885    pub data_type: Option<Sides<DataType>>,
886    /// A recorded setting that can produce the change on unchanged data,
887    /// when one can. Serialized flat, as a check's reason is.
888    #[serde(flatten)]
889    pub setting: Option<SettingDifference>,
890    /// A fixed sentence naming the change, free of numbers and names, like a
891    /// check's message.
892    pub message: String,
893}
894
895/// How a setting that can produce a diagnostic's change compares across the
896/// two reports. A diagnostic carrying one may not reflect a change in the
897/// data.
898///
899/// Two settings are read: `columns`, the column selection, on an added or
900/// removed column, and `identifier_columns` on a type change to or from
901/// `identifier`, the one type a setting assigns. An input path that types the
902/// same data differently is not recorded, so it cannot be named here (#906).
903#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
904#[serde(tag = "reason", rename_all = "snake_case")]
905#[non_exhaustive]
906pub enum SettingDifference {
907    /// The setting differs between the two reports for this column.
908    #[non_exhaustive]
909    SettingChanged {
910        /// The configuration field that differs.
911        setting: String,
912    },
913    /// At least one side did not record the setting, so it cannot be shown
914    /// to be the same.
915    #[non_exhaustive]
916    SettingUnrecorded {
917        /// The configuration field that is unrecorded.
918        setting: String,
919    },
920}
921
922fn serialize_data_types<S: serde::Serializer>(
923    types: &Option<Sides<DataType>>,
924    serializer: S,
925) -> Result<S::Ok, S::Error> {
926    types
927        .as_ref()
928        .map(|types| Sides {
929            a: types.a.name(),
930            b: types.b.name(),
931        })
932        .serialize(serializer)
933}
934
935/// The interval a sampled score was decided on.
936#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize)]
937#[non_exhaustive]
938pub struct CheckBounds {
939    /// Lowest value the whole-source score can take.
940    #[serde(serialize_with = "dataprof_core::serde_helpers::round_2")]
941    pub lower: f64,
942    /// Highest value the whole-source score can take.
943    #[serde(serialize_with = "dataprof_core::serde_helpers::round_2")]
944    pub upper: f64,
945    /// Probability that every interval in the report holds at once.
946    pub confidence_level: f64,
947}
948
949/// The overall outcome of a policy.
950#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
951#[serde(rename_all = "snake_case")]
952#[non_exhaustive]
953pub enum Verdict {
954    /// Every requirement was evaluated and met.
955    Pass,
956    /// At least one requirement was conclusively violated.
957    Fail,
958    /// Nothing was violated, and at least one requirement could not be
959    /// evaluated. Not a pass: the gate has no answer, not a positive one.
960    Inconclusive,
961}
962
963impl fmt::Display for Verdict {
964    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
965        match self {
966            Self::Pass => write!(f, "pass"),
967            Self::Fail => write!(f, "fail"),
968            Self::Inconclusive => write!(f, "inconclusive"),
969        }
970    }
971}
972
973/// The structured result of evaluating a [`QualityPolicy`].
974#[derive(Debug, Clone, PartialEq, serde::Serialize)]
975#[non_exhaustive]
976pub struct GateResult {
977    /// The overall outcome.
978    pub verdict: Verdict,
979    /// The scope every requirement was evaluated under.
980    pub scope: PolicyScope,
981    /// Whether the scan itself covered the whole source. A single check's
982    /// evidence can be weaker still, when its metric came from a retained
983    /// sample of the scanned rows.
984    pub evidence: Evidence,
985    /// Every requirement, in evaluation order.
986    pub checks: Vec<Check>,
987    /// The reports compared, when the policy was evaluated against a
988    /// baseline. Absent otherwise.
989    #[serde(skip_serializing_if = "Option::is_none")]
990    pub baseline: Option<BaselineComparison>,
991    /// The build that wrote the report evaluated, which decided the metrics
992    /// the verdict reads. `None` (serialized as `null`) when the report did
993    /// not record one. The build evaluating the policy can be another.
994    pub generator: Option<ReportGenerator>,
995    /// The caller's version of the source the report describes, `None`
996    /// (serialized as `null`) when none was recorded.
997    pub source_identity: Option<SourceIdentity>,
998}
999
1000impl GateResult {
1001    /// True only for [`Verdict::Pass`].
1002    ///
1003    /// An inconclusive result is not a pass: reading it as one is the mistake
1004    /// this API exists to prevent. Callers that need to tell "violated" from
1005    /// "could not tell" should match on [`GateResult::verdict`].
1006    pub fn passed(&self) -> bool {
1007        self.verdict == Verdict::Pass
1008    }
1009
1010    /// The checks that were evaluated and violated.
1011    pub fn violations(&self) -> impl Iterator<Item = &Check> {
1012        self.checks.iter().filter(|check| check.is_violation())
1013    }
1014
1015    /// The checks that could not be evaluated.
1016    pub fn unevaluated(&self) -> impl Iterator<Item = &Check> {
1017        self.checks
1018            .iter()
1019            .filter(|check| check.not_evaluated().is_some())
1020    }
1021}
1022
1023/// A metric a policy requires to have been analyzed.
1024#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1025#[non_exhaustive]
1026pub enum RequiredMetric {
1027    /// The quality assessment as a whole.
1028    Quality,
1029    /// One ISO 25012 dimension.
1030    Dimension(QualityDimension),
1031}
1032
1033/// What a report must satisfy.
1034///
1035/// Build one with the chainable setters, then [`evaluate`](Self::evaluate) it
1036/// against a report. Requirements are evaluated in a fixed order that does not
1037/// depend on the order they were added, so two callers stating the same policy
1038/// get the same document out.
1039#[derive(Debug, Clone, Default)]
1040#[non_exhaustive]
1041pub struct QualityPolicy {
1042    min_rows: Option<usize>,
1043    min_quality_score: Option<f64>,
1044    min_dimension_scores: BTreeMap<String, (QualityDimension, f64)>,
1045    max_null_percentage: BTreeMap<String, f64>,
1046    max_null_percentage_any: Option<f64>,
1047    max_null_count: BTreeMap<String, usize>,
1048    max_null_count_any: Option<usize>,
1049    max_duplicate_rows: Option<usize>,
1050    unique_columns: BTreeSet<String>,
1051    max_date_age: BTreeMap<String, u32>,
1052    max_date_gap: BTreeMap<String, u32>,
1053    require_metrics: Vec<RequiredMetric>,
1054    max_quality_score_drop: Option<f64>,
1055    max_dimension_score_drops: BTreeMap<String, (QualityDimension, f64)>,
1056    max_null_percentage_increase: BTreeMap<String, f64>,
1057    max_null_percentage_increase_any: Option<f64>,
1058    max_distinct_drop: BTreeMap<String, f64>,
1059    max_distinct_drop_any: Option<f64>,
1060    max_row_count_drop: Option<f64>,
1061    max_row_count_growth: Option<f64>,
1062    require_columns: BTreeSet<String>,
1063    forbid_removed_columns: bool,
1064    forbid_added_columns: bool,
1065    forbid_findings: BTreeSet<FindingCode>,
1066    timeliness_clock: TimelinessClockRule,
1067    scope: PolicyScope,
1068}
1069
1070impl QualityPolicy {
1071    /// An empty policy. It states no requirement, so evaluating it as-is is a
1072    /// [`PolicyError::NoRequirements`].
1073    pub fn new() -> Self {
1074        Self::default()
1075    }
1076
1077    /// Require the scan to have read at least `min` rows, so an empty or
1078    /// truncated extract fails instead of passing every other check.
1079    pub fn min_rows(mut self, min: usize) -> Self {
1080        self.min_rows = Some(min);
1081        self
1082    }
1083
1084    /// Require the overall quality score to be at least `min` (0..=100).
1085    pub fn min_quality_score(mut self, min: f64) -> Self {
1086        self.min_quality_score = Some(min);
1087        self
1088    }
1089
1090    /// Require one dimension's score to be at least `min` (0..=100).
1091    pub fn min_dimension_score(mut self, dimension: QualityDimension, min: f64) -> Self {
1092        self.min_dimension_scores
1093            .insert(dimension.to_string(), (dimension, min));
1094        self
1095    }
1096
1097    /// Require the named column's null percentage to be at most `max`
1098    /// (0..=100). Takes precedence over
1099    /// [`max_null_percentage_any`](Self::max_null_percentage_any) for that
1100    /// column.
1101    pub fn max_null_percentage(mut self, column: impl Into<String>, max: f64) -> Self {
1102        self.max_null_percentage.insert(column.into(), max);
1103        self
1104    }
1105
1106    /// Require every other profiled column's null percentage to be at most
1107    /// `max` (0..=100).
1108    pub fn max_null_percentage_any(mut self, max: f64) -> Self {
1109        self.max_null_percentage_any = Some(max);
1110        self
1111    }
1112
1113    /// Require the named column to hold at most `max` nulls, decided on the
1114    /// exact count. `max_null_count(column, 0)` states "no nulls" at any row
1115    /// count, where a zero null percentage is decided at the two decimals it
1116    /// is shown at. Takes precedence over
1117    /// [`max_null_count_any`](Self::max_null_count_any) for that column.
1118    pub fn max_null_count(mut self, column: impl Into<String>, max: usize) -> Self {
1119        self.max_null_count.insert(column.into(), max);
1120        self
1121    }
1122
1123    /// Require every other profiled column to hold at most `max` nulls.
1124    pub fn max_null_count_any(mut self, max: usize) -> Self {
1125        self.max_null_count_any = Some(max);
1126        self
1127    }
1128
1129    /// Require the report to count at most `max` duplicate rows.
1130    pub fn max_duplicate_rows(mut self, max: usize) -> Self {
1131        self.max_duplicate_rows = Some(max);
1132        self
1133    }
1134
1135    /// Require no non-null value of each named column to occur more than
1136    /// once, as a business key must not repeat (#904). Whole-row duplicates
1137    /// miss a reused key whenever another column differs, and always when a
1138    /// loader adds a row id.
1139    ///
1140    /// The rule reads the column's distinct count: its non-null values minus
1141    /// its distinct values are the values that repeat, and the check observes
1142    /// that number against an allowance of zero. Nulls are not values, so they
1143    /// never repeat; [`max_null_count`](Self::max_null_count) rules them out.
1144    /// A repeat the scan witnessed stays one however much was not read, so it
1145    /// fails under any scope, and none passes under
1146    /// [`PolicyScope::FullSource`] only when the scan covered the source, as
1147    /// with [`max_duplicate_rows`](Self::max_duplicate_rows). A distinct count
1148    /// that is an estimate (past one million distinct values, or sooner under
1149    /// memory pressure) or not recorded as exact witnesses nothing, so the
1150    /// check is [`NotEvaluated::ApproximateCount`] either way. A column with
1151    /// no distinct count (a nested column) is [`NotEvaluated::NotAssessed`].
1152    ///
1153    /// This is a requirement on the columns named, independent of the
1154    /// `identifier_columns` profiling option, which picks the key the
1155    /// uniqueness score and the `key_duplicates` finding read. Declaring one
1156    /// does not imply the other.
1157    pub fn unique_columns<I, S>(mut self, columns: I) -> Self
1158    where
1159        I: IntoIterator<Item = S>,
1160        S: Into<String>,
1161    {
1162        self.unique_columns
1163            .extend(columns.into_iter().map(Into::into));
1164        self
1165    }
1166
1167    /// Require the named column's newest date to lie at most `days` days
1168    /// before the timeliness reference date (#1290), so a feed that stopped
1169    /// moving fails while every other rule still passes it.
1170    ///
1171    /// The newest date is the column's `max_datetime`, a calendar date, and
1172    /// the reference date is the one the report's timeliness clock recorded
1173    /// (`reference_date`, or the run's date on a rolling clock), so the age is
1174    /// counted in calendar days and a saved report evaluated later decides
1175    /// the same. A date after the reference date is fresh. A newest date only
1176    /// gets newer as more values are read, so under [`PolicyScope::FullSource`]
1177    /// a fresh date passes whatever the scan missed, provided the column
1178    /// stays a date: on a truncated or sampled scan that holds only for a
1179    /// date type the source declared ([`NativeType::declares_date`]), since
1180    /// the rows not read may hold text that types an inferred column as text
1181    /// (#1333). A stale one fails only when the values behind it cover the
1182    /// column: every row read, and
1183    /// the date statistics computed over every value read. A report that
1184    /// records `metric_semantics.date_statistics` computed them so (#1297);
1185    /// for an older one the retained sample they came from must hold every
1186    /// non-null value. The exception is a column of slash dates whose
1187    /// day and month order the unread values could still change
1188    /// (`assumed_day_first` or `month_first`): there a fresh date read on
1189    /// part of the column is [`NotEvaluated::EvidenceIncomplete`] too. A column with no newest date (not typed as a
1190    /// date, all null, or statistics not computed) is
1191    /// [`NotEvaluated::NotAssessed`], and a report without a recorded clock is
1192    /// [`NotEvaluated::SettingUnrecorded`] on `timeliness_clock`.
1193    pub fn max_date_age(mut self, column: impl Into<String>, days: u32) -> Self {
1194        self.max_date_age.insert(column.into(), days);
1195        self
1196    }
1197
1198    /// Require the largest gap between the named column's consecutive
1199    /// distinct days to be at most `days` (#1300), so a daily file that lost
1200    /// a period from the middle of its range fails while its newest date,
1201    /// schema and most of its rows stay normal. `1` allows no missing day.
1202    ///
1203    /// The gap is the column's `largest_gap`, counted in whole calendar days
1204    /// over every value the profiler read. Under [`PolicyScope::FullSource`]
1205    /// the rule decides only when those values cover the column: the values
1206    /// that were not read can fill a hole the read ones show, or open a new
1207    /// one at either edge of the range, so a partial scan is
1208    /// [`NotEvaluated::EvidenceIncomplete`] whichever way the read values
1209    /// point. A column with no gap recorded (not typed as a date, all null, a
1210    /// report from before 0.14, or dates spanning more than
1211    /// [`DATE_GAP_YEAR_LIMIT`](dataprof_core::DATE_GAP_YEAR_LIMIT) distinct
1212    /// years) is [`NotEvaluated::NotAssessed`].
1213    pub fn max_date_gap(mut self, column: impl Into<String>, days: u32) -> Self {
1214        self.max_date_gap.insert(column.into(), days);
1215        self
1216    }
1217
1218    /// Require the report to carry a quality assessment at all.
1219    ///
1220    /// Without this, a report with no assessment leaves quality requirements
1221    /// unevaluated and the verdict inconclusive. With it, the absence is
1222    /// itself a violation — which is what a pipeline wants when quality is
1223    /// supposed to be configured on.
1224    pub fn require_quality(mut self) -> Self {
1225        self.require_metrics.push(RequiredMetric::Quality);
1226        self
1227    }
1228
1229    /// Require a specific dimension to have been assessed.
1230    pub fn require_dimension(mut self, dimension: QualityDimension) -> Self {
1231        self.require_metrics
1232            .push(RequiredMetric::Dimension(dimension));
1233        self
1234    }
1235
1236    /// Allow the overall quality score to drop at most `points` (0..=100)
1237    /// below the baseline's. Needs [`evaluate_against`](Self::evaluate_against).
1238    ///
1239    /// Under [`PolicyScope::FullSource`], a score computed over a retained
1240    /// sample on either side is read as its recorded whole-source interval,
1241    /// and the drop is decided when every change those intervals allow lies
1242    /// on one side of `points` (#1035). Each side's intervals hold together
1243    /// with that side's `confidence_level`; when both sides are sampled, the
1244    /// two hold together with probability at least the sum of the two levels
1245    /// minus one.
1246    pub fn max_quality_score_drop(mut self, points: f64) -> Self {
1247        self.max_quality_score_drop = Some(points);
1248        self
1249    }
1250
1251    /// Allow one dimension's score to drop at most `points` (0..=100) below
1252    /// the baseline's. Needs [`evaluate_against`](Self::evaluate_against).
1253    /// A sampled score is decided on its interval, as in
1254    /// [`max_quality_score_drop`](Self::max_quality_score_drop).
1255    pub fn max_dimension_score_drop(mut self, dimension: QualityDimension, points: f64) -> Self {
1256        self.max_dimension_score_drops
1257            .insert(dimension.to_string(), (dimension, points));
1258        self
1259    }
1260
1261    /// Allow the named column's null percentage to rise at most `points`
1262    /// (0..=100) above the baseline's. Takes precedence over
1263    /// [`max_null_percentage_increase_any`](Self::max_null_percentage_increase_any)
1264    /// for that column. Needs [`evaluate_against`](Self::evaluate_against).
1265    pub fn max_null_percentage_increase(mut self, column: impl Into<String>, points: f64) -> Self {
1266        self.max_null_percentage_increase
1267            .insert(column.into(), points);
1268        self
1269    }
1270
1271    /// Allow every other column both reports profiled to have its null
1272    /// percentage rise at most `points` (0..=100) above the baseline's. A
1273    /// column only the evaluated report has is not covered: it has no
1274    /// baseline, and gets a rule only when the policy names it. Needs
1275    /// [`evaluate_against`](Self::evaluate_against).
1276    pub fn max_null_percentage_increase_any(mut self, points: f64) -> Self {
1277        self.max_null_percentage_increase_any = Some(points);
1278        self
1279    }
1280
1281    /// Allow the named column's distinct count to fall at most `percent`
1282    /// (0..=100) of the baseline's (#1026). Fewer rows alone do not make a
1283    /// collapse, so the check fails only when the column's distinct share of
1284    /// non-null values fell by more than `percent` of the baseline's share as
1285    /// well. Decided on exact counts only: an estimate on either side leaves
1286    /// it [`NotEvaluated::ApproximateCount`]. Takes precedence over
1287    /// [`max_distinct_drop_any`](Self::max_distinct_drop_any) for that
1288    /// column. Needs [`evaluate_against`](Self::evaluate_against).
1289    pub fn max_distinct_drop(mut self, column: impl Into<String>, percent: f64) -> Self {
1290        self.max_distinct_drop.insert(column.into(), percent);
1291        self
1292    }
1293
1294    /// [`max_distinct_drop`](Self::max_distinct_drop) for every other column
1295    /// both reports profiled. A column only the evaluated report has is not
1296    /// covered. Needs [`evaluate_against`](Self::evaluate_against).
1297    pub fn max_distinct_drop_any(mut self, percent: f64) -> Self {
1298        self.max_distinct_drop_any = Some(percent);
1299        self
1300    }
1301
1302    /// Allow the row count to fall at most `percent` (0..=100) of the
1303    /// baseline's `rows_processed` (#1291), so a truncated extract that keeps
1304    /// its header and its shares fails. Needs
1305    /// [`evaluate_against`](Self::evaluate_against).
1306    ///
1307    /// A scan that stopped early read a lower bound of its source's rows. So
1308    /// under [`PolicyScope::FullSource`], an incomplete scan of this report
1309    /// still decides a pass and an incomplete baseline still decides a
1310    /// failure, and the other outcome is unevaluated: the rows a scan did not
1311    /// read could make up the difference. With both scans incomplete the rule
1312    /// is unevaluated. An allowance of 100% passes whatever the scans missed,
1313    /// since a count cannot fall by more. A different column set leaves it
1314    /// [`NotEvaluated::SchemaChanged`], as for a dataset-level score.
1315    pub fn max_row_count_drop(mut self, percent: f64) -> Self {
1316        self.max_row_count_drop = Some(percent);
1317        self
1318    }
1319
1320    /// Allow the row count to grow at most `percent` (0 or more) of the
1321    /// baseline's `rows_processed` (#1291), so a join that fans out or a file
1322    /// published twice fails. The mirror of
1323    /// [`max_row_count_drop`](Self::max_row_count_drop): an incomplete scan
1324    /// of this report still decides a failure, and an incomplete baseline a
1325    /// pass. Needs [`evaluate_against`](Self::evaluate_against).
1326    pub fn max_row_count_growth(mut self, percent: f64) -> Self {
1327        self.max_row_count_growth = Some(percent);
1328        self
1329    }
1330
1331    /// Require each named column to be profiled. A column missing from the
1332    /// report fails only when the report shows its source lacks it: the run's
1333    /// column selection included the column, and the column set covers the
1334    /// whole source (see the [module docs](self)).
1335    pub fn require_columns<I, S>(mut self, columns: I) -> Self
1336    where
1337        I: IntoIterator<Item = S>,
1338        S: Into<String>,
1339    {
1340        self.require_columns
1341            .extend(columns.into_iter().map(Into::into));
1342        self
1343    }
1344
1345    /// Require every column the baseline profiled to be profiled still. The
1346    /// rule is about the columns the baseline recorded: a column its source
1347    /// held but it did not profile (a projection, or a key past a partial
1348    /// read) is not one it can require. Needs
1349    /// [`evaluate_against`](Self::evaluate_against).
1350    pub fn forbid_removed_columns(mut self) -> Self {
1351        self.forbid_removed_columns = true;
1352        self
1353    }
1354
1355    /// Require every column the report profiled to be one the baseline
1356    /// profiled: a closed schema. Under [`PolicyScope::FullSource`], a report
1357    /// whose profiled columns may not be all of its source's also gets one
1358    /// check with no column, left unevaluated: a column selection that left
1359    /// columns out, one that was not recorded, or a column set covering part
1360    /// of the source. Needs [`evaluate_against`](Self::evaluate_against).
1361    pub fn forbid_added_columns(mut self) -> Self {
1362        self.forbid_added_columns = true;
1363        self
1364    }
1365
1366    /// Fail when the report holds a finding with one of these codes (#1066),
1367    /// derived with the default [`FindingPolicy`](crate::FindingPolicy) thresholds, as
1368    /// [`ProfileReport::findings`] derives them. One check per code, in code
1369    /// order. See the [module docs](self) for when a partial scan decides
1370    /// one.
1371    pub fn forbid_findings<I>(mut self, codes: I) -> Self
1372    where
1373        I: IntoIterator<Item = FindingCode>,
1374    {
1375        self.forbid_findings.extend(codes);
1376        self
1377    }
1378
1379    /// Declare how the timeliness clocks of the baseline and the report may
1380    /// differ, for the rules about change that read the timeliness score: the
1381    /// overall score drop, when both sides assessed timeliness, and the
1382    /// timeliness score drop. Defaults to [`TimelinessClockRule::Fixed`]. A
1383    /// difference the rule does not allow, or a clock either side did not
1384    /// record, leaves those rules unevaluated on the setting
1385    /// `timeliness_clock`.
1386    pub fn timeliness_clock(mut self, rule: TimelinessClockRule) -> Self {
1387        self.timeliness_clock = rule;
1388        self
1389    }
1390
1391    /// Set what the requirements are statements about. Defaults to
1392    /// [`PolicyScope::FullSource`].
1393    pub fn scope(mut self, scope: PolicyScope) -> Self {
1394        self.scope = scope;
1395        self
1396    }
1397
1398    /// Check that the policy is evaluable, without needing a report.
1399    ///
1400    /// Callers that read a policy out of configuration should do this at
1401    /// startup rather than discovering a bad threshold on the first dataset.
1402    pub fn validate(&self) -> Result<(), PolicyError> {
1403        if let Some(min) = self.min_quality_score {
1404            check_percentage(CheckCode::MinQualityScore, None, min)?;
1405        }
1406        for (dimension, min) in self.min_dimension_scores.values() {
1407            check_percentage(
1408                CheckCode::MinDimensionScore,
1409                Some(dimension.to_string()),
1410                *min,
1411            )?;
1412        }
1413        for (column, max) in &self.max_null_percentage {
1414            check_percentage(CheckCode::MaxNullPercentage, Some(column.clone()), *max)?;
1415        }
1416        if let Some(max) = self.max_null_percentage_any {
1417            check_percentage(CheckCode::MaxNullPercentage, None, max)?;
1418        }
1419        if let Some(points) = self.max_quality_score_drop {
1420            check_percentage(CheckCode::MaxQualityScoreDrop, None, points)?;
1421        }
1422        for (dimension, points) in self.max_dimension_score_drops.values() {
1423            check_percentage(
1424                CheckCode::MaxDimensionScoreDrop,
1425                Some(dimension.to_string()),
1426                *points,
1427            )?;
1428        }
1429        for (column, points) in &self.max_null_percentage_increase {
1430            check_percentage(
1431                CheckCode::MaxNullPercentageIncrease,
1432                Some(column.clone()),
1433                *points,
1434            )?;
1435        }
1436        if let Some(points) = self.max_null_percentage_increase_any {
1437            check_percentage(CheckCode::MaxNullPercentageIncrease, None, points)?;
1438        }
1439        for (column, percent) in &self.max_distinct_drop {
1440            check_percentage(CheckCode::MaxDistinctDrop, Some(column.clone()), *percent)?;
1441        }
1442        if let Some(percent) = self.max_distinct_drop_any {
1443            check_percentage(CheckCode::MaxDistinctDrop, None, percent)?;
1444        }
1445        if let Some(percent) = self.max_row_count_drop {
1446            check_percentage(CheckCode::MaxRowCountDrop, None, percent)?;
1447        }
1448        if let Some(percent) = self.max_row_count_growth
1449            && !(percent.is_finite() && percent >= 0.0)
1450        {
1451            return Err(PolicyError::ThresholdOutOfRange {
1452                code: CheckCode::MaxRowCountGrowth,
1453                subject: None,
1454                value: percent,
1455            });
1456        }
1457        if self.is_empty() {
1458            return Err(PolicyError::NoRequirements);
1459        }
1460        Ok(())
1461    }
1462
1463    fn is_empty(&self) -> bool {
1464        self.min_rows.is_none()
1465            && self.min_quality_score.is_none()
1466            && self.min_dimension_scores.is_empty()
1467            && self.max_null_percentage.is_empty()
1468            && self.max_null_percentage_any.is_none()
1469            && self.max_null_count.is_empty()
1470            && self.max_null_count_any.is_none()
1471            && self.max_duplicate_rows.is_none()
1472            && self.unique_columns.is_empty()
1473            && self.max_date_age.is_empty()
1474            && self.max_date_gap.is_empty()
1475            && self.require_metrics.is_empty()
1476            && self.require_columns.is_empty()
1477            && self.forbid_findings.is_empty()
1478            && !self.has_change_rules()
1479    }
1480
1481    /// Whether the policy states a rule about change from a baseline.
1482    fn has_change_rules(&self) -> bool {
1483        self.max_quality_score_drop.is_some()
1484            || !self.max_dimension_score_drops.is_empty()
1485            || !self.max_null_percentage_increase.is_empty()
1486            || self.max_null_percentage_increase_any.is_some()
1487            || !self.max_distinct_drop.is_empty()
1488            || self.max_distinct_drop_any.is_some()
1489            || self.max_row_count_drop.is_some()
1490            || self.max_row_count_growth.is_some()
1491            || self.forbid_removed_columns
1492            || self.forbid_added_columns
1493    }
1494
1495    /// Evaluate the policy against a report.
1496    ///
1497    /// Returns the structured outcome. The report is not modified, nothing is
1498    /// printed, and the process is not exited: what to do about a failing gate
1499    /// is the caller's decision. A policy with a rule about change is a
1500    /// [`PolicyError::BaselineRequired`] here; use
1501    /// [`evaluate_against`](Self::evaluate_against).
1502    pub fn evaluate(&self, report: &ProfileReport) -> Result<GateResult, PolicyError> {
1503        self.validate()?;
1504        if self.has_change_rules() {
1505            return Err(PolicyError::BaselineRequired);
1506        }
1507        let checks = self.absolute_checks(report);
1508        Ok(GateResult {
1509            verdict: verdict_of(&checks),
1510            scope: self.scope,
1511            evidence: scan_evidence(&report.execution),
1512            checks,
1513            baseline: None,
1514            generator: report.generator.clone(),
1515            source_identity: report.source_identity.clone(),
1516        })
1517    }
1518
1519    /// Evaluate the policy against a report and a baseline it is compared
1520    /// with.
1521    ///
1522    /// Every requirement is evaluated as [`evaluate`](Self::evaluate) does,
1523    /// then each rule about change, in a fixed order: the overall score, the
1524    /// dimensions in [`QualityDimension::all`] order, the row count drop and
1525    /// then growth, then for the null increase and then the distinct drop
1526    /// rules the named columns in name order and every other shared column in
1527    /// the baseline's order.
1528    /// The baseline may come from a flat summary, which leaves what it did
1529    /// not record unrecorded. See the [module docs](self) for when a change
1530    /// is decided.
1531    pub fn evaluate_against(
1532        &self,
1533        report: &ProfileReport,
1534        baseline: &ReportSide,
1535    ) -> Result<GateResult, PolicyError> {
1536        self.validate()?;
1537        let current = ReportSide::from_report(report);
1538        let delta = ReportDelta::between_sides(baseline, &current);
1539        let identifiers = Sides {
1540            a: baseline.identifier_order(),
1541            b: current.identifier_order(),
1542        };
1543        let sides = Sides {
1544            a: baseline,
1545            b: &current,
1546        };
1547        let mut checks = self.absolute_checks(report);
1548        if let Some(points) = self.max_quality_score_drop {
1549            checks.push(self.score_drop_check(report, &delta, &sides, &identifiers, None, points));
1550        }
1551        for dimension in QualityDimension::all() {
1552            if let Some((_, points)) = self.max_dimension_score_drops.get(&dimension.to_string()) {
1553                checks.push(self.score_drop_check(
1554                    report,
1555                    &delta,
1556                    &sides,
1557                    &identifiers,
1558                    Some(dimension),
1559                    *points,
1560                ));
1561            }
1562        }
1563        if let Some(percent) = self.max_row_count_drop {
1564            checks.push(self.row_count_change_check(&delta, RowCountRule::Drop, percent));
1565        }
1566        if let Some(percent) = self.max_row_count_growth {
1567            checks.push(self.row_count_change_check(&delta, RowCountRule::Growth, percent));
1568        }
1569        checks.extend(self.null_increase_checks(&delta));
1570        checks.extend(self.distinct_drop_checks(&delta, baseline, &current));
1571        // Collected once, so a rule over every column does not rescan the
1572        // other side's columns for each one.
1573        let (baseline_names, current_names) = (column_names(baseline), column_names(&current));
1574        if self.forbid_removed_columns {
1575            for column in baseline.columns() {
1576                checks.push(self.forbid_removed_check(
1577                    baseline,
1578                    &current,
1579                    &current_names,
1580                    &column.name,
1581                ));
1582            }
1583        }
1584        if self.forbid_added_columns {
1585            for column in current.columns() {
1586                checks.push(self.forbid_added_check(
1587                    baseline,
1588                    &current,
1589                    &baseline_names,
1590                    &column.name,
1591                ));
1592            }
1593            // The per-column checks cover the columns the report found. When
1594            // those do not enumerate the source, a column the baseline lacked
1595            // may be among the ones it did not profile, which no per-column
1596            // check can name.
1597            if self.scope == PolicyScope::FullSource
1598                && let Some(reason) = unenumerated_columns(&current)
1599            {
1600                checks.push(self.unprofiled_columns_check(baseline, &current, reason));
1601            }
1602        }
1603        let diagnostics = schema_diagnostics(baseline, &current, &delta);
1604        Ok(GateResult {
1605            verdict: verdict_of(&checks),
1606            scope: self.scope,
1607            evidence: scan_evidence(&report.execution),
1608            checks,
1609            baseline: Some(BaselineComparison {
1610                reports: delta.reports,
1611                schema: delta.schema,
1612                diagnostics,
1613                timeliness_clock: self.timeliness_clock,
1614            }),
1615            generator: report.generator.clone(),
1616            source_identity: report.source_identity.clone(),
1617        })
1618    }
1619
1620    /// The requirements about the report alone, in their fixed order.
1621    fn absolute_checks(&self, report: &ProfileReport) -> Vec<Check> {
1622        let scan = scan_evidence(&report.execution);
1623        let mut checks = Vec::new();
1624
1625        for metric in required_metrics_in_order(&self.require_metrics) {
1626            checks.push(self.require_metric_check(report, metric));
1627        }
1628        if !self.require_columns.is_empty() {
1629            let side = ReportSide::from_report(report);
1630            let names = column_names(&side);
1631            for column in &self.require_columns {
1632                checks.push(self.require_column_check(&side, &names, column));
1633            }
1634        }
1635        if let Some(min) = self.min_rows {
1636            checks.push(self.row_count_check(report, scan, min));
1637        }
1638        if let Some(min) = self.min_quality_score {
1639            checks.push(self.quality_score_check(report, scan, min));
1640        }
1641        for dimension in QualityDimension::all() {
1642            if let Some((_, min)) = self.min_dimension_scores.get(&dimension.to_string()) {
1643                checks.push(self.dimension_score_check(report, scan, dimension, *min));
1644            }
1645        }
1646        checks.extend(self.null_percentage_checks(report, scan));
1647        checks.extend(self.null_count_checks(report, scan));
1648        if let Some(max) = self.max_duplicate_rows {
1649            checks.push(self.duplicate_rows_check(report, scan, max));
1650        }
1651        for column in &self.unique_columns {
1652            let profile = report
1653                .column_profiles
1654                .iter()
1655                .find(|candidate| &candidate.name == column);
1656            checks.push(self.unique_column_check(column, profile, scan));
1657        }
1658        for (column, days) in &self.max_date_age {
1659            let profile = report
1660                .column_profiles
1661                .iter()
1662                .find(|candidate| &candidate.name == column);
1663            checks.push(self.date_age_check(report, column, profile, scan, *days));
1664        }
1665        for (column, days) in &self.max_date_gap {
1666            let profile = report
1667                .column_profiles
1668                .iter()
1669                .find(|candidate| &candidate.name == column);
1670            checks.push(self.date_gap_check(report, column, profile, scan, *days));
1671        }
1672        if !self.forbid_findings.is_empty() {
1673            let input = FindingsInput::from(report);
1674            let findings = FindingPolicy::default().collect(&input);
1675            for &code in &self.forbid_findings {
1676                let sample = if input.reads_a_partial_sample(code) {
1677                    Evidence::Incomplete {
1678                        reason: EvidenceGap::QualitySampled,
1679                    }
1680                } else {
1681                    Evidence::Complete
1682                };
1683                checks.push(self.forbid_finding_check(report, &findings, scan.and(sample), code));
1684            }
1685        }
1686        checks
1687    }
1688
1689    /// Decide one forbidden findings code.
1690    ///
1691    /// A finding present fails the check, except a finding about a share of
1692    /// the values ([`FindingReach::Share`]) under [`PolicyScope::FullSource`]
1693    /// on a scan that does not cover the source: a share over part of a
1694    /// source bounds nothing about the rest. No finding passes only when the
1695    /// rule looked at all of the report and, unless it is about how the
1696    /// source was read ([`FindingReach::Read`]), the scan covers the source
1697    /// or the scope is [`PolicyScope::Observed`].
1698    fn forbid_finding_check(
1699        &self,
1700        report: &ProfileReport,
1701        result: &FindingsResult,
1702        scan: Evidence,
1703        code: FindingCode,
1704    ) -> Check {
1705        let found: Vec<Finding> = result
1706            .findings
1707            .iter()
1708            .filter(|finding| finding.code == code)
1709            .cloned()
1710            .collect();
1711        let skipped: Vec<UnevaluatedRule> = result
1712            .not_evaluated
1713            .iter()
1714            .filter(|rule| rule.code == code)
1715            .cloned()
1716            .collect();
1717        // A duplicate-row rule skipped over an estimate says what would let
1718        // it look (#1292).
1719        let estimated_duplicates = code == FindingCode::DuplicateRows
1720            && skipped
1721                .iter()
1722                .any(|rule| rule.reason == NotEvaluatedReason::Estimated);
1723        let reach = FindingReach::of(code);
1724        let evidence = match reach {
1725            FindingReach::Read => Evidence::Complete,
1726            FindingReach::Witness | FindingReach::Share => scan,
1727        };
1728        let gap = match self.scope {
1729            PolicyScope::FullSource => evidence.gap(),
1730            PolicyScope::Observed => None,
1731        };
1732        let (status, message) = match (found.is_empty(), gap) {
1733            (false, Some(EvidenceGap::QualitySampled)) if reach == FindingReach::Share => (
1734                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete {
1735                    gap: EvidenceGap::QualitySampled,
1736                }),
1737                "the finding holds for the retained sample of values, and the values outside \
1738                 it may change it",
1739            ),
1740            (false, Some(gap)) if reach == FindingReach::Share => (
1741                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap }),
1742                "the finding holds for the rows read, and the rows that were not read may \
1743                 change it",
1744            ),
1745            (false, _) => (
1746                CheckStatus::Failed,
1747                "the report holds a finding the policy forbids",
1748            ),
1749            (true, _) if !skipped.is_empty() => (
1750                CheckStatus::NotEvaluated(NotEvaluated::FindingNotEvaluated { rules: skipped }),
1751                FINDING_NOT_EVALUATED,
1752            ),
1753            (true, Some(EvidenceGap::QualitySampled)) => (
1754                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete {
1755                    gap: EvidenceGap::QualitySampled,
1756                }),
1757                "the finding's rule found nothing in the retained sample of values, and the \
1758                 values outside it may hold it",
1759            ),
1760            (true, Some(gap)) => (
1761                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap }),
1762                "the finding's rule found nothing in the rows read, and the rows that were not \
1763                 read may hold it",
1764            ),
1765            (true, None) => (
1766                CheckStatus::Passed,
1767                "the finding's rule looked and found nothing",
1768            ),
1769        };
1770        // Where the rule could not look, the zero it found elsewhere is not a
1771        // count of the report's findings.
1772        let observed = match status {
1773            CheckStatus::NotEvaluated(NotEvaluated::FindingNotEvaluated { .. }) => None,
1774            _ => Some(MetricValue::Count(found.len())),
1775        };
1776        Check {
1777            code: CheckCode::ForbidFinding,
1778            column: None,
1779            dimension: None,
1780            finding: Some(code),
1781            expected: Expectation::AtMost {
1782                value: MetricValue::Count(0),
1783            },
1784            observed,
1785            scope: self.scope,
1786            evidence,
1787            bounds: None,
1788            baseline: None,
1789            findings: found,
1790            status,
1791            message: with_exact_count_hint(message, report, estimated_duplicates),
1792        }
1793    }
1794
1795    /// Decide a comparison whose observed value is an average or a ratio.
1796    ///
1797    /// Such a value, computed over part of a source, bounds nothing about the
1798    /// rest of it, so under [`PolicyScope::FullSource`] incomplete evidence
1799    /// leaves the requirement unevaluated in both directions. Under
1800    /// [`PolicyScope::Observed`] the question is about the data that was
1801    /// measured, so the comparison always stands.
1802    fn decide_aggregate(&self, evidence: Evidence, satisfied: bool) -> CheckStatus {
1803        match (self.scope, evidence.gap()) {
1804            (PolicyScope::FullSource, Some(gap)) => {
1805                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
1806            }
1807            _ if satisfied => CheckStatus::Passed,
1808            _ => CheckStatus::Failed,
1809        }
1810    }
1811
1812    fn require_metric_check(&self, report: &ProfileReport, metric: RequiredMetric) -> Check {
1813        let dimension = match metric {
1814            RequiredMetric::Quality => None,
1815            RequiredMetric::Dimension(dimension) => Some(dimension),
1816        };
1817        // Availability is a property of the report, not of how much of the
1818        // source it covers: a sampled run still either analyzed the metric or
1819        // did not. So this check never consults evidence.
1820        let analyzed = match (report.quality.as_ref(), dimension) {
1821            (None, _) => false,
1822            (Some(_), None) => true,
1823            (Some(quality), Some(dimension)) => {
1824                quality.metrics.dimension_score(dimension).is_some()
1825            }
1826        };
1827        let message = match (analyzed, dimension) {
1828            (true, None) => "quality was analyzed",
1829            (false, None) => "the report carries no quality assessment",
1830            (true, Some(_)) => "the required dimension was assessed",
1831            (false, Some(_)) => "the required dimension was not assessed",
1832        };
1833        Check {
1834            code: CheckCode::RequireMetric,
1835            column: None,
1836            dimension,
1837            finding: None,
1838            findings: Vec::new(),
1839            expected: Expectation::Analyzed,
1840            observed: None,
1841            scope: self.scope,
1842            evidence: Evidence::Complete,
1843            bounds: None,
1844            baseline: None,
1845            status: if analyzed {
1846                CheckStatus::Passed
1847            } else {
1848                CheckStatus::Failed
1849            },
1850            message: message.to_string(),
1851        }
1852    }
1853
1854    /// The mirror of the duplicate-row rule: rows already read do not stop
1855    /// existing when more are read, so a scan that read at least `min` rows
1856    /// settles the requirement whatever it missed. Fewer is a failure only
1857    /// when the scan covered the whole source, or under
1858    /// [`PolicyScope::Observed`]; under [`PolicyScope::FullSource`] the rows
1859    /// that were not read may make up the difference.
1860    fn row_count_check(&self, report: &ProfileReport, scan: Evidence, min: usize) -> Check {
1861        let observed = report.execution.rows_processed;
1862        let status = match (self.scope, scan.gap()) {
1863            _ if observed >= min => CheckStatus::Passed,
1864            (PolicyScope::FullSource, Some(gap)) => {
1865                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
1866            }
1867            _ => CheckStatus::Failed,
1868        };
1869        let message = match status {
1870            CheckStatus::Passed => "the scan read at least the required number of rows",
1871            CheckStatus::Failed => "fewer rows were read than the required minimum",
1872            CheckStatus::NotEvaluated(_) => {
1873                "fewer rows were read than the required minimum, and the rows that were not \
1874                 read may make up the difference"
1875            }
1876        };
1877        Check {
1878            code: CheckCode::MinRows,
1879            column: None,
1880            dimension: None,
1881            finding: None,
1882            findings: Vec::new(),
1883            expected: Expectation::AtLeast {
1884                value: MetricValue::Count(min),
1885            },
1886            observed: Some(MetricValue::Count(observed)),
1887            scope: self.scope,
1888            evidence: scan,
1889            bounds: None,
1890            baseline: None,
1891            status,
1892            message: message.to_string(),
1893        }
1894    }
1895
1896    fn quality_score_check(&self, report: &ProfileReport, scan: Evidence, min: f64) -> Check {
1897        let mut check = Check {
1898            code: CheckCode::MinQualityScore,
1899            column: None,
1900            dimension: None,
1901            finding: None,
1902            findings: Vec::new(),
1903            expected: Expectation::AtLeast {
1904                value: MetricValue::Percentage(min),
1905            },
1906            observed: None,
1907            scope: self.scope,
1908            evidence: scan.and(quality_evidence(
1909                report.quality.as_ref(),
1910                Provenance::Overall,
1911            )),
1912            bounds: None,
1913            baseline: None,
1914            status: CheckStatus::Passed,
1915            message: String::new(),
1916        };
1917        let Some(quality) = report.quality.as_ref() else {
1918            return unavailable_quality(check, report);
1919        };
1920        let Some(score) = quality.score() else {
1921            check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
1922            check.message =
1923                "no quality dimension had anything to assess, so there is no overall score"
1924                    .to_string();
1925            return check;
1926        };
1927        check.observed = Some(MetricValue::Percentage(score));
1928        let bounds = quality
1929            .score_bounds()
1930            .and_then(|bounds| check_bounds(bounds, bounds.overall_score));
1931        self.decide_score(&mut check, score, min, bounds, "the overall quality score");
1932        check
1933    }
1934
1935    fn dimension_score_check(
1936        &self,
1937        report: &ProfileReport,
1938        scan: Evidence,
1939        dimension: QualityDimension,
1940        min: f64,
1941    ) -> Check {
1942        let mut check = Check {
1943            code: CheckCode::MinDimensionScore,
1944            column: None,
1945            dimension: Some(dimension),
1946            finding: None,
1947            findings: Vec::new(),
1948            expected: Expectation::AtLeast {
1949                value: MetricValue::Percentage(min),
1950            },
1951            observed: None,
1952            scope: self.scope,
1953            evidence: scan.and(quality_evidence(
1954                report.quality.as_ref(),
1955                Provenance::Dimension(dimension),
1956            )),
1957            bounds: None,
1958            baseline: None,
1959            status: CheckStatus::Passed,
1960            message: String::new(),
1961        };
1962        let Some(quality) = report.quality.as_ref() else {
1963            return unavailable_quality(check, report);
1964        };
1965        let Some(score) = quality
1966            .scores()
1967            .dimension_scores
1968            .get(&dimension.to_string())
1969            .copied()
1970            .flatten()
1971        else {
1972            check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
1973            check.message = "this dimension had nothing to assess in this run".to_string();
1974            return check;
1975        };
1976        check.observed = Some(MetricValue::Percentage(score));
1977        let bounds = quality.score_bounds().and_then(|bounds| {
1978            check_bounds(
1979                bounds,
1980                bounds
1981                    .dimension_scores
1982                    .get(&dimension.to_string())
1983                    .copied()
1984                    .flatten(),
1985            )
1986        });
1987        self.decide_score(&mut check, score, min, bounds, "this dimension's score");
1988        check
1989    }
1990
1991    /// Decide a minimum on a score, on its whole-source interval when the
1992    /// only gap in the evidence is the quality sample and the report bounds
1993    /// the score. The interval settles the requirement when it lies wholly on
1994    /// one side of the minimum; a minimum inside it is left unevaluated.
1995    ///
1996    /// The score, its bounds and the minimum are compared at the serialized
1997    /// precision, as the rules about change are: the result and the saved
1998    /// report show them at two decimals, so a raw comparison failed a score
1999    /// shown as meeting its minimum, and a reloaded report then passed (#1085).
2000    fn decide_score(
2001        &self,
2002        check: &mut Check,
2003        score: f64,
2004        min: f64,
2005        bounds: Option<CheckBounds>,
2006        subject: &str,
2007    ) {
2008        let sampled = check.evidence.gap() == Some(EvidenceGap::QualitySampled);
2009        let min = rounded_2(min);
2010        match bounds {
2011            Some(bounds) if self.scope == PolicyScope::FullSource && sampled => {
2012                check.bounds = Some(bounds);
2013                check.status = if rounded_2(bounds.lower) >= min {
2014                    CheckStatus::Passed
2015                } else if rounded_2(bounds.upper) < min {
2016                    CheckStatus::Failed
2017                } else {
2018                    CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete {
2019                        gap: EvidenceGap::QualitySampled,
2020                    })
2021                };
2022                check.message = bounded_message(&check.status, subject);
2023            }
2024            _ => {
2025                check.status = self.decide_aggregate(check.evidence, rounded_2(score) >= min);
2026                check.message = aggregate_message(&check.status, subject);
2027            }
2028        }
2029    }
2030
2031    /// One check per named column, in column-name order, then one per
2032    /// remaining profiled column when a wildcard limit is set, in report
2033    /// column order.
2034    ///
2035    /// The order is fixed by the data rather than by how the policy was
2036    /// written, so a policy read out of a JSON object — where key order is not
2037    /// preserved uniformly across languages — still evaluates identically.
2038    fn null_percentage_checks(&self, report: &ProfileReport, scan: Evidence) -> Vec<Check> {
2039        let mut checks = Vec::new();
2040        for (column, max) in &self.max_null_percentage {
2041            let profile = report
2042                .column_profiles
2043                .iter()
2044                .find(|candidate| &candidate.name == column);
2045            checks.push(self.null_percentage_check(column, profile, scan, *max));
2046        }
2047        if let Some(max) = self.max_null_percentage_any {
2048            for profile in &report.column_profiles {
2049                if !self.max_null_percentage.contains_key(&profile.name) {
2050                    checks.push(self.null_percentage_check(
2051                        &profile.name,
2052                        Some(profile),
2053                        scan,
2054                        max,
2055                    ));
2056                }
2057            }
2058        }
2059        checks
2060    }
2061
2062    fn null_percentage_check(
2063        &self,
2064        column: &str,
2065        profile: Option<&ColumnProfile>,
2066        scan: Evidence,
2067        max: f64,
2068    ) -> Check {
2069        // Null counts accumulate over every scanned row rather than over the
2070        // retained quality sample, so only the scan's own gap applies here.
2071        let mut check = Check {
2072            code: CheckCode::MaxNullPercentage,
2073            column: Some(column.to_string()),
2074            dimension: None,
2075            finding: None,
2076            findings: Vec::new(),
2077            expected: Expectation::AtMost {
2078                value: MetricValue::Percentage(max),
2079            },
2080            observed: None,
2081            scope: self.scope,
2082            evidence: scan,
2083            bounds: None,
2084            baseline: None,
2085            status: CheckStatus::Passed,
2086            message: String::new(),
2087        };
2088        let Some(profile) = profile else {
2089            check.status = CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled);
2090            check.message = "this column has no profile in the report".to_string();
2091            return check;
2092        };
2093        let Some(percentage) = null_percentage(profile) else {
2094            // No value was read for the column, so "what share of its values
2095            // are null" has no answer. Zero rows is not zero percent.
2096            check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
2097            check.message = "no values were read for this column".to_string();
2098            return check;
2099        };
2100        check.observed = Some(MetricValue::Percentage(percentage));
2101        // At the precision `observed` is shown at, as for scores (#1085).
2102        check.status =
2103            self.decide_aggregate(check.evidence, rounded_2(percentage) <= rounded_2(max));
2104        check.message = match check.status {
2105            CheckStatus::Passed => "this column's null percentage is within the allowance",
2106            CheckStatus::Failed => "this column's null percentage is above the allowance",
2107            CheckStatus::NotEvaluated(_) => {
2108                "the scan does not cover the whole source, and a null percentage over \
2109                 part of it bounds nothing about the rest"
2110            }
2111        }
2112        .to_string();
2113        check
2114    }
2115
2116    /// The null-count ceilings, in the same order as the null-percentage
2117    /// ones: named columns in name order, then every other profiled column in
2118    /// report order.
2119    fn null_count_checks(&self, report: &ProfileReport, scan: Evidence) -> Vec<Check> {
2120        let mut checks = Vec::new();
2121        for (column, max) in &self.max_null_count {
2122            let profile = report
2123                .column_profiles
2124                .iter()
2125                .find(|candidate| &candidate.name == column);
2126            checks.push(self.null_count_check(column, profile, scan, *max));
2127        }
2128        if let Some(max) = self.max_null_count_any {
2129            for profile in &report.column_profiles {
2130                if !self.max_null_count.contains_key(&profile.name) {
2131                    checks.push(self.null_count_check(&profile.name, Some(profile), scan, max));
2132                }
2133            }
2134        }
2135        checks
2136    }
2137
2138    /// A null count, like a duplicate count, only grows as more rows are read:
2139    /// nulls the scan witnessed above the allowance fail a full-source rule
2140    /// whatever the scan missed, and a count within it passes only when the
2141    /// scan covered the source. The count is exact, so nothing is rounded.
2142    /// Unlike a percentage, it has an answer when no value was read: zero.
2143    fn null_count_check(
2144        &self,
2145        column: &str,
2146        profile: Option<&ColumnProfile>,
2147        scan: Evidence,
2148        max: usize,
2149    ) -> Check {
2150        let mut check = Check {
2151            code: CheckCode::MaxNullCount,
2152            column: Some(column.to_string()),
2153            dimension: None,
2154            finding: None,
2155            findings: Vec::new(),
2156            expected: Expectation::AtMost {
2157                value: MetricValue::Count(max),
2158            },
2159            observed: None,
2160            scope: self.scope,
2161            evidence: scan,
2162            bounds: None,
2163            baseline: None,
2164            status: CheckStatus::Passed,
2165            message: String::new(),
2166        };
2167        let Some(profile) = profile else {
2168            check.status = CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled);
2169            check.message = "this column has no profile in the report".to_string();
2170            return check;
2171        };
2172        let exceeded = profile.null_count > max;
2173        check.observed = Some(MetricValue::Count(profile.null_count));
2174        check.status = match (self.scope, scan.gap()) {
2175            (PolicyScope::FullSource, Some(_)) if exceeded => CheckStatus::Failed,
2176            (PolicyScope::FullSource, Some(gap)) => {
2177                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
2178            }
2179            _ if exceeded => CheckStatus::Failed,
2180            _ => CheckStatus::Passed,
2181        };
2182        check.message = match check.status {
2183            CheckStatus::Passed => "this column's null count is within the allowance",
2184            CheckStatus::Failed => "nulls were observed in this column above the allowance",
2185            CheckStatus::NotEvaluated(_) => {
2186                "no nulls above the allowance were observed in this column, and the rows \
2187                 that were not read may hold more"
2188            }
2189        }
2190        .to_string();
2191        check
2192    }
2193
2194    /// A duplicate count, like a null count, is a requirement that an incomplete scan
2195    /// can still settle in one direction: rows already witnessed as duplicates
2196    /// do not stop being duplicates when more rows are read, so an exact count
2197    /// above the allowance is a conclusive failure. A count at or below it is
2198    /// not a pass — the rows that were not read may hold more. An estimated
2199    /// count witnesses nothing and settles neither direction.
2200    fn duplicate_rows_check(&self, report: &ProfileReport, scan: Evidence, max: usize) -> Check {
2201        let mut check = Check {
2202            code: CheckCode::MaxDuplicateRows,
2203            column: None,
2204            dimension: Some(QualityDimension::Uniqueness),
2205            finding: None,
2206            findings: Vec::new(),
2207            expected: Expectation::AtMost {
2208                value: MetricValue::Count(max),
2209            },
2210            observed: None,
2211            scope: self.scope,
2212            evidence: scan.and(quality_evidence(
2213                report.quality.as_ref(),
2214                Provenance::Component("duplicate_rows"),
2215            )),
2216            bounds: None,
2217            baseline: None,
2218            status: CheckStatus::Passed,
2219            message: String::new(),
2220        };
2221        let Some(quality) = report.quality.as_ref() else {
2222            return unavailable_quality(check, report);
2223        };
2224        let Some(uniqueness) = quality
2225            .metrics
2226            .uniqueness
2227            .as_ref()
2228            .filter(|metrics| metrics.rows_checked > 0)
2229        else {
2230            check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
2231            check.message = "no rows were scanned for duplicates in this run".to_string();
2232            return check;
2233        };
2234        let observed = uniqueness.duplicate_rows;
2235        let exceeded = observed > max;
2236        let estimated = uniqueness.duplicate_rows_approximate;
2237        check.observed = Some(MetricValue::Count(observed));
2238        check.status = match (self.scope, check.evidence.gap()) {
2239            // A witnessed violation is a decision, whatever the scan missed.
2240            (PolicyScope::FullSource, Some(_)) if exceeded && !estimated => CheckStatus::Failed,
2241            (PolicyScope::FullSource, Some(gap)) => {
2242                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
2243            }
2244            _ if exceeded => CheckStatus::Failed,
2245            _ => CheckStatus::Passed,
2246        };
2247        let message = match check.status {
2248            CheckStatus::Passed => "the duplicate-row count is within the allowance",
2249            CheckStatus::Failed if estimated => {
2250                "the estimated duplicate-row count is above the allowance"
2251            }
2252            CheckStatus::Failed => "duplicate rows were observed above the allowance",
2253            // Every row may have been read: the gap is the estimate, which
2254            // can neither witness duplicates nor rule them out (#819).
2255            CheckStatus::NotEvaluated(_) if estimated => {
2256                "the duplicate-row count is an estimate, which can neither witness \
2257                 duplicates above the allowance nor rule them out"
2258            }
2259            CheckStatus::NotEvaluated(_) => {
2260                "no duplicate above the allowance was observed, and the rows that were not \
2261                 read may hold more"
2262            }
2263        };
2264        let undecided_estimate = estimated && matches!(check.status, CheckStatus::NotEvaluated(_));
2265        check.message = with_exact_count_hint(message, report, undecided_estimate);
2266        check
2267    }
2268
2269    /// Whether a column's non-null values repeat. See
2270    /// [`unique_columns`](Self::unique_columns).
2271    fn unique_column_check(
2272        &self,
2273        column: &str,
2274        profile: Option<&ColumnProfile>,
2275        scan: Evidence,
2276    ) -> Check {
2277        let mut check = Check {
2278            code: CheckCode::UniqueColumn,
2279            column: Some(column.to_string()),
2280            dimension: None,
2281            finding: None,
2282            findings: Vec::new(),
2283            expected: Expectation::AtMost {
2284                value: MetricValue::Count(0),
2285            },
2286            observed: None,
2287            scope: self.scope,
2288            evidence: scan,
2289            bounds: None,
2290            baseline: None,
2291            status: CheckStatus::Passed,
2292            message: String::new(),
2293        };
2294        let Some(profile) = profile else {
2295            check.status = CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled);
2296            check.message = "this column has no profile in the report".to_string();
2297            return check;
2298        };
2299        let Some(distinct) = profile.unique_count else {
2300            check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
2301            check.message = "the report counted no distinct values for this column".to_string();
2302            return check;
2303        };
2304        if profile.unique_count_is_approximate != Some(false) {
2305            check.status = CheckStatus::NotEvaluated(NotEvaluated::ApproximateCount);
2306            check.message = "this column's distinct count is an estimate, or not recorded as \
2307                             exact, which can neither witness a repeated value nor rule one out"
2308                .to_string();
2309            return check;
2310        }
2311        let values = profile.total_count.saturating_sub(profile.null_count);
2312        let repeated = values.saturating_sub(distinct);
2313        check.observed = Some(MetricValue::Count(repeated));
2314        check.status = match (self.scope, scan.gap()) {
2315            _ if repeated > 0 => CheckStatus::Failed,
2316            (PolicyScope::FullSource, Some(gap)) => {
2317                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
2318            }
2319            _ => CheckStatus::Passed,
2320        };
2321        check.message = match check.status {
2322            CheckStatus::Passed => "no non-null value of this column occurs more than once",
2323            CheckStatus::Failed => "some non-null values of this column occur more than once",
2324            CheckStatus::NotEvaluated(_) => {
2325                "no value of this column was observed more than once, and the rows that were \
2326                 not read may repeat one"
2327            }
2328        }
2329        .to_string();
2330        check
2331    }
2332
2333    /// How old a column's newest date may be, in days before the timeliness
2334    /// reference date. See [`max_date_age`](Self::max_date_age).
2335    fn date_age_check(
2336        &self,
2337        report: &ProfileReport,
2338        column: &str,
2339        profile: Option<&ColumnProfile>,
2340        scan: Evidence,
2341        max_days: u32,
2342    ) -> Check {
2343        let mut check = Check {
2344            code: CheckCode::MaxDateAge,
2345            column: Some(column.to_string()),
2346            dimension: None,
2347            finding: None,
2348            findings: Vec::new(),
2349            expected: Expectation::AtMost {
2350                value: MetricValue::Days(i64::from(max_days)),
2351            },
2352            observed: None,
2353            scope: self.scope,
2354            evidence: scan,
2355            bounds: None,
2356            baseline: None,
2357            status: CheckStatus::Passed,
2358            message: String::new(),
2359        };
2360        let Some(profile) = profile else {
2361            check.status = CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled);
2362            check.message = "this column has no profile in the report".to_string();
2363            return check;
2364        };
2365        let (newest, slash_order) = match newest_date(profile) {
2366            NewestDate::Date { date, order } => (date, order),
2367            absent => {
2368                check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
2369                check.message = match absent {
2370                    NewestDate::Malformed => {
2371                        "the newest date recorded for this column is not a YYYY-MM-DD date"
2372                    }
2373                    _ if profile.data_type == DataType::Date => {
2374                        "no newest date was recorded for this column"
2375                    }
2376                    _ => "this column is not typed as a date, so it has no newest date",
2377                }
2378                .to_string();
2379                return check;
2380            }
2381        };
2382        check.evidence = scan.and(date_statistics_evidence(report, profile));
2383        let Some(quality) = report.quality.as_ref() else {
2384            return unavailable_quality(check, report);
2385        };
2386        let Some(clock) = quality
2387            .metrics
2388            .timeliness
2389            .as_ref()
2390            .and_then(|timeliness| timeliness.clock)
2391        else {
2392            check.status = CheckStatus::NotEvaluated(NotEvaluated::SettingUnrecorded {
2393                setting: "timeliness_clock".to_string(),
2394            });
2395            check.message =
2396                "the report records no timeliness clock to measure the age against".to_string();
2397            return check;
2398        };
2399        let age = (clock.reference_date - newest).num_days();
2400        check.observed = Some(MetricValue::Days(age));
2401        let fresh = age <= i64::from(max_days);
2402        // The newest date only moves forward as more values are read, so a
2403        // fresh one is a decision whatever the evidence missed, as long as
2404        // the values read keep the reading they were given. A date type
2405        // inferred from the rows read is one such reading: rows the scan did
2406        // not reach may hold text that types the column as text, and the
2407        // whole column then has no newest date (#1333). Slash dates are read
2408        // in an order the column's values decide (#811), and an order the
2409        // unread values can still change may move the dates already read.
2410        let type_settled = !scan_left_rows_out(scan)
2411            || profile
2412                .native_type
2413                .as_ref()
2414                .is_some_and(NativeType::declares_date);
2415        let order_settled = slash_order_settled(slash_order);
2416        check.status = match (self.scope, check.evidence.gap()) {
2417            (PolicyScope::FullSource, Some(gap)) if !(fresh && type_settled && order_settled) => {
2418                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
2419            }
2420            _ if fresh => CheckStatus::Passed,
2421            _ => CheckStatus::Failed,
2422        };
2423        check.message = match check.status {
2424            CheckStatus::Passed => "this column's newest date is within the allowed age",
2425            CheckStatus::Failed => "this column's newest date is older than the allowed age",
2426            CheckStatus::NotEvaluated(_) if fresh && !order_settled => {
2427                "the newest date read in this column is within the allowed age, and the values \
2428                 that were not read may change the day and month order its slash dates are \
2429                 read in"
2430            }
2431            CheckStatus::NotEvaluated(_) if fresh => {
2432                "the newest date read in this column is within the allowed age, and the rows \
2433                 that were not read may hold values that are not dates, which would type the \
2434                 column as text"
2435            }
2436            CheckStatus::NotEvaluated(_) => {
2437                "the newest date read in this column is older than the allowed age, and the \
2438                 values that were not read may hold a newer one"
2439            }
2440        }
2441        .to_string();
2442        check
2443    }
2444
2445    /// How long a hole a column's dates may hold. See
2446    /// [`max_date_gap`](Self::max_date_gap).
2447    fn date_gap_check(
2448        &self,
2449        report: &ProfileReport,
2450        column: &str,
2451        profile: Option<&ColumnProfile>,
2452        scan: Evidence,
2453        max_days: u32,
2454    ) -> Check {
2455        let mut check = Check {
2456            code: CheckCode::MaxDateGap,
2457            column: Some(column.to_string()),
2458            dimension: None,
2459            finding: None,
2460            findings: Vec::new(),
2461            expected: Expectation::AtMost {
2462                value: MetricValue::Days(i64::from(max_days)),
2463            },
2464            observed: None,
2465            scope: self.scope,
2466            evidence: scan,
2467            bounds: None,
2468            baseline: None,
2469            status: CheckStatus::Passed,
2470            message: String::new(),
2471        };
2472        let Some(profile) = profile else {
2473            check.status = CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled);
2474            check.message = "this column has no profile in the report".to_string();
2475            return check;
2476        };
2477        let gap = match &profile.stats {
2478            ColumnStats::DateTime(stats) => stats.largest_gap.as_ref().ok_or(
2479                if stats.max_datetime.is_empty() {
2480                    "no date was recorded for this column"
2481                } else {
2482                    "no largest gap was recorded for this column: the report predates it, or                      the column's dates span more years than the profiler tracks days for"
2483                },
2484            ),
2485            _ if profile.data_type == DataType::Date => Err("no date was recorded for this column"),
2486            _ => Err("this column is not typed as a date, so it has no gap between dates"),
2487        };
2488        let gap = match gap {
2489            Ok(gap) => gap,
2490            Err(message) => {
2491                check.status = CheckStatus::NotEvaluated(NotEvaluated::NotAssessed);
2492                check.message = message.to_string();
2493                return check;
2494            }
2495        };
2496        check.evidence = scan.and(date_statistics_evidence(report, profile));
2497        check.observed = Some(MetricValue::Days(gap.days));
2498        let within = gap.days <= i64::from(max_days);
2499        // Unread values can both fill a hole and open one past either edge,
2500        // so neither reading is a decision on part of the column.
2501        check.status = match (self.scope, check.evidence.gap()) {
2502            (PolicyScope::FullSource, Some(gap)) => {
2503                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
2504            }
2505            _ if within => CheckStatus::Passed,
2506            _ => CheckStatus::Failed,
2507        };
2508        check.message = match check.status {
2509            CheckStatus::Passed => format!(
2510                "this column's largest gap between dates, {} days from {} to {}, is within the                  allowance",
2511                gap.days, gap.from, gap.to
2512            ),
2513            CheckStatus::Failed => format!(
2514                "this column's dates hold a gap of {} days from {} to {}, longer than allowed",
2515                gap.days, gap.from, gap.to
2516            ),
2517            CheckStatus::NotEvaluated(_) if within => format!(
2518                "the largest gap between the dates read in this column, {} days, is within the                  allowance, and the values that were not read may open a longer one",
2519                gap.days
2520            ),
2521            CheckStatus::NotEvaluated(_) => format!(
2522                "the dates read in this column hold a gap of {} days from {} to {}, and the                  values that were not read may fill it",
2523                gap.days, gap.from, gap.to
2524            ),
2525        };
2526        check
2527    }
2528
2529    /// How far a score may drop below the baseline's. Both sides are read
2530    /// from the delta, at their serialized precision, so the decision is the
2531    /// one a saved report and its baseline document reproduce.
2532    fn score_drop_check(
2533        &self,
2534        report: &ProfileReport,
2535        delta: &ReportDelta,
2536        sides: &Sides<&ReportSide>,
2537        identifiers: &Sides<Option<&[String]>>,
2538        dimension: Option<QualityDimension>,
2539        points: f64,
2540    ) -> Check {
2541        let (code, change, subject) = match dimension {
2542            None => (
2543                CheckCode::MaxQualityScoreDrop,
2544                &delta.quality_score,
2545                "the overall quality score",
2546            ),
2547            Some(dimension) => (
2548                CheckCode::MaxDimensionScoreDrop,
2549                &delta
2550                    .dimensions
2551                    .iter()
2552                    .find(|change| change.dimension == dimension)
2553                    .expect("a delta lists every dimension this build knows")
2554                    .score,
2555                "this dimension's score",
2556            ),
2557        };
2558        let mut check = Check {
2559            code,
2560            column: None,
2561            dimension,
2562            finding: None,
2563            findings: Vec::new(),
2564            // `0.0 - points`, not `-points`: a permitted drop of zero
2565            // serializes as 0.0 rather than -0.0.
2566            expected: Expectation::ChangeAtLeast {
2567                value: MetricValue::Percentage(0.0 - points),
2568            },
2569            observed: change.b.map(MetricValue::Percentage),
2570            scope: self.scope,
2571            evidence: change.evidence.b,
2572            bounds: None,
2573            baseline: Some(baseline_reading(change.a, change.evidence.a, change.abs)),
2574            status: CheckStatus::Passed,
2575            message: String::new(),
2576        };
2577        if report.quality.is_none() {
2578            return unavailable_quality(check, report);
2579        }
2580        let schema_changed = !delta.schema.added.is_empty() || !delta.schema.removed.is_empty();
2581        // The overall score averages the dimensions that had something to
2582        // assess, so a dimension scored on one side only changes the average
2583        // itself, whatever the data did.
2584        let dimensions_changed = dimension.is_none()
2585            && delta
2586                .dimensions
2587                .iter()
2588                .any(|change| change.score.a.is_some() != change.score.b.is_some());
2589        let reason = if let Some(gap) = pack_gap(delta, dimension) {
2590            Some(gap)
2591        } else if change.b.is_none() {
2592            Some(NotEvaluated::NotAssessed)
2593        } else if change.a.is_none() {
2594            Some(NotEvaluated::NotInBaseline)
2595        } else if schema_changed {
2596            Some(NotEvaluated::SchemaChanged)
2597        } else if dimensions_changed {
2598            Some(NotEvaluated::DimensionsChanged)
2599        } else {
2600            let facts = RunFacts::of(sides, dimension);
2601            definition_gap(
2602                delta.metric_semantics.a.as_ref(),
2603                delta.metric_semantics.b.as_ref(),
2604                score_definitions(dimension)
2605                    .iter()
2606                    .filter(|definition| definition.reaches(&facts)),
2607            )
2608            .or_else(|| {
2609                setting_gap(
2610                    &delta.configuration,
2611                    identifiers,
2612                    dimension,
2613                    self.timeliness_clock,
2614                    score_reads_clock(delta, dimension),
2615                )
2616            })
2617        };
2618        if let Some(reason) = reason {
2619            return not_evaluated_change(check, reason, subject);
2620        }
2621        let change_points = change
2622            .abs
2623            .expect("a delta has a change whenever both sides have a score");
2624        // Both sides and their change are at the serialized precision, so the
2625        // allowance is too: the decision is the one the document shows.
2626        let allowance = 0.0 - rounded_2(points);
2627        let bounded = match self.bounded_change(change, sides, dimension) {
2628            ChangeReading::Points => None,
2629            ChangeReading::Bounded(bounded) => Some(bounded),
2630            ChangeReading::Blocked(gap) => {
2631                return not_evaluated_change(
2632                    check,
2633                    NotEvaluated::EvidenceIncomplete { gap },
2634                    subject,
2635                );
2636            }
2637        };
2638        if let Some(bounded) = bounded {
2639            check.bounds = bounded.b;
2640            if let Some(baseline) = check.baseline.as_mut() {
2641                baseline.bounds = bounded.a;
2642            }
2643            check.status = if bounded.lower >= allowance {
2644                CheckStatus::Passed
2645            } else if bounded.upper < allowance {
2646                CheckStatus::Failed
2647            } else {
2648                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete {
2649                    gap: EvidenceGap::QualitySampled,
2650                })
2651            };
2652            check.message = match check.status {
2653                CheckStatus::Passed => format!(
2654                    "{subject} was computed over a sample on at least one side, and every \
2655                     change the whole-source intervals allow is within the permitted drop"
2656                ),
2657                CheckStatus::Failed => format!(
2658                    "{subject} was computed over a sample on at least one side, and every \
2659                     change the whole-source intervals allow is a larger drop than permitted"
2660                ),
2661                CheckStatus::NotEvaluated(_) => format!(
2662                    "{subject} was computed over a sample on at least one side, and the \
2663                     permitted drop lies within the change the whole-source intervals allow"
2664                ),
2665            };
2666            return check;
2667        }
2668        check.status = self.decide_change(&change.evidence, change_points >= allowance);
2669        check.message = match check.status {
2670            CheckStatus::Passed => {
2671                format!("{subject} dropped no more than allowed from the baseline")
2672            }
2673            CheckStatus::Failed => format!("{subject} dropped more than allowed from the baseline"),
2674            CheckStatus::NotEvaluated(_) => evidence_message(subject),
2675        };
2676        check
2677    }
2678
2679    /// The interval a full-source score change lies in, when at least one
2680    /// side's score came from a retained sample and every such side bounds
2681    /// it (#1035). A side whose score covers its whole source is a point.
2682    /// The change runs from the current side's lower bound minus the
2683    /// baseline's upper bound to the current upper bound minus the baseline
2684    /// lower bound, at the serialized precision.
2685    ///
2686    /// [`ChangeReading::Points`] leaves the decision to
2687    /// [`Self::decide_change`]: under [`PolicyScope::Observed`], and when
2688    /// both sides cover their whole source. A side with another gap, or a
2689    /// sampled score without a recorded interval, blocks the decision with
2690    /// its gap, the evaluated report's named first. Stored bounds on a score
2691    /// whose coverage is unrecorded are not read, as the minimum score rules
2692    /// do not read them: this build cannot tell which components such a
2693    /// score weighs, so it cannot tell what the interval vouches for.
2694    fn bounded_change(
2695        &self,
2696        change: &ScoreChange,
2697        sides: &Sides<&ReportSide>,
2698        dimension: Option<QualityDimension>,
2699    ) -> ChangeReading {
2700        if self.scope != PolicyScope::FullSource {
2701            return ChangeReading::Points;
2702        }
2703        type SideReading = Result<((f64, f64), Option<CheckBounds>), EvidenceGap>;
2704        let interval = |score: f64, evidence: Evidence, side: &ReportSide| -> SideReading {
2705            match evidence.gap() {
2706                None => Ok(((score, score), None)),
2707                Some(EvidenceGap::QualitySampled) => {
2708                    let interval = side.score_bounds().and_then(|bounds| {
2709                        let interval = match dimension {
2710                            None => bounds.overall_score,
2711                            Some(dimension) => bounds
2712                                .dimension_scores
2713                                .get(&dimension.to_string())
2714                                .copied()
2715                                .flatten(),
2716                        };
2717                        check_bounds(bounds, interval)
2718                    });
2719                    match interval {
2720                        Some(bounds) => Ok((
2721                            (rounded_2(bounds.lower), rounded_2(bounds.upper)),
2722                            Some(bounds),
2723                        )),
2724                        None => Err(EvidenceGap::QualitySampled),
2725                    }
2726                }
2727                Some(gap) => Err(gap),
2728            }
2729        };
2730        let (Some(a_score), Some(b_score)) = (change.a, change.b) else {
2731            return ChangeReading::Points;
2732        };
2733        let b = interval(b_score, change.evidence.b, sides.b);
2734        let a = interval(a_score, change.evidence.a, sides.a);
2735        let (((b_lower, b_upper), b), ((a_lower, a_upper), a)) = match (b, a) {
2736            (Err(gap), _) | (_, Err(gap)) => return ChangeReading::Blocked(gap),
2737            (Ok(b), Ok(a)) => (b, a),
2738        };
2739        if a.is_none() && b.is_none() {
2740            return ChangeReading::Points;
2741        }
2742        ChangeReading::Bounded(BoundedChange {
2743            lower: rounded_2(b_lower - a_upper),
2744            upper: rounded_2(b_upper - a_lower),
2745            a,
2746            b,
2747        })
2748    }
2749
2750    /// One check per named column, in name order, then one per other column
2751    /// both reports profiled, in the baseline's order. A column only the
2752    /// evaluated report has gets no rule unless the policy names it.
2753    fn null_increase_checks(&self, delta: &ReportDelta) -> Vec<Check> {
2754        let index = ColumnIndex::new(delta);
2755        let mut checks = Vec::new();
2756        for (column, points) in &self.max_null_percentage_increase {
2757            checks.push(self.null_increase_check(delta, &index, column, *points));
2758        }
2759        if let Some(points) = self.max_null_percentage_increase_any {
2760            for column in &delta.schema.common {
2761                if !self.max_null_percentage_increase.contains_key(column) {
2762                    checks.push(self.null_increase_check(delta, &index, column, points));
2763                }
2764            }
2765        }
2766        checks
2767    }
2768
2769    /// How far a column's null percentage may rise above the baseline's.
2770    /// Null counts accumulate over every scanned row, so each side's scan
2771    /// coverage is its evidence, and only the null-token definition can make
2772    /// the same data count differently. A column's own rule does not depend on
2773    /// the rest of the column set.
2774    fn null_increase_check(
2775        &self,
2776        delta: &ReportDelta,
2777        index: &ColumnIndex<'_>,
2778        column: &str,
2779        points: f64,
2780    ) -> Check {
2781        let change = index.changes.get(column).copied();
2782        let (null_pct_a, null_pct_b, null_pct_delta) = change.map_or(
2783            (None, None, None),
2784            |ColumnChange {
2785                 null_pct_a,
2786                 null_pct_b,
2787                 null_pct_delta,
2788                 ..
2789             }| (*null_pct_a, *null_pct_b, *null_pct_delta),
2790        );
2791        let in_report = index.in_report.contains(column);
2792        let in_baseline = index.in_baseline.contains(column);
2793        let evidence = Sides {
2794            a: delta.reports.a.evidence,
2795            b: delta.reports.b.evidence,
2796        };
2797        let mut check = Check {
2798            code: CheckCode::MaxNullPercentageIncrease,
2799            column: Some(column.to_string()),
2800            dimension: None,
2801            finding: None,
2802            findings: Vec::new(),
2803            expected: Expectation::ChangeAtMost {
2804                value: MetricValue::Percentage(points),
2805            },
2806            observed: null_pct_b.map(MetricValue::Percentage),
2807            scope: self.scope,
2808            evidence: evidence.b,
2809            bounds: None,
2810            baseline: Some(baseline_reading(null_pct_a, evidence.a, null_pct_delta)),
2811            status: CheckStatus::Passed,
2812            message: String::new(),
2813        };
2814        let reason = if !in_report {
2815            Some(NotEvaluated::ColumnNotProfiled)
2816        } else if !in_baseline {
2817            Some(NotEvaluated::NotInBaseline)
2818        } else if null_pct_b.is_none() {
2819            Some(NotEvaluated::NotAssessed)
2820        } else if null_pct_a.is_none() {
2821            Some(NotEvaluated::NotInBaseline)
2822        } else {
2823            definition_gap(
2824                delta.metric_semantics.a.as_ref(),
2825                delta.metric_semantics.b.as_ref(),
2826                [Definition::NullTokens].iter(),
2827            )
2828        };
2829        let subject = "this column's null percentage";
2830        if let Some(reason) = reason {
2831            return not_evaluated_change(check, reason, subject);
2832        }
2833        let change_points =
2834            null_pct_delta.expect("a delta has a change whenever both sides have a value");
2835        check.status = self.decide_change(&evidence, change_points <= rounded_2(points));
2836        check.message = match check.status {
2837            CheckStatus::Passed => {
2838                format!("{subject} rose no more than allowed above the baseline")
2839            }
2840            CheckStatus::Failed => format!("{subject} rose more than allowed above the baseline"),
2841            CheckStatus::NotEvaluated(_) => evidence_message(subject),
2842        };
2843        check
2844    }
2845
2846    /// How far the row count may fall or grow from the baseline's, in percent
2847    /// of the baseline's `rows_processed` (#1291).
2848    fn row_count_change_check(
2849        &self,
2850        delta: &ReportDelta,
2851        rule: RowCountRule,
2852        percent: f64,
2853    ) -> Check {
2854        let (a, b) = (&delta.reports.a, &delta.reports.b);
2855        // A baseline that read no rows has no count to take a share of.
2856        let baseline_rows = a.rows_processed.filter(|&rows| rows > 0);
2857        let change = baseline_rows
2858            .zip(b.rows_processed)
2859            .map(|(a, b)| relative_change(a as f64, b as f64));
2860        let allowed = rounded_2(percent);
2861        let (code, expected) = match rule {
2862            // `0.0 - percent`, not `-percent`: a permitted drop of zero
2863            // serializes as 0.0 rather than -0.0.
2864            RowCountRule::Drop => (
2865                CheckCode::MaxRowCountDrop,
2866                Expectation::RelativeChangeAtLeast {
2867                    value: MetricValue::Percentage(0.0 - percent),
2868                },
2869            ),
2870            RowCountRule::Growth => (
2871                CheckCode::MaxRowCountGrowth,
2872                Expectation::RelativeChangeAtMost {
2873                    value: MetricValue::Percentage(percent),
2874                },
2875            ),
2876        };
2877        let check = Check {
2878            code,
2879            column: None,
2880            dimension: None,
2881            finding: None,
2882            findings: Vec::new(),
2883            expected,
2884            observed: b.rows_processed.map(MetricValue::Count),
2885            scope: self.scope,
2886            evidence: b.evidence,
2887            bounds: None,
2888            baseline: Some(BaselineReading {
2889                observed: a.rows_processed.map(MetricValue::Count),
2890                evidence: a.evidence,
2891                change: change.map(MetricValue::Percentage),
2892                bounds: None,
2893            }),
2894            status: CheckStatus::Passed,
2895            message: String::new(),
2896        };
2897        let subject = "the row count";
2898        let schema_changed = !delta.schema.added.is_empty() || !delta.schema.removed.is_empty();
2899        let reason = if change.is_none() {
2900            Some(NotEvaluated::NotInBaseline)
2901        } else if schema_changed {
2902            Some(NotEvaluated::SchemaChanged)
2903        } else {
2904            None
2905        };
2906        if let Some(reason) = reason {
2907            return not_evaluated_change(check, reason, subject);
2908        }
2909        let change = change.expect("a decided rule has a change");
2910        let (satisfied, verb) = match rule {
2911            RowCountRule::Drop => (change >= 0.0 - allowed, "fell"),
2912            RowCountRule::Growth => (change <= allowed, "grew"),
2913        };
2914        let mut check = check;
2915        // A count cannot fall by more than all of it, so a drop allowance of
2916        // 100% (at the serialized precision) holds whatever a scan did not
2917        // read.
2918        check.status = if rule == RowCountRule::Drop && allowed >= PERCENTAGE_MAX {
2919            CheckStatus::Passed
2920        } else {
2921            self.decide_row_count_change(
2922                rule,
2923                &Sides {
2924                    a: a.evidence,
2925                    b: b.evidence,
2926                },
2927                satisfied,
2928            )
2929        };
2930        check.message = match check.status {
2931            CheckStatus::Passed => {
2932                format!("{subject} {verb} no more than allowed from the baseline")
2933            }
2934            CheckStatus::Failed => format!("{subject} {verb} more than allowed from the baseline"),
2935            CheckStatus::NotEvaluated(_) => format!(
2936                "{subject} {verb} {} than allowed from the baseline, and the rows a scan did not \
2937                 read may reverse that",
2938                if satisfied { "no more" } else { "more" }
2939            ),
2940        };
2941        check
2942    }
2943
2944    /// Decide a row count change. Each scan read a lower bound of its
2945    /// source's rows, so a gap on one side can move the true change one way
2946    /// only: more unread rows in this report make the change larger, more in
2947    /// the baseline make it smaller. An outcome the unread rows could not
2948    /// reverse stands; the other is unevaluated, naming the gap of the side
2949    /// whose unread rows could reverse it. With both sides incomplete, either
2950    /// outcome can be reversed.
2951    fn decide_row_count_change(
2952        &self,
2953        rule: RowCountRule,
2954        evidence: &Sides<Evidence>,
2955        satisfied: bool,
2956    ) -> CheckStatus {
2957        let outcome = if satisfied {
2958            CheckStatus::Passed
2959        } else {
2960            CheckStatus::Failed
2961        };
2962        if self.scope == PolicyScope::Observed {
2963            return outcome;
2964        }
2965        // A larger true change reverses a drop rule's failure and a growth
2966        // rule's pass; a smaller one the opposite.
2967        let larger_reverses = match rule {
2968            RowCountRule::Drop => !satisfied,
2969            RowCountRule::Growth => satisfied,
2970        };
2971        let gap = if larger_reverses {
2972            evidence.b.gap()
2973        } else {
2974            evidence.a.gap()
2975        };
2976        match gap {
2977            Some(gap) => CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap }),
2978            None => outcome,
2979        }
2980    }
2981
2982    /// One check per named column, in name order, then one per other column
2983    /// both reports profiled, in the baseline's order, as for
2984    /// [`null_increase_checks`](Self::null_increase_checks).
2985    fn distinct_drop_checks(
2986        &self,
2987        delta: &ReportDelta,
2988        baseline: &ReportSide,
2989        current: &ReportSide,
2990    ) -> Vec<Check> {
2991        if self.max_distinct_drop.is_empty() && self.max_distinct_drop_any.is_none() {
2992            return Vec::new();
2993        }
2994        fn by_name(side: &ReportSide) -> HashMap<&str, &ColumnSide> {
2995            side.columns()
2996                .iter()
2997                .map(|column| (column.name.as_str(), column))
2998                .collect()
2999        }
3000        let sides = Sides {
3001            a: by_name(baseline),
3002            b: by_name(current),
3003        };
3004        // A distinct count reads no sampled score, so the overall score's
3005        // sample stands in for `part_of_source`, which its rule never reads.
3006        let facts = RunFacts::of(
3007            &Sides {
3008                a: baseline,
3009                b: current,
3010            },
3011            None,
3012        );
3013        let mut checks = Vec::new();
3014        for (column, percent) in &self.max_distinct_drop {
3015            checks.push(self.distinct_drop_check(delta, &sides, &facts, column, *percent));
3016        }
3017        if let Some(percent) = self.max_distinct_drop_any {
3018            for column in &delta.schema.common {
3019                if !self.max_distinct_drop.contains_key(column) {
3020                    checks.push(self.distinct_drop_check(delta, &sides, &facts, column, percent));
3021                }
3022            }
3023        }
3024        checks
3025    }
3026
3027    /// How far a column's distinct count may fall below the baseline's, in
3028    /// percent of the baseline's count (#1026). Distinct counts accumulate
3029    /// over every scanned row, so each side's scan coverage is its evidence.
3030    /// A count that fell with the rows is not a collapse: the check fails
3031    /// only when the distinct share of non-null values fell by more than the
3032    /// allowance too. Both changes are compared at the serialized precision.
3033    fn distinct_drop_check(
3034        &self,
3035        delta: &ReportDelta,
3036        sides: &Sides<HashMap<&str, &ColumnSide>>,
3037        facts: &RunFacts,
3038        column: &str,
3039        percent: f64,
3040    ) -> Check {
3041        let read = |side: &HashMap<&str, &ColumnSide>| {
3042            side.get(column).map(|column| DistinctReading::of(column))
3043        };
3044        let (a, b) = (read(&sides.a), read(&sides.b));
3045        let counted = |reading: Option<DistinctReading>| {
3046            reading.and_then(|reading| reading.non_null.filter(|&n| n > 0).and(reading.count))
3047        };
3048        let (count_a, count_b) = (counted(a), counted(b));
3049        let count_change = count_a
3050            .zip(count_b)
3051            .map(|(a, b)| relative_change(a as f64, b as f64));
3052        let evidence = Sides {
3053            a: delta.reports.a.evidence,
3054            b: delta.reports.b.evidence,
3055        };
3056        let mut check = Check {
3057            code: CheckCode::MaxDistinctDrop,
3058            column: Some(column.to_string()),
3059            dimension: None,
3060            finding: None,
3061            findings: Vec::new(),
3062            // `0.0 - percent`, not `-percent`: a permitted drop of zero
3063            // serializes as 0.0 rather than -0.0.
3064            expected: Expectation::RelativeChangeAtLeast {
3065                value: MetricValue::Percentage(0.0 - percent),
3066            },
3067            observed: count_b.map(MetricValue::Count),
3068            scope: self.scope,
3069            evidence: evidence.b,
3070            bounds: None,
3071            baseline: Some(BaselineReading {
3072                observed: count_a.map(MetricValue::Count),
3073                evidence: evidence.a,
3074                change: count_change.map(MetricValue::Percentage),
3075                bounds: None,
3076            }),
3077            status: CheckStatus::Passed,
3078            message: String::new(),
3079        };
3080        let exact = |reading: Option<DistinctReading>| {
3081            reading.is_some_and(|reading| reading.approximate == Some(false))
3082        };
3083        let reason = if b.is_none() {
3084            Some(NotEvaluated::ColumnNotProfiled)
3085        } else if a.is_none() {
3086            Some(NotEvaluated::NotInBaseline)
3087        } else if count_b.is_none() {
3088            Some(NotEvaluated::NotAssessed)
3089        } else if count_a.is_none() {
3090            Some(NotEvaluated::NotInBaseline)
3091        } else if !exact(a) || !exact(b) {
3092            Some(NotEvaluated::ApproximateCount)
3093        } else {
3094            definition_gap(
3095                delta.metric_semantics.a.as_ref(),
3096                delta.metric_semantics.b.as_ref(),
3097                [Definition::NullTokens, Definition::JsonNumberReading]
3098                    .iter()
3099                    .filter(|definition| definition.reaches(facts)),
3100            )
3101        };
3102        let subject = "this column's distinct count";
3103        if let Some(reason) = reason {
3104            let mut check = not_evaluated_change(check, reason, subject);
3105            // A nested column holds values but has no distinct count.
3106            if count_b.is_none()
3107                && b.is_some_and(|b| b.count.is_none() && b.non_null.is_some_and(|n| n > 0))
3108            {
3109                check.message = "the report counted no distinct values for this column".into();
3110            }
3111            return check;
3112        }
3113        let (Some(a), Some(b), Some(count_change)) = (a, b, count_change) else {
3114            unreachable!("a counted column has a reading and a change on both sides")
3115        };
3116        let allowed = 0.0 - rounded_2(percent);
3117        let count_held = count_change >= allowed;
3118        let share_held = || {
3119            let share = |reading: DistinctReading| {
3120                reading.count.expect("counted") as f64 / reading.non_null.expect("counted") as f64
3121            };
3122            relative_change(share(a), share(b)) >= allowed
3123        };
3124        check.status = self.decide_change(&evidence, count_held || share_held());
3125        check.message = match check.status {
3126            CheckStatus::Passed if count_held => {
3127                format!("{subject} fell no more than allowed from the baseline")
3128            }
3129            CheckStatus::Passed => format!(
3130                "{subject} fell more than allowed from the baseline, and its distinct share of \
3131                 non-null values fell no more than allowed, so the drop follows fewer values"
3132            ),
3133            CheckStatus::Failed => format!(
3134                "{subject} and its distinct share of non-null values both fell more than allowed \
3135                 from the baseline"
3136            ),
3137            CheckStatus::NotEvaluated(_) => evidence_message(subject),
3138        };
3139        check
3140    }
3141
3142    /// Whether the side without `column` shows its source lacks it: the
3143    /// side's selection included the column, so it was not in what the side
3144    /// read, and the side's column set covers the whole source. Under
3145    /// [`PolicyScope::Observed`] the question is about what was read, so a
3146    /// column set covering part of the source still decides. `unselected` is
3147    /// the reason when the selection left the column out.
3148    fn absence_status(
3149        &self,
3150        lacking: &ReportSide,
3151        column: &str,
3152        unselected: NotEvaluated,
3153    ) -> CheckStatus {
3154        match lacking.column_selection() {
3155            None => CheckStatus::NotEvaluated(NotEvaluated::SettingUnrecorded {
3156                setting: "columns".to_string(),
3157            }),
3158            Some(selection) if !selection.includes(column) => CheckStatus::NotEvaluated(unselected),
3159            Some(_) => match (self.scope, lacking.schema_evidence().gap()) {
3160                (PolicyScope::FullSource, Some(gap)) => {
3161                    CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
3162                }
3163                _ => CheckStatus::Failed,
3164            },
3165        }
3166    }
3167
3168    fn require_column_check(
3169        &self,
3170        current: &ReportSide,
3171        current_names: &HashSet<&str>,
3172        column: &str,
3173    ) -> Check {
3174        let status = if current_names.contains(column) {
3175            CheckStatus::Passed
3176        } else {
3177            self.absence_status(current, column, NotEvaluated::ColumnNotProfiled)
3178        };
3179        let message = match &status {
3180            CheckStatus::Passed => "the required column was profiled",
3181            CheckStatus::Failed => "the required column is not in the source the report read",
3182            CheckStatus::NotEvaluated(NotEvaluated::ColumnNotProfiled) => {
3183                "the run's column selection left the required column out"
3184            }
3185            CheckStatus::NotEvaluated(NotEvaluated::SettingUnrecorded { .. }) => {
3186                "the report does not record which columns it selected, so a missing column \
3187                 cannot be shown to be absent from the source"
3188            }
3189            CheckStatus::NotEvaluated(_) => {
3190                "the required column is not in the records read, and the records that were not \
3191                 read may hold it"
3192            }
3193        };
3194        self.column_check(
3195            CheckCode::RequireColumn,
3196            column,
3197            Expectation::Present,
3198            current,
3199            None,
3200            status,
3201            message,
3202        )
3203    }
3204
3205    fn forbid_removed_check(
3206        &self,
3207        baseline: &ReportSide,
3208        current: &ReportSide,
3209        current_names: &HashSet<&str>,
3210        column: &str,
3211    ) -> Check {
3212        let status = if current_names.contains(column) {
3213            CheckStatus::Passed
3214        } else {
3215            self.absence_status(
3216                current,
3217                column,
3218                NotEvaluated::SettingChanged {
3219                    setting: "columns".to_string(),
3220                },
3221            )
3222        };
3223        let message = match &status {
3224            CheckStatus::Passed => "the column the baseline profiled is still profiled",
3225            CheckStatus::Failed => {
3226                "a column the baseline profiled is not in the source the report read"
3227            }
3228            CheckStatus::NotEvaluated(NotEvaluated::SettingChanged { .. }) => {
3229                "the report's column selection left out a column the baseline profiled"
3230            }
3231            CheckStatus::NotEvaluated(NotEvaluated::SettingUnrecorded { .. }) => {
3232                "the report does not record which columns it selected, so a column the baseline \
3233                 profiled cannot be shown to be absent from its source"
3234            }
3235            CheckStatus::NotEvaluated(_) => {
3236                "a column the baseline profiled is not in the records the report read, and the \
3237                 records that were not read may hold it"
3238            }
3239        };
3240        self.column_check(
3241            CheckCode::ForbidRemovedColumn,
3242            column,
3243            Expectation::Present,
3244            current,
3245            Some(baseline),
3246            status,
3247            message,
3248        )
3249    }
3250
3251    fn forbid_added_check(
3252        &self,
3253        baseline: &ReportSide,
3254        current: &ReportSide,
3255        baseline_names: &HashSet<&str>,
3256        column: &str,
3257    ) -> Check {
3258        let status = if baseline_names.contains(column) {
3259            CheckStatus::Passed
3260        } else {
3261            self.absence_status(
3262                baseline,
3263                column,
3264                NotEvaluated::SettingChanged {
3265                    setting: "columns".to_string(),
3266                },
3267            )
3268        };
3269        let message = match &status {
3270            CheckStatus::Passed => "the column is one the baseline profiled",
3271            CheckStatus::Failed => {
3272                "the report profiled a column the baseline's source did not have"
3273            }
3274            CheckStatus::NotEvaluated(NotEvaluated::SettingChanged { .. }) => {
3275                "the baseline's column selection left this column out"
3276            }
3277            CheckStatus::NotEvaluated(NotEvaluated::SettingUnrecorded { .. }) => {
3278                "the baseline does not record which columns it selected, so this column cannot be \
3279                 shown to be new"
3280            }
3281            CheckStatus::NotEvaluated(_) => {
3282                "this column is not in the records the baseline read, and the records it did not \
3283                 read may hold it"
3284            }
3285        };
3286        self.column_check(
3287            CheckCode::ForbidAddedColumn,
3288            column,
3289            Expectation::InBaseline,
3290            current,
3291            Some(baseline),
3292            status,
3293            message,
3294        )
3295    }
3296
3297    /// The closed-schema rule's statement about the source columns the report
3298    /// did not profile: never decided, since nothing profiled shows them.
3299    fn unprofiled_columns_check(
3300        &self,
3301        baseline: &ReportSide,
3302        current: &ReportSide,
3303        reason: NotEvaluated,
3304    ) -> Check {
3305        let message = match &reason {
3306            NotEvaluated::ColumnNotProfiled => {
3307                "the run profiled a column selection, which may have left out a source column \
3308                 the baseline lacked"
3309            }
3310            NotEvaluated::SettingUnrecorded { .. } => {
3311                "the report does not record which columns it selected, so its columns may not \
3312                 be all of its source's"
3313            }
3314            _ => {
3315                "the report read part of its source, and the records it did not read may hold \
3316                 a column the baseline lacked"
3317            }
3318        };
3319        Check {
3320            column: None,
3321            ..self.column_check(
3322                CheckCode::ForbidAddedColumn,
3323                "",
3324                Expectation::InBaseline,
3325                current,
3326                Some(baseline),
3327                CheckStatus::NotEvaluated(reason),
3328                message,
3329            )
3330        }
3331    }
3332
3333    /// A rule about which columns a report has. Its evidence is the column
3334    /// set's coverage of each side's source, not a number's.
3335    #[allow(clippy::too_many_arguments)]
3336    fn column_check(
3337        &self,
3338        code: CheckCode,
3339        column: &str,
3340        expected: Expectation,
3341        current: &ReportSide,
3342        baseline: Option<&ReportSide>,
3343        status: CheckStatus,
3344        message: &str,
3345    ) -> Check {
3346        Check {
3347            code,
3348            column: Some(column.to_string()),
3349            dimension: None,
3350            finding: None,
3351            findings: Vec::new(),
3352            expected,
3353            observed: None,
3354            scope: self.scope,
3355            evidence: current.schema_evidence(),
3356            bounds: None,
3357            baseline: baseline.map(|baseline| BaselineReading {
3358                observed: None,
3359                evidence: baseline.schema_evidence(),
3360                change: None,
3361                bounds: None,
3362            }),
3363            status,
3364            message: message.to_string(),
3365        }
3366    }
3367
3368    /// Decide a change between two averages or ratios. Under
3369    /// [`PolicyScope::FullSource`] a side computed over part of its source
3370    /// bounds nothing about the rest, so either side's gap leaves the rule
3371    /// unevaluated, the evaluated report's named first.
3372    fn decide_change(&self, evidence: &Sides<Evidence>, satisfied: bool) -> CheckStatus {
3373        match (self.scope, evidence.b.gap().or(evidence.a.gap())) {
3374            (PolicyScope::FullSource, Some(gap)) => {
3375                CheckStatus::NotEvaluated(NotEvaluated::EvidenceIncomplete { gap })
3376            }
3377            _ if satisfied => CheckStatus::Passed,
3378            _ => CheckStatus::Failed,
3379        }
3380    }
3381}
3382
3383/// The schema changes between the two sides, at most one per column, in the
3384/// delta's column order: the baseline's columns, then the added ones. A
3385/// change is reported only where both sides recorded what it reads; a flat
3386/// summary without a column's counts reports neither change for it, and one
3387/// without its type no type change. Column order is not compared, since no
3388/// rule reads it.
3389fn schema_diagnostics(
3390    baseline: &ReportSide,
3391    current: &ReportSide,
3392    delta: &ReportDelta,
3393) -> Vec<Diagnostic> {
3394    let diagnostic = |code, column: &str, data_type, message: &str| Diagnostic {
3395        code,
3396        column: column.to_string(),
3397        data_type,
3398        setting: None,
3399        message: message.to_string(),
3400    };
3401    // Whether each side's identifier hint names the column, `None` when the
3402    // side did not record its hints.
3403    let identified = |side: &ReportSide, column: &str| {
3404        side.identifier_order()
3405            .map(|names| names.iter().any(|name| name == column))
3406    };
3407    // Built once, so a wide schema is not rescanned per column.
3408    fn names(names: &[String]) -> HashSet<&str> {
3409        names.iter().map(String::as_str).collect()
3410    }
3411    fn by_name(side: &ReportSide) -> HashMap<&str, &ColumnSide> {
3412        side.columns()
3413            .iter()
3414            .map(|column| (column.name.as_str(), column))
3415            .collect()
3416    }
3417    let (added, removed) = (names(&delta.schema.added), names(&delta.schema.removed));
3418    let (baseline_columns, current_columns) = (by_name(baseline), by_name(current));
3419    delta
3420        .columns
3421        .iter()
3422        .filter_map(|change| {
3423            let column = change.name.as_str();
3424            // The side without the column decides whether its source lacks
3425            // it: a selection that includes the column would have profiled it
3426            // or refused to run, so the column is not in what that side read.
3427            let unselected = |side: &ReportSide| match side.column_selection() {
3428                Some(selection) if selection.includes(column) => None,
3429                Some(_) => Some(SettingDifference::SettingChanged {
3430                    setting: "columns".to_string(),
3431                }),
3432                None => Some(SettingDifference::SettingUnrecorded {
3433                    setting: "columns".to_string(),
3434                }),
3435            };
3436            if added.contains(column) {
3437                let setting = unselected(baseline);
3438                let message = match setting {
3439                    None => {
3440                        "the report profiled a column the baseline did not find in its source, \
3441                         so the baseline has nothing to measure its change from"
3442                    }
3443                    Some(_) => {
3444                        "the report profiled a column the baseline has no profile for, and the \
3445                         baseline's column selection is not shown to include it"
3446                    }
3447                };
3448                return Some(Diagnostic {
3449                    setting,
3450                    ..diagnostic(DiagnosticCode::ColumnAdded, column, None, message)
3451                });
3452            }
3453            if removed.contains(column) {
3454                let setting = unselected(current);
3455                let message = match setting {
3456                    None => "the baseline profiled a column the report did not find in its source",
3457                    Some(_) => {
3458                        "the baseline profiled a column the report has no profile for, and the \
3459                         report's column selection is not shown to include it"
3460                    }
3461                };
3462                return Some(Diagnostic {
3463                    setting,
3464                    ..diagnostic(DiagnosticCode::ColumnRemoved, column, None, message)
3465                });
3466            }
3467            let (a, b) = (
3468                *baseline_columns.get(column)?,
3469                *current_columns.get(column)?,
3470            );
3471            if a.populated()? && b.all_null()? {
3472                return Some(diagnostic(
3473                    DiagnosticCode::ColumnAllNull,
3474                    column,
3475                    None,
3476                    "this column held values in the baseline, and every value read for it in \
3477                     the report is null",
3478                ));
3479            }
3480            match (&a.data_type, &b.data_type) {
3481                (Some(type_a), Some(type_b))
3482                    if type_a != type_b && a.populated()? && b.populated()? =>
3483                {
3484                    let mut retyped = diagnostic(
3485                        DiagnosticCode::ColumnTypeChanged,
3486                        column,
3487                        Some(Sides {
3488                            a: type_a.clone(),
3489                            b: type_b.clone(),
3490                        }),
3491                        "this column holds values on both sides, and its inferred type differs",
3492                    );
3493                    // Only the identifier hint gives a column the identifier
3494                    // type, so the hint can explain a change only to or from
3495                    // it.
3496                    if *type_a == DataType::Identifier || *type_b == DataType::Identifier {
3497                        let setting = "identifier_columns".to_string();
3498                        retyped.setting =
3499                            match (identified(baseline, column), identified(current, column)) {
3500                                (Some(a), Some(b)) if a == b => None,
3501                                (Some(_), Some(_)) => {
3502                                    Some(SettingDifference::SettingChanged { setting })
3503                                }
3504                                _ => Some(SettingDifference::SettingUnrecorded { setting }),
3505                            };
3506                        if retyped.setting.is_some() {
3507                            retyped.message = "this column holds values on both sides, and its \
3508                                               inferred type differs; the identifier hint, \
3509                                               which sets the type, is not shown to be the \
3510                                               same on both sides"
3511                                .to_string();
3512                        }
3513                    }
3514                    Some(retyped)
3515                }
3516                _ => None,
3517            }
3518        })
3519        .collect()
3520}
3521
3522/// A delta's columns by name, built once per evaluation so a rule over every
3523/// shared column does not rescan the schema for each one.
3524/// Which way a row count rule bounds the change from the baseline.
3525#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3526enum RowCountRule {
3527    Drop,
3528    Growth,
3529}
3530
3531/// What the distinct drop rule reads about one column on one side.
3532#[derive(Debug, Clone, Copy)]
3533struct DistinctReading {
3534    /// Distinct non-null values, `None` when not counted or not recorded.
3535    count: Option<usize>,
3536    /// Whether the count is an estimate, `None` when not recorded.
3537    approximate: Option<bool>,
3538    /// Non-null values read, `None` when the counts were not recorded.
3539    non_null: Option<usize>,
3540}
3541
3542impl DistinctReading {
3543    fn of(column: &ColumnSide) -> Self {
3544        Self {
3545            count: column.unique_count,
3546            approximate: column.unique_count_is_approximate,
3547            non_null: column
3548                .counts
3549                .map(|(total, nulls)| total.saturating_sub(nulls)),
3550        }
3551    }
3552}
3553
3554/// `(b - a) / a` in percent, at the serialized precision. `a` is positive.
3555fn relative_change(a: f64, b: f64) -> f64 {
3556    rounded_2((b - a) / a * 100.0)
3557}
3558
3559struct ColumnIndex<'a> {
3560    changes: HashMap<&'a str, &'a ColumnChange>,
3561    /// Columns the evaluated report profiled.
3562    in_report: HashSet<&'a str>,
3563    /// Columns the baseline profiled.
3564    in_baseline: HashSet<&'a str>,
3565}
3566
3567impl<'a> ColumnIndex<'a> {
3568    fn new(delta: &'a ReportDelta) -> Self {
3569        let schema = &delta.schema;
3570        let names = |lists: [&'a [String]; 2]| {
3571            lists
3572                .into_iter()
3573                .flatten()
3574                .map(String::as_str)
3575                .collect::<HashSet<_>>()
3576        };
3577        Self {
3578            changes: delta
3579                .columns
3580                .iter()
3581                .map(|change| (change.name.as_str(), change))
3582                .collect(),
3583            in_report: names([&schema.common, &schema.added]),
3584            in_baseline: names([&schema.common, &schema.removed]),
3585        }
3586    }
3587}
3588
3589/// `message`, followed when `estimated` by what would make the report's
3590/// duplicate-row count exact: the setting, the limit the count was made
3591/// under, and a value that covers every row it was made over (#1292).
3592fn with_exact_count_hint(message: &str, report: &ProfileReport, estimated: bool) -> String {
3593    let uniqueness = report
3594        .quality
3595        .as_ref()
3596        .and_then(|quality| quality.metrics.uniqueness.as_ref())
3597        .filter(|uniqueness| estimated && uniqueness.duplicate_rows_approximate);
3598    let Some(uniqueness) = uniqueness else {
3599        return message.to_string();
3600    };
3601    let rows = uniqueness.rows_checked;
3602    match uniqueness.duplicate_rows_exact_limit {
3603        Some(limit) => format!(
3604            "{message}. It was counted under a duplicate_rows_exact_limit of {limit} distinct \
3605             rows; a limit of {rows}, the rows checked, counts every row exactly"
3606        ),
3607        None => format!(
3608            "{message}. A duplicate_rows_exact_limit of {rows}, the rows checked, counts every \
3609             row exactly"
3610        ),
3611    }
3612}
3613
3614/// The message of a `forbid_finding` check whose rule could not look.
3615const FINDING_NOT_EVALUATED: &str =
3616    "the finding's rule could not look at the whole report, and found no finding";
3617
3618/// What a finding is about, which decides how far a partial scan answers a
3619/// `forbid_finding` check under [`PolicyScope::FullSource`].
3620///
3621/// Exhaustive on purpose: a new findings code has to say which it is.
3622#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3623enum FindingReach {
3624    /// How the source was read: the scan itself, or the delimiter detection
3625    /// over its first records. Decided whatever part of the source was read.
3626    Read,
3627    /// Something rows witness, which more rows cannot retract: duplicates, a
3628    /// repeated key, a future date, a skipped or ragged record. A finding
3629    /// fails a partial scan; its absence passes only a complete one.
3630    Witness,
3631    /// A share of a column's values, which more rows can move either way.
3632    /// Decided only on a complete scan.
3633    Share,
3634}
3635
3636impl FindingReach {
3637    fn of(code: FindingCode) -> Self {
3638        match code {
3639            FindingCode::PartialScan
3640            | FindingCode::DelimiterAmbiguous
3641            | FindingCode::HeaderNotSplit => Self::Read,
3642            FindingCode::DuplicateRows
3643            | FindingCode::FutureDates
3644            | FindingCode::KeyDuplicates
3645            | FindingCode::RaggedRows
3646            | FindingCode::RecordsSkipped
3647            | FindingCode::TemporalOrderViolations
3648            | FindingCode::UnterminatedQuote => Self::Witness,
3649            FindingCode::AllNull
3650            | FindingCode::ConstantColumn
3651            | FindingCode::LocaleNumbers
3652            | FindingCode::MixedTypes
3653            | FindingCode::NullHeavy
3654            | FindingCode::SensitivePattern => Self::Share,
3655        }
3656    }
3657}
3658
3659/// Why a side's profiled columns may not be all of its source's columns, or
3660/// `None` when they are: every column was selected and the column set covers
3661/// the source. The selection is named ahead of the coverage, since a
3662/// projection leaves columns out however much of the source was read.
3663fn unenumerated_columns(side: &ReportSide) -> Option<NotEvaluated> {
3664    match side.column_selection() {
3665        None => Some(NotEvaluated::SettingUnrecorded {
3666            setting: "columns".to_string(),
3667        }),
3668        Some(ColumnSelection::All) => side
3669            .schema_evidence()
3670            .gap()
3671            .map(|gap| NotEvaluated::EvidenceIncomplete { gap }),
3672        Some(_) => Some(NotEvaluated::ColumnNotProfiled),
3673    }
3674}
3675
3676fn column_names(side: &ReportSide) -> HashSet<&str> {
3677    side.columns()
3678        .iter()
3679        .map(|column| column.name.as_str())
3680        .collect()
3681}
3682
3683fn baseline_reading(
3684    observed: Option<f64>,
3685    evidence: Evidence,
3686    change: Option<f64>,
3687) -> BaselineReading {
3688    BaselineReading {
3689        observed: observed.map(MetricValue::Percentage),
3690        evidence,
3691        change: change.map(MetricValue::Percentage),
3692        bounds: None,
3693    }
3694}
3695
3696/// Leave a rule about change unevaluated, with a fixed sentence naming why.
3697fn not_evaluated_change(mut check: Check, reason: NotEvaluated, subject: &str) -> Check {
3698    check.message = match &reason {
3699        NotEvaluated::NotAssessed if check.column.is_some() => {
3700            "no values were read for this column".to_string()
3701        }
3702        NotEvaluated::NotAssessed => format!("{subject} was not assessed in this report"),
3703        NotEvaluated::ColumnNotProfiled => "this column has no profile in the report".to_string(),
3704        NotEvaluated::NotInBaseline => format!("the baseline carries no value for {subject}"),
3705        NotEvaluated::ApproximateCount => format!(
3706            "{subject} is an estimate on at least one side, or not recorded as exact, and an \
3707             estimate falling is not a column collapsing"
3708        ),
3709        NotEvaluated::SchemaChanged => format!(
3710            "the two reports profiled different columns, so {subject} has a different subject \
3711             on each side"
3712        ),
3713        NotEvaluated::DimensionsChanged => {
3714            format!("{subject} averages a different set of assessed dimensions on each side")
3715        }
3716        NotEvaluated::DefinitionNotComparable { .. } => format!(
3717            "a measurement definition {subject} depends on is not recorded identically in both \
3718             reports"
3719        ),
3720        NotEvaluated::SettingChanged { .. } => format!(
3721            "a setting that moves {subject} on unchanged data differs between the two reports"
3722        ),
3723        NotEvaluated::SettingUnrecorded { .. } => format!(
3724            "a setting that moves {subject} on unchanged data is not recorded in both reports"
3725        ),
3726        NotEvaluated::QualityUnavailable { .. } => {
3727            "the report carries no quality assessment".to_string()
3728        }
3729        NotEvaluated::EvidenceIncomplete { .. } => evidence_message(subject),
3730        // Only a `forbid_finding` check, which is not a rule about change,
3731        // carries this reason.
3732        NotEvaluated::FindingNotEvaluated { .. } => FINDING_NOT_EVALUATED.to_string(),
3733    };
3734    check.status = CheckStatus::NotEvaluated(reason);
3735    check
3736}
3737
3738fn evidence_message(subject: &str) -> String {
3739    format!(
3740        "{subject} was computed over part of the source on at least one side, which bounds \
3741         nothing about the rest"
3742    )
3743}
3744
3745/// A recorded measurement definition a rule about change depends on.
3746#[derive(Debug, Clone, Copy)]
3747enum Definition {
3748    /// The text values counted as null, behind every null count and so every
3749    /// score.
3750    NullTokens,
3751    /// What a pattern match counts, behind the validity score.
3752    PatternMatchCount,
3753    /// What the range and sign rules count, behind the accuracy score.
3754    RangeRuleCount,
3755    /// What key uniqueness divides by, behind the uniqueness score.
3756    KeyUniquenessUnits,
3757    /// What the outlier ratio is measured over, behind the accuracy score.
3758    OutlierUnits,
3759    /// Which columns the outlier test runs on, behind the accuracy score.
3760    OutlierSpread,
3761    /// Which column key uniqueness may measure, behind the uniqueness score.
3762    KeyColumnSource,
3763    /// How values meet outlier fences and rule bounds, behind the accuracy
3764    /// score.
3765    AccuracyComparison,
3766    /// How a JSON number its `f64` does not hold is read, behind the
3767    /// consistency, precision, uniqueness and accuracy scores.
3768    JsonNumberReading,
3769    /// How a sampled score estimates the score over every scanned value,
3770    /// behind the consistency, accuracy, timeliness, validity and precision
3771    /// scores.
3772    SampledScoreEstimator,
3773    /// Which text forms read as dates, behind the consistency and timeliness
3774    /// scores.
3775    DateForms,
3776}
3777
3778impl Definition {
3779    fn key(self) -> &'static str {
3780        match self {
3781            Self::NullTokens => "null_tokens",
3782            Self::PatternMatchCount => "pattern_match_count",
3783            Self::RangeRuleCount => "range_rule_count",
3784            Self::KeyUniquenessUnits => "key_uniqueness_units",
3785            Self::OutlierUnits => "outlier_units",
3786            Self::OutlierSpread => "outlier_spread",
3787            Self::KeyColumnSource => "key_column_source",
3788            Self::AccuracyComparison => "accuracy_comparison",
3789            Self::JsonNumberReading => "json_number_reading",
3790            Self::SampledScoreEstimator => "sampled_score_estimator",
3791            Self::DateForms => "date_forms",
3792        }
3793    }
3794
3795    /// Whether a change of this definition can move the number a rule reads
3796    /// on either of two runs (#1317). One that cannot leaves both numbers as
3797    /// the other definition computes them, so the rule needs no record of
3798    /// it.
3799    fn reaches(self, facts: &RunFacts) -> bool {
3800        match self {
3801            Self::SampledScoreEstimator => facts.part_of_source,
3802            Self::JsonNumberReading => facts.json_numbers,
3803            Self::OutlierSpread => facts.coinciding_quartiles,
3804            Self::DateForms => facts.spaced_datetimes,
3805            Self::NullTokens
3806            | Self::PatternMatchCount
3807            | Self::RangeRuleCount
3808            | Self::KeyUniquenessUnits
3809            | Self::OutlierUnits
3810            | Self::KeyColumnSource
3811            | Self::AccuracyComparison => true,
3812        }
3813    }
3814
3815    /// Whether both sides recorded the definition, with the same value.
3816    fn same(self, a: &MetricSemantics, b: &MetricSemantics) -> bool {
3817        fn agree<T: PartialEq>(a: &Option<T>, b: &Option<T>) -> bool {
3818            a.is_some() && a == b
3819        }
3820        match self {
3821            Self::NullTokens => agree(&a.null_tokens, &b.null_tokens),
3822            Self::PatternMatchCount => agree(&a.pattern_match_count, &b.pattern_match_count),
3823            Self::RangeRuleCount => agree(&a.range_rule_count, &b.range_rule_count),
3824            Self::KeyUniquenessUnits => agree(&a.key_uniqueness_units, &b.key_uniqueness_units),
3825            Self::OutlierUnits => agree(&a.outlier_units, &b.outlier_units),
3826            Self::OutlierSpread => agree(&a.outlier_spread, &b.outlier_spread),
3827            Self::KeyColumnSource => agree(&a.key_column_source, &b.key_column_source),
3828            Self::AccuracyComparison => agree(&a.accuracy_comparison, &b.accuracy_comparison),
3829            Self::JsonNumberReading => agree(&a.json_number_reading, &b.json_number_reading),
3830            Self::SampledScoreEstimator => {
3831                agree(&a.sampled_score_estimator, &b.sampled_score_estimator)
3832            }
3833            Self::DateForms => agree(&a.date_forms, &b.date_forms),
3834        }
3835    }
3836}
3837
3838/// What two runs recorded about the facts some definitions move a number
3839/// through (#1317). Each is true when either side may meet it, and when a
3840/// side did not record it.
3841struct RunFacts {
3842    /// The score was computed over a sample of the values the scan read: a
3843    /// score over every value read is the same under either
3844    /// `sampled_score_estimator`, however much of the source the scan read.
3845    part_of_source: bool,
3846    /// The source may hold a JSON number, which `json_number_reading` reads.
3847    json_numbers: bool,
3848    /// The outlier test may have run on a column whose quartiles coincide,
3849    /// which `outlier_spread` stops testing.
3850    coinciding_quartiles: bool,
3851    /// A scored column may hold a spaced ISO datetime with a fraction or an
3852    /// offset, which `date_forms` reads as a date and earlier releases as
3853    /// text.
3854    spaced_datetimes: bool,
3855}
3856
3857impl RunFacts {
3858    /// The facts of two sides, for the score of `dimension`, the overall one
3859    /// for `None`.
3860    fn of(sides: &Sides<&ReportSide>, dimension: Option<QualityDimension>) -> Self {
3861        Self {
3862            part_of_source: !(sides.a.sample_evidence(dimension).is_complete()
3863                && sides.b.sample_evidence(dimension).is_complete()),
3864            json_numbers: sides.a.may_read_json_numbers() || sides.b.may_read_json_numbers(),
3865            coinciding_quartiles: sides.a.may_test_coinciding_quartiles()
3866                || sides.b.may_test_coinciding_quartiles(),
3867            spaced_datetimes: sides.a.may_hold_spaced_datetimes()
3868                || sides.b.may_hold_spaced_datetimes(),
3869        }
3870    }
3871}
3872
3873/// The definitions a score reads. Text length and the shape-moment estimator
3874/// feed no score.
3875fn score_definitions(dimension: Option<QualityDimension>) -> &'static [Definition] {
3876    match dimension {
3877        None => &[
3878            Definition::NullTokens,
3879            Definition::PatternMatchCount,
3880            Definition::RangeRuleCount,
3881            Definition::KeyUniquenessUnits,
3882            Definition::OutlierUnits,
3883            Definition::KeyColumnSource,
3884            Definition::AccuracyComparison,
3885            Definition::JsonNumberReading,
3886            Definition::SampledScoreEstimator,
3887            Definition::OutlierSpread,
3888            Definition::DateForms,
3889        ],
3890        Some(QualityDimension::Validity) => &[
3891            Definition::NullTokens,
3892            Definition::PatternMatchCount,
3893            Definition::SampledScoreEstimator,
3894        ],
3895        Some(QualityDimension::Accuracy) => &[
3896            Definition::NullTokens,
3897            Definition::RangeRuleCount,
3898            Definition::OutlierUnits,
3899            Definition::AccuracyComparison,
3900            Definition::JsonNumberReading,
3901            Definition::SampledScoreEstimator,
3902            Definition::OutlierSpread,
3903        ],
3904        Some(QualityDimension::Uniqueness) => &[
3905            Definition::NullTokens,
3906            Definition::KeyUniquenessUnits,
3907            Definition::KeyColumnSource,
3908            Definition::JsonNumberReading,
3909        ],
3910        Some(QualityDimension::Consistency) => &[
3911            Definition::NullTokens,
3912            Definition::JsonNumberReading,
3913            Definition::SampledScoreEstimator,
3914            Definition::DateForms,
3915        ],
3916        Some(QualityDimension::Precision) => &[
3917            Definition::NullTokens,
3918            Definition::JsonNumberReading,
3919            Definition::SampledScoreEstimator,
3920        ],
3921        Some(QualityDimension::Timeliness) => &[
3922            Definition::NullTokens,
3923            Definition::SampledScoreEstimator,
3924            Definition::DateForms,
3925        ],
3926        Some(_) => &[Definition::NullTokens],
3927    }
3928}
3929
3930/// The first definition the two sides do not both record identically.
3931fn definition_gap<'d>(
3932    a: Option<&MetricSemantics>,
3933    b: Option<&MetricSemantics>,
3934    mut definitions: impl Iterator<Item = &'d Definition>,
3935) -> Option<NotEvaluated> {
3936    definitions
3937        .find(|definition| !a.zip(b).is_some_and(|(a, b)| definition.same(a, b)))
3938        .map(|definition| NotEvaluated::DefinitionNotComparable {
3939            definition: definition.key().to_string(),
3940        })
3941}
3942
3943/// Reads one hint list out of a report's recorded hints.
3944type HintColumns = fn(&RecordedHints) -> &Vec<String>;
3945
3946/// How one setting compares across the two sides.
3947#[derive(Debug, Clone, Copy)]
3948enum Agreement {
3949    Same,
3950    Changed,
3951    Unrecorded,
3952}
3953
3954fn agreement<T: PartialEq + ?Sized>(a: Option<&T>, b: Option<&T>) -> Agreement {
3955    match (a, b) {
3956        (Some(a), Some(b)) if a == b => Agreement::Same,
3957        (Some(_), Some(_)) => Agreement::Changed,
3958        _ => Agreement::Unrecorded,
3959    }
3960}
3961
3962/// [`NotEvaluated::SettingChanged`] on `metric_packs` when one side ran
3963/// pattern detection and the other did not, and the score the rule reads
3964/// moved because of it. Validity scores the detected patterns, so a side
3965/// without the `patterns` pack assesses no validity, and its overall score
3966/// averages the other dimensions. The rule reads the packs only where that
3967/// shows: the validity score, and the overall score when validity is
3968/// assessed on one side only. No other score reads a pack: without
3969/// `quality` a side has no score at all, and `statistics` moves none.
3970///
3971/// Checked before the reasons that name the effect (`not_assessed`,
3972/// `not_in_baseline`, `dimensions_changed`), so the rule names the cause.
3973/// A side that did not record its packs (written before 0.14) leaves those
3974/// reasons to decide, as they did before: two sides that both assessed
3975/// validity both ran pattern detection, so the packs need no record there.
3976fn pack_gap(delta: &ReportDelta, dimension: Option<QualityDimension>) -> Option<NotEvaluated> {
3977    let packs = &delta.configuration.metric_packs;
3978    let patterns = |packs: &Vec<MetricPack>| packs.contains(&MetricPack::Patterns);
3979    let differ = packs.a.as_ref().map(patterns)? != packs.b.as_ref().map(patterns)?;
3980    let validity_moved = || {
3981        delta
3982            .dimensions
3983            .iter()
3984            .find(|change| change.dimension == QualityDimension::Validity)
3985            .is_some_and(|change| change.score.a.is_some() != change.score.b.is_some())
3986    };
3987    let reads = match dimension {
3988        Some(dimension) => dimension == QualityDimension::Validity,
3989        None => validity_moved(),
3990    };
3991    (differ && reads).then(|| NotEvaluated::SettingChanged {
3992        setting: "metric_packs".to_string(),
3993    })
3994}
3995
3996/// The first setting a score reads that the two sides do not both record
3997/// identically. The overall score reads every setting. A dimension reads the
3998/// identifier hint, which retypes its columns and names the key uniqueness
3999/// reads, except completeness, which counts nulls whatever the type. Accuracy
4000/// also reads the positive hint, timeliness the temporal ones and its clock,
4001/// and validity the locale, which ranks the detected patterns it scores. The
4002/// clock is read only when `reads_clock` says the score depends on it (see
4003/// [`score_reads_clock`]): a side without a timeliness score records no
4004/// clock, and an average without timeliness does not read one.
4005fn setting_gap(
4006    configuration: &ConfigurationComparison,
4007    identifiers: &Sides<Option<&[String]>>,
4008    dimension: Option<QualityDimension>,
4009    clock_rule: TimelinessClockRule,
4010    reads_clock: bool,
4011) -> Option<NotEvaluated> {
4012    let hints = &configuration.semantic_hints;
4013    let reads = |dimensions: &[QualityDimension]| {
4014        dimension.is_none_or(|dimension| dimensions.contains(&dimension))
4015    };
4016    let hint = |columns: HintColumns| {
4017        agreement(hints.a.as_ref().map(columns), hints.b.as_ref().map(columns))
4018    };
4019    let recorded = |same: Option<bool>| match same {
4020        Some(true) => Agreement::Same,
4021        Some(false) => Agreement::Changed,
4022        None => Agreement::Unrecorded,
4023    };
4024    // Both sides record the pairs themselves from 0.14. A side written before
4025    // records only the columns the pairs named, not which pairs with which,
4026    // so there only two empty pair lists are known to agree.
4027    let pairs = match configuration.temporal_pairs.same {
4028        Some(same) => recorded(Some(same)),
4029        None => match hint(|hints| &hints.temporal_pair_columns) {
4030            Agreement::Same
4031                if hints
4032                    .a
4033                    .as_ref()
4034                    .is_some_and(|hints| !hints.temporal_pair_columns.is_empty()) =>
4035            {
4036                Agreement::Unrecorded
4037            }
4038            other => other,
4039        },
4040    };
4041    let settings = [
4042        (
4043            "score_weights",
4044            dimension.is_none(),
4045            recorded(configuration.score_weights.same),
4046        ),
4047        (
4048            "identifier_columns",
4049            dimension != Some(QualityDimension::Completeness),
4050            // In the order given: the first one present is the key.
4051            agreement(identifiers.a, identifiers.b),
4052        ),
4053        (
4054            "positive_columns",
4055            reads(&[QualityDimension::Accuracy]),
4056            hint(|hints| &hints.positive_columns),
4057        ),
4058        (
4059            "temporal_columns",
4060            reads(&[QualityDimension::Timeliness]),
4061            hint(|hints| &hints.temporal_columns),
4062        ),
4063        (
4064            "temporal_pairs",
4065            reads(&[QualityDimension::Timeliness]),
4066            pairs,
4067        ),
4068        (
4069            "pattern_locale",
4070            reads(&[QualityDimension::Validity]),
4071            recorded(configuration.pattern_locale.same),
4072        ),
4073        (
4074            "timeliness_clock",
4075            reads_clock && reads(&[QualityDimension::Timeliness]),
4076            clock_agreement(
4077                clock_rule,
4078                configuration.timeliness_clock.a.as_ref(),
4079                configuration.timeliness_clock.b.as_ref(),
4080            ),
4081        ),
4082    ];
4083    settings
4084        .into_iter()
4085        .filter(|(_, read, _)| *read)
4086        .find_map(|(setting, _, agreement)| match agreement {
4087            Agreement::Same => None,
4088            Agreement::Changed => Some(NotEvaluated::SettingChanged {
4089                setting: setting.to_string(),
4090            }),
4091            Agreement::Unrecorded => Some(NotEvaluated::SettingUnrecorded {
4092                setting: setting.to_string(),
4093            }),
4094        })
4095}
4096
4097/// Whether the score a rule reads depends on the timeliness clock: both sides
4098/// carry a timeliness score and, for the overall score, timeliness carries
4099/// weight in its average. A dimension weighted `0.0` still reports its score
4100/// but moves no average. The overall rule compares the weights before the
4101/// clock, so the evaluated report's weight stands for both sides; an
4102/// unrecorded weight counts as one, and leaves the rule unevaluated on
4103/// `score_weights` first.
4104fn score_reads_clock(delta: &ReportDelta, dimension: Option<QualityDimension>) -> bool {
4105    let scored = delta
4106        .dimensions
4107        .iter()
4108        .find(|change| change.dimension == QualityDimension::Timeliness)
4109        .is_some_and(|change| change.score.a.is_some() && change.score.b.is_some());
4110    let weighted = dimension.is_some()
4111        || delta
4112            .configuration
4113            .score_weights
4114            .b
4115            .as_ref()
4116            .is_none_or(|weights| weights.timeliness > 0.0);
4117    scored && weighted
4118}
4119
4120/// How the two recorded timeliness clocks compare under the policy's rule.
4121/// The time zone and the maximum age define what "today" and "stale" mean,
4122/// so they must match under either rule; the reference date may differ only
4123/// between two rolling clocks under [`TimelinessClockRule::Rolling`]. The
4124/// mode alone moves no score, so two clocks at the same date agree whichever
4125/// way each date was chosen.
4126fn clock_agreement(
4127    rule: TimelinessClockRule,
4128    a: Option<&TimelinessClock>,
4129    b: Option<&TimelinessClock>,
4130) -> Agreement {
4131    let (Some(a), Some(b)) = (a, b) else {
4132        return Agreement::Unrecorded;
4133    };
4134    let rolling = |clock: &TimelinessClock| clock.mode == TimelinessClockMode::Rolling;
4135    let date_free = rule == TimelinessClockRule::Rolling && rolling(a) && rolling(b);
4136    let same_basis = a.timezone == b.timezone && a.max_data_age_years == b.max_data_age_years;
4137    if same_basis && (date_free || a.reference_date == b.reference_date) {
4138        Agreement::Same
4139    } else {
4140        Agreement::Changed
4141    }
4142}
4143
4144fn check_percentage(
4145    code: CheckCode,
4146    subject: Option<String>,
4147    value: f64,
4148) -> Result<(), PolicyError> {
4149    if value.is_finite() && (0.0..=PERCENTAGE_MAX).contains(&value) {
4150        return Ok(());
4151    }
4152    Err(PolicyError::ThresholdOutOfRange {
4153        code,
4154        subject,
4155        value,
4156    })
4157}
4158
4159/// Quality first, then dimensions in their declared order, each at most once.
4160fn required_metrics_in_order(requested: &[RequiredMetric]) -> Vec<RequiredMetric> {
4161    let mut ordered = Vec::new();
4162    if requested.contains(&RequiredMetric::Quality) {
4163        ordered.push(RequiredMetric::Quality);
4164    }
4165    for dimension in QualityDimension::all() {
4166        if requested.contains(&RequiredMetric::Dimension(dimension)) {
4167            ordered.push(RequiredMetric::Dimension(dimension));
4168        }
4169    }
4170    ordered
4171}
4172
4173fn verdict_of(checks: &[Check]) -> Verdict {
4174    if checks.iter().any(Check::is_violation) {
4175        Verdict::Fail
4176    } else if checks.iter().any(|check| check.not_evaluated().is_some()) {
4177        Verdict::Inconclusive
4178    } else {
4179        Verdict::Pass
4180    }
4181}
4182
4183/// Fill in a check that had no quality assessment to read, naming the reason
4184/// the report recorded. Without that, "you did not ask for this" and "this
4185/// broke" reach a gate as the same absence.
4186fn unavailable_quality(mut check: Check, report: &ProfileReport) -> Check {
4187    let quality_status = quality_status_name(&report.quality_status).to_string();
4188    check.message = match &report.quality_status {
4189        QualityAnalysisStatus::NotRequested => {
4190            "quality metrics were not requested for this run".to_string()
4191        }
4192        QualityAnalysisStatus::NoData => {
4193            "quality was requested but no sample was available to measure".to_string()
4194        }
4195        QualityAnalysisStatus::WithheldByProjection => {
4196            "quality was withheld: the requested dimensions measure whole rows and only \
4197             some columns were profiled"
4198                .to_string()
4199        }
4200        QualityAnalysisStatus::Failed { .. } => "the quality computation failed".to_string(),
4201        QualityAnalysisStatus::Unrecorded | QualityAnalysisStatus::Computed => {
4202            "the report carries no quality assessment".to_string()
4203        }
4204    };
4205    check.status = CheckStatus::NotEvaluated(NotEvaluated::QualityUnavailable { quality_status });
4206    check
4207}
4208
4209fn aggregate_message(status: &CheckStatus, subject: &str) -> String {
4210    match status {
4211        CheckStatus::Passed => format!("{subject} meets the required minimum"),
4212        CheckStatus::Failed => format!("{subject} is below the required minimum"),
4213        CheckStatus::NotEvaluated(_) => format!(
4214            "{subject} was computed over part of the source, which bounds nothing about \
4215             the rest"
4216        ),
4217    }
4218}
4219
4220fn bounded_message(status: &CheckStatus, subject: &str) -> String {
4221    match status {
4222        CheckStatus::Passed => format!(
4223            "{subject} was computed over a sample, and its whole-source interval meets the \
4224             required minimum"
4225        ),
4226        CheckStatus::Failed => format!(
4227            "{subject} was computed over a sample, and its whole-source interval is below the \
4228             required minimum"
4229        ),
4230        CheckStatus::NotEvaluated(_) => format!(
4231            "{subject} was computed over a sample, and the required minimum lies within its \
4232             whole-source interval"
4233        ),
4234    }
4235}
4236
4237/// How a full-source score drop rule reads the change between two scores.
4238enum ChangeReading {
4239    /// Decided on the two point scores.
4240    Points,
4241    /// Decided on the interval the two sides' recorded intervals allow.
4242    Bounded(BoundedChange),
4243    /// A side's evidence settles nothing about its whole source.
4244    Blocked(EvidenceGap),
4245}
4246
4247/// A score change as an interval, and the side intervals it came from (`None`
4248/// for a side whose score is a point).
4249struct BoundedChange {
4250    lower: f64,
4251    upper: f64,
4252    a: Option<CheckBounds>,
4253    b: Option<CheckBounds>,
4254}
4255
4256/// The interval a check decides on, from the report's bounds.
4257fn check_bounds(bounds: &ScoreBounds, interval: Option<ScoreInterval>) -> Option<CheckBounds> {
4258    interval.map(|interval| CheckBounds {
4259        lower: interval.lower,
4260        upper: interval.upper,
4261        confidence_level: bounds.confidence_level,
4262    })
4263}
4264
4265/// The `state` tag the report serializes for its quality status.
4266pub(crate) fn quality_status_name(status: &QualityAnalysisStatus) -> &'static str {
4267    match status {
4268        QualityAnalysisStatus::Computed => "computed",
4269        QualityAnalysisStatus::NotRequested => "not_requested",
4270        QualityAnalysisStatus::NoData => "no_data",
4271        QualityAnalysisStatus::WithheldByProjection => "withheld_by_projection",
4272        QualityAnalysisStatus::Failed { .. } => "failed",
4273        QualityAnalysisStatus::Unrecorded => "unrecorded",
4274    }
4275}
4276
4277/// Share of a column's values that are null, or `None` when no value was read.
4278/// Mirrors the Python binding's `ColumnProfile.null_percentage`.
4279fn null_percentage(profile: &ColumnProfile) -> Option<f64> {
4280    (profile.total_count > 0)
4281        .then(|| profile.null_count as f64 / profile.total_count as f64 * PERCENTAGE_MAX)
4282}
4283
4284/// What a column's date statistics say about its newest date.
4285enum NewestDate {
4286    /// The newest date, from `max_datetime`, and the order the column's
4287    /// slash dates were read in.
4288    Date {
4289        date: chrono::NaiveDate,
4290        order: Option<SlashDateOrder>,
4291    },
4292    /// None was recorded: the column is not typed as a date, no value parsed
4293    /// as one, or statistics were not computed.
4294    Absent,
4295    /// `max_datetime` holds text that is not a `YYYY-MM-DD` date, which the
4296    /// profiler never writes, so the document was written or edited
4297    /// elsewhere. Named apart from [`NewestDate::Absent`] so the check says
4298    /// which happened instead of guessing a date.
4299    Malformed,
4300}
4301
4302fn newest_date(profile: &ColumnProfile) -> NewestDate {
4303    match &profile.stats {
4304        ColumnStats::DateTime(stats) if !stats.max_datetime.is_empty() => {
4305            match chrono::NaiveDate::parse_from_str(&stats.max_datetime, "%Y-%m-%d") {
4306                Ok(date) => NewestDate::Date {
4307                    date,
4308                    order: stats.slash_date_order,
4309                },
4310                Err(_) => NewestDate::Malformed,
4311            }
4312        }
4313        _ => NewestDate::Absent,
4314    }
4315}
4316
4317/// Whether more values could change how the slash dates already read are
4318/// read. An order no value decided (`assumed_day_first`) becomes month-first
4319/// once a value only parses month-first, and a month-first order becomes
4320/// `mixed`, which reads the ambiguous values day-first, once a value only
4321/// parses day-first. A day-first or mixed order keeps every value read where
4322/// it is, and a column without slash dates has no order to change.
4323fn slash_order_settled(order: Option<SlashDateOrder>) -> bool {
4324    !matches!(
4325        order,
4326        Some(SlashDateOrder::AssumedDayFirst | SlashDateOrder::MonthFirst)
4327    )
4328}
4329
4330/// Whether the scan left rows of the source unread, so a type inferred from
4331/// the rows read may not be the whole source's (#1333). Records skipped
4332/// because they could not be turned into rows are skipped on every scan of
4333/// that source, so they leave no row of it unread, and a coverage the
4334/// report does not record is not taken for a complete one.
4335fn scan_left_rows_out(scan: Evidence) -> bool {
4336    matches!(
4337        scan.gap(),
4338        Some(EvidenceGap::Truncated | EvidenceGap::Sampled | EvidenceGap::CoverageUnrecorded)
4339    )
4340}
4341
4342/// Whether a column's date statistics saw every non-null value read.
4343///
4344/// A report that records `date_statistics: every_value` computed them over
4345/// every value read (#1297). One that records nothing computed them from the
4346/// values the profiler retained, the same values its `type_homogeneity`
4347/// classifies, so a classified count short of the non-null count says the
4348/// retained sample left some out. A report without the classification does
4349/// not record which happened.
4350fn date_statistics_evidence(report: &ProfileReport, profile: &ColumnProfile) -> Evidence {
4351    let every_value = report
4352        .metric_semantics
4353        .as_ref()
4354        .and_then(|semantics| semantics.date_statistics)
4355        == Some(DateStatistics::EveryValue);
4356    if every_value {
4357        return Evidence::Complete;
4358    }
4359    let non_null = profile.total_count.saturating_sub(profile.null_count);
4360    match &profile.type_homogeneity {
4361        Some(forms) if forms.classified_count() >= non_null => Evidence::Complete,
4362        Some(_) => Evidence::Incomplete {
4363            reason: EvidenceGap::QualitySampled,
4364        },
4365        None => Evidence::Incomplete {
4366            reason: EvidenceGap::CoverageUnrecorded,
4367        },
4368    }
4369}
4370
4371/// How much of the source the scan itself covered.
4372///
4373/// Truncation is named ahead of sampling and sampling ahead of skipped
4374/// records, so the gap reported is the largest one.
4375pub(crate) fn scan_evidence(execution: &ExecutionMetadata) -> Evidence {
4376    scan_coverage(
4377        !execution.source_exhausted || execution.truncation_reason.is_some(),
4378        execution.sampling_applied,
4379        execution.error_count > 0,
4380    )
4381}
4382
4383/// [`scan_evidence`] over the three recorded facts it reads, for a report
4384/// delta reading them from a flat summary.
4385pub(crate) fn scan_coverage(truncated: bool, sampled: bool, records_skipped: bool) -> Evidence {
4386    let reason = if truncated {
4387        Some(EvidenceGap::Truncated)
4388    } else if sampled {
4389        Some(EvidenceGap::Sampled)
4390    } else if records_skipped {
4391        Some(EvidenceGap::RecordsSkipped)
4392    } else {
4393        None
4394    };
4395    match reason {
4396        Some(reason) => Evidence::Incomplete { reason },
4397        None => Evidence::Complete,
4398    }
4399}
4400
4401/// Which part of the assessment a check reads, and so whose provenance
4402/// decides whether its number covers every scanned row.
4403#[derive(Debug, Clone, Copy)]
4404pub(crate) enum Provenance {
4405    /// The aggregate over every dimension.
4406    Overall,
4407    /// One dimension, through whichever components it is built from.
4408    Dimension(QualityDimension),
4409    /// One named component, as recorded in the assessment's confidence.
4410    Component(&'static str),
4411}
4412
4413/// The component labels a dimension is built from.
4414///
4415/// Uniqueness is the one dimension with two, and they can differ in
4416/// provenance: a full-stream row tracker counts duplicates over every row
4417/// while the key scan reads the retained sample.
4418pub(crate) fn dimension_components(dimension: QualityDimension) -> &'static [&'static str] {
4419    match dimension {
4420        QualityDimension::Completeness => &["completeness"],
4421        QualityDimension::Consistency => &["consistency"],
4422        QualityDimension::Uniqueness => &["key_uniqueness", "duplicate_rows"],
4423        QualityDimension::Accuracy => &["accuracy"],
4424        QualityDimension::Timeliness => &["timeliness"],
4425        QualityDimension::Validity => &["validity"],
4426        QualityDimension::Precision => &["precision"],
4427    }
4428}
4429
4430/// Whether `label` names a component of a dimension this build knows.
4431fn is_known(label: &str) -> bool {
4432    QualityDimension::all()
4433        .into_iter()
4434        .flat_map(dimension_components)
4435        .any(|component| *component == label)
4436}
4437
4438/// Whether the number a check reads came from every scanned row or from a
4439/// retained sample of them.
4440///
4441/// Resolved per component, so a check about one dimension is not downgraded by
4442/// another dimension's sampling.
4443fn quality_evidence(quality: Option<&QualityAssessment>, provenance: Provenance) -> Evidence {
4444    let Some(quality) = quality else {
4445        // No assessment to read; the check that called this reports the
4446        // absence itself, and there is no number for evidence to describe.
4447        return Evidence::Complete;
4448    };
4449    sampled_component_evidence(
4450        quality.sampled_dimensions().as_deref(),
4451        &quality.unlisted_components(),
4452        &quality.metrics.assessed_dimensions(),
4453        overall_left_open(
4454            quality.recorded_score_bounds(),
4455            |dimension| quality.metrics.dimension_score(dimension).is_none(),
4456            Some(&quality.metrics.score_weights),
4457        ),
4458        provenance,
4459    )
4460}
4461
4462/// Whether a dimension the sample left open (`ScoreBounds::open_dimensions`)
4463/// can still enter the overall score: it is unassessed and carries a
4464/// positive weight under the current `weights` (#1304). A scan of every
4465/// value may assess it, and its weight would move the score, so the overall
4466/// score is not settled by the sample. Unknown weights count as positive.
4467/// The assessed dimensions alone cannot show this, since the open one is not
4468/// among them.
4469pub(crate) fn overall_left_open(
4470    bounds: Option<&ScoreBounds>,
4471    unassessed: impl Fn(QualityDimension) -> bool,
4472    weights: Option<&dataprof_core::QualityScoreWeights>,
4473) -> bool {
4474    bounds.is_some_and(|bounds| {
4475        bounds
4476            .open_dimensions
4477            .iter()
4478            .filter_map(|name| name.parse::<QualityDimension>().ok())
4479            .any(|dimension| {
4480                unassessed(dimension)
4481                    && weights.is_none_or(|weights| weights.weight(dimension) > 0.0)
4482            })
4483    })
4484}
4485
4486/// [`quality_evidence`] over the recorded facts it reads: the sampled
4487/// component labels (`None` when the report did not record them), the
4488/// components computed with signal that neither list names
4489/// ([`QualityAssessment::unlisted_components`]), the dimensions the
4490/// overall score weighs, and whether the recorded bounds leave the overall
4491/// score open ([`overall_left_open`]). A report delta reads the same facts
4492/// from a flat summary, which has no [`QualityAssessment`] behind it, and
4493/// findings read one component through it, so the gate, the delta and
4494/// findings resolve coverage by one rule.
4495pub(crate) fn sampled_component_evidence(
4496    sampled: Option<&[String]>,
4497    unlisted: &[String],
4498    assessed: &[QualityDimension],
4499    overall_open: bool,
4500    provenance: Provenance,
4501) -> Evidence {
4502    let Some(sampled) = sampled else {
4503        return Evidence::Incomplete {
4504            reason: EvidenceGap::CoverageUnrecorded,
4505        };
4506    };
4507    // A sampled label this build does not know belongs to a dimension a
4508    // later release added. Its weight is in the stored overall score, and
4509    // its dimension was dropped when the report was read, so nothing here
4510    // rules out that it reaches the score: the score is not certified.
4511    if matches!(provenance, Provenance::Overall) && !sampled.iter().all(|label| is_known(label)) {
4512        return Evidence::Incomplete {
4513            reason: EvidenceGap::CoverageUnrecorded,
4514        };
4515    }
4516    // The components the number reads. The overall score is a weighted
4517    // average over the *assessed* dimensions, so a sampled dimension the
4518    // weights exclude does not reach it. Reporting the aggregate as sampled
4519    // because of one would withhold a verdict the number does not depend on.
4520    let reads: Vec<&str> = match provenance {
4521        Provenance::Overall => assessed
4522            .iter()
4523            .copied()
4524            .flat_map(dimension_components)
4525            .copied()
4526            .collect(),
4527        Provenance::Dimension(dimension) => dimension_components(dimension).to_vec(),
4528        Provenance::Component(component) => vec![component],
4529    };
4530    let any_in = |labels: &[String]| {
4531        reads
4532            .iter()
4533            .any(|component| labels.iter().any(|label| label == component))
4534    };
4535    // A component with signal that neither list names has no recorded
4536    // coverage, and unknown coverage is a larger gap than a sample.
4537    if any_in(unlisted) {
4538        return Evidence::Incomplete {
4539            reason: EvidenceGap::CoverageUnrecorded,
4540        };
4541    }
4542    // The overall score may weigh a dimension the sample left unassessed.
4543    if any_in(sampled) || (matches!(provenance, Provenance::Overall) && overall_open) {
4544        Evidence::Incomplete {
4545            reason: EvidenceGap::QualitySampled,
4546        }
4547    } else {
4548        Evidence::Complete
4549    }
4550}
4551
4552/// Every public type in this module is `#[non_exhaustive]` (#894), and so is
4553/// every enum variant with named fields, so the gate can gain variants,
4554/// struct fields and variant fields (#749) without breaking callers. Tuple
4555/// variants such as `CheckStatus::NotEvaluated(_)` are not marked: growing
4556/// one changes its positional shape, which is a redesign, not an extension.
4557///
4558/// The attribute only binds outside this crate, which is where doctests
4559/// compile. Each block below builds one struct with update syntax from a
4560/// supplied value. That is rejected only for a non-exhaustive struct from
4561/// another crate, so a field added later cannot make a block fail for a
4562/// different reason. The enums and their variants are checked by
4563/// `tests::every_public_type_is_non_exhaustive`, because no `match` or
4564/// pattern stays independent of the variants and fields they gain.
4565///
4566/// Stable rustdoc does not check the error code of a `compile_fail` block, so
4567/// any error would pass one. `tests/public_api_facade.rs` names the fields
4568/// used here in code that must compile, so a renamed field fails there instead
4569/// of passing here for the wrong reason.
4570///
4571/// ```compile_fail
4572/// use dataprof_runtime::CheckBounds;
4573/// fn f(base: CheckBounds) -> CheckBounds {
4574///     CheckBounds { lower: 0.0, ..base }
4575/// }
4576/// ```
4577///
4578/// ```compile_fail
4579/// use dataprof_runtime::Check;
4580/// fn f(base: Check) -> Check {
4581///     Check { message: String::new(), ..base }
4582/// }
4583/// ```
4584///
4585/// ```compile_fail
4586/// use dataprof_runtime::GateResult;
4587/// fn f(base: GateResult) -> GateResult {
4588///     GateResult { checks: Vec::new(), ..base }
4589/// }
4590/// ```
4591#[cfg(doctest)]
4592struct NonExhaustiveGuards;
4593
4594#[cfg(test)]
4595mod tests {
4596    use std::collections::HashMap;
4597
4598    use dataprof_core::{
4599        ColumnStats, DataSource, DataType, FileFormat, QualityScoreWeights, TruncationReason,
4600    };
4601    use dataprof_metrics::{QualityMetrics, UniquenessMetrics};
4602    use serde_json::{Value, json};
4603
4604    use super::*;
4605
4606    /// The source-level half of `NonExhaustiveGuards` (#894): every `pub` type
4607    /// declared in this module carries `#[non_exhaustive]`, and so does every
4608    /// variant with named fields inside a `pub enum`. Reading the source keeps
4609    /// the check independent of the variants and fields the types gain, and
4610    /// covers a type or variant added later without a list to update. The
4611    /// findings module shares the gate's evidence and takes the same rule
4612    /// (#909).
4613    #[test]
4614    fn every_public_type_is_non_exhaustive() {
4615        assert_non_exhaustive(include_str!("quality_gate.rs"), 15, 6);
4616        assert_non_exhaustive(include_str!("findings.rs"), 10, 2);
4617    }
4618
4619    /// `source` declares at least `types` public types and `variants`
4620    /// variants with named fields, all of them `#[non_exhaustive]`.
4621    fn assert_non_exhaustive(source: &str, types: usize, variants_with_fields: usize) {
4622        let lines: Vec<&str> = source.lines().collect();
4623        let marked = |i: usize| {
4624            lines[..i]
4625                .iter()
4626                .rev()
4627                .map(|l| l.trim())
4628                .take_while(|l| l.starts_with("#[") || l.starts_with("///"))
4629                .any(|l| l == "#[non_exhaustive]")
4630        };
4631        let identifier = |s: &str| -> String {
4632            s.chars()
4633                .take_while(|c| c.is_alphanumeric() || *c == '_')
4634                .collect()
4635        };
4636        let mut declared = Vec::new();
4637        let mut variants = Vec::new();
4638        let mut unmarked = Vec::new();
4639        let mut in_enum: Option<String> = None;
4640        for (i, line) in lines.iter().enumerate() {
4641            if let Some(enum_name) = &in_enum {
4642                if *line == "}" {
4643                    in_enum = None;
4644                } else if let Some(rest) = line.strip_prefix("    ")
4645                    && rest.starts_with(|c: char| c.is_ascii_uppercase())
4646                    && rest.contains(" {")
4647                {
4648                    let variant = format!("{enum_name}::{}", identifier(rest));
4649                    if !marked(i) {
4650                        unmarked.push(variant.clone());
4651                    }
4652                    variants.push(variant);
4653                }
4654                continue;
4655            }
4656            let Some(rest) = line
4657                .strip_prefix("pub enum ")
4658                .or_else(|| line.strip_prefix("pub struct "))
4659            else {
4660                continue;
4661            };
4662            let name = identifier(rest);
4663            if !marked(i) {
4664                unmarked.push(name.clone());
4665            }
4666            if line.starts_with("pub enum ") {
4667                in_enum = Some(name.clone());
4668            }
4669            declared.push(name);
4670        }
4671        // Guard the premise: the scan found the module's types and the
4672        // variants with named fields at all.
4673        assert!(declared.len() >= types, "{declared:?}");
4674        assert!(variants.len() >= variants_with_fields, "{variants:?}");
4675        assert!(unmarked.is_empty(), "not #[non_exhaustive]: {unmarked:?}");
4676    }
4677    use crate::ReportAssembler;
4678
4679    fn source() -> DataSource {
4680        DataSource::File {
4681            path: "drop.csv".to_string(),
4682            format: FileFormat::Csv,
4683            size_bytes: 256,
4684            modified_at: None,
4685            parquet_metadata: None,
4686            csv_metadata: None,
4687        }
4688    }
4689
4690    fn column(name: &str, total: usize, nulls: usize) -> ColumnProfile {
4691        ColumnProfile {
4692            name: name.to_string(),
4693            data_type: DataType::String,
4694            null_count: nulls,
4695            total_count: total,
4696            unique_count: None,
4697            unique_count_is_approximate: None,
4698            unique_count_lower_bound: None,
4699            invalid_count: None,
4700            type_homogeneity: None,
4701            locale_number_count: None,
4702            native_type: None,
4703            stats: ColumnStats::None,
4704            patterns: None,
4705        }
4706    }
4707
4708    /// Two columns: `id` clean, `note` one-fifth null.
4709    fn sample_data() -> HashMap<String, Vec<String>> {
4710        let ids = (1..=5).map(|n| n.to_string()).collect::<Vec<_>>();
4711        let notes = vec!["a", "b", "c", "d", ""]
4712            .into_iter()
4713            .map(str::to_string)
4714            .collect::<Vec<_>>();
4715        HashMap::from([("id".to_string(), ids), ("note".to_string(), notes)])
4716    }
4717
4718    fn complete_report() -> ProfileReport {
4719        ReportAssembler::new(source(), ExecutionMetadata::new(5, 2, 10))
4720            .columns(vec![column("id", 5, 0), column("note", 5, 1)])
4721            .with_quality_data(sample_data())
4722            .build()
4723    }
4724
4725    fn truncated_report() -> ProfileReport {
4726        ReportAssembler::new(
4727            source(),
4728            ExecutionMetadata::new(5, 2, 10).with_truncation(TruncationReason::MaxRows(5)),
4729        )
4730        .columns(vec![column("id", 5, 0), column("note", 5, 1)])
4731        .with_quality_data(sample_data())
4732        .build()
4733    }
4734
4735    fn no_quality_report() -> ProfileReport {
4736        ReportAssembler::new(source(), ExecutionMetadata::new(5, 2, 10))
4737            .columns(vec![column("id", 5, 0), column("note", 5, 1)])
4738            .with_quality_data(sample_data())
4739            .skip_quality()
4740            .build()
4741    }
4742
4743    /// A report whose uniqueness dimension witnessed `duplicates` duplicate
4744    /// rows, truncated so the evidence behind it is partial.
4745    fn duplicate_report(duplicates: usize, approximate: bool) -> ProfileReport {
4746        let metrics = QualityMetrics {
4747            uniqueness: Some(UniquenessMetrics {
4748                duplicate_rows: duplicates,
4749                key_uniqueness: 100.0,
4750                high_cardinality_warning: false,
4751                rows_checked: 5,
4752                key_column: None,
4753                key_values_checked: None,
4754                duplicate_rows_approximate: approximate,
4755                duplicate_rows_exact_limit: None,
4756            }),
4757            ..QualityMetrics::default()
4758        };
4759        ProfileReport::new(
4760            source(),
4761            vec![column("id", 5, 0)],
4762            ExecutionMetadata::new(5, 1, 10).with_truncation(TruncationReason::MaxRows(5)),
4763            Some(QualityAssessment::exact(metrics)),
4764        )
4765    }
4766
4767    fn check_for(result: &GateResult, code: CheckCode) -> &Check {
4768        result
4769            .checks
4770            .iter()
4771            .find(|check| check.code == code)
4772            .unwrap_or_else(|| panic!("no {code} check in {:?}", result.checks))
4773    }
4774
4775    fn column_check<'a>(result: &'a GateResult, name: &str) -> &'a Check {
4776        result
4777            .checks
4778            .iter()
4779            .find(|check| check.column.as_deref() == Some(name))
4780            .unwrap_or_else(|| panic!("no check for column {name}"))
4781    }
4782
4783    /// A report whose quality sample is smaller than the scan: the assembler
4784    /// bifurcates, and the dimensions computed from the reservoir are recorded
4785    /// as sampled while the ones from exact counters are not.
4786    ///
4787    /// This is the ordinary large-file shape, not an edge case. It is also the
4788    /// one an execution-metadata-only gate gets wrong: the source *was*
4789    /// exhausted and no row sampler ran, so `source_exhausted` and
4790    /// `sampling_applied` both say the scan covered everything.
4791    fn reservoir_report() -> ProfileReport {
4792        ReportAssembler::new(source(), ExecutionMetadata::new(100, 2, 10))
4793            .columns(vec![column("id", 100, 0), column("note", 100, 20)])
4794            .with_quality_data(sample_data())
4795            .build()
4796    }
4797
4798    #[test]
4799    fn a_reservoir_backed_score_is_decided_on_its_whole_source_interval() {
4800        let report = reservoir_report();
4801        assert!(report.execution.source_exhausted);
4802        assert!(!report.execution.sampling_applied);
4803        let quality = report.quality.as_ref().expect("quality was computed");
4804        let sampled = quality
4805            .sampled_dimensions()
4806            .expect("a profiling run records its provenance");
4807        assert!(
4808            !sampled.is_empty(),
4809            "the assembler did not bifurcate; this test no longer reaches the \
4810             case it guards"
4811        );
4812        let interval = quality
4813            .score_bounds()
4814            .expect("a sampled assessment carries bounds")
4815            .overall_score
4816            .expect("every sampled dimension here is bounded");
4817        assert!(
4818            interval.lower < interval.upper && interval.upper < 100.0,
4819            "a five-value sample leaves room on both sides: {interval:?}"
4820        );
4821        let decide = |min: f64| {
4822            let result = QualityPolicy::new()
4823                .min_quality_score(min)
4824                .evaluate(&report)
4825                .unwrap();
4826            // The scan itself was complete; only the metric's own evidence is
4827            // not, and a decision on the interval does not pretend otherwise.
4828            assert_eq!(result.evidence, Evidence::Complete);
4829            let check = check_for(&result, CheckCode::MinQualityScore).clone();
4830            assert_eq!(
4831                check.evidence,
4832                Evidence::Incomplete {
4833                    reason: EvidenceGap::QualitySampled
4834                }
4835            );
4836            assert_eq!(
4837                check.bounds.map(|bounds| (bounds.lower, bounds.upper)),
4838                Some((interval.lower, interval.upper))
4839            );
4840            (result.verdict, check)
4841        };
4842
4843        let (verdict, _) = decide(interval.lower);
4844        assert_eq!(verdict, Verdict::Pass);
4845
4846        let (verdict, check) = decide((interval.lower + interval.upper) / 2.0);
4847        assert_eq!(verdict, Verdict::Inconclusive);
4848        assert_eq!(
4849            check.not_evaluated(),
4850            Some(&NotEvaluated::EvidenceIncomplete {
4851                gap: EvidenceGap::QualitySampled
4852            })
4853        );
4854
4855        let (verdict, _) = decide(interval.upper + 0.01);
4856        assert_eq!(verdict, Verdict::Fail);
4857    }
4858
4859    /// A threshold equal to the value a check shows is met, and a report that
4860    /// was saved and loaded reaches the same verdict (#1085). The live report
4861    /// holds raw scores, the loaded one their two-decimal serialization, so a
4862    /// raw comparison failed `observed 66.67 >= 66.67` live and passed it
4863    /// loaded. Every (report, rule) that goes wrong is collected first.
4864    #[test]
4865    fn a_threshold_at_the_shown_value_passes_live_and_after_a_round_trip() {
4866        // One value in three missing: completeness and null share are thirds.
4867        let thirds = ReportAssembler::new(source(), ExecutionMetadata::new(3, 1, 10))
4868            .columns(vec![column("x", 3, 1)])
4869            .with_quality_data(HashMap::from([(
4870                "x".to_string(),
4871                vec!["1".to_string(), "2".to_string(), String::new()],
4872            )]))
4873            .build();
4874        let mut wrong = Vec::new();
4875        for (label, report) in [
4876            ("thirds", thirds),
4877            ("reservoir", reservoir_report()),
4878            ("complete", complete_report()),
4879        ] {
4880            let loaded: ProfileReport =
4881                serde_json::from_str(&serde_json::to_string(&report).unwrap()).unwrap();
4882            let quality = report.quality.as_ref().expect("quality was computed");
4883            let mut policies = Vec::new();
4884            // A sampled report's overall rule decides on its interval: the
4885            // lower-bound case below covers it.
4886            if quality
4887                .score_bounds()
4888                .and_then(|bounds| bounds.overall_score)
4889                .is_none()
4890            {
4891                policies.push((
4892                    "overall".to_string(),
4893                    QualityPolicy::new()
4894                        .min_quality_score(rounded_2(report.quality_score().unwrap())),
4895                ));
4896            }
4897            for (name, score) in &quality.scores().dimension_scores {
4898                let Some(score) = score else { continue };
4899                // On a sampled report the full-source rule decides on the
4900                // interval, so its threshold is the shown lower bound.
4901                let shown = quality
4902                    .score_bounds()
4903                    .and_then(|bounds| bounds.dimension_scores.get(name).copied().flatten())
4904                    .map_or(*score, |interval| interval.lower);
4905                let dimension: QualityDimension = name.parse().unwrap();
4906                policies.push((
4907                    name.clone(),
4908                    QualityPolicy::new().min_dimension_score(dimension, rounded_2(shown)),
4909                ));
4910            }
4911            for column in &report.column_profiles {
4912                let shown = rounded_2(null_percentage(column).unwrap());
4913                policies.push((
4914                    format!("null {}", column.name),
4915                    QualityPolicy::new().max_null_percentage(column.name.clone(), shown),
4916                ));
4917            }
4918            if let Some(interval) = quality
4919                .score_bounds()
4920                .and_then(|bounds| bounds.overall_score)
4921            {
4922                policies.push((
4923                    "overall lower bound".to_string(),
4924                    QualityPolicy::new().min_quality_score(rounded_2(interval.lower)),
4925                ));
4926            }
4927            // A minimum written with more decimals than a check shows is
4928            // compared as shown: `expected` reads 66.67 for 66.674, so a score
4929            // shown as 66.67 meets it, as an allowance does for a change.
4930            if label == "thirds" {
4931                policies.push((
4932                    "completeness at a third decimal".to_string(),
4933                    QualityPolicy::new()
4934                        .min_dimension_score(QualityDimension::Completeness, 66.674),
4935                ));
4936            }
4937            for (rule, policy) in policies {
4938                let live = policy.evaluate(&report).unwrap().verdict;
4939                let reloaded = policy.evaluate(&loaded).unwrap().verdict;
4940                if live != Verdict::Pass || reloaded != Verdict::Pass {
4941                    wrong.push(format!(
4942                        "{label} {rule}: live {live:?}, loaded {reloaded:?}"
4943                    ));
4944                }
4945            }
4946        }
4947        assert!(wrong.is_empty(), "{wrong:#?}");
4948    }
4949
4950    /// The interval half of #1085. A bound that rounds up when saved, such as
4951    /// 79.426 shown as 79.43, decided a minimum of 79.43 one way live and the
4952    /// other way loaded: inconclusive then pass at the lower bound, fail then
4953    /// inconclusive at the upper one. The verdict must not change on reload.
4954    #[test]
4955    fn a_bound_that_rounds_up_decides_the_same_live_and_loaded() {
4956        let mut report = reservoir_report();
4957        let quality = report.quality.clone().expect("quality was computed");
4958        let mut bounds = quality
4959            .score_bounds()
4960            .expect("a sampled report is bounded")
4961            .clone();
4962        let interval = bounds
4963            .overall_score
4964            .as_mut()
4965            .expect("the overall score is bounded");
4966        // Just below each shown value, so saving rounds both up.
4967        interval.lower = rounded_2(interval.lower) - 0.004;
4968        interval.upper = rounded_2(interval.upper) - 0.004;
4969        let (lower, upper) = (interval.lower, interval.upper);
4970        assert!(rounded_2(lower) > lower && rounded_2(upper) > upper && lower < upper);
4971        report.quality = Some(quality.with_score_bounds(Some(bounds)));
4972        let loaded: ProfileReport =
4973            serde_json::from_str(&serde_json::to_string(&report).unwrap()).unwrap();
4974
4975        let mut wrong = Vec::new();
4976        for (label, min) in [("lower", rounded_2(lower)), ("upper", rounded_2(upper))] {
4977            let policy = QualityPolicy::new().min_quality_score(min);
4978            let live = policy.evaluate(&report).unwrap().verdict;
4979            let reloaded = policy.evaluate(&loaded).unwrap().verdict;
4980            if live != reloaded {
4981                wrong.push(format!(
4982                    "min at the shown {label} bound {min}: live {live:?}, loaded {reloaded:?}"
4983                ));
4984            }
4985        }
4986        assert!(wrong.is_empty(), "{wrong:#?}");
4987    }
4988
4989    #[test]
4990    fn an_observed_scope_decides_on_the_sampled_score_itself() {
4991        let report = reservoir_report();
4992        let score = report.quality_score().unwrap();
4993        let result = QualityPolicy::new()
4994            .min_quality_score(score)
4995            .scope(PolicyScope::Observed)
4996            .evaluate(&report)
4997            .unwrap();
4998        let check = check_for(&result, CheckCode::MinQualityScore);
4999        assert_eq!(result.verdict, Verdict::Pass);
5000        assert_eq!(check.bounds, None);
5001    }
5002
5003    #[test]
5004    fn a_sampled_score_without_recorded_bounds_stays_unevaluated() {
5005        let mut report = reservoir_report();
5006        let quality = report.quality.take().unwrap();
5007        report.quality = Some(QualityAssessment::new(quality.metrics, quality.confidence));
5008
5009        let result = QualityPolicy::new()
5010            .min_quality_score(1.0)
5011            .evaluate(&report)
5012            .unwrap();
5013        assert_eq!(result.verdict, Verdict::Inconclusive);
5014        assert_eq!(check_for(&result, CheckCode::MinQualityScore).bounds, None);
5015    }
5016
5017    /// Provenance is resolved per component, so a dimension computed from
5018    /// exact counters is still decidable when another one was sampled.
5019    #[test]
5020    fn an_exactly_counted_dimension_survives_another_dimensions_sampling() {
5021        let report = reservoir_report();
5022        let sampled = report
5023            .quality
5024            .as_ref()
5025            .expect("quality was computed")
5026            .sampled_dimensions()
5027            .expect("a profiling run records its provenance");
5028        assert!(
5029            !sampled.iter().any(|label| label == "completeness"),
5030            "completeness is supposed to come from exact column counters"
5031        );
5032
5033        let result = QualityPolicy::new()
5034            .min_dimension_score(QualityDimension::Completeness, 1.0)
5035            .min_dimension_score(QualityDimension::Consistency, 1.0)
5036            .evaluate(&report)
5037            .unwrap();
5038
5039        assert_eq!(
5040            result
5041                .checks
5042                .iter()
5043                .find(|check| check.dimension == Some(QualityDimension::Completeness))
5044                .map(|check| check.evidence),
5045            Some(Evidence::Complete)
5046        );
5047        assert_eq!(
5048            result
5049                .checks
5050                .iter()
5051                .find(|check| check.dimension == Some(QualityDimension::Consistency))
5052                .map(|check| check.evidence),
5053            Some(Evidence::Incomplete {
5054                reason: EvidenceGap::QualitySampled
5055            })
5056        );
5057    }
5058
5059    /// A report read back from a document written before dataprof recorded
5060    /// provenance does not say whether its numbers cover every scanned row.
5061    ///
5062    /// The compat path used to answer `Exact` for those, which is a claim the
5063    /// document never made: a full-source policy would then rest a verdict on
5064    /// numbers that may have come from a sample. The Python reload path
5065    /// reports the same gap, so the two agree on legacy input.
5066    #[test]
5067    fn a_legacy_document_without_recorded_coverage_is_not_read_as_a_full_scan() {
5068        let document = serde_json::to_value(complete_report()).expect("serializes");
5069        let mut legacy = document.clone();
5070        // Pre-0.10 documents carried the metrics flat, with no confidence.
5071        legacy["quality"] = document["quality"]["metrics"].clone();
5072        let report: ProfileReport = serde_json::from_value(legacy).expect("legacy document loads");
5073
5074        assert_eq!(
5075            report
5076                .quality
5077                .as_ref()
5078                .expect("the metrics survived")
5079                .sampled_dimensions(),
5080            None
5081        );
5082
5083        let result = QualityPolicy::new()
5084            .min_quality_score(1.0)
5085            .evaluate(&report)
5086            .unwrap();
5087        assert_eq!(result.verdict, Verdict::Inconclusive);
5088        let check = check_for(&result, CheckCode::MinQualityScore);
5089        assert_eq!(
5090            check.evidence,
5091            Evidence::Incomplete {
5092                reason: EvidenceGap::CoverageUnrecorded
5093            }
5094        );
5095
5096        // Asked about what the metrics measured, the same report is decidable.
5097        let observed = QualityPolicy::new()
5098            .min_quality_score(1.0)
5099            .scope(PolicyScope::Observed)
5100            .evaluate(&report)
5101            .unwrap();
5102        assert_eq!(observed.verdict, Verdict::Pass);
5103    }
5104
5105    /// Weights say what reaches the aggregate, not what was measured.
5106    ///
5107    /// The overall score renormalizes over the assessed dimensions, so a
5108    /// sampled dimension the weights exclude cannot move it, and reporting the
5109    /// aggregate as sampled because of one would withhold a verdict the number
5110    /// does not depend on. The excluded dimension keeps its own provenance.
5111    #[test]
5112    fn a_zero_weighted_sampled_dimension_does_not_taint_the_overall_score() {
5113        let mut report = reservoir_report();
5114        let quality = report.quality.as_mut().expect("quality was computed");
5115        let sampled = quality
5116            .sampled_dimensions()
5117            .expect("a profiling run records its provenance");
5118        assert!(
5119            sampled.iter().any(|label| label == "consistency"),
5120            "consistency is supposed to come from the reservoir"
5121        );
5122        // Completeness is the one dimension here computed from exact column
5123        // counters, so weighting only it leaves an aggregate that no sampled
5124        // component reaches.
5125        quality.metrics.score_weights = QualityScoreWeights {
5126            completeness: 1.0,
5127            consistency: 0.0,
5128            uniqueness: 0.0,
5129            accuracy: 0.0,
5130            timeliness: 0.0,
5131            validity: 0.0,
5132            precision: 0.0,
5133        };
5134
5135        let result = QualityPolicy::new()
5136            .min_quality_score(1.0)
5137            .min_dimension_score(QualityDimension::Consistency, 1.0)
5138            .evaluate(&report)
5139            .unwrap();
5140
5141        // The aggregate no longer depends on the sampled dimension.
5142        assert_eq!(
5143            check_for(&result, CheckCode::MinQualityScore).evidence,
5144            Evidence::Complete
5145        );
5146        // The dimension itself still reports where its number came from.
5147        assert_eq!(
5148            check_for(&result, CheckCode::MinDimensionScore).evidence,
5149            Evidence::Incomplete {
5150                reason: EvidenceGap::QualitySampled
5151            }
5152        );
5153    }
5154
5155    /// A dimension excluded from the aggregate by a zero weight is still
5156    /// measured, and a gate reading its score still needs its provenance.
5157    ///
5158    /// Confidence used to be downgraded to `NotAssessed` whenever the
5159    /// *weighted* set was empty, which erased the sampling record for every
5160    /// dimension at once.
5161    #[test]
5162    fn zero_weights_do_not_erase_the_sampling_record() {
5163        let mut report = reservoir_report();
5164        let quality = report.quality.as_mut().expect("quality was computed");
5165        quality.metrics.score_weights = QualityScoreWeights {
5166            completeness: 0.0,
5167            consistency: 0.0,
5168            uniqueness: 0.0,
5169            accuracy: 0.0,
5170            timeliness: 0.0,
5171            validity: 0.0,
5172            precision: 0.0,
5173        };
5174        let reassessed =
5175            QualityAssessment::new(quality.metrics.clone(), quality.confidence.clone());
5176
5177        assert!(reassessed.metrics.assessed_dimensions().is_empty());
5178        assert!(
5179            reassessed
5180                .sampled_dimensions()
5181                .expect("provenance survives")
5182                .iter()
5183                .any(|label| label == "consistency"),
5184            "a measured dimension kept no record of coming from a sample"
5185        );
5186    }
5187
5188    #[test]
5189    fn met_requirements_pass() {
5190        let result = QualityPolicy::new()
5191            .min_quality_score(1.0)
5192            .max_null_percentage_any(50.0)
5193            .evaluate(&complete_report())
5194            .unwrap();
5195
5196        assert_eq!(result.verdict, Verdict::Pass);
5197        assert!(result.passed());
5198        assert_eq!(result.violations().count(), 0);
5199        assert_eq!(result.unevaluated().count(), 0);
5200    }
5201
5202    #[test]
5203    fn violated_requirement_fails() {
5204        let result = QualityPolicy::new()
5205            .max_null_percentage("note", 10.0)
5206            .evaluate(&complete_report())
5207            .unwrap();
5208
5209        assert_eq!(result.verdict, Verdict::Fail);
5210        assert!(!result.passed());
5211        let violation = result.violations().next().expect("one violation");
5212        assert_eq!(violation.code, CheckCode::MaxNullPercentage);
5213        assert_eq!(violation.column.as_deref(), Some("note"));
5214        assert_eq!(violation.observed, Some(MetricValue::Percentage(20.0)));
5215        assert_eq!(
5216            violation.expected,
5217            Expectation::AtMost {
5218                value: MetricValue::Percentage(10.0)
5219            }
5220        );
5221    }
5222
5223    /// The named limit decides its own column; the wildcard covers the rest.
5224    #[test]
5225    fn named_limit_overrides_the_wildcard() {
5226        let result = QualityPolicy::new()
5227            .max_null_percentage("note", 50.0)
5228            .max_null_percentage_any(0.0)
5229            .evaluate(&complete_report())
5230            .unwrap();
5231
5232        assert_eq!(result.verdict, Verdict::Pass);
5233        assert_eq!(result.checks.len(), 2);
5234        assert_eq!(
5235            column_check(&result, "note").expected,
5236            Expectation::AtMost {
5237                value: MetricValue::Percentage(50.0)
5238            }
5239        );
5240        assert_eq!(
5241            column_check(&result, "id").expected,
5242            Expectation::AtMost {
5243                value: MetricValue::Percentage(0.0)
5244            }
5245        );
5246    }
5247
5248    /// Thresholds are percentages. A caller who writes the 0..1 ratio instead
5249    /// would otherwise get a gate that silently never fires.
5250    #[test]
5251    fn thresholds_are_on_the_percentage_scale() {
5252        let result = QualityPolicy::new()
5253            .min_quality_score(0.9)
5254            .evaluate(&complete_report())
5255            .unwrap();
5256        assert_eq!(result.verdict, Verdict::Pass);
5257
5258        let err = QualityPolicy::new()
5259            .min_quality_score(101.0)
5260            .evaluate(&complete_report())
5261            .unwrap_err();
5262        assert_eq!(
5263            err,
5264            PolicyError::ThresholdOutOfRange {
5265                code: CheckCode::MinQualityScore,
5266                subject: None,
5267                value: 101.0,
5268            }
5269        );
5270        assert!(
5271            QualityPolicy::new()
5272                .max_null_percentage("id", f64::NAN)
5273                .validate()
5274                .is_err()
5275        );
5276    }
5277
5278    #[test]
5279    fn empty_policy_is_rejected_rather_than_passing_everything() {
5280        assert_eq!(
5281            QualityPolicy::new()
5282                .evaluate(&complete_report())
5283                .unwrap_err(),
5284            PolicyError::NoRequirements
5285        );
5286    }
5287
5288    /// A metric that was never analyzed is not zero and not a pass. The check
5289    /// names the recorded reason, so a pipeline can tell a misconfiguration
5290    /// from an incident.
5291    #[test]
5292    fn unanalyzed_quality_is_inconclusive_not_a_pass() {
5293        let result = QualityPolicy::new()
5294            .min_quality_score(90.0)
5295            .evaluate(&no_quality_report())
5296            .unwrap();
5297
5298        assert_eq!(result.verdict, Verdict::Inconclusive);
5299        assert!(!result.passed());
5300        let check = check_for(&result, CheckCode::MinQualityScore);
5301        assert_eq!(check.observed, None);
5302        assert_eq!(
5303            check.not_evaluated(),
5304            Some(&NotEvaluated::QualityUnavailable {
5305                quality_status: "not_requested".to_string(),
5306            })
5307        );
5308    }
5309
5310    /// `require_quality` is how a caller says the absence itself is a failure.
5311    #[test]
5312    fn require_quality_turns_absence_into_a_violation() {
5313        let result = QualityPolicy::new()
5314            .require_quality()
5315            .min_quality_score(90.0)
5316            .evaluate(&no_quality_report())
5317            .unwrap();
5318
5319        assert_eq!(result.verdict, Verdict::Fail);
5320        let required = check_for(&result, CheckCode::RequireMetric);
5321        assert!(required.is_violation());
5322        assert_eq!(required.expected, Expectation::Analyzed);
5323        assert_eq!(required.observed, None);
5324    }
5325
5326    #[test]
5327    fn require_dimension_fails_when_the_dimension_had_nothing_to_assess() {
5328        let result = QualityPolicy::new()
5329            .require_dimension(QualityDimension::Timeliness)
5330            .evaluate(&complete_report())
5331            .unwrap();
5332
5333        assert_eq!(result.verdict, Verdict::Fail);
5334        assert_eq!(
5335            check_for(&result, CheckCode::RequireMetric).dimension,
5336            Some(QualityDimension::Timeliness)
5337        );
5338    }
5339
5340    /// A dimension that was computed but had nothing to assess is reported as
5341    /// such, separately from quality never having been requested.
5342    #[test]
5343    fn unassessed_dimension_is_distinct_from_unrequested_quality() {
5344        let result = QualityPolicy::new()
5345            .min_dimension_score(QualityDimension::Timeliness, 90.0)
5346            .evaluate(&complete_report())
5347            .unwrap();
5348
5349        assert_eq!(result.verdict, Verdict::Inconclusive);
5350        assert_eq!(
5351            check_for(&result, CheckCode::MinDimensionScore).not_evaluated(),
5352            Some(&NotEvaluated::NotAssessed)
5353        );
5354    }
5355
5356    /// A column the report does not profile is not decided either way: the
5357    /// report does not record whether it was projected away or absent.
5358    #[test]
5359    fn unprofiled_column_is_not_evaluated() {
5360        let result = QualityPolicy::new()
5361            .max_null_percentage("absent", 0.0)
5362            .evaluate(&complete_report())
5363            .unwrap();
5364
5365        assert_eq!(result.verdict, Verdict::Inconclusive);
5366        assert_eq!(
5367            column_check(&result, "absent").not_evaluated(),
5368            Some(&NotEvaluated::ColumnNotProfiled)
5369        );
5370    }
5371
5372    /// The whole point of the scope: a ratio measured over a prefix of the
5373    /// source says nothing about the rows that were never read.
5374    #[test]
5375    fn a_ratio_over_a_partial_scan_cannot_pass_a_full_source_policy() {
5376        let report = truncated_report();
5377        let result = QualityPolicy::new()
5378            .max_null_percentage_any(50.0)
5379            .evaluate(&report)
5380            .unwrap();
5381
5382        assert_eq!(result.verdict, Verdict::Inconclusive);
5383        assert_eq!(
5384            result.evidence,
5385            Evidence::Incomplete {
5386                reason: EvidenceGap::Truncated
5387            }
5388        );
5389        let check = column_check(&result, "note");
5390        assert_eq!(
5391            check.not_evaluated(),
5392            Some(&NotEvaluated::EvidenceIncomplete {
5393                gap: EvidenceGap::Truncated
5394            })
5395        );
5396        // The number was still read; it is the generalization that is refused.
5397        assert_eq!(check.observed, Some(MetricValue::Percentage(20.0)));
5398
5399        // Asked about the rows that were actually read, the same report passes.
5400        let observed = QualityPolicy::new()
5401            .max_null_percentage_any(50.0)
5402            .scope(PolicyScope::Observed)
5403            .evaluate(&report)
5404            .unwrap();
5405        assert_eq!(observed.verdict, Verdict::Pass);
5406    }
5407
5408    /// Duplicates already seen do not stop being duplicates when more rows are
5409    /// read, so a partial scan can still fail a full-source requirement.
5410    #[test]
5411    fn a_witnessed_duplicate_fails_despite_a_partial_scan() {
5412        let result = QualityPolicy::new()
5413            .max_duplicate_rows(0)
5414            .evaluate(&duplicate_report(2, false))
5415            .unwrap();
5416
5417        assert_eq!(result.verdict, Verdict::Fail);
5418        let check = check_for(&result, CheckCode::MaxDuplicateRows);
5419        assert_eq!(check.observed, Some(MetricValue::Count(2)));
5420        assert_eq!(
5421            check.evidence,
5422            Evidence::Incomplete {
5423                reason: EvidenceGap::Truncated
5424            }
5425        );
5426    }
5427
5428    /// A clean prefix is not a clean source.
5429    #[test]
5430    fn no_duplicate_in_a_partial_scan_is_not_a_pass() {
5431        let result = QualityPolicy::new()
5432            .max_duplicate_rows(0)
5433            .evaluate(&duplicate_report(0, false))
5434            .unwrap();
5435
5436        assert_eq!(result.verdict, Verdict::Inconclusive);
5437        assert_eq!(
5438            check_for(&result, CheckCode::MaxDuplicateRows).not_evaluated(),
5439            Some(&NotEvaluated::EvidenceIncomplete {
5440                gap: EvidenceGap::Truncated
5441            })
5442        );
5443    }
5444
5445    /// An estimated count is not a duplicate anyone saw, so it witnesses
5446    /// nothing and settles neither direction.
5447    #[test]
5448    fn an_estimated_duplicate_count_settles_neither_direction() {
5449        let result = QualityPolicy::new()
5450            .max_duplicate_rows(0)
5451            .evaluate(&duplicate_report(2, true))
5452            .unwrap();
5453
5454        assert_eq!(result.verdict, Verdict::Inconclusive);
5455        let check = check_for(&result, CheckCode::MaxDuplicateRows);
5456        assert_eq!(
5457            check.not_evaluated(),
5458            Some(&NotEvaluated::EvidenceIncomplete {
5459                gap: EvidenceGap::Truncated
5460            })
5461        );
5462        // The gap is the estimate, not unread rows: the message said "the rows
5463        // that were not read" on a source read to the end (#819). It names
5464        // the setting that would count every row exactly (#1292); this
5465        // report records no limit, as one written before 0.14.
5466        assert_eq!(
5467            check.message,
5468            "the duplicate-row count is an estimate, which can neither witness \
5469             duplicates above the allowance nor rule them out. A \
5470             duplicate_rows_exact_limit of 5, the rows checked, counts every row exactly"
5471        );
5472    }
5473
5474    /// One null in 20,001 rows shows as a 0.00% null percentage, so a zero
5475    /// percentage limit passes it; the count ceiling decides on the count
5476    /// (#1119).
5477    #[test]
5478    fn a_null_count_ceiling_is_decided_on_the_exact_count() {
5479        let report = ReportAssembler::new(source(), ExecutionMetadata::new(20_001, 2, 10))
5480            .columns(vec![column("key", 20_001, 1), column("clean", 20_001, 0)])
5481            .build();
5482
5483        let percentage = QualityPolicy::new()
5484            .max_null_percentage("key", 0.0)
5485            .evaluate(&report)
5486            .unwrap();
5487        assert_eq!(percentage.verdict, Verdict::Pass);
5488
5489        let count = QualityPolicy::new()
5490            .max_null_count("key", 0)
5491            .max_null_count_any(0)
5492            .evaluate(&report)
5493            .unwrap();
5494        assert_eq!(count.verdict, Verdict::Fail);
5495        let key = column_check(&count, "key");
5496        assert_eq!(key.code, CheckCode::MaxNullCount);
5497        assert_eq!(key.observed, Some(MetricValue::Count(1)));
5498        assert_eq!(key.status, CheckStatus::Failed);
5499        assert_eq!(column_check(&count, "clean").status, CheckStatus::Passed);
5500    }
5501
5502    /// Nulls already counted stay counted, so a partial scan that saw more
5503    /// than allowed fails a full-source rule; one that saw no more than
5504    /// allowed decides nothing about the rows it did not read.
5505    #[test]
5506    fn witnessed_nulls_fail_a_partial_scan_and_a_clean_prefix_does_not_pass() {
5507        let result = QualityPolicy::new()
5508            .max_null_count_any(0)
5509            .evaluate(&truncated_report())
5510            .unwrap();
5511
5512        assert_eq!(result.verdict, Verdict::Fail);
5513        assert_eq!(column_check(&result, "note").status, CheckStatus::Failed);
5514        assert_eq!(
5515            column_check(&result, "id").not_evaluated(),
5516            Some(&NotEvaluated::EvidenceIncomplete {
5517                gap: EvidenceGap::Truncated
5518            })
5519        );
5520
5521        let observed = QualityPolicy::new()
5522            .max_null_count("note", 1)
5523            .scope(PolicyScope::Observed)
5524            .evaluate(&truncated_report())
5525            .unwrap();
5526        assert_eq!(observed.verdict, Verdict::Pass);
5527    }
5528
5529    /// A column with no values read has no null percentage, but it has a null
5530    /// count, zero: a full scan of an empty source decides the count rule.
5531    #[test]
5532    fn a_column_with_no_values_read_has_a_null_count_of_zero() {
5533        let report = ReportAssembler::new(source(), ExecutionMetadata::new(0, 1, 10))
5534            .columns(vec![column("key", 0, 0)])
5535            .build();
5536
5537        let count = QualityPolicy::new()
5538            .max_null_count("key", 0)
5539            .evaluate(&report)
5540            .unwrap();
5541        assert_eq!(count.verdict, Verdict::Pass);
5542        assert_eq!(
5543            column_check(&count, "key").observed,
5544            Some(MetricValue::Count(0))
5545        );
5546
5547        let percentage = QualityPolicy::new()
5548            .max_null_percentage("key", 0.0)
5549            .evaluate(&report)
5550            .unwrap();
5551        assert_eq!(
5552            column_check(&percentage, "key").not_evaluated(),
5553            Some(&NotEvaluated::NotAssessed)
5554        );
5555    }
5556
5557    /// A named column's ceiling replaces the wildcard for that column, and a
5558    /// named column the report did not profile is not read as zero nulls.
5559    #[test]
5560    fn a_named_null_count_overrides_the_wildcard_and_absence_is_unevaluated() {
5561        let result = QualityPolicy::new()
5562            .max_null_count("note", 1)
5563            .max_null_count("absent", 0)
5564            .max_null_count_any(0)
5565            .evaluate(&complete_report())
5566            .unwrap();
5567
5568        let checks: Vec<_> = result
5569            .checks
5570            .iter()
5571            .map(|check| (check.column.clone().unwrap(), check.expected))
5572            .collect();
5573        assert_eq!(
5574            checks,
5575            vec![
5576                (
5577                    "absent".to_string(),
5578                    Expectation::AtMost {
5579                        value: MetricValue::Count(0)
5580                    }
5581                ),
5582                (
5583                    "note".to_string(),
5584                    Expectation::AtMost {
5585                        value: MetricValue::Count(1)
5586                    }
5587                ),
5588                (
5589                    "id".to_string(),
5590                    Expectation::AtMost {
5591                        value: MetricValue::Count(0)
5592                    }
5593                ),
5594            ]
5595        );
5596        assert_eq!(
5597            column_check(&result, "absent").not_evaluated(),
5598            Some(&NotEvaluated::ColumnNotProfiled)
5599        );
5600        assert_eq!(column_check(&result, "note").status, CheckStatus::Passed);
5601        assert_eq!(result.verdict, Verdict::Inconclusive);
5602    }
5603
5604    /// A conclusive violation outranks an unevaluated requirement: the gate
5605    /// has an answer even though it could not check everything.
5606    #[test]
5607    fn a_violation_outranks_an_unevaluated_check() {
5608        let result = QualityPolicy::new()
5609            .max_duplicate_rows(0)
5610            .min_dimension_score(QualityDimension::Timeliness, 90.0)
5611            .evaluate(&duplicate_report(2, false))
5612            .unwrap();
5613
5614        assert_eq!(result.verdict, Verdict::Fail);
5615        assert_eq!(result.unevaluated().count(), 1);
5616    }
5617
5618    /// Evaluation order is fixed by the data, not by the order requirements
5619    /// were added, so the same policy always serializes the same document.
5620    #[test]
5621    fn evaluation_order_does_not_depend_on_insertion_order() {
5622        let report = complete_report();
5623        let forward = QualityPolicy::new()
5624            .max_null_percentage("note", 50.0)
5625            .max_null_percentage("id", 50.0)
5626            .evaluate(&report)
5627            .unwrap();
5628        let reverse = QualityPolicy::new()
5629            .max_null_percentage("id", 50.0)
5630            .max_null_percentage("note", 50.0)
5631            .evaluate(&report)
5632            .unwrap();
5633
5634        assert_eq!(forward, reverse);
5635        let columns: Vec<_> = forward
5636            .checks
5637            .iter()
5638            .map(|check| check.column.clone().unwrap())
5639            .collect();
5640        assert_eq!(columns, vec!["id".to_string(), "note".to_string()]);
5641    }
5642
5643    /// The serialized shape is the contract a CI system reads. Percentages
5644    /// carry the report's 2dp convention; counts stay whole.
5645    #[test]
5646    fn result_serializes_into_the_documented_shape() {
5647        let report = complete_report();
5648        let result = QualityPolicy::new()
5649            .max_null_percentage("note", 10.0)
5650            .evaluate(&report)
5651            .unwrap();
5652
5653        assert_eq!(
5654            serde_json::to_value(&result).unwrap(),
5655            json!({
5656                "verdict": "fail",
5657                "scope": "full_source",
5658                "evidence": {"coverage": "complete"},
5659                "checks": [{
5660                    "code": "max_null_percentage",
5661                    "column": "note",
5662                    "expected": {"comparison": "at_most", "value": 10.0},
5663                    "observed": 20.0,
5664                    "scope": "full_source",
5665                    "evidence": {"coverage": "complete"},
5666                    "status": "failed",
5667                    "message": "this column's null percentage is above the allowance",
5668                }],
5669                // The report's build and source version, written either way.
5670                "generator": serde_json::to_value(&report.generator).unwrap(),
5671                "source_identity": null,
5672            })
5673        );
5674    }
5675
5676    #[test]
5677    fn an_unevaluated_check_serializes_its_reason() {
5678        let result = QualityPolicy::new()
5679            .min_quality_score(90.0)
5680            .evaluate(&no_quality_report())
5681            .unwrap();
5682        let check = &serde_json::to_value(&result).unwrap()["checks"][0];
5683
5684        assert_eq!(check["status"], Value::String("not_evaluated".to_string()));
5685        assert_eq!(
5686            check["reason"],
5687            Value::String("quality_unavailable".to_string())
5688        );
5689        assert_eq!(
5690            check["quality_status"],
5691            Value::String("not_requested".to_string())
5692        );
5693        assert!(check.get("observed").is_none());
5694    }
5695}