u-attributes 3.0.2 → 3.1.0

data/gemfiles/rails_8_1.gemfile

@@ -3,12 +3,14 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "u-case", "~> 4.5", ">= 4.5.1"
+gem "u-case", "~> 5.7"
 
 group :test do
+  gem "logger"
+  gem "stringio"
   gem "minitest", "~> 6.0"
-  gem "simplecov", "~> 0.22.0", require: false
   gem "ostruct", "~> 0.6.3"
+  gem "simplecov", "~> 0.22.0", require: false
   gem "activemodel", "~> 8.1.0"
 end
 

data/gemfiles/rails_edge.gemfile

@@ -3,12 +3,14 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "u-case", "~> 4.5", ">= 4.5.1"
+gem "u-case", "~> 5.7"
 
 group :test do
+  gem "logger"
+  gem "stringio"
   gem "minitest", "~> 6.0"
-  gem "simplecov", "~> 0.22.0", require: false
   gem "ostruct", "~> 0.6.3"
+  gem "simplecov", "~> 0.22.0", require: false
   gem "activemodel", branch: "main", git: "https://github.com/rails/rails"
 end
 

data/lib/micro/attributes/composition.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Micro
+  module Attributes
+    # Composition behavior baked into every `Micro::Attributes` includer.
+    #
+    # - `Coercion` (prepended): hashes assigned to an attribute whose
+    #   `accept:` is another `Micro::Attributes` class are auto-built
+    #   into instances of that class. Errors on the constructed child
+    #   bubble up as `'is invalid'` markers in the parent's
+    #   `attributes_errors` (when `Accept` is active).
+    # - `Instance#__validate_nested_entities__` (included): walks nested
+    #   `Micro::Attributes` children and surfaces their invalidity into
+    #   ActiveModel `errors`. Auto-registered by
+    #   `Features::ActiveModelValidations.included`.
+    module Composition
+      module Coercion
+        private
+
+          def __micro_attributes_hash_constructible?(klass)
+            arity = klass.instance_method(:initialize).arity
+            arity == 1 || arity == -1 || arity == -2
+          end
+
+          def ___attribute_assign(key, init_hash, attribute_data)
+            accept = attribute_data[1]
+
+            # Only coerce when the target class has a constructor that
+            # accepts exactly one positional arg (or one + variadic). The
+            # arity check accepts:
+            #   - `1`        — `def initialize(arg)` (Features::Initialize, custom)
+            #   - `-1`, `-2` — `def initialize(*a)` / `def initialize(a, *b)`
+            # And rejects:
+            #   - `0`        — `Object#initialize`, would crash on hash arg
+            #   - `>= 2`     — `def initialize(a, b)` etc., would crash on hash arg
+            if accept[0] == :accept &&
+               (klass = accept[1]).is_a?(::Class) &&
+               klass.include?(::Micro::Attributes) &&
+               __micro_attributes_hash_constructible?(klass)
+              value = init_hash[key]
+
+              if value.is_a?(::Hash)
+                init_hash = init_hash.dup
+                begin
+                  init_hash[key] = klass.new(value)
+                rescue ::ArgumentError
+                  # Child construction blew up — typically a missing required
+                  # keyword on the nested class, or a strict-mode rejection.
+                  # Leave the raw hash in place so Accept's KindOf check
+                  # ("expected to be a kind of <Klass>") rejects it into
+                  # `attributes_errors` instead of escaping as an exception.
+                  # This preserves the controlled `Failure(:invalid_attributes)`
+                  # envelope for u-case use cases that hold `accept:` nested
+                  # entities.
+                  init_hash[key] = value
+                end
+              end
+            end
+
+            super(key, init_hash, attribute_data)
+
+            # Bubble a marker for nested-entity errors — but only for PUBLIC
+            # attributes. Mirror Accept's visibility gate so private/protected
+            # attribute names don't leak through `attributes_errors`.
+            child = instance_variable_get("@#{key}")
+            if child.is_a?(::Object) &&
+               child.class.include?(::Micro::Attributes) &&
+               child.respond_to?(:attributes_errors?) && child.attributes_errors? &&
+               @__attributes_errors && !@__attributes_errors.key?(key) &&
+               attribute_data[3] == :public
+              @__attributes_errors[key] = 'is invalid'
+            end
+          end
+      end
+
+      module Instance
+        def __validate_nested_entities__
+          return unless respond_to?(:errors)
+
+          # Iterate only PUBLIC attributes so private/protected nested
+          # entity names never leak through ActiveModel `errors` /
+          # `full_messages`. Mirrors the bubble's visibility gate above.
+          self.class.attributes_by_visibility[:public].each do |attr_name|
+            child = instance_variable_get("@#{attr_name}")
+
+            next unless child.is_a?(::Object) && child.class.include?(::Micro::Attributes)
+
+            child_invalid =
+              if child.respond_to?(:valid?)
+                # If the child already has errors, treat it as invalid
+                # without re-running `valid?` — AM's `valid?` calls
+                # `errors.clear` first, which would wipe any errors the
+                # caller (or another validator pass) had added to a
+                # shared child instance.
+                child.errors.any? || !child.valid?
+              elsif child.respond_to?(:attributes_errors?)
+                child.attributes_errors?
+              else
+                false
+              end
+
+            errors.add(attr_name.to_sym, 'is invalid') if child_invalid
+          end
+        end
+      end
+    end
+  end
+end

