rigortype 0.2.9 → 0.3.0

data/lib/rigor/cli/check_command.rb

@@ -8,12 +8,17 @@ require_relative "../configuration"
 require_relative "../config_audit"
 require_relative "../analysis/result"
 require_relative "../analysis/rule_catalog"
-require_relative "coverage_scan"
+# The baseline filter runs on EVERY exit path — including the ADR-87 WD4 cache-HIT fast path, which skips
+# `load_check_dependencies` — so it must be a load-time require. It pulls only YAML, never the engine.
+require_relative "../analysis/baseline"
+require_relative "../runtime/jit"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
-require_relative "ci_detector"
-require_relative "check_runner_factory"
+require_relative "../ci_detector"
+# ADR-87 WD4 — `coverage_scan` and `check_runner_factory` both pull the inference engine, so they are required
+# lazily (in `compute_coverage` / `build_check_runner`) rather than at load time: an ordinary check whose
+# result the run-cache probe serves must reach the hit verdict without `rigor/inference` in $LOADED_FEATURES.
 
 module Rigor
   class CLI
@@ -29,18 +34,34 @@ module Rigor
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize
-        load_check_dependencies
+      def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # Arm deferred YJIT enablement before any analysis work: the deadline
+        # thread only fires once a run outlasts the amortization window, so a
+        # short check finishes before it ever pays JIT compile cost while a
+        # long run JITs its dominant tail (Runtime::Jit).
+        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+        # ADR-87 WD4 — parse options + resolve config WITHOUT the inference engine, so the run-cache hit probe
+        # can run first. The heavy engine (`load_check_dependencies`) loads only on a miss / non-cacheable run.
         options = parse_check_options
         buffer = Options.resolve_buffer_binding(options, err: @err)
         return CLI::EXIT_USAGE if buffer == :usage_error
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
+        conflict = parameter_inference_incremental_conflict(configuration, options)
+        return conflict unless conflict.nil?
+
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
+        # ADR-87 WD4 — try to serve the whole run from the ADR-45 cache before booting the engine. A hit boots
+        # only CLI + config + cache + digest code (no `rigor/inference`), skipping the plugin prepass + env
+        # build entirely.
+        probed = try_run_cache_hit(configuration, options, buffer, cache_root)
+        return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
+
+        load_check_dependencies
         special = dispatch_special_check_mode(configuration, options, cache_root)
         return special unless special.nil?
 
@@ -66,23 +87,113 @@ module Rigor
 
       private
 
