cattri 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2495a8756d30c301267ad2db2dfbd4c9669e817119fa316b608408665988b747
-  data.tar.gz: 47d682eaf5465e4ab6cc4bdb7dcc74d053c93c6b8d1ee3a8cfda0925cf68662a
+  metadata.gz: 9de3a522be8c55a1b05edcc432f04d0352f0661290d6e7947b20e9399dde1462
+  data.tar.gz: d5b090040ea3e975c10342c8ac6d0ba3bfbd6b9bc1b3b8b50107c5ba12a13640
 SHA512:
-  metadata.gz: aae777877b7576a76b0be11a529aafaaac9c59066efd873fc9020689ba3ccefb78688411907b2246cb603dafa5e6868e1841e4724f296f634eac821a1bc27bc9
-  data.tar.gz: 8e919b6782d0cce71ed1a78bb46ebb92df995471238080a4e20604914d0fe958c041aec201eb598f9764598384fd776aaff03f5b131908082428c2d546c97cd9
+  metadata.gz: 43fb43c99d80be87ebf0b966093252980be960a1893e77f86f0344d8ba44f54d24bdf85f1a766b417b62f4a74a307c477f1ecde5fbb724baedb3bd6d65e858fb
+  data.tar.gz: 07b2830c5fbe6b805ceb191b2f8a1aacad6f3b3cd6ef03dca10e26b8b83dc8d708483756b4c46cac54e4d3f713b802957e9173bd959ea5b45c3b18fba5118869

data/.github/workflows/main.yml

@@ -0,0 +1,34 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '2.7.0'
+          - '3.1.4'
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run the default task
+        run: bundle exec rake
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/.gitignore

@@ -0,0 +1,72 @@
+# Ignore bundler config.
+/.bundle
+vendor/
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp
+
+# Ignore coverage reports.
+/coverage/
+
+# Ignore system specific files.
+/.byebug
+/.yardoc
+/._*
+
+# Ignore bundler binstubs.
+/bin/
+
+# Ignore Gemfile.lock
+Gemfile.lock
+
+# Ignore .env file containing sensitive information.
+.env
+
+# Ignore any local .env files.
+.env.*
+
+# VSCode settings
+.vscode/
+
+# RubyMine settings
+.idea/
+
+# Ignore VSCode workspace settings
+*.code-workspace
+
+# Ignore VSCode user-specific settings
+.vscode-server/
+
+# Ignore VSCode logs
+.vscode-logs/
+
+# Ignore the generated RDoc directory.
+/doc/
+
+# Ignore the default RVM or rbenv config.
+.rvmrc
+.rbenv-vars
+
+# Ignore macOS metadata directories.
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Ignore Windows thumbnail database.
+Thumbs.db
+
+# Ignore the Rubocop auto-generated configuration file.
+.rubocop_todo.yml
+
+# Ignore the coverage analysis directory.
+/coverage/
+
+# Ignore the local config file for Overcommit.
+.overcommit.yml
+
+*.gem
+.rspec_status

data/.rubocop.yml

@@ -28,13 +28,16 @@ Layout/LineLength:
 Lint/MissingSuper:
   Enabled: false
 
-Metrics/ClassLength:
-  Max: 200
-
 Metrics/BlockLength:
   Exclude:
     - cattri.gemspec
     - spec/**/*.rb
 
+Metrics/ClassLength:
+  Max: 200
+
 Metrics/MethodLength:
   Max: 20
