rigortype 0.0.7 → 0.0.9

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

data/lib/rigor/cache/rbs_class_ancestor_table.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "rbs_descriptor"
+
+module Rigor
+  module Cache
+    # Cache producer that materialises the RBS-declared ancestor
+    # chain of every loaded class / module into a Marshal-clean
+    # `Hash<String, Array<String>>`. Ancestor names are top-level-
+    # stripped (e.g. `"Integer"` not `"::Integer"`) to match
+    # `Environment::RbsHierarchy#normalize_name`.
+    #
+    # The hierarchy is the substrate behind every `class_ordering`
+    # query, which is itself a hot path on the dispatcher (overload
+    # selection, narrowing, etc.). Building one ancestor chain
+    # requires a full `RBS::DefinitionBuilder#build_instance` over
+    # that class — a cold-cost dominated by RBS's own resolution
+    # work. Caching the table lets a warm process skip the build
+    # entirely and pay only a `Marshal.load` of the resulting
+    # hash.
+    #
+    # Cache descriptor shape is shared with every other cache
+    # producer that depends on the RBS environment — see
+    # {RbsDescriptor.build}.
+    class RbsClassAncestorTable
+      PRODUCER_ID = "rbs.class_ancestor_table"
+
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @param store [Rigor::Cache::Store]
+      # @return [Hash{String => Array<String>}]
+      def self.fetch(loader:, store:)
+        descriptor = RbsDescriptor.build(loader)
+        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
+          compute(loader)
+        end
+      end
+
+      def self.compute(loader)
+        table = {}
+        loader.each_known_class_name do |name|
+          key = name.delete_prefix("::")
+          ancestors = ancestors_for(loader, key)
+          table[key] = ancestors unless ancestors.nil?
+        end
+        table
+      end
+
+      def self.ancestors_for(loader, class_name)
+        definition = loader.instance_definition(class_name)
+        return nil if definition.nil?
+
+        definition.ancestors.ancestors
+                  .map { |ancestor| ancestor.name.to_s.delete_prefix("::") }
+                  .uniq
+                  .freeze
+      rescue StandardError
+        nil
+      end
+
+      private_class_method :compute, :ancestors_for
+    end
+  end
+end

data/lib/rigor/cache/rbs_class_type_param_names.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "rbs_descriptor"
+
+module Rigor
+  module Cache
+    # Cache producer that materialises every loaded class's
+    # RBS-declared type-parameter names as a Marshal-clean
+    # `Hash<String, Array<Symbol>>` keyed by top-level-stripped
+    # class name (e.g. `"Array"` → `[:Elem]`, `"Hash"` →
+    # `[:K, :V]`). Producer id `"rbs.class_type_param_names"`.
+    #
+    # The dispatcher reads type-parameter names every time it
+    # builds a substitution map from a receiver's `type_args`
+    # into a method's return type — it is one of the hottest
+    # reflection lookups during analysis. Building one entry
+    # requires a full `RBS::DefinitionBuilder#build_instance`
+    # over that class, the same expensive operation
+    # {RbsClassAncestorTable} caches; the two producers share
+    # the build cost when populated together.
+    #
+    # Cache descriptor shape is shared with every other cache
+    # producer that depends on the RBS environment — see
+    # {RbsDescriptor.build}.
+    class RbsClassTypeParamNames
+      PRODUCER_ID = "rbs.class_type_param_names"
+
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @param store [Rigor::Cache::Store]
+      # @return [Hash{String => Array<Symbol>}]
+      def self.fetch(loader:, store:)
+        descriptor = RbsDescriptor.build(loader)
+        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
+          compute(loader)
+        end
+      end
+
+      def self.compute(loader)
+        table = {}
+        loader.each_known_class_name do |name|
+          key = name.delete_prefix("::")
+          params = type_params_for(loader, key)
+          table[key] = params unless params.nil?
+        end
+        table
+      end
+
+      def self.type_params_for(loader, class_name)
+        definition = loader.instance_definition(class_name)
+        return nil if definition.nil?
+
+        definition.type_params.dup.freeze
+      rescue StandardError
+        nil
+      end
+
+      private_class_method :compute, :type_params_for
+    end
+  end
+end

