cattri 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6570d6da579ae6a15c865884a895a1ef0923eafd610d2a97a474d4a888af5778
-  data.tar.gz: 6f01dcc2490c4c4ef159d5fcf88c87ab50204c293ce403e87440b87130add491
+  metadata.gz: ba04c1c408b5ffe93591ba80633bc3b7d7950d0e651e4adf738e30fe4ba795ea
+  data.tar.gz: a4d5f788238eee82419df14b8977b018ed8b7d91169f7719171186c26e9dde7d
 SHA512:
-  metadata.gz: 9dbe7c5e9a7a8f4edcc160dc6952f42e80fd0ee5c602b65113fda8059663634c9c3d7d418044a7584626e8c9294240ad78be77a32b5dcabfa94d8498d2f76178
-  data.tar.gz: 301099ebc23bc730ada63468003fe1c9cd462e0040cbc8bc194d4a015d03a59c2b777482a4a142d5c215d93bc4083b7d2f5e33dec172e97ba343b5c48085f1a5
+  metadata.gz: 1a923822a64d948f87bc16c14511ab2b9a6d278f3b3a9264ee4ab57515644f3f42dedaee7db4bd3b6d5a7d294daf866a00dd99b0d4d72b29faade58f6facc0e2
+  data.tar.gz: 26cc1589b802f4916b55b43312d567e7e68138a83e16780c6c5a49405b16e45a6325bfd5d5e39b7b80bbe5bdf53bbadd84b606765c156cf53183be6a49e251f9

data/CHANGELOG.md

@@ -1,8 +1,50 @@
+## [0.2.3] - 2025-12-14
+
+### Added
+- New specs covering write-only exposure visibility for both instance and class attributes, ensuring readers are properly private/protected while writers remain public.
+- Strengthened Context storage resolution tests to assert descriptive errors when instance receivers are missing.
+
+## [0.2.2] - 2025-05-04
+
+No breaking changes – the public DSL (cattri, final_cattri) remains identical to v0.2.0.
+
+### Removed
+- Removed `Cattri::AttributeRegistry#copy_attributes_to` and all associated logic. Subclass attribute propagation
+  is now handled entirely via runtime resolution in `Context#storage_receiver_for`, eliminating the need for eager
+  copying of attribute values or metadata.
+- Removed `Cattri::Inheritance` and its use of `.inherited` hooks for subclass propagation, since all relevant state
+  is now derived dynamically.
+
+### Changed
+- Replaced static subclass propagation with dynamic storage resolution using `Context#storage_receiver_for`,
+  which now determines the correct backing object (instance, class, or singleton class) for all reads and writes.
+- `AttributeCompiler.define_accessor` now uses `storage_receiver_for` to set final class-level attribute values
+  during compilation.
+- Final class-level attributes (`final: true, scope: :class`) are now evaluated and written directly to the correct
+  storage receiver without relying on prior duplication logic.
+
+### Added
+- Proper support for defining attributes directly on a module’s singleton_class, ensuring values are stored and
+  accessed consistently across runtime and functional tests.
+  ```ruby
+  module MyModule
+    class << self
+      include Cattri
+  
+      cattri :version, "0.1.0", final: true, scope: :class
+    end
+  end
+  ```
+- Regression tests ensuring:
+  - Subclass attribute shadowing works for `final: true, scope: :class`. 
+  - Instance and class attribute isolation behaves as expected across inheritance chains. 
+  - No mutation of final attributes once defined.
+- Test coverage for `Context#storage_receiver` for and `Context#resolve_class_storage_for` across all branching logic.
+
 ## [0.2.1] - 2025-05-01
 
 - Fixed an issue where only `final: true` instance variables defined on the current/class had their values applied.
   - Now walks the ancestor tree to ensure all attributes get set.
