xlsxrb 0.1.4 → 0.1.5

data/CHANGELOG.md

@@ -1,12 +1,33 @@
 ## [Unreleased]
+- No unreleased changes.
 
+## [0.1.5] - 2026-08-11
+
+### Added
+- Functional API for updating existing files (`Xlsxrb.modify`).
+- New `Workbook#update_sheet` and `Worksheet#update_cell` helpers for immutable data structures.
+- Syntactic sugar for `styles:` in `sheet.row` using `Hash` and `Range` keys (e.g. `styles: { 0..4 => "header" }`).
+- Support for inline anonymous styles as Hash objects (e.g. `styles: { 0 => { font: { bold: true } } }`).
+- Support for `Range` and `Array` arguments in `sheet.column` to modify multiple columns at once.
+- `WorkbookBuilder#[]` and `StreamWriter#[]` aliased to `#sheet` for elegant context switching.
+- Block-based configuration for `font` and `border` properties inside `StyleBuilder`.
+- Extensive inline RBS typing with strict generic types (eliminated `untyped` from the public API).
+- 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.
+
+### Changed
+- Replaced `method_missing` with statically defined, fully typed methods in `WorksheetProxy`, `ChartBuilder`, and `SeriesBuilder`.
+- Removed deprecated `instance_eval` block context for builders; explicit block arguments are now required.
+- Hardened security and bounds checking across the DSL for `strict_excel_mode`.
+- Fixed numerous Rubocop linting violations and standardized style rules.
 - Add specification reference policy and implemented specification mapping (`docs/SPEC_SOURCES.md`).
 - Introduce unified event-based streaming and parsing architecture (`Ooxml::Event` and event streams for WorksheetParser/SharedStringsParser).
-- Restructure test suite into four distinct tiers (Unit, Contract, E2E, Visual).
-- Add visual examples gallery (`examples/visual/` and `docs/visual/README.md`).
+- Restructure test suite into four distinct tiers (Unit, Contract, E2E, Visual) and renamed `facade_test.rb` to `public_api_test.rb`.
+- Add visual examples gallery (`examples/visual/` and `docs/visual/README.md`) and promoted it via animated GIF in the main README.
 - Implement visual regression testing (VRT) pipeline comparing generated sheets against reference baselines.
 
-
 ## [0.1.0] - 2026-03-25
 
 - Initial release

data/README.md

@@ -77,11 +77,11 @@ Generate large files efficiently by writing data directly to the file stream:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.generate("large_output.xlsx") do |writer|
-  writer.add_sheet("Sales Data") do
-    writer.add_row(["Date", "Amount", "Status"])
-    writer.add_row([Date.today, 100, true])
-    writer.set_column(0, width: 15.5)
+Xlsxrb.generate("large_output.xlsx") do |wb|
+  wb.sheet("Sales Data") do |sheet|
+    sheet.row(["Date", "Amount", "Status"])
+    sheet.row([Date.today, 100, true])
+    sheet.column(0, width: 15.5)
   end
 end
 ```
@@ -91,12 +91,56 @@ Read rows one at a time without loading the entire file into memory:
 ```ruby
 require "xlsxrb"
 
