cattri 0.1.3 → 0.2.0

data/cattri.gemspec

@@ -16,25 +16,25 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["homepage_uri"]     = spec.homepage
-  spec.metadata["source_code_uri"]  = "https://github.com/bnlucas/cattri"
+  spec.metadata["source_code_uri"]  = spec.homepage
   spec.metadata["changelog_uri"]    = "https://github.com/bnlucas/cattri/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/cattri"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
+    (`git ls-files -z`.split("\x0") + %w[README.md LICENSE.txt]).uniq
   end
 
   # Runtime dependencies
   # spec.add_dependency "gem"
 
   # Development dependencies
+  spec.add_development_dependency "debride"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "simplecov-cobertura"
   spec.add_development_dependency "simplecov-html"
+  spec.add_development_dependency "steep"
   spec.add_development_dependency "yard"
 end

data/lib/cattri/attribute.rb

@@ -1,204 +1,168 @@
 # frozen_string_literal: true
 
-require_relative "error"
+require_relative "attribute_options"
 
 module Cattri
-  # Represents a single attribute definition in Cattri.
+  # @internal
   #
-  # This class encapsulates metadata and behavior for a declared attribute,
-  # including name, visibility, default value, and setter coercion logic.
+  # Attribute acts as a thin wrapper around AttributeOptions,
+  # exposing core attribute metadata and behavior in a safe, immutable way.
   #
-  # It is used internally by the DSL to configure how accessors are defined,
-  # memoized, and resolved at runtime.
+  # Each Attribute instance represents a single logical property,
+  # and delegates its behavior (default, visibility, coercion, etc.) to its associated AttributeOptions.
+  #
+  # @example
+  #   attribute = Attribute.new(:enabled, default: true, expose: :read_write)
+  #   attribute.name          # => :enabled
+  #   attribute.default.call  # => true
+  #   attribute.expose        # => :read_write
   class Attribute
-    # Supported attribute scopes within Cattri.
-    ATTRIBUTE_TYPES = %i[class instance].freeze
-
-    # Supported Ruby method visibility levels.
-    ACCESS_LEVELS = %i[public protected private].freeze
+    # @return [Module] the class or module this attribute was defined in
+    attr_reader :defined_in
 
-    # Ruby value types considered safe to reuse as-is (no `#dup` needed).
-    SAFE_VALUE_TYPES = [Numeric, Symbol, TrueClass, FalseClass, NilClass].freeze
+    # Initializes a new attribute definition.
+    #
+    # @param name [Symbol, String] the attribute name
+    # @param defined_in [Module] the class or module where this attribute is defined
+    # @param options [Hash] configuration options
+    # @option options [Boolean] :scope whether the attribute is class-level (internally mapped to :class_attribute)
+    # @param transformer [Proc] optional block used to coerce/validate assigned values
+    def initialize(name, defined_in:, **options, &transformer)
+      @options = Cattri::AttributeOptions.new(name, transformer: transformer, **options)
+      @defined_in = defined_in
+    end
 
-    # Default options for class-level attributes.
-    DEFAULT_CLASS_ATTRIBUTE_OPTIONS = {
-      readonly: false,
-      instance_reader: true,
-      predicate: false
-    }.freeze
+    # Serializes this attribute and its configuration to a frozen hash.
+    #
+    # @return [Hash<Symbol, Object>]
+    def to_h
+      {
+        name: @options.name,
+        ivar: @options.ivar,
+        defined_in: @defined_in,
+        final: @options.final,
+        scope: @options.scope,
+        predicate: @options.predicate,
+        default: @options.default,
+        transformer: @options.transformer,
+        expose: @options.expose,
+        visibility: @options.visibility
+      }
+    end
 
-    # Default options for instance-level attributes.
-    DEFAULT_INSTANCE_ATTRIBUTE_OPTIONS = {
-      reader: true,
-      writer: true,
-      predicate: false
-    }.freeze
+    # @!attribute [r] name
+    #   @return [Symbol] the canonical name of the attribute
 
-    # @return [Symbol] the attribute name
-    attr_reader :name
+    # @!attribute [r] ivar
+    #   @return [Symbol] the backing instance variable (e.g., :@enabled)
 
