simplecov-mcp 0.3.0 → 1.0.0

data/spec/spec_helper.rb

@@ -12,21 +12,82 @@ rescue LoadError
   warn 'SimpleCov not available; skipping coverage'
 end
 
-ENV.delete('SIMPLECOV_RESULTSET')
 
 require 'rspec'
 require 'pathname'
 require 'json'
 
-require 'simple_cov_mcp'
+require 'simplecov_mcp'
 
-FIXTURES = Pathname.new(File.expand_path('fixtures', __dir__))
+FIXTURES_DIR = Pathname.new(File.expand_path('fixtures', __dir__))
+
+# Test timestamp constants for consistent and documented test data
+# Main fixture coverage timestamp: 1720000000 = 2024-07-03 16:26:40 UTC
+# This represents when the coverage data in spec/fixtures/project1/coverage/.resultset.json was "generated"
+FIXTURE_COVERAGE_TIMESTAMP = 1_720_000_000
+
+# Very old timestamp: 0 = 1970-01-01 00:00:00 UTC (Unix epoch)
+# Used in tests to simulate stale coverage (much older than any real file)
+VERY_OLD_TIMESTAMP = 0
+
+# Test timestamps for stale error formatting tests
+# 1000 = 1970-01-01 00:16:40 UTC (16 minutes and 40 seconds after epoch)
+TEST_FILE_TIMESTAMP = 1_000
+
+# Regex pattern for matching ISO 8601 timestamps with brackets in log output
+# Used to verify log timestamps in tests
+TIMESTAMP_REGEX = /\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}\]/
+
+# Helper method to mock resultset file reading with fake coverage data
+# @param root [String] The test root directory
+# @param timestamp [Integer] The timestamp to use in the fake resultset
+# @param coverage [Hash] Optional custom coverage data (default: basic foo.rb and bar.rb)
+def mock_resultset_with_timestamp(root, timestamp, coverage: nil)
+  mock_resultset_with_metadata(root, { 'timestamp' => timestamp }, coverage: coverage)
+end
+
+def mock_resultset_with_created_at(root, created_at, coverage: nil)
+  mock_resultset_with_metadata(root, { 'created_at' => created_at }, coverage: coverage)
+end
+
+def mock_resultset_with_metadata(root, metadata, coverage: nil)
+  abs_root = File.absolute_path(root)
+  default_coverage = {
+    File.join(root, 'lib', 'foo.rb') => { 'lines' => [1, 0, nil, 2] },
+    File.join(root, 'lib', 'bar.rb') => { 'lines' => [0, 0, 1] }
+  }
+
+  fake_resultset = {
+    'RSpec' => {
+      'coverage' => coverage || default_coverage
+    }.merge(metadata)
+  }
+
+  allow(File).to receive(:read).and_call_original
+  allow(File).to receive(:read).with(end_with('.resultset.json')).and_return(fake_resultset.to_json)
+  allow(SimpleCovMcp::CovUtil).to receive(:find_resultset)
+    .and_wrap_original do |method, search_root, resultset: nil|
+    if File.absolute_path(search_root) == abs_root && (resultset.nil? || resultset.to_s.empty?)
+      File.join(abs_root, 'coverage', '.resultset.json')
+    else
+      method.call(search_root, resultset: resultset)
+    end
+  end
+end
+
+# Automatically require all files in spec/support and spec/shared_examples
+Dir[File.join(__dir__, 'support', '**', '*.rb')].sort.each { |f| require f }
+Dir[File.join(__dir__, 'shared_examples', '**', '*.rb')].sort.each { |f| require f }
 
 RSpec.configure do |config|
   config.example_status_persistence_file_path = '.rspec_status'
   config.disable_monkey_patching!
-  config.order = :random
+  config.order = :defined
   Kernel.srand config.seed
+
+  # Suppress logging during tests by redirecting to a null device
+  SimpleCovMcp.default_log_file = File::NULL
+  SimpleCovMcp.active_log_file = File::NULL
 end
 
 # Shared test helpers
@@ -42,8 +103,90 @@ module TestIOHelpers
     $stdout = original_stdout
     $stderr = original_stderr
   end