data/lib/micro/attributes/features/accept.rb

@@ -35,7 +35,7 @@ module Micro::Attributes
 
         KeepProc = -> validation_data { validation_data[0] == :accept && validation_data[1] == Proc }
 
-        def __attribute_assign(key, init_hash, attribute_data)
+        def ___attribute_assign(key, init_hash, attribute_data)
           validation_data = attribute_data[1]
 
           value_to_assign = FetchValueToAssign.(init_hash, init_hash[key], attribute_data, KeepProc.(validation_data))

data/lib/micro/attributes/features/activemodel_validations.rb

@@ -66,6 +66,14 @@ module Micro::Attributes
           when base <= Features::Accept then base.send(:include, WithAccept)
           else base.send(:include, Standard)
           end
+
+          # When AM is mixed into any `Micro::Attributes` includer, auto-register
+          # a validator that recurses through nested-attribute children so
+          # `valid?` reflects deep descendant invalidity. The method is
+          # provided by `Composition::Instance`.
+          if base.include?(::Micro::Attributes)
+            base.validate(:__validate_nested_entities__)
+          end
         rescue LoadError
         end
       end

data/lib/micro/attributes/features.rb

@@ -106,13 +106,80 @@ module Micro
         ].join
 
         def self.fetch_keys(args)
-          keys = Array(args).dup.map { |name| fetch_key(name) }
+          keys = Array(args).flat_map { |name| split_strict_hash(name) }.map { |name| fetch_key(name) }
 
           raise ArgumentError, INVALID_NAME if keys.empty? || !(keys - KEYS).empty?
 
           yield(keys)
         end
 
