midwire_common 1.1.0 → 2.0.0

data/docs/plans/2026-02-13-refinements-implementation.md

@@ -0,0 +1,1494 @@
+# midwire_common 2.0.0 Refinements Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace all monkey-patching with Ruby refinements, modernize all dependencies, remove stdlib-overlapping methods, and release as version 2.0.0.
+
+**Architecture:** Each monkey-patched file becomes a refinement module (`MidwireCommon::XxxExtensions`) using Ruby's `refine` blocks. Consumers opt in per-file with `using`. A composed `MidwireCommon::All` module includes all refinement modules so `using MidwireCommon::All` activates everything at once.
+
+**Tech Stack:** Ruby >= 3.2, RSpec ~> 3.12, Rake ~> 13.0
+
+**Cross-dependency note:** Some specs depend on methods from other modules. Specifically:
+- `array_spec.rb` uses `String#here_with_pipe` (from StringExtensions)
+- `time_spec.rb` uses `String#numeric?` (from StringExtensions)
+- `version.rake` uses `String#here_with_pipe` (from StringExtensions)
+
+These must be handled when converting String first.
+
+---
+
+### Task 1: Update gemspec, version, and remove Guard
+
+**Files:**
+- Modify: `midwire_common.gemspec`
+- Modify: `lib/midwire_common/version.rb`
+- Delete: `Guardfile`
+
+**Step 1: Update gemspec**
+
+Replace the full contents of `midwire_common.gemspec` with:
+
+```ruby
+# coding: utf-8
+require File.expand_path('../lib/midwire_common/version', __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name          = 'midwire_common'
+  spec.version       = MidwireCommon::VERSION
+  spec.authors       = ['Chris Blackburn']
+  spec.email         = ['87a1779b@opayq.com']
+  spec.summary       = 'Midwire Tech Ruby Library'
+  spec.description   = 'A useful Ruby library'
+  spec.homepage      = 'https://bitbucket.org/midwiretech/midwire_common'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.add_development_dependency 'debug', '~> 1.9'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+end
+```
+
+**Step 2: Update version**
+
+In `lib/midwire_common/version.rb`, change:
+
+```ruby
+original_verbosity = $VERBOSE
+$VERBOSE = nil
+module MidwireCommon
+  VERSION = '2.0.0'.freeze
+end
+$VERBOSE = original_verbosity
+```
+
+**Step 3: Delete Guardfile**
+
+```bash
+git rm Guardfile
+```
+
+**Step 4: Run bundle install**
+
+```bash
+bundle install
+```
+
+Expected: Success. Gemfile.lock updated with new dependency versions.
+
+**Step 5: Commit**
+
+```bash
+git add midwire_common.gemspec lib/midwire_common/version.rb Gemfile.lock
+git commit -m "chore: update dependencies and bump to 2.0.0
+
+- Ruby >= 3.2, RSpec 3.12, Rake 13, Rubocop 1.60
+- Remove Guard, pry-nav
+- Add debug gem"
+```
+
+---
+
+### Task 2: Update spec_helper
+
+**Files:**
+- Modify: `spec/spec_helper.rb`
+
+**Step 1: Rewrite spec_helper**
+
+Replace full contents of `spec/spec_helper.rb`:
+
+```ruby
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter 'spec/'
+    add_filter 'vendor/'
+  end
+end
+
+require 'debug'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'midwire_common')
+require 'midwire_common/all'
+
+PROJECT_ROOT = File.expand_path('..', File.dirname(__FILE__))
+
+RSpec.configure do |config|
+  include MidwireCommon
+
+  config.expect_with :rspec do |expectations|
+    expectations.syntax = [:should, :expect]
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.syntax = [:should, :expect]
+  end
+
+  config.order = 'random'
+
+  def capture(stream)
+    begin
+      stream = stream.to_s
+      eval "$#{stream} = StringIO.new"
+      yield
+      result = eval("$#{stream}").string
+    ensure
+      eval("$#{stream} = #{stream.upcase}")
+    end
+
+    result
+  end
+end
+```
+
+Key changes:
+- `require 'pry'` → `require 'debug'`
+- `config.color = true` removed (RSpec 3 defaults to color on TTY)
+- Added `expectations.syntax = [:should, :expect]` to support both syntaxes during migration
+- Added `mocks.syntax = [:should, :expect]` for same reason
+
+**Step 2: Commit**
+
+```bash
+git add spec/spec_helper.rb
+git commit -m "chore: update spec_helper for RSpec 3 compatibility"
+```
+
+Note: Tests will NOT pass at this point. That's expected — we haven't converted the source files yet.
+
+---
+
+### Task 3: Convert String to refinements
+
+This is the first and most critical conversion because other modules depend on String methods.
+
+**Files:**
+- Modify: `lib/midwire_common/string.rb`
+- Modify: `spec/lib/midwire_common/string_spec.rb`
+- Modify: `spec/lib/midwire_common/array_spec.rb` (uses `here_with_pipe`)
+- Modify: `spec/lib/midwire_common/time_spec.rb` (uses `numeric?`)
+- Modify: `lib/tasks/version.rake` (uses `here_with_pipe`)
+
+**Step 1: Rewrite string.rb with refinements**
+
+Replace full contents of `lib/midwire_common/string.rb`:
+
+```ruby
+module MidwireCommon
+  module StringExtensions
+    refine String.singleton_class do
+      def random(count = 6, ranges = [('a'..'z'), ('A'..'Z'), ('0'..'9')])
+        coll = ranges.map(&:to_a).flatten
+        (0..(count - 1)).map { coll[rand(coll.length)] }.join
+      end
+    end
+
+    refine String do
+      def left_substr(count)
+        slice(0, count)
+      end
+
+      def right_substr(count)
+        slice(-count, count)
+      end
+
+      # html = <<-stop.here_with_pipe(delimeter="\n")
+      #   |<!-- Begin: comment  -->
+      #   |<script type="text/javascript">
+      # stop
+      def here_with_pipe(delimeter = ' ')
+        lines = split("\n")
+        lines.map! { |c| c.sub!(/\s*\|/, '') }
+        new_string = lines.join(delimeter)
+        replace(new_string)
+      end
+
+      def alpha_numeric?
+        regex = /^[a-zA-Z0-9]+$/
+        (self =~ regex) == 0 ? true : false
+      end
+
+      def email_address?
+        email_regex = /\A([\w+\-].?)+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i
+        (self =~ email_regex) == 0 ? true : false
+      end
+
+      def zipcode?
+        self =~ %r{^(\d{5})(-\d{4})?$}x ? true : false
+      end
+
+      def numeric?
+        Float(self)
+      rescue
+        false
+      else
+        true
+      end
+
+      def format_phone
+        gsub!(/[a-z,! \-\(\)\:\;\.\&\$]+/i, '')
+        '(' << slice(0..2) << ')' << slice(3..5) << '-' << slice(-4, 4)
+      end
+
+      def sanitize
+        gsub(/[^a-z0-9,! \-\(\)\:\;\.\&\$]+/i, '')
+      end
+
+      def sanitize!
+        gsub!(/[^a-z0-9,! \-\(\)\:\;\.\&\$]+/i, '')
+      end
+
+      def shorten(maxcount = 30)
+        if length >= maxcount
+          shortened = self[0, maxcount]
+          splitted = shortened.split(/\s/)
+          if splitted.length > 1
+            words = splitted.length
+            splitted[0, words - 1].join(' ') + '...'
+          else
+            shortened[0, maxcount - 3] + '...'
+          end
+        else
+          self
+        end
+      end
+
+      def escape_single_quotes
+        gsub(/[']/, '\\\\\'')
+      end
+
+      def escape_double_quotes
+        gsub(/["]/, '\\\\\"')
+      end
+
+      def snakerize
+        gsub(/::/, '/')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+      end
+
+      def camelize
+        gsub(/\/(.?)/) { '::' + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+      end
+    end
+  end
+end
+```
+
+**Step 2: Rewrite string_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/string_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::StringExtensions
+
+RSpec.describe String do
+  it 'is a String' do
+    ''.should be_a String
+  end
+
+  it 'generates a random string' do
+    String.random.length.should == 6
+  end
+
+  context 'slicing methods' do
+    it "'left' returns the leftmost 'n' characters" do
+      'My Bogus String'.left_substr(2).should == 'My'
+    end
+
+    it "'right' returns the rightmost 'n' characters " do
+      'My Bogus String'.right_substr(2).should == 'ng'
+    end
+  end
+
+  context 'formatting and manipulation' do
+    it 'here_with_pipe - without linefeeds' do
+      html = <<-STOP.here_with_pipe
+        |<!-- Begin: comment  -->
+        |<script type="text/javascript">
+        |</script>
+      STOP
+      html.should == '<!-- Begin: comment  --> <script type="text/javascript"> </script>'
+    end
+
+    it 'here_with_pipe - with linefeeds' do
+      html = <<-STOP.here_with_pipe("\n")
+        |<!-- Begin: comment  -->
+        |<script type="text/javascript">
+        |</script>
+      STOP
+      html.should == "<!-- Begin: comment  -->\n<script type=\"text/javascript\">\n</script>"
+    end
+
+    it 'here_with_pipe - with no space delimeter' do
+      html = <<-STOP.here_with_pipe('')
+        |<!-- Begin: comment  -->
+        |<script type="text/javascript">
+        |</script>
+      STOP
+      html.should == '<!-- Begin: comment  --><script type="text/javascript"></script>'
+    end
+
+    it 'format_phone returns a formatted phone number string' do
+      expect('9132329999'.format_phone).to eq('(913)232-9999')
+      expect('913.232.9999'.format_phone).to eq('(913)232-9999')
+      expect('913 232 9999'.format_phone).to eq('(913)232-9999')
+      expect('913-232-9999'.format_phone).to eq('(913)232-9999')
+    end
+
+    it 'sanitizes itself' do
+      expect('|bogus|'.sanitize).to eq('bogus')
+      expect('|∫|ß'.sanitize).to eq('')
+      expect('ßogus'.sanitize).to eq('ogus')
+      expect('<tag>bogus</tag>'.sanitize).to eq('tagbogustag')
+      expect('<tag>.bogus.</tag>'.sanitize).to eq('tag.bogus.tag')
+      s = '|∫|ß'
+      s.sanitize!
+      s.should == ''
+    end
+
+    it 'shortens itself with elipses at the end' do
+      s = 'this is my very long string which I will eventually shorten with the enhanced String class that we are now testing.'
+      short = s.shorten
+      expect(short).to eq('this is my very long string...')
+      expect(short.length).to eq(30)
+
+      s = '1234567890123456789012345678901234567890'
+      short = s.shorten
+      expect(short).to eq('123456789012345678901234567...')
+      expect(short.length).to eq(30)
+
+      s = '12345678901234567890'
+      short = s.shorten
+      expect(short).to eq('12345678901234567890')
+      expect(short.length).to eq(20)
+    end
+
+    context 'quotes' do
+      it 'escapes single quotes' do
+        "this is a 'test'".escape_single_quotes.should == "this is a \\'test\\'"
+      end
+
+      it 'escapes double quotes' do
+        expect('this is a "test"'.escape_double_quotes)
+            .to eq('this is a \\\\"test\\\\"')
+      end
+    end
+  end
+
+  context 'characterization' do
+    it 'knows if it is alpha-numeric or not' do
+      'abcd-9191'.alpha_numeric?.should eq(false)
+      'abcd.9191'.alpha_numeric?.should eq(false)
+      'abcd91910'.alpha_numeric?.should eq(true)
+      'abcd_9191'.alpha_numeric?.should eq(false)
+      'abcd 9191'.alpha_numeric?.should eq(false)
+    end
+
+    it 'knows if it is an email address or not' do
+      'abcd_9191'.email_address?.should eq(false)
+      'abcd@9191'.email_address?.should eq(false)
+      'abcd@9191.info'.email_address?.should eq(true)
+      'abcd-asdf@9191.com'.email_address?.should eq(true)
+      'abcd_asdf@9191.com'.email_address?.should eq(true)
+      'abcd.asdf@9191.com'.email_address?.should eq(true)
+    end
+
+    it 'knows if it is a zipcode or not' do
+      '13922-2356'.zipcode?.should eq(true)
+      '13922.2343'.zipcode?.should eq(false)
+      '13922 2342'.zipcode?.should eq(false)
+      'ABSSD'.zipcode?.should eq(false)
+      'i3323'.zipcode?.should eq(false)
+      '13922'.zipcode?.should eq(true)
+    end
+
+    it 'knows if it is numeric or not' do
+      '12341'.numeric?.should eq(true)
+      '12341.23'.numeric?.should eq(true)
+      '12341.00000000000000023'.numeric?.should eq(true)
+      '0.12341'.numeric?.should eq(true)
+      '0x2E'.numeric?.should eq(true)
+      ' 0.12341'.numeric?.should eq(true)
+      ' 0.12341 '.numeric?.should eq(true)
+      '.12341'.numeric?.should eq(true)
+      ' 12341.'.numeric?.should eq(false)
+      ' 12341.  '.numeric?.should eq(false)
+    end
+  end
+
+  context '.snakerize' do
+    it 'changes CamelCased string to snake_cased' do
+      expect('CamelCased'.snakerize).to eq('camel_cased')
+    end
+
+    it 'handles doulbe-colon' do
+      expect('Camel::CasedTwo'.snakerize).to eq('camel/cased_two')
+    end
+  end
+
+  context '.camelize' do
+    it 'changes snake cased string to camelized' do
+      expect('camel_cased'.camelize).to eq('CamelCased')
+    end
+
+    it 'handles slash' do
+      expect('camel/cased_two'.camelize).to eq('Camel::CasedTwo')
+    end
+  end
+end
+```
+
+Changes: removed trim method specs, added `using MidwireCommon::StringExtensions` at top.
+
+**Step 3: Add `using` to array_spec.rb (cross-dependency)**
+
+Add `using MidwireCommon::StringExtensions` after the require line in `spec/lib/midwire_common/array_spec.rb` (for `here_with_pipe` usage on line 37).
+
+**Step 4: Add `using` to time_spec.rb (cross-dependency)**
+
+Add `using MidwireCommon::StringExtensions` after the require line in `spec/lib/midwire_common/time_spec.rb` (for `numeric?` usage).
+
+**Step 5: Update version.rake**
+
+At the top of `lib/tasks/version.rake`, after `require 'midwire_common/string'`, add:
+
+```ruby
+using MidwireCommon::StringExtensions
+```
+
+**Step 6: Run string specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/string_spec.rb
+```
+
+Expected: All pass.
+
+**Step 7: Commit**
+
+```bash
+git add lib/midwire_common/string.rb spec/lib/midwire_common/string_spec.rb \
+  spec/lib/midwire_common/array_spec.rb spec/lib/midwire_common/time_spec.rb \
+  lib/tasks/version.rake
+git commit -m "refactor: convert String monkey-patch to refinements
+
+Remove trim/left_trim/right_trim (use stdlib strip/lstrip/rstrip).
+Add 'using' to dependent specs and version.rake."
+```
+
+---
+
+### Task 4: Convert Array to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/array.rb`
+- Modify: `spec/lib/midwire_common/array_spec.rb`
+
+**Step 1: Rewrite array.rb**
+
+Replace full contents of `lib/midwire_common/array.rb`:
+
+```ruby
+module MidwireCommon
+  module ArrayExtensions
+    refine Array do
+      def count_occurrences
+        hash = Hash.new(0)
+        each { |elem| hash[elem] += 1 }
+        hash
+      end
+
+      def randomize
+        sort_by { rand }
+      end
+
+      def randomize!
+        replace(randomize)
+      end
+
+      def sort_case_insensitive
+        sort_by(&:downcase)
+      end
+
+      def each_with_first_last(first_code, main_code, last_code)
+        each_with_index do |item, ndx|
+          case ndx
+          when 0 then first_code.call(item)
+          when size - 1 then last_code.call(item)
+          else main_code.call(item)
+          end
+        end
+      end
+
+      # Make a string from a multi-dimensional array:
+      # 1 dimension:
+      # [1,2,3].superjoin(["pre","between","post"])
+      #
+      # 2 dimensions (html table):
+      # [[1,2],[2,3]].superjoin(%w{<table><tr> </tr><tr> </tr></table>}, %w{<td> </td><td> </td>})
+      def superjoin(*ldescr)
+        dim = ldescr[0]
+        rest = ldescr[1..]
+        dim[0] + map do |arr|
+          (arr.respond_to?(:superjoin) && !rest.empty?) ? arr.superjoin(*rest) : arr.to_s
+        end.join(dim[1]) + dim[2]
+      end
+    end
+  end
+end
+```
+
+Changes: removed `binsearch`, wrapped in refinement module, `ldescr[1..-1]` → `ldescr[1..]`.
+
+**Step 2: Rewrite array_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/array_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::StringExtensions
+using MidwireCommon::ArrayExtensions
+
+RSpec.describe Array do
+  it 'counts occurrences of an element' do
+    [1, 2, 2, 3, 3, 3].count_occurrences.should eq(1 => 1, 2 => 2, 3 => 3)
+    %w(asdf asdf qwer asdf).count_occurrences.should == {
+      'asdf' => 3,
+      'qwer' => 1
+    }
+  end
+
+  it 'randomizes the order of an array' do
+    myarray = [1, 2, 3, 4, 5, 6, 7, 8, 9, '0']
+    myarray.randomize.should_not eq(myarray)
+    myarray.randomize!
+    myarray.should_not == [1, 2, 3, 4, 5, 6, 7, 8, 9, '0']
+  end
+
+  it 'sorts elements case insensitive' do
+    myarray = %w(zebra ghost Zebra cat Cat)
+    myarray.sort_case_insensitive.should eq(%w(Cat cat ghost Zebra zebra))
+  end
+
+  it 'can process first and last entries differently than others' do
+    text = ''
+    ['KU', 'K-State', 'MU'].each_with_first_last(
+      lambda do |team|
+        text += "#{team} came first in the NCAA basketball tournament.\n"
+      end,
+      lambda do |team|
+        text += "#{team} did not come first or last in the final four.\n"
+      end,
+      lambda do |team|
+        text += "#{team} came last in the final four this year.\n"
+      end
+    )
+    text.should == <<-string.here_with_pipe("\n")
+      |KU came first in the NCAA basketball tournament.
+      |K-State did not come first or last in the final four.
+      |MU came last in the final four this year.
+      |
+    string
+  end
+
+  it 'can superjoin elements' do
+    [1, 2, 3].superjoin(['->', '+', '<-']).should eq('->1+2+3<-')
+    [[1, 2], [2, 3]].superjoin(
+      %w(<table><tr> </tr><tr> </tr></table>), %w(<td> </td><td> </td>)
+    ).should eq(
+      '<table><tr><td>1</td><td>2</td></tr><tr><td>2</td><td>3</td></tr></table>'
+    )
+  end
+end
+```
+
+Changes: removed `binsearch` test, added `using` for both String and Array extensions.
+
+**Step 3: Run array specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/array_spec.rb
+```
+
+Expected: All pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/array.rb spec/lib/midwire_common/array_spec.rb
+git commit -m "refactor: convert Array monkey-patch to refinements
+
+Remove binsearch (use stdlib Array#bsearch)."
+```
+
+---
+
+### Task 5: Convert Hash to refinements and namespace BottomlessHash
+
+**Files:**
+- Modify: `lib/midwire_common/hash.rb`
+- Modify: `spec/lib/midwire_common/hash_spec.rb`
+
+**Step 1: Rewrite hash.rb**
+
+Replace full contents of `lib/midwire_common/hash.rb`:
+
+```ruby
+require 'uri'
+
+module MidwireCommon
+  # By Nick Ostrovsky
+  # http://firedev.com/posts/2015/bottomless-ruby-hash/
+  class BottomlessHash < Hash
+    def initialize
+      super(&-> (hash, key) { hash[key] = self.class.new })
+    end
+
+    def self.from_hash(hash)
+      new.merge(hash)
+    end
+  end
+
+  module HashExtensions
+    refine Hash do
+      def bottomless
+        MidwireCommon::BottomlessHash.from_hash(self)
+      end
+
+      def grep(pattern)
+        each_with_object([]) do |kv, res|
+          res << kv if kv[0] =~ pattern || kv[1] =~ pattern
+          res
+        end
+      end
+
+      def diff(other)
+        (keys + other.keys).uniq.each_with_object({}) do |key, memo|
+          unless self[key] == other[key]
+            memo[key] = if self[key].is_a?(Hash) && other[key].is_a?(Hash)
+                          self[key].diff(other[key])
+                        else
+                          [self[key], other[key]]
+                        end
+          end
+          memo
+        end
+      end
+
+      def apply_diff!(changes, direction = :right)
+        path = [[self, changes]]
+        pos, local_changes = path.pop
+        while local_changes
+          local_changes.each_pair do |key, change|
+            if change.is_a?(Array)
+              pos[key] = (direction == :right) ? change[1] : change[0]
+            else
+              path.push([pos[key], change])
+            end
+          end
+          pos, local_changes = path.pop
+        end
+        self
+      end
+
+      def apply_diff(changes, direction = :right)
+        cloned = clone
+        path = [[cloned, changes]]
+        pos, local_changes = path.pop
+        while local_changes
+          local_changes.each_pair do |key, change|
+            if change.is_a?(Array)
+              pos[key] = (direction == :right) ? change[1] : change[0]
+            else
+              pos[key] = pos[key].clone
+              path.push([pos[key], change])
+            end
+          end
+          pos, local_changes = path.pop
+        end
+        cloned
+      end
+
+      # Usage { a: 1, b: 2, c: 3 }.only(:a) -> { a: 1 }
+      def only(*keys)
+        dup.reject { |key, _v| !keys.flatten.include?(key.to_sym) }
+      end
+
+      # Usage h = { a: 1, b: 2, c: 3 }.pop(:a) -> { a: 1 }
+      # ... and now h == { b: 2, c: 3 }
+      def pop(*keys)
+        ret = reject { |key, _v| !keys.flatten.include?(key.to_sym) }
+        reject! { |key, _v| keys.flatten.include?(key.to_sym) }
+        ret
+      end
+
+      # Usage { a: 1, b: 2, c: 3 }.to_query_string #=> "a=1&b=2&c=3"
+      def to_query_string
+        URI.encode_www_form(self)
+      end
+
+      def symbolize_keys!
+        keys.each do |key|
+          self[(key.to_sym rescue key) || key] = delete(key)
+        end
+        self
+      end
+
+      def symbolize_keys
+        dup.symbolize_keys!
+      end
+
+      def recursively_symbolize_keys!
+        symbolize_keys!
+        values.each do |value|
+          value.recursively_symbolize_keys! if value.is_a?(Hash)
+        end
+        self
+      end
+    end
+  end
+end
+```
+
+Changes: removed `except` (built into Ruby 3.0+), replaced `URI.encode` with `URI.encode_www_form`, namespaced `BottomlessHash` under `MidwireCommon`, wrapped in refinement module.
+
+**Step 2: Rewrite hash_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/hash_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::HashExtensions
+
+RSpec.describe MidwireCommon::BottomlessHash do
+  subject { described_class.new }
+
+  it 'does not raise on missing key' do
+    expect do
+      subject[:missing][:key]
+    end.to_not raise_error
+  end
+
+  it 'returns an empty value on missing key' do
+    expect(subject[:missing][:key]).to be_empty
+  end
+
+  it 'stores and returns keys' do
+    subject[:existing][:key] = :value
+    expect(subject[:existing][:key]).to eq(:value)
+  end
+
+  context '#from_hash' do
+    let(:hash) do
+      { existing: { key: { value: :hello } } }
+    end
+
+    subject do
+      described_class.from_hash(hash)
+    end
+
+    it 'returns old hash values' do
+      expect(subject[:existing][:key][:value]).to eq(:hello)
+    end
+
+    it 'provides a bottomless version' do
+      expect(subject[:missing][:key]).to be_empty
+    end
+
+    it 'stores and returns new values' do
+      subject[:existing][:key] = :value
+      expect(subject[:existing][:key]).to eq(:value)
+    end
+
+    it 'converts nested hashes as well' do
+      expect do
+        subject[:existing][:key][:missing]
+      end.to_not raise_error
+    end
+  end
+end
+
+RSpec.describe Hash do
+  it 'greps key/value pairs using a regular expression' do
+    h = { a: 'this is a test', 'b' => 'this is not the answer' }
+    expect(h.grep(/a test/)).to eq([[:a, 'this is a test']])
+    expect(h.grep(/b/)).to eq([['b', 'this is not the answer']])
+    expect(
+      h.grep(/^this/)
+    ).to eq([[:a, 'this is a test'], ['b', 'this is not the answer']])
+  end
+
+  it 'returns elements for discretely passed keys' do
+    expect({ a: 1, b: 2, c: 3 }.only(:a)).to eq(a: 1)
+  end
+
+  it 'pops an element off of the stack' do
+    h = { a: 1, b: 2, c: 3 }
+    expect(h.pop(:a)).to eq(a: 1)
+    expect(h).to eq(b: 2, c: 3)
+  end
+
+  it 'returns a query string' do
+    expect({ a: 1, b: 2, c: 3 }.to_query_string).to eq('a=1&b=2&c=3')
+  end
+
+  it 'symbolizes its keys' do
+    h = { 'a' => 1, 'b' => 2, 'c' => 3 }
+    expect(h.symbolize_keys).to eq(a: 1, b: 2, c: 3)
+    h.symbolize_keys!
+    expect(h).to eq(a: 1, b: 2, c: 3)
+  end
+
+  it 'recursively symbolizes its keys' do
+    h = {
+      'a' => 1,
+      'b' => {
+        'a' => 1,
+        'b' => 2,
+        'c' => {
+          'a' => 1,
+          'b' => 2,
+          'c' => 3
+        }
+      },
+      'c' => 3
+    }
+    expect(h.recursively_symbolize_keys!).to eq(
+      a: 1, b: { a: 1, b: 2, c: { a: 1, b: 2, c: 3 } }, c: 3
+    )
+  end
+
+  context 'diff methods' do
+    let(:h1_keys) { { 'a' => 1, 'b' => 2, 'c' => 3 } }
+    let(:h2_keys) { { 'a' => 1, 'b' => 2, 'd' => 3 } }
+
+    let(:h1_keys_nested) { { 'a' => 1, 'b' => 2, { 'x' => 99 } => 3 } }
+    let(:h2_keys_nested) { { 'a' => 1, 'b' => 2, { 'x' => 99 } => 4 } }
+
+    let(:h1_values) { { 'a' => 1, 'b' => 2, 'c' => 3 } }
+    let(:h2_values) { { 'a' => 1, 'b' => 2, 'c' => 4 } }
+
+    context '.diff' do
+      it 'reports different keys' do
+        expect(h1_keys.diff(h2_keys)).to eq('c' => [3, nil], 'd' => [nil, 3])
+      end
+
+      it 'reports different values' do
+        expect(h1_values.diff(h2_values)).to eq('c' => [3, 4])
+      end
+
+      it 'reports different keys even with nested hashes' do
+        expect(h1_keys_nested.diff(h2_keys_nested)).to eq(
+          { 'x' => 99 } => [3, 4]
+        )
+      end
+    end
+
+    context '.apply_diff!' do
+      it 'applies diff to the right by default' do
+        diff = h1_values.diff(h2_values)
+        result = h1_values.apply_diff!(diff)
+        expect(result).to eq('a' => 1, 'b' => 2, 'c' => 4)
+        expect(h1_values).to eq('a' => 1, 'b' => 2, 'c' => 4)
+      end
+
+      it 'applies diff to the left' do
+        diff = h1_values.diff(h2_values)
+        result = h2_values.apply_diff!(diff, :left)
+        expect(result).to eq('a' => 1, 'b' => 2, 'c' => 3)
+      end
+    end
+
+    context '.apply_diff' do
+      it 'returns a new hash with diff applied' do
+        diff = h1_values.diff(h2_values)
+        result = h1_values.apply_diff(diff)
+        expect(result).to eq('a' => 1, 'b' => 2, 'c' => 4)
+        expect(h1_values).to eq('a' => 1, 'b' => 2, 'c' => 3)
+      end
+
+      it 'applies diff to the left' do
+        diff = h1_values.diff(h2_values)
+        result = h2_values.apply_diff(diff, :left)
+        expect(result).to eq('a' => 1, 'b' => 2, 'c' => 3)
+        expect(h2_values).to eq('a' => 1, 'b' => 2, 'c' => 4)
+      end
+    end
+  end
+end
+```
+
+Changes: removed `except` test, added `apply_diff` and `apply_diff!` specs, namespaced `BottomlessHash` reference, added `using`.
+
+**Step 3: Run hash specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/hash_spec.rb
+```
+
+Expected: All pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/hash.rb spec/lib/midwire_common/hash_spec.rb
+git commit -m "refactor: convert Hash monkey-patch to refinements
+
+Remove Hash#except (built into Ruby 3.0+).
+Replace URI.encode with URI.encode_www_form.
+Namespace BottomlessHash under MidwireCommon.
+Add specs for apply_diff and apply_diff!."
+```
+
+---
+
+### Task 6: Convert Integer (replacing Fixnum) to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/fixnum.rb` → becomes `lib/midwire_common/integer.rb`
+- Modify: `spec/lib/midwire_common/fixnum_spec.rb` → becomes `spec/lib/midwire_common/integer_spec.rb`
+
+**Step 1: Create integer.rb**
+
+Create `lib/midwire_common/integer.rb`:
+
+```ruby
+require 'midwire_common'
+
+module MidwireCommon
+  module IntegerExtensions
+    refine Integer do
+      include MidwireCommon::NumberBehavior
+    end
+  end
+end
+```
+
+**Step 2: Delete fixnum.rb**
+
+```bash
+git rm lib/midwire_common/fixnum.rb
+```
+
+**Step 3: Create integer_spec.rb**
+
+Create `spec/lib/midwire_common/integer_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::IntegerExtensions
+
+RSpec.describe Integer do
+  it 'can format itself with commas' do
+    8_729_928_827.commify.should == '8,729,928,827'
+  end
+end
+```
+
+Note: removed `odd?`/`even?` tests — those are built into Integer.
+
+**Step 4: Delete fixnum_spec.rb**
+
+```bash
+git rm spec/lib/midwire_common/fixnum_spec.rb
+```
+
+**Step 5: Run integer specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/integer_spec.rb
+```
+
+Expected: All pass.
+
+**Step 6: Commit**
+
+```bash
+git add lib/midwire_common/integer.rb spec/lib/midwire_common/integer_spec.rb
+git commit -m "refactor: replace Fixnum with Integer refinements
+
+Fixnum was unified into Integer in Ruby 2.4.
+Remove odd?/even? tests (built-in)."
+```
+
+---
+
+### Task 7: Convert Float to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/float.rb`
+- Modify: `spec/lib/midwire_common/float_spec.rb`
+
+**Step 1: Rewrite float.rb**
+
+Replace full contents of `lib/midwire_common/float.rb`:
+
+```ruby
+require 'midwire_common'
+
+module MidwireCommon
+  module FloatExtensions
+    refine Float do
+      include MidwireCommon::NumberBehavior
+    end
+  end
+end
+```
+
+**Step 2: Rewrite float_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/float_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::FloatExtensions
+
+RSpec.describe Float do
+  it 'can format itself with commas' do
+    8_729_928_827.0.commify.should eq('8,729,928,827.0')
+    8_729_928_827.20332002.commify.should eq('8,729,928,827.20332')
+  end
+end
+```
+
+**Step 3: Run float specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/float_spec.rb
+```
+
+Expected: All pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/float.rb spec/lib/midwire_common/float_spec.rb
+git commit -m "refactor: convert Float monkey-patch to refinements"
+```
+
+---
+
+### Task 8: Convert Enumerable to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/enumerable.rb`
+- Modify: `spec/lib/midwire_common/enumerable_spec.rb`
+
+**Step 1: Rewrite enumerable.rb**
+
+Replace full contents of `lib/midwire_common/enumerable.rb`:
+
+```ruby
+module MidwireCommon
+  module EnumerableExtensions
+    refine Enumerable do
+      def sort_by_frequency
+        histogram = each_with_object(Hash.new(0)) do |elem, hash|
+          hash[elem] += 1
+          hash
+        end
+        sort_by { |elem| [histogram[elem] * -1, elem] }
+      end
+    end
+  end
+end
+```
+
+**Step 2: Rewrite enumerable_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/enumerable_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::EnumerableExtensions
+
+RSpec.describe Enumerable do
+  it 'can sort by frequency of occurrences' do
+    [1, 2, 3, 3, 3, 3, 2].sort_by_frequency.should eq([3, 3, 3, 3, 2, 2, 1])
+    %w(a b c d e f a f f b f a).sort_by_frequency
+                               .should eq(%w(f f f f a a a b b c d e))
+  end
+end
+```
+
+**Step 3: Run enumerable specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/enumerable_spec.rb
+```
+
+Expected: All pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/enumerable.rb spec/lib/midwire_common/enumerable_spec.rb
+git commit -m "refactor: convert Enumerable monkey-patch to refinements"
+```
+
+---
+
+### Task 9: Convert Time to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/time.rb`
+- Modify: `spec/lib/midwire_common/time_spec.rb`
+
+**Step 1: Rewrite time.rb**
+
+Replace full contents of `lib/midwire_common/time.rb`:
+
+```ruby
+module MidwireCommon
+  module TimeExtensions
+    refine Time.singleton_class do
+      def timestamp(resolution = 3)
+        return Time.now.strftime('%Y%m%d%H%M%S') if resolution < 1
+        Time.now.strftime("%Y%m%d%H%M%S.%#{resolution}N")
+      end
+    end
+  end
+end
+```
+
+**Step 2: Rewrite time_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/time_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::StringExtensions
+using MidwireCommon::TimeExtensions
+
+RSpec.describe Time do
+  context 'generates a timestamp' do
+    it 'appropriate for a filename' do
+      ts = Time.timestamp
+      expect(ts.length).to eq(18)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'with the only seconds' do
+      ts = Time.timestamp(0)
+      expect(ts.length).to eq(14)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'defaults to nanosecond resolution' do
+      ts = Time.timestamp
+      expect(ts.length).to eq(18)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'with the millisecond resolution' do
+      ts = Time.timestamp(3)
+      expect(ts.length).to eq(18)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'with the microsecond resolution' do
+      ts = Time.timestamp(6)
+      expect(ts.length).to eq(21)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'with the nanosecond resolution' do
+      ts = Time.timestamp(9)
+      expect(ts.length).to eq(24)
+      expect(ts.numeric?).to eq(true)
+    end
+
+    it 'with the picosecond resolution' do
+      ts = Time.timestamp(12)
+      expect(ts.length).to eq(27)
+      expect(ts.numeric?).to eq(true)
+    end
+  end
+end
+```
+
+Note: needs `using MidwireCommon::StringExtensions` because tests call `numeric?` on the timestamp strings.
+
+**Step 3: Run time specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/time_spec.rb
+```
+
+Expected: All pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/time.rb spec/lib/midwire_common/time_spec.rb
+git commit -m "refactor: convert Time monkey-patch to refinements"
+```
+
+---
+
+### Task 10: Convert File to refinements
+
+**Files:**
+- Modify: `lib/midwire_common/file.rb`
+- Delete: `lib/midwire_common/file/stat.rb` (merge into file.rb)
+- Modify: `spec/lib/midwire_common/file/stat_spec.rb`
+
+**Step 1: Rewrite file.rb (consolidating file/stat.rb)**
+
+Replace full contents of `lib/midwire_common/file.rb`:
+
+```ruby
+module MidwireCommon
+  module FileExtensions
+    refine File::Stat.singleton_class do
+      def device_name(file)
+        Dir['/dev/*'].inject({}) do |hash, node|
+          hash.update(File.stat(node).rdev => node)
+        end.values_at(File.stat(file).dev).first || nil
+      end
+    end
+  end
+end
+```
+
+**Step 2: Delete file/stat.rb**
+
+```bash
+git rm lib/midwire_common/file/stat.rb
+rmdir lib/midwire_common/file 2>/dev/null || true
+```
+
+**Step 3: Rewrite stat_spec.rb**
+
+Replace full contents of `spec/lib/midwire_common/file/stat_spec.rb`:
+
+```ruby
+require 'spec_helper'
+
+using MidwireCommon::FileExtensions
+
+RSpec.describe File::Stat do
+  it 'knows on which device it resides' do
+    dev = File::Stat.device_name('/tmp')
+    dev.should_not be_nil
+  end
+end
+```
+
+**Step 4: Run file specs**
+
+```bash
+bundle exec rspec spec/lib/midwire_common/file/stat_spec.rb
+```
+
+Expected: All pass.
+
+**Step 5: Commit**
+
+```bash
+git add lib/midwire_common/file.rb spec/lib/midwire_common/file/stat_spec.rb
+git commit -m "refactor: convert File::Stat monkey-patch to refinements
+
+Consolidate file/stat.rb into file.rb."
+```
+
+---
+
+### Task 11: Update all.rb and midwire_common.rb
+
+**Files:**
+- Modify: `lib/midwire_common/all.rb`
+- Modify: `lib/midwire_common.rb`
+
+**Step 1: Rewrite all.rb**
+
+Replace full contents of `lib/midwire_common/all.rb`:
+
+```ruby
+require 'midwire_common/array'
+require 'midwire_common/enumerable'
+require 'midwire_common/data_file_cache'
+require 'midwire_common/file'
+require 'midwire_common/integer'
+require 'midwire_common/float'
+require 'midwire_common/hash'
+require 'midwire_common/string'
+require 'midwire_common/time'
+require 'midwire_common/time_tool'
+require 'midwire_common/yaml_setting'
+
+module MidwireCommon
+  module All
+    include MidwireCommon::StringExtensions
+    include MidwireCommon::ArrayExtensions
+    include MidwireCommon::HashExtensions
+    include MidwireCommon::IntegerExtensions
+    include MidwireCommon::FloatExtensions
+    include MidwireCommon::EnumerableExtensions
+    include MidwireCommon::TimeExtensions
+    include MidwireCommon::FileExtensions
+  end
+end
+```
+
+Key change: `fixnum` → `integer`. Adds `MidwireCommon::All` module composing all refinement modules so consumers can `using MidwireCommon::All`.
+
+**Step 2: Update midwire_common.rb**
+
+Replace full contents of `lib/midwire_common.rb`:
+
+```ruby
+require 'pathname'
+require 'midwire_common/version'
+
+module MidwireCommon
+  class << self
+    def root
+      Pathname.new(File.dirname(__FILE__)).parent
+    end
+  end
+
+  autoload :BottomlessHash, 'midwire_common/hash'
+  autoload :DataFileCache,  'midwire_common/data_file_cache'
+  autoload :NumberBehavior,  'midwire_common/number_behavior'
+  autoload :RakeHelper,      'midwire_common/rake_helper'
+  autoload :TimeTool,        'midwire_common/time_tool'
+  autoload :YamlSetting,     'midwire_common/yaml_setting'
+end
+```
+
+Added autoloads for all utility classes so they're accessible without requiring `all.rb`.
+
+**Step 3: Run full test suite**
+
+```bash
+bundle exec rspec
+```
+
+Expected: All tests pass.
+
+**Step 4: Commit**
+
+```bash
+git add lib/midwire_common/all.rb lib/midwire_common.rb
+git commit -m "refactor: update all.rb with composed refinements module
+
+Add MidwireCommon::All for 'using MidwireCommon::All'.
+Add autoloads for utility classes."
+```
+
+---
+
+### Task 12: Update README and CLAUDE.md
+
+**Files:**
+- Modify: `README.md`
+- Modify: `CLAUDE.md`
+
+**Step 1: Update README.md**
+
+Update the version string and usage section in `README.md` to reflect the new refinements API:
+
+- Change `**Version: 1.1.1**` to `**Version: 2.0.0**`
+- Update the Usage section to show `using` instead of `require`:
+
+```markdown
+## Usage
+
+### Ruby Class Extensions
+
+Require the extensions, then activate them with `using`:
+
+    require 'midwire_common/all'
+    using MidwireCommon::All
+
+... or include individual refinement modules:
+
+    require 'midwire_common/string'
+    using MidwireCommon::StringExtensions
+```
+
+- Update the `required_ruby_version` note if present
+
+**Step 2: Update CLAUDE.md**
+
+Update loading section to document the `using` pattern and the `MidwireCommon::All` module.
+
+**Step 3: Commit**
+
+```bash
+git add README.md CLAUDE.md
+git commit -m "docs: update README and CLAUDE.md for 2.0.0 refinements API"
+```
+
+---
+
+### Task 13: Final verification
+
+**Step 1: Run full test suite**
+
+```bash
+bundle exec rspec
+```
+
+Expected: All tests pass, zero failures.
+
+**Step 2: Run tests with coverage**
+
+```bash
+COVERAGE=1 bundle exec rspec
+```
+
+Review the coverage report for any gaps.
+
+**Step 3: Verify the gem builds**
+
+```bash
+gem build midwire_common.gemspec
+```
+
+Expected: `midwire_common-2.0.0.gem` built successfully.
+
+**Step 4: Clean up gem file**
+
+```bash
+rm midwire_common-2.0.0.gem
+```
+
+---
+
+## Task Dependency Graph
+
+```
+Task 1 (infrastructure) ──→ Task 2 (spec_helper) ──→ Task 3 (String) ──→ Task 4 (Array)
+                                                         │                    │
+                                                         ├→ Task 5 (Hash)     │
+                                                         ├→ Task 6 (Integer)  │
+                                                         ├→ Task 7 (Float)    │
+                                                         ├→ Task 8 (Enum)     │
+                                                         ├→ Task 9 (Time)     │
+                                                         └→ Task 10 (File)    │
+                                                                              │
+Tasks 4-10 all complete ──→ Task 11 (all.rb) ──→ Task 12 (docs) ──→ Task 13 (verify)
+```
+
+Tasks 4-10 can be executed in parallel after Task 3 completes (they don't depend on each other). Task 11 depends on all of them completing.