rigortype 0.3.8 → 0.4.0

data/plugins/rigor-activerecord/sig/active_record/relation.rbs

@@ -31,7 +31,7 @@
 #
 # Every method carries an effect annotation, and the split down
 # the middle of this file is the whole point of the Rails effect
-# layer: a **builder** is `%a{pure}` because it issues nothing —
+# layer: a **query builder** is `%a{pure}` because it issues nothing —
 # `where` composes an Arel tree and returns a relation — while a
 # **materializer** is `%a{rigor:v1:effect io.db.read}` because it
 # is the call that finally runs the query. A presenter that builds
@@ -46,6 +46,136 @@
 # `Enumerable` surface, which materialise by delegating to `each`
 # — are covered by the plugin's `effect_attributions:` instead,
 # because declaring them here would change how they TYPE.
+#
+# ## Every bound here also bounds the association's relations
+#
+# A `has_many` reader returns an
+# `ActiveRecord::Associations::CollectionProxy`, and a query
+# builder called on the proxy (`user.posts.where(…)`) returns an
+# `ActiveRecord::AssociationRelation`. Both are Relation subclasses
+# that still hold the association, and the plugin types both as
+# `Relation[Model]`. A call on either imports this file's bound, so
+# each annotation has to hold for all three classes. The facts below
+# are checked against activerecord 8.1.3.1.
+#
+# Where one of them adds records to the association's in-memory
+# target or discards them from it, the bound carries `mutate.self`:
+#
+# - `build` / `new`, `create` / `create!` and the `find_or_*`,
+#   `create_or_find_by` and `first_or_*` builders reach
+#   `@association.build` / `create`, which call `add_to_target`. On
+#   the proxy they are overrides. On an AssociationRelation they are
+#   its private `_new` / `_create`.
+# - `reset`, `reload`, `delete_all` and `destroy_all` on the proxy
+#   reset the association, which drops every record built there and
+#   not yet saved. So do `update_all` and `touch_all`: the proxy does
+#   not override them, and Relation's version ends with
+#   `.tap { reset }`, which reaches the proxy's `reset`.
+# - `insert`, `insert!` and `upsert`, and their `_all` forms, on the
+#   proxy reset the target only when it holds no unsaved record.
+#   Rails 8.1 deprecates the other branch and says those records will
+#   be lost in 8.2. The bound is written for 8.2, and it over-states
+#   8.1.
+#
+# So `user.posts.build` changes an object the caller can still reach
+# through `user`: `user.posts.size` counts the new record, and
+# `user.save` saves it. On a plain Relation, `new` and `build` change
+# nothing, so `mutate.self` over-states them there. The type cannot
+# tell the receivers apart, and an upper bound may be too wide but
+# never too narrow.
+#
+# Loading is not counted as a change. `to_a` and `load` fill the
+# target with what the database holds, which is the `io.db.read` they
+# already carry.
+#
+# `mutate.self` is written from the callee's side, as any envelope
+# is: the receiver changes itself. A caller imports the label
+# unchanged, so in the caller's row it names the proxy it called,
+# not the caller's own `self`.
+#
+# `insert`, `insert!` and `upsert` are declared here, beside their
+# `_all` forms, because a plain Relation defines them too. The
+# declaration changes no result type: an undeclared method on this
+# open receiver already types as `untyped`. It adds the checks any
+# declared method gets, `call.wrong-arity` and
+# `call.possible-nil-receiver`, and its parameter list admits every
+# call Rails accepts.
+#
+# The writers a plain Relation does not define (`<<`, `push`,
+# `append`, `concat`, `replace`, `clear`) are rows in the plugin's
+# `effect_attributions:` rather than declarations here. The same rows
+# cover `delete` / `destroy`, which a Relation does define, as
+# `delete(id_or_array)` and `destroy(id)`, but the proxy overrides as
+# `delete(*records)` and `destroy(*records)`. A declaration here
+# would need a parameter list and a return wide enough for both, and
+# it would give the two methods a second effect channel next to
+# their rows.
+#
+# ## Every parameter list here also admits the overrides
+#
+# The rule above holds for parameter lists as well as effect bounds.
+# A call on the proxy or on an AssociationRelation is checked against
+# the parameter list declared here, so a declaration must accept
+# every argument an override accepts, or valid Rails draws
+# `call.wrong-arity`. Of the overrides this file declares, only the
+# proxy's `delete_all(dependent = nil)` accepts more than the
+# Relation's `delete_all`. It takes `:nullify` or `:delete_all`, so
+# `delete_all` declares an optional argument. The price is that
+# `delete_all(:nullify)` on a plain Relation or on an
+# AssociationRelation (`user.posts.where(…)`), neither of which
+# overrides it, raises `ArgumentError` and goes unreported.
+#
+# Of the rest, the `(...)` methods of the `insert` and `insert_all`
+# families and the proxy's `delegate … to: :scope` block (the query
+# builders and `scoping`) forward their arguments unchanged to the
+# Relation's own methods, and the proxy's other overrides (`find`,
+# `last`, `take`, `build`, `create`, `calculate`, `pluck`, …) take no
+# more than the declarations here. `delete` and `destroy`, whose
+# overrides take more arguments than the Relation's, stay undeclared
+# for the reasons above.
+#
+# ## A writer that also queries carries the read too
+#
+# `io.db.write` does not include `io.db.read`: they are sibling
+# leaves. So a writer that queries before its write, or after a failed
+# one, names both. In activerecord 8.1.3.1:
+#
+# - `find_or_create_by(!)` is `find_by || create_or_find_by`, and
+#   `first_or_create(!)` is `first || create`.
+# - `create_or_find_by(!)` rescues `RecordNotUnique` with `find_by!`.
+# - `destroy_all` is `records.each(&:destroy)`, which loads first, and
+#   `destroy_by` is `where(…).destroy_all`. `update(!)` walks `each`,
+#   or passes an id to the model's `update`, which calls `find`.
+# - `update_all` and `delete_all`, and so `touch_all` and `delete_by`,
+#   first `SELECT` the distinct primary keys when the relation
+#   eager-loads, has a limit or offset and no `group`, and eager-loads
+#   or joins a collection association (`apply_join_dependency`). The
+#   proxy's `delete_all` on a `has_many :through` loads the target
+#   before it deletes.
+# - `create(!)` on the proxy of a `has_many :through` a `has_one`
+#   builds the join record through the `has_one`, which loads the
+#   record it replaces.
+#
+# The `insert` and `insert_all` families stay `io.db.write` alone.
+# Each compiles one `INSERT` statement and queries nothing else: the
+# proxy's override reads only the target it already holds in memory.
+#
+# Two kinds of query are not counted. Schema reflection is one: the
+# column and index lookups the schema cache serves would otherwise
+# make `where` a read. The model's callbacks and validators are the
+# other, including those an association option such as `dependent:`
+# or `touch:` registers. They are not part of any bound here. The
+# plugin's callback edge carries only symbol-argument callback macros
+# and a uniqueness validator, and only on the model's own `save` /
+# `destroy`. Nothing carries the reads a required `belongs_to`,
+# `touch:` or `dependent:` registers.
+#
+# One case is not covered. On that same `has_many :through` a
+# `has_one`, `new` / `build` also build the join record when the
+# source reflection has an inverse, and so do `find_or_initialize_by`
+# and `first_or_initialize`, which reach `new`. The `has_one` then
+# replaces its record: it loads the old one, and even without a
+# save it can delete, destroy or save it.
 
 module ActiveRecord
   class Relation[Elem]
