Class: Rigor::Analysis::Runner

Inherits:
Object
  • Object
show all
Defined in:
lib/rigor/analysis/runner.rb,
lib/rigor/analysis/runner/run_snapshots.rb,
lib/rigor/analysis/runner/pool_coordinator.rb,
lib/rigor/analysis/runner/envelope_messages.rb,
lib/rigor/analysis/runner/project_pre_passes.rb,
lib/rigor/analysis/runner/declaration_position.rb,
lib/rigor/analysis/runner/effect_envelope_pass.rb,
lib/rigor/analysis/runner/diagnostic_aggregator.rb,
lib/rigor/analysis/runner/buffer_pool_dispatcher.rb,
lib/rigor/analysis/runner/effect_annotation_residual_pass.rb,
sig/rigor.rbs

Overview

rubocop:disable Metrics/ClassLength

Defined Under Namespace

Modules: DeclarationPosition, EnvelopeMessages Classes: BufferPoolDispatcher, DiagnosticAggregator, EffectAnnotationResidualPass, EffectEnvelopePass, PoolCoordinator, ProjectPrePasses, RunSnapshots

Constant Summary collapse

DEFAULT_CACHE_ROOT =

Returns:

  • (String) 
".rigor/cache"
RETURN_SUMMARY_KEYS_PER_DEF =

ADR-89 WD2 — bounds on the persisted return summaries (per-def observed call keys, and total defs summarised) so the incremental snapshot stays small. A def observed under more keys than the per-def cap keeps only the first; a def past the total cap is dropped (its symbol dependents then always re-check — the conservative direction).

8
RETURN_SUMMARY_TOTAL_CAP = 
4000
PRISM_VERSION_LADDER =

Ruby versions probed (ascending) to discover the lowest one this Prism build accepts for version:. Prism exposes no version list, so the floor is found empirically — only when a misconfigured target_ruby is rejected — so the diagnostic can name it instead of leaving the user to guess (the dogfood field trial, 20260620-skill-driven-onboarding-dogfood.md, burned cycles on exactly this).

%w[
  3.0.0 3.1.0 3.2.0 3.3.0 3.4.0 3.5.0 4.0.0 4.1.0 4.2.0
].freeze
RUBY_GLOB =

Returns:

  • (String) 

      
    

  




  
Instance Attribute Summary collapse

  




  
    

      Class Method Summary
      collapse
    


    
    
  
    

      Instance Method Summary
      collapse
    


    
    
  



  
Constructor Details

  
    

  

  
    #initialize(configuration:, explain: false, cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT), plugin_requirer: nil, workers: 0, collect_stats: true, buffer: nil, prebuilt: nil, environment: nil, record_dependencies: false, record_self_calls: false, analyze_only: nil, seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil, discovery_seed: nil, no_tolerated_effects: false)  ⇒ Runner 
  

  

  


  

    
Returns a new instance of Runner.


  





  
Parameters:


    
  
    
  • 
      
        configuration
      
      
        (Rigor::Configuration)
      
      
      
    
    • 
  
    
  • 
      
        explain
      
      
        (Boolean)
      
      
        (defaults to: false)
      
      
        —
        
    surface fail-soft fallback events as :info diagnostics.
    
      
    
    • 
  
    
  • 
      
        cache_store
      
      
        (Rigor::Cache::Store, nil)
      
      
        (defaults to: Cache::Store.new(root: DEFAULT_CACHE_ROOT))
      
      
        —
        
    the persistent cache the runner exposes to producers
(RbsConstantTable and successors). Pass nil to disable caching for this run; the CLI's
--no-cache flag wires nil through. v0.0.9 group A slice 1 introduces the surface; later
slices route real producers through it.
    
      
    
    • 
  
    
  • 
      
        workers
      
      
        (Integer)
      
      
        (defaults to: 0)
      
      
        —
        
    ADR-15 Phase 4b — when greater than zero, per-file analysis dispatches
across a pool of N workers. Default 0 keeps the sequential code path bit-for-bit unchanged.
Controlled via the RIGOR_RACTOR_WORKERS env var or .rigor.yml parallel.workers: (Phase 4c,
fully wired).
    
      
    
    • 
  
    
  • 
      
        collect_stats
      
      
        (Boolean)
      
      
        (defaults to: true)
      
      
        —
        
    when true (default), #run builds a Rigor::Analysis::RunStats summary exposed via
result.stats — this forces the RBS env build at end-of-run so the class_decl_paths snapshot
has real source attribution. Set to false to skip the stats summary entirely; the CLI's
--no-stats threads false through to keep trivial-fixture runs from warming .rigor/cache.
    
      
    
    • 
  
    
  • 
      
        prebuilt
      
      
        (Rigor::Analysis::ProjectScan, nil)
      
      
        (defaults to: nil)
      
      
        —
        
    when supplied, the runner adopts the pre-built
plugin registry / dependency-source index / scanner outputs from the snapshot and skips the
per-call pre-passes that produce them. Used by long-lived integrations
(Rigor::LanguageServer::ProjectContext) to keep per-buffer requests fast — scanners walk the
project once per generation rather than once per request, and plugin #prepare runs once per
generation rather than once per request. Watched-file invalidation is the owner's responsibility;
the runner trusts the snapshot it was given.
    
      
    
    • 
  
    
  • 
      
        environment
      
      
        (Rigor::Environment, nil)
      
      
        (defaults to: nil)
      
      
        —
        
    opt-in Environment override. When supplied, sequential
mode uses the provided env instance in #analyze_files instead of building a fresh one via
Environment.for_project, and attaches the runner's per-run reporter pair onto the env's mutable
Reporters slot via Environment#attach_reporters!. Long-lived consumers (LSP ProjectContext)
pass a shared env so per-publish work doesn't repeat the Environment.for_project build (bundler
/ lockfile / collection discovery, RbsLoader construction). Pool mode ignores the override — each
worker continues to build its own Environment.
    
      
    
    • 
  
    
  • 
      
        discovery_seed
      
      
        (Hash, nil)
      
      
        (defaults to: nil)
      
      
        —
        
    issue #260 — opt-in cross-file discovery tables, keyed by
Scope::DiscoveryIndex slot name, seeded onto every per-file scope through
project_scope_seed_tables. The ONE deliberate exception to "a prebuilt: runner carries no
discovery tables": Protection::DiagnosticOracle threads the table set Tier 2's site filter already
judges anchors against, so a site admitted because a sibling-file class resolved is also a site the
oracle can kill at. nil (the default) leaves the prebuilt/LSP contract byte-identical.
    
      
    
    • 
  
    
  • 
      
        no_tolerated_effects
      
      
        (Boolean)
      
      
        (defaults to: false)
      
      
        —
        
    ADR-103 WD1 / #385 — rigor check --no-tolerated-effects.
Judges effect envelopes as if effects.tolerated: were empty. A judgment-time switch only: the
run, its collection and its cache identity are unchanged.
    
      
    
    • 
  
    
  • 
      
        configuration:
      
      
        (Configuration)
      
      
      
    
    • 
  
    
  • 
      
        explain:
      
      
        (Boolean)
      
      
        (defaults to: false)
      
      
    
    • 
  
    
  • 
      
        cache_store:
      
      
        (Object)
      
      
        (defaults to: Cache::Store.new(root: DEFAULT_CACHE_ROOT))
      
      
    
    • 
  
    
  • 
      
        plugin_requirer:
      
      
        (Object)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        workers:
      
      
        (Integer)
      
      
        (defaults to: 0)
      
      
    
    • 
  
    
  • 
      
        collect_stats:
      
      
        (Boolean)
      
      
        (defaults to: true)
      
      
    
    • 
  
    
  • 
      
        buffer:
      
      
        (Object)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        prebuilt:
      
      
        (Object)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        environment:
      
      
        (Object)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        record_dependencies:
      
      
        (Boolean)
      
      
        (defaults to: false)
      
      
    
    • 
  
    
  • 
      
        analyze_only:
      
      
        (Object)
      
      
        (defaults to: nil)
      
      
    
    • 
  






  

    
      


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 202

