rigortype 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47346567152367cb408115b6a33214e43468f2255bd632b4894d8c68164b8ada
-  data.tar.gz: 407d5cda9e08342670a4eeb05ae2c565d398866174d292c586793cb213a77fdb
+  metadata.gz: 3542aa2842a06783d02f8f35b7f31247eb8d10dce91214b31364839ad7087809
+  data.tar.gz: 6beca5ec330dab3264cb64a110bd4e6a790e16a92c5f1cf10383799b988d2bb9
 SHA512:
-  metadata.gz: f6ffecd573e1bbb387c861cbe3a6d909d217dfadef453a7a84339a4f7fd44e2c86dbbac54c8369298b56a2de3771c0f75c28cfe098cb895355a52155657f4f9d
-  data.tar.gz: 6f924aed4bc15581bae58ffa62a5d8194db3fabbdc3056f2b6cfc4f068f972063e0148f85df8b8ef3e5f5003fad35b4e9016e534ef604cbfc581d0cdab76bb7b
+  metadata.gz: 33d98371534cd4d193b39afe08dc5b442cd90e0909388a9e9a20413d8ae766665d8bb7a8573bb2236997a72ce178e35c7d2c62c64ceac804f1a31bf88b079950
+  data.tar.gz: 0fca38a07730117fa58b42d8c14642e86540a492ce0513c4612dbf58049600bb8adc224fc32cdfc518ba581a870c478b8dfbbc02ce43bf78eb251c3d1dd771db

data/README.md

@@ -239,6 +239,16 @@ Rigor consults, in order:
    Rigor walks `def` / `define_method` / `attr_*` /
    `Data.define(*Symbol)` so user-defined methods on a class
    are recognised.
