inquiry_attrs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 615f0028c78433e7cd13171ce70724af8e5c535c9bc3ddac9127b6121cec6cc2
+  data.tar.gz: 95d371d0ee8d484e6f80b353a62dc49c92d19df63eeb08c35abaccccacb1738f
+SHA512:
+  metadata.gz: f1327f64dc6cc2aec05aa5ae6b97619ba1bfa95cfe394633c44f7e7ca67a8d2fc4da5cb9cd58c114b234dde4eef3e5db973a35ed19e9678c23befd188b4d4b5b
+  data.tar.gz: a4ce3e81aab2b778aff6abf4c8532e5ed74765f457b49efc9a90134bf803d94f4396e5a3706875b73fa32159634e816779f4ad973b365f0ea105bc7ecd4bb8e5

data/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md — inquiry_attrs
+
+This file is the primary context document for AI agents and LLMs working on
+this gem. Read it fully before making any changes.
+
+---
+
+## What this gem does
+
+`inquiry_attrs` adds predicate-style inquiry methods to Rails model attributes.
+
+```ruby
+# Without inquiry_attrs
+user.status == 'active'
+
+# With inquiry_attrs
+user.status.active?   # => true
+user.status.inactive? # => false
+user.status.nil?      # => true when blank — never raises NoMethodError
+```
+
+It is a **Rails-only** gem (depends on `activesupport >= 7`, `activerecord >= 7`,
+`railties >= 7`). All Rails APIs (`blank?`, `ActiveSupport::Concern`,
+`ActiveSupport.on_load`, `String#inquiry`) are available and should be preferred
+over reinventing them.
+
+---
+
+## File map
+
+```
+lib/
+  inquiry_attrs.rb                  # Entry point — requires everything, loads Railtie
+  inquiry_attrs/
+    version.rb                      # VERSION = '1.0.0'
+    nil_inquiry.rb                  # NilInquiry::INSTANCE — frozen singleton for blank values
+    symbol_inquiry.rb               # SymbolInquiry < SimpleDelegator — wraps Symbol attrs
+    concern.rb                      # Concern — adds .inquirer class macro
+    installer.rb                    # Installer — file-system logic for the rake tasks
+    railtie.rb                      # Railtie — wires rake tasks into the host Rails app
+  tasks/
+    inquiry_attrs.rake              # Shell rake tasks (install / uninstall)
+
+test/
+  test_helper.rb                    # Minitest setup + SQLite in-memory AR connection
+  inquiry_attrs/
+    nil_inquiry_test.rb             # Unit tests for NilInquiry
+    symbol_inquiry_test.rb          # Unit tests for SymbolInquiry
+    concern_test.rb                 # Integration tests: AR, StoreModel, plain Ruby, Symbol
+    install_task_test.rb            # Unit tests for Installer (no Rake machinery needed)
+
+llms/
+  overview.md                       # Architecture deep-dive for LLMs
+  usage.md                          # Common patterns and recipes
+
+AGENTS.md                           # This file
+README.md
+CHANGELOG.md
+```
+
+---
+
+## How to run tests
+
+```bash
+# Full suite (preferred)
+bundle exec rake
+
+# Single file
+bundle exec ruby -Ilib -Itest test/inquiry_attrs/concern_test.rb
+
+# Single test by name
+bundle exec ruby -Ilib -Itest test/inquiry_attrs/concern_test.rb \
+  --name test_matching_predicate_returns_true
+```
+
+Tests use **Minitest** (`minitest-reporters` with SpecReporter). There is no
+Rails application — ActiveRecord is wired directly to an in-memory SQLite
+database in `test/test_helper.rb`.
+
+---
+
+## Architecture — the three return types
+
+`.inquirer :attr` overrides the original attribute reader and returns one of:
+
+| Raw value | Return type | Key behaviour |
+|---|---|---|
+| `nil` or any `blank?` value | `NilInquiry::INSTANCE` | `nil?` true, all predicates false |
+| `Symbol` | `SymbolInquiry.new(raw)` | predicate matches symbol name |
+| Everything else | `raw.to_s.inquiry` → `ActiveSupport::StringInquirer` | standard Rails inquiry |
+
+---
+
+## Architecture — the `instance_method` capture pattern
+
+This is the **most important** design decision in `concern.rb`:
+
+```ruby
+def inquirer(*attrs)
+  attrs.each do |attr|
+    original = method_defined?(attr) ? instance_method(attr) : nil
+
+    # Remove the method from this class's own table before redefining it to
+    # silence Ruby's "method redefined" warning. The original is already
+    # safely captured in `original` above.
+    remove_method(attr) if instance_methods(false).include?(attr)
+
+    define_method(attr) do
+      raw = original ? original.bind_call(self) : super()
+      # … return type logic
+    end
+  end
+end
+```
+
+**Why capture + remove + redefine:** `inquirer :status` must replace the original
+reader. Both AR and StoreModel define their readers via `define_method`; calling
+`define_method` again on the same method triggers Ruby's "method redefined"
+warning. Calling `remove_method` first clears it from the class's own method
+table so the subsequent `define_method` is seen as a fresh definition.
+`remove_method` is safe here because it only removes the method from *this*
+class, not from superclasses, and the original is already preserved in `original`.
+
+**Consequence:** `inquirer` must always be called **after** the attribute reader
+is defined. Violating this order produces a `NoMethodError` in plain Ruby classes
+(AR and StoreModel define readers early enough for this not to matter).
+
+---
+
+## Architecture — Railtie / rake task / Installer split
+
+```
+Rails app                    inquiry_attrs gem
+─────────────────            ──────────────────────────────────────────────────
+Gemfile ──requires──▶  lib/inquiry_attrs.rb
+                            └── lib/inquiry_attrs/railtie.rb  (only if Rails::Railtie defined)
+                                    └── rake_tasks { load 'lib/tasks/inquiry_attrs.rake' }
+
+$ rails inquiry_attrs:install
+                       ──▶  task :install
+                                └── InquiryAttrs::Installer.install!(Rails.root)
+                                        └── writes config/initializers/inquiry_attrs.rb
+```
+
+**Why Installer is a separate class:** The rake task calls `Rails.root`, which is
+unavailable in tests without a full Rails boot. By pushing all logic into
+`Installer.install!(root)`, tests can pass any `Pathname` as the root — no
+stubbing, no Rake DSL needed.
+
+**The generated initializer** contains:
+
+```ruby
+ActiveSupport.on_load(:active_record) do
+  include InquiryAttrs::Concern
+end
+```
+
+This is the **only** place where `on_load` is used. The gem itself does not
+auto-include anything on load — that would be implicit and hard to audit.
+
+---
+
+## Key classes — quick reference
+
+### `NilInquiry` (`lib/inquiry_attrs/nil_inquiry.rb`)
+
+- Frozen singleton: `NilInquiry::INSTANCE`
+- `nil?` → `true`; `blank?` → `true`; `present?` → `false`
+- Any `?`-method → `false` via `method_missing`
+- `== nil`, `== ""`, `== INSTANCE` → `true`
+- Implements `to_s` / `to_str` / `inspect`
+
+### `SymbolInquiry` (`lib/inquiry_attrs/symbol_inquiry.rb`)
+
+- Subclasses `SimpleDelegator`, wraps a `Symbol`
+- Raises `ArgumentError` for non-Symbol; unwraps nested `SymbolInquiry`
+- `?`-method returns `true` iff `sym.to_s == method_name.delete_suffix('?')`
+- `==` accepts `Symbol`, `String`, or `SymbolInquiry`
+- `is_a?(Symbol)` and `kind_of?(Symbol)` → `true`
+- `nil?` → `false`; `blank?` → `false`; `present?` → `true`
+
+### `Concern` (`lib/inquiry_attrs/concern.rb`)
+
+- `extend ActiveSupport::Concern`
+- Single class method: `inquirer(*attrs)` — see `instance_method` capture pattern above
+- Uses `blank?` (Rails) instead of `nil? || == ""`
+
+### `Installer` (`lib/inquiry_attrs/installer.rb`)
+
+- `Installer::INITIALIZER_PATH` — `Pathname` relative path to the initializer
+- `Installer::INITIALIZER_CONTENT` — the exact string written to disk
+- `Installer.install!(rails_root)` → `:created` or `:skipped`
+- `Installer.uninstall!(rails_root)` → `:removed` or `:skipped`
+- Accepts `Pathname` or `String` as `rails_root`
+
+---
+
+## Adding a new feature — checklist
+
+1. **Write the test first** in the appropriate `test/inquiry_attrs/*_test.rb` file.
+2. Implement in `lib/inquiry_attrs/`.
+3. If the feature touches `Installer` (file operations), test via `InstallerTest`
+   passing a `Dir.mktmpdir` path — never stub `Rails.root`.
+4. If the feature is a new public API, document it in `llms/overview.md` and
+   `llms/usage.md` and update `README.md`.
+5. Run the full test suite and confirm 0 failures.
+6. Update `CHANGELOG.md`.
+
+---
+
+## Things to never do
+
+| Don't | Why |
+|---|---|
+| Add `on_load` back to `lib/inquiry_attrs.rb` | Makes the gem implicitly modify every AR model; hard to audit |
+| Broaden the `rescue` in `concern.rb` | Swallows real errors in attribute readers |
+| Call `inquirer` before `attr_accessor` in plain Ruby | `instance_method` capture returns `nil`; reader will be `nil` |
+| Stub `Rails.root` in tests | Use `Installer.install!(tmpdir)` instead |
+| Add a dependency on anything outside ActiveSupport/ActiveRecord/Railties | This is a Rails gem; Rails is already the dependency |
+| Introduce allocation inside the hot path (e.g. `String.new.extend(...)`) | `NilInquiry::INSTANCE` is a frozen singleton for a reason |
+
+---
+
+## Dependencies
+
+| Gem | Version | Why |
+|---|---|---|
+| `activesupport` | `>= 7.0` | `Concern`, `blank?`, `String#inquiry`, `on_load` |
+| `activerecord` | `>= 7.0` | AR integration (attr readers, `on_load` hook) |
+| `railties` | `>= 7.0` | `Rails::Railtie` for exposing rake tasks |
+| `sqlite3` | dev only | In-memory DB for AR tests |
+| `store_model` | dev only | Integration tests for StoreModel |
+| `minitest` + `minitest-reporters` | dev only | Test framework |
+
+---
+
+## Test conventions
+
+- Use `Minitest::Test` (not `ActiveSupport::TestCase`)
+- AR schema is created in `setup` with `force: true` and dropped in `teardown`
+- `InstallerTest` uses `Dir.mktmpdir` — always clean up in `teardown`
+- `assert` / `refute` preferred over `assert_equal true/false`
+- Group related tests with comment banners: `# ── install! ── #`
+- Test method names describe the exact behaviour: `test_install_skips_when_initializer_already_exists`

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [1.0.0] — 2026-02-27
+
+### Added
+- `InquiryAttrs::Concern` with `.inquirer(*attrs)` class macro
+- `InquiryAttrs::SymbolInquiry` — predicate wrapper for Symbol attributes
+- `InquiryAttrs::NilInquiry::INSTANCE` — frozen singleton for blank/nil attributes
+- Auto-include into `ActiveRecord::Base` via `ActiveSupport.on_load(:active_record)`
+- Support for StoreModel and plain Ruby classes via explicit `include`
+- LLM context files in `llms/`

