errgonomic 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1490dc9d568769e95cc3d584907bf7a4bffb1af0381de3e4ce9a141736133166
-  data.tar.gz: 75fe0c80ad6ee5067aa8cce76c78f293e22ca1019b9d3415c57688c9c64ec2b9
+  metadata.gz: 1b7d451a7e98b347baa9556bf72fd22d3825278bf03afddb9a4fdb0e7c325b03
+  data.tar.gz: b336d798fc24356fc0a340ac24d5c562d10d242d5507a71444daa881831ecb27
 SHA512:
-  metadata.gz: 836b910b35ffd4bef2e78a7e5f72548e952a3da57f2e7642baaeeae1ba7bf93992f09b62baca76f2918836621f2dfa5780bfc56beea9c359d38d0154ae601286
-  data.tar.gz: 1fd7d78dcebdbc6eda3f54471f5e7f41c9f2f2db718ee7885489de16d9fbdbe42bf00ae842f171a32067f187abd26e7d6d93c1cb3422d893805f6c2716b7eb67
+  metadata.gz: 3967b76933831abb7750f253f345a8845c4bd00a172db427d99cd22c5fd3f41d9d18b36a7a44f4f915b04acca72009f52e4927ec8dfa60d98bea80eda82e1a2c
+  data.tar.gz: 2a7ef8d3aa5dbd1e9777e8a653a48c5d3eafbf1b8514e26a483e3056b5139dce643ace35542062512da59b2fa0c9d4b5ab915754e83e747196dabe65f6af91f8

data/.envrc

@@ -1,2 +1,2 @@
-watch_file gemset.nix
+watch_file Gemfile Gemfile.lock
 use flake

data/.rubocop.yml

@@ -1 +1,28 @@
-require: rubocop-yard
+plugins: rubocop-yard
+
+# Doctest expectation lines are executable spec; wrapping them would change
+# the assertions. Long lines carrying a `#=>` expectation are allowed.
+Layout/LineLength:
+  AllowedPatterns:
+    - '#=>'
+
+# Some(), None(), Ok() and Err() are the library's Rust-style value
+# constructors; their capitalized names are the point.
+Naming/MethodName:
+  AllowedPatterns:
+    - '\A(Some|None|Ok|Err)\z'
+
+# Option::Any and Result::Any deliberately carry the whole combinator API in
+# one class each, mirroring Rust's Option and Result surface.
+Metrics/ClassLength:
+  Exclude:
+    - lib/errgonomic/option.rb
+    - lib/errgonomic/result.rb
+
+# core_ext vendors ActiveSupport's blank?/present? patches; the reopened core
+# classes there are explained by the file header, not per class. Test
+# fixtures and cases are likewise self-describing.
+Style/Documentation:
+  Exclude:
+    - lib/errgonomic/core_ext/**/*
+    - test/**/*

