xlsxrb 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf81256a8c23f02b4ef5a1f2efb91122850960da349cc1c00bce37d4055486ac
-  data.tar.gz: c0fdb2a48e67beb7a59730fe947ca819c5ed72196c858b02a430cb5f85e953c5
+  metadata.gz: a6733f82b936fb790e6192de72890ecedd016f21dd4a5e43ee0f5123a2d35f5e
+  data.tar.gz: 3dd84ebc97a5c10a2777f6bd7557b06660e690f0723f8af6664a244a143adaa6
 SHA512:
-  metadata.gz: a4e3b7098c50d3d9e5958333f49ad2b8c22399f383067c01b0481fb82e9d1eaa50481de15afe8b2b883d6f0ee1697144ae55d028771eeca159cc38f46626043f
-  data.tar.gz: 25c3979864c017334256986e5697c793f40b22b3cdc7419d18e3ef090925f0297909ca8fafc9188cf37769344e656fa7e900cf8da8f3a310599e1cd9ab61ed8b
+  metadata.gz: 6ca0217ecd3a83a922a1098740d584c6e78fd0695f46acaa661286497a0e0de1c9214990eb7fef622a10ad4a1641f9aae73079ab61b0787570a22e434b446d0e
+  data.tar.gz: 7603890bc9f20d9143656ea83f0fd75410b4636cc66bbd152e79965b4b2bc07013de05f1489560fc896b9f5e1890c9fb6b421ec8dbc49b66ca9dec7912ab617c

data/CHANGELOG.md

@@ -1,15 +1,67 @@
+## [Unreleased]
+
+## [0.1.13] - 2026-09-25
+
+### Added
+- Non-destructive template modification: Support modifying existing XLSX templates while preserving unmapped parts, media, charts, drawings, and VBA macros via `Xlsxrb.modify`.
+- StreamSheet structural metadata accessors: Expose `merged_cells`, `auto_filter`, `data_validations`, and `conditional_formats` on `StreamSheet`.
+- Pre-Push Smart Change Detection: Optimized `bin/pre-push --all` to automatically skip runtime RBS validation and pure logic mutation testing when unrelated files are modified, adding `--last` and `--force` controls.
+
+### Changed
+- True O(1) memory streaming read via chunked entry inflation in `ZipReader` and `WorksheetParser`, preventing unbounded memory retention on large worksheets.
+- Extracted pure DSL normalizers (`Xlsxrb::DslHelpers`) and fast XML unescape utilities (`Ooxml::XmlBuilder.unescape`).
+- Constrained `rexml` runtime dependency to `~> 3.0` and excluded documentation, build assets, and developer configurations from the gem package.
+
+### Removed
+- OpenTelemetry runtime dependency and tracer spans.
+
+## [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 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 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.
+- 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).
+- 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.
@@ -20,56 +72,56 @@
 ## [0.1.10] - 2026-08-19
 
 ### Added
-- **Peer Libraries Ecosystem Guide ([docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md))**: Introduced a respectful overview of the Ruby XLSX ecosystem featuring official self-descriptions, architectural tradeoffs (SST vs. Inline Strings, Streaming vs. In-Memory), and reproducible benchmarks across 9 popular Ruby XLSX gems.
-- **Visual Assets & Screen Previews**:
+- Peer Libraries Ecosystem Guide ([docs/PEER_LIBRARIES.md](docs/PEER_LIBRARIES.md)): Introduced a respectful overview of the Ruby XLSX ecosystem featuring official self-descriptions, architectural tradeoffs (SST vs. Inline Strings, Streaming vs. In-Memory), and reproducible benchmarks across 9 popular Ruby XLSX gems.
+- Visual Assets & Screen Previews:
   - Embedded interactive WebAssembly Playground live demo preview in `README.md`.
   - Added real-world Ruby LSP autocompletion and RBS type hint preview in `README.md`.
   - Created accurate, neutral linear-scale SVG benchmark performance chart.
