canon 0.3.26 → 0.3.28

data/lib/canon/rebaseliner/call_site_resolver.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Canon
+  module Rebaseliner
+    # Parse a spec file with Prism, locate the matcher invocation at a
+    # specific line, and return enough context (matcher AST + enclosing
+    # `it`/`example` block + full source) for the locator and rewriter to
+    # work against.
+    class CallSiteResolver
+      Result = Struct.new(
+        :source,            # full file source (UTF-8 string)
+        :matcher_call_node, # Prism::CallNode for `be_*_equivalent_to(arg)`
+        :expected_node,     # the `expected` argument node (first positional arg)
+        :enclosing_block,   # the `it`/`example` block containing the call
+        :matcher_line,      # 1-indexed line number of the matcher invocation
+        keyword_init: true,
+      )
+
+      MATCHER_NAMES = %i[
+        be_equivalent_to
+        be_xml_equivalent_to
+        be_html_equivalent_to
+        be_json_equivalent_to
+        be_yaml_equivalent_to
+        be_serialization_equivalent_to
+      ].freeze
+
+      # @param spec_path [String]
+      # @param line [Integer] 1-indexed line number where the matcher
+      #   invocation lives (typically from `caller_locations`)
+      # @return [Result, nil] nil if the file can't be parsed or no matcher
+      #   call is found at that line
+      def self.resolve(spec_path:, line:)
+        source = File.read(spec_path)
+        parse_result = Prism.parse(source)
+        return nil unless parse_result.success?
+
+        new(source: source,
+            root: parse_result.value,
+            line: line).resolve
+      end
+
+      def initialize(source:, root:, line:)
+        @source = source
+        @root = root
+        @line = line
+      end
+
+      def resolve
+        call_node = find_matcher_call(@root)
+        return nil unless call_node
+
+        expected = call_node.arguments&.arguments&.first
+        return nil unless expected
+
+        enclosing = find_enclosing_block(@root, call_node)
+        return nil unless enclosing
+
+        Result.new(
+          source: @source,
+          matcher_call_node: call_node,
+          expected_node: expected,
+          enclosing_block: enclosing,
+          matcher_line: call_node.location.start_line,
+        )
+      end
+
+      private
+
+      # Locate a CallNode whose method name is one of MATCHER_NAMES and
+      # whose location encompasses the target line.
+      def find_matcher_call(root)
+        match = nil
+        walk(root) do |node|
+          next unless node.is_a?(Prism::CallNode)
+          next unless MATCHER_NAMES.include?(node.name)
+
+          loc = node.location
+          next unless @line.between?(loc.start_line, loc.end_line)
+
+          # Prefer the narrowest enclosing match (innermost matcher).
+          if match.nil? ||
+              (loc.end_line - loc.start_line) <
+                  (match.location.end_line - match.location.start_line)
+            match = node
+          end
+        end
+        match
+      end
+
+      # Locate the enclosing `it { ... }` / `example { ... }` block. RSpec
+      # uses `it("...") do ... end` which Prism parses as a CallNode with
+      # an attached BlockNode. The BlockNode is the body we want.
+      def find_enclosing_block(root, target_call)
+        candidates = []
+        walk(root) do |node|
+          next unless node.is_a?(Prism::CallNode)
+          next if node.block.nil?
+          next unless %i[it example specify focus].include?(node.name)
+
+          loc = node.location
+          target_loc = target_call.location
+          next unless loc.start_line <= target_loc.start_line &&
+            loc.end_line >= target_loc.end_line
+
+          candidates << node.block
+        end
+        # Innermost wins.
+        candidates.min_by { |b| b.location.end_line - b.location.start_line }
+      end
+
+      def walk(node, &block)
+        return unless node
+
+        yield node
+        return unless node.is_a?(Prism::Node)
+
+        node.child_nodes.each do |child|
+          walk(child, &block) unless child.nil?
+        end
+      end
+    end
+  end
+end