data/lib/rigor/cache/rbs_constant_table.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "rbs_descriptor"
+
+module Rigor
+  module Cache
+    # Cache producer that materialises every RBS-declared constant
+    # to its translated `Rigor::Type` form and stores the result as
+    # a `Hash<String, Rigor::Type>` keyed by canonical constant name.
+    # This is the v0.0.8 first cached producer per ADR-6 § 7; it
+    # caches a post-translation artefact so the cache value is
+    # `Marshal`-clean (RBS-native objects carry `RBS::Location`,
+    # which lacks `_dump_data`).
+    #
+    # Cache descriptor shape is shared with every other cache
+    # producer that depends on the RBS environment — see
+    # {RbsDescriptor.build} for the slot definitions.
+    class RbsConstantTable
+      PRODUCER_ID = "rbs.constant_type_table"
+
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @param store [Rigor::Cache::Store]
+      # @return [Hash{String => Rigor::Type}]
+      def self.fetch(loader:, store:)
+        descriptor = RbsDescriptor.build(loader)
+        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
+          compute(loader)
+        end
+      end
+
+      def self.compute(loader)
+        table = {}
+        loader.each_constant_decl do |name, entry|
+          translated = Inference::RbsTypeTranslator.translate(entry.decl.type)
+          table[name] = translated unless translated.is_a?(Type::Bot)
+        rescue StandardError
+          # Skip entries whose RBS type fails to translate; the cache
+          # stays robust to a broken signature rather than corrupting
+          # the whole table.
+        end
+        table
+      end
+
+      private_class_method :compute
+    end
+  end
+end

data/lib/rigor/cache/rbs_descriptor.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Rigor
+  module Cache
+    # Shared descriptor builder for cache producers that depend on the
+    # RBS environment (constant table, known-class set, future
+    # Marshal-clean reflection artefacts). Every consumer attaches the
+    # same three slots, so factoring the construction here keeps the
+    # producers small and ensures invalidation behaves identically
+    # across them.
+    module RbsDescriptor
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @return [Rigor::Cache::Descriptor]
+      def self.build(loader)
+        Descriptor.new(
+          gems: [rbs_gem_entry],
+          files: file_entries(loader),
+          configs: [libraries_entry(loader)]
+        )
+      end
+
+      def self.rbs_gem_entry
+        Descriptor::GemEntry.new(name: "rbs", requirement: ">= 0", locked: ::RBS::VERSION.to_s)
+      end
+
+      def self.file_entries(loader)
+        loader.signature_paths.flat_map do |root|
+          next [] unless root.directory?
+
+          Dir.glob(root.join("**", "*.rbs")).map do |path|
+            Descriptor::FileEntry.new(
+              path: path,
+              comparator: :digest,
+              value: Digest::SHA256.file(path).hexdigest
+            )
+          end
+        end
+      end
+
+      def self.libraries_entry(loader)
+        sorted = loader.libraries.map(&:to_s).sort
+        Descriptor::ConfigEntry.new(
+          key: "rbs.libraries",
+          value_hash: Digest::SHA256.hexdigest(sorted.join("\n"))
+        )
+      end
+
+      private_class_method :rbs_gem_entry, :file_entries, :libraries_entry
+    end
+  end
+end

