serialbench 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ad3e527e89762ad59203e00e1034b019a3b8a369e9251c52b6a3f389e9771e3
-  data.tar.gz: dd68a1741b3a45d9b0f945ac4e23f35b48589c00dca63849f1223657da7f66d4
+  metadata.gz: 55b58686ee445c84cbbf69588022d932a56c7014255567c19d3bc44c2ddbad53
+  data.tar.gz: 0353b87e4e5d5690a706e2ef3b2e3d96f85166092b098893c13b9024b56acf4e
 SHA512:
-  metadata.gz: 17462212111e78b23dadc54c7527dadbd57f9e5c90803876c56a455285e612ded431cb0c77428f0f194ab1831579e99cdc9030bf134971c2c4fed56ff8fc5292
-  data.tar.gz: 4f5e62c00d38f4790bf0cd1fe30da9ed0993bd175e5a995264c82dbf17ebf9311c232733d3b42519550a02775827ff1a055039caac3f912dc7604c6c7b461867
+  metadata.gz: fdf9e8086fa5e7960151717340df5f131679af2389bf4126801f9a2ab777fed04f3eba511d108e2a4fe2d3f9e47c723970a22911b20880a162d93fdf85f7ace5
+  data.tar.gz: 665f581b8491ce518a0602f76dfc7227ae51c14f343bbf650c6ee5e4b735b3d64676d4af3fd2b6e10d9eb16209ca9ec412763072183d1101cf6e63c40088a83d

data/.github/scripts/push-to-data.sh

@@ -23,7 +23,7 @@ fi
 
 DATE=$(date -u +%Y-%m-%d)
 TARGET_PATH="runs/${DATE}/${PLATFORM}-ruby-${RUBY_VERSION}.${FMT}.yaml"
-CONTENT=$(base64 < "$RESULTS_FILE")
+CONTENT=$(base64 < "$RESULTS_FILE" | tr -d '\r\n')
 
 echo "Pushing ${TARGET_PATH} to serialbench/data..."
 

data/.github/workflows/benchmark.yml

@@ -120,36 +120,6 @@ jobs:
           EOF
         shell: bash
 
-      # Each format is an independent checkpoint with its own upload.
-      # A failure in one format doesn't prevent the others from uploading.
-      - name: Benchmark xml
-        continue-on-error: true
-        shell: bash
-        env:
-          GITHUB_RUNNER_PLATFORM: ${{ matrix.platform }}
-        run: |
-          bundle exec serialbench environment execute \
-            config/environments/ci-ruby-${{ matrix.ruby-version }}.yml \
-            config/benchmarks/full-xml.yml \
-            "results/runs/ci-ruby-${{ matrix.ruby-version }}-${{ matrix.platform }}/xml"
-
-      - name: Upload xml
-        if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
-        with:
-          name: benchmark-results-${{ matrix.platform }}-ruby-${{ matrix.ruby-version }}-xml
-          path: results/runs/ci-ruby-${{ matrix.ruby-version }}-${{ matrix.platform }}/xml
-          retention-days: 30
-          if-no-files-found: warn
-
-      - name: Push xml to data repo
-        if: ${{ !cancelled() }}
-        continue-on-error: true
-        env:
-          DATA_REPO_TOKEN: ${{ secrets.DATA_REPO_TOKEN }}
-        run: .github/scripts/push-to-data.sh xml ${{ matrix.ruby-version }} ${{ matrix.platform }}
-        shell: bash
-
       - name: Benchmark json
         continue-on-error: true
         shell: bash
@@ -234,6 +204,37 @@ jobs:
         run: .github/scripts/push-to-data.sh toml ${{ matrix.ruby-version }} ${{ matrix.platform }}
         shell: bash
 
+      # Each format is an independent checkpoint with its own upload.
+      # A failure in one format doesn't prevent the others from uploading.
+      - name: Benchmark xml
+        continue-on-error: true
+        shell: bash
+        env:
+          GITHUB_RUNNER_PLATFORM: ${{ matrix.platform }}
+        run: |
+          bundle exec serialbench environment execute \
+            config/environments/ci-ruby-${{ matrix.ruby-version }}.yml \
+            config/benchmarks/full-xml.yml \
+            "results/runs/ci-ruby-${{ matrix.ruby-version }}-${{ matrix.platform }}/xml"
+
+      - name: Upload xml
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results-${{ matrix.platform }}-ruby-${{ matrix.ruby-version }}-xml
+          path: results/runs/ci-ruby-${{ matrix.ruby-version }}-${{ matrix.platform }}/xml
+          retention-days: 30
+          if-no-files-found: warn
+
+      - name: Push xml to data repo
+        if: ${{ !cancelled() }}
+        continue-on-error: true
+        env:
+          DATA_REPO_TOKEN: ${{ secrets.DATA_REPO_TOKEN }}
+        run: .github/scripts/push-to-data.sh xml ${{ matrix.ruby-version }} ${{ matrix.platform }}
+        shell: bash
+
+
   # Summary job
   summary:
     runs-on: ubuntu-latest