@@ -101,6 +231,10 @@ module ActiveRecord
     def left_outer_joins: (*untyped) -> self
     %a{pure}
     def references: (*untyped) -> self
+    # With a block, `select` is Enumerable's and returns an Array. It
+    # stays `self`: on this open receiver a method the file does not
+    # declare is not reported, while on `Array[Elem]` any ActiveSupport
+    # method the bundled overlay leaves out would be.
     %a{pure}
     def select: (*untyped) -> self
     %a{pure}
@@ -145,9 +279,33 @@ module ActiveRecord
     def with: (*untyped) -> self
     def scoping: () { () -> untyped } -> untyped
 
-    # --- finders (return an element) ---
-    %a{rigor:v1:effect io.db.read}
-    def find: (*untyped) -> Elem
+    # --- finders (return an element, or an Array of them; `find`
+    # with a block, the element or nil) ---
+    # Two or more ids return an Array, unless dropping `nil`s and
+    # duplicates leaves one. One argument returns an Array when it is an
+    # Array of ids, but one record when it is a composite key's tuple
+    # (`[shop_id, id]`), and nothing here can tell those apart. An
+    # overload keyed on an `Array` argument would be selected for every
+    # untyped id too (`find(params[:id])`). Its return would be joined
+    # with this one's into `Dynamic[Array[Elem] | Elem]`, on which a
+    # following `update` or `save` no longer resolves on the model and
+    # loses its `io.db.write`. So a single argument stays `Elem`. A
+    # splat and a `**` hash each count as one argument, so `find(*ids)`
+    # is `Elem`, while `find(id, *ids)` and `find(*args, **opts)` are
+    # Arrays even when the splat or the hash turns out empty.
+    #
+    # With a block `find` is `Enumerable#find` (`return super if
+    # block_given?`), so the id overloads do not apply: no argument
+    # returns the element or `nil`, and one argument is the `ifnone`
+    # callable, whose result joins the union. That form is rare, so
+    # it stays `untyped` rather than typing the callable. The
+    # class-side `Model.find { … }` reaches this same method through
+    # `all`.
+    %a{rigor:v1:effect io.db.read}
+    def find: () { (Elem) -> boolish } -> Elem?
+            | (untyped ifnone) { (Elem) -> boolish } -> untyped
+            | (untyped, untyped, *untyped) -> Array[Elem]
+            | (?untyped id) -> Elem
     %a{rigor:v1:effect io.db.read}
     def find_by: (*untyped) -> Elem?
     %a{rigor:v1:effect io.db.read}
