xlsxrb 0.1.2 → 0.1.4

data/Rakefile

@@ -192,11 +192,13 @@ task :wasm do
     require "open-uri"
     wasm_url = "https://cdn.jsdelivr.net/npm/@ruby/4.0-wasm-wasi@2.9.3-2.9.4/dist/ruby.wasm"
     FileUtils.mkdir_p(File.dirname(original_wasm_cache))
+    # rubocop:disable Security/Open
     URI.open(wasm_url) do |stream|
       File.open(original_wasm_cache, "wb") do |file|
         IO.copy_stream(stream, file)
       end
     end
+    # rubocop:enable Security/Open
     puts "Original ruby.wasm cached successfully."
   end
 
@@ -231,9 +233,7 @@ task :wasm do
 
   # Resolve and copy host's rexml files
   rexml_spec_path = $LOAD_PATH.find { |p| File.exist?(File.join(p, "rexml/rexml.rb")) }
-  if rexml_spec_path
-    FileUtils.cp_r(File.join(rexml_spec_path, "rexml"), bundle_assets_dir)
-  end
+  FileUtils.cp_r(File.join(rexml_spec_path, "rexml"), bundle_assets_dir) if rexml_spec_path
 
   # Gateway for strscan
   File.write(File.join(bundle_assets_dir, "strscan.rb"), <<~RUBY)
@@ -259,11 +259,11 @@ task :wasm do
   ]
   stdlib_files.each do |name|
     path = $LOAD_PATH.find { |p| File.exist?(File.join(p, name)) }
-    if path
-      dest_path = File.join(bundle_assets_dir, name)
-      FileUtils.mkdir_p(File.dirname(dest_path))
-      FileUtils.cp(File.join(path, name), dest_path)
-    end
+    next unless path
+
+    dest_path = File.join(bundle_assets_dir, name)
+    FileUtils.mkdir_p(File.dirname(dest_path))
+    FileUtils.cp(File.join(path, name), dest_path)
   end
 
   # C. Patch tmpdir.rb to automatically create /tmp in Wasm virtual filesystem (since Wasm has no writable /tmp by default)
@@ -286,20 +286,136 @@ task :wasm do
   puts "Building packed ruby.wasm from staging bundle..."
   cmd = "bundle exec rbwasm pack #{original_wasm_cache} --dir #{wasm_bundle_dir}::/usr/local/lib/ruby/site_ruby -o #{packed_wasm_path}"
   puts "Executing: #{cmd}"