data/CONTEXT.md

@@ -0,0 +1,11 @@
+# Serialbench domain glossary
+
+- **Adapter** (a.k.a. serializer): one Ruby serialization library under measurement (nokogiri, leptris, oj, psych, toml-rb…). Registered per format in `Serializers::Serializers::REGISTER`. Its interface is the **capability set** (`capabilities` → `Set<Symbol>`); the `features` hash export derives from it.
+- **Format**: xml, json, yaml, toml. One adapter belongs to exactly one format; one format has several adapters.
+- **Operation**: one measured workload — `parsing`, `generation`, `xpath`, `streaming` (the `OPERATIONS` table in `BenchmarkRunner`), plus `memory` (profiled separately). Config `operations:` uses exactly these names; absent = run all; unknown name = error.
+- **Result Leg**: one platform × ruby × format benchmark execution (one process, one config file). Produces one `results.yaml`.
+- **Data Run**: one dated directory in the data repo (`runs/YYYY-MM-DD/`), holding one YAML file per environment × format. Append-only; the site's aggregator takes the latest run's data per environment.
+- **Environment**: where a leg executes — `local`, `docker`, or `asdf` (`kind` in the environment config). Dispatched through `Runners.for`.
+- **Environment key**: `{platform}-ruby-{version}` (e.g. `macos-26-ruby-3.4`) — the site's identity for a platform×ruby pair.
+- **Capability**: a symbol in an adapter's capability set (`:xpath`, `:sax`, `:stax`, `:generate`, `:namespaces`…). Benchmarks filter adapters by capability; the site renders them as the capability strip.
+- **Fixture**: the generated test document for a format × size (`small`/`medium`/`large`), built by `Serialbench::TestData`. `test_data/{size}.{format}` files override the generated one.

data/docs/adr/0001-three-repo-split.md

@@ -0,0 +1,9 @@
+# ADR-0001: Three-repo split with incremental per-format pushes
+
+Date: 2026-08-28
+
+## Context
+The monolith coupled benchmark code, result storage, and site rendering; every publish was a batch job whose failure lost everything.
+
+## Decision
+Three repos: `serialbench/serialbench` (gem), `serialbench/data` (append-only YAML runs), `serialbench/serialbench.github.io` (Astro site). Each Result Leg pushes its file to data via the Contents API immediately and triggers a site rebuild; legs are `continue-on-error` so one eviction never blocks the others.

data/docs/adr/0002-runners-stay.md

@@ -0,0 +1,9 @@
+# ADR-0002: Docker and ASDF runners stay
+
+Date: 2026-08-28
+
+## Context
+An architecture round deleted the docker/asdf runners as "unused by CI" (only LocalRunner executes in GitHub Actions).
+
+## Decision
+Restore and keep them. The owner's requirement: every platform remains benchmarkable through the gem, not just what current CI exercises. Round 4 then repaired the asdf dispatch so the runner is actually reachable (`Runners.for`). Do not re-suggest deleting runners.

data/docs/adr/0003-capability-set.md

