enumbler 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 717637e70fa4a5c5b5419945258e2132e2fd0c5d6c9e88f983f17cc00aaabe55
-  data.tar.gz: b5a2a0d6c731fdf14fa260ceea6af15940ed146ee94c7adf6547f972d885dc00
+  metadata.gz: e565cc926b8cca7f06e64cc90503f5965003a3e5c60d1c2a5cd689ea690c8215
+  data.tar.gz: e2cfef7c22ed8ce2d51d706802c79ce1fc0b4abe8b3268aa634400051f9970b1
 SHA512:
-  metadata.gz: 1e13f79de97b243c0a914fda812722ffce084e36e15c9930e5f4ec5e6dc7c345a19909351c6da6eeb8113bf97d60eafd7aee8a80cf99ae829d9f929c8ce60c67
-  data.tar.gz: f0bfd2c79d944854af27b2b953c3fdbe7ae2e7d2e88b321d2c7332cff5fcc07f7342c2e4e6fb0be919fd9e377a7e1fce91d4c03cfb15d0de36995bb4d5527bc4
+  metadata.gz: 77c6de7fc4fbebc329e77ccee8ead1998a71e6539d45a218a1f018424a4a6e087869e0c04fc51d074f006fddfa32cf7e047e417e3b1c5706be822003029b432c
+  data.tar.gz: 8e30d49be482fc9fa3da561c134c93c8db1b8362f05c7dd83300e5e6db16b001c399382ed5c9fa3d96291ab232d4a28ac1d147bf8d7833294ece0ed98b3135e6

data/.github/workflows/ruby.yml

@@ -6,9 +6,18 @@ on:
     tags: ["*"]
   pull_request:
 
+# A new push to the same ref supersedes any in-flight run; cancel the stale
+# one rather than paying for both.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   rspec:
     runs-on: ubuntu-latest
+    # Typical matrix job is under 2 minutes; a hung job otherwise runs to
+    # GitHub's 6-hour default.
+    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
@@ -51,21 +60,34 @@ jobs:
 
     name: Publish Gem
     runs-on: ubuntu-latest
+    timeout-minutes: 10
 
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
 
+    # Publishes via RubyGems trusted publishing (OIDC) — no API key, and
+    # exempt from the account's OTP requirement.  The trusted publisher on
+    # rubygems.org is registered for this repo + this workflow filename.
+    # Uses configure-rubygems-credentials + a plain `gem push` rather than
+    # the release-gem action: that action runs `rake release`, which wants
+    # to git-push and create its own v-prefixed tag — this repo tags
+    # manually (bare version numbers) and this job runs on a detached HEAD.
+    permissions:
+      id-token: write
+
     steps:
     - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: 3.4
 
-    - name: Publish to RubyGems
+    - uses: rubygems/configure-rubygems-credentials@v2.1.0
+
+    - name: Build and push gem
       run: |
         gem build *.gemspec
         gem push *.gem
-      env:
-        GEM_HOST_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}}
 

data/AGENTS.md

@@ -5,7 +5,8 @@
 
 ## Running Checks
 - Use Bundler for all commands (`bundle exec`).
-- Lint changed Ruby files with `bundle exec rspec`.
+- Run tests with `bundle exec rspec`.
+- Lint changed Ruby files with `bundle exec rubocop`.
 
 ## Commit Guidelines
 - Keep commit messages concise and descriptive.

