rigortype 0.3.9 → 0.4.1

data/lib/rigor/environment/source_rbs_synthesis.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../cache/value_digest"
+
+module Rigor
+  class Environment
+    # ADR-32 WD5 — one plugin's `source_rbs_synthesizer` output for one source file, cached per (file content,
+    # plugin entry, engine source). Two callers read it, and sharing the function is the point:
+    #
+    # - {Environment.collect_virtual_rbs} hands each output to the loader as a `virtual:` buffer;
+    # - {.digest} reduces every loaded synthesizer's output for a file to one comparable value, which the
+    #   incremental session (ADR-89 WD1, issue #1536) keeps on the file's seed bundle and compares across an
+    #   edit.
+    #
+    # Because the digest reads the very function (and the very cache entries) the loader is fed from, "the
+    # digest did not move" means "the loader read the same bytes for this file", not "some model of what
+    # the plugin reads did not move". That is why it is taken from the output rather than from the file's
+    # comment lines: rbs-inline binds an annotation by adjacency, so a plain comment or a blank line can move
+    # one to another declaration, and in an annotated file every `def`, `attr`, constant and mixin gets a
+    # skeleton whether or not it carries an annotation of its own.
+    module SourceRbsSynthesis
+      PRODUCER_ID = "plugin.source_rbs_synthesizer"
+
+      # The digest of a file no loaded synthesizer contributes anything for — the answer for every file of a
+      # project without an annotation, and for every file when no synthesizer is loaded at all. Not a hex
+      # digest, so it can never collide with one.
+      NO_CONTRIBUTION = "none"
+
+      module_function
+
+      # The cache stores the empty string `""` as the "no contribution" sentinel because `Cache::Store`
+      # treats `nil` as a cache miss. Error tuples are stored as the canonical `[:error, message_string]`
+      # Array so the same wrapper short-circuits subsequent runs against unchanged broken input.
+      def output_for(plugin, callable, path, cache_store)
+        return invoke_safely(callable, path) if cache_store.nil?
+        return invoke_safely(callable, path) unless File.file?(path)
+
+        descriptor = cache_descriptor(plugin, path)
+        return invoke_safely(callable, path) if descriptor.nil?
+
+        cache_store.fetch_or_compute(
+          producer_id: PRODUCER_ID,
+          params: {},
+          descriptor: descriptor,
+          generation_cap: generation_cap
+        ) { invoke_safely(callable, path) || "" }
+      end
+
+      # Issue #1536 — every synthesizer's output for `path`, reduced to one value: {NO_CONTRIBUTION} when none
+      # of them contributes anything, a SHA-256 hex digest of each plugin's id and {.contribution} otherwise,
+      # and nil when an output could not be read at all.
+      #
+      # nil means "unknown", and a caller must treat it as moved. Every failure is per file: one plugin that
+      # cannot answer for one file leaves every other file's digest intact.
+      #
+      # @param synthesizers — `Plugin::Registry#source_rbs_synthesizers` pairs.
+      def digest(synthesizers, path, cache_store)
+        sha = Digest::SHA256.new
+        contributed = false
+        synthesizers.each do |plugin, callable|
+          tag, text = contribution(output_for(plugin, callable, path, cache_store))
+          next if tag.nil?
+
+          contributed = true
+          sha << plugin.manifest.id.to_s.b << "\x00" << tag << "\x00" << text.to_s.b << "\x01"
+        end
+        contributed ? sha.hexdigest : NO_CONTRIBUTION
+      rescue StandardError
+        nil
+      end
+
+      # What one output puts into the environment, as a `[tag, text]` pair, or nil for nothing: exactly the
+      # RBS {Environment.interpret_synthesizer_outcome} hands the loader. The ADR-32 WD6 / WD12 notices are left
+      # out. They reach only the run-level `source-rbs-*` rows, which every run regenerates and the per-file
+      # cache never serves, and they quote line numbers, so a line shift in a file carrying a malformed `#:`
+      # would otherwise read as a moved contribution. A failed synthesis contributes nothing to the loader but
+      # is kept as one stable value of its own, so a file flipping between "no annotation" and "broken
+      # annotation" still reads as moved. Any shape the contract does not name is digested whole, by value: the
+      # output is computed on one run and served from its cache entry on the next, and a digest of its
+      # `Marshal.dump` bytes can differ between the two (issue #1574).
+      #
+      # The RBS text itself is digested whole, comments included. RBS reads a `# resolve-type-names: false`
+      # magic comment at the start of a buffer, rbs-inline copies a `.rb` file's first comment line there, and
+      # a string-literal type may span lines that start with `#`, so no line-based stripping is sound (#1549).
+      def contribution(output)
+        return nil if output.nil? || output == ""
+        return ["rbs", output] if output.is_a?(String)
+        return ["raw", Cache::ValueDigest.hexdigest(output)] unless output.is_a?(Array)
+
+        case output[0]
+        when :error then ["error", nil]
+        when :ok then contribution(output[1])
+        else ["raw", Cache::ValueDigest.hexdigest(output)]
+        end
+      end
+
+      # One entry per (plugin, source file), all of them live for as long as the file is in the project — a
+      # generation count says nothing about staleness here, so this producer declares itself out of
+      # `Cache::Store#evict!`'s compaction pass and is bounded only by the size-based LRU pass. A method
+      # rather than a constant: `Cache::Store` is not loaded yet when this file is.
+      def generation_cap
+        Cache::Store::UNBOUNDED_GENERATIONS
+      end
+
+      # The key composes the file's content SHA with the plugin's `PluginEntry` (id + version + config_hash),
+      # so a config change or a content change invalidates the entry, and with the engine's source identity
+      # (issue #1009): a plugin's manifest version does not move when a checkout edits its synthesizer, and
+      # a stale string here also keeps the `rbs.virtual_rbs` env key warm, so the new build's rules would
+      # read the old build's RBS.
+      def cache_descriptor(plugin, path)
+        Cache::Descriptor.new(
+          files: [Cache::Descriptor::FileEntry.new(
+            path: path.to_s,
+            comparator: :digest,
+            value: input_digest(path)
+          )],
+          plugins: [plugin.plugin_entry],
+          configs: Cache::EngineSource.key_config_entries
+        )
+      rescue Cache::EngineSource::Unavailable
+        # An engine that cannot be identified must not be keyed by its inputs alone (issue #1009): nil runs the
+        # synthesizer uncached rather than serving an entry another build may have written.
+        nil
+      end
+
+      def input_digest(path)
+        Digest::SHA256.hexdigest(File.binread(path))
+      rescue ::SystemCallError
+        # Unreadable file → key on the path alone; the synthesizer's File.file?/File.read will see the same
+        # failure and return nil.
+        Digest::SHA256.hexdigest(path.to_s)
+      end
+
+      def invoke_safely(callable, path)
+        callable.call(path.to_s)
+      rescue StandardError
+        # WD6 fail-soft — a synthesizer that raises does NOT crash analysis. Unlike the `[:error, msg]`
+        # return path (which the runner surfaces as `source-rbs-synthesis-failed`), an unhandled raise is
+        # swallowed silently; the unexamined-raise channel is deliberately silent per WD6.
+        nil
+      end
+
+      private_class_method :contribution, :generation_cap, :cache_descriptor, :input_digest, :invoke_safely
+    end
+  end
+end

