inquiry_attrs 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e38ba51363664abde16b95c0369e6c81a59d5328a5040a3ae16f6b90ebc89fca
-  data.tar.gz: 8f90df1580bff8741d69d5654b16cf35ca81f5a31167a3a89563ebec7f2c4b10
+  metadata.gz: eaef756f9fda05436e3f930b7d0252712fea66dc7818b23b1238b2c098290c77
+  data.tar.gz: 61d886c923036fd403a0e2c780a1b45bb03de0f3f44f136a0a9cb44f48ebf7f5
 SHA512:
-  metadata.gz: fc6265f245d6f36cba27d4f98f82e0e2778eccf657c0ea549ab46519db81fe7865a6f3c552f8a293b11bfd434124b04552f82698bacf0950750c31d01735b1b8
-  data.tar.gz: a9acf7294f8d6c55fe5dd5ab36871d9e5b35355665888276d875ab0fd6e3a330067e6c00544b0a4a61a1f23052e5a96b59377721c3b63e7580af5b2f9efcac37
+  metadata.gz: 38bb6a3e26e701fbcc4e8dbe874f329ff74b245b67e4552566883b5a7520d2feef0d0c170ce5a639fe730792aba01d208a237914e1d23f746be98d8adb302719
+  data.tar.gz: 241b76ab67af3f051a12d40113cfaac361294e7b88a254ec12ff93d2b1f8be60309b2fa22c6e69b289d5115ce8dcd0444eb872d8bc964468beb8fe5cd8826e34

data/AGENTS.md

@@ -92,6 +92,26 @@ database in `test/test_helper.rb`.
 
 ---
 
+## Architecture — reserved predicate names
+
+Some predicate names are **already defined as real methods** on the returned
+objects. `method_missing` is never reached for them, so calling them does **not**
+test whether the attribute value equals that word.
+
+| Predicate | Defined on | What it actually does |
+|---|---|---|
+| `nil?` | Ruby `Object` | `false` for any present value; `true` for `NilInquiry` |
+| `blank?` | ActiveSupport | `true` when value is blank — not when it equals `"blank"` |
+| `present?` | ActiveSupport | Opposite of `blank?` — not when value equals `"present"` |
+| `empty?` | Ruby `String` | `true` only for `""` — not when value equals `"empty"` |
+| `frozen?` | Ruby `Object` | Reflects freeze state of the object |
+
+**When generating or reviewing code:** if an attribute's domain values include
+`nil`, `blank`, `present`, `empty`, or `frozen`, flag this and suggest direct
+string comparison (`== 'blank'`) rather than a predicate.
+
+---
+
 ## Architecture — the `instance_method` capture pattern
 
 This is the **most important** design decision in `concern.rb`:
@@ -166,9 +186,11 @@ auto-include anything on load — that would be implicit and hard to audit.
 ### `NilInquiry` (`lib/inquiry_attrs/nil_inquiry.rb`)
 
 - Frozen singleton: `NilInquiry::INSTANCE`
-- `nil?` → `true`; `blank?` → `true`; `present?` → `false`
+- `nil?` → `true`; `blank?` → `true`; `empty?` → `true`; `present?` → `false`
 - Any `?`-method → `false` via `method_missing`
 - `== nil`, `== ""`, `== INSTANCE` → `true`
+- `is_a?(NilClass)`, `kind_of?(NilClass)`, `instance_of?(NilClass)` → `true`
+  (`NilClass` cannot be subclassed; methods are overridden explicitly)
 - Implements `to_s` / `to_str` / `inspect`
 
 ### `SymbolInquiry` (`lib/inquiry_attrs/symbol_inquiry.rb`)
