cattri 0.1.3 → 0.2.1

data/sig/lib/cattri/attribute.rbs

@@ -0,0 +1,115 @@
+module Cattri
+  # @internal
+  #
+  # Attribute acts as a thin wrapper around AttributeOptions,
+  # exposing core attribute metadata and behavior in a safe, immutable way.
+  #
+  # 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
+    @options: AttributeOptions
+
+    @defined_in: ::Module
+
+    # @return [Module] the class or module this attribute was defined in
+    attr_reader defined_in: ::Module
+
+    # 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] :class whether the attribute is class-level (internally mapped to :class_attribute)
+    # @param transformer [Proc] optional block used to coerce/validate assigned values
+    def initialize: (
+        identifier name,
+        defined_in: ::Module,
+        ?ivar: identifier,
+        ?final: bool,
+        ?scope: scope_types,
+        ?predicate: bool,
+        ?default: ::Proc | untyped | nil,
+        ?expose: expose_types,
+        ?visibility: visibility_types
+      ) { (?) -> untyped } -> void
+
+    # Serializes this attribute and its configuration to a frozen hash.
+    #
+    # @return [Hash<Symbol, Object>]
+    def to_h: () -> ::Hash[::Symbol, untyped]
+
+    # @return [Symbol] the canonical name of the attribute
+    def name: () -> ::Symbol
+
+    # @return [Symbol] the backing instance variable (e.g., :@enabled)
+    def ivar: () -> ::Symbol
+
+    # @return [Proc] a callable lambda for the attribute’s default value
+    def default: () -> ::Proc
+
+    # @return [Proc] a callable transformer used to process assigned values
+    def transformer: () -> ::Proc
+
+    # @return [Symbol] method exposure type (:read, :write, :read_write, or :none)
+    def expose: () -> expose_types
+
+    # @return [Symbol] method visibility (:public, :protected, :private)
+    def visibility: () -> visibility_types
+
+    # @return [Boolean] whether the reader should remain internal
+    def internal_reader?: () -> bool
+
+    # @return [Boolean] whether the writer should remain internal
+    def internal_writer?: () -> bool
+
+    # @return [Boolean] whether the attribute allows reading
+    def readable?: () -> bool
+
+    # @return [Boolean] whether the attribute allows writing
+    def writable?: () -> bool
+
+    # @return [Boolean] whether the attribute is marked readonly
+    def readonly?: () -> bool
+
+    # @return [Boolean] whether the attribute is marked final (write-once)
+    def final?: () -> bool
+
+    # @return [Boolean] whether the attribute is class-level
+    def class_attribute?: () -> bool
+
+    # @return [Boolean] whether the attribute defines a predicate method (`:name?`)
+    def with_predicate?: () -> bool
+
+    # Returns the methods that will be defined for this attribute.
+    #
+    # Includes the base accessor, optional writer, and optional predicate.
+    #
+    # @return [Array<Symbol>] a list of method names
+    def allowed_methods: () -> ::Array[::Symbol]
+
+    # Validates whether this attribute is assignable in the current context.
+    #
+    # @raise [Cattri::AttributeError] if assignment is disallowed
+    def validate_assignment!: () -> void
+
+    # Resolves the default value for this attribute.
+    #
+    # @return [Object] the evaluated default
+    # @raise [Cattri::AttributeError] if default evaluation fails
+    def evaluate_default: () -> untyped
+
+    # Processes and transforms an incoming assignment for this attribute.
+    #
+    # @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: (*untyped args, **untyped kwargs) -> untyped
+  end
+end

data/sig/lib/cattri/attribute_compiler.rbs

@@ -0,0 +1,61 @@
+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
+    # Defines accessor methods for the given attribute in the provided context.
+    #
+    # For `final` + `class_attribute` 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 self.define_accessor: (Attribute attribute, Context context) -> void
+
+    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 self.define_accessor!: (Attribute attribute, Context context) -> void
+
+    # Defines a writer method `:name=`, assigning a transformed value to the backing store.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param context [Cattri::Context]
+    # @return [void]
+    def self.define_writer!: (Attribute attribute, Context context) -> void
+
+    # Defines a predicate method `:name?` that returns the truthiness of the value.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param context [Cattri::Context]
+    # @return [void]
+    def self.define_predicate!: (Attribute attribute, Context context) -> void
+
+    # 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 self.memoize_default_value: (InternalStore receiver, Attribute attribute) -> untyped
+  end
+end

data/sig/lib/cattri/attribute_options.rbs