-    # @return [Symbol] the attribute type (:class or :instance)
-    attr_reader :type
+    # @!attribute [r] default
+    #   @return [Proc] a callable lambda for the attribute’s default value
 
-    # @return [Symbol] the associated instance variable (e.g., :@items)
-    attr_reader :ivar
+    # @!attribute [r] transformer
+    #   @return [Proc] a callable transformer used to process assigned values
 
-    # @return [Symbol] the access level (:public, :protected, :private)
-    attr_reader :access
+    # @!attribute [r] expose
+    #   @return [Symbol] method exposure type (:read, :write, :read_write, or :none)
 
-    # @return [Proc] the normalized default value block
-    attr_reader :default
+    # @!attribute [r] visibility
+    #   @return [Symbol] method visibility (:public, :protected, :private)
 
-    # @return [Proc] the setter function used to assign values
-    attr_reader :setter
+    %i[
+      name
+      ivar
+      default
+      transformer
+      expose
+      visibility
+    ].each do |option|
+      define_method(option) { @options.public_send(option) }
+    end
 
-    # Initializes a new attribute definition.
-    #
-    # @param name [String, Symbol] the name of the attribute
-    # @param type [Symbol] either :class or :instance
-    # @param options [Hash] additional attribute configuration
-    # @param block [Proc, nil] optional block for setter coercion
-    #
-    # @raise [Cattri::UnsupportedTypeError] if an invalid type is provided
-    def initialize(name, type, options, block)
-      @type = type.to_sym
-      raise Cattri::UnsupportedTypeError, type unless ATTRIBUTE_TYPES.include?(@type)
-
-      @name = name.to_sym
-      @ivar = normalize_ivar(options[:ivar])
-      @access = options[:access] || :public
-      @default = normalize_default(options[:default])
-      @setter = normalize_setter(block)
-      @options = typed_options(options)
+    # @return [Boolean] whether the reader should remain internal
+    def internal_reader?
+      %i[write none].include?(@options.expose)
     end
 
-    # Hash-like access to option values or metadata.
-    #
-    # @param key [Symbol, String]
-    # @return [Object]
-    def [](key)
-      to_hash[key.to_sym]
+    # @return [Boolean] whether the writer should remain internal
+    def internal_writer?
+      %i[read none].include?(@options.expose)
     end
 
-    # Serializes this attribute to a hash, including core properties and type-specific flags.
-    #
-    # @return [Hash]
-    def to_hash
-      @to_hash ||= {
-        name: @name,
-        ivar: @ivar,
-        type: @type,
-        access: @access,
-        default: @default,
-        setter: @setter
-      }.merge(@options)
+    # @return [Boolean] whether the attribute allows reading
+    def readable?
+      %i[read read_write].include?(@options.expose)
     end
 
-    alias to_h to_hash
+    # @return [Boolean] whether the attribute allows writing
+    def writable?
+      return false if @options.expose == :none
 
-    # @return [Boolean] true if the attribute is class-scoped
-    def class_level?
-      type == :class
+      !readonly?
     end
 
-    # @return [Boolean] true if the attribute is instance-scoped
-    def instance_level?
-      type == :instance
-    end
+    # @return [Boolean] whether the attribute is marked readonly
+    def readonly?
+      return false if @options.expose == :none
 
-    # @return [Boolean] whether the attribute is public
-    def public?
-      access == :public
+      @options.expose == :read || final?
     end
 
-    # @return [Boolean] whether the attribute is protected
-    def protected?
-      access == :protected
+    # @return [Boolean] whether the attribute is marked final (write-once)
+    def final?
+      @options.final
     end
 
-    # @return [Boolean] whether the attribute is private
-    def private?
-      access == :private
+    # @return [Boolean] whether the attribute is class-level
+    def class_attribute?
+      @options.scope == :class
     end
 
-    # Invokes the default value logic for the attribute.
-    #
-    # @return [Object] the default value for the attribute
-    # @raise [Cattri::AttributeError] if the default value logic raises an error
-    def invoke_default
-      default.call
-    rescue StandardError => e
-      raise Cattri::AttributeError, "Failed to evaluate the default value for :#{name}. Error: #{e.message}"
+    # @return [Boolean] whether the attribute defines a predicate method (`:name?`)
+    def with_predicate?
+      @options.predicate
     end
 