+      # ADR-87 WD4 — attempt the boot-slimming run-cache hit. Returns the cached {Analysis::Result} (severity
+      # profile applied, no stats — matching a cache-served `Runner#run`) on a hit, or nil to fall through to
+      # the full engine path. Only an ordinary sequential check whose result IS cache-served the same way is
+      # eligible; every other mode (below) declines so the full path handles it unchanged.
+      def try_run_cache_hit(configuration, options, buffer, cache_root)
+        return nil unless run_cache_hit_eligible?(configuration, options, buffer)
+
+        require_relative "../analysis/run_cache_probe"
+        Analysis::RunCacheProbe.new(
+          configuration: configuration, cache_root: cache_root, explain: options.fetch(:explain)
+        ).serve(@argv.empty? ? configuration.paths : @argv)
+      end
+
+      # The probe is eligible only for a run the ADR-45 result cache actually serves: a writable cache (not
+      # `--no-cache`), no editor buffer, sequential (pool runs are not result-cacheable), and no mode needing
+      # the engine (`--coverage` / `--incremental` / `--verify-incremental`) or the runner's own reporting
+      # (`--cache-stats`, the `RIGOR_*_TRACE` dev probes). A wrongly-permitted run still MISSES (the entry was
+      # never written its way) and falls through — the gate is an optimisation, never a soundness boundary.
+      def run_cache_hit_eligible?(configuration, options, buffer)
+        buffer.nil? &&
+          !options.fetch(:no_cache) && !options.fetch(:coverage) && !options.fetch(:cache_stats) &&
+          !options.fetch(:incremental) && !options.fetch(:verify_incremental) &&
+          !pool_workers_configured?(options, configuration) &&
+          ENV["RIGOR_BUDGET_TRACE"].to_s.empty? && ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+      end
+
+      # Any signal that per-file analysis would run in a worker pool (CLI `--workers`, the env override, or the
+      # config default). Deliberately over-declines (a false positive only forgoes the fast lane); mirrors
+      # {CheckRunnerFactory.resolve_workers} without requiring it (that pulls in the engine).
+      def pool_workers_configured?(options, configuration)
+        cli = options[:workers]
+        return Integer(cli).positive? if cli
+
+        env = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return Integer(env).positive? if env && !env.empty?
+
+        configuration.parallel_workers.positive?
+      rescue ArgumentError
+        false
+      end
+
+      # ADR-87 WD4 — the engine-free tail for a cache-served hit: baseline filter + output + exit code,
+      # mirroring the full path's tail but without stats (a hit collected none), trace appendices (they read
+      # engine counters), or eviction (deferred to the next miss). `raw_result` is pre-baseline so the strict
+      # gate reads the same diagnostics the full path would.
+      def finalize_cache_hit(raw_result, configuration, options, config_warnings)
+        result = apply_baseline_filter(raw_result, configuration, options)
+        write_result(result, options.fetch(:format), config_warnings: config_warnings)
+        emit_ci_detected_output(result, options)
+
+        exit_code = result.success? ? 0 : 1
+        exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
+        exit_code
+      end
+
+      # ADR-67 WD6c — `parameter_inference:` and the ADR-46 incremental modes are mutually exclusive in slice 1.
+      # The parameter table introduces cross-file edges (a caller's argument types drive a callee's body
+      # diagnostics) that the per-file dependency recorder does not yet carry, so a cached file whose parameter
+      # seeds changed would serve a stale result. Refuse with a message naming the ADR-46 gap rather than
+      # silently producing unsound incremental diagnostics; the edge wiring is the named follow-up. Returns the
+      # usage exit code on a conflict, or nil to proceed. `--verify-incremental` (the acceptance gate that runs
+      # incremental analysis) is caught here too.
+      def parameter_inference_incremental_conflict(configuration, options)
+        return nil unless configuration.parameter_inference
+        return nil unless options.fetch(:incremental) || options.fetch(:verify_incremental)
+
+        flag = options.fetch(:incremental) ? "--incremental" : "--verify-incremental"
+        @err.puts("rigor: parameter_inference: cannot combine with #{flag} — the call-site parameter table " \
+                  "introduces cross-file caller→callee edges the ADR-46 incremental dependency graph does not " \
+                  "yet record, so a cached file could serve a stale diagnostic. Run a full check (drop " \
+                  "#{flag}), or disable parameter_inference: for this run.")
+        CLI::EXIT_USAGE
+      end
+
       # ADR-46 — the two incremental-analysis check modes both fully handle the run and return an exit code (so `run`
       # 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_verify_incremental(configuration, options, cache_root) if options.fetch(:verify_incremental)
         return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
 
         nil
       end
 
+      # ADR-85 WD1 — the persistent cache the incremental session threads into each internal Runner so plugin
+      # `#prepare` producers (the ADR-9/#74/ADR-60 WD3 record-and-validate caches) and the RBS environment serve
+      # from disk across processes / rechecks rather than recomputing every invocation. Honors `--no-cache` (nil
+      # = no store), mirroring {CheckRunnerFactory}. The whole-run ADR-45 result cache stays inert on these runs
+      # — `Runner#run_result_cacheable?` excludes `record_dependencies` / `analyze_only`.
+      def incremental_cache_store(configuration, options, cache_root)
+        return nil if options.fetch(:no_cache)
+
+        Cache::Store.new(root: cache_root, max_bytes: configuration.cache_max_bytes)
+      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)
+      def run_verify_incremental(configuration, options, cache_root)
         paths = @argv.empty? ? nil : @argv