data/lib/rigor/environment.rb

@@ -15,7 +15,9 @@ require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/installed_gem_set"
 require_relative "environment/rbs_collection_discovery"
+require_relative "environment/source_rbs_synthesis"
 require_relative "plugin/isolation"
+require_relative "cache/engine_source"
 require_relative "environment/rbs_coverage_report"
 require_relative "inference/synthetic_method_index"
 require_relative "inference/project_patched_methods"
@@ -273,8 +275,8 @@ module Rigor
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
                       synthetic_method_index: nil, project_patched_methods: nil,
-                      source_files: [])
-        resolved_paths = signature_paths || default_signature_paths(root)
+                      source_files: [], locked_gems: nil)
+        resolved_paths = project_signature_roots(signature_paths, root: root)
         # O4 MVP — append per-gem `sig/` directories discovered under the target project's bundler install
         # root. Empty array when neither an explicit path nor auto-detection finds a bundle. Order: user
         # `signature_paths:` win first (semantic precedence inside `RbsLoader.build_env_for`); gem-shipped
@@ -284,7 +286,10 @@ module Rigor
         # to the project root), use the locked gem set to filter the discovered `sig/` directories. Stale
         # gems in the bundle install tree (out-of-band installs, version drift after a `bundle update`) are
         # silently dropped so only gems the project actually declares contribute RBS.
