rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/unthreaded_rebinds.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_walker"
+require_relative "captured_locals"
+
+module Rigor
+  module Inference
+    # The names of a {CapturedLocals.writes} set that a block body rebinds somewhere `StatementEvaluator` does
+    # not carry into the body's exit scope.
+    #
+    # The per-element fold's issue #587 (b) fixpoint reads each pass's exit binding out of that evaluator, so a
+    # rebind the exit never sees leaves the fixpoint on a binding the program has already moved past, and every
+    # position of the fold re-reads it. Issue #617's unmoved-pin floor caught such a name only while nothing else
+    # moved its binding: `seen = nil; [1, 2].find { |e| seen ||= 0; (seen += 1) == 2 }` threads the `||=`, so the
+    # fixpoint left the seed, and every predicate read `0 + 1 == 2`. A name this scan returns takes the floor
+    # whatever the fixpoint converged to.
+    #
+    # The scan admits a write from these positions only, each one the evaluator threads, measured against it
+    # rather than read off it:
+    #
+    # - a statement, and the body of `(…)`, `begin` / `rescue` / `else` / `ensure`;
+    # - an assignment's value — every variable-write form, and an index `||=` / `&&=` / `op=`, but not its
+    #   receiver or index arguments;
+    # - an `if` / `unless` / `case` predicate and every branch, but not a `when` condition or an `in` guard;
+    # - both operands of `&&` / `||`;
+    # - a `while` / `until` predicate and body, a `for` index, collection and body;
+    # - a multi-assign value and its local and instance-variable targets, and the LOCAL a `rescue => e`
+    #   reference, a `for` index, a pattern capture or `=~`'s named captures binds — the evaluator binds no
+    #   class variable or global through any of them, and no instance variable outside a multi-assign;
+    # - a nested block or lambda body, for a local or an instance variable: the call's write-back fixpoint, which
+    #   joins the block's `next` and `break` paths, or the escaping-block floor covers both, and nothing covers
+    #   a class variable or global there.
+    #
+    # Every other position counts as unthreaded: a call's receiver and arguments, an array or hash literal, an
+    # interpolation, a `return` / `next` / `break` value, `rescue` modifier, `self.w =` (which rebinds `@w` with
+    # no write node at all), a `def` or class body. The list is a whitelist, so a position the evaluator gains
+    # later floors a name needlessly rather than letting a pin through. Issue #1223 is such a gain: the evaluator
+    # threads a call's receiver and arguments, the literals, the interpolations and a `rescue` modifier
+    # ({StatementEvaluator#eval_call}), and the scan does not admit them yet.
+    #
+    # A threaded rebind can still miss the exit binding when a jump leaves after it. The fold's pass and a
+    # nested block's write-back join every block-level `next` (and the write-back every `break`) into the exit
+    # ({StatementEvaluator#evaluate_invocation}), but a `while` / `until` / `for` loop's continuation joins its
+    # `next` and `break` paths only in part ({StatementEvaluator#loop_iteration}): a `for` body runs one pass,
+    # and a name outside the `while` / `until` rebind fixpoint (an instance variable) sees the first pass's
+    # `next` exits and no `break` — so the rebind such a branch made can still drop out — and `redo` / `retry`
+    # re-enter code with bindings no join sees. A rebind that textually precedes such a jump is therefore
+    # unthreaded too; the body runs forward-only, so a rebind after every jump cannot be on a jump's path, and
+    # a jump that is its construct's final statement leaves with the exit scope itself. A rebind in an `ensure`
+    # runs after any jump in its `begin`, so under any such jump it counts as preceding one.
+    module UnthreadedRebinds
+      VARIABLE_WRITE_NODES = (CapturedLocals::LOCAL_WRITE_NODES | CapturedLocals::NON_LOCAL_WRITE_NODES).freeze
+      private_constant :VARIABLE_WRITE_NODES
+
+      TARGET_NODES = Set[
+        Prism::LocalVariableTargetNode, Prism::InstanceVariableTargetNode,
+        Prism::ClassVariableTargetNode, Prism::GlobalVariableTargetNode
+      ].freeze
+      private_constant :TARGET_NODES
+
+      VALUE_ONLY = { value: :code }.freeze
+      private_constant :VALUE_ONLY
+
+      # Parent class => the child fields the evaluator threads, each with how it is entered: `:code` threads
+      # writes, `:binding` threads only the targets the construct binds ({#binding_target_threaded?}),
+      # `:ensure` is an `ensure` body, `:loop` a loop body, `:nested` a call's block and `:lambda` a lambda's
+      # body.
+      THREADED_FIELDS = {
+        Prism::StatementsNode => { body: :code },
+        Prism::ParenthesesNode => { body: :code },
+        Prism::BeginNode => { statements: :code, rescue_clause: :code, else_clause: :code, ensure_clause: :code },
+        Prism::RescueNode => { reference: :binding, statements: :code, subsequent: :code },
+        Prism::EnsureNode => { statements: :ensure },
+        Prism::ElseNode => { statements: :code },
+        Prism::IfNode => { predicate: :code, statements: :code, subsequent: :code },
+        Prism::UnlessNode => { predicate: :code, statements: :code, else_clause: :code },
+        Prism::CaseNode => { predicate: :code, conditions: :code, else_clause: :code },
+        Prism::WhenNode => { statements: :code },
+        Prism::CaseMatchNode => { predicate: :code, conditions: :code, else_clause: :code },
+        Prism::InNode => { pattern: :binding, statements: :code },
+        Prism::AndNode => { left: :code, right: :code },
+        Prism::OrNode => { left: :code, right: :code },
+        Prism::MatchPredicateNode => { value: :code, pattern: :binding },
+        Prism::MatchRequiredNode => { value: :code, pattern: :binding },
+        Prism::MatchWriteNode => { targets: :binding },
+        Prism::MultiWriteNode => { lefts: :binding, rest: :binding, rights: :binding, value: :code },
+        Prism::WhileNode => { predicate: :code, statements: :loop },
+        Prism::UntilNode => { predicate: :code, statements: :loop },
+        Prism::ForNode => { index: :binding, collection: :code, statements: :loop },
+        Prism::CallNode => { block: :nested },
+        Prism::BlockNode => { body: :code },
+        Prism::LambdaNode => { body: :lambda },
+        Prism::IndexOrWriteNode => VALUE_ONLY,
+        Prism::IndexAndWriteNode => VALUE_ONLY,
+        Prism::IndexOperatorWriteNode => VALUE_ONLY,
+        **(VARIABLE_WRITE_NODES - TARGET_NODES).to_h { |klass| [klass, VALUE_ONLY] }
+      }.transform_values(&:freeze).freeze
+      private_constant :THREADED_FIELDS
+
+      # The jumps whose path the exit binding misses, per construct. A block's `next` and `break` are joined
+      # ({StatementEvaluator#evaluate_invocation}, the write-back), and a `break` out of the fold's own call ends
+      # it, so no later iteration reads what it carried; `redo` and `retry` are joined nowhere. A loop joins
+      # its `next` and `break` paths only in part, so both still count.
+      BLOCK_JUMPS = Set[Prism::RedoNode, Prism::RetryNode].freeze
+      LOOP_JUMPS = (BLOCK_JUMPS | [Prism::NextNode, Prism::BreakNode]).freeze
+      private_constant :BLOCK_JUMPS, :LOOP_JUMPS
+
+      # The constructs that own the jumps inside them.
+      JUMP_BOUNDARY_NODES = Set[
+        Prism::BlockNode, Prism::LambdaNode, Prism::DefNode,
+        Prism::WhileNode, Prism::UntilNode, Prism::ForNode
+      ].freeze
+      private_constant :JUMP_BOUNDARY_NODES
+
+      NO_JUMP = -1
+      private_constant :NO_JUMP
+
+      EMPTY = Set.new.freeze
+      private_constant :EMPTY
+
+      # How a walk position reaches the exit scope: whether a local rebind there is threaded, whether an
+      # instance variable's is, whether a class variable's or global's is, the offset below which a rebind
+      # precedes a jump,
+      # whether the position binds targets only (`:multi_assign` under a multi-assign, `:capture` under any
+      # other binding construct, false otherwise), and the locals a nested block shadows.
+      Position = Data.define(:local, :ivar, :other, :horizon, :binding, :shadowed)
+      private_constant :Position
+
+      module_function
+
+      # @param names — the rebound names from {CapturedLocals.writes}, sigil and all.
+      # @return the subset of `names` the body rebinds somewhere the exit scope misses.
+      def names(block_node, names)
+        body = block_node.body
+        return EMPTY if body.nil? || names.empty?
+
+        wanted = names.to_set
+        found = Set.new
+        horizon = last_jump_offset(body, BLOCK_JUMPS)
+        start = Position.new(local: true, ivar: true, other: true, horizon: horizon, binding: false, shadowed: EMPTY)
+        visit(body, start, wanted, found)
+        found
+      end
+
+      def visit(node, position, wanted, found)
+        return unless node.is_a?(Prism::Node)
+        return if node.is_a?(Prism::DefinedNode)
+
+        check(node, position, wanted, found)
+        return node.rigor_each_child { |child| visit(child, position, wanted, found) } if position.binding
+
+        fields = THREADED_FIELDS[node.class]
+        return node.rigor_each_child { |child| visit_unthreaded(child, wanted, found) } if fields.nil?
+
+        threaded = threaded_children(node, fields)
+        node.rigor_each_child do |child|
+          mode = threaded[child]
+          if mode
+            visit(child, enter(node, child, mode, position), wanted, found)
+          else
+            visit_unthreaded(child, wanted, found)
+          end
+        end
+      end
+
+      def threaded_children(node, fields)
+        threaded = {}.compare_by_identity
+        fields.each do |field, mode|
+          value = node.public_send(field)
+          if value.is_a?(Array)
+            value.each { |child| threaded[child] = mode }
+          elsif value
+            threaded[value] = mode
+          end
+        end
+        threaded
+      end
+
+      # Every rebind under an unthreaded position misses the exit scope, whatever the position beneath it.
+      def visit_unthreaded(node, wanted, found)
+        Source::NodeWalker.each(node) do |descendant|
+          name = rebound_name(descendant)
+          found << name if name && wanted.include?(name)
+        end
+      end
+
+      def enter(parent, child, mode, position)
+        case mode
+        when :binding then position.with(binding: parent.is_a?(Prism::MultiWriteNode) ? :multi_assign : :capture)
+        when :ensure then position.with(horizon: position.horizon == NO_JUMP ? NO_JUMP : Float::INFINITY)
+        when :loop then extend_horizon(position, child, LOOP_JUMPS)
+        when :nested then nested_block(child, position)
+        when :lambda then nested_body(parent, child, position)
+        else position
+        end
+      end
+
+      def extend_horizon(position, body, kinds)
+        position.with(horizon: [position.horizon, last_jump_offset(body, kinds)].max)
+      end
+
+      # A call's block. A block-pass argument (`&blk`) carries no body the call's write-back reads.
+      def nested_block(child, position)
+        return position.with(local: false, ivar: false, other: false) unless child.is_a?(Prism::BlockNode)
+
+        nested_body(child, child.body, position)
+      end
+
+      # A block or lambda body: its parameters and block-locals shadow, its own jumps join the horizon, and a
+      # class variable's or global's rebind is no longer carried out.
+      def nested_body(owner, body, position)
+        extend_horizon(position, body, BLOCK_JUMPS).with(
+          other: false, shadowed: position.shadowed | CapturedLocals.introduced_locals(owner)
+        )
+      end
+
+      def check(node, position, wanted, found)
+        name = rebound_name(node)
+        return if name.nil? || !wanted.include?(name)
+        return if position.shadowed.include?(name)
+
+        found << name unless threaded_rebind?(node, name, position)
+      end
+
+      def threaded_rebind?(node, name, position)
+        return false unless VARIABLE_WRITE_NODES.include?(node.class)
+        return false unless TARGET_NODES.include?(node.class) == (position.binding ? true : false)
+
+        kind = CapturedLocals.variable_kind(name)
+        return false if position.binding && !binding_target_threaded?(kind, position.binding)
+        return false unless kind_threaded?(kind, position)
+
+        node.location.start_offset >= position.horizon
+      end
+
+      def kind_threaded?(kind, position)
+        case kind
+        when :local then position.local
+        when :ivar then position.ivar
+        else position.other
+        end
+      end
+
+      # A binding construct's target reaches the exit scope only for the kinds the evaluator binds there: a
+      # multi-assign binds locals and instance variables, and a `rescue =>` reference, a `for` index, a pattern
+      # capture or a named capture binds locals only. `a, $g = 1, :z` leaves `$g` where it was.
+      def binding_target_threaded?(kind, binding)
+        kind == :local || (kind == :ivar && binding == :multi_assign)
+      end
+
+      def rebound_name(node)
+        return node.name if VARIABLE_WRITE_NODES.include?(node.class)
+
+        CapturedLocals.setter_ivar_name(node)
+      end
+
+      # The start offset of the last `kinds` jump that belongs to the construct whose body is `body`, or
+      # {NO_JUMP}. A jump that is the body's final statement is skipped: it leaves with the exit scope itself.
+      def last_jump_offset(body, kinds)
+        return NO_JUMP if body.nil?
+
+        final = body.body.last if body.is_a?(Prism::StatementsNode)
+        offset = NO_JUMP
+        each_owned_jump(body, kinds) do |jump|
+          offset = [offset, jump.location.start_offset].max unless jump.equal?(final)
+        end
+        offset
+      end
+
+      def each_owned_jump(node, kinds, &)
+        yield node if kinds.include?(node.class)
+        return if node.is_a?(Prism::DefinedNode)
+
+        node.rigor_each_child do |child|
+          each_owned_jump(child, kinds, &) unless JUMP_BOUNDARY_NODES.include?(child.class)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/version_guard.rb

