zlight_csv 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be8e072a58943ca8b89b8f68c0943ad9daf80be6edb6274fad3f8fe7a20af34a
+  data.tar.gz: 5bf977f61545af25293a5e2b3560ee5e06df896b373a4771252d9a9dc482451a
+SHA512:
+  metadata.gz: fb006274ac24756d4336d27647343b64b6c753f6b6a5d4c35357b354558d379f8548dbef8825092c59ec9d8c4eb2431561177decb506816d22553f8d5a3eb10a
+  data.tar.gz: 88fff6de78e745e818cf22a3e92f3772550824e2453d93bc7e864a59d03a7131dafe1a4ccb7116086b30161559b65ce0f1696f236c0d339078dfa47acbd222c6

data/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.1] - 2026-09-12
+
+### Fixed
+
+- The extension now builds against a Ruby that rb-sys has no prebuilt bindings
+  for, via rb-sys `stable-api-compiled-fallback`, rather than failing outright.
+  This is the mechanism that breaks the build on every new Ruby release until
+  rb-sys catches up
+- Windows CI could not build the extension at all: the runner paired a MinGW
+  Ruby with an MSVC Rust toolchain. Ruby and Rust are now set up together so
+  their ABIs match, and Windows is verified across Ruby 3.1-4.0
+- Specs that asserted Unix-only error messages and paths now pass on Windows
+- Dropped an unreachable credentials check from the release workflow: the
+  credentials action fails first, so the check never ran
+
+### Note
+
+- 0.5.0 was tagged but never reached RubyGems: its release run built every gem
+  and then failed to publish, because trusted publishing still named the
+  project's former GitHub account. 0.5.1 is the first release carrying the
+  0.5.0 changes below.
+
+## [0.5.0] - 2026-09-12
+
+### Added
+
+- Ruby 4.0 support
+- `docker/test-matrix.sh`, which builds and tests the extension against every
+  supported Ruby in containers
+- Windows, Ruby 4.0 and a `ruby-head` early-warning job in CI, plus weekly
+  scheduled runs and Dependabot
+
+### Changed
+
+- Upgraded magnus from 0.6 to 0.8. magnus 0.6 read a field of Ruby's
+  RTypedData struct that Ruby 4.0 removed, so the extension could not compile
+  against it at all
+- Minimum Ruby is now 3.1. Ruby 3.0 is end-of-life and no longer supported by
+  magnus
+- Repository URLs now point at `codebyisaad/zlight`, which is where the code
+  is hosted
+
+### Fixed
+
+- The source gem shipped no extension and could not be compiled, so any Ruby
+  or platform without a prebuilt binary installed a gem that failed to load
+- `ZLight::ParseError`, `ZLight::EncodingError` and `ZLight::StreamClosedError`
+  were documented but never raised
+- Integers outside the i64 range were silently converted to lossy Floats
+- `col_sep` and `quote_char` longer than one byte were silently truncated when
+  reading, while writing rejected them
+- Releases no longer yank every previously published version
+
+
+## [0.4.0] - 2026-06-06
+
+### Added
+
+- `ZLight.generate` — build a CSV string from an array of hashes or an array
+  of arrays, with `headers`, `col_sep`, `quote_char` and `force_quotes` options
+- `ZLight.write` — generate a CSV and write it to a file in one call
+
+### Changed
+
+- Parsed fields are tagged with the encoding of the input string, matching
+  Ruby's stdlib CSV, so the parser and writer round-trip without
+  `force_encoding`
+
+## [0.3.0] - 2026-05-21
+
+### Changed
+
+- Release pipeline updates
+
+## [0.2.5] - 2026-05-21
+
+### Added
+
+- `ZLight.stream` and `ZLight.stream_file` — read rows one at a time without
+  loading the whole input into memory
+- `ZLight.open` — streaming with a block, closing the reader automatically
+- `ZLight::StreamReader`, including `Enumerable`, so `lazy`, `select`, `find`
+  and friends work over a stream
+
+### Fixed
+
+- Packaging and gemspec metadata corrections across 0.2.1–0.2.5
+
+## [0.2.0] - 2026-05-21
+
+### Added
+
+- Benchmark suite comparing ZLight against Ruby's stdlib CSV
+- Edge case coverage for quoting, encodings and flexible records
+
+## [0.1.2] - 2026-05-19
+
+### Added
+
+- Initial release
+- `ZLight.parse` — parse CSV strings, with `headers`, `converters`, `col_sep`,
+  `quote_char` and `flexible` options
+- `ZLight.read` — read and parse a CSV file
+- `ZLight.foreach` — iterate over parsed rows
+- Cross-platform precompiled native gems
+
+### Performance
+
+- Substantially faster than Ruby's stdlib CSV; see the README for measured
+  figures
+
+[Unreleased]: https://github.com/codebyisaad/zlight/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/codebyisaad/zlight/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/codebyisaad/zlight/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/codebyisaad/zlight/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/codebyisaad/zlight/compare/v0.2.5...v0.3.0
+[0.2.5]: https://github.com/codebyisaad/zlight/compare/v0.2.0...v0.2.5
+[0.2.0]: https://github.com/codebyisaad/zlight/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/codebyisaad/zlight/releases/tag/v0.1.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zaidan Chaudhary (also known as Saad Chaudhary)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# ZLight CSV
+
+[![Gem Version](https://badge.fury.io/rb/zlight_csv.svg)](https://badge.fury.io/rb/zlight_csv)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A fast CSV parser for Ruby, powered by Rust.
+
+## Why ZLight?
+
+Ruby's built-in CSV library is slow. ZLight parses CSV files **up to 40x faster** by using Rust under the hood.
+The gap is widest on small inputs and narrows as they grow; the measurements below show the range.
+
+### Benchmark Results
+
+Parsing with headers and numeric conversion (Apple M1):
+
+| Dataset | Ruby CSV | ZLight | Speedup |
+|---------|----------|--------|---------|
+| 1K rows | 12.6ms | 0.3ms | **42x faster** |
+| 10K rows | 133ms | 4.4ms | **30x faster** |
+| 100K rows | 1,458ms | 78ms | **19x faster** |
+
+File reading comparison (100K rows):
+
+| Method | Ruby CSV | ZLight | Speedup |
+|--------|----------|--------|---------|
+| Read all | 1,596ms | 58ms | **27x faster** |
+| Streaming | 1,104ms | 74ms | **15x faster** |
+
+Iterations per second (10K rows):
+
+```
+ZLight.parse:   253 i/s
+ZLight.stream:  159 i/s
+Ruby CSV:         8 i/s  — 33x slower
+```
+
+## Installation
+
+```ruby
+gem 'zlight_csv'
+```
+
+No Rust toolchain required — prebuilt binaries are available for Linux, macOS, and Windows.
+
+## Usage
+
+```ruby
+require 'zlight_csv'
+
+# Parse a CSV string
+data = ZLight.parse("name,age\nAlice,30\nBob,25")
+# => [{:name=>"Alice", :age=>"30"}, {:name=>"Bob", :age=>"25"}]
+
+# With automatic numeric conversion
+data = ZLight.parse(csv_string, converters: :numeric)
+# => [{:name=>"Alice", :age=>30}, {:name=>"Bob", :age=>25}]
+
+# Read from a file
+data = ZLight.read("users.csv")
+
+# Iterate over rows
+ZLight.foreach(csv_string) do |row|
+  puts row[:name]
+end
+```
+
+### Streaming Large Files
+
+For large files, use streaming to process rows one at a time without loading everything into memory:
+
+```ruby
+# Stream from a file (auto-closes when block exits)
+ZLight.open("large_file.csv") do |reader|
+  reader.each do |row|
+    process(row)
+  end
+end
+
+# Lazy enumeration — stop early without loading remaining rows
+ZLight.open("huge_file.csv", converters: :numeric) do |reader|
+  high_scores = reader.lazy
+                      .select { |row| row[:score] > 90 }
+                      .first(100)
+end
+
+# Manual control
+reader = ZLight.stream_file("data.csv")
+while row = reader.next_row
+  break if row[:id] > 1000
+  process(row)
+end
+reader.close
+```
+
+**Streaming is especially efficient for partial reads:**
+
+```
+Finding first 100 rows from 100K dataset:
+
+Ruby CSV (full parse):  1,696ms
+ZLight.parse (full):       73ms
+ZLight.stream (lazy):     0.3ms  ← 5,600x faster!
+```
+
+### Options (Reading)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `headers` | `true` | Use first row as headers (returns hashes). Set `false` for arrays. |
+| `converters` | `nil` | Set to `:numeric` to convert numbers automatically |
+| `col_sep` | `","` | Column separator (`"\t"` for TSV, `";"` for European CSV) |
+| `quote_char` | `"` | Quote character |
+| `flexible` | `true` | Allow rows with varying column counts |
+
+### Writing CSV
+
+Generate CSV strings or write directly to files:
+
+```ruby
+# Generate CSV from array of hashes
+csv = ZLight.generate([
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 25 }
+])
+# => "name,age\nAlice,30\nBob,25\n"
+
+# Generate from array of arrays (no headers)
+csv = ZLight.generate([["Alice", 30], ["Bob", 25]])
+# => "Alice,30\nBob,25\n"
+
+# Write directly to a file
+ZLight.write("users.csv", data)
+
+# With options
+ZLight.generate(data, col_sep: "\t", force_quotes: true)
+```
+
+### Options (Writing)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `headers` | `true` | Write header row (for hash input) |
+| `col_sep` | `","` | Column separator |
+| `quote_char` | `"` | Quote character |
+| `force_quotes` | `false` | Quote all fields, not just those requiring it |
+
+## Compatibility
+
+Works as a drop-in replacement for common `CSV.parse` patterns:
+
+```ruby
+# Before
+CSV.parse(data, headers: true, header_converters: :symbol, converters: :numeric)
+
+# After
+ZLight.parse(data, converters: :numeric)
+```
+
+### Differences from stdlib CSV
+
+ZLight is not a complete reimplementation of `CSV`. The differences below are
+deliberate, and are the ones most likely to matter when migrating.
+
+**API shape**
+
+- `ZLight.foreach` takes a **CSV string**, while `CSV.foreach` takes a **file
+  path**. Use `ZLight.open` to iterate a file.
+- `ZLight.foreach` parses the whole input before yielding. For genuinely lazy
+  iteration use `ZLight.stream` or `ZLight.open`.
+- `ZLight::StreamReader` is single-pass. It includes `Enumerable`, but each
+  row is consumed as it is read, so a second pass yields nothing and there is
+  no rewind. Call `ZLight.stream` again to re-read.
+
+**Parsing**
+
+- Duplicate headers collapse. Rows are `Hash`es, so `"a,a"` keeps only the
+  last `:a` column; `CSV` keeps both.
+- Fields beyond the header count are dropped rather than collected.
+- Headers become symbols always, equivalent to `header_converters: :symbol`.
+
+**`converters: :numeric`**
+
+| Input        | ZLight            | Ruby CSV   |
+|--------------|-------------------|------------|
+| `""`         | `""`              | `nil`      |
+| `"0x10"`     | `"0x10"`          | `16`       |
+| `"1_000"`    | `"1_000"`         | `1000`     |
+| `"Infinity"` | `Float::INFINITY` | `"Infinity"` |
+| `"NaN"`      | `Float::NAN`      | `"NaN"`    |
+
+Integers of any size are exact, as in `CSV`.
+
+**Writing**
+
+- `ZLight.generate` takes its column order from the keys of the **first**
+  hash. Keys that appear only in later rows are not written; keys missing
+  from a later row are written as empty fields.
+
+## Requirements
+
+- Ruby 3.1 or newer, including Ruby 4.0
+- Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), or Windows (x64)
+
+Every supported Ruby is built and tested on each change; see
+`docker/test-matrix.sh` to run that matrix yourself. Rubies without a
+precompiled binary install from the source gem and need a Rust toolchain.
+
+## Roadmap
+
+- [x] Streaming/lazy parsing for large files
+- [x] CSV writing support
+- [ ] Custom converter procs
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/codebyisaad/zlight).
+
+## Author
+
+Zaidan Chaudhary, who also publishes as Saad Chaudhary.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/VERSION