-- **Enterprise-Grade Test Suite Expansion**:
-  - **ECMA-376 XSD Schema Validation**: Comprehensive XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
-  - **Contract Testing Suite**: Comprehensive parity verification between Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
-  - **Property-Based Testing (PBT)**: Expanded automated random generation tests for Row/Column invariants, styles, and edge cases.
-  - **Visual Regression Testing (VRT)**: Added new visual baselines for table styles, drawing shapes, and pivot tables.
-  - **E2E Interoperability Suite**: Added tests for namespace-prefixed XML streaming, conditional formatting, and table structures.
+- Multi-Layered Test Suite Expansion:
+  - ECMA-376 XSD Schema Validation: XML schema validation suite ensuring strict element ordering and ISO/IEC 29500 compliance.
+  - Contract Testing Suite: Parity verification between Streaming (`Xlsxrb.write`) and In-Memory (`Xlsxrb.build`) APIs.
+  - Property-Based Testing (PBT): Expanded automated random generation tests for Row/Column invariants, styles, and edge cases.
+  - Visual Regression Testing (VRT): Added new visual baselines for table styles, drawing shapes, and pivot tables.
+  - E2E Interoperability Suite: Added tests for namespace-prefixed XML streaming, conditional formatting, and table structures.
 
 ### Fixed
-- **WebAssembly (ruby.wasm) Compatibility**: Bundled `pp` and `prettyprint` standard libraries in `ruby.wasm` package to resolve REXML LoadError during browser-based evaluation.
+- WebAssembly (ruby.wasm) Compatibility: Bundled `pp` and `prettyprint` standard libraries in `ruby.wasm` package to resolve REXML LoadError during browser-based evaluation.
 
 ### Changed
-- **Streamlined README**: Refactored README from 363 to 175 lines, focusing on core motivation, clean 4-column feature matrix, concise usage examples, and direct links to specialized documentation.
+- Streamlined README: Refactored README from 363 to 175 lines, focusing on core motivation, clean 4-column feature matrix, concise usage examples, and direct links to specialized documentation.
 
 ## [0.1.9] - 2026-08-18
 
 ### Added
-- **Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB])**: Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
-  - **Standard Encryption**: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
-  - **Agile Encryption**: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
-  - **Compound File Binary (CFB) Engine**: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
-  - **Transparent Public API Integration**: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
-  - **Security & Threat Model Hardening**:
+- Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB]): Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
+  - Standard Encryption: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
+  - Agile Encryption: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
+  - Compound File Binary (CFB) Engine: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
+  - Transparent Public API Integration: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
+  - Security & Threat Model Hardening:
     - Constant-time hash verification via `OpenSSL.secure_compare` to prevent timing attacks (CWE-208).
     - CSPRNG-backed salt, IV, and session key generation via `SecureRandom` (CWE-330).
-    - Robust DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
+    - DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
     - Strict exception hierarchy (`EncryptedFileError`, `InvalidPasswordError`, `DecryptionError`).
-  - **Cross-Platform & Interoperability Validation**: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
-  - **WebAssembly (ruby.wasm) Support**: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
+  - Cross-Platform & Interoperability Validation: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
+  - WebAssembly (ruby.wasm) Support: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
 
 ## [0.1.8] - 2026-08-18
 
 ### Changed
-- **Unified Symmetric Entrypoints**: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
-- **Streaming-First Defaults**: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
-- **Explicit In-Memory Materialization (`#load`)**: Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
-- **`CoordinateAccess` Module**: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
+- Unified Symmetric Entrypoints: Consolidated reading into `Xlsxrb.read` (supporting file path, IO, and raw binary string) and writing into `Xlsxrb.write` (supporting streaming blocks or in-memory Workbooks). Removed legacy `open`, `foreach`, and `generate` methods.
+- Streaming-First Defaults: `Xlsxrb.read` yields and returns lightweight `StreamSheet` instances with $O(1)$ constant-memory consumption by default.
+- Explicit In-Memory Materialization (`#load`): Stripped accidental random-access memory traps from `StreamSheet`; introduced explicit `StreamSheet#load` / `Workbook#load` (inspired by ActiveRecord Relations) to transition from lazy streaming to in-memory `Elements::Worksheet` / `Elements::Workbook`.
+- `CoordinateAccess` Module: Extracted coordinate lookup methods (`[]`, `cell_value`, `row_at`, `first_row`, `last_row`, `cells`, `cells_hash`) into a dedicated `Xlsxrb::Elements::CoordinateAccess` mixin module included in `Elements::Worksheet`.
 
 ### Added