@@ -48,6 +48,8 @@ module Rigor
     #   with the running Ruby**, where "the analyzer's Ruby is the target's Ruby" already covers them.
     #   A third-party gem's `VERSION` is not read: its version is the project's `Gemfile.lock`'s to say,
     #   and the lockfile is not visible from the inference layer.
+    # * The ROOTED spelling of any of the above — `::RUBY_VERSION`, `::RUBY_ENGINE`, `::Psych::VERSION` —
+    #   names the same constant as its bare twin and folds identically; see {.read_constant}.
     # * `RUBY_PLATFORM` — **never** folded. Every comparison against it is by construction
     #   platform-dependent, and the machine running `rigor` need not be the machine running the program.
     # * `<=>` — never folded (it yields -1/0/1, not a branch verdict), and neither are `defined?(Ractor)`
@@ -68,7 +70,7 @@ module Rigor
 
       # Predefined constants read from the analyzer's runtime, mapped to the operand kind they produce.
       # `:string` operands accept every comparison; `:engine` operands accept equality only.
-      PREDEFINED = { RUBY_VERSION: :string, RUBY_ENGINE: :engine }.freeze
+      PREDEFINED = { "RUBY_VERSION" => :string, "RUBY_ENGINE" => :engine }.freeze
       private_constant :PREDEFINED
 
       # Operand kinds that carry a plain Ruby String, i.e. the ones `Gem::Version.new` may wrap and the