-    # Invokes the setter function with error handling
+    # Returns the methods that will be defined for this attribute.
     #
-    # @param args [Array] the positional arguments
-    # @param kwargs [Hash] the keyword arguments
-    # @raise [Cattri::AttributeError] if setter raises an error
-    # @return [Object] the value returned by the setter
-    def invoke_setter(*args, **kwargs)
-      setter.call(*args, **kwargs)
-    rescue StandardError => e
-      raise Cattri::AttributeError, "Failed to evaluate the setter for :#{name}. Error: #{e.message}"
-    end
-
-    private
-
-    # Applies class- or instance-level defaults and filters valid option keys.
+    # Includes the base accessor, optional writer, and optional predicate.
     #
-    # @param options [Hash]
-    # @return [Hash]
-    def typed_options(options)
-      defaults = type == :class ? DEFAULT_CLASS_ATTRIBUTE_OPTIONS : DEFAULT_INSTANCE_ATTRIBUTE_OPTIONS
-      defaults.merge(options.slice(*defaults.keys))
+    # @return [Array<Symbol>] a list of method names
+    def allowed_methods
+      [name, (:"#{name}=" if writable?), (:"#{name}?" if with_predicate?)].compact.freeze
     end
 
-    # Normalizes the instance variable name for the attribute.
+    # Validates whether this attribute is assignable in the current context.
     #
-    # @param ivar [String, Symbol, nil]
-    # @return [Symbol]
-    def normalize_ivar(ivar)
-      ivar ||= name
-      :"@#{ivar.to_s.delete_prefix("@")}"
+    # @raise [Cattri::AttributeError] if assignment is disallowed
+    def validate_assignment!
+      if final?
+        raise Cattri::AttributeError, "Cannot assign to final attribute `:#{name}`"
+      elsif readonly?
+        raise Cattri::AttributeError, "Cannot assign to readonly attribute `:#{name}`"
+      end
     end
 
-    # Returns the setter proc. If no block is provided, uses default logic:
-    # - Returns kwargs if given
-    # - Returns the single positional argument if one
-    # - Returns all args as an array otherwise
+    # Resolves the default value for this attribute.
     #
-    # @param block [Proc, nil]
-    # @return [Proc]
-    def normalize_setter(block)
-      block || lambda { |*args, **kwargs|
-        return kwargs unless kwargs.empty?
-        return args.first if args.length == 1
-
-        args
-      }
+    # @return [Object] the evaluated default
+    # @raise [Cattri::AttributeError] if default evaluation fails
+    def evaluate_default
+      @options.default.call
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to evaluate the default value for `:#{@options.name}`. Error: #{e.message}"
     end
 
-    # Wraps the default value in a memoized lambda.
+    # Processes and transforms an incoming assignment for this attribute.
     #
-    # If value is already callable, returns it.
-    # If immutable, wraps it in a lambda.
-    # If mutable, wraps it in a lambda that calls `#dup`.
-    #
-    # @param default [Object, Proc, nil]
-    # @return [Proc]
-    def normalize_default(default)
-      return default if default.respond_to?(:call)
-      return -> { default } if default.frozen? || SAFE_VALUE_TYPES.any? { |type| default.is_a?(type) }
-
-      lambda {
-        begin
-          default.dup
-        rescue StandardError => e
-          raise Cattri::AttributeError,
-                "Failed to duplicate default value for :#{name}. Error: #{e.message}"
-        end
-      }
+    # @param args [Array] positional arguments to pass to the transformer
+    # @param kwargs [Hash] keyword arguments to pass to the transformer
+    # @return [Object] the transformed value
+    # @raise [Cattri::AttributeError] if transformation fails
+    def process_assignment(*args, **kwargs)
+      @options.transformer.call(*args, **kwargs)
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to evaluate the setter for `:#{@options.name}`. Error: #{e.message}"
     end
   end
 end

