rigortype 0.0.9 → 0.1.1

data/lib/rigor/plugin/loader.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "load_error"
+
+module Rigor
+  module Plugin
+    # Resolves the project's `.rigor.yml` `plugins:` entries into
+    # instantiated plugin instances, paired with a service container.
+    # Internal slice-1 implementation; the public surface is
+    # {Loader.load} returning a {Registry}.
+    #
+    # Steps per entry (in order):
+    #
+    # 1. Normalise the entry into `{ gem:, id:, config: }`.
+    # 2. `require` the gem (failures surface as a {LoadError}).
+    # 3. Look up the registered plugin class by id (or by gem
+    #    name if the entry omitted an explicit id).
+    # 4. Validate the user's config against the manifest's
+    #    `config_schema`.
+    # 5. Instantiate the plugin and call `init(services)`.
+    #
+    # Loading is deterministic: configuration order, with plugin
+    # id alphabetical as the tie-breaker for entries that resolve
+    # to the same gem. Failures do not abort the run; the loader
+    # collects them on the {Registry} so the runner can convert
+    # each one into a `:plugin_loader` diagnostic.
+    class Loader # rubocop:disable Metrics/ClassLength
+      attr_reader :services, :requirer
+
+      # @param services [Rigor::Plugin::Services]
+      # @param requirer [#call] takes a gem name and returns truthy
+      #   on successful require. Defaulted to `Kernel.require` via
+      #   a lambda; the spec injects a fake to avoid touching the
+      #   real load path.
+      def initialize(services:, requirer: ->(name) { require name })
+        @services = services
+        @requirer = requirer
+      end
+
+      def self.load(configuration:, services:, requirer: ->(name) { require name })
+        new(services: services, requirer: requirer).load(configuration.plugins)
+      end
+
+      # @param entries [Array<String, Hash>] the raw `plugins:`
+      #   list from the configuration.
+      # @return [Registry]
+      def load(entries)
+        plugins = []
+        load_errors = []
+        seen_ids = {}
+
+        Array(entries).each_with_index do |raw, index|
+          entry = normalise_entry(raw, index)
+        rescue LoadError => e
+          load_errors << e
+        else
+          begin
+            plugin = resolve_and_instantiate(entry, seen_ids)
+            plugins << plugin if plugin
+          rescue LoadError => e
+            load_errors << e
+          end
+        end
+
+        # ADR-9 slice 5 — topological sort by `manifest(consumes:)`
+        # so producers run before consumers, plus early
+        # `missing-producer` validation. Cycles surface as
+        # `dependency-cycle` LoadErrors. When validation fails, the
+        # offending plugin(s) drop from the returned plugins list
+        # and the LoadError surfaces alongside any earlier failure.
+        plugins, sort_errors = topo_sort_plugins(plugins)
+        load_errors.concat(sort_errors)
+
+        Registry.new(plugins: plugins, load_errors: load_errors)
+      end
+
+      private
+
+      # Accepts:
+      #   "rigor-rails"
+      #   { "gem" => "rigor-rails", "id" => "rails", "config" => {...} }
+      #   { gem: "rigor-rails", id: "rails", config: {...} }
+      def normalise_entry(raw, index) # rubocop:disable Metrics/CyclomaticComplexity
+        case raw
+        when String
+          { gem: raw, id: nil, config: {} }
+        when Hash
+          string_keyed = raw.to_h { |k, v| [k.to_s, v] }
+          gem_name = string_keyed["gem"] || string_keyed["id"]
+          unless gem_name.is_a?(String) && !gem_name.empty?
+            raise LoadError.new(
+              "plugin entry ##{index} must declare a non-empty `gem:` (or `id:`), got #{raw.inspect}",
+              plugin_ref: raw
+            )
+          end
+
+          { gem: gem_name, id: string_keyed["id"], config: string_keyed["config"] || {} }
+        else
+          raise LoadError.new(
+            "plugin entry ##{index} must be a String or Hash, got #{raw.class}",
+            plugin_ref: raw
+          )
+        end
+      end
+
+      def resolve_and_instantiate(entry, seen_ids) # rubocop:disable Metrics/AbcSize
+        before = Plugin.registered.keys.to_set
+        require_gem!(entry)
+        after = Plugin.registered.keys.to_set
+        newly_registered = (after - before).to_a
+
+        plugin_class = lookup_plugin_class!(entry, newly_registered)
+        manifest = plugin_class.manifest
+
+        if seen_ids.key?(manifest.id)
+          raise LoadError.new(
+            "plugin id #{manifest.id.inspect} appeared twice in configuration " \
+            "(first via #{seen_ids[manifest.id].inspect}, again via #{entry[:gem].inspect})",
+            plugin_ref: manifest.id
+          )
+        end
+        seen_ids[manifest.id] = entry[:gem]
+
+        validate_config!(manifest, entry[:config])
+        instantiate(plugin_class, entry[:config])
+      end
+
+      def require_gem!(entry)
+        @requirer.call(entry[:gem])
+      rescue ::LoadError => e
+        raise LoadError.new(
+          "could not load plugin gem #{entry[:gem].inspect}: #{e.message}",
+          plugin_ref: entry[:gem],
+          cause: e
+        )
+      end
+
+      def lookup_plugin_class!(entry, newly_registered) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        if entry[:id]
+          plugin_class = Plugin.registered_for(entry[:id])
+          unless plugin_class
+            raise LoadError.new(
+              "plugin id #{entry[:id].inspect} (gem #{entry[:gem].inspect}) " \
+              "did not register itself with Rigor::Plugin.register",
+              plugin_ref: entry[:id]
+            )
+          end
+
+          return plugin_class
+        end
+
+        case newly_registered.size
+        when 0
+          raise LoadError.new(
+            "plugin gem #{entry[:gem].inspect} did not register any plugin via Rigor::Plugin.register",
+            plugin_ref: entry[:gem]
+          )
+        when 1
+          Plugin.registered_for(newly_registered.first)
+        else
+          raise LoadError.new(
+            "plugin gem #{entry[:gem].inspect} registered multiple plugins " \
+            "(#{newly_registered.sort.inspect}); disambiguate with an explicit `id:` field",
+            plugin_ref: entry[:gem]
+          )
+        end
+      end
+
+      def validate_config!(manifest, config)
+        errors = manifest.validate_config(config)
+        return if errors.empty?
+
+        raise LoadError.new(
+          "plugin #{manifest.id.inspect} config invalid: #{errors.join('; ')}",
+          plugin_ref: manifest.id
+        )
+      end
+
+      def instantiate(plugin_class, config)
+        plugin = plugin_class.new(services: @services, config: config)
+        plugin.init(@services)
+        plugin
+      rescue StandardError => e
+        manifest_id = safe_manifest_id(plugin_class)
+        raise LoadError.new(
+          "plugin #{manifest_id.inspect} raised during init: #{e.class}: #{e.message}",
+          plugin_ref: manifest_id,
+          cause: e
+        )
+      end
+
+      def safe_manifest_id(plugin_class)
+        plugin_class.manifest.id
+      rescue StandardError
+        plugin_class.to_s
+      end
+
+      # ADR-9 slice 5 — topological sort of plugins by their
+      # `manifest(consumes:)` declarations. Returns `[sorted_plugins,
+      # load_errors]`. Determinism: when no dependency relation
+      # forces an order, plugins are visited alphabetically by
+      # manifest id. A non-optional consume of a `(plugin_id, name)`
+      # whose producer is missing emits a `:missing-producer`
+      # LoadError and drops the consumer; cycles emit a
+      # `:dependency-cycle` LoadError naming the offending chain.
+      def topo_sort_plugins(plugins)
+        # If no plugin opts into the cross-plugin API the loader's
+        # legacy configuration-order contract is preserved
+        # unchanged. Topo sort and missing-producer validation only
+        # run when at least one plugin declares `consumes:`.
+        return [plugins, []] unless plugins.any? { |p| p.manifest.consumes.any? }
+
+        index = plugins.to_h { |plugin| [plugin.manifest.id, plugin] }
+        errors = validate_missing_producers(plugins, index)
+        sortable = plugins.reject { |p| errors.any? { |e| e.plugin_ref == p.manifest.id } }
+        config_order = plugins.each_with_index.to_h { |plugin, i| [plugin.manifest.id, i] }
+
+        sort_in_topo_order(sortable, index, errors, config_order)
+      end
+
+      def validate_missing_producers(plugins, index)
+        errors = []
+        plugins.each do |plugin|
+          plugin.manifest.consumes.each do |consume|
+            next if consume.optional
+            next if index.key?(consume.plugin_id) && producer_provides?(index[consume.plugin_id], consume.name)
+
+            errors << LoadError.new(
+              "plugin #{plugin.manifest.id.inspect} consumes " \
+              "#{consume.plugin_id.inspect}/#{consume.name} but no loaded plugin " \
+              "with that id declares `produces: [#{consume.name.inspect}]`",
+              plugin_ref: plugin.manifest.id,
+              reason: :"missing-producer"
+            )
+          end
+        end
+        errors
+      end
+
+      def producer_provides?(producer, name)
+        producer.manifest.produces.include?(name)
+      end
+
+      # Kahn's algorithm with `Configuration#plugins`-order
+      # tie-break. Edges go from producer -> consumer (producer
+      # must visit first). When two plugins are simultaneously
+      # ready, the configuration-order index decides the visit
+      # order — preserves the v0.1.0 legacy contract for plugins
+      # without dependencies.
+      def sort_in_topo_order(plugins, index, errors, config_order)
+        in_degree, forward = build_consumes_graph(plugins, index, errors)
+        ordered, cycle_errors = kahn_walk(plugins, in_degree, forward, config_order)
+        [ordered, errors + cycle_errors]
+      end
+
+      def build_consumes_graph(plugins, index, errors)
+        in_degree = Hash.new(0)
+        forward = Hash.new { |h, k| h[k] = [] }
+        plugins.each do |consumer|
+          consumer.manifest.consumes.each do |consume|
+            next unless index.key?(consume.plugin_id)
+            next if errors.any? { |e| e.plugin_ref == consume.plugin_id }
+
+            forward[consume.plugin_id] << consumer.manifest.id
+            in_degree[consumer.manifest.id] += 1
+          end
+        end
+        [in_degree, forward]
+      end
+
+      def kahn_walk(plugins, in_degree, forward, config_order)
+        order = ->(plugin) { config_order.fetch(plugin.manifest.id, Float::INFINITY) }
+        ready = plugins.select { |p| in_degree[p.manifest.id].zero? }.sort_by(&order)
+        result = kahn_collect(plugins, in_degree, forward, ready, order)
+
+        return [result, []] if result.size == plugins.size
+
+        cycled = plugins - result
+        [result, [dependency_cycle_error(cycled)]]
+      end
+
+      def kahn_collect(plugins, in_degree, forward, ready, order)
+        result = []
+        until ready.empty?
+          plugin = ready.shift
+          result << plugin
+          forward[plugin.manifest.id].each do |consumer_id|
+            in_degree[consumer_id] -= 1
+            ready << plugins.find { |p| p.manifest.id == consumer_id } if in_degree[consumer_id].zero?
+          end
+          ready.sort_by!(&order)
+        end
+        result
+      end
+
+      def dependency_cycle_error(cycled)
+        ids = cycled.map { |p| p.manifest.id }.sort
+        LoadError.new(
+          "plugin dependency cycle through `manifest(consumes:)`: #{ids.inspect}",
+          plugin_ref: ids.first,
+          reason: :"dependency-cycle"
+        )
+      end
+    end
+  end
+end