@@ -88,8 +90,8 @@ module Rigor
       GEM_VERSION_PATH = "Gem::Version"
       private_constant :GEM_VERSION_PATH
 
-      # @param node [Prism::Node, nil] an `if` / `unless` predicate
-      # @return [Symbol, nil] `:truthy` / `:falsey` when the guard is decidable on the analyzer's Ruby,
+      # @param node — an `if` / `unless` predicate
+      # @return `:truthy` / `:falsey` when the guard is decidable on the analyzer's Ruby,
       #   otherwise nil (both arms stay live)
       def verdict(node)
         return nil unless node.is_a?(Prism::CallNode)
@@ -109,35 +111,40 @@ module Rigor
       end
 
       # Reads one side of the comparison into `[kind, value]`, or nil when it is not readable.
-      #
-      # @return [Array(Symbol, Object), nil]
       def read_operand(node)
         case node
         when Prism::StringNode then [:literal_string, node.unescaped]
-        when Prism::ConstantReadNode then read_predefined(node)
-        when Prism::ConstantPathNode then read_version_constant(node)
+        when Prism::ConstantReadNode, Prism::ConstantPathNode then read_constant(node)
         when Prism::CallNode then read_gem_version(node)
         end
       end
       private_class_method :read_operand
 
-      def read_predefined(node)
-        kind = PREDEFINED[node.name]
-        return nil unless kind
-
-        value = runtime_value(node.name.to_s)
-        value && [kind, value]
-      end
-      private_class_method :read_predefined
-
-      def read_version_constant(node)
+      # Dispatches on the RESOLVED name rather than on the node class. `::RUBY_VERSION` names the very
+      # constant `RUBY_VERSION` names — the leading `::` only makes the top-level lookup explicit — but
+      # Prism spells it as a `ConstantPathNode` with a nil parent, so a node-class dispatch sent it down
+      # the `X::VERSION` path and declined it for not being a curated qualified name. The same program
+      # then had two diagnostic sets for two spellings of one guard
+      # ([#877](https://github.com/rigortype/rigor/issues/877)).
+      #
+      # The foldable set is unchanged and stays closed: an unqualified name folds only when it is one of
+      # {PREDEFINED}, a qualified one only when it is in {VERSION_CONSTANTS}.
+      def read_constant(node)
         path = Source::ConstantPath.qualified_name_or_nil(node)
