Skip to main content

dataprof_core/
errors.rs

1use crate::binary_input::BinarySignature;
2use crate::shell_hint::Shell;
3use crate::source::FileFormat;
4use thiserror::Error;
5
6/// The re-encode remedy for a non-UTF-8 file at `path` that looks like
7/// `guess`, with a command for the shell of the platform this build runs on.
8fn reencode_advice(path: &str, guess: &str) -> String {
9    let note = Shell::HOST.placeholder_note(path);
10    format!(
11        "Re-encode the file as UTF-8 (e.g. `{}`) and profile the result.{note}",
12        Shell::HOST.reencode(path, guess)
13    )
14}
15
16/// The file formats this build can actually read, reflecting compiled features.
17///
18/// The list must never over-claim: Parquet is only advertised when the `parquet`
19/// feature is enabled, so an "unsupported format" error cannot point the user at
20/// a format the installed build cannot open.
21fn supported_formats_hint() -> &'static str {
22    #[cfg(feature = "parquet")]
23    {
24        "CSV, JSON, JSONL, Parquet"
25    }
26    #[cfg(not(feature = "parquet"))]
27    {
28        "CSV, JSON, JSONL"
29    }
30}
31
32/// Render a remedy as its own line, or nothing at all when there is none.
33///
34/// Streaming failures are the one family where "no advice" is a real answer: a
35/// panicked task has no remedy the caller can act on, and #550 removed the
36/// hardcoded chunk-size line that used to fill the gap. Formatting the
37/// suggestion unconditionally would end those messages in a bare newline.
38fn suggestion_line(suggestion: &str) -> String {
39    if suggestion.is_empty() {
40        String::new()
41    } else {
42        format!("\n{suggestion}")
43    }
44}
45
46/// Redact credentials from a string before it enters an error message.
47///
48/// Connection strings and driver errors can carry `scheme://user:password@host`.
49/// We collapse the userinfo to `***` so passwords (and usernames) never reach a
50/// log line or a surfaced diagnostic, while keeping the scheme/host for context.
51pub fn redact_credentials(input: &str) -> String {
52    // Match the `://[userinfo@]` segment of any URL-like token and drop userinfo.
53    let mut out = String::with_capacity(input.len());
54    let mut rest = input;
55    while let Some(scheme_idx) = rest.find("://") {
56        let after_scheme = scheme_idx + 3;
57        out.push_str(&rest[..after_scheme]);
58        let tail = &rest[after_scheme..];
59        // Userinfo, if present, ends at the first '@' before the next authority
60        // delimiter ('/', '?', '#', or whitespace).
61        let authority_end = tail
62            .find(['/', '?', '#', ' ', '\t', '\n'])
63            .unwrap_or(tail.len());
64        if let Some(at_rel) = tail[..authority_end].find('@') {
65            out.push_str("***");
66            rest = &tail[at_rel..]; // keep '@host...'
67        } else {
68            rest = tail;
69        }
70    }
71    out.push_str(rest);
72    out
73}
74
75/// Boxed originating error retained by the variants that can carry a cause.
76///
77/// `Box` rather than `Arc` is deliberate. `thiserror` renders a boxed source
78/// through `&**b`, so [`std::error::Error::source`] hands back the *concrete*
79/// error and `downcast_ref::<std::io::Error>()` succeeds. Behind an `Arc` the
80/// chain instead yields the `Arc`: the message still reads correctly while
81/// every downcast returns `None`, which is the exact capability this type
82/// exists to provide.
83pub type ErrorSource = Box<dyn std::error::Error + Send + Sync + 'static>;
84
85/// Enhanced error types with more descriptive messages for DataProfiler
86///
87/// Not `Clone`: a retained [`ErrorSource`] is a boxed trait object, and the
88/// originating errors (`std::io::Error`, `csv::Error`, ...) are not cloneable
89/// themselves.
90#[derive(Error, Debug)]
91pub enum DataProfilerError {
92    #[error("CSV parsing failed: {message}\nSuggestion: {suggestion}")]
93    #[non_exhaustive]
94    CsvParsingError {
95        message: String,
96        suggestion: String,
97        #[source]
98        source: Option<ErrorSource>,
99    },
100
101    #[error(
102        "File not found: {path}\nPlease check that the file exists and you have permission to read it"
103    )]
104    FileNotFound { path: String },
105
106    #[error(
107        "Unsupported file format: {format}\nSupported formats: {}",
108        supported_formats_hint()
109    )]
110    UnsupportedFormat { format: String },
111
112    #[error("Invalid configuration: {message}\n{suggestion}")]
113    #[non_exhaustive]
114    InvalidConfiguration {
115        message: String,
116        suggestion: String,
117        #[source]
118        source: Option<ErrorSource>,
119    },
120
121    #[error("Invalid semantic hint: {message}\n{suggestion}")]
122    InvalidSemanticHint { message: String, suggestion: String },
123
124    #[error("Streaming processing failed: {message}{}", suggestion_line(.suggestion))]
125    #[non_exhaustive]
126    StreamingError {
127        message: String,
128        suggestion: String,
129        #[source]
130        source: Option<ErrorSource>,
131    },
132
133    #[error("I/O error: {message}\nCheck file permissions and disk space")]
134    #[non_exhaustive]
135    IoError {
136        message: String,
137        #[source]
138        source: Option<ErrorSource>,
139    },
140
141    #[error("Non-UTF-8 input in {path}: {detail}\n{}", reencode_advice(.path, .guess))]
142    EncodingError {
143        path: String,
144        detail: String,
145        guess: String,
146    },
147
148    /// A file whose signature bytes name a binary format (gzip, zstd, zip,
149    /// Parquet, Arrow IPC, Feather V1) was about to reach a text reader
150    /// (#893). Built with [`DataProfilerError::binary_input`].
151    #[error("Binary input in {path}: the file is {detected}, not text\n{suggestion}")]
152    #[non_exhaustive]
153    BinaryInput {
154        path: String,
155        /// What the signature says the file is, e.g. `gzip-compressed`.
156        detected: String,
157        suggestion: String,
158    },
159
160    /// A remote object changed between the ranged reads of one profile, so
161    /// the bytes read do not all come from one version of it (#865). Built
162    /// with [`DataProfilerError::source_changed`].
163    #[error("Source changed during the read: {path}: {detail}\n{suggestion}")]
164    #[non_exhaustive]
165    SourceChanged {
166        path: String,
167        /// What showed the change, e.g. the server answering 412 to `If-Match`.
168        detail: String,
169        suggestion: String,
170    },
171
172    #[error("JSON parsing failed: {message}\nVerify JSON format and encoding")]
173    #[non_exhaustive]
174    JsonParsingError {
175        message: String,
176        #[source]
177        source: Option<ErrorSource>,
178    },
179
180    #[error("Parquet processing failed: {message}")]
181    #[non_exhaustive]
182    ParquetError {
183        message: String,
184        #[source]
185        source: Option<ErrorSource>,
186    },
187
188    #[error("Arrow processing failed: {message}")]
189    #[non_exhaustive]
190    ArrowError {
191        message: String,
192        #[source]
193        source: Option<ErrorSource>,
194    },
195
196    #[error("Unsupported data source: {message}")]
197    UnsupportedDataSource { message: String },
198
199    #[error("All engines failed: {message}")]
200    AllEnginesFailed { message: String },
201
202    #[error("Metrics calculation failed: {message}")]
203    MetricsCalculationError { message: String },
204
205    #[error(
206        "Duplicate column name{plural}: {names}\nSource: {source_label}. Column names must be unique after normalization; rename or drop the duplicate column(s) before profiling."
207    )]
208    DuplicateColumnName {
209        names: String,
210        plural: String,
211        source_label: String,
212    },
213
214    #[error("Configuration validation failed: {message}")]
215    ConfigValidationError { message: String },
216
217    #[error("Database connection failed: {message}\n{suggestion}")]
218    DatabaseConnectionError { message: String, suggestion: String },
219
220    #[error("Database query failed: {message}")]
221    DatabaseQueryError { message: String },
222
223    #[error("Database configuration error: {message}")]
224    DatabaseConfigError { message: String },
225
226    #[error("Database feature not enabled: {message}\nRecompile with the appropriate feature flag")]
227    DatabaseFeatureDisabled { message: String },
228
229    #[error("SQL validation failed: {message}")]
230    SqlValidationError { message: String },
231
232    #[error("Database SSL/TLS error: {message}")]
233    DatabaseSslError { message: String },
234}
235
236impl DataProfilerError {
237    /// Create a database connection error.
238    ///
239    /// The message is scrubbed of URL credentials before storage so a driver
240    /// error that echoes the connection string cannot leak the password.
241    pub fn database_connection(message: &str) -> Self {
242        let message = redact_credentials(message);
243        let m = message.to_lowercase();
244        let suggestion = if m.contains("refused") {
245            "Check that the database server is running and accepting connections."
246        } else if m.contains("timeout") {
247            "Increase the connection timeout or check network connectivity."
248        } else if m.contains("authentication") || m.contains("password") {
249            "Verify your credentials or use environment variables for authentication."
250        } else {
251            "Verify the connection string format and database server availability."
252        };
253        DataProfilerError::DatabaseConnectionError {
254            message,
255            suggestion: suggestion.to_string(),
256        }
257    }
258
259    /// Create a database query error.
260    ///
261    /// Redacts URL credentials that a driver error might surface; the raw SQL
262    /// text and bound parameter values are never embedded by callers.
263    pub fn database_query(message: &str) -> Self {
264        DataProfilerError::DatabaseQueryError {
265            message: redact_credentials(message),
266        }
267    }
268
269    /// Create a database config error
270    pub fn database_config(message: &str) -> Self {
271        DataProfilerError::DatabaseConfigError {
272            message: message.to_string(),
273        }
274    }
275
276    /// Create a feature-not-enabled error
277    pub fn database_feature_disabled(db_name: &str, feature: &str) -> Self {
278        DataProfilerError::DatabaseFeatureDisabled {
279            message: format!(
280                "{} support not compiled. Enable '{}' feature.",
281                db_name, feature
282            ),
283        }
284    }
285
286    /// Create a SQL validation error
287    pub fn sql_validation(message: &str) -> Self {
288        DataProfilerError::SqlValidationError {
289            message: message.to_string(),
290        }
291    }
292
293    /// Create a database SSL error
294    pub fn database_ssl(message: &str) -> Self {
295        DataProfilerError::DatabaseSslError {
296            message: message.to_string(),
297        }
298    }
299    /// Create a duplicate-column-name error from the already-collected list of
300    /// repeated names and a short transport label.
301    ///
302    /// Only the offending names and the source are embedded — never row values —
303    /// so the diagnostic cannot leak cell data.
304    pub fn duplicate_column_name(duplicates: &[String], source: &str) -> Self {
305        let plural = if duplicates.len() == 1 { "" } else { "s" };
306        let names = duplicates
307            .iter()
308            .map(|n| format!("'{}'", n))
309            .collect::<Vec<_>>()
310            .join(", ");
311        DataProfilerError::DuplicateColumnName {
312            names,
313            plural: plural.to_string(),
314            source_label: source.to_string(),
315        }
316    }
317
318    /// Create a CSV parsing error with helpful suggestions.
319    ///
320    /// `file_path` is `None` at boundaries that do not know the source (e.g. the
321    /// `From<csv::Error>` conversion); pass `Some(path)` whenever it is known so
322    /// the suggestion can name the offending file instead of a placeholder.
323    pub fn csv_parsing(original_error: &str, file_path: Option<&str>) -> Self {
324        let suggestion = if original_error.contains("field") && original_error.contains("record") {
325            let file_clause = match file_path {
326                Some(path) => format!("The CSV file '{}' has", path),
327                None => "This CSV file has".to_string(),
328            };
329            format!(
330                "{} inconsistent column counts. This often happens with:\n  • Text fields containing commas without proper quoting\n  • Mixed line endings (Windows/Unix)\n  • Embedded newlines in data\n\n  dataprof will attempt to parse it with flexible mode automatically.",
331                file_clause
332            )
333        } else if original_error.contains("UTF-8") {
334            "The file contains non-UTF-8 characters. Try converting it to UTF-8 encoding."
335                .to_string()
336        } else if original_error.contains("permission") {
337            "Check file permissions - you may not have read access to this file.".to_string()
338        } else {
339            "Try using a different CSV delimiter or check for data formatting issues.".to_string()
340        };
341
342        DataProfilerError::CsvParsingError {
343            message: original_error.to_string(),
344            suggestion,
345            source: None,
346        }
347    }
348
349    /// Create a CSV parsing error that retains `original` as its source.
350    ///
351    /// The suggestion is derived from the same message text as
352    /// [`DataProfilerError::csv_parsing`], so the two forms render identically;
353    /// only the cause chain differs.
354    pub fn csv_parsing_from<E>(original: E, file_path: Option<&str>) -> Self
355    where
356        E: std::error::Error + Send + Sync + 'static,
357    {
358        let mut err = Self::csv_parsing(&original.to_string(), file_path);
359        if let DataProfilerError::CsvParsingError { source, .. } = &mut err {
360            *source = Some(Box::new(original));
361        }
362        err
363    }
364
365    /// Create a file not found error with path context
366    pub fn file_not_found<P: AsRef<str>>(path: P) -> Self {
367        DataProfilerError::FileNotFound {
368            path: path.as_ref().to_string(),
369        }
370    }
371
372    /// A file at `path` whose bytes carry `signature`, refused before a text
373    /// reader parses it.
374    pub fn binary_input(path: &std::path::Path, signature: BinarySignature) -> Self {
375        Self::binary_input_with_format(path, signature, None)
376    }
377
378    /// [`binary_input`](Self::binary_input), naming `explicit_format` when the
379    /// caller selected a format. The Parquet hint uses it to say that a
380    /// `.parquet` path was overridden (#1356).
381    pub(crate) fn binary_input_with_format(
382        path: &std::path::Path,
383        signature: BinarySignature,
384        explicit_format: Option<&FileFormat>,
385    ) -> Self {
386        let path = path.display().to_string();
387        DataProfilerError::BinaryInput {
388            detected: signature.description().to_string(),
389            suggestion: signature.suggestion_for(&path, explicit_format),
390            path,
391        }
392    }
393
394    /// The object at `path` changed while it was being read; `detail` says
395    /// how that showed.
396    pub fn source_changed(path: &str, detail: impl Into<String>) -> Self {
397        DataProfilerError::SourceChanged {
398            path: path.to_string(),
399            detail: detail.into(),
400            suggestion: "Profile it again once writes to it have finished, or profile a copy that is not being rewritten.".to_string(),
401        }
402    }
403
404    /// Create unsupported format error with format detection
405    pub fn unsupported_format(extension: &str) -> Self {
406        DataProfilerError::UnsupportedFormat {
407            format: extension.to_string(),
408        }
409    }
410
411    /// Create configuration error with specific suggestion
412    pub fn invalid_config(message: &str, suggestion: &str) -> Self {
413        DataProfilerError::InvalidConfiguration {
414            message: message.to_string(),
415            suggestion: suggestion.to_string(),
416            source: None,
417        }
418    }
419
420    /// Create a configuration error that retains `original` as its source.
421    ///
422    /// Used by the TOML and glob conversions, where the underlying parser
423    /// reports a position worth reaching programmatically.
424    pub fn invalid_config_with_source<E>(
425        message: impl Into<String>,
426        suggestion: impl Into<String>,
427        original: E,
428    ) -> Self
429    where
430        E: std::error::Error + Send + Sync + 'static,
431    {
432        DataProfilerError::InvalidConfiguration {
433            message: message.into(),
434            suggestion: suggestion.into(),
435            source: Some(Box::new(original)),
436        }
437    }
438
439    /// Create streaming error with context
440    pub fn streaming_error(message: &str) -> Self {
441        Self::streaming_with_suggestion(message, "")
442    }
443
444    /// Create a streaming error with an actionable suggestion and no source.
445    ///
446    /// An empty suggestion means there is no remedy to offer the caller.
447    pub fn streaming_with_suggestion(
448        message: impl Into<String>,
449        suggestion: impl Into<String>,
450    ) -> Self {
451        DataProfilerError::StreamingError {
452            message: message.into(),
453            suggestion: suggestion.into(),
454            source: None,
455        }
456    }
457
458    /// Create a streaming error that retains `original` without changing its
459    /// contextual message, suggestion, or streaming category.
460    pub fn streaming_with_source<E>(
461        message: impl Into<String>,
462        suggestion: impl Into<String>,
463        original: E,
464    ) -> Self
465    where
466        E: std::error::Error + Send + Sync + 'static,
467    {
468        DataProfilerError::StreamingError {
469            message: message.into(),
470            suggestion: suggestion.into(),
471            source: Some(Box::new(original)),
472        }
473    }
474
475    /// Create an I/O error that retains `original` as its source.
476    ///
477    /// Takes the error by value: `std::io::Error` is not cloneable, so a
478    /// borrowed one could only ever be stringified, which is what this issue
479    /// set out to stop. Use `map_err(DataProfilerError::io_error)` at call
480    /// sites.
481    pub fn io_error(original: std::io::Error) -> Self {
482        DataProfilerError::IoError {
483            message: original.to_string(),
484            source: Some(Box::new(original)),
485        }
486    }
487
488    /// Create an I/O error from a message, for callers with no originating
489    /// error to retain (a condition detected by dataprof itself rather than
490    /// reported by the OS).
491    pub fn io_message(message: &str) -> Self {
492        DataProfilerError::IoError {
493            message: message.to_string(),
494            source: None,
495        }
496    }
497
498    /// Create a JSON parsing error with no retained source.
499    pub fn json_parsing_error(original: &str) -> Self {
500        DataProfilerError::JsonParsingError {
501            message: original.to_string(),
502            source: None,
503        }
504    }
505
506    /// Create a JSON parsing error that retains `original` as its source.
507    pub fn json_parsing_from<E>(original: E) -> Self
508    where
509        E: std::error::Error + Send + Sync + 'static,
510    {
511        DataProfilerError::JsonParsingError {
512            message: original.to_string(),
513            source: Some(Box::new(original)),
514        }
515    }
516
517    /// Create a CSV parsing error with a caller-supplied message and
518    /// suggestion that still retains `original` as its source.
519    ///
520    /// For callers whose suggestion is specific to their own context and so
521    /// cannot come from [`DataProfilerError::csv_parsing`]'s message analysis.
522    pub fn csv_parsing_with_source<E>(
523        message: impl Into<String>,
524        suggestion: impl Into<String>,
525        original: E,
526    ) -> Self
527    where
528        E: std::error::Error + Send + Sync + 'static,
529    {
530        DataProfilerError::CsvParsingError {
531            message: message.into(),
532            suggestion: suggestion.into(),
533            source: Some(Box::new(original)),
534        }
535    }
536
537    /// Create a CSV parsing error for a structural problem the parser itself
538    /// accepted, so there is no underlying error to keep as its source.
539    pub fn csv_structure(message: impl Into<String>, suggestion: impl Into<String>) -> Self {
540        DataProfilerError::CsvParsingError {
541            message: message.into(),
542            suggestion: suggestion.into(),
543            source: None,
544        }
545    }
546
547    /// Create a JSON parsing error with a caller-supplied message that still
548    /// retains `original` as its source.
549    ///
550    /// Used where the message adds context the decoder does not have (a record
551    /// position, a physical line number) and the decoder error is still worth
552    /// keeping underneath it.
553    pub fn json_parsing_with_source<E>(message: impl Into<String>, original: E) -> Self
554    where
555        E: std::error::Error + Send + Sync + 'static,
556    {
557        DataProfilerError::JsonParsingError {
558            message: message.into(),
559            source: Some(Box::new(original)),
560        }
561    }
562
563    /// Create an Arrow error with a caller-supplied message that still retains
564    /// `original` as its source.
565    pub fn arrow_with_source<E>(message: impl Into<String>, original: E) -> Self
566    where
567        E: std::error::Error + Send + Sync + 'static,
568    {
569        DataProfilerError::ArrowError {
570            message: message.into(),
571            source: Some(Box::new(original)),
572        }
573    }
574
575    /// Create a Parquet error with a caller-supplied message that still retains
576    /// `original` as its source.
577    pub fn parquet_with_source<E>(message: impl Into<String>, original: E) -> Self
578    where
579        E: std::error::Error + Send + Sync + 'static,
580    {
581        DataProfilerError::ParquetError {
582            message: message.into(),
583            source: Some(Box::new(original)),
584        }
585    }
586
587    /// Create an I/O error with a caller-supplied message that still retains
588    /// `original` as its source.
589    pub fn io_with_source<E>(message: impl Into<String>, original: E) -> Self
590    where
591        E: std::error::Error + Send + Sync + 'static,
592    {
593        DataProfilerError::IoError {
594            message: message.into(),
595            source: Some(Box::new(original)),
596        }
597    }
598
599    /// Create an Arrow error with no retained source.
600    pub fn arrow_error(message: &str) -> Self {
601        DataProfilerError::ArrowError {
602            message: message.to_string(),
603            source: None,
604        }
605    }
606
607    /// Create an Arrow error that retains `original` as its source.
608    pub fn arrow_error_from<E>(original: E) -> Self
609    where
610        E: std::error::Error + Send + Sync + 'static,
611    {
612        DataProfilerError::ArrowError {
613            message: original.to_string(),
614            source: Some(Box::new(original)),
615        }
616    }
617
618    /// Create a Parquet error with no retained source.
619    pub fn parquet_error(message: &str) -> Self {
620        DataProfilerError::ParquetError {
621            message: message.to_string(),
622            source: None,
623        }
624    }
625
626    /// The actionable next step for this error, as structured context.
627    ///
628    /// Suggestions live in the variants and the `Display` string, but callers
629    /// that want to react programmatically (or render the hint separately from
630    /// the message) should read it here rather than parse the formatted output.
631    pub fn suggestion(&self) -> Option<String> {
632        match self {
633            DataProfilerError::CsvParsingError { suggestion, .. }
634            | DataProfilerError::InvalidConfiguration { suggestion, .. }
635            | DataProfilerError::InvalidSemanticHint { suggestion, .. }
636            | DataProfilerError::BinaryInput { suggestion, .. }
637            | DataProfilerError::SourceChanged { suggestion, .. }
638            | DataProfilerError::DatabaseConnectionError { suggestion, .. } => {
639                Some(suggestion.clone())
640            }
641            DataProfilerError::FileNotFound { .. } => {
642                Some("Check that the file exists and you have permission to read it.".to_string())
643            }
644            DataProfilerError::UnsupportedFormat { .. } => Some(format!(
645                "This build reads {}. Convert the input to one of these formats, or rebuild with the feature for the format you need.",
646                supported_formats_hint()
647            )),
648            DataProfilerError::EncodingError { path, guess, .. } => {
649                Some(reencode_advice(path, guess))
650            }
651            DataProfilerError::StreamingError { suggestion, .. } => {
652                if suggestion.is_empty() {
653                    None
654                } else {
655                    Some(suggestion.clone())
656                }
657            }
658            DataProfilerError::DatabaseFeatureDisabled { .. } => {
659                Some("Recompile with the appropriate database feature flag.".to_string())
660            }
661            _ => None,
662        }
663    }
664
665    /// Get error category for logging/metrics
666    pub fn category(&self) -> &'static str {
667        match self {
668            DataProfilerError::CsvParsingError { .. } => "csv_parsing",
669            DataProfilerError::FileNotFound { .. } => "file_not_found",
670            DataProfilerError::UnsupportedFormat { .. } => "unsupported_format",
671            DataProfilerError::EncodingError { .. } => "encoding",
672            DataProfilerError::BinaryInput { .. } => "binary_input",
673            DataProfilerError::SourceChanged { .. } => "source_changed",
674            DataProfilerError::InvalidConfiguration { .. } => "configuration",
675            DataProfilerError::InvalidSemanticHint { .. } => "semantic_hint",
676            DataProfilerError::StreamingError { .. } => "streaming",
677            DataProfilerError::IoError { .. } => "io",
678            DataProfilerError::JsonParsingError { .. } => "json_parsing",
679            DataProfilerError::ParquetError { .. } => "parquet",
680            DataProfilerError::ArrowError { .. } => "arrow",
681            DataProfilerError::UnsupportedDataSource { .. } => "unsupported_data_source",
682            DataProfilerError::AllEnginesFailed { .. } => "all_engines_failed",
683            DataProfilerError::MetricsCalculationError { .. } => "metrics_calculation",
684            DataProfilerError::DuplicateColumnName { .. } => "duplicate_column_name",
685            DataProfilerError::ConfigValidationError { .. } => "config_validation",
686            DataProfilerError::DatabaseConnectionError { .. } => "database_connection",
687            DataProfilerError::DatabaseQueryError { .. } => "database_query",
688            DataProfilerError::DatabaseConfigError { .. } => "database_config",
689            DataProfilerError::DatabaseFeatureDisabled { .. } => "database_feature_disabled",
690            DataProfilerError::SqlValidationError { .. } => "sql_validation",
691            DataProfilerError::DatabaseSslError { .. } => "database_ssl",
692        }
693    }
694}
695
696/// Convert from anyhow::Error to DataProfilerError with context.
697///
698/// These conversions run where the source path/operation is *not* known, so they
699/// never fabricate one: a path is only ever attached by the call sites that hold
700/// it (see [`DataProfilerError::csv_parsing`], `map_io_error`, and the facade's
701/// existence check). Preserving the original message keeps the source diagnostic.
702impl From<anyhow::Error> for DataProfilerError {
703    fn from(err: anyhow::Error) -> Self {
704        let error_str = err.to_string();
705
706        // The anyhow error is retained as the source in every branch, so a
707        // caller can still reach the concrete error underneath it via
708        // `source()` even though categorisation here is message-based.
709        let source: Option<ErrorSource> = Some(err.into());
710
711        // Categorize by message only; do not invent a path we do not have.
712        if error_str.contains("CSV") {
713            DataProfilerError::CsvParsingError {
714                message: error_str,
715                suggestion: "Try using robust CSV parsing mode".to_string(),
716                source,
717            }
718        } else if error_str.contains("JSON") {
719            DataProfilerError::JsonParsingError {
720                message: error_str,
721                source,
722            }
723        } else {
724            // Generic I/O error — the original message carries the detail
725            // (including "file not found" wording) without a fabricated path.
726            DataProfilerError::IoError {
727                message: error_str,
728                source,
729            }
730        }
731    }
732}
733
734/// Convert from std::io::Error to DataProfilerError.
735///
736/// Path-less by design: callers that know the file use `map_io_error` to produce
737/// a [`DataProfilerError::FileNotFound`] with the real path. Here we keep the OS
738/// message (which already names the condition) rather than guessing a path.
739impl From<std::io::Error> for DataProfilerError {
740    fn from(err: std::io::Error) -> Self {
741        // The message is still rewritten for PermissionDenied, but the original
742        // error is retained either way: `err.source()` now yields the
743        // `std::io::Error`, so a caller can match on `kind()` instead of
744        // pattern-matching the human-readable text.
745        let message = match err.kind() {
746            std::io::ErrorKind::PermissionDenied => {
747                "Permission denied - check file access rights".to_string()
748            }
749            _ => err.to_string(),
750        };
751        DataProfilerError::IoError {
752            message,
753            source: Some(Box::new(err)),
754        }
755    }
756}
757
758/// Convert from csv::Error to DataProfilerError with enhanced context.
759///
760/// The source path is unknown at this boundary, so the suggestion is written
761/// without a filename rather than the misleading `'unknown'` placeholder.
762impl From<csv::Error> for DataProfilerError {
763    fn from(err: csv::Error) -> Self {
764        DataProfilerError::csv_parsing_from(err, None)
765    }
766}
767
768/// Convert from arrow::error::ArrowError to DataProfilerError
769#[cfg(feature = "arrow")]
770impl From<arrow::error::ArrowError> for DataProfilerError {
771    fn from(err: arrow::error::ArrowError) -> Self {
772        DataProfilerError::arrow_error_from(err)
773    }
774}
775
776/// Convert from serde_json::Error to DataProfilerError
777impl From<serde_json::Error> for DataProfilerError {
778    fn from(err: serde_json::Error) -> Self {
779        DataProfilerError::json_parsing_from(err)
780    }
781}
782
783#[cfg(test)]
784mod tests {
785    use super::*;
786
787    #[test]
788    fn test_error_categorization() {
789        let csv_error = DataProfilerError::csv_parsing("field count mismatch", Some("test.csv"));
790        assert_eq!(csv_error.category(), "csv_parsing");
791    }
792
793    #[test]
794    fn test_error_suggestions() {
795        let config_error = DataProfilerError::invalid_config(
796            "Invalid chunk size",
797            "Use a value between 1000 and 100000",
798        );
799
800        let error_string = config_error.to_string();
801        assert!(error_string.contains("Invalid chunk size"));
802        assert!(error_string.contains("Use a value between"));
803    }
804
805    #[test]
806    fn streaming_error_without_suggestion_prints_no_stale_advice() {
807        let err = DataProfilerError::streaming_error("Reader task panicked: boxed error");
808        let msg = err.to_string();
809        assert!(msg.contains("Reader task panicked"));
810        assert!(!msg.contains("chunk size"), "stale remedy leaked: {msg}");
811        assert!(err.suggestion().is_none());
812        assert!(std::error::Error::source(&err).is_none());
813        // No remedy means no line for one: an unconditional "\n{suggestion}"
814        // leaves the message ending in a bare newline, which surfaces in Python
815        // as a blank line under the error.
816        assert!(
817            !msg.ends_with('\n'),
818            "message ends in a bare newline: {msg:?}"
819        );
820        assert!(
821            !msg.contains('\n'),
822            "empty remedy still opened a line: {msg:?}"
823        );
824    }
825
826    #[test]
827    fn streaming_error_with_suggestion_prints_the_remedy_exactly_once() {
828        let err = DataProfilerError::streaming_with_suggestion(
829            "Parquet schema inference requires random access",
830            "Use infer_schema() with a file path instead",
831        );
832        let msg = err.to_string();
833        assert!(msg.contains("random access"), "{msg}");
834        assert_eq!(
835            msg.matches("Use infer_schema() with a file path instead")
836                .count(),
837            1,
838            "remedy must appear exactly once: {msg}"
839        );
840        assert!(!msg.contains("chunk size"), "stale remedy leaked: {msg}");
841        // A remedy still gets its own line, and only one.
842        assert_eq!(
843            msg.matches('\n').count(),
844            1,
845            "remedy is not on its own line: {msg:?}"
846        );
847        assert!(
848            !msg.ends_with('\n'),
849            "trailing newline after the remedy: {msg:?}"
850        );
851        assert_eq!(
852            err.suggestion(),
853            Some("Use infer_schema() with a file path instead".to_string())
854        );
855    }
856
857    #[test]
858    fn encoding_error_names_file_and_gives_reencode_advice() {
859        let err = DataProfilerError::EncodingError {
860            path: "sales.csv".to_string(),
861            detail: "first invalid UTF-8 byte at offset 12".to_string(),
862            guess: "windows-1252".to_string(),
863        };
864        assert_eq!(err.category(), "encoding");
865        let msg = err.to_string();
866        assert!(msg.contains("sales.csv"), "names the file: {msg}");
867        assert!(msg.contains("offset 12"), "reports the offset: {msg}");
868        assert!(
869            msg.to_lowercase().contains("utf-8"),
870            "mentions UTF-8: {msg}"
871        );
872        let command = Shell::HOST.reencode("sales.csv", "windows-1252");
873        assert!(msg.contains(&command), "gives a re-encode command: {msg}");
874        // The old, misleading advice must not appear.
875        assert!(
876            !msg.to_lowercase().contains("check file permissions"),
877            "{msg}"
878        );
879        assert!(!msg.contains("All engines failed"), "{msg}");
880        assert!(err.suggestion().unwrap().contains("windows-1252"));
881    }
882
883    #[test]
884    fn io_conversion_never_fabricates_a_path() {
885        // A NotFound io::Error carries no path here; the conversion must not
886        // invent one (the `'unknown'` placeholder the contract work removed).
887        let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "no such file");
888        let err = DataProfilerError::from(io_err);
889        assert_eq!(err.category(), "io");
890        assert!(!err.to_string().contains("unknown"));
891    }
892
893    #[test]
894    fn csv_conversion_without_path_omits_the_filename() {
895        // The `From<csv::Error>` boundary does not know the source file, so the
896        // suggestion must not print `'unknown'` as if it were the filename.
897        let err = DataProfilerError::csv_parsing("record has 5 fields but 3 expected", None);
898        let msg = err.to_string();
899        assert!(!msg.contains("unknown"));
900        assert!(msg.contains("This CSV file has inconsistent column counts"));
901    }
902
903    #[test]
904    fn csv_conversion_with_path_names_the_file() {
905        let err =
906            DataProfilerError::csv_parsing("record has 5 fields but 3 expected", Some("data.csv"));
907        assert!(err.to_string().contains("The CSV file 'data.csv' has"));
908    }
909
910    #[test]
911    fn file_not_found_keeps_the_real_path() {
912        let err = DataProfilerError::file_not_found("/data/sales.csv");
913        assert_eq!(err.category(), "file_not_found");
914        assert!(err.to_string().contains("/data/sales.csv"));
915    }
916
917    #[test]
918    fn unsupported_format_advertises_only_buildable_formats() {
919        let err = DataProfilerError::unsupported_format("xlsx");
920        let msg = err.to_string();
921        assert!(msg.contains("CSV, JSON, JSONL"));
922        // Parquet is only claimed when the build can actually read it.
923        #[cfg(feature = "parquet")]
924        assert!(msg.contains("Parquet"));
925        #[cfg(not(feature = "parquet"))]
926        assert!(!msg.contains("Parquet"));
927    }
928
929    #[test]
930    fn suggestion_is_available_as_structured_context() {
931        let err = DataProfilerError::unsupported_format("xlsx");
932        assert!(err.suggestion().is_some());
933        let hint = DataProfilerError::streaming_error("reader task panicked");
934        assert!(hint.suggestion().is_none());
935    }
936
937    #[test]
938    fn redact_credentials_scrubs_userinfo() {
939        assert_eq!(
940            redact_credentials("postgresql://admin:s3cret@db.internal:5432/sales"),
941            "postgresql://***@db.internal:5432/sales"
942        );
943        // No userinfo → untouched.
944        assert_eq!(
945            redact_credentials("mysql://db.internal:3306/app"),
946            "mysql://db.internal:3306/app"
947        );
948        // Embedded in a driver error message.
949        let msg = "Failed to connect: error with url mysql://root:hunter2@localhost/db";
950        let redacted = redact_credentials(msg);
951        assert!(!redacted.contains("hunter2"));
952        assert!(redacted.contains("mysql://***@localhost/db"));
953    }
954
955    #[test]
956    fn database_connection_error_redacts_password() {
957        let err = DataProfilerError::database_connection(
958            "pool timed out connecting to postgres://user:topsecret@host/db",
959        );
960        assert!(!err.to_string().contains("topsecret"));
961    }
962
963    // --- source chain (#447) ---------------------------------------------
964    //
965    // The point of retaining a source is that a caller can recover the
966    // *concrete* originating error, not just a string that reads like it. Each
967    // test below therefore downcasts, rather than comparing rendered text.
968
969    use std::error::Error as _;
970
971    #[test]
972    fn io_error_retains_the_os_error_and_its_kind() {
973        let original = std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied by acl");
974        let err = DataProfilerError::io_error(original);
975
976        let source = err.source().expect("io error must retain a source");
977        let io: &std::io::Error = source
978            .downcast_ref()
979            .expect("source must downcast to the original std::io::Error");
980        assert_eq!(io.kind(), std::io::ErrorKind::PermissionDenied);
981    }
982
983    #[test]
984    fn from_io_error_retains_the_kind_even_when_the_message_is_rewritten() {
985        // PermissionDenied is the one branch that replaces the OS text, so it is
986        // the case where a flattened source would lose the most.
987        let original = std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied by acl");
988        let err: DataProfilerError = original.into();
989
990        assert!(err.to_string().contains("Permission denied"));
991        let io: &std::io::Error = err
992            .source()
993            .and_then(|s| s.downcast_ref())
994            .expect("rewritten message must still retain the io::Error");
995        assert_eq!(io.kind(), std::io::ErrorKind::PermissionDenied);
996        assert!(io.to_string().contains("denied by acl"));
997    }
998
999    #[test]
1000    fn from_json_error_retains_line_and_column() {
1001        let original = serde_json::from_str::<serde_json::Value>("{oops}").unwrap_err();
1002        let (line, column) = (original.line(), original.column());
1003        let err: DataProfilerError = original.into();
1004
1005        let json: &serde_json::Error = err
1006            .source()
1007            .and_then(|s| s.downcast_ref())
1008            .expect("source must downcast to serde_json::Error");
1009        assert_eq!((json.line(), json.column()), (line, column));
1010    }
1011
1012    #[test]
1013    fn from_csv_error_retains_the_csv_error_kind() {
1014        let mut reader = csv::ReaderBuilder::new()
1015            .flexible(false)
1016            .from_reader("a,b\n1,2,3\n".as_bytes());
1017        let original = reader
1018            .records()
1019            .next()
1020            .expect("one record")
1021            .expect_err("ragged row must fail with flexible(false)");
1022        let err: DataProfilerError = original.into();
1023
1024        let csv: &csv::Error = err
1025            .source()
1026            .and_then(|s| s.downcast_ref())
1027            .expect("source must downcast to csv::Error");
1028        assert!(matches!(csv.kind(), csv::ErrorKind::UnequalLengths { .. }));
1029    }
1030
1031    // Gated exactly like the conversion it covers: without the feature there is
1032    // no `From<ArrowError>` impl to test.
1033    #[cfg(feature = "arrow")]
1034    #[test]
1035    fn from_arrow_error_retains_the_arrow_error() {
1036        let original = arrow::error::ArrowError::ComputeError("overflow in sum".to_string());
1037        let expected = original.to_string();
1038        let err: DataProfilerError = original.into();
1039
1040        assert!(matches!(err, DataProfilerError::ArrowError { .. }));
1041        let arrow_err: &arrow::error::ArrowError = err
1042            .source()
1043            .and_then(|s| s.downcast_ref())
1044            .expect("source must downcast to arrow::error::ArrowError");
1045        assert_eq!(arrow_err.to_string(), expected);
1046        assert!(matches!(
1047            arrow_err,
1048            arrow::error::ArrowError::ComputeError(_)
1049        ));
1050    }
1051
1052    // Parquet failures reach the user through `parquet_with_source`, which the
1053    // reader paths use; this covers that constructor's retention contract with
1054    // a stand-in error so the test needs no parquet dependency here.
1055    #[test]
1056    fn parquet_with_source_retains_the_reader_error() {
1057        let original = std::io::Error::new(std::io::ErrorKind::InvalidData, "Corrupt footer");
1058        let err =
1059            DataProfilerError::parquet_with_source("Failed to create Parquet reader", original);
1060
1061        assert!(err.to_string().contains("Failed to create Parquet reader"));
1062        let io: &std::io::Error = err
1063            .source()
1064            .and_then(|s| s.downcast_ref())
1065            .expect("parquet errors must retain the reader failure");
1066        assert_eq!(io.kind(), std::io::ErrorKind::InvalidData);
1067    }
1068
1069    #[test]
1070    fn errors_built_without_a_cause_report_no_source() {
1071        // "No source" must stay distinguishable from "source not retained":
1072        // these variants genuinely have no originating error underneath.
1073        assert!(
1074            DataProfilerError::io_message("disk budget exceeded")
1075                .source()
1076                .is_none()
1077        );
1078        assert!(
1079            DataProfilerError::json_parsing_error("not an object")
1080                .source()
1081                .is_none()
1082        );
1083        assert!(
1084            DataProfilerError::arrow_error("downcast failed")
1085                .source()
1086                .is_none()
1087        );
1088        assert!(
1089            DataProfilerError::file_not_found("/nope")
1090                .source()
1091                .is_none()
1092        );
1093    }
1094
1095    #[test]
1096    fn retaining_a_source_does_not_change_the_rendered_message() {
1097        // The #373 message contract is independent of the cause chain: the two
1098        // constructions must be indistinguishable in output.
1099        let original = std::io::Error::new(std::io::ErrorKind::NotFound, "missing");
1100        let text = original.to_string();
1101
1102        let with_source = DataProfilerError::io_error(original).to_string();
1103        let without_source = DataProfilerError::io_message(&text).to_string();
1104        assert_eq!(with_source, without_source);
1105    }
1106
1107    #[test]
1108    fn the_whole_chain_is_walkable_to_the_root() {
1109        let original = std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated");
1110        let err = DataProfilerError::io_with_source("reading chunk 4", original);
1111
1112        let mut depth = 0;
1113        let mut current: Option<&(dyn std::error::Error + 'static)> = Some(&err);
1114        while let Some(e) = current {
1115            current = e.source();
1116            depth += 1;
1117        }
1118        // Exactly two links: the DataProfilerError and the io::Error beneath it.
1119        // A wrapper type in between would make this 3 and break downcasting.
1120        assert_eq!(depth, 2);
1121    }
1122}