btctax_forms/
error.rs

1//! Error type for the PDF form-fill engine.
2
3/// Anything that can go wrong filling an official IRS PDF.
4///
5/// The **geometric read-back** failures (`Geometry`, `UnmappedField`) are the tax-safety net: a fill
6/// that lands a value in the wrong cell — or writes any field the map did not authorize — FAILS
7/// CLOSED (no PDF bytes are returned), so a mis-mapped form is never handed to a filer.
8#[derive(Debug, thiserror::Error)]
9pub enum FormsError {
10    /// The requested tax year has no bundled form set / map (this build ships TY2017, 2024 + 2025).
11    #[error("unsupported tax year {0}: this build bundles IRS forms for 2017, 2024 and 2025 only")]
12    UnsupportedYear(i32),
13
14    /// A field named by the map does not exist in the bundled PDF's AcroForm.
15    #[error("map references field {0:?} which is absent from the bundled PDF field set")]
16    MapFieldMissing(String),
17
18    /// More data rows than the form's page grid can hold on the paths that do not paginate.
19    #[error("{rows} rows exceed the {capacity}-row capacity of a single {part} page")]
20    Overflow {
21        /// The part being filled ("Part I" / "Part II").
22        part: &'static str,
23        /// The number of rows requested.
24        rows: usize,
25        /// The per-page row capacity from the map.
26        capacity: usize,
27    },
28
29    /// The geometric read-back found a written value in the WRONG column/row band — the map is
30    /// mis-aligned. Fails closed.
31    #[error("geometric read-back FAILED (mis-mapped cell): {0}")]
32    Geometry(String),
33
34    /// A field carries a value but the map never authorized writing it (a stray write). Fails closed.
35    #[error("read-back FAILED: unmapped field {0:?} was filled")]
36    UnmappedField(String),
37
38    /// The bundled PDF's structure was not what the engine expects (missing AcroForm, bad Rect, …).
39    #[error("bundled PDF structure error: {0}")]
40    Structure(String),
41
42    /// Underlying lopdf parse/serialize error.
43    #[error("pdf error: {0}")]
44    Pdf(#[from] lopdf::Error),
45
46    /// A committed TOML map failed to parse.
47    #[error("map parse error: {0}")]
48    Map(#[from] toml::de::Error),
49
50    /// I/O error serializing the PDF.
51    #[error("io error: {0}")]
52    Io(#[from] std::io::Error),
53}
btctax_forms/error.rs

btctax_forms/
error.rs
