normalized_match 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8557ff5b699123c45a96ea1cf0f01f5600d0a4eb545861b6d30e64c41a07288
+  data.tar.gz: 3fd9d9f8754a5f76073709f9666f35423bca7a49ccc4d87c7672102d126bb169
+SHA512:
+  metadata.gz: 0302d4db823ceb4f60c5e3949f25bdd67f3673539d4da52b54d6e1cbf0a3c28e38e61bbc1b99a5d5bde95d8e7da37fe973078454865c82030c981aeba2d84801
+  data.tar.gz: bf5dec8b78ccc0ce2c574c92ec7663f3367581ca3e86ed8005f414bf618d2b6c35f30aee9a4ff323081048c72442cc5cece22955a5520c6b5c7645e2a7f04b42

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FIRSTDRAFT, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# Normalized Match
+
+A normalized string matcher for RSpec that ignores case, punctuation, and some whitespace differences.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "normalized_match"
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install normalized_match
+```
+
+## Usage
+
+```ruby
+require "normalized_match"
+
+RSpec.describe "My test" do
+  it "matches strings normalized" do
+    actual = "Hello, World!"
+    expected = "hello world"
+    
+    expect(actual).to normalized_match(expected)
+  end
+end
+```
+
+The `normalized_match` matcher normalizes both strings by:
+
+- Converting to lowercase.
+- Removing all punctuation.
+- Collapsing internal whitespace (multiple spaces/tabs become single spaces).
+- Preserving line breaks for multi-line comparisons.
+- Stripping leading and trailing whitespace from lines.
+
+When a match fails, it displays a helpful side-by-side comparison table showing both the normalized and original values.
+
+## Using Heredocs
+
+When testing output that contains multiple lines, you can use Ruby's squiggly heredoc (`<<~`) to maintain nice indentation in your test files while automatically stripping leading whitespace:
+
+```ruby
+RSpec.describe "Letter counter" do
+  it "displays the letter count analysis" do
+    # Your actual output might come from a method, script, etc.
+    actual = run_codeblock(filename)
+    
+    # Use squiggly heredoc for expected output
+    # This strips leading whitespace while preserving internal formatting
+    expected = <<~EXPECTED
+      Letter count:
+      H: 1
+      e: 1
+      l: 3
+      o: 2
+      W: 1
+      r: 1
+      d: 1
+    EXPECTED
+    
+    expect(actual).to normalized_match(expected)
+  end
+end
+```
+
+**Important:** The squiggly heredoc (`<<~`) technique is especially useful because newlines _within_ the expected content are significant to the matcher. In other words, the above test would not pass if it was written as:
+
+```ruby
+expected = "Letter count: H: 1 e: 1 l: 3 o: 2 W: 1 r: 1 d: 1"
+```
+
+And the actual output was:
+
+```
+Letter count:
+H: 1
+e: 1
+l: 3
+o: 2
+W: 1
+r: 1
+d: 1
+```
+
+## Example Output
+
+When strings don't match after normalization:
+
+```
+Normalized match failed!
+
+To make it easier to match the expected output,
+we are "normalizing" both the actual output and
+expected output in this test. That means we
+lowercased, removed punctuation, and compacted
+whitespace in both.
+
+But the actual output still doesn't contain the
+expected output. Can you spot the difference?
+
+╔════════════╦══════════════════╦══════════════════╗
+║            ║     EXPECTED     ║      ACTUAL      ║
+╠════════════╬══════════════════╬══════════════════╣
+║ NORMALIZED ║  hello world     ║  goodbye world   ║
+╠════════════╬══════════════════╬══════════════════╣
+║  ORIGINAL  ║  Hello, World!   ║  Goodbye, World! ║
+╚════════════╩══════════════════╩══════════════════╝
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/firstdraft/normalized_match.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/normalized_match/normalized_match_matcher.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module NormalizedMatch
+  module NormalizedMatchMatcher
+    # Constants for table formatting
+    COLUMN_PADDING = 4 # 2 spaces on each side
+    LABEL_PADDING = 2  # For borders in label column
+    RSpec::Matchers.define :normalized_match do |expected|
+  match do |actual|
+    # Store the original values
+    @original_expected = expected
+    @original_actual = actual
+
+    # Store normalized versions for cleaner diffs
+    @expected = normalize_string(expected)
+    @actual = normalize_string(actual)
+
+    # Check if actual contains expected (substring match)
+    @actual.include?(@expected)
+  end
+
+  failure_message do |actual|
+    # Split into lines for side-by-side comparison
+    orig_expected_lines = @original_expected.to_s.split("\n")
+    orig_actual_lines = @original_actual.to_s.split("\n")
+    norm_expected_lines = @expected.to_s.split("\n")
+    norm_actual_lines = @actual.to_s.split("\n")
+
+    # Check if normalization changed anything
+    expected_changed = @original_expected.to_s != @expected.to_s
+    actual_changed = @original_actual.to_s != @actual.to_s
+    normalization_needed = expected_changed || actual_changed
+
+    # Calculate column widths
+    max_orig_expected = orig_expected_lines.map(&:length).max || 0
+    max_orig_actual = orig_actual_lines.map(&:length).max || 0
+    max_norm_expected = norm_expected_lines.map(&:length).max || 0
+    max_norm_actual = norm_actual_lines.map(&:length).max || 0
+
+    # Ensure minimum column width for headers
+    expected_col_width = [max_orig_expected, max_norm_expected, "EXPECTED".length].max + COLUMN_PADDING
+    actual_col_width = [max_orig_actual, max_norm_actual, "ACTUAL".length].max + COLUMN_PADDING
+
+    # Calculate label column width (for "NORMALIZED" and "ORIGINAL")
+    label_col_width = ["NORMALIZED".length, "ORIGINAL".length].max + COLUMN_PADDING
+
+    # Build the side-by-side table components
+
+    # Helper to pad and center text
+    def center_pad(text, width)
+      text = text.to_s
+      padding = width - text.length
+      left_pad = padding / 2
+      right_pad = padding - left_pad
+      " " * left_pad + text + " " * right_pad
+    end
+
+    # Helper to left-pad text with 2 spaces on each side
+    def pad_line(text, width)
+      "  #{text.to_s.ljust(width - COLUMN_PADDING)}  "
+    end
+
+    # Build header output
+    header_output = []
+    header_output << "Normalized match failed!"
+    header_output << ""
+
+    if normalization_needed
+      header_output << "To make it easier to match the expected output,"
+      header_output << "we are \"normalizing\" both the actual output and"
+      header_output << "expected output in this test. That means we"
+      header_output << "lowercased, removed punctuation, and compacted"
+      header_output << "whitespace in both."
+      header_output << ""
+      header_output << "But the actual output still doesn't contain the"
+      header_output << "expected output. Can you spot the difference?"
+      header_output << ""
+    else
+      header_output << "The actual output doesn't contain the expected"
+      header_output << "output. Can you spot the difference?"
+      header_output << ""
+    end
+
+    # Helper to center label text (NORMALIZED/ORIGINAL) in first column
+    def center_label(label, width, total_rows)
+      middle_row = total_rows / 2
+      (0...total_rows).map do |i|
+        if i == middle_row
+          label.center(width)
+        else
+          " " * width
+        end
+      end
+    end
+
+    # Build the table
+    table_output = []
+
+    if normalization_needed
+      # Build two-section table with labels
+      # Top border
+      table_output << "╔" + "═" * label_col_width + "╦" + "═" * expected_col_width + "╦" + "═" * actual_col_width + "╗"
+
+      # Header row
+      table_output << "║" + " " * label_col_width + "║" + center_pad("EXPECTED", expected_col_width) + "║" + center_pad("ACTUAL", actual_col_width) + "║"
+
+      # Header separator
+      table_output << "╠" + "═" * label_col_width + "╬" + "═" * expected_col_width + "╬" + "═" * actual_col_width + "╣"
+
+      # NORMALIZED section
+      max_norm_lines = [norm_expected_lines.length, norm_actual_lines.length].max
+      normalized_labels = center_label("NORMALIZED", label_col_width - LABEL_PADDING, max_norm_lines)
+
+      max_norm_lines.times do |i|
+        expected_line = norm_expected_lines[i] || ""
+        actual_line = norm_actual_lines[i] || ""
+        label = normalized_labels[i]
+        table_output << "║ #{label} ║" + pad_line(expected_line, expected_col_width) + "║" + pad_line(actual_line, actual_col_width) + "║"
+      end
+
+      # Middle separator
+      table_output << "╠" + "═" * label_col_width + "╬" + "═" * expected_col_width + "╬" + "═" * actual_col_width + "╣"
+
+      # ORIGINAL section
+      max_lines = [orig_expected_lines.length, orig_actual_lines.length].max
+      original_labels = center_label("ORIGINAL", label_col_width - LABEL_PADDING, max_lines)
+
+      max_lines.times do |i|
+        expected_line = orig_expected_lines[i] || ""
+        actual_line = orig_actual_lines[i] || ""
+        label = original_labels[i]
+        table_output << "║ #{label} ║" + pad_line(expected_line, expected_col_width) + "║" + pad_line(actual_line, actual_col_width) + "║"
+      end
+
+      # Bottom border
+      table_output << "╚" + "═" * label_col_width + "╩" + "═" * expected_col_width + "╩" + "═" * actual_col_width + "╝"
+    else
+      # Build simple table without labels column
+      # Top border
+      table_output << "╔" + "═" * expected_col_width + "╦" + "═" * actual_col_width + "╗"
+
+      # Header row
+      table_output << "║" + center_pad("EXPECTED", expected_col_width) + "║" + center_pad("ACTUAL", actual_col_width) + "║"
+
+      # Header separator
+      table_output << "╠" + "═" * expected_col_width + "╬" + "═" * actual_col_width + "╣"
+
+      # Data rows (using original since no normalization happened)
+      max_lines = [orig_expected_lines.length, orig_actual_lines.length].max
+
+      max_lines.times do |i|
+        expected_line = orig_expected_lines[i] || ""
+        actual_line = orig_actual_lines[i] || ""
+        table_output << "║" + pad_line(expected_line, expected_col_width) + "║" + pad_line(actual_line, actual_col_width) + "║"
+      end
+
+      # Bottom border
+      table_output << "╚" + "═" * expected_col_width + "╩" + "═" * actual_col_width + "╝"
+    end
+
+    # Combine all parts - header, then table (with extra newline between)
+    # Add a trailing newline so there's a blank line before RSpec's diff (when it appears)
+    message = header_output.join("\n") + "\n" + table_output.join("\n") + "\n"
+
+    message
+  end
+
+  # These methods make the matcher work better with rspec-enriched_json
+  attr_reader :expected, :actual
+
+  # Provide access to original values if needed
+  attr_reader :original_expected, :original_actual
+
+  # Tell RSpec that expected and actual can be diffed
+  def diffable?
+    true
+  end
+
+  def normalize_string(str)
+    str.to_s
+      .gsub(/[^a-zA-Z0-9\s]/, "")  # Remove punctuation but keep all whitespace
+      .downcase
+      .split("\n")                  # Split by newlines to preserve them
+      .map { |line| line.gsub(/\s+/, " ").strip }  # Normalize spaces within each line
+      .reject(&:empty?)             # Remove empty lines
+      .join("\n")                   # Rejoin with newlines
+  end
+    end
+  end
+end