-        return nil unless path && VERSION_CONSTANTS.include?(path)
+        return nil unless path
+
+        kind =
+          if path.include?("::")
+            :string if VERSION_CONSTANTS.include?(path)
+          else
+            PREDEFINED[path]
+          end
+        return nil unless kind
 
         value = runtime_value(path)
-        value && [:string, value]
+        value && [kind, value]
       end
-      private_class_method :read_version_constant
+      private_class_method :read_constant
 
       # `Gem::Version.new(<readable>)`. The inner operand must be a plain version String — an engine name
       # is not a version, and `Gem::Version.new` raises on anything `Gem::Version.correct?` rejects, so a
@@ -165,7 +172,7 @@ module Rigor
       # `const_get` would execute the target file inside the analyzer. `Module#autoload?` is what
       # separates the two ([#680](https://github.com/rigortype/rigor/issues/680)).
       #
-      # @return [String, nil] the constant's value when it is a non-empty String
+      # @return the constant's value when it is a non-empty String
       def runtime_value(path)
         mod = ::Object
         path.split("::").each do |part|

data/lib/rigor/inference/void_origin.rb

@@ -9,11 +9,11 @@ module Rigor
     # consistency, normalization, or erasure.
     #
     # @!attribute class_name
-    #   @return [String] the receiver class whose method declared `-> void`.
+    #   @return the receiver class whose method declared `-> void`.
     # @!attribute method_name
