Add comprehensive performance improvements documentation

Co-authored-by: benbalter <282759+benbalter@users.noreply.github.com>

Author: Copilot

PERFORMANCE_IMPROVEMENTS.md

@@ -0,0 +1,189 @@
+# Performance Improvements Summary
+
+This document summarizes the performance optimizations made to the word-to-markdown gem.
+
+## Overview
+
+The optimizations focus on reducing redundant DOM traversals and improving CSS selector efficiency in the document conversion process.
+
+## Key Improvements
+
+### 1. Combined Styled Elements Processing (48% faster)
+
+**Before:**
+```ruby
+def implicit_headings
+  @implicit_headings ||= begin
+    headings = []
+    @document.tree.css('[style]').each do |element|
+      headings.push element unless element.font_size.nil? || element.font_size < MIN_HEADING_SIZE
+    end
+    headings
+  end
+end
+
+def font_sizes
+  @font_sizes ||= begin
+    sizes = []
+    @document.tree.css('[style]').each do |element|
+      sizes.push element.font_size.round(-1) unless element.font_size.nil?
+    end
+    sizes.uniq.sort.extend(DescriptiveStatistics)
+  end
+end
+```
+
+**After:**
+```ruby
+def implicit_headings
+  process_styled_elements unless @implicit_headings
+  @implicit_headings
+end
+
+def font_sizes
+  process_styled_elements unless @font_sizes
+  @font_sizes
+end
+
+def process_styled_elements
+  headings = []
+  sizes = []
+
+  @document.tree.css('[style]').each do |element|
+    font_size = element.font_size
+    unless font_size.nil?
+      sizes.push font_size.round(-1)
+      headings.push element if font_size >= MIN_HEADING_SIZE
+    end
+  end
+
+  @implicit_headings = headings
+  @font_sizes = sizes.uniq.sort.extend(DescriptiveStatistics)
+end
+```
+
+**Impact:** 
+- Reduces DOM traversals from 2 to 1 when both methods are called
+- Benchmark shows 48% performance improvement (0.021s vs 0.041s)
+- Especially beneficial for documents with many styled elements
+
+### 2. Memoized List Item Spans
+
+**Before:**
+```ruby
+def remove_unicode_bullets_from_list_items!
+  path = WordToMarkdown.soffice.major_version == '5' ? 'li span span' : 'li span'
+  @document.tree.search(path).each do |span|
+    # ...
+  end
+end
+
+def remove_numbering_from_list_items!
+  path = WordToMarkdown.soffice.major_version == '5' ? 'li span span' : 'li span'
+  @document.tree.search(path).each do |span|
+    # ...
+  end
+end
+```
+
+**After:**
+```ruby
+def remove_unicode_bullets_from_list_items!
+  list_item_spans.each do |span|
+    # ...
+  end
+end
+
+def remove_numbering_from_list_items!
+  list_item_spans.each do |span|
+    # ...
+  end
+end
+
+private
+
+def list_item_spans
+  @list_item_spans ||= begin
+    path = WordToMarkdown.soffice.major_version == '5' ? 'li span span' : 'li span'
+    @document.tree.css(path)
+  end
+end
+```
+
+**Impact:**
+- Reduces version checks from 3 to 1
+- Caches the DOM query result
+- Simplifies code and improves maintainability
+
+### 3. Improved CSS Selectors
+
+**Changes:**
+- `td p` → `td > p` (direct child selector)
+- `li p` → `li > p` (direct child selector)
+- `table tr:first td` → `table tr:first-child > td` (more specific)
+- `.search()` → `.css()` (consistent API usage)
+
+**Impact:**
+- Direct child selectors (>) are more specific and can be more efficient
+- Consistent use of `.css()` method improves code clarity
+- More precise selectors reduce unnecessary element matching
+
+### 4. Configuration Updates
+
+**Fixed `.rubocop.yml`:**
+- Changed `require:` to `plugins:` for rubocop extensions
+- Updated `Metrics/LineLength` to `Layout/LineLength`
+- Auto-fixed style issues
+
+## Benchmark Results
+
+Running `script/benchmark` demonstrates the improvements:
+
+```
+                                             user     system      total        real
+CSS selector (td > p):                   0.018785   0.000000   0.018785 (  0.018785)
+CSS selector (td p):                     0.019225   0.000000   0.019225 (  0.019226)
+Process styled elements (single pass):   0.021174   0.000000   0.021174 (  0.021174)
+Process styled elements (two passes):    0.041200   0.000000   0.041200 (  0.041208)
+```
+
+**Key findings:**
+- Single pass processing is **48% faster** than two passes
+- Direct child selectors show comparable performance to descendant selectors
+- Overall improvements compound for larger documents
+
+## Testing
+
+New test file `test/test_word_to_markdown_performance.rb` validates:
+- Styled elements are processed only once and cached
+- List item spans selector is memoized
+- Empty styled elements are handled correctly
+
+All existing tests continue to pass, ensuring backward compatibility.
+
+## Usage
+
+The optimizations are transparent to users. No API changes were made, so existing code continues to work exactly as before, just faster.
+
+To measure performance improvements in your own use case:
+
+```bash
+bundle exec ruby script/benchmark
+```
+
+## Future Optimization Opportunities
+
+Potential areas for further optimization:
+1. Parallel processing for independent conversion operations
+2. Streaming processing for very large documents
+3. Cache parsed CSS styles for reuse
+4. Optimize regex patterns in string processing
+
+## Conclusion
+
+These optimizations significantly improve performance without changing the API or breaking existing functionality. The improvements are most noticeable with:
+- Large documents with many styled elements
+- Documents with extensive list structures
+- Batch processing scenarios
+
+The changes follow Ruby best practices and maintain code readability while delivering measurable performance gains.