rigortype 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0af88abcc3dd912fd5c9d22440dc456b0418d6bd0de2cae58167f8538880c1a0
-  data.tar.gz: 2ef580ca7c24007313fd4b30e4e2f0dc1cd59e68ccdc4113f3fe060694880782
+  metadata.gz: 38aa66f97f5bed742a36c156ceee7f13d3181597b74c32329b693b3c219852b3
+  data.tar.gz: 69af0ccbf42c2b890b78a558d574b49293ff6b4880875568137098624e66d3f8
 SHA512:
-  metadata.gz: 46bd06614cdbf530ada69f28fd5be8620b5e54d834c8af69663fdf0949f0592a7123e0f564d924046dbc9b3d9d04ffec96af593825c6b84cafebf1a6b1a60431
-  data.tar.gz: df1f86d712a8a081356917989a4c98c775180eb805d54300b671d652a2d87eee86a7624d9b8812f2e7a4b3b26364a668948aa8aa06481c53295908428ab0d4ae
+  metadata.gz: 8a9e0ee0461e2f0b2779981fa95758e0b7b5bd02668254dc1cb2d82002565b383d866534edff6e75c53aa0a9ae2fdb59832a35788ccfda3cb4558982bed61b15
+  data.tar.gz: 9699b63098d16e1959177684a849923384196f0dac55a532a3a0ecdff77d45c76230c3b72a273f59ec237059127007d7bb1ae01be9c9cf8b9613a02033b89bb5

data/lib/rigor/analysis/check_rules.rb

@@ -2,6 +2,7 @@
 
 require "prism"
 
+require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../type"
 require_relative "diagnostic"
@@ -172,9 +173,7 @@ module Rigor
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
           return nil if scope.discovered_method?(class_name, call_node.name, kind)
 
-          loader = scope.environment.rbs_loader
-          return nil if loader.nil?
-          return nil unless loader.class_known?(class_name)
+          return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
 
           # When the loader cannot build a class definition for a
           # name it nominally knows (constant-decl aliases such
@@ -182,9 +181,9 @@ module Rigor
           # malformed signatures), we cannot enumerate methods
           # so we MUST NOT emit a false positive. Skip the rule
           # in that case.
-          return nil unless definition_available?(loader, receiver_type, class_name)
+          return nil unless definition_available?(receiver_type, class_name, scope)
 
-          method_def = lookup_method(loader, receiver_type, class_name, call_node.name)
+          method_def = lookup_method(receiver_type, class_name, call_node.name, scope)
           return nil if method_def
 
           build_undefined_method_diagnostic(path, call_node, receiver_type)
@@ -219,27 +218,29 @@ module Rigor
           nil
         end
 
-        def definition_available?(loader, receiver_type, class_name)
+        def definition_available?(receiver_type, class_name, scope)
           if receiver_type.is_a?(Type::Singleton)
-            !loader.singleton_definition(class_name).nil?
+            !Rigor::Reflection.singleton_definition(class_name, scope: scope).nil?
           else
-            !loader.instance_definition(class_name).nil?
+            !Rigor::Reflection.instance_definition(class_name, scope: scope).nil?
           end
-        rescue StandardError
-          false
         end
 
-        def lookup_method(loader, receiver_type, class_name, method_name)
+        def lookup_method(receiver_type, class_name, method_name, scope)
           if receiver_type.is_a?(Type::Singleton)
-            loader.singleton_method(class_name: class_name, method_name: method_name)
+            Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope)
           else
-            loader.instance_method(class_name: class_name, method_name: method_name)
+            Rigor::Reflection.instance_method_definition(class_name, method_name, scope: scope)
           end
         rescue StandardError
-          # The loader is best-effort and may raise on malformed
-          # RBS. Treat any failure as "method exists" so we do
-          # NOT emit a false positive when our knowledge of the
-          # receiver class is structurally incomplete.
+          # The Reflection facade catches loader exceptions and
+          # returns nil. The wrapper here treats failures as
+          # "method exists" so we do NOT emit a false positive
+          # when our knowledge of the receiver class is
+          # structurally incomplete (Reflection's own rescue
+          # already returns nil; this catch is a defensive
+          # double-net for any future call shape that might
+          # raise).
           true
         end
 
