cattri 0.1.3 → 0.2.0

data/lib/cattri/error.rb

@@ -3,103 +3,30 @@
 module Cattri
   # Base error class for all exceptions raised by Cattri.
   #
-  # All Cattri-specific errors inherit from this class.
+  # All Cattri-specific errors inherit from this class, allowing unified
+  # rescue handling at the framework level.
+  #
+  # The backtrace is preserved and may be filtered before raising.
   #
   # @example
   #   rescue Cattri::Error => e
   #     puts "Something went wrong with Cattri: #{e.message}"
-  class Error < StandardError; end
-
-  # Parent class for all attribute-related errors in Cattri.
-  #
-  # This includes definition conflicts, setter failures, or configuration issues.
-  #
-  # @example
-  #   rescue Cattri::AttributeError => e
-  #     puts "Attribute error: #{e.message}"
-  class AttributeError < Cattri::Error; end
-
-  # Raised when a class or instance attribute is defined more than once.
-  #
-  # This helps detect naming collisions during DSL usage.
-  #
-  # @example
-  #   raise Cattri::AttributeDefinedError.new(attribute)
-  #
-  # @example
-  #   rescue Cattri::AttributeDefinedError => e
-  #     puts e.message
-  class AttributeDefinedError < Cattri::AttributeError
-    # @param type [Symbol, String] either :class or :instance
-    # @param name [Symbol, String] the name of the missing attribute
-    def initialize(type, name)
-      super("#{type.capitalize} attribute :#{name} has already been defined")
+  class Error < StandardError
+    # Initializes the error with an optional message and caller backtrace.
+    #
+    # @param msg [String, nil] the error message
+    # @param backtrace [Array<String>] optional backtrace (defaults to `caller`)
+    def initialize(msg = nil, backtrace = caller)
+      super(msg)
+      set_backtrace(backtrace)
     end
   end
 
-  # Raised when attempting to access or modify an attribute that has not been defined.
-  #
-  # This applies to both class-level and instance-level attributes.
-  # It is typically raised when calling `.class_attribute_setter` or `.instance_attribute_setter`
-  # on a name that does not exist or lacks the expected method (e.g., writer).
-  #
-  # @example
-  #   raise Cattri::AttributeNotDefinedError.new(:class, :foo)
-  #   # => Class attribute :foo has not been defined
+  # Raised for any attribute-related definition or usage failure.
   #
-  # @example
-  #   rescue Cattri::AttributeNotDefinedError => e
-  #     puts e.message
-  class AttributeNotDefinedError < Cattri::AttributeError
-    # @param type [Symbol, String] either :class or :instance
-    # @param name [Symbol, String] the name of the missing attribute
-    def initialize(type, name)
-      super("#{type.capitalize} attribute :#{name} has not been defined")
-    end
-  end
-
-  # Raised when a method definition (reader, writer, or callable) fails.
+  # This includes method conflicts, invalid configuration, and
+  # write attempts on `final` attributes.
   #
-  # This wraps the original error that occurred during `define_method` or visibility handling.
-  #
-  # @example
-  #   raise Cattri::AttributeDefinitionError.new(target, attribute, error)
-  #
-  # @example
-  #   rescue Cattri::AttributeDefinitionError => e
-  #     puts e.message
-  class AttributeDefinitionError < Cattri::AttributeError
-    # @param target [Module] the class or module receiving the method
-    # @param attribute [Cattri::Attribute] the attribute being defined
-    # @param error [StandardError] the original raised exception
-    def initialize(target, attribute, error)
-      super("Failed to define method :#{attribute.name} on #{target}. Error: #{error.message}")
-      set_backtrace(error.backtrace)
-    end
-  end
-
-  # Raised when an unsupported attribute type is passed to Cattri.
-  #
-  # Valid types are typically `:class` and `:instance`. Any other value is invalid.
-  #
-  # @example
-  #   raise Cattri::UnsupportedTypeError.new(:foo)
-  #   # => Attribute type :foo is not supported
-  class UnsupportedTypeError < Cattri::AttributeError
-    # @param type [Symbol] the invalid type that triggered the error
-    def initialize(type)
-      super("Attribute type :#{type} is not supported")
-    end
-  end
-
-  # Raised when a block is provided when defining a group of attributes `cattr :attr_a, :attr_b do ... end`
-  #
-  # @example
-  #   raise Cattri::AmbiguousBlockError
-  #   # => Cannot define multiple attributes with a block
-  class AmbiguousBlockError < Cattri::AttributeError
-    def initialize
-      super("Cannot define multiple attributes with a block")
-    end
-  end
+  # @see Cattri::Error
+  class AttributeError < Error; end
 end

