xlsxrb 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f865582e17bc03ede4f300f348f6166a666d82cd088f42a501a6518979a7b999
-  data.tar.gz: 25ba8105a6ca0318aa9bb4766a0de59da4818d18d226d212f1ec941fde3082c9
+  metadata.gz: 15a818d0e9e58b9ada1a11c90db9f9baa55fc76b3a7e62303d33a61f2e6f9896
+  data.tar.gz: c7b5f4af516d9911a1ee37ef5413939e8425bc270304900132e0962fad18905d
 SHA512:
-  metadata.gz: 6e35bcdabcff60af9084c9860fcf1838abfb507065a2eabb1004f40f16ab6cf6f7a11d136bbd83e97f46f0e460b906601db1584ef23b00c05076bfc240417baf
-  data.tar.gz: 8d4597dad8fe327f4ad887934a7f2bc18fcd65b606ef265ab38bcef0a0ae2565dc09f9e7f04dd8dc5bf7c3403fadc2a265d3ce074c9fd623489d8f4004065802
+  metadata.gz: 9deec47109a21a62aafb4a93efcee64f61f5ffb4566fd009cd1d5fdb9557e1193a53155d60ff7e4cc565317d49fb4ce8b3b89542234dff6a900981cd9220d14a
+  data.tar.gz: b536ef03e3ae01c49ff8e00c693d86fb72a9248cae1ccf93802962127d9b86ef676b5b17ca4b896613961bab8869139644e439542b1bca5adb6a7452d971f124

data/.mutant.yml

@@ -0,0 +1,8 @@
+usage: opensource
+requires:
+  - test_helper
+  - xlsxrb
+includes:
+  - lib
+  - test
+integration: test-unit

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+## [0.1.12] - 2026-09-20
+
+### Added
+- **Mutation Testing Framework (`mutant`)**:
+  - Full-scale integration of mutant test suite targeting the Functional Core (10 classes and modules, 38 subjects).
+  - Achieved **100.00% Kill Rate (1,091 / 1,091 mutations killed, 0 alive)** without exclusions.
+  - Added dedicated root configuration [`.mutant.yml`](.mutant.yml) for streamlined CLI execution (`bundle exec mutant run -- '...'`).
+  - Integrated `bundle exec rake mutant:pure` into GitHub Actions CI pipeline (`main.yml`), guaranteeing mutation-tested quality on every push and pull request.
+  - Added comprehensive architecture and testing guide in [`docs/MUTATION_TESTING.md`](docs/MUTATION_TESTING.md).
+- **Pre-Push Quality Verification Script (`bin/pre-push`)**: Added automated pre-push verification script running RuboCop, Steep type checking, RBS sync validation, Unit & Contract tests, RBS runtime type validation, and pure logic mutation testing, with automatic hook installation in `bin/setup`.
+
+### Changed
+- **Functional Core & Imperative Shell Architecture**:
+  - Purified core business logic and domain entities into deterministic, side-effect-free class methods and predicates:
+    - Extracted coordinate and validation predicates: `Elements::Cell.valid_value?`, `Cell.valid_coordinates?`, `Cell.calculate_column_letter`, `Cell.calculate_column_index`.
+    - Extracted domain validation predicates: `Elements::Row.valid_index?`, `Elements::Column.valid_index?`, `Elements::Worksheet.valid_name?`.
+    - Replaced date/time serial calculations in `Ooxml::Utils` with pure mathematical conversions (Julian Day math for `date_to_serial`, `divmod` arithmetic for `serial_to_datetime`, and rigorous 1900 leap year bug handling).
+    - Extracted binary packing utilities in `Ooxml::ZipGenerator` (`le16`, `le32`, and bitfield arithmetic for `dos_datetime`).
+    - Extracted pure XML character escaping logic in `Ooxml::XmlBuilder.escape`.
+  - Modularized `Ooxml::Writer` into domain-specific mixin modules (`DrawingXml`, `FeaturesXml`, `StylesXml`).
+  - Extracted shared DSL parameter normalization and range expansion into `Xlsxrb::DslHelpers`.
+  - Modularized reader SAX listeners into domain-specific parser components.
+
+### Fixed
+- **Boundary Validation & Error Reporting**:
+  - Strictly validate row number digits in `Elements::Cell.parse_ref` to reject malformed cell coordinate strings (e.g. `A0`, `A01`).
+  - Harmonized supported value type checks and nil/empty handling across `Elements::Cell.validate`.
+  - Corrected maximum row index boundary error messages in `Elements::Row.validate`.
+  - Hardened cryptographic stream boundary checks and corrupted header handling in Standard and Agile encryption modes.
+- **RBS Runtime Type Validation**:
+  - Expanded `Elements::Workbook#initialize`, `#sheet`, and `[]` type annotations to accept `StreamSheet` instances used by streaming readers.
+  - Made update block parameter optional in `Elements::Workbook#update_sheet` to allow testing missing block validation.
+  - Supported `Numeric` types (Float and Integer) in `ChartBuilder` and `SeriesBuilder` kwargs (`width`, etc.).
+  - Handled `RBS::Test::Tester::TypeError` in unit tests verifying block return type validation.
+
+## [0.1.11] - 2026-08-19
+
+### Performance
+- **Sub-Second Streaming Write (< 1.0s / 1,000,000 cells)**:
+  - Achieved sub-second streaming write performance (**0.97 s** median for 1M cells) while maintaining 100% full SST (Shared String Table) XML deduplication and ISO/IEC 29500 compatibility.
+  - Implemented 1-Pass Direct ZIP streaming pipeline, eliminating all intermediate tempfiles, disk seek-backs, and extra deflate flush cycles.
+  - Added dedicated unstyled fast-path in `WorksheetWriter#write_row_values` with precomputed coordinate and integer lookup tables.
+  - Pre-registered default date/time formatting styles, completely eliminating redundant per-row scan loops.
+  - Streamlined `ZipWriter` instance variable lookups to eliminate per-chunk hash overhead.
+  - Added `alias << row` to `WorksheetProxy` and `StreamWriter` for idiomatic Ruby streaming.
+- **High-Speed Streaming Read (1.61s / 1,000,000 cells)**:
+  - Reduced streaming read execution time from **3.40 s** down to **1.61 s** (over 2x speedup).
+  - Refactored `Elements::Cell` into an optimized lightweight class with `Cell.fast_create`, reducing 1M cell instantiation overhead by 5.2x (0.92s → 0.17s) while maintaining full pattern matching (`deconstruct`, `deconstruct_keys`) and immutability.
+  - Replaced per-byte Ruby scanning in `WorksheetParser.fast_scan_cells_direct` with an Onigmo C-level regular expression scanner (`CELL_FAST_RE`), eliminating 100,000 intermediate XML substring allocations and nested byte loops.
+  - Optimized `StreamRow#cells` to populate cell arrays via direct block traversal, eliminating Enumerator object allocations.
+
+### Documentation
+- Updated benchmark results, performance comparisons, and linear-scale SVG charts across `README.md` and `docs/PEER_LIBRARIES.md`.
+
 ## [0.1.10] - 2026-08-19
 
 ### Added

