canon 0.3.26 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '05685ad043ad0a5465f4e065c26cf35ad1b453511ce347a56e60d5a5153e731f'
-  data.tar.gz: 864587a2ddf54edd3f40d71676882b255904dfe6f46ee41a330ef8117ceddfed
+  metadata.gz: 6aef461e6f80457ad8fd6c227effe22086b5692f2cfcec5f4226ab0268e4956d
+  data.tar.gz: da2c4ae39e5c8a3483c811fe9bd19c49d69542b637fd97e4b62a2d20fda8bc08
 SHA512:
-  metadata.gz: 6e568174aeaf605650e7eb64267afddbe30fd4399b82c032757e60177631b75663b0cf388d16e2fbaddea774ea703cb4c88f3e11ac8307ee1a75a3ea6f6530cc
-  data.tar.gz: 5af9aded692f6b909ffd1eb50bb9e96c851b8ca98844a397ceec11f8a2eede33437f99d4df15a2870beee56954924d2fd1ec061b6cb4523d2204fa07524f0710
+  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

@@ -12,9 +12,19 @@ Key features:
 
 * **Format support**: XML, HTML, JSON, YAML
 * **Canonicalization**: W3C XML C14N 1.1, sorted JSON/YAML keys
-* **Semantic comparison**: Compare meaning, not formatting
+* **Semantic comparison**: Compare meaning, not formatting — attributes by
+  expanded name (namespace URI + local name), prefixes never affect results
 * **Multiple interfaces**: Ruby API, CLI, RSpec matchers
 * **Smart diff output**: By-line or by-object modes with syntax highlighting
+* **Fast native engines, zero mandatory C deps**:
+** XML on https://github.com/leptris/leptris[libleptris] (via moxml) whenever
+   installed — Nokogiri otherwise and for HTML; both byte-compatible, engine
+   parity is spec-gated
+** JSON on https://github.com/leptris/yeptris[libyeptris]' strict JSON surface
+   whenever the native materializer is installed (`gem install yeptris` —
+   platform gems, zero compilation), the stdlib JSON extension otherwise
+** YAML on yeptris opt-in (`CANON_YAML_BACKEND=yeptris`, ~3x Psych loads);
+   Psych otherwise
 
 == When to use formatting vs comparison
 
@@ -179,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
 
@@ -957,10 +970,25 @@ bundle exec rake performance:yaml
 * **XML/HTML Comparison**: Identical, similar, different documents
 * **Format Canonicalization**: XML C14N, JSON, YAML
 
+=== Engines
+
+Canon is engine-agnostic across its formats:
+
+* **XML**: libleptris via moxml whenever installed (parse, comparison, C14N,
+  pretty-printing); raw Nokogiri otherwise, and always Nokogiri for HTML.
+  `CANON_XML_BACKEND=nokogiri|moxml` forces either engine; parity between the
+  two is spec-gated (`spec/canon/xml/engine_parity_spec.rb`).
+* **JSON**: yeptris' strict JSON surface when the native materializer is
+  installed (platform gems — zero compilation), the stdlib JSON extension
+  otherwise. `CANON_YAML_BACKEND=psych` forces stdlib.
+* **YAML**: Psych by default; yeptris (≈3x loads) behind
+  `CANON_YAML_BACKEND=yeptris`. Parity is spec-gated
+  (`spec/canon/yaml_engine_parity_spec.rb`).
+
 === SAX Parser
 
 Canon includes a SAX-based XML parser (`Canon::Xml::SaxBuilder`) that provides
-significantly faster XML parsing by avoiding intermediate Nokogiri DOM trees.
+significantly faster XML parsing by avoiding intermediate engine DOM trees.
 
 [source,ruby]
 ----

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/comparison/xml_comparator/attribute_filter.rb

@@ -34,14 +34,24 @@ module Canon
         # @param filtered [Hash] Output hash to populate
         def self.filter_array_attributes(attributes, opts, match_opts, filtered)
           attributes.each do |attr|