data/lib/cattri/inheritance.rb

@@ -0,0 +1,35 @@
+# 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/lib/cattri/initializer_patch.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Provides a patch to `#initialize` that ensures all final attributes
+  # are initialized with their default values if not already set.
+  #
+  # This module is prepended into Cattri-including classes to enforce
+  # write-once semantics for instance-level `final: true` attributes.
+  #
+  # @example
+  #   class MyClass
+  #     include Cattri
+  #
+  #     cattri :id, -> { SecureRandom.uuid }, final: true
+  #   end
+  #
+  #   MyClass.new # => will have a UUID assigned to @id unless explicitly set
+  module InitializerPatch
+    # Hooked constructor that initializes final attributes using their defaults
+    # if no value has been set by the user.
+    #
+    # @param args [Array] any positional arguments passed to initialize
+    # @param kwargs [Hash] any keyword arguments passed to initialize
+    # @yield an optional block to pass to `super`
+    # @return [void]
+    def initialize(*args, **kwargs, &block)
+      super
+
+      self.class.send(:attribute_registry).registered_attributes.each_value do |attribute| # steep:ignore
+        next if cattri_variable_defined?(attribute.ivar) # steep:ignore
+        next unless attribute.final?
+
+        cattri_variable_set(attribute.ivar, attribute.evaluate_default) # steep:ignore
+      end
+    end
+  end
+end

data/lib/cattri/internal_store.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Cattri
+  # Internal representation of a stored attribute value.
+  AttributeValue = Struct.new(:value, :final)
+
+  # Provides an internal storage mechanism for attribute values defined via `cattri`.
+  #
+  # This module is included into any class or module using Cattri and replaces
+  # direct instance variable access with a namespaced store.
+  #
+  # It supports enforcement of `final` semantics and tracks explicit assignments.
+  module InternalStore
+    # Checks whether the internal store contains a value for the given key.
+    #
+    # @param key [String, Symbol] the attribute name or instance variable
+    # @return [Boolean] true if a value is present
+    def cattri_variable_defined?(key)
+      __cattri_store.key?(normalize_ivar(key))
+    end
+
+    # Fetches the value for a given attribute key from the internal store.
+    #
+    # @param key [String, Symbol] the attribute name or instance variable
+    # @return [Object, nil] the stored value, or nil if not present
+    def cattri_variable_get(key)
+      __cattri_store[normalize_ivar(key)]&.value
+    end
+
+    # Sets a value in the internal store for the given attribute key.
+    #
+    # Enforces final semantics if a final value was already set.
+    #
+    # @param key [String, Symbol] the attribute name or instance variable
+    # @param value [Object] the value to store
+    # @param final [Boolean] whether the value should be locked as final
+    # @return [Object] the stored value
+    def cattri_variable_set(key, value, final: false)
+      key = normalize_ivar(key)
+      guard_final!(key)
+
+      __cattri_store[key] = AttributeValue.new(value, final)
+      __cattri_set_variables << key
+
+      value
+    end
+
+    # Evaluates and sets a value for the given key only if it hasn't already been set.
+    #
+    # If a value is already present, it is returned as-is. Otherwise, the provided block
+    # is called to compute the value, which is then stored. If `final: true` is passed,
+    # the value is marked as final and cannot be reassigned.
+    #
+    # @param key [String, Symbol] the attribute name or instance variable
+    # @param final [Boolean] whether to mark the value as final (immutable once set)
+    # @yieldreturn [Object] the value to memoize if not already present
+    # @return [Object] the existing or newly memoized value
+    # @raise [Cattri::AttributeError] if attempting to overwrite a final value
+    def cattri_variable_memoize(key, final: false)
+      key = normalize_ivar(key)
+      return cattri_variable_get(key) if cattri_variable_defined?(key)
+
+      value = yield
+      cattri_variable_set(key, value, final: final)
+    end
+
+    private
+
+    # Returns the internal storage hash used for attribute values.
+    #
+    # @return [Hash<Symbol, Cattri::AttributeValue>]
+    def __cattri_store
+      @__cattri_store ||= {}
+    end
+
+    # Returns the set of attribute keys that have been explicitly assigned.
+    #
+    # @return [Set<Symbol>]
+    def __cattri_set_variables
+      @__cattri_set_variables ||= Set.new
+    end
+
+    # Normalizes the attribute key to a symbol without `@` prefix.
+    #
+    # @param key [String, Symbol]
+    # @return [Symbol]
+    def normalize_ivar(key)
+      key.to_s.delete_prefix("@").to_sym.freeze
+    end
+
+    # Raises if attempting to modify a value that was marked as final.
+    #
+    # @param key [Symbol]
+    # @raise [Cattri::AttributeError] if the key is final and already set
+    def guard_final!(key)
+      return unless cattri_variable_defined?(key)
+
+      existing = __cattri_store[key]
+      raise Cattri::AttributeError, "Cannot modify final attribute :#{key}" if existing.final
+    end
+  end
+end

