cov-loupe 3.0.0

data/spec/spec_helper.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Enable SimpleCov for this project (coverage output in ./coverage)
+begin
+  require 'simplecov'
+  SimpleCov.start do
+    enable_coverage :branch if SimpleCov.respond_to?(:enable_coverage)
+    add_filter(/^\/spec\//)
+    track_files 'lib/**/*.rb'
+  end
+
+  # Report lowest coverage files at the end of the test run
+  SimpleCov.at_exit do
+    SimpleCov.result.format!
+    require 'cov_loupe'
+    report = CovLoupe::CoverageReporter.report(threshold: 80, count: 5)
+    puts report if report
+  end
+rescue LoadError
+  warn 'SimpleCov not available; skipping coverage'
+end
+
+
+require 'rspec'
+require 'pathname'
+require 'json'
+
+require 'cov_loupe'
+
+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_hash = {
+    'RSpec' => {
+      'coverage' => coverage || default_coverage
+    }.merge(metadata)
+  }
+
+  allow(JSON).to receive(:load_file).and_call_original # Allow real JSON.load_file for other calls
+
+  allow(JSON).to receive(:load_file).with(end_with('.resultset.json'))
+    .and_return(fake_resultset_hash)
+  allow(CovLoupe::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')].each { |f| require f }
+Dir[File.join(__dir__, 'shared_examples', '**', '*.rb')].each { |f| require f }
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.order = :defined
+  Kernel.srand config.seed
+
+  # Suppress logging during tests by redirecting to /dev/null
+  # This is cheap and doesn't break tests that verify logging behavior
+  CovLoupe.default_log_file = 'stderr'
+  CovLoupe.active_log_file = 'stderr'
+
+  # Reset log file after each test to ensure tests that change it don't pollute others
+  config.after do
+    CovLoupe.active_log_file = File::NULL
+  end
+
+  config.include TestIOHelpers
+  config.include CLITestHelpers
+  config.include MCPToolTestHelpers
+  config.include MockingHelpers
+  config.include ControlFlowHelpers
+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,374 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'fileutils'
+
+RSpec.describe CovLoupe::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 'when computing file staleness details' do
+    it_behaves_like '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: CovLoupe::CoverageDataStaleError
+
+    it_behaves_like '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: CovLoupe::CoverageDataStaleError
+
+    it_behaves_like '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: CovLoupe::CoverageDataStaleError
+
+    it_behaves_like '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 'when handling 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 'when adjusting line count 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 'when handling 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 'when rel has 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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe CovLoupe do
+  let(:root) { (FIXTURES_DIR / 'project1').to_s }
+
+  describe CovLoupe::CoverageModel do
+    it 'raises file-level stale when source and coverage lengths differ' do
+      # 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 = described_class.new(root: root, resultset: 'coverage', staleness: :error)
+      # bar.rb has 2 coverage entries but 3 source lines in fixtures
+      expect do
+        model.summary_for('lib/bar.rb')
+      end.to raise_error(CovLoupe::CoverageDataStaleError, /stale/i)
+    end
+  end
+
+  describe CovLoupe::StalenessChecker do
+    it 'flags deleted files present only in coverage' do
+      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 do
+        checker.check_project!(coverage_map)
+      end.to raise_error(CovLoupe::CoverageDataProjectStaleError)
+    end
+
+    it 'does not raise for empty tracked_globs when nothing else is stale' do
+      checker = described_class.new(root: root, resultset: 'coverage', mode: :error,
+        tracked_globs: [], timestamp: Time.now.to_i)
+      expect do
+        checker.check_project!({})
+      end.not_to raise_error
+    end
+  end
+end

data/spec/support/cli_helpers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# CLI test helpers
+module CLITestHelpers
+  # Run CLI with the given arguments and return [stdout, stderr, exit_status]
+  def run_cli_with_status(*argv)
+    cli = CovLoupe::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

data/spec/support/control_flow_helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Helpers for managing control flow in RSpec tests.
+module ControlFlowHelpers
+  # Execute a block that's expected to call exit() without terminating the test.
+  # Useful for testing CLI commands that normally exit.
+  # Returns the exit status code if exit was called, otherwise returns the block's value.
+  #
+  # Examples:
+  #   status = swallow_system_exit { cli.run(['--help']) }
+  #   expect(status).to eq(0)  # --help calls exit(0)
+  #
+  #   result = swallow_system_exit { some_computation }
+  #   expect(result).to eq(expected_value)  # no exit, returns block value
+  def swallow_system_exit
+    yield
+  rescue SystemExit => e
+    e.status
+  end
+end

data/spec/support/fake_mcp.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FakeMCP
+  # Fake server captures the last created instance so we can assert on the
+  # name/version/tools passed in by CovLoupe::MCPServer.
+  class Server
+    class << self
+      attr_accessor :last_instance
+    end
+    attr_reader :params
+
+    def initialize(name:, version:, tools:)
+      @params = { name: name, version: version, tools: tools }
+      self.class.last_instance = self
+    end
+  end
+
+  # Fake stdio transport records whether `open` was called and the server
+  # it was initialized with.
+  class StdioTransport
+    class << self
+      attr_accessor :last_instance
+    end
+    attr_reader :server, :opened
+
+    def initialize(server)
+      @server = server
+      @opened = false
+      self.class.last_instance = self
+    end
+
+    def open
+      @opened = true
+    end
+
+    def opened?
+      @opened
+    end
+  end
+end

data/spec/support/io_helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Shared test helpers for I/O operations (e.g., capturing stdout/stderr).
+module TestIOHelpers
+  # Suppress stdout/stderr within the given block, yielding the StringIOs
+  def silence_output
+    original_stdout = $stdout
+    original_stderr = $stderr
+    $stdout = StringIO.new
+    $stderr = StringIO.new
+    yield $stdout, $stderr
+  ensure
+    $stdout = original_stdout
+    $stderr = original_stderr
+  end
+
+  # Capture the output of a command execution
+  # @param command [CovLoupe::Commands::BaseCommand] The command instance to execute
+  # @param args [Array] The arguments to pass to execute
+  # @return [String] The captured output
+  def capture_command_output(command, args)
+    output = nil
+    silence_output do |stdout, _stderr|
+      command.execute(args.dup)
+      output = stdout.string
+    end
+    output
+  end
+end

data/spec/support/mcp_helpers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# 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