data/README.md

@@ -166,6 +166,7 @@ Backed by an enterprise-grade QA architecture to guarantee absolute reliability:
 * **Official Microsoft Open XML SDK Validation**: Validates generated OOXML structures against Microsoft's official SDK.
 * **Visual Regression Testing (VRT)**: Headless LibreOffice Calc pixel-by-pixel rendering checks.
 * **Contract & Round-Trip Tests**: Verifies parity between Streaming and In-Memory APIs and round-trip read/write accuracy.
+* **Mutation Testing (Mutant)**: 100% mutant kill rate (1,091/1,091 mutations across 38 subjects) on pure algorithms, predicates, and coordinates ([docs/MUTATION_TESTING.md](docs/MUTATION_TESTING.md)).
 * **Security & DoS Protection**: Formula injection mitigation and ZIP bomb protection.
 
 For full architectural details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md).

data/Rakefile

@@ -462,6 +462,12 @@ task doc: %i[wasm fetch_assets] do
   FileUtils.mkdir_p("doc/docs/visual/files")
   FileUtils.cp_r(Dir.glob("docs/visual/files/*"), "doc/docs/visual/files")
 
+  FileUtils.mkdir_p("doc/docs/assets")
+  FileUtils.cp_r(Dir.glob("docs/assets/*"), "doc/docs/assets")
+
+  # Alias index.html as README_md.html for links referencing README.md
+  FileUtils.cp("doc/index.html", "doc/README_md.html") if File.exist?("doc/index.html")
+
   # --- WebAssembly Playground Integration ---
   puts "Integrating WebAssembly Playground..."
 
