rigortype 0.2.9 → 0.3.0

data/lib/rigor/cache/incremental_snapshot.rb

@@ -24,8 +24,22 @@ module Rigor
       # Bump when the on-disk shape changes so stale snapshots are ignored rather than mis-deserialized. 5:
       # the blob is zlib-deflated (ADR-54 WD2 parity with `Store` entries — the snapshot is the one cache
       # artefact that does not go through `Store`); a raw pre-5 blob fails the inflate and loads as nil, the
-      # usual fault-tolerant cold-run path.
-      SCHEMA = 5
+      # usual fault-tolerant cold-run path. 6: adds the ADR-85 WD2 `seed_bundles` section (per-file discovery
+      # contributions with `(node_id, name, fingerprint)` def-node handles); a pre-6 blob mismatches the
+      # SCHEMA gate and loads as nil (a clean cold rebuild — no migration). 7: the seed bundle gains a
+      # `singleton_def_sources` table (ADR-46 slice 4 extended to class/singleton methods) AND `digests`
+      # switches to ADR-87 packed stat entries; a pre-7 blob mismatches the gate and loads as nil (clean cold
+      # rebuild). 8: each seed bundle additionally gains a comment-stripped `code_fingerprint` for the B1
+      # bundle-equality gate; a pre-8 blob mismatches and loads as nil (clean cold rebuild). 9: adds the ADR-88
+      # WD1 `plugin_fact_digest` (a fingerprint of the plugin fact SURFACE — ADR-9 facts, ADR-60 producer
+      # values, and `incremental_state_fingerprint` hooks — that a cached diagnostic can depend on but the
+      # global fingerprint does not capture); a pre-9 blob mismatches the SCHEMA gate and loads as nil (a clean
+      # cold rebuild — no migration). 10: ADR-89 WD1 adds a per-file `declaration_signature` to each seed
+      # bundle (the per-def parameter-shape / visibility / ancestry surface the declaration-stability gate
+      # compares) and WD2 adds `return_summaries` (per-def observed-key return descriptors + mutation-effect
+      # sets the behavioural-stability gate compares); a pre-10 blob mismatches the SCHEMA gate and loads as
+      # nil (a clean cold rebuild — no migration).
+      SCHEMA = 10
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -39,9 +53,25 @@ module Rigor
       # ADR-46 slice 3:
       # `missing` maps a consumer to Set<"kind:name"> it looked up and missed.
       # `class_decls` maps a path to Set<qualified class name> it declares.
+      # ADR-85 WD2:
+      # `seed_bundles` maps an analyzed path to its per-file discovery contribution (plain-data tables +
+      # `(node_id, name, fingerprint)` def-node handles + content digest), so a warm recheck rebuilds the
+      # cross-file index by folding bundles instead of parsing every file.
+      # ADR-88 WD1:
+      # `plugin_fact_digest` is a SHA-256 hex fingerprint of the plugin fact surface at the run that wrote the
+      # snapshot (or nil for a plugin-free project). A warm recheck recomputes it and, on a mismatch, discards
+      # the snapshot and runs a full analysis — the guard for a plugin sig/catalog edit that the global
+      # fingerprint cannot see.
+      # ADR-89 WD2:
+      # `return_summaries` maps a `[path, "Class#method" | "Class.method"]` to the callee's persisted
+      # behavioural surface `{ keys:, returns:, effects: }` — the observed `[receiver, arg_types]` call keys
+      # (Marshal-clean type tuples), their `describe(:short)` return descriptors, and the content-mutated
+      # parameter positions. A recheck re-evaluates a declaration-stable changed callee at these keys and,
+      # when every return + the effects are unchanged, skips its symbol dependents.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
-                            :missing, :class_decls)
+                            :missing, :class_decls, :seed_bundles, :plugin_fact_digest,
+                            :return_summaries)
 
       # The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full
       # rebuild — the engine version + schema, the resolved configuration, the analysis **roots** (the path
@@ -104,7 +134,10 @@ module Rigor
           ancestry_sources: data[:ancestry_sources] || {},
           symbol_fingerprints: data[:symbol_fingerprints] || {},
           missing: data[:missing] || {},