-  unless system(cmd)
-    raise "Failed to build packed ruby.wasm using rbwasm pack!"
+  raise "Failed to build packed ruby.wasm using rbwasm pack!" unless system(cmd)
+end
+
+def download_file(url, dest)
+  # Check if the file exists and is not a tiny placeholder/error document
+  return if File.exist?(dest) && File.size(dest) > 1024
+
+  puts "Downloading #{url} to #{dest}..."
+  FileUtils.mkdir_p(File.dirname(dest))
+
+  require "net/http"
+  uri = URI.parse(url)
+  temp_dest = "#{dest}.tmp"
+
+  begin
+    Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 15, read_timeout: 90) do |http|
+      request = Net::HTTP::Get.new(uri)
+      # Specify User-Agent to bypass scraping prevention on CDNs and act as a normal browser
+      request["User-Agent"] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+      # Force raw (identity) encoding to prevent receiving Brotli-compressed (.br) data,
+      # which Ruby's Net::HTTP cannot decode automatically, leading to corrupted Wasm files.
+      request["Accept-Encoding"] = "identity"
+
+      http.request(request) do |response|
+        raise "HTTP error #{response.code}: #{response.message}" if response.code.to_i != 200
+
+        File.open(temp_dest, "wb") do |output|
+          response.read_body do |chunk|
+            output.write(chunk)
+          end
+        end
+      end
+    end
+    # Atomic rename to prevent leaving incomplete files on failure
+    File.rename(temp_dest, dest)
+    puts "Downloaded successfully."
+
+    # Dynamic Brotli Decompression if the server ignored identity encoding and sent Brotli (.br) data
+    if File.exist?(dest) && File.binread(dest, 4)&.bytes == [0xCF, 0xFF, 0xFF, 0x7F]
+      puts "Detected Brotli compression on #{dest}. Decompressing..."
+
+      unpacked = "#{dest}.unpacked"
+      if system("brotli -d -f -o #{unpacked} #{dest}")
+        File.rename(unpacked, dest)
+        puts "Decompressed #{dest} successfully."
+      else
+        FileUtils.rm_f(unpacked)
+        raise "Failed to decompress Brotli file: #{dest}"
+      end
+    end
+  rescue StandardError => e
+    puts "Failed to download #{url}: #{e.message}"
+    FileUtils.rm_f(temp_dest)
+    FileUtils.rm_f(dest)
+    raise "Required asset download failed. Build aborted."
+  end
+end
+
+def fetch_google_fonts
+  css_dest = "docs/fonts/fonts.css"
+  return if File.exist?(css_dest)
+
+  puts "Fetching and localizing Google Fonts..."
+  font_url = "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
+
+  css_content = nil
+  begin
+    # Specify Chrome User-Agent to ensure Google Fonts returns modern and lightweight .woff2 formats
+    # instead of legacy formats (like .ttf or .eot) designed for older browsers
+    # rubocop:disable Security/Open
+    URI.open(font_url, "User-Agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36") do |f|
+      css_content = f.read
+    end
+    # rubocop:enable Security/Open
+  rescue StandardError => e
+    puts "Failed to fetch Google Fonts CSS: #{e.message}"
+    return
   end
