Skip to main content

dataprof_runtime/
report_assembler.rs

1//! Centralized report assembly for all profiling engines.
2//!
3//! `ReportAssembler` is the single entry point for constructing a [`ProfileReport`].
4//! It replaces the scattered report construction calls across parsers, engines,
5//! and database connectors, centralizing quality metric calculation and confidence
6//! tracking in one place.
7
8use std::collections::HashMap;
9
10use dataprof_core::{
11    AnalysisOptions, ColumnProfile, ColumnStats, DataProfilerError, DataSource, DataType,
12    ExecutionMetadata, QualityDimension, SemanticHintBinding, SemanticHintKind, SemanticHints,
13};
14use dataprof_metrics::{
15    MetricConfidence, MetricsCalculator, QualityAssessment, RowCompletenessSummary,
16    RowDuplicateSummary, analysis::metrics::BifurcatedResult, columns_without_value_checks,
17    compute_value_hint_bindings,
18};
19
20use crate::{AnalysisSettings, ProfileReport, QualityAnalysisStatus};
21
22/// Builder for constructing a [`ProfileReport`].
23pub struct ReportAssembler {
24    source: DataSource,
25    execution: ExecutionMetadata,
26    columns: Vec<ColumnProfile>,
27    quality_data: Option<HashMap<String, Vec<String>>>,
28    confidence: Option<MetricConfidence>,
29    /// Why quality will not be computed, when it will not be. `None` means the
30    /// caller asked for it.
31    skip: Option<QualityAnalysisStatus>,
32    requested_dimensions: Option<Vec<QualityDimension>>,
33    semantic_hints: SemanticHints,
34    exact_value_hint_bindings: Option<Vec<SemanticHintBinding>>,
35    row_duplicates: Option<RowDuplicateSummary>,
36    row_completeness: Option<RowCompletenessSummary>,
37    /// What the caller profiled with, once `with_analysis_options` saw it.
38    analysis_settings: Option<AnalysisSettings>,
39    /// The fixed date timeliness measures against; `None` reads today's.
40    reference_date: Option<chrono::NaiveDate>,
41    /// Whether the report carries column statistics. When it does not, the
42    /// date statistics an engine kept for the quality pass are dropped once
43    /// quality is computed (#1305).
44    include_statistics: bool,
45    /// Test seam for the failure branch. No input path can currently make
46    /// `MetricsCalculator` return `Err`: both of its error constructions sit
47    /// behind an emptiness check that has already returned by then. The branch
48    /// still has to be handled, because the calculator is a public API whose
49    /// signature says it can fail, so this is how the handling is exercised.
50    #[cfg(test)]
51    forced_quality_failure: Option<String>,
52}
53
54impl ReportAssembler {
55    /// Create a new assembler with required source and execution metadata.
56    pub fn new(source: DataSource, execution: ExecutionMetadata) -> Self {
57        Self {
58            source,
59            execution,
60            columns: Vec::new(),
61            quality_data: None,
62            confidence: None,
63            skip: None,
64            requested_dimensions: None,
65            semantic_hints: SemanticHints::default(),
66            exact_value_hint_bindings: None,
67            row_duplicates: None,
68            row_completeness: None,
69            analysis_settings: None,
70            reference_date: None,
71            include_statistics: true,
72            #[cfg(test)]
73            forced_quality_failure: None,
74        }
75    }
76
77    /// Make the quality computation fail with `message`. See
78    /// [`forced_quality_failure`](Self::forced_quality_failure).
79    #[cfg(test)]
80    fn force_quality_failure(mut self, message: &str) -> Self {
81        self.forced_quality_failure = Some(message.to_string());
82        self
83    }
84
85    /// Set the column profiles for this report.
86    pub fn columns(mut self, columns: Vec<ColumnProfile>) -> Self {
87        self.columns = columns;
88        self
89    }
90
91    /// Provide sample data for quality metric calculation.
92    pub fn with_quality_data(mut self, data: HashMap<String, Vec<String>>) -> Self {
93        self.quality_data = Some(data);
94        self
95    }
96
97    /// Override the default metric confidence level.
98    pub fn with_confidence(mut self, confidence: MetricConfidence) -> Self {
99        self.confidence = Some(confidence);
100        self
101    }
102
103    /// Explicitly skip quality metric calculation because the caller did not
104    /// ask for it.
105    ///
106    /// Use [`skip_quality_no_data`](Self::skip_quality_no_data) when quality
107    /// was wanted but no sample is available. An analyzed empty source supplies
108    /// an empty sample through [`with_quality_data`](Self::with_quality_data).
109    pub fn skip_quality(mut self) -> Self {
110        self.skip = Some(QualityAnalysisStatus::NotRequested);
111        self
112    }
113
114    /// Skip quality metric calculation because no sample is available.
115    /// An analyzed empty source must instead supply an empty quality sample;
116    /// that produces an assessment with no assessable dimensions (#723).
117    ///
118    /// A caller that already deselected quality keeps that answer, and only
119    /// that one. Not asking is the more specific reason and does not stop being
120    /// true when the sample is also unavailable. Every other reason is
121    /// replaced: a projection withholds dimensions that *could* have been
122    /// measured, which says nothing once no sample is available at all.
123    pub fn skip_quality_no_data(mut self) -> Self {
124        if !matches!(self.skip, Some(QualityAnalysisStatus::NotRequested)) {
125            self.skip = Some(QualityAnalysisStatus::NoData);
126        }
127        self
128    }
129
130    /// Set the quality dimensions to compute.
131    pub fn with_requested_dimensions(mut self, dims: Vec<QualityDimension>) -> Self {
132        self.requested_dimensions = Some(dims);
133        self
134    }
135
136    /// Set semantic hints used by quality metrics.
137    pub fn with_semantic_hints(mut self, hints: SemanticHints) -> Self {
138        self.semantic_hints = hints;
139        self
140    }
141
142    /// Apply the caller's analysis selection: requested dimensions, semantic
143    /// hints, column projection, and whether quality is computed at all.
144    ///
145    /// Callers still pass their quality sample with
146    /// [`with_quality_data`](Self::with_quality_data); this decides whether it is
147    /// used. Deselecting the quality pack leaves the report with no quality
148    /// object rather than an assessment with every dimension absent — "not
149    /// analyzed" and "analyzed, nothing found" are different answers.
150    pub fn with_analysis_options(mut self, options: &AnalysisOptions) -> Self {
151        self.skip = (!options.include_quality()).then_some(QualityAnalysisStatus::NotRequested);
152        self.semantic_hints = options.semantic_hints().clone();
153        self.reference_date = options.reference_date();
154        self = self.record_analysis_settings(options);
155        self.requested_dimensions = options.quality_dimensions().map(<[_]>::to_vec);
156        if options.has_column_projection() && self.skip.is_none() {
157            // Completeness and uniqueness both contain row-level measurements.
158            // Those measurements have a different meaning after projecting a
159            // row, and the current report schema cannot label only the row-level
160            // fields as projected. Withhold the two dimensions instead of
161            // publishing plausible numbers under full-row names.
162            let mut dimensions = self
163                .requested_dimensions
164                .take()
165                .unwrap_or_else(QualityDimension::all);
166            dimensions.retain(|dimension| {
167                !matches!(
168                    dimension,
169                    QualityDimension::Completeness | QualityDimension::Uniqueness
170                )
171            });
172            if dimensions.is_empty() {
173                self.skip = Some(QualityAnalysisStatus::WithheldByProjection);
174            }
175            self.requested_dimensions = Some(dimensions);
176        }
177        self
178    }
179
180    /// Record the settings `options` profile with, which every report
181    /// carries whether or not quality is computed.
182    ///
183    /// [`with_analysis_options`](Self::with_analysis_options) does this
184    /// itself. A caller that skips quality and so applies nothing else from
185    /// the options calls it on its own.
186    pub fn record_analysis_settings(mut self, options: &AnalysisOptions) -> Self {
187        self.analysis_settings = Some(AnalysisSettings::from_options(options));
188        self.include_statistics = options.include_statistics();
189        self
190    }
191
192    /// Provide full-stream evidence for value-driven semantic hints.
193    ///
194    /// Streaming engines should pass their bounded-memory accumulator output;
195    /// it supersedes evidence recomputed from the retained quality sample.
196    pub fn with_exact_value_hint_bindings(mut self, bindings: Vec<SemanticHintBinding>) -> Self {
197        self.exact_value_hint_bindings = Some(bindings);
198        self
199    }
200
201    /// Provide full-stream row-duplicate counts from an engine's row
202    /// tracker; they supersede the sample-based duplicate scan.
203    pub fn with_row_duplicates(mut self, summary: Option<RowDuplicateSummary>) -> Self {
204        self.row_duplicates = summary;
205        self
206    }
207
208    /// Provide full-stream complete-record counts from an engine's row
209    /// tracker. Without them `complete_records_ratio` can only be bounded
210    /// from below, since per-column null totals cannot tell whether two
211    /// nulls fell in the same record.
212    pub fn with_row_completeness(mut self, summary: Option<RowCompletenessSummary>) -> Self {
213        self.row_completeness = summary;
214        self
215    }
216
217    /// Build the final [`ProfileReport`].
218    ///
219    /// This does not fail. A quality computation that returns an error leaves
220    /// the report without an assessment, exactly as a run that never asked for
221    /// one does, so the report records which of the two happened in
222    /// [`ProfileReport::quality_status`] rather than discarding the column
223    /// profiles that did compute.
224    pub fn build(mut self) -> ProfileReport {
225        self.withhold_container_values();
226        let (quality, status) = match &self.skip {
227            Some(reason) => (None, reason.clone()),
228            None => match &self.quality_data {
229                Some(data) => self.compute_quality(data),
230                None => (None, QualityAnalysisStatus::NoData),
231            },
232        };
233        let bindings = self.compute_hint_bindings();
234        if !self.include_statistics {
235            for column in &mut self.columns {
236                if matches!(column.stats, ColumnStats::DateTime(_)) {
237                    column.stats = ColumnStats::None;
238                }
239            }
240        }
241
242        ProfileReport::new(self.source, self.columns, self.execution, quality)
243            .with_quality_status(status)
244            .with_semantic_hint_bindings(bindings)
245            .with_analysis_settings(self.analysis_settings)
246    }
247
248    /// Keep container columns out of every value-level quality check.
249    ///
250    /// Whatever an engine sampled for a [`DataType::Nested`] column is a
251    /// serialisation of its values, different on every input path, so a
252    /// consistency or format check over it would score the serialiser (#637).
253    /// The column keeps its entry, emptied: its nulls still count toward
254    /// completeness through the profile, and an input of only nested columns
255    /// is still an input with columns rather than an empty one.
256    fn withhold_container_values(&mut self) {
257        let Some(data) = self.quality_data.as_mut() else {
258            return;
259        };
260        for column in &self.columns {
261            if column.data_type == DataType::Nested
262                && let Some(values) = data.get_mut(&column.name)
263            {
264                values.clear();
265            }
266        }
267    }
268
269    /// Measure how each semantic hint bound to the data.
270    ///
271    /// Identifier binding is structural — the hint coerces the column's type, so
272    /// it is read off the column profiles and is always exact. Positive and
273    /// temporal hints are value-driven. Streaming engines provide exact
274    /// full-stream counts; callers without those accumulators fall back to the
275    /// quality data and tag the result exact only when it covers every row.
276    fn compute_hint_bindings(&self) -> Vec<SemanticHintBinding> {
277        if self.semantic_hints.is_empty() {
278            return Vec::new();
279        }
280
281        let mut bindings = Vec::new();
282        for (_, column) in self
283            .semantic_hints
284            .iter()
285            .filter(|(kind, _)| *kind == SemanticHintKind::Identifier)
286        {
287            if let Some(profile) = self.columns.iter().find(|c| c.name == column) {
288                let checked = profile.total_count.saturating_sub(profile.null_count);
289                let matched = if profile.data_type == DataType::Identifier {
290                    checked
291                } else {
292                    0
293                };
294                bindings.push(SemanticHintBinding {
295                    column: column.to_string(),
296                    kind: SemanticHintKind::Identifier,
297                    checked_values: checked,
298                    matched_values: matched,
299                    exact: true,
300                });
301            }
302        }
303
304        if let Some(exact) = &self.exact_value_hint_bindings {
305            let full_coverage = self.execution.source_exhausted && !self.execution.sampling_applied;
306            bindings.extend(exact.iter().cloned().map(|mut binding| {
307                // Engine accumulators cover every value they processed. That
308                // is every source row for ordinary reservoir-backed streaming,
309                // but not when row-level sampling skipped records or an early
310                // stop left part of the source unread.
311                binding.exact &= full_coverage;
312                binding
313            }));
314        } else if let Some(data) = &self.quality_data {
315            let sample_size = data.values().map(|v| v.len()).max().unwrap_or(0);
316            let exact = !self.is_streaming_context(sample_size);
317            bindings.extend(compute_value_hint_bindings(
318                data,
319                &self.semantic_hints,
320                exact,
321            ));
322        }
323
324        bindings
325    }
326
327    fn compute_quality(
328        &self,
329        data: &HashMap<String, Vec<String>>,
330    ) -> (Option<QualityAssessment>, QualityAnalysisStatus) {
331        #[cfg(test)]
332        if let Some(message) = &self.forced_quality_failure {
333            return Self::failed(DataProfilerError::MetricsCalculationError {
334                message: message.clone(),
335            });
336        }
337
338        let sample_size = data.values().map(|v| v.len()).max().unwrap_or(0);
339        let is_streaming = self.is_streaming_context(sample_size);
340
341        if is_streaming {
342            self.compute_bifurcated_quality(data)
343        } else {
344            self.compute_uniform_quality(data)
345        }
346    }
347
348    /// Record a quality computation that was requested, attempted, and failed.
349    fn failed(error: DataProfilerError) -> (Option<QualityAssessment>, QualityAnalysisStatus) {
350        // Still logged, so an operator watching a run sees it happen. The
351        // report carries it too: a log line is not part of the output a
352        // consumer reads back, and absence alone reads as a clean skip.
353        log::warn!("Quality metrics calculation failed: {error}");
354        (
355            None,
356            QualityAnalysisStatus::Failed {
357                error: error.to_string(),
358            },
359        )
360    }
361
362    fn is_streaming_context(&self, sample_size: usize) -> bool {
363        self.execution.sampling_applied
364            || (sample_size > 0 && sample_size < self.execution.rows_processed)
365    }
366
367    fn compute_bifurcated_quality(
368        &self,
369        data: &HashMap<String, Vec<String>>,
370    ) -> (Option<QualityAssessment>, QualityAnalysisStatus) {
371        let calculator = MetricsCalculator::new()
372            .with_row_completeness(self.row_completeness)
373            .with_reference_date(self.reference_date);
374        match calculator.calculate_bifurcated_metrics_with_hints(
375            data,
376            &self.columns,
377            self.requested_dimensions.as_deref(),
378            &self.semantic_hints,
379            self.row_duplicates,
380        ) {
381            Ok(result) => {
382                let confidence = self
383                    .confidence
384                    .clone()
385                    .unwrap_or_else(|| self.mixed_confidence(&result));
386                (
387                    Some(
388                        QualityAssessment::new(result.metrics, confidence)
389                            .with_score_bounds(result.score_bounds)
390                            .with_estimated_scores(result.estimated_scores)
391                            .with_columns_without_value_checks(Some(columns_without_value_checks(
392                                &self.columns,
393                            ))),
394                    ),
395                    QualityAnalysisStatus::Computed,
396                )
397            }
398            Err(error) => Self::failed(error),
399        }
400    }
401
402    fn compute_uniform_quality(
403        &self,
404        data: &HashMap<String, Vec<String>>,
405    ) -> (Option<QualityAssessment>, QualityAnalysisStatus) {
406        let calculator = MetricsCalculator::new()
407            .with_row_completeness(self.row_completeness)
408            .with_reference_date(self.reference_date);
409        match calculator.calculate_comprehensive_metrics_with_hints(
410            data,
411            &self.columns,
412            self.requested_dimensions.as_deref(),
413            &self.semantic_hints,
414            self.row_duplicates,
415        ) {
416            Ok(metrics) => {
417                let confidence = self
418                    .confidence
419                    .clone()
420                    .unwrap_or_else(|| self.uniform_confidence(&metrics, data));
421                // An estimated component is bounded as the bifurcated path
422                // bounds it, so the scores it reaches still decide (#1292).
423                let bounds = match &confidence {
424                    MetricConfidence::Mixed {
425                        sampled_dimensions, ..
426                    } if self.confidence.is_none() => calculator.score_bounds_for(
427                        data,
428                        &self.columns,
429                        &self.semantic_hints,
430                        &metrics,
431                        sampled_dimensions,
432                        self.row_duplicates,
433                    ),
434                    _ => Ok((None, None)),
435                };
436                let (score_bounds, estimated_scores) = match bounds {
437                    Ok(bounds) => bounds,
438                    Err(error) => return Self::failed(error),
439                };
440                (
441                    Some(
442                        QualityAssessment::new(metrics, confidence)
443                            .with_score_bounds(score_bounds)
444                            .with_estimated_scores(estimated_scores)
445                            .with_columns_without_value_checks(Some(columns_without_value_checks(
446                                &self.columns,
447                            ))),
448                    ),
449                    QualityAnalysisStatus::Computed,
450                )
451            }
452            Err(error) => Self::failed(error),
453        }
454    }
455
456    /// Exact, unless a count the uniform path read is an estimate.
457    ///
458    /// The quality sample holds every row here, but two counts come from
459    /// estimators rather than the sample: the row tracker's duplicate rows
460    /// and the key column's distinct values. Either becomes an estimate past
461    /// its exact limit or under memory pressure, which a low
462    /// `duplicate_rows_exact_limit` reaches on a small source (#1292).
463    /// Declaring the assessment exact then let the gate read an estimated
464    /// duplicate count as a witnessed failure; the estimated component is
465    /// listed as sampled instead, as the streaming path lists it.
466    fn uniform_confidence(
467        &self,
468        metrics: &dataprof_metrics::QualityMetrics,
469        data: &HashMap<String, Vec<String>>,
470    ) -> MetricConfidence {
471        let mut estimated = Vec::new();
472        if let Some(uniqueness) = metrics.uniqueness.as_ref() {
473            if uniqueness.rows_checked > 0 && uniqueness.duplicate_rows_approximate {
474                estimated.push("duplicate_rows".to_string());
475            }
476            let key_estimated = uniqueness
477                .key_column
478                .as_deref()
479                .filter(|_| uniqueness.key_measured())
480                .and_then(|key| self.columns.iter().find(|profile| profile.name == key))
481                .is_some_and(|profile| profile.unique_count_is_approximate == Some(true));
482            if key_estimated {
483                estimated.push("key_uniqueness".to_string());
484            }
485        }
486        if estimated.is_empty() {
487            return MetricConfidence::Exact;
488        }
489        let exact = QualityAssessment::new(metrics.clone(), MetricConfidence::Exact)
490            .exact_dimensions()
491            .unwrap_or_default()
492            .into_iter()
493            .filter(|component| !estimated.contains(component))
494            .collect();
495        MetricConfidence::Mixed {
496            exact_dimensions: exact,
497            sampled_dimensions: estimated,
498            sample_size: data.values().map(Vec::len).max().unwrap_or(0),
499        }
500    }
501
502    fn mixed_confidence(&self, result: &BifurcatedResult) -> MetricConfidence {
503        MetricConfidence::Mixed {
504            exact_dimensions: result.exact_dimensions.clone(),
505            sampled_dimensions: result.sampled_dimensions.clone(),
506            sample_size: result.sample_size,
507        }
508    }
509}
510
511#[cfg(test)]
512mod tests {
513    use super::*;
514    use dataprof_core::{FileFormat, MetricPack, TruncationReason};
515
516    fn test_source() -> DataSource {
517        DataSource::File {
518            path: "test.csv".to_string(),
519            format: FileFormat::Csv,
520            size_bytes: 1024,
521            modified_at: None,
522            parquet_metadata: None,
523            csv_metadata: None,
524        }
525    }
526
527    #[test]
528    fn test_basic_report_assembly() {
529        let report =
530            ReportAssembler::new(test_source(), ExecutionMetadata::new(100, 3, 50)).build();
531
532        assert_eq!(report.execution.rows_processed, 100);
533        assert!(report.quality.is_none());
534        assert!(report.column_profiles.is_empty());
535    }
536
537    #[test]
538    fn test_skip_quality() {
539        let mut data = HashMap::new();
540        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
541
542        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
543            .with_quality_data(data)
544            .skip_quality()
545            .build();
546
547        assert!(report.quality.is_none());
548    }
549
550    /// The defect: a quality computation that was requested and failed used to
551    /// produce a report byte-identical to one that never asked for quality.
552    #[test]
553    fn failed_quality_computation_is_not_a_skip() {
554        let mut data = HashMap::new();
555        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
556
557        let failed = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
558            .with_quality_data(data.clone())
559            .force_quality_failure("uniqueness accumulator disagreed with the row count")
560            .build();
561        let skipped = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
562            .with_quality_data(data)
563            .skip_quality()
564            .build();
565
566        assert!(failed.quality.is_none());
567        assert!(skipped.quality.is_none());
568        assert_eq!(
569            failed.quality_status,
570            QualityAnalysisStatus::Failed {
571                error: "Metrics calculation failed: uniqueness accumulator disagreed with the \
572                        row count"
573                    .to_string(),
574            }
575        );
576        assert_eq!(skipped.quality_status, QualityAnalysisStatus::NotRequested);
577        assert_ne!(failed.quality_status, skipped.quality_status);
578    }
579
580    #[test]
581    fn computed_quality_reports_computed() {
582        let mut data = HashMap::new();
583        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
584
585        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
586            .with_quality_data(data)
587            .build();
588
589        assert!(report.quality.is_some());
590        assert_eq!(report.quality_status, QualityAnalysisStatus::Computed);
591    }
592
593    #[test]
594    fn absent_quality_data_reports_no_data() {
595        let explicit = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1))
596            .skip_quality_no_data()
597            .build();
598        let implicit = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1)).build();
599
600        assert_eq!(explicit.quality_status, QualityAnalysisStatus::NoData);
601        assert_eq!(implicit.quality_status, QualityAnalysisStatus::NoData);
602    }
603
604    #[test]
605    fn empty_quality_data_is_analyzed() {
606        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1))
607            .with_quality_data(HashMap::new())
608            .build();
609
610        assert_eq!(report.quality_status, QualityAnalysisStatus::Computed);
611        assert!(report.quality_score().is_none());
612        assert!(
613            report
614                .quality
615                .unwrap()
616                .metrics
617                .assessed_dimensions()
618                .is_empty()
619        );
620    }
621
622    /// Not asking is the more specific reason, and an unavailable sample does not
623    /// make it untrue. Builder order must not change the answer either way.
624    #[test]
625    fn deselected_quality_survives_an_unavailable_sample() {
626        let deselected =
627            AnalysisOptions::default().with_metric_packs(Some(vec![MetricPack::Schema]));
628        let options_first = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1))
629            .with_analysis_options(&deselected)
630            .skip_quality_no_data()
631            .build();
632        let skip_first = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1))
633            .skip_quality_no_data()
634            .with_analysis_options(&deselected)
635            .build();
636
637        assert_eq!(
638            options_first.quality_status,
639            QualityAnalysisStatus::NotRequested
640        );
641        assert_eq!(
642            skip_first.quality_status,
643            QualityAnalysisStatus::NotRequested
644        );
645    }
646
647    /// Deselection is the only reason that outranks an unavailable sample. A
648    /// projection withholds dimensions that could have been measured, which
649    /// says nothing once no sample is available at all.
650    #[test]
651    fn an_unavailable_sample_outranks_projection_withholding() {
652        let projected = AnalysisOptions::default()
653            .with_quality_dimensions(Some(vec![
654                QualityDimension::Completeness,
655                QualityDimension::Uniqueness,
656            ]))
657            .with_columns(Some(vec!["col".to_string()]));
658
659        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(0, 0, 1))
660            .with_analysis_options(&projected)
661            .skip_quality_no_data()
662            .build();
663
664        assert_eq!(report.quality_status, QualityAnalysisStatus::NoData);
665    }
666
667    /// Completeness and uniqueness measure whole rows; the projection path
668    /// withholds them rather than publishing projected numbers under full-row
669    /// names. A consumer must not read that as "you did not ask".
670    #[test]
671    fn projection_withholding_every_dimension_is_not_a_skip() {
672        let mut data = HashMap::new();
673        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
674        let options = AnalysisOptions::default()
675            .with_quality_dimensions(Some(vec![
676                QualityDimension::Completeness,
677                QualityDimension::Uniqueness,
678            ]))
679            .with_columns(Some(vec!["col".to_string()]));
680
681        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
682            .with_quality_data(data)
683            .with_analysis_options(&options)
684            .build();
685
686        assert!(report.quality.is_none());
687        assert_eq!(
688            report.quality_status,
689            QualityAnalysisStatus::WithheldByProjection
690        );
691    }
692
693    #[test]
694    fn test_batch_produces_exact_confidence() {
695        let mut data = HashMap::new();
696        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
697
698        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
699            .with_quality_data(data)
700            .build();
701
702        assert!(report.quality.is_some());
703        let quality = report.quality.unwrap();
704        assert!(matches!(quality.confidence, MetricConfidence::Exact));
705    }
706
707    #[test]
708    fn test_streaming_produces_mixed_confidence() {
709        let mut data = HashMap::new();
710        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
711
712        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(1000, 1, 50))
713            .with_quality_data(data)
714            .build();
715
716        assert!(report.quality.is_some());
717        let quality = report.quality.unwrap();
718        match &quality.confidence {
719            MetricConfidence::Mixed {
720                exact_dimensions,
721                sampled_dimensions,
722                sample_size,
723            } => {
724                assert!(exact_dimensions.contains(&"completeness".to_string()));
725                // No key column exists in this fixture, so key_uniqueness
726                // carries no signal and must not be claimed as exact.
727                assert!(!exact_dimensions.contains(&"key_uniqueness".to_string()));
728                assert!(sampled_dimensions.contains(&"consistency".to_string()));
729                assert!(sampled_dimensions.contains(&"accuracy".to_string()));
730                assert!(sampled_dimensions.contains(&"timeliness".to_string()));
731                assert!(sampled_dimensions.contains(&"duplicate_rows".to_string()));
732                assert_eq!(*sample_size, 2);
733            }
734            other => panic!("Expected Mixed confidence, got {:?}", other),
735        }
736    }
737
738    #[test]
739    fn test_streaming_exact_row_duplicates_have_exact_provenance() {
740        let data = HashMap::from([("col".to_string(), vec!["a".to_string(), "b".to_string()])]);
741
742        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(1000, 1, 50))
743            .with_quality_data(data)
744            .with_row_duplicates(Some(RowDuplicateSummary {
745                duplicate_rows: 25,
746                rows_checked: 1000,
747                approximate: false,
748                exact_limit: dataprof_metrics::EXACT_CARDINALITY_THRESHOLD,
749                max_duplicate_rows: 25,
750            }))
751            .build();
752
753        let quality = report.quality.expect("quality assessment");
754        let uniqueness = quality.metrics.uniqueness.expect("uniqueness metrics");
755        assert_eq!(uniqueness.duplicate_rows, 25);
756        assert_eq!(uniqueness.rows_checked, 1000);
757        assert!(!uniqueness.duplicate_rows_approximate);
758        match quality.confidence {
759            MetricConfidence::Mixed {
760                exact_dimensions,
761                sampled_dimensions,
762                ..
763            } => {
764                assert!(exact_dimensions.contains(&"duplicate_rows".to_string()));
765                assert!(!sampled_dimensions.contains(&"duplicate_rows".to_string()));
766            }
767            other => panic!("Expected Mixed confidence, got {other:?}"),
768        }
769    }
770
771    #[test]
772    fn test_streaming_approximate_row_duplicates_have_sampled_provenance() {
773        let data = HashMap::from([("col".to_string(), vec!["a".to_string(), "b".to_string()])]);
774
775        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(20_000, 1, 50))
776            .with_quality_data(data)
777            .with_row_duplicates(Some(RowDuplicateSummary {
778                duplicate_rows: 500,
779                rows_checked: 20_000,
780                approximate: true,
781                exact_limit: dataprof_metrics::EXACT_CARDINALITY_THRESHOLD,
782                max_duplicate_rows: 500,
783            }))
784            .build();
785
786        let quality = report.quality.expect("quality assessment");
787        let uniqueness = quality.metrics.uniqueness.expect("uniqueness metrics");
788        assert!(uniqueness.duplicate_rows_approximate);
789        match quality.confidence {
790            MetricConfidence::Mixed {
791                exact_dimensions,
792                sampled_dimensions,
793                ..
794            } => {
795                assert!(!exact_dimensions.contains(&"duplicate_rows".to_string()));
796                assert!(sampled_dimensions.contains(&"duplicate_rows".to_string()));
797            }
798            other => panic!("Expected Mixed confidence, got {other:?}"),
799        }
800    }
801
802    #[test]
803    fn test_sampling_applied_triggers_bifurcation() {
804        let mut data = HashMap::new();
805        data.insert("col".to_string(), vec!["a".to_string(), "b".to_string()]);
806
807        let execution = ExecutionMetadata::new(2, 1, 10).with_sampling(0.1);
808
809        let report = ReportAssembler::new(test_source(), execution)
810            .with_quality_data(data)
811            .build();
812
813        assert!(report.quality.is_some());
814        let quality = report.quality.unwrap();
815        assert!(matches!(quality.confidence, MetricConfidence::Mixed { .. }));
816    }
817
818    fn positive_binding() -> SemanticHintBinding {
819        SemanticHintBinding {
820            column: "col".to_string(),
821            kind: SemanticHintKind::Positive,
822            checked_values: 2,
823            matched_values: 0,
824            exact: true,
825        }
826    }
827
828    #[test]
829    fn exact_hint_binding_stays_exact_for_exhaustive_stream() {
830        let report = ReportAssembler::new(test_source(), ExecutionMetadata::new(2, 1, 10))
831            .with_semantic_hints(SemanticHints::new(vec!["col".to_string()], vec![]))
832            .with_exact_value_hint_bindings(vec![positive_binding()])
833            .build();
834
835        assert!(report.semantic_hint_bindings[0].exact);
836    }
837
838    #[test]
839    fn exact_hint_binding_is_downgraded_for_sampled_or_truncated_execution() {
840        let executions = [
841            ExecutionMetadata::new(2, 1, 10).with_sampling(0.5),
842            ExecutionMetadata::new(2, 1, 10).with_truncation(TruncationReason::MaxRows(2)),
843        ];
844
845        for execution in executions {
846            let report = ReportAssembler::new(test_source(), execution)
847                .with_semantic_hints(SemanticHints::new(vec!["col".to_string()], vec![]))
848                .with_exact_value_hint_bindings(vec![positive_binding()])
849                .build();
850
851            assert!(!report.semantic_hint_bindings[0].exact);
852            assert!(!report.semantic_hint_bindings[0].is_proven_inert());
853        }
854    }
855}