-
   ```ruby
   module Options
     include Cattri

data/lib/cattri/attribute.rb

@@ -105,7 +105,7 @@ module Cattri
     def readonly?
       return false if @options.expose == :none
 
-      @options.expose == :read || final?
+      @options.expose == :read
     end
 
     # @return [Boolean] whether the attribute is marked final (write-once)

data/lib/cattri/attribute_compiler.rb

@@ -26,13 +26,14 @@ module Cattri
       def define_accessor(attribute, context)
         if attribute.class_attribute? && attribute.final?
           value = attribute.evaluate_default
-          context.target.cattri_variable_set(attribute.ivar, value) # steep:ignore
+          context.storage_receiver_for(attribute) # steep:ignore
+                 .cattri_variable_set(attribute.ivar, value, final: attribute.final?) # steep:ignore
         end
 
         return if attribute.expose == :none
 
         define_accessor!(attribute, context)
-        define_writer!(attribute, context)
+        define_writer!(attribute, context) if attribute.writable?
         define_predicate!(attribute, context) if attribute.with_predicate?
       end
 
@@ -48,12 +49,13 @@ module Cattri
       # @return [void]
       def define_accessor!(attribute, context)
         context.define_method(attribute) do |*args, **kwargs|
+          receiver = context.storage_receiver_for(attribute, self)
           readonly_call = args.empty? && kwargs.empty?
-          return AttributeCompiler.send(:memoize_default_value, self, attribute) if readonly_call
+          return AttributeCompiler.send(:memoize_default_value, receiver, attribute) if readonly_call
 
           attribute.validate_assignment!
           value = attribute.process_assignment(*args, **kwargs)
-          cattri_variable_set(attribute.ivar, value) # steep:ignore
+          receiver.cattri_variable_set(attribute.ivar, value) # steep:ignore
         end
       end
 
@@ -64,8 +66,10 @@ module Cattri
       # @return [void]
       def define_writer!(attribute, context)
         context.define_method(attribute, name: :"#{attribute.name}=") do |value|
+          receiver = context.storage_receiver_for(attribute, self)
+
           coerced_value = attribute.process_assignment(value)
-          cattri_variable_set(attribute.ivar, coerced_value, final: attribute.final?) # steep:ignore
+          receiver.cattri_variable_set(attribute.ivar, coerced_value, final: attribute.final?) # steep:ignore
         end
       end
 
@@ -82,19 +86,10 @@ module Cattri
 
       # Returns the default value for the attribute, memoizing it in the backing store.
       #
-      # For `final` attributes, raises unless explicitly initialized.
-      #
       # @param receiver [Object] the instance or class receiving the value
       # @param attribute [Cattri::Attribute]
       # @return [Object] the stored or evaluated default
-      # @raise [Cattri::AttributeError] if final attribute is unset or evaluation fails
       def memoize_default_value(receiver, attribute)
-        if attribute.final?
-          return receiver.cattri_variable_get(attribute.ivar) if receiver.cattri_variable_defined?(attribute.ivar)
-
-          raise Cattri::AttributeError, "Final attribute :#{attribute.name} cannot be written to"
-        end
-
         receiver.cattri_variable_memoize(attribute.ivar, final: attribute.final?) do
           attribute.evaluate_default
         end

data/lib/cattri/attribute_options.rb

@@ -20,25 +20,29 @@ module Cattri
       # Validates and normalizes the `expose` configuration.
       #
       # @param expose [Symbol, String] one of: :read, :write, :read_write, :none
+      # @param attribute_name [Symbol, nil] optional attribute name for error context
       # @return [Symbol]
       # @raise [Cattri::AttributeError] if the value is invalid
-      def validate_expose!(expose)
+      def validate_expose!(expose, attribute_name: nil)
         expose = expose.to_sym
         return expose if EXPOSE_OPTIONS.include?(expose) # steep:ignore
 
-        raise Cattri::AttributeError, "Invalid expose option `#{expose.inspect}` for :#{name}"
+        detail = attribute_name ? " for :#{attribute_name}" : ""
+        raise Cattri::AttributeError, "Invalid expose option `#{expose.inspect}`#{detail}"
       end
 
       # Validates and normalizes method visibility.
       #
       # @param visibility [Symbol, String] one of: :public, :protected, :private
+      # @param attribute_name [Symbol, nil] optional attribute name for error context
       # @return [Symbol]
       # @raise [Cattri::AttributeError] if the value is invalid
-      def validate_visibility!(visibility)
+      def validate_visibility!(visibility, attribute_name: nil)
         visibility = visibility.to_sym
         return visibility if VISIBILITIES.include?(visibility) # steep:ignore
 
-        raise Cattri::AttributeError, "Invalid visibility `#{visibility.inspect}` for :#{name}"
+        detail = attribute_name ? " for :#{attribute_name}" : ""
+        raise Cattri::AttributeError, "Invalid visibility `#{visibility.inspect}`#{detail}"
       end
     end
 
@@ -88,8 +92,8 @@ module Cattri
       @predicate = predicate
       @default = normalize_default(default)
       @transformer = normalize_transformer(transformer)
-      @expose = self.class.validate_expose!(expose)
-      @visibility = self.class.validate_visibility!(visibility)
+      @expose = self.class.validate_expose!(expose, attribute_name: @name)
+      @visibility = self.class.validate_visibility!(visibility, attribute_name: @name)
 
       freeze
     end

data/lib/cattri/attribute_registry.rb

@@ -87,23 +87,6 @@ module Cattri
       attribute.allowed_methods
     end
 
-    # Copies registered attributes from this context to another,
-    # preserving definitions and assigning values for `final: true, scope: :class`.
-    #
-    # @param target_context [Cattri::Context]
-    # @return [void]
-    def copy_attributes_to(target_context)
-      registered_attributes.each_value do |attribute|
-        next unless attribute.class_attribute? && attribute.final?
-
-        target_registry = target_context.target.send(:attribute_registry)
-        target_registry.send(:register_attribute, attribute)
-
-        value = context.target.cattri_variable_get(attribute.ivar) # steep:ignore
-        target_context.target.cattri_variable_set(attribute.ivar, value) # steep:ignore
-      end
-    end
-
     private
 
     # Validates that no attribute with the same name is already registered.

data/lib/cattri/context.rb

@@ -22,7 +22,9 @@ module Cattri
     # @return [Module]
     attr_reader :target
 
-    # @param target [Module, Class]
+    # Initializes the context wrapper.
+    #
+    # @param target [Module, Class] the receiver where attributes are defined
     def initialize(target)
       @target = target
     end
@@ -102,6 +104,44 @@ module Cattri
         __cattri_defined_methods[attribute.name].include?(normalized_name)
     end
 
+    # Resolves and returns the module or class where methods and storage should be defined
+    # for the given attribute. Ensures the internal store is included on the resolved target.
+    #
+    # - For class-level attributes, this returns the singleton class unless it's already a singleton.
+    # - For instance-level attributes, this returns the class/module directly.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [Module]
+    def target_for(attribute)
+      return @target if attribute.class_attribute? && singleton_class?(@target)
+
+      attribute.class_attribute? ? @target.singleton_class : @target
+    end
+
+    # Determines the object (class/module or runtime instance) that should hold
+    # the backing storage for the given attribute.
+    #
+    # - For class-level attributes, uses the singleton class of `defined_in` or the module itself
+    # - For instance-level attributes, uses the provided instance
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param instance [Object, nil] the runtime instance, if needed for instance-level access
+    # @return [Object] the receiver for attribute value storage
+    # @raise [Cattri::Error] if instance is required but missing
+    def storage_receiver_for(attribute, instance = nil)
+      receiver =
+        if attribute.class_attribute?
+          resolve_class_storage_for(attribute, instance)
+        elsif instance
+          instance
+        else
+          raise Cattri::Error, "Missing runtime instance for instance-level attribute :#{attribute.name}"
+        end
+
+      install_internal_store!(receiver)
+      receiver
+    end
+
     private
 
     # Internal tracking of explicitly defined methods per attribute.