data/lib/cattri/introspection.rb

@@ -1,70 +1,77 @@
 # frozen_string_literal: true
 
 module Cattri
-  # Adds debugging and inspection helpers for reading the current values of
-  # class- and instance-level attributes defined via Cattri.
+  # Provides a read-only interface for inspecting attributes defined via the Cattri DSL.
   #
-  # This module is intended for use in development and test environments to
-  # help capture attribute state at a given moment.
-  #
-  # It can be included in any class or module that uses {Cattri::ClassAttributes}
-  # or {Cattri::InstanceAttributes}.
-  #
-  # @example
-  #   class MyConfig
-  #     extend Cattri::ClassAttributes
-  #     include Cattri::Introspection
-  #
-  #     cattr :items, default: []
-  #   end
-  #
-  #   MyConfig.items << :a
-  #   MyConfig.snapshot_class_attributes #=> { items: [:a] }
+  # When included, adds class-level methods to:
+  # - Check if an attribute is defined
+  # - Retrieve attribute definitions
+  # - List defined attribute methods
+  # - Trace the origin of an attribute
   module Introspection
-    # Hook called when the module is included. Extends the base with class methods.
-    #
-    # @param base [Class, Module]
+    # @param base [Class, Module] the target that includes `Cattri`
     # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
     end
 
-    # Class-level methods for introspection.
+    # @api public
+    # Class-level introspection methods exposed via `.attribute_defined?`, `.attribute`, etc.
     module ClassMethods
-      # Returns a hash of current class attribute values.
+      # Returns true if the given attribute has been defined on this class or any ancestor.
       #
-      # @return [Hash<Symbol, Object>] a snapshot of each defined class attribute
-      def snapshot_class_attributes
-        return {} unless respond_to?(:class_attributes)
+      # @param name [Symbol, String] the attribute name
+      # @return [Boolean]
+      def attribute_defined?(name)
+        !!attribute(name)
+      end
 
-        class_attributes.each_with_object({}) do |attribute, hash|
-          hash[attribute] = send(attribute)
-        end.freeze
+      # Returns the attribute definition for the given name.
+      #
+      # Includes inherited definitions if available.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [Cattri::Attribute, nil]
+      def attribute(name)
+        attribute_registry.defined_attributes(with_ancestors: true)[name.to_sym] # steep:ignore
       end
 