+
+Metrics/ParameterLists:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [0.2.0] - 2025-05-01
+
+### Changed
+
+- Replaced `cattr` and `iattr` with unified `cattri` DSL
+  - All attributes now use `cattri`, with `scope: :class` or `scope: :instance`
+  - `iattr` and `cattr` are no longer public API
+
+- Attribute behavior is now centralized via:
+  - `Cattri::Attribute` and `Cattri::AttributeOptions`
+  - `Cattri::Context` and `ContextRegistry`
+  - `Cattri::InternalStore` for safe write-once value storage
+
+- Final attributes (`final: true`) now enforced at the store level, with safe write-once semantics
+- Visibility and exposure are fully separated:
+  - `visibility: :public|:protected|:private` sets method scope
+  - `expose: :read_write|:read|:write|:none` controls which methods are generated
+- New predicate handling via `predicate: true`, with visibility inheritance
+
+### Added
+
+- Support for `scope:` to explicitly declare attribute scope
+- `InitializerPatch` to apply default values for `final` instance attributes
+- `memoize_default_value` helper to simplify accessor generation
+- 100% RSpec coverage and branch coverage
+- Steep RBS type signatures for public and internal API
+- Full introspection via `.attributes`, `.attribute`, `.attribute_methods`, `.attribute_source`
+
+### Removed
+
+- `iattr`, `cattr`, `iattr_alias`, `cattr_alias`, and setter helpers (`*_setter`)
+- Legacy inheritance hook logic and module-style patching
+
+### Notes
+
+This release consolidates and simplifies the attribute system into a modern, safer, and more flexible DSL. All existing functionality is preserved through the `cattri` interface.
+
+This version introduces **breaking changes** to the DSL. Migration guide available in the README.
+
+---
+
 ## [0.1.3] - 2025-04-22
 
 ### Added

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in cattri.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/README.md

@@ -1,244 +1,256 @@
 # Cattri
 
-A **minimal‑footprint** DSL for defining **class‑level** and **instance‑level** attributes in Ruby, with first‑class support for custom defaults, coercion, visibility tracking, and safety‑first error handling.
+**Cattri** is a minimal-footprint Ruby DSL for defining class-level and instance-level attributes with clarity, safety, and full visibility control — without relying on ActiveSupport.
 
----
+It offers subclass-safe inheritance, lazy or static defaults, optional coercion, and write-once (`final`) semantics, while remaining lightweight and idiomatic.
 
-## Why another attribute DSL?
+---
 
-| Capability | Cattri | `attr_*` / `cattr_*` (Ruby / ActiveSupport) | `dry-configurable` |
-|------------|:------:|:-------------------------------------------:|:------------------:|
-| **Single DSL for class *and* instance attributes** | ✅ | ❌ (separate APIs) | ⚠️ (config only) |
-| **Per‑subclass deep copy of attribute metadata & values** | ✅ | ❌ | ❌ |
-| **Built‑in visibility tracking (`public` / `protected` / `private`)** | ✅ | ❌ | ❌ |
-| **Lazy or static *default* values** | ✅ | ⚠️ (writer‑based) | ✅ |
-| **Optional *coercion* via custom setter block** | ✅ | ❌ | ✅ |
-| **Read‑only / write‑only flags** | ✅ | ⚠️ (reader / writer macros) | ❌ |
-| **Introspection helpers (`snapshot_*`)** | ✅ | ❌ | ⚠️ via internals |
-| **Clear, granular error hierarchy** | ✅ | ❌ | ✅ |
-| **Zero runtime dependencies** | ✅ | ⚠️ (ActiveSupport) | ✅ |
+## ✨ Features
 
-> **TL;DR** – If you need lightweight, _Rails‑agnostic_ attribute helpers that play nicely with inheritance and don’t leak state between subclasses, Cattri is for you.
+- ✅ Unified `cattri` API for both class and instance attributes
+- 🔍 Tracks visibility: `public`, `protected`, `private`
+- 🔁 Inheritance-safe attribute copying
+- 🧼 Lazy defaults or static values
+- 🔒 Write-once `final: true` support
+- 👁 Predicate support (`admin?`, etc.)
+- 🔍 Introspection: list all attributes and methods
+- 🧪 100% test and branch coverage
+- 🔌 Zero runtime dependencies
 
 ---
 
-## Installation
-
-```bash
-bundle add cattri     # Ruby ≥ 2.7
-```
+## 💡 Why Use Cattri?
 
-Or in your Gemfile:
+Ruby's built-in attribute helpers and Rails' `class_attribute` are either too limited or too invasive. Cattri offers:
 
-```ruby
-gem "cattri"
-```
+| Capability                                     | Cattri | `attr_*` / `cattr_*` | `class_attribute` (Rails) |
+|-----------------------------------------------|--------|----------------------|---------------------------|
+| Single DSL for class & instance attributes     | ✅     | ❌                    | ❌                         |
+| Subclass-safe value & metadata inheritance    | ✅     | ❌                    | ⚠️                         |
+| Visibility-aware (`private`, `protected`)     | ✅     | ❌                    | ❌                         |
+| Lazy or static defaults                       | ✅     | ⚠️                    | ✅                         |
+| Optional coercion or transformation           | ✅     | ❌                    | ⚠️                         |
+| Write-once (`final: true`) semantics          | ✅     | ❌                    | ❌                         |
 
 ---
 
