xlsxrb 0.1.4 → 0.1.6

data/docs/ARCHITECTURE.md

@@ -18,6 +18,30 @@ 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 delegation to avoid boilerplate, we explicitly generate and write out those delegations in the source code.
+
+### 1. **`Xlsxrb` Module is the ONLY Entrypoint:**
+   The `Xlsxrb` module provides the top-level methods: `generate`, `build`, `read`, `foreach`, and `modify`. Users should **never** instantiate internal classes (like `Xlsxrb::Ooxml::WorkbookWriter`) directly.
+
+2. **The `@api public` Contract (SemVer Guarantee):**
+   Any module, class, or method tagged with `# @api public` in its YARD documentation is guaranteed to follow Semantic Versioning.
+   - Patch versions (0.1.x -> 0.1.y) will not break these APIs.
+   - Minor versions (0.x.0 -> 0.y.0) will not break these APIs once 1.0.0 is released (during 0.x.x, it is a best-effort promise).
+   - Major versions (1.x -> 2.x) are the only time breaking changes to `@api public` components are permitted.
+
+3. **Block-Yielded Objects are Public APIs:**
+   All builder objects yielded into blocks (e.g., `writer` in `Xlsxrb.generate { |writer| }`, `sheet` in `writer.sheet { |sheet| }`, `chart` in `sheet.chart { |chart| }`) are explicitly marked as `@api public`. Their exposed methods constitute the DSL and are strictly protected by the SemVer contract.
+
+---
+
 ## 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. |
+