rigortype 0.4.6 → 0.4.7

data/lib/rigor/analysis/runner/project_pre_passes.rb

@@ -378,8 +378,8 @@ module Rigor
         # Builds the {Rigor::Plugin::TrustPolicy} for this run. Trusted gems are the gem-name half of every
         # entry in `Configuration#plugins`. Allowed read roots default to the project root (CWD), the
         # project's signature_paths, and each trusted gem's `Gem::Specification#full_gem_path`, plus any
-        # extras the user listed under `plugins_io.allowed_paths`. Slice 2 keeps `network_policy` `:disabled`
-        # — the only value the configuration accepts today.
+        # extras the user listed under `plugins_io.allowed_paths`. `network_policy` is `plugins_io.network`
+        # (`:disabled` or `:allowlist`).
         def build_trust_policy
           trusted_gems = @configuration.plugins.map { |entry| trusted_gem_name(entry) }.uniq
           roots = [Dir.pwd]
@@ -409,7 +409,7 @@ module Rigor
           return nil if gem_name.nil? || gem_name.empty?
 
           spec = Gem.loaded_specs[gem_name]
-          spec&.full_gem_path # rigor:disable undefined-method
+          spec&.full_gem_path
         rescue StandardError
           nil
         end

data/lib/rigor/analysis/runner/run_level_facts.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # ADR-116 WD3 (#1195) — the run-level fact registry. A run-level fact is a fact about the RUN rather than
+      # about one file: the project-signature state, the definition-build failures, the HKT-scan outcome, the
+      # `RunStats` RBS tables, the effect-annotation carrier. Each is declared ONCE below, and every path that
+      # used to hand-list the slots — the {RunSnapshots} store, the {PoolCoordinator} backends, the
+      # {WorkerSession} drain, the {DiagnosticAggregator} rows and the incremental snapshot's
+      # `RunLevelRows` — reads the declarations instead.
+      #
+      # A {Fact} carries:
+      #
+      # - `name` and `empty` — the store key and its value before anything is recorded;
+      # - `merge` — how a recorded value folds into the slot: {Merge.assign}, {Merge.first_wins} (#784) or
+      #   {Merge.union_by_class} (#696);
+      # - `source` — `:environment` (read off a coordinator-side environment before the per-file loop, so a
+      #   fork child inherits the demand it makes), `:analysis` (read after the loop, and drained out of each
+      #   pool worker, because the per-file analysis is what demands it) or `:stats` (`RunStats` telemetry,
+      #   read only when stats are collected);
+      # - `gate` — for an `:environment` fact, which environment it is read from; an empty-closure run
+      #   resolves one per gate, lazily, and every other path hands the same environment to both;
+      # - `demand` — for an `:analysis` fact, whether collecting it makes a demand of its own (the HKT
+      #   registry build, #784) rather than reading what the analysis already demanded. A path that must not
+      #   pay for a demand (the Ractor prewarm, an empty closure with a replay in hand) drains only the others;
+      # - `replay` — whether a narrowed incremental run replays the previous full run's value
+      #   ({Cache::IncrementalSnapshot::RunLevelRows});
+      # - `row` / `position` — the {DiagnosticAggregator} method that turns the slot into diagnostics, and
+      #   where that row sits in the post-analysis stream (docs/type-specification/diagnostic-policy.md fixes
+      #   the order). Nil for a fact no diagnostic reads.
+      #
+      # The declaration ORDER is the collection order: {.harvest} reads the `:environment` facts in it, and
+      # that order is load-bearing (the stand-downs are read before the env-forcing reads, the conformance
+      # scan — which demands definitions — last). The row order is `position`, independently.
+      #
+      # Rows whose producer is not a slot here — the reporter streams, which the reporters snapshot and
+      # absorb themselves, and the two plugin tables the coordinator collects — are declared as {Row}s so
+      # the whole post-analysis order lives in one place.
+      #
+      # Everything here is frozen data plus module functions, never a closure: {WorkerSession#drain_reporters}
+      # reads these declarations inside a Ractor worker, and a drained value has to stay Marshal-clean (#805)
+      # for the fork backend.
+      module RunLevelFacts
+        Fact = Data.define(:name, :empty, :merge, :source, :gate, :demand, :replay, :row, :position)
+        Row = Data.define(:builder, :position)
+
+        # The predicates an `:environment` collector consults, taken by the coordinator when it harvests.
+        Context = Data.define(:project_signature_paths, :plugin_signature_paths, :record_effects)
+
+        # How a recorded value folds into its slot.
+        module Merge
+          module_function
+
+          def assign(_current, incoming)
+            incoming
+          end
+
+          # Issue #784 — the HKT scan is one build over the overlay every worker shares, so the first tuple
+          # recorded is the run's outcome.
+          def first_wins(current, incoming)
+            current.nil? ? incoming : current
+          end
+
+          # Issue #696 / #1902 — each pool worker holds its own loader, so the run's set is the union, one
+          # tuple per class chosen by {Environment::RbsLoader.definition_build_detail_order} rather than by
+          # arrival.
+          def union_by_class(current, incoming)
+            return current if incoming.nil? || incoming.empty?
+
+            (current + incoming)
+              .group_by(&:first)
+              .map { |_, candidates| candidates.min_by { |c| Environment::RbsLoader.definition_build_detail_order(c) } }
+              .freeze
+          end
+        end
+
+        # One collector per fact, named after it: `(environment, context) -> value`.
+        module Collect
+          module_function
+
+          # Issue #610 — gated on a loaded plugin contributing signatures, not on `signature_paths:`: the
+          # source a plugin's `sig/` stands down against is typically an `rbs collection install`.
+          def signature_standdowns(environment, context)
+            return [] unless context.plugin_signature_paths
+
+            loader = environment&.rbs_loader
+            return [] if loader.nil? || !loader.respond_to?(:deferred_signature_paths)
+            return [] if loader.deferred_signature_paths.empty?
+
+            loader.signature_standdowns
+          end
+
+          # Issue #1713 — not behind the `signature_paths:` gate either; the loader answers without building
+          # its env when no gated directory is active.
+          def vendored_standdowns(environment, _context)
+            loader = environment&.rbs_loader
+            loader.respond_to?(:vendored_standdowns) ? loader.vendored_standdowns : []
+          end
+
+          # The four below read the project's OWN `signature_paths:` state, and each forces the otherwise-lazy
+          # env build, so they are gated on the project declaring `signature_paths:`.
+          def synthesized_namespaces(environment, context)
+            return [] unless context.project_signature_paths
+
+            environment&.rbs_loader&.synthesized_namespaces || []
+          end
+
+          # Read after the env-forcing read above: the collision derivation reads the BUILT env.
+          def quarantined_signatures(environment, context)
+            return [] unless context.project_signature_paths
+
+            environment&.rbs_loader&.quarantined_signatures || []
+          end
+
+          def env_build_failure(environment, context)
+            return nil unless context.project_signature_paths
+
+            environment&.rbs_loader&.env_build_failure
+          end
+
+          # Read LAST of the signature state: the scan demands the definition of every `rigor:v1:conforms-to`
+          # class, and a resulting definition-build failure has to be in the loader before the `:analysis`
+          # read of {.definition_build_failures}.
+          def conformance_results(environment, context)
+            return [] unless context.project_signature_paths
+
+            RbsExtended::ConformanceChecker.scan(environment&.rbs_loader)
+          end
+
+          # #441 — the inline stratum of `effect.annotations-unchecked`. Skipped when effect collection is on:
+          # {EffectEnvelopePass} reads the loader directly then.
+          def effect_annotation_carrier(environment, context)
+            virtual = context.record_effects ? nil : environment&.rbs_loader&.virtual_rbs
+            Effects::SignatureSources.annotated_carrier(virtual)
+          rescue StandardError
+            [].freeze
+          end
+
+          # Issue #696 — read after the loop: definition builds are lazy, per class, on first demand. NOT
+          # gated on `signature_paths:` like the signature state: nothing is forced here (this reads what the
+          # analysis already demanded), and two BUNDLED sources can collapse a class with no project sig set
+          # in sight (the `bigdecimal` / `BigMath` shape, #299).
+          def definition_build_failures(environment, _context)
+            environment&.rbs_loader&.definition_build_failures || []
+          end
+
+          # Issue #784 — the run demands the registry once itself, so the outcome does not depend on which
+          # files were analysed. One build, one outcome whoever demands it, so a Rigor-owned demand cannot
+          # change what is reported (unlike #696's per-class list).
+          def hkt_scan_failure(environment, _context)
+            return nil if environment.nil?
+
+            environment.hkt_registry
+            environment.hkt_scan_failure
+          end
+
+          def class_decl_paths(environment, _context)
+            environment&.rbs_loader&.class_decl_paths || {}.freeze
+          end
+
+          def signature_paths(environment, _context)
+            environment&.rbs_loader&.signature_paths || [].freeze
+          end
+        end
+
+        EMPTY_LIST = [].freeze
+        EMPTY_TABLE = {}.freeze
+
+        FACTS = [
+          Fact.new(name: :signature_standdowns, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :rbs_plugin_signature_stood_down_diagnostics, position: 60),
+          Fact.new(name: :vendored_standdowns, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :rbs_vendored_signature_stood_down_diagnostics, position: 70),
+          Fact.new(name: :synthesized_namespaces, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :rbs_synthesized_namespace_diagnostics, position: 50),
+          Fact.new(name: :quarantined_signatures, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :rbs_quarantined_signature_diagnostics, position: 10),
+          Fact.new(name: :env_build_failure, empty: nil, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :rbs_environment_build_failed_diagnostics, position: 20),
+          Fact.new(name: :conformance_results, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :signature_state, demand: false, replay: false,
+                   row: :conforms_to_diagnostics, position: 80),
+          # Read by {EffectAnnotationResidualPass}, outside this stream.
+          Fact.new(name: :effect_annotation_carrier, empty: EMPTY_LIST, merge: :assign, source: :environment,
+                   gate: :annotation_carrier, demand: false, replay: false, row: nil, position: nil),
+          Fact.new(name: :definition_build_failures, empty: EMPTY_LIST, merge: :union_by_class, source: :analysis,
+                   gate: nil, demand: false, replay: true,
+                   row: :rbs_definition_build_failed_diagnostics, position: 30),
+          Fact.new(name: :hkt_scan_failure, empty: nil, merge: :first_wins, source: :analysis,
+                   gate: nil, demand: true, replay: true,
+                   row: :rbs_hkt_scan_failed_diagnostics, position: 40),
+          Fact.new(name: :class_decl_paths, empty: EMPTY_TABLE, merge: :assign, source: :stats,
+                   gate: nil, demand: false, replay: false, row: nil, position: nil),
+          Fact.new(name: :signature_paths, empty: EMPTY_LIST, merge: :assign, source: :stats,
+                   gate: nil, demand: false, replay: false, row: nil, position: nil)
+        ].freeze
+
+        # The rows no slot above produces. The reporter streams follow the `rbs.coverage.*` ladder and the
+        # conformance rows; the plugin-authored run disclosures (#1051) come before the engine-authored trust
+        # refusal envelope (#959), which is read last so every per-file plugin call has recorded its refusals.
+        ROWS = [
+          Row.new(builder: :unresolved_payload_diagnostics, position: 90),
+          Row.new(builder: :lossy_projection_diagnostics, position: 100),
+          Row.new(builder: :hkt_directive_diagnostics, position: 110),
+          Row.new(builder: :deprecated_form_diagnostics, position: 120),
+          Row.new(builder: :boundary_cross_diagnostics, position: 130),
+          Row.new(builder: :source_rbs_synthesis_diagnostics, position: 140),
+          Row.new(builder: :plugin_run_disclosure_diagnostics, position: 150),
+          Row.new(builder: :plugin_trust_refusal_diagnostics, position: 160)
+        ].freeze
+
+        # The per-run reporter accumulators, by drain key. Each reporter snapshots and absorbs its own
+        # streams (`#snapshot` / `#absorb`), so a new stream inside one touches that reporter and its row.
+        REPORTERS = %i[rbs_extended boundary_cross source_rbs_synthesis].freeze
+
+        BY_NAME = FACTS.to_h { |fact| [fact.name, fact] }.freeze
+
+        # Read inside a Ractor worker's drain, so every constant here is deeply shareable.
+        Ractor.make_shareable(FACTS)
+        Ractor.make_shareable(ROWS)
+        Ractor.make_shareable(BY_NAME)
+
+        module_function
+
+        def facts
+          FACTS
+        end
+
+        def fact(name)
+          BY_NAME.fetch(name)
+        end
+
+        def names(source: nil)
+          (source ? FACTS.select { |fact| fact.source == source } : FACTS).map(&:name)
+        end
+
+        def replayable_names
+          FACTS.select(&:replay).map(&:name)
+        end
+
+        def empty_values
+          FACTS.to_h { |fact| [fact.name, fact.empty] }
+        end
+
+        # The post-analysis diagnostic builders, in their contract order.
+        def row_builders
+          (FACTS.select(&:row).map { |fact| Row.new(builder: fact.row, position: fact.position) } + ROWS)
+            .sort_by(&:position)
+            .map(&:builder)
+        end
+
+        # Collects every fact of `source`, in declaration order, from the environment the block yields for
+        # its gate (one call per gate, on first need). `:analysis` and `:stats` facts take the block's
+        # environment with a nil gate.
+        def harvest(source, context)
+          environments = {}
+          FACTS.each_with_object({}) do |fact, collected|
+            next unless fact.source == source
+
+            environment = environments.fetch(fact.gate) { environments[fact.gate] = yield(fact.gate) }
+            collected[fact.name] = Collect.public_send(fact.name, environment, context)
+          end
+        end
+
+        # The `:analysis` facts as an analysing process reports them: the {WorkerSession} drain, and the
+        # coordinator's own environment on the paths that analyse on it. Plain tuples — Marshal-clean and
+        # shareable.
+        #
+        # @param demanding — nil drains every `:analysis` fact; false only those that read what was already
+        #   demanded; true only those that make a demand of their own.
+        def drain(environment, demanding: nil)
+          FACTS.each_with_object({}) do |fact, drained|
+            next unless fact.source == :analysis
+            next unless demanding.nil? || fact.demand == demanding
+
+            drained[fact.name] = Collect.public_send(fact.name, environment, nil)
+          end
+        end
+
+        # The `:analysis` facts out of a drained hash, for {RunSnapshots#absorb}.
+        def drained_facts(drained)
+          names(source: :analysis).each_with_object({}) do |name, facts|
+            facts[name] = drained[name] if drained.key?(name)
+          end
+        end
+
+        def snapshot_reporters(reporters)
+          REPORTERS.to_h { |name| [name, reporters.fetch(name).snapshot] }
+        end
+
+        # A drain shape that lacks a reporter's key records nothing for it.
+        def absorb_reporters(reporters, drained)
+          REPORTERS.each { |name| reporters.fetch(name).absorb(drained[name]) }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner/run_snapshots.rb