-        locked = LockfileResolver.locked_gems(
+        #
+        # #1064 — `locked_gems:` is that same map resolved by the caller. The Ractor pool passes it because
+        # Bundler's parser cannot run in a non-main Ractor; every other caller leaves it nil and resolves here.
+        locked = locked_gems || LockfileResolver.locked_gems(
           lockfile_path: bundler_lockfile,
           project_root: root,
           auto_detect: bundler_auto_detect
@@ -358,13 +363,14 @@ module Rigor
           # the bundle walk and `rbs collection install` all stay authoritative.
           deferred_signature_paths: plugin_sig_paths
         )
-        # Issue #824 / ADR-32 WD13 — one `:info` per inline member the loader stood down against the
-        # project's own `sig/`. Recorded HERE because this is where the reporter is: the run's
-        # `source_rbs_synthesis` stream already carries WD12's "parsed but not honoured" rows, drains out of
-        # pool workers, and is regenerated (never cached) on every run, so the member-level stand-down needs
-        # no plumbing of its own. Costs nothing for a project with no inline RBS: the loader's reader
-        # short-circuits on an empty `virtual_rbs`.
-        record_inline_member_standdowns(loader, source_rbs_synthesis_reporter, root)
+        # Issues #824 / #1075 — the rows ADR-112 WD5's consistency rule reports for members the project's
+        # own `sig/` and an inline source both declare: an error per contradiction (or per refinement that
+        # exceeds its own declared type), an `:info` per inline member dropped undecided. Recorded HERE
+        # because this is where the reporter is: the run's `source_rbs_synthesis` stream already carries
+        # WD12's "parsed but not honoured" rows, drains out of pool workers, and is regenerated (never cached)
+        # on every run, so the member-level outcome needs no plumbing of its own. Costs nothing for a project
+        # with no inline RBS: the loader's reader short-circuits on an empty `virtual_rbs`.
+        record_member_consistency(loader, source_rbs_synthesis_reporter, root)
         # ADR-20 slice 2c + 2e — seed hkt_registry with the bundled builtins. The Environment's
         # `#hkt_registry` getter then LAZILY merges in the RBS env scan on first call so fast paths that
         # don't consult HKT (e.g. `rigor check --cache-stats --no-stats`) don't pay the eager env-build cost
@@ -385,6 +391,13 @@ module Rigor
         )
       end
 
+      # The project-owned `sig/` roots a run reads: the explicit `signature_paths:` when given, else the
+      # auto-detected `<root>/sig` (or none). Public so {Cache::IncrementalSnapshot} digests exactly the
+      # directories the environment loads, including the auto-detected one a `nil` `signature_paths:` hides.
+      def project_signature_roots(signature_paths, root: Dir.pwd)
+        signature_paths || default_signature_paths(root)
+      end
+
       private
 
       def default_signature_paths(root)
@@ -491,8 +504,9 @@ module Rigor
       # empty and this method short-circuits to `[]` without walking the file list.
       #
       # WD5 — when `cache_store` is supplied, each (file, plugin) synthesizer call is memoised through
-      # `Cache::Store`. The cache key composes the file's content SHA with the plugin's `PluginEntry` (id +
-      # version + config_hash) so a config change or content change invalidates the entry automatically.
+      # `Cache::Store` ({SourceRbsSynthesis.output_for}, which owns the key). The incremental session's
+      # per-file digest (issue #1536) reads the same function, so the two can never disagree on what a file
+      # contributed.
       def collect_virtual_rbs(plugin_registry, source_files, cache_store, reporter)
         return [] if plugin_registry.nil?
 
@@ -503,7 +517,7 @@ module Rigor
         result = []
         source_files.each do |path|
           synthesizers.each do |plugin, callable|
-            outcome = synthesizer_output_for(plugin, callable, path, cache_store)
+            outcome = SourceRbsSynthesis.output_for(plugin, callable, path, cache_store)
             outcome = interpret_synthesizer_outcome(outcome, plugin, path, reporter)
             next if outcome.nil? || outcome.empty?
 
@@ -514,23 +528,6 @@ module Rigor
         result
       end
 
-      # ADR-32 WD5 — cache wrapper around a single (plugin, file) invocation. The cache stores the empty
-      # string `""` as the "no contribution" sentinel because `Cache::Store` treats `nil` as a cache miss.
-      # Error tuples are stored as the canonical `[:error, message_string]` Array so the same wrapper
-      # short-circuits subsequent runs against unchanged broken input.
-      def synthesizer_output_for(plugin, callable, path, cache_store)
-        return invoke_synthesizer_safely(callable, path) if cache_store.nil?
-        return invoke_synthesizer_safely(callable, path) unless File.file?(path)
-
-        descriptor = build_synthesizer_cache_descriptor(plugin, path)
-        cache_store.fetch_or_compute(
-          producer_id: SYNTHESIZER_CACHE_PRODUCER_ID,
-          params: {},
-          descriptor: descriptor,
-          generation_cap: synthesizer_generation_cap
-        ) { invoke_synthesizer_safely(callable, path) || "" }
-      end
-
       # ADR-32 WD6 / WD12 — route a synthesizer return value through the per-run reporter. The
       # synthesizer's contract (declared in
       # `plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb`) admits four return shapes:
@@ -565,29 +562,78 @@ module Rigor
         reporter&.record(plugin_id: plugin.manifest.id, path: path, message: message.to_s, kind: kind)
       end
 
-      # ADR-32 WD13 — turn each {Environment::RbsLoader#inline_member_standdowns} record into a WD12
-      # `:not_honoured` entry, so the run's `plugin.rbs-inline.source-rbs-annotation-not-honoured` row names
-      # BOTH sources and which one won. WD12's rule is what makes this necessary rather than optional: an
-      # annotation Rigor parses and does not honour is reported, never swallowed — and a silent per-member
-      # strip is exactly the shape that rule forbids.
+      # ADR-112 WD5 / issue #1075 — turn each reported {MemberConsistency::Record} into a row on the
+      # synthesis stream. A contradiction, or a refinement outside its own declared type, is a `:contradiction`
+      # entry ({Analysis::CheckRules::RULE_CONTRADICTING_SIGNATURE}, an error), positioned at the `.rbs`
+      # member when there is one: that file is real and its line is exact, where the inline member's position
+      # lives in the synthesized RBS buffer, a document nobody has. An undecided pair keeps ADR-32 WD12's
+      # `:not_honoured` row at the annotated `.rb` (line 1, as every entry on that stream is): the inline
+      # signature was parsed and dropped, and WD12 forbids swallowing that. The silent outcomes — equal, or
+      # merged to the more precise side — record nothing.
       #
-      # The row is positioned at the annotated `.rb` (line 1, as every entry on this stream is): the member's
-      # own position lives in the synthesized RBS buffer, which describes a document nobody has, and the
-      # ADR-54 environment cache drops positions anyway, so a line read off it would differ warm and cold.
-      def record_inline_member_standdowns(loader, reporter, root)
+      # The records are derived with a {MemberConsistency::RbsProof}, so a contradiction is proven from the
+      # RBS hierarchy of core and stdlib classes, never from the analyzer process's loaded constants.
+      def record_member_consistency(loader, reporter, root)
         return if reporter.nil?
 
-        loader.inline_member_standdowns.each do |class_name, method_name, kind, signature_path, virtual_name|
-          plugin_id, path = split_virtual_source_name(virtual_name)
-          next if path.nil?
-
-          reporter.record(
-            plugin_id: plugin_id, path: path, kind: :not_honoured,
-            message: inline_member_standdown_message(class_name, method_name, kind, signature_path, root)
-          )
+        proof = MemberConsistency::RbsProof.new(loader)
+        loader.member_consistency(proof: proof).each do |record|
+          case record.outcome
+          when :contradiction then record_member_contradiction(reporter, record, root)
+          when :refinement then record_refinement_contradiction(reporter, record, root)
+          when :undecided then record_member_undecided(reporter, record, root)
+          end
         end
       end
 
+      def record_member_contradiction(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id, path: path_relative_to(record.signature_path, root), line: record.signature_line,
+          kind: :contradiction,
+          message: "`#{member_label(record)}` is declared here and by an inline annotation in " \
+                   "`#{path_relative_to(path, root)}`, and the two contradict: #{record.detail}. Rigor reads " \
+                   "this `.rbs` declaration. Regenerate the signature, or fix the annotation, so that one " \
+                   "of the two refines the other."
+        )
+      end
+
+      def record_refinement_contradiction(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        path = record.signature_path if path.nil?
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id.to_s, path: path_relative_to(path, root), line: record.signature_line,
+          kind: :contradiction,
+          message: "`#{member_label(record)}` refines its own signature to a type outside it: " \
+                   "#{record.detail}. A `rigor:v1:` refinement may narrow the ordinary RBS contract, never " \
+                   "contradict it, so one of the two is wrong."
+        )
+      end
+
+      def record_member_undecided(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id, path: path, kind: :not_honoured,
+          message: "`#{member_label(record)}` is also declared in " \
+                   "`#{path_relative_to(record.signature_path, root)}`, and Rigor cannot tell which of the two " \
+                   "is the more precise (#{record.detail}), so the `.rbs` declaration binds and the inline " \
+                   "signature was dropped. Left to collide the two would fail the class's definition build, " \
+                   "and every call on it — real methods and typos alike — would read `Dynamic[top]`. Make " \
+                   "one of the two a refinement of the other, or remove one, to settle which binds."
+        )
+      end
+
+      def member_label(record)
+        separator = record.kind == :singleton ? "." : "#"
+        "#{record.class_name}#{separator}#{record.method_name}"
+      end
+
       # Splits a virtual buffer name back into the pair {.collect_virtual_rbs} composed it from
       # (`virtual:<plugin id>:<source path>`). Limited to three fields so a path carrying a colon survives.
       # Returns `[nil, nil]` for a name in any other shape — a synthesizer channel this method does not own.