@@ -0,0 +1 @@
+0.5.1

data/ext/zlight_csv/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "zlight_csv"
+# Synced from ../../VERSION by extconf.rb — do not edit manually.
+version = "0.4.0"
+edition = "2021"
+authors = ["Zaidan Chaudhary", "Saad Chaudhary"]
+description = "High-performance CSV parser for Ruby, powered by Rust"
+license = "MIT"
+repository = "https://github.com/codebyisaad/zlight"
+
+[lib]
+crate-type = ["cdylib"]
+path = "src/lib.rs"
+
+[dependencies]
+csv = "1"
+magnus = "0.8"
+# Depended on directly, only to turn on stable-api-compiled-fallback.
+# rb-sys ships prebuilt bindings for Ruby versions it knows about and fails
+# outright on ones it does not, which is what breaks the build on every new
+# Ruby before rb-sys catches up. The fallback compiles the shim from the
+# headers of whatever Ruby is present instead, so an unreleased Ruby builds.
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+thiserror = "1"
+
+[profile.release]
+lto = true
+codegen-units = 1
+opt-level = 3
+strip = true

data/ext/zlight_csv/extconf.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+def sync_cargo_version!
+  version = File.read(File.expand_path("../../VERSION", __dir__), encoding: "UTF-8").strip
+  cargo_toml = File.join(__dir__, "Cargo.toml")
+  contents = File.read(cargo_toml, encoding: "UTF-8")
+  updated = contents.sub(/^version = ".*"$/, %(version = "#{version}"))
+  File.write(cargo_toml, updated) if contents != updated
+end
+
+sync_cargo_version!
+
+create_rust_makefile("zlight_csv/zlight_csv")

