adornment-core 0.1.0

data/lib/adornment/core/hooks.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Passes the reflection API on to includers, prependers and extenders of a module: prepended to
+    # activated modules at activation, and by {Attachment.grant} to plain modules that include or
+    # prepend one (Ruby calls `included` only on the module included directly, so each module in
+    # the chain must pass it on). Classes never get it: nothing includes a class.
+    # @api private
+    module Propagation
+      # Grants reflection to the includer, then calls the next `included`. The arguments are
+      # forwarded unchanged, so an `included do ... end` DSL defined on the module (called with no
+      # base and a block) keeps working.
+      # @param args [Array] the includer, as Ruby passes it (or nothing, for a DSL block call)
+      # @return [Object] whatever the next `included` returns
+      def included(*args, &)
+        Attachment.grant(args[0], :include) if args[0].is_a?(Module)
+        super
+      end
+
+      # Grants reflection to the prepender, then calls the next `prepended`.
+      # @param args [Array] the prepender, as Ruby passes it
+      # @return [Object] whatever the next `prepended` returns
+      def prepended(*args, &)
+        Attachment.grant(args[0], :prepend) if args[0].is_a?(Module)
+        super
+      end
+
+      # Grants reflection to the extender (the extended object's singleton side), then calls the
+      # next `extended`.
+      # @param args [Array] the extended object, as Ruby passes it
+      # @return [Object] whatever the next `extended` returns
+      def extended(*args, &)
+        Attachment.grant(args[0], :extend) if args[0].is_a?(Module)
+        super
+      end
+
+      private :included, :prepended, :extended
+    end
+
+    # Definition hooks prepended to an activated owner's singleton class (once per ancestry:
+    # subclasses inherit them). A definition takes the owner's pending declarations; a definition
+    # with nothing pending does nothing, so ordinary definitions cost one fiber-local lookup.
+    # Like any Ruby hook, an owner's own `method_added` must call `super`.
+    # @api private
+    module Hooks
+      # An instance method entry was added: it takes the owner's pending declarations, if any.
+      # @param name [Symbol]
+      # @return [Object] whatever the next `method_added` returns
+      # @raise [Adornment::InvalidTarget, Adornment::DefinitionError] from the attachment checks
+      def method_added(name)
+        Attachment.added(self, name, :instance) if Pending.for?(self)
+        super
+      end
+
+      # A singleton method entry was added: it takes the owner's pending declarations, if any.
+      # @param name [Symbol]
+      # @return [Object] whatever the next `singleton_method_added` returns
+      # @raise [Adornment::InvalidTarget, Adornment::DefinitionError] from the attachment checks
+      def singleton_method_added(name)
+        Attachment.added(self, name, :singleton) if Pending.for?(self)
+        super
+      end
+
+      # A constant was added to the owner: pending declarations can no longer attach.
+      # @param name [Symbol]
+      # @return [Object] whatever the next `const_added` returns
+      # @raise [Adornment::LeftoverAnnotations] when the owner has pending declarations
+      def const_added(name)
+        Pending.const_added(self, name)
+        super
+      end
+
+      private :method_added, :singleton_method_added, :const_added
+    end
+  end
+end

