hecks 1.3.0 → 1.4.0

data/lib/hecks/codemod/legacy_dispatch_args.rb

@@ -0,0 +1,299 @@
+require "json"
+require "prism"
+
+module Hecks
+  module Codemod
+    # The rewriting half of `bin/codemod_legacy_dispatch_args` — reads what
+    # `LegacyDispatchRecorder` observed and rewrites each agreed call site
+    # from loose keyword facts to `to:` / `with:`:
+    #
+    #   runtime.dispatch("Banking::Account.FreezeAccount", number: { value: "a" })
+    #   # becomes
+    #   runtime.dispatch("Banking::Account.FreezeAccount", to: "a")
+    #
+    # A key that carried receiver identity and is a declared fact of the
+    # command appears in both `to:` and `with:`, and only when its expression
+    # is safe to evaluate twice.
+    #
+    # A site is rewritten only when every recorded dispatch through it split
+    # the same way, strict `with:` accepted it (or refused it with the same
+    # class the loose call was refused with), no key it would move into `to:`
+    # also rode the event payload (`to:` would empty that field for whatever
+    # reacts downstream), and the call's own text still
+    # carries exactly the recorded keys, identity keys as literal pairs.
+    # Anything else is reported with its reason and left alone. Ruby files
+    # and the runnable blocks of Markdown guides (the ones `spec/support/
+    # doctest.rb` executes) are both rewritten.
+    module LegacyDispatchArgs
+      ROUTING = %i[to with saga_correlation].freeze
+      RUNNABLE_OPENERS = ["```ruby bluebook", "```ruby boot", "```ruby", "<!-- doctest:boot"].freeze
+
+      Plan = Struct.new(:to_keys, :with_keys, :slots, keyword_init: true)
+      Outcome = Struct.new(:path, :line, :status, :reason, keyword_init: true)
+      Skip = Struct.new(:reason)
+
+      module_function
+
+      # { [path, line] => Plan or Skip }
+      def plans(recording)
+        File.foreach(recording).map { |line| JSON.parse(line) }
+            .select { |entry| entry["site"] }
+            .group_by { |entry| entry["site"].rpartition(":").then { |path, _, line| [path, line.to_i] } }
+            .transform_values { |entries| plan_for(entries) }
+      end
+
+      def plan_for(entries)
+        refused = entries.find { |entry| entry["unrewritable"] }
+        return Skip.new(refused["unrewritable"]) if refused
+
+        mismatch = entries.find { |entry| entry["strict"] && entry["strict"] != entry["outcome"] }
+        if mismatch
+          return Skip.new("with: would refuse (#{mismatch['strict']}) where the loose call ended #{mismatch['outcome']}")
+        end
+
+        leaked = entries.flat_map { |entry| (entry["to_keys"].to_a - entry["with_keys"].to_a) & entry["payload_keys"].to_a }.uniq
+        unless leaked.empty?
+          return Skip.new("#{leaked.join(', ')} carries receiver identity AND rides the event payload, " \
+                          "which `to:` would empty")
+        end
+
+        shapes = entries.map { |entry| [entry["keys"].sort, entry["to_keys"], entry["with_keys"].sort, entry["slots"]] }.uniq
+        return Skip.new("the site dispatched #{shapes.size} differently-shaped fact sets") unless shapes.one?
+
+        first = entries.first
+        Plan.new(to_keys: first["to_keys"], with_keys: first["with_keys"], slots: first["slots"])
+      end
+
+      # [new_text, outcomes] for one file; `site_plans` is { line => Plan or Skip }.
+      def rewrite(path, site_plans)
+        text = File.binread(path).force_encoding(Encoding::UTF_8)
+        outcomes = []
+        edits = []
+
+        site_plans.sort.each do |line, plan|
+          result = plan.is_a?(Skip) ? plan : edit_for(text, path, line, plan)
+          if result.is_a?(Skip)
+            outcomes << Outcome.new(path: path, line: line, status: :skipped, reason: result.reason)
+          else
+            edits << result
+            outcomes << Outcome.new(path: path, line: line, status: :rewritten)
+          end
+        end
+
+        edits.uniq.sort_by { |start, _, _| -start }.each do |start, finish, replacement|
+          text = text.byteslice(0, start) + replacement + text.byteslice(finish..)
+        end
+        [text, outcomes]
+      end
+
+      # [start byte, end byte, replacement] in file coordinates, or a Skip.
+      def edit_for(text, path, line, plan)
+        offset, code, first_line = region(text, path, line)
+        return Skip.new("line #{line} is not inside a runnable Ruby block") unless code
+
+        tree = Prism.parse(code, line: first_line)
+        return Skip.new("the enclosing Ruby does not parse") unless tree.errors.empty?
+
+        calls = []
+        collect_calls(tree.value, line, calls)
+        skips = []
+        calls.sort_by { |call| call.location.length }.each do |call|
+          keywords = call.arguments.arguments.last
+          result = replacement_for(keywords, plan)
+          if result.is_a?(Skip)
+            skips << result
+            next
+          end
+
+          return [offset + keywords.location.start_offset, offset + keywords.location.end_offset, result]
+        end
+        skips.first || Skip.new("no call with keyword arguments at line #{line}")
+      end
+
+      # The whole file for Ruby; for Markdown, the runnable block containing
+      # `line`. [byte offset of the block, its code, its first line number].
+      def region(text, path, line)
+        return [0, text, 1] unless path.end_with?(".md")
+
+        offset = 0
+        open = nil
+        text.each_line.with_index(1) do |source_line, number|
+          if open
+            if source_line.strip == open[:closer]
+              if open[:runnable] && (open[:line]...number).cover?(line)
+                return [open[:offset], text.byteslice(open[:offset], offset - open[:offset]),
+                        open[:line]]
+              end
+
+              open = nil
+            end
+          elsif source_line.start_with?("```", "<!-- doctest:boot")
+            opener = source_line.rstrip
+            open = { closer: opener.start_with?("<!--") ? "-->" : "```", runnable: RUNNABLE_OPENERS.include?(opener),
+                     offset: offset + source_line.bytesize, line: number + 1 }
+          end
+          offset += source_line.bytesize
+        end
+        nil
+      end
+
+      def collect_calls(node, line, found)
+        return unless node
+
+        if node.is_a?(Prism::CallNode) && node.arguments&.arguments&.last.is_a?(Prism::KeywordHashNode) &&
+           node.location.start_line <= line && line <= node.location.end_line
+          found << node
+        end
+        node.compact_child_nodes.each { |child| collect_calls(child, line, found) }
+      end
+
+      def key_of(element)
+        element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) ? element.key.unescaped : nil
+      end
+
+      # The rewritten keyword arguments, or why this call does not match the plan.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def replacement_for(keywords, plan)
+        elements = keywords.elements
+        return Skip.new("a keyword with a non-literal key") if elements.any? { |e| e.is_a?(Prism::AssocNode) && key_of(e).nil? }
+
+        routing = elements.select { |element| ROUTING.map(&:to_s).include?(key_of(element)) }
+        loose = elements - routing
+        return Skip.new("no loose keywords in this call") if loose.empty?
+        return Skip.new("to: is spelled in the call but the recording routed by identity") if routing.any? do |e|
+          key_of(e) == "to"
+        end && !plan.slots.empty?
+
+        literal = loose.filter_map { |element| key_of(element) }
+        splats = loose.reject { |element| key_of(element) }
+        recorded = (plan.to_keys + plan.with_keys).uniq
+        if splats.empty? && literal.sort != recorded.sort
+          return Skip.new("the call's keys (#{literal.sort.join(', ')}) are not the recorded keys (#{recorded.sort.join(', ')})")
+        end
+        if splats.any? && !((literal - recorded).empty? && (plan.to_keys - literal).empty?)
+          return Skip.new("a splat carries keys this call does not spell out")
+        end
+
+        route = route_text(loose, plan)
+        return route if route.is_a?(Skip)
+
+        to_only = loose.select { |element| (plan.to_keys - plan.with_keys).include?(key_of(element)) }
+        kept = elements - to_only
+        facts = loose - to_only
+        positions = facts.map { |element| kept.index(element) }
+        return Skip.new("routing keywords sit between the facts") unless positions.each_cons(2).all? { |a, b| b == a + 1 }
+
+        assemble(keywords, kept, facts, route)
+      end
+
+      def route_text(loose, plan)
+        parts = []
+        plan.slots.each do |slot|
+          element = loose.find { |candidate| key_of(candidate) == slot["key"] }
+          expression = element && identity_expression(element.value, slot)
+          return Skip.new("#{slot['key']}: its identity is not spelled the recorded way") unless expression
+          if plan.with_keys.include?(slot["key"]) && !pure?(expression)
+            return Skip.new("#{slot['key']}: carries identity and a fact, and its expression is not safe to evaluate twice")
+          end
+
+          parts[slot["part"]] = expression.slice
+        end
+
+        case parts.size
+        when 0 then nil
+        when 1 then "to: #{parts.first}"
+        when 2 then "to: { aggregate: #{parts[0]}, entity: #{parts[1]} }"
+        else "to: { aggregate: #{parts[0]}, entities: [#{parts[1..].join(', ')}] }"
+        end
+      end
+
+      # Every fact keeps its own line, re-aligned. A fact that used to
+      # start a line was aligned under whatever the call opened with; once
+      # the facts sit inside `with: { `, that column means nothing, so each
+      # following fact is re-indented under the first fact's new column
+      # (ordinary Ruby hash alignment) and any line inside a single fact's
+      # own value is shifted by the same amount, keeping its shape.
+      def assemble(keywords, kept, facts, route)
+        elements = keywords.elements
+        source = keywords.location.slice
+        base = keywords.location.start_offset
+        gap_after = lambda do |element|
+          following = elements[elements.index(element) + 1]
+          start = element.location.end_offset - base
+          following ? source.byteslice(start, following.location.start_offset - element.location.end_offset) : ", "
+        end
+
+        pieces = route ? [route] : []
+        column = advance(keywords.location.start_column, pieces.empty? ? "" : "#{route}, ")
+        index = 0
+        while index < kept.size
+          element = kept[index]
+          if facts.first.equal?(element)
+            pieces << with_clause(facts, column, gap_after)
+            index += facts.size
+          else
+            pieces << element.slice
+            index += 1
+          end
+          column = advance(column, "#{pieces.last}, ")
+        end
+        pieces.join(", ")
+      end
+
+      def with_clause(facts, column, gap_after)
+        opener = "with: { "
+        fact_column = column + opener.length
+        delta = fact_column - facts.first.location.start_column
+        body = facts.each_with_index.map do |fact, position|
+          gap = position < facts.size - 1 ? gap_after.call(fact).sub(/\n[^\S\n]*\z/, "\n#{' ' * fact_column}") : ""
+          reindent(fact.slice, delta) + gap
+        end.join
+        "#{opener}#{body} }"
+      end
+
+      # The column `text` ends at, having started at `column`.
+      def advance(column, text)
+        before, newline, after = text.rpartition("\n")
+        newline.empty? ? column + before.length + after.length : after.length
+      end
+
+      # Every line but the first moved right (or left) by `delta`.
+      def reindent(text, delta)
+        return text if delta.zero? || !text.include?("\n")
+
+        first, _, rest = text.partition("\n")
+        "#{first}\n" + rest.gsub(/^[^\S\n]*/) do |indent|
+          delta.positive? ? indent + (" " * delta) : indent[0, [indent.length + delta, 0].max]
+        end
+      end
+
+      def identity_expression(value, slot)
+        return value if slot["form"] == "scalar"
+        return nil unless value.is_a?(Prism::HashNode) && value.elements.one?
+
+        pair = value.elements.first
+        pair.value if key_of(pair) == slot["inner"]
+      end
+
+      # Safe to evaluate twice: literals, variable/constant reads, and
+      # argument-free method chains over them (`order.id`, `created.instance.id`).
+      def pure?(node)
+        case node
+        when Prism::StringNode, Prism::SymbolNode, Prism::IntegerNode, Prism::FloatNode, Prism::NilNode,
+             Prism::TrueNode, Prism::FalseNode, Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode,
+             Prism::ConstantReadNode, Prism::ConstantPathNode
+          true
+        when Prism::InterpolatedStringNode
+          node.parts.all? do |part|
+            part.is_a?(Prism::StringNode) ||
+              (part.is_a?(Prism::EmbeddedStatementsNode) && Array(part.statements&.body).all? { |inner| pure?(inner) })
+          end
+        when Prism::CallNode
+          node.arguments.nil? && node.block.nil? && (node.receiver.nil? || pure?(node.receiver))
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/codemod/legacy_dispatch_recorder.rb