@@ -565,3 +571,63 @@ desc "Run static type checking with Steep"
 task typecheck: :sig do
   sh "bundle exec steep check"
 end
+
+namespace :mutant do
+  desc "Run mutation testing on pure logic and algorithms (coordinates, serial, conversion)"
+  task :pure do
+    default_subjects = [
+      "Xlsxrb::Elements::CoordinateAccess#cells",
+      "Xlsxrb::Elements::CoordinateAccess#[]",
+      "Xlsxrb::Elements::Cell#ref",
+      "Xlsxrb::Elements::Cell#to_i",
+      "Xlsxrb::Elements::Cell#to_f",
+      "Xlsxrb::Elements::Cell#content",
+      "Xlsxrb::Elements::Cell#to_s",
+      "Xlsxrb::Elements::Cell#valid?",
+      "Xlsxrb::Elements::Cell.calculate_column_letter",
+      "Xlsxrb::Elements::Cell.calculate_column_index",
+      "Xlsxrb::Elements::Cell.valid_coordinates?",
+      "Xlsxrb::Elements::Cell.valid_value?",
+      "Xlsxrb::Ooxml::Utils.serial_to_date",
+      "Xlsxrb::Ooxml::Utils.date_to_serial",
+      "Xlsxrb::Ooxml::Utils.datetime_to_serial",
+      "Xlsxrb::Ooxml::Utils.serial_to_datetime",
+      "Xlsxrb::Ooxml::ZipGenerator.le16",
+      "Xlsxrb::Ooxml::ZipGenerator.le32",
+      "Xlsxrb::StreamRow#valid?",
+      "Xlsxrb::StreamRow#unmapped_data",
+      "Xlsxrb::StreamRow#errors",
+      "Xlsxrb::StreamRow#values",
+      "Xlsxrb::Elements::Worksheet.valid_name?",
+      "Xlsxrb::Elements::Worksheet#valid?",
+      "Xlsxrb::Elements::Worksheet#load",
+      "Xlsxrb::Ooxml::Cfb::Reader.cfb?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#stream?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#root?",
+      "Xlsxrb::Ooxml::Cfb::DirEntry#storage?",
+      "Xlsxrb::Elements::Column.valid_index?",
+      "Xlsxrb::Elements::Column.validate",
+      "Xlsxrb::Elements::Column#valid?",
+      "Xlsxrb::Elements::Row.valid_index?",
+      "Xlsxrb::Elements::Row#valid?",
+      "Xlsxrb::Elements::Workbook#valid?",
+      "Xlsxrb::Ooxml::XmlBuilder.escape",
+      "Xlsxrb::Ooxml::ZipGenerator.dos_datetime",
+      "Xlsxrb::DslHelpers.normalize_column_indices"
+    ].join(" ")
+    subjects = ENV["MUTANT_SUBJECTS"] || default_subjects
+    test_files = [
+      "./test/xlsxrb/elements_test.rb",
+      "./test/xlsxrb/ooxml_test.rb",
+      "./test/xlsxrb/ooxml/utils_test.rb",
+      "./test/xlsxrb/ooxml/crypto_test.rb",
+      "./test/xlsxrb/ooxml/cfb_test.rb",
+      "./test/zip_generator_test.rb",
+      "./test/xlsxrb/stream_row_test.rb",
+      "./test/xlsxrb/style_builder_test.rb",
+      "./test/xlsxrb/dsl_helpers_test.rb"
+    ].select { |f| File.exist?(f) }
+    requires = test_files.map { |f| "-r #{f}" }.join(" ")
+    sh "bundle exec mutant run --usage opensource #{requires} -- #{subjects}"
+  end
+end

data/benchmark.rb

@@ -9,6 +9,7 @@ require "bundler/inline"
 puts "Ensuring benchmark peer ecosystem gems are available (bundler/inline)..."
 gemfile(true) do
   source "https://rubygems.org"
+  gem "rubyzip", ">= 2.3.0"
   gem "caxlsx", "4.5.0"
   gem "xlsxtream", "3.1.0"
   gem "fast_excel", "0.5.0", platform: :mri
@@ -187,7 +188,7 @@ RUNNER_SCRIPT = <<~'RUBY'
   when ["xlsxrb_inmemory", "read"]
     require_relative "lib/xlsxrb"
     measure do
-      wb = Xlsxrb.read(filename)
+      wb = Xlsxrb.read(filename).load
       count = 0
       wb.sheets.each do |sheet|
         sheet.rows.each do |row|