data/lib/rigor/plugin/manifest.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Value object describing one plugin's identity and metadata.
+    # Constructed once per plugin class through {Rigor::Plugin::Base.manifest};
+    # consumed by {Rigor::Plugin::Loader} when matching project
+    # configuration entries to registered plugins and by
+    # {Rigor::Cache::Descriptor::PluginEntry} when deriving cache keys.
+    #
+    # The fields are pinned by ADR-2 § "Registration, Configuration,
+    # and Caching"; the v0.1.0 plugin contract surface treats this
+    # struct as the public manifest shape.
+    class Manifest # rubocop:disable Metrics/ClassLength
+      # Same regex {Rigor::Cache::Store::VALID_PRODUCER_ID} uses,
+      # so plugin ids round-trip through cache producer ids and
+      # `plugin.<id>.<rule>` diagnostic identifiers without escape.
+      VALID_ID = /\A[a-z][a-z0-9._-]*\z/
+
+      # The first-implementation `config_schema` accepts these value
+      # kinds. Slice 1 only checks key presence and shallow value
+      # kind; richer schemas (nested maps, enums) land later when
+      # the v0.1.0 protocol slices need them.
+      VALID_VALUE_KINDS = %i[string boolean integer array hash any].freeze
+
+      # ADR-9 slice 4 — declared cross-plugin fact dependencies.
+      # `produces:` lists the names this plugin publishes through
+      # its `#prepare(services)` hook. `consumes:` lists the
+      # `(plugin_id, name)` pairs this plugin reads from
+      # `services.fact_store`. The loader uses both for
+      # topological sort + missing-producer detection (slice 5);
+      # slice 4 carries the declarations on the manifest but the
+      # loader does not yet enforce them.
+      Consumption = Data.define(:plugin_id, :name, :optional) do
+        def initialize(plugin_id:, name:, optional: false)
+          super(plugin_id: plugin_id.to_s, name: name.to_sym, optional: optional ? true : false)
+        end
+      end
+
+      attr_reader :id, :version, :description, :protocols, :config_schema, :produces, :consumes
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        id:, version:,
+        description: nil, protocols: [], config_schema: {},
+        produces: [], consumes: []
+      )
+        validate_id!(id)
+        validate_version!(version)
+        validate_protocols!(protocols)
+        validate_config_schema!(config_schema)
+        validate_produces!(produces)
+
+        assign_fields(id, version, description, protocols, config_schema, produces, consumes)
+        freeze
+      end
+
+      private
+
+      def assign_fields(id, version, description, protocols, config_schema, produces, consumes) # rubocop:disable Metrics/ParameterLists
+        @id = id.dup.freeze
+        @version = version.dup.freeze
+        @description = description.nil? ? nil : description.to_s.dup.freeze
+        @protocols = protocols.map(&:to_sym).freeze
+        @config_schema = config_schema.to_h { |k, v| [k.to_s.dup.freeze, v.to_sym] }.freeze
+        @produces = produces.map(&:to_sym).freeze
+        @consumes = coerce_consumes(consumes)
+      end
+
+      public
+
+      # Validates the user-supplied plugin config block against this
+      # manifest's `config_schema`. Returns an array of human-readable
+      # error strings (empty when the config is valid). Slice 1 checks
+      # only unknown keys and shallow value kind; nested schemas come
+      # with later slices.
+      def validate_config(config)
+        return ["plugin config must be a Hash, got #{config.class}"] unless config.is_a?(Hash)
+
+        errors = []
+        config.each do |key, value|
+          key_s = key.to_s
+          unless config_schema.key?(key_s)
+            errors << "unknown config key #{key_s.inspect} for plugin #{id.inspect}"
+            next
+          end
+
+          kind = config_schema.fetch(key_s)
+          errors << "config key #{key_s.inspect} expected #{kind}, got #{value.class}" unless value_matches?(value,
+                                                                                                             kind)
+        end
+        errors
+      end
+
+      def to_h
+        {
+          "id" => id,
+          "version" => version,
+          "description" => description,
+          "protocols" => protocols.map(&:to_s),
+          "config_schema" => config_schema.to_h { |k, v| [k, v.to_s] },
+          "produces" => produces.map(&:to_s),
+          "consumes" => consumes.map { |c| consumption_hash(c) }
+        }
+      end
+
+      def ==(other)
+        other.is_a?(Manifest) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_id!(id)
+        return if id.is_a?(String) && id.match?(VALID_ID)
+
+        raise ArgumentError,
+              "plugin manifest id must match #{VALID_ID.inspect}, got #{id.inspect}"
+      end
+
+      def validate_version!(version)
+        return if version.is_a?(String) && !version.empty?
+
+        raise ArgumentError, "plugin manifest version must be a non-empty String, got #{version.inspect}"
+      end
+
+      def validate_protocols!(protocols)
+        return if protocols.is_a?(Array) && protocols.all? { |p| p.is_a?(Symbol) || p.is_a?(String) }
+
+        raise ArgumentError, "plugin manifest protocols must be an Array of Symbol/String, got #{protocols.inspect}"
+      end
+
+      def validate_config_schema!(schema)
+        unless schema.is_a?(Hash)
+          raise ArgumentError,
+                "plugin manifest config_schema must be a Hash, got #{schema.inspect}"
+        end
+
+        schema.each_value do |kind|
+          next if VALID_VALUE_KINDS.include?(kind.to_sym)
+
+          raise ArgumentError,
+                "plugin manifest config_schema value kind must be one of " \
+                "#{VALID_VALUE_KINDS.inspect}, got #{kind.inspect}"
+        end
+      end
+
+      def value_matches?(value, kind)
+        case kind
+        when :string then value.is_a?(String)
+        when :boolean then [true, false].include?(value)
+        when :integer then value.is_a?(Integer)
+        when :array then value.is_a?(Array)
+        when :hash then value.is_a?(Hash)
+        when :any then true
+        else false
+        end
+      end
+
+      def validate_produces!(produces)
+        return if produces.is_a?(Array) && produces.all? { |p| p.is_a?(Symbol) || p.is_a?(String) }
+
+        raise ArgumentError, "plugin manifest produces must be an Array of Symbol/String, got #{produces.inspect}"
+      end
+
+      def coerce_consumes(consumes)
+        unless consumes.is_a?(Array)
+          raise ArgumentError, "plugin manifest consumes must be an Array, got #{consumes.inspect}"
+        end
+
+        consumes.map { |entry| coerce_consumption(entry) }.freeze
+      end
+
+      def coerce_consumption(entry)
+        case entry
+        when Consumption then entry
+        when Hash then build_consumption_from_hash(entry)
+        else raise ArgumentError,
+                   "plugin manifest consumes entry must be a Hash or Consumption, got #{entry.inspect}"
+        end
+      end
+
+      def consumption_hash(consumption)
+        { "plugin_id" => consumption.plugin_id, "name" => consumption.name.to_s, "optional" => consumption.optional }
+      end
+
+      def build_consumption_from_hash(entry)
+        plugin_id = entry[:plugin_id] || entry["plugin_id"]
+        name = entry[:name] || entry["name"]
+        optional = entry.key?(:optional) ? entry[:optional] : entry["optional"]
+        if plugin_id.nil? || name.nil?
+          raise ArgumentError,
+                "plugin manifest consumes entry missing plugin_id/name: #{entry.inspect}"
+        end
+
+        Consumption.new(plugin_id: plugin_id, name: name, optional: optional || false)
+      end
+    end
+  end
+end