data/lib/adornment/core/immutable.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Deep-frozen copies of annotation values (public as {Adornment.immutable_copy}).
+    #
+    # Array, Hash, Set and String values are copied and frozen, recursively; the caller's objects
+    # are never mutated or frozen. Other objects are kept by reference. A value that is already
+    # deeply immutable (`Ractor.shareable?`, which CRuby answers in O(1) once an object is known
+    # to be shareable) is returned as it is, since nobody can mutate it. The identity table that
+    # preserves cycles and shared subgraphs is allocated only when a container is traversed.
+    # @api private
+    module Immutable
+      extend self
+
+      # @param value [Object]
+      # @param seen [Hash{Object => Object}, nil] originals to their copies (identity), shared by a
+      #   traversal so cycles and shared subgraphs are copied once
+      # @return [Object] a deep-frozen copy of a String, Array, Hash or Set; `value` itself when it
+      #   is already deeply immutable or of any other class
+      def copy(value, seen = nil)
+        case value
+        when String
+          value.frozen? ? value : value.dup.freeze
+        when Array, Hash, Set
+          return value if Ractor.shareable?(value)
+
+          container(value, seen || {}.compare_by_identity)
+        else
+          value
+        end
+      end
+
+      # Copies an Array, Hash or Set whose elements may need copying.
+      # @param value [Array, Hash, Set]
+      # @param seen [Hash{Object => Object}] see {copy}
+      # @return [Array, Hash, Set] a frozen copy (a Hash keeps `compare_by_identity`)
+      def container(value, seen)
+        return seen[value] if seen.key?(value)
+
+        case value
+        when Array
+          seen[value] = out = []
+          value.each { |v| out << copy(v, seen) }
+        when Hash
+          seen[value] = out = value.compare_by_identity? ? {}.compare_by_identity : {}
+          value.each { |k, v| out[copy(k, seen)] = copy(v, seen) }
+        else # Set
+          seen[value] = out = Set.new
+          value.each { |v| out << copy(v, seen) }
+        end
+        out.freeze
+      end
+    end
+  end
+end

data/lib/adornment/core/private/annotation_methods.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # An owner's annotation methods: one per annotation type, named after it (`Traced(...)`),
+    # declaring an annotation of that type for the next definition. Extended into the owner, so
+    # its subclasses inherit them and nothing is defined globally.
+    # @api private
+    class AnnotationMethods < Module
+      # @return [Hash{Symbol => Class}] frozen; method name => annotation type
+      attr_reader :types
+
+      # @param owner [Module]
+      # @return [AnnotationMethods] the owner's own module, created and extended into the owner on
+      #   first use (a subclass of an activated class gets its own on its first `use_annotations`)
+      def self.for(owner)
+        state = State.for(owner)
+        methods = state.annotation_methods || state.lock.synchronize { state.annotation_methods ||= new(owner) }
+        owner.extend(methods) unless owner.singleton_class.include?(methods) # outside the lock
+        methods
+      end
+
+      # @param owner [Module]
+      # @return [Hash{Symbol => Class}] the annotation methods usable on `owner` (its own and
+      #   inherited ones; nearer modules win)
+      def self.types_of(owner)
+        owner.singleton_class.ancestors.grep(AnnotationMethods).reverse_each.inject({}) { |all, d| all.merge(d.types) }
+      end
+
+      # @param owner [Module] the owner this module belongs to (shown by {#inspect})
+      def initialize(owner)
+        super()
+        @owner = owner
+        @types = {}.freeze
+      end
+
+      # Defines the method `name`, which declares `type.new(*args, **kwargs)` for the next
+      # definition of the receiver. Adding the same name and type again does nothing; another type
+      # under the same name replaces the method.
+      # @param name [Symbol]
+      # @param type [Class] an annotation type
+      # @return [void]
+      def add(name, type)
+        return if @types[name].equal?(type) # activated again with the same vocabulary
+
+        remove_method(name) if @types.key?(name)
+        @types = @types.merge(name => type).freeze
+        define_method(name) do |*args, **kwargs, &block|
+          raise ArgumentError, "#{name}(...) takes no block" if block
+
+          location = caller_locations(1, 1).first # the user's declaration, captured once
+          Attachment.declare(self, type.new(*args, **kwargs), location)
+        end
+      end
+
+      # @return [String] `#<Adornment::Core::AnnotationMethods Owner>`
+      def inspect = "#<Adornment::Core::AnnotationMethods #{@owner.inspect}>"
+      alias to_s inspect
+    end
+  end
+end

