backspin 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3810a17b9b213b010cadd7419559fda50aed8dee3faad5865e824e765921339d
-  data.tar.gz: 400594d38ca7937da9095c78eb6578d5d384077a1cbbf78db97f06e133c6dcd0
+  metadata.gz: d2fd83cd35c05021e0df8e585060247f0bee2fd1034d43861bf462bbb1d67101
+  data.tar.gz: 1ee344e3596a9442d17dbbaab2aaa541d676fb2f734d13b28ad34d49948b684b
 SHA512:
-  metadata.gz: c2614110086b787c10b31504ae0eed80b32adc7a72d61709f6fba6245e093b35f92816227faebf781b3257e25b766c45676c47e74422176ae07fbc3eafaabce2
-  data.tar.gz: 6bb11f527a1aebc8ed495ccde7ca4deddf87b33f33f160cf76da13e02bc994e9b397cbaa59df2f30656cbd4a589ea70ebe24194743ac96a9b639fcda4cd9bf22
+  metadata.gz: 9be21d06b0087032243e2df85bfffa060fa9a8f411ce4733a125fffbdbe40ac58d2637d1f18f9b70831730917ef9aa0baff38f6021439d37c444984f7acee886
+  data.tar.gz: 2720731b166213d551c0dd58e7478e23d20637b1d4157945fcac090298ff5059fdce1c86e3e98e20087fc5bd27de52a522b35e1a124158c914c23ede4fa53dfe

data/.circleci/config.yml

@@ -12,14 +12,22 @@ jobs:
       ruby-version:
         type: string
     docker:
-      - image: cimg/ruby:<< parameters.ruby-version >>
+      - image: ghcr.io/jdx/mise:2026.9.15-debian
+    environment:
+      MISE_RUBY_VERSION: << parameters.ruby-version >>
+      MISE_YES: "1"
     steps:
       - checkout
+      - run:
+          name: Install project tools
+          command: |
+            apt-get update && apt-get install -y --no-install-recommends build-essential libyaml-dev
+            mise install
       - ruby/install-deps:
-          key: gems-v1-ruby<< parameters.ruby-version >>
+          key: gems-v2-mise-ruby<< parameters.ruby-version >>
       - run:
-          name: Run specs
-          command: bundle exec rake spec
+          name: Run specs with Plur
+          command: plur spec
       - run:
           name: Run fake gem specs
           command: bundle exec rake spec:fake_gem

data/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      previous-ref:
+        description: Tag or commit before the version increase (for retrying an unpublished release)
+        required: true
+        type: string
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: rsanheim/.github/.github/workflows/gem-release.yml@4ced52859dd60019b930a3f2023424e77b37ee2a
+    with:
+      gem: backspin
+      ruby-version: "4.0.0"

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.14.0
+* Improved verification errors with per-field summaries for stdout, stderr, and exit status, plus three lines of context around output changes. Long diffs are limited to 50 lines; set `BACKSPIN_FULL_DIFF=1` to show the full diff.
+* Preserved custom matcher failure reasons and made missing final newlines visible in output diffs.
+* Fixed `backspin_dir` configuration to accept String paths as well as Pathname objects.
+
 ## 0.13.0
 * Added `Backspin.compare(reference:, actual:)` for differential testing - runs both commands live and compares their filtered output, with no record file. Only stdout, stderr, and exit status are compared, so the two commands may differ in argv and env without normalization.
 * Added `Backspin::ReferenceCommandError`, raised when a compare's reference command produces no output at all (usually a sign it failed to start), rather than comparing empty to empty.

data/CLAUDE.md

@@ -24,9 +24,11 @@ bin/rspec spec/[file]:[line]    # Run specific test
 ### Building and Releasing
 ```bash
 bin/rake install     # Install gem locally for testing
-bin/rake release     # Release to RubyGems (updates version, tags, pushes)
+bin/rake build       # Build the gem locally
 ```
 