@@ -111,12 +151,42 @@ module Cattri
       @__cattri_defined_methods ||= Hash.new { |h, k| h[k] = Set.new }
     end
 
-    # Determines whether to define the method on the instance or singleton.
+    # Determines whether the object is a singleton_class or not.
+    #
+    # @param obj [Object]
+    # @return [Boolean]
+    def singleton_class?(obj)
+      obj.singleton_class? # Ruby 3.2+
+    rescue NoMethodError
+      obj.inspect.start_with?("#<Class:")
+    end
+
+    # Resolves the proper class-level storage receiver for the attribute.
     #
     # @param attribute [Cattri::Attribute]
-    # @return [Module]
-    def target_for(attribute)
-      attribute.class_attribute? ? @target.singleton_class : @target
+    # @param instance [Object, nil]
+    # @return [Object]
+    def resolve_class_storage_for(attribute, instance)
+      if attribute.final?
+        singleton_class?(attribute.defined_in) ? attribute.defined_in : attribute.defined_in.singleton_class
+      else
+        attribute_scope = instance || attribute.defined_in
+        attribute_scope.singleton_class
+      end
+    end
+
+    # Installs the internal store on the receiver if not present.
+    #
+    # @param receiver [Object]
+    # @return [void]
+    def install_internal_store!(receiver)
+      return if receiver.respond_to?(:cattri_variables)
+
+      if singleton_class?(receiver)
+        receiver.extend(Cattri::InternalStore)
+      else
+        receiver.include(Cattri::InternalStore) # steep:ignore
+      end
     end
 
     # Defines the method and applies its access visibility.
@@ -157,11 +227,9 @@ module Cattri
     #   - Returns `:private` for instance-level attributes
     # - Otherwise, returns the explicitly declared visibility (`attribute.visibility`)
     #
-    # This ensures that internal-only attributes remain inaccessible outside their scope,
-    # while still being usable by subclasses if class-level.
-    #
     # @param attribute [Cattri::Attribute]
-    # @return [Symbol]
+    # @param name [Symbol]
+    # @return [Symbol] one of `:public`, `:protected`, or `:private`
     def effective_visibility(attribute, name)
       return :protected if attribute.class_attribute? && internal_method?(attribute, name)
       return :private if !attribute.class_attribute? && internal_method?(attribute, name)
@@ -172,14 +240,9 @@ module Cattri
     # Determines whether the given method name (accessor or writer)
     # should be treated as internal-only based on the attribute's `expose` configuration.
     #
-    # This is used when resolving method visibility (e.g., private vs protected).
-    #
-    # - Writer methods (`:attr=`) are considered internal if the attribute lacks public read access.
-    # - Reader methods (`:attr`) are considered internal if the attribute lacks public write access.
-    #
-    # @param attribute [Cattri::Attribute] the attribute definition
-    # @param name [Symbol, String] the method name being defined
-    # @return [Boolean] true if the method should be scoped for internal use only
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol, String]
+    # @return [Boolean]
     def internal_method?(attribute, name)
       return attribute.internal_writer? if name.to_s.end_with?("=")
 

data/lib/cattri/context_registry.rb

@@ -30,7 +30,8 @@ module Cattri
     #
     # @return [Cattri::Context] the context used for method definition and visibility tracking
     def context
-      @context ||= Context.new(self) # steep:ignore
+      base = instance_variable_get(:@__cattri_base_target) || self
+      @context ||= Context.new(base) # steep:ignore
     end
   end
 end

data/lib/cattri/initializer_patch.rb

@@ -31,7 +31,7 @@ module Cattri
         next if cattri_variable_defined?(attribute.ivar) # steep:ignore
         next unless attribute.final?
 
-        cattri_variable_set(attribute.ivar, attribute.evaluate_default) # steep:ignore
+        cattri_variable_set(attribute.ivar, attribute.evaluate_default, final: true) # steep:ignore
       end
     end
   end

data/lib/cattri/internal_store.rb

@@ -13,6 +13,17 @@ module Cattri
   #
   # It supports enforcement of `final` semantics and tracks explicit assignments.
   module InternalStore
+    # Returns the list of attribute keys stored by Cattri on this object.
+    #
+    # Mimics Ruby's `#instance_variables`, but only includes attributes defined
+    # via `cattri` and omits the leading `@` from names. All keys are returned as
+    # frozen symbols (e.g., `:enabled` instead of `:@enabled`).
+    #
+    # @return [Array<Symbol>] the list of internally tracked attribute keys
+    def cattri_variables
+      __cattri_store.keys.freeze
+    end
+
     # Checks whether the internal store contains a value for the given key.
     #
     # @param key [String, Symbol] the attribute name or instance variable

data/lib/cattri/introspection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Cattri
   # Provides a read-only interface for inspecting attributes defined via the Cattri DSL.
   #
@@ -62,7 +64,9 @@ module Cattri
       #
       # @return [Hash{Symbol => Set<Symbol>}]
       def attribute_methods
-        context.defined_methods # steep:ignore
+        attribute_registry.defined_attributes(with_ancestors: true).transform_values do |attribute| # steep:ignore
+          Set.new(attribute.allowed_methods)
+        end
       end
 
       # Returns the original class or module where the given attribute was defined.

data/lib/cattri/version.rb

@@ -2,6 +2,6 @@
 
 module Cattri
   # :nocov:
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
   # :nocov:
 end

data/lib/cattri/visibility.rb