-    #   @return [Symbol] the method whose return was recovered.
+    #   @return the method whose return was recovered.
     # @!attribute kind
-    #   @return [Symbol] `:instance` or `:singleton`.
+    #   @return `:instance` or `:singleton`.
     VoidOrigin = Data.define(:class_name, :method_name, :kind) do
       # A human-facing `Class#method` / `Class.method` label for the diagnostic message.
       def label

data/lib/rigor/inference/void_tail_summary.rb

@@ -75,10 +75,8 @@ module Rigor
       # consult; the memo persists across consults for the run. The memo is probed before the visited
       # set is allocated so the common post-warmup hit path allocates nothing.
       #
-      # @param def_node [Prism::DefNode]
-      # @param owner [String] the qualified receiver class the `def` belongs to.
-      # @param kind [Symbol] `:instance` or `:singleton`.
-      # @return [Inference::VoidOrigin, nil]
+      # @param owner — the qualified receiver class the `def` belongs to.
+      # @param kind — `:instance` or `:singleton`.
       def origin_for(def_node, owner, kind)
         return nil if def_node.nil?
 

data/lib/rigor/language_server/buffer_table.rb

@@ -51,7 +51,7 @@ module Rigor
       # computed from the stale text would be wrong. Consumers check {#desynchronized?} and decline to answer
       # rather than answering wrongly; the mark clears on the next `didOpen` or full-text change.
       #
-      # @return [Boolean] true when the changes were applied.
+      # @return true when the changes were applied.
       def apply_changes(uri:, changes:, version:)
         text = IncrementalSync.apply_all(@entries[uri]&.bytes, changes)
         @desynchronized.delete(uri)
