backspin 0.4.0 → 0.4.2

data/fixtures/backspin/use_record_filter.yml

@@ -0,0 +1,15 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'hello"
+  - world'
+  stdout: 'HELLO WORLD
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/verify_system.yml

@@ -0,0 +1,12 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - hello
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/verify_system_diff.yml

@@ -0,0 +1,11 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - 'true'
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/version_test.yml

@@ -0,0 +1,14 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - ruby
+  - "--version"
+  stdout: 'ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/lib/backspin/command.rb

@@ -12,11 +12,7 @@ module Backspin
       @recorded_at = recorded_at
 
       # Accept either a CommandResult or individual stdout/stderr/status
-      @result = result || CommandResult.new(
-        stdout: stdout || "",
-        stderr: stderr || "",
-        status: status || 0
-      )
+      @result = result || CommandResult.new(stdout: stdout || "", stderr: stderr || "", status: status || 0)
     end
 
     def stdout

data/lib/backspin/command_diff.rb

@@ -4,20 +4,27 @@ module Backspin
   # Represents the difference between a recorded command and actual execution
   # Handles verification and diff generation for a single command
   class CommandDiff
-    attr_reader :recorded_command, :actual_result, :matcher
+    attr_reader :recorded_command, :actual_command, :matcher
 
-    def initialize(recorded_command:, actual_result:, matcher: nil)
+    def initialize(recorded_command:, actual_command:, matcher: nil)
       @recorded_command = recorded_command
-      @actual_result = actual_result
-      @matcher = matcher
+      @actual_command = actual_command
+      @matcher = normalize_matcher(matcher)
     end
 
     # @return [Boolean] true if the command output matches
     def verified?
-      if matcher
-        matcher.call(recorded_command.to_h, actual_result.to_h)
+      # First check if method classes match
+      return false unless method_classes_match?
+
+      if matcher.nil?
+        recorded_command.result == actual_command.result
+      elsif matcher.is_a?(Proc) # basic all matcher: lambda { |recorded, actual| ...}
+        matcher.call(recorded_command.to_h, actual_command.to_h)
+      elsif matcher.is_a?(Hash) # matcher: {all: lambda { |recorded, actual| ...}, stdout: lambda { |recorded, actual| ...}}
+        verify_with_hash_matcher
       else
-        recorded_command.result == actual_result
+        raise ArgumentError, "Invalid matcher type: #{matcher.class}"
       end
     end
 
@@ -27,12 +34,17 @@ module Backspin
 
       parts = []
 
-      parts << stdout_diff if recorded_command.stdout != actual_result.stdout
+      # Check method class mismatch first
+      unless method_classes_match?
+        parts << "Command type mismatch: expected #{recorded_command.method_class.name}, got #{actual_command.method_class.name}"
+      end
+
+      parts << stdout_diff if recorded_command.stdout != actual_command.stdout
 
-      parts << stderr_diff if recorded_command.stderr != actual_result.stderr
+      parts << stderr_diff if recorded_command.stderr != actual_command.stderr
 
-      if recorded_command.status != actual_result.status
-        parts << "Exit status: expected #{recorded_command.status}, got #{actual_result.status}"
+      if recorded_command.status != actual_command.status
+        parts << "Exit status: expected #{recorded_command.status}, got #{actual_command.status}"
       end
 
       parts.join("\n\n")
@@ -49,20 +61,90 @@ module Backspin
 
     private
 
+    def method_classes_match?
+      recorded_command.method_class == actual_command.method_class
+    end
+
+    def normalize_matcher(matcher)
+      return nil if matcher.nil?
+      return matcher if matcher.is_a?(Proc)
+
+      raise ArgumentError, "Matcher must be a Proc or Hash, got #{matcher.class}" unless matcher.is_a?(Hash)
+
+      # Validate hash keys and values
+      matcher.each do |key, value|
+        unless %i[all stdout stderr status].include?(key)
+          raise ArgumentError, "Invalid matcher key: #{key}. Must be one of: :all, :stdout, :stderr, :status"
+        end
+        raise ArgumentError, "Matcher for #{key} must be callable (Proc/Lambda)" unless value.respond_to?(:call)
+      end
+      matcher
+    end
+
+    def verify_with_hash_matcher
+      recorded_hash = recorded_command.to_h
+      actual_hash = actual_command.to_h
+
+      all_passed = matcher[:all].nil? || matcher[:all].call(recorded_hash, actual_hash)
+
+      fields_passed = %w[stdout stderr status].all? do |field|
+        field_sym = field.to_sym
+        if matcher[field_sym]
+          matcher[field_sym].call(recorded_hash[field], actual_hash[field])
+        else
+          recorded_hash[field] == actual_hash[field]
+        end
+      end
+
+      all_passed && fields_passed
+    end
+
     def failure_reason
       reasons = []
