canon 0.3.27 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8de5d7008a348037ef44fdd8bd5ee722e8077e058ab1e53cd2995b0dd5f0e2c
-  data.tar.gz: 930b0efd7c7302968a6ff2f4fd9af8a6261a1a57fc71707d9206333a380f47a8
+  metadata.gz: 6aef461e6f80457ad8fd6c227effe22086b5692f2cfcec5f4226ab0268e4956d
+  data.tar.gz: da2c4ae39e5c8a3483c811fe9bd19c49d69542b637fd97e4b62a2d20fda8bc08
 SHA512:
-  metadata.gz: 570bd7072c65d9c87316becd43334255bb176ee4260c1d40738cd51ee3d030c4ea3df9d93e923a2f6062c493271fb122bb252e1f41c6c0e40836d7fbe675fd5b
-  data.tar.gz: a7d60c235f74cdf466a35b4ef6204c9943d306a1167dead26123314326936f90f7d96a5d2ee3bd2ace308556655c2e6492d2beb2ebab25933d4ce796dfd84e9f
+  metadata.gz: 8cd8327564623711f977aec6b31943433ab962bdec534b2ac107f0eb7ead31cb0854551f3ef614ae1f2e2cdd059b5ac6b3655b44e7cc0dd82d34cff0a2c4b045
+  data.tar.gz: fcaac6df39848f1fd387710e57de61533dac6543028f412b08bd36d9615157a8252a81b13f015606ce666da31d02a5eeea0896abfadafdca6543dc92ac4977c6

data/.rubocop.yml

@@ -17,3 +17,5 @@ plugins:
 
 AllCops:
   TargetRubyVersion: 3.0
+  Exclude:
+    - "spec/fixtures/**/*"

data/README.adoc

@@ -189,6 +189,9 @@ $ canon help
 * **link:docs/CHARACTER_VISUALIZATION[Character visualization]** -
   Whitespace and special characters
 * **link:docs/INPUT_VALIDATION[Input validation]** - Error handling
+* **link:docs/features/regenerate-expected[Regenerating expected heredocs]** -
+  `CANON_REGENERATE_EXPECTED=true` to rewrite failing `be_*_equivalent_to`
+  heredocs in-place from the prettyprinted received value
 
 === Advanced topics
 

data/docs/features/regenerate-expected.adoc