+Releases use a pull request that updates `lib/backspin/version.rb` and adds a matching nonempty section to `CHANGELOG.md`. Use normal premerge CI to establish readiness. After merge to `main`, the shared GitHub Actions workflow rechecks the version and changelog, invokes `rubygems/release-gem@v1` and Bundler for tagging and gem publication, then creates the GitHub release from the changelog notes. Invalid release notes prevent publication. See `CONTRIBUTING.md` for trusted publisher setup.
+
 ### Code Quality
 ```bash
 script/lint                      # Run Standard Ruby linter

data/CONTRIBUTING.md

@@ -11,6 +11,7 @@ Note that Backspin is in early development and the API _will_ change before stab
 - [Making Changes](#making-changes)
 - [Testing](#testing)
 - [Submitting Changes](#submitting-changes)
+- [Release Maintainer Setup](#release-maintainer-setup)
 - [Code Style](#code-style)
 - [Reporting Issues](#reporting-issues)
 - [Feature Requests](#feature-requests)
@@ -161,6 +162,25 @@ end
 - Update examples in README.md if changing public APIs
 - Ensure CI passes (tests against Ruby 3.2, 3.3, 3.4, and 4.0)
 
+## Release Maintainer Setup
+
+Before the first automated release, configure a RubyGems trusted publisher for the `backspin` gem using the [reusable workflow setup](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows):
+
+- Repository owner: `rsanheim`
+- Repository name: `backspin`
+- Workflow filename: `gem-release.yml`
+- Workflow Repository Owner: `rsanheim`
+- Workflow Repository Name: `.github`
+- Environment: `release`
+
+The workflow filename identifies the shared reusable workflow. The caller is `.github/workflows/release.yml`, which grants GitHub OIDC permission (`id-token: write`). No long-lived RubyGems API key is needed.
+
+Release pull requests update `lib/backspin/version.rb` and add a nonempty `## VERSION` section to `CHANGELOG.md`; the section body becomes the GitHub release notes. Keep the version change and its notes in the same pull request. Use the normal premerge CI checks to establish release readiness. Merging to `main` starts the release workflow, which rechecks the version and changelog before publishing; invalid release notes prevent publication. Ordinary merges do not publish anything.
+
+If publication fails before the gem is uploaded, fix the cause and manually run the Release workflow on `main`, setting `previous-ref` to the tag before the version increase. Confirm the target version is still unpublished before retrying.
+
+The shared release workflow is pinned in `.github/workflows/release.yml`. Update that commit deliberately when adopting shared release changes. Bundler's standard `build`, `install`, and `release` tasks remain available; the automated workflow is the normal publishing path.
+
 ## Code Style
 
 Backspin uses [Standard Ruby](https://github.com/standardrb/standard) for code formatting. Run the linter before committing:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.13.0)
+    backspin (0.14.0)
       logger
 
 GEM

data/README.md

@@ -253,6 +253,23 @@ result.error_message  # Human-readable error if verification failed
 result.diff  # Diff between expected and actual output
 ```
 
+### Verification diffs
+
+Verification errors include the failure reason and a summary of changes to stdout, stderr,
+and exit status. Output diffs show three lines of context around each change, with `...`
+where unchanged lines are omitted. A `\ No newline at end of output` marker identifies
+output without a final newline.
+
+Diffs are limited to 50 lines by default. To see every diff line, run your tests with:
+
+```sh
+BACKSPIN_FULL_DIFF=1 bundle exec rake spec
+```
+
+The limit applies to `result.diff` and the diff portion of `result.error_message`. The
+environment variable removes the size limit; unchanged lines outside the context windows
+are still omitted.
+
 ### Configuration
 
 You can configure Backspin's behavior globally:
@@ -344,16 +361,24 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 This repo also includes a decoupled full-stack fixture gem at `fixtures/projects/dummy_cli_gem` that uses Backspin the way downstream projects do. Run it with:
 
 ```bash
-bundle exec rake full_stack:dummy_app
+bundle exec rake spec:fake_gem
 ```
 
 To re-record that fixture's committed YAML snapshots:
 
 ```bash
-bundle exec rake full_stack:record_dummy_app
+bundle exec rake spec:fake_gem_record
 ```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Releasing
+
+Open a pull request that updates `lib/backspin/version.rb` and adds a nonempty matching version section to `CHANGELOG.md` (for example, `## 0.14.0`). CI checks the effective gemspec version and fails if a version change has no release notes.
+
+Use the normal premerge CI checks to establish release readiness. After the pull request merges into `main`, the shared workflow rechecks the version and changelog, then invokes `rubygems/release-gem@v1`. The official action uses OIDC trusted publishing and Bundler's standard release task to build the gem, create and push `vVERSION`, and publish to RubyGems. After the action succeeds, the shared workflow creates a GitHub release using that changelog section. Invalid release notes prevent publication. Commits that leave the gem version unchanged do not trigger a release.
+
+The release implementation lives in [`rsanheim/.github`](https://github.com/rsanheim/.github) and is pinned to a commit in `.github/workflows/release.yml`. See [the maintainer setup](CONTRIBUTING.md#release-maintainer-setup) before enabling releases.
 
 ## Contributing
 

data/Rakefile

@@ -34,5 +34,3 @@ namespace :spec do
 end
 
 task default: %i[spec standard]
-
-load "release.rake" if File.exist?("release.rake")

data/fixtures/projects/dummy_cli_gem/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../../..
   specs:
-    backspin (0.13.0)
+    backspin (0.14.0)
       logger
 
 PATH
@@ -40,7 +40,7 @@ DEPENDENCIES
   rspec (~> 3)
 
 CHECKSUMS
-  backspin (0.13.0)
+  backspin (0.14.0)
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   dummy_cli_gem (0.1.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203

data/lib/backspin/backspin_result.rb

@@ -36,10 +36,18 @@ module Backspin
       return nil unless verified? == false
       return "Output verification failed" unless @command_diff
 
-      msg = "Output verification failed:\n\n"
-      msg += @command_diff.summary
-      msg += "\n#{@command_diff.diff}" if @command_diff.diff
-      msg
+      parts = ["Output verification failed:", @command_diff.summary, "", "Summary:"]
+      @command_diff.field_summary.each do |line|
+        parts << "  #{line}"
+      end
+
+      diff = @command_diff.diff
+      if diff && !diff.empty?
+        parts << ""
+        parts << diff
+      end
+
+      parts.join("\n")
     end
 
     def success?

data/lib/backspin/command_diff.rb

@@ -3,6 +3,9 @@
 module Backspin
   # Represents the difference between expected and actual snapshots.
   class CommandDiff
+    CONTEXT_LINES = 3
+    MAX_DIFF_LINES = 50
+
     attr_reader :expected, :actual, :matcher
 
     def initialize(expected:, actual:, matcher: nil, filter: nil, filter_on: :both)
@@ -26,6 +29,15 @@ module Backspin
       @verified = @matcher.match?
     end
 
+    # @return [Array<String>] Per-field change status lines
+    def field_summary
+      lines = []
+      lines << stdout_field_summary
+      lines << stderr_field_summary
+      lines << status_field_summary
+      lines
+    end
+
     # @return [String, nil] Human-readable diff if not verified
     def diff
       return nil if verified?
@@ -48,7 +60,8 @@ module Backspin
         parts << "Exit status: expected #{expected_compare.status}, got #{actual_compare.status}"
       end
 
-      parts.join("\n\n")
+      result = parts.join("\n\n")
+      maybe_truncate(result)
     end
 
     # @return [String] Single line summary for error messages
@@ -62,6 +75,30 @@ module Backspin
 
     private
 
+    def stdout_field_summary
+      if expected_compare.stdout == actual_compare.stdout
+        "stdout: unchanged"
+      else
+        "stdout: changed"
+      end
+    end
+
+    def stderr_field_summary
+      if expected_compare.stderr == actual_compare.stderr
+        "stderr: unchanged"
+      else
+        "stderr: changed"
+      end
+    end
+
+    def status_field_summary
+      if expected_compare.status == actual_compare.status
+        "status: unchanged"
+      else
+        "status: changed (expected #{expected_compare.status}, actual #{actual_compare.status})"
+      end
+    end
+
     def command_types_match?
       expected.command_type == actual.command_type
     end
@@ -83,25 +120,77 @@ module Backspin
     end
 
     def generate_line_diff(expected, actual)
-      expected_lines = (expected || "").lines
-      actual_lines = (actual || "").lines
+      expected_lines = split_lines(expected)
+      actual_lines = split_lines(actual)
+      max_lines = [expected_lines.length, actual_lines.length].max
+
+      changed = Array.new(max_lines, false)
+      max_lines.times do |i|
+        changed[i] = (expected_lines[i] != actual_lines[i])
+      end
+
+      visible = Array.new(max_lines, false)
+      max_lines.times do |i|
+        next unless changed[i]
+        range_start = [i - CONTEXT_LINES, 0].max
+        range_end = [i + CONTEXT_LINES, max_lines - 1].min
+        (range_start..range_end).each { |j| visible[j] = true }
+      end
 
       diff_lines = []
-      max_lines = [expected_lines.length, actual_lines.length].max
+      first_visible = visible.index(true)
+      diff_lines << "..." if first_visible&.positive?
+      in_hunk = false
 
       max_lines.times do |i|
-        expected_line = expected_lines[i]
-        actual_line = actual_lines[i]
+        unless visible[i]
+          if in_hunk
+            diff_lines << "..."
+            in_hunk = false
+          end
+          next
+        end
+
+        in_hunk = true
 
-        if expected_line != actual_line
-          diff_lines << "-#{expected_line.chomp}" if expected_line
-          diff_lines << "+#{actual_line.chomp}" if actual_line
+        if changed[i]
+          diff_lines << "-#{render_line(expected_lines[i])}" if i < expected_lines.length
+          diff_lines << "+#{render_line(actual_lines[i])}" if i < actual_lines.length
+        else
+          line = expected_lines[i] || actual_lines[i]
+          diff_lines << " #{render_line(line)}"
         end
       end
 
       diff_lines.join("\n")
     end
 
+    def split_lines(value)
+      (value || "").lines
+    end
+
+    def render_line(line)
+      rendered = line.to_s.chomp
+      return rendered if line.to_s.end_with?("\n")
+
+      "#{rendered}\n\\ No newline at end of output"
+    end
+
+    def maybe_truncate(diff_text)
+      return diff_text if full_diff?
+
+      lines = diff_text.lines
+      return diff_text if lines.length <= MAX_DIFF_LINES
+
+      truncated = lines.first(MAX_DIFF_LINES).join
+      truncated.chomp!
+      truncated + "\n(diff truncated, set BACKSPIN_FULL_DIFF=1 for full output)"
+    end
+
+    def full_diff?
+      ENV["BACKSPIN_FULL_DIFF"] == "1"
+    end
+
     attr_reader :expected_compare
 
     attr_reader :actual_compare

data/lib/backspin/configuration.rb

@@ -8,7 +8,7 @@ module Backspin
   class Configuration
     attr_accessor :scrub_credentials
     # The directory where backspin will store its files - defaults to fixtures/backspin
-    attr_accessor :backspin_dir
+    attr_reader :backspin_dir
     # Whether to raise an exception when verification fails in `run`/`capture` - defaults to true
     attr_accessor :raise_on_verification_failure
     # Logger for Backspin diagnostics - defaults to WARN level, logfmt-lite format
@@ -24,6 +24,10 @@ module Backspin
       @logger = default_logger
     end
 
+    def backspin_dir=(path)
+      @backspin_dir = Pathname.new(path)
+    end
+
     def add_credential_pattern(pattern)
       @credential_patterns << pattern
     end

data/lib/backspin/version.rb

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

data/mise.toml

@@ -1,2 +1,3 @@
 [tools]
 ruby = "4.0.0"
+"github:rsanheim/plur" = { version = "latest", minimum_release_age = "0s" }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -33,7 +33,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
-- ".gem_release.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
@@ -84,7 +84,6 @@ files:
 - lib/backspin/snapshot.rb
 - lib/backspin/version.rb
 - mise.toml
-- release.rake
 - script/lint
 homepage: https://github.com/rsanheim/backspin
 licenses:
@@ -107,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []

data/.gem_release.yml

@@ -1,13 +0,0 @@
-# Configuration for gem-release
-bump:
-  commit: true
-  message: "Bump version to %{version}"
-  skip_ci: false
-  push: true
-
-tag:
-  tag: v%{version}
-  sign: true
-
-release:
-  host: https://rubygems.org

data/release.rake

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-
-# Simplified release tasks using gem-release
-# Install with: gem install gem-release
-# https://github.com/svenfuchs/gem-release
-namespace :release do
-  desc "Release a new version (bump, tag, release)"
-  task :version, [:level] do |t, args|
-    level = args[:level] || "patch"
-
-    # Pre-release checks
-    # Rake::Task["release:check"].invoke
-
-    puts "\nReleasing #{level} version..."
-
-    # Use gem-release to bump, tag, and release to rubygems and github
-    sh "gem bump --version #{level}"
-    new_version = File.read("lib/backspin/version.rb").match(/VERSION = "(\d+\.\d+\.\d+)"/)[1]
-
-    sh "bundle install"
-    sh "git commit -am 'Bump version to #{new_version}'"
-    sh "git push"
-
-    sh "gem release --tag --push"
-    Rake::Task["release:github"].invoke(new_version)
-  end
-
-  desc "Create GitHub release for specified version or current version"
-  task :github, [:version] do |t, args|
-    version = args[:version] || Backspin::VERSION
-
-    if system("which gh > /dev/null 2>&1")
-      puts "\nCreating GitHub release for v#{version}..."
-      sh "gh release create v#{version} --title 'Release v#{version}' --generate-notes"
-    else
-      puts "\nGitHub CLI not found. Create release manually at:"
-      puts "https://github.com/rsanheim/backspin/releases/new?tag=v#{version}"
-    end
-  end
-
-  desc "Check if ready for release"
-  task :check do
-    require "open-uri"
-    require "json"
-
-    current_version = Backspin::VERSION
-    errors = []
-
-    # Check RubyGems for latest version
-    begin
-      gem_data = JSON.parse(URI.open("https://rubygems.org/api/v1/gems/backspin.json").read)
-      latest_version = gem_data["version"]
-
-      if Gem::Version.new(current_version) <= Gem::Version.new(latest_version)
-        errors << "Current version (#{current_version}) is not greater than latest released version (#{latest_version})"
-      else
-        puts "✓ Version #{current_version} is ready for release (latest: #{latest_version})"
-      end
-    rescue => e
-      puts "⚠ Could not check RubyGems version: #{e.message}"
-    end
-
-    # Check git status
-    if system("git diff --quiet && git diff --cached --quiet")
-      puts "✓ No uncommitted changes"
-    else
-      errors << "You have uncommitted changes"
-    end
-
-    # Check branch
-    current_branch = `git rev-parse --abbrev-ref HEAD`.strip
-    if current_branch != "main"
-      puts "⚠ Not on main branch (currently on #{current_branch})"
-      print "Continue anyway? (y/N): "
-      response = $stdin.gets.chomp
-      errors << "Not on main branch" unless response.downcase == "y"
-    else
-      puts "✓ On main branch"
-    end
-
-    unless errors.empty?
-      puts "\n❌ Cannot release:"
-      errors.each { |e| puts "  - #{e}" }
-      abort
-    end
-
-    puts "\n✅ All checks passed!"
-  end
-end
-
-# Convenience tasks
-desc "Release patch version"
-task "release:patch" => ["release:version"]
-
-desc "Release minor version"
-task "release:minor" do
-  Rake::Task["release:version"].invoke("minor")
-end
-
-desc "Release major version"
-task "release:major" do
-  Rake::Task["release:version"].invoke("major")
-end