backspin 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a6c6a0ef97c99ace7fb068e7b85bc40c2f45594bc30ce5002920fd62fcd384
-  data.tar.gz: f62c15526c0a19a4ae876b8c737b172e2557c54a55f4d5045a0dbc499ccfcd51
+  metadata.gz: edf2daa2123a270ca28d593b594188db57913b2ca5905a45b6a9e0d1221c0da4
+  data.tar.gz: 3ec4407d3396e3e8390f62b3c0e7d2124bdf026e4b02e74c036ee37fab8430a4
 SHA512:
-  metadata.gz: 117a79e8e448bae03c68b44e8a6de23671d746d2ea664094e7dc82792d8ff323af7c6faf73f85a9aa020bb259127660abc8d7687cf861b627049b6e3b88ff41f
-  data.tar.gz: dfeabf728ef8448d01889dbe2d62d9d2a8236da296d9f6ee21619f6e3f976218cd0af3da2ac8b7f4ab1ff9cbc19dd4afaef1ca64ac777f3f9215180a1349c1c0
+  metadata.gz: a851d194aa4f400c9104643b5521e7b5bd5e159708a0d6114c70cfd39907fb6174041a3bccffdc824edb3e224bab7db453b906c35adc7f0a2908d2b034a9b11a
+  data.tar.gz: 01b1c9b4288f978d9946090afda49e17001732ec0b4f5e47d3831767975d731e5c940cc0fbdd7ccfca4a2bdf54bc8d281eba7d3dc4cbbd137e3f4edb576d9378

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.10.0 - 2026-02-11
+* Added `filter_on` to `Backspin.run` and `Backspin.capture` (`:both` default, `:record` opt-out).
+* Changed default filter behavior: `filter` now applies during verify comparisons/diffs when `filter_on: :both`.
+* Matcher callbacks now receive mutable copies of comparison data so in-place mutations do not mutate snapshots.
+* Snapshot serialization is now immutable: `Snapshot#to_h` returns a frozen representation built at initialization.
+
 ## 0.9.0 - 2026-02-11
 * Breaking: `Backspin.run` and `Backspin.capture` now return `Backspin::BackspinResult` with explicit `result.actual` / `result.expected` snapshots.
 * Breaking: result convenience accessors (`result.stdout`, `result.stderr`, `result.status`) were removed in favor of snapshot access.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.9.0)
+    backspin (0.10.0)
 
 GEM
   remote: https://rubygems.org/

data/MATCHERS.md

@@ -77,6 +77,24 @@ The `:all` matcher receives full hashes with these keys:
 - `"env"` - Optional Hash of env vars (command runs only)
 - `"recorded_at"` - Timestamp string
 
+Matcher inputs are copies of comparison data so in-place mutation inside matcher callbacks
+does not mutate Backspin's stored snapshots.
+
+Matcher callbacks should return a boolean. Any truthy return value is treated as pass,
+and false/nil is treated as failure.
+
+Example with safe in-place mutation:
+
+```ruby
+matcher = {
+  all: ->(recorded, actual) {
+    recorded["stdout"].gsub!(/id=\d+/, "id=[ID]")
+    actual["stdout"].gsub!(/id=\d+/, "id=[ID]")
+    recorded["stdout"] == actual["stdout"]
+  }
+}
+```
+
 ## Examples
 
 ### Matching Version Numbers

data/README.md