-            name = attr.name
+            # Expanded name (XML Namespaces 1.0 §5.2/§5.3): an
+            # unprefixed attribute is in NO namespace — {no-ns}srsName
+            # and {uri}srsName are different attributes, and two
+            # prefixes bound to the same URI are the same attribute.
+            # Local-name keys conflated qualified with unqualified
+            # attributes whenever the prefix matched the element's
+            # (issue #155).
+            name = expanded_attribute_name(attr)
             value = attr.value
 
             # Skip namespace declarations - they're handled separately
-            next if namespace_declaration?(name)
+            next if namespace_declaration?(attr.name)
 
-            # Skip if attribute name should be ignored
-            next if ignore_by_name?(name, opts)
+            # Skip if attribute name should be ignored — by local name
+            # (user-facing list) or expanded key, so ignore lists keep
+            # working against both forms.
+            next if ignore_by_name?(attr.name, opts) ||
+              ignore_by_name?(name, opts)
 
             # Skip if attribute content should be ignored
             next if ignore_by_content?(value, opts)
@@ -54,6 +64,26 @@ module Canon
           end
         end
 
+        # Expanded attribute key: "{namespace-uri}local-name", or the
+        # bare local name when the attribute is in no namespace.
+        # Prefixed-but-unresolvable attributes (namespace-invalid
+        # documents — an undeclared prefix has no expanded name) fall
+        # back to the local name: recovery comparison cannot do better.
+        def self.expanded_attribute_name(attr)
+          case attr
+          when Canon::Xml::Nodes::AttributeNode
+            uri = attr.namespace_uri
+            attr.prefix
+          when defined?(Nokogiri) && Nokogiri::XML::Attr
+            uri = attr.namespace&.href
+            attr.namespace&.prefix
+          else
+            uri = attr.namespace_uri
+            nil
+          end
+          uri && !uri.empty? ? "{#{uri}}#{attr.name}" : attr.name
+        end
+
         # Filter hash-format attributes (Nokogiri/Moxml)
         #
         # @param attributes [Hash] Hash-like attributes

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/diff_formatter/by_line/html_formatter.rb

@@ -33,82 +33,11 @@ module Canon
         # @return [String] Formatted diff
         def format(doc1, doc2)
           compute_line_num_width(doc1, doc2)
-          # If we have DiffNodes from comparison, use the new pipeline
-          if @differences&.any?(Canon::Diff::DiffNode)
-            # Check if we should skip based on show_diffs setting
-            if should_skip_diff_display?
-              return ""
-            end
-
-            # Use new pipeline when DiffNodes available
-            return format_with_pipeline(doc1, doc2)
-          end
-
-          # LEGACY: Fall back to old DOM-based behavior
-          # Check if we should show any diffs based on differences array
-          if should_skip_diff_display?
-            return ""
-          end
-
-          output = []
-
-          begin
-            # Parse to DOM using HTML parser
-            root1 = Canon::Html::DataModel.from_html(doc1,
-                                                     version: @html_version)
-            root2 = Canon::Html::DataModel.from_html(doc2,
-                                                     version: @html_version)
-
-            # Match elements semantically
-            matcher = Canon::Xml::ElementMatcher.new
-            matches = matcher.match_trees(root1, root2)
-
-            # Pretty-print HTML for line mapping
-            pretty_printer = Canon::PrettyPrinter::Html.new(indent: 2)
-            pretty1 = pretty_printer.format(doc1)
-            pretty2 = pretty_printer.format(doc2)
-
-            # Build line range maps using pretty-printed documents
-            mapper1 = Canon::Xml::LineRangeMapper.new(indent: 2)
-            mapper2 = Canon::Xml::LineRangeMapper.new(indent: 2)
-            map1 = mapper1.build_map(root1, pretty1)
-            map2 = mapper2.build_map(root2, pretty2)
-
-            # Use pretty-printed document lines for display
-            lines1 = pretty1.split("\n")
-            lines2 = pretty2.split("\n")
-
-            # Display diffs based on element matches
-            result = format_element_matches(matches, map1, map2, lines1, lines2)
-            output << result
-          rescue StandardError => e
-            # Fall back to simple diff on error
-            output << colorize("Warning: DOM parsing failed, using simple diff",
-                               :yellow)
-            output << colorize("Error: #{e.class}: #{e.message}", :red)
+          return "" if should_skip_diff_display?
 
