cattri 0.1.3 → 0.2.0

data/sig/lib/cattri/error.rbs

@@ -0,0 +1,28 @@
+module Cattri
+  # Base error class for all exceptions raised by Cattri.
+  #
+  # 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
+    # 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: (?::String? msg, ?::Array[::String] backtrace) -> void
+  end
+
+  # Raised for any attribute-related definition or usage failure.
+  #
+  # This includes method conflicts, invalid configuration, and
+  # write attempts on `final` attributes.
+  #
+  # @see Cattri::Error
+  class AttributeError < Error
+  end
+end

data/sig/lib/cattri/inheritance.rbs

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

data/sig/lib/cattri/initializer_patch.rbs

@@ -0,0 +1,26 @@
+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: (*untyped args, **untyped kwargs) { (?) -> untyped } -> void
+  end
+end

data/sig/lib/cattri/internal_store.rbs

@@ -0,0 +1,75 @@
+module Cattri
+  # Internal representation of a stored attribute value.
+  AttributeValue: untyped
+
+  # 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
+    @__cattri_store: ::Hash[::Symbol, untyped]
+
+    @__cattri_set_variables: ::Set[::Symbol]
+
+    # 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?: (identifier key) -> bool
+
+    # 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: (identifier key) -> untyped
+
+    # 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: (identifier key, untyped value, ?final: bool) -> untyped
+
+    # 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: (identifier key, ?final: bool) { () -> untyped } -> untyped
+
+    private
+
+    # Returns the internal storage hash used for attribute values.
+    #
+    # @return [Hash<Symbol, Cattri::AttributeValue>]
+    def __cattri_store: () -> ::Hash[::Symbol, untyped]
+
+    # Returns the set of attribute keys that have been explicitly assigned.
+    #
+    # @return [Set<Symbol>]
+    def __cattri_set_variables: () -> ::Set[::Symbol]
+
+    # Normalizes the attribute key to a symbol without `@` prefix.
+    #
+    # @param key [String, Symbol]
+    # @return [Symbol]
+    def normalize_ivar: (identifier key) -> ::Symbol
+
+    # 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!: (::Symbol key) -> void
+  end
+end

data/sig/lib/cattri/introspection.rbs

@@ -0,0 +1,61 @@
+module Cattri
+  # Provides a read-only interface for inspecting attributes defined via the Cattri DSL.
+  #
+  # 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
+    # @param base [Class, Module] the target that includes `Cattri`
+    # @return [void]
+    def self.included: (::Module base) -> void
+
+    # @api public
+    # Class-level introspection methods exposed via `.attribute_defined?`, `.attribute`, etc.
+    module ClassMethods
+      # Returns true if the given attribute has been defined on this class or any ancestor.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [Boolean]
+      def attribute_defined?: (identifier name) -> bool
+
+      # 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: (identifier name) -> Attribute?
+
+      # 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: bool) -> ::Array[::Symbol]
+
+      # 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: bool) -> ::Hash[::Symbol, Attribute]
+
+      # 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: () -> ::Hash[::Symbol, ::Set[::Symbol]]
+
+      # 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: (identifier name) -> ::Module?
+    end
+  end
+end

data/sig/lib/cattri/types.rbs

@@ -0,0 +1,19 @@
+module Cattri
+  type identifier = ::String | ::Symbol
+
+  type scope_types = :class | :instance
+
+  type expose_types = :read_write | :read | :write | :none
+
+  type visibility_types = :public | :protected | :private
+
+  type attribute_options = {
+      ivar?: identifier,
+      final: bool,
+      scope?: scope_types,
+      predicate?: bool,
+      default?: ::Proc | untyped,
+      expose?: expose_types,
+      visibility?: visibility_types
+    }
+end

data/sig/lib/cattri/visibility.rbs

@@ -0,0 +1,55 @@
+module Cattri
+  # Cattri::Visibility tracks the current method visibility context (`public`, `protected`, `private`)
+  # when defining methods dynamically. It mimics Ruby's native visibility behavior so that
+  # `cattr` and `iattr` definitions can automatically infer the intended access level
+  # based on the current context in the source file.
+  #
+  # This module is intended to be extended by classes that include or extend Cattri.
+  #
+  # @example
+  #   class MyClass
+  #     include Cattri
+  #
+  #     private
+  #     cattr :sensitive_data
+  #   end
+  #
+  #   # => :sensitive_data will be defined as a private method
+  module Visibility
+    @__cattri_visibility: visibility_types
+
+    # Returns the currently active visibility scope on the class or module.
+    #
+    # Defaults to `:public` unless changed explicitly via `public`, `protected`, or `private`.
+    #
+    # @return [Symbol] :public, :protected, or :private
+    def __cattri_visibility: () -> visibility_types
+
+    # Intercepts calls to `public` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#public`.
+    #
+    # @param args [Array<Symbol>] method names to make public, or empty to set context
+    # @return [void]
+    def public: (*untyped args) -> void
+
+    # Intercepts calls to `protected` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#protected`.
+    #
+    # @param args [Array<Symbol>] method names to make protected, or empty to set context
+    # @return [void]
+    def protected: (*untyped args) -> void
+
+    # Intercepts calls to `private` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#private`.
+    #
+    # @param args [Array<Symbol>] method names to make private, or empty to set context
+    # @return [void]
+    def private: (*untyped args) -> void
+  end
+end