-      # @!method snapshot_cattrs
-      #   Alias for {.snapshot_class_attributes}
-      #   @see .snapshot_class_attributes
-      alias snapshot_cattrs snapshot_class_attributes
-    end
+      # Returns a list of attribute names defined on this class.
+      #
+      # Includes inherited attributes if `with_ancestors` is true.
+      #
+      # @param with_ancestors [Boolean]
+      # @return [Array<Symbol>]
+      def attributes(with_ancestors: false)
+        attribute_registry.defined_attributes(with_ancestors: with_ancestors).keys # steep:ignore
+      end
+
+      # Returns a hash of attribute definitions defined on this class.
+      #
+      # Includes inherited attributes if `with_ancestors` is true.
+      #
+      # @param with_ancestors [Boolean]
+      # @return [Hash{Symbol => Cattri::Attribute}]
+      def attribute_definitions(with_ancestors: false)
+        attribute_registry.defined_attributes(with_ancestors: with_ancestors) # steep:ignore
+      end
 
-    # Returns a hash of current instance attribute values for this object.
-    #
-    # @return [Hash<Symbol, Object>] a snapshot of each defined instance attribute
-    def snapshot_instance_attributes
-      return {} unless self.class.respond_to?(:instance_attributes)
+      # Returns a hash of all methods defined by Cattri attributes.
+      #
+      # This includes accessors, writers, and predicates where applicable.
+      #
+      # @return [Hash{Symbol => Set<Symbol>}]
+      def attribute_methods
+        context.defined_methods # steep:ignore
+      end
 
-      self.class.instance_attributes.each_with_object({}) do |attribute, hash|
-        hash[attribute] = send(attribute)
-      rescue NoMethodError
-        # Catch for write-only methods
-        hash[attribute] = instance_variable_get(:"@#{attribute}")
+      # Returns the original class or module where the given attribute was defined.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [Module, nil]
+      def attribute_source(name)
+        attribute(name)&.defined_in
       end
     end
-
-    # @!method snapshot_iattrs
-    #   Alias for {#snapshot_instance_attributes}
-    #   @see #snapshot_instance_attributes
-    alias snapshot_iattrs snapshot_instance_attributes
   end
 end

data/lib/cattri/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Cattri
-  VERSION = "0.1.3"
+  # :nocov:
+  VERSION = "0.2.0"
+  # :nocov:
 end

data/lib/cattri.rb

@@ -1,119 +1,58 @@
 # frozen_string_literal: true
 
-require_relative "cattri/version"
-require_relative "cattri/visibility"
-require_relative "cattri/class_attributes"
-require_relative "cattri/instance_attributes"
+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"
+require_relative "cattri/visibility"
 
-# The primary entry point for the Cattri gem.
-#
-# When included, it enables both class-level and instance-level attribute definitions
-# via `cattr` and `iattr`-style DSLs, providing a lightweight alternative to traditional
-# `attr_*` and `cattr_*` patterns.
-#
-# The module includes:
-# - `Cattri::ClassAttributes` (for class-level configuration)
-# - `Cattri::InstanceAttributes` (for instance-level configuration)
-# - `Cattri::Visibility` (for default access control)
-#
-# It also installs a custom `.inherited` hook to ensure that subclassed classes
-# receive deep copies of attribute metadata and current values.
-#
-# Note: The `Cattri::Introspection` module must be included manually if needed.
-#
-# @example Using both class and instance attributes
-#   class Config
-#     include Cattri
+# Main entrypoint for the Cattri DSL.
 #
-#     cattr :enabled, default: true
-#     iattr :name, default: "anonymous"
-#   end
+# When included in a class or module, this installs both class-level and instance-level
+# attribute handling logic, visibility tracking, subclass inheritance propagation,
+# and default value enforcement.
 #
-#   Config.enabled          # => true
-#   Config.new.name         # => "anonymous"
+# It supports:
+# - Defining class or instance attributes using `cattri` or `final_cattri`
+# - Visibility tracking and method scoping
+# - Write-once semantics for `final: true` attributes
+# - Safe method generation with introspection support
 module Cattri
-  # Hook triggered when `include Cattri` is called.
+  # Sets up the Cattri DSL on the including class or module.
   #
