backspin 0.2.1 → 0.4.0

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -3,6 +3,4 @@ set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
-bundle install
-
-# Do any other automated setup that you need to do here
+bundle install

data/lib/backspin/command.rb

@@ -1,31 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "command_result"
+
 module Backspin
   class Command
-    attr_reader :args, :stdout, :stderr, :status, :recorded_at, :method_class
+    attr_reader :args, :result, :recorded_at, :method_class
 
-    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, recorded_at: nil)
+    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, result: nil, recorded_at: nil)
       @method_class = method_class
       @args = args
-      @stdout = stdout
-      @stderr = stderr
-      @status = status
       @recorded_at = recorded_at
+
+      # Accept either a CommandResult or individual stdout/stderr/status
+      @result = result || CommandResult.new(
+        stdout: stdout || "",
+        stderr: stderr || "",
+        status: status || 0
+      )
+    end
+
+    def stdout
+      @result.stdout
+    end
+
+    def stderr
+      @result.stderr
+    end
+
+    def status
+      @result.status
     end
 
     # Convert to hash for YAML serialization
     def to_h(filter: nil)
       data = {
         "command_type" => @method_class.name,
-        "args" => @args,
-        "stdout" => Backspin.scrub_text(@stdout),
-        "stderr" => Backspin.scrub_text(@stderr),
-        "status" => @status,
+        "args" => scrub_args(@args),
+        "stdout" => Backspin.scrub_text(@result.stdout),
+        "stderr" => Backspin.scrub_text(@result.stderr),
+        "status" => @result.status,
         "recorded_at" => @recorded_at
       }
 
       # Apply filter if provided
-      if filter
-        data = filter.call(data)
-      end
+      data = filter.call(data) if filter
 
       data
     end
@@ -52,6 +70,25 @@ module Backspin
         recorded_at: data["recorded_at"]
       )
     end
+
+    private
+
+    def scrub_args(args)
+      return args unless Backspin.configuration.scrub_credentials && args
+
+      args.map do |arg|
+        case arg
+        when String
+          Backspin.scrub_text(arg)
+        when Array
+          scrub_args(arg)
+        when Hash
+          arg.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
+        else
+          arg
+        end
+      end
+    end
   end
 end
 

data/lib/backspin/command_diff.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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
+
+    def initialize(recorded_command:, actual_result:, matcher: nil)
+      @recorded_command = recorded_command
+      @actual_result = actual_result
+      @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)
+      else
+        recorded_command.result == actual_result
+      end
+    end
+
+    # @return [String, nil] Human-readable diff if not verified
+    def diff
+      return nil if verified?
+
+      parts = []
+
+      parts << stdout_diff if recorded_command.stdout != actual_result.stdout
+
+      parts << stderr_diff if recorded_command.stderr != actual_result.stderr
+
+      if recorded_command.status != actual_result.status
+        parts << "Exit status: expected #{recorded_command.status}, got #{actual_result.status}"
+      end
+
+      parts.join("\n\n")
+    end
+
+    # @return [String] Single line summary for error messages
+    def summary
+      if verified?
+        "✓ Command verified"
+      else
+        "✗ Command failed: #{failure_reason}"
+      end
+    end
+
+    private
+
+    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
+      reasons.join(", ")
+    end
+
+    def stdout_diff
+      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_result.stdout)}"
+    end
+
+    def stderr_diff
+      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_result.stderr)}"
+    end
+
+    def generate_line_diff(expected, actual)
+      expected_lines = (expected || "").lines
+      actual_lines = (actual || "").lines
+
+      diff_lines = []
+      max_lines = [expected_lines.length, actual_lines.length].max
+
+      max_lines.times do |i|
+        expected_line = expected_lines[i]
+        actual_line = actual_lines[i]
+
+        if expected_line != actual_line
+          diff_lines << "-#{expected_line.chomp}" if expected_line
+          diff_lines << "+#{actual_line.chomp}" if actual_line
+        end
+      end
+
+      diff_lines.join("\n")
+    end
+  end
+end