-          class_decls: data[:class_decls] || {}
+          class_decls: data[:class_decls] || {},
+          seed_bundles: data[:seed_bundles] || {},
+          plugin_fact_digest: data[:plugin_fact_digest],
+          return_summaries: data[:return_summaries] || {}
         )
       rescue StandardError
         nil
@@ -122,7 +155,10 @@ module Rigor
           ancestry_sources: payload.ancestry_sources,
           symbol_fingerprints: payload.symbol_fingerprints,
           missing: payload.missing,
-          class_decls: payload.class_decls
+          class_decls: payload.class_decls,
+          seed_bundles: payload.seed_bundles,
+          plugin_fact_digest: payload.plugin_fact_digest,
+          return_summaries: payload.return_summaries
         )
         blob = Zlib::Deflate.deflate(raw)
         tmp = "#{@path}.#{Process.pid}.tmp"

data/lib/rigor/cache/rbs_descriptor.rb

@@ -3,6 +3,7 @@
 require "digest"
 
 require_relative "descriptor"
+require_relative "file_digest"
 
 module Rigor
   module Cache
@@ -17,15 +18,36 @@ module Rigor
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: [libraries_entry(loader), virtual_rbs_entry(loader)].compact
+          configs: config_entries(loader)
         )
       end
 
+      # Lazy-files variant for the ADR-45 run-diagnostics record-and-validate cache. The cache KEY reads only
+      # `gems` + `configs` ({Runner#run_key_descriptor}); the RBS signature-tree `files` are read solely on a
+      # MISS, by the dependency descriptor ({Runner#run_dependency_descriptor}). So a warm HIT never digests
+      # the (large, vendored) RBS tree. {RunDescriptor} is NOT a {Descriptor} — it is never composed, hashed,
+      # or `==`'d, only its three readers are consulted — so deferring `files` costs no soundness, and `gems`
+      # / `configs` are byte-identical to {.build} (the key is unchanged).
+      def self.build_run(loader)
+        RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
+      end
+
+      # The `gems` + `configs` slots the run cache key reads. Cheap — no RBS env load, no file digesting
+      # (only the configured library names + any plugin-synthesised virtual RBS are hashed).
+      def self.config_entries(loader)
+        [libraries_entry(loader.libraries), virtual_rbs_entry(loader)].compact
+      end
+
+      # Public (ADR-87 WD4) so the boot-slimming run-cache probe reconstructs the identical `gems` +
+      # `rbs.libraries` key slots the runner writes, from the config-derived library list, without a loader.
       def self.rbs_gem_entry
         Descriptor::GemEntry.new(name: "rbs", requirement: ">= 0", locked: ::RBS::VERSION.to_s)
       end
 
-      def self.file_entries(loader)
+      # @param comparator [Symbol] `:digest` (default) for the env-cache KEY descriptor ({.build}), where the
+      #   value must be deterministic; `:stat` (ADR-87 WD1) for the validation-only run-dependency descriptor
+      #   ({RunDescriptor#files}), where the stat tier short-circuits the SHA-256 on an unmoved file.
+      def self.file_entries(loader, comparator: :digest)
         roots = loader.signature_paths +
                 Rigor::Environment::RbsLoader.vendored_gem_sig_paths +
                 Rigor::Environment::RbsLoader.core_overlay_sig_paths
@@ -33,17 +55,20 @@ module Rigor
           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
-            )
+            digest = FileDigest.hexdigest(path)
+            if comparator == :stat
+              Descriptor::FileEntry.stat(path: path, digest: digest)
+            else
+              Descriptor::FileEntry.new(path: path, comparator: :digest, value: digest)
+            end
           end
         end
       end
 
-      def self.libraries_entry(loader)
-        sorted = loader.libraries.map(&:to_s).sort
+      # @param library_names [Array<String, Symbol>] the loader's merged library list (or, on the WD4 probe
+      #   path, `Environment::DEFAULT_LIBRARIES + config.libraries` reconstructed without a loader).
+      def self.libraries_entry(library_names)
+        sorted = library_names.map(&:to_s).sort
         Descriptor::ConfigEntry.new(
           key: "rbs.libraries",
           value_hash: Digest::SHA256.hexdigest(sorted.join("\n"))
@@ -66,7 +91,28 @@ module Rigor
         )
       end
 
