backspin 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a6c6a0ef97c99ace7fb068e7b85bc40c2f45594bc30ce5002920fd62fcd384
-  data.tar.gz: f62c15526c0a19a4ae876b8c737b172e2557c54a55f4d5045a0dbc499ccfcd51
+  metadata.gz: a9533baf54aa3ae09b9d483d41149a6ede985f3f974f038e287034928a0ab1e3
+  data.tar.gz: 75b9cb2018b1f1ca5878f6ce75af74bc9fc4822319ac2f12e8c654f30624f859
 SHA512:
-  metadata.gz: 117a79e8e448bae03c68b44e8a6de23671d746d2ea664094e7dc82792d8ff323af7c6faf73f85a9aa020bb259127660abc8d7687cf861b627049b6e3b88ff41f
-  data.tar.gz: dfeabf728ef8448d01889dbe2d62d9d2a8236da296d9f6ee21619f6e3f976218cd0af3da2ac8b7f4ab1ff9cbc19dd4afaef1ca64ac777f3f9215180a1349c1c0
+  metadata.gz: a8d851c2836d8cd0be15b341a7f2af332c356aaa9688766a5b51f65110539a2d500cac8238abd4bc0a668a689effbef45a8f009829a3cd28ff4acd249bb506b4
+  data.tar.gz: 0151e1de9a47285ca75552e97154b57100de50fe691100869144e1ed17e1b7c421a012599c4462a333f6abd0c4779f110a4fbffd2bbe60d14d600469da459bad

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.11.0 - 2026-02-11
+* Added immutable top-level `first_recorded_at` metadata for record files.
+* Added mutable top-level `recorded_at` metadata that updates on each successful re-record.
+* Added top-level `record_count`, incremented on each successful record write.
+* Record format now writes `format_version: 4.1`; loading remains backward-compatible with 4.0 record files.
+* Added acceptance coverage for v4.1 schema and 4.0-to-4.1 upgrade behavior.
+* Removed legacy committed `.yml` record fixtures from old schema versions.
+
+## 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.11.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

@@ -91,6 +91,28 @@ result = Backspin.run(["echo", "hello"], name: "echo_test", mode: :verify)
 expect(result.verified?).to be true
 ```
 
+### Record Metadata
+
+Backspin writes records using `format_version: "4.1"` with top-level metadata:
+
+```yaml
+---
+format_version: "4.1"
+first_recorded_at: "2026-01-01T10:00:00Z" # immutable
+recorded_at: "2026-02-01T10:00:00Z"       # updates on each write
+record_count: 3                            # increments on each write
+snapshot:
+  command_type: "Open3::Capture3"
+  args: ["echo", "hello"]
+  stdout: "hello\n"
+  stderr: ""
+  status: 0
+  recorded_at: "2026-02-01T10:00:00Z"
+```
+
+When re-recording with `mode: :record`, Backspin preserves `first_recorded_at`, updates `recorded_at`, and increments `record_count`.
+Existing `4.0` records still load and are upgraded to `4.1` metadata on the next write.
+
 ### Environment Variables
 
 ```ruby
@@ -132,6 +154,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
@@ -139,14 +141,16 @@ result.expected.stdout
 - Error message is generated from `BackspinResult#error_message`.
 - Do not duplicate `diff` content in exception formatting.
 
