rigortype 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5960ec17b35768103e97d752f8cc6fd78fcb3f12e12fc43dfa41be07ec5317b
-  data.tar.gz: e79c9b25c973c8938e9b2f0a2741cca5195342619827b320ca521ec09e54321e
+  metadata.gz: 1a2903b58458e4dafb9acfb05574d615031a79b8b7b521b02029bd30b07ef433
+  data.tar.gz: cf13a88ee96fe6a3acb471fb8f8936407b28bae6bd92852e8263b11ec0738870
 SHA512:
-  metadata.gz: af1e033a25410c0f87943f12d43ab18a3a0d2a79c01307c2117c2fc15be4c9db3cb28e6fec10ce598ef6a5bfa063227f280c023a0f7e9025b06c69946df4654d
-  data.tar.gz: 351b3275dd35f37a11d30a696627e23a6cdca31bfb94fa3eacae762d2de624e4a914c6f8f4eebdd7df0bd17fd9fac13fe55ac434957509b742771a00d352a981
+  metadata.gz: 5761ae7907222592d4fd8a7c747e24f414c95fc2ce2ce2b0385a8277b0860aaa89c76c2da94b37575f3a79ac6dddbd4fd21fd16f8064ded1aecbb0e5fadb68f7
+  data.tar.gz: 8c98d8abd24b9eacef42ba5dbcade9481427a03b61c57306efb273b34ca7b2cbdc73535d3c7495aba90b13051274f9df715a6064f98e9ffb9bdbc995e573560e

data/README.md

@@ -15,13 +15,32 @@ for any class it can find, and reports a small but trustworthy
 catalogue of bugs (undefined methods on typed receivers, wrong
 positional arity, provable `Integer / 0`, …).
 
