Skip to main content

openreadout_core/
reader.rs

1//! The traits every format crate implements, and the registry that dispatches on them.
2
3use std::io::Read;
4use std::path::Path;
5
6use crate::error::{Error, Result};
7use crate::model::{
8    AttachmentInfo, CheckReport, DetectConfidence, FileInfo, FormatDescriptor, LsEntry, Spectrum,
9    Table, Trace,
10};
11use crate::pixel::Plane;
12use crate::provenance::ProvenanceMap;
13use crate::source::Input;
14
15/// Result of sniffing a file's first bytes.
16#[derive(Debug, Clone)]
17pub struct Detection {
18    /// Format id of the reader that matched.
19    pub format_id: &'static str,
20    /// How sure the match is.
21    pub confidence: DetectConfidence,
22    /// Why the match is less than definite, if it is.
23    pub note: Option<String>,
24}
25
26/// Which representation `read_spectrum_view` returns when a scan stores more than one
27/// (Fourier-transform instruments typically keep a profile *and* the instrument's centroid list).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
29#[non_exhaustive]
30pub enum SpectrumView {
31    /// The scan's primary data: the profile when one was recorded, otherwise the centroids.
32    #[default]
33    Primary,
34    /// The centroid list stored by the instrument software, when the scan has one; otherwise
35    /// the same as `Primary`.
36    Centroid,
37}
38
39/// Which plane of an image to read. All zero-based.
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
41pub struct PlaneIndex {
42    /// Channel index.
43    pub c: u32,
44    /// Z index (focal plane).
45    pub z: u32,
46    /// Time index.
47    pub t: u32,
48}
49
50/// An open file. Implementations must keep `info` cheap: read headers, never pixels.
51pub trait Dataset: Send {
52    /// Header-only summary.
53    fn info(&self) -> Result<FileInfo>;
54    /// The vendor's metadata tree as JSON, names untouched.
55    fn vendor_metadata(&self) -> Result<serde_json::Value>;
56    /// Provenance of the normalized fields this reader fills.
57    fn provenance(&self) -> ProvenanceMap;
58    /// Structural listing for `info --view structure`.
59    fn entries(&self) -> Result<Vec<LsEntry>>;
60    /// Read one full-resolution plane. Mosaics are stitched; pyramids are ignored.
61    fn read_plane(&mut self, image: u32, index: PlaneIndex) -> Result<Plane>;
62    /// Integrity validation for `check`.
63    fn check(&mut self) -> Result<CheckReport>;
64    /// Integrity validation that reads headers and structure only (`check --headers-only`, and
65    /// the `index` crawl): offsets, declared sizes and counts against the file length, missing
66    /// parts; no decompression, no decoding of samples and no checksums over the data. Readers
67    /// whose `check` decodes data override it; the default is `check`, which for most formats
68    /// already reads only headers and structure.
69    fn check_headers(&mut self) -> Result<CheckReport> {
70        self.check()
71    }
72    /// Other files on disk that belong to this dataset (multi-file OME-TIFF members, CZI file
73    /// parts, OIR continuation files, a SpikeGLX `.meta`/`.bin` pair, an imzML `.ibd`, VSI
74    /// `.ets` stacks, ...), excluding the path that was opened. Only files that exist are
75    /// listed. `index` records them as members of this dataset instead of separate records.
76    /// Directory datasets (a Bruker `.d`, a ChemStation `.D`) keep the default: the directory
77    /// itself is the dataset.
78    fn member_files(&self) -> Vec<std::path::PathBuf> {
79        Vec::new()
80    }
81    /// Evidence that the file is not finished: the structures its software writes last that
82    /// are absent and the planes already complete ([`crate::live::WriteState`]). `None` for
83    /// finished files and for formats that do not know their write order (the default).
84    /// [`crate::live::assess`] turns it into `acquisition: in_progress | interrupted`.
85    fn write_state(&self) -> Option<crate::live::WriteState> {
86        None
87    }
88    /// Rows `[first_row, first_row + max_rows)` of table `index`. Formats without tables keep the default.
89    fn read_table(&mut self, index: u32, first_row: u64, max_rows: u64) -> Result<Table> {
90        let _ = (index, first_row, max_rows);
91        Err(Error::unsupported(
92            "core",
93            "tabular data",
94            "This format exposes images, not tables.",
95        ))
96    }
97    /// Samples `[first_sample, first_sample + max_samples)` of sweep `sweep` of trace `index`.
98    fn read_trace(
99        &mut self,
100        index: u32,
101        sweep: u32,
102        first_sample: u64,
103        max_samples: u64,
104    ) -> Result<Trace> {
105        let _ = (index, sweep, first_sample, max_samples);
106        Err(Error::unsupported(
107            "core",
108            "sampled signals",
109            "This format does not expose traces.",
110        ))
111    }
112    /// Spectrum `spectrum` of run `index`. Formats without spectra keep the default.
113    fn read_spectrum(&mut self, index: u32, spectrum: u64) -> Result<Spectrum> {
114        let _ = (index, spectrum);
115        Err(Error::unsupported(
116            "core",
117            "mass spectra",
118            "This format exposes images, not spectra.",
119        ))
120    }
121    /// MS level of every spectrum of run `run`, in spectrum-index order, when the reader knows
122    /// them without decoding peaks (a scan index, per-scan events, header summaries). `None`
123    /// (the default) means unknown: [`spectrum_by_level`] then reads the spectra one by one.
124    fn spectrum_ms_levels(&mut self, run: u32) -> Result<Option<Vec<u32>>> {
125        let _ = run;
126        Ok(None)
127    }
128    /// Zero-based index of the spectrum with instrument scan number `scan_number` in run `run`.
129    /// `Ok(None)` means the reader keeps no scan-number map; callers then assume scan numbers
130    /// are contiguous from the first spectrum's (see [`spectrum_by_scan`]).
131    fn find_spectrum(&mut self, run: u32, scan_number: u64) -> Result<Option<u64>> {
132        let _ = (run, scan_number);
133        Ok(None)
134    }
135    /// Visit the headers of run `run`'s spectra from spectrum `first` on, in index order,
136    /// without decoding any peaks (scan number, MS level, RT, polarity, precursor, isolation,
137    /// activation, filter, the file's stored TIC/base peak: [`crate::scans::ScanHeader`]).
138    /// `visit` returns false to stop. `Ok(false)` (the default) means the reader has no
139    /// header-only path; [`crate::scans::visit_scans`] then decodes the spectra.
140    fn visit_scan_headers(
141        &mut self,
142        run: u32,
143        first: u64,
144        visit: &mut dyn FnMut(crate::scans::ScanHeader) -> bool,
145    ) -> Result<bool> {
146        let _ = (run, first, visit);
147        Ok(false)
148    }
149    /// Like `read_spectrum`, choosing between stored representations. Formats that store only one
150    /// keep the default, which ignores `view`.
151    fn read_spectrum_view(
152        &mut self,
153        index: u32,
154        spectrum: u64,
155        view: SpectrumView,
156    ) -> Result<Spectrum> {
157        let _ = view;
158        self.read_spectrum(index, spectrum)
159    }
160    /// Read one plane of pyramid level `level` (0 = full resolution, larger = more downsampled;
161    /// `ImageInfo::pyramid_levels` says how many exist). Formats without pyramids keep the
162    /// default, which serves level 0 and rejects the rest.
163    fn read_plane_level(&mut self, image: u32, index: PlaneIndex, level: u32) -> Result<Plane> {
164        if level == 0 {
165            return self.read_plane(image, index);
166        }
167        Err(Error::unsupported(
168            "core",
169            "pyramid level reads",
170            "This format does not expose downsampled pyramid levels; read level 0.",
171        ))
172    }
173    /// Read the rectangle `region` of one plane of pyramid level `level`, in that level's pixel
174    /// coordinates (see [`crate::region`]). A region outside the level is a usage error (exit
175    /// 2). Readers that store pixels in tiles, subblocks or chunks override it to decode only
176    /// the tiles the region touches, which also makes regions of planes too large to assemble
177    /// whole ([`crate::pixel::MAX_PLANE_BYTES`]) readable. The default reads the whole plane at
178    /// the level and crops it.
179    fn read_region(
180        &mut self,
181        image: u32,
182        index: PlaneIndex,
183        level: u32,
184        region: crate::region::Region,
185    ) -> Result<Plane> {
186        let plane = self.read_plane_level(image, index, level)?;
187        crate::region::crop(plane, region, &format!("image {image} level {level}"))
188    }
189    /// Files embedded in the container (thumbnails, label images, time stamps, ...).
190    fn attachments(&self) -> Result<Vec<AttachmentInfo>> {
191        Ok(Vec::new())
192    }
193    /// Raw bytes of attachment `index` (see `attachments`).
194    fn read_attachment(&mut self, index: u32) -> Result<Vec<u8>> {
195        let _ = index;
196        Err(Error::unsupported(
197            "core",
198            "attachments",
199            "This format has no embedded attachments; `info --view structure` lists what the file contains.",
200        ))
201    }
202    /// Per-frame acquisition records of image `image` (acquisition time, stage position,
203    /// detector state, ...), too numerous for `info`. Each record is a JSON object in the
204    /// reader's documented vocabulary. At most `limit` records are returned (`None` = all);
205    /// the first value is the total number of records. `info --view full` stores them under
206    /// `images[i].extra.frames` (see [`attach_frames`]). Formats without per-frame records keep
207    /// the default (no records).
208    fn frames(&self, image: u32, limit: Option<usize>) -> Result<(u64, Vec<serde_json::Value>)> {
209        let _ = (image, limit);
210        Ok((0, Vec::new()))
211    }
212    /// Experiment facts this reader knows that the normalized model cannot carry (a Bruker NMR
213    /// `title` file, an mzML `sampleList`), each value with its origin in `provenance`. They are
214    /// laid over the experiment derived from `info` ([`crate::experiment::of_dataset`]). Most
215    /// readers keep the default: everything they know is already in `info`.
216    fn experiment(&self) -> Option<crate::experiment::Experiment> {
217        None
218    }
219    /// The layout of a multi-well plate (high-content screening): imaged wells, the images of
220    /// each, and how complete the copy on disk is. `info` reports it under `plate`. Readers
221    /// of other files keep the default (none).
222    fn plate(&self) -> Option<crate::plate::PlateSummary> {
223        None
224    }
225    /// What the reader itself knows about this file's variant beyond `info` (structures met
226    /// but not decoded, values assumed, calibrations, block types), laid over its assurance
227    /// profile's observations ([`crate::assurance::assess`]). Most readers keep the default:
228    /// their profile reads everything it needs from `info`. Wrappers forward it.
229    fn assurance_observations(&self) -> crate::assurance::Observations {
230        crate::assurance::Observations::default()
231    }
232    /// This file's assurance ([`crate::assurance::assess_dataset`] over `info`); `None` when
233    /// `info` cannot be read. The strict-mode wrapper returns the assessment it gates on, so
234    /// `check` reports it even when strict mode refuses `info`.
235    fn file_assurance(&self) -> Option<crate::assurance::Assurance> {
236        let info = self.info().ok()?;
237        Some(crate::assurance::assess(
238            &info,
239            self.assurance_observations(),
240            &self.provenance(),
241        ))
242    }
243    /// Leave the peaks the instrument flags as reference or background ions out of the spectra
244    /// read from now on (Thermo `.raw`: what ThermoRawFileParser and ProteoWizard before
245    /// 3.0.20286 write). Returns false when the format flags no peaks (nothing changes).
246    fn exclude_flagged_peaks(&mut self, exclude: bool) -> bool {
247        let _ = exclude;
248        false
249    }
250    /// True for the `--strict` wrapper ([`crate::strict::StrictDataset`]): outputs built from
251    /// it withhold the fields its assurance does not validate (`Assurance::strict_withholds`).
252    fn is_strict(&self) -> bool {
253        false
254    }
255}
256
257/// Read the spectrum with instrument scan number `scan` of run `run`: through
258/// [`Dataset::find_spectrum`] when the reader has a scan-number map, otherwise assuming scan
259/// numbers are contiguous from the first spectrum's.
260pub fn spectrum_by_scan(
261    ds: &mut dyn Dataset,
262    run: u32,
263    scan: u64,
264    view: SpectrumView,
265) -> Result<Spectrum> {
266    if let Some(i) = ds.find_spectrum(run, scan)? {
267        return ds.read_spectrum_view(run, i, view);
268    }
269    let first = ds.read_spectrum_view(run, 0, view)?;
270    let i = scan.checked_sub(first.scan_number).ok_or_else(|| {
271        Error::Usage(format!(
272            "scan {scan} precedes the first scan ({})",
273            first.scan_number
274        ))
275    })?;
276    let sp = if i == 0 {
277        first
278    } else {
279        ds.read_spectrum_view(run, i, view)?
280    };
281    if sp.scan_number != scan {
282        return Err(Error::Usage(format!(
283            "scan numbers are not contiguous; spectrum {i} is scan {}. Use --index",
284            sp.scan_number
285        )));
286    }
287    Ok(sp)
288}
289
290/// Read the `nth` (1-based) spectrum of MS level `ms_level` in run `run`. MS1 and MS/MS scans
291/// are interleaved in most runs, so the first MS2 scan cannot be found by assuming the MS1 scans
292/// come first: the reader's per-spectrum MS levels ([`Dataset::spectrum_ms_levels`]) locate it
293/// and only that spectrum is decoded; a reader without them is walked from its first spectrum,
294/// `scan_count` (from `info` → `spectra[run].scan_count`) bounding the walk.
295pub fn spectrum_by_level(
296    ds: &mut dyn Dataset,
297    run: u32,
298    ms_level: u32,
299    nth: u64,
300    scan_count: u64,
301    view: SpectrumView,
302) -> Result<Spectrum> {
303    if nth == 0 {
304        return Err(Error::Usage(
305            "--nth counts from 1 (the first scan of that level)".into(),
306        ));
307    }
308    let mut seen = 0u64;
309    if let Some(levels) = ds.spectrum_ms_levels(run)? {
310        for (i, l) in levels.iter().enumerate() {
311            if *l == ms_level {
312                seen += 1;
313                if seen == nth {
314                    return ds.read_spectrum_view(run, i as u64, view);
315                }
316            }
317        }
318        return Err(Error::Usage(format!(
319            "run {run} has {seen} MS{ms_level} spectra (asked for number {nth}); `info` → spectra[].extra.ms_level_counts lists the counts"
320        )));
321    }
322    for i in 0..scan_count {
323        let sp = ds.read_spectrum_view(run, i, view)?;
324        if sp.ms_level == ms_level {
325            seen += 1;
326            if seen == nth {
327                return Ok(sp);
328            }
329        }
330    }
331    Err(Error::Usage(format!(
332        "run {run} has {seen} MS{ms_level} spectra (asked for number {nth}); `info` → spectra[].extra.ms_level_counts lists the counts"
333    )))
334}
335
336/// Default number of per-frame records `info --view full` embeds per image (`--all-frames` lifts
337/// it).
338pub const DEFAULT_FRAME_RECORDS: usize = 100;
339
340/// Store each image's per-frame records under `extra.frames` (plus `extra.frame_records_total`
341/// and, when capped, `extra.frames_truncated: true`). Images without records are left untouched.
342pub fn attach_frames(ds: &dyn Dataset, info: &mut FileInfo, limit: Option<usize>) -> Result<()> {
343    for img in &mut info.images {
344        let (total, records) = ds.frames(img.index, limit)?;
345        if records.is_empty() {
346            continue;
347        }
348        let truncated = (records.len() as u64) < total;
349        img.extra
350            .insert("frames".into(), serde_json::Value::Array(records));
351        img.extra
352            .insert("frame_records_total".into(), serde_json::Value::from(total));
353        if truncated {
354            img.extra
355                .insert("frames_truncated".into(), serde_json::Value::Bool(true));
356        }
357    }
358    Ok(())
359}
360
361/// A format implementation.
362pub trait FormatReader: Send + Sync {
363    /// Static description of the format (id, name, extensions, known gaps).
364    fn descriptor(&self) -> FormatDescriptor;
365    /// Inspect the first bytes (up to 64 KiB) and the path; return `None` if this is not ours.
366    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection>;
367    /// Open for reading.
368    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>>;
369    /// Like [`sniff`](FormatReader::sniff), for an [`Input`] that may not be on the local file
370    /// system. Readers whose detection looks at other files (a directory's contents, a
371    /// sibling) override it to look through [`Input::fs`]; the default calls `sniff` with the
372    /// input's path.
373    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
374        self.sniff(head, input.path())
375    }
376    /// Open an [`Input`]: a local path, a buffer in memory, or a source the host provides.
377    /// Readers that read through [`Input::fs`] override it (and make `open` a thin wrapper);
378    /// the default opens local inputs by path and reports every other source as unsupported
379    /// (exit 6), so a reader that does not read through byte sources never touches the local disk
380    /// for a buffer that merely has the same name.
381    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
382        if input.is_local() {
383            return self.open(input.path());
384        }
385        let d = self.descriptor();
386        Err(Error::Unsupported {
387            format: "input",
388            feature: format!(
389                "reading {} ({}) from an in-memory or host-provided source",
390                d.name, d.id
391            ),
392            hint: Some(
393                "This reader opens local files only so far: save the data to a file and open its path."
394                    .into(),
395            ),
396        })
397    }
398    /// True when [`open_input`](FormatReader::open_input) reads any [`Input`] (memory, host
399    /// callbacks), not only local paths.
400    fn reads_any_source(&self) -> bool {
401        false
402    }
403    /// The reader's assurance profile (its crate's `src/assurance.rs`): how to fingerprint a
404    /// file's variant and which variants the development corpus validates. `None` (the
405    /// default) makes every file of the format `unvalidated`.
406    fn assurance(&self) -> Option<&'static crate::assurance::AssuranceProfile> {
407        None
408    }
409}
410
411/// Number of leading bytes handed to `sniff`.
412pub const SNIFF_LEN: usize = 64 * 1024;
413
414/// Ordered collection of readers. First definite match wins; otherwise best confidence.
415pub struct Registry {
416    readers: Vec<Box<dyn FormatReader>>,
417    /// `--strict`: datasets opened through this registry refuse outputs their file's
418    /// assurance does not validate ([`crate::strict`]).
419    strict: bool,
420}
421
422impl std::fmt::Debug for Registry {
423    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
424        let ids: Vec<String> = self.readers.iter().map(|r| r.descriptor().id).collect();
425        f.debug_struct("Registry")
426            .field("readers", &ids)
427            .field("strict", &self.strict)
428            .finish()
429    }
430}
431
432impl Default for Registry {
433    /// An empty registry, strict when the process-wide default says so
434    /// ([`crate::assurance::default_strict`]: `--strict`, `OPENREADOUT_STRICT=1`).
435    fn default() -> Self {
436        Registry {
437            readers: Vec::new(),
438            strict: crate::assurance::default_strict(),
439        }
440    }
441}
442
443impl Registry {
444    /// An empty registry. Readers are consulted in the order they are added.
445    pub fn new() -> Self {
446        Self::default()
447    }
448
449    /// Add a reader at the end of the detection order (and make its assurance profile known).
450    pub fn register(&mut self, reader: Box<dyn FormatReader>) {
451        if let Some(p) = reader.assurance() {
452            crate::assurance::register_profile(p);
453        }
454        self.readers.push(reader);
455    }
456
457    /// Strict mode (`--strict`, MCP `strict: true`): every dataset this registry opens refuses,
458    /// with exit 6 and a hint, to return outputs its file's assurance does not validate
459    /// (`assurance.strict_refuses`: an unvalidated variant, an undecoded structure or an unapplied
460    /// calibration affecting them). `check` and `info --view structure` are never refused.
461    #[must_use]
462    pub fn strict(mut self, on: bool) -> Self {
463        self.strict = on;
464        self
465    }
466
467    /// True in strict mode.
468    pub fn is_strict(&self) -> bool {
469        self.strict
470    }
471
472    /// Builder form of [`Registry::register`].
473    pub fn with(mut self, reader: Box<dyn FormatReader>) -> Self {
474        self.register(reader);
475        self
476    }
477
478    /// Descriptors of every registered reader, in detection order.
479    pub fn descriptors(&self) -> Vec<FormatDescriptor> {
480        self.readers.iter().map(|r| r.descriptor()).collect()
481    }
482
483    /// The reader with this format id, if registered.
484    pub fn by_id(&self, id: &str) -> Option<&dyn FormatReader> {
485        self.readers
486            .iter()
487            .find(|r| r.descriptor().id == id)
488            .map(AsRef::as_ref)
489    }
490
491    /// Read the head of the file and ask every reader. A directory (a vendor "folder format"
492    /// such as a Bruker `.d`) is offered to every reader with an empty head; readers that accept
493    /// directories recognise them by their path and contents.
494    pub fn detect(&self, path: &Path) -> Result<(&dyn FormatReader, Detection)> {
495        self.detect_input(&Input::local(path))
496    }
497
498    /// Like [`detect`](Registry::detect), for any [`Input`] (a local path, a buffer, a host
499    /// source).
500    pub fn detect_input(&self, input: &Input) -> Result<(&dyn FormatReader, Detection)> {
501        let path = input.path();
502        let meta = input.metadata()?;
503        let mut head = Vec::new();
504        if !meta.is_dir() {
505            let mut file = input.open()?;
506            head = vec![0u8; SNIFF_LEN];
507            let mut filled = 0;
508            while filled < head.len() {
509                let n = file
510                    .read(&mut head[filled..])
511                    .map_err(|e| Error::io(path, e))?;
512                if n == 0 {
513                    break;
514                }
515                filled += n;
516            }
517            head.truncate(filled);
518            if filled == 0 {
519                // An empty file is a truncated file (interrupted copy or acquisition), not an
520                // unknown format: report it as corrupt so agents do not go looking for a reader.
521                return Err(Error::Corrupt {
522                    format: "input",
523                    detail: "the file is empty (0 bytes)".into(),
524                    offset: Some(0),
525                });
526            }
527        }
528        let mut best: Option<(&dyn FormatReader, Detection)> = None;
529        for r in &self.readers {
530            if let Some(d) = r.sniff_input(&head, input) {
531                let better = match &best {
532                    None => true,
533                    Some((_, b)) => rank(d.confidence) > rank(b.confidence),
534                };
535                if better {
536                    let definite = d.confidence == DetectConfidence::Definite;
537                    best = Some((r.as_ref(), d));
538                    if definite {
539                        break;
540                    }
541                }
542            }
543        }
544        best.ok_or_else(|| Error::UnknownFormat {
545            path: path.to_path_buf(),
546        })
547    }
548
549    /// Detect and open.
550    pub fn open(&self, path: &Path) -> Result<(Detection, Box<dyn Dataset>)> {
551        let (reader, det) = self.detect(path)?;
552        let ds = reader.open(path)?;
553        Ok((det, self.guard(ds)?))
554    }
555
556    /// In strict mode, wrap `ds` so it refuses unvalidated outputs; otherwise return it as is.
557    pub fn guard(&self, ds: Box<dyn Dataset>) -> Result<Box<dyn Dataset>> {
558        if self.strict {
559            crate::strict::StrictDataset::wrap(ds)
560        } else {
561            Ok(ds)
562        }
563    }
564
565    /// Detect and open any [`Input`]. Readers that only read local files report other inputs
566    /// as unsupported (exit 6).
567    pub fn open_input(&self, input: &Input) -> Result<(Detection, Box<dyn Dataset>)> {
568        let (reader, det) = self.detect_input(input)?;
569        let ds = reader.open_input(input)?;
570        Ok((det, self.guard(ds)?))
571    }
572
573    /// Detect from bytes already in memory (the first up to [`SNIFF_LEN`] bytes of a stream,
574    /// e.g. standard input). `name` stands in for the path readers may consult for an extension.
575    pub fn detect_bytes(&self, head: &[u8], name: &Path) -> Result<(&dyn FormatReader, Detection)> {
576        let head = &head[..head.len().min(SNIFF_LEN)];
577        let mut best: Option<(&dyn FormatReader, Detection)> = None;
578        for r in &self.readers {
579            if let Some(d) = r.sniff(head, name)
580                && best
581                    .as_ref()
582                    .is_none_or(|(_, b)| rank(d.confidence) > rank(b.confidence))
583            {
584                let definite = d.confidence == DetectConfidence::Definite;
585                best = Some((r.as_ref(), d));
586                if definite {
587                    break;
588                }
589            }
590        }
591        best.ok_or_else(|| Error::UnknownFormat {
592            path: name.to_path_buf(),
593        })
594    }
595}
596
597fn rank(c: DetectConfidence) -> u8 {
598    match c {
599        DetectConfidence::Definite => 3,
600        DetectConfidence::Likely => 2,
601        DetectConfidence::ExtensionOnly => 1,
602    }
603}
604
605/// Helper for readers: does the path have one of these extensions (case-insensitive)?
606pub fn has_extension(path: &Path, exts: &[&str]) -> bool {
607    path.extension()
608        .and_then(|e| e.to_str())
609        .is_some_and(|e| exts.iter().any(|x| x.eq_ignore_ascii_case(e)))
610}
611
612#[cfg(test)]
613mod tests {
614    use super::*;
615    use crate::provenance::Confidence;
616
617    #[derive(Debug)]
618    struct PathOnly;
619
620    impl FormatReader for PathOnly {
621        fn descriptor(&self) -> FormatDescriptor {
622            FormatDescriptor {
623                id: "path-only".into(),
624                name: "Path-only test format".into(),
625                vendor: String::new(),
626                extensions: vec!["po".into()],
627                family: "test".into(),
628                can_read: true,
629                can_write: false,
630                confidence: Confidence::Low,
631                known_gaps: Vec::new(),
632            }
633        }
634        fn sniff(&self, head: &[u8], _path: &Path) -> Option<Detection> {
635            head.starts_with(b"PO").then_some(Detection {
636                format_id: "path-only",
637                confidence: DetectConfidence::Definite,
638                note: None,
639            })
640        }
641        fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
642            Err(Error::Other(format!("opened {}", path.display())))
643        }
644    }
645
646    #[test]
647    fn unmigrated_readers_refuse_non_file_inputs() {
648        let reg = Registry::new().with(Box::new(PathOnly));
649        let input = Input::from_bytes("x.po", b"PO data".to_vec());
650        let (r, det) = reg.detect_input(&input).unwrap();
651        assert_eq!(det.format_id, "path-only");
652        assert!(!r.reads_any_source());
653        let err = reg.open_input(&input).map(|_| ()).unwrap_err();
654        assert_eq!(err.exit_code(), 6, "{err}");
655        assert!(err.hint().is_some());
656        // Local paths still reach `open`.
657        let dir = tempfile::tempdir().unwrap();
658        let path = dir.path().join("x.po");
659        std::fs::write(&path, b"PO data").unwrap();
660        let err = reg
661            .open_input(&Input::local(&path))
662            .map(|_| ())
663            .unwrap_err();
664        assert!(err.to_string().starts_with("opened "), "{err}");
665        // Empty inputs are corrupt, missing ones are I/O errors, like `detect`.
666        let empty = Input::from_bytes("e.po", Vec::new());
667        let code = |i: &Input| reg.detect_input(i).map(|_| ()).unwrap_err().exit_code();
668        assert_eq!(code(&empty), 4);
669        assert_eq!(code(&empty.with_path("other.po")), 5);
670    }
671}
672
673#[cfg(test)]
674mod level_tests {
675    use super::*;
676    use crate::model::{CheckReport, FileInfo, LsEntry, Spectrum};
677
678    /// A run with the given MS levels; counts the spectra decoded.
679    struct Run {
680        levels: Vec<u32>,
681        indexed: bool,
682        reads: u64,
683    }
684    impl Dataset for Run {
685        fn info(&self) -> Result<FileInfo> {
686            Err(Error::Other("unused".into()))
687        }
688        fn vendor_metadata(&self) -> Result<serde_json::Value> {
689            Ok(serde_json::Value::Null)
690        }
691        fn provenance(&self) -> ProvenanceMap {
692            ProvenanceMap::new()
693        }
694        fn entries(&self) -> Result<Vec<LsEntry>> {
695            Ok(vec![])
696        }
697        fn read_plane(&mut self, _: u32, _: PlaneIndex) -> Result<Plane> {
698            Err(Error::Other("unused".into()))
699        }
700        fn check(&mut self) -> Result<CheckReport> {
701            Ok(CheckReport::new("fake", "fake"))
702        }
703        fn read_spectrum(&mut self, _: u32, i: u64) -> Result<Spectrum> {
704            self.reads += 1;
705            Ok(Spectrum {
706                index: i,
707                ms_level: self.levels[i as usize],
708                ..Spectrum::default()
709            })
710        }
711        fn spectrum_ms_levels(&mut self, _: u32) -> Result<Option<Vec<u32>>> {
712            Ok(self.indexed.then(|| self.levels.clone()))
713        }
714    }
715
716    #[test]
717    fn nth_of_level_uses_the_index_when_there_is_one() {
718        for indexed in [true, false] {
719            let mut r = Run {
720                levels: vec![1, 2, 2, 1, 2],
721                indexed,
722                reads: 0,
723            };
724            let sp = spectrum_by_level(&mut r, 0, 2, 3, 5, SpectrumView::Primary).unwrap();
725            assert_eq!(sp.index, 4);
726            assert_eq!(r.reads, if indexed { 1 } else { 5 });
727            let err = spectrum_by_level(&mut r, 0, 2, 4, 5, SpectrumView::Primary).unwrap_err();
728            assert!(err.to_string().contains("has 3 MS2 spectra"), "{err}");
729        }
730    }
731}