+
+  # Stub staleness checking to return a specific value
+  # @param value [String, false] The staleness value to return ('L', 'T', 'M', or false)
+  def stub_staleness_check(value)
+    checker_double = instance_double(SimpleCovMcp::StalenessChecker)
+    allow(checker_double).to receive_messages(stale_for_file?: value, off?: false)
+    allow(checker_double).to receive(:check_file!)
+    allow(SimpleCovMcp::StalenessChecker).to receive(:new).and_return(checker_double)
+  end
 end
 
+# CLI test helpers
+module CLITestHelpers
+  # Run CLI with the given arguments and return [stdout, stderr, exit_status]
+  def run_cli_with_status(*argv)
+    cli = SimpleCovMcp::CoverageCLI.new
+    status = nil
+    out_str = err_str = nil
+    silence_output do |out, err|
+      begin
+        cli.run(argv.flatten)
+        status = 0
+      rescue SystemExit => e
+        status = e.status
+      end
+      out_str = out.string
+      err_str = err.string
+    end
+    [out_str, err_str, status]
+  end
+end
+
+# MCP Tool shared examples and helpers
+module MCPToolTestHelpers
+  def setup_mcp_response_stub
+    # Standardized MCP::Tool::Response stub that works for all tools
+    response_class = Class.new do
+      attr_reader :payload, :meta
+
+      def initialize(payload, meta: nil)
+        @payload = payload
+        @meta = meta
+      end
+    end
+    stub_const('MCP::Tool::Response', response_class)
+  end
+
+  def expect_mcp_text_json(response, expected_keys: [])
+    item = response.payload.first
+
+    # Check for a 'text' part
+    expect(item['type']).to eq('text')
+    expect(item).to have_key('text')
+
+    # Parse and validate JSON content
+    data = JSON.parse(item['text'])
+
+    # Check for expected keys
+    expected_keys.each do |key|
+      expect(data).to have_key(key)
+    end
+
+    [data, item] # Return for additional custom assertions
+  end
+end
+
+
+
 RSpec.configure do |config|
   config.include TestIOHelpers
+  config.include CLITestHelpers
+  config.include MCPToolTestHelpers
+end
+
+# Custom matchers
+RSpec::Matchers.define :show_source_table_or_fallback do
+  match do |output|
+    has_table_header = output.match?(/(^|\n)\s*Line\s+\|\s+Source/)
+    has_fallback = output.include?('[source not available]')
+    has_table_header || has_fallback
+  end
+
+  failure_message do |output|
+    "expected output to include a source table header (e.g., 'Line | Source') " \
+      "or the fallback '[source not available]'"
+  end
 end

