type_balancer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d017bcd987973e61c2cca2f30f3a968ebccc0604b7043e44fd7ca4aa22a57a2
+  data.tar.gz: 214815b85a1095b6c4b9b853c6154b3c919d4671db2c69a6730ca21dcad5c559
+SHA512:
+  metadata.gz: c8e8dd1cd9854f80d68a54475e13634bb2ca2e78350f9fe4994252a502bd7acd75d764f7a7c0bd779808ebf39ba496289efa50f8bc7a281391d9e11d3a8ab500
+  data.tar.gz: fbcec72c85c4480f6b035f07bc8f49311798b90dd14c6eaf8cf4a7054c8ec2e7ded4ef9d1dd08e9029a5ce2f698696054f9f96191fae5f88461ad5d303aa10c8

data/.rubocop.yml

@@ -0,0 +1,96 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/*'
+    - 'ext/**/*'
+    - 'benchmark/**/*'
+    - 'vendor/**/*'
+    - 'examples/quality.rb'
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/type_balancer/distributor.rb'
+    - 'lib/type_balancer/balancer.rb'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'lib/type_balancer/distributor.rb'
+    - 'lib/type_balancer/balancer.rb'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+  Exclude:
+    - 'lib/type_balancer/distributor.rb'
+    - 'lib/type_balancer/balancer.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 10
+  Exclude:
+    - 'lib/type_balancer/distributor.rb'
+    - 'lib/type_balancer/balancer.rb'
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/RepeatedExample:
+  Enabled: false  # We have intentionally repeated examples
+
+RSpec/MultipleDescribes:
+  Enabled: false  # We have intentionally structured our specs this way
+
+RSpec/RepeatedExampleGroupDescription:
+  Enabled: false  # We have intentionally structured our specs this way
+
+# Disable all Capybara/RSpec cops
+Capybara/RSpec:
+  Enabled: false
+
+# Disable all RSpec/Capybara cops
+RSpec/Capybara:
+  Enabled: false
+
+# Disable all RSpec/FactoryBot cops
+RSpec/FactoryBot:
+  Enabled: false
+
+# Disable all RSpec/Rails cops
+RSpec/Rails:
+  Enabled: false
+
+# Disable PredicateMatcher cop that's causing errors
+RSpec/PredicateMatcher:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-29
+
+- Initial release

data/Dockerfile

@@ -0,0 +1,38 @@
+# Allow platform to be specified at build time
+ARG PLATFORM=linux/arm64
+ARG RUBY_VERSION
+FROM --platform=${PLATFORM} ruby:${RUBY_VERSION}-slim
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    build-essential \
+    pkg-config \
+    libffi-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Rust if YJIT is enabled
+ARG ENABLE_YJIT=false
+RUN if [ "${ENABLE_YJIT}" = "true" ]; then \
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y; \
+    fi
+
+WORKDIR /app
+
+# Copy all necessary files for building the gem
+COPY Gemfile Gemfile.lock type_balancer.gemspec Rakefile ./
+COPY lib/ lib/
+COPY sig/ sig/
+COPY benchmark/ benchmark/
+
+# Initialize Git repository and stage files (needed for gemspec)
+RUN git init && \
+    git add .
+
+# Install dependencies
+RUN bundle install
+
+# Set environment variable for Ruby to find native extensions
+ENV RUBYLIB=/app/lib
+
+CMD ["bundle", "exec", "rake", "benchmark:complete"] 

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in type_balancer.gemspec
+gemspec
+
+group :development do
+  gem 'benchmark'
+  gem 'benchmark-ips', '~> 2.12'
+  gem 'ffi'
+  gem 'rake', '~> 13.0'
+  gem 'rake-compiler', '~> 1.2'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.21'
+  gem 'rubocop-rake', '~> 0.6.0'
+  gem 'rubocop-rspec', '~> 2.26'
+  gem 'simplecov', '~> 0.22.0'
+end

