Skip to main content

stuffr_core/
error.rs

1use crate::display::fmt_name;
2use crate::format::FormatId;
3
4pub type Result<T> = std::result::Result<T, Error>;
5
6#[derive(Debug, thiserror::Error)]
7#[non_exhaustive]
8pub enum Error {
9    /// Stuffr's environment failed: a disk error, a permission failure, a
10    /// broken pipe. Exit 1, which this project reserves for "stuffr itself
11    /// failed" and nothing else.
12    ///
13    /// **Constructed through a hand-written `From` impl, not a derived one**
14    /// — see below `Error`'s own `impl` block. The derived `#[from]` was
15    /// blind to whether the failing read sat above or below a codec decoder,
16    /// which made a bare `?` below one wrong by default; four sites had it
17    /// wrong at once. [`crate::source::decode_side`] carries the whole
18    /// argument.
19    #[error("i/o error: {}", fmt_name(&.0.to_string()))]
20    Io(#[source] std::io::Error),
21
22    #[error("usage error: {}", fmt_name(.0))]
23    Usage(String),
24
25    #[error("format `{0}` is not available in this build")]
26    FormatNotEnabled(FormatId),
27
28    #[error("could not detect format; leading bytes were {seen}")]
29    UnknownFormat { seen: String },
30
31    #[error("format is ambiguous; candidates: {candidates}. Pass --format to choose.")]
32    AmbiguousFormat { candidates: String },
33
34    #[error("input is not seekable and `{format}` requires random access")]
35    NotSeekable { format: FormatId },
36
37    #[error("spill limit of {limit} bytes exceeded; raise --max-spill or use a seekable input")]
38    SpillLimitExceeded { limit: u64 },
39
40    #[error("resource limit exceeded: {}", fmt_name(.0))]
41    ResourceLimit(String),
42
43    #[error("archive is corrupt: {}", fmt_name(.0))]
44    Corrupt(String),
45
46    /// An entry the extraction refuses to materialise. `path` is the entry
47    /// name, verbatim. `reason` may quote a link target or directory, already
48    /// escaped for display with [`fmt_name`]; `Display` escapes it again,
49    /// which is harmless because escaping is idempotent.
50    #[error("unsafe entry path `{}` refused: {}", fmt_name(.path), fmt_name(.reason))]
51    UnsafePath { path: String, reason: String },
52
53    #[error("fidelity degraded under strict mode: {0} warning(s)")]
54    FidelityDegraded(usize),
55
56    #[error("entry `{}` not found", fmt_name(.0))]
57    EntryNotFound(String),
58
59    #[error("unsupported: {}", fmt_name(.0))]
60    Unsupported(String),
61
62    #[error("`{format}` can be {available} but not {requested} by this build")]
63    CapabilityUnavailable {
64        format: FormatId,
65        /// The direction that IS available, e.g. "read".
66        available: &'static str,
67        /// The direction that was asked for and is not, e.g. "written".
68        requested: &'static str,
69    },
70
71    /// Nesting exceeded [`crate::probe::MAX_CHAIN_DEPTH`]. Names the bound so
72    /// the message is actionable rather than merely a refusal.
73    #[error("archive nesting exceeds the {depth}-layer limit")]
74    ChainTooDeep { depth: usize },
75
76    /// The chain resolved to raw bytes with no container to open — e.g.
77    /// `list`/`test` pointed at a plain codec stream, or at a file whose
78    /// magic and extension both name none. Names what the input actually
79    /// resolved to (`chain.describe()`), so "unpack this .gz" is actionable
80    /// rather than a bare refusal.
81    #[error("{chain} is not an archive — it has no entries to list")]
82    NotAnArchive { chain: String },
83}
84
85impl Error {
86    /// "Entry number `index` does not exist; here is what does."
87    ///
88    /// One constructor rather than a `format!` at each raiser, because there
89    /// are two routes to an out-of-range index and they must report it
90    /// IDENTICALLY: a container's own [`crate::ArchiveRead::by_index`] finds
91    /// it immediately (zip, which has a central directory to check against),
92    /// while a caller counting a forward walk finds it only at the end of the
93    /// archive (tar, ar, cpio, and anything on a pipe). A script that could
94    /// tell those apart from the message would be reading an implementation
95    /// detail of the source it was handed.
96    ///
97    /// [`Self::EntryNotFound`] rather than [`Self::Usage`] because the variant
98    /// exists for exactly this — "you named an entry this archive does not
99    /// have" — and carries the same exit code, 2. The payload is shaped to
100    /// read inside that variant's own `entry \`{0}\` not found` wording.
101    ///
102    /// Indices are 0-based throughout, so the valid range is stated
103    /// explicitly rather than left to be derived from the count: `0-5` is
104    /// harder to get wrong than "6 entries" is.
105    pub fn entry_index_out_of_range(index: usize, entries: usize) -> Self {
106        Error::EntryNotFound(match entries {
107            0 => format!("#{index} (this archive has no entries)"),
108            n => format!(
109                "#{index} (valid indices are 0-{} in this {n}-entry archive)",
110                n - 1
111            ),
112        })
113    }
114
115    /// A container whose caps say `!stores_hardlinks` was handed an
116    /// `EntryKind::Hardlink`: refused (exit 3) before anything is written,
117    /// never stored as a regular file. `plan_entry_write` keeps links away
118    /// from such writers; this is each writer's backstop, and the ONE wording.
119    pub fn hardlink_not_storable(container: &str, name: &str) -> Self {
120        Error::Unsupported(format!(
121            "{container} cannot store the hard link `{name}`: it has no hard link entry, \
122             and a link written as a regular file would be an empty copy"
123        ))
124    }
125
126    /// Maps to the process exit code, per the spec's table. Lives here rather
127    /// than in the CLI so it is unit-testable without a process spawn.
128    ///
129    /// # Exit 5 or exit 6 on an absurd header field: the rule the guards actually follow
130    ///
131    /// Seven of this workspace's guards refuse a declared header field before
132    /// it can do damage, and they split across two codes. The table is
133    /// exhaustive of the seven it names, NOT of every bounding check in the
134    /// tree:
135    ///
136    /// | guard | error | exit |
137    /// |---|---|---|
138    /// | `cpio.rs`'s `c_namesize` ceiling | `ResourceLimit` | 6 |
139    /// | `cpio.rs`'s and `zip.rs`'s `read_symlink_target` (declared target over 65,536 bytes) | `ResourceLimit` | 6 |
140    /// | `ar.rs`'s `refuse_if_over` (GNU name table, BSD identifier) | `ResourceLimit` | 6 |
141    /// | `ar.rs`'s `/N` index past the declared name table | `Corrupt` | 5 |
142    /// | `zip.rs`'s entry payload that never delivers its declared size | `Corrupt` | 5 |
143    /// | `zip.rs`'s index that reaches no entry over a file that opens with one | `Corrupt` | 5 |
144    ///
145    /// **The rule is a fact about what stuffr DID, not about what the input
146    /// declared:**
147    ///
148    /// * **Exit 6 — stuffr declined to ask the allocator.** The field was
149    ///   measured against a structural ceiling and refused before anything was
150    ///   sized from it. Nothing was read past the header.
151    /// * **Exit 5 — stuffr read the bytes and they contradict each other.** No
152    ///   allocation was ever in question; what is wrong is the file's
153    ///   agreement with itself.
154    ///
155    /// **It is NOT "could a bigger machine honour it".** Three of those sites
156    /// used to argue that locally, and their own reproducers falsify it:
157    /// cpio's is a **274-byte file declaring a 2.6 GiB name**, which no
158    /// machine anywhere can deliver, and it answers 6; ar's two guards split
159    /// across 5 and 6 on the **same 68-byte file**. Nothing about the input's
160    /// plausibility separates them, so a caller cannot predict the code from
161    /// the file — only from which guard stopped first. Each site links here
162    /// rather than re-deriving a local justification, because four local
163    /// derivations produced four different rules for one contract.
164    ///
165    /// What a caller can still read off the code: exit 6 says a LIMIT decided
166    /// the outcome, exit 5 says the FILE did and no budget changes that. The
167    /// container ceilings above are fixed rather than tunable (`OpenOpts`
168    /// carries no memory field, unlike `DecodeOpts::memory_limit`), so exit 6
169    /// there is not an invitation to retry with a bigger budget — it is still
170    /// the honest code, because a ceiling and not the bytes is what decided.
171    pub fn exit_code(&self) -> i32 {
172        match self {
173            Error::Usage(_) => 2,
174            Error::NotAnArchive { .. } => 2,
175            // The caller named an entry the archive does not contain — the
176            // same shape as naming a format this build does not have, and
177            // the same answer `NotAnArchive` above gives for "you pointed
178            // this verb at the wrong thing". Explicit, not the wildcard
179            // below: `stuffr unpack a.tar -C out nosuch.txt` extracting
180            // nothing must be distinguishable from an i/o failure.
181            Error::EntryNotFound(_) => 2,
182            // The same shape again, and the fourth wrong code this
183            // wildcard has produced. `stuffr list plain.txt.gz` (not an
184            // archive) exited 2; `stuffr list plain.txt` (no format at all)
185            // exited 1, as if stuffr had failed rather than the caller
186            // having pointed a verb at the wrong file. `AmbiguousFormat`'s
187            // own message literally says "Pass `--format` to choose" —
188            // actionable advice with an exit code that says "internal
189            // failure". Both are usage, both are 2.
190            Error::UnknownFormat { .. } | Error::AmbiguousFormat { .. } => 2,
191            Error::FormatNotEnabled(_) => 3,
192            Error::CapabilityUnavailable { .. } => 3,
193            // Exit 3 is "this build cannot do that", and every raiser of
194            // `Unsupported` in this workspace is exactly that — a capability
195            // or expressiveness limit, never an internal failure:
196            //
197            // * tar's, ar's and cpio's `by_index` refusal on a seekable
198            //   source ("this container carries no entry index, by design").
199            // * cpio's 4 GiB per-entry ceiling, which is its `u32` size
200            //   field and not a bug.
201            // * zip's unsupported compression method — an encrypted entry, a
202            //   pre-deflate legacy method, or the pure tier's zstd gap, whose
203            //   message names `--features c-backed`.
204            // * a `Chain` variant added upstream that this build does not
205            //   know how to open, decode or describe.
206            // * `create_symlink` on a non-unix host.
207            //
208            // Explicit, not the wildcard below, and it did fall through it
209            // until Phase 2's Task 11: every one of those was reported as a
210            // generic failure, indistinguishable from an internal error, so a
211            // user told "rebuild with `--features c-backed`" got the same
212            // exit code as a panic-adjacent bug. That is the THIRD wrong code
213            // this wildcard has produced in this phase, after
214            // `ChainTooDeep` and `EntryNotFound`.
215            Error::Unsupported(_) => 3,
216            // "You asked for random access and this source cannot do it" is
217            // the same answer as the two arms above — a capability limit,
218            // actionable, and never an internal failure. It is the *required*
219            // reply to `by_index` on a forward-only source (container
220            // conformance property 6, and SEVEN raisers: `tar.rs`, `ar.rs`,
221            // `cpio.rs` and `zip.rs` each raise it once for exactly this, and
222            // `ladder.rs` (twice) and `probe.rs` (once) raise it from below
223            // the container layer, when the ladder itself cannot supply
224            // seek), so a valid archive on a pipe produced it on every single
225            // read — and the wildcard below
226            // reported that by-design refusal as exit 1, "stuffr failed".
227            // `entries.rs:453` already treats it as interchangeable with
228            // `Unsupported` when deciding whether to fall back to a forward
229            // walk; the exit code now agrees with that. The FIFTH wrong code
230            // this wildcard has produced, after `ChainTooDeep`,
231            // `EntryNotFound`, `Unsupported` and the
232            // `UnknownFormat`/`AmbiguousFormat` pair. Found by Phase 3a's
233            // honesty oracle (`honesty.rs`), before the fuzzer had run once.
234            Error::NotSeekable { .. } => 3,
235            Error::FidelityDegraded(_) => 4,
236            Error::Corrupt(_) => 5,
237            // A nesting bound is a bound on WORK, the same family as the
238            // spill and ratio limits — never exit 5, so a refused nesting
239            // bomb stays distinguishable from a corrupt file. Explicit, not
240            // the wildcard below: falling through it would make a refused
241            // nesting bomb indistinguishable from an internal error.
242            Error::SpillLimitExceeded { .. }
243            | Error::ResourceLimit(_)
244            | Error::ChainTooDeep { .. } => 6,
245            Error::UnsafePath { .. } => 7,
246            // A wrong exit code landing here is not always this match's own
247            // fault: it can equally mean the wrong `Error` variant was
248            // constructed upstream, before this function ever ran. See
249            // `Error::from_decode_io` — Task 4b's fix lives there, not here.
250            _ => 1,
251        }
252    }
253
254    /// Classifies an io error that arose while decoding.
255    ///
256    /// Malformed input becomes [`Error::Corrupt`] (exit 5); everything else
257    /// stays [`Error::Io`] (exit 1). `InvalidData` is the convention every
258    /// codec's decoder is expected to normalise onto for malformed input; a
259    /// codec whose backend disagrees adapts at its own boundary rather than
260    /// this classification changing. gzip is one such codec: flate2's
261    /// pure-Rust backend actually raises `InvalidInput` and `UnexpectedEof`,
262    /// never `InvalidData`, so gzip's decoder wraps it in an adapter that
263    /// folds both onto `InvalidData` before this function ever sees them.
264    ///
265    /// `OutOfMemory` becomes [`Error::ResourceLimit`] (exit 6), not
266    /// `Corrupt`: a codec whose dictionary allocation would exceed
267    /// `DecodeOpts::memory_limit` is refusing to allocate, not reporting a
268    /// damaged file, and exit 5 would actively mislead the caller about
269    /// which of those happened. A codec that raises this kind is expected to
270    /// have NOT routed it through the same `InvalidData`-folding adapter it
271    /// uses for malformed input, the same way `InvalidData` above is a
272    /// convention the codec opts into deliberately.
273    ///
274    /// One rule here rather than a helper each codec calls: putting the
275    /// decision in nine places means the natural code — a bare `?` on an
276    /// `io::Error` — silently bypasses it, and a convention whose failure mode
277    /// is invisible is not a convention. Conformance property 9 enforces the
278    /// codec half, that malformed input surfaces as `InvalidData` at all.
279    ///
280    /// Lives in `stuffr-core` rather than in `ops` because Phase 2's containers
281    /// need the identical classification on their own decode paths.
282    ///
283    /// **Task 4b (Phase 3a's fuzzing harness) added a fourth call site:**
284    /// `probe.rs`'s `resolve_chain_deep_with` re-probes a DECODED stream
285    /// whenever a codec has no container above it and the path named
286    /// nothing further (stdin, or an extension that ran out) — the loop
287    /// documented on `resolve_chain_deep`'s own doc comment. That re-probe
288    /// used to read through a bare `?`, so a truncated zlib stream
289    /// (`\x78\xda\x0a`, three bytes) or an empty file named `.lz` reported
290    /// `Error::Io` — exit 1, "stuffr failed" — for input that is simply
291    /// corrupt, while `stuffr cat` on the IDENTICAL bytes (via
292    /// `ops::decompress`, whose decode read was already wired to this
293    /// function) correctly exited 5. This is deliberately NOT filed as a
294    /// sixth instance of `exit_code`'s `_ => 1` wildcard misfiling a KNOWN
295    /// variant (see that match's own comment for the five it has produced):
296    /// `Error::Io` reaching that wildcard is correct, by construction —
297    /// it has no dedicated arm because the wildcard IS its arm. The bug
298    /// here was upstream of `exit_code` entirely: the wrong variant got
299    /// constructed in the first place, at a read that passed through a
300    /// decoder without this classifier's protection.
301    pub fn from_decode_io(e: std::io::Error) -> Self {
302        match e.kind() {
303            std::io::ErrorKind::InvalidData => Error::Corrupt(e.to_string()),
304            std::io::ErrorKind::OutOfMemory => Error::ResourceLimit(e.to_string()),
305            _ => Error::Io(e),
306        }
307    }
308}
309
310/// The single conversion every `?` on a read path passes through.
311///
312/// Hand-written rather than derived with thiserror's `#[from]`, because the
313/// derived one could not see the one fact that decides the answer: whether the
314/// read that failed sat BELOW a codec decoder (the archive's fault) or above
315/// one (stuffr's environment failing). [`crate::source::mark_decode_side`]
316/// records that at the read, and this is where it is spent.
317///
318/// Before this existed, the distinction was carried by whether the author of a
319/// given `?` remembered to write `map_err(Error::from_decode_io)` instead — so
320/// the natural code was wrong by default, and four sites had it wrong at once
321/// (`spill.rs`'s ladder rung 3, `lha.rs`'s `Lha::open`, `cpio.rs`'s per-header
322/// read-ahead, `zip.rs`'s `read_fixed`/`skip`). A 21-byte zstd stream whose
323/// decoded bytes opened with ARJ's `60 EA` magic reached the first of them and
324/// reported `i/o error` — exit 1, "stuffr failed" — where `stuffr cat` on the
325/// identical bytes correctly said the archive was corrupt.
326///
327/// [`Error::from_decode_io`] folds only `InvalidData` and `OutOfMemory`, so
328/// this cannot mistake an environment failure for corruption even when one
329/// propagates up through a decoder: it keeps its own kind, so it stays
330/// [`Error::Io`].
331impl From<std::io::Error> for Error {
332    fn from(e: std::io::Error) -> Self {
333        if crate::source::is_decode_side(&e) {
334            Error::from_decode_io(e)
335        } else {
336            Error::Io(e)
337        }
338    }
339}
340
341#[cfg(test)]
342mod tests {
343    use super::*;
344    use crate::format::FormatId;
345
346    #[test]
347    fn free_text_messages_escape_names_but_keep_their_own_text() {
348        let m = Error::Corrupt(format!("entry `{}` bad", "a\x1bb")).to_string();
349        assert_eq!(m, "archive is corrupt: entry `a\\x1bb` bad");
350        let io = std::io::Error::new(std::io::ErrorKind::InvalidData, "a\x1bb short");
351        assert_eq!(Error::Io(io).to_string(), "i/o error: a\\x1bb short");
352        for e in [
353            Error::Usage("x".into()),
354            Error::ResourceLimit("x".into()),
355            Error::Unsupported("x".into()),
356        ] {
357            assert!(!e.to_string().contains('\x1b'));
358        }
359        let plain = "`naïve` \"q\" 'q' 日本";
360        assert_eq!(
361            Error::Unsupported(plain.into()).to_string(),
362            format!("unsupported: {plain}")
363        );
364    }
365
366    #[test]
367    fn entry_names_in_error_messages_are_escaped() {
368        let all = [
369            Error::EntryNotFound("a\x1bb".into()),
370            Error::UnsafePath {
371                path: "a\x1bb".into(),
372                reason: "r".to_string(),
373            },
374        ];
375        for e in all {
376            let m = e.to_string();
377            assert!(m.contains("a\\x1bb"), "{m}");
378            assert!(!m.contains('\x1b'), "{m:?}");
379        }
380    }
381
382    #[test]
383    fn exit_codes_match_the_spec_table() {
384        assert_eq!(Error::Usage("bad flag".into()).exit_code(), 2);
385        assert_eq!(
386            Error::FormatNotEnabled(FormatId::new("zstd")).exit_code(),
387            3
388        );
389        assert_eq!(
390            Error::Unsupported("no zstd in this build".into()).exit_code(),
391            3
392        );
393        assert_eq!(
394            Error::NotSeekable {
395                format: FormatId::new("squashfs")
396            }
397            .exit_code(),
398            3
399        );
400        assert_eq!(Error::FidelityDegraded(2).exit_code(), 4);
401        assert_eq!(Error::Corrupt("bad crc".into()).exit_code(), 5);
402        assert_eq!(Error::EntryNotFound("nosuch.txt".into()).exit_code(), 2);
403        assert_eq!(Error::SpillLimitExceeded { limit: 42 }.exit_code(), 6);
404        assert_eq!(Error::ResourceLimit("oom".into()).exit_code(), 6);
405        assert_eq!(
406            Error::UnsafePath {
407                path: "../x".into(),
408                reason: "path traversal above the destination".to_string(),
409            }
410            .exit_code(),
411            7
412        );
413    }
414
415    /// The refusal has to say what IS valid, not merely that the asked-for
416    /// index is not — and the zero-entry case must not underflow its way to
417    /// "valid indices are 0-18446744073709551615".
418    #[test]
419    fn an_out_of_range_index_names_the_valid_range_and_survives_an_empty_archive() {
420        let e = Error::entry_index_out_of_range(9, 6);
421        assert_eq!(e.exit_code(), 2);
422        let text = e.to_string();
423        assert!(text.contains("#9"), "{text}");
424        assert!(
425            text.contains("0-5"),
426            "the valid range must be stated, not left to be derived: {text}"
427        );
428
429        let empty = Error::entry_index_out_of_range(0, 0).to_string();
430        assert!(
431            empty.contains("no entries") && !empty.contains("0-1844"),
432            "an empty archive must not underflow into a nonsense range: {empty}"
433        );
434    }
435
436    #[test]
437    fn from_decode_io_keys_resource_limit_off_out_of_memory_not_corrupt() {
438        // A codec refusing to allocate a declared dictionary is not reporting
439        // a damaged file — exit 6, never exit 5. See `DecodeOpts::memory_limit`.
440        let io_err = std::io::Error::new(std::io::ErrorKind::OutOfMemory, "too big");
441        let classified = Error::from_decode_io(io_err);
442        assert!(matches!(classified, Error::ResourceLimit(_)));
443        assert_eq!(classified.exit_code(), 6);
444    }
445
446    #[test]
447    fn not_seekable_names_the_format_so_callers_can_act() {
448        let e = Error::NotSeekable {
449            format: FormatId::new("squashfs"),
450        };
451        assert!(e.to_string().contains("squashfs"));
452        // Exit 3, not 1. A source that cannot seek is a capability limit in
453        // exactly the sense `Unsupported` and `CapabilityUnavailable` are,
454        // and it is the mandated answer to `by_index` on a forward-only
455        // source — so exit 1 meant every valid archive read from a pipe
456        // reported "stuffr failed". See `exit_code`'s own arm for why this
457        // is the fifth variant the wildcard has misfiled.
458        assert_eq!(e.exit_code(), 3);
459        assert_ne!(
460            e.exit_code(),
461            1,
462            "a by-design refusal must stay distinguishable from an internal failure"
463        );
464    }
465
466    #[test]
467    fn unsupported_is_a_capability_limit_not_a_generic_failure() {
468        // The three exit-3 variants say the same thing at different
469        // granularities — "this build cannot do that" — so they must not
470        // disagree on the code. `Unsupported` fell through the wildcard to 1
471        // until Phase 2's Task 11, which made a container's honest
472        // "rebuild with `--features c-backed`" indistinguishable from an
473        // internal error. See `exit_code`'s own comment for the full list of
474        // raisers and why every one of them belongs here.
475        let unsupported = Error::Unsupported(
476            "zip entry uses compression method 93 (zstd); rebuild with `--features c-backed`"
477                .into(),
478        );
479        assert_eq!(unsupported.exit_code(), 3);
480        assert_eq!(
481            Error::FormatNotEnabled(FormatId::new("zstd")).exit_code(),
482            3
483        );
484        assert_eq!(
485            Error::CapabilityUnavailable {
486                format: FormatId::new("lzma"),
487                available: "read as a zip entry",
488                requested: "written as one",
489            }
490            .exit_code(),
491            3
492        );
493        assert_ne!(
494            unsupported.exit_code(),
495            1,
496            "exit 1 is an internal failure; a capability limit is actionable and must be \
497             distinguishable from one"
498        );
499    }
500
501    #[test]
502    fn chain_too_deep_is_a_resource_limit_not_a_generic_failure() {
503        // A refused nesting bomb must be distinguishable from an internal
504        // error — falling through the wildcard to 1 would erase that.
505        assert_eq!(Error::ChainTooDeep { depth: 4 }.exit_code(), 6);
506    }
507
508    #[test]
509    fn not_an_archive_names_the_chain_and_is_a_usage_error() {
510        let e = Error::NotAnArchive {
511            chain: "gzip".into(),
512        };
513        assert!(
514            e.to_string().contains("gzip"),
515            "must name what the input resolved to: {e}"
516        );
517        assert_eq!(e.exit_code(), 2);
518    }
519
520    #[test]
521    fn unknown_format_reports_what_was_actually_seen() {
522        // The error must name the bytes, otherwise debugging a misdetection
523        // means adding print statements to the library.
524        let e = Error::UnknownFormat {
525            seen: "1f 8b 08".into(),
526        };
527        assert!(e.to_string().contains("1f 8b 08"));
528    }
529
530    /// "You pointed the verb at the wrong file" is one answer, not three.
531    ///
532    /// `NotAnArchive` already exited 2. `UnknownFormat` and
533    /// `AmbiguousFormat` fell through the wildcard to 1 — an internal
534    /// failure — so `stuffr list plain.txt.gz` exited 2 and `stuffr list
535    /// plain.txt` exited 1 for the same class of mistake. Explicit arms,
536    /// not the wildcard: that wildcard has now produced a wrong code five
537    /// times, `NotSeekable` being the fifth (see its own arm in
538    /// `exit_code`).
539    #[test]
540    fn pointing_a_verb_at_the_wrong_file_is_always_exit_two() {
541        assert_eq!(
542            Error::UnknownFormat {
543                seen: "de ad be ef".into()
544            }
545            .exit_code(),
546            2,
547            "an undetectable format is the caller's mistake, not an internal failure"
548        );
549        let ambiguous = Error::AmbiguousFormat {
550            candidates: "lzma, lzip".into(),
551        };
552        assert_eq!(
553            ambiguous.exit_code(),
554            2,
555            "a message that says `Pass --format to choose` is actionable, so exit 2"
556        );
557        assert!(
558            ambiguous.to_string().contains("--format"),
559            "and it must keep saying so: {ambiguous}"
560        );
561        // The neighbour they must agree with.
562        assert_eq!(
563            Error::NotAnArchive {
564                chain: "gzip".into()
565            }
566            .exit_code(),
567            2
568        );
569        // And the codes they must NOT collide with: a build-capability
570        // limit is still 3, a damaged file still 5.
571        assert_eq!(Error::Unsupported("no".into()).exit_code(), 3);
572        assert_eq!(Error::Corrupt("bad".into()).exit_code(), 5);
573    }
574}