data/lib/canon/rebaseliner/heredoc_locator.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Canon
+  module Rebaseliner
+    # Resolve a Prism AST node (the `expected` argument passed to a Canon
+    # matcher) to a {HeredocTarget} that can be rewritten in-place, or to a
+    # skip reason. Handles the metanorma-iso pattern of multiple sequential
+    # assignments to the same local var via "most-recent assignment before
+    # the matcher line" semantics.
+    class HeredocLocator
+      Result = Struct.new(:status, :heredoc_spec, keyword_init: true) do
+        def rewritable?
+          status == :ok
+        end
+      end
+
+      # @param spec_path [String] absolute path of the spec file (passed through
+      #   into any returned HeredocTarget)
+      # @param source [String] full file source string
+      # @param enclosing_block [Prism::Node] the `it`/`example` block node
+      #   that contains the matcher invocation
+      # @param expected_node [Prism::Node] the AST node passed as `expected`
+      #   to the matcher
+      # @param matcher_line [Integer] 1-indexed line of the matcher call;
+      #   used as the upper bound when walking backward for the most recent
+      #   local-var assignment
+      def initialize(spec_path:, source:, enclosing_block:, expected_node:,
+                     matcher_line:)
+        @spec_path = spec_path
+        @source = source
+        @enclosing_block = enclosing_block
+        @expected_node = expected_node
+        @matcher_line = matcher_line
+      end
+
+      # @return [Result] :ok with a HeredocTarget, or a :skipped_* status
+      def resolve
+        resolve_node(@expected_node)
+      end
+
+      private
+
+      def resolve_node(node)
+        case node
+        when Prism::StringNode
+          resolve_string_node(node)
+        when Prism::InterpolatedStringNode
+          resolve_interpolated_string_node(node)
+        when Prism::LocalVariableReadNode
+          resolve_local_variable(node)
+        else
+          # CallNode, ConstantReadNode, IndexReadNode, etc.
+          Result.new(status: :skipped_method_call)
+        end
+      end
+
+      def resolve_string_node(node)
+        opening = node.opening_loc&.slice
+        return Result.new(status: :skipped_inline_string) unless heredoc_opening?(opening)
+
+        spec = build_heredoc_spec(node, opening)
+        Result.new(status: :ok, heredoc_spec: spec)
+      end
+
+      def resolve_interpolated_string_node(node)
+        opening = node.opening_loc&.slice
+        return Result.new(status: :skipped_inline_string) unless heredoc_opening?(opening)
+
+        # Any interpolation part means we can't rewrite mechanically in v1.
+        Result.new(status: :skipped_interpolation)
+      end
+
+      def resolve_local_variable(node)
+        name = node.name
+        most_recent = find_most_recent_assignment(@enclosing_block, name,
+                                                  @matcher_line)
+        return Result.new(status: :skipped_cross_file) unless most_recent
+
+        resolve_node(most_recent.value)
+      end
+
+      # Walk all statements inside the enclosing block recursively and
+      # collect every LocalVariableWriteNode whose name matches and whose
+      # line is strictly before `matcher_line`. Return the one with the
+      # greatest line number.
+      def find_most_recent_assignment(block_node, name, matcher_line)
+        candidates = []
+        walk(block_node) do |child|
+          next unless child.is_a?(Prism::LocalVariableWriteNode)
+          next unless child.name == name
+          next unless child.location.start_line < matcher_line
+
+          candidates << child
+        end
+        candidates.max_by { |c| c.location.start_line }
+      end
+
+      def walk(node, &block)
+        return unless node.is_a?(Prism::Node)
+
+        node.child_nodes.each do |child|
+          next if child.nil?
+
+          yield child
+          walk(child, &block)
+        end
+      end
+
+      def heredoc_opening?(opening)
+        opening&.start_with?("<<")
+      end
+
+      def heredoc_style(opening)
+        case opening
+        when /\A<<~/ then :squiggly
+        when /\A<<-/ then :dash
+        else :strict
+        end
+      end
+
+      def build_heredoc_spec(node, opening)
+        content_loc = node.content_loc
+        closing_loc = node.closing_loc
+        style = heredoc_style(opening)
+        terminator_indent = closing_loc.start_column
+
+        HeredocTarget.new(
+          spec_path: @spec_path,
+          source: @source,
+          style: style,
+          content_start_offset: content_loc.start_offset,
+          content_end_offset: content_loc.end_offset,
+          terminator_indent: terminator_indent,
+        )
+      end
+    end
+  end
+end

data/lib/canon/rebaseliner/heredoc_rewriter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Canon
+  module Rebaseliner
+    # Replace a heredoc's body in a spec file with new content, preserving
+    # the heredoc's opening style (`<<~` re-indented, `<<-`/`<<` verbatim).
+    module HeredocRewriter
+      module_function
+
+      # @param spec [HeredocTarget] description of the heredoc to rewrite
+      # @param new_body [String] new heredoc body (pretty-printed actual);
+      #   may or may not have a trailing newline; the rewriter normalises.
+      # @return [void]
+      def rewrite!(spec, new_body)
+        body = format_body(new_body, spec.style, spec.terminator_indent)
+        new_source = spec.source.byteslice(0, spec.content_start_offset) +
+          body +
+          spec.source.byteslice(spec.content_end_offset..-1)
+        AtomicWriter.write(spec.spec_path, new_source)
+      end
+
+      # Format the new body to fit the heredoc style.
+      # - `:squiggly` (`<<~`): re-indent each line to the terminator column.
+      # - `:dash` / `:strict`: write verbatim (the original code is
+      #   indentation-sensitive, leave it alone).
+      # Always ensures a single trailing newline before the terminator line.
+      def format_body(new_body, style, terminator_indent)
+        normalised = new_body.dup
+        normalised << "\n" unless normalised.end_with?("\n")
+
+        case style
+        when :squiggly
+          indent = " " * (terminator_indent || 0)
+          stripped = strip_common_leading_whitespace(normalised)
+          stripped.lines.map { |line| line == "\n" ? line : "#{indent}#{line}" }.join
+        else
+          normalised
+        end
+      end
+
+      # Remove the largest common leading-whitespace prefix from a multi-line
+      # string, mirroring `<<~`'s own behaviour. Blank lines don't constrain
+      # the prefix.
+      def strip_common_leading_whitespace(text)
+        lines = text.lines
+        leading = lines
+          .reject { |l| l.chomp.empty? }
+          .map { |l| l[/\A[ \t]*/].length }
+          .min || 0
+        return text if leading.zero?
+
+        lines.map { |l| l.chomp.empty? ? l : l[leading..] }.join
+      end
+    end
+  end
+end