data/lib/backspin/command_result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Represents the result of executing a command
+  # Stores stdout, stderr, and exit status
+  class CommandResult
+    attr_reader :stdout, :stderr, :status
+
+    def initialize(stdout:, stderr:, status:)
+      @stdout = stdout
+      @stderr = stderr
+      @status = normalize_status(status)
+    end
+
+    # @return [Boolean] true if the command succeeded (exit status 0)
+    def success?
+      status.zero?
+    end
+
+    # @return [Boolean] true if the command failed (non-zero exit status)
+    def failure?
+      !success?
+    end
+
+    # @return [Hash] Hash representation of the result
+    def to_h
+      {
+        "stdout" => stdout,
+        "stderr" => stderr,
+        "status" => status
+      }
+    end
+
+    # Compare two results for equality
+    def ==(other)
+      return false unless other.is_a?(CommandResult)
+
+      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)}>"
+    end
+
+    private
+
+    def normalize_status(status)
+      case status
+      when Integer
+        status
+      when Process::Status
+        status.exitstatus
+      else
+        status.respond_to?(:exitstatus) ? status.exitstatus : status.to_i
+      end
+    end
+  end
+end

data/lib/backspin/record.rb

@@ -4,6 +4,7 @@ module Backspin
   class NoMoreRecordingsError < StandardError; end
 
   class Record
+    FORMAT_VERSION = "2.0"
     attr_reader :path, :commands, :first_recorded_at
 
     def initialize(path)
@@ -22,10 +23,9 @@ module Backspin
 
     def save(filter: nil)
       FileUtils.mkdir_p(File.dirname(@path))
-      # New format: top-level metadata with commands array
       record_data = {
         "first_recorded_at" => @first_recorded_at,
-        "format_version" => "2.0",
+        "format_version" => FORMAT_VERSION,
         "commands" => @commands.map { |cmd| cmd.to_h(filter: filter) }
       }
       File.write(@path, record_data.to_yaml)

data/lib/backspin/record_result.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+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
+
+    def initialize(output:, mode:, record_path:, commands:, verified: nil, command_diffs: nil)
+      @output = output
+      @mode = mode
+      @record_path = record_path
+      @commands = commands
+      @verified = verified
+      @command_diffs = command_diffs || []
+    end
+
+    # @return [Boolean] true if this result is from recording
+    def recorded?
+      mode == :record
+    end
+
+    # @return [Boolean, nil] true/false for verification results, nil for recording
+    def verified?
+      @verified
+    end
+
+    # @return [Boolean] true if this result is from playback mode
+    def playback?
+      mode == :playback
+    end
+
+    # @return [String, nil] Human-readable error message if verification failed
+    def error_message
+      return nil unless verified? == false
+      return "No commands to verify" if command_diffs.empty?
+
+      failed_diffs = command_diffs.reject(&:verified?)
+      return "All commands verified" if failed_diffs.empty?
+
+      msg = "Output verification failed for #{failed_diffs.size} command(s):\n\n"
+
+      command_diffs.each_with_index do |diff, idx|
+        next if diff.verified?
+
+        msg += "Command #{idx + 1}: #{diff.summary}\n"
+        msg += diff.diff
+        msg += "\n\n" if idx < command_diffs.size - 1
+      end
+
+      msg
+    end
+
+    # @return [String, nil] Combined diff from all failed commands
+    def diff
+      return nil if command_diffs.empty?
+
+      failed_diffs = command_diffs.reject(&:verified?)
+      return nil if failed_diffs.empty?
+
+      diff_parts = []
+      command_diffs.each_with_index do |cmd_diff, idx|
+        diff_parts << "Command #{idx + 1}:\n#{cmd_diff.diff}" unless cmd_diff.verified?
+      end
+
+      diff_parts.join("\n\n")
+    end
+
+    # Convenience accessors for command output
+    # For single command (common case), these provide direct access
+    # For multiple commands, use all_stdout, all_stderr, etc.
+
+    # @return [String, nil] stdout from the first command
+    def stdout
+      commands.first&.result&.stdout
+    end
+
+    # @return [String, nil] stderr from the first command
+    def stderr
+      commands.first&.result&.stderr
+    end
+
+    # @return [Integer, nil] exit status from the first command
+    def status
+      commands.first&.result&.status
+    end
+
+    # Multiple command accessors
+
+    # @return [Array<String>] stdout from all commands
+    def all_stdout
+      commands.map { |cmd| cmd.result.stdout }
+    end
+
+    # @return [Array<String>] stderr from all commands
+    def all_stderr
+      commands.map { |cmd| cmd.result.stderr }
+    end
+
+    # @return [Array<Integer>] exit status from all commands
+    def all_status
+      commands.map { |cmd| cmd.result.status }
+    end
+
+    # @return [Boolean] true if this result contains multiple commands
+    def multiple_commands?
+      commands.size > 1
+    end
+
+    # @return [Boolean] true if all commands succeeded (exit status 0)
+    def success?
+      if multiple_commands?
+        # Check all commands - if any command has non-zero status, we're not successful
+        commands.all? { |cmd| cmd.result.status.zero? }
+      else
+        status&.zero? || false
+      end
+    end
+
+    # @return [Boolean] true if any command failed (non-zero exit status)
+    def failure?
+      !success?
+    end
+
+    # @return [Hash] Summary of the result for debugging
+    def to_h
+      hash = {
+        mode: mode,
+        recorded: recorded?,
+        playback: playback?,
+        stdout: stdout,
+        stderr: stderr,
+        status: status,
+        record_path: record_path.to_s
+      }
+
+      # 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