@@ -63,13 +63,13 @@ module Rigor
         false
       end
 
-      # @return [Boolean] true when the last `didChange` for `uri` could not be applied, so the held text no
+      # @return true when the last `didChange` for `uri` could not be applied, so the held text no
       #   longer matches the editor's.
       def desynchronized?(uri)
         @desynchronized.key?(uri)
       end
 
-      # @return [String, nil] why `uri` is desynchronised, for the log line; nil when it is in sync.
+      # @return why `uri` is desynchronised, for the log line; nil when it is in sync.
       def desynchronization_reason(uri)
         @desynchronized[uri]
       end
@@ -91,7 +91,7 @@ module Rigor
         @dirty.delete(uri)
       end
 
-      # @return [Boolean] true when `uri` has unsaved changes. A buffer that is dirty may only be published
+      # @return true when `uri` has unsaved changes. A buffer that is dirty may only be published
       #   from an analysis that bound ITS bytes — see the publish-set invariant in
       #   `docs/design/20260517-language-server.md`.
       def dirty?(uri)

data/lib/rigor/language_server/completion_provider.rb

@@ -42,7 +42,7 @@ module Rigor
         @project_context = project_context
       end
 
-      # @return [Array<Hash>, nil] LSP `CompletionItem[]` or nil
+      # @return LSP `CompletionItem[]` or nil
       #   when the cursor isn't at a position the provider can
       #   enumerate completions for. Returning nil maps to
       #   `result: null` per the LSP spec — clients treat it as

data/lib/rigor/language_server/debouncer.rb

@@ -68,7 +68,6 @@ module Rigor
         end
       end
 
-      # @return [Integer] number of currently-pending tasks.
       def pending_size
         @mutex.synchronize { @tasks.size }
       end

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -30,13 +30,13 @@ module Rigor
         hint: 4
       }.freeze
 
-      # @param debouncer [Rigor::LanguageServer::Debouncer, nil]
+      # @param debouncer —
       #   when present, `publish_for` schedules its work through
       #   the debouncer (cancels prior pending task for the same
       #   URI, fires after `debounce_seconds` quiet-time). Nil
       #   keeps the slice 4-7 synchronous behaviour — primarily
       #   useful for specs.
-      # @param debounce_seconds [Numeric] quiet-time before the
+      # @param debounce_seconds — quiet-time before the
       #   debounced publish fires. 0 with a debouncer means
       #   "schedule on next-tick" (still async); without a
       #   debouncer the value is unused.
@@ -212,7 +212,7 @@ module Rigor
         notify(uri, diagnostics)
       end
 
-      # @return [Hash, nil] `{ uri:, path:, bytes: }` when `uri` is eligible for the batch, or nil to
+      # @return `{ uri:, path:, bytes: }` when `uri` is eligible for the batch, or nil to
       #   exclude it. Mirrors `#run_and_notify`'s own guards: a buffer closed during the debounce window is
       #   dropped silently (its didClose empty publish already cleared the markers); a desynchronised buffer
       #   publishes an EMPTY set immediately (same as the single-buffer path) rather than joining the batch.
@@ -268,8 +268,9 @@ module Rigor
 
       # Runs `Analysis::Runner` with a `BufferBinding` so the buffer bytes (instead of the on-disk file) drive
       # the parse. The `Rigor::Analysis::ProjectScan` cached on the ProjectContext is passed through
-      # `prebuilt:` so plugin `#prepare`, the dependency-source walker, and the synthetic-method /
-      # project-patched scanners do not re-run per publish. The snapshot rebuilds only when
+      # `prebuilt:` so plugin `#prepare`, the dependency-source walker, the synthetic-method /
+      # project-patched scanners and (#1038) the template-unit transforms do not re-run per publish — the
+      # last of those is an Erubi compile of every view for an ERB project. The snapshot rebuilds only when
       # `ProjectContext#invalidate!` fires (watched-file or configuration change). Returns the LSP-shaped
       # Diagnostic Array, ready to serialize into the notification's `params.diagnostics` field.
       def run_analysis(path:, bytes:)
@@ -320,7 +321,7 @@ module Rigor
         end
       end
 