-Xlsxrb.foreach("large_file.xlsx", sheet: 0) do |row|
-  puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
+Xlsxrb.foreach("large_file.xlsx") do |sheet|
+  sheet.each do |row|
+    puts "Row #{row.index}: #{row.cells.map(&:value).join(', ')}"
+  end
+end
+```
+
+### In-Memory Building & Modifying
+
+`xlsxrb` provides a powerful, immutable-by-default API for modifying existing Excel files or building templates in-memory. 
+
+#### Modifying an Existing File
+You can update specific cells or sheets using the functional `Xlsxrb.modify` API, which yields the parsed `Workbook`.
+
+```ruby
+require "xlsxrb"
+
+# Create a dummy template.xlsx for this example
+Xlsxrb.build { |w| w.sheet("Invoice") }.write("template.xlsx")
+
+Xlsxrb.modify("template.xlsx", "output.xlsx") do |wb|
+  wb.update_sheet("Invoice") do |sheet|
+    # Update a specific cell
+    sheet = sheet.update_cell("C4", value: "INV-10042")
+    sheet = sheet.update_cell("C5", value: Date.today)
+    
+    # Or append new rows
+    sheet.with(rows: sheet.rows + [
+      Xlsxrb::Elements::Row.new(index: sheet.rows.size, cells: [])
+    ])
+  end
 end
 ```
 
-*(For In-Memory document building, cell modifications, or template updating, please refer to the detailed RDoc API documentation).*
+#### Hash & Range Styling (Syntactic Sugar)
+You can directly apply inline styles or use Ranges for multiple columns without boilerplate:
+
+```ruby
+Xlsxrb.build do |wb|
+  # Use [] accessor for sheets
+  wb["Report"].row(
+    ["ID", "Name", "Score", "Rank"],
+    # Apply 'header' style to first two columns, and bold inline style to the third
+    styles: { 0..1 => "header", 2 => { font: { bold: true, color: "red" } } }
+  )
+  
+  # Set multiple column widths at once using Ranges
+  wb["Report"].column("A".."D", width: 15.0)
+end
+```
 
 ## Feature Support & ECMA-376 Compliance
 
@@ -145,28 +189,58 @@ To run the benchmark locally for 1,000,000 cells (100,000 rows):
 ruby benchmark.rb 100000
 ```
 
+## Security (Protection against CSV/Excel Injection)
+
+Unlike CSV files which lack type definitions and force Excel to guess types (often inadvertently executing strings starting with `=`), `.xlsx` files generated by `xlsxrb` are strictly typed.
+
+When you pass a Ruby `String` to `xlsxrb`, it explicitly writes it as a `String` (`t="s"`) into the OOXML file. Therefore, **even if a string starts with `=`, Excel will never evaluate it as a formula**. To write a formula, you must explicitly use `Xlsxrb::Elements::Formula.new`. This design completely mitigates CSV/Formula Injection vulnerabilities by default without requiring additional sanitization.
+
+### External Link Updates (`update_links`)
+
+As an extra layer of "defense in depth", `xlsxrb` configures the workbook to **never automatically update external links** when opened (`updateLinks="never"`). This is intentionally set to `never` by default to prevent Excel from silently reaching out to external resources or executing DDE (Dynamic Data Exchange) links, which is a known vector for malware.
+
+If you absolutely need external links to update automatically, you can explicitly override this (though **it is highly discouraged due to security risks**):
+
+```ruby
+Xlsxrb.generate("file.xlsx") do |wb|
+  # WARNING: Enabling this can expose users to malicious external reference vulnerabilities!
+  wb.workbook_property(:update_links, "always") 
+  # ...
+end
+```
+
 ## Testing & Quality Assurance
 