@@ -177,7 +199,8 @@ auto-include anything on load — that would be implicit and hard to audit.
 - 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`
+- `is_a?(Symbol)`, `kind_of?(Symbol)`, `instance_of?(Symbol)` → `true`
+  (`Symbol` cannot be subclassed; methods are overridden explicitly)
 - `nil?` → `false`; `blank?` → `false`; `present?` → `true`
 
 ### `Concern` (`lib/inquiry_attrs/concern.rb`)
@@ -219,6 +242,7 @@ auto-include anything on load — that would be implicit and hard to audit.
 | 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 |
+| Suggest `.blank?` / `.nil?` / `.present?` / `.empty?` / `.frozen?` as inquiry predicates for those exact values | These are real methods, not inquiry predicates — they test object state, not string equality. Use `== 'blank'` etc. instead |
 
 ---
 

data/CHANGELOG.md

@@ -11,6 +11,27 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [1.0.2] — 2026-02-27
+
+### Added
+
+- **`NilInquiry#is_a?` / `#kind_of?` / `#instance_of?`** — all three type-check
+  methods now return `true` when called with `NilClass` as the argument.
+  `NilClass` cannot be subclassed in Ruby, so the methods are overridden
+  explicitly (the same technique already used by `SymbolInquiry` for `Symbol`).
+  `is_a?(InquiryAttrs::NilInquiry)` continues to return `true`.
+
+- **`SymbolInquiry#kind_of?` / `#instance_of?`** — aliased to the existing
+  `is_a?` override so all three type-check methods consistently return `true`
+  for `Symbol` and the `SymbolInquiry` class itself.
+
+- **README — ⚠️ Reserved predicate names** — new section documenting that
+  attribute values whose names match built-in Ruby/Rails `?`-methods (`nil`,
+  `blank`, `present`, `empty`, `frozen`) will invoke the real method rather than
+  testing string equality, and explaining the safe `== 'value'` alternative.
+
+---
+
 ## [1.0.0] — 2026-02-27
 
 ### Added
@@ -80,5 +101,6 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
-[Unreleased]: https://github.com/pniemczyk/inquiry_attrs/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/pniemczyk/inquiry_attrs/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/pniemczyk/inquiry_attrs/compare/v1.0.0...v1.0.2
 [1.0.0]: https://github.com/pniemczyk/inquiry_attrs/releases/tag/v1.0.0

data/CLAUDE.md

@@ -110,3 +110,28 @@ gem build inquiry_attrs.gemspec
 - **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
+
+---
+
+## Reserved predicate names — gotcha
+
+Some predicate names are **real methods** on the objects `inquiry_attrs` returns.
+They are **never** handled by `method_missing` and do **not** test string equality.
+
+| Predicate | Actual behaviour |
+|---|---|
+| `.nil?` | Always `false` for present values; always `true` for blank (`NilInquiry`) |
+| `.blank?` | Tests blankness (nil / "" / whitespace) — not `value == "blank"` |
+| `.present?` | Opposite of `blank?` — not `value == "present"` |
+| `.empty?` | `true` only for `""` — not `value == "empty"` |
+| `.frozen?` | Reflects the object's freeze state |
+
+**When writing or reviewing code:** if a domain value matches one of the names
+above, use direct comparison instead:
+
+```ruby
+record.state == 'blank'    # ✅ correct
+record.state.blank?        # ❌ tests blankness, not state == "blank"
+```
+
+See `README.md` → "⚠️ Reserved predicate names" for the full worked example.

data/README.md

@@ -121,6 +121,52 @@ sub.state.nil?        # => true
 
 ---
 