@@ -1,68 +1,58 @@
 # frozen_string_literal: true
 
+require_relative "run_level_facts"
+
 module Rigor
   module Analysis
     class Runner
-      # Mutable per-run holder for the end-of-pass snapshots that the analysis paths compute as a side
-      # effect and the rest of the run reads back: the RBS `class_decl_paths` / `signature_paths` tables
-      # (consumed by {RunStats}), the synthesized-namespace name list, the `conforms-to` scan results
-      # (consumed by the diagnostic aggregator), and the effect-annotation carrier (#441 — consumed by
-      # {EffectAnnotationResidualPass} on the runs that never store the environment).
+      # Mutable per-run store for the run-level facts ({RunLevelFacts}): one slot per declared fact, keyed by
+      # its name. The analysis paths write it ({PoolCoordinator} — sequential, fork-pool, Ractor-pool,
+      # fallback, empty closure) and the rest of the run reads it back: the {DiagnosticAggregator} rows,
+      # {RunStats}, {EffectAnnotationResidualPass} and the incremental snapshot's `RunLevelRows`.
+      #
+      # A shared mutable holder keeps the write/read timing of the original inline ivars while letting the
+      # writer and the readers live in separate objects without a back-reference cycle.
       #
-      # The snapshots are written by whichever analysis path ran ({PoolCoordinator} sequential / fork-pool /
-      # fallback) and read by the {Runner} and {DiagnosticAggregator}. A shared mutable holder keeps the
-      # write/read timing bit-for-bit with the original inline ivars (the same pattern the reporter
-      # accumulators use) while letting the writer and readers live in separate objects without a
-      # back-reference cycle.
+      # The analysis paths write through {#absorb}, which folds each value in by its fact's declared merge
+      # rule. `[]=` and the per-fact `name=` writers (defined from the declarations, like the readers) are a
+      # plain assignment that bypasses the merge rule: they exist for specs that seed a slot, and no
+      # production path calls them.
       class RunSnapshots
