rigortype 0.1.15 → 0.1.17

data/lib/rigor/cli.rb

@@ -9,6 +9,7 @@ require_relative "configuration"
 require_relative "version"
 require_relative "analysis/diagnostic"
 require_relative "analysis/result"
+require_relative "cli/options"
 
 module Rigor
   # The CLI class is a dispatcher: each `run_*` method delegates to a
@@ -77,20 +78,19 @@ module Rigor
       EXIT_USAGE
     end
 
-    def run_check
-      require_relative "analysis/runner"
-      require_relative "analysis/buffer_binding"
-      require_relative "analysis/baseline"
-      require_relative "cache/store"
-
+    def run_check # rubocop:disable Metrics/AbcSize
+      load_check_dependencies
       options = parse_check_options
-      buffer = resolve_buffer_binding(options)
+      buffer = Options.resolve_buffer_binding(options, err: @err)
       return EXIT_USAGE if buffer == :usage_error
 
       configuration = load_check_configuration(options)
       cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
+      special = dispatch_special_check_mode(configuration, options, cache_root)
+      return special unless special.nil?
+
       runner = build_check_runner(
         configuration: configuration, options: options,
         buffer: buffer, cache_root: cache_root
@@ -100,6 +100,8 @@ module Rigor
 
       write_result(result, options.fetch(:format))
       write_run_stats(result.stats) if result.stats
+      write_trace_appendices
+      runner.cache_store&.evict!
       write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
 
       exit_code = result.success? ? 0 : 1
@@ -107,6 +109,95 @@ module Rigor
       exit_code
     end
 
+    # ADR-46 — the two incremental-analysis check modes both fully handle
+    # the run and return an exit code (so `run_check` short-circuits);
+    # returns nil for an ordinary check.
+    def dispatch_special_check_mode(configuration, options, cache_root)
+      return run_verify_incremental(configuration) if options.fetch(:verify_incremental)
+      return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
+
+      nil
+    end
+
+    # ADR-46 — the incremental-analysis acceptance gate. Runs a baseline
+    # analysis (recording cross-file dependencies), then re-analyzes a
+    # representative subset of files and serves the rest from the per-file
+    # cache (the body tier), and asserts the merged diagnostics are
+    # byte-identical to a full `--no-cache` analysis. A mismatch means the
+    # incremental machinery would serve a stale — manufactured —
+    # diagnostic, the soundness failure this gate exists to catch. Prints a
+    # one-line PASS (exit 0) or the differing diagnostics (exit 1).
+    def run_verify_incremental(configuration)
+      paths = @argv.empty? ? nil : @argv
+      session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
+      session.baseline
+      analyzed = session.analyzed_files
+
+      # Every other file forms the re-analyzed subset, so the run exercises
+      # BOTH the subset-analysis path and the cache-serving path.
+      subset = analyzed.each_with_index.select { |_, index| index.even? }.map(&:first)
+      incremental = normalize_diagnostics(session.reanalyze_subset(subset))
+      full = normalize_diagnostics(verify_full_diagnostics(configuration, paths))
+
+      report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size)
+    end
+
+    # ADR-46 — cross-process incremental analysis (`--incremental`). Derives
+    # the global fingerprint cheaply (no RBS env build), loads the disk
+    # snapshot, and on a fingerprint hit re-analyzes only the files changed
+    # since the last run (plus their dependents), serving the rest from the
+    # snapshot; on a miss runs a full baseline. Persists the updated
+    # snapshot for the next invocation. Diagnostics are identical to a full
+    # run (the `--verify-incremental` gate enforces this); the win is
+    # skipping per-file inference for unchanged files.
+    def run_incremental_check(configuration, options, cache_root)
+      paths = @argv.empty? ? nil : @argv
+      probe = Analysis::Runner.new(configuration: configuration, cache_store: nil)
+      files = paths ? probe.analysis_file_set(paths) : probe.analysis_file_set
+      fingerprint = Cache::IncrementalSnapshot.fingerprint(
+        configuration: configuration, roots: paths || configuration.paths
+      )
+      snapshot = Cache::IncrementalSnapshot.new(root: cache_root)
+      session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
+
+      diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
+      @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
+                "(#{files.size} files)")
+
+      result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration, options)
+      write_result(result, options.fetch(:format))
+      result.success? ? 0 : 1
+    end
+
+    def verify_full_diagnostics(configuration, paths)
+      runner = Analysis::Runner.new(configuration: configuration, cache_store: nil)
+      (paths ? runner.run(paths) : runner.run).diagnostics
+    end
+
+    def normalize_diagnostics(diagnostics)
+      diagnostics.map(&:to_h).sort_by do |hash|
+        [hash["path"].to_s, hash["line"].to_i, hash["column"].to_i, hash["rule"].to_s, hash["message"].to_s]
+      end
+    end
+
+    def report_verify_incremental(incremental, full, subset_size:, total:)
+      if incremental == full
+        @out.puts("rigor: --verify-incremental OK — incremental " \
+                  "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
+                  "matches full (#{full.size} diagnostics)")
+        return 0
+      end
+
+      only_incremental = incremental - full
+      only_full = full - incremental
+      @err.puts("rigor: --verify-incremental FAILED — incremental and full diagnostics differ.")
+      @err.puts("  incremental-only: #{only_incremental.size}, full-only: #{only_full.size}")
+      (only_incremental + only_full).first(10).each do |hash|
+        @err.puts("    #{hash['path']}:#{hash['line']}:#{hash['column']}: [#{hash['rule']}] #{hash['message']}")
+      end
+      1
+    end
+
     # ADR-22 slice 5 — the `--baseline-strict` CI gate. When the
     # flag is set, ANY baseline drift fails the run — not only
     # excess drift (a bucket over threshold, which already fails