data/lib/adornment/core/private/attachment.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Declaration, definitions and verification, plus the activation check and the reflection grant
+    # for includers. Activation itself is {Target.extended}.
+    # @api private
+    module Attachment
+      # --- activation and propagation ------------------------------------------------------
+
+      extend self
+
+      # @param owner [Object]
+      # @return [Boolean] whether `owner` is a class or module with the definition hooks
+      def activated?(owner) = owner.is_a?(Module) && owner.singleton_class.include?(Hooks)
+
+      # Includers, prependers and extenders of activated modules get the read-only reflection API,
+      # as activated owners do. Modules among the includers and prependers pass it on to their own
+      # includers.
+      # @param base [Module] the includer, prepender or extender
+      # @param kind [:include, :prepend, :extend]
+      # @return [void]
+      def grant(base, kind)
+        base.extend(Reflection) unless base.singleton_class.include?(Reflection)
+        return if kind == :extend || base.is_a?(Class)
+
+        base.singleton_class.prepend(Propagation) unless base.singleton_class.include?(Propagation)
+      end
+
+      # --- declaration -----------------------------------------------------------------------
+
+      # The shared enqueue of every declaration path (declaration methods and `adorn`).
+      #
+      # @param owner [Module] the class or module declaring
+      # @param annotation [Adornment::Annotation]
+      # @param location [Thread::Backtrace::Location, nil] the user's call, captured once by the
+      #   public entry point with `caller_locations(1, 1)` and formatted lazily
+      # @return [nil]
+      # @raise [ArgumentError] when `annotation` is not an annotation instance
+      # @raise [Adornment::DuplicateAnnotation, Adornment::LeftoverAnnotations] see {Pending.push!}
+      def declare(owner, annotation, location)
+        check_instance!(annotation)
+        Pending.push!(owner, annotation, location)
+      end
+
+      # Raises unless `annotation` is a method annotation instance.
+      # @param annotation [Object]
+      # @return [void]
+      # @raise [ArgumentError] naming `Type.new(...)` when `annotation` is a type
+      def check_instance!(annotation)
+        return if annotation.is_a?(Annotation)
+
+        if annotation.is_a?(Class) && annotation < Annotation
+          raise ArgumentError, "#{annotation.inspect} is an annotation type, not an instance; " \
+                               "pass #{annotation.short_name}.new(...)"
+        end
+        raise ArgumentError, "expected an Adornment annotation instance, got #{annotation.inspect}"
+      end
+
+      # --- definitions -----------------------------------------------------------------------
+
+      # A new entry for `name` on `owner`, which has pending declarations: it takes them,
+      # replacing the entry's annotations. Every entry Ruby reports counts: definitions, copies
+      # (aliases, `module_function`) and visibility changes of inherited methods alike.
+      # The pending declarations are taken first, so a failed check leaves none behind and
+      # attaches nothing.
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param side [:instance, :singleton]
+      # @return [void]
+      # @raise [Adornment::InvalidTarget] for an annotation whose type does not target `side`
+      # @raise [Adornment::DefinitionError] when a validator rejects the method
+      def added(owner, name, side)
+        pending = Pending.take(owner)
+        annotations = pending.map(&:annotation).freeze
+        unless annotations.all? { |a| a.class.targets.include?(side) }
+          wrong = annotations.reject { |a| a.class.targets.include?(side) }
+          raise InvalidTarget, "#{describe(owner, name, side)}: #{wrong.map(&:inspect).join(', ')} " \
+                               "cannot annotate #{side} methods (targets: #{wrong.first.class.targets.inspect})"
+        end
+        site = Site.new(owner, name, side, annotations)
+        pending.each { |declaration| validate!(declaration, site) }
+        State.for(owner).set_entry(side, name, annotations)
+      end
+
+      # Runs one declaration's validator; a StandardError becomes a DefinitionError (its cause)
+      # pointing at the declaration.
+      # @param declaration [Pending::PendingDeclaration]
+      # @param site [Site]
+      # @return [void]
+      # @raise [Adornment::DefinitionError] with the validator's error as `cause`
+      def validate!(declaration, site)
+        declaration.annotation.validate(site)
+      rescue StandardError => e
+        location = declaration.location
+        error = DefinitionError.new("#{site.label}: #{e.message}" \
+                                    "#{" (declared at #{location})" if location}")
+        error.set_backtrace(location ? [location, *caller] : caller)
+        raise error, cause: e
+      end
+
+      # --- verification ----------------------------------------------------------------------
+
+      # Takes the owner's pending declarations and raises if there were any.
+      # @param owner [Module]
+      # @return [nil]
+      # @raise [Adornment::LeftoverAnnotations]
+      def verify(owner)
+        left = Pending.take(owner)
+        raise LeftoverAnnotations.new({ owner => left }) unless left.empty?
+
+        nil
+      end
+
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param side [:instance, :singleton]
+      # @return [String] `Owner#name` or `Owner.name`
+      def describe(owner, name, side) = "#{owner.inspect}#{side == :singleton ? '.' : '#'}#{name}"
+    end
+  end
+end

data/lib/adornment/core/private/pending.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Pending declarations: one fiber-local Hash, `{owner => [PendingDeclaration, ...]}`, that
+    # compares owners by identity (no user `hash`/`eql?` is called).
+    #
+    # Declarations wait for the next method definition of the owner they were made on, so at
+    # most one owner has pending declarations at a time. These raise {LeftoverAnnotations}
+    # (and clear the pending declarations):
+    #
+    # - a declaration on another owner while declarations are still pending;
+    # - a constant added to the owner while it has pending declarations (a nested
+    #   `class Inner`, `X = ...`), via `const_added`.
+    #
+    # Nothing traces body ends: declarations left at the end of a body stay pending until one of
+    # the above, the owner's next definition, or verification. Pending declarations are seen
+    # only by their own fiber.
+    # @api private
+    module Pending
+      # The fiber-local key of the table.
+      KEY = :__adornment_core_pending__
+      # The shared empty result.
+      NONE = [].freeze
+
+      # A declaration waiting for the next method definition.
+      #
+      # The caller location is kept as captured and formatted only when it is read (diagnostics).
+      class PendingDeclaration
+        # @return [Adornment::Annotation]
+        attr_reader :annotation
+
+        # @api private
+        # @param annotation [Adornment::Annotation]
+        # @param location [Thread::Backtrace::Location, nil] the declaration's caller location
+        def initialize(annotation, location)
+          @annotation = annotation
+          @location = location
+          freeze
+        end
+
+        # @return [String, nil] `path:line` of the declaration
+        def location
+          loc = @location
+          loc && "#{loc.path}:#{loc.lineno}"
+        end
+
+        # @api private
+        # @return [Thread::Backtrace::Location, nil] the location as captured
+        def raw_location = @location
+
+        # @return [String] `#<Adornment::Core::Pending::PendingDeclaration #<Traced> at path:line>`
+        def inspect = "#<Adornment::Core::Pending::PendingDeclaration #{@annotation.inspect}#{" at #{location}" if @location}>"
+        alias to_s inspect
+      end
+
+      extend self
+
+      # @return [Hash{Module => Array<PendingDeclaration>}] this fiber's table (created on first
+      #   use, compared by identity), at most one entry
+      def table
+        Thread.current[KEY] ||= {}.compare_by_identity
+      end
+
+      # @return [Boolean] whether this fiber has no pending declarations at all
+      def empty? = table.empty?
+
+      # @param owner [Module]
+      # @return [Boolean] whether `owner` has pending declarations in this fiber
+      def for?(owner)
+        t = table
+        !t.empty? && t.key?(owner)
+      end
+
+      # Queues `annotation`, declared at `location`, for `owner`.
+      # @param owner [Module]
+      # @param annotation [Adornment::Annotation]
+      # @param location [Thread::Backtrace::Location, nil]
+      # @return [nil]
+      # @raise [LeftoverAnnotations] when another owner still has pending declarations
+      # @raise [DuplicateAnnotation] for a second non-repeatable annotation of one type (the
+      #   owner's pending declarations are cleared first)
+      def push!(owner, annotation, location)
+        t = table
+        unless t.empty? || t.key?(owner)
+          left = take_all
+          raise LeftoverAnnotations.new(left, "#{owner.inspect} got a declaration while other declarations were pending")
+        end
+
+        declarations = (t[owner] ||= [])
+        type = annotation.class
+
+        if !type.repeatable? && declarations.any? { |p| p.annotation.instance_of?(type) }
+          t.delete(owner)
+
+          raise DuplicateAnnotation, "#{owner.inspect}: #{annotation.class.short_name} declared twice " \
+                                     "for one method (it is not repeatable); pending declarations cleared"
+        end
+        declarations << PendingDeclaration.new(annotation, location)
+        nil
+      end
+
+      # @param owner [Module]
+      # @return [Array<PendingDeclaration>] the owner's declarations (removed)
+      def take(owner)
+        t = table
+        return NONE if t.empty?
+
+        t.delete(owner) || NONE
+      end
+
+      # @param owner [Module]
+      # @return [Array<PendingDeclaration>] the owner's declarations (not removed)
+      def peek(owner)
+        t = table
+        t[owner] || NONE
+      end
+
+      # @return [Hash{Module => Array<PendingDeclaration>}] every pending declaration (removed)
+      def take_all
+        t = table
+        return {} if t.empty?
+
+        left = t.dup
+        t.clear
+        left
+      end
+
+      # A constant was added to `owner`: its pending declarations can no longer attach.
+      # @param owner [Module]
+      # @param name [Symbol] the constant
+      # @return [nil]
+      # @raise [LeftoverAnnotations] when `owner` has pending declarations (they are cleared)
+      def const_added(owner, name)
+        return unless for?(owner)
+
+        raise LeftoverAnnotations.new({ owner => take(owner) }, "constant #{name} added to #{owner.inspect} " \
+                                                                "while declarations were pending")
+      end
+    end
+  end
+end

data/lib/adornment/core/private/query.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Lookups behind {Reflection}. The resolved method is found through Ruby's own lookup
+    # (`instance_method(name).owner`): one UnboundMethod, no ancestors. The queries that read
+    # overridden methods walk the ancestors, nearest first, through each module with its own entry
+    # for the name, and stop at an undef barrier. A visibility change (`private :inherited`) is an
+    # own entry like any other.
+    # @api private
+    module Query
+      # The shared empty result.
+      NONE = State::NONE
+
+      extend self
+
+      # Yields `(holder, side, annotations)` for each module the walk visits. The first yield is
+      # the resolved method.
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param singleton [Boolean]
+      # @yieldparam holder [Module] the class or module that holds the entry
+      # @yieldparam side [:instance, :singleton]
+      # @yieldparam annotations [Array<Adornment::Annotation>] frozen, possibly empty
+      # @return [nil]
+      def each_entry(owner, name, singleton)
+        start = singleton ? owner.singleton_class : owner
+        return unless start.method_defined?(name) || start.private_method_defined?(name)
+
+        ancestors = start.ancestors
+        i = next_own(ancestors, 0, name)
+        while i
+          holder, side = holder_of(ancestors[i])
+          yield holder, side, State.of(holder)&.entry(side, name) || NONE
+          later = next_own(ancestors, i + 1, name)
+          break if later.nil? || undef_between?(ancestors, i, later, name)
+
+          i = later
+        end
+        nil
+      end
+
+      # The resolved method's annotations: those of the module Ruby's lookup names
+      # (`instance_method(name).owner`).
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param singleton [Boolean]
+      # @return [Array<Adornment::Annotation>] frozen; empty when nothing is attached or the method
+      #   is not defined
+      def resolved_entry(owner, name, singleton)
+        start = singleton ? owner.singleton_class : owner
+        return NONE unless start.method_defined?(name) || start.private_method_defined?(name)
+
+        mod = start.instance_method(name).owner
+        entry = if mod.singleton_class?
+                  State.of(mod.attached_object)&.entry(:singleton,
+                                                       name)
+                else
+                  State.of(mod)&.entry(:instance, name)
+                end
+        entry || NONE
+      end
+
+      # Whether `mod` has its own entry for `name` (modules prepended to it do not count).
+      # @param mod [Module]
+      # @param name [Symbol]
+      # @return [Boolean]
+      def own?(mod, name)
+        mod.method_defined?(name, false) || mod.private_method_defined?(name, false)
+      end
+
+      # @param ancestors [Array<Module>]
+      # @param from [Integer]
+      # @param name [Symbol]
+      # @return [Integer, nil] the index of the first module at or after `from` with its own entry
+      def next_own(ancestors, from, name)
+        i = from
+        while i < ancestors.size
+          return i if own?(ancestors[i], name)
+
+          i += 1
+        end
+        nil
+      end
+
+      # Whether a module strictly between the two indexes undefines `name` (an undef entry is not
+      # an own entry, so it is never found by {next_own}).
+      # @param ancestors [Array<Module>]
+      # @param from [Integer]
+      # @param to [Integer]
+      # @param name [Symbol]
+      # @return [Boolean]
+      def undef_between?(ancestors, from, to, name)
+        i = from + 1
+        while i < to
+          return true if ancestors[i].undefined_instance_methods.include?(name)
+
+          i += 1
+        end
+        false
+      end
+
+      # @param mod [Module] an ancestor, possibly a singleton class
+      # @return [Array(Module, Symbol)] the class or module holding `mod`'s entries, and the side
+      def holder_of(mod)
+        mod.singleton_class? ? [mod.attached_object, :singleton] : [mod, :instance]
+      end
+
+      # The resolved method's annotations, filtered by `type`.
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param type [Class, nil]
+      # @param singleton [Boolean]
+      # @return [Array<Adornment::Annotation>] frozen
+      def annotations_for(owner, name, type, singleton)
+        annotations = resolved_entry(owner, name, singleton)
+        return annotations if type.nil? || annotations.all?(type)
+
+        annotations.select { |a| a.is_a?(type) }.freeze
+      end
+
+      # Names with an entry in some ancestor (activated ones), in ancestor order.
+      # @param owner [Module]
+      # @param singleton [Boolean]
+      # @return [Array<Symbol>]
+      def candidate_names(owner, singleton)
+        names = []
+        (singleton ? owner.singleton_class : owner).ancestors.each do |mod|
+          entries = mod.singleton_class? ? State.of(mod.attached_object)&.entries(:singleton) : State.of(mod)&.entries(:instance)
+          names.concat(entries.keys) if entries
+        end
+        names.uniq
+      end
+    end
+  end
+end

data/lib/adornment/core/private/site.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # The method annotations are about to attach to, passed to {Annotation#validate}. One site per
+    # definition, shared by every annotation in `annotations`, the complete proposed set (frozen).
+    class Site
+      # @return [Module] the class or module defining the method
+      attr_reader :owner
+      # @return [Symbol]
+      attr_reader :name
+      # @return [Array<Adornment::Annotation>] the complete proposed set (frozen)
+      attr_reader :annotations
+
+      # @api private
+      # @param owner [Module]
+      # @param name [Symbol]
+      # @param side [:instance, :singleton]
+      # @param annotations [Array<Adornment::Annotation>] the complete proposed set (frozen)
+      def initialize(owner, name, side, annotations)
+        @owner = owner
+        @name = name
+        @side = side
+        @annotations = annotations
+      end
+
+      # @note Takes no arguments, unlike `Object#method`, which it replaces on sites.
+      # @return [UnboundMethod] the method as defined now
+      def method = (singleton? ? @owner.singleton_class : @owner).instance_method(@name)
+
+      # @return [Boolean] whether the method is an instance method of {#owner}
+      def instance? = @side == :instance
+
+      # @return [Boolean] whether the method is a singleton method of {#owner}
+      def singleton? = @side == :singleton
+
+      # @return [String] `Owner#name` or `Owner.name`
+      def label = "#{@owner.inspect}#{singleton? ? '.' : '#'}#{@name}"
+
+      # @return [String] `#<Adornment::Core::Site Owner#name>`
+      def inspect = "#<Adornment::Core::Site #{label}>"
+      alias to_s inspect
+    end
+  end
+end