rigortype 0.4.1 → 0.4.2

data/docs/manual/plugins/README.md

@@ -14,7 +14,8 @@ The full catalogue, with a one-line scope for every plugin, is
 ## Available pages
 
 - [rigor-activerecord](rigor-activerecord.md) — ActiveRecord
-  finder / relation typing and schema-checked columns.
+  finder / relation typing and schema-checked columns; roots models reached only through an
+  association for `rigor unused`.
 - [rigor-rails-routes](rigor-rails-routes.md) — `*_path` / `*_url`
   helper validation against a parsed `config/routes.rb`.
 - [rigor-rails-i18n](rigor-rails-i18n.md) — `t(...)` / `I18n.t(...)`
@@ -69,6 +70,10 @@ The full catalogue, with a one-line scope for every plugin, is
   (`params`, `namespace`, verb macros, `desc`, `route_setting`) and
   `Grape::Entity` `expose` declarations, including the `instance_eval`'d
   block `self` bindings.
+- [rigor-alba](rigor-alba.md) — types the inline `Alba.serialize { }` block `self`, and
+  roots the resources alba infers from `many :articles` for `rigor unused`.
+- [rigor-typelizer](rigor-typelizer.md) — roots the serializer classes typelizer generates TypeScript
+  interfaces from, for `rigor unused`.
 - [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
   argument validation (out-of-range codes, unknown status symbols).
 - [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher

data/docs/manual/plugins/rigor-activerecord.md

@@ -228,6 +228,27 @@ member left out stays lenient rather than reported.
 `ActiveRecord::Base` is deliberately **not** declared: closing it would
 close every model in the project.
 
+## Roots for `rigor unused`
+
+```ruby
+class Recipe < ApplicationRecord
+  belongs_to :user                              # ActiveRecord loads User
+  has_many :comments, as: :commentable          # ... and Comment
+  has_many :tags, through: :taggings            # no root of its own, see below
+  belongs_to :owner, polymorphic: true          # no single target: no root
+end
+```
+
+`User` and `Comment` are named nowhere in the source, so [`rigor unused`](../02-cli-reference.md#rigor-unused) would list a model reached only this way. The plugin publishes the class each association resolves to as a `:reachability_roots` fact, mirroring ActiveRecord's own lookup:
+
+- a literal `class_name:` (String or Symbol, or a rooted `"::Foo"`) wins;
+- otherwise `has_many` / `has_and_belongs_to_many` use the singularized, camelized name and `belongs_to` / `has_one` the camelized name;
+- the name is tried as nested in the owner itself (`Post` looks for `Post::Comment`), then in the owner's enclosing namespaces innermost first (`Admin::Recipe` looks for `Admin::User`), then at top level. If a candidate is not a model but is a namespace of one, nothing is rooted, since ActiveRecord would pick that module.
+
+A root is published only when the project declares a model of that name. Nothing is published for a `polymorphic: true` association, a non-literal `class_name:` or `**options`, or a `through:` association without a literal `class_name:` / `source_type:` (a literal `source_type:` names the class; otherwise its target is the source association's, and that association roots it). Associations written inside `class << self`, a `def` or a block other than `with_options` are not seen, and neither is the block-parameter form `with_options(...) do |o| o.belongs_to :x end`. Literal options of a `with_options` group are merged into the associations inside it, the innermost group winning as in Rails; a group with non-literal options (`with_options opts do`) is skipped, as is `anonymous_class:`, an association whose own options hide the class (a `**splat`, an options variable, a non-literal `class_name:`), and a computed name equal to the owner's own name (Rails 7.2+ tries the top-level class first). The merged options also decide the association reader's type: `with_options optional: true` makes `belongs_to` readers nilable, and `class_name:` and `polymorphic:` set the target or make it `Dynamic`. The name is inflected with the real `ActiveSupport::Inflector`; if it cannot be loaded the plugin publishes nothing.
+
+The roots are flat: an association on a model `rigor unused` itself reports as dead still roots its target, so a chain of dead models can leave the last one unlisted. Project-custom inflections are not read, so a model whose name relies on one is under-rooted rather than wrongly rooted. The roots are published in reduced mode too, since they do not depend on the schema.
+
 ## Limitations
 
 - **Direct-superclass match only.** `class Admin < User` where

data/docs/manual/plugins/rigor-alba.md

@@ -0,0 +1,60 @@
+# rigor-alba
+
+Teaches Rigor about the [alba](https://github.com/okuramasafumi/alba) JSON serializer. alba does not ship its
+RBS in the gem, so without this plugin every alba call in your project reads `Dynamic[top]`. The plugin only
+removes false diagnostics and publishes `rigor unused` roots; it adds no diagnostic and no return type.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-alba
+```
+
+## What it does
+
+```ruby
+# Inline resources: the block runs on an anonymous Alba::Resource class, so `attributes` and friends resolve
+# instead of firing call.unresolved-toplevel.
+json = Alba.serialize(user) { attributes :id, :name }
+hash = Alba.hashify(user) { attributes :id }
+```
+
+The plugin contributes no return types: `Alba.serialize(obj)` runs your own `<Class>Resource#serialize`, which
+you may override to return anything.
+
+The block may sit anywhere a value can: `render json: Alba.serialize(x) { ... }` resolves the same as an
+assignment.
+
+## Roots for `rigor unused`
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  many :articles                               # alba loads ArticleResource, then ArticleSerializer
+  one :editor, resource: EditorResource        # explicit: nothing inferred
+end
+```
+
+`ArticleResource` appears nowhere in the source, so `rigor unused` would list it. The plugin publishes it as a
+root. It does so only for an association that gives no `resource:` / `serializer:`, no second argument and no
+block, and only when a class of the inferred name exists in the project (nesting-aware: inside `module Admin`
+alba tries `Admin::ArticleResource` first). The name is classified with the real `ActiveSupport::Inflector`;
+if it cannot be loaded the plugin publishes nothing.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-alba
+    config:
+      resource_search_paths: ["app"]   # default
+```
+
+`resource_search_paths` is where the plugin looks for resource classes. Widen it if your resources live
+outside `app/`.
+
+## More
+
+Internals and the known limits: [plugins/rigor-alba/README.md](../../../plugins/rigor-alba/README.md).

data/docs/manual/plugins/rigor-minitest.md

@@ -44,18 +44,36 @@ their `refute_*` equivalents.
 | --- | --- |
 | `assert_kind_of(T, x)` / `assert_instance_of(T, x)` | narrow to `T` |
 | `assert_nil(x)` | narrow to `Constant<nil>` |
-| `assert_equal(literal, x)` | narrow to `Constant<literal>` |
+| `assert_equal(literal, x)` | meet with `Constant<literal>` (see below) |
 | `assert_match(regex, x)` | narrow to `String` |
 | `refute_kind_of` / `refute_instance_of` (+ `assert_not_*`) | narrow away from `T` |
 | `refute_nil(x)` / `assert_not_nil(x)` | narrow away from nil |
-| `refute_equal(literal, x)` / `assert_not_equal(...)` | narrow away from `Constant<literal>` |
+| `refute_equal(literal, x)` / `assert_not_equal(...)` | unchanged |
 | `_(x).must_be_kind_of(T)` / `must_be_a(T)` / `must_be_instance_of(T)` / `must_be_an_instance_of(T)` | narrow to `T` |
 | `_(x).must_be_nil` | narrow to `Constant<nil>` |
-| `_(x).must_equal(literal)` | narrow to `Constant<literal>` |
+| `_(x).must_equal(literal)` | meet with `Constant<literal>` (see below) |
 | `_(x).must_match(regex)` | narrow to `String` |
 | `_(x).wont_be_kind_of(T)` / `wont_be_instance_of(T)` | narrow away from `T` |
 | `_(x).wont_be_nil` | narrow away from nil |
-| `_(x).wont_equal(literal)` | narrow away from `Constant<literal>` |
+| `_(x).wont_equal(literal)` | unchanged |
+
+### Equality is not identity
+
+`assert_equal(literal, x)` and `_(x).must_equal(literal)` pass when
+`literal == x`, and `==` can hold across classes: `1 == 1.0`,
+`1 == 1r`, and a class with its own `==` (a `ModInt` that compares
+`to_i`) passes `assert_equal 9, m`. The assertion therefore never
+replaces `x`'s type:
+
+- a `nil`, `true`, `false`, or Symbol literal has identity `==`, so `x`
+  narrows to that literal whatever its type was;
+- an Integer, Float, or String literal narrows `x` only when every
+  member of `x`'s type is already of the literal's class (or a `nil`,
+  boolean, or Symbol the literal cannot equal). After
+  `x = rand(10); assert_equal 9, x`, `x` is `9`;
+- otherwise — `x` is `Dynamic`, of a user class, or of another numeric
+  class (`assert_equal 9.0, x` with an Integer `x`), or the literal is
+  `0.0`, which `-0.0` also equals — `x` keeps its type.
 
 ## No diagnostics, no config
 

data/docs/manual/plugins/rigor-typelizer.md

@@ -0,0 +1,71 @@
+# rigor-typelizer
+
+Teaches `rigor unused` about the serializer classes the [typelizer](https://github.com/skryukov/typelizer) gem
+generates TypeScript types from. typelizer writes an interface for every named class that does
+`include Typelizer::DSL` or `extend Typelizer::DSL`, and for all of its subclasses. Such a class may never be
+referenced from Ruby and still be used by your frontend through the generated type, so without this plugin
+`rigor unused` lists it as a removal candidate. The plugin adds no diagnostic and no return type.
+
+It ships bundled in `rigortype`. Activate it under `plugins:`:
+
+```yaml
+plugins:
+  - rigor-typelizer
+```
+
+## What it roots
+
+```ruby
+# app/serializers/application_serializer.rb
+class ApplicationSerializer
+  include Typelizer::DSL           # rooted
+end
+
+# app/serializers/user_serializer.rb
+class UserSerializer < ApplicationSerializer   # rooted: a subclass of a DSL class
+end
+
+# app/serializers/event_serializer.rb
+class EventSerializer
+  extend Typelizer::DSL            # rooted
+end
+
+class PlainFormatter               # not rooted: no Typelizer::DSL on its chain
+end
+```
+
+A subclass is followed through any chain of project classes, and a compact header such as
+`class Admin::UserSerializer < Base` resolves `Base` the way Ruby does (against the lexical scope, not
+`Admin`).
+
+## What it does not root
+
+- A class outside the configured `dirs`. typelizer generates any DSL class that is loaded, but it loads only `dirs`;
+  a class elsewhere is loaded when something references it, so it is not dead.
+- A `module` that includes `Typelizer::DSL`. typelizer registers the module's own name and then calls
+  `.descendants` on it, which a plain module does not have, so it generates no interface.
+- A DSL call that does not run with the class as `self`: inside a method, a block, a lambda or `class << self`.
+- A class whose DSL comes only from an `ActiveSupport::Concern` `included do include Typelizer::DSL end` block.
+  typelizer does register such a class; the plugin does not follow module hooks, so this is a missed root and the
+  class stays a candidate.
+
+`reject_class`, the lambda typelizer's configuration uses to drop a class from the output, is evaluated at
+runtime and is not modelled. A rejected class is still rooted, which hides a candidate and never invents a
+finding.
+
+## Configuration
+
+```yaml
+plugins:
+  - gem: rigor-typelizer
+    config:
+      dirs: ["app/resources", "app/serializers"]   # default
+```
+
+`dirs` mirrors `Typelizer.dirs`; the default is what `Typelizer::Railtie` sets when you configure none. Set it
+to the same list you give typelizer. Superclasses are resolved over all of your project's `paths:`, so a class
+that shadows a base outside `dirs` is noticed.
+
+## More
+
+Internals and the known limits: [plugins/rigor-typelizer/README.md](../../../plugins/rigor-typelizer/README.md).

data/lib/rigor/analysis/check_rules/ivar_write_collector.rb

@@ -40,8 +40,10 @@ module Rigor
         NODE_CLASSES = [Prism::DefNode].freeze
         RULE_WALK_GATES = %i[inside_def detached_ivar_facet].freeze
 
-        # Returns `Hash[class_name (String) => Hash[ivar_name (Symbol) => Array<{node:, type:}>]]`. Empty
-        # when the tree has no qualifying writes.
+        # Returns `Hash[class_name (String) => Hash[ivar_name (Symbol) => Array<{node:, type:, declared:}>]]`.
+        # Empty when the tree has no qualifying writes. `declared` is the translated type of the class's RBS
+        # declaration of the ivar — an `@x: T` member or the slot an `attr_*` member implies, own or
+        # inherited — and nil when the RBS declares none.
         def initialize(scope_index)
           @scope_index = scope_index
           @accumulator = {}
@@ -112,9 +114,31 @@ module Rigor
           return if scope.nil?
 
           rvalue_type = scope.type_of(node.value)
+          declared = declared_ivar(scope, class_name, node.name)
           @accumulator[class_name] ||= {}
           @accumulator[class_name][node.name] ||= []
-          @accumulator[class_name][node.name] << { node: node, type: rvalue_type }
+          @accumulator[class_name][node.name] << { node: node, type: rvalue_type, declared: declared }
+        end
+
+        def declared_ivar(scope, class_name, ivar_name)
+          loader = scope.environment&.rbs_loader
+          return nil if loader.nil?
+
+          variable = loader.instance_definition(class_name)&.instance_variables&.[](ivar_name)
+          return nil if variable.nil?
+
+          translate_declared(variable.type, loader, class_name)
+        end
+
+        # `self` / `instance` in a class's declaration is that class; a module's stays untyped, since its
+        # instances belong to includers no RBS type names. A translation failure reads as untyped, which only
+        # ever withholds a finding.
+        def translate_declared(rbs_type, loader, class_name)
+          owner = Type::Combinator.nominal_of(class_name) unless loader.rbs_module?(class_name)
+          Inference::RbsTypeTranslator.translate(rbs_type, self_type: owner, instance_type: owner,
+                                                           alias_expander: loader)
+        rescue StandardError
+          Type::Combinator.untyped
         end
       end
     end

data/lib/rigor/analysis/check_rules/lexical_method_sites.rb

@@ -3,7 +3,6 @@
 require "prism"
 
 require_relative "../../inference/scope_indexer"
-require_relative "../../source/constant_path"
 require_relative "../../source/node_children"
 
 module Rigor
@@ -12,13 +11,9 @@ module Rigor
       # Issue #1120 — the two ways one file makes a method callable at some sites and not at others, which
       # `call.undefined-method` has to ask the file's syntax about because no project-wide table can answer:
       #
-      # - **Refinements.** `using M` activates M's refinements from the end of the call to the end of the body
-      #   that holds it — the file's top level or a `class` / `module` body, including everything nested in it —
-      #   and nowhere else, not even in another file. A `refine X do … end` block is active inside itself. What
-      #   each module refines is the project-wide `Scope#discovered_refinements`; this answers whether any of
-      #   those modules is in effect at a call site. A `using` whose argument is not a constant
-      #   (`using Module.new { refine … }`) names no module, so every refinement counts as in effect throughout
-      #   its file. A `using` inside a `def` raises in Ruby and activates nothing.
+      # - **Refinements.** Issue #1673 — answered by the file's in-effect refinements ({#refinements}, the
+      #   {Inference::InEffectRefinements} the typer reads too); the rules ask it for derived answers
+      #   (`refinement_active?`, `any_at?`, `refinement_def?`).
       # - **Singleton defs on locals.** `def o.m` defines `m` on the one object `o` holds. The local's type
       #   is not changed; `o.m` is simply not reported within the scope the `def` is written in (the
       #   enclosing `def`, `class` / `module` body, or file — a block shares its enclosing scope's locals).
@@ -26,42 +21,18 @@ module Rigor
       # Built lazily: the walk runs the first time a would-fire call asks, so a file with no such call pays
       # one small object and nothing else.
       class LexicalMethodSites
-        def initialize(root)
+        # Issue #1703 — the file's root, which `call.possible-nil-receiver` re-walks for a `key?` guard.
+        attr_reader :root
+
+        # `refinements` is the query `Inference::ScopeIndexer` stamped on the file's discovery index, so the rules and
+        # the typer share one walk; a query over another tree, or none, builds this file's own on the first ask.
+        def initialize(root, refinements = nil)
           @root = root
           @built = false
+          @refinements = refinements if refinements&.over?(root)
         end
 
-        # Is a refinement from one of `modules` (refining-module names) in effect at `call_node`?
-        def refinement_active?(call_node, modules)
-          build
-          return true if @unresolved_using
-
-          offset = call_node.location.start_offset
-          return true if @refine_blocks.any? { |start, stop| offset >= start && offset < stop }
-
-          @usings.any? do |start, stop, candidates|
-            offset >= start && offset < stop && candidates.any? { |name| modules.include?(name) }
-          end
-        end
-
-        # Issue #1367 — is any refinement in effect at `node`: a `using` of any module, a `using` of a non-constant, or
-        # the inside of a `refine` block? The `global.*` stream check asks it where it cannot name the refining
-        # module (a `define_method` or `alias_method` inside `refine` records none).
-        def using_in_effect?(node)
-          build
-          return true if @unresolved_using
-
-          offset = node.location.start_offset
-          @refine_blocks.any? { |start, stop| offset >= start && offset < stop } ||
-            @usings.any? { |start, stop, _candidates| offset >= start && offset < stop }
-        end
-
-        # Is `def_node` one of the defs a `refine X do … end` body defines on X? Such a def redefines X's method by
-        # design, so X's declared signature for the name is not its contract (issue #1120, maintainer ruling a′).
-        def refinement_def?(def_node)
-          build
-          @refinement_defs.include?(def_node.location.start_offset)
-        end
+        def refinements = (@refinements ||= Inference::InEffectRefinements.new(@root))
 
         # Does a `def <local>.<name>` for this call's local receiver and method name sit in the scope the call
         # is in?
@@ -92,45 +63,35 @@ module Rigor
           return if @built
 
           @built = true
-          @usings = []
-          @refine_blocks = []
           @singleton_defs = []
           @scopes = []
-          @refinement_defs = Set.new
-          @unresolved_using = false
           return if @root.nil?
 
           location = @root.location
           span = [location.start_offset, location.end_offset]
-          walk(@root, [], span, span, false)
+          walk(@root, span)
         end
 
-        # `body` is the `[start, end]` of the body a `using` here stays in effect to the end of; `locals` is the
-        # span of the scope a local written here belongs to.
-        def walk(node, prefix, body, locals, in_def)
+        # `locals` is the span of the scope a local written here belongs to.
+        def walk(node, locals)
           case node
           when Prism::ClassNode, Prism::ModuleNode
-            span = scope_span(node)
-            inner = Source::ConstantPath.declaration_prefix(prefix, node.constant_path) || prefix
-            return walk_children(node.body, inner, span, span, false)
+            return walk_children(node.body, scope_span(node))
           when Prism::SingletonClassNode
-            walk(node.expression, prefix, body, locals, in_def)
-            span = scope_span(node)
-            return walk_children(node.body, prefix, span, span, false)
+            walk(node.expression, locals)
+            return walk_children(node.body, scope_span(node))
           when Prism::DefNode
             record_singleton_def(node, locals)
-            return walk_children(node.body, prefix, body, scope_span(node), true)
-          when Prism::CallNode
-            record_call(node, prefix, body, in_def)
+            return walk_children(node.body, scope_span(node))
           end
 
-          walk_children(node, prefix, body, locals, in_def)
+          walk_children(node, locals)
         end
 
-        def walk_children(node, prefix, body, locals, in_def)
+        def walk_children(node, locals)
           return if node.nil?
 
-          node.rigor_each_child { |child| walk(child, prefix, body, locals, in_def) }
+          node.rigor_each_child { |child| walk(child, locals) }
         end
 
         def record_singleton_def(node, locals)
@@ -140,38 +101,6 @@ module Rigor
           @singleton_defs << [receiver.name, node.name, *locals]
         end
 
-        def record_call(node, prefix, body, in_def)
-          if Inference::ScopeIndexer.refine_target(node)
-            @refine_blocks << span_of(node.block)
-            record_refinement_defs(node.block.body)
-          elsif using_call?(node) && !in_def
-            record_using(node, prefix, body)
-          end
-        end
-
-        def record_refinement_defs(body)
-          return if body.nil?
-
-          Inference::ScopeIndexer.each_refinement_def(body) do |def_node|
-            @refinement_defs << def_node.location.start_offset
-          end
-        end
-
-        def using_call?(node)
-          node.name == :using && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
-            node.arguments&.arguments&.size == 1
-        end
-
-        def record_using(node, prefix, body)
-          argument = node.arguments.arguments.first
-          if argument.is_a?(Prism::ConstantReadNode) || argument.is_a?(Prism::ConstantPathNode)
-            candidates = Inference::ScopeIndexer.constant_receiver_candidates(argument, prefix)
-            @usings << [node.location.end_offset, body.last, candidates]
-          else
-            @unresolved_using = true
-          end
-        end
-
         # The span of a node that opens a local scope, recorded for {#nested_scope_holds?}.
         def scope_span(node)
           span = span_of(node)