-## Quick start
+## 🚀 Usage Examples
+
+Cattri uses a single DSL method, `cattri`, to define both class-level and instance-level attributes.
+
+Use the `scope:` option to indicate whether the attribute belongs to the class (`:class`) or the instance (`:instance`). If omitted, it defaults to `:instance`.
 
 ```ruby
-class Config
-  include Cattri          # exposes `cattr` & `iattr`
-
-  # -- class‑level ----------------------------------
-  cattr :flag_a, :flag_b, default: true
-  cattr :enabled,         default: true, predicate: true
-  cattr :timeout,         default: -> { 5.0 }, instance_reader: false
-
-  # -- instance‑level -------------------------------
-  iattr :item_a, :item_b, default: true
-  iattr :name,            default: "anonymous"
-  iattr_alias :username, :name
-  iattr :age,             default: 0 do |val|                 # coercion block
-    Integer(val)
-  end
-end
+class User
+  include Cattri
 
-Config.enabled        # => true
-Config.enabled = false
-Config.enabled?       # => false (created with predicate: true flag)
-Config.new.age = "42" # => 42
-Config.new.username   # proxy to Config.new.name
-```
+  # Final class-level attribute
+  cattri :type, :standard, final: true, scope: :class
 
----
+  # Writable class-level attribute
+  cattri :config, -> { {} }, scope: :class
 
-## Defining attributes
+  # Final instance-level attribute
+  cattri :id, -> { SecureRandom.uuid }, final: true
 
-### Class attributes (`cattr`)
+  # Writable instance-level attributes
+  cattri :name, "anonymous"
+  cattri :admin, false, predicate: true
 
-```ruby
-cattr :log_level,
-      default: :info,
-      access:  :protected,     # respects current visibility by default
-      readonly: false,
-      predicate: true,         # defines #{name}? predicate method that respects visibility
-      instance_reader: true do |value|
-  value.to_sym
+  def initialize(id)
+    self.id = id # set the value for `cattri :id`
+  end
 end
-```
 
-### Instance attributes (`iattr`)
+# Class-level access
+User.type         # => :standard
+User.config       # => {}
 
-```ruby
-iattr :token, default: -> { SecureRandom.hex(8) },
-              reader:  true,
-              writer:  false,                  # read‑only
-              predicate: true
+# Instance-level access
+user = User.new
+user.name         # => "anonymous"
+user.admin?       # => false
+user.id           # => uuid
 ```
 
-Both forms accept:
+---
 
-| Option | Purpose |
-| ------ | ------- |
-| `default:` | Static value or callable (`Proc`) evaluated lazily. |
-| `access:` | Override inferred visibility (`:public`, `:protected`, `:private`). |
-| `reader:` / `writer:` | Disable reader or writer for instance attributes. |
-| `readonly:` | Shorthand for class attributes (`writer` is always present). |
-| `instance_reader:` | Expose class attribute as instance reader (default: **true**). |
-| `predicate` | Define a `:name?` method that calls `!!send(name)`
+## 👇 Accessing Attributes Within the Class
 
-If you pass a block, it’s treated as a **coercion setter** and receives the incoming value.
+```ruby
+class User
+  include Cattri
 
----
+  cattri :id, -> { SecureRandom.uuid }, final: true
+  cattri :type, :standard, final: true, scope: :class
 
-## Post-definition coercion with `*_setter`
+  def initialize(id)
+    self.id = id                 # Sets instance-level attribute
+  end
 
-If you define multiple attributes at once, you can't provide a coercion block inline:
+  def summary
+    "#{self.class.type}-#{id}"  # Accesses class-level and instance-level attributes
+  end
 
-```ruby
-cattr :foo, :bar, default: nil      # ❌ cannot use block here
+  def self.default_type
+    type  # Same as self.type — resolves on the singleton
+  end
+end
 ```
 
-Instead, define them first, then apply a coercion later using:
+---
 
-- `cattr_setter` for class attributes
-- `iattr_setter` for instance attributes
+## 🧭 Attribute Scope
 
-These allow you to attach or override the setter logic after the fact:
+By default, attributes are defined per-instance. You can change this behavior using `scope:`.
 
 ```ruby
 class Config
   include Cattri
 
