minitwin 1.0.0

data/lib/minitwin/class_methods/rbs.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  module ClassMethods
+    module Rbs
+
+      #: () -> String
+      def to_rbs
+        # :nocov:
+        return "" unless name
+
+        lines = []
+        superclass_name = superclass ? " < ::#{superclass.name}" : ""
+        # :nocov:
+        lines << "class ::#{name}#{superclass_name}"
+
+        # Collect initializer parameters
+        init_params = []
+
+        props = properties
+        props.each do |prop, meta|
+          as_meta = meta[:as]
+          # Dynamic aliases (Proc) cannot be represented statically in RBS;
+          # fall back to the base property name.
+          reader_name = as_meta && !as_meta.is_a?(Proc) && as_meta != prop ? as_meta : prop
+          type = rbs_type_for(meta)
+          lines << "  attr_reader #{reader_name}: #{type}"
+          if method_defined?(:"#{prop}=", false)
+            # :nocov:
+            lines << "  attr_writer #{prop}: #{type}"
+            # :nocov:
+          end
+
+          # Add to initializer parameters (all optional)
+          init_params << "?#{prop}: #{type}"
+        end
+
+        collections.each do |name_sym, meta|
+          elem_type = rbs_elem_type_for(meta)
+          lines << "  attr_accessor #{name_sym}: ::Array[#{elem_type}]"
+
+          # Add to initializer parameters (all optional, collections accept arrays or individual items)
+          init_params << "?#{name_sym}: ::Array[#{elem_type}]"
+        end
+
+        # Add initializer signature
+        lines << ""
+        lines << if init_params.any?
+                   "  def initialize: (#{init_params.join(", ")}, **untyped) -> void"
+                 else
+                   "  def initialize: (**untyped) -> void"
+                 end
+
+        lines << "end"
+        lines.join("\n")
+      end
+
+      private
+
+      def rbs_type_for(meta)
+        if meta[:twin]
+          rbs_class_name(meta[:twin])
+        elsif meta[:nested_class]
+          rbs_class_name(meta[:nested_class])
+        else
+          dry_type_to_rbs(meta[:type])
+        end
+      end
+
+      def rbs_elem_type_for(meta)
+        if meta[:element_twin]
+          rbs_class_name(meta[:element_twin])
+        else
+          "untyped"
+        end
+      end
+
+      def rbs_class_name(klass)
+        return "untyped" unless klass&.name
+
+        "::#{klass.name}"
+      end
+
+      def dry_type_to_rbs(dry_type)
+        return "untyped" unless dry_type
+
+        if dry_type.respond_to?(:primitive) && dry_type.primitive
+          prim = dry_type.primitive
+          if [TrueClass, FalseClass].include?(prim)
+            "bool"
+          elsif prim.is_a?(Class) && prim.name
+            "::#{prim.name}"
+          else
+            "untyped"
+          end
+        else
+          s =
+            begin
+              dry_type.to_s
+            rescue StandardError
+              ""
+            end
+          i =
+            begin
+              dry_type.inspect
+            rescue StandardError
+              ""
+            end
+          blob = [s, i, dry_type.class.name].join(" ")
+          return "bool" if blob.include?("Bool")
+          return "::Integer" if blob.include?("Integer")
+          return "::String" if blob.include?("String")
+          return "::Float" if blob.include?("Float")
+
+          begin
+            v1 = dry_type.call(true)
+            v2 = dry_type.call(false)
+            return "bool" if [true, false].include?(v1) && [true, false].include?(v2)
+          rescue StandardError
+            # Expected: Type coercion may fail for non-boolean types.
+            # Continue to fallback 'untyped'.
+          end
+          "untyped"
+        end
+      end
+    end
+  end
+end

data/lib/minitwin/class_methods/types_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class Minitwin
+  module ClassMethods
+    module TypesHelper
+      private
+
+      def dry_type_primitive(type)
+        return nil unless type.respond_to?(:primitive)
+
+        type.primitive
+      end
+
+      def type_default_value(type)
+        primitive_class = dry_type_primitive(type)
+
+        # :nocov:
+        case primitive_class
+        when Integer then 0
+        when String then ""
+        when TrueClass, FalseClass then false
+        else
+          # Fallback: inspect type representation for hints
+          infer_default_from_type_string(type)
+        end
+      end
+
+      def infer_default_from_type_string(type)
+        # Build type description from multiple sources for better inference
+        parts = [type.to_s, type.class.name]
+        begin
+          parts << type.inspect
+        rescue StandardError
+          # Type.inspect may fail for some custom types
+        end
+        type_description = parts.compact.join(" ")
+
+        return 0 if type_description.include?("Integer")
+        return "" if type_description.include?("String")
+        return false if type_description.include?("Bool")
+
+        nil
+      rescue StandardError
+        # Expected: Type introspection may fail for custom or complex types.
+        # Return nil as a safe default.
+        nil
+      end
+
+      def coerce_with_type(raw_value, type)
+        coerced = attempt_type_coercion(raw_value, type)
+        primitive_class = dry_type_primitive(type)
+
+        # Force string conversion if type is String but coercion didn't produce one
+        if raw_value && !coerced.is_a?(String) && primitive_class == String
+          coerced = raw_value.to_s
+        end
+
+        coerced
+      end
+
+      def attempt_type_coercion(raw_value, type)
+        return raw_value unless type
+
+        type.call(raw_value)
+      rescue *Minitwin.send(:coercion_error_classes)
+        raw_value
+      end
+    end
+  end
+end

