xlsxrb 0.1.2 → 0.1.3

data/benchmark.rb

@@ -192,6 +192,13 @@ 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 +207,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: */