@@ -271,12 +272,10 @@ module Rigor
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
           return nil if scope.discovered_method?(class_name, call_node.name, kind)
 
-          loader = scope.environment.rbs_loader
-          return nil if loader.nil?
-          return nil unless loader.class_known?(class_name)
-          return nil unless definition_available?(loader, receiver_type, class_name)
+          return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+          return nil unless definition_available?(receiver_type, class_name, scope)
 
-          method_def = lookup_method(loader, receiver_type, class_name, call_node.name)
+          method_def = lookup_method(receiver_type, class_name, call_node.name, scope)
           return nil if method_def.nil? || method_def == true
 
           arity_envelope = compute_arity_envelope(method_def)
@@ -383,12 +382,14 @@ module Rigor
           receiver_type = scope.type_of(call_node.receiver)
           return nil unless receiver_type.is_a?(Type::Union)
 
-          loader = scope.environment.rbs_loader
-          return nil if loader.nil?
+          # The rule only fires when the analyzer has access to
+          # an RBS loader; without it, the per-member method-
+          # presence checks below cannot rule out a sound call.
+          return nil unless Rigor::Reflection.rbs_class_known?("NilClass", scope: scope)
 
           return nil unless union_contains_nil?(receiver_type)
-          return nil unless union_method_present_on_non_nil?(receiver_type, call_node.name, loader, scope)
-          return nil if nil_class_has_method?(call_node.name, loader)
+          return nil unless union_method_present_on_non_nil?(receiver_type, call_node.name, scope)
+          return nil if nil_class_has_method?(call_node.name, scope)
 
           build_nil_receiver_diagnostic(path, call_node)
         end
@@ -409,27 +410,25 @@ module Rigor
         # that are unsound on the non-nil branch — that is the
         # `undefined_method_diagnostic` rule's job, and we want
         # exactly one diagnostic per offending call site.
-        def union_method_present_on_non_nil?(union, method_name, loader, scope)
+        def union_method_present_on_non_nil?(union, method_name, scope)
           non_nil_members = union.members.reject { |m| nil_member?(m) }
           return false if non_nil_members.empty?
 
-          non_nil_members.all? { |m| method_present_anywhere?(m, method_name, loader, scope) }
+          non_nil_members.all? { |m| method_present_anywhere?(m, method_name, scope) }
         end
 
-        def method_present_anywhere?(member, method_name, loader, scope)
+        def method_present_anywhere?(member, method_name, scope)
           class_name = concrete_class_name(member)
           return true if class_name.nil? # Dynamic / Top / Bot — be permissive.
           return true if scope.discovered_method?(class_name, method_name, :instance)
-          return true unless loader.class_known?(class_name)
-          return true unless definition_available?(loader, member, class_name)
+          return true unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+          return true unless definition_available?(member, class_name, scope)
 
-          !lookup_method(loader, member, class_name, method_name).nil?
+          !lookup_method(member, class_name, method_name, scope).nil?
         end
 
-        def nil_class_has_method?(method_name, loader)
-          return false unless loader.class_known?("NilClass")
-
-          definition = loader.instance_definition("NilClass")
+        def nil_class_has_method?(method_name, scope)
+          definition = Rigor::Reflection.instance_definition("NilClass", scope: scope)
           return false if definition.nil?
 
           !definition.methods[method_name.to_sym].nil?
@@ -684,12 +683,10 @@ module Rigor
           # supplies BOTH a `def` and an RBS sig, the sig is
           # the authoritative parameter contract and we
           # should validate calls against it.
-          loader = scope.environment.rbs_loader
-          return nil if loader.nil?
-          return nil unless loader.class_known?(class_name)
-          return nil unless definition_available?(loader, receiver_type, class_name)
+          return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+          return nil unless definition_available?(receiver_type, class_name, scope)
 
-          method_def = lookup_method(loader, receiver_type, class_name, call_node.name)
+          method_def = lookup_method(receiver_type, class_name, call_node.name, scope)
           return nil if method_def.nil? || method_def == true
           return nil unless method_def.method_types.size == 1
 