-  cattr :log_level
-  cattr_setter :log_level do |val|
-    val.to_s.downcase.to_sym
-  end
-
-  iattr_writer :token
-  iattr_setter :token do |val|
-    val.strip
-  end
+  cattri :global_timeout, 30, scope: :class
+  cattri :retries, 3  # implicitly scope: :instance
 end
+
+Config.global_timeout        # => 30
+
+instance = Config.new
+instance.retries             # => 3
+instance.global_timeout      # => NoMethodError
 ```
 
-Coercion is only applied when the attribute is written (via `=` or callable form), not when read.
+- `scope: :class` defines the attribute on the class (i.e., the singleton).
+- `scope: :instance` (or omitting scope) defines the attribute per instance.
 
-Attempting to use `*_setter` on an undefined attribute or one without a writer will raise:
+---
 
-- `Cattri::AttributeNotDefinedError` – the attribute doesn't exist or wasn't fully defined
-- `Cattri::AttributeDefinitionError` – the attribute is marked as readonly
+## 🛡 Final Attributes
 
-These APIs ensure your DSL stays consistent and extensible, even when bulk-declaring attributes up front.
+```ruby
+class Settings
+  include Cattri
+  cattri :version, -> { "1.0.0" }, final: true, scope: :class
+end
+
+Settings.version          # => "1.0.0"
+Settings.version = "2.0"  # => Raises Cattri::AttributeError
+```
+
+- `final: true, scope: :class` defines a constant class-level attribute. It cannot be reassigned and uses the value provided at definition.
+- `final: true` (with instance scope) defines a write-once attribute. If not explicitly set during initialization, the default value will be used.
+
+> Note: `final_cattri` is a shorthand for `cattri(..., final: true)`, included for API symmetry but not required.
 
 ---
 
-## Visibility tracking
+## 👁 Attribute Exposure
 
-Cattri watches calls to `public`, `protected`, and `private` while you define methods:
+The `expose:` option controls what public methods are generated for an attribute. You can fine-tune whether the reader, writer, or neither is available.
 
 ```ruby
-class Secrets
+class Profile
   include Cattri
 
-  private
-  cattr :api_key
+  cattri :name, "guest", expose: :read_write
+  cattri :token, "secret", expose: :read
+  cattri :attempts, 0, expose: :write
+  cattri :internal_flag, true, expose: :none
 end
-
-Secrets.private_methods.include?(:api_key)   # => true
 ```
 
-No boilerplate—attributes inherit the visibility that was in effect at the call site.
+### Exposure Levels
+
+- `:read_write` — defines both reader and writer
+- `:read` — defines a reader only
+- `:write` — defines a writer only
+- `:none` — defines no public methods (internal only)
+
+> Predicate methods (`admin?`, etc.) are enabled via `predicate: true`.
 
 ---
 
-## Safe inheritance
+## 🔐 Visibility
 
-Subclassing copies both **metadata** and **current values**, using defensive `#dup` where possible and falling back safely when objects are frozen or not duplicable:
+Cattri respects Ruby's `public`, `protected`, and `private` scoping when defining methods. You can also explicitly override visibility using `visibility:`.
 
 ```ruby
-class Base
+class Document
   include Cattri
-  cattr :settings, default: {}
-end
 
-class Child < Base; end
+  private
+  cattri :token
+
+  protected
+  cattri :internal_flag
+
+  public
+  cattri :title
 
-Base.settings[:foo]  = 1
-Child.settings       # => {}  (isolated copy)
+  cattri :owner, "system", visibility: :protected
+end
 ```
 
+- If defined inside a visibility scope, Cattri applies that visibility automatically
+- Use `visibility:` to override the inferred scope
+- Applies only to generated methods (reader, writer, predicate), not internal store access
+
 ---
 
-## Introspection helpers
+## 🔍 Introspection
 
-Add `include Cattri::Introspection` (or `extend` for class‑only use) to snapshot live values:
+Enable introspection with:
 
 ```ruby
-Config.snapshot_cattrs   # => { enabled: false, timeout: 5.0 }
-instance.snapshot_iattrs # => { name: "bob", age: 42 }
-```
+User.with_cattri_introspection
 