@@ -0,0 +1,157 @@
+---
+title: Regenerating expected heredocs
+parent: Features
+nav_order: 50
+---
+= Regenerating expected heredocs
+:toc:
+:toclevels: 3
+
+== Purpose
+
+When a Canon matcher (`be_xml_equivalent_to`, `be_html_equivalent_to`, etc.)
+asserts equivalence against a heredoc-literal `expected`, and the
+upstream code legitimately changes its output, the fixture heredoc
+needs to be updated to the new value. The default workflow is:
+
+1. Run `bundle exec rspec` — see N failing assertions.
+2. Copy the prettyprinted received from canon's diff display.
+3. Paste into the `<<~XML ... XML` heredoc in the spec file.
+4. Re-run, iterate.
+
+For large fixture suites (e.g. the metanorma stack — 200+ heredocs per
+rebaseline event) this is slow and error-prone (indent drift, partial
+copies, missed trailing whitespace).
+
+The `CANON_REGENERATE_EXPECTED=true` env var collapses steps 2-3 into
+an automated rewrite.
+
+== Workflow
+
+[source,sh]
+----
+CANON_REGENERATE_EXPECTED=true bundle exec rspec
+git diff           # review what changed
+git commit -am "rebaseline fixtures after upstream X change"
+----
+
+When the env var is set:
+
+* Every failing `be_*_equivalent_to` assertion attempts to rewrite the
+  source heredoc that backs its `expected` argument.
+* The rewrite uses the same `Canon::PrettyPrinter` that powers
+  `CANON_<FORMAT>_DIFF_SHOW_PRETTYPRINT_RECEIVED` — output is identical
+  to what would have appeared in the diff display.
+* Successful rewrites mark the assertion as passing for the run, so CI
+  does not fail mid-rebaseline.
+* Passing assertions are never touched.
+* Negated matchers (`.not_to`) are never rewritten.
+
+Each rewrite (or skip) emits a single-line log to stderr:
+
+[source]
+----
+[canon:rebaseline] rewritten /path/to/spec.rb:123
+[canon:rebaseline] skipped_interpolation /path/to/spec.rb:456
+----
+
+== Supported expected forms (v1)
+
+The rebaseliner uses Prism to parse the caller spec file and locate the
+heredoc backing the `expected` argument. It supports:
+
+* `<<~XML` / `<<-XML` / `<<XML` heredoc assigned to a local variable in
+  the same `it` block.
+* `<<~XML` / `<<-XML` / `<<XML` heredoc passed inline directly to the
+  matcher.
+* *Multiple sequential assignments* to the same local variable within
+  one `it` block (the common metanorma pattern of reassigning `output`
+  before each format-specific expect). The rebaseliner walks backward
+  from the failing `expect` line to the *most-recent* assignment and
+  rewrites that one.
+* Substitution chains on the actual side (e.g.
+  `expect(strip_guid(actual).gsub(...))`) — since the matcher receives
+  the post-substitution value, idempotency holds on the next run.
+
+== Skipped with a warning (v1)
+
+* Heredoc with `#{}` interpolation. Mechanical rewriting would lose
+  the interpolation; v2 (token preservation) is planned.
+* Expected value from a method call (`load_fixture(...)`). The
+  expected is computed at runtime; the rebaseliner cannot identify
+  which on-disk fixture to rewrite.
+* Expected value from a `let` or `shared_context` in a different
+  spec/support file. v1 does not cross file boundaries.
+* Inline string literal expected (no heredoc). There is nothing to
+  re-indent into.
+
+In each skipped case the file is left unchanged and the assertion
+fails normally with the standard Canon diff display.
+
+== Tracking line shifts across multiple rewrites
+
+After a rewrite, the file's on-disk line numbering can shift if the new
+heredoc body has a different line count from the old. Ruby's
+`caller_locations` continues to report the *original* line numbers
+during the same process run (the in-memory source is unchanged), so
+the rebaseliner maintains a per-file cumulative line-shift tracker and
+translates subsequent caller-reported lines accordingly. Multiple
+rewrites within a single `it` block, or across multiple `it` blocks
+in the same spec file, work transparently.
+
+== Limitations and v2 roadmap
+
+The following are intentionally out of v1 scope:
+
+* `#{}` interpolation in heredoc bodies — v2 adds token-preserving
+  rewrites that re-anchor `#{var}` fragments in the prettyprinted
+  actual.
+* JSON and YAML format prettyprinter wiring (v1 covers XML + HTML).
+* A `canon regenerate SPEC_GLOB` Thor subcommand with a summary
+  report.
+* File-locking for `parallel_rspec` safety. v1 documents "do not run
+  rebaseline mode in parallel."
+* Optional `rubocop -A` post-rewrite formatter.
+
+== Architecture
+
+The rebaseliner is a self-contained module under
+`lib/canon/rebaseliner/`:
+
+`Canon::Rebaseliner`::
+  Top-level orchestrator. `enabled?` reads the env var.
+  `rewrite!` is the entry called by the matcher hook on failure.
+
+`CallSiteResolver`::
+  Parses the spec file with Prism and locates the matcher invocation
+  on the failing line. Returns the AST node passed as `expected` and
+  the enclosing `it`/`example` block.
+
+`HeredocLocator`::
+  Classifies the `expected` AST node. For local-variable references,
+  walks the enclosing block backward to find the most-recent
+  assignment. Returns a `HeredocSpec` describing the byte range to
+  rewrite, or a skip reason.
+
+`HeredocRewriter`::
+  Re-indents the new body for `<<~` (squiggly) heredocs and writes the
+  new source via `AtomicWriter`.
+
+`AtomicWriter`::
+  Tempfile-then-rename to avoid half-written files on Ctrl-C.
+
+`Logger`::
+  Single-line stderr writes with the `[canon:rebaseline]` prefix.
+
+The matcher hook lives in `lib/canon/rspec_matchers.rb`. It captures
+`caller_locations` only when the env var is set, so passing
+assertions pay no overhead.
+
+== Testing the rebaseliner
+
+`spec/canon/rebaseliner_spec.rb` runs each fixture under
+`spec/fixtures/rebaseliner/` in a subprocess with the env var set,
+then asserts the file content was (or was not) modified appropriately
+and that the stderr log line is present. Add new fixture cases by
+dropping `*_input.rb` into `spec/fixtures/rebaseliner/` and a new
+example into `rebaseliner_spec.rb`.

data/lib/canon/comparison/diff_node_builder.rb

