cattri 0.1.3 → 0.2.0

data/lib/cattri/attribute_registry.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "attribute_compiler"
+
+module Cattri
+  # Cattri::AttributeRegistry is responsible for managing attribute definitions
+  # for a given context (class or module). It validates uniqueness, applies
+  # definition logic, and supports inheritance and introspection.
+  #
+  # It handles both eager and deferred attribute compilation and ensures correct
+  # behavior for `scope: :class`, `final: true`, and other attribute options.
+  class AttributeRegistry
+    # @return [Cattri::Context] the context this registry operates within
+    attr_reader :context
+
+    # Initializes a new registry for the provided context.
+    #
+    # @param context [Cattri::Context]
+    def initialize(context)
+      @context = context
+    end
+
+    # Returns the attributes registered directly on this context.
+    #
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def registered_attributes
+      (@__cattri_registered_attributes ||= {}).dup.freeze # steep:ignore
+    end
+
+    # Returns all known attributes, optionally including inherited definitions.
+    #
+    # @param with_ancestors [Boolean] whether to include ancestors
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def defined_attributes(with_ancestors: false)
+      return registered_attributes unless with_ancestors
+
+      context.attribute_lookup_sources
+             .select { |mod| mod.respond_to?(:attribute_registry, true) }
+             .flat_map { |mod| mod.send(:attribute_registry).registered_attributes.to_a }
+             .to_h
+             .merge(registered_attributes)
+             .freeze
+    end
+
+    # Fetches an attribute by name, or returns nil.
+    #
+    # @param name [String, Symbol]
+    # @param with_ancestors [Boolean]
+    # @return [Cattri::Attribute, nil]
+    def fetch_attribute(name, with_ancestors: false)
+      defined_attributes(with_ancestors: with_ancestors)[name.to_sym]
+    end
+
+    # Fetches an attribute by name, or raises if not found.
+    #
+    # @param name [String, Symbol]
+    # @param with_ancestors [Boolean]
+    # @return [Cattri::Attribute]
+    # @raise [Cattri::AttributeError] if the attribute is not defined
+    def fetch_attribute!(name, with_ancestors: false)
+      defined_attributes(with_ancestors: with_ancestors).fetch(name.to_sym) do
+        raise Cattri::AttributeError, "Attribute :#{name} has not been defined"
+      end
+    end
+
+    # Defines a new attribute and registers it on the current context.
+    #
+    # @param name [String, Symbol] the attribute name
+    # @param value [Object, Proc, nil] default value or initializer
+    # @param options [Hash] attribute options (`:class`, `:final`, etc.)
+    # @yield [*args] optional transformation block used as setter
+    # @return [Array<Symbol>] list of methods defined by this attribute
+    # @raise [Cattri::AttributeError] if the name is already defined
+    def define_attribute(name, value, **options, &block)
+      name = name.to_sym
+      validate_unique!(name)
+
+      options_with_default = options.merge(default: value)
+      attribute = Cattri::Attribute.new(
+        name,
+        defined_in: context.target,
+        **options_with_default,
+        &block
+      )
+
+      register_attribute(attribute)
+      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.
+    #
+    # @param name [Symbol]
+    # @raise [Cattri::AttributeError]
+    def validate_unique!(name)
+      return unless instance_variable_defined?(:@__cattri_registered_attributes)
+      return unless @__cattri_registered_attributes.key?(name)
+
+      raise Cattri::AttributeError, "Attribute :#{name} has already been defined"
+    end
+
+    # Registers an attribute and applies or defers its definition.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def register_attribute(attribute)
+      unless instance_variable_defined?(:@__cattri_registered_attributes)
+        (@__cattri_registered_attributes ||= {}) # steep:ignore
+      end
+
+      @__cattri_registered_attributes[attribute.name] = attribute
+      return defer_definition(attribute) if context.defer_definitions?
+
+      apply_definition!(attribute)
+    end
+
+    # Defers the attribute definition if in a module context.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def defer_definition(attribute)
+      context.ensure_deferred_support!
+      context.target.defer_attribute(attribute) # steep:ignore
+    end
+
+    # Applies the attribute definition using the compiler.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    # @raise [Cattri::AttributeError]
+    def apply_definition!(attribute)
+      Cattri::AttributeCompiler.define_accessor(attribute, context)
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Attribute #{attribute.name} could not be defined. Error: #{e.message}"
+    end
+  end
+end