@@ -3,8 +3,8 @@
 module Cattri
   # Cattri::Visibility tracks the current method visibility context (`public`, `protected`, `private`)
   # when defining methods dynamically. It mimics Ruby's native visibility behavior so that
-  # `cattr` and `iattr` definitions can automatically infer the intended access level
-  # based on the current context in the source file.
+  # `cattri` definitions can automatically infer the intended access level based on the current context
+  # in the source file.
   #
   # This module is intended to be extended by classes that include or extend Cattri.
   #
@@ -13,7 +13,7 @@ module Cattri
   #     include Cattri
   #
   #     private
-  #     cattr :sensitive_data
+  #     cattri :sensitive_data
   #   end
   #
   #   # => :sensitive_data will be defined as a private method

data/lib/cattri.rb

@@ -3,7 +3,6 @@
 require_relative "cattri/attribute"
 require_relative "cattri/context_registry"
 require_relative "cattri/dsl"
-require_relative "cattri/inheritance"
 require_relative "cattri/initializer_patch"
 require_relative "cattri/internal_store"
 require_relative "cattri/introspection"
@@ -33,14 +32,16 @@ module Cattri
     [base, base.singleton_class].each do |mod|
       mod.include(Cattri::InternalStore)
       mod.include(Cattri::ContextRegistry)
+      mod.instance_variable_set(:@__cattri_base_target, base)
     end
 
+    base.extend(Cattri::InternalStore)
+    base.singleton_class.extend(Cattri::InternalStore)
+
     base.prepend(Cattri::InitializerPatch)
     base.extend(Cattri::Visibility)
     base.extend(Cattri::Dsl)
     base.extend(ClassMethods)
-
-    Cattri::Inheritance.install(base)
   end
 
   # Provides opt-in class-level introspection support.

data/sig/lib/cattri/attribute_options.rbs

@@ -35,14 +35,14 @@ module Cattri
     # @param expose [Symbol, String] one of: :read, :write, :read_write, :none
     # @return [Symbol]
     # @raise [Cattri::AttributeError] if the value is invalid
-    def self.validate_expose!: (expose_types | identifier expose) -> untyped
+    def self.validate_expose!: (expose_types | identifier expose, ?attribute_name: ::Symbol?) -> untyped
 
     # Validates and normalizes method visibility.
     #
     # @param visibility [Symbol, String] one of: :public, :protected, :private
     # @return [Symbol]
     # @raise [Cattri::AttributeError] if the value is invalid
-    def self.validate_visibility!: (visibility_types | identifier visibility) -> untyped
+    def self.validate_visibility!: (visibility_types | identifier visibility, ?attribute_name: ::Symbol?) -> untyped
 
     # Valid method visibility levels.
     VISIBILITIES: ::Array[visibility_types]

data/sig/lib/cattri/context.rbs

@@ -68,6 +68,24 @@ module Cattri
     # @return [Boolean]
     def method_defined?: (Attribute attribute, ?name: identifier?) -> bool
 
+    # Determines whether to define the method on the instance or singleton.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [Module]
+    def target_for: (Attribute attribute) -> ::Module
+
+    # Determines the object (class/module or runtime instance) that should hold
+    # the backing storage for the given attribute.
+    #
+    # - For class-level attributes, uses the singleton class of `defined_in` or the module itself
+    # - For instance-level attributes, uses the provided instance
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param instance [Object, nil] the runtime instance, if needed for instance-level access
+    # @return [Object] the receiver for attribute value storage
+    # @raise [Cattri::Error] if instance is required but missing
+    def storage_receiver_for: (Attribute attribute, ::Object? instance) -> ::Object
+
     private
 
     # Internal tracking of explicitly defined methods per attribute.
@@ -75,11 +93,24 @@ module Cattri
     # @return [Hash{Symbol => Set<Symbol>}]
     def __cattri_defined_methods: () -> ::Hash[::Symbol, ::Set[::Symbol]]
 
-    # Determines whether to define the method on the instance or singleton.
+    # Determines whether the object is a singleton_class or not.
+    #
+    # @param obj [Object]
+    # @return [Boolean]
+    def singleton_class?: (untyped obj) -> bool
+
+    # Resolves the proper class-level storage receiver for the attribute.
     #
     # @param attribute [Cattri::Attribute]
-    # @return [Module]
-    def target_for: (Attribute attribute) -> ::Module
+    # @param instance [Object, nil]
+    # @return [Object]
+    def resolve_class_storage_for: (Attribute attribute, ::Object? instance) -> ::Object
+
+    # Installs the internal store on the receiver if not present.
+    #
+    # @param receiver [Object]
+    # @return [void]
+    def install_internal_store!: (::Object receiver) -> void
 
     # Defines the method and applies its access visibility.
     #

data/sig/lib/cattri/internal_store.rbs

@@ -13,6 +13,15 @@ module Cattri
 
     @__cattri_set_variables: ::Set[::Symbol]
 
+    # Returns the list of attribute keys stored by Cattri on this object.
+    #
+    # Mimics Ruby's `#instance_variables`, but only includes attributes defined
+    # via `cattri` and omits the leading `@` from names. All keys are returned as
+    # frozen symbols (e.g., `:enabled` instead of `:@enabled`).
+    #
+    # @return [Array<Symbol>] the list of internally tracked attribute keys
+    def cattri_variables: () -> ::Array[::Symbol]
+
     # Checks whether the internal store contains a value for the given key.
     #
     # @param key [String, Symbol] the attribute name or instance variable

data/spec/cattri/attribute_compiler_spec.rb

@@ -26,7 +26,7 @@ RSpec.describe Cattri::AttributeCompiler do
 
       it "eagerly sets the default value on the target class" do
         described_class.define_accessor(attribute, context)
-        expect(dummy_class.cattri_variable_get(:count)).to eq(100)
+        expect(dummy_class.count).to eq(100)
       end
     end
 