-      reasons << "stdout differs" if recorded_command.stdout != actual_result.stdout
-      reasons << "stderr differs" if recorded_command.stderr != actual_result.stderr
-      reasons << "exit status differs" if recorded_command.status != actual_result.status
+
+      # Check method class first
+      unless method_classes_match?
+        reasons << "command type mismatch"
+        return reasons.join(", ")
+      end
+
+      if matcher.nil?
+        reasons << "stdout differs" if recorded_command.stdout != actual_command.stdout
+        reasons << "stderr differs" if recorded_command.stderr != actual_command.stderr
+        reasons << "exit status differs" if recorded_command.status != actual_command.status
+      elsif matcher.is_a?(Hash)
+        recorded_hash = recorded_command.to_h
+        actual_hash = actual_command.to_h
+
+        # Check :all matcher first
+        reasons << ":all matcher failed" if matcher[:all] && !matcher[:all].call(recorded_hash, actual_hash)
+
+        # Check field-specific matchers
+        %w[stdout stderr status].each do |field|
+          field_sym = field.to_sym
+          if matcher[field_sym]
+            unless matcher[field_sym].call(recorded_hash[field], actual_hash[field])
+              reasons << "#{field} custom matcher failed"
+            end
+          elsif recorded_hash[field] != actual_hash[field]
+            # Always check exact equality for fields without matchers
+            reasons << "#{field} differs"
+          end
+        end
+      else
+        # Proc matcher
+        reasons << "custom matcher failed"
+      end
+
       reasons.join(", ")
     end
 
     def stdout_diff
-      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_result.stdout)}"
+      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_command.stdout)}"
     end
 
     def stderr_diff
-      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_result.stderr)}"
+      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_command.stderr)}"
     end
 
     def generate_line_diff(expected, actual)

data/lib/backspin/command_result.rb

@@ -35,13 +35,11 @@ module Backspin
     def ==(other)
       return false unless other.is_a?(CommandResult)
 
-      stdout == other.stdout &&
-        stderr == other.stderr &&
-        status == other.status
+      stdout == other.stdout && stderr == other.stderr && status == other.status
     end
 
     def inspect
-      "#<Backspin::CommandResult status=#{status} stdout=#{stdout.inspect.truncate(50)} stderr=#{stderr.inspect.truncate(50)}>"
+      "#<Backspin::CommandResult status=#{status} stdout=#{stdout} stderr=#{stderr}>"
     end
 
     private

data/lib/backspin/record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Backspin
   class RecordFormatError < StandardError; end
 
@@ -7,12 +9,37 @@ module Backspin
     FORMAT_VERSION = "2.0"
     attr_reader :path, :commands, :first_recorded_at
 
+    def self.load_or_create(path)
+      record = new(path)
+      record.load_from_file if File.exist?(path)
+      record
+    end
+
+    def self.load_from_file(path)
+      raise Backspin::RecordNotFoundError unless File.exist?(path)
+
+      record = new(path)
+      record.load_from_file
+      record
+    end
+
+    def self.build_record_path(name)
+      backspin_dir = Backspin.configuration.backspin_dir
+      backspin_dir.mkpath
+
+      File.join(backspin_dir, "#{name}.yml")
+    end
+
+    def self.create(name)
+      path = build_record_path(name)
+      new(path)
+    end
+
     def initialize(path)
       @path = path
       @commands = []
       @first_recorded_at = nil
       @playback_index = 0
-      load_from_file if File.exist?(@path)
     end
 
     def add_command(command)
@@ -35,7 +62,7 @@ module Backspin
       @commands = []
       @playback_index = 0
       load_from_file if File.exist?(@path)
-      @playback_index = 0  # Reset again after loading to ensure it's at 0
+      @playback_index = 0 # Reset again after loading to ensure it's at 0
     end
 
     def exists?
@@ -51,9 +78,7 @@ module Backspin
     end
 
     def next_command
-      if @playback_index >= @commands.size
-        raise NoMoreRecordingsError, "No more recordings available for replay"
-      end
+      raise NoMoreRecordingsError, "No more recordings available for replay" if @playback_index >= @commands.size
 
       command = @commands[@playback_index]
       @playback_index += 1
@@ -65,11 +90,7 @@ module Backspin
       @playback_index = 0
     end
 
-    def self.load_or_create(path)
-      new(path)
-    end
-
-    private
+    # private
 
     def load_from_file
       data = YAML.load_file(@path.to_s)

data/lib/backspin/record_result.rb