def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
               cache_store: Cache::Store.new(root: DEFAULT_CACHE_ROOT),
               plugin_requirer: nil, workers: 0, collect_stats: true,
               buffer: nil, prebuilt: nil, environment: nil,
               record_dependencies: false, record_self_calls: false, analyze_only: nil,
               seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
               discovery_seed: nil, no_tolerated_effects: false)
  @configuration = configuration
  @explain = explain
  @cache_store = enforce_read_only_cache(cache_store, buffer)
  @plugin_requirer = plugin_requirer
  @workers = workers
  @collect_stats = collect_stats
  @buffer = buffer
  @prebuilt = prebuilt
  @environment_override = environment
  # ADR-46 slice 1 — opt-in cross-file dependency recording. Off by default; when true,
  # `analyze_file` records each file's cross-file reads into `file_dependencies` (the incremental
  # cache, a later slice, consumes them).
  @record_dependencies = record_dependencies
  # ADR-24 slice 4a — opt-in unresolved-implicit-self-call recording. Off by default; when true,
  # `analyze_file` activates the engine choke-point recorder and collects each file's misses into
  # `unresolved_self_calls` (a later closed-class-gated rule consumes them). Purely observational —
  # diagnostics are byte-identical.
  @record_self_calls = record_self_calls
  @unresolved_self_calls = {}
  # ADR-103 WD13 — effect collection. Derived from the configuration, never from a flag: the
  # `effects:` block (or an implicit one, which is how `rigor effects` opts in) is the ONLY switch.
  # Observational — diagnostics are byte-identical whichever way it resolves.
  @record_effects = configuration.effects_enabled?
  # ADR-103 WD6 / #385 — the project's `effects.attribution:` table, built once and carried on the
  # collection window so a fork-pool worker scans under the same claims the parent does.
  @effect_attribution = Effects::Attribution.build(configuration.effects_attribution)
  # ADR-103 WD6 / #386 — the call-site envelope index, built lazily off the run's environment
  # (`#effect_envelope_index`) because the strata it reads include the built RBS one.
  @effect_envelope_index = nil
  @effect_envelope_index_env = nil
  # #387 — the compiled plugin effect tables, memoised on the ancestry table they were built from
  # (see `#effect_plugin_facts`).
  @effect_plugin_facts = nil
  @effect_plugin_facts_ancestry = nil
  # ADR-103 WD1 invariant 3 / #385 — `--no-tolerated-effects`, the audit switch. It changes the
  # JUDGMENT only: collection, the propagated table and the cache identity are all untouched, so an
  # audit run and an ordinary one share a cache entry and differ solely in which lane the envelope
  # check reads.
  @no_tolerated_effects = no_tolerated_effects
  @file_effects = {}
  @effect_table = nil
  @effects_served_from_cache = false
  @run_dependency_descriptor = nil
  # Memoised activation decision for the `call.self-undefined-method` rule (nil = not yet computed).
  # See `self_undefined_rule_active?`.
  @self_undefined_rule_active = nil
  @analyzed_files = [].freeze
  # In-memory source map for `#run_source` — `{ logical_path => source String }`. When set,
  # `parse_source` reads bytes from here instead of disk and `expand_paths` accepts the (possibly
  # non-existent) logical path. nil on a normal disk-backed run.
  @in_memory_sources = nil
  # ADR-46 slice 2 — the subset-analysis hook. When set (a collection of paths), the whole-project
  # pre-pass still runs over every file (so the cross-file index is complete), but only files in this
  # set are analyzed for diagnostics — the body tier re-analyses the affected closure and serves the
  # rest from the per-file cache. `nil` (the default) analyzes everything.
  @analyze_only = analyze_only && Set.new(analyze_only)
  # ADR-85 WD2 — seed-bundle discovery. When `collect_seed_bundles`, the cross-file discovery pre-pass
  # rebuilds from the prior run's per-file bundles (`@restored_seed_bundles`, re-walking only changed
  # files) instead of parsing every file, and exposes the refreshed set via `#seed_bundles` for the
  # session to persist. Off by default — a plain `rigor check` keeps today's parse+walk.
  @collect_seed_bundles = collect_seed_bundles
  @restored_seed_bundles = seed_bundles || {}
  @seed_bundles = {}.freeze
  # ADR-67 WD6c lift — a precomputed inferred-param table. When the incremental session already ran the
  # collector (it must, to diff the table against its snapshot BEFORE deciding the re-analyse closure),
  # it hands the result here so `seed_parameter_inference` seeds without a second whole-project collect
  # — and so the table the diff was decided on and the table this run seeds from are the SAME object,
  # not merely an equal recomputation. nil (the default) keeps the runner self-sufficient.
  @param_inferred_types_override = param_inferred_types
  # Issue #260 — the opt-in cross-file discovery seed (see the `discovery_seed:` doc above). Frozen and
  # never mutated; `project_scope_seed_tables` starts from a copy of it and lets any table this run
  # actually computed win.
  @discovery_seed = discovery_seed&.freeze
  @file_dependencies = {}
  @plugin_registry = Plugin::Registry::EMPTY
  @dependency_source_index = DependencySourceInference::Index::EMPTY
  @rbs_extended_reporter = RbsExtended::Reporter.new
  @boundary_cross_reporter = DependencySourceInference::BoundaryCrossReporter.new
  @source_rbs_synthesis_reporter = Plugin::SourceRbsSynthesisReporter.new
  # `#run` resets these for each invocation; pre-seed them to empty containers so `build_run_stats` /
  # `pre_file_diagnostics` (private, called only from `#run`) can read them without nil-guards. The
  # four end-of-pass snapshots (RBS class / signature-path tables, synthesized-namespace names,
  # `rigor:v1:conforms-to` results) live in one shared mutable {RunSnapshots} sink so the analysis
  # path that writes them and the run / aggregator code that reads them stay in separate
  # collaborators without a back-reference cycle.
  @snapshots = RunSnapshots.new
  @cached_plugin_prepare_diagnostics = [].freeze
  @project_discovered_classes = {}.freeze
  @project_discovered_def_nodes = {}.freeze
  @project_discovered_singleton_def_nodes = {}.freeze
  @project_discovered_def_sources = {}.freeze
  @project_discovered_singleton_def_sources = {}.freeze
  @project_discovered_superclasses = {}.freeze
  @project_discovered_includes = {}.freeze
  @project_discovered_class_sources = {}.freeze
  @project_discovered_method_visibilities = {}.freeze
  @project_discovered_methods = {}.freeze
  @project_data_member_layouts = {}.freeze
  @project_struct_member_layouts = {}.freeze
  # ADR-67 WD6a — the call-site parameter-inference table, populated by the opt-in pre-pass in
  # `assemble_run_diagnostics` when `parameter_inference:` is enabled, then seeded onto every per-file
  # scope (sequential + fork-worker) through `project_scope_seed_tables`. Empty by default, so the gate-off
  # run carries no table and is byte-identical.
  @project_param_inferred_types = {}.freeze
  # Issue #352 / ADR-17 — the `pre_eval:` constant publication table, populated by
  # `seed_pre_eval_constants` in `assemble_run_diagnostics` and seeded onto every per-file scope
  # (sequential + fork-worker) through `project_scope_seed_tables`. Empty unless the project lists
  # `pre_eval:` files that declare publishable constants, so a project without one is byte-identical.
  @project_pre_eval_constants = {}.freeze
  # ADR-84 WD2 — per-run identity token for the user-method return memo's bucket (see
  # Scope::DiscoveryIndex#run_generation). Minted fresh in `run_analysis` so the memo never serves an
  # entry across a run boundary (LSP re-check, ADR-62 warm loop); nil until the first run so
  # runner-less probes keep the per-file fallback.
  @run_generation = nil
  build_collaborators