data/lib/rigor/plugin/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Read-side query API over the plugins loaded for a single
+    # `Analysis::Runner.run`. Constructed by
+    # {Rigor::Plugin::Loader.load} and exposed downstream so the
+    # contribution merger (slice 3) and diagnostic provenance
+    # (slice 5) can iterate over loaded plugin instances in
+    # deterministic order.
+    #
+    # The registry is read-only after construction; ordering is
+    # the order in which {Rigor::Plugin::Loader} resolved
+    # configuration entries, which is project-config order with
+    # plugin-id alphabetical as the tie-breaker.
+    class Registry
+      attr_reader :plugins, :load_errors
+
+      # @param plugins [Array<Rigor::Plugin::Base>] instantiated
+      #   plugin instances in deterministic order.
+      # @param load_errors [Array<Rigor::Plugin::LoadError>] failures
+      #   surfaced during loading. Each error is also turned into a
+      #   diagnostic by the runner.
+      def initialize(plugins: [], load_errors: [])
+        @plugins = plugins.dup.freeze
+        @load_errors = load_errors.dup.freeze
+        freeze
+      end
+
+      def find(id)
+        id_s = id.to_s
+        plugins.find { |plugin| plugin.manifest.id == id_s }
+      end
+
+      def ids
+        plugins.map { |plugin| plugin.manifest.id }
+      end
+
+      def empty?
+        plugins.empty?
+      end
+
+      def any_load_errors?
+        !load_errors.empty?
+      end
+
+      EMPTY = new.freeze
+    end
+  end
+end

