adornment-core 0.1.0

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Per-owner state, held in a hidden instance variable of the owner (so it lives and dies with
+    # the owner; nothing global refers to it strongly).
+    #
+    # Entries (attached annotations) are one Hash per side, written under the lock and read
+    # without it. Readers of a single entry get a frozen Array: CRuby runs `Hash#[]` and
+    # `Hash#[]=` with Symbol keys atomically under the GVL, so a reader sees the old or the new
+    # value. A whole-side read freezes the Hash in place and returns it as the snapshot; the next
+    # write copies it into a new mutable Hash first. So writing N names in a row costs O(N) (not
+    # O(N^2) as with a copy per write), and at rest only one Hash per side exists.
+    #
+    # The lock guards the entry writes; no user code runs under it. Pending declarations are not
+    # kept here (see {Pending}).
+    # @api private
+    class State
+      # The owner's instance variable that holds its state.
+      IVAR = :@__adornment_state__
+      # Guards the creation of states (one per owner).
+      CREATE_LOCK = Mutex.new
+      # The shared empty entry.
+      NONE = [].freeze
+
+      # @param owner [Module]
+      # @return [State, nil] the owner's state; nil when it has none yet
+      def self.of(owner) = owner.instance_variable_get(IVAR)
+
+      # @param owner [Module]
+      # @return [State] the owner's state, created on first use. Creating it registers the owner:
+      #   activation registers too, but a subclass of an activated class inherits the hooks without
+      #   being activated, and is registered when it first declares.
+      def self.for(owner)
+        owner.instance_variable_get(IVAR) || CREATE_LOCK.synchronize do
+          owner.instance_variable_get(IVAR) || begin
+            state = new
+            owner.instance_variable_set(IVAR, state)
+            Registry.register(owner)
+            state
+          end
+        end
+      end
+
+      # @return [Mutex] guards entry writes and the creation of {#annotation_methods}
+      attr_reader :lock
+
+      # @return [AnnotationMethods, nil] the owner's declaration methods module, once created
+      attr_accessor :annotation_methods
+
+      def initialize
+        @lock = Mutex.new
+        @instance = {}
+        @singleton = {}
+        @annotation_methods = nil
+      end
+
+      # @param side [:instance, :singleton]
+      # @param name [Symbol]
+      # @return [Array<Annotation>, nil] frozen; nil when the method never took declarations
+      def entry(side, name)
+        (side == :singleton ? @singleton : @instance)[name]
+      end
+
+      # @param side [:instance, :singleton]
+      # @return [Hash{Symbol => Array<Annotation>}] frozen snapshot of a side
+      def entries(side)
+        live = side == :singleton ? @singleton : @instance
+        return live if live.frozen?
+
+        @lock.synchronize { (side == :singleton ? @singleton : @instance).freeze }
+      end
+
+      # Replaces the entry for `name`.
+      # @param side [:instance, :singleton]
+      # @param name [Symbol]
+      # @param value [Array<Annotation>] frozen
+      # @return [nil]
+      def set_entry(side, name, value)
+        @lock.synchronize { writable(side)[name] = value }
+        nil
+      end
+
+      # The side's mutable Hash (a frozen snapshot is copied first). Called under the lock.
+      # @param side [:instance, :singleton]
+      # @return [Hash{Symbol => Array<Annotation>}]
+      def writable(side)
+        live = side == :singleton ? @singleton : @instance
+        return live unless live.frozen?
+
+        live = live.dup
+        side == :singleton ? @singleton = live : @instance = live
+      end
+    end
+
+    # Weak registry of activated owners, for global discovery and verification.
+    # `ObjectSpace::WeakMap` is used because `ObjectSpace::WeakKeyMap` cannot enumerate its keys.
+    # @api private
+    module Registry
+      @map = ObjectSpace::WeakMap.new
+      @lock = Mutex.new
+
+      class << self
+        # @param owner [Module]
+        # @return [void]
+        def register(owner) = @lock.synchronize { @map[owner] = true }
+
+        # @param owner [Module]
+        # @return [void]
+        def unregister(owner) = @lock.synchronize { @map.delete(owner) }
+
+        # @return [Array<Module>] the reachable registered owners (a copy)
+        def owners = @lock.synchronize { @map.keys }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # Checks on annotation types, shared by the facade, the owner API and reflection.
+    # @api private
+    module Utils
+      # @api private
+      # @param type [Class] an annotation type
+      # @return [Symbol] the declaration method name of a type without an alias: the last segment of
+      #   its constant name
+      # @raise [ArgumentError] for a non-annotation type, or an anonymous one
+      def self.declaration_name(type)
+        check_type!(type)
+        name = type.name or raise ArgumentError, "anonymous annotation type #{type.inspect} needs an alias (Name: type)"
+        name.split("::").last.to_sym
+      end
+
+      # Raises unless `type` is a method annotation type: a class that included
+      # `Adornment::Annotation[...]` (the policy module is the only way in).
+      # @api private
+      # @param type [Object]
+      # @return [void]
+      # @raise [ArgumentError]
+      def self.check_type!(type)
+        return if type.is_a?(Class) && type < Annotation
+
+        raise ArgumentError, "#{type.inspect} is not an annotation type; include Adornment::Annotation[...]"
+      end
+
+      # @api private
+      # @param args [Array] positional arguments
+      # @param options [Hash] keyword arguments
+      # @return [String] call arguments as written: `Integer, default: 1`
+      def self.render_arguments(args, options)
+        [*args.map(&:inspect), *options.map { |key, value| "#{key}: #{value.inspect}" }].join(", ")
+      end
+    end
+  end
+end

data/lib/adornment/core/reflection.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # One declaration found along a method's ancestor chain (see {Reflection#declarations_for}).
+    #
+    # @!attribute [r] annotation
+    #   @return [Adornment::Annotation]
+    # @!attribute [r] owner
+    #   @return [Module] the class or module that declared it
+    # @!attribute [r] method_name
+    #   @return [Symbol]
+    # @!attribute [r] singleton
+    #   @return [Boolean] whether it annotates a singleton method of `owner`
+    # @!attribute [r] resolved
+    #   @return [Boolean] whether it is attached to the method Ruby's lookup reaches
+    Declaration = Data.define(:annotation, :owner, :method_name, :singleton, :resolved)
+
+    # Owner API for reading annotations. Activated owners have it through {Target}; classes and
+    # modules that include, prepend or extend an activated module receive it automatically.
+    #
+    # Queries read annotations from the *resolved method*: the method Ruby would call for
+    # the given name. An override does not inherit annotations from the method it replaces.
+    # {#find_annotation} and {#declarations_for} also search overridden methods along the
+    # ancestor chain. Query results are frozen.
+    module Reflection
+      # Annotations of the resolved method.
+      #
+      # @param name [Symbol, String]
+      # @param type [Class, nil] only annotations that are `is_a?(type)`
+      # @param singleton [Boolean] query the singleton method
+      # @return [Array<Adornment::Annotation>] frozen, in declaration order
+      def annotations_for(name, type = nil, singleton: false)
+        Core::Query.annotations_for(self, name.to_sym, type, singleton)
+      end
+
+      # Every declaration for `name` along the ancestor chain, nearest owner first.
+      #
+      # @param name [Symbol, String]
+      # @param singleton [Boolean] walk the singleton method
+      # @return [Array<Adornment::Core::Declaration>] frozen; the resolved method's come first, with
+      #   `resolved: true`
+      def declarations_for(name, singleton: false)
+        name = name.to_sym
+        result = []
+        resolved = true
+        Core::Query.each_entry(self, name, singleton) do |holder, side, annotations|
+          annotations.each do |annotation|
+            result << Declaration.new(annotation: annotation, owner: holder, method_name: name,
+                                      singleton: side == :singleton, resolved: resolved)
+          end
+          resolved = false
+        end
+        result.freeze
+      end
+
+      # The annotation of `type` on the resolved method, or nil.
+      #
+      # @param name [Symbol, String]
+      # @param type [Class] a non-repeatable annotation type; matches with `is_a?(type)`
+      # @param singleton [Boolean] query the singleton method
+      # @return [Adornment::Annotation, nil]
+      # @raise [ArgumentError] for repeatable types (use {#annotations_for}) or non-annotation types
+      def annotation(name, type, singleton: false)
+        Core::Utils.check_type!(type)
+        raise ArgumentError, "#{type} is repeatable; use annotations_for(name, #{type})" if type.repeatable?
+
+        Core::Query.resolved_entry(self, name.to_sym, singleton).find { |a| a.is_a?(type) }
+      end
+
+      # The annotation of `type` on the resolved method or, failing that, on the nearest method it
+      # overrides along the ancestor chain; nil when none has one.
+      #
+      # @param name [Symbol, String]
+      # @param type [Class] a non-repeatable annotation type; matches with `is_a?(type)`
+      # @param singleton [Boolean] query the singleton method
+      # @return [Adornment::Annotation, nil]
+      # @raise [ArgumentError] for repeatable types (use {#declarations_for}) or non-annotation
+      #   types
+      def find_annotation(name, type, singleton: false)
+        Core::Utils.check_type!(type)
+        raise ArgumentError, "#{type} is repeatable; use declarations_for(name)" if type.repeatable?
+
+        Core::Query.each_entry(self, name.to_sym, singleton) do |_holder, _side, annotations|
+          annotations.each { |a| return a if a.is_a?(type) }
+        end
+        nil
+      end
+
+      # Every method whose resolved method is annotated with `type` (see {#annotations_for}),
+      # including methods inherited from ancestors.
+      #
+      # @param type [Class] an annotation type; matches with `is_a?(type)`
+      # @param singleton [Boolean] look at singleton methods
+      # @return [Hash{Symbol => Adornment::Annotation}] frozen, for non-repeatable types
+      # @return [Hash{Symbol => Array<Adornment::Annotation>}] frozen, for repeatable types
+      # @raise [ArgumentError] when `type` is not an annotation type
+      def annotated_with(type, singleton: false)
+        Core::Utils.check_type!(type)
+        result = {}
+        Core::Query.candidate_names(self, singleton).each do |name|
+          found = Core::Query.annotations_for(self, name, type, singleton)
+          next if found.empty?
+
+          result[name] = type.repeatable? ? found : found.first
+        end
+        result.freeze
+      end
+
+      # Only the annotations this class or module itself attached to `name`, while it still
+      # defines the method.
+      #
+      # @param name [Symbol, String]
+      # @param type [Class, nil] only annotations that are `is_a?(type)`
+      # @param singleton [Boolean] query the singleton method
+      # @return [Array<Adornment::Annotation>] frozen
+      def own_annotations_for(name, type = nil, singleton: false)
+        name = name.to_sym
+        entry = Core::State.of(self)&.entry(singleton ? :singleton : :instance, name)
+        return Core::State::NONE unless entry && Core::Query.own?(singleton ? singleton_class : self, name)
+
+        type ? entry.select { |a| a.is_a?(type) }.freeze : entry
+      end
+
+      # The methods this class or module itself annotated and still defines, in the order they were
+      # first annotated (re-annotating a method keeps its place).
+      #
+      # @param singleton [Boolean] list singleton methods
+      # @return [Array<Symbol>] frozen
+      def own_annotated_methods(singleton: false)
+        side = singleton ? :singleton : :instance
+        entries = Core::State.of(self)&.entries(side) or return Core::State::NONE
+        mod = singleton ? singleton_class : self
+        entries.filter_map { |name, annotations| name if !annotations.empty? && Core::Query.own?(mod, name) }.freeze
+      end
+
+      # Annotations declared on this owner (in the current fiber) that are still waiting for a
+      # definition.
+      #
+      # @return [Array<Adornment::Annotation>] frozen, in declaration order
+      def pending_adornments
+        Core::Pending.peek(self).map(&:annotation).freeze
+      end
+    end
+  end
+end

data/lib/adornment/core/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Adornment
+  module Core
+    # The gem version.
+    VERSION = "0.1.0"
+  end
+end

data/lib/adornment/core.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# adornment-core: the declarative metadata engine behind Adornment.
+#
+#   require "adornment/core"
+#
+#   class Traced
+#     include Adornment::Annotation[]
+#
+#     attr_reader :span
+#
+#     def initialize(span: nil)
+#       @span = span
+#     end
+#   end
+#
+#   class Orders
+#     include Adornment[Traced]
+#
+#     Traced(span: "orders.fetch")
+#     def fetch(id) = id
+#   end
+#
+#   Orders.annotations_for(:fetch) # => [#<Traced span="orders.fetch">]
+#
+# This file is the public facade: every top-level `Adornment.*` method is declared here and
+# delegates to an internal component under `Adornment::Core`. The supported surface is this
+# facade, the owner API ({Adornment::Core::Target}, {Adornment::Core::Reflection}), the records
+# and errors listed in the README. Everything else under `Adornment::Core` is internal.
+
+require_relative "core/version"
+require_relative "core/errors"
+
+unless RUBY_ENGINE == "ruby"
+  raise Adornment::UnsupportedPlatformError,
+        "adornment-core requires CRuby (MRI); #{RUBY_ENGINE} #{RUBY_ENGINE_VERSION} is not supported"
+end
+
+require_relative "core/immutable"
+require_relative "core/private/state"
+require_relative "core/private/site"
+require_relative "core/private/utils"
+require_relative "core/private/pending"
+require_relative "core/private/attachment"
+require_relative "core/private/query"
+require_relative "core/private/annotation_methods"
+require_relative "core/reflection"
+require_relative "core/annotation"
+require_relative "core/hooks"
+require_relative "core/base"
+
+# Annotations for Ruby methods: types, declarations above `def`, reflection and verification.
+# `Adornment[...]`, {Adornment::Annotation} and the errors live here; the owner API and records
+# live under {Adornment::Core}.
+module Adornment
+  class << self
+    # @!group Activation
+
+    # The recommended activation: `include Adornment[Traced, Cached]`, `include Adornment[Trace:
+    # Traced]` (an alias names the declaration method), or `include Adornment[]` (no declaration
+    # methods; declare with `adorn`).
+    #
+    # @param types [Array<Class>] annotation types; each declaration method is named after its
+    #   type (`Traced(...)`)
+    # @param aliases [Hash{Symbol => Class}] declaration method name => annotation type
+    # @return [Adornment::Core::Base] a module whose inclusion activates the includer
+    # @raise [ArgumentError] for a class that is not an annotation type
+    def [](*types, **aliases)
+      Core::Base.new(types, aliases)
+    end
+
+    # @param owner [Object]
+    # @return [Boolean] whether `owner` is an activated class or module (it or an ancestor used
+    #   `include Adornment[...]` or `extend Adornment::Core::Target`)
+    def activated?(owner)
+      Core::Attachment.activated?(owner)
+    end
+
+    # @!group Discovery
+
+    # Every registered class or module with its own methods annotated with `type`: the defining
+    # owners, not subclasses or includers that inherit those methods (ask those with
+    # `Owner.annotated_with`).
+    #
+    # @param type [Class] an annotation type; annotations match with `is_a?(type)`
+    # @param singleton [Boolean] look at singleton methods
+    # @return [Hash{Module => Hash{Symbol => Annotation}}] frozen; for repeatable types each value
+    #   is a frozen Array of annotations
+    # @raise [ArgumentError] when `type` is not an annotation type
+    def annotated_with(type, singleton: false)
+      Core::Utils.check_type!(type)
+      side = singleton ? :singleton : :instance
+      result = {}
+      Core::Registry.owners.each do |owner|
+        methods = {}
+        mod = singleton ? owner.singleton_class : owner
+        Core::State.of(owner)&.entries(side)&.each do |name, annotations|
+          found = annotations.select { |a| a.is_a?(type) }
+          next if found.empty? || !Core::Query.own?(mod, name) # removed since
+
+          methods[name] = type.repeatable? ? found.freeze : found.first
+        end
+        result[owner] = methods.freeze if methods.any?
+      end
+      result.freeze
+    end
+
+    # @return [Array<Module>] the registered (activated), still reachable owners. The registry
+    #   holds owners weakly.
+    def registered_owners
+      Core::Registry.owners
+    end
+
+    # @!group Verification and diagnostics
+
+    # Raises one aggregated error for every declaration still pending in the current fiber (and
+    # clears them), and runs the lint over the registered, reachable owners.
+    #
+    # @param lint [:warn, :error, false] how to run the bare-constant lint: print its diagnostics,
+    #   raise them, or skip it
+    # @return [nil]
+    # @raise [Adornment::LeftoverAnnotations] for declarations that never attached
+    # @raise [Adornment::LintError] with `lint: :error`, when the lint finds something
+    # @raise [ArgumentError] for any other `lint:` value
+    def verify_all!(lint: :warn)
+      unless [:warn, :error, false].include?(lint)
+        raise ArgumentError, "lint: must be :warn, :error or false, got #{lint.inspect}"
+      end
+
+      owners = Core::Registry.owners
+      leftovers = Core::Pending.take_all
+      diagnostics = lint ? Core::Lint.run(owners) : []
+      diagnostics.each { |d| warn("adornment: #{d}") } if lint == :warn
+      raise LeftoverAnnotations, leftovers unless leftovers.empty?
+      raise LintError, diagnostics if lint == :error && !diagnostics.empty?
+
+      nil
+    end
+
+    # Runs the heuristic bare-constant lint.
+    #
+    # @param targets [Array<Module, String>] registered owners or file paths
+    # @return [Array<Adornment::Core::Lint::Diagnostic>]
+    # @raise [LoadError] when Prism cannot be loaded
+    def lint(*targets)
+      Core::Lint.run(targets.flatten)
+    end
+
+    # Removes an owner from global discovery and verification (idempotent) and drops its pending
+    # declarations. Its hooks stay installed and its metadata stays readable through
+    # its own reflection API; activating it again registers it again.
+    #
+    # @param owner [Module]
+    # @return [nil]
+    def unregister(owner)
+      Core::Registry.unregister(owner)
+      Core::Pending.take(owner)
+      nil
+    end
+
+    # @!group Utilities for extension gems
+
+    # The freezing rule of annotation values: Array, Hash, Set and String values are copied and
+    # deep-frozen (the argument is never mutated); other objects are returned as they are.
+    #
+    # @param value [Object]
+    # @return [Object] a deep-frozen copy, or `value` itself when it is already deeply immutable or
+    #   not a container or String
+    def immutable_copy(value)
+      Core::Immutable.copy(value)
+    end
+
+    # @!endgroup
+
+    private
+
+    def append_features(_base)
+      raise ArgumentError, "include Adornment[...] (with the annotation types), not bare Adornment: " \
+                           "a bare include would leak Adornment's constants into your constant lookup"
+    end
+
+    def prepend_features(_base)
+      raise ArgumentError, "use include Adornment[...], not prepend Adornment"
+    end
+
+    def extend_object(_base)
+      raise ArgumentError, "use include Adornment[...] or extend Adornment::Core::Target, not extend Adornment"
+    end
+  end
+
+  # The annotation engine. The owner API ({Base}, {Target}, {Reflection}), the records
+  # ({Declaration}, {Pending::PendingDeclaration}, {Site}, {Lint::Diagnostic}), {Lint} and
+  # {VERSION} are public; everything marked `@api private` is internal and may change in any
+  # release.
+  module Core
+    # Loaded on first use: the lint (which parses source with Prism) is not needed to declare or
+    # reflect on annotations.
+    autoload :Lint, File.expand_path("core/diagnostics/lint", __dir__)
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: adornment-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Zahoruiko
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Adornment Core provides declarative method annotations for Ruby.
+  Define annotation types, attach immutable metadata to the next method
+  definition, and inspect annotations along Ruby's method lookup chain.
+  Detects annotation declarations left without a method.
+
+  Pure Ruby with no runtime dependencies. Does not wrap or replace methods.
+  Supports CRuby 3.3 and later.
+email:
+- zahoruiko.yaroslav@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/adornment/core.rb
+- lib/adornment/core/annotation.rb
+- lib/adornment/core/base.rb
+- lib/adornment/core/diagnostics/lint.rb
+- lib/adornment/core/errors.rb
+- lib/adornment/core/hooks.rb
+- lib/adornment/core/immutable.rb
+- lib/adornment/core/private/annotation_methods.rb
+- lib/adornment/core/private/attachment.rb
+- lib/adornment/core/private/pending.rb
+- lib/adornment/core/private/query.rb
+- lib/adornment/core/private/site.rb
+- lib/adornment/core/private/state.rb
+- lib/adornment/core/private/utils.rb
+- lib/adornment/core/reflection.rb
+- lib/adornment/core/version.rb
+homepage: https://github.com/YaroslavZahoruiko/adornment-core
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/YaroslavZahoruiko/adornment-core
+  changelog_uri: https://github.com/YaroslavZahoruiko/adornment-core/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/YaroslavZahoruiko/adornment-core/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Declarative method annotations and metadata for Ruby.
+test_files: []