@@ -0,0 +1,150 @@
+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
+    @name: ::Symbol
+
+    @ivar: ::Symbol
+
+    @final: bool
+
+    @scope: scope_types
+
+    @predicate: bool
+
+    @default: ::Proc
+
+    @transformer: ::Proc
+
+    @expose: expose_types
+
+    @visibility: visibility_types
+
+    # 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 self.validate_expose!: (expose_types | identifier expose) -> 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
+
+    # Valid method visibility levels.
+    VISIBILITIES: ::Array[visibility_types]
+
+    # Valid expose options for method generation.
+    EXPOSE_OPTIONS: ::Array[expose_types]
+
+    # Valid scope types.
+    SCOPES: ::Array[scope_types]
+
+    # Built-in Ruby value types that are safe to reuse as-is (no dup needed).
+    SAFE_VALUE_TYPES: ::Array[untyped]
+
+    attr_reader name: ::Symbol
+
+    attr_reader ivar: ::Symbol
+
+    attr_reader final: bool
+
+    attr_reader scope: scope_types
+
+    attr_reader predicate: bool
+
+    attr_reader default: ::Proc
+
+    attr_reader transformer: ::Proc
+
+    attr_reader expose: expose_types
+
+    attr_reader visibility: visibility_types
+
+    # 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 class_attribute [Boolean] indicates if the attribute is class-level
+    # @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: (
+        identifier name,
+        ?ivar: identifier?,
+        ?final: bool,
+        ?scope: scope_types,
+        ?predicate: bool,
+        ?default: untyped,
+        ?transformer: ::Proc?,
+        ?expose: expose_types,
+        ?visibility: visibility_types
+      ) -> void
+
+    # Returns a frozen hash representation of this option set.
+    #
+    # @return [Hash<Symbol, Object>]
+    def to_h: () -> ::Hash[::Symbol, untyped]
+
+    # Allows hash-style access to the option set.
+    #
+    # @param key [Symbol, String]
+    # @return [Object]
+    def []: (untyped key) -> untyped
+
+    private
+
+    # Normalizes the instance variable name, defaulting to @name.
+    #
+    # @param ivar [String, Symbol, nil]
+    # @return [Symbol]
+    def normalize_ivar: (identifier? ivar) -> ::Symbol
+
+    # 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: (::Proc | untyped default) -> ::Proc
+
+    # 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: (::Proc? transformer) -> ::Proc
+
+    # 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_types scope) -> ::Symbol
+  end
+end

data/sig/lib/cattri/attribute_registry.rbs

@@ -0,0 +1,101 @@
+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 `class: true`, `final: true`, and other attribute options.
+  class AttributeRegistry
+    @context: Context
+
+    @__cattri_registered_attributes: ::Hash[::Symbol, Attribute]
+
+    # @return [Cattri::Context] the context this registry operates within
+    attr_reader context: Context
+
+    # Initializes a new registry for the provided context.
+    #
+    # @param context [Cattri::Context]
+    def initialize: (Context context) -> void
+
+    # Returns the attributes registered directly on this context.
+    #
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def registered_attributes: () -> ::Hash[::Symbol, Attribute]
+
+    # 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: bool) -> ::Hash[::Symbol, Attribute]
+
+    # Fetches an attribute by name, or returns nil.
+    #
+    # @param name [String, Symbol]
+    # @param with_ancestors [Boolean]
+    # @return [Cattri::Attribute, nil]
+    def fetch_attribute: (identifier name, ?with_ancestors: bool) -> Attribute
+
+    # 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!: (identifier name, ?with_ancestors: bool) -> Attribute
+
+    # 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: (
+        identifier name,
+        Proc | untyped value,
+        ?ivar: identifier,
+        ?final: bool,
+        ?scope: scope_types,
+        ?predicate: bool,
+        ?default: ::Proc | untyped | nil,
+        ?expose: expose_types,
+        ?visibility: visibility_types
+      ) { (?) -> untyped } -> ::Array[::Symbol]
+
+    # Copies registered attributes from this context to another,
+    # preserving definitions and assigning values for `final: true, class: true`.
+    #
+    # @param target_context [Cattri::Context]
+    # @return [void]
+    def copy_attributes_to: (Context target_context) -> void
+
+    private
+
+    # Validates that no attribute with the same name is already registered.
+    #
+    # @param name [Symbol]
+    # @raise [Cattri::AttributeError]
+    def validate_unique!: (::Symbol name) -> void
+
+    # Registers an attribute and applies or defers its definition.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def register_attribute: (Attribute attribute) -> void
+
+    # Defers the attribute definition if in a module context.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def defer_definition: (Attribute attribute) -> void
+
+    # Applies the attribute definition using the compiler.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    # @raise [Cattri::AttributeError]
+    def apply_definition!: (Attribute attribute) -> void
+  end
+end