+5. **Opt-in gem-source inference (ADR-10).** Gems listed
+   under `dependencies.source_inference:` in `.rigor.yml`
+   have their `lib/` walked the same way project source is,
+   so methods on those gems' classes resolve even without
+   RBS. Inferred returns crossing the gem boundary are
+   wrapped in `Dynamic[T]` so the call site retains the
+   provenance — RBS / RBS::Inline / generated stubs / plugin
+   contracts always win on conflict. Default behaviour is
+   unchanged: gems not listed stay at the
+   RBS-or-`Dynamic[Top]` boundary.
 
 If a type cannot be proved, the engine returns `Dynamic[Top]`
 (Rigor's gradual carrier) and stays silent — Rigor never invents

data/lib/rigor/analysis/dependency_source_inference/builder.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "gem_resolver"
+require_relative "index"
+require_relative "walker"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Folds a `Configuration::Dependencies` value into a
+      # frozen {Index}. Resolves each non-disabled entry through
+      # {GemResolver}, walks each resolved gem's `roots:` via
+      # {Walker.walk} under the configured `budget_per_gem` cap,
+      # and aggregates the per-gem method catalogs into the
+      # Index's flat `(class_name, method_name) → kind` table.
+      #
+      # Entries with `mode: :disabled` are skipped without
+      # resolution attempts so users can "list and disable" a
+      # gem in configuration without provoking a missing-gem
+      # diagnostic.
+      module Builder
+        module_function
+
+        # @param dependencies [Rigor::Configuration::Dependencies]
+        # @return [Index]
+        def build(dependencies) # rubocop:disable Metrics/MethodLength
+          return Index::EMPTY if dependencies.empty?
+
+          resolved = []
+          unresolvable = []
+          catalog = {}
+          class_to_gem = {}
+          budget_exceeded = []
+          budget = dependencies.budget_per_gem
+
+          dependencies.source_inference.each do |entry|
+            next if entry.disabled?
+
+            outcome = GemResolver.resolve(entry)
+            case outcome
+            when GemResolver::Resolved
+              resolved << outcome
+              walked = walker_outcome_for(outcome, budget)
+              catalog.merge!(walked.catalog)
+              record_class_to_gem(walked.catalog, outcome.gem_name, class_to_gem)
+              budget_exceeded << outcome.gem_name if walked.truncated?
+            when GemResolver::Unresolvable then unresolvable << outcome
+            end
+          end
+
+          Index.new(
+            resolved_gems: resolved, unresolvable: unresolvable,
+            method_catalog: catalog, budget_exceeded: budget_exceeded,
+            class_to_gem: class_to_gem,
+            budget_overrun_strategy: dependencies.budget_overrun_strategy
+          )
+        end
+
+        # ADR-10 5b — per-class reverse-lookup table (β budget
+        # semantics). Records `class_name → gem_name` for every
+        # class observed in the gem's catalog. First-write-wins:
+        # if two opt-in gems re-open the same class, the first
+        # gem to harvest the class owns it in the reverse index.
+        # The dispatcher only consults this map when the
+        # `budget_overrun_strategy` is `:dependency_silence`,
+        # so the storage cost is never paid back unless the
+        # user opts in.
+        def record_class_to_gem(catalog, gem_name, class_to_gem)
+          catalog.each_key do |(class_name, _method_name)|
+            class_to_gem[class_name] ||= gem_name
+          end
+        end
+
+        # Per-resolved-gem walk. Isolated so a single gem's
+        # filesystem error / parse failure cannot abort the
+        # build; the walker swallows its own per-file errors,
+        # and a top-level raise here degrades the gem to "no
+        # contributions" without touching the rest of the run.
+        def walker_outcome_for(resolved, budget)
+          Walker.walk(gem_dir: resolved.gem_dir, roots: resolved.roots, budget: budget)
+        rescue StandardError
+          Walker::Outcome.new(catalog: {}.freeze, truncated: false)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference/gem_resolver.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Maps a `Configuration::Dependencies::Entry` to the gem's
+      # on-disk installation directory by consulting RubyGems
+      # (`Gem.loaded_specs` first, falling back to
+      # `Gem::Specification.find_by_name`). Returns either a
+      # frozen {Resolved} value object or an {Unresolvable} value
+      # describing why the gem cannot participate in this run.
+      #
+      # Resolution failures are surfaced as
+      # `dynamic.dependency-source.gem-not-found` diagnostics by
+      # {Analysis::Runner} rather than crashing the run, so a
+      # missing gem in `dependencies.source_inference` degrades
+      # cleanly to "no contributions from that gem" — every other
+      # gem and the project source remain unaffected.
+      module GemResolver
+        # Successful resolution. `version` is the spec version as
+        # a String so it round-trips into cache descriptors
+        # (slice 3) without leaking a `Gem::Version` instance
+        # through public surfaces.
+        Resolved = Data.define(:gem_name, :version, :gem_dir, :mode, :roots) do
+          def descriptor_key
+            [gem_name, version, mode].freeze
+          end
+        end
+
+        # Unresolvable reasons. `:not_in_bundle` covers both the
+        # "RubyGems doesn't know this gem" case and the
+        # `LoadError`-style raise from `find_by_name`. Future
+        # reasons (`:c_extension_only`, `:no_lib_root`) are
+        # introduced as the walker discovers them in slice 2b.
+        Unresolvable = Data.define(:gem_name, :reason)
+
+        VALID_REASONS = %i[not_in_bundle].freeze
+
+        module_function
+
+        # @param entry [Rigor::Configuration::Dependencies::Entry]
+        # @return [Resolved, Unresolvable]
+        def resolve(entry)
+          spec = locate_gem_spec(entry.gem)
+          return Unresolvable.new(gem_name: entry.gem, reason: :not_in_bundle) if spec.nil?
+
+          Resolved.new(
+            gem_name: entry.gem,
+            version: spec.version.to_s,
+            gem_dir: spec.full_gem_path, # rigor:disable undefined-method
+            mode: entry.mode,
+            roots: entry.roots
+          )
+        end
+
+        # Locator. `Gem.loaded_specs` reflects the bundle (cheap
+        # lookup, no filesystem walk); `find_by_name` is the
+        # broader fallback for gems present on the gem path but
+        # not yet `require`'d. `Gem::MissingSpecError` is a
+        # `LoadError` subclass, so the rescue covers both
+        # missing-spec and load-error signals.
+        def locate_gem_spec(name)
+          Gem.loaded_specs[name] || begin
+            Gem::Specification.find_by_name(name)
+          rescue LoadError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference/index.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../../cache/descriptor"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Per-run collection of gem-source-inference state. Holds
+      # the resolved gems the walker MAY visit (slice 2b) plus
+      # the unresolvable entries the runner SHOULD surface as
+      # `dynamic.dependency-source.gem-not-found` diagnostics.
+      #
+      # Slice 2a lands the data structure only; the dispatcher
+      # tier consults {#contribution_for} but the lookup always
+      # answers `nil` until slice 2b populates the method table
+      # by walking the resolved gems' `roots:`.
+      class Index
+        attr_reader :resolved_gems, :unresolvable, :method_catalog, :budget_exceeded,
+                    :class_to_gem, :budget_overrun_strategy
+
+        # @param method_catalog [Hash{[String, Symbol] => Symbol}]
+        #   the flat `(class_name, method_name) → :instance | :singleton`
+        #   table produced by {Walker.walk}, aggregated across
+        #   every resolved gem in the run. The Index itself stays
+        #   gem-agnostic — the per-gem attribution that slice 3's
+        #   cache descriptor needs lives on `Resolved`, not here.
+        # @param budget_exceeded [Array<String>] gem names whose
+        #   {Walker} run hit the per-gem catalog cap (slice 4).
+        #   The Runner consumes this list to emit one
+        #   `dynamic.dependency-source.budget-exceeded` warning
+        #   per gem.
+        # @param class_to_gem [Hash<String, String>] reverse
+        #   lookup `class_name → gem_name` (slice 5b). Built
+        #   first-write-wins: when two opt-in gems re-open the
+        #   same class, the first gem owns it. The dispatcher
+        #   consults this map under the `:dependency_silence`
+        #   budget overrun strategy so call sites on a
+        #   budget-exceeded gem's classes degrade to
+        #   `Dynamic[top]` instead of falling through to the
+        #   user-class fallback.
+        def initialize( # rubocop:disable Metrics/ParameterLists
+          resolved_gems: [], unresolvable: [], method_catalog: {},
+          budget_exceeded: [], class_to_gem: {},
+          budget_overrun_strategy: :walker_cap
+        )
+          @resolved_gems = resolved_gems.freeze
+          @unresolvable = unresolvable.freeze
+          @method_catalog = method_catalog.freeze
+          @budget_exceeded = budget_exceeded.freeze
+          @class_to_gem = class_to_gem.freeze
+          @budget_overrun_strategy = budget_overrun_strategy
+          freeze
+        end
+
+        # @return [String, nil] the gem that owns `class_name`
+        #   (first-write-wins); `nil` when the class isn't in
+        #   any opt-in gem's catalog.
+        def gem_for(class_name)
+          @class_to_gem[class_name]
+        end
+
+        # Looks up the recorded method kind for a
+        # `(class_name, method_name)` pair. Returns `:instance`
+        # / `:singleton` when the walker observed a definition
+        # under one of the resolved gems' `roots:`, or `nil`
+        # otherwise. Slice 2b-ii enriches this with the inferred
+        # return type so the dispatcher tier can build a
+        # `Type::Dynamic` directly from the lookup result.
+        def contribution_for(class_name:, method_name:)
+          @method_catalog[[class_name, method_name]]
+        end
+
+        def empty?
+          @resolved_gems.empty?
+        end
+
+        # Builds a frozen `Cache::Descriptor` carrying one
+        # `DependencyEntry` row per resolved gem in this run.
+        # Cache producers that observe ADR-10 inference outputs
+        # compose this descriptor with their own (RBS, plugin,
+        # file-digest) descriptors so a `bundle update` on a
+        # listed gem invalidates exactly that gem's slice while
+        # leaving the rest of the cache hot.
+        #
+        # Unresolvable entries contribute nothing — there is no
+        # version to key on, and the runner already surfaces them
+        # as `dynamic.dependency-source.gem-not-found`
+        # diagnostics. Resolved-but-disabled entries are also
+        # absent: the {Builder} skips them before resolution, so
+        # they never reach the index.
+        def cache_descriptor
+          dependencies = @resolved_gems.map do |resolved|
+            Cache::Descriptor::DependencyEntry.new(
+              gem_name: resolved.gem_name,
+              gem_version: resolved.version,
+              mode: resolved.mode
+            )
+          end
+          Cache::Descriptor.new(dependencies: dependencies)
+        end
+      end
+
+      # Frozen empty index — the runner uses this when
+      # `Configuration#dependencies.source_inference` is empty
+      # so the dispatcher tier holds a stable, non-nil
+      # reference even on default configurations.
+      Index::EMPTY = Index.new.freeze
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference/walker.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Walks a resolved gem's `roots:` and collects the
+      # `(class_name, method_name) → :instance | :singleton`
+      # method catalog. The walker is the source of facts the
+      # dispatcher tier (slice 2b-ii) consults to recognise a
+      # method as defined by an opt-in gem and contribute a
+      # `Type::Dynamic` return at the call site.
+      #
+      # Slice 2b-i intentionally collects only the catalog, not
+      # the inferred return type. The dispatcher tier returns
+      # `Dynamic[top]` on a hit until slice 2b-ii wires return-
+      # type inference; the visible payoff today is removing the
+      # `call.undefined-method` diagnostic for opt-in gem methods
+      # at receivers Rigor knows by `Nominal[T]` (typically
+      # because the user authored an RBS skeleton).
+      #
+      # Hard exclusions are NOT user-configurable, per ADR-10
+      # § "Hard exclusions": top-level `spec/`, `test/`, `bin/`,
+      # plus any non-`.rb` source. C extensions fall out
+      # automatically because the walker only loads `.rb` files.
+      module Walker
+        # Top-level directories that MUST NOT participate in
+        # gem-source inference even when the user lists them
+        # under `roots:`. The check is case-insensitive against
+        # the first segment of `roots:`; nested `spec/` /
+        # `test/` directories deeper inside `lib/` are NOT
+        # filtered (a few gems legitimately ship `lib/.../spec/`).
+        HARD_EXCLUDED_ROOTS = %w[spec test bin].freeze
+
+        # Walker outcome wrapping the harvested method catalog
+        # plus a budget-exceeded flag. ADR-10 slice 4 introduces
+        # the cap; the Walker stops appending to the accumulator
+        # once `catalog.size` reaches `budget`, and `truncated?`
+        # reports whether the cap was reached. The Index records
+        # this per-gem so the Runner can surface a single
+        # `dynamic.dependency-source.budget-exceeded` warning
+        # naming the affected gem(s).
+        Outcome = Data.define(:catalog, :truncated) do
+          def truncated? = truncated
+        end
+
+        # Sentinel for "no cap" — used by callers that don't
+        # care about the budget (specs, tooling). Production
+        # code MUST pass an integer.
+        UNBOUNDED = Float::INFINITY
+
+        module_function
+
+        # @param gem_dir [String, Pathname] absolute path to the
+        #   gem's installation directory.
+        # @param roots [Array<String>] subdirectory names within
+        #   the gem to walk (defaults to `["lib"]` per
+        #   `Configuration::Dependencies::Entry`).
+        # @param budget [Integer, Float] per-gem catalog cap
+        #   (method-definition count). When unset, defaults to
+        #   `UNBOUNDED` for backwards-compatible test paths.
+        # @return [Outcome] frozen wrapper carrying the catalog
+        #   (`Hash{[class_name, method_name] => :instance |
+        #   :singleton}`) and a `truncated?` flag set when the
+        #   walker stopped harvesting because the budget was
+        #   reached. Methods of identical name on the same class
+        #   with different kinds (rare; private API mostly)
+        #   carry the kind that wins the per-class first walk.
+        def walk(gem_dir:, roots:, budget: UNBOUNDED)
+          accumulator = {}
+          truncated = false
+          accepted_roots(roots).each do |root|
+            break if truncated
+
+            truncated = walk_root(File.join(gem_dir.to_s, root), accumulator, budget)
+          end
+          Outcome.new(catalog: accumulator.freeze, truncated: truncated)
+        end
+
+        # Drops hard-excluded entries before any filesystem
+        # walk happens. Reasoning: we never want a gem's
+        # `spec/` to participate even if the user requested
+        # it — the noise from RSpec-style globals plus the
+        # cost of walking test fixtures isn't worth the
+        # marginal coverage.
+        def accepted_roots(roots)
+          roots.reject { |root| HARD_EXCLUDED_ROOTS.include?(root.downcase) }
+        end
+
+        # Returns true when the budget tripped during this
+        # root's walk so the caller can stop iterating
+        # subsequent roots.
+        def walk_root(root_dir, accumulator, budget) # rubocop:disable Naming/PredicateMethod
+          return false unless File.directory?(root_dir)
+
+          Dir.glob(File.join(root_dir, "**", "*.rb")).each do |path|
+            harvest_file(path, accumulator, budget)
+            return true if accumulator.size >= budget
+          end
+          false
+        end
+
+        def harvest_file(path, accumulator, budget)
+          parse_result = Prism.parse_file(path)
+          return unless parse_result.errors.empty?
+
+          walk_node(parse_result.value, [], false, accumulator, budget)
+        rescue StandardError
+          # Gem source we can't parse / read silently degrades
+          # to "no contribution from this file". The user-facing
+          # diagnostic stream is reserved for the project source;
+          # opt-in gem source MUST NOT pollute it with parse
+          # errors the user cannot fix.
+          nil
+        end
+
+        # Walks a Prism subtree, accumulating method definitions
+        # under their qualified class name. Mirrors the shape of
+        # `Inference::ScopeIndexer#walk_methods` but stays
+        # decoupled from `Scope` because gem-source inference
+        # runs without a scope context.
+        def walk_node(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          return unless node.is_a?(Prism::Node)
+          return if accumulator.size >= budget
+
+          case node
+          when Prism::ClassNode, Prism::ModuleNode
+            descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          when Prism::SingletonClassNode
+            descend_singleton_class(node, qualified_prefix, accumulator, budget)
+          when Prism::DefNode
+            record_def_node(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        def walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          node.compact_child_nodes.each do |child|
+            break if accumulator.size >= budget
+
+            walk_node(child, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        # `class Foo` / `module Bar`. The dynamic-prefix shape
+        # (`module ::Foo`-rooted variants whose left side is a
+        # runtime expression) is treated as opaque — we walk the
+        # children under the same prefix so any inner class
+        # definitions are still recorded under their own name.
+        def descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          name = qualified_name_for(node.constant_path)
+          if name && node.body
+            walk_node(node.body, qualified_prefix + [name], in_singleton_class, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
+          end
+        end
+
+        # `class << self` only — `class << expr` for any other
+        # `expr` is treated as opaque so we don't accidentally
+        # record per-instance singleton methods under the
+        # surrounding class.
+        def descend_singleton_class(node, qualified_prefix, accumulator, budget)
+          if node.expression.is_a?(Prism::SelfNode) && node.body
+            walk_node(node.body, qualified_prefix, true, accumulator, budget)
+          else
+            walk_children(node, qualified_prefix, false, accumulator, budget)
+          end
+        end
+
+        def record_def_node(node, qualified_prefix, in_singleton_class, accumulator, _budget)
+          return if qualified_prefix.empty?
+
+          class_name = qualified_prefix.join("::")
+          kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+          accumulator[[class_name, node.name]] ||= kind
+        end
+
+        # Resolves a `Prism::ConstantPathNode` /
+        # `Prism::ConstantReadNode` chain to its dot-separated
+        # name (e.g. `"Foo::Bar"`). Returns nil for the rare
+        # dynamic-prefix shape (`module ::Foo`-rooted variants
+        # whose left side is a runtime expression) so the
+        # walker treats those as opaque rather than guessing.
+        def qualified_name_for(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode
+            parent = node.parent.nil? ? nil : qualified_name_for(node.parent)
+            return nil if !node.parent.nil? && parent.nil?
+
+            parent.nil? ? node.name.to_s : "#{parent}::#{node.name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "dependency_source_inference/gem_resolver"
+require_relative "dependency_source_inference/index"
+require_relative "dependency_source_inference/walker"
+require_relative "dependency_source_inference/builder"
+
+module Rigor
+  module Analysis
+    # Implementation of [ADR-10 — Opt-in dependency-source
+    # inference](../../../docs/adr/10-dependency-source-inference.md).
+    #
+    # The namespace coordinates three components:
+    #
+    # - {GemResolver} maps a
+    #   `Configuration::Dependencies::Entry` to either a frozen
+    #   `Resolved(gem_name, version, gem_dir, mode, roots)` or an
+    #   `Unresolvable(gem_name, reason)` value.
+    # - {Builder.build} folds a `Configuration::Dependencies`
+    #   into a frozen {Index} carrying the partitioned outcomes.
+    # - {Index} holds the per-run state the dispatcher tier
+    #   consults via `#contribution_for`. Slice 2a ships the
+    #   stub returning `nil`; slice 2b populates the method
+    #   table by walking each resolved gem's `roots:`.
+    #
+    # Per the ADR's "Implementation slicing" section, slice 2 is
+    # split internally:
+    #
+    # - Slice 2a (this commit): gem resolution, index plumbing,
+    #   `Analysis::Runner` wiring, `dynamic.dependency-source.gem-not-found`
+    #   diagnostic for unresolvable entries.
+    # - Slice 2b (next commit): walker, dispatcher tier
+    #   integration, `Type::Dynamic`-wrapped returns.
+    module DependencySourceInference
+    end
+  end
+end

data/lib/rigor/analysis/runner.rb

@@ -12,6 +12,7 @@ require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
+require_relative "dependency_source_inference"
 require_relative "diagnostic"
 require_relative "result"
 
@@ -21,7 +22,7 @@ module Rigor
       RUBY_GLOB = "**/*.rb"
       DEFAULT_CACHE_ROOT = ".rigor/cache"
 
-      attr_reader :cache_store, :plugin_registry
+      attr_reader :cache_store, :plugin_registry, :dependency_source_index
 
       # @param configuration [Rigor::Configuration]
       # @param explain [Boolean] surface fail-soft fallback events
@@ -40,6 +41,7 @@ module Rigor
         @cache_store = cache_store
         @plugin_requirer = plugin_requirer
         @plugin_registry = Plugin::Registry::EMPTY
+        @dependency_source_index = DependencySourceInference::Index::EMPTY
       end
 
       # Walks every Ruby file under `paths`, parses it, builds a
@@ -58,22 +60,37 @@ module Rigor
         return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
 
         @plugin_registry = load_plugins
+        @dependency_source_index = DependencySourceInference::Builder.build(@configuration.dependencies)
         environment = Environment.for_project(
           libraries: @configuration.libraries,
           signature_paths: @configuration.signature_paths,
           cache_store: @cache_store,
-          plugin_registry: @plugin_registry
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index
         )
         expansion = expand_paths(paths)
 
-        diagnostics = plugin_load_diagnostics
-        diagnostics += plugin_prepare_diagnostics
-        diagnostics += expansion.fetch(:errors)
+        diagnostics = pre_file_diagnostics(expansion)
         diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
 
         Result.new(diagnostics: apply_severity_profile(diagnostics))
       end
 
+      # Pre-file diagnostic streams that fire once per run rather
+      # than per analyzed file: plugin load / prepare envelopes,
+      # the ADR-10 dependency-source resolution surface, and the
+      # `expand_paths` errors for `paths:` entries that don't
+      # exist or aren't `.rb`. Aggregated here so `#run` stays
+      # under the ABC budget.
+      def pre_file_diagnostics(expansion)
+        plugin_load_diagnostics +
+          plugin_prepare_diagnostics +
+          dependency_source_diagnostics +
+          dependency_source_budget_diagnostics +
+          dependency_source_config_conflict_diagnostics +
+          expansion.fetch(:errors)
+      end
+
       # `target_ruby` flows through to Prism's `version:` option.
       # Prism enforces the supported range and raises
       # `ArgumentError` for versions it does not recognise. Run a
@@ -207,6 +224,78 @@ module Rigor
         end
       end
 
+      # ADR-10 § "Diagnostic prefix family" — surfaces gems
+      # listed in `dependencies.source_inference` that RubyGems
+      # could not resolve. The run continues; the gem simply
+      # contributes nothing this session, mirroring the
+      # plugin-load error envelope. Authored `:warning` because
+      # an unresolvable gem usually means a typo or a missing
+      # `bundle install` rather than a project-blocking problem;
+      # the severity profile still re-stamps it.
+      def dependency_source_diagnostics
+        @dependency_source_index.unresolvable.map do |entry|
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "dependencies.source_inference[].gem #{entry.gem_name.inspect} could not be " \
+                     "resolved (#{entry.reason}); skipping",
+            severity: :warning,
+            rule: "dynamic.dependency-source.gem-not-found",
+            source_family: :builtin
+          )
+        end
+      end
+
+      # ADR-10 § "Budget interaction" / slice 4 — emits one
+      # `:warning` per gem whose Walker run hit the
+      # `dependencies.budget_per_gem` cap. The cap is a Walker-
+      # side guard rail (slice 4 picks the (α) semantics from
+      # ADR-10 WD4: harvesting stops, the dispatcher behaves
+      # exactly as before for unrecorded methods). The
+      # diagnostic names the gem and points the user at the
+      # three remediations: ship RBS, reduce `mode:` from
+      # `full` to `when_missing`, or de-list the gem.
+      # ADR-10 § "config-conflict diagnostic" / 5d — surfaces
+      # `Configuration::Dependencies` warnings accumulated
+      # during `from_h` deduplication of the `includes:`-chain
+      # source_inference array. Each warning describes a
+      # per-gem mode conflict that the merge resolved
+      # right-wins; the user sees one diagnostic per conflict.
+      # `:warning` matches the user's "warn but don't block"
+      # preference per the design discussion.
+      def dependency_source_config_conflict_diagnostics
+        @configuration.dependencies.warnings.map do |message|
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: message,
+            severity: :warning,
+            rule: "dynamic.dependency-source.config-conflict",
+            source_family: :builtin
+          )
+        end
+      end
+
+      def dependency_source_budget_diagnostics
+        budget = @configuration.dependencies.budget_per_gem
+        @dependency_source_index.budget_exceeded.map do |gem_name|
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "dependencies.source_inference[].gem #{gem_name.inspect} exceeded the per-gem " \
+                     "catalog cap (#{budget} method definitions); the remaining methods fall back " \
+                     "to the existing RBS-or-Dynamic[top] boundary. Ship RBS for the gem, set " \
+                     "`mode: when_missing` instead of `full`, or de-list the gem.",
+            severity: :warning,
+            rule: "dynamic.dependency-source.budget-exceeded",
+            source_family: :builtin
+          )
+        end
+      end
+
       # ADR-9 slice 3 — invokes every loaded plugin's `#prepare`
       # hook once per run, after the loader's `#init` pass and
       # before per-file iteration. Plugins publish facts here