backspin 0.8.0 → 0.10.0

data/lib/backspin.rb

@@ -6,13 +6,12 @@ require "open3"
 require "pathname"
 require "backspin/version"
 require "backspin/configuration"
-require "backspin/command_result"
-require "backspin/command"
+require "backspin/snapshot"
 require "backspin/matcher"
 require "backspin/command_diff"
 require "backspin/record"
+require "backspin/backspin_result"
 require "backspin/recorder"
-require "backspin/record_result"
 
 module Backspin
   class RecordNotFoundError < StandardError; end
@@ -29,12 +28,12 @@ module Backspin
       result.diff
     end
 
-    def recorded_commands
-      result.command_diffs.map(&:recorded_command)
+    def expected_snapshot
+      result.expected
     end
 
-    def actual_commands
-      result.command_diffs.map(&:actual_command)
+    def actual_snapshot
+      result.actual
     end
   end
 
@@ -72,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
-    # @return [RecordResult] Result object with output and status
-    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, &block)
+    # @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, 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
@@ -92,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
-    # @return [RecordResult] Result object with captured output
-    def capture(record_name, mode: :auto, matcher: nil, filter: nil, &block)
+    # @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, 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)
@@ -114,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
@@ -130,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)
@@ -146,8 +158,8 @@ module Backspin
       result = case mode
       when :record
         stdout, stderr, status = execute_command(command, normalized_env)