-        attr_accessor :class_decl_paths, :signature_paths,
-                      :synthesized_namespaces, :quarantined_signatures, :signature_standdowns, :vendored_standdowns,
-                      :conformance_results,
-                      :env_build_failure, :definition_build_failures, :hkt_scan_failure,
-                      :effect_annotation_carrier
-
-        # Constructor defaults match the {Runner} constructor: the pre-seed values `build_run_stats` /
-        # `pre_file_diagnostics` read before the first analysis path runs are frozen empties. The
-        # `env_build_failure` slot is nil (no failure) rather than an empty collection — it holds a single
-        # `[error_class, first_line, buffer_names]` tuple or nothing. Its per-class sibling
-        # `definition_build_failures` (#696) holds a LIST, because a collapsed universe fails many classes,
-        # and is accumulated ACROSS pool workers rather than assigned once — see
-        # {PoolCoordinator#merge_worker_reporters}. `hkt_scan_failure` (#784) is nil-or-tuple like
-        # `env_build_failure`, not a list like `definition_build_failures`: the scan is ONE build over the
-        # whole `signature_paths:` overlay, not a per-class one, so it has exactly one outcome per run.
-        # `signature_standdowns` (#610) is the quarantine slot's twin for the plugin-contributed files that
-        # stood down against a colliding generic arity: a list, assigned once from the loader as
-        # `quarantined_signatures` is, and derived from the final env so a cache HIT carries it too.
-        # `vendored_standdowns` (#1713) is the same shape of slot for what a required-feature-gated vendored
-        # directory left out because another signature source declares it.
         def initialize