data/lib/cattri/attribute_compiler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Cattri
+  # @internal
+  #
+  # Responsible for defining methods on the target class/module
+  # based on the metadata in a {Cattri::Attribute}.
+  #
+  # This includes:
+  # - callable accessors (acting as both reader and writer)
+  # - predicate methods
+  # - explicit writers (`:name=` methods)
+  #
+  # Handles both instance and class-level attributes, including
+  # memoization and validation of default values for final attributes.
+  class AttributeCompiler
+    class << self
+      # Defines accessor methods for the given attribute in the provided context.
+      #
+      # For `final` + `scope: :class` attributes, the default is eagerly assigned.
+      # Then, if permitted by `expose`, the reader, writer, and/or predicate methods are defined.
+      #
+      # @param attribute [Cattri::Attribute] the attribute to define
+      # @param context [Cattri::Context] the target context for method definition
+      # @return [void]
+      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
+        end
+
+        return if attribute.expose == :none
+
+        define_accessor!(attribute, context)
+        define_writer!(attribute, context)
+        define_predicate!(attribute, context) if attribute.with_predicate?
+      end
+
+      private
+
+      # Defines a callable method that acts as both getter and setter.
+      #
+      # If called with no arguments, it returns the default (memoized).
+      # If called with arguments, it processes the assignment and writes the value.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_accessor!(attribute, context)
+        context.define_method(attribute) do |*args, **kwargs|
+          readonly_call = args.empty? && kwargs.empty?
+          return AttributeCompiler.send(:memoize_default_value, self, attribute) if readonly_call
+
+          attribute.validate_assignment!
+          value = attribute.process_assignment(*args, **kwargs)
+          cattri_variable_set(attribute.ivar, value) # steep:ignore
+        end
+      end
+
+      # Defines a writer method `:name=`, assigning a transformed value to the backing store.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_writer!(attribute, context)
+        context.define_method(attribute, name: :"#{attribute.name}=") do |value|
+          coerced_value = attribute.process_assignment(value)
+          cattri_variable_set(attribute.ivar, coerced_value, final: attribute.final?) # steep:ignore
+        end
+      end
+
+      # Defines a predicate method `:name?` that returns the truthiness of the value.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_predicate!(attribute, context)
+        context.define_method(attribute, name: :"#{attribute.name}?") do
+          !!send(attribute.name) # rubocop:disable Style/DoubleNegation
+        end
+      end
+
+      # 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
+      end
+    end
+  end
+end