@@ -6,6 +6,7 @@ module Backspin
   # Handles stubbing and recording of command executions
   class Recorder
     include RSpec::Mocks::ExampleMethods
+    SUPPORTED_COMMAND_TYPES = [:capture3, :system]
 
     attr_reader :commands, :verification_data, :mode, :record
 
@@ -17,7 +18,7 @@ module Backspin
     end
 
     def record_calls(*command_types)
-      command_types = [:capture3, :system] if command_types.empty?
+      command_types = SUPPORTED_COMMAND_TYPES if command_types.empty?
 
       command_types.each do |command_type|
         record_call(command_type)
@@ -31,7 +32,7 @@ module Backspin
       when :capture3
         setup_capture3_call_stub
       else
-        raise ArgumentError, "Unknown command type: #{command_type}"
+        raise ArgumentError, "Unsupported command type: #{command_type} - currently supported types: #{SUPPORTED_COMMAND_TYPES.join(", ")}"
       end
     end
 
@@ -66,7 +67,6 @@ module Backspin
           # For system calls, we only track the exit status
           @verification_data["stdout"] = ""
           @verification_data["stderr"] = ""
-          # Derive exit status from result: true = 0, false = non-zero
           @verification_data["status"] = result ? 0 : 1
 
           result
@@ -107,12 +107,10 @@ module Backspin
       allow_any_instance_of(Object).to receive(:system) do |receiver, *args|
         command = @record.next_command
 
-        # Make sure this is a system command
         unless command.method_class == ::Kernel::System
           raise RecordNotFoundError, "Expected Kernel::System command but got #{command.method_class.name}"
         end
 
-        # Return true if exit status was 0, false otherwise
         command.status == 0
       rescue NoMoreRecordingsError => e
         raise RecordNotFoundError, e.message
@@ -121,17 +119,14 @@ module Backspin
 
     def setup_capture3_call_stub
       allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
-        # Execute the real command
         stdout, stderr, status = original_method.call(*args)
 
-        # Parse command args
         cmd_args = if args.length == 1 && args.first.is_a?(String)
           args.first.split(" ")
         else
           args
         end
 
-        # Create command with interaction data
         command = Command.new(
           method_class: Open3::Capture3,
           args: cmd_args,
@@ -142,17 +137,12 @@ module Backspin
         )
         @commands << command
 
-        # Store output for later access (last one wins)
-        Backspin.last_output = stdout
-
-        # Return original result
         [stdout, stderr, status]
       end
     end
 
     def setup_system_call_stub
       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)
 
         # Parse command args based on how system was called
@@ -164,14 +154,9 @@ module Backspin
           args
         end
 
-        # For system calls, stdout and stderr are not captured
-        # The caller of system() doesn't have access to them
-        stdout = ""
-        stderr = ""
-        # Derive exit status from result: true = 0, false = non-zero, nil = command failed
+        stdout, stderr = "", ""
         status = result ? 0 : 1
 
-        # Create command with interaction data
         command = Command.new(
           method_class: ::Kernel::System,
           args: parsed_args,
@@ -182,10 +167,6 @@ module Backspin
         )
         @commands << command
 
-        # Store output for later access (for consistency with capture3)
-        Backspin.last_output = stdout
-
-        # Return the original result (true/false/nil)
         result
       end
     end

data/lib/backspin/version.rb

@@ -1,3 +1,3 @@
 module Backspin
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end