-          @class_decl_paths = {}.freeze
-          @signature_paths = [].freeze
-          @synthesized_namespaces = [].freeze
-          @quarantined_signatures = [].freeze
-          @signature_standdowns = [].freeze
-          @vendored_standdowns = [].freeze
-          @conformance_results = [].freeze
-          @env_build_failure = nil
-          @definition_build_failures = [].freeze
-          @hkt_scan_failure = nil
-          @effect_annotation_carrier = [].freeze
+          @values = RunLevelFacts.empty_values
         end
 
-        # Per-`#run` reset. Mirrors the original `#run` body, which reset these to NON-frozen empties (distinct
-        # from the frozen constructor defaults) at the top of each run.
+        # Per-`#run` reset to every fact's declared empty value.
         def reset_for_run
-          @class_decl_paths = {}.freeze
-          @signature_paths = []
-          @synthesized_namespaces = []
-          @quarantined_signatures = []
-          @signature_standdowns = []
-          @vendored_standdowns = []
-          @conformance_results = []
-          @env_build_failure = nil
-          @definition_build_failures = []
-          @hkt_scan_failure = nil
-          @effect_annotation_carrier = [].freeze
+          @values = RunLevelFacts.empty_values
+        end
+
+        def [](name)
+          RunLevelFacts.fact(name)
+          @values[name]
+        end
+
+        def []=(name, value)
+          RunLevelFacts.fact(name)
+          @values[name] = value
+        end
+
+        # Folds `facts` (`{name => value}`) into the store, each by its fact's merge rule.
+        def absorb(facts)
+          facts.each do |name, value|
+            merge = RunLevelFacts.fact(name).merge
+            @values[name] = RunLevelFacts::Merge.public_send(merge, @values[name], value)
+          end
+          self
+        end
+
+        def to_h
+          @values.dup
+        end
+
+        RunLevelFacts.facts.each do |fact|
+          define_method(fact.name) { @values[fact.name] }
+          define_method(:"#{fact.name}=") { |value| @values[fact.name] = value }
         end
       end
     end