@@ -67,6 +67,26 @@ RSpec.describe Cattri::AttributeCompiler do
         expect(instance.enabled?).to eq(true)
       end
     end
+
+    context "when expose is :read" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :visible,
+          defined_in: dummy_class,
+          default: -> { "shown" },
+          expose: :read
+        )
+      end
+
+      it "does not define a writer" do
+        described_class.define_accessor(attribute, context)
+        instance = dummy_class.new
+
+        expect(instance.visible).to eq("shown")
+        expect(instance.respond_to?(:visible=)).to be(false)
+        expect(instance.respond_to?(:visible=, true)).to be(false)
+      end
+    end
   end
 
   describe ".define_accessor!" do
@@ -134,46 +154,16 @@ RSpec.describe Cattri::AttributeCompiler do
   describe ".memoize_default_value" do
     let(:instance) { dummy_class.new }
 
-    context "non-final attribute" do
-      let(:attribute) do
-        Cattri::Attribute.new(
-          :foo,
-          defined_in: dummy_class,
-          default: -> { "bar" },
-          expose: :read_write
-        )
-      end
-
-      it "stores and returns the evaluated default" do
-        result = described_class.send(:memoize_default_value, instance, attribute)
-        expect(result).to eq("bar")
-        expect(instance.cattri_variable_get(:foo)).to eq("bar")
-      end
-    end
-
-    context "final attribute" do
-      let(:attribute) do
-        Cattri::Attribute.new(
-          :immutable,
-          defined_in: dummy_class,
-          final: true,
-          default: -> { "locked" },
-          expose: :read
-        )
-      end
-
-      it "raises if value is not already set" do
-        expect do
-          described_class.send(:memoize_default_value, instance, attribute)
-        end.to raise_error(Cattri::AttributeError, /Final attribute :immutable cannot be written to/)
-      end
-
-      it "returns value if already set" do
-        instance.cattri_variable_set(:immutable, "preset", final: true)
-        result = described_class.send(:memoize_default_value, instance, attribute)
+    it "memoizes the evaluated default" do
+      attribute = Cattri::Attribute.new(
+        :foo,
+        defined_in: dummy_class,
+        default: -> { "bar" },
+        expose: :read_write
+      )
 
-        expect(result).to eq("preset")
-      end
+      expect(described_class.send(:memoize_default_value, instance, attribute)).to eq("bar")
+      expect(instance.cattri_variable_get(:foo)).to eq("bar")
     end
   end
 end

data/spec/cattri/attribute_options_spec.rb

@@ -144,6 +144,18 @@ RSpec.describe Cattri::AttributeOptions do
         expect(instance.instance_variable_get(:@visibility)).to eq(:private)
       end
     end
+
+    it "raises a helpful error when expose is invalid" do
+      expect do
+        described_class.new(name, expose: :bogus)
+      end.to raise_error(Cattri::AttributeError, /:bogus.*for :my_attribute/)
+    end
+
+    it "raises a helpful error when visibility is invalid" do
+      expect do
+        described_class.new(name, visibility: :bogus)
+      end.to raise_error(Cattri::AttributeError, /:bogus.*for :my_attribute/)
+    end
   end
 
   describe "#[]" do

data/spec/cattri/attribute_registry_spec.rb

@@ -117,43 +117,6 @@ RSpec.describe Cattri::AttributeRegistry do
     end
   end
 
-  describe "#copy_attributes_to" do
-    let(:target_klass) do
-      Class.new do
-        include Cattri
-      end
-    end
-
-    let!(:target_registry) { target_klass.send(:attribute_registry) }
-    let(:target_context) { Cattri::Context.new(target_klass) }
-
-    it "copies final class attributes and sets their values" do
-      registry.define_attribute(:enabled, "yes", scope: :class, final: true)
-      registry.context.target.cattri_variable_set(:@enabled, "yes")
-
-      registry.copy_attributes_to(target_context)
-
-      expect(target_klass.cattri_variable_get(:@enabled)).to eq("yes")
-      expect(target_registry.fetch_attribute(:enabled)).to be_a(Cattri::Attribute)
-    end
-
-    it "skips non-final or instance-level attributes" do
-      registry.define_attribute(:skipped1, "val", scope: :instance, final: true)
-      registry.define_attribute(:skipped2, "val", scope: :class, final: false)
-
-      expect do
-        registry.copy_attributes_to(target_context)
-      end.not_to(change { target_klass.send(:attribute_registry).defined_attributes })
-    end
-
-    it "restores original context after copying" do
-      original_context = registry.context
-      registry.copy_attributes_to(target_context)
-
-      expect(registry.context).to equal(original_context)
-    end
-  end
-
   describe "#validate_unique!" do
     context "when no attributes are registered" do
       it "returns without raising" do

data/spec/cattri/attribute_spec.rb