data/CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md — inquiry_attrs
+
+## Start here
+
+Before writing any code, read these files in order:
+
+1. **@AGENTS.md** — architecture, design decisions, guardrails, test conventions
+2. **@llms/overview.md** — class responsibilities and internal design notes
+3. **@llms/usage.md** — common patterns and recipes
+
+---
+
+## Project context
+
+| | |
+|---|---|
+| **Gem name** | `inquiry_attrs` |
+| **Type** | Rails gem (Ruby only, no frontend) |
+| **Ruby** | ≥ 3.0 |
+| **Rails deps** | `activesupport`, `activerecord`, `railties` — all ≥ 7.0 |
+| **Test framework** | Minitest (`minitest-reporters`, SpecReporter) |
+| **Database** | SQLite in-memory (tests only) |
+
+---
+
+## Running tests
+
+```bash
+# Full suite (preferred)
+bundle exec rake
+
+# Full suite (explicit)
+bundle exec rake test
+
+# Single file
+bundle exec ruby -Ilib -Itest test/inquiry_attrs/concern_test.rb
+
+# Single test by name
+bundle exec ruby -Ilib -Itest test/inquiry_attrs/concern_test.rb \
+  --name test_matching_predicate_returns_true
+```
+
+---
+
+## Key files — one-line each
+
+```
+lib/inquiry_attrs/nil_inquiry.rb    # NilInquiry::INSTANCE — frozen singleton for blank values
+lib/inquiry_attrs/symbol_inquiry.rb # SymbolInquiry < SimpleDelegator — wraps Symbol attrs
+lib/inquiry_attrs/concern.rb        # .inquirer macro — instance_method capture pattern
+lib/inquiry_attrs/installer.rb      # Installer.install!/uninstall! — file-system logic
+lib/inquiry_attrs/railtie.rb        # loads rake tasks into the host Rails app
+lib/tasks/inquiry_attrs.rake        # rails inquiry_attrs:install / :uninstall
+test/test_helper.rb                 # Minitest setup + SQLite + on_load simulation
+```
+
+---
+
+## Code style
+
+Follow **@~/.agent-os/standards/code-style.md** and **@~/.agent-os/standards/best-practices.md**.
+
+Key rules that apply to this gem:
+
+- 2-space indentation, no tabs
+- Single quotes for strings; double quotes only for interpolation
+- `snake_case` methods/variables, `PascalCase` classes, `UPPER_SNAKE_CASE` constants
+- Comment the *why*, not the *what*; never remove existing comments unless removing the associated code
+- Keep it simple — fewest lines possible, no over-engineering
+
+---
+
+## Workflow
+
+### Fixing a bug or adding a feature
+
+1. Read **@AGENTS.md** → section "Adding a new feature — checklist"
+2. Write the failing test first
+3. Implement the fix
+4. Run the full suite — must be 0 failures before committing
+
+### Testing the rake task
+
+The rake tasks are thin shells over `InquiryAttrs::Installer`. Test `Installer`
+directly — pass a `Dir.mktmpdir` path as `rails_root`. Never stub `Rails.root`.
+
+```ruby
+def test_something
+  Dir.mktmpdir do |tmpdir|
+    root = Pathname.new(tmpdir)
+    FileUtils.mkdir_p(root.join('config', 'initializers'))
+    result = InquiryAttrs::Installer.install!(root)
+    assert_equal :created, result
+  end
+end
+```
+
+### Building the gem
+
+```bash
+gem build inquiry_attrs.gemspec
+```
+
+---
+
+## Hard rules (from @AGENTS.md)
+
+- **Never** add `ActiveSupport.on_load` back to `lib/inquiry_attrs.rb` — the
+  on_load lives only in the generated initializer
+- **Never** call `inquirer` before `attr_accessor` in plain Ruby classes
+- **Never** broaden the `rescue` in `concern.rb`
+- **Never** stub `Rails.root` in tests — use `Installer.install!(tmpdir)` instead

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,186 @@
+# inquiry_attrs
+
+Predicate-style inquiry methods for Rails model attributes.
+
+Instead of comparing strings:
+
+```ruby
+user.status == 'active'
+user.role == 'admin'
+```
+
+Write expressive predicates:
+
+```ruby
+user.status.active?
+user.role.admin?
+```
+
+Nil/blank attributes safely return `false` for every predicate — no more
+`NoMethodError` on nil.
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'inquiry_attrs'
+```
+
+---
+
+## Quick start
+
+### ActiveRecord — zero configuration
+
+`inquiry_attrs` auto-includes itself into every `ActiveRecord::Base` subclass
+via `ActiveSupport.on_load(:active_record)`. Just call `.inquirer` in any model:
+
+```ruby
+class User < ApplicationRecord
+  inquirer :status, :kind
+end
+
+user = User.new(status: "active", kind: "admin")
+user.status.active?   # => true
+user.status.inactive? # => false
+user.kind.admin?      # => true
+user.kind.user?       # => false
+```
+
+### Nil / blank attributes
+
+```ruby
+user = User.new(status: nil)
+
+user.status.nil?     # => true
+user.status.active?  # => false   ← no NoMethodError!
+user.status == nil   # => true
+```
+
+### String comparison and String methods still work
+
+```ruby
+user.status            # => "active"
+user.status == 'active'           # => true
+user.status.include?('act')       # => true
+user.status.upcase                # => "ACTIVE"
+```
+
+---
+
+## StoreModel
+
+Include `InquiryAttrs::Concern` explicitly for non-AR classes:
+
+```ruby
+class ShippingAddress
+  include StoreModel::Model
+  include InquiryAttrs::Concern
+
+  attribute :kind, :string   # "shipping", "billing", "return"
+  inquirer  :kind
+end
+
+address = ShippingAddress.new(kind: "billing")
+address.kind.billing?   # => true
+address.kind.shipping?  # => false
+```
+
+---
+
+## Plain Ruby
+
+```ruby
+class Subscription
+  include InquiryAttrs::Concern
+
+  attr_accessor :plan, :state
+
+  def initialize(plan:, state: nil)
+    @plan  = plan
+    @state = state
+  end
+
+  # Call inquirer AFTER attr_accessor — the original reader must exist first.
+  inquirer :plan, :state
+end
+
+sub = Subscription.new(plan: 'enterprise')
+sub.plan.enterprise?  # => true
+sub.state.nil?        # => true
+```
+
+---
+
+## How it works
+
+`.inquirer :attr` wraps the original attribute reader and returns one of three
+objects based on the raw value:
+
+| Raw value | Return type | Key behaviour |
+|---|---|---|
+| `nil` or any blank value | `InquiryAttrs::NilInquiry::INSTANCE` | `nil?` → `true`, all predicates → `false` |
+| `Symbol` | `InquiryAttrs::SymbolInquiry` | `:active.active?` → `true` |
+| Any other string | `ActiveSupport::StringInquirer` | Standard Rails inquiry |
+
+### `InquiryAttrs::NilInquiry`
+
+A frozen singleton returned for blank attributes. Every `?`-method returns
+`false`; behaves like `nil` in comparisons and `blank?` checks.
+
+```ruby
+ni = InquiryAttrs::NilInquiry::INSTANCE
+ni.nil?       # => true
+ni.active?    # => false
+ni == nil     # => true
+ni.blank?     # => true
+```
+
+### `InquiryAttrs::SymbolInquiry`
+
+Wraps a Symbol with predicate methods; compares equal to both the symbol and
+its string equivalent.
+
+```ruby
+si = InquiryAttrs::SymbolInquiry.new(:active)
+si.active?         # => true
+si == :active      # => true
+si == 'active'     # => true
+si.is_a?(Symbol)   # => true
+si.to_s            # => "active"
+```
+
+---
+
+## API
+
+### `InquiryAttrs::Concern`
+
+Auto-included into `ActiveRecord::Base`. Include manually in other classes.
+
+### `.inquirer(*attribute_names)`
+
+```ruby
+inquirer :status                         # single attribute
+inquirer :status, :role, :plan           # multiple attributes
+inquirer :status, only: :show            # passes options to before_action style macros (AR scoped)
+```
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec ruby -Ilib -Itest test/inquiry_attrs/nil_inquiry_test.rb \
+                                test/inquiry_attrs/symbol_inquiry_test.rb \
+                                test/inquiry_attrs/concern_test.rb
+```
+
+---
+
+## License
+
+MIT