-To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a 4-tier testing strategy:
+To support reliability, compliance with the ECMA-376 specification, and consistent updates, `xlsxrb` is backed by a highly rigorous, enterprise-grade Quality Assurance (QA) and testing architecture.
+
+### Multi-Tier Testing Strategy
+* **Round-Trip Testing**: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
+* **Contract Consistency**: Ensures semantic output consistency between the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build`) APIs.
+* **Property-Based Testing (PBT)**: Automatically generates random data to catch edge cases (e.g., huge numbers, special characters) preventing unexpected crashes.
+* **Concurrency Validation**: Thread and Ractor safety checks to guarantee no global variable pollution during parallel execution.
+* **Security & DoS Protection**: Hardened against malicious files, including memory exhaustion (ZIP Bombs) and infinite parsing loops.
+
+### Strict Interoperability & Rendering
+* **Official Open XML SDK Validation (E2E)**: Every generated spreadsheet is structurally validated against the official Microsoft Open XML SDK to prevent file corruption warnings in Microsoft Excel.
+* **Visual Regression Testing (VRT)**: Spreadsheets are rendered via a headless LibreOffice Calc engine and compared pixel-by-pixel against visual baselines to catch subtle rendering regressions.
 
-1. Round-Trip Testing: Unit tests verify that every generated sheet can be reliably parsed back by the reader with identical content and styling.
-2. Contract Consistency: The library ensures semantic output consistency between the Streaming (`Xlsxrb.generate`) and In-Memory (`Xlsxrb.build`) APIs.
-3. Official Open XML SDK Validation (E2E): Every feature is validated against the official Microsoft Open XML SDK. Generated spreadsheets are structurally checked to prevent file corruption warnings.
-4. Visual Regression Testing (VRT): To guarantee rendering correctness, generated XLSX files are rendered via a headless LibreOffice Calc engine, and compared pixel-by-pixel against visual baselines.
+### Performance & Types
+* **Continuous Benchmarking**: Memory usage and processing speeds are profiled in CI on large datasets to prevent performance regressions and OOM leaks.
+* **Runtime Type Validation**: Strong dynamic typing using `RBS::Test` to ensure the library's types are perfectly sound at runtime.
 
-For details on running the tests locally or within our pre-configured Dev Container, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+For a comprehensive breakdown of our QA matrix, see [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md). For details on running tests locally, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
 ## Development
 
 We welcome contributions! The project is configured with a ready-to-use Dev Container to streamline local environment setup.
 
-For contribution guidelines, E2E testing policies, and the step-by-step development workflow, please refer to [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+For contribution guidelines, E2E testing policies, and the step-by-step development workflow (including how to run the Dev Container from your terminal), please refer to [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/niku/xlsxrb. 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/niku/xlsxrb/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/niku/xlsxrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -174,4 +248,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Xlsxrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/niku/xlsxrb/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Xlsxrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -88,6 +88,12 @@ end
 task test: %i[build_sdk_runner ensure_reader_fixtures]
 
 namespace :test do
+  desc "Run tests with runtime type checking enabled (RBS_TEST=1)"
+  task :rbs do
+    ENV["RBS_TEST"] = "1"
+    Rake::Task["test:unit"].invoke
+    Rake::Task["test:contract"].invoke
+  end
   Rake::TestTask.new(:unit) do |t|
     t.libs << "test"
     t.libs << "lib"
@@ -139,7 +145,10 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+require "bundler/audit/task"
+Bundler::Audit::Task.new
+
+task default: %i[bundle:audit rubocop typecheck test]
 
 namespace :visual do
   desc "Generate docs/visual/ README.md explanation gallery"
@@ -210,6 +219,8 @@ task :wasm do
 
   # A. Write custom static stubs and gateways dynamically
   File.write(File.join(bundle_assets_dir, "openssl.rb"), "# frozen_string_literal: true\n")
+  time_rb_path = $LOAD_PATH.lazy.map { |p| File.join(p, "time.rb") }.find { |f| File.exist?(f) }
+  FileUtils.cp(time_rb_path, bundle_assets_dir) if time_rb_path
 
   File.write(File.join(bundle_assets_dir, "opentelemetry.rb"), <<~RUBY)
     # frozen_string_literal: true
@@ -410,7 +421,7 @@ task doc: %i[wasm fetch_assets] do
      "--exclude 'docs/zeta\\.js' " \
      "--exclude 'docs/office_thread\\.js' " \
      "--exclude 'docs/preview\\.html' " \
-     "--title 'xlsxrb Documentation' --main README.md README.md \"docs/visual/VisualGallery.md\" lib/"
+     "--title 'xlsxrb Documentation' --main README.md README.md CHANGELOG.md CODE_OF_CONDUCT.md docs/*.md \"docs/visual/VisualGallery.md\" lib/"
 
   # Copy visual gallery images and files so they are available in RDoc output
   FileUtils.mkdir_p("doc/test/visual/baselines")
@@ -514,3 +525,12 @@ namespace :doc do
     end
   end
 end
+desc "Generate RBS signature files from inline annotations"
+task :sig do
+  sh "bundle exec rbs-inline --output lib/**/*.rb"
+end
+
+desc "Run static type checking with Steep"
+task typecheck: :sig do
+  sh "bundle exec steep check"
+end

data/Steepfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+
+  check "lib/xlsxrb.rb"
+
+  library "date"
+  library "time"
+  library "securerandom"
+  library "openssl"
+  library "pathname"
+  library "tempfile"
+  library "bigdecimal"
+
+  repo_path "sig"
+
+  configure_code_diagnostics(Steep::Diagnostic::Ruby.lenient)
+end

data/docs/ARCHITECTURE.md

@@ -18,6 +18,23 @@ Xlsxrb uses **only** the Ruby standard library and Bundled Gems:
 
 ---
 
+## Coding Policies
+
+### 🚫 The `method_missing` Policy
+As a strict rule, **we do not accept dynamic method definitions using `method_missing`** anywhere in the codebase. All user-facing API methods and internal delegations must be explicitly defined in the code. This ensures:
+1. **Type Safety & Static Analysis**: RBS and Steep can completely validate arguments and structures.
+2. **Developer Experience**: IDE autocompletion, jump-to-definition, and YARD documentation work perfectly.
+3. **Traceability**: If a method exists, you can `grep` for it.
+
+Even in cases where proxy patterns (e.g. `WorksheetProxy`) or OOXML builder mappings (e.g. `ChartBuilder`, `SeriesBuilder`) would traditionally benefit from dynamic method delegation to avoid boilerplate, we explicitly generate and write out those delegations in the source code.
+
+### API Contract (SemVer)
+- Methods tagged with `@api public` in their YARD documentation are guaranteed to follow SemVer.
+- Methods without this tag (or tagged `@api private`) are internal and may change at any time.
+- Note that during the 0.x series, this is a "best effort" promise, but after 1.0.0, strict SemVer guarantees will apply to all `@api public` methods.
+
+---
+
 ## Directory Structure
 
 ```