@@ -132,6 +132,41 @@ result = Backspin.run(["date"], name: "timestamp_test", matcher: {stdout: timest
 
 For more matcher examples and detailed documentation, see [MATCHERS.md](MATCHERS.md).
 
+### Filters and Canonicalization
+
+Use `filter:` to normalize snapshot data (timestamps, random IDs, absolute paths).
+
+By default (`filter_on: :both`), Backspin applies `filter`:
+- when writing record snapshots
+- during verify for both expected and actual, before matcher and diff
+
+If you only want record-time filtering, use `filter_on: :record`.
+
+Migration note: older behavior applied `filter` only at record write. To preserve that behavior, set `filter_on: :record`.
+
+```ruby
+normalize_filter = ->(snapshot) do
+  snapshot.merge(
+    "stdout" => snapshot["stdout"].gsub(/id=\d+/, "id=[ID]")
+  )
+end
+
+# default: filter_on :both
+Backspin.run(["echo", "id=123"], name: "canonicalized", filter: normalize_filter)
+Backspin.run(["echo", "id=999"], name: "canonicalized", filter: normalize_filter) # verifies
+
+# capture also supports verify-time canonicalization
+Backspin.capture("capture_canonicalized", filter: normalize_filter) do
+  puts "id=123"
+end
+Backspin.capture("capture_canonicalized", filter: normalize_filter) do
+  puts "id=999"
+end
+
+# record-only filtering
+Backspin.run(["echo", "id=123"], name: "record_only", filter: normalize_filter, filter_on: :record)
+```
+
 ### Working with the Result Object
 
 The API returns a `Backspin::BackspinResult` object with helpful methods:

data/docs/backspin-result-api-sketch.md

@@ -15,8 +15,8 @@ Branch: `spike-backspin-result-api`
 ### Entry points
 
 ```ruby
-Backspin.run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, &block)
-Backspin.capture(name, mode: :auto, matcher: nil, filter: nil, &block)
+Backspin.run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
+Backspin.capture(name, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
 ```
 
 Both return `BackspinResult`.
@@ -130,7 +130,9 @@ result.expected.stdout
 ## Matcher and Filter Semantics
 
 - `matcher:` applies only during verify and compares `expected` vs `actual`.
-- `filter:` applies only when writing snapshots to disk.
+- `filter:` applies during record writes, and during verify when `filter_on: :both`.
+- `filter_on:` supports `:both` (default) and `:record`.
+- `Snapshot` serializes once at initialization and returns a frozen hash from `to_h`.
 - Default match still compares stdout/stderr/status only.
 
 ## Error Semantics

data/lib/backspin/command_diff.rb

@@ -5,21 +5,25 @@ module Backspin
   class CommandDiff
     attr_reader :expected, :actual, :matcher
 
-    def initialize(expected:, actual:, matcher: nil)
+    def initialize(expected:, actual:, matcher: nil, filter: nil, filter_on: :both)
       @expected = expected
       @actual = actual
+      @expected_compare = build_comparison_snapshot(expected, filter: filter, filter_on: filter_on)
+      @actual_compare = build_comparison_snapshot(actual, filter: filter, filter_on: filter_on)
       @matcher = Matcher.new(
         config: matcher,
-        expected: expected,
-        actual: actual
+        expected: @expected_compare,
+        actual: @actual_compare
       )
+      @verified = nil
     end
 
     # @return [Boolean] true if the snapshot output matches.
     def verified?
-      return false unless command_types_match?
+      return @verified unless @verified.nil?
+      return @verified = false unless command_types_match?
 
-      @matcher.match?
+      @verified = @matcher.match?
     end
 
     # @return [String, nil] Human-readable diff if not verified
@@ -27,23 +31,21 @@ module Backspin
       return nil if verified?
 
       parts = []
-      expected_hash = expected.to_h
-      actual_hash = actual.to_h
 
       unless command_types_match?
         parts << "Command type mismatch: expected #{expected.command_type.name}, got #{actual.command_type.name}"
       end
 
-      if expected_hash["stdout"] != actual_hash["stdout"]
-        parts << stdout_diff(expected_hash["stdout"], actual_hash["stdout"])
+      if expected_compare.stdout != actual_compare.stdout
+        parts << stdout_diff(expected_compare.stdout, actual_compare.stdout)
       end
 
-      if expected_hash["stderr"] != actual_hash["stderr"]
-        parts << stderr_diff(expected_hash["stderr"], actual_hash["stderr"])
+      if expected_compare.stderr != actual_compare.stderr
+        parts << stderr_diff(expected_compare.stderr, actual_compare.stderr)
       end
 
-      if expected_hash["status"] != actual_hash["status"]
-        parts << "Exit status: expected #{expected_hash["status"]}, got #{actual_hash["status"]}"
+      if expected_compare.status != actual_compare.status
+        parts << "Exit status: expected #{expected_compare.status}, got #{actual_compare.status}"
       end
 
       parts.join("\n\n")
@@ -99,5 +101,60 @@ module Backspin
 
       diff_lines.join("\n")
     end
+
+    attr_reader :expected_compare
+
+    attr_reader :actual_compare
+
+    def build_comparison_snapshot(snapshot, filter:, filter_on:)
+      data = deep_dup(snapshot.to_h)
+      if filter && filter_on == :both
+        data = filter.call(data)
+      end
+
+      ComparisonSnapshot.new(
+        command_type: snapshot.command_type,
+        data: deep_freeze(data)
+      )
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |entry| deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_value { |entry| deep_freeze(entry) }
+      when Array
+        value.each { |entry| deep_freeze(entry) }
+      end
+      value.freeze
+    end
+
+    class ComparisonSnapshot
+      attr_reader :command_type, :stdout, :stderr, :status
+
+      def initialize(command_type:, data:)
+        @command_type = command_type
+        @data = data
+        @stdout = data["stdout"]
+        @stderr = data["stderr"]
+        @status = data["status"]
+      end
+
+      def to_h
+        @data
+      end
+    end
   end
 end

data/lib/backspin/matcher.rb

@@ -13,48 +13,12 @@ module Backspin
 
     # @return [Boolean] true if snapshots match according to configured matcher
     def match?
-      if config.nil?
-        default_matcher.call(expected.to_h, actual.to_h)
-      elsif config.is_a?(Proc)
-        config.call(expected.to_h, actual.to_h)
-      elsif config.is_a?(Hash)
-        verify_with_hash_matcher
-      else
-        raise ArgumentError, "Invalid matcher type: #{config.class}"
-      end
+      evaluation[:match]
     end
 
     # @return [String] reason why matching failed
     def failure_reason
-      reasons = []
-
-      if config.nil?
-        expected_hash = expected.to_h
-        actual_hash = actual.to_h
-
-        reasons << "stdout differs" if expected_hash["stdout"] != actual_hash["stdout"]
-        reasons << "stderr differs" if expected_hash["stderr"] != actual_hash["stderr"]
-        reasons << "exit status differs" if expected_hash["status"] != actual_hash["status"]
-      elsif config.is_a?(Hash)
-        expected_hash = expected.to_h
-        actual_hash = actual.to_h
-
-        config.each do |field, matcher_proc|
-          case field
-          when :all
-            reasons << ":all matcher failed" unless matcher_proc.call(expected_hash, actual_hash)
-          when :stdout, :stderr, :status
-            unless matcher_proc.call(expected_hash[field.to_s], actual_hash[field.to_s])
-              reasons << "#{field} custom matcher failed"
-            end
-          end
-        end
-      else
-        # Proc matcher
-        reasons << "custom matcher failed"
-      end
-
-      reasons.join(", ")
+      evaluation[:reason]
     end
 
     private
@@ -75,29 +39,73 @@ module Backspin
       config
     end
 
-    def verify_with_hash_matcher
-      expected_hash = expected.to_h
-      actual_hash = actual.to_h
+    def evaluation
+      @evaluation ||= if config.nil?
+        evaluate_default
+      elsif config.is_a?(Proc)
+        evaluate_proc
+      elsif config.is_a?(Hash)
+        evaluate_hash
+      else
+        raise ArgumentError, "Invalid matcher type: #{config.class}"
+      end
+    end
+
+    def evaluate_default
+      reasons = []
+      reasons << "stdout differs" if expected.stdout != actual.stdout
+      reasons << "stderr differs" if expected.stderr != actual.stderr
+      reasons << "exit status differs" if expected.status != actual.status
 
-      results = config.map do |field, matcher_proc|
-        case field
+      {match: reasons.empty?, reason: reasons.join(", ")}
+    end
+
+    def evaluate_proc
+      match = !!config.call(deep_dup(expected_hash), deep_dup(actual_hash))
+      reason = match ? "" : "custom matcher failed"
+      {match: match, reason: reason}
+    end
+
+    def evaluate_hash
+      reasons = []
+
+      config.each do |field, matcher_proc|
+        passed = case field
         when :all
-          matcher_proc.call(expected_hash, actual_hash)
+          matcher_proc.call(deep_dup(expected_hash), deep_dup(actual_hash))
         when :stdout, :stderr, :status
-          matcher_proc.call(expected_hash[field.to_s], actual_hash[field.to_s])
+          matcher_proc.call(deep_dup(expected.public_send(field)), deep_dup(actual.public_send(field)))
         else
           raise ArgumentError, "Unknown field: #{field}"
         end
+
+        next if passed
+
+        reasons << ":all matcher failed" if field == :all
+        reasons << "#{field} custom matcher failed" if %i[stdout stderr status].include?(field)
       end
 
-      results.all?
+      {match: reasons.empty?, reason: reasons.join(", ")}
+    end
+
+    def expected_hash
+      @expected_hash ||= expected.to_h
+    end
+
+    def actual_hash
+      @actual_hash ||= actual.to_h
     end
 
-    def default_matcher
-      @default_matcher ||= lambda do |recorded, actual|
-        recorded["stdout"] == actual["stdout"] &&
-          recorded["stderr"] == actual["stderr"] &&
-          recorded["status"] == actual["status"]
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |entry| deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
       end
     end
   end

data/lib/backspin/record.rb

@@ -47,10 +47,12 @@ module Backspin
 
     def save(filter: nil)
       FileUtils.mkdir_p(File.dirname(@path))
+      snapshot_data = @snapshot&.to_h
+      snapshot_data = filter.call(deep_dup(snapshot_data)) if snapshot_data && filter
       record_data = {
         "format_version" => FORMAT_VERSION,
         "recorded_at" => @recorded_at,
-        "snapshot" => @snapshot&.to_h(filter: filter)
+        "snapshot" => snapshot_data
       }
       File.write(@path, record_data.to_yaml)
     end
@@ -91,5 +93,20 @@ module Backspin
     rescue Psych::SyntaxError => e
       raise RecordFormatError, "Invalid record format: #{e.message}"
     end
+
+    private
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |entry| deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
   end
 end

data/lib/backspin/recorder.rb

@@ -6,13 +6,14 @@ require "backspin/command_diff"
 module Backspin
   # Handles capture-mode recording and verification
   class Recorder
-    attr_reader :mode, :record, :matcher, :filter
+    attr_reader :mode, :record, :matcher, :filter, :filter_on
 
-    def initialize(mode: :record, record: nil, matcher: nil, filter: nil)
+    def initialize(mode: :record, record: nil, matcher: nil, filter: nil, filter_on: :both)
       @mode = mode
       @record = record
       @matcher = matcher
       @filter = filter
+      @filter_on = filter_on
     end
 
     # Performs capture recording by intercepting all stdout/stderr output
@@ -62,7 +63,9 @@ module Backspin
       command_diff = CommandDiff.new(
         expected: expected_snapshot,
         actual: actual_snapshot,
-        matcher: @matcher
+        matcher: @matcher,
+        filter: @filter,
+        filter_on: @filter_on
       )
 
       BackspinResult.new(

data/lib/backspin/snapshot.rb

@@ -7,12 +7,13 @@ module Backspin
 
     def initialize(command_type:, args:, env: nil, stdout: "", stderr: "", status: 0, recorded_at: nil)
       @command_type = command_type
-      @args = args
-      @env = env
-      @stdout = stdout || ""
-      @stderr = stderr || ""
+      @args = sanitize_args(args)
+      @env = env.nil? ? nil : sanitize_env(env)
+      @stdout = Backspin.scrub_text((stdout || "").dup).freeze
+      @stderr = Backspin.scrub_text((stderr || "").dup).freeze
       @status = status || 0
-      @recorded_at = recorded_at
+      @recorded_at = recorded_at.nil? ? nil : recorded_at.dup.freeze
+      @serialized_hash = build_serialized_hash
     end
 
     def success?
@@ -23,20 +24,8 @@ module Backspin
       !success?
     end
 
-    def to_h(filter: nil)
-      data = {
-        "command_type" => command_type.name,
-        "args" => scrub_args(args),
-        "stdout" => Backspin.scrub_text(stdout),
-        "stderr" => Backspin.scrub_text(stderr),
-        "status" => status,
-        "recorded_at" => recorded_at
-      }
-
-      data["env"] = scrub_env(env) if env
-      data = filter.call(data) if filter
-
-      data
+    def to_h
+      @serialized_hash
     end
 
     def self.from_h(data)
@@ -62,6 +51,19 @@ module Backspin
 
     private
 
+    def build_serialized_hash
+      data = {
+        "command_type" => command_type.name,
+        "args" => args,
+        "stdout" => stdout,
+        "stderr" => stderr,
+        "status" => status,
+        "recorded_at" => recorded_at
+      }
+      data["env"] = env if env
+      deep_freeze(data)
+    end
+
     def scrub_args(value)
       return value unless Backspin.configuration.scrub_credentials && value
 
@@ -82,6 +84,37 @@ module Backspin
 
       value.transform_values { |entry| entry.is_a?(String) ? Backspin.scrub_text(entry) : entry }
     end
+
+    def sanitize_args(value)
+      deep_freeze(scrub_args(deep_dup(value)))
+    end
+
+    def sanitize_env(value)
+      deep_freeze(scrub_env(deep_dup(value)))
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_value { |v| deep_freeze(v) }
+      when Array
+        value.each { |v| deep_freeze(v) }
+      end
+      value.freeze
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |entry| deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
   end
 end
 

data/lib/backspin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backspin
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/backspin.rb

@@ -71,19 +71,30 @@ module Backspin
     # @param env [Hash] Environment variables to pass to Open3.capture3
     # @param mode [Symbol] Recording mode - :auto, :record, :verify
     # @param matcher [Proc, Hash] Custom matcher for verification
-    # @param filter [Proc] Custom filter for recorded data
+    # @param filter [Proc] Custom filter for recorded data/canonicalization
+    # @param filter_on [Symbol] Filter application mode - :both (default), :record
     # @return [BackspinResult] Aggregate result for this run
-    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, &block)
+    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
+      validate_filter_on!(filter_on)
+
       if block_given?
         raise ArgumentError, "command must be omitted when using a block" unless command.nil?
         raise ArgumentError, "env is not supported when using a block" unless env.nil?
 
-        return perform_capture(name, mode: mode, matcher: matcher, filter: filter, &block)
+        return perform_capture(name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
       end
 
       raise ArgumentError, "command is required" if command.nil?
 
-      perform_command_run(command, name: name, env: env, mode: mode, matcher: matcher, filter: filter)
+      perform_command_run(
+        command,
+        name: name,
+        env: env,
+        mode: mode,
+        matcher: matcher,
+        filter: filter,
+        filter_on: filter_on
+      )
     end
 
     # Captures all stdout/stderr output from a block
@@ -91,18 +102,20 @@ module Backspin
     # @param record_name [String] Name for the record file
     # @param mode [Symbol] Recording mode - :auto, :record, :verify
     # @param matcher [Proc, Hash] Custom matcher for verification
-    # @param filter [Proc] Custom filter for recorded data
+    # @param filter [Proc] Custom filter for recorded data/canonicalization
+    # @param filter_on [Symbol] Filter application mode - :both (default), :record
     # @return [BackspinResult] Aggregate result for this run
-    def capture(record_name, mode: :auto, matcher: nil, filter: nil, &block)
+    def capture(record_name, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
       raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
       raise ArgumentError, "block is required" unless block_given?
+      validate_filter_on!(filter_on)
 
-      perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, &block)
+      perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
     end
 
     private
 
-    def perform_capture(record_name, mode:, matcher:, filter:, &block)
+    def perform_capture(record_name, mode:, matcher:, filter:, filter_on:, &block)
       record_path = Record.build_record_path(record_name)
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
@@ -113,7 +126,7 @@ module Backspin
         Record.load_or_create(record_path)
       end
 
-      recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter)
+      recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on)
 
       result = case mode
       when :record
@@ -129,7 +142,7 @@ module Backspin
       result
     end
 
-    def perform_command_run(command, name:, env:, mode:, matcher:, filter:)
+    def perform_command_run(command, name:, env:, mode:, matcher:, filter:, filter_on:)
       record_path = Record.build_record_path(name)
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
@@ -180,7 +193,13 @@ module Backspin
           stderr: stderr,
           status: status.exitstatus
         )
-        command_diff = CommandDiff.new(expected: expected_snapshot, actual: actual_snapshot, matcher: matcher)
+        command_diff = CommandDiff.new(
+          expected: expected_snapshot,
+          actual: actual_snapshot,
+          matcher: matcher,
+          filter: filter,
+          filter_on: filter_on
+        )
         BackspinResult.new(
           mode: :verify,
           record_path: record.path,
@@ -242,5 +261,11 @@ module Backspin
 
       raise ArgumentError, "Unknown mode: #{mode}"
     end
+
+    def validate_filter_on!(filter_on)
+      return if %i[both record].include?(filter_on)
+
+      raise ArgumentError, "Unknown filter_on: #{filter_on}. Must be :both or :record"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Rob Sanheim