-        session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
+        # ADR-85 WD1 — thread the store so the gate also asserts the cache-served producer path stays
+        # byte-identical to the uncached full run (`verify_full_diagnostics` builds a nil-store runner).
+        session = Analysis::IncrementalSession.new(
+          configuration: configuration, paths: paths,
+          cache_store: incremental_cache_store(configuration, options, cache_root)
+        )
         session.baseline
         analyzed = session.analyzed_files
 
@@ -101,18 +212,30 @@ module Rigor
       # 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)
+        require_relative "check_runner_factory"
         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)
+        store = incremental_cache_store(configuration, options, cache_root)
+        session = Analysis::IncrementalSession.new(
+          configuration: configuration, paths: paths,
+          cache_store: store,
+          # ADR-46 — thread the same worker-count precedence the standard `check` path uses
+          # (CLI `--workers` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > 0) so the recheck's closure
+          # re-analysis parallelises; the fork pool marshals dependency records back so the graph is sound.
+          workers: CheckRunnerFactory.resolve_workers(options, configuration)
+        )
 
         diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
+        # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
+        # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
+        # built just to size the banner (recon §3 — the analysis tree was expanded three times per recheck).
         @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
-                  "(#{files.size} files)")
+                  "(#{session.analyzed_files.size} files)")
+        emit_incremental_fact_surface_notes(session)
+        write_incremental_cache_stats(session, cache_root, store) if options.fetch(:cache_stats)
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
@@ -120,6 +243,40 @@ module Rigor
         result.success? ? 0 : 1
       end
 
+      # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
+      # value, or an `incremental_state_fingerprint` hook) forced a full run: either it CHANGED since the
+      # snapshot (a Sorbet sig edit, a schema change) or a contributing plugin declares NO fingerprint surface
+      # (opaque — a full run every invocation). Both are the sound direction; the note explains why a recheck
+      # was not warm.
+      def emit_incremental_fact_surface_notes(session)
+        opaque = session.opaque_plugin_ids
+        unless opaque.empty?
+          @err.puts("rigor: --incremental plugin#{'s' unless opaque.size == 1} #{opaque.sort.join(', ')} " \
+                    "contribute call-site types with no incremental fingerprint surface; the snapshot cannot " \
+                    "be reused (full analysis every run).")
+        end
+        return unless session.fact_surface_invalidated? && opaque.empty?
+
+        @err.puts("rigor: --incremental plugin fact surface changed since the snapshot; ran a full analysis.")
+      end
+
+      # ADR-88 WD1 — `--incremental --cache-stats` surfaces the on-disk cache inventory (as a plain `check`
+      # does) plus the fact-surface status line, so an operator can see whether a full run was fact-surface
+      # driven. The plain `check` cache-stats path is bypassed by the incremental short-circuit, so it is
+      # emitted here.
+      def write_incremental_cache_stats(session, cache_root, store)
+        write_cache_stats(cache_root, store)
+        status =
+          if !session.opaque_plugin_ids.empty?
+            "opaque (#{session.opaque_plugin_ids.sort.join(', ')})"
+          elsif session.fact_surface_invalidated?
+            "changed — snapshot invalidated"
+          else
+            "unchanged"
+          end
+        @out.puts("  plugin fact surface: #{status}")
+      end
+
       def verify_full_diagnostics(configuration, paths)
         runner = Analysis::Runner.new(configuration: configuration, cache_store: nil)
         (paths ? runner.run(paths) : runner.run).diagnostics
@@ -227,6 +384,7 @@ module Rigor
       end
 
       def build_check_runner(configuration:, options:, buffer:, cache_root:)