data/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Enumbler is a Ruby gem that provides database-backed enums for ActiveRecord: real foreign-key lookup tables that behave like `enum`s. It supports ActiveRecord/ActiveSupport >= 6.0, < 9 and Ruby >= 3.1.
+
+## Commands
+
+```bash
+bin/setup                                  # install dependencies
+bundle exec rspec                          # run all tests
+bundle exec rspec spec/enumbler_spec.rb:42 # run a single test by file:line
+bundle exec rubocop                        # lint (also runs as a lefthook pre-commit hook)
+```
+
+### Matrix testing
+
+CI tests Ruby 3.1–3.4 against Rails 6.0–8.0 using the `Gemfile.rails*` files. To reproduce locally:
+
+```bash
+BUNDLE_GEMFILE=Gemfile.rails7.2 bundle install
+BUNDLE_GEMFILE=Gemfile.rails7.2 bundle exec rspec
+```
+
+When changing dependencies, keep all `Gemfile.rails*` variants (and their lockfiles) in sync with the main `Gemfile`.
+
+### Branching & releasing
+
+Modified git flow (see README "Development"): feature branches off `develop`; releases go to `main` via `release/x.y.z` (or `hotfix/x.y.z` off `main`), then the tag is merged back into `develop`. A release is a bare version tag on `main` (no `v` prefix, e.g. `0.10.0`) matching `lib/enumbler/version.rb`; pushing the tag makes CI run the rspec matrix and publish the gem to rubygems.org.
+
+## Architecture
+
+The gem is four small files under `lib/enumbler/`, split across the two sides of the relationship:
+
+- **`lib/enumbler.rb`** (`Enumbler` module) — included in `ApplicationRecord`; gives *consuming* models `enumbled_to :color`, a `belongs_to` replacement. It defines class scopes (`House.color(:black)`), per-enum predicates (`house.black?`, `house.not_black?`, optionally prefixed), and db-free helper attributes (`house.color_label`, `color_enum`, `color_graphql_enum`).
+
+- **`lib/enumbler/enabler.rb`** (`Enumbler::Enabler`) — included in the *lookup* model (e.g. `Color`); provides the `enumble :black, 1, ...` DSL. Each call builds an `Enumble`, registers it in the class-level `@enumbles` collection, and metaprograms constants (`Color::BLACK`), class finders (`Color.black`, `Color.black(:label)`), and predicates — with conflict detection against ActiveRecord methods (modeled on `ActiveRecord::Enum`). Also holds all the `find_enumble(s)` / `ids_from_enumbler` lookup methods (in-memory, no db hit; bang variants raise `Enumbler::Error`) and `seed_the_enumbler(!)` for syncing the definitions into the database table.
+
+- **`lib/enumbler/enumble.rb`** (`Enumbler::Enumble`) — plain value object for one enum row (id, enum symbol, label, extra attributes). Equality is loose: two Enumbles are `==` if id **or** enum **or** label match (this is how duplicate definitions are caught).
+
+- **`lib/enumbler/collection.rb`** — an `Array` subclass with `method_missing` so `Color.enumbles.black` works.
+
+- **`lib/enumbler/core_ext/symbol/case_equality_operator.rb`** — patches `Symbol#===` so `case Color.black; when :black` works. It's a global core extension; be careful changing it.
+
+The label column defaults to `label` but can be remapped per-model with `enumbler_label_column_name :emotion`; internally `Enumble#label` always refers to the enumbler value regardless of the underlying column.
+
+## Tests
+
+Specs run against an in-memory SQLite database (`spec/support/establish_sqlite_connection.rb`); each spec file defines its own schema with `ActiveRecord::Schema.define` and DatabaseCleaner wraps each example in a transaction. `spec/enumbler_spec.rb` covers nearly everything and defines the shared test models (Color, House, Feeling). Rails-version-conditional behavior may need `BUNDLE_GEMFILE` runs to verify.
+
+## Style
+
+RuboCop enforces double-quoted strings, max line length 119, trailing commas in multiline literals, and `TargetRubyVersion: 3.4` — but code must still run on Ruby 3.1 (see the gemspec), so avoid 3.2+-only syntax.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
+    enumbler (0.11.0)
       activerecord (>= 6.0, < 9)
       activesupport (>= 6.0, < 9)
 

data/Gemfile.rails6.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
+    enumbler (0.11.0)
       activerecord (>= 6.0, < 9)
       activesupport (>= 6.0, < 9)
 
@@ -96,4 +96,4 @@ DEPENDENCIES
   sqlite3 (~> 1.6)
 
 BUNDLED WITH
-   2.4.12
+   2.6.9

data/Gemfile.rails6.1.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
-      activerecord (>= 5.2.3, < 7)
-      activesupport (>= 5.2.3, < 7)
+    enumbler (0.11.0)
+      activerecord (>= 6.0, < 9)
+      activesupport (>= 6.0, < 9)
 
 GEM
   remote: https://rubygems.org/
@@ -72,6 +72,7 @@ GEM
       parser (>= 2.7.1.5)
     ruby-progressbar (1.13.0)
     sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.8.0)
@@ -79,6 +80,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
   activemodel (= 6.1.7.10)
@@ -95,4 +97,4 @@ DEPENDENCIES
   sqlite3 (~> 1.6)
 
 BUNDLED WITH
-   2.4.12
+   2.6.9

