rigortype 0.1.4 → 0.1.5

data/lib/rigor/plugin/macro/block_as_method.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier A declaration: "the block passed to a
+      # class-level DSL call of one of `verbs` runs as an instance
+      # method on `receiver_constraint`'s subclass tree, with
+      # `self` typed accordingly."
+      #
+      # Authored on a plugin manifest:
+      #
+      #   manifest(
+      #     id: "sinatra",
+      #     version: "0.1.0",
+      #     block_as_methods: [
+      #       Rigor::Plugin::Macro::BlockAsMethod.new(
+      #         receiver_constraint: "Sinatra::Base",
+      #         verbs: %i[get post put delete head options patch link unlink]
+      #       )
+      #     ]
+      #   )
+      #
+      # Sinatra is the canonical worked target (`Sinatra::Base#generate_method`
+      # at `lib/sinatra/base.rb:1788-1793` literally does
+      # `define_method(name, &block); remove_method` — the block IS
+      # the method body, byte-for-byte). The substrate adopts the
+      # same contract: declare the receiver constraint + the
+      # class-level methods whose block argument runs as if it were
+      # an instance method of the receiver.
+      #
+      # Slice 1a (this file) is **the contract only**. The engine
+      # hook that consults registered entries and narrows
+      # `Scope#self_type` for a block whose enclosing call matches
+      # arrives in slice 1b.
+      #
+      # ## Fields
+      #
+      # - `receiver_constraint` — fully-qualified class name (String)
+      #   that the call's lexical receiver MUST be (or inherit from)
+      #   for the entry to fire. For Sinatra modular-style this is
+      #   `"Sinatra::Base"`; the substrate's class-context match
+      #   accepts every subclass.
+      # - `verbs` — Array of Symbol method names. A call shape
+      #   `<receiver_subclass>.get('/path') { ... }` matches when
+      #   `:get` is in this list.
+      # - `self_type` — Symbol selecting the kind of `self`-binding
+      #   the substrate applies inside the block. Slice 1a accepts
+      #   only `:receiver_instance` (the block runs as an instance
+      #   method of the receiver class). Other kinds (`:receiver_singleton`,
+      #   `:dsl_recorder`) are reserved for later slices.
+      #
+      # ## Ractor-shareability
+      #
+      # All fields are frozen at construction (ADR-15 Phase 1).
+      # `verbs` is dup-frozen so the caller's mutable array does
+      # not leak into the value. `Ractor.shareable?` returns true
+      # after `#initialize`.
+      class BlockAsMethod
+        SELF_TYPE_RECEIVER_INSTANCE = :receiver_instance
+        VALID_SELF_TYPES = [SELF_TYPE_RECEIVER_INSTANCE].freeze
+
+        attr_reader :receiver_constraint, :verbs, :self_type
+
+        def initialize(receiver_constraint:, verbs:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
+          validate_receiver_constraint!(receiver_constraint)
+          validate_verbs!(verbs)
+          validate_self_type!(self_type)
+
+          @receiver_constraint = receiver_constraint.dup.freeze
+          @verbs = verbs.map(&:to_sym).freeze
+          @self_type = self_type
+          freeze
+        end
+
+        def to_h
+          {
+            "receiver_constraint" => receiver_constraint,
+            "verbs" => verbs.map(&:to_s),
+            "self_type" => self_type.to_s
+          }
+        end
+
+        def ==(other)
+          other.is_a?(BlockAsMethod) &&
+            receiver_constraint == other.receiver_constraint &&
+            verbs == other.verbs &&
+            self_type == other.self_type
+        end
+        alias eql? ==
+
+        def hash
+          [receiver_constraint, verbs, self_type].hash
+        end
+
+        private
+
+        def validate_receiver_constraint!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::BlockAsMethod#receiver_constraint must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_verbs!(verbs)
+          unless verbs.is_a?(Array) && !verbs.empty?
+            raise ArgumentError,
+                  "Plugin::Macro::BlockAsMethod#verbs must be a non-empty Array, got #{verbs.inspect}"
+          end
+
+          verbs.each do |v|
+            next if v.is_a?(Symbol) || (v.is_a?(String) && !v.empty?)
+
+            raise ArgumentError,
+                  "Plugin::Macro::BlockAsMethod#verbs entries must be Symbol/non-empty String, " \
+                  "got #{v.inspect}"
+          end
+        end
+
+        def validate_self_type!(self_type)
+          return if VALID_SELF_TYPES.include?(self_type)
+
+          raise ArgumentError,
+                "Plugin::Macro::BlockAsMethod#self_type must be one of #{VALID_SELF_TYPES.inspect}, " \
+                "got #{self_type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/macro/external_file.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier D declaration: "files matching `glob` are
+      # analysed as if their body were pasted at a call site whose
+      # `self` is an instance of `receiver_type` (and whose `@ivar`
+      # facts come from `bound_ivars`)."
+      #
+      # Worked motivating cases (per the per-library survey):
+      #
+      # - Redmine's `WebhookPayload#instance_eval(File.read(path), path, 1)`
+      #   at `app/models/webhook_payload.rb:71`. The payload templates
+      #   under `config/webhooks/*.rb` run with `self` typed as
+      #   `Redmine::WebhookPayload` and ivars like `@event` / `@issue`
+      #   / `@user` pre-bound by the caller.
+      # - tDiary Core's plugin loader pattern — `misc/plugin/*.rb`
+      #   files loaded under `instance_eval` with the tDiary plugin
+      #   instance as `self`.
+      #
+      # ## Authoring shape
+      #
+      #     manifest(
+      #       id: "redmine-webhook-payloads",
+      #       version: "0.1.0",
+      #       external_files: [
+      #         Rigor::Plugin::Macro::ExternalFile.new(
+      #           glob: "config/webhooks/*.rb",
+      #           receiver_type: "Redmine::WebhookPayload",
+      #           bound_ivars: {
+      #             "@event" => "Symbol",
+      #             "@issue" => "Issue?",
+      #             "@user"  => "User"
+      #           }
+      #         )
+      #       ]
+      #     )
+      #
+      # ## Fields
+      #
+      # - `glob` — non-empty String pattern. Interpreted relative
+      #   to the project root (the directory containing `.rigor.yml`)
+      #   at scan time. Slice 5a accepts any non-empty glob
+      #   pattern syntactically; the engine integration (slice 5b)
+      #   pins the resolution rule.
+      # - `receiver_type` — non-empty String. The class name `self`
+      #   inside the loaded file binds to. Engine integration (slice
+      #   5b) narrows the file-entry scope's `self_type` to
+      #   `Nominal[receiver_type]`.
+      # - `bound_ivars` — Hash<String, String>. Each key MUST start
+      #   with `@`; each value is a non-empty type-name String. The
+      #   engine pre-binds these as ivar facts in the file-entry
+      #   scope (slice 5b).
+      #
+      # ## Slice 5a scope
+      #
+      # **This file ships the value class + manifest hook ONLY.**
+      # The engine integration that (a) adds matched files to the
+      # analysis set, (b) narrows the file-entry `self_type`, and
+      # (c) pre-binds `bound_ivars` as ivar facts is **queued for
+      # slice 5b**, gated on demonstrated demand. The survey
+      # identifies only Redmine + tDiary as concrete consumers;
+      # premature engine work is deferred until those cases (or
+      # equivalents) materialise as committed plugin targets.
+      #
+      # With only this slice landed, plugin authors CAN declare a
+      # Tier D manifest entry today — the declaration round-trips
+      # through `Manifest#to_h` (cache-key stable) and is exposed
+      # on `Manifest#external_files` — but the substrate does not
+      # yet act on it. The contract is forward-compatible: when
+      # slice 5b lands, the engine reads the same declarations and
+      # plugin gems do not need to change.
+      class ExternalFile
+        attr_reader :glob, :receiver_type, :bound_ivars
+
+        def initialize(glob:, receiver_type:, bound_ivars: {})
+          validate_glob!(glob)
+          validate_receiver_type!(receiver_type)
+          validate_bound_ivars!(bound_ivars)
+
+          @glob = glob.dup.freeze
+          @receiver_type = receiver_type.dup.freeze
+          @bound_ivars = bound_ivars.to_h { |k, v| [k.dup.freeze, v.dup.freeze] }.freeze
+          freeze
+        end
+
+        def to_h
+          {
+            "glob" => glob,
+            "receiver_type" => receiver_type,
+            "bound_ivars" => bound_ivars
+          }
+        end
+
+        def ==(other)
+          other.is_a?(ExternalFile) && to_h == other.to_h
+        end
+        alias eql? ==
+
+        def hash
+          to_h.hash
+        end
+
+        private
+
+        def validate_glob!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::ExternalFile#glob must be a non-empty String, got #{value.inspect}"
+        end
+
+        def validate_receiver_type!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::ExternalFile#receiver_type must be a non-empty String, got #{value.inspect}"
+        end
+
+        def validate_bound_ivars!(value)
+          unless value.is_a?(Hash)
+            raise ArgumentError,
+                  "Plugin::Macro::ExternalFile#bound_ivars must be a Hash, got #{value.inspect}"
+          end
+
+          value.each do |k, v|
+            unless k.is_a?(String) && k.start_with?("@") && k.length > 1
+              raise ArgumentError,
+                    "Plugin::Macro::ExternalFile#bound_ivars key must be a String starting with `@`, " \
+                    "got #{k.inspect}"
+            end
+            next if v.is_a?(String) && !v.empty?
+
+            raise ArgumentError,
+                  "Plugin::Macro::ExternalFile#bound_ivars value must be a non-empty String, " \
+                  "got #{v.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/macro/heredoc_template.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier C declaration: "the class-level DSL call
+      # `<receiver_constraint>.<method_name>(name_arg, ...)` emits
+      # synthetic methods on the calling class, with names
+      # interpolating the source-visible literal argument at
+      # `symbol_arg_position`."
+      #
+      # Textbook target — dry-struct's `attribute :name, T` and
+      # ActiveStorage's `has_one_attached :avatar` both have this
+      # shape: a class-level call enumerates a literal Symbol
+      # argument; the framework `class_eval`s a heredoc
+      # interpolating that Symbol; the emit table is fixed.
+      #
+      # ## Authoring shape
+      #
+      #     manifest(
+      #       id: "activestorage",
+      #       version: "0.1.0",
+      #       heredoc_templates: [
+      #         Rigor::Plugin::Macro::HeredocTemplate.new(
+      #           receiver_constraint: "ActiveRecord::Base",
+      #           method_name: :has_one_attached,
+      #           symbol_arg_position: 0,
+      #           emit: [
+      #             { name: "#{name}",            returns: "ActiveStorage::Attached::One" },
+      #             { name: "#{name}_attachment", returns: "ActiveStorage::Attachment" },
+      #             { name: "#{name}_blob",       returns: "ActiveStorage::Blob" }
+      #           ],
+      #           class_level_emit: [
+      #             { name: "with_attached_#{name}", returns: "ActiveRecord::Relation" }
+      #           ]
+      #         )
+      #       ]
+      #     )
+      #
+      # ## Fields
+      #
+      # - `receiver_constraint` — fully-qualified class name (String).
+      #   Synthesis fires when the call's lexical receiver class
+      #   equals or inherits from this constraint.
+      # - `method_name` — Symbol naming the DSL method (e.g.
+      #   `:has_one_attached`, `:attribute`).
+      # - `symbol_arg_position` — Integer (default 0) — the
+      #   argument index whose literal Symbol value becomes the
+      #   `name` interpolated into each emit row's `name:`
+      #   template. Slice 2a accepts non-negative integers only.
+      # - `emit` — Array of `Emit` (or coerced Hash) — instance
+      #   methods to synthesise on the calling class.
+      # - `class_level_emit` — same shape, but the synthesised
+      #   methods are singleton (class-level) methods.
+      #
+      # ## Floor / ceiling per ADR-16 WD13
+      #
+      # Slice 2 ships at the **floor**: each emit row's `name:`
+      # is the source of truth for the synthetic method's name
+      # (a single `"\#{name}"` placeholder gets interpolated with
+      # the literal symbol argument at `symbol_arg_position`).
+      # The `returns:` strings are **recorded in the manifest but
+      # not resolved**; the engine emits synthetic methods with
+      # `Dynamic[T]` returns plus a
+      # `macro.tier_c.unresolved-return` provenance marker.
+      # Precise return-type resolution via ADR-13's
+      # `Plugin::TypeNodeResolver` is the **ceiling**, deferred
+      # to a later slice — the `returns:` declarations cost
+      # nothing to write today and unlock precision then.
+      #
+      # ## Slice 2a scope
+      #
+      # This file ships the value class only. Slice 2b wires the
+      # pre-pass that scans Tier C call sites + the
+      # `SyntheticMethodIndex` the dispatcher consults; slice 2c
+      # authors `examples/rigor-dry-struct/` and
+      # `examples/rigor-dry-types/` as the worked consumers.
+      class HeredocTemplate
+        NAME_PLACEHOLDER = "\#{name}"
+
+        attr_reader :receiver_constraint, :method_name, :symbol_arg_position, :emit, :class_level_emit
+
+        def initialize(receiver_constraint:, method_name:, symbol_arg_position: 0, emit: [], class_level_emit: [])
+          validate_receiver_constraint!(receiver_constraint)
+          validate_method_name!(method_name)
+          validate_symbol_arg_position!(symbol_arg_position)
+
+          @receiver_constraint = receiver_constraint.dup.freeze
+          @method_name = method_name.to_sym
+          @symbol_arg_position = symbol_arg_position
+          @emit = coerce_emit_list!(emit, "emit")
+          @class_level_emit = coerce_emit_list!(class_level_emit, "class_level_emit")
+          freeze
+        end
+
+        def to_h
+          {
+            "receiver_constraint" => receiver_constraint,
+            "method_name" => method_name.to_s,
+            "symbol_arg_position" => symbol_arg_position,
+            "emit" => emit.map(&:to_h),
+            "class_level_emit" => class_level_emit.map(&:to_h)
+          }
+        end
+
+        def ==(other)
+          other.is_a?(HeredocTemplate) && to_h == other.to_h
+        end
+        alias eql? ==
+
+        def hash
+          to_h.hash
+        end
+
+        # One row of an emit table: the synthetic method's
+        # name-template (the analyzer interpolates `\#{name}` with
+        # the call-site literal symbol) and its declared return
+        # type (recorded as a string in slice 2a, resolved by the
+        # ceiling slice via ADR-13).
+        class Emit
+          attr_reader :name, :returns
+
+          def initialize(name:, returns:)
+            unless name.is_a?(String) && !name.empty?
+              raise ArgumentError,
+                    "Macro::HeredocTemplate::Emit#name must be a non-empty String, got #{name.inspect}"
+            end
+            unless returns.is_a?(String) && !returns.empty?
+              raise ArgumentError,
+                    "Macro::HeredocTemplate::Emit#returns must be a non-empty String, got #{returns.inspect}"
+            end
+
+            @name = name.dup.freeze
+            @returns = returns.dup.freeze
+            freeze
+          end
+
+          def to_h
+            { "name" => name, "returns" => returns }
+          end
+
+          def ==(other)
+            other.is_a?(Emit) && name == other.name && returns == other.returns
+          end
+          alias eql? ==
+
+          def hash
+            [name, returns].hash
+          end
+        end
+
+        private
+
+        def validate_receiver_constraint!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::HeredocTemplate#receiver_constraint must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_method_name!(value)
+          return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+          raise ArgumentError,
+                "Plugin::Macro::HeredocTemplate#method_name must be Symbol or non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_symbol_arg_position!(value)
+          return if value.is_a?(Integer) && value >= 0
+
+          raise ArgumentError,
+                "Plugin::Macro::HeredocTemplate#symbol_arg_position must be a non-negative Integer, " \
+                "got #{value.inspect}"
+        end
+
+        def coerce_emit_list!(entries, label)
+          unless entries.is_a?(Array)
+            raise ArgumentError,
+                  "Plugin::Macro::HeredocTemplate##{label} must be an Array, got #{entries.inspect}"
+          end
+
+          entries.map { |entry| coerce_emit_entry!(entry, label) }.freeze
+        end
+
+        def coerce_emit_entry!(entry, label)
+          case entry
+          when Emit then entry
+          when Hash
+            Emit.new(name: entry[:name] || entry["name"], returns: entry[:returns] || entry["returns"])
+          else
+            raise ArgumentError,
+                  "Plugin::Macro::HeredocTemplate##{label} entry must be an Emit or Hash, " \
+                  "got #{entry.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/macro/trait_registry.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier B declaration: "the class-level DSL call
+      # `<receiver_constraint>.<method_name>(:trait_a, :trait_b, ...)`
+      # effectively includes the modules named in
+      # `modules_by_symbol[:trait_a]` + `[:trait_b]` (plus any
+      # `always_included` modules) on the calling class."
+      #
+      # Worked target: Devise's model-side `devise :database_authenticatable,
+      # :recoverable` DSL (per-library survey § Devise). The bundled
+      # registry mirrors `lib/devise/modules.rb`'s symbol → module table;
+      # `always_included` carries the modules Devise always mixes in
+      # regardless of selection (e.g. `Devise::Models::Authenticatable`).
+      #
+      # ## Authoring shape
+      #
+      #     manifest(
+      #       id: "devise",
+      #       version: "0.1.0",
+      #       trait_registries: [
+      #         Rigor::Plugin::Macro::TraitRegistry.new(
+      #           receiver_constraint: "ActiveRecord::Base",
+      #           method_name: :devise,
+      #           symbol_arg_position: :rest,
+      #           modules_by_symbol: {
+      #             database_authenticatable: "Devise::Models::DatabaseAuthenticatable",
+      #             recoverable:              "Devise::Models::Recoverable",
+      #             rememberable:             "Devise::Models::Rememberable"
+      #           },
+      #           always_included: ["Devise::Models::Authenticatable"]
+      #         )
+      #       ]
+      #     )
+      #
+      # ## Fields
+      #
+      # - `receiver_constraint` — fully-qualified class name (String).
+      #   Synthesis fires when the call's lexical receiver class
+      #   equals or inherits from this constraint.
+      # - `method_name` — Symbol naming the DSL method
+      #   (e.g. `:devise`).
+      # - `symbol_arg_position` — `:rest` (all positional Symbol args
+      #   are traits, slice 3a's only supported form) or a
+      #   non-negative Integer (the index of a single trait symbol —
+      #   reserved for future shapes; not yet honoured by the
+      #   scanner).
+      # - `modules_by_symbol` — Hash<Symbol, String>. Maps each
+      #   recognised trait symbol to a fully-qualified module name.
+      #   Symbols not in the table fall through (silent skip; the
+      #   scanner emits a `macro.tier_b.unknown-trait` `:info`
+      #   provenance marker per WD9 / WD13).
+      # - `always_included` — Array<String>. Fully-qualified module
+      #   names that are added to every call site (even when no
+      #   symbols match). Mirrors Devise's `always_include` modules.
+      #
+      # ## Floor / ceiling per ADR-16 WD13
+      #
+      # Slice 3 ships at the **floor**: the substrate per-method-
+      # explodes each included module's RBS instance methods into
+      # the existing `SyntheticMethodIndex` (slice 2b primitive).
+      # The synthesised methods adopt the module's authored RBS
+      # return types — Tier B is NOT subject to the Tier C
+      # `Dynamic[T]` floor because the source-of-truth (the
+      # module's authored RBS) is not a manifest-declared string.
+      # Per ADR-5 robustness, the substrate does not fabricate
+      # precision; it simply replays the modules's signatures.
+      #
+      # **Out of scope for slice 3** (deferred follow-ups):
+      # - `class_methods_module:` per-trait (Devise's `ClassMethods`
+      #   extend-pattern); slice 3 covers instance methods only.
+      # - `sort_key:` for controlled include ordering across traits;
+      #   slice 3 uses plugin-registration order then registry
+      #   declaration order.
+      # - `included_do_digest:` — the per-module `included do` block
+      #   facts (attr_reader / after_save / etc.); slice 3 emits
+      #   only the module's plain instance methods.
+      #
+      # ## Slice 3a scope
+      #
+      # This file ships the value class only. Slice 3b wires the
+      # scanner that walks Tier B call sites + the per-method
+      # explosion via `SyntheticMethodIndex`; slice 3c authors
+      # `examples/rigor-devise/` model side as the worked consumer.
+      class TraitRegistry
+        REST_POSITION = :rest
+
+        attr_reader :receiver_constraint, :method_name, :symbol_arg_position, :modules_by_symbol, :always_included
+
+        def initialize(receiver_constraint:, method_name:, symbol_arg_position: REST_POSITION,
+                       modules_by_symbol: {}, always_included: [])
+          validate_receiver_constraint!(receiver_constraint)
+          validate_method_name!(method_name)
+          validate_symbol_arg_position!(symbol_arg_position)
+          validate_modules_by_symbol!(modules_by_symbol)
+          validate_always_included!(always_included)
+
+          @receiver_constraint = receiver_constraint.dup.freeze
+          @method_name = method_name.to_sym
+          @symbol_arg_position = symbol_arg_position
+          @modules_by_symbol = modules_by_symbol.to_h { |k, v| [k.to_sym, v.dup.freeze] }.freeze
+          @always_included = always_included.map { |m| m.dup.freeze }.freeze
+          freeze
+        end
+
+        def to_h
+          {
+            "receiver_constraint" => receiver_constraint,
+            "method_name" => method_name.to_s,
+            "symbol_arg_position" => symbol_arg_position.to_s,
+            "modules_by_symbol" => modules_by_symbol.to_h { |k, v| [k.to_s, v] },
+            "always_included" => always_included
+          }
+        end
+
+        def ==(other)
+          other.is_a?(TraitRegistry) && to_h == other.to_h
+        end
+        alias eql? ==
+
+        def hash
+          to_h.hash
+        end
+
+        # @return [String, nil] fully-qualified module name for the
+        #   given trait symbol, or nil when the registry doesn't
+        #   know the symbol (caller emits a tier_b.unknown-trait
+        #   provenance marker and falls through).
+        def module_for(symbol)
+          modules_by_symbol[symbol.to_sym]
+        end
+
+        private
+
+        def validate_receiver_constraint!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::TraitRegistry#receiver_constraint must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_method_name!(value)
+          return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+          raise ArgumentError,
+                "Plugin::Macro::TraitRegistry#method_name must be Symbol or non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_symbol_arg_position!(value)
+          return if value == REST_POSITION || (value.is_a?(Integer) && value >= 0)
+
+          raise ArgumentError,
+                "Plugin::Macro::TraitRegistry#symbol_arg_position must be :rest or a non-negative Integer, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_modules_by_symbol!(value)
+          unless value.is_a?(Hash)
+            raise ArgumentError,
+                  "Plugin::Macro::TraitRegistry#modules_by_symbol must be a Hash, got #{value.inspect}"
+          end
+
+          value.each do |k, v|
+            unless k.is_a?(Symbol) || (k.is_a?(String) && !k.empty?)
+              raise ArgumentError,
+                    "Plugin::Macro::TraitRegistry#modules_by_symbol key must be Symbol/non-empty String, " \
+                    "got #{k.inspect}"
+            end
+            next if v.is_a?(String) && !v.empty?
+
+            raise ArgumentError,
+                  "Plugin::Macro::TraitRegistry#modules_by_symbol value must be a non-empty String, " \
+                  "got #{v.inspect}"
+          end
+        end
+
+        def validate_always_included!(value)
+          unless value.is_a?(Array)
+            raise ArgumentError,
+                  "Plugin::Macro::TraitRegistry#always_included must be an Array, got #{value.inspect}"
+          end
+
+          value.each do |m|
+            next if m.is_a?(String) && !m.empty?
+
+            raise ArgumentError,
+                  "Plugin::Macro::TraitRegistry#always_included entry must be a non-empty String, " \
+                  "got #{m.inspect}"
+          end
+        end
+      end
+    end
+  end
+end