-- **Default Cell Streaming (`Xlsxrb::StreamRow`)**: Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
+- Default Cell Streaming (`Xlsxrb::StreamRow`): Enabled streaming along both row and cell dimensions via `row.each_cell` and `sheet.each_cell`, parsing cells on-demand to handle sheets with thousands of columns in $O(1)$ constant memory.
 
 ## [0.1.7] - 2026-08-16
 
 ### Added
 - Bundled native Ruby LSP Add-on (`RubyLsp::Xlsxrb::Addon`) for zero-configuration, context-aware method autocompletion and rich markdown documentation in VS Code and LSP-enabled editors for block arguments (`wb.`, `s.`, `sheet.`, `stream_writer.`, `stream_sheet.`).
-- Comprehensive YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
+- YARD documentation (`@param`, `@return`, `@example`) across all public APIs, builders, proxies, and elements.
 
 ### Developer Experience
 - Enhanced `rbs-inline` type signatures across all facade methods and builder objects with automated RBS generation.
@@ -84,10 +136,10 @@
 - Hash-compatible symbol indexing in `Elements::Row#[]` (`:cells`, `:index`, `:height`, `:attrs`) and `Elements::Cell#[]` (`:value`, `:ref`, `:style_index`).
 
 ### Performance
-- **Streaming Write**: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
-- **In-Memory Write**: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
-- **Streaming Read**: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
-- **In-Memory Read**: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
+- Streaming Write: Replaced per-cell micro IO calls with row-level string buffering and fast-path serialization for unstyled cells (1,000,000 cells in 1.62s with standard SST).
+- In-Memory Write: Optimized DOM serialization (`WorksheetWriter#write_row`) with row-level buffer aggregation, boosting 1,000,000 cells write from 22.33s to 4.06s (5.5x faster) and reducing GC count by 83%.
+- Streaming Read: Implemented zero-allocation byte scanning for cell attributes (`r="..."`, `t="..."`, `s="..."`) and direct integer conversion for SST indexes, cutting GC count by ~70% (129 -> 40) and boosting 1,000,000 cells read to 3.38s.
+- In-Memory Read: Reduced peak memory footprint by 57% (582 MB -> 250 MB).
 
 ### Documentation
 - Overhauled `benchmark.rb` with `bundler/inline` for deterministic, zero-setup benchmark reproduction pinning peer gem versions.
@@ -107,7 +159,7 @@
 - Full `RBS::Test` runtime type validation enabled for the entire test suite.
 - Extensive Excel limit warnings documented via YARD tags.
 - Formal SemVer API contract with `@api public` tags for user-facing methods.
-- Comprehensive mutation testing (Mutant) and test coverage (SimpleCov) integrations.
+- Mutation testing (Mutant) and test coverage (SimpleCov) integrations.
 
 ### Changed
 - Replaced `method_missing` with statically defined, fully typed methods in `WorksheetProxy`, `ChartBuilder`, and `SeriesBuilder`.

data/README.md

@@ -4,7 +4,7 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 ## Motivation
 
-The Ruby ecosystem already has great XLSX libraries, each designed for specific tradeoffs:
+The Ruby ecosystem has several XLSX libraries designed for specific tradeoffs:
 
 | Library | Read | Write | Streaming | In-Memory |
 | :--- | :---: | :---: | :---: | :---: |