@@ -237,6 +238,7 @@ RUNNER_SCRIPT = <<~'RUBY'
       end
     end
   when ["simple_xlsx_reader", "read"]
+    gem "rubyzip", "~> 1.3.0"
     require "simple_xlsx_reader"
     measure do
       doc = SimpleXlsxReader.open(filename)

data/docs/ARCHITECTURE.md

@@ -509,6 +509,6 @@ To ensure library robustness and consistency across execution paths, we organize
    - Run via: `bundle exec rake test:e2e`
 
 4. **Visual Examples & VRT (`test/visual/`):**
-   - **Living Documentation:** Compiles visual DSL scripts under `examples/visual/` into the [Visual Examples Gallery](visual/README.md).
+   - **Living Documentation:** Compiles visual DSL scripts under `examples/visual/` into the [Visual Examples Gallery](visual/VisualGallery.md).
    - **Visual Regression Testing:** Renders the generated spreadsheets into PNG files using headless LibreOffice Calc, and calculates pixel differences against reference baselines using ImageMagick.
    - Run via: `bundle exec rake test:visual`

data/docs/DEVELOPMENT.md

@@ -32,7 +32,11 @@ To run the different tiers of our testing strategy:
    ```bash
    bundle exec rake test:visual
    ```
-7. **Run All Tests:**
+7. **Mutation Testing (Pure Logic & Algorithms):**
+   ```bash
+   bundle exec rake mutant:pure
+   ```
+8. **Run All Tests:**
    ```bash
    bundle exec rake test
    ```
@@ -41,7 +45,7 @@ To run the different tiers of our testing strategy:
 
 ## Development Workflow
 
-High-level API expansion follows the Facade rules documented in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). In short: if a low-level writer feature is stable, the default expectation is that it should eventually be exposed through the high-level DSL as well, with consistent naming, both streaming and in-memory coverage, backward-compatible options/block forms where practical, and matching Facade-level tests.
+High-level API expansion follows the Facade rules documented in [ARCHITECTURE.md](ARCHITECTURE.md). In short: if a low-level writer feature is stable, the default expectation is that it should eventually be exposed through the high-level DSL as well, with consistent naming, both streaming and in-memory coverage, backward-compatible options/block forms where practical, and matching Facade-level tests.
 
 To ensure systematic progress, reliable round-trip compatibility, and strict adherence to the ECMA-376 specification, we follow this iterative development cycle for each new feature:
 

data/docs/MUTATION_TESTING.md