data/lib/canon/rebaseliner/heredoc_target.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Canon
+  module Rebaseliner
+    # Data struct describing a heredoc literal located in a spec file:
+    # where its body lives in the source (byte range), what style of heredoc
+    # delimiter opens it (`<<~`, `<<-`, `<<`), and what indent the
+    # terminator sits at (used by `<<~` re-indenting).
+    HeredocTarget = Struct.new(
+      :spec_path,           # absolute path
+      :source,              # full file source string (UTF-8)
+      :style,               # :squiggly (<<~) | :dash (<<-) | :strict (<<)
+      :content_start_offset, # byte offset where body starts (after opening line's \n)
+      :content_end_offset,   # byte offset where body ends (just before terminator line)
+      :terminator_indent,    # integer column of the terminator (relevant for :squiggly)
+      keyword_init: true,
+    )
+  end
+end

data/lib/canon/rebaseliner/logger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Canon
+  module Rebaseliner
+    # Single-line stderr writes prefixed with `[canon:rebaseline]`. CI- and
+    # grep-friendly. No color, no buffering.
+    module Logger
+      PREFIX = "[canon:rebaseline]"
+
+      module_function
+
+      # @param status [Symbol] :rewritten / :skipped_* / :error
+      # @param spec_path [String]
+      # @param line [Integer]
+      # @param detail [String, nil] short reason or contextual note
+      # @return [void]
+      def log(status, spec_path:, line:, detail: nil)
+        location = "#{spec_path}:#{line}"
+        suffix = detail ? " (#{detail})" : ""
+        warn "#{PREFIX} #{status} #{location}#{suffix}"
+      end
+    end
+  end
+end