data/lib/rigor/analysis/runner/worker_payload.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # ADR-116 WD3 (#1195) — what one analysing {WorkerSession} hands back to the {PoolCoordinator}: its
+      # per-file results and every drain, taken in one place ({.harvest}) and folded in by one
+      # ({PoolCoordinator#absorb_worker_payload}). A fork child marshals it to its payload file, the Ractor
+      # backend sends it with `:done`, and the fork backend's degrade path harvests the parent session the
+      # same way.
+      #
+      # Every field is Marshal-clean (#805) and, on the Ractor backend, copyable: the drains are frozen
+      # `Data` entries and Hashes of Strings. `effects` is nil unless the run collects effects (ADR-103 WD13).
+      #
+      # The refusals are carried but not absorbed: their merge order is the file order of the whole run, so
+      # each backend merges them itself (#1900).
+      WorkerPayload = Data.define(:results, :reporters, :dependencies, :analysis_reads, :analysis_disclosures,
+                                  :disclosures, :refusals, :effects) do
+        # Drains `session` in the order the fork child always has: the reporters (which demand the HKT
+        # registry) before the refusal delta, so a refusal that demand makes is reported.
+        def self.harvest(session, results: {}, record_effects: false)
+          new(
+            results: results,
+            reporters: session.drain_reporters,
+            dependencies: session.drain_dependencies,
+            analysis_reads: session.drain_analysis_reads,
+            analysis_disclosures: session.drain_analysis_disclosures,
+            disclosures: session.drain_run_disclosures,
+            refusals: session.drain_trust_refusals,
+            effects: record_effects ? session.drain_effects : nil
+          )
+        end
+      end
+    end
+  end
+end