end

    		
  





  



  

    
Instance Attribute Details

    
      
      
      

  

  
    #analyzed_files  ⇒ Array[String]  (readonly)
  

  

  


  

    
Returns the value of attribute analyzed_files.


  





  

Returns:


    
  
    
  • 
      
      
        (Array[String])
      
      
      
    
    • 
  





  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def analyzed_files
  @analyzed_files
end

    		
  





    
      
      
      

  

  
    #boundary_cross_reporter  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute boundary_cross_reporter.


  





  



  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def boundary_cross_reporter
  @boundary_cross_reporter
end

    		
  





    
      
      
      

  

  
    #buffer  ⇒ Object  (readonly)
  

  

  


  

    
ADR-pending editor mode — present when the runner is wired for the --tmp-file / --instead-of
buffer-binding shape (docs/design/20260516-editor-mode.md). Nil for normal project runs.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


328
329
330

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 328

def buffer
  @buffer
end

    		
  





    
      
      
      

  

  
    #cache_store  ⇒ Object  (readonly)
  

  

  


  

    
Rigor::Cache::Store itself is not yet sig-covered (the
cache namespace is in UNSIGNED_NAMESPACES per
spec/rigor/public_api_drift_spec.rb), so reference it as
untyped until the full Cache::Store sig lands. Steep
otherwise raises RBS::UnknownTypeName for the named type.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


121
122
123

    		
    
      
# File 'sig/rigor.rbs', line 121

def cache_store
  @cache_store
end

    		
  





    
      
      
      

  

  
    #dependency_source_index  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute dependency_source_index.


  





  



  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def dependency_source_index
  @dependency_source_index
end

    		
  





    
      
      
      

  

  
    #file_dependencies  ⇒ Hash[String, untyped]  (readonly)
  

  

  


  

    
ADR-46 — the per-file cross-file read records this run captured (empty unless
record_dependencies: true). Sequential analysis records into @file_dependencies via
#analyze_file; the fork pool records per-worker and marshals the records into the coordinator, so a
pooled --incremental recheck refreshes the same dependency graph a sequential recheck would. A run
is either sequential OR pooled for a given file set, so the two maps never carry the same key.


  





  

Returns:


    
  
    
  • 
      
      
        (Hash[String, untyped])
      
      
      
    
    • 
  





  

    
      


74
75
76
77

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 74

def file_dependencies
  pooled = @pool_coordinator.collected_dependencies
  pooled.empty? ? @file_dependencies : @file_dependencies.merge(pooled)
end

    		
  





    
      
      
      

  

  
    #plugin_registry  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute plugin_registry.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def plugin_registry
  @plugin_registry
end

    		
  





    
      
      
      

  

  
    #rbs_extended_reporter  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute rbs_extended_reporter.


  





  



  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def rbs_extended_reporter
  @rbs_extended_reporter
end

    		
  





    
      
      
      

  

  
    #seed_bundles  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute seed_bundles.


  





  



  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def seed_bundles
  @seed_bundles
end

    		
  





    
      
      
      

  

  
    #unresolved_self_calls  ⇒ Object  (readonly)
  

  

  


  

    
Returns the value of attribute unresolved_self_calls.


  





  



  

    
      


65
66
67

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 65

def unresolved_self_calls
  @unresolved_self_calls
end

    		
  





    
  



  

    
Class Method Details


    
      

  

  
    .prism_supported_floor  ⇒ String? 
  

  

  


  

    
Returns the lowest target_ruby this Prism build accepts, or nil if none of the
ladder parses. Memoised per process (the value is constant for a given Prism).


  





  

Returns:


    
  
    
  • 
      
      
        (String, nil)
      
      
      
        —
        
    the lowest target_ruby this Prism build accepts, or nil if none of the
ladder parses. Memoised per process (the value is constant for a given Prism).
    
      
    
    • 
  





  

    
      


1125
1126
1127
1128
1129
1130
1131
1132

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 1125

def self.prism_supported_floor
  @prism_supported_floor ||= PRISM_VERSION_LADDER.find do |candidate|
    Prism.parse("nil", version: candidate)
    true
  rescue ArgumentError
    false
  end
end

    		
  





    
  


  

    
Instance Method Details


    
      

  

  
    #adopt_effect_collections(collections)  ⇒ Object 
  

  

  


  

    
Issue #382 — adopt persisted collections as this run's own and close the graph over them. The
warm-hit half of the whole-run effects slot: the analysis did not run, so #assemble_run_diagnostics
never reached #close_effect_graph and the fixpoint is run here instead. The fixpoint is ALWAYS
re-run rather than persisted — it is the cheap half, and a stored table would have to be invalidated
by every input a summary has.


  





  



  

    
      


137
138
139
140

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 137

def adopt_effect_collections(collections)
  @file_effects = collections
  close_effect_graph
end

    		
  





    
      

  

  
    #analysis_file_set(paths = @configuration.paths)  ⇒ Array[String] 
  

  

  


  

    
ADR-46 — the project file set that a run over paths would analyze, computed by globbing only (no
RBS environment build), so the incremental fingerprint can be derived cheaply on the warm path
before deciding whether to build the env at all.


  





  
Parameters:


    
  
    
  • 
      
        paths
      
      
        (Array[String])
      
      
        (defaults to: @configuration.paths)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array[String])
      
      
      
    
    • 
  





  

    
      


418
419
420

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 418

def analysis_file_set(paths = @configuration.paths)
  expand_paths(paths).fetch(:files)
end

    		
  





    
      

  

  
    #analyzed_file_entries(expansion)  ⇒ Object 
  

  

  


  

    
      


972
973
974
975
976
977
978
979

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 972

def analyzed_file_entries(expansion)
  expansion.fetch(:files).map do |path|
    physical = @buffer ? @buffer.resolve(path) : path
    # ADR-87 WD1 — validation-only dependency descriptor, so the stat-then-digest `:stat` comparator
    # applies (the env-cache KEY files stay `:digest`).
    Cache::Descriptor::FileEntry.stat(path: physical, digest: Cache::FileDigest.hexdigest(physical))
  end
end

    		
  





    
      

  

  
    #assemble_run_diagnostics(expansion, environment: nil)  ⇒ Object 
  

  

  


  

    
      


808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 808