-  # Installs core attribute DSLs and visibility settings into the host class.
-  # Also injects `.inherited` logic to propagate attribute metadata to subclasses.
+  # Includes internal storage and registry infrastructure into both the base and its singleton class,
+  # prepends initialization logic, extends visibility and DSL handling, and installs the
+  # subclassing hook to propagate attributes to descendants.
   #
-  # @param base [Class, Module] the receiving class or module
+  # @param base [Class, Module] the target that includes `Cattri`
   # @return [void]
   def self.included(base)
-    base.extend(Cattri::Visibility)
-    base.extend(Cattri::ClassAttributes)
-    base.include(Cattri::InstanceAttributes)
-
-    base.singleton_class.define_method(:inherited) do |subclass|
-      super(subclass) if defined?(super)
-
-      %i[class instance].each do |type|
-        Cattri.send(:copy_attributes_to, self, subclass, type)
-      end
+    [base, base.singleton_class].each do |mod|
+      mod.include(Cattri::InternalStore)
+      mod.include(Cattri::ContextRegistry)
     end
-  end
-
-  class << self
-    private
-
-    # Copies attribute definitions and backing values from one class to a subclass.
-    #
-    # This is invoked automatically via the `.inherited` hook to ensure
-    # subclass isolation and metadata integrity.
-    #
-    # @param origin [Class] the parent class
-    # @param subclass [Class] the child class inheriting the attributes
-    # @param type [Symbol] either `:class` or `:instance`
-    # @return [void]
-    # @raise [Cattri::AttributeError] if an ivar copy operation fails
-    def copy_attributes_to(origin, subclass, type)
-      ivar = :"@__cattri_#{type}_attributes"
-      attributes = origin.instance_variable_get(ivar) || {}
 
-      subclass_attributes = attributes.transform_values do |attribute|
-        copy_ivar_to(origin, subclass, attribute)
-        attribute.dup
-      end
+    base.prepend(Cattri::InitializerPatch)
+    base.extend(Cattri::Visibility)
+    base.extend(Cattri::Dsl)
+    base.extend(ClassMethods)
 
-      subclass.instance_variable_set(ivar, subclass_attributes)
-    end
+    Cattri::Inheritance.install(base)
+  end
 
-    # Duplicates the current value of an attribute's backing ivar to the subclass.
-    #
-    # Falls back to raw assignment if duplication is not supported.
+  # Provides opt-in class-level introspection support.
+  #
+  # This allows users to call methods like `.attribute_defined?`, `.attribute_methods`, etc.,
+  # to inspect which attributes have been defined.
+  module ClassMethods
+    # Enables Cattri's attribute introspection methods on the current class.
     #
-    # @param origin [Class] the parent class
-    # @param subclass [Class] the receiving subclass
-    # @param attribute [Cattri::Attribute]
     # @return [void]
-    # @raise [Cattri::AttributeError] if the value cannot be safely duplicated
-    def copy_ivar_to(origin, subclass, attribute)
-      value = duplicate_value(origin, attribute)
-      subclass.instance_variable_set(attribute.ivar, value)
-    end
-
-    # Attempts to duplicate the value of an attribute's backing ivar.
-    #
-    # This method first tries to duplicate the value stored in the ivar.
-    # If duplication is not supported due to the object's nature (e.g., it is frozen or immutable),
-    # it will fall back to returning the original value.
-    #
-    # @param origin [Class] the parent class from which the ivar value is being retrieved
-    # @param attribute [Cattri::Attribute] the attribute for which the ivar value is being duplicated
-    # @return [Object] the duplicated value or the original value if duplication is not possible
-    # @raise [Cattri::AttributeError] if duplication fails due to unsupported object types
-    def duplicate_value(origin, attribute)
-      value = origin.instance_variable_get(attribute.ivar)
-
-      begin
-        value.dup
-      rescue TypeError, FrozenError
-        puts "HERE"
-        value
-      end
-    rescue StandardError => e
-      raise Cattri::AttributeError, "Failed to duplicate value for attribute #{attribute}. Error: #{e.message}"
+    def with_cattri_introspection
+      include(Cattri::Introspection) # steep:ignore
     end
   end
 end