@@ -0,0 +1,9 @@
+# ADR-0003: The capability set is the single adapter interface
+
+Date: 2026-08-29
+
+## Context
+Adapters declared capabilities through 49 individual `supports_X?` predicates, a parallel `features` hash, and (after a partial migration) a `capabilities` Set — three interfaces that could and did contradict (nokogiri's features denied streaming it has; rexml declared xpath without implementing `xpath_query`).
+
+## Decision
+One source of truth: `capabilities` returns a `Set<Symbol>`; adapters override with `super | Set.new(...)`; the per-format `features` export derives from it; benchmark selection filters via `supports?`. New capability = one symbol. Do not reintroduce per-capability predicate methods.

data/docs/adr/0004-explicit-workflow-steps.md

@@ -0,0 +1,9 @@
+# ADR-0004: Benchmark workflow keeps 12 explicit format steps
+
+Date: 2026-08-30
+
+## Context
+benchmark.yml repeats a benchmark/upload/push trio per format; a composite action could collapse 12 steps to 4.
+
+## Decision
+Decline. `continue-on-error` is a caller-side property a composite cannot carry; the independent-checkpoint semantics would need re-implementation; each explicit step is a grep-able checkpoint during incident triage; the pipeline had a fragile week and the duplication is the price of the isolation property. Revisit only if a fifth format arrives.

data/docs/adr/0005-site-loader-stays-flat.md

@@ -0,0 +1,9 @@
+# ADR-0005: Site loader stays a flat store
+
+Date: 2026-08-29 (reaffirmed 2026-08-30)
+
+## Context
+The site's `loadBenchmarks` returns a flat `BenchmarkStore` that components re-shape; a domain-query loader (leaderboard()/availability()/trend()) was proposed twice.
+
+## Decision
+Defer. After the redesign the data layer is small, single-purpose modules (parser/aggregator/trend/versions, 18 tests) and no consumer friction has appeared. Revisit when a second dashboard view forces its own query shape.

data/docs/adr/0006-operations-vocabulary.md

@@ -0,0 +1,9 @@
+# ADR-0006: One operations vocabulary
+
+Date: 2026-08-29
+
+## Context
+Benchmark configs declared `parse`/`generate`; the runner's OPERATIONS table used `parsing`/`generation`; `xpath` was in production configs but not the model's legal values; the config's `operations:` list was never read.
+
+## Decision
+The OPERATIONS keys plus `memory` are the only legal names, end to end (config values, model validation, runner dispatch). Absent key = run everything; unknown name = `ArgumentError` with guidance. lutaml-model caveat: `default:` on a collection merges into deserialized values, so the everything-default lives in the runner, not the model.

data/lib/serialbench/benchmark_runner.rb

@@ -135,6 +135,11 @@ module Serialbench
               results << result if result
             rescue StandardError => e
               puts "    #{format}/#{serializer.name}: ERROR - #{e.message}"
+            ensure
+              # Free the previous adapter's documents before the next one
+              # parses + profiles; without this, six adapters' trees coexist
+              # and windows runners OOM during the xml memory pass.
+              GC.start
             end
           end
         end

data/lib/serialbench/serializers.rb

@@ -75,7 +75,7 @@ module Serialbench
           name: serializer_singleton.name,
           format: serializer_singleton.format.to_s,
           version: serializer_singleton.version,
-          features: serializer_singleton.features
+          features: serializer_singleton.features.transform_keys(&:to_s)
         )
       end
 

data/lib/serialbench/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Serialbench
-  VERSION = '0.7.0'
+  VERSION = '0.8.1'
 end

data/lib/serialbench.rb

@@ -4,7 +4,6 @@ require_relative 'serialbench/version'
 require_relative 'serialbench/serializers'
 require_relative 'serialbench/benchmark_runner'
 require_relative 'serialbench/cli'
-require_relative 'serialbench/memory_profiler'
 require_relative 'serialbench/models'
 
 module Serialbench

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serialbench
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Ribose
@@ -264,6 +264,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- CONTEXT.md
 - Gemfile
 - README.adoc
 - Rakefile
@@ -289,6 +290,12 @@ files:
 - docs/WEBSITE_COMPLETION_PLAN.md
 - docs/WINDOWS_LIBXML_FIX.md
 - docs/WINDOWS_SETUP.md
+- docs/adr/0001-three-repo-split.md
+- docs/adr/0002-runners-stay.md
+- docs/adr/0003-capability-set.md
+- docs/adr/0004-explicit-workflow-steps.md
+- docs/adr/0005-site-loader-stays-flat.md
+- docs/adr/0006-operations-vocabulary.md
 - exe/serialbench
 - lib/serialbench.rb
 - lib/serialbench/benchmark_runner.rb
@@ -298,8 +305,6 @@ files:
 - lib/serialbench/cli/environment_cli.rb
 - lib/serialbench/cli/ruby_build_cli.rb
 - lib/serialbench/cli/validate_cli.rb
-- lib/serialbench/config_manager.rb
-- lib/serialbench/memory_profiler.rb
 - lib/serialbench/models.rb
 - lib/serialbench/models/benchmark_config.rb
 - lib/serialbench/models/benchmark_result.rb

