type_balancer 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c93fa5dcb75821b9f9ea3340f06ca63d67f84781bcf90f13ac089abac7283b7
-  data.tar.gz: fbfadcf9eed52f9f82a5f0a99f05fe3801c8529c32735f3d2eac5b0d42648a4b
+  metadata.gz: 404bf713a39abab585e33e9f196d6f9e0ab21f11b07a14fbc91d37a8ac1f2ce7
+  data.tar.gz: 6f5975a9e2a4789645779d3d4fc8463cf8140250b15d650b32e2f8096ebbd9b7
 SHA512:
-  metadata.gz: 316f4c79fb96b3ff7362a61a4524f2d08e67be712b23f6c1a6f36d4b24332ae58266ce2fbd6dd39a7deea190f9f2f9e965c0bafe94443dd24be571ed62f302fd
-  data.tar.gz: 054a3439add0798dc20593ace1681734fbed87f4d162baeb9e41b6f672cbbb43c7c2b17cd67a92d2c1a4a047b9418707139c2168cdcbde08a105376af53eb39e
+  metadata.gz: 8c8f8754168d393a49e0c705a633fefdfda11e0d18f56bc224459549eff14948ad659219fcf9bc0b97acc22b61147c75aace1d3fb33ae344b6158592a68720c5
+  data.tar.gz: d7a52bbff78479249faf11e3d38a1c8821324221d5b226db310a31918aa1a5f209358c2d375b8f0b876f08bb7d49dbaaac188aa3f2d06e61ba96232e327b9e07

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.2.0] - 2025-04-30
+
+### Added
+- Introduced strategy pattern for flexible balancing algorithms
+- Added sliding window strategy as the default balancing algorithm
+  - Configurable window size (default: 10)
+  - Maintains both local and global type ratios
+  - Adaptive behavior for remaining items
+- Added comprehensive strategy documentation in README and balance.md
+- Added large scale balance test suite for thorough strategy validation
+
+### Enhanced
+- Improved quality testing infrastructure
+  - Added quality:all rake task that runs both quality.rb and large_scale_balance_test.rb
+  - Enhanced CI workflow to run all quality checks
+  - Added strategy-specific test cases
+- Updated documentation with detailed strategy explanations and use cases
+- Added extensive test coverage for strategy system
+
+### Fixed
+- Improved handling of type distribution in edge cases
+- Better handling of remaining items when types are depleted
+- Enhanced transition handling between windows
+
 ## [0.1.4] - 2025-04-29
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    type_balancer (0.1.4)
+    type_balancer (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -52,15 +52,69 @@ items = [
   # ... more items
 ]
 
-# Balance items by type
+# Balance items by type (uses default sliding window strategy)
 balanced_items = TypeBalancer.balance(items, type_field: :type)
+
+# Use sliding window strategy with custom window size
+balanced_items = TypeBalancer.balance(items, 
+  type_field: :type,
+  strategy: :sliding_window,
+  window_size: 25
+)
 ```
 
 ## Balancing Collections with `TypeBalancer.balance`
 
 The primary method for balancing collections is `TypeBalancer.balance`. This method takes an array of items and distributes them by type, ensuring optimal spacing and respecting type ratios.
 
-**Basic Example:**
+### Available Strategies
+
+TypeBalancer uses a strategy pattern to provide different balancing algorithms. Currently, the gem implements a sophisticated sliding window strategy as its default approach:
+
+#### Sliding Window Strategy (Default)
+The sliding window strategy balances items by examining a fixed-size window of items at a time (default size: 10). Within each window, it maintains the overall ratio of types while ensuring each type gets fair representation. This creates both local and global balance in your content distribution.
+
+**When to Use Sliding Window Strategy:**
+- Content feeds where users might stop scrolling at any point
+- When you want to ensure diversity in any segment of your list
+- When you need to maintain both local and global balance
+- When you want to prevent long runs of the same type while still allowing some natural clustering
+
+**Window Size Selection Guide:**
+- Small windows (5-10): Strict local balance, ideal for shorter lists or when immediate diversity is critical
+- Medium windows (15-25): Balance between local and global distribution
+- Large windows (30+): More gradual transitions, better for preserving some natural clustering
+
+```ruby
+# Basic usage with default window size (10)
+balanced = TypeBalancer.balance(items, type_field: :type)
+
+# Custom window size for stricter local balance
+balanced = TypeBalancer.balance(items, 
+  type_field: :type,
+  strategy: :sliding_window,
+  window_size: 5
+)
+
+# Larger window for more gradual transitions
+balanced = TypeBalancer.balance(items,
+  type_field: :type,
+  strategy: :sliding_window,
+  window_size: 25
+)
+
+# With custom type ordering
+balanced = TypeBalancer.balance(items,
+  type_field: :type,
+  strategy: :sliding_window,
+  window_size: 15,
+  type_order: %w[image video article]
+)
+```
+
+The strategy system is designed to be extensible, allowing for future implementations of different balancing algorithms as needed.
+
+### Basic Example
 
 ```ruby
 items = [
@@ -73,18 +127,25 @@ balanced = TypeBalancer.balance(items, type_field: :type)
 # => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
 ```
 
-**Custom Type Order:**
+### Custom Type Order
 
 You can specify a custom order for types using the `type_order` argument. This controls the priority of types in the balanced output.
 
 ```ruby
 # Prioritize images, then videos, then articles
-balanced = TypeBalancer.balance(items, type_field: :type, type_order: %w[image video article])
+balanced = TypeBalancer.balance(items,
+  type_field: :type,
+  type_order: %w[image video article],
+  strategy: :sliding_window,
+  window_size: 15
+)
 # => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
 ```
 
 - `type_field`: The key to use for type extraction (default: `:type`).
 - `type_order`: An array of type names (as strings) specifying the desired order.
+- `strategy`: The balancing strategy to use (default: `:sliding_window`).
+- `window_size`: Size of the sliding window for the sliding window strategy (default: 10).
 
 For more advanced usage and options, see [Detailed Balance Method Documentation](docs/balance.md).
 

data/Rakefile

@@ -17,6 +17,24 @@ Rake::ExtensionTask.new('type_balancer') do |ext|
   ext.config_options = ['--with-cflags=-Wall -Wextra -O3']
 end
 
+# Quality check tasks
+namespace :quality do
+  desc 'Run basic quality checks'
+  task :basic do
+    puts "\nRunning basic quality checks..."
+    ruby '-I lib examples/quality.rb'
+  end
+
+  desc 'Run large scale balance tests'
+  task :large_scale do
+    puts "\nRunning large scale balance tests..."
+    ruby '-I lib examples/large_scale_balance_test.rb'
+  end
+
+  desc 'Run all quality checks'
+  task all: %i[basic large_scale]
+end
+
 # Add GoogleTest task using CMake
 namespace :gtest do
   desc 'Build and run all GoogleTest tests'
@@ -62,7 +80,7 @@ task test_with_mocks: [:spec] do
   Rake::Task['gtest:all'].invoke
 end
 
-task default: [:test_with_mocks, 'lint:all']
+task default: [:test_with_mocks, 'lint:all', 'quality:all']
 
 # Benchmark tasks
 namespace :benchmark do

data/docs/balance.md

@@ -1,25 +1,124 @@
 # Detailed Documentation: `TypeBalancer.balance`
 
-`TypeBalancer.balance` is the main method for distributing items of different types across a sequence, ensuring optimal spacing and respecting type ratios. It is highly configurable and supports custom type fields and type orderings.
+`TypeBalancer.balance` is the main method for distributing items of different types across a sequence, ensuring optimal spacing and respecting type ratios. It is highly configurable and supports custom type fields, type orderings, and different balancing strategies.
 
 ## Method Signature
 
 ```ruby
-TypeBalancer.balance(items, type_field: :type, type_order: nil)
+TypeBalancer.balance(items, type_field: :type, type_order: nil, strategy: nil, **strategy_options)
 ```
 
 ### Arguments
 - `items` (Array<Hash>): The collection of items to balance. Each item should have a type field (default: `:type`).
 - `type_field` (Symbol/String, optional): The key to use for extracting the type from each item. Default is `:type`.
 - `type_order` (Array<String>, optional): An array specifying the desired order of types in the output. If omitted, the gem determines the order automatically.
+- `strategy` (Symbol, optional): The balancing strategy to use. Default is `:sliding_window`.
+- `strategy_options` (Hash, optional): Additional options specific to the chosen strategy.
 
-## Return Value
-- Returns a new array of items, balanced by type and spaced as evenly as possible.
-- The output array will have the same length as the input.
+## Available Strategies
+
+### 1. Sliding Window Strategy (default)
+The sliding window strategy is a sophisticated approach that balances items by examining fixed-size windows of items sequentially. For each window, it:
+1. Calculates the target ratio of each type based on the overall collection
+2. Ensures minimum representation of each type when possible
+3. Distributes remaining slots to maintain target ratios
+4. Handles transitions between windows to maintain smooth distribution
+
+**Technical Details:**
+- Default window size: 10 items
+- Minimum representation: Each type gets at least one slot in a window if ratio > 0
+- Ratio preservation: Maintains approximate global ratios while ensuring local diversity
+- Adaptive sizing: Window size automatically adjusts near the end of the collection
+
+**Configuration Options:**
+```ruby
+TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 25,        # Size of the sliding window
+  type_field: :type,      # Field containing type information
+  type_order: %w[...]     # Optional: preferred type order
+)
+```
+
+**When to Use:**
+1. **Content Feed Optimization**
+   - Perfect for social media feeds, blog lists, or any paginated content
+   - Ensures users see a diverse mix regardless of where they stop scrolling
+   ```ruby
+   TypeBalancer.balance(posts, 
+     strategy: :sliding_window,
+     window_size: 10
+   )
+   ```
+
+2. **E-commerce Category Display**
+   - Balances product types in search results or category pages
+   - Maintains category ratios while ensuring variety
+   ```ruby
+   TypeBalancer.balance(products,
+     strategy: :sliding_window,
+     window_size: 15,
+     type_field: :category
+   )
+   ```
+
+3. **News Feed Management**
+   - Mixes different news categories while maintaining importance
+   - Larger windows allow for some natural clustering
+   ```ruby
+   TypeBalancer.balance(articles,
+     strategy: :sliding_window,
+     window_size: 25,
+     type_order: %w[breaking featured regular]
+   )
+   ```
+
+**Window Size Guidelines:**
+- **Small (5-10 items)**
+  - Strictest local balance
+  - Best for: Short lists, critical diversity needs
+  - Example: Featured content sections
+
+- **Medium (15-25 items)**
+  - Balanced local/global distribution
+  - Best for: Standard content feeds
+  - Example: Blog post listings
+
+- **Large (30+ items)**
+  - More gradual transitions
+  - Best for: Long-form content, natural grouping
+  - Example: Search results with category clustering
+
+**Implementation Notes:**
+- The strategy maintains a queue for each type
+- Window calculations consider both used and available items
+- Edge cases (end of collection, single type) are handled gracefully
+- Performance scales linearly with collection size
+
+**Example with Analysis:**
+```ruby
+# Balance a feed with analytics
+items = [
+  { type: 'video', id: 1 },
+  { type: 'article', id: 2 },
+  # ... more items
+]
+
+balanced = TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 15,
+  type_field: :type
+)
+
+# Analyze distribution in first window
+first_window = balanced.first(15)
+distribution = first_window.group_by { |i| i[:type] }
+                         .transform_values(&:count)
+```
 
 ## Usage Examples
 
-### 1. Basic Balancing
+### 1. Basic Balancing (Default Strategy)
 ```ruby
 items = [
   { type: 'video', title: 'Video 1' },
@@ -33,11 +132,14 @@ balanced = TypeBalancer.balance(items)
 # => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
 ```
 
-### 2. Custom Type Order
+### 2. Custom Strategy Options
 ```ruby
-# Prioritize images, then videos, then articles
-balanced = TypeBalancer.balance(items, type_order: %w[image video article])
-# => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
+# Large window size for more gradual transitions
+balanced = TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 50,
+  type_order: %w[image video article]
+)
 ```
 
 ### 3. Custom Type Field
@@ -64,6 +166,7 @@ If a type in `type_order` is not present in the input, it is simply ignored in t
 - The `type_order` argument must be an array of strings matching the type values in your items.
 - If you use a custom `type_field`, ensure all items have that field.
 - The method does not mutate the input array.
+- Strategy options are specific to each strategy and are ignored by other strategies.
 
 ## See Also
 - [README.md](../README.md) for general usage

data/docs/quality.md

@@ -53,15 +53,23 @@ The script tests several key aspects of the TypeBalancer gem:
 - Shows spacing calculations between positions
 - Verifies edge cases (single item, no items, all items)
 
-### 2. Robust Balance Method Tests
+### 2. Strategy System
+- Tests the default sliding window strategy
+- Verifies behavior with different window sizes
+- Checks strategy options and customization
+- Ensures backward compatibility with existing code
+
+### 3. Robust Balance Method Tests
 - Loads scenarios from a YAML file (`examples/balance_test_data.yml`)
 - Tests `TypeBalancer.balance` with and without the `type_order` argument
+- Tests different strategy configurations
 - Checks type counts, custom order, and exception handling for empty input
 - Prints a color-coded summary table for pass/fail counts
 
-### 3. Content Feed Example
+### 4. Content Feed Example
 - Shows a real-world example of content type distribution
 - Verifies position allocation for different content types (video, image, article)
+- Tests strategy behavior with real-world data
 - Checks distribution statistics and ratios
 
 ## Output Format

data/examples/large_scale_balance_test.rb

@@ -0,0 +1,289 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/AbcSize
+# rubocop:disable Metrics/CyclomaticComplexity
+# rubocop:disable Metrics/PerceivedComplexity
+
+require 'type_balancer'
+require 'yaml'
+require 'json'
+
+class LargeScaleBalanceTest
+  GREEN = "\e[32m"
+  RED = "\e[31m"
+  YELLOW = "\e[33m"
+  RESET = "\e[0m"
+
+  def initialize
+    @total_records = 500
+    @type_distribution = {
+      'type_a' => 250, # 50%
+      'type_b' => 175, # 35%
+      'type_c' => 75   # 15%
+    }
+    @window_sizes = [10, 25, 50, 100]
+    @failures = []
+    @tests_run = 0
+    @tests_passed = 0
+  end
+
+  def run
+    puts "\n#{YELLOW}Running Large Scale Balance Test#{RESET}"
+    puts "Total Records: #{@total_records}"
+    puts 'Distribution:'
+    @type_distribution.each do |type, count|
+      puts "  #{type}: #{count} (#{(count.to_f / @total_records * 100).round(1)}%)"
+    end
+
+    test_data = generate_test_data
+
+    # Test default strategy
+    puts "\n#{YELLOW}Testing Default Strategy (Sliding Window)#{RESET}"
+    run_balance_test(test_data)
+
+    # Test with different window sizes
+    @window_sizes.each do |size|
+      puts "\n#{YELLOW}Testing Sliding Window Strategy with Window Size #{size}#{RESET}"
+      run_balance_test(test_data, strategy: :sliding_window, window_size: size)
+    end
+
+    # Test with custom type order
+    puts "\n#{YELLOW}Testing with Custom Type Order#{RESET}"
+    run_balance_test(
+      test_data,
+      strategy: :sliding_window,
+      types: %w[type_c type_b type_a],
+      window_size: 25
+    )
+
+    print_summary
+    @failures.empty?
+  end
+
+  private
+
+  def record_failure(message)
+    @failures << message
+  end
+
+  def generate_test_data
+    items = []
+    @type_distribution.each do |type, count|
+      count.times do |i|
+        items << { type: type, id: "#{type}_#{i + 1}" }
+      end
+    end
+    items.shuffle
+  end
+
+  def run_balance_test(items, strategy_options = {})
+    @tests_run += 1
+    puts "\nRunning balance test..."
+    puts "Strategy options: #{strategy_options.inspect}" unless strategy_options.empty?
+
+    # Balance the items
+    balanced_items = TypeBalancer.balance(items, type_field: :type, **strategy_options)
+
+    # Track if this test passes
+    test_passed = true
+
+    # Get window size (default is 10)
+    window_size = strategy_options[:window_size] || 10
+
+    # Track remaining items for each type
+    remaining_items = @type_distribution.dup
+
+    # Analyze windows
+    balanced_items.each_slice(window_size).with_index do |window, index|
+      window_result = analyze_window(window, index + 1, remaining_items)
+      test_passed = false unless window_result
+
+      # Update remaining items
+      window.each do |item|
+        remaining_items[item[:type]] -= 1
+      end
+    end
+
+    # Analyze full distribution
+    distribution_result = analyze_full_distribution(balanced_items)
+    test_passed = false unless distribution_result
+
+    # Analyze type transitions
+    transition_result = analyze_type_transitions(balanced_items)
+    test_passed = false unless transition_result
+
+    @tests_passed += 1 if test_passed
+  end
+
+  def analyze_window(items, window_number, remaining_items)
+    puts "\nAnalyzing window #{window_number} (#{items.size} items):"
+    distribution = items.map { |item| item[:type] }.tally
+    window_passed = true
+
+    distribution.each do |type, count|
+      percentage = (count.to_f / items.size * 100).round(1)
+      puts "#{type}: #{count} (#{percentage}%)"
+    end
+
+    # Calculate how many items we have left to work with
+    total_remaining = remaining_items.values.sum
+    remaining_items.transform_values { |count| count.to_f / total_remaining }
+
+    # Only enforce strict distribution when we have enough items of each type
+    has_enough_items = remaining_items.values.all? { |count| count >= items.size / 3 }
+
+    if has_enough_items
+      # When we have enough items, ensure each type that has items left appears at least once
+      remaining_items.each do |type, count|
+        next if count <= 0
+
+        unless distribution.key?(type)
+          record_failure("Window #{window_number}: #{type} does not appear but has #{count} items remaining")
+          window_passed = false
+        end
+      end
+
+      # Prevent any type from completely dominating a window when we have enough items
+      max_allowed = (items.size * 0.7).ceil # Allow up to 70% when we have enough items
+      distribution.each do |type, count|
+        next unless count > max_allowed
+
+        message = "Window #{window_number}: #{type} appears #{count} times (#{percentage}%), "
+        message += "exceeding maximum allowed #{max_allowed} when sufficient items remain"
+        record_failure(message)
+        window_passed = false
+      end
+    else
+      # When running low on items, just verify we're using available items efficiently
+      distribution.each do |type, count|
+        max_possible = [remaining_items[type], items.size].min
+        next unless count > max_possible
+
+        message = "Window #{window_number}: #{type} appears #{count} times but only had #{max_possible} items available"
+        record_failure(message)
+        window_passed = false
+      end
+    end
+
+    window_passed
+  end
+
+  def analyze_full_distribution(balanced_items)
+    puts "\nFull Distribution Analysis:"
+    distribution = balanced_items.map { |item| item[:type] }.tally
+    distribution_passed = true
+
+    distribution.each do |type, count|
+      percentage = (count.to_f / balanced_items.length * 100).round(1)
+      target_percentage = (@type_distribution[type].to_f / @total_records * 100).round(1)
+      diff = (percentage - target_percentage).abs.round(1)
+      color = if diff <= 0.1
+                GREEN
+              elsif diff <= 0.5
+                YELLOW
+              else
+                RED
+              end
+      puts "#{color}#{type}: #{count} (#{percentage}%) - Target: #{target_percentage}% (Diff: #{diff}%)#{RESET}"
+
+      # Full distribution should be very close to target
+      next unless diff > 0.5
+
+      message = "Full distribution: #{type} off by #{diff}% "
+      message += "(expected #{target_percentage}%, got #{percentage}%)"
+      record_failure(message)
+      distribution_passed = false
+    end
+
+    distribution_passed
+  end
+
+  def analyze_type_transitions(items)
+    puts "\nType Transition Analysis:"
+    transitions = Hash.new { |h, k| h[k] = Hash.new(0) }
+    total_transitions = 0
+    transition_passed = true
+
+    # Track consecutive occurrences
+    current_type = nil
+    consecutive_count = 0
+    remaining_items = @type_distribution.dup
+
+    items.each do |item|
+      # Update remaining items
+      remaining_items[item[:type]] -= 1
+      total_remaining = remaining_items.values.sum
+      available_types = remaining_items.count { |_, count| count.positive? }
+
+      if item[:type] == current_type
+        consecutive_count += 1
+        # Allow longer runs when we're running out of items
+        max_consecutive = if available_types >= 3 && total_remaining >= 100
+                            5 # Strict when we have lots of items and all types
+                          elsif available_types >= 2 && total_remaining >= 50
+                            8  # More lenient as we start running out
+                          elsif available_types >= 2 && total_remaining >= 20
+                            12 # Even more lenient with two types
+                          else
+                            Float::INFINITY # No limit when almost out or only one type left
+                          end
+
+        if consecutive_count > max_consecutive
+          message = "Found #{consecutive_count} consecutive #{current_type} items "
+          message += "when #{total_remaining} total items remained (#{available_types} types available)"
+          record_failure(message)
+          transition_passed = false
+          break # Stop checking transitions once we find a violation
+        end
+      else
+        consecutive_count = 1
+        current_type = item[:type]
+      end
+    end
+
+    # Analyze transitions for information only
+    items.each_cons(2) do |a, b|
+      transitions[a[:type]][b[:type]] += 1
+      total_transitions += 1
+    end
+
+    transitions.each do |from_type, to_types|
+      puts "\nTransitions from #{from_type}:"
+      to_types.each do |to_type, count|
+        percentage = (count.to_f / total_transitions * 100).round(1)
+        puts "  to #{to_type}: #{count} (#{percentage}%)"
+      end
+    end
+
+    transition_passed
+  end
+
+  def print_summary
+    puts "\n#{'-' * 50}"
+    if @failures.empty?
+      puts "#{GREEN}All tests passed!#{RESET}"
+    else
+      puts "#{RED}#{@failures.size} test failures:#{RESET}"
+      @failures.each_with_index do |failure, index|
+        puts "#{index + 1}. #{failure}"
+      end
+    end
+    puts "Tests run: #{@tests_run}"
+    puts "Tests passed: #{@tests_passed}"
+    puts('-' * 50)
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  test = LargeScaleBalanceTest.new
+  exit(test.run ? 0 : 1)
+end
+
+# rubocop:enable Metrics/ClassLength
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/AbcSize
+# rubocop:enable Metrics/CyclomaticComplexity
+# rubocop:enable Metrics/PerceivedComplexity