-      private_class_method :rbs_gem_entry, :file_entries, :libraries_entry, :virtual_rbs_entry
+      private_class_method :virtual_rbs_entry
+
+      # The lazy-files run descriptor {RbsDescriptor.build_run} returns. Exposes the three readers the
+      # run-diagnostics cache consults — `gems` + `configs` are supplied eagerly (they feed the cache KEY,
+      # and are cheap); `files` (the RBS signature-tree digests, read only on a MISS) is computed once on
+      # first access and memoised, so a warm HIT never pays for it.
+      class RunDescriptor
+        attr_reader :gems, :configs
+
+        def initialize(loader:, gems:, configs:)
+          @loader = loader
+          @gems = gems
+          @configs = configs
+        end
+
+        def files
+          # ADR-87 WD1 — this descriptor is validated (never a cache key), so the RBS signature tree rides the
+          # stat-then-digest `:stat` tier: a warm run stat-checks the (large, vendored) tree instead of
+          # re-hashing it.
+          @files ||= RbsDescriptor.file_entries(@loader, comparator: :stat)
+        end
+      end
     end
   end
 end

data/lib/rigor/cache/store.rb

@@ -224,10 +224,9 @@ module Rigor
         key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
         path = disk ? entry_path(producer_id, key) : nil
         cached = path && read_entry(path, deserialize: deserialize)
-        if cached && (pair = cached.value).is_a?(Array) && pair.size == 2 &&
-           pair[1].is_a?(Descriptor) && pair[1].fresh?
+        if (validated = fresh_pair_value(cached))
           @monitor.synchronize { record(:hits, producer_id) }
-          return pair[0]
+          return validated[0]
         end
 
         value, dependency_descriptor = block_given? ? yield : [nil, Descriptor.new]
@@ -239,6 +238,24 @@ module Rigor
         value
       end
 
+      # ADR-87 WD4 — the READ half of {#fetch_or_validate} with no compute and no write: returns the cached
+      # value on a fresh hit, nil on a miss / stale / unavailable-disk. The boot-slimming hit probe calls this
+      # to serve a run's diagnostics WITHOUT loading the inference engine — it never runs a producer block, so
+      # there is nothing to write. Records a hit (for `--cache-stats` parity) but never a miss (a probe miss
+      # hands off to the full path, which records its own).
+      def peek_validated(producer_id:, key_descriptor:, params: {}, deserialize: nil)
+        validate_producer_id!(producer_id)
+        return nil unless ensure_schema_version!
+
+        key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
+        cached = read_entry(entry_path(producer_id, key), deserialize: deserialize)
+        validated = fresh_pair_value(cached)
+        return nil if validated.nil?
+
+        @monitor.synchronize { record(:hits, producer_id) }
+        validated[0]
+      end
+
       # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only. Stale
       # temp file cleanup and the whole-project generation cap run regardless of `max_bytes:` — they reclaim
       # provably-dead bytes (leaked temp files, unreachable content-keyed generations) rather than enforcing a
@@ -274,6 +291,19 @@ module Rigor
       Entry = Data.define(:descriptor_bytes, :value)
       private_constant :Entry
 
+      # A record-and-validate entry is a fresh hit iff it deserialised to a `[value, dependency_descriptor]`
+      # pair whose descriptor still validates against the filesystem. Returns the pair on a fresh hit, nil
+      # otherwise. Shared by {#fetch_or_validate} and {#peek_validated} so both apply identical hit criteria.
+      def fresh_pair_value(cached)
+        return nil if cached.nil?
+
+        pair = cached.value
+        return nil unless pair.is_a?(Array) && pair.size == 2 &&
+                          pair[1].is_a?(Descriptor) && pair[1].fresh?
+
+        pair
+      end
+
       def record(counter, producer_id)
         case counter
         when :hits then @hits += 1