def assemble_run_diagnostics(expansion, environment: nil)
  # Force the deferred cross-file discovery pre-pass on the analysis (miss) path. Memoised, so the
  # eager force in `#run` (recording / subset modes) makes this a no-op. A warm cache HIT never calls
  # `assemble_run_diagnostics`, so it never runs the two whole-project parse passes. Runs over the FULL
  # expansion — subset (`analyze_only`) mode still needs the complete cross-file index (ADR-46 §2).
  ensure_project_discovery(expansion)
  # ADR-67 WD6a — the opt-in call-site parameter-inference pre-pass. Runs on the parent BEFORE the pool
  # split (so every worker sees the same frozen table — the seed-before-fork determinism the discovery
  # tables use) and only on the analysis (miss / non-cacheable) path (a warm ADR-45 cache HIT never
  # assembles). Gate off → no-op, and `environment` is left untouched so its lazy build timing is
  # unchanged. Returns the resolved environment so the sequential dispatch reuses it (no double build).
  environment = seed_parameter_inference(expansion, environment)
  # Issue #352 — the `pre_eval:` constant publication pre-pass. Same placement rationale as the line
  # above: it runs on the parent BEFORE the pool split so every worker sees the same frozen table, and
  # only on the analysis (miss) path. No `pre_eval:` entry → no-op, and `environment` passes through
  # untouched so its lazy build timing is unchanged.
  environment = seed_pre_eval_constants(expansion, environment)
  diagnostics = @diagnostic_aggregator.pre_file_diagnostics(expansion)
  # ADR-46 — record which project files this run actually analyzed (the `analyze_only` subset, or
  # all of them). The incremental orchestrator serves every analyzed-but-not-affected file from the
  # per-file cache, so it needs the full analyzed set to subtract the affected closure from.
  targets = target_files(expansion)
  @analyzed_files = targets
  diagnostics += @pool_coordinator.analyze_files(targets, environment: environment)
  # ADR-103 WD12 — the effect fixpoint, in the post-pool aggregation slot beside the conformance
  # results. Graph-only over a finite lattice, so it is a plain worklist to a true fixpoint; it
  # contributes NO diagnostics and its result leaves through `#effect_table`, never through the
  # stream. Skipped entirely when collection did not run.
  close_effect_graph
  diagnostics += @diagnostic_aggregator.rbs_quarantined_signature_diagnostics
  diagnostics += @diagnostic_aggregator.rbs_environment_build_failed_diagnostics
  diagnostics += @diagnostic_aggregator.rbs_synthesized_namespace_diagnostics
  diagnostics += @diagnostic_aggregator.conforms_to_diagnostics
  diagnostics += @diagnostic_aggregator.rbs_extended_reporter_diagnostics
  diagnostics += @diagnostic_aggregator.boundary_cross_diagnostics
  diagnostics + @diagnostic_aggregator.source_rbs_synthesis_diagnostics
end

    		
  





    
      

  

  
    #build_run_dependency_descriptor(expansion, rbs_descriptor)  ⇒ Object 
  

  

  


  

    
      


960
961
962
963
964
965
966
967
968
969
970

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 960

def build_run_dependency_descriptor(expansion, rbs_descriptor)
  entries = analyzed_file_entries(expansion) + pre_eval_file_entries + rbs_descriptor.files
  @plugin_registry.plugins.each do |plugin|
    # Read the boundary WITHOUT triggering its lazy `@io_boundary ||=` initializer: plugin instances
    # are frozen after the run, and a plugin that never built a boundary read no files through it,
    # so it contributes no dependencies.
    boundary = plugin.instance_variable_get(:@io_boundary)
    entries.concat(boundary.cache_descriptor.files) if boundary
  end
  Cache::Descriptor.new(files: entries)
end

    		
  





    
      

  

  
    #class_declarations  ⇒ Object 
  

  

  


  

    
ADR-46 slice 3 — per-file set of the qualified class/module names declared in that file. Used to
detect a class that appeared in an edit so a subclass whose ancestor was previously undefined
(and so recorded a negative class edge) is re-checked. Inverts the project class-source attribution
(class → declaring files).


  





  



  

    
      


476
477
478
479
480
481
482

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 476

def class_declarations
  result = Hash.new { |hash, key| hash[key] = Set.new }
  @project_discovered_class_sources.each do |class_name, files|
    files.each { |file| result[file] << class_name }
  end
  result.transform_values(&:freeze).freeze
end

    		
  





    
      

  

  
    #close_effect_graph  ⇒ Object 
  

  

  


  

    
ADR-103 WD13 — fail-soft at the run level too: a propagator that raises leaves the table empty and
the run untouched. Propagator.propagate already swallows its own failures; this guards the merge.


  





  



  

    
      


792
793
794
795
796
797
798

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 792

def close_effect_graph
  return unless @record_effects

  @effect_table = Effects::Propagator.propagate(effect_collection, discharge: effect_discharge)
rescue StandardError
  @effect_table = Effects::EffectTable.empty
end

    		
  





    
      

  

  
    #collect_param_inference_table(files)  ⇒ Object 
  

  

  


  

    
ADR-67 WD6c lift — computes the whole-project inferred-param table without running an analysis.
The incremental session calls this BEFORE deciding its re-analyse closure: the table's diff against
the snapshot's stored table is what invalidates a callee whose seeds moved because a caller file
changed. Same collector invocation as #seed_parameter_inference (one round, same workers), so the
session-computed table and an in-run collect are byte-identical by construction. Fails soft to the
empty table — which the caller's diff then treats as "every stored entry removed", the conservative
direction (those callees re-check).


  





  



  

    
      


498
499
500
501
502
503
504
505
506
507
508

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 498

def collect_param_inference_table(files)
  return {}.freeze unless @configuration.parameter_inference

  environment = @pool_coordinator.resolve_sequential_environment(source_files: files)
  Inference::ParameterInferenceCollector.collect(
    files: files, environment: environment,
    target_ruby: @configuration.target_ruby, max_rounds: 1, workers: @workers
  )
rescue StandardError
  {}.freeze
end

    		
  





    
      

  

  
    #collect_return_summaries(result, nodes, sources, separator, memo, effects_evaluator)  ⇒ Object 
  

  

  


  

    
Folds one def-node/def-source table pair's memo entries into the return-summary result under
separator. A live def node (a cold / re-walked file) is the identity every cross-file caller
resolved through, so memo[node] holds those callers' observed keys; a DefHandle (an unchanged
file on the warm path) never keyed a memo entry, so it is skipped (its summary is carried over from
the snapshot). Bounded per def and in total so the snapshot stays small.


  





  



  

    
      


536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 536

def collect_return_summaries(result, nodes, sources, separator, memo, effects_evaluator)
  nodes.each do |class_name, methods|
    methods.each do |method_name, node|
      next if node.is_a?(Inference::DefHandle)

      entries = memo[node]
      next if entries.nil? || entries.empty?

      path_line = sources.dig(class_name, method_name)
      next if path_line.nil?

      break if result.size >= RETURN_SUMMARY_TOTAL_CAP

      capped = entries.first(RETURN_SUMMARY_KEYS_PER_DEF)
      result[[path_line.split(":", 2).first, "#{class_name}#{separator}#{method_name}"]] = {
        keys: capped.map { |entry| [entry.receiver, entry.arg_types] },
        returns: capped.map { |entry| entry.result.describe(:short) },
        effects: content_effects(effects_evaluator, node)
      }
    end
  end
end

    		
  





    
      

  

  
    #compute_run_diagnostics(expansion)  ⇒ Object 
  

  

  


  

    
ADR-45 — unchanged-project fast path. Serves the whole run's (pre-severity-profile) diagnostics
from one record-and-validate cache entry when every file the previous run read is unchanged,
skipping the dominant per-file inference. The dependency set is collected AFTER the run (so it
captures files the plugins read mid-analysis, e.g. a Pundit policy) and re-validated on the next
run; the entry is keyed on the inputs known up front (config, gem / engine versions, analyzed-path
set).


  





  



  

    
      


623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 623