@@ -4,13 +4,14 @@ module Backspin
   # Result object for all Backspin record operations
   # Provides a consistent interface whether recording, verifying, or playing back
   class RecordResult
-    attr_reader :output, :record_path, :commands, :mode, :command_diffs
+    attr_reader :output, :commands, :mode, :command_diffs
+    attr_reader :record
 
-    def initialize(output:, mode:, record_path:, commands:, verified: nil, command_diffs: nil)
+    def initialize(output:, mode:, record:, verified: nil, command_diffs: nil)
       @output = output
       @mode = mode
-      @record_path = record_path
-      @commands = commands
+      @record = record
+      @commands = record.commands
       @verified = verified
       @command_diffs = command_diffs || []
     end
@@ -20,8 +21,16 @@ module Backspin
       mode == :record
     end
 
+    def record_path
+      record.path
+    end
+
     # @return [Boolean, nil] true/false for verification results, nil for recording
     def verified?
+      return @verified unless mode == :verify
+
+      return false if command_diffs.size < commands.size
+
       @verified
     end
 
@@ -33,6 +42,12 @@ module Backspin
     # @return [String, nil] Human-readable error message if verification failed
     def error_message
       return nil unless verified? == false
+
+      # Check for command count mismatch first
+      if command_diffs.size < commands.size
+        return "Expected #{commands.size} commands but only #{command_diffs.size} were executed"
+      end
+
       return "No commands to verify" if command_diffs.empty?
 
       failed_diffs = command_diffs.reject(&:verified?)
@@ -130,24 +145,15 @@ module Backspin
         playback: playback?,
         stdout: stdout,
         stderr: stderr,
-        status: status,
-        record_path: record_path.to_s
+        status: status
       }
 
-      # Only include verified if it's not nil
       hash[:verified] = verified? unless verified?.nil?
-
-      # Only include diff if present
       hash[:diff] = diff if diff
-
       # Include number of failed commands if in verify mode
       hash[:failed_commands] = command_diffs.count { |d| !d.verified? } if mode == :verify && command_diffs.any?
 
       hash
     end
-
-    def inspect
-      "#<Backspin::RecordResult mode=#{mode} verified=#{verified?.inspect} status=#{status}>"
-    end
   end
 end

data/lib/backspin/recorder.rb

@@ -1,25 +1,30 @@
+# frozen_string_literal: true
+
 require "open3"
 require "ostruct"
 require "rspec/mocks"
+require "backspin/command_result"
+require "backspin/command_diff"
 
 module Backspin
   # Handles stubbing and recording of command executions
   class Recorder
     include RSpec::Mocks::ExampleMethods
-    SUPPORTED_COMMAND_TYPES = [:capture3, :system]
+    SUPPORTED_COMMAND_TYPES = %i[capture3 system].freeze
 
-    attr_reader :commands, :verification_data, :mode, :record
+    attr_reader :commands, :mode, :record, :options
 
-    def initialize(mode: :record, record: nil)
+    def initialize(mode: :record, record: nil, options: {})
       @mode = mode
       @record = record
+      @options = options
       @commands = []
-      @verification_data = {}
+      @playback_index = 0
+      @command_diffs = []
     end
 
-    def record_calls(*command_types)
+    def setup_recording_stubs(*command_types)
       command_types = SUPPORTED_COMMAND_TYPES if command_types.empty?
-
       command_types.each do |command_type|
         record_call(command_type)
       end
@@ -32,67 +37,110 @@ module Backspin
       when :capture3
         setup_capture3_call_stub
       else
-        raise ArgumentError, "Unsupported command type: #{command_type} - currently supported types: #{SUPPORTED_COMMAND_TYPES.join(", ")}"
+        raise ArgumentError,
+          "Unsupported command type: #{command_type} - currently supported types: #{SUPPORTED_COMMAND_TYPES.join(", ")}"
       end
     end
 
-    # Setup stubs for playback mode - just return recorded values
-    def setup_playback_stub(command)
-      if command.method_class == Open3::Capture3
-        actual_status = OpenStruct.new(exitstatus: command.status)
-        allow(Open3).to receive(:capture3).and_return([command.stdout, command.stderr, actual_status])
-      elsif command.method_class == ::Kernel::System
-        # For system, return true if exit status was 0
-        allow_any_instance_of(Object).to receive(:system).and_return(command.status == 0)
-      end
+    # Records registered commands, adds them to the record, saves the record, and returns the overall RecordResult
+    def perform_recording
+      result = yield
+      record.save(filter: options[:filter])
+      RecordResult.new(output: result, mode: :record, record: record)
     end
 