data/lib/canon/rebaseliner.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Canon
+  # In-place rebaselining of `be_*_equivalent_to` heredoc expectations.
+  #
+  # Opt-in via `CANON_REGENERATE_EXPECTED=true`. When set, a failing
+  # matcher assertion has its expected heredoc body replaced with the
+  # prettyprinted received value, and the assertion is reported as
+  # passing for the run. Default OFF; passing assertions are never
+  # touched.
+  #
+  # See docs/features/regenerate-expected.adoc for the supported
+  # expected-argument forms and the recommended workflow.
+  module Rebaseliner
+    autoload :AtomicWriter, "canon/rebaseliner/atomic_writer"
+    autoload :Logger, "canon/rebaseliner/logger"
+    autoload :HeredocTarget, "canon/rebaseliner/heredoc_target"
+    autoload :HeredocRewriter, "canon/rebaseliner/heredoc_rewriter"
+    autoload :HeredocLocator, "canon/rebaseliner/heredoc_locator"
+    autoload :CallSiteResolver, "canon/rebaseliner/call_site_resolver"
+    ENV_VAR = "CANON_REGENERATE_EXPECTED"
+
+    # @return [Boolean] true when the env var is set to a truthy value.
+    #   Memoised per process.
+    def self.enabled?
+      return @enabled if defined?(@enabled)
+
+      @enabled = case ENV.fetch(ENV_VAR, "").to_s.downcase
+                 when "1", "true", "yes", "on" then true
+                 else false
+                 end
+    end
+
+    # Reset memoisation; used by tests.
+    def self.reset!
+      remove_instance_variable(:@enabled) if defined?(@enabled)
+      @line_shifts = nil
+    end
+
+    # Per-file cumulative line-shift tracking. After a rewrite, the file
+    # on disk has different line numbering, but Ruby's caller_locations
+    # still reports the ORIGINAL line numbers (the in-memory source).
+    # For each spec_path we accumulate (threshold_line, delta) tuples,
+    # and use them to translate an original line number to its current
+    # post-rewrite line.
+    def self.line_shifts
+      @line_shifts ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Translate an original caller line to the current line in the file,
+    # given accumulated shifts.
+    def self.shifted_line(spec_path, original_line)
+      shifts = line_shifts[spec_path]
+      shifts.inject(original_line) do |line, (threshold, delta)|
+        original_line > threshold ? line + delta : line
+      end
+    end
+
+    # Record a line shift caused by a rewrite. `threshold` is the original
+    # source line where the rewrite began; any subsequent line in the
+    # original source after that threshold is offset by `delta`.
+    def self.record_shift(spec_path, threshold, delta)
+      line_shifts[spec_path] << [threshold, delta]
+    end
+
+    # Attempt to rewrite the heredoc that backs a failing assertion.
+    #
+    # @param spec_path [String] absolute path of the spec file containing
+    #   the matcher invocation
+    # @param line [Integer] 1-indexed line of the matcher invocation
+    # @param prettyprinted_actual [String] new body content
+    # @return [Symbol] :rewritten, :skipped_inline_string,
+    #   :skipped_interpolation, :skipped_method_call,
+    #   :skipped_cross_file, :skipped_unresolved, or :error
+    def self.rewrite!(spec_path:, line:, prettyprinted_actual:)
+      # Translate the caller-reported original line to its current
+      # position in the on-disk file, accounting for any previous
+      # rewrites that shifted subsequent lines.
+      effective_line = shifted_line(spec_path, line)
+      call_site = CallSiteResolver.resolve(spec_path: spec_path,
+                                           line: effective_line)
+      unless call_site
+        Logger.log(:skipped_unresolved, spec_path: spec_path, line: line,
+                                        detail: "no matcher call at line")
+        return :skipped_unresolved
+      end
+
+      locator = HeredocLocator.new(
+        spec_path: spec_path,
+        source: call_site.source,
+        enclosing_block: call_site.enclosing_block,
+        expected_node: call_site.expected_node,
+        matcher_line: call_site.matcher_line,
+      )
+      result = locator.resolve
+      unless result.rewritable?
+        Logger.log(result.status, spec_path: spec_path, line: line)
+        return result.status
+      end
+
+      old_line_count = line_count_in_range(call_site.source,
+                                           result.heredoc_spec)
+      HeredocRewriter.rewrite!(result.heredoc_spec, prettyprinted_actual)
+      count_newlines(File.read(spec_path)
+        .byteslice(result.heredoc_spec.content_start_offset,
+                   File.size(spec_path) -
+                   result.heredoc_spec.content_start_offset))
+      # Compute shift simply by re-reading the file size delta in lines.
+      record_shift_from_disk(spec_path, call_site, result.heredoc_spec,
+                             old_line_count)
+      Logger.log(:rewritten, spec_path: spec_path, line: line)
+      :rewritten
+    rescue StandardError => e
+      Logger.log(:error, spec_path: spec_path, line: line,
+                         detail: "#{e.class}: #{e.message}")
+      :error
+    end
+
+    # Count newlines in the original heredoc body (between content_start
+    # and content_end byte offsets) and in the rewritten file's same
+    # logical range; the difference is the line shift to record. We
+    # threshold the shift on the line where the heredoc opened, so that
+    # only lines AFTER the rewrite point are adjusted.
+    def self.line_count_in_range(source, heredoc_spec)
+      body = source.byteslice(heredoc_spec.content_start_offset,
+                              heredoc_spec.content_end_offset -
+                              heredoc_spec.content_start_offset)
+      count_newlines(body.to_s)
+    end
+
+    def self.count_newlines(str)
+      str.count("\n")
+    end
+
+    def self.record_shift_from_disk(spec_path, call_site, heredoc_spec,
+                                    old_line_count)
+      new_source = File.read(spec_path)
+      # The new body lives at the same content_start_offset (since the
+      # offset is computed pre-rewrite from the pre-rewrite source). We
+      # need to find where the heredoc body ends in the new source. The
+      # closing terminator is unchanged textually, so we can search for
+      # the next occurrence of the closing line from the start offset.
+      pre = new_source.byteslice(0, heredoc_spec.content_start_offset)
+      remainder = new_source.byteslice(heredoc_spec.content_start_offset..-1)
+      # Find the closing terminator: same text as in the original source.
+      original_close = call_site.source.byteslice(
+        heredoc_spec.content_end_offset,
+        call_site.source.bytesize - heredoc_spec.content_end_offset,
+      ).lines.first.to_s
+      close_idx = remainder.index(original_close)
+      return unless close_idx
+
+      new_body = remainder.byteslice(0, close_idx)
+      new_line_count = count_newlines(new_body)
+      delta = new_line_count - old_line_count
+      return if delta.zero?
+
+      threshold = pre.count("\n")
+      record_shift(spec_path, threshold, delta)
+    end
+  end
+end