@@ -243,9 +401,9 @@ module ActiveRecord
     def entries: () -> Array[Elem]
     %a{rigor:v1:effect io.db.read}
     def load: (?untyped) -> self
-    %a{rigor:v1:effect io.db.read}
+    %a{rigor:v1:effect io.db.read, mutate.self}
     def reload: () -> self
-    %a{pure}
+    %a{rigor:v1:effect mutate.self}
     def reset: () -> self
     %a{pure}
     def loaded?: () -> bool
@@ -272,56 +430,73 @@ module ActiveRecord
     %a{pure}
     def table: () -> untyped
     %a{pure}
-    def arel: () -> untyped
+    def arel: (?untyped aliases) -> untyped
 
     # --- whole-relation persistence ---
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def update_all: (untyped) -> Integer
-    %a{rigor:v1:effect io.db.write}
-    def delete_all: () -> Integer
-    %a{rigor:v1:effect io.db.write}
+    # The optional argument is the association proxy's `dependent`
+    # (see the header). A plain Relation's and an AssociationRelation's
+    # `delete_all` take none.
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
+    def delete_all: (?untyped dependent) -> Integer
+    # On a plain `has_many`, the proxy's `destroy_all` returns `nil`
+    # when a `before_remove` callback throws `:abort`. A `:through` one,
+    # which includes `has_and_belongs_to_many`, still returns the
+    # records. `Array[Elem]?` would report `call.possible-nil-receiver`
+    # on every `destroyed.each` for a case only such a callback reaches.
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def destroy_all: () -> Array[Elem]
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write}
     def update: (*untyped) -> untyped
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write}
     def update!: (*untyped) -> untyped
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write}
     def delete_by: (*untyped) -> Integer
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write}
     def destroy_by: (*untyped) -> Array[Elem]
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def touch_all: (*untyped) -> Integer
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.write, mutate.self}
+    def insert: (untyped, **untyped) -> untyped
+    %a{rigor:v1:effect io.db.write, mutate.self}
     def insert_all: (untyped, **untyped) -> untyped
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.write, mutate.self}
+    def insert!: (untyped, **untyped) -> untyped
+    %a{rigor:v1:effect io.db.write, mutate.self}
     def insert_all!: (untyped, **untyped) -> untyped
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.write, mutate.self}
+    def upsert: (untyped, **untyped) -> untyped
+    %a{rigor:v1:effect io.db.write, mutate.self}
     def upsert_all: (untyped, **untyped) -> untyped
 
     # --- instantiating builders (return an element) ---