-      # @return [Hash, nil] the LSP `Diagnostic` Hash, or nil to
+      # @return the LSP `Diagnostic` Hash, or nil to
       #   skip diagnostics outside the buffer's own path (e.g.
       #   `.rigor.yml`-anchored info diagnostics get filtered —
       #   they belong to the project, not the buffer).

data/lib/rigor/language_server/document_symbol_provider.rb

@@ -30,7 +30,7 @@ module Rigor
         @project_context = project_context
       end
 
-      # @return [Array<Hash>, nil] LSP `DocumentSymbol[]` for the
+      # @return LSP `DocumentSymbol[]` for the
       #   buffer at `uri`. Returns nil when the URI isn't open or
       #   doesn't parse cleanly enough to surface symbols — LSP
       #   clients fall back to no-outline in that case.

data/lib/rigor/language_server/folding_range_provider.rb

@@ -23,7 +23,7 @@ module Rigor
         @project_context = project_context
       end
 
-      # @return [Array<Hash>, nil] LSP `FoldingRange[]` for the
+      # @return LSP `FoldingRange[]` for the
       #   buffer, or nil when the URI isn't open / parseable.
       def provide(uri)
         path, entry = buffer_for(uri)

data/lib/rigor/language_server/hover_provider.rb

@@ -29,7 +29,7 @@ module Rigor
         @renderer = renderer
       end
 
-      # @return [Hash, nil] an LSP `Hover` payload or nil when no
+      # @return an LSP `Hover` payload or nil when no
       #   expression sits at the queried position. Returning nil
       #   maps to `result: null` per the LSP spec — clients
       #   suppress the hover popup in that case.

data/lib/rigor/language_server/hover_renderer.rb

@@ -13,7 +13,7 @@ module Rigor
     # (method call, constant, local, ivar, literal) gets the most relevant type-aware presentation per
     # `docs/design/20260517-lsp-hover-completion.md`.
     class HoverRenderer
-      # @param node_scope_lookup [#[]] node-to-scope table built by `ScopeIndexer.index`. The renderer indexes
+      # @param node_scope_lookup — node-to-scope table built by `ScopeIndexer.index`. The renderer indexes
       #   into it to retrieve the receiver's narrow scope when specialising on `CallNode`. The lookup never
       #   returns nil (the indexer's Hash carries `default_scope` as its default value), so the renderer trusts
       #   the lookup result.
@@ -83,9 +83,9 @@ module Rigor
         )
       end
 
-      # @return [[RBS::Definition::Method, String, Symbol], nil] the resolved method definition, the receiver
-      #   class name, and the dispatch kind (`:instance` or `:singleton`); nil when the receiver shape isn't
-      #   yet supported or the method doesn't resolve through the RBS env.
+      # @return `[definition, receiver_class_name, kind]` — the resolved method definition (nil when the
+      #   method doesn't resolve through the RBS env), the receiver class name, and the dispatch kind
+      #   (`:instance` or `:singleton`); `[nil, nil, nil]` when the receiver shape isn't yet supported.
       def lookup_method(receiver_type, method_name, scope)
         case receiver_type
         when Type::Singleton

data/lib/rigor/language_server/incremental_sync.rb

@@ -46,10 +46,10 @@ module Rigor
       # Applies every change in order, each against the result of the previous — the LSP contract for a
       # multi-change `didChange` notification.
       #
-      # @param text [String, nil] the held buffer text; nil when no buffer is open for the URI.
-      # @param changes [Array<Hash>] the `contentChanges` array.
-      # @return [String] the new buffer text.
-      # @raise [UnappliableChange] if any change cannot be applied.
+      # @param text — the held buffer text; nil when no buffer is open for the URI.
+      # @param changes — the `contentChanges` array.
+      # @return the new buffer text.
+      # @raise UnappliableChange — if any change cannot be applied.
       def apply_all(text, changes)
         raise UnappliableChange, "contentChanges must be an Array, got #{changes.class}" unless changes.is_a?(Array)
 
@@ -64,7 +64,7 @@ module Rigor
       # companion to `range` and is accepted-but-ignored: it is redundant with `range`, historically ambiguous
       # about its units, and `range` is the authoritative field.
       #