-            # Include relevant backtrace lines
-            relevant_trace = e.backtrace.select do |line|
-              line.include?("canon")
-            end.take(3)
-            unless relevant_trace.empty?
-              output << colorize("Backtrace:", :yellow)
-              relevant_trace.each do |line|
-                output << colorize("  #{line}", :yellow)
-              end
-            end
-
-            output << ""
-            simple = SimpleFormatter.new(
-              use_color: @use_color,
-              context_lines: @context_lines,
-              diff_grouping_lines: @diff_grouping_lines,
-              visualization_map: @visualization_map,
-            )
-            output << simple.format(doc1, doc2)
-          end
-
-          output.join("\n")
+          # The DiffNode pipeline is the only renderer: without
+          # DiffNodes there is nothing to report (#84).
+          format_with_pipeline(doc1, doc2)
         end
 
         # Format using new DiffReportBuilder pipeline
@@ -260,227 +189,6 @@ module Canon
 
           output.join("\n")
         end
-
-        private
-
-        # Format element matches for display
-        def format_element_matches(matches, map1, map2, lines1, lines2)
-          output = []
-
-          # Detect non-ASCII characters in the diff
-          all_text = (lines1 + lines2).join
-          non_ascii = Legend.detect_non_ascii(all_text, @visualization_map)
-
-          # Add Unicode legend if any non-ASCII characters detected
-          unless non_ascii.empty?
-            output << Legend.build_legend(non_ascii, use_color: @use_color)
-            output << ""
-          end
-
-          # Build a set of elements to skip (children of parents showing diffs)
-          elements_to_skip = build_skip_set(matches, map1, map2, lines1,
-                                            lines2)
-
-          # Build a set of children of matched parents
-          children_of_matched_parents = build_children_set(matches)
-
-          # Collect diff sections with metadata
-          diff_sections = collect_diff_sections(matches, map1, map2, lines1,
-                                                lines2, elements_to_skip,
-                                                children_of_matched_parents)
-
-          # Sort by line number
-          diff_sections.sort_by! do |section|
-            section[:start_line1] || section[:start_line2] || 0
-          end
-
-          # Group diffs by proximity if diff_grouping_lines is set
-          formatted_diffs = if @diff_grouping_lines
-                              groups = group_diff_sections(diff_sections,
-                                                           @diff_grouping_lines)
-                              format_diff_groups(groups)
-                            else
-                              diff_sections.filter_map do |s|
-                                s[:formatted]
-                              end.join("\n\n")
-                            end
-
-          output << formatted_diffs
-          output.join("\n")
-        end
-
-        # Build set of elements to skip (children with parents showing diffs)
-        def build_skip_set(matches, map1, map2, lines1, lines2)
-          elements_to_skip = Set.new
-          elements_with_diffs = Set.new
-
-          # Build set of element pairs that have semantic diffs
-          build_elements_with_semantic_diffs_set
-
-          # First pass: identify elements with line differences
-          # (semantic filtering happens in collect_diff_sections)
-          matches.each do |match|
-            next unless match.status == :matched
-
-            range1 = map1[match.elem1]
-            range2 = map2[match.elem2]
-            next unless range1 && range2
-
-            elem_lines1 = lines1[range1.start_line..range1.end_line]
-            elem_lines2 = lines2[range2.start_line..range2.end_line]
-
-            # Add if there are line diffs
-            # Semantic filtering is done in collect_diff_sections
-            if elem_lines1 != elem_lines2
-              elements_with_diffs.add(match.elem1)
-            end
-          end
-
-          # Second pass: skip children of elements with diffs
-          elements_with_diffs.each do |elem|
-            current = Canon::Comparison::NodeInspector.parent(elem)
-            while current
-              if Canon::Comparison::NodeInspector.element_node?(current) &&
-                  elements_with_diffs.include?(current)
-                elements_to_skip.add(elem)
-                break
-              end
-              current = Canon::Comparison::NodeInspector.parent(current)
-            end
-          end
-
-          elements_to_skip
-        end
-
-        # Collect diff sections with metadata
-        def collect_diff_sections(matches, map1, map2, lines1, lines2,
-                                   elements_to_skip, _children_of_matched_parents)
-          diff_sections = []
-          no_range_count = 0
-          no_diff_count = 0
-
-          # If there are NO semantic diffs, don't show any matched elements
-          # (all text diffs were normalized away)
-          elements_with_semantic_diffs = build_elements_with_semantic_diffs_set
-
-          matches.each do |match|
-            case match.status
-            when :matched
-              next if elements_to_skip.include?(match.elem1)
-
-              # Only apply semantic filtering if we have DiffNode objects
-              # (when called standalone or without DiffNodes, show all diffs)
-              if !@differences.nil? && !@differences.empty? && @differences.any?(Canon::Diff::DiffNode)
-                # Skip if no semantic diffs exist (all diffs were normalized)
-                next if elements_with_semantic_diffs.empty?
-
-                # Skip if this element has no semantic diffs in its subtree
-                next unless has_semantic_diff_in_subtree?(match.elem1,
-                                                          elements_with_semantic_diffs)
-              end
-
-              range1 = map1[match.elem1]
-              range2 = map2[match.elem2]
-              if !range1 || !range2
-                no_range_count += 1
-              end
-
-              section = format_matched_element_with_metadata(match, map1,
-                                                             map2, lines1,
-                                                             lines2)
-              if range1 && range2 && !section
-                no_diff_count += 1
-              end
-              diff_sections << section if section
-            when :deleted
-              # Don't skip deleted elements - they should always be shown
-              section = format_deleted_element_with_metadata(match, map1,
-                                                             lines1)
-              diff_sections << section if section
-            when :inserted
-              # Don't skip inserted elements - they should always be shown
-              section = format_inserted_element_with_metadata(match, map2,
-                                                              lines2)
-              diff_sections << section if section
-            end
-          end
-
-          diff_sections
-        end
-
-        # Format a matched element showing differences
-        def format_matched_element(match, map1, map2, lines1, lines2)
-          range1 = map1[match.elem1]
-          range2 = map2[match.elem2]
-          return nil unless range1 && range2
-
-          # Extract line ranges
-          elem_lines1 = lines1[range1.start_line..range1.end_line]
-          elem_lines2 = lines2[range2.start_line..range2.end_line]
-
-          # Skip if identical
-          return nil if elem_lines1 == elem_lines2
-
-          # Run line diff
-          diffs = ::Diff::LCS.sdiff(elem_lines1, elem_lines2)
-
-          # Identify diff blocks
-          diff_blocks = identify_diff_blocks(diffs)
-          return nil if diff_blocks.empty?
-
-          # Group into contexts
-          contexts = group_diff_blocks_into_contexts(diff_blocks,
-                                                     @diff_grouping_lines || 0)
-
-          # Expand with context lines
-          expanded_contexts = expand_contexts_with_context_lines(contexts,
-                                                                 @context_lines,
-                                                                 diffs.length)
-
-          # Format contexts
-          output = []
-          expanded_contexts.each_with_index do |context, idx|
-            output << "" if idx.positive?
-            output << format_context(context, diffs, range1.start_line,
-                                     range2.start_line)
-          end
-
-          output.join("\n")
-        end
-
-        # Format a deleted element
-        def format_deleted_element(match, map1, lines1)
-          range1 = map1[match.elem1]
-          return nil unless range1
-
-          output = []
-          path_str = match.path.join("/")
-          output << colorize("Element: #{path_str} [DELETED]", :red, :bold)
-
-          # Show all lines as deleted
-          (range1.start_line..range1.end_line).each do |i|
-            output << format_unified_line(i + 1, nil, "-", lines1[i], :red)
-          end
-
-          output.join("\n")
-        end
-
-        # Format an inserted element
-        def format_inserted_element(match, map2, lines2)
-          range2 = map2[match.elem2]
-          return nil unless range2
-
-          output = []
-          path_str = match.path.join("/")
-          output << colorize("Element: #{path_str} [INSERTED]", :green, :bold)
-
-          # Show all lines as inserted
-          (range2.start_line..range2.end_line).each do |i|
-            output << format_unified_line(nil, i + 1, "+", lines2[i], :green)
-          end
-
-          output.join("\n")
-        end
       end
     end
   end

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