rigortype 0.2.9 → 0.3.0

data/skills/rigor-project-init/references/05-jit-performance.md

@@ -0,0 +1,125 @@
+# Reference 05 — JIT and run speed (YJIT / ZJIT)
+
+Operational, not part of onboarding proper: how Rigor uses a Ruby JIT to
+speed up analysis, how to tell whether it is active in your install, and the
+trade-off (and break-even point) if you want to override the default. Read
+this when a project is large enough that `rigor check` wall time matters —
+Rails monorepos especially. On a small project you can ignore it entirely:
+Rigor already does the right thing with no configuration.
+
+## TL;DR
+
+- **You usually do nothing.** Rigor enables YJIT automatically once a run has
+  been going long enough to be worth it, and leaves it off for short runs
+  where it would only add warm-up cost. This is on by default.
+- **Break-even is ~5 seconds.** A JIT pays for its warm-up only on longer
+  runs; below it, JIT-on is *slower*. Rigor's 5-second deadline is set at
+  that crossover.
+- **YJIT, not ZJIT.** Ruby 4.0 ships both JITs, but YJIT is faster for Rigor's
+  workload — measurably so on every run large enough for a JIT to help. Rigor
+  uses YJIT; there is no reason to force ZJIT.
+
+## How Rigor uses a JIT
+
+`rigor check` and `rigor coverage` arm a background timer at the start of a
+run. If the run is still going after ~5 seconds, YJIT is switched on for the
+remainder; a run that finishes first never pays any JIT cost. So:
+
+- A quick check (a small project, or a warm cache hit) runs on the plain
+  interpreter — no warm-up penalty.
+- A long cold analysis of a large project gets YJIT for its dominant tail,
+  where the speed-up more than repays the warm-up.
+
+Diagnostics and their counts are identical whether or not the JIT engages —
+a JIT changes wall time only, never results.
+
+The long-running servers `rigor lsp` and `rigor mcp` turn YJIT on at start
+instead, since they always run long.
+
+## Is a JIT available in my install?
+
+The deferred-YJIT feature only helps if the Ruby your `rigor` runs on was
+built with YJIT support. Rigor is installed standalone (see the manual's
+Installing Rigor chapter: `rigor docs manual/01-installation`), so this is a
+property of *that* Ruby, which may differ from your project's Ruby.
+
+Check the Ruby that runs `rigor`:
+
+```sh
+ruby --yjit -e 'require "rbconfig"; puts "YJIT: #{RbConfig::CONFIG["YJIT_SUPPORT"]}"; puts "ZJIT: #{RbConfig::CONFIG["ZJIT_SUPPORT"]}"'
+# YJIT: yes   → the deferred-YJIT engages automatically on long runs
+# YJIT: no    → the feature is a silent no-op; runs use the interpreter
+```
+
+- Most prebuilt CRuby 3.3+ (mise / rbenv / asdf, the recommended install
+  channels) ship with YJIT built in but **not** ZJIT — a prebuilt
+  mise Ruby 4.0, for example, reports `YJIT: yes` / `ZJIT: no`, because
+  ZJIT needs `rustc` at build time and the prebuilt binary omits it. That
+  is exactly the configuration Rigor wants: YJIT is the faster JIT for
+  Rigor (see the YJIT-vs-ZJIT section below), so a missing ZJIT costs you
+  nothing.
+- The Nix flake package of Rigor bundles a Ruby with **both** JITs; that
+  is the only common install where `ZJIT: yes` — and Rigor still uses
+  YJIT there.
+- A YJIT-less Ruby is not an error — Rigor just runs interpreted, correctly.
+
+## Overriding the default
+
+Three environment variables, documented in the CLI reference's
+"Environment variables" section (`rigor docs manual/02-cli-reference`):
+
+| Want | Do |
+| --- | --- |
+| Force YJIT on for the **whole** run (including the first 5 s) | `RUBYOPT="--yjit" rigor check …` |
+| Turn Rigor's JIT off entirely | `RIGOR_DISABLE_YJIT=1 rigor check …` |
+| Change the deadline (advanced) | `RIGOR_YJIT_DEADLINE=<seconds> rigor check …` |
+
+When would you override?
+
+- **Force-on** helps only if *every* run you care about is long (a big
+  monorepo in CI where even the fast path is > 5 s). On mixed workloads the
+  default deadline is better — it protects your quick local re-checks.
+- **Off** is the escape hatch if a JIT ever misbehaves on your platform, or to
+  get a clean interpreter baseline when measuring.
+
+## Why the ~5-second break-even (the trade-off)
+
+A JIT compiles hot code to machine code, which costs time up front and repays
+it over the rest of the run. On a short run the compilation never amortizes,
+so JIT-on loses. Measured cold `rigor check`, by project size:
+
+| run size | interpreter | YJIT | effect |
+| --- | --- | --- | --- |
+| ~1.6 s (small lib) | baseline | **+67 %** | JIT-on loses badly |
+| ~4 s (medium lib) | baseline | ~break-even | a wash |
+| ~8 s | baseline | **−13 %** | JIT-on wins |
+| ~19 s (Rails monorepo) | baseline | **−20 %** | wins more |
+| ~17 s (large Rails app) | baseline | **−28 %** | biggest win |
+
+The deadline parks the enable point just past the loss zone: runs that finish
+before ~5 s never pay warm-up; longer runs collect the win on their tail.
+
+## YJIT vs ZJIT (Ruby 4.0)
+
+Ruby 4.0 ships a second JIT, **ZJIT** (a newer method-based JIT;
+[upstream docs](https://docs.ruby-lang.org/en/master/jit/zjit_md.html)). It
+is real and correctness-safe on Rigor (identical diagnostics), but **slower
+than YJIT for Rigor's workload** at Ruby 4.0. Measured cold, on the runs where
+a JIT helps at all:
+
+| target | YJIT vs interpreter | ZJIT vs interpreter | ZJIT vs YJIT |
+| --- | --- | --- | --- |
+| ~8 s | −13 % | −4 % | +10 % |
+| ~19 s (monorepo) | −20 % | −13 % | +10 % |
+| ~17 s (large app) | −28 % | −14 % | +21 % |
+
+YJIT wins on every workload large enough to warrant a JIT; ZJIT's peak
+speed-up is roughly half. ZJIT only edges YJIT on tiny runs — the zone where
+you want no JIT at all. **Do not force ZJIT** (`RUBYOPT="--zjit"`) for Rigor;
+the automatic YJIT is faster. Full measurement + methodology (a
+contributor-side note, web only):
+<https://github.com/rigortype/rigor/blob/master/docs/notes/20260714-jit-evaluation-yjit-zjit-ruby40.md>.
+
+This verdict is Ruby-4.0-specific; ZJIT is younger than YJIT and improving, so
+it may close the gap in a later Ruby. Until then YJIT is the right default —
+which is what Rigor already does.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - Rigor contributors
@@ -129,26 +129,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: parallel_tests
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -269,8 +249,13 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
-description: Rigor is a CLI-first static analyzer for Ruby applications that prioritizes
-  type inference, clean application code, and zero runtime dependencies.
+description: 'Rigor is a CLI-first static analyzer for Ruby applications that prioritizes
+  type inference, clean application code, and zero runtime dependencies. Rigor is
+  a standalone tool, not a library: install it independently rather than adding it
+  to your application''s Gemfile. It runs on Ruby 4.0 while your project keeps its
+  own Ruby, and it reads your project as data rather than loading it, so a Gemfile
+  entry only constrains your application''s Ruby and dependency resolution. Installation
+  channels (mise, asdf, gem install, container, Nix): https://github.com/rigortype/rigor/blob/master/docs/install.md'
 email:
 - maintainers@example.invalid
 executables:
@@ -410,11 +395,17 @@ files:
 - lib/rigor/analysis/check_rules.rb
 - lib/rigor/analysis/check_rules/always_truthy_condition_collector.rb
 - lib/rigor/analysis/check_rules/dead_assignment_collector.rb
+- lib/rigor/analysis/check_rules/duplicate_hash_key_collector.rb
+- lib/rigor/analysis/check_rules/inferred_param_guard.rb
 - lib/rigor/analysis/check_rules/ivar_write_collector.rb
 - lib/rigor/analysis/check_rules/main_pass_collector.rb
+- lib/rigor/analysis/check_rules/return_in_ensure_collector.rb
+- lib/rigor/analysis/check_rules/rule_ids.rb
 - lib/rigor/analysis/check_rules/rule_walk.rb
 - lib/rigor/analysis/check_rules/self_closedness_scanner.rb
+- lib/rigor/analysis/check_rules/shadowed_rescue_collector.rb
 - lib/rigor/analysis/check_rules/unreachable_clause_collector.rb
+- lib/rigor/analysis/check_rules/void_value_use_collector.rb
 - lib/rigor/analysis/dependency_recorder.rb
 - lib/rigor/analysis/dependency_source_inference.rb
 - lib/rigor/analysis/dependency_source_inference/boundary_cross_reporter.rb
@@ -428,9 +419,13 @@ files:
 - lib/rigor/analysis/fact_store.rb
 - lib/rigor/analysis/incremental.rb
 - lib/rigor/analysis/incremental_session.rb
+- lib/rigor/analysis/path_expansion.rb
+- lib/rigor/analysis/plugin_fact_fingerprint.rb
 - lib/rigor/analysis/project_scan.rb
 - lib/rigor/analysis/result.rb
 - lib/rigor/analysis/rule_catalog.rb
+- lib/rigor/analysis/run_cache_key.rb
+- lib/rigor/analysis/run_cache_probe.rb
 - lib/rigor/analysis/run_stats.rb
 - lib/rigor/analysis/runner.rb
 - lib/rigor/analysis/runner/diagnostic_aggregator.rb
@@ -438,6 +433,7 @@ files:
 - lib/rigor/analysis/runner/project_pre_passes.rb
 - lib/rigor/analysis/runner/run_snapshots.rb
 - lib/rigor/analysis/self_call_resolution_recorder.rb
+- lib/rigor/analysis/severity_stamp.rb
 - lib/rigor/analysis/worker_session.rb
 - lib/rigor/ast.rb
 - lib/rigor/ast/type_node.rb
@@ -448,6 +444,7 @@ files:
 - lib/rigor/builtins/regex_refinement.rb
 - lib/rigor/builtins/static_return_refinements.rb
 - lib/rigor/cache/descriptor.rb
+- lib/rigor/cache/file_digest.rb
 - lib/rigor/cache/incremental_snapshot.rb
 - lib/rigor/cache/rbs_cache_producer.rb
 - lib/rigor/cache/rbs_class_ancestor_table.rb
@@ -458,12 +455,12 @@ files:
 - lib/rigor/cache/rbs_environment_marshal_patch.rb
 - lib/rigor/cache/rbs_known_class_names.rb
 - lib/rigor/cache/store.rb
+- lib/rigor/ci_detector.rb
 - lib/rigor/cli.rb
 - lib/rigor/cli/annotate_command.rb
 - lib/rigor/cli/baseline_command.rb
 - lib/rigor/cli/check_command.rb
 - lib/rigor/cli/check_runner_factory.rb
-- lib/rigor/cli/ci_detector.rb
 - lib/rigor/cli/command.rb
 - lib/rigor/cli/coverage_command.rb
 - lib/rigor/cli/coverage_mutation.rb
@@ -486,6 +483,7 @@ files:
 - lib/rigor/cli/plugins_command.rb
 - lib/rigor/cli/plugins_renderer.rb
 - lib/rigor/cli/prism_colorizer.rb
+- lib/rigor/cli/probe_environment.rb
 - lib/rigor/cli/protection_fork_scan.rb
 - lib/rigor/cli/protection_renderer.rb
 - lib/rigor/cli/protection_report.rb
@@ -512,6 +510,7 @@ files:
 - lib/rigor/environment/bundle_sig_discovery.rb
 - lib/rigor/environment/class_registry.rb
 - lib/rigor/environment/constant_type_cache_holder.rb
+- lib/rigor/environment/default_libraries.rb
 - lib/rigor/environment/hkt_registry_holder.rb
 - lib/rigor/environment/lockfile_resolver.rb
 - lib/rigor/environment/missing_gem_constant_index.rb
@@ -553,6 +552,8 @@ files:
 - lib/rigor/inference/builtins/time_catalog.rb
 - lib/rigor/inference/closure_escape_analyzer.rb
 - lib/rigor/inference/coverage_scanner.rb
+- lib/rigor/inference/def_handle.rb
+- lib/rigor/inference/def_node_resolver.rb
 - lib/rigor/inference/def_return_typer.rb
 - lib/rigor/inference/dynamic_origin.rb
 - lib/rigor/inference/expression_typer.rb
@@ -609,6 +610,8 @@ files:
 - lib/rigor/inference/synthetic_method.rb
 - lib/rigor/inference/synthetic_method_index.rb
 - lib/rigor/inference/synthetic_method_scanner.rb
+- lib/rigor/inference/void_origin.rb
+- lib/rigor/inference/void_tail_summary.rb
 - lib/rigor/language_server.rb
 - lib/rigor/language_server/buffer_resolution.rb
 - lib/rigor/language_server/buffer_table.rb
@@ -664,6 +667,7 @@ files:
 - lib/rigor/rbs_extended/hkt_directives.rb
 - lib/rigor/rbs_extended/reporter.rb
 - lib/rigor/reflection.rb
+- lib/rigor/runtime/jit.rb
 - lib/rigor/scope.rb
 - lib/rigor/scope/discovery_index.rb
 - lib/rigor/sig_gen.rb
@@ -674,6 +678,7 @@ files:
 - lib/rigor/sig_gen/observation_collector.rb
 - lib/rigor/sig_gen/observed_call.rb
 - lib/rigor/sig_gen/path_mapper.rb
+- lib/rigor/sig_gen/rbs_validity.rb
 - lib/rigor/sig_gen/renderer.rb
 - lib/rigor/sig_gen/type_elaborator.rb
 - lib/rigor/sig_gen/write_result.rb
@@ -682,6 +687,7 @@ files:
 - lib/rigor/source.rb
 - lib/rigor/source/constant_path.rb
 - lib/rigor/source/literals.rb
+- lib/rigor/source/node_children.rb
 - lib/rigor/source/node_locator.rb
 - lib/rigor/source/node_walker.rb
 - lib/rigor/testing.rb
@@ -725,6 +731,7 @@ files:
 - lib/rigor/type_node/union.rb
 - lib/rigor/value_semantics.rb
 - lib/rigor/version.rb
+- lib/rigortype.rb
 - plugins/rigor-actioncable/lib/rigor-actioncable.rb
 - plugins/rigor-actioncable/lib/rigor/plugin/actioncable.rb
 - plugins/rigor-actioncable/lib/rigor/plugin/actioncable/analyzer.rb
@@ -850,6 +857,7 @@ files:
 - plugins/rigor-statesman/lib/rigor/plugin/statesman.rb
 - plugins/rigor-typescript-utility-types/lib/rigor-typescript-utility-types.rb
 - plugins/rigor-typescript-utility-types/lib/rigor/plugin/typescript_utility_types.rb
+- sig/prism_node_children.rbs
 - sig/rigor.rbs
 - sig/rigor/analysis/baseline.rbs
 - sig/rigor/analysis/check_rules/always_truthy_condition_collector.rbs
@@ -911,6 +919,7 @@ files:
 - skills/rigor-project-init/references/02-configure.md
 - skills/rigor-project-init/references/03-baseline-and-bugs.md
 - skills/rigor-project-init/references/04-sig-uplift.md
+- skills/rigor-project-init/references/05-jit-performance.md
 - skills/rigor-protection-uplift/SKILL.md
 - skills/rigor-rbs-setup/SKILL.md
 - skills/rigor-upgrade/SKILL.md
@@ -922,6 +931,15 @@ metadata:
   source_code_uri: https://github.com/rigortype/rigor
   documentation_uri: https://github.com/rigortype/rigor/tree/master/docs
   rubygems_mfa_required: 'true'
+post_install_message: |
+  Rigor installs as a standalone CLI, not a project dependency. Run `rigor check app lib` from your
+  project root — no `bundle exec`.
+
+  If this came from `bundle add rigortype` or a Gemfile entry, remove it: Rigor runs on its own Ruby
+  and analyses your project from the outside, so in a Gemfile it constrains your application's Ruby
+  and dependency resolution without giving you anything. Per-project version pinning without that
+  cost, plus every other channel, is documented in
+  https://github.com/rigortype/rigor/blob/master/docs/install.md
 rdoc_options: []
 require_paths:
 - lib

data/lib/rigor/cli/ci_detector.rb

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