data/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+This document captures how we develop `errgonomic`: the workflow, the quality gate, and the values that decide a judgment call when the rules run out.
+
+## Environment
+
+The toolchain is pinned by `flake.nix` and loaded automatically by `direnv`. A checkout with `direnv allow` already has the correct Ruby toolchain (ruby and the locked gem environment) on the path. The project is self-contained and targets multiple systems (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin): do not install tools globally or reach outside the repository, except where a task explicitly calls for it (for example, reading a script in a sibling project as a reference).
+
+Gems are provided by [gems4nix](https://github.com/omc/gems4nix), which reads `Gemfile.lock` directly — there is no `gemset.nix`. When gem dependencies change, run `bundle lock --add-checksums` (preserving the platform list — gems4nix needs the `CHECKSUMS` section and the precompiled platform variants), then `rake gems4nix:groups` to regenerate the committed `gem-groups.json` group mapping.
+
+Nontrivial development, debugging, and testing commands live as Rake tasks in the `Rakefile` rather than being re-typed ad hoc — they should be reproducible and not churn permission prompts. `rake -T` lists what is available.
+
+## Development loop
+
+We work test-first, in three beats:
+
+1. **Red** — write a failing test that names the behavior you intend. Run it and watch it fail for the reason you expect. A test that passes the moment you write it was not testing the new behavior.
+2. **Green** — write the least code that makes the test pass. Resist designing ahead of the test in front of you.
+3. **Refactor** — with the test green, improve the shape of the code. The test is your safety net; the behavior must not change.
+
+Each beat ends with a compiling, formatted tree. One small conceptual change per edit; multi-concern edits get broken up. Small, reversible steps beat large speculative ones.
+
+## The gate — a ladder
+
+The inner rungs run constantly; the outer rungs are slower and run when preparing to push or open a PR. Run them in order; do not skip ahead.
+
+**Per edit, and before each commit (inner gate):**
+
+```sh
+bundle exec rubocop        # formatted & lint-clean
+bundle exec yard doctest   # doctests pass — most behavior is specified here
+bundle exec rake test      # unit tests pass (incl. the Rails integration test)
+```
+
+A change that fails any of these is not ready. Keep formatting-only changes in their own commit so they do not obscure a behavioral diff. `bundle exec rake` runs the full suite (test + yard:doctest) in one shot.
+
+**Before push / PR (outer gate):**
+
+```sh
+bundle exec rake                 # full suite: unit tests + doctests
+nix build .#errgonomic           # the gem builds as a derivation; rake runs in its checkPhase
+nix flake check --all-systems    # builds every check on the local system, evaluates all four
+```
+
+**After push (CI gate):** a push is done when CI is green, not when `git push` succeeds. Check whatever CI this repo runs (`gh run list`, `gh run view --log-failed`); checks take minutes, so it is fine to schedule the check as a followup and keep working — but the change is not landed until they pass. A CI failure is a regression: diagnose it from the logs, reproduce it locally where you can, and capture it as a test so it cannot recur silently. CI earns you the coverage you cannot run locally — a target your machine isn't, a matrix leg, a slower suite — for free. Here, CI (`.github/workflows/main.yml`) runs `yard doctest` and `rake test` on the latest Ruby 3.4.x on ubuntu-latest, matching the Ruby pinned by the flake.
+
+Tests *are* the requirements: a behavior is defined by the test that asserts it. Prefer doctests where an example clarifies a function's contract — they document and test at once and cannot drift out of date without failing the build. In this repo, the YARD `@example` blocks under `lib/**/*.rb` are the primary suite.
+
+## Commits
+
+- One logical change per commit. The subject names the conceptual change (not the file change); the body says why, when the why is not obvious.
+- **Agents do not sign commits** unless explicitly directed. Pass `--no-gpg-sign` per commit (do not set `git config commit.gpgsign false`). Signing happens later, by a human, at review.
+- Agents do not add co-author or generated-by trailers.
+
+## Comments and documentation
+
+Comments explain intent and rationale — the *why* behind a non-obvious choice. They must stand on their own: a reader should understand a comment without chasing a ticket, an external document, a previous version of the code, a project plan, or (rarely, and only when it genuinely aids understanding) another file. Write for the developer who arrives a year from now with none of today's context.
+
+## What we value, in order
+
+When two designs compete, prefer them in this order.
+
+1. **Correct.** The code states its behavior and is tested against that statement. Invalid states are made unrepresentable rather than guarded against after the fact. Runtime failures produce diagnostics that tell an operator what went wrong and what to do.
+2. **Simple.** The code reads clearly at the right level of abstraction, and is idiomatic and approachable to another developer. Fewer moving parts, fewer sources of truth.
+3. **Performant.** Done well, the first two rarely cost us speed. Do not trade clarity for micro-optimization without a measurement that demands it.
+
+We also keep abstraction just-in-time: let the compiler and tests tell us where a seam is needed rather than pre-abstracting, and refactor when a real need surfaces.

data/README.md

@@ -2,6 +2,26 @@
 
 Errgonomic provides some lightweight, opinionated ergonomics for error handling in Ruby. These semantics are a blend of Rails `present?` conventions, and Rust `Option` and `Result` type combinators. Without going full Option and Result. Probably.
 
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add errgonomic
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install errgonomic
+```
+
+Errgonomic requires Ruby >= 3.0.
+
+## Usage
+
+### Presence helpers
+
 The `present_or` method takes what you might ordinarily write as `foo || default` with a possible nil or falsey value, and brings that to any other object that may be `blank?`.
 
 ```ruby
@@ -29,45 +49,187 @@ When constructing that fallback object may be expensive, you can provide a block
 And when all else fails, you can control the failure, by raising an exception for blank objects. This can be preferable to sending a blank object to some other downstream code that may be expecting a value, causing an ambiguous failure.
 
 ```ruby
-irb(main):007> [].present_or_raise("foo")
+[].present_or_raise!("foo")
 # => foo (Errgonomic::NotPresentError)
 ```
 
-## Installation
+Each helper has a `blank_or*` counterpart for when you expect the object to be blank: `blank_or`, `blank_or_else`, `blank_or_raise!`.
 
-TODO: Replace `errgonomic` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### Type assertions
 
-Install the gem and add to the application's Gemfile by executing:
+The same pattern applies to runtime type expectations:
 
-```bash
-bundle add errgonomic
+```ruby
+"hello".type_or_raise!(String)
+# => "hello"
+
+123.type_or_raise!(String)
+# => Expected String but got Integer (Errgonomic::TypeMismatchError)
+
+123.type_or(String, "default")
+# => "default"
+
+123.type_or_else(String) { "default" }
+# => "default"
+
+"hello".not_type_or_raise!(Integer)
+# => "hello"
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Option
 
-```bash
-gem install errgonomic
+`Some(value)` and `None()` wrap a value that may or may not be there, with most of the Rust `Option` combinators:
+
+```ruby
+Some(1).unwrap!                  # => 1
+None().unwrap!                   # => raises Errgonomic::UnwrapError
+None().unwrap_or(2)              # => 2
+None().unwrap_or_else { 2 }      # => 2
+Some(1).expect!("must be set")   # => 1
+
+Some(1).map { |x| x + 1 }        # => Some(2)
+Some(2).and_then { |x| Some(x + 1) } # => Some(3)
+None().or(Some(1))               # => Some(1)
+Some(:left).xor(None())          # => Some(:left)
+Some(1).zip(Some(2))             # => Some([1, 2])
+Some(1).ok_or("nope")            # => Ok(1)
+None().ok_or("nope")             # => Err("nope")
 ```
 
-## Usage
+Options support pattern matching:
+
+```ruby
+case measurement
+in Errgonomic::Option::Some, value
+  "Measurement is #{value}"
+in Errgonomic::Option::None
+  "Measurement is not available"
+end
+```
+
+An unhandled Option refuses to leak into your output: `to_s` and `to_json` raise `Errgonomic::SerializeError`, so you handle the inner value deliberately rather than shipping `#<Errgonomic::Option::Some...>` to a user.
+
+`unwrap!` and `expect!` are for tests and consoles, not application code: they raise on `None`, which is exactly the ambiguous failure the type exists to prevent. Application code should always have a combinator or pattern match that handles the `None` branch explicitly; if none fits, that is a gap worth an issue rather than a reason to unwrap.
+
+Presence follows the discriminant, as in Rust: `Some` is `present?` and `None` is `blank?`, regardless of the wrapped value. So `Some(false).present?` and `Some(nil).present?` are both `true`. If you care about the inner value's own presence, unwrap it first.
+
+Equality is between Options only: `Some(5) == Some(5)`, but `Some(5) == 5` and `None() == nil` are `false`. That is quiet, never an error, matching how every Ruby object compares across types. Rust rejects `Some(5) == 5` at compile time; Ruby cannot, so guard the idiom in review and tests: compare against a wrapped value (`opt == Some(5)`) or test the inner value (`opt.some_and? { |v| v == 5 }`).
+
+### Result
 
-TODO: Write usage instructions here
+`Ok(value)` and `Err(error)` express an operation that may fail, again with the Rust combinators:
+
+```ruby
+Ok(1).unwrap!                        # => 1
+Err(:nope).unwrap!                   # => raises Errgonomic::UnwrapError
+Err(:nope).unwrap_or(2)              # => 2
+
+Ok(1).map { |x| x + 1 }              # => Ok(2)
+Err(:bob).map_err { |e| e.capitalize } # => Err(:Bob)
+Ok(1).and_then { |x| Ok(x + 1) }     # => Ok(2)
+Err(:e).or_else { |e| Ok(1) }        # => Ok(1)
+
+Ok(1).ok_and?(&:odd?)                # => true
+Err(:a).err_and? { |_| true }        # => true
+```
+
+Results also pattern match, including against the kind of inner value:
+
+```ruby
+case result
+in Errgonomic::Result::Ok, value
+  "Measurement is #{value}"
+in Errgonomic::Result::Err, String => msg
+  "Measurement failed with a message: #{msg}"
+in Errgonomic::Result::Err, Exception => e
+  "Measurement produced an exception -- #{e.class}: #{e}"
+end
+```
+
+Like Options, unwrapped Results refuse `to_s` and `to_json`. And `Object#result?` / `Object#assert_result!` help enforce at runtime that a value is a Result.
+
+### Optional collections
+
+Hash and Array gain two additive lookups each, and nothing else changes about them. `fetch_option` follows presence the way Rust's `HashMap#get` and slice `get` do: a present key or index holding `nil` is `Some(nil)`, and only a missing one is `None()`.
+
+```ruby
+h = { color: :blue, shade: nil }
+h.fetch_option(:color)  # => Some(:blue)
+h.fetch_option(:shade)  # => Some(nil)
+h.fetch_option(:smell)  # => None()
+
+[:a, nil].fetch_option(1)  # => Some(nil)
+[:a, nil].fetch_option(2)  # => None()
+```
+
+`into_optional` wraps the collection in `Errgonomic::OptionalHash` / `Errgonomic::OptionalArray`, a view whose lookups all return Options. The wrappers are deliberately small — `[]`, `[]=`, `dig`, presence checks, and (for arrays) `first`/`last` — and are composed around the plain collection rather than subclassing it, because a subclass sheds its custom semantics every time `select` or `transform_values` returns a plain Hash. `to_h` / `to_a` hand back a detached copy.
+
+```ruby
+h = { person: { name: 'Ada', middle_name: nil } }.into_optional
+h.dig(:person, :name)         # => Some("Ada")
+h.dig(:person, :middle_name)  # => Some(nil)   (present, holding nil)
+h.dig(:person, :nickname)     # => None()      (absent)
+
+[].into_optional.first        # => None()
+```
+
+`dig` checks presence at every step, so an absent path and a present `nil` stay distinguishable, which core `dig` conflates. Digging into a non-collection raises `Errgonomic::TypeMismatchError` rather than answering `None()`, in the gem's pedantic style.
+
+### Booleans
+
+Booleans lift into the containers, following Rust's `bool`: `then_some`, and `ok_or`/`ok_or_else` from nightly. Rust splits the lazy form into `then`, but that name is core Ruby (`Kernel#then`), which Errgonomic will not redefine; `then_some` takes either a value or a block instead. Rust's `ok_or` returns `Result<(), E>`; Ruby has no unit type, so `Ok` carries `true`.
+
+```ruby
+admin.then_some(:badge)       # => Some(:badge) when true, None() when false
+admin.then_some { badge! }    # lazy variant
+valid.ok_or("invalid input")  # => Ok(true) / Err("invalid input")
+```
+
+### Pedantic runtime checks
+
+Combinators that accept a block (`and_then`, `or_else`, ...) check at runtime that the block returned an Option or Result, raising `Errgonomic::ArgumentError` otherwise. That beats an ambiguous `undefined method` error somewhere downstream. If you would rather have the ambiguous downstream errors, you can opt out — but not quietly:
+
+```ruby
+Errgonomic.with_ambiguous_downstream_errors do
+  # anything goes in here
+end
+```
+
+### Rails integration
+
+When `Rails::Railtie` is defined, Errgonomic installs a Railtie with two opt-in integrations for ActiveRecord:
+
+- `include Errgonomic::Rails::ActiveRecordOptional` in a model makes its nullable attributes and `optional: true` associations return `Some(value)` or `None()` instead of a value-or-nil. This is all-or-nothing per model: every nullable column and optional association is wrapped, with no per-attribute opt-in.
+- `delegate_optional :name, to: :association` (available on all models) delegates through an optional association, returning an Option instead of raising on nil.
+
+`Object#to_option` is also available in Rails to lift any value into an Option (`nil.to_option # => None()`).
+
+#### ActiveRecord compromises
+
+ActiveRecord assumes things about accessors that a strict Rust Option cannot satisfy, so the integration carries four deliberate compromises. Everywhere else, treat a departure from Rust's `Option` semantics as a bug; these four are intended:
+
+1. `None#nil?` answers `true`, so ActiveRecord internals and ordinary `.nil?` checks treat an absent value as absent. Equality does not follow suit: `None() == nil` is still `false`.
+2. `Some` delegates `persisted?`, `marked_for_destruction?`, and `touch_later` to its record, so a `Some` can stand in for its record during persistence.
+3. Quoting is patched so an `Option` passed into `where`/`quote` is unwrapped at the SQL boundary.
+4. `SomeValidator` provides a presence-style validation for Option attributes.
+
+The set is closed. If a future integration appears to need a fifth compromise, that is a signal ActiveRecord is pushing back somewhere unmapped, and it warrants a design discussion rather than a quiet patch.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. The repository is a self-contained Nix flake; with direnv, `direnv allow` puts the right toolchain on your path.
 
 This project encourages **red, green, refactor** when making changes. First, add or change a test that captures the desired behavior; next, run the tests to observe the failure message, confirming the test is useful; next, make the smallest code change(s) to make the test pass. Once tests pass, review your diff and look for opportunities to simplify or improve abstractions; make changes and iterate, running tests on each change to guard against regressions.
 
-Run the doctest suite with:
+Most of the behavior above is specified as YARD doctests, so the examples in the code documentation are the test suite. Run them with:
 
 ```bash
-nix develop -c yard doctest
+nix develop -c rake yard:doctest
 ```
 
-Run all tests with:
+Run the full suite (unit tests plus doctests) with:
 
-```
+```bash
 nix develop -c rake
 ```
 
@@ -75,7 +237,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/omc/errgonomic. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nz/errgonomic/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/omc/errgonomic. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/omc/errgonomic/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -83,4 +245,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Errgonomic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nz/errgonomic/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Errgonomic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/omc/errgonomic/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -11,7 +11,20 @@ end
 require 'yard/doctest/rake'
 YARD::Doctest::RakeTask.new do |task|
   task.doctest_opts = %w[-v]
-  task.pattern = 'lib/**/*.rb'
+  # Expand here: the pattern reaches yard through a shell whose ** means *,
+  # which silently dropped every doctest under lib/errgonomic/*/.
+  task.pattern = FileList['lib/**/*.rb'].join(' ')
 end
 
 task default: %i[test yard:doctest]
+
+namespace :gems4nix do
+  desc 'Regenerate gem-groups.json after Gemfile/Gemfile.lock changes'
+  task :groups do
+    require 'json'
+    locked = JSON.parse(`nix flake metadata --json`).dig('locks', 'nodes', 'gems4nix', 'locked')
+    ref = "github:#{locked['owner']}/#{locked['repo']}/#{locked['rev']}"
+    src = JSON.parse(`nix flake prefetch --json #{ref}`).fetch('storePath')
+    sh "ruby #{src}/lib/gemfile-env/gem-groups.rb > gem-groups.json"
+  end
+end

data/flake.lock

@@ -1,23 +1,45 @@
 {
   "nodes": {
+    "gems4nix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1784080771,
+        "narHash": "sha256-+Vnzrg4XMbTmFtr00krmdt5W8uKKKDVmV1B1cLDsGks=",
+        "owner": "omc",
+        "repo": "gems4nix",
+        "rev": "faecc855e315fc38ada09d7b60e53f1158370fd8",
+        "type": "github"
+      },
+      "original": {
+        "owner": "omc",
+        "ref": "nz/gemspec-directive-fix",
+        "repo": "gems4nix",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1751741127,
-        "narHash": "sha256-t75Shs76NgxjZSgvvZZ9qOmz5zuBE8buUaYD28BMTxg=",
+        "lastModified": 1784432872,
+        "narHash": "sha256-n3gKTBIV4ZA5VQpUakffBe3KGu4+mhPoA34rrqS0GkA=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "29e290002bfff26af1db6f64d070698019460302",
+        "rev": "fd1462031fdee08f65fd0b4c6b64e22239a77870",
         "type": "github"
       },
       "original": {
         "owner": "nixos",
-        "ref": "nixos-25.05",
+        "ref": "nixos-26.05",
         "repo": "nixpkgs",
         "type": "github"
       }
     },
     "root": {
       "inputs": {
+        "gems4nix": "gems4nix",
         "nixpkgs": "nixpkgs"
       }
     }

data/flake.nix

@@ -2,11 +2,20 @@
   description = "Errgonomic";
 
   inputs = {
-    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-25.05";
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-26.05";
+    gems4nix = {
+      url = "github:omc/gems4nix/nz/gemspec-directive-fix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
   };
 
   outputs =
-    inputs@{ self, nixpkgs, ... }:
+    {
+      self,
+      nixpkgs,
+      gems4nix,
+      ...
+    }:
     let
       allSystems = [
         "x86_64-linux"
@@ -14,8 +23,7 @@
         "x86_64-darwin"
         "aarch64-darwin"
       ];
-      overlays = [
-      ];
+      overlays = [ gems4nix.overlays.default ];
       forAllSystems =
         f:
         nixpkgs.lib.genAttrs allSystems (
@@ -25,33 +33,90 @@
             inherit system;
           }
         );
+      # lib/errgonomic/version.rb is the single source of truth for the version.
+      version = builtins.head (
+        builtins.match ".*VERSION = '([^']+)'.*" (builtins.readFile ./lib/errgonomic/version.rb)
+      );
+      # The full Gemfile.lock environment, shared by the dev shell and the
+      # package's check phase. The gemspec and version.rb ride along because the
+      # Gemfile references the gemspec, which requires version.rb.
+      gemEnvFor =
+        pkgs:
+        pkgs.gemfileEnv {
+          name = "errgonomic-gems";
+          gemfile = ./Gemfile;
+          gemfileLock = ./Gemfile.lock;
+          gemspec = ./errgonomic.gemspec;
+          extraFiles = {
+            "lib/errgonomic/version.rb" = ./lib/errgonomic/version.rb;
+          };
+          # Committed group mapping keeps evaluation pure (no Ruby IFD), so
+          # foreign systems still evaluate on one machine. Regenerate with
+          # `rake gems4nix:groups` after changing the Gemfile.
+          gemGroups = builtins.fromJSON (builtins.readFile ./gem-groups.json);
+        };
     in
     {
+      packages = forAllSystems (
+        { pkgs, ... }:
+        let
+          gems = gemEnvFor pkgs;
+        in
+        rec {
+          default = errgonomic;
+          errgonomic = pkgs.stdenv.mkDerivation {
+            pname = "errgonomic";
+            inherit version;
+            src = ./.;
+            nativeBuildInputs = [
+              pkgs.ruby
+              pkgs.git
+            ];
+            # The gemspec computes its file list with `git ls-files`, so give the
+            # sandboxed source copy a git index to enumerate.
+            buildPhase = ''
+              runHook preBuild
+              git init -q
+              git add -A
+              gem build errgonomic.gemspec
+              runHook postBuild
+            '';
+            nativeCheckInputs = [ gems ];
+            doCheck = true;
+            checkPhase = ''
+              runHook preCheck
+              export HOME="$TMPDIR"
+              export GEM_PATH="${gems}/${pkgs.ruby.gemPath}"
+              rake
+              runHook postCheck
+            '';
+            installPhase = ''
+              runHook preInstall
+              mkdir -p $out
+              cp errgonomic-${version}.gem $out/
+              runHook postInstall
+            '';
+          };
+        }
+      );
+
+      # Every package builds and its tests pass; `nix flake check` certifies it.
+      checks = self.packages;
+
       devShells = forAllSystems (
         { pkgs, ... }:
         let
-          inherit (pkgs) ruby bundix;
+          gems = gemEnvFor pkgs;
         in
         {
           default = pkgs.mkShell {
             buildInputs = [
-              ruby
-              bundix
-              (pkgs.bundlerEnv {
-                name = "errgonomic";
-                gemdir = ./.;
-                extraConfigPaths = [
-                  ./errgonomic.gemspec
-                  ./lib/errgonomic/version.rb
-                ];
-                postInstall = ''
-                  find . >&2
-                '';
-              })
+              pkgs.ruby
+              gems
             ];
+            env.GEM_PATH = "${gems}/${pkgs.ruby.gemPath}";
           };
         }
       );
-
     };
 }