data/lib/rigor/analysis/diagnostic.rb

@@ -3,7 +3,12 @@
 module Rigor
   module Analysis
     class Diagnostic
-      attr_reader :path, :line, :column, :message, :severity, :rule
+      # The default source family. Matches the existing analyzer-
+      # internal rule families; serialised as `"builtin"` and is the
+      # baseline against which non-default families are recognised.
+      DEFAULT_SOURCE_FAMILY = :builtin
+
+      attr_reader :path, :line, :column, :message, :severity, :rule, :source_family
 
       # `rule:` is the stable identifier (a kebab-case string)
       # of the diagnostic's source rule. It is used by the
@@ -12,8 +17,16 @@ module Rigor
       # category. Diagnostics not produced by `CheckRules`
       # (parse errors, path errors, internal analyzer errors)
       # may leave `rule` as nil and stay unsuppressible.
+      #
+      # `source_family:` names the producer of the rule. The default
+      # `:builtin` covers analyzer-internal rules; future families
+      # like `:rbs_extended`, `:generated`, or `"plugin.<id>"` (per
+      # ADR-2 § "Plugin Diagnostic Provenance") let consumers
+      # distinguish where a diagnostic originated without committing
+      # to the plugin API itself.
       # rubocop:disable Metrics/ParameterLists
-      def initialize(path:, line:, column:, message:, severity: :error, rule: nil)
+      def initialize(path:, line:, column:, message:, severity: :error, rule: nil,
+                     source_family: DEFAULT_SOURCE_FAMILY)
         # rubocop:enable Metrics/ParameterLists
         @path = path
         @line = line
@@ -21,12 +34,24 @@ module Rigor
         @message = message
         @severity = severity
         @rule = rule
+        @source_family = source_family
       end
 
       def error?
         severity == :error
       end
 
+      # The fully-qualified rule identifier — `<source_family>.<rule>`
+      # when the source is non-default, or just `<rule>` for the
+      # `:builtin` family. Returns nil when `rule` itself is nil
+      # (e.g. parse errors and internal-analyzer errors).
+      def qualified_rule
+        return nil if rule.nil?
+        return rule if source_family == DEFAULT_SOURCE_FAMILY
+
+        "#{source_family}.#{rule}"
+      end
+
       def to_h
         {
           "path" => path,
@@ -34,6 +59,7 @@ module Rigor
           "column" => column,
           "severity" => severity.to_s,
           "rule" => rule,
+          "source_family" => source_family.to_s,
           "message" => message
         }
       end

data/lib/rigor/builtins/imported_refinements.rb

@@ -78,6 +78,41 @@ module Rigor
           return nil unless args.size == 2
 
           Type::Combinator.non_empty_hash(args[0], args[1])
+        },
+        # v0.0.7 — `key_of[T]` and `value_of[T]` type functions.
+        # Each takes a single type argument and projects the
+        # known-keys (resp. known-values) union out of `T`. See
+        # `Type::Combinator.key_of` for the per-shape projection
+        # rules. Use `lower_snake` per the
+        # imported-built-in-types.md type-function naming rule.
+        "key_of" => lambda { |args|
+          return nil unless args.size == 1
+
+          Type::Combinator.key_of(args.first)
+        },
+        "value_of" => lambda { |args|
+          return nil unless args.size == 1
+
+          Type::Combinator.value_of(args.first)
+        },
+        # `int_mask[1, 2, 4]` — every integer representable by
+        # a bitwise OR over the listed flags. Each arg must be a
+        # `Constant<Integer>`; the parser wraps integer literals
+        # for this purpose. Builder declines on any non-integer
+        # arg.
+        "int_mask" => lambda { |args|
+          flags = args.map { |arg| arg.is_a?(Type::Constant) && arg.value.is_a?(Integer) ? arg.value : nil }
+          return nil if flags.any?(&:nil?)
+
+          Type::Combinator.int_mask(flags)
+        },
+        # `int_mask_of[T]` — derives the closure from a finite
+        # integer literal type (single Constant<Integer> or a
+        # Union of them).
+        "int_mask_of" => lambda { |args|
+          return nil unless args.size == 1
+
+          Type::Combinator.int_mask_of(args.first)
         }
       }.freeze
       private_constant :PARAMETERISED_TYPE_BUILDERS
