rigortype 0.1.1 → 0.1.3

data/lib/rigor/analysis/rule_catalog.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require_relative "check_rules"
+
+module Rigor
+  module Analysis
+    # Single-source-of-truth metadata table for every CheckRule
+    # the analyzer ships. Consumed by `rigor explain <rule>` so
+    # users can read the same information the docs site eventually
+    # publishes without leaving the terminal.
+    #
+    # Each entry carries:
+    #
+    # - `id` — canonical rule id (`call.undefined-method`).
+    # - `summary` — single-line headline (≤ 80 chars).
+    # - `fires_when` — bullet-shaped list of conditions that
+    #   trigger the rule, in the order a reader can scan
+    #   top-to-bottom.
+    # - `does_not_fire_when` — explicit list of cases the rule
+    #   intentionally skips. Useful for "why am I NOT seeing
+    #   this diagnostic?" questions.
+    # - `suppression` — short note on how to suppress (in-source
+    #   `# rigor:disable` and the v0.1.2 file-scope variant
+    #   `# rigor:disable-file`, plus `.rigor.yml` `disable:`,
+    #   apply to every rule, so the note covers any rule-specific
+    #   nuance — e.g. unreachable-branch lives on the dead-branch
+    #   line, not the predicate line).
+    # - `severity_authored` — Symbol the rule emits with.
+    # - `severity_by_profile` — Hash of `:lenient` / `:balanced`
+    #   / `:strict` to the configured severity per profile, taken
+    #   from `Configuration::SeverityProfile::PROFILES`.
+    # - `since` — first version the rule shipped in.
+    module RuleCatalog # rubocop:disable Metrics/ModuleLength
+      Entry = Data.define(:id, :summary, :fires_when, :does_not_fire_when,
+                          :suppression, :severity_authored, :severity_by_profile, :since) do
+        def aliases
+          CheckRules::LEGACY_RULE_ALIASES.select { |_legacy, canonical| canonical == id }.keys
+        end
+
+        # Hash-shaped form for `--format=json` consumers. Keys are
+        # Strings so the payload is JSON-stable without a transform
+        # pass.
+        def to_h
+          {
+            "id" => id,
+            "aliases" => aliases,
+            "summary" => summary,
+            "fires_when" => fires_when,
+            "does_not_fire_when" => does_not_fire_when,
+            "suppression" => suppression,
+            "severity_authored" => severity_authored.to_s,
+            "severity_by_profile" => severity_by_profile.transform_keys(&:to_s).transform_values(&:to_s),
+            "since" => since
+          }
+        end
+      end
+
+      ENTRIES = {
+        CheckRules::RULE_UNDEFINED_METHOD => Entry.new(
+          id: CheckRules::RULE_UNDEFINED_METHOD,
+          summary: "Method does not exist on the receiver's statically-known class.",
+          fires_when: [
+            "The call is `receiver.method(...)` with an explicit receiver.",
+            "The receiver type resolves to `Type::Nominal` / `Singleton` / `Constant` / `Tuple` / `HashShape`.",
+            "The receiver class is RBS-known (declared in the loaded environment).",
+            "The user has not declared the method via `def` or recognised `define_method`.",
+            "Neither the receiver class nor an ancestor's RBS sig declares the method."
+          ],
+          does_not_fire_when: [
+            "Implicit-self calls (no receiver) — too noisy without per-method RBS for every helper.",
+            "Receiver is `Dynamic[T]` / `Top` / `Union` — by definition the method set isn't enumerable.",
+            "Receiver class is in the loader but its RBS definition cannot be built (constant aliases)."
+          ],
+          suppression: "`# rigor:disable call.undefined-method` on the call line, " \
+                       "or `disable: [\"call.undefined-method\"]` in `.rigor.yml`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_WRONG_ARITY => Entry.new(
+          id: CheckRules::RULE_WRONG_ARITY,
+          summary: "Call's positional argument count is outside the declared overloads' envelope.",
+          fires_when: [
+            "Call is `receiver.method(args...)` with explicit receiver + plain positional args.",
+            "Receiver class is RBS-known and the method has a definition.",
+            "Actual positional count is below the min or above the max across all overloads."
+          ],
+          does_not_fire_when: [
+            "Call uses `*splat`, keyword arguments, block-pass, or forwarded arguments.",
+            "Method declares required keyword arguments (caller must pass kwargs the rule doesn't model).",
+            "Method has a `*rest` positional parameter (max arity is unbounded)."
+          ],
+          suppression: "`# rigor:disable call.wrong-arity`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ARGUMENT_TYPE => Entry.new(
+          id: CheckRules::RULE_ARGUMENT_TYPE,
+          summary: "Call passes an argument whose type the parameter cannot accept.",
+          fires_when: [
+            "The parameter type rejects the argument under `accepts(arg, mode: :gradual)`.",
+            "Method has a single overload (multi-overload checking is deferred).",
+            "Both sides have a non-Dynamic concrete type."
+          ],
+          does_not_fire_when: [
+            "Either the parameter or the argument is `Dynamic[T]`.",
+            "Method has multiple overloads.",
+            "Method has `*rest_positionals`, required keywords, or trailing positionals."
+          ],
+          suppression: "`# rigor:disable call.argument-type-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_NIL_RECEIVER => Entry.new(
+          id: CheckRules::RULE_NIL_RECEIVER,
+          summary: "Receiver may be nil and the method is not defined on NilClass.",
+          fires_when: [
+            "Receiver type is `Type::Union` containing `Constant<nil>` (or `nil` from the RBS Optional).",
+            "The non-nil branch has the method, but `NilClass` does not.",
+            "Call is not safe-navigation (`x&.method`)."
+          ],
+          does_not_fire_when: [
+            "Method exists on every member of the union (including NilClass).",
+            "Receiver was narrowed via `return if x.nil?` / similar early-return guard.",
+            "Call uses safe-navigation (`x&.method`)."
+          ],
+          suppression: "`# rigor:disable call.possible-nil-receiver`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.2"
+        ),
+
+        CheckRules::RULE_DUMP_TYPE => Entry.new(
+          id: CheckRules::RULE_DUMP_TYPE,
+          summary: "`dump_type(expr)` from Rigor::Testing — informational type print.",
+          fires_when: [
+            "Top-level / DSL-block call to `dump_type(expr)` after `include Rigor::Testing`."
+          ],
+          does_not_fire_when: [
+            "Outside a context that includes Rigor::Testing.",
+            "Argument is not a single expression."
+          ],
+          suppression: "Remove the `dump_type` call (it's a debug helper, not a real diagnostic).",
+          severity_authored: :info,
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ASSERT_TYPE => Entry.new(
+          id: CheckRules::RULE_ASSERT_TYPE,
+          summary: "`assert_type(\"<expected>\", expr)` from Rigor::Testing — type-equality check.",
+          fires_when: [
+            "Inferred type's display does not match the asserted string.",
+            "Useful in fixture self-assertions (every `spec/integration/fixtures/*.rb` uses it)."
+          ],
+          does_not_fire_when: [
+            "Inferred type matches the assertion exactly."
+          ],
+          suppression: "Update the assertion to the actual inferred type, or correct the source.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :error, balanced: :error, strict: :error },
+          since: "0.0.1"
+        ),
+
+        CheckRules::RULE_ALWAYS_RAISES => Entry.new(
+          id: CheckRules::RULE_ALWAYS_RAISES,
+          summary: "Call provably raises (today: Integer division-by-zero).",
+          fires_when: [
+            "Receiver is `Integer` / `IntegerRange` / `Constant<Integer>`.",
+            "Operator is `/` / `%` / `div` / `modulo` / `divmod`.",
+            "Argument is a `Constant<Integer>` whose value is exactly zero."
+          ],
+          does_not_fire_when: [
+            "Receiver is Float / Rational (those return Infinity / NaN, not an exception).",
+            "Argument is a Union containing zero (\"may raise\" not \"always raises\")."
+          ],
+          suppression: "`# rigor:disable flow.always-raises`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.0.3"
+        ),
+
+        CheckRules::RULE_UNREACHABLE_BRANCH => Entry.new(
+          id: CheckRules::RULE_UNREACHABLE_BRANCH,
+          summary: "An if / unless / ternary's literal predicate makes one branch dead.",
+          fires_when: [
+            "Predicate is a syntactic literal: `true` / `false` / `nil` / Integer / Float / String / Symbol / Regexp.",
+            "The corresponding dead branch carries a non-empty body."
+          ],
+          does_not_fire_when: [
+            "Predicate is an inferred-constant expression (not a literal). The literal-only envelope avoids " \
+            "false positives from Rigor's incomplete loop / mutation / RBS-strictness modelling.",
+            "The dead branch is empty (no useful location to point at)."
+          ],
+          suppression: "`# rigor:disable unreachable-branch` on the dead-branch line (the diagnostic " \
+                       "points at the dead branch, not the predicate, so the suppression goes there).",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_ALWAYS_TRUTHY_CONDITION => Entry.new(
+          id: CheckRules::RULE_ALWAYS_TRUTHY_CONDITION,
+          summary: "An if / unless / ternary predicate's inferred type folds to a constant.",
+          fires_when: [
+            "Predicate's inferred type is `Type::Constant<true | false | nil | ...>`.",
+            "Predicate is NOT a syntactic literal (the literal-only `flow.unreachable-branch` rule covers those)."
+          ],
+          does_not_fire_when: [
+            "Predicate sits inside a `WhileNode` / `UntilNode` / `ForNode` / `BlockNode` ancestor — " \
+            "Rigor's mutation tracking through loop bodies is incomplete enough that an inferred " \
+            "`Constant<bool>` can be a false positive.",
+            "Predicate is a defensive `.nil?` / `.empty?` / `.zero?` / `.any?` / `.none?` / `.all?` / " \
+            "`.respond_to?` call — these typically fire when the user is being more cautious than the " \
+            "RBS strict-on-returns sig admits.",
+            "Predicate folds to a non-Constant type (Union / Nominal / Dynamic / etc.)."
+          ],
+          suppression: "`# rigor:disable always-truthy-condition` on the predicate line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_DEAD_ASSIGNMENT => Entry.new(
+          id: CheckRules::RULE_DEAD_ASSIGNMENT,
+          summary: "Local variable assigned in a method body but never read.",
+          fires_when: [
+            "Plain `LocalVariableWriteNode` (not `+=` / `||=` / multi-assign) inside a `DefNode` body.",
+            "The target name does not appear as a `LocalVariableReadNode` anywhere in the same body, " \
+            "including nested blocks / lambdas.",
+            "The write is not the last statement of the body (Ruby's implicit return)."
+          ],
+          does_not_fire_when: [
+            "Top-level / class-body assignments (their reachability spans the file's introspection / require surface).",
+            "The target name starts with `_` (Ruby convention for intentionally-unused).",
+            "The write is a destructure (`a, b = foo`) or operator-write (`x += 1` / `x ||= 1`).",
+            "The write is the last statement of the method body (assignments return their rvalue)."
+          ],
+          suppression: "`# rigor:disable dead-assignment` on the offending line, or rename the local to `_<name>`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_RETURN_TYPE => Entry.new(
+          id: CheckRules::RULE_RETURN_TYPE,
+          summary: "Method body's last-expression type is incompatible with the declared return type.",
+          fires_when: [
+            "Method has a `def` body the engine can re-type.",
+            "Method's RBS sig declares a non-`untyped` return type.",
+            "Body's inferred return type does not flow into the declared type under gradual acceptance.",
+            "When the RBS sig carries `%a{rigor:v1:return: <refinement>}` (v0.1.2), the refinement " \
+            "carrier — `non-empty-string`, `positive-int`, etc. — replaces the bare RBS class for the " \
+            "comparison, so a body the bare class would accept may still fail the refinement."
+          ],
+          does_not_fire_when: [
+            "Method's declared return is `untyped` / `void`.",
+            "Body's last expression is `Dynamic[T]` (the engine cannot rule out the declared type)."
+          ],
+          suppression: "`# rigor:disable def.return-type-mismatch`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.0"
+        ),
+
+        CheckRules::RULE_VISIBILITY_MISMATCH => Entry.new(
+          id: CheckRules::RULE_VISIBILITY_MISMATCH,
+          summary: "Explicit-receiver call to a method declared `private` in source.",
+          fires_when: [
+            "Call is `receiver.method(...)` with explicit non-self receiver.",
+            "Receiver type resolves to `Type::Nominal[X]`.",
+            "X is a user-defined class whose source carries the method under `private`."
+          ],
+          does_not_fire_when: [
+            "Implicit-self call (no receiver) — always allowed for private.",
+            "Receiver is `self` (Ruby 2.7+ permits `self.private_method`).",
+            "Receiver class is RBS-known but not user-source-defined (RBS-side visibility is deferred).",
+            "Method is `:protected` (subclass tracking is deferred)."
+          ],
+          suppression: "`# rigor:disable method-visibility-mismatch`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          since: "0.1.2"
+        ),
+
+        CheckRules::RULE_IVAR_WRITE_MISMATCH => Entry.new(
+          id: CheckRules::RULE_IVAR_WRITE_MISMATCH,
+          summary: "Same instance variable assigned a different concrete class within one class.",
+          fires_when: [
+            "Two or more `@var = ...` writes occur in instance methods of the same class.",
+            "First write's rvalue resolves to a concrete class (Nominal / Singleton / Constant / Tuple → " \
+            "\"Array\" / HashShape → \"Hash\").",
+            "A later write's rvalue resolves to a different concrete class."
+          ],
+          does_not_fire_when: [
+            "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
+            "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
+            "Writes live in different classes that happen to share an ivar name.",
+            "Writes are in `def self.foo` (singleton) bodies — those track separately."
+          ],
+          suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          since: "0.1.2"
+        )
+      }.freeze
+
+      module_function
+
+      # Looks up a rule by canonical id, legacy alias, or family
+      # wildcard. Returns an Array<Entry>:
+      #
+      # - canonical id → 1-element array,
+      # - legacy alias → 1-element array (resolved to canonical),
+      # - family token (`call`) → every entry under that family,
+      # - unknown token → empty array.
+      def resolve(token)
+        token = token.to_s
+        return [ENTRIES.fetch(token)] if ENTRIES.key?(token)
+
+        if CheckRules::LEGACY_RULE_ALIASES.key?(token)
+          canonical = CheckRules::LEGACY_RULE_ALIASES.fetch(token)
+          return [ENTRIES.fetch(canonical)]
+        end
+
+        if CheckRules::RULE_FAMILIES.include?(token)
+          return ENTRIES.values.select { |entry| entry.id.start_with?("#{token}.") }.sort_by(&:id)
+        end
+
+        []
+      end
+
+      def all
+        ENTRIES.values.sort_by(&:id)
+      end
+    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
@@ -140,7 +157,8 @@ module Rigor
         Plugin::TrustPolicy.new(
           trusted_gems: trusted_gems,
           allowed_read_roots: roots,
-          network_policy: @configuration.plugins_io_network
+          network_policy: @configuration.plugins_io_network,
+          allowed_url_hosts: @configuration.plugins_io_allowed_url_hosts
         )
       end
 
@@ -206,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

data/lib/rigor/cache/descriptor.rb

@@ -24,8 +24,10 @@ module Rigor
     class Descriptor # rubocop:disable Metrics/ClassLength
       # Bumped on incompatible schema changes. The storage layer
       # mixes this into the cache key, so a bump implicitly
-      # invalidates every cached value.
-      SCHEMA_VERSION = 1
+      # invalidates every cached value. v2 added the
+      # `dependencies` slot for ADR-10 per-gem-version cache slice
+      # invalidation.
+      SCHEMA_VERSION = 2
 
       # Per-slot entry value objects. Constructors validate enums /
       # required fields and freeze the resulting struct so no caller
@@ -134,6 +136,54 @@ module Rigor
         end
       end
 
+      # Per-(gem, version, mode) row carrying the cache slice
+      # boundary for ADR-10 dependency-source inference. A
+      # `bundle update` that bumps a listed gem's pinned version
+      # produces a different `gem_version` here and therefore a
+      # fresh cache key — invalidating exactly that gem's slice
+      # without disturbing other gems' slices or the project's
+      # own cache.
+      #
+      # `mode` mirrors the
+      # [Configuration::Dependencies::VALID_MODES](../configuration/dependencies.rb)
+      # enum (`:disabled` / `:when_missing` / `:full`); a mode
+      # change for the same gem also forces invalidation because
+      # the inferred shapes depend on whether RBS overrides the
+      # walk.
+      class DependencyEntry
+        VALID_MODES = %i[disabled when_missing full].freeze
+
+        attr_reader :gem_name, :gem_version, :mode
+
+        def initialize(gem_name:, gem_version:, mode:)
+          unless VALID_MODES.include?(mode)
+            raise ArgumentError,
+                  "DependencyEntry mode must be one of #{VALID_MODES.inspect}, got #{mode.inspect}"
+          end
+
+          @gem_name = gem_name.to_s.dup.freeze
+          @gem_version = gem_version.to_s.dup.freeze
+          @mode = mode
+          freeze
+        end
+
+        def to_h
+          { "gem_name" => gem_name, "gem_version" => gem_version, "mode" => mode.to_s }
+        end
+
+        def ==(other)
+          other.is_a?(DependencyEntry) &&
+            other.gem_name == gem_name &&
+            other.gem_version == gem_version &&
+            other.mode == mode
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, gem_name, gem_version, mode].hash
+        end
+      end
+
       # Raised when {.compose} encounters incompatible entries
       # under the same key (file digest mismatch, gem-locked
       # disagreement, …). Callers handle the exception by
@@ -141,13 +191,14 @@ module Rigor
       # contribution silently.
       class Conflict < StandardError; end
 
-      attr_reader :files, :gems, :plugins, :configs
+      attr_reader :files, :gems, :plugins, :configs, :dependencies
 
-      def initialize(files: [], gems: [], plugins: [], configs: [])
+      def initialize(files: [], gems: [], plugins: [], configs: [], dependencies: [])
         @files = files.dup.freeze
         @gems = gems.dup.freeze
         @plugins = plugins.dup.freeze
         @configs = configs.dup.freeze
+        @dependencies = dependencies.dup.freeze
         freeze
       end
 
@@ -170,7 +221,8 @@ module Rigor
         gems = compose_by_key(descriptors.flat_map(&:gems), :name)
         plugins = compose_by_key(descriptors.flat_map(&:plugins), :id)
         configs = compose_by_key(descriptors.flat_map(&:configs), :key)
-        new(files: files, gems: gems, plugins: plugins, configs: configs)
+        dependencies = compose_by_key(descriptors.flat_map(&:dependencies), :gem_name)
+        new(files: files, gems: gems, plugins: plugins, configs: configs, dependencies: dependencies)
       end
 
       # @param producer_id [String]
@@ -196,6 +248,7 @@ module Rigor
       def to_canonical_hash
         {
           "configs" => sort_entries(configs, "key").map(&:to_h),
+          "dependencies" => sort_entries(dependencies, "gem_name").map(&:to_h),
           "files" => sort_entries(files, "path").map(&:to_h),
           "gems" => sort_entries(gems, "name").map(&:to_h),
           "plugins" => sort_entries(plugins, "id").map(&:to_h)