+## ⚠️ Reserved predicate names
+
+Some predicate names are **already defined as real methods** on the objects
+`inquiry_attrs` returns. Calling them does **not** test whether the attribute
+value equals that word — the existing method is called instead and
+`method_missing` is never reached.
+
+| Value / predicate | Already defined by | What it actually tests |
+|---|---|---|
+| `"nil"` / `.nil?` | Ruby `Object#nil?` | Whether the object is `nil` — always `false` for present strings, always `true` for blank values |
+| `"blank"` / `.blank?` | ActiveSupport `Object#blank?` | Whether the value is blank (`nil`, `""`, whitespace) — **not** whether it equals `"blank"` |
+| `"present"` / `.present?` | ActiveSupport `Object#present?` | Opposite of `blank?` — **not** whether it equals `"present"` |
+| `"empty"` / `.empty?` | Ruby `String#empty?` | Whether the string is `""` — **not** whether it equals `"empty"` |
+| `"frozen"` / `.frozen?` | Ruby `Object#frozen?` | Whether the object is frozen — **not** whether it equals `"frozen"` |
+
+### Example of the problem
+
+```ruby
+class Order < ApplicationRecord
+  inquirer :state
+end
+
+# ❌ Misleading — .blank? tests blankness, not state == "blank"
+order = Order.new(state: 'blank')
+order.state.blank?    # => false  ("blank" is a non-empty string, so not blank)
+
+# ❌ Misleading — .present? tests non-blankness, not state == "present"
+order = Order.new(state: 'present')
+order.state.present?  # => true  (any non-blank string is present)
+
+# ❌ Misleading — .nil? tests object identity, not state == "nil"
+order = Order.new(state: 'nil')
+order.state.nil?      # => false  (it is a StringInquirer, not nil)
+```
+
+**Rule of thumb:** if your domain uses values such as `nil`, `blank`, `present`,
+`empty`, or `frozen`, use direct string comparison instead of a predicate:
+
+```ruby
+order.state == 'blank'    # ✅ reliable
+order.state == 'present'  # ✅ reliable
+order.state == 'nil'      # ✅ reliable
+```
+
+---
+
 ## How it works
 
 `.inquirer :attr` wraps the original attribute reader and returns one of three
@@ -132,31 +178,42 @@ objects based on the raw value:
 | `Symbol` | `InquiryAttrs::SymbolInquiry` | `:active.active?` → `true` |
 | Any other string | `ActiveSupport::StringInquirer` | Standard Rails inquiry |
 