-    # Setup stubs for verification - capture actual output
-    def setup_verification_stub(command)
-      @verification_data = {}
-
-      if command.method_class == Open3::Capture3
-        allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
-          stdout, stderr, status = original_method.call(*args)
-          @verification_data["stdout"] = stdout
-          @verification_data["stderr"] = stderr
-          @verification_data["status"] = status.exitstatus
-          [stdout, stderr, status]
-        end
-      elsif command.method_class == ::Kernel::System
-        allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
-          # Execute the real system call
-          result = original_method.call(receiver, *args)
+    # Performs verification by executing commands and comparing with recorded values
+    def perform_verification
+      raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record" if record.empty?
 
-          # For system calls, we only track the exit status
-          @verification_data["stdout"] = ""
-          @verification_data["stderr"] = ""
-          @verification_data["status"] = result ? 0 : 1
+      # Initialize tracking variables
+      @command_diffs = []
+      @command_index = 0
 
-          result
+      # Setup verification stubs for capture3
+      allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
+        recorded_command = record.commands[@command_index]
+
+        if recorded_command.nil?
+          raise RecordNotFoundError, "No more recorded commands, but tried to execute: #{args.inspect}"
         end
+
+        stdout, stderr, status = original_method.call(*args)
+
+        actual_command = Command.new(
+          method_class: Open3::Capture3,
+          args: args,
+          stdout: stdout,
+          stderr: stderr,
+          status: status.exitstatus
+        )
+
+        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: options[:matcher])
+        @command_index += 1
+        [stdout, stderr, status]
       end
+
+      # Setup verification stubs for system
+      allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
+        recorded_command = record.commands[@command_index]
+
+        result = original_method.call(receiver, *args)
+
+        actual_command = Command.new(
+          method_class: ::Kernel::System,
+          args: args,
+          stdout: "",
+          stderr: "",
+          status: result ? 0 : 1
+        )
+
+        # Create CommandDiff to track the comparison
+        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: options[:matcher])
+
+        @command_index += 1
+        result
+      end
+
+      output = yield
+
+      all_verified = @command_diffs.all?(&:verified?)
+
+      RecordResult.new(
+        output: output,
+        mode: :verify,
+        verified: all_verified,
+        record: record,
+        command_diffs: @command_diffs
+      )
     end
 
-    # Setup stubs for replay mode - returns recorded values for multiple commands
-    def setup_replay_stubs
-      raise ArgumentError, "Record required for replay mode" unless @record
+    # Performs playback by returning recorded values without executing actual commands
+    def perform_playback
+      raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record" if record.empty?
 
+      # Setup replay stubs
       setup_capture3_replay_stub
       setup_system_replay_stub
+
+      # Execute block (all commands will be stubbed with recorded values)
+      output = yield
+
+      RecordResult.new(
+        output: output,
+        mode: :playback,
+        verified: true, # Always true for playback
+        record: record
+      )
     end
 
     private
 
     def setup_capture3_replay_stub
-      allow(Open3).to receive(:capture3) do |*args|
+      allow(Open3).to receive(:capture3) do |*_args|
         command = @record.next_command
 
-        # Make sure this is a capture3 command
-        unless command.method_class == Open3::Capture3
-          raise RecordNotFoundError, "Expected Open3::Capture3 command but got #{command.method_class.name}"
-        end
-
         recorded_stdout = command.stdout
         recorded_stderr = command.stderr
         recorded_status = OpenStruct.new(exitstatus: command.status)
@@ -104,14 +152,10 @@ module Backspin
     end
 
     def setup_system_replay_stub
-      allow_any_instance_of(Object).to receive(:system) do |receiver, *args|
+      allow_any_instance_of(Object).to receive(:system) do |_receiver, *_args|
         command = @record.next_command
 
-        unless command.method_class == ::Kernel::System
-          raise RecordNotFoundError, "Expected Kernel::System command but got #{command.method_class.name}"
-        end
-
-        command.status == 0
+        command.status.zero?
       rescue NoMoreRecordingsError => e
         raise RecordNotFoundError, e.message
       end
@@ -135,7 +179,7 @@ module Backspin
           status: status.exitstatus,
           recorded_at: Time.now.iso8601
         )
-        @commands << command
+        record.add_command(command)
 
         [stdout, stderr, status]
       end
@@ -154,7 +198,8 @@ module Backspin
           args
         end
 
-        stdout, stderr = "", ""
+        stdout = ""
+        stderr = ""
         status = result ? 0 : 1
 
         command = Command.new(
@@ -165,7 +210,7 @@ module Backspin
           status: status,
           recorded_at: Time.now.iso8601
         )
-        @commands << command
+        record.add_command(command)
 
         result
       end

data/lib/backspin/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Backspin
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end