def compute_run_diagnostics(expansion)
  @run_served_from_cache = false
  return assemble_run_diagnostics(expansion) unless run_result_cacheable?

  environment = @pool_coordinator.resolve_sequential_environment(source_files: target_files(expansion))
  # Lazy-files descriptor: the cache KEY reads only `gems` + `configs`; the RBS signature-tree `files`
  # are digested solely by `run_dependency_descriptor` on a MISS, so a warm HIT never walks the tree.
  rbs_descriptor = if environment&.rbs_loader
                     Cache::RbsDescriptor.build_run(environment.rbs_loader)
                   else
                     Cache::Descriptor.new
                   end
  @run_environment = environment
  key_descriptor = run_key_descriptor(expansion, rbs_descriptor)
  return assemble_run_diagnostics(expansion, environment: environment) if key_descriptor.nil?

  # ADR-103 WD13 / #382 — the effects slot is consulted FIRST, because it is the one that can force
  # the analysis: a missing or differently-identified sidecar is a miss for effects consumers only,
  # and the only way to re-collect is to re-analyze. When it hits (or collection is off) this returns
  # nil and the diagnostics slot decides on its own, exactly as it did before effects existed.
  analysis = serve_effect_collections(expansion, environment, key_descriptor, rbs_descriptor)
  computed = false
  diagnostics = @cache_store.fetch_or_validate(
    producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID, key_descriptor: key_descriptor,
    generation_cap: RunCacheKey::GENERATION_CAP
  ) do
    computed = true
    diags = analysis || assemble_run_diagnostics(expansion, environment: environment)
    [diags, run_dependency_descriptor(expansion, rbs_descriptor)]
  end
  # An effects miss that ran the analysis is not a cache-served run even when the diagnostics slot
  # then hit — the stats it would otherwise suppress were all gathered.
  @run_served_from_cache = !computed && analysis.nil?
  diagnostics
rescue StandardError
  # The result cache must never break a run. If anything in the cache path fails, fall back to a
  # direct, uncached analysis.
  @run_served_from_cache = false
  assemble_run_diagnostics(expansion)
end

    		
  





    
      

  

  
    #content_effects(effects_evaluator, node)  ⇒ Object 
  

  

  


  

    
The content-mutated parameter positions of node, or [] if the computation raises (defensive: the
effects surface only routes attention, never soundness — a missing set reads as "no floor").


  





  



  

    
      


561
562
563
564
565

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 561

def content_effects(effects_evaluator, node)
  effects_evaluator.content_mutated_parameter_positions(node)
rescue StandardError
  []
end

    		
  





    
      

  

  
    #effect_collection  ⇒ Object 
  

  

  


  

    
The merged per-file collections behind #effect_table — the direct summaries, before the graph
closure. #381's snapshot records these, because a diff over direct summaries stays attributable to
the pull request's own lines.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


119
120
121

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 119

def effect_collection
  Effects::FileCollection.merge_all(effect_collections)
end

    		
  





    
      

  

  
    #effect_collections_by_path  ⇒ Object 
  

  

  


  

    
Issue #382 — the same collections keyed by the path that produced each, which is the form the two
caches persist: { "lib/a.rb" => FileCollection, … }. The merged #effect_collection cannot be
persisted per file (merging is where the path is deliberately dropped), and per file is what an
ADR-46 recheck needs — it re-collects the changed closure and serves the rest from the snapshot.


  





  



  

    
      


127
128
129
130

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 127

def effect_collections_by_path
  pooled = @pool_coordinator.collected_effects
  pooled.empty? ? @file_effects.dup : @file_effects.merge(pooled)
end

    		
  





    
      

  

  
    #effect_discharge  ⇒ Object 
  

  

  


  

    
ADR-103 WD14 / #385 — the effects.tolerated: policy the propagator's second (undischarged) lane
is computed under. Built from the configuration and never from the audit flag: BOTH lanes are in
the table, and --no-tolerated-effects picks the other one at judgment time, so one fixpoint
serves an audit run and an ordinary one alike.


  





  



  

    
      


804
805
806

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 804

def effect_discharge
  @effect_discharge ||= Effects::Discharge.new(@configuration.effects_tolerated)
end

    		
  





    
      

  

  
    #effect_plugin_facts  ⇒ Object 
  

  

  


  

    
#387 — the loaded plugins' compiled effect contributions, read by rigor effects so the snapshot's
vocabulary is the one the collection window scanned under. Same untyped reasoning again.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


106
107
108
109
110
111
112
113
114

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 106

def effect_plugin_facts
  table = @project_discovered_superclasses
  return @effect_plugin_facts if @effect_plugin_facts && @effect_plugin_facts_ancestry.equal?(table)

  @effect_plugin_facts_ancestry = table
  @effect_plugin_facts = Effects::PluginFacts.build(
    @plugin_registry, superclasses: table, includes: @project_discovered_includes
  )
end

    		
  





    
      

  

  
    #effect_sources  ⇒ Object 
  

  

  


  

    
#381 — { "Class#m" => [path] }, which the snapshot's reach: globs match against. Same
untyped reasoning as its two siblings above.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


156
157
158
159
160
161
162
163

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 156

def effect_sources
  effect_collections.each_with_object({}) do |collection, out|
    path = collection.path
    next if path.nil?

    collection.summaries.each_key { |key| (out[key] ||= []) << path }
  end
end

    		
  





    
      

  

  
    #effect_table  ⇒ Object 
  

  

  


  

    
ADR-103 — the propagated effect graph and the merged per-file collections behind it. A report
surface: never a diagnostic, empty when the configuration carries no effects: block. Typed
untyped for the same reason cache_store is — Rigor::Effects is not sig-covered yet
(spec/rigor/public_api_drift_spec.rb), and a named reference would raise RBS::UnknownTypeName.


  





  

Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


85
86
87

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 85

def effect_table
  @effect_table || Effects::EffectTable.empty
end

    		
  





    
      

  

  
    #effects_served_from_cache?  ⇒ Boolean 
  

  

  


  

    
Issue #382 — whether this run's effect collections came from the whole-run effects slot rather than
from a fresh collection pass. Read by the specs and by nothing in the engine; #effect_table reads
the same either way, which is the property the slot exists to provide.


  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  





  

    
      


145
146
147

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 145

def effects_served_from_cache?
  @effects_served_from_cache
end

    		
  





    
      

  

  
    #evaluate_return_types(paths, specs)  ⇒ Hash 
  

  

  


  

    
ADR-89 WD2 — re-evaluate the return type of specific project methods at previously-observed call keys,
WITHOUT analyzing any file. The incremental session calls this session-side (before dispatching the
recheck) to prove a declaration-stable, changed callee returns the same type at every key its baseline
callers used, so those callers' re-analysis can be skipped. Builds the cross-file discovery index (the
ADR-85 seed-bundle fold, re-walking only edited files) and the RBS environment (served from the cache
store) exactly as a real run's setup does, then re-drives each spec's def through the ADR-84 return
memo. Off any hot path — invoked only when declaration-stable changed pairs carry a persisted summary.


  





  
Parameters:


    
  
    
  • 
      
        paths
      
      
        (Array<String>, nil)
      
      
      
        —
        
    analysis roots (nil → the configuration's paths:).
    
      
    
    • 
  
    
  • 
      
        specs
      
      
        (Array<Hash>)
      
      
      
        —
        
    each { class_name:, method_name:, singleton:, keys: [[receiver, args], …] }.
    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Hash)
      
      
      
        —
        
    { [class_name, method_name, singleton] => [return_descriptor_or_nil, …] }.
    
      
    
    • 
  





  

    
      


578
579
580
581
582
583
584

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 578

def evaluate_return_types(paths, specs)
  return {} if specs.empty?

  Cache::FileDigest.with_run(strict: @configuration.cache_validation_strict?) do
    Inference::DefNodeResolver.with_run { evaluate_return_types_setup(paths, specs) }
  end