data/lib/inquiry_attrs/concern.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  # +ActiveSupport::Concern+ that adds the +.inquirer+ macro to any class.
+  #
+  # For ActiveRecord models this is automatically included via
+  # +ActiveSupport.on_load(:active_record)+ — no explicit include needed:
+  #
+  #   class User < ApplicationRecord
+  #     inquirer :status, :role
+  #   end
+  #
+  # For StoreModel, plain Ruby, or any other class, include it manually:
+  #
+  #   class Address
+  #     include StoreModel::Model
+  #     include InquiryAttrs::Concern
+  #
+  #     attribute :kind, :string
+  #     inquirer  :kind
+  #   end
+  #
+  module Concern
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Wraps the named attribute readers with inquiry behaviour.
+      #
+      # Returns one of three objects depending on the raw value:
+      #
+      # * +InquiryAttrs::NilInquiry::INSTANCE+ — when the value is +blank?+
+      # * +InquiryAttrs::SymbolInquiry+         — when the value is a +Symbol+
+      # * +ActiveSupport::StringInquirer+        — for any other present value
+      #   (identical to calling +value.inquiry+ on a string)
+      #
+      # @param attrs [Array<Symbol>] attribute reader names to wrap
+      def inquirer(*attrs)
+        attrs.each do |attr|
+          # Capture the original reader before we overwrite it.
+          # This covers attr_accessor, StoreModel, and AR attribute methods
+          # that are already defined by the time inquirer is called.
+          original = method_defined?(attr) ? instance_method(attr) : nil
+
+          # Remove the method from this class's own table (not from superclasses)
+          # so the define_method below is seen as a fresh definition rather than
+          # a redefinition — silencing Ruby's "method redefined" warning.
+          remove_method(attr) if instance_methods(false).include?(attr)
+
+          define_method(attr) do
+            raw = if original
+                    original.bind_call(self)
+                  else
+                    # Lazy AR attribute methods or Dry::Struct hash access.
+                    begin
+                      super()
+                    rescue NoMethodError
+                      begin
+                        self[attr]
+                      rescue NoMethodError, TypeError
+                        nil
+                      end
+                    end
+                  end
+
+            if raw.blank?
+              NilInquiry::INSTANCE
+            elsif raw.is_a?(Symbol)
+              SymbolInquiry.new(raw)
+            else
+              raw.to_s.inquiry
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inquiry_attrs/installer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  # Manages the lifecycle of the inquiry_attrs initializer inside a Rails app.
+  #
+  # This class holds all file-system logic so it can be unit-tested without
+  # requiring a full Rails boot or Rake DSL.  The rake tasks are thin shells
+  # that delegate here.
+  #
+  # @example From a Rake task (or Rails generator):
+  #   InquiryAttrs::Installer.install!(Rails.root)
+  #   InquiryAttrs::Installer.uninstall!(Rails.root)
+  #
+  class Installer
+    INITIALIZER_PATH = Pathname.new('config/initializers/inquiry_attrs.rb')
+
+    INITIALIZER_CONTENT = <<~RUBY
+      # frozen_string_literal: true
+
+      # Auto-include InquiryAttrs::Concern into every ActiveRecord model so that
+      # the .inquirer macro is available without an explicit include in each class.
+      #
+      # Generated by: rails inquiry_attrs:install
+      #
+      # To opt out of auto-include, remove this file and add
+      #   include InquiryAttrs::Concern
+      # to whichever models need it.
+      ActiveSupport.on_load(:active_record) do
+        include InquiryAttrs::Concern
+      end
+    RUBY
+
+    # Write the initializer to +rails_root/config/initializers/inquiry_attrs.rb+.
+    #
+    # @param rails_root [Pathname, String] the root directory of the Rails app
+    # @return [:created, :skipped]
+    def self.install!(rails_root)
+      destination = Pathname.new(rails_root).join(INITIALIZER_PATH)
+
+      return :skipped if destination.exist?
+
+      destination.write(INITIALIZER_CONTENT)
+      :created
+    end
+
+    # Remove the initializer if it exists.
+    #
+    # @param rails_root [Pathname, String]
+    # @return [:removed, :skipped]
+    def self.uninstall!(rails_root)
+      destination = Pathname.new(rails_root).join(INITIALIZER_PATH)
+
+      return :skipped unless destination.exist?
+
+      destination.delete
+      :removed
+    end
+  end
+end