data/lib/cattri/context.rb

@@ -1,171 +1,189 @@
 # frozen_string_literal: true
 
 require "set"
+require_relative "deferred_attributes"
 
 module Cattri
-  # Provides a controlled interface for defining methods and instance variables
-  # on a target class or module. Used internally by Cattri to define attribute
-  # readers and writers while preserving access visibility and tracking which
-  # methods were explicitly created.
+  # Cattri::Context encapsulates the class or module that attributes are being defined on.
   #
-  # This abstraction allows class and instance attribute logic to be composed
-  # consistently and safely across both standard and singleton contexts.
+  # It provides a safe interface for dynamically defining methods and tracking metadata,
+  # such as declared accessors, access visibility, and deferred attribute declarations.
+  #
+  # It handles:
+  # - Attribute method definitions (reader/writer/predicate)
+  # - Visibility enforcement
+  # - Target resolution (instance vs. class-level)
+  # - Method deduplication and tracking
+  #
+  # All method definitions occur directly on the resolved target (e.g., the class or its singleton).
   class Context
-    # Allowed Ruby visibility levels for methods.
-    ACCESS_LEVELS = %i[public protected private].freeze
-    private_constant :ACCESS_LEVELS
-
-    # @return [Module, Class] the receiver to which accessors will be added
+    # The class or module that owns the attributes.
+    #
+    # @return [Module]
     attr_reader :target
 
-    # Initializes a new context wrapper around the given target.
-    #
-    # @param target [Module, Class] the object to define methods or ivars on
+    # @param target [Module, Class]
     def initialize(target)
       @target = target
-      @defined_methods = Set.new
     end
 
-    # Returns the singleton class of the target.
+    # Returns a frozen copy of all attribute methods explicitly defined by this context.
     #
-    # This is used to define methods on the class itself (not its instances).
+    # This does not include inherited or module-defined methods.
     #
-    # @return [Class]
-    def singleton
-      @target.singleton_class
+    # @return [Hash{Symbol => Set<Symbol>}] map of attribute name to defined method names
+    def defined_methods
+      (@__cattri_defined_methods ||= {}).dup.freeze # steep:ignore
     end
 
-    # Checks whether a method is already defined on the target.
-    #
-    # This includes public, protected, private, and previously defined methods
-    # via this context (tracked in `@defined_methods`).
+    # Whether this target should defer method definitions (e.g., if it's a module).
     #
-    # @param method [String, Symbol]
     # @return [Boolean]
-    def method_defined?(method)
-      @target.method_defined?(method) ||
-        @target.private_method_defined?(method) ||
-        @target.protected_method_defined?(method) ||
-        @defined_methods.include?(method.to_sym)
+    def defer_definitions?
+      @target.is_a?(Module) && !@target.is_a?(Class)
     end
 
-    # Defines a method on the appropriate context (class or singleton).
+    # Ensures the target includes Cattri::DeferredAttributes if needed.
     #
-    # If the method already exists, it is not redefined. Visibility is applied
-    # according to the attribute's `:access` setting (defaulting to `:public`).
+    # Used to prepare modules for later application of attributes when included elsewhere.
     #
-    # @param attribute [Cattri::Attribute]
-    # @param name [Symbol, nil] optional method name override
-    # @yield the method implementation
-    # @raise [Cattri::AttributeDefinitionError] if method definition fails
     # @return [void]
-    def define_method(attribute, name: nil, &block)
-      name = (name || attribute.name).to_sym
-      return if method_defined?(name)
+    def ensure_deferred_support!
+      return if @target < Cattri::DeferredAttributes
 
-      define_method!(attribute, name: name, &block)
+      @target.extend(Cattri::DeferredAttributes)
     end
 
-    # Defines a method on the target class or singleton class, regardless of whether it already exists.
+    # All ancestors and included modules used for attribute lookup and inheritance.
     #
