wesc 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65b91a95acd3078a53de01dd1a5f73f99d0057c2bebffbdcc1340ca0c4195252
+  data.tar.gz: 109ceeea27a5f686e59a9d121af8974bd9e296b0b8be0af2e9a058dc9eb69290
+SHA512:
+  metadata.gz: d4e239e1c836bece4d89fb23cd76caa418865df89fff7bdc091aa65f0c2790b615f68de025d5aea05f5c0018f33cc04860c15fb33e7dd6e3b0d8c9bbdae70671
+  data.tar.gz: 662b9ee4e0ed332b9b638b39f2854eb2ad0c810764b44e13401e4da93d7485fa76bebc9f4867ddd0c063a234dc4422d0062e285b5090c04f2428b5a5ab5677f6

data/README.md

@@ -0,0 +1,94 @@
+# wesc (Ruby)
+
+Ruby bindings for [`wesc`](https://github.com/luwes/wesc)'s streaming
+HTML/web-component bundler. The Rust core runs in-process via a native extension
+— no subprocess, no WASM — so you can build and server-render web components
+straight from a Ruby backend (Rack, Sinatra, Rails, plain WEBrick, …).
+
+The extension is built with [Magnus](https://github.com/matsadler/magnus) on top
+of [rb-sys](https://github.com/oxidize-rb/rb-sys), the same way the Node, Python,
+and PHP bindings use napi-rs / PyO3 / ext-php-rs. The native module
+(`Wesc::Native`, [`ext/wesc/src/lib.rs`](./ext/wesc/src/lib.rs)) is wrapped by a thin pure-Ruby
+layer ([`lib/wesc.rb`](./lib/wesc.rb)) that exposes the idiomatic
+keyword-argument API.
+
+```sh
+gem install wesc
+```
+
+## Usage
+
+```ruby
+require "wesc"
+
+# One-shot: returns the full HTML output as a (binary) String.
+html = Wesc.build(["./index.html"], minify: true)
+puts "#{html.bytesize} bytes"
+
+# Streaming: low memory, chunk by chunk. The block receives each chunk as a
+# String, then `nil` once to signal end-of-stream. Raising from the block
+# stops the build.
+Wesc.build_stream(["./index.html"]) do |chunk|
+  io.write(chunk) unless chunk.nil?
+end
+```
+
+## API
+
+- `Wesc.build(entry_points, outcss: nil, outjs: nil, minify: false) -> String`
+- `Wesc.build_stream(entry_points, outcss: nil, outjs: nil, minify: false) { |chunk| ... } -> nil`
+
+| Argument       | Type                  | Notes                                              |
+| -------------- | --------------------- | -------------------------------------------------- |
+| `entry_points` | `Array<String>`       | First entry is the host document.                  |
+| `outcss`       | `String, nil`         | Path to write the bundled CSS file. `nil` skips.   |
+| `outjs`        | `String, nil`         | Path to write the bundled JS file. `nil` skips.    |
+| `minify`       | `Boolean`             | Minify generated assets. Defaults to `false`.      |
+| `&block`       | `{ \|String, nil\| }` | `build_stream` only. Gets each chunk, then `nil`.  |
+
+`build` returns a binary (`ASCII-8BIT`) `String`. `build_stream` yields each
+chunk as a binary `String`, then yields `nil` once to mark end-of-stream — the
+same trailing-`nil`/`None` convention as the Python and PHP bindings.
+
+> The bundler keeps a process-global file/template cache, so builds should not
+> run concurrently within a single process — serialize them (the
+> [`examples/ruby-server`](https://github.com/luwes/wesc/tree/main/examples/ruby-server)
+> demo does exactly this with a `Mutex`).
+
+## Building from source
+
+This is an rb-sys gem. From this directory:
+
+```sh
+bundle install
+bundle exec rake compile    # build the native extension into lib/wesc/
+bundle exec rake test       # compile (if needed) + run the test suite
+bundle exec rake build      # package the gem into pkg/
+```
+
+`rake compile` runs `cargo` under the hood, so the prerequisites are:
+
+- The [Rust toolchain](https://rustup.rs) (the repo pins a version via
+  `rust-toolchain.toml`).
+- Ruby 3.0+ with development headers.
+- A C toolchain and `libclang` for bindgen (Xcode Command Line Tools on macOS;
+  `build-essential` + `libclang-dev` on Linux).
+
+`rake compile` is the canonical build: rb-sys drives `cargo` and passes the
+Ruby-specific linker flags (on macOS, `-Wl,-undefined,dynamic_lookup`) a loadable
+extension needs, since the Ruby symbols are resolved by the host process at
+load time.
+
+The crate (at [`ext/wesc`](./ext/wesc)) is also a member of the repo's Cargo
+workspace, so `cargo check -p wesc-rb` typechecks it against the active Ruby on
+your `PATH`. It's excluded from the workspace's `default-members`, so a bare
+`cargo build` at the root won't try to build it (it needs Ruby headers +
+libclang, and a plain `cargo build -p wesc-rb` won't *link* standalone — that's
+what `rake compile` is for).
+
+> Tip: with [rbenv](https://github.com/rbenv/rbenv) the bundled
+> [`.ruby-version`](./.ruby-version) selects a Ruby 3 toolchain automatically in
+> this directory.
+
+See the repo README's [Ruby section](../../README.md) for the broader project
+and `crates/wesc-rb/ext/wesc/src/lib.rs` for the binding source.

data/ext/wesc/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "wesc-rb"
+version = "0.6.2" # x-release-please-version
+authors = ["Wesley Luyten <me@wesleyluyten.com>"]
+edition = "2021"
+license = "MIT"
+description = "Ruby bindings for the wesc web component bundler"
+repository = "https://github.com/luwes/wesc"
+publish = false
+
+[lib]
+# The cdylib is loaded by Ruby as a native extension (`require "wesc/wesc_rb"`).
+# The lib name drives the extension's `Init_wesc_rb` symbol and the built
+# `libwesc_rb` artifact, so it must stay in sync with the
+# `#[magnus::init(name = "wesc_rb")]` in src/lib.rs and the
+# `create_rust_makefile("wesc/wesc_rb")` call in extconf.rb. It deliberately
+# differs from the core crate's `wesc` lib name so rb-sys's `cargo metadata`
+# lookup resolves this crate and not the bundler core.
+name = "wesc_rb"
+crate-type = ["cdylib"]
+
+[dependencies]
+# Depend on the published bundler core by version so the gem is self-contained
+# when built outside the repo (cross-compiled release gems and `gem install`
+# from source both fetch it from crates.io). Inside this monorepo the root
+# Cargo.toml's `[patch.crates-io]` redirects it to the local crates/wesc, so
+# `rake compile` builds against the in-tree core. This requirement must track
+# the core crate's version (the marker keeps release-please bumping it in
+# lockstep); otherwise the patched local 0.x core fails to satisfy it and the
+# whole workspace stops resolving.
+wesc = "0.6.2" # x-release-please-version
+magnus = "0.7"

data/ext/wesc/extconf.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Build the native extension with rb-sys (cargo under the hood).
+#
+# The crate's Cargo.toml lives alongside this file (ext/wesc/), so rb-sys builds
+# the local `wesc_rb` cdylib and installs it as `wesc/wesc_rb.{so,bundle}` —
+# which lib/wesc.rb loads with `require_relative "wesc/wesc_rb"`.
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("wesc/wesc_rb")

data/ext/wesc/src/lib.rs

@@ -0,0 +1,116 @@
+#![deny(clippy::all)]
+
+//! Ruby bindings for `wesc`.
+//!
+//! Exposes the streaming web-component bundler to Ruby via [Magnus](https://github.com/matsadler/magnus)
+//! (on top of [rb-sys](https://github.com/oxidize-rb/rb-sys)) so it can run
+//! in-process on a Ruby server — no subprocess, no WASM.
+//!
+//! These are the *native* entry points. They live under the `Wesc::Native`
+//! module and take plain positional arguments; the thin pure-Ruby wrapper in
+//! `lib/wesc.rb` re-exposes them as `Wesc.build` / `Wesc.build_stream` with
+//! idiomatic keyword arguments (mirroring the Python package's native module +
+//! wrapper split).
+//!
+//! Two entry points, matching how a server typically consumes a build:
+//! - [`build`]        — returns the full output as a (binary) `String`.
+//! - [`build_stream`] — yields each chunk to the block (low memory). The block
+//!   runs in Ruby, then receives `nil` once to signal end-of-stream.
+//!
+//! Magnus guards the FFI boundary: a Rust panic is caught and re-raised as a
+//! Ruby exception rather than unwinding into the VM (which would be undefined
+//! behavior), and a Ruby exception raised by the block surfaces back to the
+//! caller as a normal `Result::Err`.
+//!
+//! Note: the underlying bundler keeps a process-global file/template cache, so
+//! builds should not run concurrently within a single process — serialize them
+//! (the streaming server example does exactly this).
+
+use magnus::{function, prelude::*, Error, RString, Ruby, Value};
+use wesc::{build as wesc_build, BuildOptions};
+
+/// Assemble [`BuildOptions`] from the native (positional) arguments.
+fn collect_options(
+    entry_points: Vec<String>,
+    outcss: Option<String>,
+    outjs: Option<String>,
+    minify: bool,
+) -> BuildOptions {
+    BuildOptions {
+        entry_points,
+        outcss,
+        outjs,
+        minify,
+    }
+}
+
+/// Build the entry points and return the full HTML output as a binary `String`.
+///
+/// Exposed to Ruby as `Wesc::Native.build`; see `Wesc.build` in `lib/wesc.rb`
+/// for the public keyword-argument API.
+fn build(
+    ruby: &Ruby,
+    entry_points: Vec<String>,
+    outcss: Option<String>,
+    outjs: Option<String>,
+    minify: bool,
+) -> RString {
+    let options = collect_options(entry_points, outcss, outjs, minify);
+
+    let mut output: Vec<u8> = Vec::new();
+    wesc_build(options, &mut |chunk: &[u8]| {
+        output.extend_from_slice(chunk);
+    });
+
+    ruby.str_from_slice(&output)
+}
+
+/// Stream the build to the block, chunk by chunk, for low-memory output.
+///
+/// The block is called once per output chunk with the chunk as a binary
+/// `String`, then once with `nil` to signal the end of the stream. If the block
+/// raises, no further chunks are delivered and the exception propagates out.
+///
+/// Exposed to Ruby as `Wesc::Native.build_stream`; see `Wesc.build_stream` in
+/// `lib/wesc.rb` for the public keyword-argument API.
+fn build_stream(
+    ruby: &Ruby,
+    entry_points: Vec<String>,
+    outcss: Option<String>,
+    outjs: Option<String>,
+    minify: bool,
+) -> Result<(), Error> {
+    let block = ruby.block_proc()?;
+    let options = collect_options(entry_points, outcss, outjs, minify);
+
+    // Remember the first block error so we can stop yielding and surface it.
+    let mut pending_error: Option<Error> = None;
+    wesc_build(options, &mut |chunk: &[u8]| {
+        if pending_error.is_some() {
+            return;
+        }
+        let bytes = ruby.str_from_slice(chunk);
+        if let Err(err) = block.call::<_, Value>((bytes,)) {
+            pending_error = Some(err);
+        }
+    });
+
+    if let Some(err) = pending_error {
+        return Err(err);
+    }
+
+    // Signal end-of-stream.
+    block.call::<_, Value>((ruby.qnil(),))?;
+    Ok(())
+}
+
+/// Initialize the native extension: define `Wesc::Native` and its module
+/// functions. The pure-Ruby `Wesc` wrapper (lib/wesc.rb) builds on these.
+#[magnus::init(name = "wesc_rb")]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Wesc")?;
+    let native = module.define_module("Native")?;
+    native.define_singleton_method("build", function!(build, 4))?;
+    native.define_singleton_method("build_stream", function!(build_stream, 4))?;
+    Ok(())
+}

data/lib/wesc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wesc
+  VERSION = "0.6.2"
+end

data/lib/wesc.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# WeSC — We are the Superlative Components.
+#
+# A streaming HTML / web-component bundler. This gem exposes the Rust core (via
+# a native extension) so it can run in-process on a Ruby server — no subprocess,
+# no WASM.
+#
+#   require "wesc"
+#
+#   # One-shot: returns the full HTML output as a (binary) String.
+#   html = Wesc.build(["./index.html"], minify: true)
+#
+#   # Streaming: low memory, chunk by chunk. The block gets each chunk as a
+#   # String, then `nil` once to signal end-of-stream.
+#   Wesc.build_stream(["./index.html"]) { |chunk| ... }
+#
+# See https://github.com/luwes/wesc for the full documentation.
+
+require_relative "wesc/version"
+# The native extension (defines Wesc::Native). Built from crates/wesc-rb via
+# rb-sys; see the gem's Rakefile (`rake compile`).
+require_relative "wesc/wesc_rb"
+
+module Wesc
+  module_function
+
+  # Build the entry points and return the full HTML output as a (binary) String.
+  #
+  #   html = Wesc.build(["./index.html"], minify: true)
+  #
+  # @param entry_points [Array<String>] entry point paths; the first is the host
+  #   document.
+  # @param outcss [String, nil] optional path to write the bundled CSS file.
+  # @param outjs [String, nil] optional path to write the bundled JS file.
+  # @param minify [Boolean] minify generated JS/CSS assets. Defaults to false.
+  # @return [String] the rendered HTML (ASCII-8BIT / binary encoding).
+  def build(entry_points, outcss: nil, outjs: nil, minify: false)
+    Native.build(Array(entry_points), outcss, outjs, minify ? true : false)
+  end
+
+  # Stream the build to a block, chunk by chunk, for low-memory output.
+  #
+  # The block is called with each chunk as a String, then once with `nil` to
+  # signal the end of the stream. Raising from the block stops the build and the
+  # exception propagates out of this method.
+  #
+  #   Wesc.build_stream(["./index.html"]) do |chunk|
+  #     io.write(chunk) unless chunk.nil?
+  #   end
+  #
+  # @param entry_points [Array<String>] entry point paths; the first is the host
+  #   document.
+  # @param outcss [String, nil] optional path to write the bundled CSS file.
+  # @param outjs [String, nil] optional path to write the bundled JS file.
+  # @param minify [Boolean] minify generated JS/CSS assets. Defaults to false.
+  # @yieldparam chunk [String, nil] each output chunk, then `nil` at end-of-stream.
+  # @return [void]
+  def build_stream(entry_points, outcss: nil, outjs: nil, minify: false, &block)
+    raise ArgumentError, "Wesc.build_stream requires a block" unless block
+
+    Native.build_stream(Array(entry_points), outcss, outjs, minify ? true : false, &block)
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: wesc
+version: !ruby/object:Gem::Version
+  version: 0.6.2
+platform: ruby
+authors:
+- Wesley Luyten
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Ruby bindings for wesc's streaming HTML/web-component bundler. The Rust
+  core runs in-process via a native extension — no subprocess, no WASM.
+email:
+- me@wesleyluyten.com
+executables: []
+extensions:
+- ext/wesc/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/wesc/Cargo.toml
+- ext/wesc/extconf.rb
+- ext/wesc/src/lib.rs
+- lib/wesc.rb
+- lib/wesc/version.rb
+homepage: https://github.com/luwes/wesc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/luwes/wesc
+  source_code_uri: https://github.com/luwes/wesc
+  changelog_uri: https://github.com/luwes/wesc/blob/main/CHANGELOG.md
+  cargo_crate_name: wesc-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: We are the Superlative Components! — a streaming HTML/web-component bundler.
+test_files: []