@@ -193,7 +284,14 @@ module Rigor
     end
 
     def build_check_runner(configuration:, options:, buffer:, cache_root:)
-      cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
+      cache_store = if options.fetch(:no_cache)
+                      nil
+                    else
+                      Cache::Store.new(
+                        root: cache_root,
+                        max_bytes: configuration.cache_max_bytes
+                      )
+                    end
       Analysis::Runner.new(
         configuration: configuration,
         explain: options.fetch(:explain),
@@ -204,37 +302,6 @@ module Rigor
       )
     end
 
-    # Editor-mode CLI envelope. The `--tmp-file=PATH` /
-    # `--instead-of=PATH` pair binds an in-flight buffer file to
-    # the logical project path it represents (see
-    # `docs/design/20260516-editor-mode.md`). Both flags must
-    # appear together; either alone is a usage error. The
-    # physical file must be readable; missing-file is a usage
-    # error too so editors get one consistent failure shape.
-    #
-    # Returns:
-    # - `nil` when neither flag was supplied (legacy path).
-    # - `Rigor::Analysis::BufferBinding` when the pair is valid.
-    # - `:usage_error` after writing one diagnostic to stderr;
-    #   the caller MUST translate this to `EXIT_USAGE`.
-    def resolve_buffer_binding(options)
-      tmp = options[:tmp_file]
-      instead = options[:instead_of]
-      return nil if tmp.nil? && instead.nil?
-
-      if tmp.nil? || instead.nil?
-        @err.puts("--tmp-file and --instead-of must appear together")
-        return :usage_error
-      end
-
-      unless File.file?(tmp)
-        @err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
-        return :usage_error
-      end
-
-      Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
-    end
-
     # ADR-15 Phase 4c — resolves the worker count by
     # precedence: CLI `--workers=N` (most explicit) > env
     # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
@@ -296,7 +363,18 @@ module Rigor
         # `.rigor.yml`. Intended for single-file / ad-hoc CI use;
         # ordinary projects should configure the plugin in
         # `.rigor.yml`.
-        treat_all_as_inline_rbs: false
+        treat_all_as_inline_rbs: false,
+        # ADR-46 — the incremental-analysis acceptance gate. Runs a
+        # baseline analysis, re-analyzes a subset and serves the rest from
+        # the per-file cache, and asserts the merged diagnostics are
+        # byte-identical to a full `--no-cache` run. Exits non-zero on any
+        # mismatch. Off by default.
+        verify_incremental: false,
+        # ADR-46 — cross-process incremental analysis. With a disk snapshot
+        # of the prior run's per-file diagnostics + dependency graph,
+        # re-analyzes only the changed closure and serves the rest from the
+        # snapshot. Off by default.
+        incremental: false
       }
       parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
         opts.banner = "Usage: rigor check [options] [paths]"
@@ -314,14 +392,7 @@ module Rigor
                 "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
           options[:workers] = value
         end