@@ -145,7 +180,7 @@ module Rigor
       # soft (returns `nil` from `parse`) on any deviation so the
       # `RBS::Extended` directive site can fall back to the
       # RBS-declared type rather than crash on a typo.
-      class Parser
+      class Parser # rubocop:disable Metrics/ClassLength
         def initialize(input)
           @scanner = StringScanner.new(input.strip)
         end
@@ -153,6 +188,12 @@ module Rigor
         def parse
           type = parse_type
           return nil if type.nil?
+
+          # v0.0.7 — trailing `[K]` indexed-access projects
+          # into the parsed type. Multiple `[K]` segments
+          # chain (`Tuple[A, B, C][1][0]`).
+          type = parse_indexed_access_chain(type)
+          return nil if type.nil?
           return nil unless @scanner.eos?
 
           type
@@ -160,12 +201,21 @@ module Rigor
 
         private
 
-        SIMPLE_NAME = /[a-z][a-z0-9-]*/
+        # Refinement names use kebab-case (`non-empty-string`),
+        # type-function names use lower_snake (`key_of`,
+        # `value_of`, `int_mask`). The regex accepts both shapes;
+        # the registry lookup decides which family the name
+        # belongs to.
+        SIMPLE_NAME = /[a-z][a-z0-9_-]*/
         CLASS_NAME = /[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*/
         SIGNED_INT = /-?\d+/
         private_constant :SIMPLE_NAME, :CLASS_NAME, :SIGNED_INT
 
         def parse_type
+          if (class_name = @scanner.scan(CLASS_NAME))
+            return parse_class_arg_tail(class_name)
+          end
+
           name = @scanner.scan(SIMPLE_NAME)
           return nil if name.nil?
 
@@ -176,6 +226,25 @@ module Rigor
           end
         end
 
+        # `T[K]` — keep applying `[K]` indexes until no more
+        # opening brackets are present. Each index consumes one
+        # type argument; multi-arg `[K1, K2]` fails (the spec
+        # specifies a single key).
+        def parse_indexed_access_chain(type)
+          loop do
+            skip_ws
+            break unless @scanner.peek(1) == "["
+
+            @scanner.getch
+            args = parse_type_arg_list
+            return nil if args.nil? || args.size != 1
+            return nil unless @scanner.getch == "]"
+
+            type = Type::Combinator.indexed_access(type, args.first)
+          end
+          type
+        end
+
         def parse_parametric_type_args(name)
           builder = PARAMETERISED_TYPE_BUILDERS[name]
           return nil if builder.nil?
@@ -227,12 +296,33 @@ module Rigor
         def parse_type_arg
           skip_ws
           if (class_name = @scanner.scan(CLASS_NAME))
-            Type::Combinator.nominal_of(class_name)
+            parse_class_arg_tail(class_name)
+          elsif (literal = @scanner.scan(SIGNED_INT))
+            # Integer-literal arg, used by `int_mask[1, 2, 4]`.
+            # Wrapped as `Constant<Integer>` so type-arg builders
+            # see a uniform `Array<Type::t>`.
+            Type::Combinator.constant_of(Integer(literal))
           else
             parse_type
           end
         end
 
+        # Class-name-headed type argument with optional `[T_1,
+        # …]` type-args tail. Used so `key_of[Hash[Symbol,
+        # Integer]]` parses as the projection of a parameterised
+        # nominal carrier rather than rejecting the inner
+        # brackets.
+        def parse_class_arg_tail(class_name)
+          return Type::Combinator.nominal_of(class_name) unless @scanner.peek(1) == "["
+
+          @scanner.getch # consume '['
+          args = parse_type_arg_list
+          return nil if args.nil?
+          return nil unless @scanner.getch == "]"
+
+          Type::Combinator.nominal_of(class_name, type_args: args)
+        end
+
         def parse_int_bound
           skip_ws
           literal = @scanner.scan(SIGNED_INT)

data/lib/rigor/cache/descriptor.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Rigor
+  module Cache
+    # Cache invalidation descriptor — the typed-slot schema fixed by
+    # [`docs/design/20260505-cache-slice-taxonomy.md`](../../../docs/design/20260505-cache-slice-taxonomy.md).
+    # Pure value object: no I/O, no global state, fully immutable
+    # after construction. The storage layer
+    # ([`Rigor::Cache::Store`](store.rb), v0.0.8 slice 2) consumes
+    # descriptors but does not extend them.
+    #
+    # The descriptor has four slots (`files`, `gems`, `plugins`,
+    # `configs`); every slot is an array of typed entries; an empty
+    # array means "no dependency in this slot". Composition unions
+    # by key per slot; conflicts on the comparison fields raise
+    # {Conflict}.
+    #
+    # See ADR-2 § "Registration, Configuration, and Caching" for
+    # the design rationale and ADR-6 for the storage backend
+    # decisions that consume this schema.
+    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
+
+      # Per-slot entry value objects. Constructors validate enums /
+      # required fields and freeze the resulting struct so no caller
+      # can mutate after the entry is in a Descriptor.
+
+      class FileEntry
+        VALID_COMPARATORS = %i[digest mtime exists].freeze
+
+        attr_reader :path, :comparator, :value
+
+        def initialize(path:, comparator:, value:)
+          unless VALID_COMPARATORS.include?(comparator)
+            raise ArgumentError,
+                  "FileEntry comparator must be one of #{VALID_COMPARATORS.inspect}, got #{comparator.inspect}"
+          end
+
+          @path = path.to_s.dup.freeze
+          @comparator = comparator
+          @value = value.to_s.dup.freeze
+          freeze
+        end
+
+        def to_h
+          { "path" => path, "comparator" => comparator.to_s, "value" => value }
+        end
+
+        def ==(other)
+          other.is_a?(FileEntry) && other.path == path && other.comparator == comparator && other.value == value
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, path, comparator, value].hash
+        end
+      end
+
+      class GemEntry
+        attr_reader :name, :requirement, :locked
+
+        def initialize(name:, requirement:, locked: nil)
+          @name = name.to_s.dup.freeze
+          @requirement = requirement.to_s.dup.freeze
+          @locked = locked.nil? ? nil : locked.to_s.dup.freeze
+          freeze
+        end
+
+        def to_h
+          { "name" => name, "requirement" => requirement, "locked" => locked }
+        end
+
+        def ==(other)
+          other.is_a?(GemEntry) && other.name == name && other.requirement == requirement && other.locked == locked
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, name, requirement, locked].hash
+        end
+      end
+
+      class PluginEntry
+        attr_reader :id, :version, :config_hash
+
+        def initialize(id:, version:, config_hash: nil)
+          @id = id.to_s.dup.freeze
+          @version = version.to_s.dup.freeze
+          @config_hash = config_hash.nil? ? nil : config_hash.to_s.dup.freeze
+          freeze
+        end
+
+        def to_h
+          { "id" => id, "version" => version, "config_hash" => config_hash }
+        end
+
+        def ==(other)
+          other.is_a?(PluginEntry) &&
+            other.id == id && other.version == version && other.config_hash == config_hash
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, id, version, config_hash].hash
+        end
+      end
+
+      class ConfigEntry
+        attr_reader :key, :value_hash
+
+        def initialize(key:, value_hash:)
+          @key = key.to_s.dup.freeze
+          @value_hash = value_hash.to_s.dup.freeze
+          freeze
+        end
+
+        def to_h
+          { "key" => key, "value_hash" => value_hash }
+        end
+
+        def ==(other)
+          other.is_a?(ConfigEntry) && other.key == key && other.value_hash == value_hash
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, key, value_hash].hash
+        end
+      end
+
+      # Raised when {.compose} encounters incompatible entries
+      # under the same key (file digest mismatch, gem-locked
+      # disagreement, …). Callers handle the exception by
+      # invalidating the cache slice rather than choosing one
+      # contribution silently.
+      class Conflict < StandardError; end
+
+      attr_reader :files, :gems, :plugins, :configs
+
+      def initialize(files: [], gems: [], plugins: [], configs: [])
+        @files = files.dup.freeze
+        @gems = gems.dup.freeze
+        @plugins = plugins.dup.freeze
+        @configs = configs.dup.freeze
+        freeze
+      end
+
+      # File-comparator strictness ordering. `:digest` is strictest
+      # (deterministic across machines); `:mtime` is cheaper but
+      # local; `:exists` is the weakest signal. When two
+      # contributors disagree on the comparator for the same
+      # `path`, the stricter one wins.
+      COMPARATOR_STRICTNESS = { digest: 2, mtime: 1, exists: 0 }.freeze
+      private_constant :COMPARATOR_STRICTNESS
+
+      # Composes any number of descriptors into a single descriptor
+      # whose slots are the union of the inputs' slots. Conflicts
+      # raise {Conflict}; idempotent contributions (same key, same
+      # value) collapse to a single entry.
+      def self.compose(*descriptors)
+        return new if descriptors.empty?
+
+        files = compose_files(descriptors.flat_map(&:files))
+        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)
+      end
+
+      # @param producer_id [String]
+      # @param params [Hash] inputs the producer was called with
+      # @return [String] hex SHA-256 cache key for the value
+      def cache_key_for(producer_id:, params: {})
+        payload = {
+          "schema_version" => SCHEMA_VERSION,
+          "producer_id" => producer_id.to_s,
+          "params" => self.class.canonicalize_value(params),
+          "descriptor" => to_canonical_hash
+        }
+        Digest::SHA256.hexdigest(JSON.generate(payload))
+      end
+
+      # Canonical UTF-8 JSON serialisation. Slots appear in
+      # lexicographic order; entries are sorted by their key field
+      # so two equivalent descriptors produce identical bytes.
+      def to_canonical_bytes
+        JSON.generate(to_canonical_hash).b
+      end
+
+      def to_canonical_hash
+        {
+          "configs" => sort_entries(configs, "key").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)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(Descriptor) &&
+          to_canonical_bytes == other.to_canonical_bytes
+      end
+      alias eql? ==
+
+      def hash
+        to_canonical_bytes.hash
+      end
+
+      class << self
+        # Recursively coerces a Ruby value into a JSON-canonical
+        # structure: hash keys are stringified and sorted; arrays
+        # preserve order; symbols stringify; everything else is
+        # JSON-renderable.
+        def canonicalize_value(value)
+          case value
+          when Hash
+            value.to_a.map { |k, v| [k.to_s, canonicalize_value(v)] }.sort_by(&:first).to_h
+          when Array
+            value.map { |v| canonicalize_value(v) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+      end
+
+      private
+
+      def sort_entries(entries, key)
+        entries.sort_by { |e| e.to_h.fetch(key).to_s }
+      end
+
+      def self.compose_by_key(entries, key)
+        grouped = entries.group_by { |e| e.public_send(key) }
+        grouped.map do |_k, group|
+          unique = group.uniq
+          if unique.size == 1
+            unique.first
+          else
+            raise Conflict,
+                  "cache descriptor conflict on #{key}=#{group.first.public_send(key).inspect}: " \
+                  "got #{unique.size} incompatible entries"
+          end
+        end
+      end
+      private_class_method :compose_by_key
+
+      def self.compose_files(entries)
+        grouped = entries.group_by(&:path)
+        grouped.map do |path, group|
+          merge_file_group(path, group)
+        end
+      end
+      private_class_method :compose_files
+
+      def self.merge_file_group(path, group)
+        strictest_rank = group.map { |e| COMPARATOR_STRICTNESS.fetch(e.comparator) }.max
+        strictest = group.select { |e| COMPARATOR_STRICTNESS.fetch(e.comparator) == strictest_rank }
+        values = strictest.map(&:value).uniq
+        unless values.size == 1
+          raise Conflict,
+                "cache descriptor conflict on file=#{path.inspect}: " \
+                "got #{values.size} disagreeing values under the stricter comparator"
+        end
+
+        strictest.first
+      end
+      private_class_method :merge_file_group
+    end
+  end
+end