end

    		
  





    
      

  

  
    #evaluate_return_types_setup(paths, specs)  ⇒ Object 
  

  

  


  

    
Builds the discovery index + environment (a real run's prologue, minus per-file analysis) and
re-evaluates each spec's def. Extracted so #evaluate_return_types's with_run wrappers stay thin.


  





  



  

    
      


588
589
590
591
592
593
594
595
596
597
598

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 588

def evaluate_return_types_setup(paths, specs)
  expansion = expand_paths(paths || @configuration.paths)
  @project_discovery_done = false
  @run_generation = Object.new.freeze
  run_project_pre_passes(expansion: expansion)
  ensure_project_discovery(expansion)
  environment = @pool_coordinator.resolve_sequential_environment(source_files: target_files(expansion))
  specs.to_h do |spec|
    [[spec[:class_name], spec[:method_name], spec[:singleton]], evaluate_spec_returns(spec, environment)]
  end
end

    		
  





    
      

  

  
    #evaluate_spec_returns(spec, environment)  ⇒ Object 
  

  

  


  

    
Re-evaluates one spec's def at each of its observed keys. Locates the (live) def node in the discovery
index, builds a project-seeded scope, and returns one return descriptor per key (nil when the def is
missing / bodyless or the memo refuses a transient result — the caller reads either as "not provably
stable" and keeps the dependents).


  





  



  

    
      


604
605
606
607
608
609
610
611
612
613
614
615

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 604

def evaluate_spec_returns(spec, environment)
  table = spec[:singleton] ? @project_discovered_singleton_def_nodes : @project_discovered_def_nodes
  node = table.dig(spec[:class_name], spec[:method_name])
  node = Inference::DefNodeResolver.resolve(node) if node.is_a?(Inference::DefHandle)
  return spec[:keys].map { nil } if node.nil?

  scope = seed_project_scope(Scope.empty(environment: environment, source_path: spec[:path]))
  spec[:keys].map do |(receiver, arg_types)|
    result = scope.user_method_return(node, receiver, arg_types)
    result&.describe(:short)
  end
end

    		
  





    
      

  

  
    #file_dependents  ⇒ Hash[String, untyped] 
  

  

  


  

    
ADR-46 §2 — inverts #file_dependencies into the reverse edge the incremental step walks:
dependents[X] = { A : A read a declaration / body from X }. On an edit to X, the body tier
(slice 2) re-analyses {X} ∪ dependents[X] and serves every other file from the per-file cache.
Built on demand from the recorded sources sets (so it reflects whatever analyze_file captured —
empty unless the runner was constructed with record_dependencies: true). The negative (missing)
edges are NOT inverted here: they feed the structural tier (slice 3), which re-checks a consumer
when a name it looked up and did not resolve later appears.


  





  

Returns:


    
  
    
  • 
      
      
        (Hash[String, untyped])
      
      
      
    
    • 
  





  

    
      


429
430
431

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 429

def file_dependents
  Incremental.invert(file_dependencies.transform_values(&:sources))
end

    		
  





    
      

  

  
    #param_inferred_types  ⇒ Object 
  

  

  


  

    
ADR-67 WD6c lift — the inferred-param table this run seeded from (frozen; empty when
parameter_inference: is off or the pre-pass failed soft). The incremental session reads it back
after a baseline so the snapshot records the seeds the cached diagnostics were computed under.


  





  



  

    
      


487
488
489

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 487

def param_inferred_types
  @project_param_inferred_types
end

    		
  





    
      

  

  
    #pre_eval_file_entries  ⇒ Object 
  

  

  


  

    
Issue #352 — a pre_eval: file is a real input to the run's diagnostics: its defs populate the
ADR-17 patched-method registry and (since #352) its constants populate the project seed. ADR-17 WD5
permits listing a file under pre_eval: and NOT under paths:, and such a file never appears in the
expansion — so without this entry, editing one would leave the run-result cache serving diagnostics
computed against the previous version. The common case (a lib/core_ext/ file that is also under
paths:) contributes a duplicate entry, which the descriptor's per-path validation absorbs.


  





  



  

    
      


987
988
989
990
991
992
993
994

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 987

def pre_eval_file_entries
  @configuration.pre_eval.filter_map do |path|
    physical = @buffer ? @buffer.resolve(path) : path
    next unless File.file?(physical)

    Cache::Descriptor::FileEntry.stat(path: physical, digest: Cache::FileDigest.hexdigest(physical))
  end
end

    		
  





    
      

  

  
    #prepare_project_scan(paths: @configuration.paths)  ⇒ Object 
  

  

  


  

    
Runs every project-wide pre-pass (load_plugins +
plugin#prepare + dependency-source builder +
synthetic-method scanner + project-patched scanner)
exactly once, then returns a frozen
ProjectScan snapshot.


Long-lived integrations (Rigor::LanguageServer::ProjectContext)
call this once per project-state generation and feed the
snapshot back into Runner.new(prebuilt: scan) for every
subsequent per-buffer publish. The cold pre-pass cost is
paid once per generation rather than once per keystroke.


Notes for callers:


    

  • The runner this method is called on may be a "build only"
instance — @buffer is typically nil so the scanners
observe on-disk bytes for the full project. Callers that
want pre-passes to see a particular buffer's edits should
build the runner WITH buffer: set.
    • 

  • The returned ProjectScan is frozen and shareable; the
underlying plugin_registry is the same object that ran
#prepare, so the per-plugin services.fact_store is
already populated for subsequent dispatch use.
    • 



  





  
Parameters:


    
  
    
  • 
      
        paths:
      
      
        (Array[String])
      
      
        (defaults to: @configuration.paths)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Object)
      
      
      
    
    • 
  





  

    
      


1018
1019
1020
1021
1022
1023

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 1018

def prepare_project_scan(paths: @configuration.paths)
  expansion = expand_paths(paths)
  result = @pre_passes.run(expansion: expansion)
  apply_pre_passes_result(result)
  @pre_passes.build_project_scan(result)
end

    		
  





    
      

  

  
    #return_summaries  ⇒ Hash 
  

  

  


  

    
ADR-89 WD2 — the per-method observed-key return summaries the run's ADR-84 return memo just captured.
For each project method with live memo entries, a bounded { keys:, returns:, effects: } summary the
incremental session persists: keys the observed [receiver, arg_types] type tuples, returns their
describe(:short) descriptors, effects the content-mutated parameter positions (a caller-visible
arg-flooring surface). Only meaningful right after a run populated the memo (baseline / recheck),
before the bucket rolls. Keys are held live here; the session Marshals them for the snapshot.


  





  

Returns:


    
  
    
  • 
      
      
        (Hash)
      
      
      
        —
        
    { [path, "Class#method" | "Class.method"] => { keys:, returns:, effects: } }.
    
      
    
    • 
  





  

    
      


518
519
520
521
522
523
524
525
526
527
528
529

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 518

def return_summaries
  memo = Inference::ExpressionTyper.harvest_return_memo
  return {} if memo.empty?

  result = {}
  effects_evaluator = Inference::StatementEvaluator.new(scope: Scope.empty)
  collect_return_summaries(result, @project_discovered_def_nodes, @project_discovered_def_sources,
                           "#", memo, effects_evaluator)
  collect_return_summaries(result, @project_discovered_singleton_def_nodes,
                           @project_discovered_singleton_def_sources, ".", memo, effects_evaluator)
  result
end

    		
  





    
      

  

  
    #run(paths = @configuration.paths)  ⇒ Result 
  

  

  


  

    
Walks every Ruby file under paths, parses it, builds a per-node scope index through
Rigor::Inference::ScopeIndexer, and runs the Rigor::Analysis::CheckRules catalogue over it.
Returns a Rigor::Analysis::Result aggregating every produced diagnostic plus any Prism parse
errors. The Environment is built once at run start through Environment.for_project so all files
share the same RBS load.


  





  
Parameters:


    
  
    
  • 
      
        paths
      
      
        (Array[String])
      
      
        (defaults to: @configuration.paths)
      
      
    
    • 
  




Returns:





  

    
      


335
336
337
338
339
340
341
342
343
344
345
346

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 335

def run(paths = @configuration.paths)
  # One per-run file-digest memo spans the whole run, so a path is SHA-256'd at most once across the
  # run-diagnostics dependency descriptor, its `fresh?` validation, the RBS signature tree, and every
  # plugin producer's watched-glob validation (they overlap heavily on the warm path). The nested ADR-85
  # WD3 memo yields one stable `Prism::DefNode` per resolved bundle handle for the run (both are no-ops
  # outside their respective consumers — an empty thread-local table).
  # ADR-87 WD1 — `cache.validation` (or the RIGOR_STRICT_VALIDATION env, which wins) selects the
  # freshness path for this run; the `auto` default resolves strict in CI (#190), stat-first elsewhere.
  Cache::FileDigest.with_run(strict: @configuration.cache_validation_strict?) do
    Inference::DefNodeResolver.with_run { run_analysis(paths) }
  end
end

    		
  





    
      

  

  
    #run_analysis(paths)  ⇒ Object 
  

  

  


  

    
      


348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 348

def run_analysis(paths)
  Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
    @configuration.fold_platform_specific_paths

  wall_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

  target_ruby_error = validate_target_ruby
  return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error

  expansion = expand_paths(paths)
  @snapshots.reset_for_run
  # Per-run reset of the deferred-discovery memo (see `#ensure_project_discovery`).
  @project_discovery_done = false
  # Per-run reset of the environment the cacheable path resolves, reused by the envelope pass so a
  # run never builds two.
  @run_environment = nil
  # ADR-84 WD2 — roll the return-memo bucket: a fresh frozen token per run makes every per-file scope
  # of THIS run share one memo bucket while entries from any earlier run in this process (stale after
  # an edit) become unreachable.
  @run_generation = Object.new.freeze

  if @prebuilt
    adopt_prebuilt_project_scan(@prebuilt)
  else
    run_project_pre_passes(expansion: expansion)
  end

  # The recording / subset (ADR-46) modes read the discovery tables outside the analysis assembly, so
  # they force the build eagerly here (matching pre-slice-1 timing); every other mode defers it to the
  # miss path so a warm cache HIT skips the two whole-project parse passes entirely.
  ensure_project_discovery(expansion) if force_eager_discovery?

  diagnostics = compute_run_diagnostics(expansion)
  # ADR-103 WD12 / #383 — `effect.envelope-exceeded`, recomputed every run from the (possibly
  # cached) effect table and never stored. It sits OUTSIDE `compute_run_diagnostics` on purpose:
  # the `effects:` block is absent from the diagnostics cache identity, so a finding written into
  # that entry would outlive the configuration that produced it. See {EffectEnvelopePass}.
  diagnostics += effect_envelope_diagnostics(expansion)
  # ADR-103 WD13 commitment 1 / #384 — the mirror image: a project that wrote effect annotations
  # and NO `effects:` block. Same placement rationale (the block is absent from the diagnostics
  # cache identity, so a residual stored there would outlive the edit that answers it), and the
  # opposite gate, so exactly one of the two ever runs.
  diagnostics += effect_annotation_residual_diagnostics

  Result.new(
    diagnostics: @diagnostic_aggregator.apply_severity_profile(diagnostics),
    stats: stats_for_run(wall_started_at: wall_started_at, expansion: expansion)
  )
end

    		
  





    
      

  

  
    #run_dependency_descriptor(expansion, rbs_descriptor)  ⇒ Object 
  

  

  


  

    
Files the run actually depended on, collected AFTER it ran: every analyzed file, every RBS sig
file (rbs_descriptor.files), and every file each plugin read (complete post-run, so reads made
mid-analysis are included). Re-digested on the next run by Descriptor#fresh?.
Memoised because a collecting run asks twice — once to validate the effects sidecar it just wrote,
once for the diagnostics entry — and this is a whole-project stat + digest walk. Both asks happen
after the same analysis, so they are answering about the same world; a run with collection off asks
once and the memo is inert.


  





  



  

    
      


956
957
958

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 956

def run_dependency_descriptor(expansion, rbs_descriptor)
  @run_dependency_descriptor ||= build_run_dependency_descriptor(expansion, rbs_descriptor)
end

    		
  





    
      

  

  
    #run_key_descriptor(expansion, rbs_descriptor)  ⇒ Object 
  

  

  


  

    
Stable cache key inputs — known before the run: a digest of the resolved configuration, the engine


    

  • rbs versions + --explain, and the analyzed-path SET (adding/removing a file changes the key;
editing one is caught by dependency validation). nil disables the cache for this run rather than
risking a malformed key.
    • 



  





  



  

    
      


939
940
941
942
943
944
945
946
947

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 939

def run_key_descriptor(expansion, rbs_descriptor)
  # ADR-87 WD4 — the key is built through the shared {RunCacheKey} builder the boot-slimming probe also
  # uses, so the miss path (here, passing the loader's `rbs_descriptor.configs`) and the hit path (which
  # reconstructs `rbs.libraries` from config) can never drift out of key agreement.
  RunCacheKey.descriptor(
    configuration: @configuration, files: expansion.fetch(:files),
    explain: @explain, rbs_config_entries: rbs_descriptor.configs
  )
end

    		
  





    
      

  

  
    #run_result_cacheable?  ⇒ Boolean 
  

  

  


  

    
Cacheable only for a full sequential project run with a writable cache and no per-buffer /
prebuilt override — every other mode has a different result identity (pool workers read in
separate processes; editor mode is per-buffer; prebuilt is the LSP path).


The ADR-46 incremental modes are excluded too, now that they carry a real cache store (ADR-85
WD1): a record_dependencies run MUST perform per-file analysis to capture the dependency
graph (a cache-served run records nothing, leaving the next recheck's dependents empty —
unsound), and an analyze_only subset run produces intentionally partial diagnostics that
share the full run's result key (run_key_descriptor keys on the whole expansion, not the
subset), so serving one as the other would manufacture a wrong result. Both instead use the
store for the RBS-env + plugin-producer tiers, where the incremental win actually lives.
ADR-103 WD13 / issue #382 — a COLLECTING run is no longer excluded. It was, for the same reason a
record_dependencies run is (a cache-served run collects nothing, so #effect_table would come
back empty from a warm hit), and the sidecar slot is what lifts it: the collections ride their own
entry under their own identity, so a warm run restores them and re-runs only the fixpoint. A run
with collection OFF never reads or writes that slot and is byte-identical here.


  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  





  

    
      


929
930
931
932
933

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 929

def run_result_cacheable?
  !@cache_store.nil? && !@cache_store.read_only? &&
    @buffer.nil? && @prebuilt.nil? && !pool_mode? &&
    !@record_dependencies && @analyze_only.nil?
end

    		
  





    
      

  

  
    #run_source(source:, path: "(source).rb")  ⇒ Result 
  

  

  


  

    
Analyze a single source String in memory, without writing it to disk — a clean entry point for
embedders (LSP / editor mode) and a faster spec path than the per-call tmpdir + chdir. The source
is bound to path (purely a logical identity carried in diagnostic locations; it need not exist on
disk). The full run machinery still runs — environment build, plugin prepare, severity profile —
so the result matches a one-file disk run; only the cross-file project pre-pass is empty (there is
one file, and the per-file indexer self-discovers its own classes / defs).


  





  
Parameters:


    
  
    
  • 
      
        source
      
      
        (String)
      
      
      
        —
        
    Ruby source to analyze.
    
      
    
    • 
  
    
  • 
      
        path
      
      
        (String)
      
      
        (defaults to: "(source).rb")
      
      
        —
        
    logical path for diagnostic locations.
    
      
    
    • 
  
    
  • 
      
        source:
      
      
        (String)
      
      
      
    
    • 
  
    
  • 
      
        path:
      
      
        (String)
      
      
        (defaults to: "(source).rb")
      
      
    
    • 
  




Returns:





  

    
      


408
409
410
411
412
413

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 408

def run_source(source:, path: "(source).rb")
  @in_memory_sources = { path => source }
  run([path])
ensure
  @in_memory_sources = nil
end

    		
  





    
      

  

  
    #seed_parameter_inference(expansion, environment)  ⇒ Object 
  

  

  


  

    
ADR-67 WD6a — the check-walk parameter-inference pre-pass. Populates @project_param_inferred_types
(read by project_scope_seed_tables) with the call-site union of every undeclared parameter, running
ONE round (a single hop of call-site → param typing; the protection scan's three-round fixpoint stays a
protection-surface luxury until measured). No-op unless parameter_inference: is enabled, so the
default run pays exactly nothing here and environment passes through unchanged (preserving the lazy
env-build timing). When enabled, it resolves the environment once — the collector types call-site
arguments against the same RBS / plugin surface the check uses — and returns it so the sequential
dispatch reuses that build. The whole-project file set (not the analyze_only subset) is scanned: the
inference is cross-file (a call site in one file types a parameter in another). Fails soft — a collector
error must never break a run, so the table stays empty and the run proceeds unseeded.


  





  



  

    
      


856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 856

def seed_parameter_inference(expansion, environment)
  return environment unless @configuration.parameter_inference

  if @param_inferred_types_override
    @project_param_inferred_types = @param_inferred_types_override
    return environment
  end

  files = expansion.fetch(:files)
  environment ||= @pool_coordinator.resolve_sequential_environment(source_files: files)
  @project_param_inferred_types = Inference::ParameterInferenceCollector.collect(
    files: files, environment: environment,
    target_ruby: @configuration.target_ruby, max_rounds: 1, workers: @workers
  )
  environment
rescue StandardError
  @project_param_inferred_types = {}.freeze
  environment
end

    		
  





    
      

  

  
    #seed_pre_eval_constants(expansion, environment)  ⇒ Object 
  

  

  


  

    
Issue #352 / ADR-17 — the pre_eval: CONSTANT publication pre-pass, the twin of the slice-2 patched-
METHOD registry the eager pre-passes already build. Walks each listed file's constant writes with the
per-file pre-pass (Inference::ScopeIndexer.build_in_source_constants) under a project-seeded scope,
widens each result to its erased class, and populates @project_pre_eval_constants — which
project_scope_seed_tables then seeds onto every per-file scope, so TIMEOUT = 30 in a listed file
reads as Integer instead of Dynamic[top] in its consumers. The widening + multi-file conflict rules
live in Inference::PreEvalConstants.


Runs here rather than in Rigor::Analysis::Runner::ProjectPrePasses#run because typing a constant's rvalue needs the RBS
environment, which the eager pre-passes feed rather than consume. Fails soft — a collector error must
never break a run, so the table stays empty and the run proceeds exactly as it does today.


  





  



  

    
      


887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 887

def seed_pre_eval_constants(expansion, environment)
  paths = @configuration.pre_eval.select { |path| File.file?(path) }
  return environment if paths.empty?

  environment ||= @pool_coordinator.resolve_sequential_environment(source_files: expansion.fetch(:files))
  @project_pre_eval_constants = Inference::PreEvalConstants.collect(
    paths: paths, target_ruby: @configuration.target_ruby, buffer: @buffer,
    scope_builder: lambda { |path|
      seed_project_scope(Scope.empty(environment: environment, source_path: path))
    }
  )
  environment
rescue StandardError
  @project_pre_eval_constants = {}.freeze
  environment
end

    		
  





    
      

  

  
    #stats_for_run(wall_started_at:, expansion:)  ⇒ Object 
  

  

  


  

    
A cache hit skipped the analysis, so the per-run stats (wall split, RBS-class counts, …) were never
gathered — report none rather than the stale snapshot defaults.


  





  



  

    
      


906
907
908
909
910
911

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 906

def stats_for_run(wall_started_at:, expansion:)
  return nil unless @collect_stats
  return nil if @run_served_from_cache

  build_run_stats(wall_started_at: wall_started_at, expansion: expansion)
end

    		
  





    
      

  

  
    #symbol_fingerprints  ⇒ Object 
  

  

  


  

    
ADR-46 slice 4 — per-symbol body fingerprints, computed from the project pre-pass def index. Returns
a frozen hash of the form:


{ "path/to/file.rb" => { "ClassName#method" => sha256_hex, … }, … }



Used by IncrementalSession to detect which symbols in a changed file actually changed
bodies, so only callers of those specific symbols are re-checked. Only meaningful after a run that
populated @project_discovered_def_nodes (i.e. any full or subset analysis); returns an empty
frozen hash before the first run.


  





  



  

    
      


440
441
442
443
444
445
446
447
448
449

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 440

def symbol_fingerprints
  result = Hash.new { |h, k| h[k] = {} }
  collect_symbol_fingerprints(result, @project_discovered_def_sources, @project_discovered_def_nodes, "#")
  # ADR-46 slice 4 (singleton) — class/singleton-method bodies live in the parallel singleton tables the
  # instance loop never read (recon S5). Fingerprint them under a `"Class.method"` key (the format the
  # `singleton_def_for` dependency edge uses) so a `def self.x` body edit produces a changed pair.
  collect_symbol_fingerprints(result, @project_discovered_singleton_def_sources,
                              @project_discovered_singleton_def_nodes, ".")
  result.transform_values(&:freeze).freeze
end

    		
  





    
      

  

  
    #validate_target_ruby  ⇒ Object 
  

  

  


  

    
target_ruby flows through to Prism's version: option. Prism enforces the supported range and
raises ArgumentError for versions it does not recognise. Run a one-time smoke parse here so a
misconfigured target_ruby surfaces as a single project-level diagnostic instead of crashing the
whole run on the first file — and name the supported floor + where to read the right value, so the
fix is obvious without a guess-and-retry loop.


  





  



  

    
      


1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154

    		
    
      
# File 'lib/rigor/analysis/runner.rb', line 1139

def validate_target_ruby
  Prism.parse("nil", version: @configuration.target_ruby)
  nil
rescue ArgumentError => e
  floor = self.class.prism_supported_floor
  Diagnostic.new(
    path: ".rigor.yml", line: 1, column: 1,
    message: "target_ruby #{@configuration.target_ruby.inspect} is not supported by this Rigor build " \
             "(Prism accepts #{floor} and newer). Set target_ruby to your project's Ruby version " \
             "(>= #{floor}) — read it from Gemfile.lock's `RUBY VERSION` or .ruby-version. " \
             "(Prism: #{e.message})",
    severity: :error,
    rule: "configuration-error",
    source_family: :builtin
  )
end