-## Record Format Sketch (v4)
+## Record Format Sketch (v4.1)
 
 Single-snapshot format to match single-snapshot runtime model:
 
 ```yaml
 ---
-format_version: "4.0"
+format_version: "4.1"
+first_recorded_at: "2026-01-01T00:00:00Z"
 recorded_at: "2026-02-11T00:00:00Z"
+record_count: 3
 snapshot:
   command_type: "Open3::Capture3"
   args: ["echo", "hello"]
@@ -182,11 +186,11 @@ Status date: 2026-02-11
 
 1. `Snapshot` and `BackspinResult` classes are implemented and wired into runtime paths.
 2. `Backspin.run` and `Backspin.capture` now return `BackspinResult`.
-3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array).
+3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array), with v4.1 top-level metadata.
 4. `Matcher` and `CommandDiff` now operate on expected/actual snapshots.
 5. Legacy result/command layering was removed from `lib/`.
-6. Specs have been migrated to the new result contract and v4 format.
-7. Validation is green: `66 examples, 0 failures` and Standard lint passes.
+6. Specs have been migrated to the new result contract and v4.1 format.
+7. Validation is green: `89 examples, 0 failures` and Standard lint passes.
 8. Public docs now use `result.actual` / `result.expected` terminology.
 
 ## Success Criteria
@@ -196,7 +200,7 @@ Status date: 2026-02-11
 3. In `:verify` mode, `result.expected` is present, `result.verified?` is boolean, and mismatch cases populate `result.diff` plus `result.error_message`.
 4. No multi-command result API remains in the public result contract.
 5. Snapshot object exposes a stable single-command shape: `stdout`, `stderr`, `status`, `args`, `env`, `command_type`.
-6. Record format uses one snapshot (v4), not a commands array.
+6. Record format uses one snapshot (v4.x), not a commands array.
 7. Existing strict verification behavior remains: default raises `Backspin::VerificationError`, while `raise_on_verification_failure = false` returns a failed result without raising.
 8. End-to-end Unix command examples are covered in specs: `echo` record/verify, `ls -1` record/verify, `date` mismatch behavior (or matcher override), and captured `grep | wc` pipeline output via `Backspin.capture`.
 9. Matcher behavior is preserved: default matching remains stdout/stderr/status, and custom `matcher:` contract (Proc, hash fields, `:all`) continues to work for both run and capture verification.

data/fixtures/backspin/.gitkeep

@@ -0,0 +1 @@
+

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

@@ -4,8 +4,9 @@ module Backspin
   class RecordFormatError < StandardError; end
 
   class Record
-    FORMAT_VERSION = "4.0"
-    attr_reader :path, :snapshot, :recorded_at
+    FORMAT_VERSION = "4.1"
+    SUPPORTED_FORMAT_VERSIONS = ["4.0", FORMAT_VERSION].freeze
+    attr_reader :path, :snapshot, :first_recorded_at, :recorded_at, :record_count
 
     def self.load_or_create(path)
       record = new(path)
@@ -36,28 +37,40 @@ module Backspin
     def initialize(path)
       @path = path
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def set_snapshot(snapshot)
       @snapshot = snapshot
-      @recorded_at ||= snapshot.recorded_at
+      snapshot_recorded_at = snapshot.recorded_at || Time.now.iso8601
+      @first_recorded_at ||= snapshot_recorded_at
+      @recorded_at = snapshot_recorded_at
       self
     end
 
     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
+      next_record_count = (@record_count || 0) + 1
       record_data = {
         "format_version" => FORMAT_VERSION,
+        "first_recorded_at" => @first_recorded_at,
         "recorded_at" => @recorded_at,
-        "snapshot" => @snapshot&.to_h(filter: filter)
+        "record_count" => next_record_count,
+        "snapshot" => snapshot_data
       }
       File.write(@path, record_data.to_yaml)
+      @record_count = next_record_count
     end
 
     def reload
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
       load_from_file if File.exist?(@path)
     end
 
@@ -71,13 +84,15 @@ module Backspin
 
     def clear
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def load_from_file
       data = YAML.load_file(@path.to_s)
 
-      unless data.is_a?(Hash) && data["format_version"] == FORMAT_VERSION
+      unless data.is_a?(Hash) && SUPPORTED_FORMAT_VERSIONS.include?(data["format_version"])
         raise RecordFormatError, "Invalid record format: expected format version #{FORMAT_VERSION}"
       end
 
@@ -86,10 +101,49 @@ module Backspin
         raise RecordFormatError, "Invalid record format: missing snapshot"
       end
 
-      @recorded_at = data["recorded_at"]
+      format_version = data["format_version"]
+      @recorded_at = data["recorded_at"] || snapshot_data["recorded_at"]
+      if format_version == FORMAT_VERSION
+        @first_recorded_at = data["first_recorded_at"]
+        @record_count = data["record_count"]
+      else
+        # Backfill metadata for v4.0 records.
+        @first_recorded_at = data["first_recorded_at"] || @recorded_at
+        @record_count = data.fetch("record_count", 1)
+      end
+      validate_metadata!
       @snapshot = Snapshot.from_h(snapshot_data)
     rescue Psych::SyntaxError => e
       raise RecordFormatError, "Invalid record format: #{e.message}"
     end
+
+    private
+
+    def validate_metadata!
+      unless @first_recorded_at.is_a?(String) && !@first_recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing first_recorded_at"
+      end
+
+      unless @recorded_at.is_a?(String) && !@recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing recorded_at"
+      end
+
+      unless @record_count.is_a?(Integer) && @record_count.positive?
+        raise RecordFormatError, "Invalid record format: record_count must be a positive integer"
+      end
+    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/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(