rigortype 0.3.8 → 0.4.0

data/plugins/rigor-actionpack/lib/rigor/plugin/actionpack/erb_compiler.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "erb"
+
+require "rigor/plugin"
+require "rigor/plugin/isolation"
+
+module Rigor
+  module Plugin
+    class Actionpack < Rigor::Plugin::Base
+      # #393 — ERB → Ruby, with the line map the template-unit seam (#392) reports through.
+      #
+      # ## Which compiler
+      #
+      # [ADR-90](../../../../../../docs/adr/90-target-library-resolution-from-project-bundle.md): Erubi is
+      # **never bundled** — it is not a Rigor dependency and nothing here adds it to a Gemfile — but it is
+      # what Rails itself compiles with, so it is used when it resolves in the ANALYSED project's bundle,
+      # through the same `Isolation.require_with_target_bundle` path `Inflector` takes. Stdlib `ERB` is the
+      # fallback, and it is always there. Whichever ran is reported as the unit's `transform_id`
+      # (`erubi-1.13.1` / `erb-6.0.1.1`), which rides the unit digest — so a project that installs Erubi
+      # between two runs re-analyses rather than replaying the stdlib answer.
+      #
+      # ## The line map is measured, never assumed
+      #
+      # Both compilers are line-preserving: a tag's text is rewritten in place and the newlines between
+      # tags are emitted verbatim, which is why a Rails backtrace can name `show.html.erb:12`. What differs
+      # is the **prologue** — stdlib ERB emits a `#coding:` magic comment above the body, Erubi emits its
+      # buffer initialiser — and neither documents its height as API.
+      #
+      # So the height is measured rather than hardcoded: {.line_offset} compiles a probe template of marked
+      # lines once per compiler and reads back which compiled line the first marker landed on, checking at
+      # the same time that the following markers step by exactly one. A compiler that fails that check is
+      # refused (the caller declines the file) rather than trusted, because the failure mode of a wrong
+      # offset is every finding in every template reported at the wrong line — silent, and worse than no
+      # unit at all.
+      module ErbCompiler
+        # A compiler whose probe did not step line-for-line. Caught by {Actionpack#template_units_for_file},
+        # which declines the file.
+        class Unmappable < StandardError; end
+
+        # Three marked lines, each a STATEMENT tag. A tag's Ruby is emitted verbatim, so the marker is
+        # findable in the compiled source and each one is forced onto its own compiled line.
+        #
+        # Plain text would not do: consecutive text lines are one chunk and are emitted as ONE append
+        # carrying the newlines escaped inside the literal — the compiler then pads the missing lines out
+        # BELOW it, so a text probe reads as a collapse when the line numbering is in fact intact. That
+        # padding is exactly the property being measured, and a tag probe measures it without tripping
+        # over how the padding is spelled.
+        PROBE = (1..3).map { |n| "<% RIGOR_ERB_PROBE_#{n} %>\n" }.join.freeze
+        private_constant :PROBE
+
+        # An output tag whose Ruby OPENS A BLOCK: `<%= form_with(model: @user) do |f| %>`, the single most
+        # common shape in a real Rails view. Neither compiler handles it — both emit
+        # `_buf << (form_with(…) do |f|).to_s`, which is a syntax error, so every template using a form
+        # helper produced two parse diagnostics and no unit at all (431 of them on redmine, measured).
+        #
+        # Rails does not hit this because its own ERB handler carries exactly this rule
+        # (`ActionView::Template::Handlers::ERB::BLOCK_EXPR`) and emits `@output_buffer.append= expr`
+        # unwrapped for a matching tag. The same rule is applied here one step earlier, as a rewrite of
+        # the TEMPLATE rather than of a compiler's output: `<%=` becomes `<%` for such a tag, which is a
+        # same-width, same-line edit both compilers then handle, and the discarded value is the buffer
+        # append the design note says is not an origin anyway.
+        BLOCK_EXPR = /\s*((\s+|\))do|\{)(\s*\|[^|]*\|)?\s*\z/
+        private_constant :BLOCK_EXPR
+
+        # The Erubi/Rails trim markers, which stdlib ERB only understands under a `trim_mode:` that also
+        # changes how it emits newlines. They are blanked instead — `<%-` → `<% `, `-%>` → ` %>` — which
+        # is the same-width, same-line rewrite {BLOCK_EXPR} uses and keeps the line map out of the
+        # compiler's trim rules entirely. Left in place under `trim_mode: nil` they parse as Ruby's unary
+        # minus and cost the template its unit (87 of redmine's 506, measured after the block-expression
+        # fix and before this one).
+        TRIM_OPEN = /<%-/
+        private_constant :TRIM_OPEN
+
+        TRIM_CLOSE = /-%>/
+        private_constant :TRIM_CLOSE
+
+        # #1047 — a LAYOUT's `yield`. `<%= yield %>`, `<%= yield :sidebar %>` and `<% if content_for?(:x) %>`
+        # are what a layout is made of, and the first two are legal ERB and illegal Ruby anywhere outside a
+        # method body — so every layout's compiled source failed to parse and the file was declined (four of
+        # redmine's 506 templates, two of mastodon's 46; `docs/notes/20260917-erb-template-units.md` § 3).
+        #
+        # The seam deliberately does NOT wrap a unit's body in a synthesised method
+        # (`docs/internal-spec/macro-substrate.md` § Positions: wrapping would shift every line and compose
+        # a second line map onto the plugin's), so the fix is a rewrite of the TEMPLATE, in the same pre-pass
+        # {BLOCK_EXPR} and {TRIM_OPEN} live in: the `yield` KEYWORD inside an ERB tag becomes a call to
+        # {YIELD_METHOD}, an ordinary implicit-self method on the synthesised view context, declared in
+        # `sig/action_view.rbs` as returning `String`.
+        #
+        # Unlike the other two rewrites this one is NOT width-preserving, and it does not have to be: a unit
+        # whose `line_map` is non-empty reports at column 1 by construction
+        # ({Analysis::TemplateUnits#remap} — "the template's lines and the compiled Ruby's columns do not
+        # correspond"), so only the LINE count is load-bearing, and the replacement contains no newline.
+        #
+        # What the rewrite deliberately does not do is give the call a TYPE beyond `String`. Rails' `yield`
+        # returns whatever the inner template's buffer holds, and `yield :sidebar` returns the `content_for`
+        # buffer — an empty `SafeBuffer` when nothing was provided, never nil. A lenient `String` is the
+        # widest honest reading, and inventing anything narrower would be the `Parameters#[]` trap one
+        # layer up.
+        YIELD_METHOD = "__rigor_yield"
+
+        # The `yield` keyword, and only the keyword: not `foo.yield`, not `:yield`, not `@yield`, not
+        # `yielding`. A `yield` inside a STRING literal in a tag (`<%= t("yield") %>`) is rewritten too —
+        # the pre-pass is a Regexp over the tag, not a Ruby lexer — which changes a literal's bytes in a
+        # body that is never executed and that no rule reads the contents of. Recorded rather than guarded,
+        # because a lexer here would be a second Ruby parser to keep honest.
+        YIELD_KEYWORD = /(?<![A-Za-z0-9_.:@$])yield(?![A-Za-z0-9_?!])/
+        private_constant :YIELD_KEYWORD
+
+        # Any ERB tag, non-greedy and multi-line — the region {YIELD_KEYWORD} is applied inside, so a
+        # `yield` in the template's HTML text is left exactly as it was written. A `<%%` opener is ERB's
+        # escape for a LITERAL `<%` in the output, so what follows it is text too and is skipped.
+        ANY_TAG = /<%.*?%>/m
+        private_constant :ANY_TAG
+
+        # `<%= … %>` and `<%== … %>`, non-greedy and multi-line. No capture group: the block below reads
+        # the tag it was handed rather than `Regexp.last_match`, whose group is `String?` however sure
+        # the pattern makes it — and a rewrite that depends on global match state is the harder one to
+        # read anyway.
+        OUTPUT_TAG = /<%={1,2}(?!=).*?%>/m
+        private_constant :OUTPUT_TAG
+
+        # The `<%=` / `<%==` opener of a matched tag, which is all that gets rewritten.
+        OUTPUT_OPENER = /\A<%=+/
+        private_constant :OUTPUT_OPENER
+
+        module_function
+
+        # `[ruby_source, line_map, transform_id]` for one template's bytes. `text` must already be valid
+        # UTF-8 — {.scrub} is the caller's, because more than one thing reads the template and every one
+        # of them has to read the SAME bytes.
+        #
+        # `line_map` is `{ compiled line => template line }` for every template line, explicitly — NOT the
+        # empty "identity" map, even when the offset is zero. An empty map tells the engine the transform
+        # was byte-preserving and lets the compiled Ruby's COLUMNS through, and an ERB column names
+        # nothing in the template (`macro-substrate.md` § Positions).
+        def compile(text)
+          offset = line_offset
+          raise Unmappable, "#{transform_id} does not emit template lines one per compiled line" if offset.nil?
+
+          compiled = compile_source(normalize(text))
+          map = (1..template_line_count(text)).to_h { |line| [line + offset, line] }
+          [compiled, map, transform_id]
+        end
+
+        # A template's bytes as valid UTF-8. A `.erb` file is whatever the project committed, and an
+        # invalid byte is not a reason to refuse it: `ERB`, `Regexp#match?` and Prism all raise on one,
+        # so every reader has to be handed the same scrubbed String or they disagree about the file.
+        def scrub(source)
+          text = source.to_s.dup.force_encoding(Encoding::UTF_8)
+          return text if text.valid_encoding?
+
+          text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+
+        # The compiled Ruby for one template, through whichever compiler resolved.
+        def compile_source(text)
+          if erubi?
+            ::Erubi::Engine.new(text).src
+          else
+            ::ERB.new(text, trim_mode: nil).src
+          end
+        end
+
+        # Rewrites every block-opening output tag into a statement tag; see {BLOCK_EXPR}. Line- and
+        # width-preserving by construction: only the tag's `=` characters are replaced, by spaces.
+        def normalize(text)
+          normalize_block_expressions(normalize_yields(text.gsub(TRIM_OPEN, "<% ").gsub(TRIM_CLOSE, " %>")))
+        end
+
+        # Rewrites the `yield` keyword inside every ERB tag into a call on the view context; see
+        # {YIELD_METHOD}. Runs BEFORE {#normalize_block_expressions} so that pass reads the tag bodies it
+        # will actually hand to the compiler.
+        def normalize_yields(text)
+          return text unless text.match?(YIELD_KEYWORD)
+
+          text.gsub(ANY_TAG) { |tag| tag.start_with?("<%%") ? tag : tag.gsub(YIELD_KEYWORD, YIELD_METHOD) }
+        end
+
+        def normalize_block_expressions(text)
+          text.gsub(OUTPUT_TAG) do |tag|
+            opener = tag[OUTPUT_OPENER]
+            next tag if opener.nil?
+
+            body = tag[opener.length...-2].to_s
+            next tag unless body.match?(BLOCK_EXPR)
+
+            "<%#{' ' * (opener.length - 2)}#{body}%>"
+          end
+        end
+
+        # A template's last line may lack its newline; `String#lines` already counts it, and an EMPTY
+        # template has no lines at all and needs no rows.
+        def template_line_count(text)
+          text.lines.length
+        end
+
+        # How many compiled lines sit above the template's first line. Measured once per process per
+        # compiler — the answer cannot change under a loaded compiler, and the probe compile is cheap
+        # enough that memoising it is about tidiness rather than cost.
+        def line_offset
+          return @line_offset if defined?(@line_offset) && @line_offset
+
+          @line_offset = probe_offset
+        end
+
+        # `nil` when the loaded compiler does not step line-for-line.
+        def probe_offset
+          lines = compile_source(PROBE).lines
+          first = lines.index { |line| line.include?("RIGOR_ERB_PROBE_1") }
+          return nil if first.nil?
+
+          (2..3).each do |marker|
+            return nil unless lines[first + marker - 1]&.include?("RIGOR_ERB_PROBE_#{marker}")
+          end
+          first
+        end
+
+        # `erubi-1.13.1` / `erb-6.0.1.1` — the compiler's identity, which rides the unit digest.
+        def transform_id
+          @transform_id ||= if erubi?
+                              "erubi-#{::Erubi::VERSION}"
+                            else
+                              "erb-#{::ERB.const_defined?(:VERSION) ? ::ERB::VERSION : 'stdlib'}"
+                            end
+        end
+
+        # True once Erubi has been loaded out of the analysed project's bundle AND its line numbering has
+        # been measured. Resolved ONCE per process: a failed resolution is as memoised as a successful
+        # one, so a project without Erubi does not pay a `$LOAD_PATH` walk per template.
+        #
+        # `Isolation.require_with_target_bundle` is [ADR-90](../../../../../../docs/adr/90-target-library-resolution-from-project-bundle.md)'s
+        # path — Rigor's own gem env first, then the analysed project's bundle, `$LOAD_PATH` appended and
+        # only on a failed require. Erubi is not a Rigor dependency and is never added to one. Any load
+        # failure is equally "no Erubi here"; stdlib `ERB` answers the same question, so nothing is
+        # reported and nothing degrades but the compiler's name.
+        #
+        # A resolved Erubi that does NOT step line-for-line is **demoted** rather than trusted. Erubi pads
+        # its output to the template's line count deliberately (it is why a Rails backtrace can name
+        # `show.html.erb:12`), so the demotion is not expected to fire — but a compiler whose numbering
+        # the probe cannot confirm would silently report every finding in every template at the wrong
+        # line, and stdlib ERB is right here and always present.
+        def erubi?
+          return @erubi if defined?(@erubi)
+
+          @erubi = load_erubi
+          return @erubi unless @erubi
+          return true unless probe_offset.nil?
+
+          @erubi = false
+        end
+
+        def load_erubi
+          Isolation.require_with_target_bundle("erubi", Isolation.target_bundle_root)
+          defined?(::Erubi::Engine) ? true : false
+        rescue ::StandardError, ::LoadError
+          false
+        end
+
+        # Test seam: forget the probed offset, the resolved compiler and its id, so one process can measure
+        # both compilers. Never called by the plugin itself.
+        def reset!
+          remove_instance_variable(:@line_offset) if defined?(@line_offset)
+          remove_instance_variable(:@transform_id) if defined?(@transform_id)
+          remove_instance_variable(:@erubi) if defined?(@erubi)
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-actionpack/lib/rigor/plugin/actionpack/render_locals.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "controller_scan"
+require_relative "erb_compiler"
+require_relative "view_assigns"
+require_relative "view_units"
+
+module Rigor
+  module Plugin
+    class Actionpack < Rigor::Plugin::Base
+      # #1047 — the locals a render site passes, indexed by the template they are passed TO.
+      #
+      # #393 seeded a template's `locals:` from the Rails 7.1 strict-locals comment only, so a partial
+      # without one read its own parameters as method calls on the view context. That absence has a
+      # measured cost rather than a theoretical one: redmine's `app/views/common/_other.html.erb` opens
+      # with the standard optional-local preamble
+      #
+      #     <% path = nil unless defined? path %>
+      #
+      # and the compiled Ruby really does assign nil there, because nothing told the unit that `path` is
+      # bound — so the flow rules folded three live branches and `flow.` had to join `call.` in the
+      # plugin's default suppressed set for that reason alone
+      # (`docs/notes/20260917-erb-template-units.md` § 4). Tracing the render site is what lets the flow
+      # rules back into a view.
+      #
+      # ## Why over-binding is the safe direction and under-binding is not
+      #
+      # A name this index seeds that the render site did not really pass costs nothing: the local binds
+      # `Dynamic`, `defined?` reads it as bound, and no rule folds anything. A name it MISSES is the
+      # false positive above. So the union across render sites is deliberately generous — a name bound at
+      # only some of a partial's render sites is seeded anyway, typed `Dynamic`, never left absent — and
+      # every shape below that cannot be settled from literals contributes a NAME with no type rather
+      # than nothing.
+      #
+      # The one thing that is not generous is the TYPE. A type is a claim the engine acts on, so a name
+      # keeps a concrete type only when every site that passes it passes the same one; anything else is
+      # {ViewUnits::UNKNOWN_LOCAL}, which the engine binds `Dynamic[top]` (ADR-5).
+      #
+      # ## What a render site is read for
+      #
+      # Both sides of the render, because both bind the same thing:
+      #
+      # - a **controller** site, through {Analyzer.render_target_for} — `render partial: "card",
+      #   locals: { user: @user }`;
+      # - a **template** site, in the compiled Ruby of every view — the same keyword form, plus the
+      #   positional-hash form `render "card", user: @user`, which is locals in a view and OPTIONS in a
+      #   controller (`ActionView::Helpers::RenderingHelper#render(options, locals)` against
+      #   `ActionController::Base#render(options)`). Reading the controller form as locals would seed a
+      #   `status` local for every `render :show, status: :ok` in the corpus.
+      #
+      # `collection:` and `object:` bind a local named after the partial, or after `as:` when given, and a
+      # collection additionally binds the `_counter` and `_iteration` companions Rails provides.
+      #
+      # ## The compiled-source cache
+      #
+      # Building the index compiles every template in the project, and `#template_units_for_file` is about
+      # to compile each of them again. So the builder keeps what it compiled, keyed by path and guarded by
+      # the template's own scrubbed bytes, and the hook reuses it — a full run does exactly the compile
+      # work it did before this feature, one pass instead of two. An editor buffer's bytes differ from the
+      # file's, so its template falls through to its own compile; the index itself is built once per
+      # plugin instance and revalidated once per collection pass against {Builder.fingerprint}, so an
+      # unsaved buffer's render sites are NOT read — its partials keep the locals the saved file passes
+      # until the save.
+      class RenderLocals
+        # What a name is seeded with when no site settled a type for it, or when two disagreed.
+        UNKNOWN = ViewUnits::UNKNOWN_LOCAL
+
+        # Finders and constructors whose Rails implementation raises rather than returning nil — the same
+        # closed set {ViewAssigns::NON_NIL_PRODUCERS} names, and for the same reason: a nil-free nominal
+        # standing in for a runtime nil licenses folds that report correct code.
+        NON_NIL_PRODUCERS = ViewAssigns::NON_NIL_PRODUCERS
+
+        # `{ "common/_other" => { "path" => UNKNOWN, … } }`, keyed by logical name with the format
+        # stripped — a partial's locals do not depend on which format rendered it.
+        attr_reader :by_template
+
+        # The {Builder.fingerprint} of the sources this index was built from, taken BEFORE they were read —
+        # so an edit that lands during the build reads as a change on the next pass rather than being
+        # recorded as already seen. nil for {.empty}, which therefore never matches a real fingerprint.
+        attr_reader :fingerprint
+
+        # Every method name a project helper `def`s — see {ViewUnits.self_declared_locals}.
+        attr_reader :helper_methods
+
+        def initialize(by_template, compiled = {}, fingerprint: nil, helper_methods: {})
+          @by_template = by_template.freeze
+          @compiled = compiled.freeze
+          @fingerprint = fingerprint
+          @helper_methods = helper_methods.freeze
+          freeze
+        end
+
+        def self.empty
+          new({})
+        end
+
+        # `common/_other.html` → the names every site that renders `common/_other` passed.
+        def seeds_for(logical_name)
+          @by_template.fetch(logical_name.to_s.sub(%r{\.[^./]+\z}, ""), {})
+        end
+
+        # The `[compiled, line_map, transform_id, parse_ok]` this index already computed for `path`, or nil
+        # when it read different bytes (an editor buffer) or never saw the file. The bytes are compared
+        # rather than trusted: a unit compiled from the file on disk must never stand in for one the editor
+        # is holding.
+        def compiled_for(path, text)
+          entry = @compiled[path.to_s]
+          return nil if entry.nil? || entry.first != text
+
+          entry.drop(1)
+        end
+
+        # Builds the index from the controller sources and the templates the plugin claims.
+        class Builder
+          def initialize(io_boundary:, controller_search_paths:, view_search_paths:, view_assigns:,
+                         helper_search_paths: [])
+            @io_boundary = io_boundary
+            @controller_search_paths = controller_search_paths
+            @view_search_paths = view_search_paths
+            @helper_search_paths = helper_search_paths
+            @view_assigns = view_assigns
+            # `{ target => [ { name => type_name_or_nil }, … ] }` — one hash per render site, merged only
+            # once every site has been seen, because "bound at some sites" is a property of the whole set.
+            @sites = Hash.new { |hash, key| hash[key] = [] }
+          end
+
+          def build
+            fingerprint = self.class.fingerprint(
+              io_boundary: @io_boundary, controller_search_paths: @controller_search_paths,
+              view_search_paths: @view_search_paths, helper_search_paths: @helper_search_paths
+            )
+            harvest_controllers
+            compiled = harvest_templates
+            RenderLocals.new(@sites.transform_values { |sites| merge(sites) }, compiled,
+                             fingerprint: fingerprint, helper_methods: harvest_helper_methods)
+          end
+
+          # What the index was built from, as one String: every controller, helper and template path with
+          # its size and mtime. A glob catches a file appearing or vanishing and a stat catches an edit;
+          # neither reads a byte, so revalidating costs one `stat` per file, once per collection pass.
+          #
+          # There is deliberately no content-digest fallback, unlike the collector's ADR-87 pack: a
+          # byte-identical `touch` moves the fingerprint and rebuilds this index while the collector still
+          # carries the units. That costs one rebuild and never a wrong answer — the rebuilt index is the
+          # index the carried units were seeded from — so a digest per file per pass is not worth buying.
+          def self.fingerprint(io_boundary:, controller_search_paths:, view_search_paths:, helper_search_paths: [])
+            files = source_files(io_boundary, controller_search_paths, "*.rb") +
+                    source_files(io_boundary, helper_search_paths, "*.rb") +
+                    source_files(io_boundary, view_search_paths, "*.erb")
+            files.map do |path|
+              stat = File.stat(path)
+              "#{path}\0#{stat.size}\0#{stat.mtime.to_r}"
+            rescue SystemCallError
+              "#{path}\0gone"
+            end.join("\n")
+          end
+
+          # Project-relative paths, the spelling `#template_units_for_file` is handed and the spelling the
+          # compiled cache is keyed by.
+          def self.source_files(io_boundary, roots, pattern)
+            root_prefix = "#{Dir.pwd}#{File::SEPARATOR}"
+            roots.flat_map do |root|
+              absolute = File.expand_path(root)
+              next [] unless io_boundary.directory?(absolute)
+
+              Dir.glob(File.join(absolute, "**", pattern)).map { |path| path.delete_prefix(root_prefix) }
+            end
+          end
+
+          private
+
+          # Two sites that agree on a name and its type keep the type; anything else — a disagreement, a
+          # site that settled no type, or a site that did not pass the name at all — is `Dynamic`.
+          def merge(sites)
+            names = sites.flat_map(&:keys).uniq
+            names.to_h do |name|
+              types = sites.map { |site| site.key?(name) ? site[name] : :absent }.uniq
+              [name, types.length == 1 && types.first.is_a?(String) ? types.first : UNKNOWN]
+            end
+          end
+
+          HELPER_DEF = /^[ \t]*def[ \t]+(?:self\.)?([a-z_][A-Za-z0-9_]*[?!]?)/
+          private_constant :HELPER_DEF
+
+          # `{ "current_user" => true }` for every `def` in a project helper. A line scan rather than a
+          # parse: the answer only has to be a superset of the names a helper can answer, and a name read
+          # out of a comment or a heredoc merely leaves one template's `defined?` test unseeded — which is
+          # what #393 shipped for every name.
+          def harvest_helper_methods
+            source_files(@helper_search_paths, "*.rb").each_with_object({}) do |path, names|
+              read(path)&.scan(HELPER_DEF)&.each { |(name)| names[name] = true }
+            end
+          end
+
+          def harvest_controllers
+            source_files(@controller_search_paths, "*.rb").each do |path|
+              tree = parse_file(path)
+              next if tree.nil?
+
+              ControllerScan.each_controller(tree, []) do |node, namespace|
+                harvest_controller(node, namespace)
+              end
+            end
+          end
+
+          def harvest_controller(node, namespace)
+            segments = namespace + ControllerScan.constant_segments(node.constant_path)
+            prefix = ControllerScan.controller_path(segments)
+            return if prefix.nil?
+
+            ControllerScan.method_bodies(node).each do |action, body|
+              ivars = @view_assigns.seeds_for("#{prefix}/#{action}")
+              ControllerScan.each_render(body) do |call|
+                record(controller_target(call, prefix), call, ivars, view_side: false)
+              end
+            end
+          end
+
+          # {Analyzer.render_target_for} already answers this for a controller: `render :edit`,
+          # `render "admin/shared/form"`, `render partial: "card"`. Its `[:template, name]` /
+          # `[:partial, name]` pair reduces to the name, because the locals of a template and of a partial
+          # are seeded the same way.
+          def controller_target(call, prefix)
+            Analyzer.render_target_for(call, prefix)&.last
+          end
+
+          # Every claimed template, compiled once. Returns the `{ path => [text, compiled, map, id, ok] }`
+          # cache `#template_units_for_file` reuses.
+          def harvest_templates
+            source_files(@view_search_paths, "*.erb").each_with_object({}) do |path, compiled|
+              text = read(path)
+              next if text.nil?
+
+              text = ErbCompiler.scrub(text)
+              source, line_map, transform = ErbCompiler.compile(text)
+              result = Prism.parse(source)
+              compiled[path] = [text, source, line_map, transform, result.errors.empty?]
+              next unless result.errors.empty?
+
+              harvest_template(path, result.value)
+            end
+          rescue ErbCompiler::Unmappable
+            {}
+          end
+
+          def harvest_template(path, tree)
+            name = ViewUnits.logical_name(path, @view_search_paths).sub(%r{\.[^./]+\z}, "")
+            directory = name.include?("/") ? File.dirname(name) : ""
+            ivars = @view_assigns.seeds_for(name)
+            ControllerScan.each_render(tree) do |call|
+              record(template_target(call, directory), call, ivars, view_side: true)
+            end
+          end
+
+          # The view-side reading of a render target, which differs from the controller's in exactly one
+          # place: a bare positional name is a PARTIAL here. `template:` is the escape hatch an author uses
+          # when they mean otherwise, and `layout:` in a view names a partial too — the same reading
+          # {Effects::CalleeRule.rails_render_partial} takes, for the same reason.
+          def template_target(call, directory)
+            explicit = string_option(call, "template")
+            return qualify(explicit, directory) if explicit
+
+            partial = string_option(call, "partial") || string_option(call, "layout")
+            return partialize(qualify(partial, directory)) if partial
+
+            positional = (call.arguments&.arguments || []).grep_v(Prism::KeywordHashNode).first
+            return nil unless positional.is_a?(Prism::StringNode) || positional.is_a?(Prism::SymbolNode)
+
+            partialize(qualify(positional.unescaped, directory))
+          end
+
+          def record(target, call, ivars, view_side:)
+            return if target.nil? || target.empty?
+
+            locals = locals_at(call, target, ivars, view_side: view_side)
+            @sites[target] << locals
+          end
+
+          # The names one render site binds, and the type of each where the site settled one.
+          def locals_at(call, target, ivars, view_side:)
+            arguments = call.arguments&.arguments || []
+            options = arguments.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+            locals = {}
+            # `render "card", user: @user` — the view's second positional argument IS the locals hash, and
+            # the controller's is options. Read alongside an explicit `locals:` rather than instead of it,
+            # because over-binding is the safe direction.
+            collect_pairs(options, locals, ivars) if view_side && !arguments.first.is_a?(Prism::KeywordHashNode)
+            collect_pairs(option(call, "locals"), locals, ivars)
+            collect_object_locals(call, target, locals, ivars)
+            locals
+          end
+
+          # `locals: { user: @user }` and its hashrocket spelling. A key that is not a literal symbol or
+          # string — a computed key, a `**splat` — names nothing this can seed, and is skipped rather than
+          # guessed at.
+          def collect_pairs(hash, locals, ivars)
+            return unless hash.is_a?(Prism::HashNode) || hash.is_a?(Prism::KeywordHashNode)
+
+            hash.elements.each do |element|
+              next unless element.is_a?(Prism::AssocNode)
+
+              name = literal_name(element.key)
+              next if name.nil? || !name.match?(/\A[a-z_][A-Za-z0-9_]*\z/)
+
+              locals[name] = value_type(element.value, ivars)
+            end
+          end
+
+          # `object:` binds one local named after the partial; `collection:` binds the same name plus the
+          # `_counter` and `_iteration` companions Rails provides, and never a type — the local is the
+          # ELEMENT, and nothing at the site names the element's class.
+          def collect_object_locals(call, target, locals, ivars)
+            base = literal_name(option(call, "as")) || File.basename(target).delete_prefix("_")
+            return unless base.match?(/\A[a-z_][A-Za-z0-9_]*\z/)
+
+            object = option(call, "object")
+            collection = option(call, "collection")
+            locals[base] = value_type(object, ivars) if object
+            return if collection.nil?
+
+            locals[base] = nil
+            locals["#{base}_counter"] = nil
+            locals["#{base}_iteration"] = nil
+          end
+
+          # The two shapes a render site settles a type from, and nothing else: a non-nil-able finder or
+          # constructor on a constant (`User.find(params[:id])`), and an ivar the rendering unit's own
+          # seeds already typed. Anything else is a name with no type.
+          def value_type(node, ivars)
+            case node
+            when Prism::InstanceVariableReadNode then ivars[node.name.to_s]
+            when Prism::CallNode then produced_type(node)
+            end
+          end
+
+          def produced_type(call)
+            return nil unless NON_NIL_PRODUCERS.include?(call.name)
+
+            receiver = call.receiver
+            return nil unless receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
+
+            name = ControllerScan.constant_segments(receiver).join("::")
+            name.empty? ? nil : name
+          end
+
+          def option(call, key)
+            hash = call.arguments&.arguments&.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+            pair = hash&.elements&.find do |element|
+              element.is_a?(Prism::AssocNode) && literal_name(element.key) == key
+            end
+            pair&.value
+          end
+
+          def string_option(call, key)
+            value = option(call, key)
+            value.is_a?(Prism::StringNode) || value.is_a?(Prism::SymbolNode) ? value.unescaped : nil
+          end
+
+          def literal_name(node)
+            node.unescaped if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+          end
+
+          def qualify(name, directory)
+            return nil if name.nil? || name.empty?
+            return name if name.include?("/") || directory.empty?
+
+            "#{directory}/#{name}"
+          end
+
+          def partialize(name)
+            return nil if name.nil?
+
+            directory, separator, base = name.rpartition("/")
+            return base.start_with?("_") ? name : "_#{name}" if separator.empty?
+
+            base.start_with?("_") ? name : "#{directory}/_#{base}"
+          end
+
+          def source_files(roots, pattern)
+            self.class.source_files(@io_boundary, roots, pattern)
+          end
+
+          def read(path)
+            @io_boundary.read_file(File.expand_path(path))
+          rescue Plugin::AccessDeniedError, Errno::ENOENT
+            nil
+          end
+
+          def parse_file(path)
+            contents = read(path)
+            return nil if contents.nil?
+
+            result = Prism.parse(contents)
+            result.errors.empty? ? result.value : nil
+          end
+        end
+      end
+    end
+  end
+end