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