data/lib/inquiry_attrs/nil_inquiry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  # Returned by an inquired attribute when its raw value is blank.
+  #
+  # Every +?+ predicate returns +false+, so callers never receive a
+  # +NoMethodError+ and nil comparisons work naturally.
+  #
+  #   user.status         # => InquiryAttrs::NilInquiry::INSTANCE  (when nil/blank)
+  #   user.status.nil?    # => true
+  #   user.status.active? # => false
+  #   user.status == nil  # => true
+  #
+  class NilInquiry
+    INSTANCE = new.freeze
+
+    # Any +?+ method returns false — no NoMethodError on blank attributes.
+    def method_missing(method_name, *_args, &_block)
+      return false if method_name.to_s.end_with?('?')
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?('?') || super
+    end
+
+    def nil? = true
+    def blank? = true
+    def empty? = true
+    def present? = false
+    def to_s = ''
+    def to_str = ''
+    def inspect = 'nil'
+
+    def ==(other)
+      other.nil? || other == '' || other.equal?(INSTANCE)
+    end
+  end
+end

data/lib/inquiry_attrs/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  class Railtie < Rails::Railtie
+    railtie_name :inquiry_attrs
+
+    # Expose `rails inquiry_attrs:install` to the host application.
+    rake_tasks do
+      load File.expand_path('../../tasks/inquiry_attrs.rake', __dir__)
+    end
+  end
+end