@@ -598,59 +644,10 @@ module Rigor
         [plugin_id, path]
       end
 
-      def inline_member_standdown_message(class_name, method_name, kind, signature_path, root)
-        separator = kind == :singleton ? "." : "#"
-        "`#{class_name}#{separator}#{method_name}` is also declared in " \
-          "`#{path_relative_to(signature_path, root)}`, and an explicit `.rbs` declaration wins over an " \
-          "inline annotation for the same member, so the inline signature was dropped. Left to collide the " \
-          "two would fail the class's definition build, and every call on it — real methods and typos " \
-          "alike — would read `Dynamic[top]`. Remove one of the two declarations to make the inline " \
-          "annotation bind."
-      end
-
       def path_relative_to(path, root)
         prefix = "#{root}#{File::SEPARATOR}"
         path.to_s.start_with?(prefix) ? path.to_s.delete_prefix(prefix) : path.to_s
       end
-
-      SYNTHESIZER_CACHE_PRODUCER_ID = "plugin.source_rbs_synthesizer"
-      private_constant :SYNTHESIZER_CACHE_PRODUCER_ID
-
-      # One entry per (plugin, source file), all of them live for as long as the file is in the project — a
-      # generation count says nothing about staleness here, so this producer declares itself out of
-      # `Cache::Store#evict!`'s compaction pass and is bounded only by the size-based LRU pass. A method
-      # rather than a constant: `Cache::Store` is not loaded yet when this class body runs.
-      def synthesizer_generation_cap
-        Cache::Store::UNBOUNDED_GENERATIONS
-      end
-
-      def build_synthesizer_cache_descriptor(plugin, path)
-        Cache::Descriptor.new(
-          files: [Cache::Descriptor::FileEntry.new(
-            path: path.to_s,
-            comparator: :digest,
-            value: synthesizer_input_digest(path)
-          )],
-          plugins: [plugin.plugin_entry]
-        )
-      end
-
-      def synthesizer_input_digest(path)
-        Digest::SHA256.hexdigest(File.binread(path))
-      rescue ::SystemCallError
-        # Unreadable file → key on the path alone; the synthesizer's File.file?/File.read will see the same
-        # failure and return nil.
-        Digest::SHA256.hexdigest(path.to_s)
-      end
-
-      def invoke_synthesizer_safely(callable, path)
-        callable.call(path.to_s)
-      rescue StandardError
-        # WD6 fail-soft — a synthesizer that raises does NOT crash analysis. Unlike the `[:error, msg]`
-        # return path (which the runner surfaces as `source-rbs-synthesis-failed`), an unhandled raise is
-        # swallowed silently; the unexamined-raise channel is deliberately silent per WD6.
-        nil
-      end
     end
 
     # Resolves a constant name to a Rigor::Type::Nominal (the *instance* type carrier). Consults the static
@@ -696,6 +693,17 @@ module Rigor
       end
     end
 
+    # Issue #1362 — the translated type of the RBS declaration of the global variable `name` (`$stdout: IO` answers
+    # `Nominal[IO]`), or nil when no signature declares it or the environment carries no RBS loader. With
+    # `builtin: true` it answers only for a declaration in Ruby's own core or stdlib signatures, a global the
+    # interpreter sets; a project's or a gem's declaration then answers nil.
+    def global_for_name(name, builtin: false)
+      return nil if rbs_loader.nil?
+      return nil if builtin && !rbs_loader.core_or_stdlib_global?(name)
+
+      rbs_loader.global_type(name)
+    end
+
     # Returns true when the constant name is known to either the static registry or the RBS loader. Useful
     # for callers that only need a presence check without materialising a type carrier.
     def class_known?(name)