data/Gemfile.rails7.0.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
-      activerecord (>= 5.2.3, < 8)
-      activesupport (>= 5.2.3, < 8)
+    enumbler (0.11.0)
+      activerecord (>= 6.0, < 9)
+      activesupport (>= 6.0, < 9)
 
 GEM
   remote: https://rubygems.org/
@@ -71,12 +71,14 @@ GEM
       parser (>= 2.7.1.5)
     ruby-progressbar (1.13.0)
     sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.8.0)
 
 PLATFORMS
   arm64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
   activemodel (= 7.0.8.7)
@@ -93,4 +95,4 @@ DEPENDENCIES
   sqlite3 (~> 1.6)
 
 BUNDLED WITH
-   2.4.12
+   2.6.9

data/Gemfile.rails7.1.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
-      activerecord (>= 5.2.3, < 8)
-      activesupport (>= 5.2.3, < 8)
+    enumbler (0.11.0)
+      activerecord (>= 6.0, < 9)
+      activesupport (>= 6.0, < 9)
 
 GEM
   remote: https://rubygems.org/
@@ -47,6 +47,7 @@ GEM
       concurrent-ruby (~> 1.0)
     logger (1.7.0)
     method_source (1.1.0)
+    mini_portile2 (2.8.9)
     minitest (5.25.5)
     mutex_m (0.3.0)
     parallel (1.27.0)
@@ -87,6 +88,8 @@ GEM
       parser (>= 2.7.1.5)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
+    sqlite3 (1.5.4)
+      mini_portile2 (~> 2.8.0)
     sqlite3 (1.5.4-arm64-darwin)
     timeout (0.4.3)
     tzinfo (2.0.6)
@@ -95,6 +98,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
   activemodel (= 7.1.5.1)
@@ -111,4 +115,4 @@ DEPENDENCIES
   sqlite3 (~> 1.5.0)
 
 BUNDLED WITH
-   2.4.12
+   2.6.9

data/Gemfile.rails7.2.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
-      activerecord (>= 5.2.3, < 8)
-      activesupport (>= 5.2.3, < 8)
+    enumbler (0.11.0)
+      activerecord (>= 6.0, < 9)
+      activesupport (>= 6.0, < 9)
 
 GEM
   remote: https://rubygems.org/
@@ -46,6 +46,7 @@ GEM
       concurrent-ruby (~> 1.0)
     logger (1.7.0)
     method_source (1.1.0)
+    mini_portile2 (2.8.9)
     minitest (5.25.5)
     parallel (1.27.0)
     parser (3.3.8.0)
@@ -85,6 +86,8 @@ GEM
       parser (>= 2.7.1.5)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
+    sqlite3 (1.5.4)
+      mini_portile2 (~> 2.8.0)
     sqlite3 (1.5.4-arm64-darwin)
     timeout (0.4.3)
     tzinfo (2.0.6)
@@ -93,6 +96,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
   activemodel (<= 8)
@@ -109,4 +113,4 @@ DEPENDENCIES
   sqlite3 (~> 1.5.0)
 
 BUNDLED WITH
-   2.4.12
+   2.6.9

data/Gemfile.rails8.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enumbler (0.10.0)
+    enumbler (0.11.0)
       activerecord (>= 6.0, < 9)
       activesupport (>= 6.0, < 9)
 
@@ -85,6 +85,7 @@ GEM
     ruby-progressbar (1.10.1)
     securerandom (0.4.1)
     sqlite3 (2.6.0-arm64-darwin)
+    sqlite3 (2.6.0-x86_64-linux-gnu)
     timeout (0.4.3)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -93,6 +94,7 @@ GEM
 
 PLATFORMS
   arm64-darwin
+  x86_64-linux
 
 DEPENDENCIES
   activemodel (>= 8)

data/README.md