-    %a{pure}
+    # Given an Array of attribute hashes, `new`, `build`, `create` and
+    # `create!` return an Array of records. No overload says so, for
+    # the reason `find` gives: an untyped argument would select it too.
+    %a{rigor:v1:effect mutate.self}
     def new: (*untyped) ?{ (Elem) -> void } -> Elem
-    %a{pure}
+    %a{rigor:v1:effect mutate.self}
     def build: (*untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def create: (*untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def create!: (*untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def find_or_create_by: (untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def find_or_create_by!: (untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.read}
+    %a{rigor:v1:effect io.db.read, mutate.self}
     def find_or_initialize_by: (untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def create_or_find_by: (untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def create_or_find_by!: (untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def first_or_create: (?untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.write}
+    %a{rigor:v1:effect io.db.read, io.db.write, mutate.self}
     def first_or_create!: (?untyped) ?{ (Elem) -> void } -> Elem
-    %a{rigor:v1:effect io.db.read}
+    %a{rigor:v1:effect io.db.read, mutate.self}
     def first_or_initialize: (?untyped) ?{ (Elem) -> void } -> Elem
   end
 end

data/plugins/rigor-activestorage/lib/rigor/plugin/activestorage.rb

@@ -37,6 +37,7 @@ module Rigor
     class Activestorage < Rigor::Plugin::Base
       manifest(
         id: "activestorage",
+        target_gems: ["activestorage"],
         # Bumped 2026-09-02 (#621) — attachment owners are keyed by their de-rooted name and a reopened
         # class's attachments are UNIONed rather than clobbered, so a cached 0.1.0 index can be missing the
         # attachments the merge restores.
@@ -66,12 +67,15 @@ module Rigor
       def init(_services)
         @model_search_paths = Array(config.fetch("model_search_paths")).map(&:to_s)
         @attachment_index = nil
-        @load_errors = []
+        @load_errors = {}
       end
 
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = attachment_index
-        return load_error_diagnostics(path) if index.nil?
+        if index.nil?
+          disclose_load_errors
+          return []
+        end
         return [] if index.empty?
 
         Analyzer.new(path: path, attachment_index: index).analyze(root).diagnostics
@@ -125,24 +129,32 @@ module Rigor
         # covers model-file additions.
         @attachment_index = cache_for(:attachment_index, params: {}).call
       rescue Plugin::AccessDeniedError => e
-        @load_errors << "rigor-activestorage: #{e.message}"
+        @load_errors["1-read-refused"] ||= "rigor-activestorage: #{e.message}"
         nil
       rescue StandardError => e
-        @load_errors << "rigor-activestorage: discovery failed: #{e.class}: #{e.message}"
+        @load_errors["2-discovery-failed"] ||=
+          "rigor-activestorage: discovery failed: #{e.class}: #{e.message}"
         nil
       end
 
-      def load_error_diagnostics(path)
-        @load_errors.uniq.map do |message|
-          Rigor::Analysis::Diagnostic.new(
-            path: path,
-            line: 1,
-            column: 1,
-            message: message,
-            severity: :warning,
-            rule: "load-error"
-          )
+      # Issue #1056 — "the attachment index did not load" is a fact about the run's INPUTS, not about the
+      # file being analysed, so both outcomes are registered rather than returned: see
+      # {Plugin::Base#disclose_once} for the channel and the position. Returned from the per-file hook they
+      # carried no once-guard at all — the `.uniq` collapsed repeats within one instance's list, but the
+      # whole list was re-emitted on every analysed file.
+      #
+      # The `key`s carry an ordinal prefix because the engine emits a plugin's disclosures in KEY order
+      # (#1051), and a refused read must still precede a discovery failure the way `@load_errors` records
+      # them — `@load_errors` is now keyed by that same string, which also caps it: `#attachment_index`
+      # re-attempts the load per call site, and the old Array appended a fresh interpolated string every
+      # time (the unbounded-growth shape #569 measured at 4.2 M retained strings on Redmine). The key, not
+      # the message, is the identity: a second refusal naming a different path collapses into the first row
+      # rather than adding one — the notice is "the index did not load", said once.
+      def disclose_load_errors
+        @load_errors.each do |key, message|
+          disclose_once(key, message: message, severity: :warning, rule: "load-error")
         end
+        nil
       end
     end
 

data/plugins/rigor-activesupport-core-ext/lib/rigor/plugin/activesupport_core_ext/effects.rb

@@ -8,7 +8,7 @@ module Rigor
       # rigor-activesupport-core-ext's effect contract (ADR-103 WD10; design note § 11.2; issue #387).
       #
       # **Scope note.** This is the *impure* half of ActiveSupport only: the clock, the notification bus and
-      # `CurrentAttributes`. The `%a{pure}` sweep over `blank?` / `present?` / `deep_dup` and the rest of
+      # `CurrentAttributes`. The `%a{pure}` sweep over `blank?` / `present?` / `presence` and the rest of
       # the core_ext predicate surface — the single cheapest purity win in a Rails app, per WD10 — is issue
       # #388 and lands in this plugin's shipped RBS, not here (`try` was audited and skipped: it dispatches
       # to whatever method the caller names, so its purity is a fact about the call site, not about `try`).
@@ -115,11 +115,18 @@ module Rigor
         # which is what earns `Date` its row here — the label is a fact about the module, not about the
         # receiver, and the three only ever differed in which spellings the bundle had got round to
         # declaring.
+        #
+        # `String#in_time_zone` is the exception: it has no instant to convert. It parses through
+        # `TimeZone#parse(str, now = now())`, whose default argument reads the clock on every call, or through
+        # `to_time` when no zone is set — so it takes `CLOCK`, not `ZONE_READ`.
         def in_time_zone_rows
           [TIME, DATE, DATETIME].map do |receiver|
             row(receiver, :in_time_zone, ZONE_READ,
                 why: "the default argument reads `Time.zone` when the caller doesn't name one explicitly")
-          end
+          end + [
+            row("String", :in_time_zone, CLOCK,
+                why: "parses in `Time.zone` (the default argument) and fills the parts from the zone's `now`")
+          ]
         end
 
         def current_rows

data/plugins/rigor-activesupport-core-ext/lib/rigor/plugin/activesupport_core_ext.rb

@@ -42,9 +42,13 @@ module Rigor
     class ActivesupportCoreExt < Rigor::Plugin::Base
       manifest(
         id: "activesupport-core-ext",
+        target_gems: ["activesupport"],
+        # Bumped 2026-09-10 (#534 item 7) — `ActiveSupport::Concern` is declared, so `extend
+        # ActiveSupport::Concern` resolves instead of reading as an unresolved constant.
+        #
         # Bumped 2026-09-02 (#632) — `ActiveSupport::Duration`'s reader surface (`ago`/`to_i`/`iso8601`/…)
         # is now declared, open_receivers-protected; see the class comment above.
-        version: "0.4.0",
+        version: "0.5.0",
         description: "RBS bundle for the most-frequently-flagged ActiveSupport core_ext extensions, " \
                      "plus the `ActiveSupport::Duration` type of the numeric time multipliers and its " \
                      "reader surface.",
@@ -55,7 +59,10 @@ module Rigor
         # `call.undefined-method` fire against it. Distinct from the RECEIVER-side FP the multiplier
         # `dynamic_return` gate guards (`Time#day` vs `Duration#day`, in the class comment above) — this is
         # the class's OWN unenumerable member set.
-        open_receivers: ["ActiveSupport::Duration"],
+        # `ActiveSupport::Concern` (#534 item 7) is here for the same reason at a different scale: the
+        # declaration names `included` / `prepended` / `class_methods` so `extend ActiveSupport::Concern`
+        # resolves, and everything else the module really responds to must stay lenient.
+        open_receivers: ["ActiveSupport::Duration", "ActiveSupport::Concern"],
         # ADR-103 WD10 (#387) — the IMPURE half of ActiveSupport: the clock, the notification bus and
         # `CurrentAttributes`. The `%a{pure}` sweep over the predicate surface is issue #388 and lands in
         # `sig/`, not here. See {Effects}.