+
+  urls = css_content.scan(%r{url\((https://fonts\.gstatic\.com/[^)]+)\)}).flatten
+
+  urls.uniq.each do |url|
+    filename = url.split("/").last
+    local_path = "docs/fonts/#{filename}"
+    download_file(url, local_path)
+    css_content.gsub!(url, filename)
+  end
+
+  FileUtils.mkdir_p("docs/fonts")
+  File.write(css_dest, css_content)
+  puts "Google Fonts localized successfully."
+end
+
+desc "Fetch required external assets for offline usage"
+task :fetch_assets do
+  require "open-uri"
+  require "fileutils"
+
+  # Fetch Ruby WASI JS
+  download_file(
+    "https://cdn.jsdelivr.net/npm/@ruby/wasm-wasi@2.9.3-2.9.4/dist/browser.umd.js",
+    "docs/wasm/browser.umd.js"
+  )
+
+  # Fetch ZetaOffice Wasm
+  base_zeta_url = "https://cdn.zetaoffice.net/zetaoffice_latest/"
+  %w[soffice.js soffice.wasm soffice.data soffice.data.js.metadata qtloader.js].each do |file|
+    download_file(base_zeta_url + file, "docs/zetaoffice/#{file}")
+  end
+
+  # Fetch and localize Google Fonts
+  fetch_google_fonts
 end
 
 desc "Generate RDoc documentation including Visual Gallery"
-task doc: :wasm do
+task doc: %i[wasm fetch_assets] do
   FileUtils.rm_rf("doc")
-  sh "bundle exec rdoc --title 'xlsxrb Documentation' --main README.md README.md \"docs/visual/VisualGallery.md\" lib/"
+
+  # RDoc コマンドを実行 (--exclude を指定して docs 配下のプレビュー用アセットの誤パースを回避)
+  sh "bundle exec rdoc --op doc " \
+     "--exclude 'docs/coi-serviceworker\\.js' " \
+     "--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/"
 
   # Copy visual gallery images and files so they are available in RDoc output
   FileUtils.mkdir_p("doc/test/visual/baselines")
-  FileUtils.cp_r("test/visual/baselines", "doc/test/visual")
   FileUtils.mkdir_p("doc/test/visual/support/illustrations")
+  FileUtils.cp_r(Dir.glob("test/visual/baselines/*"), "doc/test/visual/baselines")
   FileUtils.cp_r(Dir.glob("test/visual/support/illustrations/*.png"), "doc/test/visual/support/illustrations")
 
   FileUtils.mkdir_p("doc/docs/visual/files")
@@ -312,21 +428,36 @@ task doc: :wasm do
   FileUtils.mkdir_p("doc/css")
   FileUtils.mkdir_p("doc/js")
   FileUtils.mkdir_p("doc/wasm")
+  FileUtils.mkdir_p("doc/zetaoffice")
+  FileUtils.mkdir_p("doc/fonts")
+
   FileUtils.cp("docs/wasm/wasm_doc_helper.js", "doc/js/wasm_doc_helper.js")
   FileUtils.cp("docs/wasm/wasm_doc_helper.css", "doc/css/wasm_doc_helper.css")
   FileUtils.cp("docs/wasm/ruby.wasm", "doc/wasm/ruby.wasm")
+  FileUtils.cp("docs/wasm/browser.umd.js", "doc/wasm/browser.umd.js")
+  FileUtils.cp_r(Dir.glob("docs/zetaoffice/*"), "doc/zetaoffice")
+  FileUtils.cp_r(Dir.glob("docs/fonts/*"), "doc/fonts")
+
+  # Copy LibreOffice Wasm Preview assets to doc directory
+  FileUtils.cp("docs/preview.html", "doc/preview.html")
+  FileUtils.cp("docs/coi-serviceworker.js", "doc/coi-serviceworker.js")
+  FileUtils.cp("docs/zeta.js", "doc/zeta.js")
+  FileUtils.cp("docs/office_thread.js", "doc/office_thread.js")
 
   # Inject stylesheet and javascript loading tags to all generated HTML docs
   Dir.glob("doc/**/*.html").each do |html_path|
+    next if File.basename(html_path) == "preview.html"
+
     html_content = File.read(html_path)
     depth = html_path.sub(%r{\Adoc/}, "").count("/")
     rel_prefix = "../" * depth
 
-    js_tag = %Q{<script src="#{rel_prefix}js/wasm_doc_helper.js" defer></script>}
-    css_tag = %Q{<link href="#{rel_prefix}css/wasm_doc_helper.css" rel="stylesheet">}
+    coi_tag = %(<script src="#{rel_prefix}coi-serviceworker.js"></script>)
+    js_tag = %(<script src="#{rel_prefix}js/wasm_doc_helper.js" defer></script>)
+    css_tag = %(<link href="#{rel_prefix}css/wasm_doc_helper.css" rel="stylesheet">)
 
     if html_content.include?("<body")
-      modified = html_content.sub("<body", "#{js_tag}\n#{css_tag}\n<body")
+      modified = html_content.sub("<body", "#{coi_tag}\n#{js_tag}\n#{css_tag}\n<body")
       File.write(html_path, modified)
     end
   end
@@ -346,7 +477,23 @@ namespace :doc do
       Port: port,
       DocumentRoot: File.expand_path("doc", __dir__),
       Logger: WEBrick::Log.new(nil, WEBrick::BasicLog::WARN),
-      AccessLog: []
+      AccessLog: [],
+      # If the file is a Brotli-compressed Wasm/Data asset (checked via magic bytes),
+      # dynamically inject 'Content-Encoding: br' header so the browser decompresses it natively.
+      RequestCallback: lambda { |req, res|
+        if req.path.end_with?(".wasm") || req.path.end_with?(".data")
+          # Resolve physical file path from req.path manually since res.filename is nil at this stage
+          local_path = File.join(File.expand_path("doc", __dir__), req.path)
+          if File.exist?(local_path)
+            first_bytes = begin
+              File.binread(local_path, 4)
+            rescue StandardError
+              nil
+            end
+            res["Content-Encoding"] = "br" if first_bytes != "\x00asm"
+          end
+        end
+      }
     )
 
     puts "=================================================="

data/benchmark.rb

@@ -192,6 +192,14 @@ def run_in_subprocess(_name, &block)
   end
 end
 
+def median(array)
+  return 0.0 if array.empty?
+
+  sorted = array.sort
+  len = sorted.length
+  (sorted[(len - 1) / 2] + sorted[len / 2]) / 2.0
+end
+
 def run_benchmark(name, snippet)
   print format("%-25s", name)
   results = ITERATIONS.times.map do
@@ -200,23 +208,25 @@ def run_benchmark(name, snippet)
   end
   puts
 
-  avg_time = results.compact.map { |r| r[:time] }.compact.sum / results.compact.size.to_f
-  avg_cpu = results.compact.map { |r| r[:cpu] }.compact.sum / results.compact.size.to_f
-  avg_mem = results.compact.map { |r| r[:memory] }.compact.sum / results.compact.size.to_f
-  avg_gc = results.compact.map { |r| r[:gc_count] }.compact.sum / results.compact.size.to_f
-  avg_alloc = results.compact.map { |r| r[:alloc_objects] }.compact.sum / results.compact.size.to_f
-  avg_wchar = results.compact.map { |r| r[:wchar] }.compact.sum / results.compact.size.to_f
-  avg_rchar = results.compact.map { |r| r[:rchar] }.compact.sum / results.compact.size.to_f
+  valid_results = results.compact
+
+  median_time = median(valid_results.map { |r| r[:time] }.compact)
+  median_cpu = median(valid_results.map { |r| r[:cpu] }.compact)
+  median_mem = median(valid_results.map { |r| r[:memory] }.compact)
+  median_gc = median(valid_results.map { |r| r[:gc_count] }.compact)
+  median_alloc = median(valid_results.map { |r| r[:alloc_objects] }.compact)
+  median_wchar = median(valid_results.map { |r| r[:wchar] }.compact)
+  median_rchar = median(valid_results.map { |r| r[:rchar] }.compact)
 
   {
     name: name,
-    time: avg_time,
-    cpu: avg_cpu,
-    memory: avg_mem,
-    gc_count: avg_gc,
-    alloc_m: avg_alloc / 1_000_000.0,
-    wchar_mb: avg_wchar / 1_048_576.0,
-    rchar_mb: avg_rchar / 1_048_576.0
+    time: median_time,
+    cpu: median_cpu,
+    memory: median_mem,
+    gc_count: median_gc,
+    alloc_m: median_alloc / 1_000_000.0,
+    wchar_mb: median_wchar / 1_048_576.0,
+    rchar_mb: median_rchar / 1_048_576.0
   }
 end
 

data/docs/DEVELOPMENT.md

@@ -0,0 +1,67 @@
+# Development & Contribution Guide
+
+This document outlines the internal development workflow, test commands, and E2E testing policies for contributors working on `xlsxrb`.
+
+## Test Commands
+
+To run the different tiers of our testing strategy:
+
+1. **Unit Tests:**
+   ```bash
+   bundle exec rake test:unit
+   ```
+2. **Contract Tests:**
+   ```bash
+   bundle exec rake test:contract
+   ```
+3. **Interoperability (E2E) Tests:**
+   Requires .NET SDK to be installed (pre-configured in Dev Container).
+   ```bash
+   bundle exec rake test:e2e
+   ```
+4. **Visual Regression Tests (VRT):**
+   Requires LibreOffice, ImageMagick, and `poppler-utils`.
+   ```bash
+   bundle exec rake test:visual
+   ```
+5. **Run All Tests:**
+   ```bash
+   bundle exec rake test
+   ```
+
+---
+
+## 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.
+
+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:
+
+1. **Select a Feature:** Choose a specific element or behavior from the specification to implement.
+2. **Writer Unit Tests:** Write unit tests for the Writer component targeting this feature.
+3. **Writer Implementation:** Implement the Writer functionality.
+4. **Run Writer Tests:** Execute the Writer unit tests. If they fail, return to step 3.
+5. **Writer E2E & Validation:** Test the Writer's generated XLSX file using the Open XML SDK. This includes structural validation using `OpenXmlValidator`. If the test or validation fails, return to step 2.
+6. **Reader Unit Tests:** Write unit tests for the Reader component. Crucially, include round-trip tests to ensure the Reader can accurately parse the output of your Writer.
+7. **Reader Implementation:** Implement the Reader functionality.
+8. **Run Reader Tests:** Execute the Reader unit tests. If they fail, return to step 6 or 7. If the round-trip test reveals a structural flaw in the Writer's output, return all the way back to step 2.
+9. **Reader E2E:** Verify that the Reader can successfully parse a valid XLSX file generated by the Open XML SDK that includes the new feature. If it fails, return to step 6 or 7.
+10. **Full Test Suite:** Run the entire test suite (`rake test`). If any tests fail, trace back to the appropriate step.
+11. **Commit:** Commit the changes. The commit message must clearly describe the specific feature implemented in this cycle.
+12. **Next Feature:** Proceed to the next feature and return to step 1.
+
+---
+
+## E2E Policy
+
+E2E tests are required for every new feature. Omitting them is the exception, not the rule, and requires explicit justification.
+
+A strong signal that E2E should not be omitted: if you are adding a new XML element, a new attribute on a top-level structure, or a new public API parameter, E2E is expected.
+
+Omission is only acceptable when **all** of the following hold:
+
+1. The change adds a minor attribute to an XML structure that is **already exercised end-to-end** by an existing E2E scenario for the same element.
+2. No new XML element or branch is introduced.
+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.

data/docs/coi-serviceworker.js

@@ -0,0 +1,82 @@
+/*! coi-serviceworker v0.1.7 - Guido Zuidhof and contributors, licensed under MIT */
+// Source: https://github.com/gzguidoti/coi-serviceworker
+// Purpose: Allows running WebAssembly with SharedArrayBuffer on browsers by setting COOP and COEP headers via Service Worker.
+let coepCredentialless = false;
+if (typeof window === 'undefined') {
+    self.addEventListener("install", () => self.skipWaiting());
+    self.addEventListener("activate", (event) => event.waitUntil(self.clients.claim()));
+
+    self.addEventListener("message", (ev) => {
+        if (!ev.data) {
+            return;
+        } else if (ev.data.type === "deregister") {
+            self.registration
+                .unregister()
+                .then(() => {
+                    return self.clients.matchAll();
+                })
+                .then(clients => {
+                    clients.forEach((client) => client.navigate(client.url));
+                });
+        } else if (ev.data.type === "coepCredentialless") {
+            coepCredentialless = ev.data.value;
+        }
+    });
+
+    self.addEventListener("fetch", function (event) {
+        const r = event.request;
+        if (r.cache === "only-if-cached" && r.mode !== "same-origin") {
+            return;
+        }
+
+        const request = (coepCredentialless && r.mode === "no-cors")
+            ? new Request(r, { credentials: "omit" })
+            : r;
+        event.respondWith(
+            fetch(request)
+                .then((response) => {
+                    if (response.status === 0) {
+                        return response;
+                    }
+
+                    const newHeaders = new Headers(response.headers);
+                    newHeaders.set("Cross-Origin-Embedder-Policy",
+                        coepCredentialless ? "credentialless" : "require-corp"
+                    );
+                    if (!coepCredentialless) {
+                        newHeaders.set("Cross-Origin-Resource-Policy", "cross-origin");
+                    }
+                    newHeaders.set("Cross-Origin-Opener-Policy", "same-origin");
+
+                    return new Response(response.body, {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers: newHeaders,
+                    });
+                })
+                .catch((e) => console.error(e))
+        );
+    });
+} else {
+    (() => {
+        const reloaded = sessionStorage.getItem("coiReloaded");
+        const isSecureContext = window.isSecureContext;
+        if (!isSecureContext) return;
+
+        if (navigator.serviceWorker) {
+            navigator.serviceWorker.register(window.document.currentScript.src).then(
+                (registration) => {
+                    registration.addEventListener("updatefound", () => {
+                        sessionStorage.setItem("coiReloaded", "true");
+                        window.location.reload();
+                    });
+                    if (registration.active && !navigator.serviceWorker.controller) {
+                        sessionStorage.setItem("coiReloaded", "true");
+                        window.location.reload();
+                    }
+                },
+                (err) => console.error("COI registration failed: ", err)
+            );
+        }
+    })();
+}

data/docs/office_thread.js

@@ -0,0 +1,77 @@
+/* -*- Mode: JS; tab-width: 2; indent-tabs-mode: nil; js-indent-level: 2; fill-column: 100 -*- */
+// SPDX-License-Identifier: MIT
+// Source: Derived from ZetaOffice WebAssembly example (https://github.com/zetaoffice/zeta-wasm-examples)
+// Purpose: Runs WebAssembly-based LibreOffice (Calc) in a separate Web Worker thread.
+
+// Debugging note:
+// Switch the web worker in the browsers debug tab to debug this code.
+// It's the "em-pthread" web worker with the most memory usage, where "zetajs" is defined.
+
+'use strict';
+
+
+// global variables - zetajs environment:
+let zetajs, css;
+
+// = global variables (some are global for easier debugging) =
+// common variables:
+let context, desktop, xModel, ctrl;
+
+
+function demo() {
+  context = zetajs.getUnoComponentContext();
+  const bean_overwrite = new css.beans.PropertyValue({Name: 'Overwrite', Value: true});
+  const bean_odt_export = new css.beans.PropertyValue({Name: 'FilterName', Value: 'writer8'});
+  desktop = css.frame.Desktop.create(context);
+
+  zetajs.mainPort.onmessage = function (e) {
+    switch (e.data.cmd) {
+    case 'upload':
+      loadFile(e.data.filename);
+      break;
+    case 'download':
+      xModel.store();
+      zetajs.mainPort.postMessage({cmd: 'download', id: e.data.id});
+      break;
+    default:
+      throw Error('Unknown message command: ' + e.data.cmd);
+    }
+  }
+  zetajs.mainPort.postMessage({cmd: 'thr_running'});
+}
+
+function loadFile(filename) {
+  if (xModel) {
+    try {
+      const xCloseable = css.util.XCloseable.query(xModel);
+      if (xCloseable) {
+        xCloseable.close(true);
+      } else {
+        xModel.dispose();
+      }
+    } catch (e) {
+      console.warn("xCloseable.close failed, trying dispose:", e);
+      try {
+        xModel.dispose();
+      } catch (e2) {
+        console.error("Failed to dispose old xModel:", e2);
+      }
+    }
+    xModel = null;
+  }
+
+  const in_path = 'file:///tmp/office/' + filename;
+  xModel = desktop.loadComponentFromURL(in_path, '_default', 0, []);
+  ctrl = xModel.getCurrentController();
+  ctrl.getFrame().getContainerWindow().FullScreen = true;
+  zetajs.mainPort.postMessage({cmd: 'ui_ready'});
+}
+
+Module.zetajs.then(function(pZetajs) {
+  // initializing zetajs environment:
+  zetajs = pZetajs;
+  css = zetajs.uno.com.sun.star;
+  demo();  // launching demo
+});
+
+/* vim:set shiftwidth=2 softtabstop=2 expandtab cinoptions=b1,g0,N-s cinkeys+=0=break: */