data/lib/inquiry_attrs/symbol_inquiry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  # Wraps a Symbol to provide the same predicate interface as
+  # +ActiveSupport::StringInquirer+.
+  #
+  #   inquiry = SymbolInquiry.new(:active)
+  #   inquiry.active?      # => true
+  #   inquiry.inactive?    # => false
+  #   inquiry == :active   # => true
+  #   inquiry == 'active'  # => true
+  #   inquiry.is_a?(Symbol) # => true
+  #
+  class SymbolInquiry < SimpleDelegator
+    # @param sym [Symbol]
+    # @raise [ArgumentError] if the argument is not a Symbol
+    def initialize(sym)
+      raise ArgumentError, "Must be a Symbol, got #{sym.class}" unless sym.is_a?(Symbol)
+
+      super(sym.is_a?(SymbolInquiry) ? sym.__getobj__ : sym)
+    end
+
+    def method_missing(method_name, *_args, &_block)
+      if method_name.to_s.end_with?('?')
+        __getobj__.to_s == method_name.to_s.delete_suffix('?')
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?('?') || super
+    end
+
+    # Compares against Symbol, String, or another SymbolInquiry.
+    def ==(other)
+      case other
+      when SymbolInquiry then __getobj__ == other.__getobj__
+      when Symbol        then __getobj__ == other
+      when String        then __getobj__.to_s == other
+      else false
+      end
+    end
+
+    def is_a?(klass)    = klass == Symbol || super
+    alias kind_of? is_a?
+
+    def nil?    = false
+    def blank?  = false
+    def present? = true
+    def to_s    = __getobj__.to_s
+    def to_sym  = __getobj__
+    def inspect = ":#{__getobj__}"
+  end
+end