-    # This bypasses any checks for prior definition and forcibly installs the method using `define_method`.
-    # The method will be assigned visibility based on the attribute's `:access` setting.
+    # @return [Array<Module>]
+    def attribute_lookup_sources
+      ([@target] + @target.ancestors + @target.singleton_class.included_modules).uniq
+    end
+
+    # Defines a method for the given attribute unless already defined locally.
     #
-    # Used internally by attribute definers to (re)define writers, readers, or callables.
+    # Respects attribute-level force overwrite and enforces visibility rules.
     #
-    # @param attribute [Cattri::Attribute] the attribute whose context and access rules apply
-    # @param name [Symbol, nil] the method name to define (defaults to attribute name)
-    # @yield the method body to define
-    # @raise [Cattri::AttributeDefinitionError] if method definition fails
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol, nil] optional method name override
+    # @yield method implementation block
+    # @raise [Cattri::AttributeError] if method is already defined and not forced
     # @return [void]
-    def define_method!(attribute, name: nil, &block)
+    def define_method(attribute, name: nil, &block)
+      name = (name || attribute.name).to_sym
       target = target_for(attribute)
 
-      begin
-        target.define_method(name, &block)
-        @defined_methods << name unless method_defined?(name)
-        apply_access(name, attribute)
-      rescue StandardError => e
-        raise Cattri::AttributeDefinitionError.new(target, attribute, e)
+      if method_defined?(attribute, name: name)
+        raise Cattri::AttributeError, "Method `:#{name}` already defined on #{target}"
       end
-    end
 
-    # Checks whether the target has the given instance variable.
-    #
-    # @param name [Symbol, String]
-    # @return [Boolean]
-    def ivar_defined?(name)
-      @target.instance_variable_defined?(sanitize_ivar(name))
+      define_method!(target, attribute, name, &block)
     end
 
-    # Retrieves the value of the specified instance variable on the target.
+    # Checks if the given method is already defined on the resolved target.
     #
-    # @param name [Symbol, String]
-    # @return [Object]
-    def ivar_get(name)
-      @target.instance_variable_get(sanitize_ivar(name))
-    end
-
-    # Assigns a value to the specified instance variable on the target.
+    # Only checks methods directly defined on the class or singleton—not ancestors.
     #
-    # @param name [Symbol, String]
-    # @param value [Object]
-    # @return [void]
-    def ivar_set(name, value)
-      @target.instance_variable_set(sanitize_ivar(name), value)
-    end
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol, nil]
+    # @return [Boolean]
+    def method_defined?(attribute, name: nil)
+      normalized_name = (name || attribute.name).to_sym
+      target = target_for(attribute)
 
-    # Memoizes a value in the instance variable only if not already defined.
-    #
-    # @param name [Symbol, String]
-    # @param value [Object]
-    # @return [Object] the existing or assigned value
-    def ivar_memoize(name, value)
-      return ivar_get(name) if ivar_defined?(name)
+      defined_locally = (
+        target.public_instance_methods(false) +
+          target.protected_instance_methods(false) +
+          target.private_instance_methods(false)
+      )
 
-      ivar_set(name, value)
+      defined_locally.include?(normalized_name) ||
+        __cattri_defined_methods[attribute.name].include?(normalized_name)
     end
 
     private
 
-    # Selects the correct definition target based on attribute type.
+    # Internal tracking of explicitly defined methods per attribute.
+    #
+    # @return [Hash{Symbol => Set<Symbol>}]
+    def __cattri_defined_methods
+      @__cattri_defined_methods ||= Hash.new { |h, k| h[k] = Set.new }
+    end
+
+    # Determines whether to define the method on the instance or singleton.
     #
     # @param attribute [Cattri::Attribute]
-    # @return [Module] either the target or its singleton class
+    # @return [Module]
     def target_for(attribute)
-      attribute.class_level? ? singleton : @target
+      attribute.class_attribute? ? @target.singleton_class : @target
     end
 
-    # Validates and normalizes access level.
+    # Defines the method and applies its access visibility.
     #
