lightningcss 0.1.0-aarch64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68cc2374c2bb0eea54e1a30712d302a560a6f731cdc56012058dff3b62b07413
+  data.tar.gz: fb5c3908ffb991bb51ae27b3c888ca8d1214c57dcd50127eeb3e94e6c6f6785c
+SHA512:
+  metadata.gz: 4301d8b631775d46c9f167adca5b5668fb6e35d1ccee9473ad9396a1870d696e5eb08226fbba20fbfd3504e5816ed006a4ea76502fb0ea0accd30057bae3d6a1
+  data.tar.gz: 6d10fe592139616f30fe5477e1cc0db8f8d892726c5cac0a2de1e9881bc55f99f4a61042f581bb2c4c37722d671c6c716010b21dd2e7bdb9d7f267df0dbd180a

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Marco Roth
+
+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/README.md

@@ -0,0 +1,231 @@
+<h2 align="center">⚡ Lightning CSS for Ruby</h2>
+
+<h4 align="center">An extremely fast CSS parser, transformer, bundler, and minifier.</h4>
+
+<div align="center">Ruby bindings for <a href="https://lightningcss.dev">Lightning CSS</a>, the CSS toolchain written in Rust.</div><br/>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/lightningcss"><img alt="Gem Version" src="https://img.shields.io/gem/v/lightningcss"></a>
+  <a href="https://lightningcss.dev"><img alt="Documentation" src="https://img.shields.io/badge/lightningcss.dev-documentation-green"></a>
+  <a href="https://github.com/marcoroth/lightningcss-ruby/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/github/license/marcoroth/lightningcss-ruby"></a>
+  <a href="https://github.com/marcoroth/lightningcss-ruby/issues"><img alt="Issues" src="https://img.shields.io/github/issues/marcoroth/lightningcss-ruby"></a>
+</p>
+
+<br/>
+
+### What is Lightning CSS for Ruby?
+
+Ruby bindings for [Lightning CSS](https://lightningcss.dev), an extremely fast CSS parser, transformer, bundler, and minifier written in Rust.
+
+Everything here is Lightning CSS doing the work. For what the options mean and what it can do, [lightningcss.dev](https://lightningcss.dev) is the reference.
+
+### Installation
+
+```bash
+bundle add lightningcss
+```
+
+Precompiled gems are published for Linux (gnu and musl) and macOS, on x86_64, aarch64, and arm. On those platforms nothing is compiled at install time. Anywhere else the gem builds from source and needs the [Rust toolchain](https://rustup.rs).
+
+### Usage
+
+#### Transforming
+
+```ruby
+LightningCSS.transform(".a { color: #ff0000 }", minify: true).code
+#=> ".a{color:red}"
+```
+
+#### Minifying
+
+`minify` answers the code directly, for when the rest of the result is not interesting.
+
+```ruby
+LightningCSS.minify(".a { color: #ff0000 }")
+#=> ".a{color:red}"
+```
+
+#### Targeting browsers
+
+Give the browsers you support, each as its major version. Anything they cannot read is lowered, with the original kept after it so that a browser which understands it still wins.
+
+```ruby
+LightningCSS.transform(".a { color: lab(50% 40 59) }", targets: { chrome: 80 }, minify: true).code
+#=> ".a{color:#bf5702;color:lab(50% 40 59)}"
+```
+
+#### Bundling
+
+`bundle` resolves the `@import` statements a stylesheet was written with by reading the files they name, so it takes a path on disk to the entry stylesheet.
+
+```ruby
+LightningCSS.bundle("app/assets/stylesheets/application.css", minify: true).code
+```
+
+#### CSS modules
+
+Compiling as a CSS module renames every class, id, `@keyframes`, and custom identifier, and reports what each name became.
+
+```ruby
+result = LightningCSS.transform(".card { color: red }", css_modules: true, minify: true)
+
+result.code
+#=> "._8Z4fiW_card{color:red}"
+
+result.exports
+#=> {"card" => "_8Z4fiW_card"}
+```
+
+Pass a hash instead of `true` to say how:
+
+```ruby
+LightningCSS.transform(".card {}", css_modules: { pattern: "scoped-[local]" }).exports
+#=> {"card" => "scoped-card"}
+```
+
+#### Scoping
+
+`scope` narrows every rule by a selector fragment, so a stylesheet only applies where that fragment matches. The fragment lands on the last compound of each selector, which is where a scope belongs.
+
+```ruby
+LightningCSS.transform(".card .title { color: red }", scope: "[data-scope-abc]", minify: true).code
+#=> ".card .title[data-scope-abc]{color:red}"
+```
+
+Any single selector works as a fragment, so one carrying its own alternatives is fine:
+
+```ruby
+LightningCSS.transform(".title { color: red }", scope: ":where([s], [s] *)", minify: true).code
+#=> ".title:where([s],[s] *){color:red}"
+```
+
+Keyframe selectors are left alone, and so is the inside of a functional pseudo class:
+
+```ruby
+LightningCSS.transform(".x:not(.y) { color: red }", scope: "[s]", minify: true).code
+#=> ".x:not(.y)[s]{color:red}"
+```
+
+#### Style attributes
+
+A style attribute is the list of declarations an element carries inline. It has no selectors and no at-rules around it, so it is its own grammar.
+
+```ruby
+LightningCSS.transform_style_attribute("color: #ff0000; border: none", minify: true).code
+#=> "color:red;border:none"
+```
+
+Having no selectors and no names, it takes neither `scope` nor `css_modules`, and says so when given one.
+
+#### Reusing options
+
+`LightningCSS::Transformer` holds a set of options to use across many stylesheets. Options given to a call are merged over the ones it was built with.
+
+```ruby
+transformer = LightningCSS::Transformer.new(minify: true, targets: { chrome: 100 })
+
+transformer.transform(".a { color: red }").code
+transformer.transform(css, scope: "[data-scope-abc]").code
+transformer.with(scope: "[s]")
+```
+
+It answers `call` as well, so it can be handed to anything expecting something callable.
+
+### Options
+
+| Option           | Type           | Description                                                                            |
+|------------------|----------------|----------------------------------------------------------------------------------------|
+| `filename`       | `String`       | The name to use in errors and warnings.                                                |
+| `minify`         | `bool`         | Whether to print the result as small as it goes.                                       |
+| `error_recovery` | `bool`         | Whether to carry on past a rule it cannot read. Off by default, so such a rule raises. |
+| `targets`        | `Hash`         | The browsers being compiled for, each as its major version.                            |
+| `css_modules`    | `bool`, `Hash` | Whether to compile as a CSS module, and how.                                           |
+| `scope`          | `String`       | A selector fragment to narrow every rule by.                                           |
+
+An option nobody reads is refused:
+
+```ruby
+LightningCSS.transform(".a {}", nonsense: true)
+#=> LightningCSS::OptionError: Unknown option: nonsense
+```
+
+### Results
+
+`transform`, `bundle`, and `transform_style_attribute` all answer a `LightningCSS::Result`.
+
+```ruby
+result = LightningCSS.transform(".a { color: #ff0000 }", minify: true)
+
+result.code
+#=> ".a{color:red}"
+
+result.to_s
+#=> ".a{color:red}"
+
+result.exports
+#=> nil
+
+result.warnings
+#=> []
+
+result.warnings?
+#=> false
+```
+
+`exports` is filled in when the stylesheet was compiled as a CSS module, and maps every name as it was written to the name it was compiled to:
+
+```ruby
+result = LightningCSS.transform(".card { color: red }", css_modules: true, minify: true)
+
+result.code
+#=> "._8Z4fiW_card{color:red}"
+
+result.exports
+#=> {"card" => "_8Z4fiW_card"}
+```
+
+`warnings` holds what Lightning CSS understood well enough to keep but not well enough to act on. They are worth reading, because what they describe is kept as written and then does nothing:
+
+```ruby
+result = LightningCSS.transform(".a:deep(.b) { color: red }", minify: true)
+
+result.warnings?
+#=> true
+
+result.warnings.first
+#=> "'deep' is not recognized as a valid pseudo-class. Did you mean '::deep' (pseudo-element) or is this a typo? at :0:9"
+
+result.code
+#=> ".a:deep(.b){color:red}"
+```
+
+### Development
+
+The gem is a C extension over a Rust crate. `rust/` builds a static library and generates the C header with [cbindgen](https://github.com/mozilla/cbindgen), `ext/lightningcss/` wraps it, and `lib/` is the Ruby API over that.
+
+```bash
+bin/setup
+bundle exec rake
+```
+
+`sig/` is generated from the `#:` annotations next to the code. Regenerate it with `rake rbs` after changing a signature, and CI checks that it matches.
+
+### Acknowledgements
+
+[Lightning CSS](https://lightningcss.dev) is written by [Devon Govett](https://github.com/devongovett) and maintained at [parcel-bundler/lightningcss](https://github.com/parcel-bundler/lightningcss). This gem only calls into it. Every CSS feature, browser target, and optimization comes from there.
+
+Its selector engine, [`parcel_selectors`](https://github.com/parcel-bundler/lightningcss/tree/master/selectors), is a fork of the selector matching from [Servo](https://servo.org), by the Servo Project Developers.
+
+Thank you to all of them.
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/lightningcss-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/marcoroth/lightningcss-ruby/blob/main/CODE_OF_CONDUCT.md).
+
+Issues with CSS parsing, transforming, or minifying itself belong [upstream](https://github.com/parcel-bundler/lightningcss/issues), since this gem does none of that. Issues with the Ruby API, the build, or the bindings belong here.
+
+### License
+
+The Ruby, C, and Rust code in this gem is available under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+It builds against [Lightning CSS](https://github.com/parcel-bundler/lightningcss), which is licensed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/), and the native extension a precompiled gem ships has that code compiled into it. MPL-2.0 is a file-level copyleft license, so the source of the MPL-covered files stays available under the MPL. The upstream [LICENSE](https://github.com/parcel-bundler/lightningcss/blob/master/LICENSE) has the terms, and a copy travels with the gem in [`licenses/`](licenses) so that whoever received it has them in hand.

data/ext/lightningcss/extconf.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "fileutils"
+
+ext_dir = __dir__
+root_dir = File.expand_path("../..", ext_dir)
+
+rust_dir = File.join(root_dir, "rust")
+
+unless File.exist?(File.join(rust_dir, "Cargo.toml"))
+  abort <<~MESSAGE
+
+    ERROR: Rust sources not found at #{rust_dir}.
+
+  MESSAGE
+end
+
+unless system("cargo --version > /dev/null 2>&1")
+  abort <<~MESSAGE
+
+    ERROR: Rust toolchain not found.
+
+    lightningcss requires the Rust toolchain to compile from source.
+
+    Install Rust: https://rustup.rs
+
+  MESSAGE
+end
+
+RUST_TARGETS = {
+  "aarch64-linux-gnu" => "aarch64-unknown-linux-gnu",
+  "aarch64-linux-musl" => "aarch64-unknown-linux-musl",
+  "arm-linux-gnu" => "armv7-unknown-linux-gnueabihf",
+  "arm-linux-musl" => "armv7-unknown-linux-musleabihf",
+  "arm64-darwin" => "aarch64-apple-darwin",
+  "x86_64-darwin" => "x86_64-apple-darwin",
+  "x86_64-linux-gnu" => "x86_64-unknown-linux-gnu",
+  "x86_64-linux-musl" => "x86_64-unknown-linux-musl",
+  "x86-linux-gnu" => "i686-unknown-linux-gnu",
+  "x86-linux-musl" => "i686-unknown-linux-musl",
+}.freeze
+
+cross_compiling = ENV.key?("RUBY_CC_VERSION")
+target_platform = ENV.fetch("CARGO_BUILD_TARGET", nil)
+
+if cross_compiling && target_platform.nil?
+  rcd_platform = ENV.fetch("RCD_PLATFORM", "")
+  target_platform = RUST_TARGETS[rcd_platform]
+
+  if target_platform.nil?
+    ruby_platform = RbConfig::CONFIG["arch"]
+    target_platform = RUST_TARGETS.values.find { |target| ruby_platform.include?(target.split("-").first) }
+  end
+end
+
+header_path = File.join(ext_dir, "include", "lightningcss.h")
+
+FileUtils.mkdir_p(File.dirname(header_path))
+
+target_dir = File.join(rust_dir, "target")
+
+if target_platform
+  puts "lightningcss: Cross-compiling Rust for target: #{target_platform}"
+
+  system("rustup target add #{target_platform}") || warn("lightningcss: Failed to add Rust target #{target_platform}")
+
+  cargo_args = "--release --target #{target_platform}"
+  lib_dir = File.join(target_dir, target_platform, "release")
+else
+  puts "lightningcss: Compiling Rust library for native platform..."
+
+  cargo_args = "--release"
+  lib_dir = File.join(target_dir, "release")
+end
+
+unless system("cd #{rust_dir} && cargo build #{cargo_args}")
+  abort "ERROR: Failed to compile lightningcss from Rust source."
+end
+
+unless File.exist?(header_path)
+  abort "ERROR: cbindgen did not generate #{header_path}. Try `cargo clean` in #{rust_dir} and reinstall."
+end
+
+static_lib = File.join(lib_dir, "liblightningcss_ffi.a")
+
+if File.exist?(static_lib)
+  puts "lightningcss: Static library found at #{static_lib}"
+
+  $LDFLAGS << " #{static_lib}"
+else
+  host_os = target_platform || RbConfig::CONFIG["host_os"]
+
+  lib_name = case host_os
+             when /darwin/ then "liblightningcss_ffi.dylib"
+             when /mingw|mswin|windows/ then "lightningcss_ffi.dll"
+             else "liblightningcss_ffi.so"
+             end
+
+  lib_path = File.join(lib_dir, lib_name)
+
+  abort "ERROR: Shared library not found at #{lib_path}" unless File.exist?(lib_path)
+
+  puts "lightningcss: Shared library found at #{lib_path} (dynamic)"
+
+  $LDFLAGS << " -L#{lib_dir} -llightningcss_ffi"
+  $LDFLAGS << " -Wl,-rpath,#{lib_dir}" if RbConfig::CONFIG["host_os"].match?(/darwin|linux/)
+end
+
+$CFLAGS << " -I#{ext_dir}"
+
+create_makefile("lightningcss/lightningcss")

data/ext/lightningcss/include/lightningcss.h

@@ -0,0 +1,28 @@
+/* Generated by cbindgen — do not edit manually */
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>
+
+#ifndef LIGHTNINGCSS_H
+#define LIGHTNINGCSS_H
+
+typedef struct LightningCssResult {
+  char *value;
+  char *error;
+} LightningCssResult;
+
+struct LightningCssResult lightningcss_transform(const char *code, const char *options_json);
+
+struct LightningCssResult lightningcss_transform_style_attribute(const char *code,
+                                                                 const char *options_json);
+
+struct LightningCssResult lightningcss_bundle(const char *path, const char *options_json);
+
+char *lightningcss_version(void);
+
+void lightningcss_string_free(char *value);
+
+void lightningcss_result_free(struct LightningCssResult result);
+
+#endif  /* LIGHTNINGCSS_H */

data/ext/lightningcss/lightningcss.c

@@ -0,0 +1,101 @@
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include "include/lightningcss.h"
+
+static VALUE rb_mLightningCSS;
+static VALUE rb_mBackend;
+static VALUE rb_eError;
+static VALUE rb_eParseError;
+static VALUE rb_eOptionError;
+static VALUE rb_eBundleError;
+
+static VALUE make_utf8_string(const char *cstring) {
+  return rb_enc_str_new_cstr(cstring, rb_utf8_encoding());
+}
+
+static VALUE take_utf8_string(char *cstring) {
+  if (!cstring) return Qnil;
+
+  VALUE string = make_utf8_string(cstring);
+  lightningcss_string_free(cstring);
+
+  return string;
+}
+
+static VALUE error_class_for(const char *message) {
+  if (strstr(message, "Invalid options") || strstr(message, "Invalid CSS modules pattern")) {
+    return rb_eOptionError;
+  }
+
+  if (strstr(message, "os error") || strstr(message, "No such file")) {
+    return rb_eBundleError;
+  }
+
+  if (strstr(message, "Invalid scope selector") || strstr(message, "Scope selector")) {
+    return rb_eOptionError;
+  }
+
+  return rb_eParseError;
+}
+
+static VALUE unwrap(struct LightningCssResult result) {
+  if (result.error) {
+    VALUE message = make_utf8_string(result.error);
+    VALUE error_class = error_class_for(result.error);
+
+    lightningcss_result_free(result);
+
+    rb_raise(error_class, "%s", StringValueCStr(message));
+  }
+
+  if (!result.value) {
+    lightningcss_result_free(result);
+
+    rb_raise(rb_eError, "Lightning CSS returned no result");
+  }
+
+  VALUE value = make_utf8_string(result.value);
+
+  lightningcss_result_free(result);
+
+  return value;
+}
+
+static VALUE rb_transform(VALUE self, VALUE code, VALUE options) {
+  (void) self;
+
+  return unwrap(lightningcss_transform(StringValueCStr(code), StringValueCStr(options)));
+}
+
+static VALUE rb_transform_style_attribute(VALUE self, VALUE code, VALUE options) {
+  (void) self;
+
+  return unwrap(lightningcss_transform_style_attribute(StringValueCStr(code), StringValueCStr(options)));
+}
+
+static VALUE rb_bundle(VALUE self, VALUE path, VALUE options) {
+  (void) self;
+
+  return unwrap(lightningcss_bundle(StringValueCStr(path), StringValueCStr(options)));
+}
+
+static VALUE rb_native_version(VALUE self) {
+  (void) self;
+
+  return take_utf8_string(lightningcss_version());
+}
+
+void Init_lightningcss(void) {
+  rb_mLightningCSS = rb_define_module("LightningCSS");
+  rb_mBackend = rb_define_module_under(rb_mLightningCSS, "Backend");
+
+  rb_eError = rb_define_class_under(rb_mLightningCSS, "Error", rb_eStandardError);
+  rb_eParseError = rb_define_class_under(rb_mLightningCSS, "ParseError", rb_eError);
+  rb_eOptionError = rb_define_class_under(rb_mLightningCSS, "OptionError", rb_eError);
+  rb_eBundleError = rb_define_class_under(rb_mLightningCSS, "BundleError", rb_eError);
+
+  rb_define_singleton_method(rb_mBackend, "transform", rb_transform, 2);
+  rb_define_singleton_method(rb_mBackend, "transform_style_attribute", rb_transform_style_attribute, 2);
+  rb_define_singleton_method(rb_mBackend, "bundle", rb_bundle, 2);
+  rb_define_singleton_method(rb_mBackend, "version", rb_native_version, 0);
+}

data/lib/lightningcss/backend.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LightningCSS
+  module Backend
+    module Unavailable
+      #: (String, String) -> String
+      def transform(_code, _options_json)
+        unavailable(__method__)
+      end
+
+      #: (String, String) -> String
+      def transform_style_attribute(_code, _options_json)
+        unavailable(__method__)
+      end
+
+      #: (String, String) -> String
+      def bundle(_path, _options_json)
+        unavailable(__method__)
+      end
+
+      #: () -> String
+      def version
+        unavailable(__method__)
+      end
+
+      private
+
+      #: (Symbol?) -> bot
+      def unavailable(name)
+        raise NotImplementedError, "LightningCSS::Backend.#{name} is defined by the native extension, which did not load"
+      end
+    end
+
+    extend Unavailable
+  end
+end

data/lib/lightningcss/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LightningCSS
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class OptionError < Error; end
+  class BundleError < Error; end
+end

data/lib/lightningcss/options.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module LightningCSS
+  # The options a call was given, on their way to the native library.
+  #
+  # Lightning CSS reads them as JSON, so this is where a Ruby hash becomes one, and where an option
+  # nobody knows is refused. Refusing early is the point: an option the native side does not read
+  # would otherwise be accepted and quietly do nothing.
+  #
+  #     LightningCSS::Options.new(minify: true).to_json  #=> "{\"minify\":true}"
+  #
+  class Options
+    KNOWN = [
+      :filename,
+      :minify,
+      :error_recovery,
+      :targets,
+      :css_modules,
+      :scope
+    ].freeze #: Array[Symbol]
+
+    STYLE_ATTRIBUTE = [
+      :filename,
+      :minify,
+      :error_recovery,
+      :targets
+    ].freeze #: Array[Symbol]
+
+    attr_reader :to_h #: Hash[Symbol, untyped]
+
+    #: (Hash[Symbol, untyped], ?allowed: Array[Symbol], ?subject: String) -> String
+    def self.serialize(options, allowed: KNOWN, subject: "a transform")
+      new(allowed: allowed, subject: subject, **options).to_json
+    end
+
+    #: (?allowed: Array[Symbol], ?subject: String, **untyped) -> void
+    def initialize(allowed: KNOWN, subject: "a transform", **options)
+      given = options.transform_keys(&:to_sym)
+
+      validate!(given.keys, allowed, subject)
+
+      @to_h = normalize(given).freeze
+
+      freeze
+    end
+
+    #: (?untyped) -> String
+    def to_json(state = nil)
+      JSON.generate(to_h, state)
+    end
+
+    #: () -> String
+    def inspect
+      "#<#{self.class.name} #{to_h.inspect}>"
+    end
+
+    private
+
+    #: (Array[Symbol], Array[Symbol], String) -> void
+    def validate!(names, allowed, subject)
+      unknown = names - KNOWN
+
+      raise OptionError, "Unknown option#{"s" if unknown.length > 1}: #{unknown.join(", ")}" if unknown.any?
+
+      unsupported = names - allowed
+
+      return if unsupported.empty?
+
+      raise OptionError, "#{unsupported.join(", ")} #{unsupported.one? ? "is not an option" : "are not options"} for #{subject}"
+    end
+
+    #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    def normalize(options)
+      normalized = options.dup
+
+      normalized[:css_modules] = {} if normalized[:css_modules] == true
+      normalized.delete(:css_modules) if normalized[:css_modules] == false
+
+      normalized.compact
+    end
+  end
+end