+        require_relative "check_runner_factory"
         CheckRunnerFactory.build(
           configuration: configuration, options: options,
           buffer: buffer, cache_root: cache_root
@@ -391,7 +549,10 @@ module Rigor
       end
 
       def inject_treat_all_as_inline_rbs(entries)
-        filtered = entries.reject { |entry| rigor_rbs_inline_entry?(entry) }
+        # Single-homed with the WD2 auto-wire gate (`Configuration.rbs_inline_plugin_entry?`) so the flag and
+        # the default agree on what "already listed" means; a pre-existing entry is removed so this one's
+        # `require_magic_comment: false` wins unconditionally.
+        filtered = entries.reject { |entry| Configuration.rbs_inline_plugin_entry?(entry) }
         filtered + [{
           "gem" => "rigor-rbs-inline",
           "id" => "rbs-inline",
@@ -399,18 +560,6 @@ module Rigor
         }]
       end
 
-      def rigor_rbs_inline_entry?(entry)
-        case entry
-        when String
-          entry == "rigor-rbs-inline"
-        when Hash
-          string_keyed = entry.to_h { |k, v| [k.to_s, v] }
-          string_keyed["gem"] == "rigor-rbs-inline" || string_keyed["id"] == "rbs-inline"
-        else
-          false
-        end
-      end
-
       def handle_clear_cache(cache_root)
         if File.directory?(cache_root)
           FileUtils.rm_rf(cache_root)
@@ -451,6 +600,42 @@ module Rigor
         @err.puts("  recursion-fixpoint-cap hits: #{counts[Inference::BudgetTrace::RECURSION_FIXPOINT_CAP]}")
         @err.puts("  block-writeback-cap hits:  #{counts[Inference::BudgetTrace::BLOCK_WRITEBACK_CAP]}")
         write_budget_distributions
+        write_memo_profile(counts)
+      end
+
+      # Dumps the ADR-57 return-memo profile (WD0). Entries / hit rate / body evals / the non-store split, then
+      # the top signatures by body-eval count with their distinct-memo-key counts — the evidence for choosing
+      # between a finalization-aware taint gate and memo-key normalization. `--workers 0` for exact counts.
+      def write_memo_profile(counts)
+        bt = Inference::BudgetTrace
+        hits = counts[bt::MEMO_HITS]
+        misses = counts[bt::MEMO_MISSES]
+        consults = hits + misses
+        rate = consults.positive? ? format("%.1f%%", 100.0 * hits / consults) : "n/a"
+        @err.puts("")
+        @err.puts("Return-memo profile (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
+        @err.puts("  infer entries:   #{counts[bt::MEMO_ENTRIES]}")
+        @err.puts("  memo consults:   #{consults}  (hits #{hits} / misses #{misses}; hit rate #{rate})")
+        @err.puts("  body evals:      #{counts[bt::MEMO_BODY_EVALS]}")
+        @err.puts("  non-stored:      on-stack #{counts[bt::MEMO_REFUSE_ON_STACK]}  " \
+                  "unroll-in-flight #{counts[bt::MEMO_REFUSE_UNROLL]}  " \
+                  "consult-tainted #{counts[bt::MEMO_REFUSE_CONSULT_TAINTED]}  " \
+                  "transient-tainted #{counts[bt::MEMO_REFUSE_TRANSIENT]}")
+        write_memo_signature_table
+      end
+
+      # Top 15 signatures by body-eval (compute) count, each with its distinct-memo-key count — a signature
+      # whose distinct-key count dwarfs its evals is arg-granularity thrash (the key-normalization candidate).
+      def write_memo_signature_table
+        bt = Inference::BudgetTrace
+        evals = bt.distribution(bt::MEMO_BODY_EVAL_BY_SIGNATURE)
+        return if evals.empty?
+
+        keys = bt.distribution(bt::MEMO_DISTINCT_KEY_BY_SIGNATURE)
+        @err.puts("  top signatures by body-eval count (evals / distinct-keys / signature):")
+        evals.sort_by { |sig, n| [-n, sig] }.first(15).each do |sig, n|
+          @err.puts("    #{n.to_s.rjust(8)}  #{keys.fetch(sig, 0).to_s.rjust(6)}  #{sig}")
+        end
       end
 
       # Dumps the read-only size distributions (ADR-41 Slice 2a). These observe how large unions actually get, with no
@@ -488,7 +673,6 @@ module Rigor
       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
@@ -625,6 +809,7 @@ module Rigor
       def compute_coverage(runner, configuration, options)
         return nil unless options.fetch(:coverage)
 
+        require_relative "coverage_scan"
         files = @argv.empty? ? runner.analysis_file_set : runner.analysis_file_set(@argv)
         CoverageScan.precision_report(files: files, configuration: configuration)
       end
@@ -682,7 +867,7 @@ module Rigor
         return unless options.fetch(:ci_detect)
         return unless options.fetch(:format) == "text"
 
-        platform = CLI::CiDetector.detect
+        platform = CiDetector.detect
         return if platform.nil?
 
         if platform.native_stdout?

data/lib/rigor/cli/coverage_command.rb

@@ -14,6 +14,7 @@ require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
 require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
+require_relative "../runtime/jit"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
@@ -53,7 +54,11 @@ module Rigor
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
       # @return [Integer] CLI exit status.
-      def run
+      def run # rubocop:disable Metrics/AbcSize
+        # Arm deferred YJIT enablement (Runtime::Jit): a scan long enough to
+        # amortize JIT compile cost enables mid-flight; a short one finishes
+        # first and never pays it. Same seam as `rigor check`.
+        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
         return with_tests_misuse_error if options[:with_tests] && !options[:mutation]

data/lib/rigor/cli/docs_command.rb

@@ -20,9 +20,6 @@ module Rigor
     #
     # `<name>` resolves a category-qualified path (`handbook/03-narrowing`), a prefixed basename (`03-narrowing`), or a
     # short name (`narrowing`, when it is unique across categories).
-    #
-    # The pre-v0.3.0 verb spellings `rigor docs list` / `rigor docs path <name>` still work but emit a stderr
-    # deprecation notice; they are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI deprecations").
     class DocsCommand < Command
       USAGE = <<~USAGE
         Usage: rigor docs [<name>] [--path <name>] [--list [<category>]]
@@ -46,10 +43,6 @@ module Rigor
           rigor docs editor-integration
           rigor docs --path 17-driving-improvement
           rigor docs --list handbook
-
-        Deprecated (removed in v0.3.0) — use the flags above:
-          rigor docs list           ->  rigor docs --list
-          rigor docs path <name>    ->  rigor docs --path <name>
       USAGE
 
       # The bundled docs live at `<gem_root>/docs/`. From `lib/rigor/cli/docs_command.rb` that is three directories up.
@@ -58,18 +51,8 @@ module Rigor
       HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
       LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
 
-      # The verb subcommands the flags superseded keep working with a stderr deprecation notice until this version drops
-      # them. Each maps to the canonical advice printed and the flag it rewrites to.
-      LEGACY_VERB_REMOVAL = "v0.3.0"
-      LEGACY_VERBS = {
-        "list" => { old: "list",        advice: "--list",        flag: "--list" },
-        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
-      }.freeze
-
       # @return [Integer] CLI exit status.
       def run
-        rewrite_legacy_verb!
-
         case @argv.first
         when nil
           run_index
@@ -92,19 +75,6 @@ module Rigor
 
       private
 
-      # Translate a deprecated verb spelling into its flag form, warning once on stderr, so the dispatch above only
-      # handles canonical forms.
-      def rewrite_legacy_verb!
-        spec = LEGACY_VERBS[@argv.first]
-        return unless spec
-
-        @err.puts(
-          "rigor docs: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
-          "#{LEGACY_VERB_REMOVAL}; use `rigor docs #{spec.fetch(:advice)}` instead."
-        )
-        @argv[0] = spec.fetch(:flag)
-      end
-
       def run_index
         if File.file?(LLMS_INDEX)
           @out.write(File.read(LLMS_INDEX))