+        # Normalize a Hash arg passed to `Micro::Attributes.with(...)` into
+        # the per-entry form that `fetch_key` consumes.
+        #
+        # Handles BOTH:
+        #
+        # - The legacy single-key strict form (`{initialize: :strict}`,
+        #   `{accept: :strict}`) — preserved as-is, returned in a single-key
+        #   hash so the existing `fetch_key` branch matches it.
+        # - The new self-documenting hash API:
+        #
+        #     Micro::Attributes.with(
+        #       initialize: true | :strict,
+        #       accept:     true | :strict,
+        #       diff:       true,
+        #       keys_as:    :symbol | :string | :indifferent,
+        #       active_model: :validations
+        #     )
+        #
+        #   Each entry expands into the corresponding legacy feature symbol
+        #   (or single-key strict hash). `false`/`nil`/the no-op variants
+        #   for `keys_as` (`:string`/`:indifferent`) expand to nothing, so
+        #   "omit a key = feature off" reads naturally.
+        def self.split_strict_hash(arg)
+          return [arg] unless arg.is_a?(Hash)
+
+          arg.flat_map { |key, value| expand_hash_entry(key, value) }
+        end
+
+        def self.expand_hash_entry(key, value)
+          case key
+          when :initialize
+            case value
+            when true    then [:initialize]
+            when :strict then [{ initialize: :strict }]
+            when false, nil then []
+            else [{ key => value }]
+            end
+          when :accept
+            case value
+            when true    then [:accept]
+            when :strict then [{ accept: :strict }]
+            when false, nil then []
+            else [{ key => value }]
+            end
+          when :diff
+            case value
+            when true       then [:diff]
+            when false, nil then []
+            else [{ key => value }]
+            end
+          when :keys_as
+            case value
+            when :symbol                                  then [:keys_as_symbol]
+            when :string, :indifferent, nil, false        then []
+            else [{ key => value }]
+            end
+          when :active_model
+            case value
+            when :validations then [:activemodel_validations]
+            when nil, false   then []
+            else [{ key => value }]
+            end
+          else
+            [{ key => value }]
+          end
+        end
+
         def self.remove_base_if_has_strict(keys)
           keys.delete_if { |key| key == INIT } if keys.include?(INIT_STRICT)
           keys.delete_if { |key| key == ACCEPT } if keys.include?(ACCEPT_STRICT)

data/lib/micro/attributes/macros.rb

@@ -108,9 +108,47 @@ module Micro
         protected(name) if Options.protected?(visibility_index)
       end
 
+      # Re-apply visibility for an already-defined attribute. Used by
+      # `attribute!` so a subclass can promote a private/protected
+      # parent attribute back to public (or change visibility in either
+      # direction). Without this, `__attributes_data__` would say one
+      # thing while the actual reader's Ruby visibility said another.
+      #
+      # Note — `attribute!` is authoritative here: if the user defined a
+      # custom reader method (`def name; ...; end`) between the parent's
+      # `attribute` and the child's `attribute!`, this call will adjust
+      # that custom method's Ruby visibility too. That matches the
+      # documented "redefine these attributes" contract of `attribute!`.
+      def __attribute_reapply_visibility(name, visibility_index)
+        [Options::PUBLIC, Options::PRIVATE, Options::PROTECTED].each do |idx|
+          __attributes_groups[idx].delete(name)
+        end
+        __attributes_groups[visibility_index] << name
+
+        if Options.private?(visibility_index)
+          private(name)
+        elsif Options.protected?(visibility_index)
+          protected(name)
+        else
+          public(name)
+        end
+      end
+
+      # Sync the required set with the new options. Name kept for backwards
+      # compat with downstream gems (u-case v4) that may introspect it —
+      # the method is now add-or-remove rather than add-only so that
+      # `attribute!` on a child can relax a parent's required attribute
+      # by giving it a default (or vice-versa).
+      #
+      # When a `default:` is present, the attribute is NEVER required —
+      # `default:` always wins. `attribute :foo, default: X, required: true`
+      # treats `required: true` as a docs hint; the default supplies a value
+      # when none is passed, matching the 3.0.x behavior.
       def __attributes_required_add(name, opt, hasnt_default)
-        if opt[:required] || (attributes_are_all_required? && hasnt_default)
+        if hasnt_default && (opt[:required] || attributes_are_all_required?)
           __attributes_required__.add(name)
+        else
+          __attributes_required__.delete(name)
         end
 
         nil
@@ -119,10 +157,10 @@ module Micro
       def __attributes_data_to_assign(name, opt, visibility_index)
         hasnt_default = !opt.key?(:default)
 