@@ -179,6 +179,15 @@ module Canon
           return "whitespace: #{describe_whitespace(text1)} vs #{describe_whitespace(text2)}"
         end
 
+        # Identical content modulo whitespace: two full visualized
+        # copies read as materially different text when the only
+        # delta is trailing/invisible whitespace (#94) — the compact
+        # character-count description says what actually differs.
+        if text1.strip == text2.strip
+          return "whitespace-only: #{describe_whitespace(text1)} vs " \
+                 "#{describe_whitespace(text2)}"
+        end
+
         "Text: \"#{visualize_whitespace(text1)}\" vs \"#{visualize_whitespace(text2)}\""
       end
 

data/lib/canon/config/env_schema.rb

@@ -21,6 +21,12 @@ module Canon
 
       FORMAT_ATTRIBUTE_TYPES = {
         preprocessing: :string,
+
+        # Rebaseliner: opt-in mode that rewrites failing heredoc
+        # expectations in spec files with the prettyprinted received
+        # value. Read directly by Canon::Rebaseliner.enabled?; schema
+        # entry exists for --env-help discoverability.
+        regenerate_expected: :boolean,
       }.freeze
 
       class << self

data/lib/canon/rebaseliner/atomic_writer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "fileutils"
+
+module Canon
+  module Rebaseliner
+    # Write a file atomically by writing to a same-directory tempfile and
+    # renaming over the target. Preserves the original file's mode. Avoids
+    # half-written files on Ctrl-C.
+    module AtomicWriter
+      module_function
+
+      # @param path [String] absolute path to write
+      # @param contents [String] new file contents
+      # @return [void]
+      def write(path, contents)
+        original_mode = File.stat(path).mode
+        dir = File.dirname(path)
+        Tempfile.create(["canon-rebaseline", ".tmp"], dir) do |tmp|
+          tmp.binmode
+          tmp.write(contents)
+          tmp.flush
+          tmp.fsync
+          tmp.close
+          File.chmod(original_mode, tmp.path)
+          File.rename(tmp.path, path)
+        end
+      end
+    end
+  end
+end

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

data/lib/canon/rspec_matchers.rb

@@ -4,6 +4,9 @@ require "canon" unless defined?(Canon)
 require "canon/comparison"
 require "canon/diff_formatter"
 require "canon/config"
+require "canon/rebaseliner"
+require "canon/pretty_printer/xml"
+require "canon/pretty_printer/html"
 
 begin
   require "rspec/expectations"
@@ -88,60 +91,135 @@ module Canon
       end
 
       def matches?(target)
+        # Capture caller_locations only when rebaseliner is enabled so that
+        # passing assertions don't pay for stack walking.
+        @rebaseliner_caller = caller_locations(1, 12) if Canon::Rebaseliner.enabled?
+        equivalent = compute_equivalent(target)
+        return true if equivalent
+
+        attempt_rebaseline
+      end
+
+      # Skip the rebaseliner path for `.not_to`. RSpec invokes
+      # `does_not_match?` if defined, instead of negating `matches?`.
+      def does_not_match?(target)
+        !compute_equivalent(target)
+      end
+
+      def failure_message
+        "expected #{format_name} to be equivalent\n\n#{diff_output}"
+      end
+
+      def failure_message_when_negated
+        "expected #{format_name} not to be equivalent"
+      end
+
+      def expected
+        @expected
+      end
+
+      def actual
+        @target
+      end
+
+      def diffable # rubocop:disable Naming/PredicateMethod
+        false
+      end
+
+      private
+
+      # Run the actual comparison and set @target / @comparison_result.
+      # Returns the boolean equivalence result.
+      def compute_equivalent(target)
         @target = target
 
-        # Build comparison options from config and matcher params
         opts = build_comparison_options
-
-        # Add format hint if explicitly provided
         opts[:format] = @format if @format
 
-        # Delegate to Canon::Comparison.equivalent? - the SINGLE source of truth
-        # Comparison handles format detection, HTML parsing, and all business logic
         @comparison_result = Canon::Comparison.equivalent?(
           @expected,
           @target,
           opts,
         )
 
-        # When verbose: true, result is a ComparisonResult object
-        # Use the equivalent? method to check for normative differences
         case @comparison_result
         when Canon::Comparison::ComparisonResult
           @comparison_result.equivalent?
         when Hash