data/lib/rigor/cache/rbs_environment.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "rbs_descriptor"
+require_relative "rbs_environment_marshal_patch"
+
+module Rigor
+  module Cache
+    # Cache producer that materialises the entire
+    # `RBS::Environment` (the loader's `build_env` result) and
+    # round-trips it through `Marshal` against the patched
+    # `RBS::Location` (see {RbsEnvironmentMarshalPatch}).
+    #
+    # Cold runs pay the full
+    # `RBS::EnvironmentLoader#load + RBS::Environment.from_loader
+    # + resolve_type_names` cost once; warm runs (and a separate
+    # loader sharing the same Store) load the marshalled blob and
+    # skip the parse / resolve stages entirely. The
+    # `RbsConstantTable`, `RbsKnownClassNames`,
+    # `RbsClassAncestorTable`, and `RbsClassTypeParamNames`
+    # caches still live alongside this producer — their cached
+    # values are reached without re-touching env, but when an
+    # uncached lookup happens (`instance_method`,
+    # `singleton_method`, …) the env produced here is what
+    # answers it.
+    #
+    # Cache descriptor shape is shared with every other cache
+    # producer that depends on the RBS environment — see
+    # {RbsDescriptor.build}.
+    class RbsEnvironment
+      PRODUCER_ID = "rbs.environment"
+
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @param store [Rigor::Cache::Store]
+      # @return [::RBS::Environment]
+      def self.fetch(loader:, store:)
+        descriptor = RbsDescriptor.build(loader)
+        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
+          compute(loader)
+        end
+      end
+
+      def self.compute(loader)
+        Rigor::Environment::RbsLoader.build_env_for(
+          libraries: loader.libraries,
+          signature_paths: loader.signature_paths
+        )
+      end
+
+      private_class_method :compute
+    end
+  end
+end

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+# Adds `_dump` / `_load` to {RBS::Location} so an
+# `RBS::Environment` (and its transitive AST nodes, all of
+# which carry Locations) round-trips through `Marshal`. The
+# rbs gem's C-extension `RBS::Location` ships without the
+# Marshal hooks; until rbs grows them upstream this patch is
+# the minimal monkey-patch the v0.0.9 RBS::Environment cache
+# relies on.
+#
+# Patch policy (purely additive):
+#
+# - `_dump` returns an empty string. The cached env loses
+#   per-node source-position info, but Rigor does not consult
+#   `RBS::Location` from any analysis code path (every
+#   diagnostic uses Prism's own location), so the loss is
+#   inert in practice.
+# - `_load` reconstructs a sentinel Location backed by an
+#   empty `<cached>` Buffer. Code paths that DID consult
+#   Location after a cache hit see a benign zero-range value
+#   rather than crashing.
+#
+# Idempotent: the guard checks `method_defined?(:_dump)` so
+# requiring this file twice (or against an upstream rbs that
+# adds Marshal hooks itself) is a no-op.
+module RBS
+  class Location
+    unless method_defined?(:_dump)
+      def _dump(_)
+        ""
+      end
+
+      def self._load(_)
+        new(buffer: ::RBS::Buffer.new(name: "<cached>", content: ""), start_pos: 0, end_pos: 0)
+      end
+    end
+  end
+end

data/lib/rigor/cache/rbs_known_class_names.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "rbs_descriptor"
+
+module Rigor
+  module Cache
+    # Cache producer that materialises the set of every RBS-declared
+    # class / module / alias name (top-level prefixed, e.g.
+    # `"::Math"`) currently loaded into the environment. Marshal-
+    # clean — the cache value is a `Set<String>`.
+    #
+    # The set lets `RbsLoader#class_known?` answer point lookups in
+    # O(1) without re-parsing the name on each call, and lets a warm
+    # process skip the env walk entirely (the env still has to be
+    # built to enumerate decls on cold misses; subsequent processes
+    # sharing the Store load the set straight from disk).
+    #
+    # Cache descriptor shape is shared with {RbsConstantTable} via
+    # {RbsDescriptor.build}; a single signature change or rbs gem
+    # bump invalidates both producers in lockstep.
+    class RbsKnownClassNames
+      PRODUCER_ID = "rbs.known_class_names"
+
+      # @param loader [Rigor::Environment::RbsLoader]
+      # @param store [Rigor::Cache::Store]
+      # @return [Set<String>]
+      def self.fetch(loader:, store:)
+        descriptor = RbsDescriptor.build(loader)
+        store.fetch_or_compute(producer_id: PRODUCER_ID, params: {}, descriptor: descriptor) do
+          compute(loader)
+        end
+      end
+
+      def self.compute(loader)
+        names = Set.new
+        loader.each_known_class_name { |name| names << name }
+        names
+      end
+
+      private_class_method :compute
+    end
+  end
+end