@@ -162,11 +162,54 @@ when :blue, :purple
 end
 ```
 
+## Suppressing database warnings
+
+When an `enumble` defines extra attributes, the Enumbler verifies them against the model's table at class-load time.  If the table cannot be inspected — for example, while your test databases are dropped mid-way through a `rake parallel:setup` — it prints an `[Enumbler Warning]` for every affected model rather than raising.  If those warnings are just noise in your workflow, you can suppress them:
+
+```ruby
+Enumbler.suppress_database_warnings = true
+```
+
+Or set the environment variable `ENUMBLER_SUPPRESS_DATABASE_WARNINGS` to any non-empty value — handy for wrapping database reset commands:
+
+```bash
+ENUMBLER_SUPPRESS_DATABASE_WARNINGS=1 bundle exec rake parallel:setup
+```
+
+The Ruby-level setting, when assigned, takes precedence over the environment variable.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Branching (modified git flow)
+
+Day-to-day work follows git flow: feature/bug/chore branches come off `develop` and are merged back into `develop` via PR. Releases move `develop` into `main` through a `release/x.y.z` branch (or a `hotfix/x.y.z` branch off `main` for urgent fixes), and after tagging, the tag is merged back into `develop` so both branches share the release commit.
+
+### Releasing a New Version
+
+A release is triggered by pushing a **version tag** to GitHub: the `CI Matrix Testing` workflow runs the rspec matrix and, if green, the `Publish Gem` job builds the gem and pushes it to [rubygems.org](https://rubygems.org).
+
+Two things to know before tagging:
+
+1. The published version comes from `lib/enumbler/version.rb`, **not** the tag name — make sure they match (the tag is bare, no `v` prefix: `0.10.0`).
+2. RubyGems rejects duplicate versions, so every release needs a version bump.
+
+Steps:
+
+1. Bump `Enumbler::VERSION` in `lib/enumbler/version.rb` (and run `bundle install` so the lockfiles pick it up) on a `release/x.y.z` branch off `develop` (or `hotfix/x.y.z` off `main`).
+2. Merge the branch into `main`, then tag the release commit:
+
+   ```bash
+   git checkout main && git pull
+   git tag -a 0.10.0 -m "Release 0.10.0"
+   git push origin main 0.10.0
+   ```
+
+3. Watch the `CI Matrix Testing` workflow on the tag: when the publish job is green, confirm the new version on [rubygems.org](https://rubygems.org/gems/enumbler).
+4. Merge the tag back into `develop`: `git checkout develop && git merge 0.10.0 && git push`.
 
 ### Matrix testing
 

data/lib/enumbler/enabler.rb

@@ -462,12 +462,16 @@ module Enumbler
         raise Enumbler::Error,
           "The model #{self} does not support the attribute(s): #{unsupported_attrs.keys.map(&:to_s).to_sentence}"
       rescue ActiveRecord::PendingMigrationError
+        return if Enumbler.suppress_database_warnings?
+
         warn "[Enumbler Warning] => The model #{self} does not currently support the attribute(s): " \
              "#{unsupported_attrs.keys.map(&:to_s).to_sentence}. " \
              "You have a pending migration which hopefully would remedy this! " \
              "If not, you need to add a migration for this attibrute or " \
              "remove it from the Enumbler."
       rescue ActiveRecord::StatementInvalid
+        return if Enumbler.suppress_database_warnings?
+
         warn "[Enumbler Warning] => Unable to find a table for #{self}." \
              "This is to be expected if there is a pending migration;  " \
              "however, if there is not then something is amiss."

data/lib/enumbler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Enumbler
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/enumbler.rb

@@ -17,6 +17,26 @@ module Enumbler
   # An error raised by the Enumbler.
   class Error < StandardError; end
 
+  class << self
+    attr_writer :suppress_database_warnings
+
+    # Suppress the boot-time `[Enumbler Warning]` messages emitted when a
+    # model's table or attributes cannot be verified (e.g., while the database
+    # is dropped during a test database reset).  Enable by setting
+    # `Enumbler.suppress_database_warnings = true` or by setting the
+    # environment variable `ENUMBLER_SUPPRESS_DATABASE_WARNINGS` to any
+    # non-empty value.  The Ruby-level setting, when assigned, wins over the
+    # environment variable.
+    # @return [Boolean]
+    def suppress_database_warnings?
+      if @suppress_database_warnings.nil?
+        ENV["ENUMBLER_SUPPRESS_DATABASE_WARNINGS"].present?
+      else
+        @suppress_database_warnings
+      end
+    end
+  end
+
   # Include these ClassMethods in your base ApplicationRecord model to bestow
   # any of your models with the ability to be connected to an Enumbled relation
   # in the same way you would use `belongs_to` now you use `enumbled_to`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumbler
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Damon Timm
@@ -63,6 +63,7 @@ files:
 - ".ruby-version"
 - ".solargraph.yml"
 - AGENTS.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - Gemfile.rails6.0
@@ -114,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Enums are terrific, but lack integrity.  Let's add some!
 test_files: []