yass-css 0.2.0

data/Cargo.toml

@@ -0,0 +1,7 @@
+# This Cargo.toml is here to let externals tools (IDEs, etc.) know that this is
+# a Rust project. Your extensions dependencies should be added to the Cargo.toml
+# in the ext/ directory.
+
+[workspace]
+members = ["./ext/yass"]
+resolver = "2"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Cameron Dutro
+
+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,139 @@
+# Yass
+
+Yass is a Ruby wrapper around the [Stylo](https://github.com/servo/stylo) CSS engine, the parser behind the Firefox and Servo browsers developed by Mozilla.
+
+## Rationale
+
+I needed a CSS parser in Ruby but couldn't find one that could handle nested CSS rules. Stylo was born out of that need, and aims to be a complete CSS parser for Ruby, covering the entire CSS spec.
+
+Stylo is itself under active development, and Yass does not yet wrap the entire Stylo API. If Yass doesn't support a feature you need, consider adding the missing functionality and submitting a pull request.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add yass-css
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install yass-css
+```
+
+## Usage
+
+There are two main ways to use Yass: by navigating the object hierarchy by hand, or by using the visitor pattern.
+
+By "navigating the object hierarchy," I just mean "calling methods on objects." Here's an example.
+
+```ruby
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  h1 {
+    align-items: center;
+    display: flex;
+    position: absolute;
+  }
+CSS
+
+# this is the whole h1 { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::StyleRule
+
+# this is the h1 selector
+first_selector = first_rule.selectors.first.children.first
+puts first_selector.value  # => "h1"
+```
+
+The entire object hierarchy can be discovered by dropping into a console session (via `bin/console`) and playing around.
+
+### The Visitor Pattern
+
+Yass also comes with a `Yass::Visitor` class that implements the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern).
+
+Some people love the visitor pattern, and some people seem to hate it. If you're in the second camp, feel free to skip this section.
+
+Visitor classes contain `visit_*` methods that the library calls in-order as it traverses the object hierarchy contained within a parsed stylesheet. The methods the visitor supports can be examined by reading the code in lib/yass/visitor.rb.
+
+Let's write a visitor class that prints all the class names in the given stylesheet:
+
+```ruby
+class MyVisitor < Yass::Visitor
+  def visit_selector_klass(node)
+    # node is an instance of Yass::Selector::Klass
+    puts node.value
+  end
+end
+```
+
+Now we can use our visitor to visit a stylesheet:
+
+```ruby
+sheet = Yass::Parser.parse(<<~CSS)
+  .left {
+    float: left;
+  }
+
+  .right {
+    float: right;
+  }
+CSS
+
+visitor = MyVisitor.new
+
+# this will result in "left" and "right" being printed to stdout
+visitor.visit(sheet)
+```
+
+## Examples
+
+For more examples, see the examples/ directory.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to compile the native extension and run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+Simply execute:
+
+```bash
+bundle exec rake
+```
+
+This will compile the native extension and run the tests immediately afterwards. To compile only, run:
+
+```bash
+bundle exec rake compile
+```
+
+To run the tests only, run:
+
+```bash
+bundle exec rake spec
+```
+
+To run the full test suite (much slower) that attempts to parse the ~33k example CSS files from the [Web Platform Test (WPT) suite](https://github.com/web-platform-tests/wpt), run:
+
+```ruby
+bundle exec rake spec:full
+```
+
+## Releasing
+
+Releasing Yass is done by creating a new release on GitHub. Doing so will trigger a special CI job capable of building the native extension for all supported plaforms and publishing a "fat" .gem file to rubygems.org.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/camertron/yass. 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/camertron/yass/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Yass project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/camertron/yass/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rb_sys/extensiontask"
+
+# task build: :compile
+
+GEMSPEC = Gem::Specification.load("yass.gemspec")
+
+RbSys::ExtensionTask.new("yass", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/yass"
+  ext.cross_compile = true
+  ext.cross_platform = [
+    "x86_64-linux",
+    "aarch64-linux",
+    "x86_64-darwin",
+    "arm64-darwin",
+    "x64-mingw-ucrt",
+  ]
+end
+
+task default: %i[compile spec]
+
+namespace :spec do
+  desc 'Run full specs suit'
+  task full: [:full_spec_env, :compile, :spec]
+
+  task :full_spec_env do
+    ENV['FULL_SPEC'] = 'true'
+  end
+end
+
+# For whatever reason, the :native task that comes with rb-sys doesn't work, so
+# we define our own
+task :native, [:platform] do |task, args|
+  env = if args[:platform] =~ /mingw/
+    # custom docker image that includes Python, which stylo seems to need
+    sh(
+      "docker", "build",
+      "--platform", "linux/amd64",
+      "-f", "dockerfiles/windows.dockerfile",
+      "-t", "camertron/rbsys-x64-mingw-ucrt:latest",
+      "dockerfiles/"
+    )
+
+    { "RCD_IMAGE" => "camertron/rbsys-x64-mingw-ucrt:latest" }
+  else
+    {}
+  end
+
+  sh(env, "bundle", "exec", "rb-sys-dock", "--platform", args[:platform], "--build")
+end
+
+task :codegen do
+  require "yass"
+  require_relative "codegen/rust_file_set"
+
+  general_files = Yass::Codegen::RustFileSet::new(
+    Dir.glob("ext/yass/src/general/**/*.rs")
+  )
+
+  File.write("lib/yass/general.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{general_files.module_tree.to_ruby_classes}
+  RUBY
+
+  declaration_files = Yass::Codegen::RustFileSet.new(Dir.glob("ext/yass/src/declarations/**/*.rs"))
+
+  File.write("lib/yass/declarations.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{declaration_files.module_tree.to_ruby_classes}
+  RUBY
+
+  selector_files = Yass::Codegen::RustFileSet.new(Dir.glob("ext/yass/src/selectors/**/*.rs"))
+
+  File.write("lib/yass/selectors.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{selector_files.module_tree.to_ruby_classes}
+  RUBY
+
+  rule_files = Yass::Codegen::RustFileSet.new([
+    "ext/yass/src/rules/rule.rs",
+    "ext/yass/src/rules/style_rule.rs",
+    "ext/yass/src/rules/media_rule.rs",
+    "ext/yass/src/rules/font_face_rule.rs",
+    *Dir.glob("ext/yass/src/rules/fonts/**/*.rs"),
+  ])
+
+  File.write("lib/yass/rules.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{rule_files.module_tree.to_ruby_classes}
+  RUBY
+
+  all_modules = general_files.module_tree
+    .merge(declaration_files.module_tree)
+    .merge(selector_files.module_tree)
+    .merge(rule_files.module_tree)
+
+  visitor_class = <<~RUBY
+    # frozen_string_literal: true
+
+    module Yass
+      class Visitor
+        def visit(node)
+          node.accept(self) if node
+        end
+
+        def visit_list(nodes)
+          nodes.each { |node| visit(node) }
+        end
+
+        def visit_stylesheet(node)
+          visit_list(node.rules)
+        end
+
+    #{all_modules.to_visitor_methods(indent: "    ").join("\n")}
+      end
+    end
+  RUBY
+
+  File.write("lib/yass/visitor.rb", visitor_class)
+end

data/codegen/ruby_module_tree.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "utils"
+
+module Yass
+  module Codegen
+    class RubyModule
+      attr_reader :name
+      attr_accessor :rust_struct
+
+      def initialize(name)
+        @name = name
+      end
+
+      def children
+        @children ||= {}
+      end
+    end
+
+    class RubyModuleTree
+      class << self
+        def from_structs(rust_structs)
+          root = RubyModule.new(nil)
+
+          rust_structs.each do |rust_struct|
+            current = root
+
+            rust_struct.ruby_class_name.split("::").each do |ns|
+              if !current.children.include?(ns)
+                current.children[ns] = RubyModule.new(ns)
+              end
+
+              current = current.children[ns]
+            end
+
+            current.rust_struct = rust_struct
+          end
+
+          new(root)
+        end
+      end
+
+      include Utils
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = root
+      end
+
+      def to_ruby_classes(indent: "")
+        to_ruby_classes_helper(root.children["Yass"], ["Yass"], indent)
+      end
+
+      def to_visitor_methods(indent:)
+        to_visitor_methods_helper(root.children["Yass"], ["Yass"], indent)
+      end
+
+      def merge(other)
+        if root.name != other.root.name
+          raise ArgumentError, "this tree and other tree have different names, '#{name}' vs '#{other.root.name}'"
+        end
+
+        new_root = merge_helper(root, other.root)
+        self.class.new(new_root)
+      end
+
+      private
+
+      def merge_helper(first, second)
+        RubyModule.new(first.name).tap do |mod|
+          first.children.each do |key, first_child_mod|
+            if (second_child_mod = second.children[key])
+              mod.children[key] = merge_helper(first_child_mod, second_child_mod)
+            else
+              mod.children[key] = first_child_mod
+            end
+          end
+
+          second.children.each do |key, second_child_mod|
+            # merge for identical keys should happen in first pass above
+            if !first.children.include?(key)
+              mod.children[key] = second_child_mod
+            end
+          end
+        end
+      end
+
+      def to_ruby_classes_helper(mod, nesting, indent = "")
+        class_or_module = Kernel.const_get(nesting.join("::"))
+        class_or_module_def = class_or_module.class == Class ? "class #{mod.name}" : "module #{mod.name}"
+
+        children = mod.children.map do |mod_name, child|
+          to_ruby_classes_helper(child, [*nesting, mod_name], indent + "  ")
+        end
+
+        accept_method = if mod.rust_struct
+          [
+            "#{indent}  def accept(visitor)",
+            "#{indent}    visitor.visit_#{nesting_to_s(nesting[1..-1])}(self)",
+            "#{indent}  end",
+          ]
+        end
+
+        kind_method = if mod.rust_struct
+          [
+            "#{indent}  def kind",
+            "#{indent}    :#{underscore(nesting.last).downcase}",
+            "#{indent}  end",
+          ]
+        end
+
+        constants = if mod.rust_struct
+          method_names = class_or_module.instance_methods - Object.methods - [:accept, :to_h]
+
+          if method_names.size > 0
+            [
+              "#{indent}  RUBY_METHODS = %i(#{method_names.map(&:to_s).sort.join(" ")}).freeze"
+            ]
+          end
+        end
+
+        includes = if mod.rust_struct
+          ["#{indent}  include ::Yass::Node"]
+        end
+
+        lines = [
+          "#{indent}#{class_or_module_def}",
+          *join_line_groups(
+            constants,
+            includes,
+            accept_method,
+            kind_method,
+            (children.empty? ? [] : [children.join("\n\n")]),
+          ),
+          "#{indent}end",
+        ]
+
+        lines.join("\n")
+      end
+
+      def to_visitor_methods_helper(mod, nesting, indent)
+        line_groups = []
+
+        if mod.rust_struct
+          method_name = "visit_#{nesting_to_s(nesting[1..-1])}"
+
+          line_groups << [
+            "#{indent}def #{method_name}(node)",
+            *(debug? ? ["#{indent}  puts \"Visiting #{method_name}\""] : []),
+            *mod.rust_struct.rust_methods.map do |rust_method|
+              if rust_method.visit_kind == :single
+                [
+                  "#{indent}  visit(node.#{rust_method.name})"
+                ]
+              else
+                [
+                  "#{indent}  visit_list(node.#{rust_method.name})"
+                ]
+              end
+            end,
+            "#{indent}end",
+          ]
+        end
+
+        mod.children.each do |mod_name, child|
+          line_groups << to_visitor_methods_helper(child, [*nesting, mod_name], indent)
+        end
+
+        join_line_groups(*line_groups)
+      end
+
+      def debug?
+        !!ENV["DEBUG"]
+      end
+    end
+  end
+end

data/codegen/rust_file_set.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "ruby_module_tree"
+
+module Yass
+  module Codegen
+    class RustStruct
+      attr_reader :name, :ruby_class_name, :rust_methods
+
+      def initialize(name:, ruby_class_name:, rust_methods:)
+        @name = name
+        @ruby_class_name = ruby_class_name
+        @rust_methods = rust_methods
+      end
+    end
+
+    class RustMethod
+      attr_reader :name, :return_type, :visit_kind
+
+      def initialize(name:, return_type:, visit_kind:)
+        @name = name
+        @return_type = return_type
+        @visit_kind = visit_kind
+      end
+    end
+
+    class RustFileSet
+      attr_reader :rust_file_paths
+
+      def initialize(rust_file_paths)
+        @rust_file_paths = rust_file_paths
+      end
+
+      def structs
+        @structs ||= rust_file_paths.flat_map do |rust_file|
+          rust_code = File.read(rust_file)
+
+          rust_code.scan(/#\[magnus(?:\:\:wrap)?\(class = "([\w:]+)"(?:, mark)?\)\]\s+pub struct (\w+)/).map do |ruby_class_name, rust_struct_name|
+            next unless ruby_class_name && rust_struct_name
+
+            m = rust_code.match(/impl\s+#{rust_struct_name}\s+(\{)/)
+            next unless m
+
+            start = pos = m.end(1)
+            count = 1
+
+            while count > 0
+              case rust_code[pos]
+              when "{"
+                count += 1
+              when "}"
+                count -= 1
+              end
+
+              pos += 1
+            end
+
+            impl_body = rust_code[start..pos]
+            rust_method_names = impl_body.scan(/pub fn (\w+)\(ruby: &Ruby, rb_self: typed_data::Obj<Self>\) -> ([\w<>:, ]+) \{/)
+            rust_methods = []
+
+            rust_method_names.each do |name, return_type|
+              if ["Option<Value>", "Value"].include?(return_type)
+                rust_methods << RustMethod.new(name: name, return_type: return_type, visit_kind: :single)
+              elsif ["RArray", "Result<RArray, Error>"].include?(return_type)
+                rust_methods << RustMethod.new(name: name, return_type: return_type, visit_kind: :multiple)
+              end
+            end
+
+            RustStruct.new(
+              name: rust_struct_name,
+              ruby_class_name: ruby_class_name,
+              rust_methods: rust_methods
+            )
+          end
+        end
+      end
+
+      def module_tree
+        @module_tree ||= RubyModuleTree.from_structs(structs)
+      end
+    end
+  end
+end

data/codegen/utils.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yass
+  module Codegen
+    module Utils
+      def underscore(str)
+        str.gsub(/(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/, "_")
+      end
+
+      def nesting_to_s(nesting)
+        nesting
+          .map { |part| underscore(part).downcase }
+          .map { |part| part == "declarations" ? "declaration" : part }
+          .join("_")
+      end
+
+      def join_line_groups(*line_groups)
+        result = line_groups.compact.reject(&:empty?).flat_map do |group|
+          [*group.flatten, ""]
+        end
+
+        result.pop
+        result
+      end
+    end
+  end
+end

data/dockerfiles/windows.dockerfile

@@ -0,0 +1,3 @@
+FROM rbsys/x64-mingw-ucrt:0.9.126
+
+RUN apt-get update && apt-get install -y python3

data/examples/basic_example.rb

@@ -0,0 +1,32 @@
+require "yass"
+require "pp"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  h1 {
+    align-items: center;
+    display: flex;
+    position: absolute;
+  }
+CSS
+
+# this is the whole h1 { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::StyleRule
+
+# this is the h1 selector
+first_selector = first_rule.selectors.first.children.first
+puts first_selector.value  # => "h1"
+
+# this is all the declarations inside the h1 rule
+declarations = first_rule.declarations
+
+# this is the first align-items declaration
+declaration = declarations.first
+puts declaration.kind   # => :align_items
+puts declaration.class  # => Yass::Declarations::AlignItems
+puts declaration.value  # => :center
+
+# this will turn the entire stylesheet into a JSON-compatible
+# data structure (only arrays, hashes, strings, etc) and
+# pretty-print it
+pp sheet.to_h

data/examples/font_example.rb

@@ -0,0 +1,19 @@
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  @font-face {
+    font-family: "Bitstream Vera Serif Bold";
+    src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2");
+  }
+CSS
+
+# this is the whole @font-face { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::FontFaceRule
+
+family = first_rule.family
+puts family.name  # => "Bitstream Vera Serif Bold"
+
+first_source = first_rule.sources.first
+puts first_source.class          # => Yass::Font::Source::Url
+puts first_source.specified_url  # => "https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2"

data/examples/media_example.rb

@@ -0,0 +1,31 @@
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  @media screen and (max-width: 600px) {
+    .container {
+      flex-direction: column;
+    }
+  }
+CSS
+
+# this is the whole @media { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::MediaRule
+
+# this is the "screen and ..." part
+first_query = first_rule.media_queries.first
+puts first_query.media_type.value       # => "screen"
+puts first_query.query_condition.value  # => "(max-width: 600px)"
+
+# Sadly Stylo doesn't give us access to the full parse tree for the
+# query condition, so the best we can do is emit the unparsed string.
+
+# this is the .container rule
+first_nested_rule = first_rule.rules.first
+first_selector = first_nested_rule.selectors.first.children.first
+puts first_selector.value  # => "container"
+
+# this is the flex-direction declaration
+first_declaration = first_nested_rule.declarations.first
+puts first_declaration.kind   # => :flex_direction
+puts first_declaration.value  # => :column