data/lib/inquiry_attrs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module InquiryAttrs
+  VERSION = '1.0.0'
+end

data/lib/inquiry_attrs.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/concern'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/string/inquiry'
+
+require_relative 'inquiry_attrs/version'
+require_relative 'inquiry_attrs/nil_inquiry'
+require_relative 'inquiry_attrs/symbol_inquiry'
+require_relative 'inquiry_attrs/concern'
+require_relative 'inquiry_attrs/installer'
+
+# InquiryAttrs adds predicate-style inquiry methods to Rails model attributes.
+#
+# Instead of comparing strings:
+#
+#   user.status == 'active'
+#
+# Write expressive predicates:
+#
+#   user.status.active?
+#
+# Nil/blank values safely return +false+ for all predicates — no more
+# +NoMethodError+ on nil.
+#
+# Run the install task to wire the gem into your Rails app:
+#
+#   rails inquiry_attrs:install
+#
+# That creates +config/initializers/inquiry_attrs.rb+ which calls
+# +ActiveSupport.on_load(:active_record)+ so that every ActiveRecord model
+# gets the +.inquirer+ macro with no explicit include.
+#
+# For StoreModel or plain Ruby classes, include the concern manually:
+#
+#   class ShippingAddress
+#     include StoreModel::Model
+#     include InquiryAttrs::Concern
+#
+#     attribute :kind, :string
+#     inquirer  :kind
+#   end
+#
+module InquiryAttrs
+end
+
+# Register the Railtie when running inside a Rails application.
+# The Railtie exposes the `rails inquiry_attrs:install` rake task.
+require 'inquiry_attrs/railtie' if defined?(Rails::Railtie)

data/lib/tasks/inquiry_attrs.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'inquiry_attrs/installer'
+
+namespace :inquiry_attrs do
+  INITIALIZER_RELATIVE = InquiryAttrs::Installer::INITIALIZER_PATH.to_s
+
+  desc 'Install an initializer that auto-includes InquiryAttrs::Concern into ActiveRecord'
+  task :install do
+    result = InquiryAttrs::Installer.install!(Rails.root)
+
+    case result
+    when :created then printf "  %-10s %s\n", 'create', INITIALIZER_RELATIVE
+    when :skipped then printf "  %-10s %s\n", 'skip',   "#{INITIALIZER_RELATIVE} already exists"
+    end
+  end
+
+  desc 'Remove the inquiry_attrs initializer'
+  task :uninstall do
+    result = InquiryAttrs::Installer.uninstall!(Rails.root)
+
+    case result
+    when :removed then printf "  %-10s %s\n", 'remove', INITIALIZER_RELATIVE
+    when :skipped then printf "  %-10s %s\n", 'skip',   "#{INITIALIZER_RELATIVE} not found"
+    end
+  end
+end

data/llms/overview.md

