poetry-core 0.0.2

data/app/components/poetry/core/concerns/agent_tools.rb

@@ -0,0 +1,418 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Poetry
+  module Core
+    module Concerns
+      # The agent-tool contract: class-level declarations of the
+      # component's agent-callable tools - the "operate" projection of the
+      # component's Stimulus surface. A tool names one action an in-page
+      # agent may invoke on a rendered instance (WebMCP's
+      # `document.modelContext`, or any client that reads the registry),
+      # described in MCP `Tool` shape: name, description, JSON-Schema
+      # input, and safety annotations.
+      #
+      #   tool :set_value,
+      #        description: "Select the option whose value matches.",
+      #        params: { value: { type: "string", required: true,
+      #                           description: "The option value to select." } },
+      #        executes: :set_value,
+      #        mutating: true
+      #
+      # Declarations are validated at CLASS LOAD, like use_stimulus:
+      # `executes:` resolves through {Concerns::Stimulus#stimulus_action}
+      # against the component's declared controllers and the controllers
+      # manifest, so a tool can never name an action the JS does not
+      # define - declare `use_stimulus` before `tool`. The resolved
+      # descriptor ("poetry--core--combobox#setValue") is the tool's wire
+      # form: registration runtimes dispatch it verbatim.
+      #
+      # Safety doctrine (non-negotiable): tools are read-only unless
+      # declared `mutating: true` (`annotations.readOnlyHint` inverts it),
+      # `untrusted_content: true` marks tools whose output carries
+      # user-authored content, and declaring a tool exposes NOTHING by
+      # itself - emission is opt-in per rendered instance, owned by the
+      # registration runtime, never default-on.
+      #
+      # Projection: {ClassMethods#tool_definitions} feeds the registry's
+      # per-component `tools` section (plain strings, YAML-safe), which
+      # the agent surfaces (llms.txt, MCP server, skills, docs) and the
+      # WebMCP registration payload all read - one contract, every
+      # surface.
+      module AgentTools
+        extend ActiveSupport::Concern
+
+        # Raised at class load for an invalid tool declaration.
+        class ToolError < Poetry::Core::Error; end
+
+        # One declared tool. `executes` is the declared action spec
+        # (`[method]` or `[controller, method]`) - resolved to a bare
+        # Stimulus descriptor per PROJECTING class (see
+        # {ClassMethods#tool_definitions}); `input_schema` is the
+        # normalized JSON-Schema object (string keys) or nil for a
+        # parameterless tool.
+        Tool = Struct.new(:name, :title, :description, :input_schema,
+                          :executes, :mutating, :untrusted_content,
+                          keyword_init: true)
+
+        # Tool and param names stay inside the WebMCP tool-name grammar
+        # (ASCII alphanumerics, `_`, `-`, `.`) with poetry's stricter
+        # snake_case convention, so a composed full name (instance prefix +
+        # tool name) can never need escaping.
+        NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+        # The house character budgets: names stay far under the spec's
+        # 128-char full-name cap (instance prefixes join later);
+        # descriptions stay inside the agent-legibility budget.
+        NAME_LIMIT = 64
+        # The registrar controller (poetry-agent's) that a `webmcp:` root
+        # registers; its manifest entry joins core's catalog when the gem
+        # loads, so the wiring validates like any other controller.
+        WEBMCP_CONTROLLER = "poetry--agent--webmcp"
+        # The agent-legibility budget for a tool description.
+        DESCRIPTION_LIMIT = 500
+        # The agent-legibility budget for one parameter's description
+        # (Chrome's guidance: 150 characters per parameter description).
+        PARAM_DESCRIPTION_LIMIT = 150
+        # The registrar's built-in per-document registration budget; the
+        # root carries an explicit budget only when the configured value
+        # ({Poetry::Core::Config#webmcp_registration_budget}) differs.
+        WEBMCP_DEFAULT_BUDGET = 20
+
+        class_methods do
+          # Declares one agent-callable tool of this component.
+          #
+          # @param name [Symbol] the tool's name (snake_case; composes into
+          #   the registered full name, so it must satisfy the WebMCP name
+          #   grammar)
+          # @param description [String] what the tool does and when to use
+          #   it - positive, single-function, non-empty (agents pick tools
+          #   by this text)
+          # @param executes [Symbol, Array(Symbol, Symbol)] the Stimulus
+          #   action the tool dispatches: a bare method resolves across the
+          #   component's declared controllers; `[:controller, :method]`
+          #   pins one. Validated against the controllers manifest at
+          #   class load.
+          # @param params [Hash{Symbol => Hash}, nil] the tool's parameters
+          #   as `name => spec`; each spec requires `type:` and may carry
+          #   `required: true` (folded into the schema's `required` list)
+          #   plus any JSON-Schema keywords (`description:` - at most
+          #   {PARAM_DESCRIPTION_LIMIT} characters -, `enum:`, ...). The
+          #   generated schema closes with `additionalProperties: false`,
+          #   so a runtime rejects parameters the tool never declared.
+          # @param input_schema [Hash, nil] a complete JSON-Schema object
+          #   for advanced shapes - mutually exclusive with `params:`
+          # @param title [String, nil] human-readable label for agent UIs
+          #   (the spec's UA-displayable field); defaults to the tool name
+          #   humanized (`set_value` -> "Set value")
+          # @param mutating [Boolean] declare true when invoking the tool
+          #   changes state; tools are read-only by default
+          #   (`annotations.readOnlyHint` is the inverse of this flag)
+          # @param untrusted_content [Boolean] declare true when the
+          #   tool's output can carry user-authored content
+          # @return [void]
+          # @raise [ToolError] at class load for a duplicate name, invalid
+          #   name/description/params, or an `executes:` action the
+          #   declared controllers do not define
+          # @example A parameterless UI-state tool
+          #   tool :open, description: "Open the dialog.",
+          #        executes: :open, mutating: true
+          def tool(name, description:, executes:, # rubocop:disable Metrics/ParameterLists -- one keyword per Tool field
+                   params: nil, input_schema: nil, title: nil, mutating: false, untrusted_content: false)
+            name = validate_tool_name!(name)
+            raise ToolError, "#{self}: tool #{name.inspect} declared twice" if own_tools.key?(name)
+
+            validate_tool_action!(name, executes) # the class-load gate; resolution happens at projection
+            own_tools[name] = AgentTools::Tool.new(
+              name: name,
+              title: title&.to_s,
+              description: validate_tool_description!(name, description),
+              input_schema: normalize_tool_schema!(name, params, input_schema),
+              executes: Array(executes).map(&:to_sym),
+              mutating: mutating ? true : false,
+              untrusted_content: untrusted_content ? true : false
+            )
+          end
+
+          # This class's own tool declarations, name => {Tool}.
+          #
+          # @return [Hash{Symbol => Tool}]
+          def own_tools
+            @own_tools ||= {}
+          end
+
+          # The effective tools after inheritance: superclass chain
+          # root-first, a subclass redeclaring a name replaces it.
+          #
+          # @return [Hash{Symbol => Tool}]
+          def tools
+            chain = []
+            klass = self
+            while klass.respond_to?(:own_tools)
+              chain.unshift(klass)
+              klass = klass.superclass
+            end
+
+            chain.each_with_object({}) do |ancestor, resolved|
+              resolved.merge!(ancestor.own_tools)
+            end
+          end
+
+          # The registry-shaped projection of the resolved tools: MCP
+          # `Tool` fields (name / title / description / inputSchema /
+          # annotations) plus the `executes` dispatch descriptor - plain
+          # string keys, YAML round-trippable.
+          #
+          # `executes` resolves HERE, against the projecting class: a
+          # subclass that re-controllers its root (Sheet over Dialog)
+          # projects its own controller's descriptor for an inherited
+          # bare `executes: :open`, and a pinned controller the subclass
+          # no longer wires raises instead of projecting a descriptor the
+          # rendered DOM cannot dispatch.
+          #
+          # @return [Array<Hash>]
+          # @raise [ToolError] when an inherited tool's action does not
+          #   resolve on this class's declared controllers
+          def tool_definitions
+            tools.values.map do |tool|
+              definition = { "name" => tool.name.to_s }
+              definition["title"] = tool.title || default_tool_title(tool.name)
+              definition["description"] = tool.description
+              definition["inputSchema"] = tool.input_schema if tool.input_schema
+              definition["annotations"] = {
+                "readOnlyHint" => !tool.mutating,
+                "untrustedContentHint" => tool.untrusted_content
+              }
+              definition["executes"] = resolve_tool_action(tool)
+              definition
+            end
+          end
+
+          # The bare Stimulus descriptor a tool dispatches on THIS class.
+          #
+          # @param tool [Tool]
+          # @return [String] e.g. "poetry--core--combobox#setValue"
+          # @raise [ToolError] when the action does not resolve on the
+          #   class's declared controllers, or resolves to a controller
+          #   the class does not wire
+          def resolve_tool_action(tool)
+            descriptor = validate_tool_action!(tool.name, tool.executes)
+            identifier = descriptor.split("#").first
+            return descriptor if stimulus_identifiers.include?(identifier)
+
+            raise ToolError,
+                  "#{self}: tool #{tool.name.inspect} executes #{descriptor}, but #{self} does not " \
+                  "wire #{identifier} (declared: #{stimulus_identifiers.join(", ")}) - redeclare the " \
+                  "tool on #{self} with the controller it wires"
+          end
+
+          private
+
+          # The UA-displayable default title: the snake_case name as
+          # words, first letter up ("set_value" -> "Set value").
+          #
+          # @api private
+          def default_tool_title(name)
+            words = name.to_s.tr("_", " ")
+            words[0].upcase + words[1..]
+          end
+
+          # @api private
+          def validate_tool_name!(name)
+            unless name.is_a?(Symbol) || name.is_a?(String)
+              raise ToolError, "#{self}: tool name must be a Symbol (got #{name.class})"
+            end
+
+            text = name.to_s
+            unless NAME_PATTERN.match?(text) && text.length <= NAME_LIMIT
+              raise ToolError,
+                    "#{self}: invalid tool name #{name.inspect} - snake_case " \
+                    "([a-z][a-z0-9_]*), at most #{NAME_LIMIT} characters"
+            end
+            text.to_sym
+          end
+
+          # @api private
+          def validate_tool_description!(name, description)
+            text = description.to_s.strip
+            if text.empty? || text.length > DESCRIPTION_LIMIT
+              raise ToolError,
+                    "#{self}: tool #{name.inspect} description must be present and " \
+                    "at most #{DESCRIPTION_LIMIT} characters"
+            end
+            text
+          end
+
+          # The `executes:` gate: build the bare descriptor through the
+          # class's own stimulus_action, which resolves the controller
+          # across the use_stimulus declarations and validates the method
+          # against the controllers manifest. Returns the descriptor;
+          # callers keep the spec (`Array(executes)`) for re-resolution.
+          #
+          # @api private
+          def validate_tool_action!(name, executes)
+            args = Array(executes)
+            unless args.size.between?(1, 2) && args.all? { |arg| arg.is_a?(Symbol) || arg.is_a?(String) }
+              raise ToolError,
+                    "#{self}: tool #{name.inspect} executes: takes a method Symbol " \
+                    "or [controller, method]"
+            end
+
+            begin
+              stimulus_action(*args)
+            rescue ArgumentError, Poetry::Core::Stimulus::Declarations::DeclarationError,
+                   Poetry::Core::Stimulus::Manifest::UnknownName => e
+              raise ToolError,
+                    "#{self}: tool #{name.inspect} executes: #{executes.inspect} - " \
+                    "#{e.message} (declare use_stimulus before tool)"
+            end
+          end
+
+          # @api private
+          def normalize_tool_schema!(name, params, input_schema)
+            if params && input_schema
+              raise ToolError,
+                    "#{self}: tool #{name.inspect} takes ONE of params: or input_schema:"
+            end
+            return deep_stringify_tool_keys(validate_input_schema!(name, input_schema)) if input_schema
+            return nil if params.nil? || params.empty?
+
+            raise ToolError, "#{self}: tool #{name.inspect} params: must be a Hash" unless params.is_a?(Hash)
+
+            properties = {}
+            required = []
+            params.each do |param_name, spec|
+              param = validate_tool_name!(param_name).to_s
+              unless spec.is_a?(Hash) && (spec[:type] || spec["type"])
+                raise ToolError,
+                      "#{self}: tool #{name.inspect} param #{param_name.inspect} needs " \
+                      "a Hash spec with type:"
+              end
+              spec = deep_stringify_tool_keys(spec)
+              required << param if spec.delete("required")
+              validate_param_description!(name, param, spec["description"])
+              properties[param] = spec
+            end
+
+            schema = { "type" => "object", "properties" => properties }
+            schema["required"] = required if required.any?
+            schema["additionalProperties"] = false
+            schema
+          end
+
+          # @api private
+          def validate_param_description!(name, param, description)
+            return if description.nil?
+
+            text = description.to_s
+            return unless text.strip.empty? || text.length > PARAM_DESCRIPTION_LIMIT
+
+            raise ToolError,
+                  "#{self}: tool #{name.inspect} param #{param.inspect} description must be present " \
+                  "and at most #{PARAM_DESCRIPTION_LIMIT} characters"
+          end
+
+          # @api private
+          def validate_input_schema!(name, input_schema)
+            unless input_schema.is_a?(Hash) && (input_schema[:type] || input_schema["type"])
+              raise ToolError,
+                    "#{self}: tool #{name.inspect} input_schema: must be a JSON-Schema " \
+                    "Hash with type:"
+            end
+            input_schema
+          end
+
+          # @api private
+          def deep_stringify_tool_keys(value)
+            case value
+            when Hash then value.to_h { |key, inner| [key.to_s, deep_stringify_tool_keys(inner)] }
+            when Array then value.map { |inner| deep_stringify_tool_keys(inner) }
+            when Symbol then value.to_s
+            else value
+            end
+          end
+        end
+        # Whether this rendered instance opted into WebMCP registration
+        # (`webmcp: true` or `webmcp: "name"` on the call).
+        #
+        # @return [Boolean]
+        def webmcp_enabled?
+          !!@webmcp
+        end
+
+        # The instance name the registrar composes tool names from
+        # (`poetry.{name}.{tool}`): the explicit `webmcp:` string, else the
+        # component title (give instances explicit names when a page
+        # renders several of one component - the browser rejects
+        # duplicate tool names).
+        #
+        # @return [String, nil] nil when not enabled
+        # @raise [ToolError] when the explicit name is not a valid instance
+        #   name
+        def webmcp_name
+          return nil unless webmcp_enabled?
+
+          name = (@webmcp == true ? self.class.component_title : @webmcp.to_s).tr("-", "_")
+          unless NAME_PATTERN.match?(name) && name.length <= NAME_LIMIT
+            raise ToolError,
+                  "#{self.class}: webmcp: #{@webmcp.inspect} is not a valid instance name " \
+                  "(snake_case, at most #{NAME_LIMIT} characters)"
+          end
+          name
+        end
+
+        # The instance's registration payload: its resolved tool
+        # definitions, each passed through {#webmcp_tool_definition} so a
+        # component can enrich a schema with rendered facts (Tabs adds the
+        # rendered tab values as an enum).
+        #
+        # @return [Array<Hash>]
+        def webmcp_tools
+          self.class.tool_definitions.map { |definition| webmcp_tool_definition(definition) }
+        end
+
+        # The per-instance enrichment hook - override to refine a tool's
+        # projected definition with what only the rendered instance knows.
+        # Must return a JSON-serializable Hash with the same keys.
+        #
+        # @param definition [Hash] the class-level projection
+        # @return [Hash]
+        def webmcp_tool_definition(definition)
+          definition
+        end
+
+        # The registrar wiring for the root: applied by
+        # {Concerns::Stimulus#stimulus_attributes_for} on the ONE shared
+        # Attributes instance, so data-controller merges correctly with
+        # the component's own controllers. Raises when the runtime gem is
+        # absent - opting in without poetry-agent is a configuration error,
+        # not a silent no-op.
+        #
+        # @param attrs [Poetry::Core::HTML::Attributes]
+        # @return [void]
+        # @api private
+        def apply_webmcp_wiring(attrs)
+          return unless webmcp_enabled?
+
+          unless Poetry::Core::Stimulus::Manifest.catalog.key?(WEBMCP_CONTROLLER)
+            raise ToolError,
+                  "#{self.class}: webmcp: requires the poetry-agent gem (its #{WEBMCP_CONTROLLER} " \
+                  "controller is not registered) - add `gem \"poetry-agent\"` to the Gemfile"
+          end
+          if self.class.tools.empty?
+            raise ToolError,
+                  "#{self.class}: webmcp: opted in, but the component declares no tools"
+          end
+
+          builder = Poetry::Core::Stimulus::Builder.new(WEBMCP_CONTROLLER, attrs)
+          builder.register_controller
+          builder.with_value(:name, webmcp_name)
+          builder.with_value(:tools, JSON.generate(webmcp_tools))
+          budget = Poetry::Core::Config.current.webmcp_registration_budget
+          builder.with_value(:budget, budget) if budget != WEBMCP_DEFAULT_BUDGET
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/core/concerns/declared_attributes.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Concerns
+      # The declared-attribute engine shared by the Styles and Options DSLs.
+      # Each DSL is one "kind" of declared attribute: registration lands in
+      # per-kind class-level collections (@_<kind>_attributes,
+      # @_<kind>_attributes_with_defaults, @_<kind>_proc_defaults), explicit
+      # initialization is tracked per instance through the registered_<kind>s
+      # class_attribute the owning concern declares, and hierarchy-wide
+      # queries walk the ancestry up to the base component class.
+      # Kind-specific surface - variants and CSS emission for styles,
+      # ActiveModel types and value formats for options - stays in the
+      # owning concern.
+      module DeclaredAttributes
+        extend ActiveSupport::Concern
+
+        # Where ancestor walks stop: declarations above the base component
+        # class are nobody's.
+        BASE_COMPONENT_CLASS = Poetry::Core::Component
+
+        class_methods do
+          private
+
+          # Registers a declared attribute in the per-kind class-level
+          # collections. Runs before any option extraction so the presence
+          # of :default (static or proc) is still observable.
+          #
+          # The :doc string is documentation, not an ActiveModel option - it
+          # is lifted out here (before `attribute` ever sees the hash) into
+          # the per-kind docs map that the registry and doc build project.
+          #
+          # @param kind [Symbol] :style or :option
+          # @param name [Symbol, String] the attribute name
+          # @param options [Hash] the attribute options
+          def register_declared_attribute(kind, name, options)
+            declared_ivar_set(:"@_#{kind}_attributes") << name.to_sym
+
+            doc = options.delete(:doc)
+            declared_ivar_hash(:"@_#{kind}_docs")[name.to_sym] = doc if doc
+
+            declared_ivar_set(:"@_#{kind}_attributes_with_defaults") << name.to_sym if options.key?(:default)
+
+            return unless options[:default].is_a?(Proc)
+
+            declared_ivar_hash(:"@_#{kind}_proc_defaults")[name.to_sym] = options[:default]
+          end
+
+          # The declaration docs for a kind, hierarchy-wide (nearest
+          # declaration wins).
+          #
+          # @param kind [Symbol] :style or :option
+          # @return [Hash{Symbol => String}]
+          def declared_docs(kind)
+            collect_declared_map(:"@_#{kind}_docs")
+          end
+
+          # Extracts the shared :default/:required options. A proc default
+          # is deleted so ActiveModel never installs it (the getter override
+          # evaluates it lazily against the instance); a static default
+          # stays in the hash for `attribute` to install.
+          #
+          # @param options [Hash] the original options hash
+          # @return [Array<(Boolean, Object)>] required and default_value
+          def extract_declared_defaults(options)
+            default_value = options[:default]
+            options.delete(:default) if default_value.is_a?(Proc)
+
+            required = options.delete(:required) || false
+
+            [required, default_value]
+          end
+
+          # Sets up per-instance initialization tracking: every declared
+          # attribute records explicit writes; a proc default additionally
+          # resolves through the tracked state on read.
+          #
+          # @param kind [Symbol] :style or :option
+          # @param name [Symbol] the attribute name
+          # @param default_value [Object] the default value (may be a Proc)
+          def setup_declared_tracking(kind, name, default_value)
+            override_declared_setter_for_tracking(kind, name)
+            override_declared_getter_for_proc_default(kind, name, default_value) if default_value.is_a?(Proc)
+          end
+
+          # Overrides the setter to record the attribute in the kind's
+          # registered set.
+          #
+          # @param kind [Symbol] :style or :option
+          # @param name [Symbol] the attribute name
+          def override_declared_setter_for_tracking(kind, name)
+            original_setter = instance_method("#{name}=")
+            registry_reader = :"registered_#{kind}s"
+            registry_writer = :"registered_#{kind}s="
+
+            define_method("#{name}=") do |value|
+              public_send(registry_writer, Set.new) if public_send(registry_reader).nil?
+              public_send(registry_reader) << name.to_sym
+              original_setter.bind_call(self, value)
+            end
+          end
+
+          # Overrides the getter so an unset attribute evaluates its proc
+          # default against the instance (other attributes are readable),
+          # surfacing the value in the attributes hash without marking the
+          # attribute initialized - reads keep following the proc until an
+          # explicit write.
+          #
+          # @param kind [Symbol] :style or :option
+          # @param name [Symbol] the attribute name
+          # @param default_value [Proc] the proc that provides the default value
+          def override_declared_getter_for_proc_default(kind, name, default_value)
+            original_getter = instance_method(name)
+            initialized_predicate = :"#{kind}_attribute_initialized?"
+
+            define_method(name) do
+              if public_send(initialized_predicate, name)
+                original_getter.bind_call(self)
+              else
+                value = instance_exec(&default_value)
+                @attributes.write_from_user(name.to_s, value)
+                value
+              end
+            end
+          end
+
+          # All declared attributes of a kind across the hierarchy.
+          #
+          # @param kind [Symbol] :style or :option
+          # @return [Array<Symbol>] sorted array of attribute names
+          def declared_attributes(kind)
+            collect_declared_set(:"@_#{kind}_attributes")
+          end
+
+          # Declared attributes of a kind with any default (static or proc).
+          #
+          # @param kind [Symbol] :style or :option
+          # @return [Array<Symbol>] sorted array of attribute names
+          def declared_attributes_with_defaults(kind)
+            collect_declared_set(:"@_#{kind}_attributes_with_defaults")
+          end
+
+          # Declared attributes of a kind with a static (non-proc) default.
+          #
+          # @param kind [Symbol] :style or :option
+          # @return [Array<Symbol>] sorted array of attribute names
+          def declared_attributes_with_static_defaults(kind)
+            proc_defaults_ivar = :"@_#{kind}_proc_defaults"
+
+            collect_declared_set(:"@_#{kind}_attributes_with_defaults") do |attributes_set, defaults, klass|
+              next unless defaults
+
+              proc_defaults = klass.instance_variable_get(proc_defaults_ivar)
+              defaults.each do |attr|
+                attributes_set << attr unless proc_defaults&.key?(attr)
+              end
+            end
+          end
+
+          # Declared attributes of a kind with a proc default.
+          #
+          # @param kind [Symbol] :style or :option
+          # @return [Array<Symbol>] sorted array of attribute names
+          def declared_attributes_with_proc_defaults(kind)
+            collect_declared_set(:"@_#{kind}_proc_defaults") do |attributes_set, proc_defaults, _klass|
+              attributes_set.merge(proc_defaults.keys) if proc_defaults
+            end
+          end
+
+          # Collects a Set-valued class-level collection across the
+          # hierarchy.
+          #
+          # @param ivar_name [Symbol] the instance variable name to collect
+          # @yield [attributes_set, values, klass] optional block for custom collection logic
+          # @return [Array<Symbol>] sorted array of collected attributes
+          def collect_declared_set(ivar_name)
+            attributes_set = Set.new
+
+            declared_hierarchy do |klass|
+              values = klass.instance_variable_get(ivar_name)
+
+              if block_given?
+                yield(attributes_set, values, klass)
+              elsif values
+                attributes_set.merge(values)
+              end
+            end
+
+            attributes_set.to_a.sort
+          end
+
+          # Collects a Hash-valued class-level collection across the
+          # hierarchy; the nearest declaration wins on key conflicts.
+          #
+          # @param ivar_name [Symbol] the instance variable name to collect
+          # @return [Hash{Symbol => Object}]
+          def collect_declared_map(ivar_name)
+            map = {}
+
+            declared_hierarchy do |klass|
+              klass_map = klass.instance_variable_get(ivar_name)
+              map = klass_map.merge(map) if klass_map
+            end
+
+            map
+          end
+
+          # Walks the ancestry from this class toward the base component
+          # class, yielding each class that can carry declarations. The base
+          # class itself is never yielded.
+          def declared_hierarchy
+            klass = self
+
+            while klass&.respond_to?(:instance_variable_get)
+              yield klass
+
+              klass = klass.superclass
+              break if klass == BASE_COMPONENT_CLASS || !klass.ancestors.include?(BASE_COMPONENT_CLASS)
+            end
+          end
+
+          # The class-level Set for an ivar, created on first use.
+          #
+          # @param ivar_name [Symbol]
+          # @return [Set]
+          def declared_ivar_set(ivar_name)
+            instance_variable_get(ivar_name) || instance_variable_set(ivar_name, Set.new)
+          end
+
+          # The class-level Hash for an ivar, created on first use.
+          #
+          # @param ivar_name [Symbol]
+          # @return [Hash]
+          def declared_ivar_hash(ivar_name)
+            instance_variable_get(ivar_name) || instance_variable_set(ivar_name, {})
+          end
+        end
+
+        # The cop cannot see across the class_methods block boundary: this
+        # modifier governs the module's instance methods, not the block's.
+        private # rubocop:disable Lint/UselessAccessModifier
+
+        # The initialized-attribute list behind a kind's registered set.
+        #
+        # @param registry [Set, nil] the per-instance registered set
+        # @return [Array<Symbol>] sorted array of initialized attribute names
+        def initialized_declared_attributes(registry)
+          return [] if registry.nil?
+
+          registry.to_a.sort
+        end
+
+        # Whether an attribute is recorded in a kind's registered set.
+        #
+        # @param registry [Set, nil] the per-instance registered set
+        # @param name [Symbol, String] the attribute name
+        # @return [Boolean] true if the attribute was explicitly set
+        def declared_attribute_registered?(registry, name)
+          return false if registry.nil?
+
+          registry.include?(name.to_sym)
+        end
+      end
+    end
+  end
+end