data/lib/rigor/ci_detector.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Runtime CI-environment detection (ADR-51 WD7), modelled on `OndraM/ci-detector` (the library PHPStan uses). Reads
+  # the well-known environment variables a CI provider sets and returns the matching {Platform}, classifying it into a
+  # **tier** that decides how `rigor check` surfaces diagnostics there:
+  #
+  #   :native_stdout   — Rigor has a native format that renders purely from
+  #                      stdout, so it is auto-emitted on top of the human
+  #                      output (GitHub Actions → `github`, TeamCity →
+  #                      `teamcity`). These are the first-class platforms.
+  #   :native_artifact — Rigor has a native format but it needs a CI-wired
+  #                      report artifact, not stdout (GitLab CI → `gitlab`).
+  #                      First-class, but Rigor only *hints* the format.
+  #   :reviewdog       — no native Rigor format; second-class, routed through
+  #                      reviewdog (`checkstyle`/`sarif`) or `junit`. Hint
+  #                      only.
+  #
+  # Lives outside the CLI namespace because it is a pure function of the environment hash with no CLI dependency, and
+  # non-CLI consumers exist: {Configuration#cache_validation_strict?} resolves the `auto` cache-validation default
+  # through it (a fresh CI checkout regenerates every stat tuple, so ADR-87's stat tier cannot work there).
+  # Detection is fully testable; callers pass `ENV`.
+  # `RIGOR_CI_DETECT=0` (or `false`/`no`) disables it globally — the seam the spec suite uses for determinism.
+  module CiDetector
+    Platform = Struct.new(:id, :name, :format, :tier, keyword_init: true) do
+      def native_stdout? = tier == :native_stdout
+      def native_artifact? = tier == :native_artifact
+      def reviewdog? = tier == :reviewdog
+    end
+
+    # The detection table, ordered most-specific first so the generic `CI=true` catch-all is last (a provider that
+    # also sets `CI` is still recognised by its own variable). `match` is `:truthy` (value in 1/true/yes/on),
+    # `:present` (variable set non-empty), or `:equals`.
+    PROVIDERS = [
+      { id: "github-actions", name: "GitHub Actions", format: "github", tier: :native_stdout,
+        var: "GITHUB_ACTIONS", match: :truthy },
+      { id: "gitlab", name: "GitLab CI", format: "gitlab", tier: :native_artifact,
+        var: "GITLAB_CI", match: :truthy },
+      { id: "teamcity", name: "TeamCity", format: "teamcity", tier: :native_stdout,
+        var: "TEAMCITY_VERSION", match: :present },
+      { id: "circleci", name: "CircleCI", format: nil, tier: :reviewdog,
+        var: "CIRCLECI", match: :truthy },
+      { id: "jenkins", name: "Jenkins", format: nil, tier: :reviewdog,
+        var: "JENKINS_URL", match: :present },
+      { id: "travis", name: "Travis CI", format: nil, tier: :reviewdog,
+        var: "TRAVIS", match: :truthy },
+      { id: "appveyor", name: "AppVeyor", format: nil, tier: :reviewdog,
+        var: "APPVEYOR", match: :truthy },
+      { id: "azure-pipelines", name: "Azure Pipelines", format: nil, tier: :reviewdog,
+        var: "TF_BUILD", match: :present },
+      { id: "bitbucket", name: "Bitbucket Pipelines", format: nil, tier: :reviewdog,
+        var: "BITBUCKET_BUILD_NUMBER", match: :present },
+      { id: "buildkite", name: "Buildkite", format: nil, tier: :reviewdog,
+        var: "BUILDKITE", match: :truthy },
+      { id: "drone", name: "Drone CI", format: nil, tier: :reviewdog,
+        var: "DRONE", match: :truthy },
+      { id: "semaphore", name: "Semaphore", format: nil, tier: :reviewdog,
+        var: "SEMAPHORE", match: :truthy },
+      { id: "codeship", name: "Codeship", format: nil, tier: :reviewdog,
+        var: "CI_NAME", match: :equals, value: "codeship" },
+      { id: "ci", name: "CI", format: nil, tier: :reviewdog,
+        var: "CI", match: :truthy }
+    ].freeze
+
+    module_function
+
+    # Returns the detected {Platform}, or nil when no CI is recognised or detection is disabled via `RIGOR_CI_DETECT`.
+    def detect(env = ENV)
+      return nil if disabled?(env)
+
+      row = PROVIDERS.find { |provider| matches?(env, provider) }
+      return nil if row.nil?
+
+      Platform.new(id: row[:id], name: row[:name], format: row[:format], tier: row[:tier])
+    end
+
+    def disabled?(env)
+      %w[0 false no off].include?(env["RIGOR_CI_DETECT"].to_s.strip.downcase)
+    end
+
+    def matches?(env, provider)
+      value = env[provider[:var]].to_s.strip
+      case provider[:match]
+      when :truthy then %w[1 true yes on].include?(value.downcase)
+      when :present then !value.empty?
+      when :equals then value.downcase == provider[:value]
+      end
+    end
+  end
+end