-          # Legacy format - Hash with :differences array and :preprocessed strings
           @comparison_result[:differences].empty?
         when Array
-          # Legacy format - XML/JSON/YAML returns []
           @comparison_result.empty?
         else
-          # Boolean result
           @comparison_result
         end
       end
 
-      def failure_message
-        "expected #{format_name} to be equivalent\n\n#{diff_output}"
-      end
+      # When the rebaseliner env var is on and the comparison failed, try to
+      # rewrite the heredoc that backs the expected value. Returns `true` to
+      # the matcher (so the assertion is treated as passing) when a rewrite
+      # succeeded; otherwise `false` so the normal failure path runs.
+      def attempt_rebaseline
+        return false unless Canon::Rebaseliner.enabled?
+        return false unless @rebaseliner_caller
 
-      def failure_message_when_negated
-        "expected #{format_name} not to be equivalent"
-      end
+        frame = first_user_frame(@rebaseliner_caller)
+        return false unless frame
 
-      def expected
-        @expected
+        prettyprinted = pretty_print_actual
+        return false unless prettyprinted
+
+        status = Canon::Rebaseliner.rewrite!(
+          spec_path: frame.absolute_path || frame.path,
+          line: frame.lineno,
+          prettyprinted_actual: prettyprinted,
+        )
+        status == :rewritten
+      rescue StandardError => e
+        Canon::Rebaseliner::Logger.log(
+          :error,
+          spec_path: frame&.path.to_s,
+          line: frame&.lineno.to_i,
+          detail: "#{e.class}: #{e.message}",
+        )
+        false
       end
 
-      def actual
-        @target
+      # Drop frames inside RSpec internals and canon itself; the first
+      # remaining is the user's spec file.
+      def first_user_frame(locations)
+        locations.find do |loc|
+          path = loc.absolute_path || loc.path
+          next false unless path
+          next false if %r{/gems/rspec-(expectations|core|mocks|support)-}.match?(path)
+          next false if %r{/lib/rspec/(expectations|core|mocks|support)/}.match?(path)
+          next false if path.include?("/canon/lib/canon/")
+          next false if path.end_with?("/lib/canon/rspec_matchers.rb")
+
+          true
+        end
       end
 
-      def diffable # rubocop:disable Naming/PredicateMethod
-        false
+      # Format the actual value with the appropriate pretty-printer for the
+      # heredoc rewrite. Returns nil when no prettyprinter is wired (e.g.
+      # JSON/YAML in v1).
+      def pretty_print_actual
+        fmt = @format || detect_format
+        case fmt
+        when :xml
+          Canon::PrettyPrinter::Xml.new.format(@target.to_s)
+        when :html, :html4, :html5
+          # fixture_ready: true emits actually-indented XHTML-shaped
+          # output suitable for direct paste into a heredoc.
+          Canon::PrettyPrinter::Html.new(fixture_ready: true)
+            .format(@target.to_s)
+        end
       end
 
-      private
+      def detect_format
+        Canon::Comparison::FormatDetector.detect(@expected)
+      rescue StandardError
+        nil
+      end
 
       def format_name
         # Use explicitly provided format if available

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.27"
+  VERSION = "0.3.28"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.27
+  version: 0.3.28
 platform: ruby
 authors:
 - Ribose Inc.
@@ -187,6 +187,7 @@ files:
 - docs/features/match-options/index.adoc
 - docs/features/match-options/pretty-printed-fixtures.adoc
 - docs/features/performance.adoc
+- docs/features/regenerate-expected.adoc
 - docs/getting-started/index.adoc
 - docs/getting-started/quick-start.adoc
 - docs/guides/choosing-configuration.adoc
@@ -342,6 +343,13 @@ files:
 - lib/canon/pretty_printer/json.rb
 - lib/canon/pretty_printer/xml.rb
 - lib/canon/pretty_printer/xml_normalized.rb
+- lib/canon/rebaseliner.rb
+- lib/canon/rebaseliner/atomic_writer.rb
+- lib/canon/rebaseliner/call_site_resolver.rb
+- lib/canon/rebaseliner/heredoc_locator.rb
+- lib/canon/rebaseliner/heredoc_rewriter.rb
+- lib/canon/rebaseliner/heredoc_target.rb
+- lib/canon/rebaseliner/logger.rb
 - lib/canon/rspec_matchers.rb
 - lib/canon/tree_diff.rb
 - lib/canon/tree_diff/adapters.rb