@@ -112,8 +112,8 @@ RSpec.describe Cattri::Attribute do
   describe "#writable?" do
     [
       [true, :read, false],
-      [true, :write, false],
-      [true, :read_write, false],
+      [true, :write, true],
+      [true, :read_write, true],
       [true, :none, false],
       [false, :read, false],
       [false, :write, true],
@@ -134,8 +134,8 @@ RSpec.describe Cattri::Attribute do
   describe "#readonly?" do
     [
       [true, :read, true],
-      [true, :write, true],
-      [true, :read_write, true],
+      [true, :write, false],
+      [true, :read_write, false],
       [true, :none, false],
       [false, :read, true],
       [false, :write, false],

data/spec/cattri/context_registry_spec.rb

@@ -6,6 +6,7 @@ RSpec.describe Cattri::ContextRegistry do
   let(:klass) do
     Class.new do
       include Cattri::ContextRegistry
+
       public :context, :attribute_registry
     end
   end

data/spec/cattri/context_spec.rb

@@ -3,7 +3,7 @@
 require "spec_helper"
 
 RSpec.describe Cattri::Context do
-  let(:context_target) { Class.new }
+  let!(:context_target) { Class.new }
 
   def define_attribute(name, value, scope: :instance, visibility: :public)
     Cattri::Attribute.new(
@@ -181,6 +181,64 @@ RSpec.describe Cattri::Context do
     end
   end
 
+  describe "#target_for" do
+    subject(:result) { context.target_for(attribute) }
+
+    context "when a class-level attribute is provided" do
+      let(:attribute) { class_attribute }
+
+      it "returns the singleton_class" do
+        expect(result).to eq(context_target.singleton_class)
+      end
+    end
+
+    context "when a instance-level attribute is provided" do
+      let(:attribute) { instance_attribute }
+
+      it "returns the context's target" do
+        expect(result).to eq(context_target)
+      end
+    end
+
+    context "when a class-level attribute is provided and the context is a singleton_class" do
+      let(:context_target) { singleton_class }
+      let(:attribute) { class_attribute }
+
+      it "returns the singleton_class" do
+        expect(result).to eq(singleton_class)
+      end
+    end
+  end
+
+  describe "#storage_receiver_for" do
+    context "when a class-level attribute is provided" do
+      it "resolves to the instance's singleton_class, if instance is provided" do
+        receiver = context.storage_receiver_for(class_attribute, self)
+        expect(receiver).to eq(singleton_class)
+      end
+
+      it "resolves to the attribute's defined_in.singleton_class when no instance is provided" do
+        receiver = context.storage_receiver_for(class_attribute) # no instance passed
+        expect(receiver).to eq(context_target.singleton_class)
+      end
+    end
+
+    context "when a instance-level attribute is provided" do
+      it "returns the instance" do
+        receiver = context.storage_receiver_for(instance_attribute, self)
+        expect(receiver).to eq(self)
+      end
+    end
+
+    context "when a received cannot be resolved" do
+      it "raises a descriptive Cattri::Error" do
+        expect { context.storage_receiver_for(instance_attribute, nil) }
+          .to raise_error(Cattri::Error,
+                          /Missing runtime instance for instance-level attribute :#{instance_attribute.name}/)
+      end
+    end
+  end
+
   describe "#__cattri_defined_methods" do
     it "returns a Hash" do
       expect(context.send(:__cattri_defined_methods)).to be_a(Hash)
@@ -201,26 +259,85 @@ RSpec.describe Cattri::Context do
     end
   end
 
-  describe "#target_for" do
-    subject(:result) { context.send(:target_for, attribute) }
+  describe "#resolve_class_storage_for" do
+    def define_attribute(name, final:, defined_in:, scope: :class)
+      Cattri::Attribute.new(
+        name,
+        final: final,
+        defined_in: defined_in,
+        scope: scope,
+        default: -> { "value" },
+        visibility: :public
+      )
+    end
+
+    context "when attribute is final" do
+      it "returns defined_in if already a singleton_class" do
+        mod = Module.new
+        singleton = mod.singleton_class
+        attribute = define_attribute(:final_attr, final: true, defined_in: singleton)
+
+        expect(context.send(:resolve_class_storage_for, attribute, nil)).to eq(singleton)
+      end
 
-    context "when a class-level attribute is provided" do
-      let(:attribute) { class_attribute }
+      it "returns singleton_class of defined_in if not already a singleton" do
+        klass = Class.new
+        attribute = define_attribute(:final_attr, final: true, defined_in: klass)
 
-      it "returns the singleton_class" do
-        expect(result).to eq(context_target.singleton_class)
+        expect(context.send(:resolve_class_storage_for, attribute, nil)).to eq(klass.singleton_class)
       end
     end
 
-    context "when a instance-level attribute is provided" do
-      let(:attribute) { instance_attribute }
+    context "when attribute is not final" do
+      it "returns singleton_class of instance if instance is provided" do
+        instance = Object.new
+        attribute = define_attribute(:nonfinal_attr, final: false, defined_in: context_target)
 
-      it "returns the context's target" do
-        expect(result).to eq(context_target)
+        expect(context.send(:resolve_class_storage_for, attribute, instance)).to eq(instance.singleton_class)
+      end
+
+      it "returns singleton_class of defined_in if no instance is provided" do
+        attribute = define_attribute(:nonfinal_attr, final: false, defined_in: context_target)
+
+        expect(context.send(:resolve_class_storage_for, attribute, nil)).to eq(context_target.singleton_class)
       end
     end
   end
 
+  describe "#install_internal_store!" do
+    let(:context) { Cattri::Context.new(Object.new) }
+
+    it "does nothing if receiver already responds to cattri_variables" do
+      receiver = Class.new do
+        def self.cattri_variables; end
+      end
+
+      expect { context.send(:install_internal_store!, receiver) }
+        .not_to(change { receiver.ancestors })
+    end
+
+    it "extends singleton class if receiver is a singleton class" do
+      base = Class.new
+      singleton = base.singleton_class
+
+      expect(singleton.ancestors).not_to include(Cattri::InternalStore)
+
+      context.send(:install_internal_store!, singleton)
+
+      expect(singleton.ancestors).to include(Cattri::InternalStore)
+    end
+
+    it "includes module if receiver is a regular class or module" do
+      klass = Class.new
+
+      expect(klass.ancestors).not_to include(Cattri::InternalStore)
+
+      context.send(:install_internal_store!, klass)
+
+      expect(klass.ancestors).to include(Cattri::InternalStore)
+    end
+  end
+
   describe "#define_method!" do
     let(:target) { context.send(:target_for, class_attribute) }
     let(:attribute_name) { class_attribute.name }

data/spec/cattri/internal_store_spec.rb

@@ -13,6 +13,16 @@ RSpec.describe Cattri::InternalStore do
 
   subject(:instance) { klass.new }
 
+  describe "#cattri_variables" do
+    it "returns a list of all cattri variables" do
+      instance.cattri_variable_set(:foo, 123)
+      instance.cattri_variable_set(:bar, 123)
+      instance.cattri_variable_set(:@baz, 123)
+
+      expect(instance.cattri_variables).to match_array(%i[foo bar baz])
+    end
+  end
+
   describe "#cattri_variable_defined?" do
     it "returns false when variable is not set" do
       expect(instance.cattri_variable_defined?(:foo)).to be false

data/spec/cattri/introspection_spec.rb

@@ -6,6 +6,7 @@ RSpec.describe Cattri::Introspection do
   let(:klass) do
     Class.new do
       include Cattri
+
       cattri :foo, 123
     end
   end
@@ -13,6 +14,7 @@ RSpec.describe Cattri::Introspection do
   let(:subclass) do
     Class.new(klass) do
       include Cattri::Introspection
+
       cattri :bar, "bar"
     end
   end
@@ -75,6 +77,12 @@ RSpec.describe Cattri::Introspection do
       expect(methods.keys).to include(:bar)
       expect(methods[:bar]).to include(:bar)
     end
+
+    it "includes methods for inherited attributes" do
+      methods = subclass.attribute_methods
+      expect(methods.keys).to include(:foo)
+      expect(methods[:foo]).to include(:foo)
+    end
   end
 
   describe ".attribute_source" do

data/spec/cattri_spec.rb

@@ -35,6 +35,7 @@ RSpec.describe Cattri do
     let(:introspective_class) do
       Class.new do
         include Cattri
+
         cattri :id, "foo"
 
         with_cattri_introspection
@@ -51,4 +52,190 @@ RSpec.describe Cattri do
       expect(introspective_class.attribute_methods).to include(:id)
     end
   end
+
+  describe "regression tests" do
+    it "allows one-time assignment to final instance attribute" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :value, final: true
+
+        def initialize(value)
+          self.value = value
+        end
+      end
+
+      instance = klass.new("first")
+      expect(instance.value).to eq("first")
+
+      expect { instance.value = "second" }.to raise_error(Cattri::AttributeError)
+    end
+
+    it "prevents any assignment to final class attribute" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :value, -> { "init" }, final: true, scope: :class
+      end
+
+      expect(klass.value).to eq("init")
+      expect { klass.value = "fail" }.to raise_error(Cattri::AttributeError)
+    end
+
+    it "allows shadowing parent class attributes" do
+      parent = Class.new do
+        include Cattri
+
+        cattri :enabled, true, final: true, scope: :class
+      end
+
+      child = Class.new do
+        include Cattri
+
+        cattri :enabled, false, final: true, scope: :class
+      end
+
+      expect(parent.enabled).to be(true)
+      expect(child.enabled).to be(false)
+    end
+
+    it "defines predicate method for instance attribute" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :flag, false, predicate: true
+      end
+
+      instance = klass.new
+      expect(instance.flag?).to eq(false)
+
+      instance.flag = true
+      expect(instance.flag?).to eq(true)
+    end
+
+    it "evaluates and stores default value lazily" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :computed, -> { "value" }
+      end
+
+      instance = klass.new
+
+      expect(instance.cattri_variable_defined?(:computed)).to eq(false)
+      expect(instance.computed).to eq("value")
+      expect(instance.cattri_variable_defined?(:computed)).to eq(true)
+    end
+
+    it "isolates instance and class attributes correctly" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :config, scope: :class
+        cattri :state, scope: :instance
+      end
+
+      klass.config = "shared"
+      a = klass.new
+      b = klass.new
+      a.state = "one"
+      b.state = "two"
+
+      expect(klass.config).to eq("shared")
+      expect(a.state).to eq("one")
+      expect(b.state).to eq("two")
+    end
+
+    it "allows for class attributes set on a module's singleton_class" do
+      mod = Module.new do
+        class << self
+          include Cattri
+
+          cattri :version, "0.1.0", final: true, scope: :class
+        end
+      end
+
+      expect(mod.version).to eq("0.1.0"), "Expected module singleton_class to retain class-level attribute value"
+    end
+
+    it "isolates class attributes across subclasses" do
+      parent = Class.new do
+        include Cattri
+
+        cattri :level, "parent", scope: :class
+      end
+
+      child = Class.new(parent)
+      expect(child.level).to eq("parent")
+
+      child.level = "child"
+
+      expect(parent.level).to eq("parent")
+      expect(child.level).to eq("child")
+    end
+
+    it "applies custom coercion via block during assignment" do
+      klass = Class.new do
+        include Cattri
+
+        cattri :age do |value|
+          Integer(value)
+        end
+      end
+
+      instance = klass.new
+      instance.age = "42"
+
+      expect(instance.age).to eq(42)
+    end
+
+    it "allows inherited initialize to set final attribute once" do
+      base = Class.new do
+        include Cattri
+
+        cattri :token, final: true
+
+        def initialize(token)
+          self.token = token
+        end
+      end
+
+      subclass = Class.new(base)
+      obj = subclass.new("abc123")
+
+      expect(obj.token).to eq("abc123")
+      expect { obj.token = "fail" }.to raise_error(Cattri::AttributeError)
+    end
+  end
+
+  describe "visibility with write-only exposure" do
+    let(:klass) do
+      Class.new do
+        include Cattri
+
+        cattri :token, expose: :write
+        cattri :level, :low, expose: :write, scope: :class
+      end
+    end
+
+    it "keeps the reader private while writer stays public on instances" do
+      instance = klass.new
+
+      expect(klass.public_instance_methods(false)).to include(:token=)
+      expect(klass.private_instance_methods(false)).to include(:token)
+      expect { instance.token }.to raise_error(NoMethodError)
+
+      instance.token = "set"
+      expect(instance.send(:token)).to eq("set")
+    end
+
+    it "marks class-level readers as protected while keeping the writer public" do
+      expect(klass.singleton_class.public_instance_methods(false)).to include(:level=)
+      expect(klass.singleton_class.protected_instance_methods(false)).to include(:level)
+      expect { klass.level }.to raise_error(NoMethodError)
+
+      klass.level = :high
+      expect(klass.send(:level)).to eq(:high)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cattri
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-02 00:00:00.000000000 Z
+date: 2025-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debride
@@ -154,7 +154,6 @@ files:
 - lib/cattri/deferred_attributes.rb
 - lib/cattri/dsl.rb
 - lib/cattri/error.rb
-- lib/cattri/inheritance.rb
 - lib/cattri/initializer_patch.rb
 - lib/cattri/internal_store.rb
 - lib/cattri/introspection.rb
@@ -170,7 +169,6 @@ files:
 - sig/lib/cattri/deferred_attributes.rbs
 - sig/lib/cattri/dsl.rbs
 - sig/lib/cattri/error.rbs
-- sig/lib/cattri/inheritance.rbs
 - sig/lib/cattri/initializer_patch.rbs
 - sig/lib/cattri/internal_store.rbs
 - sig/lib/cattri/introspection.rbs
@@ -185,7 +183,6 @@ files:
 - spec/cattri/deferred_attrributes_spec.rb
 - spec/cattri/dsl_spec.rb
 - spec/cattri/error_spec.rb
-- spec/cattri/inheritance_spec.rb
 - spec/cattri/initializer_patch_spec.rb
 - spec/cattri/internal_store_spec.rb
 - spec/cattri/introspection_spec.rb

data/lib/cattri/inheritance.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Cattri
-  # Handles subclassing behavior for classes that use Cattri.
-  #
-  # This module installs a custom `.inherited` hook on the target class's singleton,
-  # ensuring that attribute definitions and values are deep-copied to the subclass.
-  #
-  # The hook preserves any existing `.inherited` behavior defined on the class,
-  # calling it before applying attribute propagation.
-  module Inheritance
-    # Installs an `inherited` hook on the given class.
-    #
-    # When the class is subclassed, Cattri will copy over attribute metadata and values
-    # using the subclass’s context. This ensures subclass safety and definition isolation.
-    #
-    # Any pre-existing `.inherited` method is preserved and invoked first.
-    #
-    # @param base [Class] the class to install the hook on
-    # @return [void]
-    def self.install(base)
-      singleton = base.singleton_class
-      existing = singleton.instance_method(:inherited) rescue nil # rubocop:disable Style/RescueModifier
-
-      singleton.define_method(:inherited) do |subclass|
-        # :nocov:
-        existing.bind(self).call(subclass) # steep:ignore
-        # :nocov:
-
-        context = Cattri::Context.new(subclass)
-        attribute_registry.send(:copy_attributes_to, context) # steep:ignore
-      end
-    end
-  end
-end

data/sig/lib/cattri/inheritance.rbs

@@ -1,21 +0,0 @@
-module Cattri
-  # Handles subclassing behavior for classes that use Cattri.
-  #
-  # This module installs a custom `.inherited` hook on the target class's singleton,
-  # ensuring that attribute definitions and values are deep-copied to the subclass.
-  #
-  # The hook preserves any existing `.inherited` behavior defined on the class,
-  # calling it before applying attribute propagation.
-  module Inheritance
-    # Installs an `inherited` hook on the given class.
-    #
-    # When the class is subclassed, Cattri will copy over attribute metadata and values
-    # using the subclass’s context. This ensures subclass safety and definition isolation.
-    #
-    # Any pre-existing `.inherited` method is preserved and invoked first.
-    #
-    # @param base [Class] the class to install the hook on
-    # @return [void]
-    def self.install: (::Module base) -> void
-  end
-end

data/spec/cattri/inheritance_spec.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe Cattri::Inheritance do
-  let(:base_class) do
-    Class.new.tap do |klass|
-      klass.include(Cattri::ContextRegistry)
-      klass.singleton_class.include(Cattri::ContextRegistry)
-
-      klass.attr_reader :inherited_called_with
-
-      def klass.inherited(subclass)
-        @inherited_called_with = subclass
-      end
-
-      def klass.inherited_called_with # rubocop:disable Style/TrivialAccessors
-        @inherited_called_with
-      end
-    end
-  end
-
-  before do
-    allow(Cattri::Context).to receive(:new).and_call_original
-    allow_any_instance_of(Cattri::AttributeRegistry).to receive(:copy_attributes_to)
-  end
-
-  describe ".install" do
-    it "preserves and calls existing inherited method" do
-      Cattri::Inheritance.install(base_class)
-
-      subclass = Class.new(base_class) # triggers inherited hook
-
-      expect(base_class.inherited_called_with).to eq(subclass)
-    end
-
-    it "initializes a Cattri::Context for the subclass" do
-      Cattri::Inheritance.install(base_class)
-
-      expect(Cattri::Context).to receive(:new) do |actual_subclass|
-        expect(actual_subclass.superclass).to eq(base_class)
-      end
-
-      Class.new(base_class)
-    end
-
-    it "invokes copy_attributes_to with the subclass context" do
-      context = instance_double(Cattri::Context)
-      allow(Cattri::Context).to receive(:new).and_return(context)
-
-      registry = instance_double(Cattri::AttributeRegistry)
-      allow(base_class).to receive(:attribute_registry).and_return(registry)
-
-      expect(registry).to receive(:copy_attributes_to).with(context)
-
-      Cattri::Inheritance.install(base_class)
-      Class.new(base_class)
-    end
-  end
-end