-    # @param access [Symbol, String, nil]
-    # @return [Symbol] a valid visibility level
-    def validate_access(access)
-      access = (access || :public).to_sym
-      return access if ACCESS_LEVELS.include?(access)
+    # @param target [Module]
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol]
+    # @yield method implementation
+    # @return [void]
+    def define_method!(target, attribute, name, &block)
+      target.class_eval { define_method(name, &block) } # steep:ignore
+      __cattri_defined_methods[attribute.name] << name
 
-      warn "[Cattri] `#{access.inspect}` is not a supported access level, defaulting to :public"
-      :public
+      apply_visibility!(target, name, attribute)
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to define accessor methods for `:#{name}` on #{target}. Error: #{e.message}"
     end
 
-    # Applies method visibility to a newly defined method.
+    # Applies visibility (`public`, `protected`, `private`) to a method.
+    #
+    # Skips application for `:public` (default in Ruby).
     #
-    # @param method_name [Symbol]
+    # @param target [Module]
+    # @param name [Symbol]
     # @param attribute [Cattri::Attribute]
     # @return [void]
-    def apply_access(method_name, attribute)
-      return if attribute.public?
+    def apply_visibility!(target, name, attribute)
+      visibility = effective_visibility(attribute, name)
+      return if visibility == :public
 
-      access = validate_access(attribute[:access])
-      Module.instance_method(access).bind(@target).call(method_name)
+      Module.instance_method(visibility).bind(target).call(name)
     end
 
-    # Ensures consistent formatting for ivar keys.
+    # Determines the effective visibility of the attribute.
     #
-    # @param name [Symbol, String]
+    # - If the attribute has no public writer or reader (i.e., `expose: :write` or `:none`)
+    #   - Returns `:protected` for class-level attributes
+    #   - 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]
-    def sanitize_ivar(name)
-      :"@#{name.to_s.delete_prefix("@")}"
+    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)
+
+      Cattri::AttributeOptions.validate_visibility!(attribute.visibility)
+    end
+
+    # 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
+    def internal_method?(attribute, name)
+      return attribute.internal_writer? if name.to_s.end_with?("=")
+
+      attribute.internal_reader?
     end
   end
 end

data/lib/cattri/context_registry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "attribute_registry"
+require_relative "context"
+
+module Cattri
+  # Provides per-class or per-module access to the attribute registry and method definition context.
+  #
+  # This module is included into both the base and singleton class of any class using Cattri.
+  # It initializes and exposes a lazily-evaluated `attribute_registry` and `context` specific
+  # to the current scope, enabling safe and isolated attribute handling.
+  module ContextRegistry
+    private
+
+    # Returns the attribute definition registry for this class or module.
+    #
+    # The registry is responsible for tracking all defined attributes, both class-level and
+    # instance-level, handling application logic, and copying across subclasses where needed.
+    #
+    # @return [Cattri::AttributeRegistry] the registry used to define and apply attributes
+    def attribute_registry
+      @attribute_registry ||= Cattri::AttributeRegistry.new(context)
+    end
+
+    # Returns the method definition context for this class or module.
+    #
+    # The context wraps the current target (class or module) and provides utilities
+    # for defining attribute methods (readers, writers, predicates), managing visibility,
+    # and recording declared methods to avoid duplication.
+    #
+    # @return [Cattri::Context] the context used for method definition and visibility tracking
+    def context
+      @context ||= Context.new(self) # steep:ignore
+    end
+  end
+end