data/ext/zlight_csv/src/converter.rs

@@ -0,0 +1,133 @@
+use magnus::{encoding::Index, prelude::*, Ruby, Value};
+
+/// Converts a byte slice field to a Ruby string value tagged with `encoding`.
+///
+/// Fields are labelled with the encoding of the original input string (or UTF-8
+/// for file streams) so that parsed values match Ruby's stdlib CSV behavior and
+/// round-trip cleanly through the writer.
+#[inline(always)]
+pub fn field_to_string(ruby: &Ruby, field: &[u8], encoding: Index) -> Value {
+    ruby.enc_str_new(field, encoding).as_value()
+}
+
+/// Fast check if a byte slice looks like it could be a float.
+/// Scans for '.', 'e', or 'E' in a single pass.
+#[inline(always)]
+fn looks_like_float(bytes: &[u8]) -> bool {
+    bytes.iter().any(|&b| b == b'.' || b == b'e' || b == b'E')
+}
+
+/// Trim ASCII whitespace from both ends without allocation.
+#[inline(always)]
+fn trim_ascii(bytes: &[u8]) -> &[u8] {
+    let start = bytes.iter().position(|&b| !b.is_ascii_whitespace()).unwrap_or(bytes.len());
+    let end = bytes.iter().rposition(|&b| !b.is_ascii_whitespace()).map_or(start, |i| i + 1);
+    &bytes[start..end]
+}
+
+/// Outcome of the integer fast path.
+enum IntScan {
+    /// Parsed exactly into an i64.
+    Fits(i64),
+    /// A valid decimal integer, but too large in magnitude for an i64.
+    TooLarge,
+    /// Not a decimal integer at all.
+    NotAnInteger,
+}
+
+/// Fast path: scan an optionally signed run of ASCII digits without full UTF-8
+/// validation.
+///
+/// Values outside i64 are reported as `TooLarge` rather than rejected, so the
+/// caller can fall back to an exact Ruby Integer instead of an inexact float.
+#[inline(always)]
+fn scan_int(bytes: &[u8]) -> IntScan {
+    if bytes.is_empty() {
+        return IntScan::NotAnInteger;
+    }
+
+    let digits = match bytes[0] {
+        b'-' | b'+' => &bytes[1..],
+        _ => bytes,
+    };
+    let negative = bytes[0] == b'-';
+
+    if digits.is_empty() {
+        return IntScan::NotAnInteger;
+    }
+
+    let mut magnitude: i64 = 0;
+    let mut overflowed = false;
+
+    for &b in digits {
+        if !b.is_ascii_digit() {
+            return IntScan::NotAnInteger;
+        }
+        if overflowed {
+            continue;
+        }
+        match magnitude
+            .checked_mul(10)
+            .and_then(|m| m.checked_add((b - b'0') as i64))
+        {
+            Some(next) => magnitude = next,
+            // Keep scanning to confirm the rest is digits too, but remember
+            // that the value needs Ruby's arbitrary-precision Integer.
+            None => overflowed = true,
+        }
+    }
+
+    if overflowed {
+        IntScan::TooLarge
+    } else if negative {
+        IntScan::Fits(-magnitude)
+    } else {
+        IntScan::Fits(magnitude)
+    }
+}
+
+/// Builds an exact Ruby Integer from a decimal string too large for an i64.
+///
+/// Ruby Integers are arbitrary precision, so no digits are lost. `scan_int` has
+/// already established that the slice is ASCII digits with an optional sign,
+/// which is why `String#to_i` is safe here.
+#[inline]
+fn big_integer(ruby: &Ruby, digits: &[u8]) -> Option<Value> {
+    let text = std::str::from_utf8(digits).ok()?;
+    ruby.str_new(text).funcall("to_i", ()).ok()
+}
+
+/// Attempts to parse a byte slice as a numeric value (integer or float).
+#[inline]
+fn try_parse_numeric(ruby: &Ruby, field: &[u8]) -> Option<Value> {
+    let trimmed = trim_ascii(field);
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    // Fast path: try integer parsing without UTF-8 conversion.
+    if !looks_like_float(trimmed) {
+        match scan_int(trimmed) {
+            IntScan::Fits(i) => return Some(ruby.integer_from_i64(i).as_value()),
+            IntScan::TooLarge => return big_integer(ruby, trimmed),
+            IntScan::NotAnInteger => {}
+        }
+    }
+
+    // Slow path: need UTF-8 for float parsing.
+    let text = std::str::from_utf8(trimmed).ok()?;
+    text.parse::<f64>()
+        .ok()
+        .map(|f| ruby.float_from_f64(f).as_value())
+}
+
+/// Converts a byte slice field to an appropriate Ruby value.
+/// If `convert_numeric` is true, attempts to parse as number first.
+#[inline(always)]
+pub fn field_to_value(ruby: &Ruby, field: &[u8], convert_numeric: bool, encoding: Index) -> Value {
+    if !convert_numeric {
+        return field_to_string(ruby, field, encoding);
+    }
+
+    try_parse_numeric(ruby, field).unwrap_or_else(|| field_to_string(ruby, field, encoding))
+}

