dewasm-pozeiden 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 840e85a24319fdbcc2c333a875f547f80a90370f3f9ce8ee1f6b79f6095be983
+  data.tar.gz: 44f58f21c7df3ac443bd14033cdd9c8484ed75061cd3f5fb27d02fc87c5a02e0
+SHA512:
+  metadata.gz: 81a693085219f6198a4b7a0189ff0eef7a235494408614025662e8238a2c02823c2ca534af77c75b1f2cf8a2c287e23d8e4da88b6d9974c30b2e71a766978f21
+  data.tar.gz: e8c5324e3437768a57c2ad18fe12c57d385b30243b0d9d84055f380a2774e035c9222d0b4a1236f610205c512c7136d1a8337a4d417ff9bba7a6b73316e8ada1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hiroya Fujinami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE-POZEIDEN

@@ -0,0 +1,75 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright © 2025 Star City Security Consulting, LLC (SC2) (https://sc2.in)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

data/README.md

@@ -0,0 +1,231 @@
+# dewasm-pozeiden
+
+**Mermaid** diagram rendering in **pure Ruby**.
+
+[pozeiden](https://github.com/sc2in/pozeiden) is a mermaid renderer written in Zig.
+This gem compiles it to `wasm32-wasi` and converts that WebAssembly module to Ruby source with [dewasm](https://github.com/dewasm/dewasm), so rendering runs on plain Ruby.
+There is *no browser*, *no native extension*, and *no wasm runtime* involved: the gem is Ruby code that a stock `ruby` executes.
+
+The gem is built from pozeiden 0.4.1 at commit `071fbbb85fb73a06994c163c6093123bd3ac11f6`, pinned in `wasm/build.zig.zon` and surfaced as `Dewasm::Pozeiden::POZEIDEN_VERSION`.
+
+Seventeen diagram types are supported, the ones pozeiden implements: pie, flowchart, sequence, gitgraph, class, state, er, gantt, timeline, xychart, quadrant, mindmap, sankey, c4, block, requirement, and kanban.
+
+> [!NOTE]
+> This gem **cannot be used commercially**: the rendering core derives from pozeiden, which is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE-POZEIDEN).
+>
+> [dewasm-merman](https://github.com/dewasm/ruby-merman) is licensed under MIT and covers more diagram types, but is much larger.
+
+## Install
+
+```console
+$ gem install dewasm-pozeiden
+```
+
+Or in `Gemfile`:
+
+```ruby
+gem "dewasm-pozeiden"
+```
+
+Ruby 3.4 or newer is required, because the converted module stores WebAssembly linear memory in an `IO::Buffer`.
+
+## Usage
+
+Render a diagram to an SVG string:
+
+```ruby
+require "dewasm/pozeiden"
+
+svg = Dewasm::Pozeiden.render(<<~MERMAID)
+  flowchart LR
+    A[Start] --> B{Choice}
+    B --> C[End]
+MERMAID
+
+File.write("flowchart.svg", svg)
+```
+
+Unrecognised input renders pozeiden's fallback SVG and counts as success.
+Pass `strict: true` to get an error instead:
+
+```ruby
+Dewasm::Pozeiden.render("this is not a diagram at all")
+# => "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"400\" height=\"120\"> ..."
+
+Dewasm::Pozeiden.render("this is not a diagram at all", strict: true)
+# raises Dewasm::Pozeiden::Error: pozeiden returned error.UnknownDiagramType
+```
+
+`render_with_metadata` also returns the detected diagram type and the accessibility metadata declared in the source:
+
+```ruby
+result = Dewasm::Pozeiden.render_with_metadata(<<~MERMAID)
+  flowchart LR
+    accTitle: Build pipeline
+    accDescr: How a build flows
+    A --> B
+MERMAID
+
+result.diagram_type   # => :flowchart
+result.title          # => "Build pipeline"
+result.descr          # => "How a build flows"
+result.svg            # => "<svg ...>"
+```
+
+`detect_diagram_type` classifies the source without rendering it:
+
+```ruby
+Dewasm::Pozeiden.detect_diagram_type("pie title Pets\n")   # => :pie
+Dewasm::Pozeiden.detect_diagram_type("nothing here\n")     # => :unknown
+```
+
+Rendering options are keyword arguments of `render` and `render_with_metadata`:
+
+```ruby
+Dewasm::Pozeiden.render(source, max_width: 800, theme_override: { node_fill: "#ffe4b5" })
+```
+
+| Keyword | Meaning |
+| --- | --- |
+| `strict:` | Raise on unrecognised input instead of rendering the fallback SVG. Default `false`. |
+| `max_width:` | Scale the SVG so its width does not exceed this many user units. `0` disables. |
+| `max_height:` | Scale the SVG so its height does not exceed this many user units. `0` disables. |
+| `scale:` | Uniform scale factor for the SVG `viewBox`, ignored when `max_width` or `max_height` is set. |
+| `theme_override:` | Theme values to override for this call. |
+| `random:` | Source of random bytes for the module's `random_get` import, anything responding to `bytes(count)`. Default `Random`. |
+
+The accepted `theme_override` keys are pozeiden's `ThemeOverride` fields: `background`, `text_color`, `node_fill`, `node_stroke`, `edge_color`, `font_size`, `font_size_small`, and `font_family`.
+The first five and the last take a string, the two font sizes take an integer.
+Any other key raises `Dewasm::Pozeiden::Error` with `zig_error` `:UnknownField`; unknown keys are never ignored.
+
+Errors that pozeiden itself reports carry its Zig error name:
+
+```ruby
+begin
+  Dewasm::Pozeiden.render(source, strict: true)
+rescue Dewasm::Pozeiden::Error => e
+  e.zig_error   # => :UnknownDiagramType
+end
+```
+
+Input larger than 4 MiB raises `Dewasm::Pozeiden::Error` before the WebAssembly module is called.
+That is the size of the module's input buffer, chosen to match pozeiden's own `max_input_bytes` default.
+
+## API
+
+Every call instantiates the converted module, runs, and drops it.
+WebAssembly linear memory is not retained between calls, so no state carries over from one render to the next.
+
+| Ruby | pozeiden |
+| --- | --- |
+| `Dewasm::Pozeiden.render(text, **options)` | `renderWithOptions(allocator, text, RenderOptions)` |
+| `Dewasm::Pozeiden.render_with_metadata(text, **options)` | `renderWithMetadata(allocator, text, RenderOptions)` |
+| `Dewasm::Pozeiden.detect_diagram_type(text)` | `detectDiagramType(text)` |
+| `Dewasm::Pozeiden::RenderResult` | `RenderResult` |
+| `Dewasm::Pozeiden::Error#zig_error` | the `@errorName` of the returned error |
+| `Dewasm::Pozeiden::POZEIDEN_VERSION` | the pinned upstream revision |
+
+`Dewasm::Pozeiden.render` maps to `renderWithOptions` rather than to the two-argument `render`, because the options are always sent; the defaults are pozeiden's own, so `Dewasm::Pozeiden.render(text)` renders what `render(allocator, text)` renders.
+
+## How it is built
+
+`wasm/` is a self-contained Zig project: it depends on pozeiden pinned by commit in `wasm/build.zig.zon`, fetched by the Zig package manager into the gitignored `wasm/zig-pkg/`, and `wasm/src/shim.zig` is this project's own WebAssembly interface over pozeiden's public API, not upstream's playground shim.
+The module is built for `wasm32-wasi` in `ReleaseSmall`, single threaded, with the entry point disabled and `rdynamic` set, post-processed with `wasm-opt -Oz --enable-bulk-memory --enable-sign-ext --enable-nontrapping-float-to-int`, and converted to Ruby by dewasm at the revision recorded in `DEWASM_REVISION`.
+
+Neither build product is committed: `wasm/pozeiden.wasm` and `lib/dewasm/pozeiden/wasm_module.rb` are produced by the build, and the generated Ruby is shipped in the gem.
+
+## Size, memory, and speed
+
+<!-- measurements:begin -->
+Measured on macOS 26.5.2, Apple M1 Pro, Ruby 4.0.4.
+
+| Quantity | Value |
+| --- | --- |
+| `wasm/pozeiden.wasm` after `wasm-opt -Oz` | 479 KB |
+| Generated `wasm_module.rb` | 2.6 MB |
+| Packaged `.gem` | 366 KB |
+| `require "dewasm/pozeiden"` | 322 ms |
+| Resident memory after `require` | 126.9 MB |
+| `render`, flowchart | 3.6 ms |
+| `render`, pie chart | 38 ms |
+| `render_with_metadata`, flowchart | 3.1 ms |
+| `detect_diagram_type` | 0.3 ms |
+<!-- measurements:end -->
+
+The rows fall into three groups.
+The first ones are what ships: the WebAssembly module, the Ruby source dewasm generates from it, and the packaged gem.
+The next two are the one-time cost of loading that source, in time and in resident memory.
+The rest are per-call costs, one call of each function on a small diagram.
+
+Three facts hold whatever the magnitudes are.
+Resident memory after `require` is dominated by the instruction sequences of the loaded code, not by rendering, so it is paid once and does not grow with the number of calls.
+Each call allocates the module's linear memory, which holds the 4 MiB input buffer, the 8 MiB scratch arena, and the 4 MiB output buffer, and drops it when the call returns.
+Rendering is deterministic: two renders of the same source produce byte-identical SVGs, both with the default random source and with a fixed one.
+
+The numbers move with the pinned pozeiden commit and with the dewasm revision used to generate the module, so rerun `rake measure` after changing either.
+
+## Tasks
+
+The Rakefile drives everything.
+`rake generate` does not build the WebAssembly module itself, so a clean checkout runs `rake wasm:build` first; from there `rake test` runs what it needs.
+
+### `rake wasm:build`
+
+```console
+$ rake wasm:build
+```
+
+Builds `wasm/` with `zig build` and post-processes it into `wasm/pozeiden.wasm` with `wasm-opt -Oz`.
+It needs Zig 0.16 and `wasm-opt` from Binaryen.
+
+### `rake generate`
+
+```console
+$ rake generate
+```
+
+Converts that module into the Ruby the gem ships.
+It needs `wasm/pozeiden.wasm`, and a dewasm binary, its path in `DEWASM_BIN`.
+
+### `rake test`
+
+```console
+$ rake test
+```
+
+Runs `test/` against the generated module.
+It needs `rake generate`.
+
+### `rake measure`
+
+```console
+$ rake measure
+```
+
+Refreshes the measurements table in `README.md` with numbers from this machine.
+It needs `rake generate`, and a built gem in the checkout for the `.gem` row.
+
+### `rake build`
+
+```console
+$ rake build
+```
+
+Packages the gem.
+It needs `rake generate`.
+
+### `rake clean`
+
+```console
+$ rake clean
+```
+
+Removes the build products, `wasm/zig-out`, and `wasm/.zig-cache`.
+It needs nothing.
+
+## License
+
+The code in this repository (the shim, the wrapper, the tools, and the tests) is Copyright (c) 2026 Hiroya Fujinami, under the [MIT License](LICENSE).
+
+The generated `wasm_module.rb` derives from pozeiden and stays under the [PolyForm Noncommercial License 1.0.0](LICENSE-POZEIDEN), whose required notice is preserved there: Copyright © 2025 Star City Security Consulting, LLC (SC2).
+Every render runs that module, so use of the gem as a whole is bound by the noncommercial restriction.

data/lib/dewasm/pozeiden/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Dewasm
+  module Pozeiden
+    VERSION = "0.1.0"
+
+    # The pozeiden revision this gem's WebAssembly module was built from.
+    POZEIDEN_VERSION = "0.4.1 (071fbbb85fb73a06994c163c6093123bd3ac11f6)"
+  end
+end