@@ -0,0 +1,129 @@
+# inquiry_attrs — LLM Context Overview
+
+> Load this file before modifying or extending the gem.
+
+## Purpose
+
+`inquiry_attrs` adds predicate-style inquiry methods to Rails model attributes.
+It is a Rails-only gem (depends on ActiveSupport ≥ 7.0 and ActiveRecord ≥ 7.0).
+
+## File map
+
+```
+lib/
+  inquiry_attrs.rb                 # Entry point — requires everything, fires on_load hook
+  inquiry_attrs/
+    version.rb                     # VERSION constant
+    nil_inquiry.rb                 # NilInquiry::INSTANCE — returned for blank values
+    symbol_inquiry.rb              # SymbolInquiry — wraps Symbol attributes
+    concern.rb                     # Concern — provides .inquirer class macro
+test/
+  test_helper.rb                   # Minitest setup, SQLite in-memory AR connection
+  inquiry_attrs/
+    nil_inquiry_test.rb
+    symbol_inquiry_test.rb
+    concern_test.rb                # Integration: AR, StoreModel, plain Ruby, Symbol attrs
+llms/
+  overview.md                      # This file
+  usage.md                         # Common patterns and recipes
+```
+
+## Public surface
+
+### Auto-include for ActiveRecord
+
+```ruby
+# lib/inquiry_attrs.rb
+ActiveSupport.on_load(:active_record) do
+  include InquiryAttrs::Concern
+end
+```
+
+This fires once when ActiveRecord is first loaded, so every
+`ApplicationRecord` subclass automatically has access to `.inquirer` — no
+explicit `include` needed in AR models.
+
+### `InquiryAttrs::Concern` (opt-in for non-AR classes)
+
+```ruby
+include InquiryAttrs::Concern   # adds .inquirer class method
+```
+
+### `.inquirer(*attrs)` — the only public class-level API
+
+```ruby
+inquirer :status                 # wraps :status reader
+inquirer :status, :role, :plan   # wraps multiple readers at once
+```
+
+## Return type decision table
+
+| Raw value (from original reader) | Return type |
+|---|---|
+| `nil`, `""`, or any `blank?` value | `InquiryAttrs::NilInquiry::INSTANCE` |
+| `Symbol` | `InquiryAttrs::SymbolInquiry.new(raw)` |
+| Any other string | `raw.to_s.inquiry` → `ActiveSupport::StringInquirer` |
+
+## Class responsibilities
+
+### `InquiryAttrs::NilInquiry`
+
+- Frozen singleton (`INSTANCE`)
+- `nil?` → `true`; `blank?` → `true`; `present?` → `false`
+- Every `?`-method → `false` via `method_missing`
+- `== nil`, `== ""`, `== INSTANCE` → `true`
+- Implements `to_s`, `to_str`, `inspect`
+
+### `InquiryAttrs::SymbolInquiry < SimpleDelegator`
+
+- Wraps a `Symbol`; raises `ArgumentError` for non-symbols
+- Unwraps nested `SymbolInquiry` on init
+- Any `?`-method returns `true` iff `sym.to_s == method_name.delete_suffix('?')`
+- `==` accepts `Symbol`, `String`, or `SymbolInquiry`
+- `is_a?(Symbol)` → `true` (and `kind_of?`)
+- `nil?` → `false`; `blank?` → `false`; `present?` → `true`
+
+### `InquiryAttrs::Concern`
+
+The `inquirer` class method:
+
+1. Captures the **original** reader with `instance_method(attr)` before
+   redefining — this is the critical design choice that makes plain Ruby
+   `attr_accessor` and StoreModel work correctly.
+2. Defines a new method via `define_method` that calls `original.bind_call(self)`
+   to read the raw value.
+3. Falls back to `super()` → `self[attr]` → `nil` when no original exists
+   (e.g., lazy AR attribute definitions or Dry::Struct).
+4. Applies the return type decision table above.
+
+## Why `instance_method` capture instead of `super()`?
+
+When `inquirer :status` is called after `attr_accessor :status`, the new
+`define_method` *replaces* the attr_accessor reader. There is then no superclass
+method to call via `super()`, which raises `NoMethodError`. Capturing
+`instance_method(:status)` before the redefinition avoids this entirely.
+
+For AR models, `ActiveModel::Attributes` pre-defines readers before `inquirer`
+is typically called, so `instance_method` finds them too.
+
+## Why `blank?` instead of `nil? || == ""`?
+
+Since this is a Rails-only gem, `blank?` (from ActiveSupport) is always
+available. It handles `nil`, `""`, whitespace-only strings, and any object
+that defines `blank?`, all in one call.
+
+## Rails conventions used
+
+| Convention | Where used |
+|---|---|
+| `ActiveSupport::Concern` | `InquiryAttrs::Concern` |
+| `ActiveSupport.on_load(:active_record)` | `lib/inquiry_attrs.rb` — auto-include in AR |
+| `ActiveSupport::StringInquirer` via `String#inquiry` | `concern.rb` — wraps string values |
+| `Object#blank?` | `concern.rb` — nil/blank detection |
+
+## Test setup
+
+- **Framework:** Minitest with `minitest-reporters` (SpecReporter)
+- **Database:** SQLite in-memory (`adapter: 'sqlite3', database: ':memory:'`)
+- **AR schema:** defined inline in `setup` with `force: true`, dropped in `teardown`
+- **Run command:** `bundle exec ruby -Ilib -Itest test/inquiry_attrs/*.rb`

data/llms/usage.md