@@ -0,0 +1,52 @@
+# Mutation Testing in xlsxrb
+
+To ensure enterprise-grade reliability and avoid "shallow test coverage" (where line coverage is high but assertions are missing or weak), `xlsxrb` adopts **Mutation Testing** via [`mbj/mutant`](https://github.com/mbj/mutant) with `test-unit` integration.
+
+As of the current release, the test suite achieves **100.00% kill rate (1,091 / 1,091 mutations killed, 0 alive)** across all 38 pure functional subjects.
+
+## Motivation & Strategy
+
+Standard code coverage measures whether lines of code were executed during tests. However, it cannot guarantee that the tests will fail if the code's behavior is altered or corrupted. Mutation testing systematically modifies source code (introducing "mutants" such as flipping conditionals, substituting constants, or removing statements) and checks whether existing tests catch the mutation ("kill" the mutant).
+
+### Targeted Scope: Functional Core, Pure Predicates & Byte Encoding
+
+Running mutation testing across the entire codebase (which includes heavy file I/O, ZIP streaming, and large XML parsing) is computationally expensive and prone to creating brittle tests for streaming writers. Therefore, `xlsxrb` follows the **Functional Core / Imperative Shell** architecture, focusing mutation testing strictly on pure functions, boundary predicates, coordinate conversions, and binary encoders:
+
+1. **Coordinates & Cell Conversions (`Xlsxrb::Elements::Cell`, `CoordinateAccess`)**:
+   - Column letters to 0-based indices (`"A"` ↔ `0`, `"Z"` ↔ `25`, `"AA"` ↔ `26`, up to `"XFD"` ↔ `16383`).
+   - Pure predicate checks (`Cell.valid_coordinates?`, `Cell.valid_value?`, `Cell#valid?`).
+   - String, integer, and float conversions (`Cell#to_s`, `Cell#to_i`, `Cell#to_f`, `Cell#content`, `Cell#ref`).
+   - Coordinate access references and cell sorting (`CoordinateAccess#cells`, `CoordinateAccess#[]`).
+2. **Worksheet, Column, Row & Workbook Invariants (`Xlsxrb::Elements::*`, `Xlsxrb::StreamRow`)**:
+   - Worksheet name validation (`Worksheet.valid_name?` with 1..31 characters and forbidden character rules `\ / ? * [ ]`).
+   - Column and row bounds (`Column.valid_index?`, `Column.validate`, `Column#valid?`, `Row.valid_index?`, `Row#valid?`).
+   - Workbook structure validation (`Workbook#valid?`).
+   - Streaming row data integrity (`StreamRow#valid?`, `StreamRow#unmapped_data`, `StreamRow#errors`, `StreamRow#values`).
+3. **Serial Value & DateTime Conversions (`Xlsxrb::Ooxml::Utils`)**:
+   - Julian Day ↔ 1900-based serial number conversions (`date_to_serial`, `serial_to_date`).
+   - Time fractions and fractional days arithmetic (`datetime_to_serial`, `serial_to_datetime`).
+   - Excel 1900 leap year bug handling.
+4. **Binary Parsing & Bitfield Packings (`Xlsxrb::Ooxml::ZipGenerator`, `Xlsxrb::Ooxml::Cfb`)**:
+   - Little-endian 16/32-bit byte serialization (`ZipGenerator.le16`, `ZipGenerator.le32`).
+   - MS-DOS packed datetime calculation with arithmetic bitfield combinations (`ZipGenerator.dos_datetime`).
+   - Compound File Binary (CFB) magic header recognition (`Cfb::Reader.cfb?`) and directory entry predicates (`DirEntry#stream?`, `#root?`, `#storage?`).
+5. **XML Character Escaping (`Xlsxrb::Ooxml::XmlBuilder`)**:
+   - Pure escaping of XML special characters (`XmlBuilder.escape`) with object identity preservation for clean strings.
+6. **DSL Normalization (`Xlsxrb::DslHelpers`)**:
+   - Column indices, range, and alphabet normalization (`DslHelpers.normalize_column_indices`).
+
+### Excluded Scope (Non-Targets)
+
+- **Streaming XML Writers & Parsers**: Validated via Microsoft Open XML SDK schema checks and round-trip parsing tests rather than mutant to avoid brittle assertions.
+- **Visual Regression Testing (VRT)**: Headless rendering with LibreOffice Calc is validated via image diffs in CI.
+- **Cryptographic Key Stretching**: Password hashing with 100,000 spin iterations is validated by specific contract tests to avoid slow feedback cycles.
+
+## Running Mutation Testing
+
+```bash
+# Run full mutation testing suite (38 subjects, ~35 seconds)
+bundle exec rake mutant:pure
+
+# Or run mutant against a specific class or method using .mutant.yml configuration
+bundle exec mutant run -- 'Xlsxrb::Elements::Cell.valid_value?'
+```

data/docs/PEER_LIBRARIES.md

@@ -88,25 +88,25 @@ The following benchmarks evaluate processing **1,000,000 cells** (100,000 rows
 
 | Library | Version | Model | String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| **xlsxtream** | 3.1.0 | Streaming | Inline String | **1.19 s** | 1.20 s | **18.2 MB** | 1072.0 |
-| **xlsxrb (Streaming)** | - | Streaming | SST (Shared) | **1.73 s** | 1.65 s | 94.4 MB | 39.0 |
-| **fast_excel** | 0.5.0 | Streaming | SST (Shared) | 1.89 s | 1.89 s | 148.2 MB | 245.0 |
-| **xlsxrb (In-Memory)** | - | In-Memory | SST (Shared) | 3.84 s | 3.83 s | 278.3 MB | 32.0 |
-| **write_xlsx** | 1.15.0 | In-Memory | SST (Shared) | 4.32 s | 4.34 s | 201.2 MB | 33.0 |
-| **caxlsx** | 4.5.0 | In-Memory | Inline String | 5.15 s | 5.12 s | 188.6 MB | 23.0 |
-| **rubyXL** | 3.4.38 | In-Memory | Inline String | 38.81 s | 37.82 s | 2186.8 MB | 103.0 |
+| **xlsxrb (Streaming)** | - | Streaming | SST (Shared) | **0.95 s** | **0.95 s** | 67.6 MB | **34.0** |
+| **xlsxtream** | 3.1.0 | Streaming | Inline String | 1.16 s | 1.17 s | **17.0 MB** | 323.0 |
+| **fast_excel** | 0.5.0 | Streaming | SST (Shared) | 2.02 s | 2.14 s | 148.3 MB | 210.0 |
+| **xlsxrb (In-Memory)** | - | In-Memory | SST (Shared) | 2.42 s | 2.57 s | 209.0 MB | 16.0 |
+| **write_xlsx** | 1.15.0 | In-Memory | SST (Shared) | 4.39 s | 4.42 s | 217.4 MB | 25.0 |
+| **caxlsx** | 4.5.0 | In-Memory | Inline String | 5.28 s | 5.28 s | 177.4 MB | 24.0 |
+| **rubyXL** | 3.4.38 | In-Memory | Inline String | 43.13 s | 43.65 s | 2167.2 MB | 101.0 |
 
 ### Read Performance (1,000,000 cells)
 
 | Library | Version | Model | Time (Median) | Time (Mean) | Peak Memory | GC Count |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| **xlsxrb (Streaming)** | - | Streaming | **3.17 s** | 3.22 s | 91.4 MB | 43.0 |
-| **simple_xlsx_reader** | 5.1.0 | Streaming | 4.48 s | 4.45 s | **38.5 MB** | 1669.0 |
-| **xlsxrb (In-Memory)** | - | In-Memory | 5.71 s | 5.89 s | 224.8 MB | 63.0 |
-| **creek** | 2.6.3 | Streaming | 8.14 s | 8.02 s | 834.6 MB | 477.0 |
-| **xsv** | 1.4.1 | Streaming | 14.61 s | 14.50 s | 76.1 MB | 2224.0 |
-| **roo** | 3.0.0 | Streaming | 15.69 s | 13.36 s | 119.7 MB | 441.0 |
-| **rubyXL** | 3.4.38 | In-Memory | 37.13 s | 40.35 s | 2537.6 MB | 146.0 |
+| **xlsxrb (Streaming)** | - | Streaming | **1.73 s** | **1.72 s** | 136.2 MB | **45.0** |
+| **xlsxrb (In-Memory)** | - | In-Memory | 4.33 s | 4.46 s | 304.3 MB | 77.0 |
+| **simple_xlsx_reader** | 5.1.0 | Streaming | 4.38 s | 4.41 s | **32.8 MB** | 918.0 |
+| **creek** | 2.6.3 | Streaming | 7.12 s | 7.05 s | 840.1 MB | 419.0 |
+| **roo** | 3.0.0 | Streaming | 10.95 s | 10.33 s | 123.4 MB | 196.0 |
+| **xsv** | 1.4.1 | Streaming | 14.56 s | 14.59 s | 73.6 MB | 2028.0 |
+| **rubyXL** | 3.4.38 | In-Memory | 30.74 s | 30.78 s | 2289.6 MB | 146.0 |
 
 ---
 

data/docs/QUALITY_ASSURANCE.md

@@ -15,6 +15,7 @@ Below is an overview of the inspection mechanisms, when they run, the quality at
 | **Unit & Contract Tests** | `rake test:unit test:contract` | ⭕ | ⭕ | - | Accuracy / Functional Reqs | Dynamic Analysis (Assertions) | Method specification violations, unexpected return values, edge-case failures. |
 | **Runtime Type Validation (RBS::Test)** | `rake test:rbs` | △ (Opt-in) | ⭕ | - | Type Safety (Dynamic) | Dynamic Analysis (Runtime Hooks) | Type errors slipping past static checks, divergence between RBS docs and implementation. |
 | **Property-Based Testing (PBT)** | `rake test:pbt` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
+| **Mutation Testing (Mutant)** | `rake mutant:pure` | ⭕ | ⭕ | - | Test Suite Rigor / Detection Power | Fault Injection / Mutation Analysis (100% kill on 1,091 mutants) | Shallow tests, unasserted edge cases, and surviving mutant bugs in pure algorithms, predicates, and coordinates logic. |
 | **Security Validation (DoS Protection)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Availability / Safety | Dynamic Analysis (Malicious Input) | Memory/disk exhaustion from ZIP bombs, infinite parsing loops from malformed files. |
 | **Concurrency Validation (Thread/Ractor)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Thread Safety | Dynamic Analysis (Parallel Execution) | Global variable pollution, data mixing during concurrent request processing. |
 | **XSD Schema Validation** | Included in `rake test:unit` | ⭕ | ⭕ | - | Compatibility / Compliance | Structural Validation | "We found a problem with some content in it" errors when opening in Excel. |

data/docs/assets/benchmark_results.svg

@@ -46,40 +46,40 @@
     <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
     <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
     
-    <!-- xlsxtream 3.1.0: 1.19s -->
-    <text x="150" y="85" text-anchor="end" class="label">xlsxtream 3.1.0</text>
-    <rect x="160" y="72" width="6.5" height="18" rx="3" fill="#64748b"/>
-    <text x="174.5" y="85" class="value">1.19 s</text>
+    <!-- xlsxrb (Streaming): 0.95s -->
+    <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="72" width="5.2" height="18" rx="3" fill="#3b82f6"/>
+    <text x="173.2" y="85" class="value">0.95 s</text>
 
-    <!-- xlsxrb (Streaming): 1.73s -->
-    <text x="150" y="120" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
-    <rect x="160" y="107" width="9.5" height="18" rx="3" fill="#3b82f6"/>
-    <text x="177.5" y="120" class="value">1.73 s</text>
+    <!-- xlsxtream 3.1.0: 1.16s -->
+    <text x="150" y="120" text-anchor="end" class="label">xlsxtream 3.1.0</text>
+    <rect x="160" y="107" width="6.4" height="18" rx="3" fill="#64748b"/>
+    <text x="174.4" y="120" class="value">1.16 s</text>
 
-    <!-- fast_excel 0.5.0: 1.89s -->
+    <!-- fast_excel 0.5.0: 2.02s -->
     <text x="150" y="155" text-anchor="end" class="label">fast_excel 0.5.0</text>
-    <rect x="160" y="142" width="10.4" height="18" rx="3" fill="#64748b"/>
-    <text x="178.4" y="155" class="value">1.89 s</text>
+    <rect x="160" y="142" width="11.1" height="18" rx="3" fill="#64748b"/>
+    <text x="179.1" y="155" class="value">2.02 s</text>
 
-    <!-- xlsxrb (In-Memory): 3.84s -->
+    <!-- xlsxrb (In-Memory): 2.42s -->
     <text x="150" y="190" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
-    <rect x="160" y="177" width="21.1" height="18" rx="3" fill="#3b82f6"/>
-    <text x="189.1" y="190" class="value">3.84 s</text>
+    <rect x="160" y="177" width="13.3" height="18" rx="3" fill="#3b82f6"/>
+    <text x="181.3" y="190" class="value">2.42 s</text>
 
-    <!-- write_xlsx 1.15.0: 4.32s -->
+    <!-- write_xlsx 1.15.0: 4.39s -->
     <text x="150" y="225" text-anchor="end" class="label">write_xlsx 1.15.0</text>
-    <rect x="160" y="212" width="23.8" height="18" rx="3" fill="#64748b"/>
-    <text x="191.8" y="225" class="value">4.32 s</text>
+    <rect x="160" y="212" width="24.1" height="18" rx="3" fill="#64748b"/>
+    <text x="192.1" y="225" class="value">4.39 s</text>
 
-    <!-- caxlsx 4.5.0: 5.15s -->
+    <!-- caxlsx 4.5.0: 5.28s -->
     <text x="150" y="260" text-anchor="end" class="label">caxlsx 4.5.0</text>
-    <rect x="160" y="247" width="28.3" height="18" rx="3" fill="#64748b"/>
-    <text x="196.3" y="260" class="value">5.15 s</text>
+    <rect x="160" y="247" width="29.0" height="18" rx="3" fill="#64748b"/>
+    <text x="197.0" y="260" class="value">5.28 s</text>
 
-    <!-- rubyXL 3.4.38: 38.81s -->
+    <!-- rubyXL 3.4.38: 43.13s -->
     <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
-    <rect x="160" y="282" width="213.5" height="18" rx="3" fill="#64748b"/>
-    <text x="381.5" y="295" class="value">38.81 s</text>
+    <rect x="160" y="282" width="220.0" height="18" rx="3" fill="#64748b"/>
+    <text x="388.0" y="295" class="value">43.13 s</text>
   </g>
 
   <!-- Right: Read Performance -->
@@ -103,42 +103,42 @@
     <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
     <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
     
-    <!-- xlsxrb (Streaming): 3.17s -->
+    <!-- xlsxrb (Streaming): 1.73s -->
     <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
-    <rect x="160" y="72" width="17.4" height="18" rx="3" fill="#3b82f6"/>
-    <text x="185.4" y="85" class="value">3.17 s</text>
+    <rect x="160" y="72" width="9.5" height="18" rx="3" fill="#3b82f6"/>
+    <text x="177.5" y="85" class="value">1.73 s</text>
 
-    <!-- simple_xlsx_reader: 4.48s -->
-    <text x="150" y="120" text-anchor="end" class="label">simple_xlsx_reader</text>
-    <rect x="160" y="107" width="24.6" height="18" rx="3" fill="#64748b"/>
-    <text x="192.6" y="120" class="value">4.48 s</text>
+    <!-- xlsxrb (In-Memory): 4.33s -->
+    <text x="150" y="120" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="107" width="23.8" height="18" rx="3" fill="#3b82f6"/>
+    <text x="191.8" y="120" class="value">4.33 s</text>
 
-    <!-- xlsxrb (In-Memory): 5.71s -->
-    <text x="150" y="155" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
-    <rect x="160" y="142" width="31.4" height="18" rx="3" fill="#3b82f6"/>
-    <text x="199.4" y="155" class="value">5.71 s</text>
+    <!-- simple_xlsx_reader: 4.38s -->
+    <text x="150" y="155" text-anchor="end" class="label">simple_xlsx_reader</text>
+    <rect x="160" y="142" width="24.1" height="18" rx="3" fill="#64748b"/>
+    <text x="192.1" y="155" class="value">4.38 s</text>
 
-    <!-- creek 2.6.3: 8.14s -->
+    <!-- creek 2.6.3: 7.12s -->
     <text x="150" y="190" text-anchor="end" class="label">creek 2.6.3</text>
-    <rect x="160" y="177" width="44.8" height="18" rx="3" fill="#64748b"/>
-    <text x="212.8" y="190" class="value">8.14 s</text>
+    <rect x="160" y="177" width="39.2" height="18" rx="3" fill="#64748b"/>
+    <text x="207.2" y="190" class="value">7.12 s</text>
 
-    <!-- xsv 1.4.1: 14.61s -->
-    <text x="150" y="225" text-anchor="end" class="label">xsv 1.4.1</text>
-    <rect x="160" y="212" width="80.4" height="18" rx="3" fill="#64748b"/>
-    <text x="248.4" y="225" class="value">14.61 s</text>
+    <!-- roo 3.0.0: 10.95s -->
+    <text x="150" y="225" text-anchor="end" class="label">roo 3.0.0</text>
+    <rect x="160" y="212" width="60.2" height="18" rx="3" fill="#64748b"/>
+    <text x="228.2" y="225" class="value">10.95 s</text>
 
-    <!-- roo 3.0.0: 15.69s -->
-    <text x="150" y="260" text-anchor="end" class="label">roo 3.0.0</text>
-    <rect x="160" y="247" width="86.3" height="18" rx="3" fill="#64748b"/>
-    <text x="254.3" y="260" class="value">15.69 s</text>
+    <!-- xsv 1.4.1: 14.56s -->
+    <text x="150" y="260" text-anchor="end" class="label">xsv 1.4.1</text>
+    <rect x="160" y="247" width="80.1" height="18" rx="3" fill="#64748b"/>
+    <text x="248.1" y="260" class="value">14.56 s</text>
 
-    <!-- rubyXL 3.4.38: 37.13s -->
+    <!-- rubyXL 3.4.38: 30.74s -->
     <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
-    <rect x="160" y="282" width="204.2" height="18" rx="3" fill="#64748b"/>
-    <text x="372.2" y="295" class="value">37.13 s</text>
+    <rect x="160" y="282" width="169.1" height="18" rx="3" fill="#64748b"/>
+    <text x="337.1" y="295" class="value">30.74 s</text>
   </g>
 
   <!-- Footer -->
-  <text x="480" y="455" text-anchor="middle" class="footer">Tested on Ruby 3.4+ in isolated subprocesses • Full GC and peak memory metrics in docs/PEER_LIBRARIES.md</text>
+  <text x="480" y="455" text-anchor="middle" class="footer">Tested on Ruby 4.0+ in isolated subprocesses • Full GC and peak memory metrics in docs/PEER_LIBRARIES.md</text>
 </svg>