data/docs/DEVELOPMENT.md

@@ -65,3 +65,61 @@ Omission is only acceptable when **all** of the following hold:
 3. Unit tests and round-trip tests fully cover the new behaviour.
 4. `rake test` passes with Open XML SDK validation included.
 5. The commit message explicitly names the existing E2E scenario that provides coverage and states why a new scenario adds no value.
+
+---
+
+## Development via Dev Container
+
+The project is pre-configured with a Dev Container to simplify local environment setup (installing .NET, LibreOffice, ImageMagick, and Noto fonts).
+
+### VS Code (GUI)
+You can open this repository in VS Code and select **"Dev Containers: Reopen in Container"** from the Command Palette.
+
+### Terminal (Devcontainer CLI)
+If you prefer to use the terminal instead of VS Code, you can run the devcontainer using the official `@devcontainers/cli`:
+
+1. Install the CLI on your host machine (if not already installed):
+   ```bash
+   npm install -g @devcontainers/cli
+   ```
+2. Use the helper script `bin/devcontainer` to start and interact with the container:
+   - **Interactive shell** (Automatically shares your host's Git/AI tool configs as read-only):
+     ```bash
+     bin/devcontainer
+     ```
+   - **Run commands directly**:
+     ```bash
+     bin/devcontainer rake test
+     ```
+
+### Customizing with Personal Overrides (e.g., Dotfiles, API Keys, Shell History)
+
+The `bin/devcontainer` script dynamically parses a personal configuration patch and maps it to devcontainer CLI flags on startup. This is a workaround for a specification limit of devcontainer CLI's `--override-config` flag, which acts as a complete replacement of the configuration rather than a partial merge, wiping out base configurations like build settings.
+
+To configure this, create a JSON (or JSONC) file at `${XDG_CONFIG_HOME:-~/.config}/devcontainer/override.jsonc` (or `override.json`) on your host machine.
+
+**Example: Persisting histories, forwarding API keys, and Auto-installing Dotfiles**
+```json
+{
+  "mounts": [
+    // Volume for general persistent directories (e.g., Claude Code history in ~/.local/share/claude)
+    "type=volume,source=xlsxrb-local-share,target=/home/vscode/.local/share"
+  ],
+  "containerEnv": {
+    // Explicitly forward API keys from your host shell to the container environment
+    "OPENAI_API_KEY": "${localEnv:OPENAI_API_KEY}",
+    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
+    "GEMINI_API_KEY": "${localEnv:GEMINI_API_KEY}"
+  },
+  "dotfiles": {
+    "repository": "https://github.com/<your-github-username>/dotfiles.git",
+    "targetPath": "~/dotfiles",
+    "installCommand": "install.sh"
+  }
+}
+```
+
+You can also use a custom file path by exporting the `DEVCONTAINER_OVERRIDE_CONFIG` environment variable in your host shell:
+```bash
+export DEVCONTAINER_OVERRIDE_CONFIG="/path/to/your/custom-override.json"
+```

data/docs/QUALITY_ASSURANCE.md

@@ -0,0 +1,26 @@
+# Quality Assurance (QA) & Testing Architecture
+
+`xlsxrb` is designed to be an enterprise-grade, highly reliable, and highly performant library for reading and writing Excel spreadsheets. To achieve and maintain this standard, we have implemented a comprehensive Quality Assurance matrix that covers everything from static code analysis and dynamic runtime validation to performance benchmarking and visual regression testing.
+
+Below is an overview of the inspection mechanisms, when they run, the quality attributes they guarantee, and the specific bugs they prevent.
+
+## QA Matrix
+
+| Inspection Mechanism / Tool | Execution Command / Mechanism | Local | CI (PR/Push) | Scheduled (Weekly) | Target Quality Attribute | Validation Method | Prevented Bugs / Issues |
+| :--- | :--- | :---: | :---: | :---: | :--- | :--- | :--- |
+| **RuboCop** | `rake rubocop` | ⭕ | ⭕ | - | Readability / Maintainability | Static Analysis (Syntax/Linting) | Overly complex methods, non-standard syntax, unused variables. |
+| **Steep & RBS** | `rake typecheck` | ⭕ | ⭕ | - | Type Safety (Static) | Static Analysis (Type Check) | `NoMethodError`, passing incorrect arguments, method typo bugs. |
+| **Bundler Audit** | `rake audit` | - | ⭕ | - | Security | Dependency Scanning | Inclusion of external gems with known vulnerabilities (CVEs). |
+| **Dependabot** | `.github/dependabot.yml` | - | - | ⭕ | Currency / Maintenance | Repository Monitoring | Outdated dependencies or CI actions. |
+| **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)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
+
+| **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. |
+| **E2E Interoperability Tests** | `rake test:e2e` | △ (Opt-in) | ⭕ | - | Compatibility (Real-world) | 3rd-party SDK Execution | Structural defects so severe that the official .NET SDK cannot read them. |
+| **Load / Stress Testing** | Action: `benchmark.yml` | - | ⭕ | - | Performance / Stability | Massive Data Generation (e.g., 10k+ rows) | Out of Memory (OOM) crashes or extreme delays when processing large datasets. |
+| **Memory & Speed Benchmark** | Action: `benchmark.yml` | - | ⭕ | - | Performance | Continuous Profiling | Memory leaks, severe performance degradation due to inefficient loop additions. |
+| **Visual Regression Testing (VRT)** | `rake test:visual` | - | ⭕ | - | Visual Accuracy (UI/UX) | Headless Rendering / Pixel Diff | Visual bugs like "cell background colors dropping" or "chart layouts breaking" after code changes. |
+