data/lib/cattri/attribute_options.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Cattri
+  # @internal
+  #
+  # AttributeOptions encapsulates normalized metadata for a single Cattri-defined attribute.
+  #
+  # It validates, transforms, and freezes all input during initialization,
+  # ensuring attribute safety and immutability at runtime.
+  #
+  # @example
+  #   options = AttributeOptions.new(:enabled, default: true, expose: :read_write)
+  #   options.name         # => :enabled
+  #   options.default.call # => true
+  #   options.expose       # => :read_write
+  class AttributeOptions
+    class << self
+      # Validates and normalizes the `expose` configuration.
+      #
+      # @param expose [Symbol, String] one of: :read, :write, :read_write, :none
+      # @return [Symbol]
+      # @raise [Cattri::AttributeError] if the value is invalid
+      def validate_expose!(expose)
+        expose = expose.to_sym
+        return expose if EXPOSE_OPTIONS.include?(expose) # steep:ignore
+
+        raise Cattri::AttributeError, "Invalid expose option `#{expose.inspect}` for :#{name}"
+      end
+
+      # 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 validate_visibility!(visibility)
+        visibility = visibility.to_sym
+        return visibility if VISIBILITIES.include?(visibility) # steep:ignore
+
+        raise Cattri::AttributeError, "Invalid visibility `#{visibility.inspect}` for :#{name}"
+      end
+    end
+
+    # Valid method visibility levels.
+    VISIBILITIES = %i[public protected private].freeze
+
+    # Valid expose options for method generation.
+    EXPOSE_OPTIONS = %i[read write read_write none].freeze
+
+    # Valid scope types.
+    SCOPES = %i[class instance].freeze
+    private_constant :SCOPES
+
+    # Built-in Ruby value types that are safe to reuse as-is (no dup needed).
+    SAFE_VALUE_TYPES = [Numeric, Symbol, TrueClass, FalseClass, NilClass].freeze
+    private_constant :SAFE_VALUE_TYPES
+
+    attr_reader :name, :ivar, :final, :scope, :predicate,
+                :default, :transformer, :expose, :visibility
+
+    # Initializes a frozen attribute configuration.
+    #
+    # @param name [Symbol, String] the attribute name
+    # @param ivar [Symbol, String, nil] optional custom instance variable name
+    # @param final [Boolean] marks the attribute as write-once
+    # @param scope [Symbol] indicates if the attribute is class-level (:class) or instance-level (:instance)
+    # @param predicate [Boolean] whether to define a `?` predicate method
+    # @param default [Object, Proc, nil] default value or callable
+    # @param transformer [Proc, nil] optional coercion block
+    # @param expose [Symbol] access level to define (:read, :write, :read_write, :none)
+    # @param visibility [Symbol] method visibility (:public, :protected, :private)
+    def initialize(
+      name,
+      ivar: nil,
+      final: false,
+      scope: :instance,
+      predicate: false,
+      default: nil,
+      transformer: nil,
+      expose: :read_write,
+      visibility: :public
+    )
+      @name = name.to_sym
+      @ivar = normalize_ivar(ivar)
+      @final = final
+      @scope = validate_scope!(scope)
+      @predicate = predicate
+      @default = normalize_default(default)
+      @transformer = normalize_transformer(transformer)
+      @expose = self.class.validate_expose!(expose)
+      @visibility = self.class.validate_visibility!(visibility)
+
+      freeze
+    end
+
+    # Returns a frozen hash representation of this option set.
+    #
+    # @return [Hash<Symbol, Object>]
+    def to_h
+      hash = {
+        name: @name,
+        ivar: @ivar,
+        final: @final,
+        scope: @scope,
+        predicate: @predicate,
+        default: @default,
+        transformer: @transformer,
+        expose: @expose,
+        visibility: @visibility
+      }
+      hash.freeze
+      hash
+    end
+
+    # Allows hash-style access to the option set.
+    #
+    # @param key [Symbol, String]
+    # @return [Object]
+    def [](key)
+      to_h[key.to_sym]
+    end
+
+    private
+
+    # Normalizes the instance variable name, defaulting to @name.
+    #
+    # @param ivar [String, Symbol, nil]
+    # @return [Symbol]
+    def normalize_ivar(ivar)
+      ivar ||= name
+      :"@#{ivar.to_s.delete_prefix("@")}"
+    end
+
+    # Wraps the default in a Proc with immutability protection.
+    #
+    # - Returns original Proc if given.
+    # - Wraps immutable types as-is.
+    # - Duplicates mutable values at runtime.
+    #
+    # @param default [Object, Proc, nil]
+    # @return [Proc]
+    def normalize_default(default)
+      return default if default.is_a?(Proc)
+      return -> { default } if default.frozen? || SAFE_VALUE_TYPES.any? { |t| default.is_a?(t) }
+
+      -> { default.dup }
+    end
+
+    # Returns a normalized assignment transformer.
+    #
+    # Falls back to a default transformer that returns:
+    # - `kwargs` if `args.empty?`
+    # - the single argument if one is passed
+    # - `[*args, kwargs]` otherwise
+    #
+    # @param transformer [Proc, nil]
+    # @return [Proc]
+    def normalize_transformer(transformer)
+      transformer || lambda { |*args, **kwargs|
+        return kwargs if args.empty?
+        return args.length == 1 ? args[0] : args if kwargs.empty?
+
+        [*args, kwargs]
+      }
+    end
+
+    # Validates and normalizes the provided scope value.
+    #
+    # If `scope` is `nil`, it defaults to `:instance`. If it's one of the allowed
+    # values (`:class`, `:instance`), it is returned as-is. Otherwise, an error is raised.
+    #
+    # @param scope [Symbol, nil] the requested attribute scope
+    # @return [Symbol] the validated scope (`:class` or `:instance`)
+    # @raise [Cattri::AttributeError] if the scope is invalid
+    def validate_scope!(scope)
+      return :instance if scope.nil?
+      return scope if SCOPES.include?(scope)
+
+      raise Cattri::AttributeError, "Invalid scope `#{scope.inspect}` for :#{name}. Must be :class or :instance"
+    end
+  end
+end