data/lib/serialbench/config_manager.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-require 'ostruct'
-require_relative 'schema_validator'
-
-module Serialbench
-  # Manages configuration loading and validation for Serialbench
-  class ConfigManager
-    class ConfigurationError < StandardError; end
-
-    SCHEMA_PATH = File.join(__dir__, '../../docs/serialbench_config_schema.yaml')
-
-    # Load and validate configuration from file
-    def self.load_and_validate(config_path)
-      new.load_and_validate(config_path)
-    end
-
-    def initialize
-      @validator = SchemaValidator.new
-    end
-
-    # Load configuration file and validate against schema
-    def load_and_validate(config_path)
-      raise ConfigurationError, "Configuration file not found: #{config_path}" unless File.exist?(config_path)
-
-      begin
-        config_data = YAML.load_file(config_path)
-      rescue Psych::SyntaxError => e
-        raise ConfigurationError, "Invalid YAML syntax in #{config_path}: #{e.message}"
-      rescue StandardError => e
-        raise ConfigurationError, "Error reading configuration file #{config_path}: #{e.message}"
-      end
-
-      validate_config(config_data, config_path)
-      normalize_config(config_data)
-    end
-
-    private
-
-    # Validate configuration against schema
-    def validate_config(config_data, _config_path)
-      # For now, perform basic validation since we don't have a specific config schema validator
-      validate_basic_config(config_data)
-    end
-
-    # Load the configuration schema
-    def load_schema
-      raise ConfigurationError, "Configuration schema not found: #{SCHEMA_PATH}" unless File.exist?(SCHEMA_PATH)
-
-      begin
-        YAML.load_file(SCHEMA_PATH)
-      rescue StandardError => e
-        raise ConfigurationError, "Error loading configuration schema: #{e.message}"
-      end
-    end
-
-    # Normalize and convert configuration to structured object
-    def normalize_config(config_data)
-      config = OpenStruct.new(config_data)
-
-      # Apply defaults
-      config.output_dir ||= 'benchmark-results'
-      config.benchmark_config ||= 'config/full.yml'
-      config.auto_install = true if config.auto_install.nil?
-
-      # Validate runtime-specific requirements
-      case config.runtime
-      when 'docker'
-        validate_docker_config(config)
-      when 'asdf'
-        validate_asdf_config(config)
-      else
-        raise ConfigurationError, "Unknown runtime: #{config.runtime}"
-      end
-
-      config
-    end
-
-    # Validate Docker-specific configuration
-    def validate_docker_config(config)
-      raise ConfigurationError, "Docker runtime requires 'image_variants' to be specified" unless config.image_variants && !config.image_variants.empty?
-
-      invalid_variants = config.image_variants - %w[slim alpine]
-      return if invalid_variants.empty?
-
-      raise ConfigurationError, "Invalid image variants: #{invalid_variants.join(', ')}. Valid variants: slim, alpine"
-    end
-
-    # Validate ASDF-specific configuration
-    def validate_asdf_config(config)
-      # Check if ASDF is available
-      raise ConfigurationError, 'ASDF is not installed or not in PATH. Please install ASDF to use asdf runtime.' unless command_available?('asdf')
-
-      # Validate Ruby version format for ASDF (should include patch version)
-      config.ruby_versions.each do |version|
-        raise ConfigurationError, "ASDF runtime requires full version numbers (e.g., '3.2.8'), got: #{version}" unless version.match?(/^\d+\.\d+\.\d+$/)
-      end
-    end
-
-    # Basic configuration validation
-    def validate_basic_config(config_data)
-      # Check required fields
-      required_fields = %w[runtime ruby_versions output_dir benchmark_config]
-      required_fields.each do |field|
-        raise ConfigurationError, "Missing required field: #{field}" unless config_data.key?(field)
-      end
-
-      # Validate runtime
-      valid_runtimes = %w[docker asdf]
-      unless valid_runtimes.include?(config_data['runtime'])
-        raise ConfigurationError,
-              "Invalid runtime: #{config_data['runtime']}. Valid runtimes: #{valid_runtimes.join(', ')}"
-      end
-
-      # Validate ruby_versions is an array
-      raise ConfigurationError, 'ruby_versions must be an array' unless config_data['ruby_versions'].is_a?(Array)
-
-      return unless config_data['ruby_versions'].empty?
-
-      raise ConfigurationError, 'ruby_versions cannot be empty'
-    end
-
-    # Check if a command is available in PATH
-    def command_available?(command)
-      system("which #{command} > /dev/null 2>&1")
-    end
-  end
-end

data/lib/serialbench/memory_profiler.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Serialbench
-  class MemoryProfiler
-    def self.profile(&block)
-      return yield unless defined?(::MemoryProfiler)
-
-      ::MemoryProfiler.report(&block)
-    end
-
-    def self.available?
-      require 'memory_profiler'
-      defined?(::MemoryProfiler) ? true : false
-    rescue LoadError
-      false
-    end
-
-    def self.format_report(report)
-      return 'Memory profiling not available' unless report
-
-      {
-        total_allocated: report.total_allocated,
-        total_retained: report.total_retained,
-        allocated_memory: report.total_allocated_memsize,
-        retained_memory: report.total_retained_memsize,
-        allocated_objects_by_gem: report.allocated_memory_by_gem,
-        retained_objects_by_gem: report.retained_memory_by_gem
-      }
-    end
-  end
-end