-The differentiator is a richer type vocabulary than ordinary
-RBS expresses. Rigor reasons about *what values an expression
-actually produces* — literal values, integer ranges,
-refinement-type carriers, per-position tuple / hash shapes —
-not just *which class an object belongs to*. See **[Beyond
-`Integer` and `String`](#beyond-integer-and-string-rigors-richer-type-vocabulary)**
-for the full type-model story; the short pitch is below.
+**Two design commitments drive Rigor.**
+
+1. **Types are facts, not wishes.** Hand-written type
+   annotations drift from the implementation the moment they
+   are written. Rigor infers from the code itself — every
+   carrier in its type vocabulary is derived from what your
+   source actually produces, not from a signature you authored
+   and might forget to update. When you do want RBS in
+   `sig/`, [`rigor sig-gen`](docs/adr/14-rbs-sig-generation.md)
+   emits it from inference results so the written form starts
+   in sync with reality, and `tighter-return` candidates flag
+   the cases where an existing `.rbs` is already weaker than
+   what the implementation provably returns.
+2. **Programmable inference beyond unions.** A plain union
+   (`Integer | nil`) is not the type story Ruby needs. Rigor
+   reasons about *what values an expression actually
+   produces* — literal values, integer ranges, refinement
+   carriers, per-position tuple / hash shapes, bound-method
+   bindings — and exposes a plugin extension API plus an
+   [ADR-16](docs/adr/16-macro-expansion.md) macro / DSL
+   expansion substrate so Rails-shape DSLs are first-class
+   type sources rather than analysis blind spots.
+
+See **[Beyond `Integer` and `String`](#beyond-integer-and-string-rigors-richer-type-vocabulary)**
+for the full type-model story; the carrier-zoo table is the
+short pitch.
 
 When you want tighter types than RBS expresses, refine them
 through the
@@ -532,7 +551,7 @@ Common knobs the file exposes:
 
 ## Status
 
-Current released version: **`v0.1.4`**. The analyzer is usable
+Current released version: **`v0.1.5`**. The analyzer is usable
 on real Ruby code today; the rule catalogue is deliberately
 narrow — Rigor's stance is to surface zero false positives
 while the inference surface stabilises. Forward-looking commitments
@@ -540,50 +559,19 @@ while the inference surface stabilises. Forward-looking commitments
 [`docs/ROADMAP.md`](docs/ROADMAP.md); the release-by-release
 "what shipped" record is [`CHANGELOG.md`](CHANGELOG.md).
 
-`v0.1.4` (released 2026-05-14) delivered:
-
-- **[ADR-10](docs/adr/10-dependency-source-inference.md) closed
-  end-to-end** — opt-in gem-source inference, per-gem budget,
-  cache slice, and the `dynamic.dependency-source.boundary-cross`
-  `:info` diagnostic that surfaces RBS / gem-source overlap
-  under `mode: :full`.
-- **[ADR-11](docs/adr/11-sorbet-input-adapter.md) primary surface
-  + per-call-site assertion gating** — `rigor-sorbet` ingests
-  Sorbet `sig { ... }` blocks, `T.let` / `T.cast` / `T.must` /
-  `T.bind` / `T.assert_type!` / `T.reveal_type` / `T.absurd`,
-  and RBI files. Per-call-site `enforce_sigil` gates assertion
-  recognisers by the caller file's `# typed:` sigil.
-- **[ADR-13](docs/adr/13-typenode-resolver-plugin.md) plugin
-  TypeNode resolver + TypeScript-utility-type adapter** —
-  `Plugin::TypeNodeResolver` extension point + five
-  Rigor-canonical shape-projection type functions
-  (`pick_of` / `omit_of` / `partial_of` / `required_of` /
-  `readonly_of`) + the opt-in `rigor-typescript-utility-types`
-  plugin mapping TS spellings onto the core functions.
-  `Pick[T, :a | :b]` round-trips through the directive grammar.
-- **[ADR-14](docs/adr/14-rbs-sig-generation.md) — `rigor sig-gen`
-  CLI** — emits RBS from inference results across five
-  classifications (`new-file` / `new-method` / `tighter-return`
-  / `equivalent` / `skipped`); `--params=untyped` default,
-  `--params=observed` opt-in via `--observe=PATH`.
-- **`Method` carrier (`Type::BoundMethod`)** —
-  `Object#method(:sym).call` / `.()` / `[]` round-trip with
-  full precision instead of collapsing to `untyped`.
-- **Rails ecosystem (Tier 1 + Tier 2)** — `rigor-rails-routes`,
-  `rigor-rails-i18n`, `rigor-actionmailer`, `rigor-activejob`,
-  `rigor-actionpack` (4 phases), `rigor-factorybot`, and
-  `rigor-activerecord` publishing `:model_index` via the
-  ADR-9 cross-plugin fact channel.
+`v0.1.5` (released 2026-05-16) delivered (full slice list in `CHANGELOG.md` § `[0.1.5]`):
+
+- **ADR-15 Ractor migration end-to-end** (Phases 1–4c + 4b.x) — opt-in `rigor check --workers=N` parallelism; pool ≡ sequential proven on 14 real-world projects (31,840 files); spec-suite wall-clock 162s → 27s on 12 cores via `parallel_tests`.
+- **[ADR-16](docs/adr/16-macro-expansion.md) macro / DSL expansion substrate** — four-tier declarative manifest contract (block-as-method, trait-inlining registry, heredoc-template, external-file) with Tier B/C precision promotion and three worked consumer plugins (`rigor-sinatra`, `rigor-devise`, `rigor-dry-struct`). Closes ROADMAP O2 at the WD13 floor.
+- **Real-world Rails / Ruby survey** — fourteen projects swept; opt-in `rigor-activesupport-core-ext` RBS bundle delivers `−75 %` total diagnostics; built-in vendored gem RBS for six native-extension gems (`pg` / `mysql2` / `nokogiri` / `bcrypt` / `redis` / `idn-ruby`); Bundler-aware sig discovery; `RbsLoader#env` failure-memo (~550× speedup on a conflicting sig).
+- **O4 Layer 3 target-project RBS source discovery (slices 1+2+3)** — `Gemfile.lock` parse + bundle-sig filter, `rbs_collection.lock.yaml` awareness, missing-gem `:info` diagnostic.
+- **DEFAULT_LIBRARIES stdlib coverage expansion** — out-of-the-box RBS classes available 1,273 → 1,427 (+154); 31 additional stdlib libraries auto-load.
+- **`is_a?(C)` lexical-nesting constant resolution** — predicate-narrowing now mirrors Ruby's `Module.nesting`-driven lookup.
 
 Twenty-four worked plugin examples now ship under
 [`examples/`](examples/) — see
 [`examples/README.md`](examples/README.md) for the comparison
-table. The current `[Unreleased]` cycle on `master` (release
-pending) also delivered the [ADR-16](docs/adr/16-macro-expansion.md)
-macro / DSL expansion substrate (four-tier declarative
-manifest contract + engine integration + Tier B/C precision
-promotion); see `CHANGELOG.md` `[Unreleased]` for the full
-landing notes.
+table.
 
 ## Contributing
 
@@ -594,5 +582,3 @@ skill documentation contributors should know about.
 ## License
 
 Mozilla Public License Version 2.0. See [`LICENSE`](LICENSE).
-</content>
-</invoke>

data/lib/rigor/analysis/buffer_binding.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Binds one logical project path (the path the user is editing,
+    # e.g. `lib/foo.rb`) to a physical file containing the in-flight
+    # buffer bytes (e.g. `/tmp/9539itfeh2.rb`). When the runner /
+    # workers / pre-passes need to read source for the logical path,
+    # they read from the physical path instead; when they emit a
+    # `Diagnostic`, the path is the logical one so editors highlight
+    # the buffer the user is actually looking at.
+    #
+    # See `docs/design/20260516-editor-mode.md` for the design.
+    # The CLI surfaces this through paired `--tmp-file` /
+    # `--instead-of` flags on `rigor check` and `rigor type-of`;
+    # programmatic callers pass a `BufferBinding` to `Runner.new`.
+    BufferBinding = Data.define(:logical_path, :physical_path) do
+      # Returns the physical path to read bytes from when the caller
+      # is about to parse `path`. For non-logical paths returns the
+      # input unchanged. Cheap to call on every path; the binding is
+      # singular today (one buffer per run).
+      def resolve(path)
+        path == logical_path ? physical_path : path
+      end
+
+      # Returns the path the caller should report in user-facing
+      # output (diagnostics, run stats) when it currently holds the
+      # physical path. The inverse of `#resolve`. Non-physical paths
+      # pass through unchanged, so it is safe to stamp every
+      # outgoing path through this helper.
+      def display_path(path)
+        path == physical_path ? logical_path : path
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules.rb

@@ -944,8 +944,18 @@ module Rigor
         # / Constant / Tuple / HashShape; the wrapper exists so
         # the ivar rule can extend the envelope (or apply
         # different filters) without disturbing the call rules.
+        #
+        # `TrueClass` / `FalseClass` are both normalised to
+        # `"bool"` here so the common boolean-flag idiom
+        # (`@loaded = false` in `initialize` then `@loaded = true`
+        # on first work) doesn't fire the mismatch rule. A real
+        # `bool → String` drift still trips because the second
+        # write's `ivar_class_for` returns `"String"`.
         def ivar_class_for(type)
-          concrete_class_name(type)
+          name = concrete_class_name(type)
+          return "bool" if %w[TrueClass FalseClass].include?(name)
+
+          name
         end
 
         def build_always_truthy_condition_diagnostic(path, predicate_node, polarity)

data/lib/rigor/analysis/dependency_source_inference/index.rb

@@ -54,7 +54,7 @@ module Rigor
         )
           @resolved_gems = resolved_gems.freeze
           @unresolvable = unresolvable.freeze
-          @method_catalog = method_catalog.freeze
+          @method_catalog = normalize_catalog(method_catalog).freeze
           @budget_exceeded = budget_exceeded.freeze
           @class_to_gem = class_to_gem.freeze
           @budget_overrun_strategy = budget_overrun_strategy
@@ -62,6 +62,19 @@ module Rigor
           freeze
         end
 
+        # Accepts both the post-heuristic `CatalogEntry` shape
+        # (the Walker's current output) and the legacy bare-Symbol
+        # `:instance` / `:singleton` shape (older tests + earlier
+        # in-tree callers). Symbol values are wrapped into
+        # `CatalogEntry(kind: value, return_type: nil)` so the
+        # downstream dispatcher always sees a single shape.
+        def normalize_catalog(catalog)
+          catalog.transform_values do |value|
+            value.is_a?(Symbol) ? Walker::CatalogEntry.new(kind: value) : value
+          end
+        end
+        private :normalize_catalog
+
         # @return [String, nil] the gem that owns `class_name`
         #   (first-write-wins); `nil` when the class isn't in
         #   any opt-in gem's catalog.

data/lib/rigor/analysis/dependency_source_inference/return_type_heuristic.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../type"
+
+module Rigor
+  module Analysis
+    module DependencySourceInference
+      # Walker enhancement (ADR-10 § "Open questions"): pulls a
+      # **heuristic** return type out of a method body's tail
+      # expression. The heuristic is intentionally narrow — only
+      # the trivially-decidable shapes contribute. Everything
+      # else returns `nil`, which the dispatcher consumes as
+      # "fall back to `Dynamic[top]`" (the pre-enhancement
+      # behaviour).
+      #
+      # The contract is a strict floor:
+      #
+      # - Last statement is a literal scalar (Integer / Float /
+      #   Symbol / true / false / nil) → `Constant<value>`.
+      # - Last statement is a String literal → `Nominal[String]`
+      #   (NOT `Constant<"x">`; a String literal is mutable under
+      #   `# frozen_string_literal: false`, so the analyzer cannot
+      #   claim object identity).
+      # - Last statement is an Array / Hash literal →
+      #   `Nominal[Array]` / `Nominal[Hash]` (element-type
+      #   inference stays deferred — too expensive for the
+      #   heuristic tier).
+      # - Last statement is `self` → `nil` (the caller's receiver
+      #   nominal would be more accurate but the walker doesn't
+      #   carry the receiver context; deferred).
+      # - Anything else → `nil`.
+      #
+      # The dispatcher wraps the returned type in `Dynamic[T]`
+      # before returning to the user per ADR-10's `Dynamic`-origin
+      # contract. The wrapping is the dispatcher's responsibility,
+      # not the heuristic's.
+      module ReturnTypeHeuristic
+        module_function
+
+        # @param def_node [Prism::DefNode]
+        # @return [Rigor::Type, nil] heuristic return type, or
+        #   `nil` when the body's tail expression doesn't match
+        #   any of the recognised shapes.
+        def extract(def_node)
+          body = def_node.body
+          return nil if body.nil?
+
+          tail = tail_expression(body)
+          literal_return_type(tail)
+        end
+
+        # Extracts the last evaluated expression of the method
+        # body. A `Prism::DefNode`'s body is either a
+        # `StatementsNode` (multi-statement body) or a single
+        # expression node directly. We dig past `BeginNode` /
+        # rescue wrappers to the protected body's tail.
+        def tail_expression(node)
+          case node
+          when Prism::StatementsNode
+            tail_expression(node.body.last) unless node.body.empty?
+          when Prism::BeginNode
+            tail_expression(node.statements) if node.statements
+          when nil
+            nil
+          else
+            node
+          end
+        end
+        private_class_method :tail_expression
+
+        # The per-shape heuristic. Per the module docstring,
+        # immutable scalar literals fold to `Constant<value>`;
+        # mutable container literals (String, Array, Hash) fold
+        # to the appropriate Nominal; everything else returns
+        # nil.
+        def literal_return_type(node)
+          case node
+          when Prism::IntegerNode, Prism::FloatNode then Type::Combinator.constant_of(node.value)
+          when Prism::SymbolNode then symbol_constant(node)
+          when Prism::TrueNode then Type::Combinator.constant_of(true)
+          when Prism::FalseNode then Type::Combinator.constant_of(false)
+          when Prism::NilNode then Type::Combinator.constant_of(nil)
+          when Prism::StringNode then Type::Combinator.nominal_of("String")
+          when Prism::ArrayNode then Type::Combinator.nominal_of("Array")
+          when Prism::HashNode then Type::Combinator.nominal_of("Hash")
+          end
+        end
+        private_class_method :literal_return_type
+
+        # `Prism::SymbolNode#value` returns the Symbol's name as
+        # a String. We `.to_sym` it for the Constant carrier so
+        # `:foo` is `Constant<:foo>`, not `Constant<"foo">`.
+        def symbol_constant(node)
+          value = node.value
+          return nil if value.nil?
+
+          Type::Combinator.constant_of(value.to_sym)
+        end
+        private_class_method :symbol_constant
+      end
+    end
+  end
+end

data/lib/rigor/analysis/dependency_source_inference/walker.rb

@@ -2,23 +2,26 @@
 
 require "prism"
 
+require_relative "return_type_heuristic"
+
 module Rigor
   module Analysis
     module DependencySourceInference
       # Walks a resolved gem's `roots:` and collects the
-      # `(class_name, method_name) → :instance | :singleton`
-      # method catalog. The walker is the source of facts the
-      # dispatcher tier (slice 2b-ii) consults to recognise a
+      # `(class_name, method_name) → CatalogEntry(kind,
+      # return_type)` method catalog. The walker is the source
+      # of facts the dispatcher tier consults to recognise a
       # method as defined by an opt-in gem and contribute a
-      # `Type::Dynamic` return at the call site.
+      # `Type::Dynamic`-wrapped return at the call site.
       #
-      # Slice 2b-i intentionally collects only the catalog, not
-      # the inferred return type. The dispatcher tier returns
-      # `Dynamic[top]` on a hit until slice 2b-ii wires return-
-      # type inference; the visible payoff today is removing the
-      # `call.undefined-method` diagnostic for opt-in gem methods
-      # at receivers Rigor knows by `Nominal[T]` (typically
-      # because the user authored an RBS skeleton).
+      # The dispatcher tier wraps every walker-contributed return
+      # in `Dynamic[T]` per ADR-10's gem-boundary contract. When
+      # the heuristic ({ReturnTypeHeuristic}) recognises the
+      # method body's tail expression, the dispatcher uses the
+      # heuristic's static facet; otherwise it falls back to
+      # `Dynamic[top]` (the pre-heuristic behaviour). The
+      # heuristic is intentionally narrow — only literal-tail
+      # method bodies fold; everything else degrades silently.
       #
       # Hard exclusions are NOT user-configurable, per ADR-10
       # § "Hard exclusions": top-level `spec/`, `test/`, `bin/`,
@@ -45,6 +48,19 @@ module Rigor
           def truncated? = truncated
         end
 
+        # Per-method catalog entry. `kind` is `:instance` or
+        # `:singleton`; `return_type` is the
+        # {ReturnTypeHeuristic}-extracted static facet (a
+        # `Rigor::Type::*`) or `nil` when the heuristic declined.
+        # The dispatcher wraps a non-nil `return_type` in
+        # `Dynamic[T]`; a `nil` `return_type` falls back to
+        # `Dynamic[top]`.
+        class CatalogEntry < Data.define(:kind, :return_type)
+          def initialize(kind:, return_type: nil)
+            super
+          end
+        end
+
         # Sentinel for "no cap" — used by callers that don't
         # care about the budget (specs, tooling). Production
         # code MUST pass an integer.
@@ -175,7 +191,11 @@ module Rigor
 
           class_name = qualified_prefix.join("::")
           kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
-          accumulator[[class_name, node.name]] ||= kind
+          key = [class_name, node.name]
+          return if accumulator.key?(key) # first walk wins
+
+          return_type = ReturnTypeHeuristic.extract(node)
+          accumulator[key] = CatalogEntry.new(kind: kind, return_type: return_type)
         end
 
         # Resolves a `Prism::ConstantPathNode` /

data/lib/rigor/analysis/project_scan.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Frozen snapshot of the project-wide state {Runner} consumes
+    # before per-file analysis fires: the loaded plugin registry
+    # (with `#prepare` already invoked), the dependency-source
+    # index, the synthetic-method and project-patched indexes
+    # produced by the pre-pass scanners, and the diagnostics
+    # those passes emitted.
+    #
+    # Owners (`Rigor::LanguageServer::ProjectContext`, future
+    # editor / sig-gen integrations) build a ProjectScan once
+    # per project-state generation via
+    # `Runner#prepare_project_scan` and pass it to
+    # `Runner.new(prebuilt: ...)` so per-buffer publishes skip
+    # the scanner walks and `#prepare` re-runs. When watched
+    # project files change, the owner discards the ProjectScan
+    # and a fresh one builds on next read.
+    #
+    # Editor mode v1 contract reminder: scanners observe the
+    # bytes that were on disk at scan time, NOT the in-flight
+    # buffer. Edits to a file that itself declares synthetic
+    # methods (or `pre_eval:`-listed patches) are NOT visible
+    # until the owner invalidates the scan — typically via
+    # `workspace/didChangeWatchedFiles`. This is the same
+    # trade-off the LSP made when slice 7 cached only the
+    # `Environment`; extending the cache to the pre-pass
+    # outputs preserves the contract.
+    ProjectScan = Data.define(
+      :plugin_registry,
+      :dependency_source_index,
+      :synthetic_method_index,
+      :project_patched_methods,
+      :plugin_prepare_diagnostics,
+      :pre_eval_diagnostics
+    )
+  end
+end