data/lib/normalized_match.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rspec/matchers"
+require_relative "normalized_match/normalized_match_matcher"
+
+# Main namespace.
+module NormalizedMatch
+end
+
+# Include the matcher in RSpec when this gem is loaded
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include NormalizedMatch::NormalizedMatchMatcher
+  end
+end

data/normalized_match.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "normalized_match"
+  spec.version = "0.1.0"
+  spec.authors = ["Raghu Betina"]
+  spec.email = ["raghu@firstdraft.com"]
+  spec.homepage = "https://github.com/firstdraft/normalized_match"
+  spec.summary = "A normalized string matcher for RSpec that ignores case, punctuation, and whitespace differences"
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/firstdraft/normalized_match/issues",
+    "changelog_uri" => "https://github.com/firstdraft/normalized_match/blob/main/CHANGELOG.md",
+    "homepage_uri" => "https://github.com/firstdraft/normalized_match",
+    "label" => "Normalized Match",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/firstdraft/normalized_match"
+  }
+
+  spec.required_ruby_version = ">= 3.0"
+  spec.add_dependency "rspec", "~> 3.0"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: normalized_match
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Raghu Betina
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+email:
+- raghu@firstdraft.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/normalized_match.rb
+- lib/normalized_match/normalized_match_matcher.rb
+- normalized_match.gemspec
+homepage: https://github.com/firstdraft/normalized_match
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/firstdraft/normalized_match/issues
+  changelog_uri: https://github.com/firstdraft/normalized_match/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/firstdraft/normalized_match
+  label: Normalized Match
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/firstdraft/normalized_match
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A normalized string matcher for RSpec that ignores case, punctuation, and
+  whitespace differences
+test_files: []