data/spec/staleness_checker_spec.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'fileutils'
+
+RSpec.describe SimpleCovMcp::StalenessChecker do
+  let(:tmpdir) { Dir.mktmpdir('scmcp-stale') }
+  after { FileUtils.remove_entry(tmpdir) if tmpdir && File.directory?(tmpdir) }
+
+  def write_file(path, lines)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, 'w') { |f| lines.each { |l| f.puts(l) } }
+  end
+
+  shared_examples 'a staleness check' do |
+    description:,
+    file_lines:,
+    coverage_lines:,
+    timestamp:,
+    expected_details:,
+    expected_stale_char:,
+    expected_error:
+  |
+    it description do
+      file = File.join(tmpdir, 'lib', 'test.rb')
+      write_file(file, file_lines) if file_lines
+
+      ts = if timestamp == :past
+        now = Time.now
+        past = Time.at(now.to_i - 3600)
+        File.utime(past, past, file)
+        now
+      else
+        timestamp
+      end
+
+      checker = described_class.new(root: tmpdir, resultset: nil, mode: 'error',
+        tracked_globs: nil, timestamp: ts)
+
+      details = checker.send(:compute_file_staleness_details, file, coverage_lines)
+
+      expected_details.each do |key, value|
+        if value == :any
+          expect(details).to have_key(key)
+        else
+          expect(details[key]).to eq(value)
+        end
+      end
+
+      expect(checker.stale_for_file?(file, coverage_lines)).to eq(expected_stale_char)
+
+      if expected_error
+        expect { checker.check_file!(file, coverage_lines) }.to raise_error(expected_error)
+      else
+        expect { checker.check_file!(file, coverage_lines) }.not_to raise_error
+      end
+    end
+  end
+
+  context 'compute_file_staleness_details' do
+    include_examples 'a staleness check',
+      description: 'detects newer file vs coverage timestamp',
+      file_lines: ['a', 'b'],
+      coverage_lines: [1, 1],
+      timestamp: Time.at(Time.now.to_i - 3600),
+      expected_details: {
+        exists: true,
+        cov_len: 2,
+        src_len: 2,
+        newer: true,
+        len_mismatch: false,
+        file_mtime: :any,
+        coverage_timestamp: :any
+      },
+      expected_stale_char: 'T',
+      expected_error: SimpleCovMcp::CoverageDataStaleError
+
+    include_examples 'a staleness check',
+      description: 'detects length mismatch between source and coverage',
+      file_lines: ['a', 'b', 'c', 'd'],
+      coverage_lines: [1, 1],
+      timestamp: Time.now,
+      expected_details: {
+        exists: true,
+        cov_len: 2,
+        src_len: 4,
+        newer: false,
+        len_mismatch: true,
+        file_mtime: :any,
+        coverage_timestamp: :any
+      },
+      expected_stale_char: 'L',
+      expected_error: SimpleCovMcp::CoverageDataStaleError
+
+    include_examples 'a staleness check',
+      description: 'treats missing file as stale',
+      file_lines: nil,
+      coverage_lines: [1, 1, 1],
+      timestamp: Time.now,
+      expected_details: {
+        exists: false,
+        newer: false,
+        len_mismatch: true,
+        file_mtime: nil,
+        coverage_timestamp: :any
+      },
+      expected_stale_char: 'M',
+      expected_error: SimpleCovMcp::CoverageDataStaleError
+
+    include_examples 'a staleness check',
+      description: 'is not stale when timestamps and lengths match',
+      file_lines: ['a', 'b', 'c'],
+      coverage_lines: [1, 0, nil],
+      timestamp: :past,
+      expected_details: {
+        exists: true,
+        newer: false,
+        len_mismatch: false,
+        file_mtime: :any,
+        coverage_timestamp: :any
+      },
+      expected_stale_char: false,
+      expected_error: nil
+  end
+
+  context 'missing_trailing_newline? edge cases' do
+    let(:checker) do
+      described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
+    end
+
+    it 'detects file without trailing newline' do
+      file = File.join(tmpdir, 'no_newline.rb')
+      File.write(file, 'line1')
+      expect(checker.send(:missing_trailing_newline?, file)).to be true
+    end
+
+    it 'detects file with trailing newline (LF)' do
+      file = File.join(tmpdir, 'with_newline.rb')
+      File.write(file, "line1\n")
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles file with CRLF endings (Windows-style)' do
+      file = File.join(tmpdir, 'crlf.rb')
+      File.write(file, "line1\r\nline2\r\n", mode: 'wb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles file ending with CRLF but no final newline' do
+      file = File.join(tmpdir, 'crlf_no_final.rb')
+      File.write(file, "line1\r\nline2", mode: 'wb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be true
+    end
+
+    it 'handles empty file' do
+      file = File.join(tmpdir, 'empty.rb')
+      File.write(file, '')
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles file with mixed line endings' do
+      file = File.join(tmpdir, 'mixed.rb')
+      File.write(file, "line1\nline2\r\nline3\n", mode: 'wb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'returns false for non-existent file' do
+      file = File.join(tmpdir, 'nonexistent.rb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles errors gracefully' do
+      file = File.join(tmpdir, 'test.rb')
+      File.write(file, 'content')
+
+      # Mock File.open to raise an error
+      allow(File).to receive(:open).with(file, 'rb').and_raise(StandardError.new('IO error'))
+
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles binary files that end with newline' do
+      file = File.join(tmpdir, 'binary.dat')
+      File.write(file, "\x00\x01\x02\x0A", mode: 'wb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be false
+    end
+
+    it 'handles binary files that do not end with newline' do
+      file = File.join(tmpdir, 'binary_no_newline.dat')
+      File.write(file, "\x00\x01\x02\xFF", mode: 'wb')
+      expect(checker.send(:missing_trailing_newline?, file)).to be true
+    end
+  end
+
+  context 'line count adjustment with missing trailing newline' do
+    let(:checker) do
+      described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
+    end
+
+    it 'adjusts line count when file has no trailing newline and counts differ by 1' do
+      file = File.join(tmpdir, 'adjust.rb')
+      # Write 3 lines without final newline
+      File.write(file, "line1\nline2\nline3")
+
+      # Coverage has 3 lines, file counts as 3 lines (no newline at end)
+      # but File.foreach will count 3 iterations
+      coverage_lines = [1, 0, 1]
+      details = checker.send(:compute_file_staleness_details, file, coverage_lines)
+
+      expect(details[:len_mismatch]).to be false
+    end
+
+    it 'does not adjust when file has trailing newline' do
+      file = File.join(tmpdir, 'no_adjust.rb')
+      # Write 3 lines with final newline
+      File.write(file, "line1\nline2\nline3\n")
+
+      # Coverage has 3 lines, file also counts as 3 lines (foreach counts by separator)
+      coverage_lines = [1, 0, 1]
+      details = checker.send(:compute_file_staleness_details, file, coverage_lines)
+
+      # No mismatch - both are 3 lines
+      expect(details[:src_len]).to eq(3)
+      expect(details[:cov_len]).to eq(3)
+      expect(details[:len_mismatch]).to be false
+    end
+
+    it 'does not adjust when difference is more than 1' do
+      file = File.join(tmpdir, 'big_diff.rb')
+      File.write(file, "line1\nline2\nline3\nline4\nline5")
+
+      coverage_lines = [1, 0, 1]
+      details = checker.send(:compute_file_staleness_details, file, coverage_lines)
+
+      expect(details[:len_mismatch]).to be true
+    end
+
+    it 'does not adjust when coverage is empty' do
+      file = File.join(tmpdir, 'empty_cov.rb')
+      File.write(file, "line1\nline2")
+
+      coverage_lines = []
+      details = checker.send(:compute_file_staleness_details, file, coverage_lines)
+
+      expect(details[:len_mismatch]).to be false
+    end
+  end
+
+  context 'safe_count_lines edge cases' do
+    let(:checker) do
+      described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
+    end
+
+    it 'returns 0 for non-existent file' do
+      file = File.join(tmpdir, 'nonexistent.rb')
+      expect(checker.send(:safe_count_lines, file)).to eq(0)
+    end
+
+    it 'handles errors gracefully' do
+      file = File.join(tmpdir, 'test.rb')
+      File.write(file, "line1\nline2\n")
+
+      # Mock File.foreach to raise an error
+      allow(File).to receive(:foreach).with(file).and_raise(StandardError.new('IO error'))
+
+      expect(checker.send(:safe_count_lines, file)).to eq(0)
+    end
+
+    it 'counts lines correctly for file with final newline' do
+      file = File.join(tmpdir, 'with_newline.rb')
+      File.write(file, "line1\nline2\nline3\n")
+      # File.foreach counts 3 iterations (by line separator)
+      expect(checker.send(:safe_count_lines, file)).to eq(3)
+    end
+
+    it 'counts lines correctly for file without final newline' do
+      file = File.join(tmpdir, 'no_newline.rb')
+      File.write(file, "line1\nline2\nline3")
+      # File.foreach counts 3 iterations
+      expect(checker.send(:safe_count_lines, file)).to eq(3)
+    end
+
+    it 'returns 0 for empty file' do
+      file = File.join(tmpdir, 'empty.rb')
+      File.write(file, '')
+      expect(checker.send(:safe_count_lines, file)).to eq(0)
+    end
+  end
+
+  context 'rel method with path prefix mismatches' do
+    let(:checker) do
+      described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
+    end
+
+    it 'returns relative path for files within project root' do
+      file_inside = File.join(tmpdir, 'lib', 'test.rb')
+      expect(checker.send(:rel, file_inside)).to eq('lib/test.rb')
+    end
+
+    it 'handles ArgumentError when path prefixes differ (absolute vs relative)' do
+      # Test the specific ArgumentError scenario: absolute path vs relative root
+      # This simulates the bug scenario where coverage data has absolute paths
+      # but the root is somehow processed as relative (edge case)
+      checker_with_relative_root = described_class.new(root: '.', resultset: nil, mode: 'off',
+        timestamp: Time.now)
+
+      # Override the @root to simulate the edge case where it's still relative
+      checker_with_relative_root.instance_variable_set(:@root, './subdir')
+
+      file_absolute = '/opt/shared_libs/utils/validation.rb'
+
+      # This should trigger the ArgumentError rescue and return the absolute path
+      expect(checker_with_relative_root.send(:rel, file_absolute))
+        .to eq('/opt/shared_libs/utils/validation.rb')
+    end
+
+    it 'handles relative file paths with absolute root' do
+      file_relative = './lib/test.rb'
+
+      # This should work fine (both are converted to absolute internally)
+      expect { checker.send(:rel, file_relative) }.not_to raise_error
+    end
+
+    it 'works with check_file! when rel encounters ArgumentError' do
+      # Test the specific case where rel() would crash with ArgumentError
+      # Instead of testing the full check_file! flow, just test that rel() works
+
+      checker_with_edge_case = described_class.new(root: '.', resultset: nil, mode: 'off',
+        timestamp: Time.now)
+      checker_with_edge_case.instance_variable_set(:@root, './subdir')
+
+      file_outside = '/opt/company_gem/lib/core.rb'
+
+      # This should trigger the ArgumentError and return the absolute path
+      # instead of crashing with ArgumentError
+      result = checker_with_edge_case.send(:rel, file_outside)
+      expect(result).to eq('/opt/company_gem/lib/core.rb')
+
+      # Verify it doesn't raise ArgumentError
+      expect { checker_with_edge_case.send(:rel, file_outside) }.not_to raise_error
+    end
+
+    it 'handles files outside project root gracefully (returns relative path with ..)' do
+      # Test that normal "outside but compatible" paths still work
+      file_outside = '/tmp/external_file.rb'
+
+      # This should return a relative path with .. (not trigger ArgumentError)
+      result = checker.send(:rel, file_outside)
+      expect(result).to include('..') # Should contain relative navigation
+      expect(result).not_to start_with('/') # Should be relative, not absolute
+    end
+
+    it 'allows project-level staleness checks to handle coverage outside root' do
+      future_time = Time.at(Time.now.to_i + 3600)
+      checker_with_relative_root = described_class.new(root: '.', resultset: nil, mode: 'error',
+        timestamp: future_time)
+      checker_with_relative_root.instance_variable_set(:@root, './subdir')
+
+      external_dir = Dir.mktmpdir('scmcp-outside')
+
+      begin
+        external_file = File.join(external_dir, 'shared.rb')
+        File.write(external_file, "puts 'hi'\n")
+
+        coverage_map = { external_file => [1] }
+
+        expect { checker_with_relative_root.check_project!(coverage_map) }.not_to raise_error
+      ensure
+        FileUtils.remove_entry(external_dir) if external_dir && File.directory?(external_dir)
+      end
+    end
+  end
+end

data/spec/staleness_more_spec.rb

@@ -3,37 +3,40 @@
 require 'spec_helper'
 
 RSpec.describe 'Additional staleness cases' do
-  let(:root) { (FIXTURES / 'project1').to_s }
+  let(:root) { (FIXTURES_DIR / 'project1').to_s }
 
   describe SimpleCovMcp::CoverageModel do
     it 'raises file-level stale when source and coverage lengths differ' do
-      # Ensure time is not the triggering factor
-      allow(SimpleCovMcp::CovUtil).to receive(:latest_timestamp).and_return(Time.now.to_i)
+      # Ensure time is not the triggering factor - use current timestamp
+      mock_resultset_with_timestamp(root, Time.now.to_i, coverage: {
+        File.join(root, 'lib', 'bar.rb') => { 'lines' => [1, 1] } # 2 entries vs 3 lines in source
+      })
       model = SimpleCovMcp::CoverageModel.new(root: root, resultset: 'coverage', staleness: 'error')
-      # bar.rb has 3 coverage entries but 4 source lines in fixtures
-      expect {
+      # bar.rb has 2 coverage entries but 3 source lines in fixtures
+      expect do
         model.summary_for('lib/bar.rb')
-      }.to raise_error(SimpleCovMcp::CoverageDataStaleError, /stale/i)
+      end.to raise_error(SimpleCovMcp::CoverageDataStaleError, /stale/i)
     end
   end
 
   describe SimpleCovMcp::StalenessChecker do
     it 'flags deleted files present only in coverage' do
-      checker = described_class.new(root: root, resultset: 'coverage', mode: 'error')
+      checker = described_class.new(root: root, resultset: 'coverage', mode: 'error',
+        timestamp: Time.now.to_i)
       coverage_map = {
         File.join(root, 'lib', 'does_not_exist_anymore.rb') => { 'lines' => [1] }
       }
-      expect {
+      expect do
         checker.check_project!(coverage_map)
-      }.to raise_error(SimpleCovMcp::CoverageDataProjectStaleError)
+      end.to raise_error(SimpleCovMcp::CoverageDataProjectStaleError)
     end
 
     it 'does not raise for empty tracked_globs when nothing else is stale' do
-      allow(SimpleCovMcp::CovUtil).to receive(:latest_timestamp).and_return(Time.now.to_i)
-      checker = described_class.new(root: root, resultset: 'coverage', mode: 'error', tracked_globs: [])
-      expect {
+      checker = described_class.new(root: root, resultset: 'coverage', mode: 'error',
+        tracked_globs: [], timestamp: Time.now.to_i)
+      expect do
         checker.check_project!({})
-      }.not_to raise_error
+      end.not_to raise_error
     end
   end
 end

data/spec/support/mcp_runner.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+require 'json'
+
+module Spec
+  module Support
+    module McpRunner
+      # Thin wrapper around `Open3.popen3` that standardizes how the integration
+      # specs talk to the `simplecov-mcp` executable. It accepts either a single
+      # JSON-RPC request hash, a sequence of requests, or raw string input,
+      # writes them to the subprocess stdin (ensuring a trailing newline), then
+      # collects stdout, stderr, and the exit status with a timeout. The helper
+      # always returns a hash containing those streams plus the `Process::Status`
+      # so callers can make assertions without duplicating the boilerplate.
+
+      module_function
+
+      def call(requests: nil, input: nil, env: {}, lib_path:, exe_path:, timeout: 5,
+        close_stdin: true)
+        payload = build_payload(requests, input)
+
+        stdout_str = ''
+        stderr_str = ''
+        status = nil
+
+        Open3.popen3(env, 'ruby', '-I', lib_path, exe_path) do |stdin, stdout, stderr, wait_thr|
+          unless payload.nil?
+            stdin.write(payload)
+            stdin.write("\n") if !payload.empty? && !payload.end_with?("\n")
+          end
+          stdin.close if close_stdin
+
+          Timeout.timeout(timeout) do
+            stdout_str = stdout.read
+            stderr_str = stderr.read
+            status = wait_thr.value
+          end
+        end
+
+        { stdout: stdout_str, stderr: stderr_str, status: status }
+      rescue Timeout::Error
+        raise "MCP server timed out after #{timeout} seconds"
+      end
+
+      def call_json(request_hash, **kwargs)
+        call(requests: request_hash, **kwargs)
+      end
+
+      def call_json_stream(request_hashes, **kwargs)
+        call(requests: Array(request_hashes), **kwargs)
+      end
+
+      def build_payload(requests, input)
+        return input unless requests
+
+        normalized = requests.is_a?(Array) ? requests : [requests]
+        normalized.map { |req| req.is_a?(String) ? req : JSON.generate(req) }.join("\n")
+      end
+      private_class_method :build_payload
+    end
+  end
+end