data/lib/cattri/deferred_attributes.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Cattri
+  # Provides support for defining attributes within a module that should be
+  # applied later to any class or module that includes or extends it.
+  #
+  # This allows DSL modules to define Cattri attributes without prematurely
+  # applying them to themselves, deferring application to the including/extending context.
+  module DeferredAttributes
+    # Hook into the module extension lifecycle to ensure deferred attributes are
+    # applied when the module is included or extended.
+    #
+    # @param base [Module] the module that extended this module
+    # @return [void]
+    def self.extended(base)
+      return if base.singleton_class.ancestors.include?(Hook)
+
+      base.singleton_class.prepend(Hook)
+    end
+
+    # Hook methods for inclusion/extension that trigger deferred application.
+    module Hook
+      # Called when a module including `DeferredAttributes` is included into another module/class.
+      #
+      # @param target [Module] the including class or module
+      # @return [void]
+      def included(target)
+        apply_deferred_attributes(target) if respond_to?(:apply_deferred_attributes) # steep:ignore
+      end
+
+      # Called when a module including `DeferredAttributes` is extended into another module/class.
+      #
+      # @param target [Module] the extending class or module
+      # @return [void]
+      def extended(target)
+        apply_deferred_attributes(target) if respond_to?(:apply_deferred_attributes) # steep:ignore
+      end
+    end
+
+    # Registers an attribute to be applied later when this module is included or extended.
+    #
+    # @param attribute [Cattri::Attribute] the attribute to defer
+    # @return [void]
+    def defer_attribute(attribute)
+      deferred_attributes[attribute.name] = attribute
+    end
+
+    # Applies all deferred attributes to the target class or module.
+    #
+    # This is triggered automatically by the {Hook} on `included` or `extended`.
+    #
+    # @param target [Module] the class or module to apply the attributes to
+    # @return [void]
+    def apply_deferred_attributes(target)
+      context = Cattri::Context.new(target)
+
+      deferred_attributes.each_value do |attribute|
+        Cattri::AttributeCompiler.define_accessor(attribute, context)
+      end
+    end
+
+    private
+
+    # Internal storage of deferred attributes for this module.
+    #
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def deferred_attributes
+      @deferred_attributes ||= {}
+    end
+  end
+end

data/lib/cattri/dsl.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Provides the primary DSL for defining class-level and instance-level attributes.
+  #
+  # This module is extended into any class or module that includes Cattri,
+  # and exposes methods like `cattri` and `final_cattri` for concise attribute declaration.
+  #
+  # All attributes are defined through the underlying attribute registry and
+  # are associated with method accessors (reader, writer, predicate) based on options.
+  module Dsl
+    # Defines a new attribute with optional default, coercion, and visibility options.
+    #
+    # The attribute can be defined with a static value, a lazy-evaluated block,
+    # or with additional options like `final`, `predicate`, or `expose`.
+    #
+    # The attribute will be defined as either class-level or instance-level
+    # depending on the `scope:` option.
+    #
+    # @param name [Symbol, String] the attribute name
+    # @param value [Object, nil] optional static value or default
+    # @param options [Hash] additional attribute configuration
+    # @option options [Boolean] :scope whether this is a class-level (:class) or instance-level (:instance) attribute
+    # @option options [Boolean] :final whether the attribute is write-once
+    # @option options [Boolean] :predicate whether to define a predicate method
+    # @option options [Symbol] :expose whether to expose `:read`, `:write`, `:read_write`, or `:none`
+    # @option options [Symbol] :visibility the visibility for generated methods (`:public`, `:protected`, `:private`)
+    # @yield optional block to lazily evaluate the attribute’s default value
+    # @return [Array<Symbol>] the defined methods
+    def cattri(name, value = nil, **options, &block)
+      options = { visibility: __cattri_visibility }.merge(options) # steep:ignore
+      attribute_registry.define_attribute(name, value, **options, &block) # steep:ignore
+    end
+
+    # Defines a write-once (final) attribute.
+    #
+    # Final attributes can be written only once and raise on re-assignment.
+    # This is equivalent to `cattri(..., final: true)`.
+    #
+    # @param name [Symbol, String] the attribute name
+    # @param value [Object, nil] static or lazy default value
+    # @param options [Hash] additional attribute configuration
+    # @option options [Boolean] :scope whether this is a class-level (:class) or instance-level (:instance) attribute
+    # @option options [Boolean] :final whether the attribute is write-once
+    # @option options [Boolean] :predicate whether to define a predicate method
+    # @option options [Symbol] :expose whether to expose `:read`, `:write`, `:read_write`, or `:none`
+    # @option options [Symbol] :visibility the visibility for generated methods (`:public`, `:protected`, `:private`)
+    # @yield optional block to lazily evaluate the default
+    # @return [Array<Symbol>] the defined methods
+    def final_cattri(name, value, **options, &block)
+      cattri(name, value, **options.merge(final: true), &block) # steep:ignore
+    end
+  end
+end