data/lib/minitwin/class_methods.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "class_methods/dsl"
+require_relative "class_methods/constructors"
+require_relative "class_methods/rbs"
+require_relative "class_methods/caches"
+require_relative "class_methods/types_helper"
+require_relative "class_methods/coercion"
+
+class Minitwin
+  # Class-level DSL and public constructors split into focused modules.
+  module ClassMethods
+    include Minitwin::ClassMethods::Dsl
+    include Minitwin::ClassMethods::Constructors
+    include Minitwin::ClassMethods::Rbs
+    include Minitwin::ClassMethods::Caches
+    include Minitwin::ClassMethods::TypesHelper
+    include Minitwin::ClassMethods::Coercion
+
+    # Limit DSL surface to class body usage
+    private :property, :collection, :nested
+
+    # Make constructors and RBS API public
+    public :from_hash, :from_json, :from_params, :from_object, :from_objects, :from_collection, :to_rbs
+  end
+end

data/lib/minitwin/initialization.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  # Instance construction and low-level helpers used by the DSL-generated
+  # accessors. Filters unknown keys on initialize and seeds nested block
+  # properties so that validations on nested twins can run.
+  module Initialization
+    # Cache constant references for JIT optimization
+    ALIASES_VAR = Minitwin::DYNAMIC_ALIASES_VAR
+    ALIASES_REV_VAR = Minitwin::DYNAMIC_ALIASES_REV_VAR
+
+    # Forbidden method names that should never be aliased for security reasons
+    FORBIDDEN_ALIAS_NAMES = %i[
+      eval instance_eval class_eval module_eval
+      send __send__ public_send
+      method_missing respond_to_missing?
+      define_method remove_method undef_method
+      instance_variable_get instance_variable_set
+      instance_variables instance_variable_defined?
+      const_get const_set
+      class_variable_get class_variable_set
+      binding tap then yield_self to_proc
+      freeze __id__ object_id
+      == equal? eql? hash <=>
+    ].freeze
+
+    #: (**untyped) -> instance
+    def initialize(**args)
+      allowed_keys = self.class.send(:allowed_attribute_keys)
+
+      args.select! { |arg, _| allowed_keys.include?(arg.to_sym) }
+
+      getter_defaults = {}
+      self.class.block_properties.each do |method|
+        getter_defaults[method] = {} if allowed_keys.include?(method)
+      end
+
+      attrs = getter_defaults.merge(args)
+
+      # Skip per-setter alias recomputation during bulk init; recompute once after
+      @__skip_alias_recompute__ = true
+      if Minitwin.send(:active_model_initialized?, self.class)
+        super(attrs)
+      else
+        # :nocov: (exercised only without ActiveModel; covered by subprocess test)
+        attrs.each { |k, v| assign_attribute(method: k, value: v) }
+        # :nocov:
+      end
+      @__skip_alias_recompute__ = false
+
+      __recompute_dynamic_aliases__ if self.class.dynamic_aliases?
+    end
+
+    private
+
+    def assign_attribute(method:, value:)
+      if respond_to?("#{method}=")
+        send("#{method}=", value)
+      else
+        instance_variable_set("@#{method}", value)
+      end
+    end
+
+    def attribute_methods
+      self.class.send(:allowed_attribute_keys_array)
+    end
+
+    def define_instance_variable(name:, value:)
+      instance_variable_set(Minitwin::Utils.ivar_name(name), value)
+    end
+
+    # Define or update per-instance alias methods for properties/collections
+    # where `as:` was provided as a Proc. The Proc is executed in the context
+    # of the instance to compute the alias name.
+    def __recompute_dynamic_aliases__
+      instance_variable_set(ALIASES_VAR, {}) unless instance_variable_defined?(ALIASES_VAR)
+      instance_variable_set(ALIASES_REV_VAR, {}) unless instance_variable_defined?(ALIASES_REV_VAR)
+
+      # Handle scalar properties and collections
+      __recompute_aliases_for_collection__(:properties)
+      __recompute_aliases_for_collection__(:collections)
+
+      # Handle nested dynamic aliases (registered by DSL#nested)
+      __recompute_nested_aliases__
+    end
+
+    def __recompute_aliases_for_collection__(collection_method)
+      return unless self.class.respond_to?(collection_method)
+
+      self.class.public_send(collection_method).each do |key, meta|
+        as_meta = meta[:as]
+        next unless as_meta.is_a?(Proc)
+
+        alias_name = __compute_alias_name__(as_meta)
+        next if alias_name.nil?
+
+        __apply_dynamic_alias__(key, alias_name)
+      end
+    end
+
+    def __recompute_nested_aliases__
+      return unless self.class.respond_to?(:dynamic_nested_aliases)
+
+      self.class.dynamic_nested_aliases.each do |entry|
+        as_meta = entry[:as]
+        target = entry[:target]
+
+        if as_meta.is_a?(Proc)
+          alias_name = __compute_nested_alias_name__(entry)
+          next if alias_name.nil?
+
+          __apply_dynamic_alias__(target, alias_name)
+        else
+          # Static alias recorded by nested to support protected inner readers
+          __apply_dynamic_alias__(target, as_meta)
+        end
+      end
+    end
+
+    def __compute_alias_name__(as_proc)
+      instance_exec(&as_proc)
+    rescue StandardError
+      # Expected: Dynamic alias proc may fail or return invalid names.
+      # Return nil to skip this alias definition.
+      nil
+    end
+
+    def __compute_nested_alias_name__(entry)
+      obj = public_send(entry[:group])
+      obj = Minitwin::Utils.traverse_path(obj, entry[:path][0..-2])
+      obj.instance_exec(&entry[:as])
+    rescue StandardError
+      # Expected: Nested path traversal or dynamic alias proc may fail.
+      # Return nil to skip this alias definition.
+      nil
+    end
+
+    def __apply_dynamic_alias__(target_method, alias_name)
+      unless alias_name.is_a?(String) || alias_name.is_a?(Symbol)
+        raise ArgumentError, "Invalid alias name #{alias_name.inspect}: must be a String or Symbol"
+      end
+
+      alias_key = alias_name.to_sym
+      aliases = instance_variable_get(ALIASES_VAR)
+      aliases_rev = instance_variable_get(ALIASES_REV_VAR)
+
+      # Security check: prevent aliasing to forbidden method names
+      if FORBIDDEN_ALIAS_NAMES.include?(alias_key)
+        raise ArgumentError, "Cannot define dynamic alias '#{alias_key}': forbidden method name for security reasons"
+      end
+
+      prev = aliases[target_method]
+      if prev && prev != alias_key
+        begin
+          singleton_class.send(:remove_method, prev)
+        rescue NameError
+          # Expected: method may not exist if previously failed to define
+        end
+        aliases_rev.delete(prev)
+      end
+
+      # Collision checks: alias already used by another target or an existing method
+      if aliases_rev.key?(alias_key) && aliases_rev[alias_key] != target_method
+        raise ArgumentError, "Dynamic alias '#{alias_key}' already defined for '#{aliases_rev[alias_key]}'"
+      end
+
+      if respond_to?(alias_key, true) && aliases_rev[alias_key] != target_method
+        raise ArgumentError, "Cannot define dynamic alias '#{alias_key}': method already exists"
+      end
+
+      # Define forwarding method on the singleton class
+      singleton_class.send(:define_method, alias_key) do
+        send(target_method)
+      end
+
+      aliases[target_method] = alias_key
+      aliases_rev[alias_key] = target_method
+    end
+
+    # Public: expose current dynamic aliases as a Hash of alias_name => target_method
+    def dynamic_aliases
+      return {} unless instance_variable_defined?(ALIASES_REV_VAR) && instance_variable_get(ALIASES_REV_VAR)
+
+      instance_variable_get(ALIASES_REV_VAR).dup
+    end
+  end
+end