-        default = hasnt_default ? __attributes_required_add(name, opt, hasnt_default) : opt[:default]
+        __attributes_required_add(name, opt, hasnt_default)
 
         [
-          default,
+          hasnt_default ? nil : opt[:default],
           Options.for_accept(opt),
           opt[:freeze],
           Options.visibility_name_from_index(visibility_index)
@@ -144,6 +182,7 @@ module Micro
 
         if can_overwrite || !has_attribute
           __attributes_data__[name] = __attributes_data_to_assign(name, opt, visibility_index)
+          __attribute_reapply_visibility(name, visibility_index) if has_attribute
         end
 
         __call_after_attribute_assign__(name, opt)
@@ -175,10 +214,152 @@ module Micro
         __attributes_public.member?(key)
       end
 
-      def attribute(name, options = Kind::Empty::HASH)
+      def attribute(name, options = Kind::Empty::HASH, &block)
+        options = __micro_attributes_block_options__(name, options, block) if block
         __attribute_assign(name, false, options)
       end
 
+      # Mix more `Micro::Attributes` features into this class. Sugar for
+      # `include Micro::Attributes.with(*names)` — accepts the same forms,
+      # including the hash-style API (e.g. `with initialize: :strict`).
+      #
+      #   with :keys_as_symbol
+      #   with :keys_as_symbol, :activemodel_validations
+      #   with initialize: :strict, accept: :strict
+      def with(*names)
+        send(:include, ::Micro::Attributes.with(*names))
+      end
+
+      private
+
+        def __micro_attributes_block_options__(name, options, block)
+          if options.key?(:accept)
+            raise ArgumentError,
+                  "attribute #{name.inspect}: cannot pass both `accept:` and a block — " \
+                  "the block already builds an inline class for `accept:`. " \
+                  "Use one or the other."
+          end
+
+          options = options.dup
+          options[:accept] = __micro_attributes_build_inline_class__(name, block)
+          options
+        end
+
+        # Build an anonymous nested class for `attribute :foo do ... end`.
+        #
+        # The inline class is wired with `Micro::Attributes.with(...)` so it
+        # always has a hash-keyword constructor and accept-validation
+        # machinery (the bare minimum for block-form to be useful). On top
+        # of that default, every `Features::*` module already in the host's
+        # ancestors is replayed — so a `KeysAsSymbol` / `ActiveModelValidations`
+        # / `Strict` host yields an inline child with the same mix.
+        #
+        # This handles three host patterns:
+        # - `include Micro::Attributes.with(...)` — features come from With::*
+        #   in ancestors, replayed below.
+        # - bare `include Micro::Attributes` — defaults to init+accept.
+        # - direct `include Micro::Attributes::Features::*` (the `u-case`
+        #   pattern) — same detection path picks them up.
+        def __micro_attributes_build_inline_class__(name, block)
+          klass = Class.new
+          klass.send(:include, ::Micro::Attributes.with(*__micro_attributes_inline_features__))
+
+          klass.class_eval(&block)
+
+          # Lazy outer label — capture the host class OBJECT (not its
+          # `.name` string) so naming resolves AFTER any later constant
+          # assignment (matters for `Micro::Attributes.new { ... }`,
+          # where the constant is assigned only after the factory returns).
+          outer = self
+          label_proc = -> { "#{outer.name || outer.inspect}(#{name})" }
+
+          klass.define_singleton_method(:to_s,    &label_proc)
+          klass.define_singleton_method(:inspect, &label_proc)
+
+          # Stop instances from leaking the anonymous class's heap address
+          # via the default `Object#inspect`. The new inspect:
+          # - uses `self.class.to_s` (stable via the singleton above)
+          # - surfaces ONLY public attribute values — consults
+          #   `attributes_by_visibility[:public]` so private/protected
+          #   values aren't leaked
+          # - which also hides framework ivars like ActiveModel's
+          #   `@errors`, `@validation_context`, etc., since they aren't
+          #   declared attributes
+          #
+          # Skip if the block already defined `inspect` directly on the
+          # inline class — user-defined `def inspect` inside the block
+          # wins over the macro's default.
+          unless klass.instance_methods(false).include?(:inspect)
+            klass.send(:define_method, :inspect) do
+              public_attrs = self.class.attributes_by_visibility[:public]
+              present = public_attrs.select { |n| instance_variable_defined?("@#{n}") }
+
+              if present.empty?
+                "#<#{self.class}>"
+              else
+                body = present.map { |n| "@#{n}=#{instance_variable_get("@#{n}").inspect}" }.join(', ')
+                "#<#{self.class} #{body}>"
+              end
+            end
+          end
+
+          # ActiveModel-aware naming — but ONLY when the inline class
+          # actually has AM mixed in. AM's error renderer reaches for
+          # `klass.model_name`, which on an anonymous class defaults to
+          # `ActiveModel::Name.new(klass)` and raises "Class name cannot
+          # be blank". The singleton override provides the explicit name.
+          #
+          # We DO NOT define the override on non-AM inline classes,
+          # because that would flip `respond_to?(:model_name)` from
+          # false → true on AM-less hosts and break any duck-typing
+          # feature-detection (`if klass.respond_to?(:model_name); ...`).
+          if defined?(::ActiveModel::Validations) && klass.include?(::ActiveModel::Validations)
+            klass.define_singleton_method(:model_name) do
+              ::ActiveModel::Name.new(self, nil, label_proc.call)
+            end
+          end
+
+          klass
+        end
+
+        # Detect every Micro::Attributes feature module already in the host's
+        # ancestors and map it back to the args `Micro::Attributes.with` accepts.
+        # Always includes `:initialize` and `:accept` defaults so block-form
+        # attributes can be hash-constructed and type-checked.
+        FEATURE_NAME_TO_ARG = {
+          'Micro::Attributes::Features::Initialize'              => :initialize,
+          'Micro::Attributes::Features::Accept'                  => :accept,
+          'Micro::Attributes::Features::Diff'                    => :diff,
+          'Micro::Attributes::Features::KeysAsSymbol'            => :keys_as_symbol,
+          'Micro::Attributes::Features::ActiveModelValidations'  => :activemodel_validations
+        }.freeze
+
+        STRICT_NAME_TO_VARIANT = {
+          'Micro::Attributes::Features::Initialize::Strict' => :initialize,
+          'Micro::Attributes::Features::Accept::Strict'     => :accept
+        }.freeze
+
+        def __micro_attributes_inline_features__
+          features = [:initialize, :accept]
+          strict   = {}
+
+          ancestors.each do |mod|
+            next unless mod.is_a?(::Module) && mod.name
+
+            if (arg = FEATURE_NAME_TO_ARG[mod.name])
+              features << arg
+            elsif (key = STRICT_NAME_TO_VARIANT[mod.name])
+              strict[key] = :strict
+            end
+          end
+
+          features.uniq!
+          features << strict unless strict.empty?
+          features
+        end
+
+      public
+
       RaiseKindError = ->(expected, given) do
         if (util = Kind.const_get(:KIND, false)) && util.respond_to?(:error!)
           util.error!(expected, given)
@@ -218,7 +399,8 @@ module Micro
       module ForSubclasses
         WRONG_NUMBER_OF_ARGS = 'wrong number of arguments (given 0, expected 1 or more)'.freeze
 
-        def attribute!(name, options = Kind::Empty::HASH)
+        def attribute!(name, options = Kind::Empty::HASH, &block)
+          options = __micro_attributes_block_options__(name, options, block) if block
           __attribute_assign(name, true, options)
         end
 

data/lib/micro/attributes/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   module Attributes
-    VERSION = '3.0.2'.freeze
+    VERSION = '3.1.0'.freeze
   end
 end

data/lib/micro/attributes.rb

@@ -8,15 +8,19 @@ module Micro
     require 'micro/attributes/utils'
     require 'micro/attributes/diff'
     require 'micro/attributes/macros'
+    require 'micro/attributes/composition'
     require 'micro/attributes/features'
 
     def self.included(base)
       base.extend(::Micro::Attributes.const_get(:Macros))
+      base.send(:prepend, ::Micro::Attributes::Composition::Coercion)
+      base.send(:include, ::Micro::Attributes::Composition::Instance)
 
       base.class_eval do
         private_class_method :__attributes, :__attribute_reader
         private_class_method :__attribute_assign, :__attributes_groups
         private_class_method :__attributes_required_add, :__attributes_data_to_assign
+        private_class_method :__attribute_reapply_visibility
       end
 
       def base.inherited(subclass)
@@ -38,6 +42,64 @@ module Micro
       Features.all
     end
 
+    # `Struct.new`-style class factory. Returns a fresh class that includes
+    # `Micro::Attributes.with(...)` with the requested features (merged on
+    # top of the default preset `{ initialize: true, accept: true }`).
+    # The block (if given) is `class_eval`d on the new class so attributes
+    # can be declared inline.
+    #
+    #   User = Micro::Attributes.new do
+    #     attribute :name, accept: String
+    #   end
+    #
+    #   StrictUser = Micro::Attributes.new(initialize: :strict, accept: :strict) do
+    #     attribute :name, accept: String
+    #     attribute :age,  accept: Numeric
+    #   end
+    #
+    # The preset is overridable per-key — pass `initialize: false` to opt
+    # out, or `initialize: :strict` to upgrade. Use the hash API only
+    # (positional symbols are intentionally not accepted here so the
+    # "preset + override" semantics stay unambiguous).
+    NEW_DEFAULTS = { initialize: true, accept: true }.freeze
+    private_constant :NEW_DEFAULTS
+
+    def self.new(options = {}, &block)
+      raise ArgumentError, 'options must be a Hash' unless options.is_a?(Hash)
+
+      effective = NEW_DEFAULTS.merge(options)
+
+      # `:initialize` must resolve to one of the allowed "on" values.
+      # Catches `false`, `nil`, garbage values like `'wrong'`, etc. —
+      # without it the returned class has no hash constructor and the
+      # next `klass.new(hash)` raises an opaque `ArgumentError` from
+      # `Object#initialize`.
+      unless [true, :strict].include?(effective[:initialize])
+        raise ArgumentError,
+              '`Micro::Attributes.new` requires the :initialize feature ' \
+              '(omit the key or pass `true` / `:strict`)'
+      end
+
+      klass = Class.new
+      klass.send(:include, with(effective))
+      klass.class_eval(&block) if block
+
+      # ActiveModel-aware naming for the anonymous factory class. Without
+      # this, the first call to `errors.full_messages` raises "Class name
+      # cannot be blank" because AM's `model_name` is invoked on a still-
+      # anonymous class (the user may never assign the result to a
+      # constant). `self.name` resolves lazily — Ruby fills it in if/when
+      # the constant is assigned later. Mirrors the inline-child fix in
+      # `Macros#__micro_attributes_build_inline_class__`.
+      if defined?(::ActiveModel::Validations) && klass.include?(::ActiveModel::Validations)
+        klass.define_singleton_method(:model_name) do
+          ::ActiveModel::Name.new(self, nil, self.name || self.inspect)
+        end
+      end
+
+      klass
+    end
+
     def attribute?(name, include_all = false)
       self.class.attribute?(name, include_all)
     end
@@ -147,13 +209,21 @@ module Micro
 
       def __attributes_assign(hash)
         self.class.__attributes_data__.each do |name, attribute_data|
-          __attribute_assign(name, hash, attribute_data) if attribute?(name, true)
+          ___attribute_assign(name, hash, attribute_data) if attribute?(name, true)
         end
 
         __attributes.freeze
       end
 
-      def __attribute_assign(name, init_hash, attribute_data)
+      # Renamed from `__attribute_assign` (3 underscores) to put the per-attribute
+      # instance-level assignment hook deeper into the "internal" naming convention
+      # than the class-method macro of the same prior name in `Macros`. Coercion is
+      # prepended to every host class, so this method's MRO position is now ahead of
+      # the host class itself — a user who defined `def __attribute_assign(...)`
+      # directly on their class would have been silently intercepted. The 3-underscore
+      # name is intentionally less inviting and avoids any conceivable collision with
+      # the class-method version still named `__attribute_assign` in `Macros`.
+      def ___attribute_assign(name, init_hash, attribute_data)
         value_to_assign = FetchValueToAssign.(init_hash, init_hash[name], attribute_data)
 
         ivar_value = instance_variable_set("@#{name}", value_to_assign)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-attributes
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -97,6 +97,7 @@ files:
 - gemfiles/rails_8_1.gemfile
 - gemfiles/rails_edge.gemfile
 - lib/micro/attributes.rb
+- lib/micro/attributes/composition.rb
 - lib/micro/attributes/diff.rb
 - lib/micro/attributes/features.rb
 - lib/micro/attributes/features/accept.rb