adornment-core 0.1.0

data/lib/adornment/core/annotation.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Adornment
+  # Method annotation types are ordinary named classes configured by including
+  # `Adornment::Annotation[...]`. Their fields are instance variables set by an ordinary
+  # `initialize`, so Ruby itself decides what is positional, what is a keyword and what is
+  # required:
+  #
+  #   class Route
+  #     include Adornment::Annotation[repeatable: true]
+  #
+  #     attr_reader :path, :verbs
+  #
+  #     def initialize(path, verbs: [:GET])
+  #       @path = path
+  #       @verbs = verbs.map(&:to_sym)
+  #     end
+  #   end
+  #
+  # After `initialize` returns, `new` copies and deep-freezes every instance variable
+  # ({Adornment.immutable_copy}) and freezes the instance, so an initializer neither freezes nor
+  # copies anything itself. Every instance variable is a field: it takes part in `==`, `hash`,
+  # `to_h`, inspection and pattern matching.
+  #
+  # This module is the instance marker of method annotations. Including it bare is an error:
+  # `Adornment::Annotation[...]` (or `[]` for the defaults) returns the policy module that
+  # includes it. Policies: `repeatable:` (false) and `targets:` (`[:instance, :singleton]`).
+  module Annotation
+    class << self
+      # @param args [Array] must be empty: policies are keywords
+      # @param policies [Hash] `repeatable:`, `targets:`; only the given ones are stored (the
+      #   others are inherited, or defaults)
+      # @return [Adornment::Core::PolicyModule] the policy module to include
+      # @raise [ArgumentError] for positional arguments, unknown policies or invalid values
+      def [](*args, **policies)
+        unless args.empty?
+          raise ArgumentError, "Adornment::Annotation[...] takes policies as keywords " \
+                               "(#{Core::Policies::KEYS.map { |k| "#{k}:" }.join(', ')}), got #{args.map(&:inspect).join(', ')}"
+        end
+
+        Core::PolicyModule.new(policies)
+      end
+
+      private
+
+      def append_features(base)
+        return super if base.is_a?(Core::PolicyModule)
+
+        raise ArgumentError, "use include Adornment::Annotation[...] (policies, or [] for the defaults), " \
+                             "not bare Adornment::Annotation"
+      end
+
+      def prepend_features(_base)
+        raise ArgumentError, "use include Adornment::Annotation[...], not prepend"
+      end
+
+      def extend_object(_base)
+        raise ArgumentError, "use include Adornment::Annotation[...], not extend"
+      end
+    end
+
+    # Attachment-time check, called with the {Core::Site} the annotation is about to attach to
+    # (once per annotation; every annotation of one definition gets the same site, with the
+    # complete proposed set). Read and raise; never mutate. A `StandardError` raised here is
+    # re-raised as {Adornment::DefinitionError} (its `cause`) and nothing is attached. Called
+    # again for every attachment, so it must tolerate repeats. The default does nothing.
+    #
+    # @param site [Adornment::Core::Site]
+    # @return [void]
+    def validate(site); end
+
+    # @yieldparam field [Symbol]
+    # @yieldparam value [Object]
+    # @yieldreturn [Array(Object, Object)] a key-value pair, as for `Hash#to_h` with a block
+    # @return [Hash{Symbol => Object}] the fields (instance variables without `@`), in the order
+    #   the initializer set them; with a block, the pairs it returns
+    def to_h(&block)
+      out = {}
+      instance_variables.each { |ivar| out[ivar.name.delete_prefix("@").to_sym] = instance_variable_get(ivar) }
+      block ? out.to_h(&block) : out
+    end
+
+    # Pattern matching on the fields: `in { path: String => path }`.
+    # @param _keys [Array<Symbol>, nil] ignored: every field is returned
+    # @return [Hash{Symbol => Object}]
+    def deconstruct_keys(_keys) = to_h
+
+    # Same class and equal fields (`==` on each instance variable).
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      return true if equal?(other)
+      return false unless other.class == self.class
+
+      ivars = instance_variables
+      return false unless ivars.size == other.instance_variables.size
+
+      ivars.each do |ivar|
+        unless other.instance_variable_defined?(ivar) && instance_variable_get(ivar) == other.instance_variable_get(ivar)
+          return false
+        end
+      end
+      true
+    end
+
+    # Same class and `eql?` fields: the Hash-key equality that matches {#hash}.
+    # @param other [Object]
+    # @return [Boolean]
+    def eql?(other)
+      return true if equal?(other)
+      return false unless other.class == self.class
+
+      ivars = instance_variables
+      return false unless ivars.size == other.instance_variables.size
+
+      ivars.each do |ivar|
+        unless other.instance_variable_defined?(ivar) && instance_variable_get(ivar).eql?(other.instance_variable_get(ivar))
+          return false
+        end
+      end
+      true
+    end
+
+    # @return [Integer] from the class and the fields, independent of field order
+    def hash = [self.class, to_h].hash
+
+    # @return [String] `#<TypeName field=value, ...>`
+    def inspect
+      name = self.class.name || "Adornment::Annotation"
+      pairs = instance_variables.map do |ivar|
+        "#{ivar.name.delete_prefix('@')}=#{instance_variable_get(ivar).inspect}"
+      end
+      pairs.empty? ? "#<#{name}>" : "#<#{name} #{pairs.join(', ')}>"
+    end
+    alias to_s inspect
+  end
+
+  module Core
+    # The module `Adornment::Annotation[...]` returns: the explicitly given policies, plus the
+    # method annotation marker. Including it in a class makes that class a method annotation type.
+    # @api private
+    class PolicyModule < Module
+      # @return [Hash] the explicitly given policies (frozen)
+      attr_reader :overrides
+
+      # @param policies [Hash] validated by {Policies.validate}
+      # @raise [ArgumentError] for unknown policies or invalid values
+      def initialize(policies)
+        super()
+        @overrides = Policies.validate(policies)
+        include(Annotation) # passes Annotation's guard: this is a PolicyModule
+
+        freeze
+      end
+
+      # @return [String] e.g. `Adornment::Annotation[repeatable: true]`
+      def inspect = "Adornment::Annotation[#{@overrides.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}]"
+      alias to_s inspect
+
+      private
+
+      # Checks the host, includes the module, then installs the type behavior on the host.
+      def append_features(host)
+        Policies.check_host!(self, host)
+        super
+        Policies.install(host)
+        host
+      end
+
+      def prepend_features(_host)
+        raise ArgumentError, "use include #{inspect}, not prepend"
+      end
+
+      def extend_object(_host)
+        raise ArgumentError, "use include #{inspect}, not extend"
+      end
+    end
+
+    # Merges and validates method annotation policies. Each policy module stores only its
+    # overrides; a type's policy merges the policy modules of its ancestors, least specific first,
+    # then applies the defaults. The merged policy is cached on the type and dropped (for the type
+    # and its subclasses) whenever a policy module is included.
+    # @api private
+    module Policies
+      # The policy names `Annotation[...]` accepts.
+      KEYS = %i[repeatable targets].freeze
+      # The method kinds a type may target.
+      SIDES = %i[instance singleton].freeze
+      # The policy of a type that sets nothing.
+      DEFAULTS = { repeatable: false, targets: SIDES }.freeze
+      # The instance variable caching a type's merged policy.
+      IVAR = :@__adornment_policy__
+
+      @lock = Mutex.new
+
+      class << self
+        # @param policies [Hash] `repeatable:` and/or `targets:`
+        # @return [Hash] the validated, frozen overrides
+        # @raise [ArgumentError] for unknown keys, a non-boolean `repeatable:`, or `targets:`
+        #   that is not a non-empty subset of {SIDES}
+        def validate(policies)
+          unknown = policies.keys - KEYS
+          unless unknown.empty?
+            raise ArgumentError, "unknown annotation polic(y/ies) #{unknown.map { |k| "#{k}:" }.join(', ')}; " \
+                                 "allowed: #{KEYS.map { |k| "#{k}:" }.join(', ')}"
+          end
+
+          out = {}
+          policies.each { |key, value| out[key] = key == :repeatable ? boolean(value) : sides(value) }
+          out.freeze
+        end
+
+        # @param type [Class] an annotation type
+        # @return [Hash] the type's merged policy (frozen), computed once and cached on the type
+        #   (a frozen type cannot hold the cache, so it is merged on every read)
+        def of(type)
+          cached = type.instance_variable_get(IVAR)
+          return cached if cached
+
+          policy = merged(type.ancestors.grep(PolicyModule))
+          type.frozen? ? policy : type.instance_variable_set(IVAR, policy)
+        end
+
+        # Checks an inclusion into `host` before Ruby includes it: a plain class.
+        # @param mod [PolicyModule] the module being included (for the message)
+        # @param host [Module]
+        # @return [void]
+        # @raise [ArgumentError] for a module, a `Data` or a `Struct` subclass
+        def check_host!(mod, host)
+          return if host.is_a?(Class) && !(host < Data) && !(host < Struct)
+
+          raise ArgumentError, "#{mod.inspect} can only be included in a plain class " \
+                               "(fields are instance variables set by initialize), not #{host.inspect}"
+        end
+
+        # Installs the class behavior after the inclusion and drops cached policies below `host`.
+        # @param host [Class] the new (or re-configured) annotation type
+        # @return [void]
+        def install(host)
+          @lock.synchronize { forget(host) }
+          host.extend(TypeMethods)
+        end
+
+        # Applies the freezing rule to an initialized instance: every instance variable is copied
+        # and deep-frozen, then the instance is frozen. An instance its initializer froze already
+        # is kept as it is.
+        # @param instance [Adornment::Annotation]
+        # @return [Adornment::Annotation] `instance`, frozen
+        def seal(instance)
+          return instance if instance.frozen?
+
+          instance.instance_variables.each do |ivar|
+            value = instance.instance_variable_get(ivar)
+            copied = Immutable.copy(value)
+            instance.instance_variable_set(ivar, copied) unless copied.equal?(value)
+          end
+          instance.freeze
+        end
+
+        private
+
+        # Drops the cached policy of `type` and of its subclasses (recursively).
+        def forget(type)
+          type.remove_instance_variable(IVAR) if type.instance_variable_defined?(IVAR) && !type.frozen?
+          type.subclasses.each { |sub| forget(sub) }
+        end
+
+        # Policy modules nearest first => the merged, defaulted policy.
+        def merged(modules)
+          out = {}
+          modules.reverse_each { |m| out.merge!(m.overrides) }
+          DEFAULTS.merge(out).freeze
+        end
+
+        # @return [Boolean] `value`, when it is true or false
+        def boolean(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, "repeatable: must be true or false, got #{value.inspect}"
+        end
+
+        # @return [Array<Symbol>] the frozen, de-duplicated sides `value` names
+        def sides(value)
+          list = Array(value).map { |t| t.respond_to?(:to_sym) ? t.to_sym : t }.uniq
+          if list.empty? || !(list - SIDES).empty?
+            raise ArgumentError, "targets: must be a non-empty subset of #{SIDES.inspect}, got #{value.inspect}"
+          end
+
+          list.freeze
+        end
+      end
+    end
+
+    # Class-level construction and readers of annotation types.
+    # @api private
+    module TypeMethods
+      # Ruby's own construction (the initializer's positional and keyword parameters), then the
+      # freezing rule ({Policies.seal}).
+      # @return [Adornment::Annotation] frozen
+      def new(...) = Policies.seal(super)
+
+      # @return [String] the last segment of the constant name (`Traced` for `Obs::Traced`)
+      def short_name = name ? name.split("::").last : inspect
+
+      # @return [Boolean] whether several annotations of this type may annotate one method
+      def repeatable? = adornment_policy[:repeatable]
+
+      # @return [Array<Symbol>] the method kinds (`:instance`, `:singleton`) the type may annotate
+      def targets = adornment_policy[:targets]
+
+      # @api private
+      # @return [Hash] the merged policy
+      def adornment_policy = @__adornment_policy__ || Policies.of(self)
+
+      # Not a constructor for method annotations: they are declared above the method.
+      # @param args [Array] shown in the error as the call form
+      # @param kwargs [Hash] shown in the error as the call form
+      # @return [void] never returns
+      # @raise [TargetError] always, naming the call form (`Get["/x"]` → `Get("/x")`)
+      def [](*args, **kwargs)
+        raise TargetError, "#{short_name} is a method annotation; write it as a call above the method: " \
+                           "`#{short_name}(#{Core::Utils.render_arguments(args, kwargs)})`"
+      end
+    end
+  end
+end

data/lib/adornment/core/base.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # The anonymous module returned by `Adornment[...]`. Including it activates the includer
+    # (`extend Target`) and defines its declaration methods (`use_annotations`).
+    class Base < Module
+      # @api private
+      # @param types [Array<Class>] annotation types
+      # @param aliases [Hash{Symbol => Class}] declaration method name => annotation type
+      # @raise [ArgumentError] for a class that is not an annotation type
+      def initialize(types, aliases)
+        super()
+        types.each { |t| Core::Utils.check_type!(t) }
+        aliases.each_value { |t| Core::Utils.check_type!(t) }
+        @types = types.dup.freeze
+        @aliases = aliases.transform_keys(&:to_sym).freeze
+      end
+
+      # @return [String] e.g. `Adornment[Traced, Cache: Cached]`
+      def inspect
+        parts = @types.map { |t| t.name || t.inspect } + @aliases.map { |k, t| "#{k}: #{t.name || t.inspect}" }
+        "Adornment[#{parts.join(', ')}]"
+      end
+      alias to_s inspect
+
+      private
+
+      # Activates the includer and defines its declaration methods.
+      def included(base)
+        super
+        base.extend(Target)
+        base.use_annotations(*@types, **@aliases)
+      end
+
+      def extend_object(_base)
+        raise ArgumentError, "extend #{inspect} is not supported; use include #{inspect}"
+      end
+
+      def prepend_features(_base)
+        raise ArgumentError, "prepend #{inspect} is not supported; use include #{inspect}"
+      end
+    end
+
+    # Owner API for declaring: `extend Adornment::Core::Target`, then `use_annotations`.
+    # `include Adornment[...]` does both in one line. Extending activates the owner.
+    module Target
+      # Activation: the owner is registered for discovery, gets the read-only {Reflection} API,
+      # the definition hooks (once per ancestry: a subclass of an activated class inherits them)
+      # and, for a module, {Core::Propagation} to pass reflection on to its includers. The owner's
+      # state is created on first use.
+      # @api private
+      # @param base [Module] the owner being activated
+      # @raise [ArgumentError] for a singleton class or anything that is not a class or module
+      def self.extended(base)
+        super
+        unless base.is_a?(Module) && !base.singleton_class?
+          raise ArgumentError, "Adornment can only activate classes and modules, not #{base.inspect}"
+        end
+
+        Core::Registry.register(base) # also after an unregister
+        singleton = base.singleton_class
+        base.extend(Reflection) unless singleton.include?(Reflection)
+        singleton.prepend(Core::Hooks) unless singleton.include?(Core::Hooks)
+        singleton.prepend(Core::Propagation) unless base.is_a?(Class) || singleton.include?(Core::Propagation)
+      end
+
+      # Defines one declaration method per type, named after the last segment of the type's
+      # constant name, or after the alias key: `use_annotations Traced, Cache: MyLib::Cached`.
+      #
+      # @param types [Array<Class>] method annotation types
+      # @param aliases [Hash{Symbol => Class}] declaration method name => type
+      # @return [nil]
+      # @raise [ArgumentError] for anonymous types without an alias, non-annotation types, or a
+      #   name that collides with a singleton method not defined by Adornment
+      def use_annotations(*types, **aliases)
+        named = types.to_h { |t| [Core::Utils.declaration_name(t), t] }.merge(aliases.transform_keys(&:to_sym))
+        named.each_value { |type| Core::Utils.check_type!(type) }
+        named.each_key do |name|
+          next unless respond_to?(name, true) # Check for collisions with other methods
+          next if method(name).owner.is_a?(AnnotationMethods) # Check if the method is defined by Adornment
+
+          raise ArgumentError, "#{inspect}.#{name} already exists and was not defined by Adornment; " \
+                               "rename the declaration method with an alias (#{name.to_s.downcase}_alias: Type)"
+        end
+        annotation_methods = Core::AnnotationMethods.for(self)
+        named.each { |name, type| annotation_methods.add(name, type) }
+        nil
+      end
+
+      # Declares annotation instances for the next method definition, without declaration methods:
+      # `adorn Route.new("/users")`, `adorn ADMIN_ONLY`, `adorn first, second`. Only instances:
+      # build them with `Type.new(...)`.
+      #
+      # @param annotations [Array<Adornment::Annotation>]
+      # @return [nil]
+      # @raise [ArgumentError] with no arguments, or for a type or any other non-instance
+      # @raise [Adornment::DuplicateAnnotation] for a second non-repeatable annotation of one type
+      # @raise [Adornment::LeftoverAnnotations] when another owner still has pending declarations
+      def adorn(*annotations)
+        raise ArgumentError, "adorn needs at least one annotation instance" if annotations.empty?
+
+        location = caller_locations(1, 1).first
+        annotations.each { |annotation| Core::Attachment.declare(self, annotation, location) }
+        nil
+      end
+
+      # Raises if this owner has declarations (in the current fiber) that never attached, and
+      # clears them.
+      #
+      # @return [nil]
+      # @raise [Adornment::LeftoverAnnotations]
+      def verify_adornments! = Core::Attachment.verify(self)
+    end
+  end
+end

data/lib/adornment/core/diagnostics/lint.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Heuristic lint for bare annotation constants (loaded on first use).
+    #
+    # A line holding only `Traced` inside a class body is a constant read: it declares nothing. The
+    # lint parses source files with Prism and flags statements directly in a `class` or `module`
+    # body that consist only of a constant read or constant path whose text matches a declaration
+    # method or type registered on that owner. It evaluates nothing and cannot know intent. A
+    # `# adornment:ignore` comment on the statement's line suppresses its diagnostic.
+    module Lint
+      # A comment on a statement's line that suppresses its diagnostic.
+      IGNORE = /#\s*adornment:ignore\b/
+
+      # The LoadError message when Prism is not available.
+      PRISM_MISSING = "the adornment lint reads source with Prism: Ruby 3.3+ ships it as a default gem; " \
+                      "on other Rubies add gem \"prism\" to your Gemfile"
+
+      # One possible mistake.
+      #
+      # @!attribute [r] path
+      #   @return [String]
+      # @!attribute [r] line
+      #   @return [Integer]
+      # @!attribute [r] owner
+      #   @return [String] the enclosing class or module as written in the source
+      # @!attribute [r] constant
+      #   @return [String] the flagged text
+      Diagnostic = Data.define(:path, :line, :owner, :constant) do
+        # @return [String]
+        def message
+          "`#{constant}` alone is a constant read and declares nothing; did you mean `#{constant}()`? " \
+            "(add `# adornment:ignore` if intended)"
+        end
+
+        # @return [String]
+        def to_s = "#{path}:#{line}: in #{owner}: #{message}"
+      end
+
+      class << self
+        # Lints the files that define `targets`: owners are mapped to their source files, Strings
+        # are file paths; every file is parsed once.
+        # @param targets [Array<Module, String>] registered owners or file paths
+        # @return [Array<Diagnostic>]
+        # @raise [LoadError] when Prism cannot be loaded
+        def run(targets)
+          load_prism
+          owners = Core::Registry.owners
+          by_name = owners.select(&:name).to_h { |o| [o.name, o] }
+          fallback = owners.flat_map { |o| names_for(o) }.uniq
+          files = targets.flat_map { |t| t.is_a?(Module) ? files_for(t) : [File.expand_path(t.to_s)] }.uniq
+          files.select { |f| File.file?(f) }.flat_map { |f| lint_file(f, by_name, fallback) }
+        end
+
+        # Requires Prism unless it is loaded already.
+        # @api private
+        # @return [void]
+        # @raise [LoadError] with {PRISM_MISSING}
+        def load_prism
+          return if defined?(::Prism.parse_file)
+
+          require "prism"
+        rescue LoadError
+          raise LoadError, PRISM_MISSING
+        end
+
+        # Files that define `owner`: its constant location and its methods' source locations.
+        # Sources that are not files (eval strings) are skipped.
+        # @api private
+        # @param owner [Module]
+        # @return [Array<String>] existing file paths
+        def files_for(owner)
+          paths = []
+          if owner.name
+            loc = begin
+              Object.const_source_location(owner.name)
+            rescue NameError
+              nil
+            end
+            paths << loc[0] if loc && !loc.empty?
+          end
+          [owner, owner.singleton_class].each do |mod|
+            (mod.instance_methods(false) + mod.private_instance_methods(false)).each do |name|
+              loc = mod.instance_method(name).source_location
+              paths << loc[0] if loc
+            end
+          end
+          paths.uniq.select { |p| File.file?(p) }
+        end
+
+        # Declaration method names (aliases included) and full type names of the method annotations
+        # usable on `owner`.
+        # @api private
+        # @param owner [Module]
+        # @return [Array<String>]
+        def names_for(owner)
+          Core::AnnotationMethods.types_of(owner).flat_map { |name, type| [name.to_s, type.name].compact }.uniq
+        end
+
+        # Parses one file and flags bare constants in class and module bodies.
+        # @api private
+        # @param path [String]
+        # @param by_name [Hash{String => Module}] registered owners by constant name
+        # @param fallback [Array<String>] names checked in bodies of unregistered owners
+        # @return [Array<Diagnostic>]
+        def lint_file(path, by_name, fallback)
+          result = Prism.parse_file(path)
+          ignored = result.comments.filter_map { |c| c.location.start_line if c.location.slice.match?(IGNORE) }
+          found = []
+          walk(result.value, [], by_name) do |statements, owner_name, owner|
+            names = owner ? names_for(owner) : fallback
+            statements.each do |node|
+              next unless %i[constant_read_node constant_path_node].include?(node.type)
+              next unless names.include?(node.slice)
+              next if ignored.include?(node.location.start_line)
+
+              found << Diagnostic.new(path: path, line: node.location.start_line, owner: owner_name, constant: node.slice)
+            end
+          end
+          found
+        end
+
+        # Yields each class or module body's statement list with its owner name and registered
+        # owner.
+        # @api private
+        # @param node [Prism::Node]
+        # @param nesting [Array<String>] the enclosing constant paths
+        # @param by_name [Hash{String => Module}]
+        # @yieldparam statements [Array<Prism::Node>]
+        # @yieldparam owner_name [String] the nesting as written, joined with `::`
+        # @yieldparam owner [Module, nil] the registered owner of that name
+        # @return [void]
+        def walk(node, nesting, by_name, &)
+          return unless node.is_a?(Prism::Node)
+
+          if %i[class_node module_node].include?(node.type)
+            inner = nesting + [node.constant_path.slice]
+            full = inner.join("::")
+            owner = by_name[full] || by_name[node.constant_path.slice]
+            yield(node.body.body, full, owner) if node.body&.type == :statements_node
+            node.body&.compact_child_nodes&.each { |child| walk(child, inner, by_name, &) }
+          else
+            node.compact_child_nodes.each { |child| walk(child, nesting, by_name, &) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/adornment/core/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Adornment
+  # Base class of every error Adornment raises (except {UnsupportedPlatformError}).
+  class Error < StandardError; end
+
+  # A non-repeatable annotation type was declared twice for one method.
+  class DuplicateAnnotation < Error; end
+
+  # An annotation was declared for a method kind (instance or singleton) its type does not target.
+  class InvalidTarget < Error; end
+
+  # A method annotation was written with brackets (`Get["/x"]`) instead of as a call above the
+  # method (`Get "/x"`).
+  class TargetError < Error; end
+
+  # An annotation's {Adornment::Annotation#validate} rejected the method it was about to attach
+  # to. The validator's own exception is the `cause`; the message names the method
+  # (`Owner#name` or `Owner.name`) and, when known, the declaration's location, which is also
+  # the first backtrace entry. Nothing was attached.
+  class DefinitionError < Error; end
+
+  # Declarations that never attached to a method.
+  class LeftoverAnnotations < Error
+    # @return [Hash{Module => Array<Core::Pending::PendingDeclaration>}] frozen; leftovers per owner
+    attr_reader :leftovers
+
+    # @param leftovers [Hash{Module => Array<Core::Pending::PendingDeclaration>}]
+    # @param reason [String, nil] why they can no longer attach, prepended to the message
+    def initialize(leftovers, reason = nil)
+      @leftovers = leftovers.transform_values { |list| list.dup.freeze }.freeze
+      super(build_message(reason))
+    end
+
+    private
+
+    # @return [String] the reason (if any), then each owner's leftovers with their locations
+    def build_message(reason)
+      lines = @leftovers.map do |owner, pending|
+        items = pending.map { |p| "  #{p.annotation.inspect}#{" (declared at #{p.location})" if p.location}" }
+        "#{owner.inspect}: #{pending.size} declaration(s) not attached to any method:\n#{items.join("\n")}"
+      end
+      lines.unshift("#{reason}:") if reason
+      lines.join("\n")
+    end
+  end
+
+  # The bare-constant lint found possible mistakes and ran with `lint: :error`.
+  class LintError < Error
+    # @return [Array<Adornment::Core::Lint::Diagnostic>]
+    attr_reader :diagnostics
+
+    # @param diagnostics [Array<Adornment::Core::Lint::Diagnostic>]
+    def initialize(diagnostics)
+      @diagnostics = diagnostics.dup.freeze
+      super(diagnostics.join("\n"))
+    end
+  end
+
+  # Raised by `require "adornment/core"` on Ruby engines other than CRuby.
+  class UnsupportedPlatformError < LoadError; end
+end