-        opts.on("--tmp-file=PATH",
-                "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
-          options[:tmp_file] = value
-        end
-        opts.on("--instead-of=PATH",
-                "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
-          options[:instead_of] = value
-        end
+        Options.add_editor_mode(opts, options)
         opts.on("--baseline=PATH",
                 "ADR-22: load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
           options[:baseline] = value
@@ -338,6 +409,14 @@ module Rigor
                 "ADR-32: force-load rigor-rbs-inline with require_magic_comment: false") do
           options[:treat_all_as_inline_rbs] = true
         end
+        opts.on("--verify-incremental",
+                "ADR-46: assert incremental analysis matches a full run, then exit") do
+          options[:verify_incremental] = true
+        end
+        opts.on("--incremental",
+                "ADR-46: re-analyze only files changed since the last run (cross-process cache)") do
+          options[:incremental] = true
+        end
       end
       parser.parse!(@argv)
       options
@@ -402,6 +481,139 @@ module Rigor
       stats.format(@err)
     end
 
+    # Opt-in developer diagnostics printed after the run: the
+    # inference-cutoff trace (RIGOR_BUDGET_TRACE) and the heap-attribution
+    # profile (RIGOR_HEAP_PROFILE). Each gates itself, so this is a no-op
+    # on a normal run.
+    def write_trace_appendices
+      write_budget_trace
+      write_heap_profile
+    end
+
+    # Dumps the opt-in inference-cutoff counters (RIGOR_BUDGET_TRACE).
+    # These are the hard-coded "budget" guards that silently degrade
+    # to `Dynamic[top]` / a fallback bound — counting them shows where
+    # inference actually stopped. Process-global counters: meaningful
+    # only on a single-process run (`--workers 0`), since they do not
+    # cross fork boundaries.
+    def write_budget_trace
+      return unless Inference::BudgetTrace.enabled?
+
+      counts = Inference::BudgetTrace.snapshot
+      @err.puts("")
+      @err.puts("Inference cutoffs (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
+      @err.puts("  recursion-guard hits:      #{counts[Inference::BudgetTrace::RECURSION_GUARD]}")
+      @err.puts("  ancestor-walk-limit hits:  #{counts[Inference::BudgetTrace::ANCESTOR_WALK_LIMIT]}")
+      @err.puts("  hkt-fuel-exhausted hits:   #{counts[Inference::BudgetTrace::HKT_FUEL_EXHAUSTED]}")
+      write_budget_distributions
+    end
+
+    # Dumps the read-only size distributions (ADR-41 Slice 2a). These
+    # observe how large unions actually get, with no cap enforced — the
+    # data the `union_size` budget default should be chosen from. The
+    # `over` thresholds bracket the TypeProf prior (10) and Rigor's spec
+    # default (24).
+    def write_budget_distributions
+      summary = Inference::BudgetTrace.summarize(Inference::BudgetTrace::UNION_ARITY, over: [10, 24, 40])
+      pct = summary[:percentiles]
+      @err.puts("  union arity:  n=#{summary[:count]} max=#{summary[:max]} " \
+                "p50=#{pct[:p50]} p90=#{pct[:p90]} p99=#{pct[:p99]}")
+      over = summary[:over]
+      @err.puts("    unions ≥10: #{over[10]}  ≥24: #{over[24]}  ≥40: #{over[40]}")
+    end
+
+    # Dumps a live-heap class breakdown (RIGOR_HEAP_PROFILE) — retained
+    # objects by class after a forced GC, ranked by total memsize. The
+    # tool for attributing where the analyzer's resident memory goes
+    # (ADR-41 Slice 2b): it answers whether the heap is type carriers,
+    # RBS objects, Prism nodes, or fact-store Hashes/Strings. Walking the
+    # whole heap is slow — a dev probe, not a normal diagnostic. Run
+    # single-process (`--workers 0`) so the parent heap is the analysis
+    # heap; the gem is required lazily so a normal run never loads it.
+    def write_heap_profile
+      return if ENV["RIGOR_HEAP_PROFILE"].to_s.empty?
+
+      by_class, total = tally_live_heap
+      @err.puts("")
+      @err.puts("Heap profile (RIGOR_HEAP_PROFILE; live objects after GC, by class)")
+      @err.puts("  total tracked: #{heap_mb(total)} across #{by_class.size} classes")
+      by_class.sort_by { |_, (_, bytes)| -bytes }.first(30).each do |name, (count, bytes)|
+        @err.puts("  #{heap_mb(bytes).rjust(10)}  #{count.to_s.rjust(9)} obj  #{name}")
+      end
+      write_string_allocation_sites
+    end
+
+    # Loads the analysis-path dependencies lazily (so non-check commands
+    # stay light) and starts heap-allocation tracing if requested, before
+    # any analysis object is allocated.
+    def load_check_dependencies
+      require_relative "analysis/runner"
+      require_relative "analysis/buffer_binding"
+      require_relative "analysis/baseline"
+      require_relative "cache/store"
+      start_heap_trace_if_requested
+    end
+
+    # Starts allocation tracing (RIGOR_HEAP_TRACE) as early as possible so
+    # the heap profile can attribute retained Strings to their allocation
+    # `file:line`. Very high overhead — run on a small file subset only.
+    def start_heap_trace_if_requested
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      require "objspace"
+      ObjectSpace.trace_object_allocations_start
+    end
+
+    # When RIGOR_HEAP_TRACE is on, groups the live String objects by their
+    # allocation site (`sourcefile:sourceline`) and prints the top sites by
+    # count — pinpointing which engine code retains the millions of strings
+    # that dominate the large-app heap (ADR-41 Slice 2b). Strings allocated
+    # before tracing started report `(pre-trace)`.
+    def write_string_allocation_sites
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      by_site = Hash.new(0)
+      ObjectSpace.each_object(String) do |str|
+        file = ObjectSpace.allocation_sourcefile(str)
+        line = ObjectSpace.allocation_sourceline(str)
+        by_site[file ? "#{file}:#{line}" : "(pre-trace)"] += 1
+      end
+      @err.puts("")
+      @err.puts("  String allocation sites (top 25 by live count)")
+      by_site.sort_by { |_, n| -n }.first(25).each do |site, n|
+        @err.puts("  #{n.to_s.rjust(9)}  #{site}")
+      end
+    end
+
+    # Walks the whole live heap (after a forced GC) and tallies
+    # `{class_name => [count, memsize]}` plus the grand total. Returns
+    # `[by_class, total]`. Slow — a dev probe only.
+    def tally_live_heap
+      require "objspace"
+      GC.start
+      by_class = Hash.new { |h, k| h[k] = [0, 0] }
+      total = 0
+      ObjectSpace.each_object do |obj|
+        size = ObjectSpace.memsize_of(obj)
+        entry = by_class[heap_class_name(obj)]
+        entry[0] += 1
+        entry[1] += size
+        total += size
+      end
+      [by_class, total]
+    end
+
+    def heap_class_name(obj)
+      klass = Object.instance_method(:class).bind_call(obj)
+      klass.name || klass.inspect
+    rescue StandardError
+      "(unknown)"
+    end
+
+    def heap_mb(bytes)
+      Kernel.format("%.1f MB", bytes / 1_048_576.0)
+    end
+
     def write_cache_stats(cache_root, runtime_store)
       inv = Cache::Store.disk_inventory(root: cache_root)
 

data/lib/rigor/configuration/dependencies.rb

@@ -77,7 +77,7 @@ module Rigor
         return new([]) if data.nil?
         raise ArgumentError, "dependencies: must be a Hash, got #{data.inspect}" unless data.is_a?(Hash)
 
-        raw_entries = Array(data["source_inference"]).map { |raw| coerce_entry(raw) }
+        raw_entries = coerce_source_inference(data["source_inference"])
         entries, warnings = dedupe_entries(raw_entries)
         budget = coerce_budget_per_gem(data.fetch("budget_per_gem", DEFAULT_BUDGET_PER_GEM))
         strategy = coerce_budget_overrun_strategy(
@@ -158,6 +158,23 @@ module Rigor
 
         private
 
+        # `source_inference:` is a list of per-gem entries, or `false` /
+        # omitted to disable it (the default). Guard the Ruby
+        # `Array(false) == [false]` quirk that would otherwise feed `false`
+        # straight into coerce_entry and crash the whole run on a perfectly
+        # reasonable "off" config (`dependencies: { source_inference: false }`).
+        def coerce_source_inference(value)
+          return [] if value.nil? || value == false
+
+          unless value.is_a?(Array)
+            raise ArgumentError,
+                  "dependencies.source_inference: must be a list of entries " \
+                  "(or false / omitted to disable), got #{value.inspect}"
+          end
+
+          value.map { |raw| coerce_entry(raw) }
+        end
+
         def coerce_entry(raw)
           unless raw.is_a?(Hash)
             raise ArgumentError,

data/lib/rigor/configuration/severity_profile.rb

@@ -39,6 +39,7 @@ module Rigor
       PROFILES = {
         lenient: {
           "call.undefined-method" => :error,
+          "call.self-undefined-method" => :off,
           "call.unresolved-toplevel" => :off,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :warning,
@@ -47,6 +48,7 @@ module Rigor
           "flow.unreachable-branch" => :info,
           "flow.dead-assignment" => :info,
           "flow.always-truthy-condition" => :info,
+          "flow.unreachable-clause" => :info,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -54,10 +56,15 @@ module Rigor
           "def.override-visibility-reduced" => :off,
           "def.override-return-widened" => :off,
           "def.override-param-narrowed" => :off,
-          "def.ivar-write-mismatch" => :warning
+          "def.ivar-write-mismatch" => :warning,
+          # Opt-in author assertion: you only see it if you wrote a
+          # `conforms-to` directive, so it stays a :warning even in
+          # lenient — it is never unsolicited noise.
+          "rbs_extended.unsatisfied-conformance" => :warning
         }.freeze,
         balanced: {
           "call.undefined-method" => :error,
+          "call.self-undefined-method" => :off,
           "call.unresolved-toplevel" => :warning,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
@@ -66,6 +73,11 @@ module Rigor
           "flow.unreachable-branch" => :warning,
           "flow.dead-assignment" => :warning,
           "flow.always-truthy-condition" => :warning,
+          # ADR-47 WD4: stays :info (not :warning like its siblings) in the
+          # default balanced profile until the regression-corpus FP gate is
+          # green; promote to :warning once Mastodon/GitLab/Redmine triage
+          # to zero net false positives.
+          "flow.unreachable-clause" => :info,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -73,10 +85,12 @@ module Rigor
           "def.override-visibility-reduced" => :warning,
           "def.override-return-widened" => :warning,
           "def.override-param-narrowed" => :warning,
-          "def.ivar-write-mismatch" => :warning
+          "def.ivar-write-mismatch" => :warning,
+          "rbs_extended.unsatisfied-conformance" => :warning
         }.freeze,
         strict: {
           "call.undefined-method" => :error,
+          "call.self-undefined-method" => :off,
           "call.unresolved-toplevel" => :error,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
@@ -85,6 +99,10 @@ module Rigor
           "flow.unreachable-branch" => :error,
           "flow.dead-assignment" => :error,
           "flow.always-truthy-condition" => :error,
+          # ADR-47: strict opts into the new rule at :warning (one notch
+          # below its :error siblings) while it proves out — see the
+          # balanced-profile note above.
+          "flow.unreachable-clause" => :warning,
           "assert.type-mismatch" => :error,
           "dump.type" => :error,
           "def.return-type-mismatch" => :error,
@@ -92,7 +110,8 @@ module Rigor
           "def.override-visibility-reduced" => :error,
           "def.override-return-widened" => :error,
           "def.override-param-narrowed" => :error,
-          "def.ivar-write-mismatch" => :error
+          "def.ivar-write-mismatch" => :error,
+          "rbs_extended.unsatisfied-conformance" => :error
         }.freeze
       }.freeze
 

data/lib/rigor/configuration.rb

@@ -69,7 +69,13 @@ module Rigor
       "baseline" => nil,
       "fold_platform_specific_paths" => false,
       "cache" => {
-        "path" => ".rigor/cache"
+        "path" => ".rigor/cache",
+        # LRU eviction cap in bytes. nil (the default) disables eviction;
+        # the cache grows until the user runs `rigor check --clear-cache`.
+        # Set to a positive integer (e.g. 536870912 for 512 MB) to keep the
+        # cache bounded — the least-recently-used entries are removed at the
+        # end of each run when the total exceeds this limit.
+        "max_bytes" => nil
       },
       "plugins_io" => {
         "network" => "disabled",
@@ -166,7 +172,8 @@ module Rigor
     PATH_KEYS = %w[paths signature_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
-    attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
+    attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
+                :disabled_rules,
                 :libraries, :signature_paths, :fold_platform_specific_paths,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
@@ -334,6 +341,8 @@ module Rigor
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
       ) == true
       @cache_path = cache.fetch("path").to_s
+      raw_max = cache.fetch("max_bytes")
+      @cache_max_bytes = raw_max.nil? ? nil : Integer(raw_max)
       @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
       @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
       @plugins_io_allowed_url_hosts = Array(plugins_io.fetch("allowed_url_hosts")).map(&:to_s).freeze
@@ -383,7 +392,8 @@ module Rigor
         "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
-          "path" => cache_path
+          "path" => cache_path,
+          "max_bytes" => cache_max_bytes
         },
         "plugins_io" => {
           "network" => plugins_io_network.to_s,