-      # @raise [UnappliableChange]
+      # @raise UnappliableChange
       def apply(text, change)
         raise UnappliableChange, "contentChanges entry must be a Hash, got #{change.class}" unless change.is_a?(Hash)
 
@@ -95,7 +95,7 @@ module Rigor
         raise UnappliableChange, "held text is not valid UTF-8: #{e.message}"
       end
 
-      # @return [Array<Array(Integer, Integer)>] one `[content_start, content_end]` pair per line, in Ruby
+      # @return one `[content_start, content_end]` pair per line, in Ruby
       #   character indices. `content_end` excludes the line terminator, so it doubles as the clamp target for
       #   an over-long `character`. A trailing terminator yields a final empty span — the virtual last line an
       #   editor puts the cursor on, and the anchor for an end-of-document insert.

data/lib/rigor/language_server/project_context.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../environment"
+require_relative "../project_environment"
 require_relative "../cache/store"
 require_relative "../analysis/runner"
 require_relative "../analysis/incremental_session"
@@ -11,12 +12,14 @@ module Rigor
     # Per-session cache of the project-wide analyzer state the LSP reads on every request — chiefly the
     # `Environment` (with its ~100-300ms RBS env build), a read-only `Cache::Store` that lets the runner hit
     # the on-disk RBS cache without writing back, and (since the pre-pass cache slice) a frozen
-    # {Rigor::Analysis::ProjectScan} snapshot covering the plugin registry, dependency-source index, and
-    # pre-pass scanner outputs.
+    # {Rigor::Analysis::ProjectScan} snapshot covering the plugin registry, dependency-source index,
+    # pre-pass scanner outputs and (since #1038) the compiled template-unit index.
     #
     # The pre-pass scan lets `DiagnosticPublisher#run_analysis` build a `Runner` with `prebuilt:` so per-buffer
     # publishes skip plugin `#prepare`, the synthetic-method scanner, the project-patched scanner, and the
-    # dependency-source walker. For projects with substrate plugins / opt-in dependency source / sizeable
+    # dependency-source walker — and, since #1038, the template-unit transform: a publish recompiles only a
+    # template that moved on disk since the scan was built (plus the buffer's own, always), rather than every
+    # view in the project. For projects with substrate plugins / opt-in dependency source / sizeable
     # `pre_eval:` configuration this cuts publish wall time substantially — for the trivial case the savings
     # are small (the per-publish path is already ≈2ms once Environment is warm).
     #
@@ -74,11 +77,7 @@ module Rigor
           dependency_source_index: project_scan.dependency_source_index,
           synthetic_method_index: project_scan.synthetic_method_index,
           project_patched_methods: project_scan.project_patched_methods,
-          bundler_bundle_path: @configuration.bundler_bundle_path,
-          bundler_auto_detect: @configuration.bundler_auto_detect,
-          bundler_lockfile: @configuration.bundler_lockfile,
-          rbs_collection_lockfile: @configuration.rbs_collection_lockfile,
-          rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect
+          **ProjectEnvironment.dependency_discovery_options(@configuration)
         )
       end
 

data/lib/rigor/language_server/publish_batcher.rb

@@ -15,10 +15,10 @@ module Rigor
     # dropped. The same claim/consume shape `DiagnosticPublisher#run_project_round` already uses for the
     # whole-project save round (#246), generalised to an arbitrary key type and an arbitrary batch action.
     class PublishBatcher
-      # @param on_batch [#call] `(keys) -> void`, called with the deduplicated Array of keys pending at the
+      # @param on_batch — `(keys) -> void`, called with the deduplicated Array of keys pending at the
       #   start of one round. May be called more than once in a row when keys keep arriving while a round
       #   runs.
-      # @param on_error [#call, nil] `(exception) -> void`, called when `on_batch` raises. A round must
+      # @param on_error — `(exception) -> void`, called when `on_batch` raises. A round must
       #   never wedge the coalescing lock for every future `#enqueue` call — ownership is always released
       #   before this fires. Whatever was mid-flight when the round raised is lost; anything enqueued by a
       #   concurrent `#enqueue` call after this round's drain but before the rescue stays pending and rides