data/sig/lib/cattri.rbs

@@ -0,0 +1,37 @@
+# Main entrypoint for the Cattri DSL.
+#
+# 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.
+#
+# 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
+  VERSION: ::String
+
+  # Sets up the Cattri DSL on the including class or module.
+  #
+  # 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 target that includes `Cattri`
+  # @return [void]
+  def self.included: (::Module base) -> void
+
+  # 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.
+    #
+    # @return [void]
+    def with_cattri_introspection: () -> void
+
+    include Introspection
+  end
+end

data/spec/cattri/attribute_compiler_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Cattri::AttributeCompiler do
+  let(:dummy_class) do
+    Class.new do
+      include Cattri
+    end
+  end
+
+  let(:context) { dummy_class.send(:context) }
+
+  describe ".define_accessor" do
+    context "when attribute is final and class-level" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :count,
+          defined_in: dummy_class,
+          scope: :class,
+          final: true,
+          default: -> { 100 },
+          expose: :read_write
+        )
+      end
+
+      it "eagerly sets the default value on the target class" do
+        described_class.define_accessor(attribute, context)
+        expect(dummy_class.cattri_variable_get(:count)).to eq(100)
+      end
+    end
+
+    context "when expose is :none" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :secret,
+          defined_in: dummy_class,
+          default: -> { "hidden" },
+          expose: :none
+        )
+      end
+
+      it "does not define any methods" do
+        described_class.define_accessor(attribute, context)
+        instance = dummy_class.new
+        expect(instance).not_to respond_to(:secret)
+      end
+    end
+
+    context "when expose is :read_write with predicate" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :enabled,
+          defined_in: dummy_class,
+          default: -> { false },
+          predicate: true,
+          expose: :read_write
+        )
+      end
+
+      it "defines reader, writer, and predicate methods" do
+        described_class.define_accessor(attribute, context)
+        instance = dummy_class.new
+
+        expect(instance.enabled).to eq(false)
+        instance.enabled = true
+        expect(instance.enabled?).to eq(true)
+      end
+    end
+  end
+
+  describe ".define_accessor!" do
+    let(:attribute) do
+      Cattri::Attribute.new(
+        :setting,
+        defined_in: dummy_class,
+        default: -> { "default" },
+        expose: :read_write
+      )
+    end
+
+    it "defines a reader/writer method" do
+      described_class.send(:define_accessor!, attribute, context)
+      instance = dummy_class.new
+
+      expect(instance.setting).to eq("default")
+      instance.setting("updated")
+      expect(instance.setting).to eq("updated")
+    end
+  end
+
+  describe ".define_writer!" do
+    let(:attribute) do
+      Cattri::Attribute.new(
+        :mode,
+        defined_in: dummy_class,
+        default: -> { "auto" },
+        expose: :read_write
+      )
+    end
+
+    it "defines a writer method using 'name='" do
+      described_class.send(:define_accessor!, attribute, context)
+      described_class.send(:define_writer!, attribute, context)
+
+      instance = dummy_class.new
+      instance.mode = "manual"
+      expect(instance.mode).to eq("manual")
+    end
+  end
+
+  describe ".define_predicate!" do
+    let(:attribute) do
+      Cattri::Attribute.new(
+        :active,
+        defined_in: dummy_class,
+        default: -> {},
+        predicate: true,
+        expose: :read_write
+      )
+    end
+
+    it "defines a predicate method returning truthiness" do
+      described_class.send(:define_accessor!, attribute, context)
+      described_class.send(:define_predicate!, attribute, context)
+
+      instance = dummy_class.new
+      expect(instance.active?).to be false
+      instance.active("yes")
+      expect(instance.active?).to be true
+    end
+  end
+
+  describe ".memoize_default_value" do
+    let(:instance) { dummy_class.new }
+
+    context "non-final attribute" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :foo,
+          defined_in: dummy_class,
+          default: -> { "bar" },
+          expose: :read_write
+        )
+      end
+
+      it "stores and returns the evaluated default" do
+        result = described_class.send(:memoize_default_value, instance, attribute)
+        expect(result).to eq("bar")
+        expect(instance.cattri_variable_get(:foo)).to eq("bar")
+      end
+    end
+
+    context "final attribute" do
+      let(:attribute) do
+        Cattri::Attribute.new(
+          :immutable,
+          defined_in: dummy_class,
+          final: true,
+          default: -> { "locked" },
+          expose: :read
+        )
+      end
+
+      it "raises if value is not already set" do
+        expect do
+          described_class.send(:memoize_default_value, instance, attribute)
+        end.to raise_error(Cattri::AttributeError, /Final attribute :immutable cannot be written to/)
+      end
+
+      it "returns value if already set" do
+        instance.cattri_variable_set(:immutable, "preset", final: true)
+        result = described_class.send(:memoize_default_value, instance, attribute)
+
+        expect(result).to eq("preset")
+      end
+    end
+  end
+end