@@ -0,0 +1,204 @@
+# inquiry_attrs — Usage Patterns
+
+> Common patterns and recipes for LLMs helping users work with this gem.
+
+## 1. ActiveRecord — no setup needed
+
+```ruby
+# Just call inquirer in any AR model.
+# No include required — auto-added via ActiveSupport.on_load(:active_record).
+
+class User < ApplicationRecord
+  inquirer :status, :role, :plan
+end
+
+user = User.new(status: 'active', role: 'admin', plan: 'pro')
+
+user.status.active?    # => true
+user.status.inactive?  # => false
+user.role.admin?       # => true
+user.plan.pro?         # => true
+user.plan.free?        # => false
+
+# String methods still work
+user.status == 'active'          # => true
+user.status.include?('act')      # => true
+user.status.upcase               # => "ACTIVE"
+```
+
+## 2. Nil / blank safety
+
+```ruby
+user = User.new(status: nil)
+
+user.status.nil?     # => true
+user.status.blank?   # => true
+user.status.active?  # => false   ← no NoMethodError!
+user.status == nil   # => true
+user.status.to_s     # => ""
+
+# Guard pattern
+if user.status.nil?
+  # handle blank
+elsif user.status.active?
+  # handle active
+end
+```
+
+## 3. Replace case/when string comparisons
+
+```ruby
+# Before
+case user.status
+when 'active'    then grant_access(user)
+when 'suspended' then deny_access(user)
+when nil, ''     then redirect_to login_path
+end
+
+# After
+grant_access(user)          if user.status.active?
+deny_access(user)           if user.status.suspended?
+redirect_to login_path      if user.status.nil?
+```
+
+## 4. Scopes and conditions
+
+```ruby
+class User < ApplicationRecord
+  inquirer :status
+
+  scope :active,    -> { where(status: 'active') }
+  scope :suspended, -> { where(status: 'suspended') }
+end
+
+# In views or controllers
+User.all.select { |u| u.status.active? }
+```
+
+## 5. StoreModel
+
+```ruby
+class ShippingAddress
+  include StoreModel::Model
+  include InquiryAttrs::Concern   # required for non-AR classes
+
+  attribute :kind, :string
+  inquirer  :kind
+end
+
+class Order < ApplicationRecord
+  attribute :shipping_address, ShippingAddress.to_type
+end
+
+order.shipping_address.kind.billing?   # => true/false
+order.shipping_address.kind.nil?       # => true when blank
+```
+
+## 6. Plain Ruby class
+
+```ruby
+class Subscription
+  include InquiryAttrs::Concern
+
+  attr_accessor :plan, :state
+
+  def initialize(plan:, state: nil)
+    @plan  = plan
+    @state = state
+  end
+
+  # IMPORTANT: call inquirer AFTER attr_accessor
+  inquirer :plan, :state
+end
+
+sub = Subscription.new(plan: 'enterprise')
+sub.plan.enterprise?  # => true
+sub.state.nil?        # => true
+```
+
+## 7. Symbol attributes (e.g., Dry::Struct, enums stored as symbols)
+
+```ruby
+# If a reader returns a Symbol, you get SymbolInquiry
+si = InquiryAttrs::SymbolInquiry.new(:active)
+si.active?        # => true
+si.inactive?      # => false
+si == :active     # => true
+si == 'active'    # => true
+si.is_a?(Symbol)  # => true
+si.to_s           # => "active"
+si.to_sym         # => :active
+```
+
+## 8. Testing models with inquirer
+
+```ruby
+# Minitest
+class UserTest < ActiveSupport::TestCase
+  test 'status predicate' do
+    user = User.new(status: 'active')
+    assert user.status.active?
+    refute user.status.inactive?
+    assert_equal 'active', user.status
+  end
+
+  test 'nil status is safe' do
+    user = User.new(status: nil)
+    assert user.status.nil?
+    refute user.status.active?
+  end
+end
+```
+
+## 9. Detecting NilInquiry in code
+
+```ruby
+# Use nil? or == nil — do NOT use is_a?(NilClass)
+user.status.nil?             # => true   ✅
+user.status == nil           # => true   ✅
+user.status.is_a?(NilClass)  # => false  ❌ (it's NilInquiry, not NilClass)
+
+# Or compare to the instance directly
+user.status.equal?(InquiryAttrs::NilInquiry::INSTANCE)  # => true
+```
+
+## 10. Common mistakes
+
+```ruby
+# ❌ Calling inquirer before attr_accessor in plain Ruby
+class Broken
+  include InquiryAttrs::Concern
+  inquirer :status           # no original reader to capture yet!
+  attr_accessor :status
+end
+
+# ✅ Always after
+class Fixed
+  include InquiryAttrs::Concern
+  attr_accessor :status
+  inquirer :status
+end
+
+# ❌ Forgetting include for non-AR classes
+class MyStoreModel
+  include StoreModel::Model
+  # include InquiryAttrs::Concern  ← missing!
+  inquirer :status               # => NoMethodError
+end
+
+# ✅ Explicit include for StoreModel / plain Ruby
+class MyStoreModel
+  include StoreModel::Model
+  include InquiryAttrs::Concern  # ← required
+  inquirer :status
+end
+```
+
+## 11. Difference from `String#inquiry` (ActiveSupport)
+
+| Feature | `"active".inquiry` | `inquirer :status` |
+|---|---|---|
+| Nil/blank safety | Raises `NoMethodError` | Returns `NilInquiry::INSTANCE` |
+| Symbol support | Manual conversion | Automatic `SymbolInquiry` |
+| Model integration | Manual wrapping | Declarative macro |
+| AR auto-include | No | Yes, via `on_load` |

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: inquiry_attrs
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Pawel Niemczyk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  InquiryAttrs wraps ActiveRecord/ActiveModel (and StoreModel/Dry::Struct) attributes with
+  predicate-style inquiry methods. Write user.status.active? instead of
+  user.status == "active". Blank/nil values safely return false for every
+  predicate — no more NoMethodError on nil. Run `rails inquiry_attrs:install`
+  to generate an initializer that auto-includes the concern into every
+  ActiveRecord model.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE
+- README.md
+- lib/inquiry_attrs.rb
+- lib/inquiry_attrs/concern.rb
+- lib/inquiry_attrs/installer.rb
+- lib/inquiry_attrs/nil_inquiry.rb
+- lib/inquiry_attrs/railtie.rb
+- lib/inquiry_attrs/symbol_inquiry.rb
+- lib/inquiry_attrs/version.rb
+- lib/tasks/inquiry_attrs.rake
+- llms/overview.md
+- llms/usage.md
+homepage: https://github.com/your-org/inquiry_attrs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/your-org/inquiry_attrs
+  source_code_uri: https://github.com/your-org/inquiry_attrs
+  changelog_uri: https://github.com/your-org/inquiry_attrs/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Predicate-style inquiry methods for Rails model attributes
+test_files: []