data/gem-groups.json

@@ -0,0 +1 @@
+{"errgonomic":["default"],"yard":["development"],"yard-doctest":["development"],"activerecord":["development"],"minitest":["development"],"rails":["development"],"rake":["development"],"rspec":["development"],"rubocop":["development"],"rubocop-yard":["development"],"solargraph":["development"],"sqlite3":["development"],"concurrent-ruby":["default","development"],"drb":["development"],"prism":["development"],"activemodel":["development"],"activesupport":["development"],"base64":["development"],"bigdecimal":["development"],"connection_pool":["development"],"i18n":["development"],"json":["development"],"logger":["development"],"securerandom":["development"],"timeout":["development"],"tzinfo":["development"],"uri":["development"],"action_text-trix":["development"],"actioncable":["development"],"actionmailbox":["development"],"actionmailer":["development"],"actionpack":["development"],"actiontext":["development"],"actionview":["development"],"activejob":["development"],"activestorage":["development"],"builder":["development"],"bundler":["development"],"crass":["development"],"date":["development"],"erb":["development"],"erubi":["development"],"globalid":["development"],"io-console":["development"],"irb":["development"],"loofah":["development"],"mail":["development"],"marcel":["development"],"mini_mime":["development"],"net-imap":["development"],"net-pop":["development"],"net-protocol":["development"],"net-smtp":["development"],"nio4r":["development"],"nokogiri":["development"],"pp":["development"],"prettyprint":["development"],"psych":["development"],"racc":["development"],"rack":["development"],"rack-session":["development"],"rack-test":["development"],"rackup":["development"],"rails-dom-testing":["development"],"rails-html-sanitizer":["development"],"railties":["development"],"rdoc":["development"],"reline":["development"],"stringio":["development"],"thor":["development"],"tsort":["development"],"useragent":["development"],"websocket-driver":["development"],"websocket-extensions":["development"],"zeitwerk":["development"],"diff-lcs":["development"],"rspec-core":["development"],"rspec-expectations":["development"],"rspec-mocks":["development"],"rspec-support":["development"],"ast":["development"],"language_server-protocol":["development"],"lint_roller":["development"],"parallel":["development"],"parser":["development"],"rainbow":["development"],"regexp_parser":["development"],"rubocop-ast":["development"],"ruby-progressbar":["development"],"unicode-display_width":["development"],"unicode-emoji":["development"],"backport":["development"],"benchmark":["development"],"commander":["development"],"highline":["development"],"jaro_winkler":["development"],"kramdown":["development"],"kramdown-parser-gfm":["development"],"observer":["development"],"open3":["development"],"ostruct":["development"],"parlour":["development"],"rbs":["development"],"reverse_markdown":["development"],"rexml":["development"],"sorbet-runtime":["development"],"sord":["development"],"tilt":["development"],"yard-activesupport-concern":["development"],"yard-solargraph":["development"]}

data/lib/errgonomic/core_ext/array.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../option'
+require_relative '../optional_array'
+
+# Two additive lookups; no existing Array behavior changes, for the same
+# reasons given in core_ext/hash.rb.
+class Array
+  # Retrieve the element at an integer index, wrapped in an Option,
+  # following element presence as Rust's slice get does: an element holding
+  # nil is Some(nil); only an out-of-bounds index is None.
+  #
+  # @example
+  #   a = [:a, nil]
+  #   a.fetch_option(0) # => Some(:a)
+  #   a.fetch_option(1) # => Some(nil)
+  #   a.fetch_option(2) # => None()
+  def fetch_option(index)
+    unless index.is_a?(::Integer)
+      raise Errgonomic::TypeMismatchError,
+            "index must be an Integer, got #{index.class}"
+    end
+    return None() unless (-length...length).cover?(index)
+
+    Some(self[index])
+  end
+
+  # Wrap this array in an Errgonomic::OptionalArray view. The wrapper reads
+  # and writes this same array; use its to_a for a detached copy.
+  #
+  # @example
+  #   a = [:a].into_optional
+  #   a[0] # => Some(:a)
+  #   a[1] # => None()
+  def into_optional
+    Errgonomic::OptionalArray.new(self)
+  end
+end