data/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: .
+  specs:
+    type_balancer (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    benchmark (0.4.0)
+    benchmark-ips (2.14.0)
+    diff-lcs (1.6.1)
+    docile (1.4.1)
+    ffi (1.17.1)
+    ffi (1.17.1-arm64-darwin)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    parallel (1.26.3)
+    parser (3.3.7.3)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rake-compiler (1.2.9)
+      rake
+    regexp_parser (2.10.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    rubocop (1.75.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.43.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.43.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  benchmark
+  benchmark-ips (~> 2.12)
+  ffi
+  rake (~> 13.0)
+  rake-compiler (~> 1.2)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  rubocop-rake (~> 0.6.0)
+  rubocop-rspec (~> 2.26)
+  simplecov (~> 0.22.0)
+  type_balancer!
+
+BUNDLED WITH
+   2.6.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Carl Smith
+
+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,86 @@
+<img src="https://www.ruby-lang.org/images/header-ruby-logo.png" width="50" align="right" alt="Ruby Logo"/>
+
+# TypeBalancer
+
+[![Gem Version](https://badge.fury.io/rb/type_balancer.svg)](https://badge.fury.io/rb/type_balancer)
+[![CI](https://github.com/llwebconsulting/type_balancer/actions/workflows/ci.yml/badge.svg)](https://github.com/llwebconsulting/type_balancer/actions/workflows/ci.yml)
+[![Ruby Coverage](https://img.shields.io/badge/ruby--coverage-78.57%25-yellow.svg)](https://github.com/llwebconsulting/type_balancer/blob/main/coverage/index.html)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+A Ruby gem for balancing and distributing items of different types across a sequence while maintaining optimal spacing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'type_balancer'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install type_balancer
+```
+
+## Usage
+
+```ruby
+items = [
+  { type: 'video', title: 'Video 1' },
+  { type: 'image', title: 'Image 1' },
+  { type: 'article', title: 'Article 1' },
+  # ... more items
+]
+
+# Balance items by type
+balanced_items = TypeBalancer.balance(items, type_field: :type)
+```
+
+## Performance Characteristics
+
+TypeBalancer is designed to handle collections of varying sizes efficiently. Here are the current performance metrics:
+
+- Tiny collections (10 items): Microsecond-level processing (9-14μs)
+- Small collections (100 items): Sub-millisecond processing (~450-500μs)
+- Medium collections (1,000 items): Fast processing (~20-21ms)
+- Large collections (10,000 items): Efficient processing (~193-209ms)
+
+Performance has been thoroughly tested across Ruby versions (3.2.8, 3.3.7, and 3.4.2). YJIT provides significant improvements for small datasets (up to 51% faster for tiny collections) with varying impact on larger datasets. For detailed benchmarks across Ruby versions and YJIT configurations, see our [benchmark documentation](docs/benchmarks/README.md).
+
+### Recommendations
+
+- Suitable for real-time processing of collections up to 10,000 items
+- Excellent performance for content management systems and feed generation
+- Thread-safe and memory-efficient
+- If you need to process very large collections (>10,000 items), consider batch processing or open an issue for guidance
+
+## Features
+
+- Maintains optimal spacing between items of the same type
+- Supports custom type fields
+- Preserves original item data
+- Thread-safe
+- Zero dependencies
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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/llwebconsulting/type_balancer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/llwebconsulting/type_balancer/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TypeBalancer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/llwebconsulting/type_balancer/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/extensiontask'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+Rake::ExtensionTask.new('type_balancer') do |ext|
+  ext.lib_dir = 'lib/type_balancer'
+  ext.ext_dir = 'ext/type_balancer'
+  ext.source_pattern = '*.{c,h}'
+  ext.config_options = ['--with-cflags=-Wall -Wextra -O3']
+end
+
+# Add GoogleTest task using CMake
+namespace :gtest do
+  desc 'Build and run all GoogleTest tests'
+  task :all do
+    Dir.chdir('c_tests') do
+      sh './build.sh'
+    end
+  end
+
+  desc 'Build and run a specific GoogleTest test (e.g., rake gtest:run[TestSuite.TestName])'
+  task :run, [:test_name] do |_, args|
+    test_filter = args[:test_name] ? "--gtest_filter=#{args[:test_name]}" : ''
+    Dir.chdir('c_tests') do
+      sh "rm -rf build && mkdir build && cd build && cmake .. && make && ./type_balancer_tests #{test_filter} | cat"
+    end
+  end
+
+  desc 'List all available GoogleTest tests'
+  task :list do
+    Dir.chdir('c_tests') do
+      sh 'rm -rf build && mkdir build && cd build && cmake .. && make && ./type_balancer_tests --gtest_list_tests | cat'
+    end
+  end
+end
+
+namespace :lint do
+  desc 'Run C linting with clang-tidy'
+  task :c do
+    mkdir_p 'c_tests/build'
+    Dir.chdir('c_tests/build') do
+      sh 'cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..'
+    end
+    sh 'clang-tidy -p c_tests/build ext/type_balancer/*.{c,h}'
+  end
+
+  desc 'Run all linting checks'
+  task all: %i[rubocop c]
+end
+
+desc 'Run all tests with proper mocking'
+task test_with_mocks: [:spec] do
+  puts 'Running tests with proper mocking...'
+  Rake::Task['gtest:all'].invoke
+end
+
+task default: [:test_with_mocks, 'lint:all']
+
+# Benchmark tasks
+namespace :benchmark do
+  desc 'Run distributor benchmark comparing C extension vs Pure Ruby (without YJIT)'
+  task :distributor do
+    ruby 'benchmark/distributor_benchmark.rb'
+  end
+
+  desc 'Run combined benchmark comparing full C vs Ruby implementations (without YJIT)'
+  task :combined do
+    ruby 'benchmark/combined_benchmark.rb'
+  end
+
+  desc 'Run all benchmarks (without YJIT)'
+  task all: %i[distributor combined]
+
+  namespace :yjit do
+    desc 'Run distributor benchmark comparing C extension vs Pure Ruby with YJIT enabled'
+    task :distributor do
+      ENV['RUBY_YJIT_ENABLE'] = '1'
+      ruby 'benchmark/distributor_benchmark.rb'
+    end
+
+    desc 'Run combined benchmark comparing full C vs Ruby implementations with YJIT enabled'
+    task :combined do
+      ENV['RUBY_YJIT_ENABLE'] = '1'
+      ruby 'benchmark/combined_benchmark.rb'
+    end
+
+    desc 'Run all benchmarks with YJIT enabled'
+    task all: %i[distributor combined]
+  end
+
+  desc 'Run all benchmarks with and without YJIT'
+  task complete: %i[all yjit:all]
+end

data/benchmark/README.md

@@ -0,0 +1,90 @@
+# TypeBalancer Benchmarks
+
+This directory contains benchmarks for measuring TypeBalancer's performance across different Ruby versions and configurations.
+
+## Latest Benchmark Results
+
+Tests run on ARM64 platform (M-series Mac via Docker) with Ruby versions 3.2.8, 3.3.7, and 3.4.2, both with and without YJIT.
+
+### Processing Time by Dataset Size
+
+#### Tiny Dataset (10 items)
+- Processing time: ~15 microseconds
+- Throughput: ~65-70k operations/second
+- Even distribution achieved: 40/30/30 split
+
+#### Small Dataset (100 items)
+- Processing time: ~550 microseconds
+- Throughput: ~1.8k operations/second
+- Even distribution achieved: 34/33/33 split
+
+#### Medium Dataset (1,000 items)
+- Processing time: ~50 milliseconds
+- Throughput: ~20 operations/second
+- Even distribution achieved: 33.4/33.3/33.3 split
+
+#### Large Dataset (10,000 items)
+- Processing time: ~4.3-4.7 seconds
+- Throughput: ~0.21-0.23 operations/second
+- Even distribution achieved: 33.34/33.33/33.33 split
+
+### Performance Analysis
+
+#### Ruby Version Comparison (10,000 items)
+| Ruby Version | YJIT | Time (seconds) |
+|-------------|------|----------------|
+| 3.2.8       | No   | 4.37          |
+| 3.2.8       | Yes  | 4.29          |
+| 3.3.7       | No   | 4.45          |
+| 3.3.7       | Yes  | 4.31          |
+| 3.4.2       | No   | 4.71          |
+| 3.4.2       | Yes  | 4.71          |
+
+#### Key Findings
+1. YJIT Impact:
+   - Provides modest improvements (2-3%) on larger datasets
+   - Most effective with Ruby 3.2.8
+   - Diminishing returns in newer Ruby versions
+
+2. Scaling Characteristics:
+   - Performance scales non-linearly with dataset size
+   - Sweet spot appears to be around 1,000 items
+   - Processing time increases significantly beyond 1,000 items
+
+3. Distribution Quality:
+   - Maintains excellent distribution ratios across all dataset sizes
+   - Larger datasets achieve near-perfect distribution (33.33%)
+
+## Current Limitations and Future Work
+
+1. Performance Concerns:
+   - Large datasets (>10,000 items) process slower than desired
+   - Non-linear scaling suggests algorithmic optimization opportunities
+   - Current implementation prioritizes distribution quality over speed
+
+2. Optimization Priorities:
+   - Improve processing time for large datasets
+   - Investigate algorithmic improvements in distribution logic
+   - Explore parallel processing options for large collections
+
+3. Recommendations:
+   - For production use, process collections of ≤1,000 items at a time
+   - Break larger datasets into smaller batches
+   - Monitor memory usage with very large collections
+
+## Running Benchmarks
+
+To run the benchmarks:
+
+```bash
+# Run all Ruby versions with and without YJIT
+./bin/run_benchmarks.sh --platform linux/arm64
+
+# Run specific version with YJIT
+./bin/run_benchmarks.sh -v 3.3.8 --yjit --platform linux/arm64
+
+# Run specific version without YJIT
+./bin/run_benchmarks.sh -v 3.3.8 --no-yjit --platform linux/arm64
+```
+
+Results will be saved in the `benchmark_results` directory. 

data/benchmark/end_to_end_benchmark.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark/ips"
+require_relative "../lib/type_balancer"
+
+# Print Ruby and platform info
+puts "Ruby version: #{RUBY_VERSION}"
+puts "RUBY_PLATFORM: #{RUBY_PLATFORM}"
+puts "YJIT enabled: #{RubyVM.const_defined?(:YJIT) && RubyVM::YJIT.enabled?}"
+
+# Test data generator
+def generate_test_data(size)
+  types = %w[video image article]
+  Array.new(size) do |i|
+    {
+      id: i,
+      type: types[i % types.size],
+      title: "Item #{i}"
+    }
+  end
+end
+
+# More granular test cases
+TEST_CASES = [
+  { name: "Tiny Dataset", size: 10 },
+  { name: "Small Dataset", size: 100 },
+  { name: "Medium Dataset", size: 1_000 },
+  { name: "Large Dataset", size: 10_000 }
+]
+
+def run_benchmark
+  puts "\nRunning benchmarks..."
+
+  TEST_CASES.each do |test_case|
+    puts "\nBenchmarking #{test_case[:name]} (#{test_case[:size]} items)"
+    collection = generate_test_data(test_case[:size])
+
+    # Single warmup run to ensure everything is loaded
+    TypeBalancer.balance(collection, type_field: :type)
+
+    # Run benchmark
+    Benchmark.ips do |bm|
+      # Adjust warmup/time based on dataset size
+      warmup_time = test_case[:size] <= 100 ? 1 : 2
+      bench_time = test_case[:size] <= 100 ? 2 : 3
+
+      bm.config(time: bench_time, warmup: warmup_time)
+      bm.report("Ruby Implementation") do
+        TypeBalancer.balance(collection, type_field: :type)
+      end
+    end
+
+    # Print distribution stats for verification
+    result = TypeBalancer.balance(collection, type_field: :type)
+    puts "\nDistribution Stats:"
+    %w[video image article].each do |type|
+      count = result.count { |i| i[:type] == type }
+      puts "#{type.capitalize}: #{count} (#{(count.to_f / test_case[:size] * 100).round(2)}%)"
+    end
+  end
+end
+
+run_benchmark