@@ -17,23 +17,27 @@ The Ruby ecosystem already has great XLSX libraries, each designed for specific
 | [xlsxtream](https://rubygems.org/gems/xlsxtream) | ❌ | ✅ | ✅ | ❌ |
 | [fast_excel](https://rubygems.org/gems/fast_excel) | ❌ | ✅ | ✅ | ❌ |
 | [rubyXL](https://rubygems.org/gems/rubyXL) | ✅ | ✅ | ❌ | ✅ |
-| **[xlsxrb](https://github.com/niku/xlsxrb)** | **✅** | **✅** | **✅** | **✅** |
+| [xlsxrb](https://github.com/niku/xlsxrb) | ✅ | ✅ | ✅ | ✅ |
 
-Each of these libraries makes deliberate architectural choices:
-* **Streaming Model**: Writes or reads rows sequentially on-the-fly to maintain a constant $O(1)$, low-memory footprint regardless of dataset size.
-* **In-Memory Model**: Builds a complete document object model, offering flexible random access, cell updates, and document templates at the cost of memory usage on large spreadsheets.
+These libraries make different architectural tradeoffs:
+* Streaming Model: Writes or reads rows sequentially on-the-fly to maintain a constant $O(1)$, low-memory footprint regardless of dataset size.
+* In-Memory Model: Builds a complete document object model, offering flexible random access, cell updates, and document templates at the cost of memory usage on large spreadsheets.
 
-Traditionally, maintaining an all-in-one gem that offers both reading and writing across both streaming and in-memory models, alongside rich OOXML features, high performance, and strict compatibility, presents an inherent open-source challenge: the cumulative maintenance overhead often exceeds the capacity of individual human maintainers.
+Maintaining a gem that supports both reading and writing across streaming and in-memory models, alongside OOXML features and specification compatibility, involves significant ongoing maintenance overhead.
 
-`xlsxrb` is built on a modern premise: **Advanced Agentic AI (AI Coders) can sustainably handle this maintenance demand.** By utilizing AI agents to automate end-to-end testing, visual regression testing, specification compliance verification, and documentation updates, `xlsxrb` delivers a fast, specification-compliant, and fully-featured XLSX library built for long-term sustainability.
+`xlsxrb` addresses this through automated workflows: AI coding agents handle routine maintenance tasks such as end-to-end testing, visual regression testing, schema compliance checks, and documentation synchronization, enabling sustainable maintenance of both streaming and in-memory architectures.
 
 ### Design Principles
 
-- **Minimal Dependencies**: Zero core logic dependencies. Built purely on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.). The only runtime dependency is `opentelemetry-api` (zero-overhead no-op when unconfigured).
-- **Streaming Support**: True $O(1)$ constant memory streaming for both reading and writing massive spreadsheets.
-- **Strict OpenXML Interoperability**: Fully compliant with ISO/IEC 29500 (ECMA-376) and validated continuously against the official Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
-- **AI-Assisted Sustainability**: Leveraging AI coding agents for automated quality assurance, E2E validation, and continuous feature expansion.
-- **Modern Ruby**: Built for Ruby 4.0 or higher.
+- Zero Runtime Dependencies: Built strictly on the Ruby standard library and bundled gems (`zlib`, `rexml`, etc.) with zero third-party runtime dependencies.
+- Streaming Support: Constant $O(1)$ memory streaming for reading and writing spreadsheets.
+- OpenXML Interoperability: Compliant with ISO/IEC 29500 (ECMA-376) and validated against the Microsoft [Open XML SDK](https://github.com/dotnet/Open-XML-SDK).
+- AI-Assisted Maintenance: Uses AI coding agents for automated quality assurance and verification workflows. Operational guidelines are defined in [AGENTS.md](AGENTS.md).
+- Ruby 4.0+: Requires Ruby 4.0 or higher.
+
+### Autonomous Quality Assurance
+
+To maintain its multi-layered QA suite (Steep static typing, 100% mutation kill rate across 38 subjects, ECMA-376 XSD validation, and $O(1)$ streaming memory) without high manual maintenance overhead, xlsxrb defines remediation workflows for AI coding agents ([AGENTS.md](AGENTS.md), [docs/QA_AGENTS.md](docs/QA_AGENTS.md)).
 
 ## Installation
 
@@ -134,7 +138,7 @@ end
 
 ### IDE Autocompletion & Ruby LSP Support
 
-Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-configuration method autocompletion and hover documentation in VS Code and other editors:
+Includes a native Ruby LSP Add-on and full RBS signatures for zero-configuration method autocompletion and hover documentation in VS Code and other editors:
 
 <p align="center">
   <img src="docs/assets/lsp_autocompletion.png" width="100%" alt="Ruby LSP Autocompletion & Type Signature Hints in VS Code"/>
@@ -142,9 +146,9 @@ Includes a native **Ruby LSP Add-on** and full **RBS signatures** for zero-confi
 
 ## Feature Support & ECMA-376 Compliance
 
-`xlsxrb` supports nearly all major business spreadsheet features:
-* **Layout & Structure**: Formulas, Hyperlinks, Merge Cells, Freeze/Split Panes, Page Setup, Auto Filters, Data Validations, Sheet/Workbook Protection.
-* **Styling & Media**: Rich Text, Cell Styles & Fills, Conditional Formatting (color scales, data bars), Embedded Images, Charts (Line, Bar, Pie, Radar, Scatter).
+`xlsxrb` supports standard spreadsheet features:
+* Layout & Structure: Formulas, Hyperlinks, Merge Cells, Freeze/Split Panes, Page Setup, Auto Filters, Data Validations, Sheet/Workbook Protection.
+* Styling & Media: Rich Text, Cell Styles & Fills, Conditional Formatting (color scales, data bars), Embedded Images, Charts (Line, Bar, Pie, Radar, Scatter).
 
 For full details, see [docs/SPEC_SOURCES.md](docs/SPEC_SOURCES.md).
 
@@ -162,11 +166,12 @@ To reproduce locally: `ruby benchmark.rb 100000 10`
 
 ## Quality Assurance & Testing
 
-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.
-* **Security & DoS Protection**: Formula injection mitigation and ZIP bomb protection.
+Verified by a multi-layered QA architecture:
+* 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/lib/xlsxrb/chart_builder.rb

@@ -80,7 +80,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for legend styling/layout.
     # @return [Object] The configured legend property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def legend(*args, **kwargs)
       @options[:legend] = kwargs.empty? ? args.first : kwargs
     end
@@ -91,7 +91,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for plot area configuration.
     # @return [Object] The configured plot_area property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def plot_area(*args, **kwargs)
       @options[:plot_area] = kwargs.empty? ? args.first : kwargs
     end
@@ -102,7 +102,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured chart_space property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def chart_space(*args, **kwargs)
       @options[:chart_space] = kwargs.empty? ? args.first : kwargs
     end
@@ -113,7 +113,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured style property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String | Integer) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String | Integer)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String | Integer) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String | Integer)
     def style(*args, **kwargs)
       @options[:style] = kwargs.empty? ? args.first : kwargs
     end
@@ -124,7 +124,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured data_labels property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def data_labels(*args, **kwargs)
       @options[:data_labels] = kwargs.empty? ? args.first : kwargs
     end
@@ -135,7 +135,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def plot_visible_only(*args, **kwargs)
       @options[:plot_visible_only] = kwargs.empty? ? args.first : kwargs
     end
@@ -146,7 +146,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [String]
     # @api public
-    #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+    #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
     def display_blanks_as(*args, **kwargs)
       @options[:display_blanks_as] = kwargs.empty? ? args.first : kwargs
     end
@@ -157,7 +157,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def view3d(*args, **kwargs)
       @options[:view3d] = kwargs.empty? ? args.first : kwargs
     end
@@ -168,7 +168,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def category_axis(*args, **kwargs)
       @options[:category_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -179,7 +179,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def value_axis(*args, **kwargs)
       @options[:value_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -190,7 +190,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def show_legend_key(*args, **kwargs)
       @options[:show_legend_key] = kwargs.empty? ? args.first : kwargs
     end
@@ -258,7 +258,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def fill(*args, **kwargs)
         @options[:fill] = kwargs.empty? ? args.first : kwargs
       end
@@ -269,7 +269,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def line(*args, **kwargs)
         @options[:line] = kwargs.empty? ? args.first : kwargs
       end
@@ -280,7 +280,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def trendline(*args, **kwargs)
         @options[:trendline] = kwargs.empty? ? args.first : kwargs
       end
@@ -291,7 +291,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def data_labels(*args, **kwargs)
         @options[:data_labels] = kwargs.empty? ? args.first : kwargs
       end
@@ -302,7 +302,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Boolean, String]
       # @api public
-      #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+      #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
       def smooth(*args, **kwargs)
         @options[:smooth] = kwargs.empty? ? args.first : kwargs
       end
@@ -313,7 +313,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def shape(*args, **kwargs)
         @options[:shape] = kwargs.empty? ? args.first : kwargs
       end
@@ -324,7 +324,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def type(*args, **kwargs)
         @options[:type] = kwargs.empty? ? args.first : kwargs
       end

data/lib/xlsxrb/dsl_helpers.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "elements/cell"
+require_relative "ooxml/utils"
+
+module Xlsxrb
+  # Internal helper module for normalizing and validating DSL arguments
+  # shared between {WorksheetBuilder} (in-memory) and {StreamWriter} (streaming).
+  #
+  # @api private
+  module DslHelpers
+    # Normalizes merge cell range string or coordinate components into a canonical range reference (e.g. "A1:C3").
+    #
+    # @param range [String, Hash, nil]
+    # @param row [Integer, nil]
+    # @param col_start [Integer, String, nil]
+    # @param col_end [Integer, String, nil]
+    # @param row_start [Integer, nil]
+    # @param row_end [Integer, nil]
+    # @param strict_excel_mode [Boolean]
+    # @return [String]
+    #: (untyped range, ?row: Integer?, ?col_start: (Integer | String)?, ?col_end: (Integer | String)?, ?row_start: Integer?, ?row_end: Integer?, ?strict_excel_mode: bool) -> String
+    def self.normalize_merge_range(range = nil, row: nil, col_start: nil, col_end: nil, row_start: nil, row_end: nil, strict_excel_mode: true)
+      if range.is_a?(Hash)
+        row = range[:row]
+        row_start = range[:row_start]
+        row_end = range[:row_end]
+        col_start = range[:col_start]
+        col_end = range[:col_end]
+        range = nil
+      end
+
+      if range
+        raise ArgumentError, "Invalid merge range format: '#{range}'. Expected format like 'A1:B2'." if strict_excel_mode && !range.match?(/\A[A-Za-z]{1,3}\d+(:[A-Za-z]{1,3}\d+)?\z/)
+
+        range
+      else
+        r_start = row || row_start || 0
+        r_end = row || row_end || 0
+        c_start = Elements::Cell.column_index(col_start || 0)
+        c_end = Elements::Cell.column_index(col_end || 0)
+        start_ref = "#{Elements::Cell.column_letter(c_start)}#{r_start + 1}"
+        end_ref = "#{Elements::Cell.column_letter(c_end)}#{r_end + 1}"
+        "#{start_ref}:#{end_ref}"
+      end
+    end
+
+    # Normalizes sheet protection options and hashes plain-text password if supplied.
+    #
+    # @param opts [Hash]
+    # @return [Hash]
+    #: (Hash[Symbol, untyped] opts) -> Hash[Symbol, untyped]
+    def self.normalize_protection_options(opts)
+      normalized = opts.dup
+      plain_password = normalized[:password]
+      needs_hash = plain_password.is_a?(String) && !plain_password.empty? &&
+                   normalized[:algorithm_name].nil? && normalized[:hash_value].nil? &&
+                   normalized[:salt_value].nil? && normalized[:spin_count].nil? &&
+                   !plain_password.match?(/\A[0-9A-Fa-f]{4}\z/)
+      if needs_hash
+        normalized.delete(:password)
+        normalized.merge!(Ooxml::Utils.hash_password(plain_password))
+      end
+      normalized
+    end
+
+    # Normalizes column index or letter or Range to an array of 0-based column integers.
+    #
+    # @param index [Integer, String, Symbol, Range, Array]
+    # @return [Array<Integer>]
+    #: (untyped index) -> Array[Integer]
+    def self.normalize_column_indices(index)
+      case index
+      when Range, Array
+        index.map { |i| Elements::Cell.column_index(i) }
+      else
+        [Elements::Cell.column_index(index)]
+      end
+    end
+
+    # Normalizes page margins into a compact hash.
+    #
+    # @param left [Float, nil]
+    # @param right [Float, nil]
+    # @param top [Float, nil]
+    # @param bottom [Float, nil]
+    # @param header [Float, nil]
+    # @param footer [Float, nil]
+    # @return [Hash{Symbol => Float}]
+    #: (?left: Float?, ?right: Float?, ?top: Float?, ?bottom: Float?, ?header: Float?, ?footer: Float?) -> Hash[Symbol, Float]
+    def self.normalize_page_margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
+      { left: left, right: right, top: top, bottom: bottom, header: header, footer: footer }.compact
+    end
+
+    # Normalizes table options hash.
+    #
+    # @param ref [String]
+    # @param columns [Array<String>, Array<Hash>]
+    # @param name [String, nil]
+    # @param display_name [String, nil]
+    # @param style [String, nil]
+    # @param opts [Hash]
+    # @return [Hash]
+    #: (String ref, columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> Hash[Symbol, untyped]
+    def self.normalize_table_options(ref, columns:, name: nil, display_name: nil, style: nil, **opts)
+      tbl = { ref: ref, columns: columns }
+      tbl[:name] = name if name
+      tbl[:display_name] = display_name if display_name
+      tbl[:style] = style if style
+      tbl.merge!(opts)
+      tbl
+    end
+
+    # Converts a cell range (e.g. "A1:B2" or "A1") to an absolute reference format (e.g. "$A$1:$B$2" or "$A$1").
+    #
+    # @param range [String]
+    # @return [String]
+    #: (String range) -> String
+    def self.absolute_range(range)
+      range.gsub(/(?:\$)?([A-Z]+)(?:\$)?(\d+)\b/, '$\1$\2')
+    end
+
+    # Normalizes row values: if given a column-keyed Hash, converts to a sparse Array.
+    # If already an Array or other non-Hash enumerable, returns as-is without allocations.
+    #
+    # @param values [Array<Object>, Hash{String, Integer, Symbol => Object}, nil]
+    # @return [Array<Object>, nil]
+    #: (untyped values) -> untyped
+    def self.normalize_row_values(values)
+      return values unless values.is_a?(Hash)
+
+      cells_array = []
+      values.each do |k, v|
+        cells_array[Elements::Cell.column_index(k)] = v
+      end
+      cells_array
+    end
+
+    # Normalizes row styles: if given a Hash of column-keyed styles (including Ranges/Arrays),
+    # expands to a sparse Array of styles. If already an Array or nil, returns as-is without allocations.
+    #
+    # @param styles [untyped]
+    # @return [untyped]
+    #: (untyped styles) -> untyped
+    def self.normalize_row_styles(styles)
+      return styles unless styles.is_a?(Hash)
+
+      styles_array = []
+      styles.each do |k, v|
+        if k.is_a?(Range) || k.is_a?(Array)
+          k.each { |idx| styles_array[Elements::Cell.column_index(idx)] = v }
+        else
+          styles_array[Elements::Cell.column_index(k)] = v
+        end
+      end
+      styles_array
+    end
+
+    # Validates row index and height against Excel limits in strict mode.
+    #
+    # @param row_index [Integer]
+    # @param height [Float, Integer, nil]
+    # @param strict_excel_mode [Boolean]
+    # @return [void]
+    #: (Integer row_index, Float | Integer | nil height, ?strict_excel_mode: bool) -> void
+    def self.validate_row_bounds!(row_index, height, strict_excel_mode: true)
+      return unless strict_excel_mode
+
+      raise ArgumentError, "Row index #{row_index} exceeds Excel limit of 1,048,576 rows" if row_index >= 1_048_576
+      raise ArgumentError, "Row height #{height} must be between 0 and 409 points (Excel limitation)" if height && (height.negative? || height > 409)
+    end
+  end
+end