data/lib/rigor/plugin/services.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Dependency-injection container handed to every plugin's
+    # {Rigor::Plugin::Base#init} method. Plugins read from the
+    # container; they MUST NOT mutate it. The container is
+    # constructed once per `Analysis::Runner.run` and destroyed
+    # at the end of the run.
+    #
+    # ADR-2 § "Registration, Configuration, and Caching" reserves
+    # this surface for "constructor injection for analyzer
+    # services such as reflection providers, type factories,
+    # loggers, and configuration readers". Slice 1 wires four
+    # of those:
+    #
+    # - `reflection`: the {Rigor::Reflection} read-side facade.
+    # - `type`: the {Rigor::Type::Combinator} factory module.
+    # - `configuration`: the project's {Rigor::Configuration}.
+    # - `cache_store`: the {Rigor::Cache::Store} the run is using
+    #   (or `nil` when caching is disabled). Slice 6 wires
+    #   plugin-side cache producers through this entry.
+    #
+    # Loggers are not yet a public surface in the core analyzer;
+    # they will be added when the diagnostics formatter grows a
+    # progress channel.
+    #
+    # Slice 2 (Plugin trust / I/O policy) extends the container
+    # with `trust_policy` and a per-plugin `io_boundary_for(plugin_id)`
+    # factory. Plugins should reach for the boundary rather than
+    # raw `File.read` so reads stay within the trusted scope and
+    # feed cache invalidation; ADR-2 § "Plugin Trust and I/O
+    # Policy" documents the trust model the boundary enforces.
+    #
+    # ADR-9 slice 2 adds `fact_store`: the per-run cross-plugin
+    # `Plugin::FactStore`. Producer plugins publish their facts
+    # in `#prepare(services)` (slice 3); consumer plugins read in
+    # `#diagnostics_for_file` via `services.fact_store.read(...)`.
+    # A fresh `FactStore` instance is constructed per Services
+    # when none is supplied — the runner threads its own instance
+    # in once slice 3 wires `#prepare` invocation.
+    class Services
+      attr_reader :reflection, :type, :configuration, :cache_store, :trust_policy, :fact_store
+
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        reflection:, type:, configuration:,
+        cache_store: nil, trust_policy: nil, fact_store: nil
+      )
+        @reflection = reflection
+        @type = type
+        @configuration = configuration
+        @cache_store = cache_store
+        @trust_policy = trust_policy || default_trust_policy
+        @fact_store = fact_store || FactStore.new
+        freeze
+      end
+
+      # Returns a fresh {IoBoundary} bound to `plugin_id` and the
+      # current `trust_policy`. The boundary accumulates per-plugin
+      # cache descriptor entries; the loader / contribution merger
+      # constructs one boundary per plugin per run.
+      def io_boundary_for(plugin_id)
+        IoBoundary.new(policy: @trust_policy, plugin_id: plugin_id)
+      end
+
+      private
+
+      def default_trust_policy
+        TrustPolicy.new(
+          trusted_gems: [],
+          allowed_read_roots: [Dir.pwd],
+          network_policy: :disabled
+        )
+      end
+    end
+  end
+end