Skip to main content

dataprof_core/
errors.rs

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