-Great for debugging or test assertions.
+User.attributes              # => [:type, :name, :admin]
+User.attribute(:type).final? # => true
+User.attribute_methods       # => { type: [:type], name: [:name], admin: [:admin, :admin?] }
+User.attribute_source(:name) # => User
+```
 
 ---
 
-## Error handling
+## 📦 Installation
 
-All errors inherit from `Cattri::Error`, allowing a single rescue for any gem‑specific issue.
+Add to your Gemfile:
 
-| Error class | Raised when… |
-|-------------|--------------|
-| `Cattri::AttributeDefinedError` | an attribute is declared twice on the same level |
-| `Cattri::AttributeDefinitionError` | method generation (`define_method`) fails |
-| `Cattri::UnsupportedTypeError` | an internal API receives an unknown type |
-| `Cattri::AttributeError` | generic superclass for attribute‑related issues |
+```ruby
+gem "cattri"
+```
 
-Example:
+Or via Bundler:
 
-```ruby
-begin
-  class Foo
-    include Cattri
-    cattr :foo
-    cattr :foo   # duplicate
-  end
-rescue Cattri::AttributeDefinedError => e
-  warn e.message   # => "Class attribute :foo has already been defined"
-rescue Cattri::AttributeError => e
-  warn e.message   # => Catch-all for any error raised within attributes
-end
+```sh
+bundle add cattri
 ```
 
 ---
 
-## Comparison with standard patterns
+## 🧱 Design Overview
 
-* **Core Ruby macros** (`attr_accessor`, `cattr_accessor`) are simple but global—attributes bleed into subclasses and lack defaults or coercion.
-* **ActiveSupport** extends the API but still relies on mutable class variables and offers no visibility control.
-* **Dry‑configurable** is robust yet heavyweight when you only need a handful of attributes outside a full config object.
+Cattri includes:
 
-Cattri sits in the sweet spot: **micro‑sized (~300 LOC)**, dependency‑free, and purpose‑built for attribute declaration.
+- `InternalStore` for final-safe value tracking
+- `ContextRegistry` and `Context` for method definition logic
+- `Attribute` and `AttributeOptions` for metadata handling
+- `Visibility` tracking for DSL-defined methods
+- `InitializerPatch` for final attribute enforcement on `#initialize`
+- `Dsl` for `cattri` and `final_cattri`
+- `Inheritance` to ensure subclass copying
 
 ---
 
-## Testing tips
+## 🧪 Test Coverage
+
+Cattri is tested with 100% line and branch coverage. All dynamic definitions are validated via RSpec, and edge cases are covered, including:
 
-* Use `include Cattri::Introspection` in spec helper files to capture snapshots before/after mutations.
-* Rescue `Cattri::Error` in high‑level test helpers to assert failures without coupling to sub‑class names.
+- Predicate methods
+- Final value enforcement
+- Class vs. instance scope
+- Attribute inheritance
+- Visibility and expose interaction
 
 ---
 
@@ -247,13 +259,13 @@ Cattri sits in the sweet spot: **micro‑sized (~300 LOC)**, dependency‑free,
 1. Fork the repo
 2. `bundle install`
 3. Run the test suite with `bundle exec rake`
-4. Submit a pull request – ensure new code is covered and **rubocop** passes.
+4. Submit a pull request – ensure new code is covered and **rubocop** passes
 
 ---
 
 ## License
 
-This gem is released under the MIT License – see See [LICENSE](LICENSE) for details.
+This gem is released under the MIT License – see [LICENSE](LICENSE) for details.
 
 ## 🙏 Credits
 

data/Steepfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+target :lib do
+  check "lib"
+  signature "sig"
+end

data/bin/console

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "cattri"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# class Tester
+#   include Cattri
+#
+#   cattr :public_attr, default: 1
+#
+#   protected
+#   cattr :protected_attr, default: 2
+#
+#   private
+#   cattr :private_attr, default: 3
+#
+#   class << self
+#     def protected_proxy
+#       self.protected_attr
+#     end
+#
+#     def private_proxy
+#       self.private_attr
+#     end
+#   end
+# end
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here