data/lib/minitwin/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Minitwin
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.join(__dir__, "..", "tasks", "minitwin.rake")
+    end
+  end
+end

data/lib/minitwin/serialization.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  # Serialization to Hash/JSON and ActiveModel validation aggregation.
+  # Converts nested twins recursively and preserves array items (dropping only
+  # nil). When ActiveModel validations are available, nested errors are
+  # surfaced on the parent using dot/bracket notation.
+  module Serialization
+    # Cache constant references for JIT optimization
+    ALIASES_VAR = Minitwin::DYNAMIC_ALIASES_VAR
+    NESTED_PREFIX = Minitwin::NESTED_READER_PREFIX
+
+    #: (render_nil: bool) -> Hash[Symbol, untyped]
+    def to_hash(render_nil: false)
+      hash = Minitwin.hash_klass.new
+
+      methods_to_serialize = self.class.send(:serializable_getters)
+
+      methods_to_serialize.each do |method|
+        value = send(method)
+        next if value.nil? && !render_nil
+
+        hash[method] = transform_value_for_serialization(value)
+      end
+
+      # Include dynamic alias keys (defined per instance via `as: -> { ... }`).
+      if instance_variable_defined?(ALIASES_VAR)
+        aliases = instance_variable_get(ALIASES_VAR)
+        if aliases && !aliases.empty?
+          aliases.each do |target_method, alias_method|
+            # Skip nested proxy aliases at the top level; nested groups
+            # serialize under their container key only.
+            next if target_method.is_a?(Symbol) && target_method.to_s.start_with?(NESTED_PREFIX)
+
+            # Read the value from the original target method to avoid issues if
+            # the alias method is overridden. Apply the same transformation rules
+            # as above for nested twins and arrays.
+            value = send(target_method)
+            next if value.nil? && !render_nil
+
+            hash[alias_method] = transform_value_for_serialization(value)
+          end
+        end
+      end
+
+      hash
+    end
+
+    alias to_h to_hash
+
+    #: (**untyped) -> String
+    def to_json(**)
+      to_hash(**).to_json
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def attributes
+      # Use setter-based attribute names and read via `send` to allow
+      # accessing protected original readers when aliases (`as:`) are used.
+      attribute_methods.each_with_object({}) do |m, h|
+        h[m] = send(m) if respond_to?(m, true)
+      end
+    end
+
+    #: () -> bool
+    def valid?
+      # If ActiveModel validations are available and included, run them and
+      # aggregate nested errors. Otherwise, consider the twin valid.
+      if defined?(ActiveModel::Validations) && self.class.ancestors.include?(ActiveModel::Validations)
+        super
+
+        self.class.block_properties.each do |property|
+          child = send(property)
+          next unless child.respond_to?(:valid?)
+
+          child.valid?
+          child.errors.each do |attribute|
+            errors.add("#{property}.#{attribute.attribute}", attribute.message)
+          end
+        end
+
+        self.class.collection_properties.each do |property|
+          send(property).each_with_index do |value, index|
+            next unless value.respond_to?(:valid?)
+
+            value.valid?
+            value.errors.each do |attribute|
+              errors.add("#{property}[#{index}].#{attribute.attribute}", attribute.message)
+            end
+          end
+        end
+
+        errors.empty?
+      else
+        # When ActiveModel is not available, consider the twin valid by default.
+        true
+      end
+    end
+
+    #: () -> String
+    def inspect
+      attrs = to_hash.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+      "#<#{self.class.name} #{attrs}>"
+    end
+
+    # Internal helper for PrettyPrint. Do not call this on your own.
+    #: (PP) -> void
+    def pretty_print(pretty_printer)
+      pretty_printer.object_group(self) do
+        pretty_printer.breakable
+        pretty_printer.seplist(
+          ordered_attributes_for_pp,
+          -> {
+            pretty_printer.text(",")
+            pretty_printer.breakable
+          }
+        ) do |(name, value)|
+          pretty_printer.group do
+            pretty_printer.text name.to_s
+            pretty_printer.text ": "
+            pretty_printer.pp value
+          end
+        end
+      end
+    end
+
+    private
+
+    def transform_value_for_serialization(value)
+      case value
+      when Minitwin
+        value.to_hash
+      when Array
+        value.filter_map { |item| item.respond_to?(:to_hash) ? item.to_hash : item }
+      else
+        value
+      end
+    end
+
+    def ordered_attributes_for_pp
+      methods = ordered_methods_for_pp
+      attrs = methods.map { |m| [display_name_for(m), send(m)] }
+      attrs + dynamic_aliases_for_pp
+    end
+
+    def ordered_methods_for_pp
+      ordered = self.class.send(:property_order)
+      all_methods = self.class.send(:serializable_getters)
+      ordered.select { |m| all_methods.include?(m) } + (all_methods - ordered)
+    end
+
+    def display_name_for(method)
+      meta = self.class.properties[method] || self.class.collections[method]
+      meta && meta[:as] && !meta[:as].is_a?(Proc) ? meta[:as] : method
+    end
+
+    def dynamic_aliases_for_pp
+      return [] unless instance_variable_defined?(ALIASES_VAR)
+
+      aliases = instance_variable_get(ALIASES_VAR)
+      return [] unless aliases && !aliases.empty?
+
+      aliases.filter_map do |target_method, alias_method|
+        next if target_method.is_a?(Symbol) && target_method.to_s.start_with?(NESTED_PREFIX)
+
+        [alias_method, send(target_method)]
+      end
+    end
+
+  end
+end