+> **Note:** if an attribute value shares a name with a built-in Ruby/Rails
+> predicate (`"nil"`, `"blank"`, `"present"`, `"empty"`, `"frozen"`) the real
+> method will be called — not a string-equality check. See
+> [⚠️ Reserved predicate names](#️-reserved-predicate-names) for details.
+
 ### `InquiryAttrs::NilInquiry`
 
 A frozen singleton returned for blank attributes. Every `?`-method returns
-`false`; behaves like `nil` in comparisons and `blank?` checks.
+`false`; behaves like `nil` in comparisons, `blank?` checks, and type
+introspection.
 
 ```ruby
 ni = InquiryAttrs::NilInquiry::INSTANCE
-ni.nil?       # => true
-ni.active?    # => false
-ni == nil     # => true
-ni.blank?     # => true
+ni.nil?                  # => true
+ni.active?               # => false
+ni == nil                # => true
+ni.blank?                # => true
+ni.is_a?(NilClass)       # => true
+ni.kind_of?(NilClass)    # => true
+ni.instance_of?(NilClass) # => true
 ```
 
 ### `InquiryAttrs::SymbolInquiry`
 
 Wraps a Symbol with predicate methods; compares equal to both the symbol and
-its string equivalent.
+its string equivalent; reports itself as a `Symbol` in all type-check methods.
 
 ```ruby
 si = InquiryAttrs::SymbolInquiry.new(:active)
-si.active?         # => true
-si == :active      # => true
-si == 'active'     # => true
-si.is_a?(Symbol)   # => true
-si.to_s            # => "active"
+si.active?                # => true
+si == :active             # => true
+si == 'active'            # => true
+si.is_a?(Symbol)          # => true
+si.kind_of?(Symbol)       # => true
+si.instance_of?(Symbol)   # => true
+si.to_s                   # => "active"
 ```
 
 ---
@@ -172,7 +229,6 @@ Auto-included into `ActiveRecord::Base`. Include manually in other classes.
 ```ruby
 inquirer :status                         # single attribute
 inquirer :status, :role, :plan           # multiple attributes
-inquirer :status, only: :show            # passes options to before_action style macros (AR scoped)
 ```
 
 ---
@@ -181,9 +237,16 @@ inquirer :status, only: :show            # passes options to before_action style
 
 ```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
+
+# 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
 ```
 
 ---

data/lib/inquiry_attrs/nil_inquiry.rb

@@ -25,6 +25,12 @@ module InquiryAttrs
       method_name.to_s.end_with?('?') || super
     end
 
+    # NilClass cannot be subclassed in Ruby, so we override the type-check
+    # methods explicitly — the same technique used by SymbolInquiry for Symbol.
+    def is_a?(klass) = klass == NilClass || super
+    alias kind_of? is_a?
+    alias instance_of? is_a?
+
     def nil? = true
     def blank? = true
     def empty? = true

data/lib/inquiry_attrs/symbol_inquiry.rb

@@ -42,8 +42,9 @@ module InquiryAttrs
       end
     end
 
-    def is_a?(klass)    = klass == Symbol || super
+    def is_a?(klass) = klass == Symbol || super
     alias kind_of? is_a?
+    alias instance_of? is_a?
 
     def nil?    = false
     def blank?  = false

data/lib/inquiry_attrs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InquiryAttrs
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.0.2'.freeze
 end

data/llms/overview.md

@@ -64,14 +64,39 @@ inquirer :status, :role, :plan   # wraps multiple readers at once
 | `Symbol` | `InquiryAttrs::SymbolInquiry.new(raw)` |
 | Any other string | `raw.to_s.inquiry` → `ActiveSupport::StringInquirer` |
 
+## Reserved predicate names
+
+Several predicate names are **already defined as real methods** on the returned
+objects. `method_missing` is never reached for them, so they **do not** test
+whether the raw attribute value equals that word — they invoke the existing method.
+
+| Predicate | Defined by | What it tests |
+|---|---|---|
+| `nil?` | Ruby `Object` | Whether the object is `nil` — always `false` for present values |
+| `blank?` | ActiveSupport | Whether the value is blank (nil / "" / whitespace) |
+| `present?` | ActiveSupport | Opposite of `blank?` |
+| `empty?` | Ruby `String` / `NilInquiry` | Whether the string is `""` |
+| `frozen?` | Ruby `Object` | Whether the object is frozen |
+
+**Code generation rule:** when a model's attribute domain includes values whose
+names match the table above (e.g. a `state` column that can hold `"blank"` or
+`"nil"`), use direct string comparison — never a predicate:
+
+```ruby
+record.state == 'blank'    # ✅ tests string equality
+record.state.blank?        # ❌ tests blankness, not state == "blank"
+```
+
 ## Class responsibilities
 
 ### `InquiryAttrs::NilInquiry`
 
 - Frozen singleton (`INSTANCE`)
-- `nil?` → `true`; `blank?` → `true`; `present?` → `false`
-- Every `?`-method → `false` via `method_missing`
+- `nil?` → `true`; `blank?` → `true`; `empty?` → `true`; `present?` → `false`
+- Every `?`-method → `false` via `method_missing` (except the explicit overrides above)
 - `== nil`, `== ""`, `== INSTANCE` → `true`
+- `is_a?(NilClass)`, `kind_of?(NilClass)`, `instance_of?(NilClass)` → `true`
+  (`NilClass` cannot be subclassed; overridden explicitly)
 - Implements `to_s`, `to_str`, `inspect`
 
 ### `InquiryAttrs::SymbolInquiry < SimpleDelegator`
@@ -80,7 +105,8 @@ inquirer :status, :role, :plan   # wraps multiple readers at once
 - 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?`)
+- `is_a?(Symbol)`, `kind_of?(Symbol)`, `instance_of?(Symbol)` → `true`
+  (`Symbol` cannot be subclassed; overridden explicitly)
 - `nil?` → `false`; `blank?` → `false`; `present?` → `true`
 
 ### `InquiryAttrs::Concern`

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquiry_attrs
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Pawel Niemczyk