data/lib/rigor/cli/annotate_command.rb

@@ -9,11 +9,13 @@ require_relative "../configuration"
 require_relative "options"
 require_relative "../environment"
 require_relative "../scope"
+require_relative "../source/node_children"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
+require_relative "probe_environment"
 
 module Rigor
   class CLI
@@ -105,7 +107,7 @@ module Rigor
         # bindings, so a loop-body line annotates the joined widened type (`Integer`) rather than a stale
         # first-iterations constant (`1 | 2`).
         scope_index = Inference::ScopeIndexer.index(
-          parse_result.value, default_scope: base_scope(configuration),
+          parse_result.value, default_scope: base_scope(configuration, file),
                               converged_loop_recording: true
         )
         line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
@@ -128,12 +130,12 @@ module Rigor
         @out.puts(JSON.generate({ "annotations" => annotations }))
       end
 
-      def base_scope(configuration)
+      # The plugin-aware environment for the annotated file, so a `#=> <type>` matches what `rigor check`
+      # infers on that line — including types synthesized from the file's own inline RBS annotations (the file
+      # is threaded as the synthesizer's `source_files:`; see {ProbeEnvironment}).
+      def base_scope(configuration, file)
         Scope.empty(
-          environment: Environment.for_project(
-            libraries: configuration.libraries,
-            signature_paths: configuration.signature_paths
-          )
+          environment: ProbeEnvironment.build(configuration: configuration, source_files: [file])
         )
       end
 
@@ -247,14 +249,18 @@ module Rigor
             block.call(stmt)
           end
         else
-          node.compact_child_nodes.each { |child| each_statement(child, &block) }
+          node.rigor_each_child { |child| each_statement(child, &block) }
         end
       end
 
       # For a line no statement closes (the `if` / block header lines), fall back to the widest expression ending there.
+      # A hash-pair node (`1 => 2,` inside a multi-line literal / keyword-argument list) is not an expression — typing
+      # it only echoes the `Dynamic[top]` fallback — so those interior lines stay bare and the literal's type appears
+      # once, on the line the enclosing statement closes.
       def fill_uncovered_lines(program, by_line)
         widest_per_line(program).each do |line, node|
           next if by_line.key?(line)
+          next if node.is_a?(Prism::AssocNode) || node.is_a?(Prism::AssocSplatNode)
 
           type = node.is_a?(Prism::BlockParametersNode) ? block_params_type(node) : type_of(node)
           by_line[line] = type unless type.nil?
@@ -298,7 +304,7 @@ module Rigor
         return if node.nil?
 
         block.call(node)
-        node.compact_child_nodes.each { |child| walk(child, &block) }
+        node.rigor_each_child { |child| walk(child, &block) }
       end
 
       # Types the node through the flow evaluator (not the bare expression typer) under its recorded entry scope, so
@@ -331,7 +337,7 @@ module Rigor
         return if node.nil?
 
         block.call(node) if node.is_a?(Prism::DefNode)
-        node.compact_child_nodes.each { |child| each_def_node(child, &block) }
+        node.rigor_each_child { |child| each_def_node(child, &block) }
       end
     end
   end

data/lib/rigor/cli/baseline_command.rb

@@ -87,8 +87,11 @@ module Rigor
           "match-mode: #{options.fetch(:match_mode)})"
         )
         if configuration.baseline_path.nil?
+          # Name the config file that actually governs this project (`.rigor.dist.yml` when no local override
+          # exists), so the hint points at the file the user must edit.
+          config_name = options.fetch(:config) || Configuration.discover || ".rigor.yml"
           @err.puts(
-            "rigor: note — `.rigor.yml` does not declare `baseline:`; " \
+            "rigor: note — `#{config_name}` does not declare `baseline:`; " \
             "add `baseline: #{path}` to activate the suppression."
           )
         end