-        command_result = Command.new(
-          method_class: Open3::Capture3,
+        actual_snapshot = Snapshot.new(
+          command_type: Open3::Capture3,
           args: command,
           env: normalized_env,
           stdout: stdout,
@@ -155,37 +167,47 @@ module Backspin
           status: status.exitstatus,
           recorded_at: Time.now.iso8601
         )
-        record.add_command(command_result)
+        record.set_snapshot(actual_snapshot)
         record.save(filter: filter)
-        RecordResult.new(output: [stdout, stderr, status], mode: :record, record: record)
+        BackspinResult.new(
+          mode: :record,
+          record_path: record.path,
+          actual: actual_snapshot,
+          output: [stdout, stderr, status]
+        )
       when :verify
         raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
-        raise RecordNotFoundError, "No commands found in record #{record.path}" if record.empty?
-        if record.commands.size != 1
-          raise RecordFormatError, "Invalid record format: expected 1 command for run, found #{record.commands.size}"
-        end
+        raise RecordNotFoundError, "No snapshot found in record #{record.path}" if record.empty?
 
-        recorded_command = record.commands.first
-        unless recorded_command.method_class == Open3::Capture3
+        expected_snapshot = record.snapshot
+        unless expected_snapshot.command_type == Open3::Capture3
           raise RecordFormatError, "Invalid record format: expected Open3::Capture3 for run"
         end
 
         stdout, stderr, status = execute_command(command, normalized_env)
-        actual_command = Command.new(
-          method_class: Open3::Capture3,
+        actual_snapshot = Snapshot.new(
+          command_type: Open3::Capture3,
           args: command,
           env: normalized_env,
           stdout: stdout,
           stderr: stderr,
           status: status.exitstatus
         )
-        command_diff = CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: matcher)
-        RecordResult.new(
-          output: [stdout, stderr, status],
+        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,
+          actual: actual_snapshot,
+          expected: expected_snapshot,
           verified: command_diff.verified?,
-          record: record,
-          command_diffs: [command_diff]
+          command_diff: command_diff,
+          output: [stdout, stderr, status]
         )
       else
         raise ArgumentError, "Unknown mode: #{mode}"
@@ -218,7 +240,7 @@ module Backspin
       return unless configuration.raise_on_verification_failure && result.verified? == false
 
       error_message = "Backspin verification failed!\n"
-      error_message += "Record: #{result.record.path}\n"
+      error_message += "Record: #{result.record_path}\n"
       details = result.error_message || result.diff
       error_message += "\n#{details}" if details
 
@@ -239,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.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -37,6 +37,7 @@ files:
 - bin/rake
 - bin/rspec
 - bin/setup
+- docs/backspin-result-api-sketch.md
 - examples/match_on_example.rb
 - fixtures/backspin/all_and_fields.yml
 - fixtures/backspin/all_bypass_equality.yml
@@ -94,14 +95,13 @@ files:
 - fixtures/backspin/verify_system_diff.yml
 - fixtures/backspin/version_test.yml
 - lib/backspin.rb
-- lib/backspin/command.rb
+- lib/backspin/backspin_result.rb
 - lib/backspin/command_diff.rb
-- lib/backspin/command_result.rb
 - lib/backspin/configuration.rb
 - lib/backspin/matcher.rb
 - lib/backspin/record.rb
-- lib/backspin/record_result.rb
 - lib/backspin/recorder.rb
+- lib/backspin/snapshot.rb
 - lib/backspin/version.rb
 - release.rake
 - script/lint

data/lib/backspin/command.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "command_result"
-
-module Backspin
-  class Command
-    attr_reader :args, :env, :result, :recorded_at, :method_class
-
-    def initialize(method_class:, args:, env: nil, stdout: nil, stderr: nil, status: nil, result: nil, recorded_at: nil)
-      @method_class = method_class
-      @args = args
-      @env = env
-      @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" => scrub_args(@args),
-        "stdout" => Backspin.scrub_text(@result.stdout),
-        "stderr" => Backspin.scrub_text(@result.stderr),
-        "status" => @result.status,
-        "recorded_at" => @recorded_at
-      }
-
-      data["env"] = scrub_env(@env) if @env
-
-      # Apply filter if provided
-      data = filter.call(data) if filter
-
-      data
-    end
-
-    # Create from hash (for loading from YAML)
-    def self.from_h(data)
-      # Determine method class from command_type
-      method_class = case data["command_type"]
-      when "Open3::Capture3"
-        Open3::Capture3
-      when "Backspin::Capturer"
-        Backspin::Capturer
-      else
-        raise RecordFormatError, "Unknown command type: #{data["command_type"]}"
-      end
-
-      new(
-        method_class: method_class,
-        args: data["args"],
-        env: data["env"],
-        stdout: data["stdout"],
-        stderr: data["stderr"],
-        status: data["status"],
-        recorded_at: data["recorded_at"]
-      )
-    end
-
-    private
-
-    def scrub_args(args)
-      return args unless Backspin.configuration.scrub_credentials && args
-
-      case args
-      when String
-        Backspin.scrub_text(args)
-      when Array
-        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
-      when Hash
-        args.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
-      else
-        args
-      end
-    end
-
-    def scrub_env(env)
-      return env unless Backspin.configuration.scrub_credentials && env
-
-      env.transform_values { |value| value.is_a?(String) ? Backspin.scrub_text(value) : value }
-    end
-  end
-end
-
-# Define the Open3::Capture3 class for identification
-module Open3
-  class Capture3; end
-end
-
-# Define the Backspin::Capturer class for identification
-module Backspin
-  class Capturer; end
-end

data/lib/backspin/command_result.rb

@@ -1,58 +0,0 @@
-# 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} stderr=#{stderr}>"
-    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_result.rb

@@ -1,153 +0,0 @@
-# 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, :commands, :mode, :command_diffs
-    attr_reader :record
-
-    def initialize(output:, mode:, record:, verified: nil, command_diffs: nil)
-      @output = output
-      @mode = mode
-      @record = record
-      @commands = record.commands
-      @verified = verified
-      @command_diffs = command_diffs || []
-    end
-
-    # @return [Boolean] true if this result is from recording
-    def recorded?
-      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
-
-    # @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?)
-      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?,
-        stdout: stdout,
-        stderr: stderr,
-        status: status
-      }
-
-      hash[:verified] = verified? unless verified?.nil?
-      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
-  end
-end