data/ext/zlight_csv/src/error.rs

@@ -0,0 +1,122 @@
+use magnus::{prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+use thiserror::Error;
+
+/// Enumerated error types for ZlightCsv operations.
+#[derive(Debug, Error)]
+pub enum ZlightError {
+    #[error("CSV parsing error: {0}")]
+    CsvParse(csv::Error),
+
+    #[error("Invalid UTF-8 encoding in header: {0}")]
+    InvalidHeaderEncoding(String),
+
+    #[error("Missing required argument: {0}")]
+    MissingArgument(&'static str),
+
+    #[error("Invalid option value for '{key}': expected {expected}, got {actual}")]
+    InvalidOption {
+        key: &'static str,
+        expected: &'static str,
+        actual: String,
+    },
+
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("Stream reader has been closed")]
+    StreamClosed,
+}
+
+impl ZlightError {
+    /// Converts to a Ruby exception with the appropriate exception class.
+    ///
+    /// Requires the Ruby handle, which is always available here: an error is
+    /// only converted on its way out of an extension method, and those run on
+    /// a Ruby thread holding the GVL. Building an exception needs a class, and
+    /// a class cannot be obtained without the handle, so there is no sensible
+    /// fallback for a VM we are not attached to.
+    #[inline]
+    pub fn to_magnus_error(&self) -> MagnusError {
+        let ruby = Ruby::get().expect("errors are only converted while a Ruby method is running");
+        MagnusError::new(self.exception_class(&ruby), self.to_string())
+    }
+
+    /// Resolves the exception class to raise, preferring the gem's own
+    /// `ZLight::*` class over the built-in it descends from.
+    fn exception_class(&self, ruby: &Ruby) -> ExceptionClass {
+        self.zlight_class_name()
+            .and_then(|name| resolve_zlight_class(ruby, name))
+            .unwrap_or_else(|| self.builtin_class(ruby))
+    }
+
+    /// Name of the `ZLight::*` class this error is documented to raise as, for
+    /// errors that have one.
+    fn zlight_class_name(&self) -> Option<&'static str> {
+        match self {
+            ZlightError::CsvParse(_) => Some("ParseError"),
+            ZlightError::InvalidHeaderEncoding(_) => Some("EncodingError"),
+            ZlightError::StreamClosed => Some("StreamClosedError"),
+            ZlightError::MissingArgument(_)
+            | ZlightError::InvalidOption { .. }
+            | ZlightError::Io(_) => None,
+        }
+    }
+
+    /// Built-in class to raise when there is no `ZLight::*` equivalent, and the
+    /// fallback if one cannot be resolved.
+    fn builtin_class(&self, ruby: &Ruby) -> ExceptionClass {
+        match self {
+            ZlightError::CsvParse(_) => ruby.exception_runtime_error(),
+            ZlightError::InvalidHeaderEncoding(_) => ruby.exception_encoding_error(),
+            ZlightError::MissingArgument(_) | ZlightError::InvalidOption { .. } => {
+                ruby.exception_arg_error()
+            }
+            ZlightError::Io(_) | ZlightError::StreamClosed => ruby.exception_io_error(),
+        }
+    }
+}
+
+/// Looks up `ZLight::<name>`.
+///
+/// The extension is loaded before lib/zlight_csv.rb defines these classes, so
+/// the lookup happens when an error is raised rather than at init. It returns
+/// `None` if the Ruby side was never loaded, leaving the caller to fall back to
+/// a built-in class.
+fn resolve_zlight_class(ruby: &Ruby, name: &'static str) -> Option<ExceptionClass> {
+    let zlight: RModule = ruby.class_object().const_get("ZLight").ok()?;
+    zlight.const_get(name).ok()
+}
+
+impl From<csv::Error> for ZlightError {
+    /// The csv crate wraps read failures in its own error type. A directory or
+    /// an unreadable file is an IO problem, not malformed CSV, so unwrap those
+    /// rather than reporting them as a parse failure.
+    fn from(err: csv::Error) -> Self {
+        if !err.is_io_error() {
+            return ZlightError::CsvParse(err);
+        }
+
+        match err.into_kind() {
+            csv::ErrorKind::Io(io) => ZlightError::Io(io),
+            kind => unreachable!("is_io_error() guarantees ErrorKind::Io, got {kind:?}"),
+        }
+    }
+}
+
+impl From<ZlightError> for MagnusError {
+    #[inline]
+    fn from(err: ZlightError) -> Self {
+        err.to_magnus_error()
+    }
+}
+
+pub type Result<T> = std::result::Result<T, ZlightError>;
+
+/// Converts a `csv` crate error into a Ruby exception.
+///
+/// `?` cannot bridge csv::Error to MagnusError on its own, because that would
+/// need two chained `From` conversions.
+#[inline]
+pub fn csv_error(err: csv::Error) -> MagnusError {
+    ZlightError::from(err).into()
+}