@@ -0,0 +1,186 @@
+# Nothing here requires a gem at load time — this file arrives through
+# RUBYOPT, ahead of `bundler/setup`, and activating a default gem (json)
+# that early makes Bundler refuse the Gemfile's own version. `json` is
+# required on first write instead, by which point Bundler has resolved.
+require_relative "../deprecation"
+
+module Hecks
+  module Codemod
+    # The observing half of `bin/codemod_legacy_dispatch_args`. Loaded into a
+    # test run through RUBYOPT (`bin/codemod_legacy_dispatch_args record --
+    # <command>` arms it), it wraps `Runtime::Dispatcher#dispatch` and, for
+    # every call that passed loose keyword facts, appends one JSON line
+    # saying how that call's facts split between `to:` and `with:`.
+    #
+    # **Why record instead of reading source** — loose keyword facts carry the
+    # receiver's identity (`number: { value: "a1" }`, `id: order.id`) mixed
+    # in with the command's facts, and which key is which is a property of
+    # the target command's IR (its `identified_by`, its declared attributes,
+    # the reference aliases `ReactionInvocation` accepts), not of the call's
+    # text. The recorder asks the same `ReactionInvocation.build(explicit:
+    # true)` split a policy's `with:` projection already uses, against the
+    # real registry and the real values, then checks the strict `with:`
+    # door would accept the result. The rewriter only touches a site whose
+    # every observation agrees.
+    #
+    # Each line: site ("path:line", the caller's own line), verb, the loose
+    # keys, `to_keys` (keys that carried receiver identity), `with_keys`
+    # (declared facts — a key can be both), `slots` (which key fills which
+    # part of the route, and whether its identity sat inside a one-field
+    # hash), `strict` (the refusal class strict `with:` raises, or nil),
+    # `outcome` ("ok" or the class the real dispatch raised),
+    # `payload_keys` (every key the dispatch's own events carried), and
+    # `unrewritable` when no split exists.
+    module LegacyDispatchRecorder
+      module_function
+
+      def arm!(path)
+        return install!(path) if defined?(Hecks::Runtime::Dispatcher)
+
+        trace = TracePoint.new(:end) do |point|
+          next unless point.self.is_a?(Module) && point.self.name == "Hecks::Runtime::Dispatcher"
+
+          trace.disable
+          install!(path)
+        end
+        trace.enable
+      end
+
+      def install!(path)
+        Hecks::Runtime::Dispatcher.prepend(Wrap)
+        Wrap.path = path
+      end
+
+      # Prepended onto Runtime::Dispatcher.
+      module Wrap
+        class << self
+          attr_accessor :path
+        end
+
+        def dispatch(verb, to: nil, with: nil, saga_correlation: nil, **legacy_args)
+          return super if legacy_args.empty?
+
+          entry = LegacyDispatchRecorder.observe(self, verb, to, with, legacy_args)
+          begin
+            result = super
+            entry[:outcome] = "ok"
+            entry[:payload_keys] = LegacyDispatchRecorder.payload_keys(result)
+            result
+          rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised unchanged
+            entry[:outcome] = e.class.name
+            raise
+          ensure
+            LegacyDispatchRecorder.write(Wrap.path, entry)
+          end
+        end
+      end
+
+      # Every key the dispatch's own events carry. A loose fact reaches the
+      # event payload whether the command declares it or not, and a policy
+      # with no `with:` projection forwards that payload verbatim — so
+      # moving a key out of the facts and into `to:` can silently empty a
+      # field whatever reacts downstream needs. Recorded here so `plan_for`
+      # can refuse exactly those sites; a real one (Banking's own
+      # FreezeAccount -> ReviewOnFreeze -> AccountFreezeReview.Open, in
+      # docs/implemented/reference/policy.md, whose own `# => true` on
+      # `reaction_log.last[:delivered]` went false) is why this exists.
+      def payload_keys(result)
+        return [] unless result.respond_to?(:events)
+
+        result.events.flat_map { |event| Hash(event.payload).keys.map(&:to_s) }.uniq
+      rescue StandardError
+        []
+      end
+
+      def observe(dispatcher, verb, to, with, legacy)
+        frame = caller_locations(2).find { |location| Hecks::Deprecation.external?(location) }
+        entry = { site: frame && "#{frame.absolute_path || frame.path}:#{frame.lineno}", verb: verb.to_s,
+                  to_given: !to.nil?, keys: legacy.keys.map(&:to_s) }
+        entry.merge(split(dispatcher.registry, verb, to, with, legacy))
+      rescue StandardError => e
+        entry.merge(unrewritable: "#{e.class}: #{e.message}")
+      end
+
+      def write(path, entry)
+        require "json"
+        File.open(path, "a") do |file|
+          file.flock(File::LOCK_EX)
+          file.puts(JSON.generate(entry))
+        end
+      end
+
+      def split(registry, verb, to, with, legacy)
+        return { unrewritable: "with: and loose keywords in the same call" } if with
+        return { unrewritable: "a loose keyword that is not a Symbol" } unless legacy.keys.all?(Symbol)
+
+        invocation = Hecks::Runtime::ReactionInvocation
+        target = invocation.send(:resolve_target, registry, verb)
+
+        if to
+          return { to_keys: [], with_keys: legacy.keys.map(&:to_s), slots: [],
+                   strict: strict(target, to, legacy) }
+        end
+
+        built = invocation.build(registry: registry, verb: verb, projected: legacy, explicit: true)
+        route = built[:to]
+        with_keys = legacy.keys.select { |key| built[:with].key?(key) }
+        to_keys = route.nil? ? [] : legacy.keys.select { |key| consumed?(registry, verb, legacy, key, route) }
+        slots = slots_for(route, to_keys, legacy)
+        return slots if slots.is_a?(Hash)
+
+        { to_keys: to_keys.map(&:to_s), with_keys: with_keys.map(&:to_s), slots: slots,
+          strict: strict(target, route, legacy.slice(*with_keys)) }
+      end
+
+      # A key carried receiver identity when the route changes (or can no
+      # longer be built) without it.
+      def consumed?(registry, verb, legacy, key, route)
+        Hecks::Runtime::ReactionInvocation.build(registry: registry, verb: verb,
+                                                 projected: legacy.except(key), explicit: true)[:to] != route
+      rescue StandardError
+        true
+      end
+
+      # Which key fills each part of the route. Refuses anything a source
+      # rewrite cannot spell as `to: <that key's expression>`: a composite
+      # identity, two keys naming the same part, or a non-String identity
+      # (`to:` takes only a String).
+      def slots_for(route, to_keys, legacy)
+        return [] if route.nil?
+
+        parts = route.is_a?(Hash) ? [route[:aggregate], *route[:entities]] : [route]
+        if to_keys.size != parts.size
+          return { unrewritable: "identity spread over #{to_keys.size} keys for #{parts.size} route parts" }
+        end
+
+        to_keys.map do |key|
+          form, inner, text = candidate(legacy[key])
+          return { unrewritable: "#{key}: identity is not a String or a one-field hash of one" } unless text
+
+          matches = parts.each_index.select { |index| parts[index].to_s == text }
+          return { unrewritable: "#{key}: identity matches #{matches.size} route parts" } unless matches.one?
+
+          { key: key.to_s, part: matches.first, form: form, inner: inner }
+        end
+      end
+
+      def candidate(raw)
+        return ["scalar", nil, raw] if raw.is_a?(String)
+        return nil unless raw.is_a?(Hash) && raw.size == 1
+
+        inner, value = raw.first
+        ["hash", inner.to_s, value] if value.is_a?(String)
+      end
+
+      def strict(target, route, facts)
+        Hecks::Runtime::Invocation.route(route, entity_depth: target.entities.size)
+        Hecks::Runtime::Invocation.facts_for(target.command, with: facts, legacy: {})
+        nil
+      rescue StandardError => e
+        e.class.name
+      end
+    end
+  end
+end
+
+Hecks::Codemod::LegacyDispatchRecorder.arm!(ENV["HECKS_LEGACY_DISPATCH_RECORD"]) if ENV["HECKS_LEGACY_DISPATCH_RECORD"]