data/sig/lib/cattri/context.rbs

@@ -0,0 +1,130 @@
+module Cattri
+  # Cattri::Context encapsulates the class or module that attributes are being defined on.
+  #
+  # 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
+    @target: ::Module
+
+    @__cattri_defined_methods: ::Hash[::Symbol, ::Set[::Symbol]]
+
+    # The class or module that owns the attributes.
+    #
+    # @return [Module]
+    attr_reader target: ::Module
+
+    # @param target [Module, Class]
+    def initialize: (::Module target) -> void
+
+    # Returns a frozen copy of all attribute methods explicitly defined by this context.
+    #
+    # This does not include inherited or module-defined methods.
+    #
+    # @return [Hash{Symbol => Set<Symbol>}] map of attribute name to defined method names
+    def defined_methods: () -> ::Hash[::Symbol, ::Set[::Symbol]]
+
+    # Whether this target should defer method definitions (e.g., if it's a module).
+    #
+    # @return [Boolean]
+    def defer_definitions?: () -> bool
+
+    # Ensures the target includes Cattri::DeferredAttributes if needed.
+    #
+    # Used to prepare modules for later application of attributes when included elsewhere.
+    #
+    # @return [void]
+    def ensure_deferred_support!: () -> void
+
+    # All ancestors and included modules used for attribute lookup and inheritance.
+    #
+    # @return [Array<Module>]
+    def attribute_lookup_sources: () -> ::Array[::Module]
+
+    # Defines a method for the given attribute unless already defined locally.
+    #
+    # Respects attribute-level force overwrite and enforces visibility rules.
+    #
+    # @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 attribute, ?name: identifier?) { (?) -> untyped } -> void
+
+    # Checks if the given method is already defined on the resolved target.
+    #
+    # Only checks methods directly defined on the class or singleton—not ancestors.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol, nil]
+    # @return [Boolean]
+    def method_defined?: (Attribute attribute, ?name: identifier?) -> bool
+
+    private
+
+    # Internal tracking of explicitly defined methods per attribute.
+    #
+    # @return [Hash{Symbol => Set<Symbol>}]
+    def __cattri_defined_methods: () -> ::Hash[::Symbol, ::Set[::Symbol]]
+
+    # Determines whether to define the method on the instance or singleton.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [Module]
+    def target_for: (Attribute attribute) -> ::Module
+
+    # Defines the method and applies its access visibility.
+    #
+    # @param target [Module]
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol]
+    # @yield method implementation
+    # @return [void]
+    def define_method!: (::Module target, Attribute attribute, ::Symbol name) { (?) -> untyped } -> void
+
+    # Applies visibility (`public`, `protected`, `private`) to a method.
+    #
+    # Skips application for `:public` (default in Ruby).
+    #
+    # @param target [Module]
+    # @param name [Symbol]
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def apply_visibility!: (::Module target, ::Symbol name, Attribute attribute) -> void
+
+    # Determines the effective visibility of the attribute.
+    #
+    # - 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 effective_visibility: (Attribute attribute, ::Symbol name) -> visibility_types
+
+    # 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 attribute, Symbol name) -> bool
+  end
+end

data/sig/lib/cattri/context_registry.rbs

@@ -0,0 +1,31 @@
+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
+    @attribute_registry: AttributeRegistry
+
+    @context: Context
+
+    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: () -> AttributeRegistry
+
+    # 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
+  end
+end

data/sig/lib/cattri/deferred_attributes.rbs

@@ -0,0 +1,53 @@
+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
+    @deferred_attributes: ::Hash[::Symbol, Attribute]
+
+    # 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: (::Module base) -> void
+
+    # 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: (::Module target) -> void
+
+      # Called when a module including `DeferredAttributes` is extended into another module/class.
+      #
+      # @param target [Module] the extending class or module
+      # @return [void]
+      def extended: (::Module target) -> void
+    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 attribute) -> void
+
+    # 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: (::Module target) -> void
+
+    private
+
+    # Internal storage of deferred attributes for this module.
+    #
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def deferred_attributes: () -> ::Hash[::Symbol, Attribute]
+  end
+end