cataract 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afbaeaaa174e69b056a175c1a0aed5da7f52e33fcbc4859448262aff427086f9
-  data.tar.gz: dd190c243a6d494ed1e87c155cdeda2e6843bbc827e048e8df7eb992d2c8d09b
+  metadata.gz: 7b98cea191d8f92ffa56c46ad4600a8f16594fcbf1d6fe66b5c5317c161a1599
+  data.tar.gz: 7501de6b3fb3aba7d7319332932008003a181b4eaa67ed50b0b23aaa0063ff5c
 SHA512:
-  metadata.gz: '083570d10482fe637251a7d6fa912e6ec0ea3daa3d0283fa65b6f7aa54d798c693cb359fda1c6186bc5223504d9f31d91e6b359c170d718623279f2aac615186'
-  data.tar.gz: 5bd729068d06e069f625b2fc2d034dab769707f749ee175fbc420253cac953e52f8143194c1bca51a18bcd16d6190026e1823375b9eba3a564fd39a237e065ea
+  metadata.gz: 45b860f18d838ac6dab2d775ce4f73e38624cce23ed700bcd40c91aeb5713f6ac19b120a7647a4a838e050a86605bf252a7b83f4c4d20335eb9e18436db64dab
+  data.tar.gz: 8625e832be70e0d463a3bd90116132d6e871cbe51eff1ec61fe0e7b7d1a290a2265ee94e7731fccf16b3d46380d39d07d49e703febbfe2d7137c5aec8c46f99f

data/.github/workflows/ci.yml

@@ -46,32 +46,3 @@ jobs:
           clang-tidy --version
           bundle exec rake lint
           touch .lint-passed
-
-  docs:
-    # Only run on push to main (not PRs)
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    needs: test-ubuntu
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: '3.4'
-          bundler-cache: true
-
-      - name: Compile extension and generate documentation
-        run: bundle exec rake compile docs
-
-      - name: Disable Jekyll processing
-        run: touch docs/.nojekyll
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
-          allow_empty_commit: true

data/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Compile extension and generate documentation
+        run: bundle exec rake compile docs
+
+      - name: Disable Jekyll processing
+        run: touch docs/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.gitignore

@@ -42,4 +42,6 @@ benchmarks/.benchmark_results/
 
 # Documentation (generated by YARD)
 docs/
+!docs/files/
+!docs/files/EXAMPLE.md
 .yardoc/

data/CHANGELOG.md

@@ -1 +1,5 @@
+## [0.1.1] - 2025-11-09
+
+- Fix bugs with Stylesheet#merge resulting in wrong results (#11)
+
 ## [0.1.0] - 2025-11-09

data/Gemfile

@@ -14,6 +14,7 @@ gem 'benchmark-ips', '~> 2.0'
 gem 'css_parser', '~> 1.0' # for benchmarking against
 gem 'minitest'
 gem 'minitest-spec'
+gem 'nokogiri' # for docs
 gem 'simplecov', require: false
 gem 'simplecov-cobertura', require: false
 gem 'webmock', '~> 3.0' # for testing URL loading

data/README.md

@@ -11,7 +11,7 @@ A performant CSS parser for accurate parsing of complex CSS structures.
 - **C Extension**: Performance-focused C implementation for parsing and serialization
 - **CSS2 Support**: Selectors, combinators, pseudo-classes, pseudo-elements, @media queries
 - **CSS3 Support**: Attribute selectors (`^=`, `$=`, `*=`)
-- **CSS Color Level 4**: Supports hex, rgb, hsl, hwb, oklab, oklch, and named colors with high precision
+- **CSS Color Level 4**: Parses and preserves modern color formats (hex, rgb, hsl, hwb, oklab, oklch, lab, lch, named colors). Optional color conversion utility for transforming between formats.
 - **Specificity Calculation**: Automatic CSS specificity computation
 - **Media Query Filtering**: Query rules by media type
 - **Zero Runtime Dependencies**: Pure C extension with no runtime gem dependencies

data/Rakefile

@@ -12,7 +12,7 @@ begin
   require 'rake/extensiontask'
 
   # Configure the main extension
-  Rake::ExtensionTask.new('cataract') do |ext|
+  Rake::ExtensionTask.new('native_extension') do |ext|
     ext.lib_dir = 'lib/cataract'
     ext.ext_dir = 'ext/cataract'
   end
@@ -26,7 +26,6 @@ end
 
 # Configure CLEAN to run before compilation
 # rake-compiler already adds: tmp/, lib/**/*.{so,bundle}, etc.
-# All C files are now hand-written (Ragel removed), so only clean build artifacts
 CLEAN.include('ext/**/Makefile', 'ext/**/*.o')
 
 Rake::TestTask.new(:test) do |t|
@@ -182,6 +181,8 @@ begin
   desc 'Generate example CSS analysis for documentation'
   task :generate_example do
     puts 'Generating GitHub CSS analysis example...'
+    require 'fileutils'
+    FileUtils.mkdir_p('docs')
     # Generate with file. prefix for YARD compatibility
     system('ruby examples/css_analyzer.rb https://github.com -o docs/file.github_analysis.html')
   end

data/cataract.gemspec

@@ -5,11 +5,11 @@ require_relative 'lib/cataract/version'
 Gem::Specification.new do |spec|
   spec.name          = 'cataract'
   spec.version       = Cataract::VERSION
-  spec.authors       = ['Your Name']
-  spec.email         = ['your.email@example.com']
+  spec.authors       = ['James Cook']
+  spec.email         = ['jcook.rubyist@gmail.com']
 
-  spec.summary       = 'CSS parser built with Ragel state machines'
-  spec.description   = 'A high-performance CSS parser using Ragel finite state machines for accurate parsing of complex CSS structures'
+  spec.summary       = 'High-performance CSS parser with C extensions'
+  spec.description   = 'A performant CSS parser with C extensions for accurate parsing of complex CSS structures including media queries, nested selectors, and CSS Color Level 4'
   spec.homepage      = 'https://github.com/jamescook/cataract'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 3.1.0')

data/docs/files/EXAMPLE.md

@@ -0,0 +1,35 @@
+# Live Example
+
+This is a live example of Cataract analyzing GitHub.com's CSS.
+
+**{file:github_analysis.html View GitHub.com CSS Analysis Report}**
+
+This analysis was generated using:
+
+```bash
+ruby examples/css_analyzer.rb https://github.com -o docs/github_analysis.html
+```
+
+The example demonstrates:
+- **Real-world CSS parsing performance** - Analyzing 16,000+ rules from GitHub.com
+- **Property usage statistics** - Top properties and their frequency
+- **Color palette extraction** - All colors used across the site
+- **Specificity analysis** - Distribution of selector complexity
+- **!important usage patterns** - How often declarations are marked important
+
+The analysis is regenerated each time documentation is built with `rake docs`.
+
+## Running Your Own Analysis
+
+You can analyze any website or CSS file:
+
+```bash
+# Analyze a website
+ruby examples/css_analyzer.rb https://example.com
+
+# Analyze a CSS file
+ruby examples/css_analyzer.rb path/to/styles.css
+
+# Save to HTML report
+ruby examples/css_analyzer.rb https://example.com -o report.html
+```

data/examples/css_analyzer/analyzer.rb

@@ -16,17 +16,10 @@ module CSSAnalyzer
     def initialize(source, options = {})
       @source = source
       @options = {
-        top: 20,
-        use_shim: false
+        top: 20
       }.merge(options)
       @timings = {}
 
-      # Load shim if requested
-      if @options[:use_shim]
-        require_relative '../../lib/cataract/css_parser_compat'
-        Cataract.mimic_CssParser!
-      end
-
       # Load CSS based on source type
       @stylesheet = load_css(source)
     end
@@ -76,10 +69,9 @@ module CSSAnalyzer
 
     # Save parsed CSS to a file for debugging/comparison
     def save_parsed_css
-      # Generate a unique filename based on source and shim usage
+      # Generate a unique filename based on source
       source_slug = @source.gsub(%r{[:/]}, '_').gsub(/[^a-zA-Z0-9_.-]/, '')
-      shim_suffix = @options[:use_shim] ? '-shim' : '-direct'
-      filename = "parsed-css-#{source_slug}#{shim_suffix}.css"
+      filename = "parsed-css-#{source_slug}.css"
 
       # Serialize stylesheet to CSS
       css_output = @stylesheet.to_s
@@ -120,27 +112,18 @@ module CSSAnalyzer
       premailer = Premailer.new(url, with_html_string: false)
       @timings[:fetch] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - fetch_start
 
-      # Get CSS parser from Premailer
+      # Get CSS parser from Premailer and convert to string
       parser = premailer.instance_variable_get(:@css_parser)
+      parse_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      css_string = parser.to_s
+      @timings[:premailer_parse] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - parse_start
 
-      # If using Cataract shim, parser is already a Cataract::Stylesheet - use it directly
-      if defined?(CssParser::CATARACT_SHIM) && CssParser::CATARACT_SHIM
-        @timings[:premailer_parse] = 0  # Already parsed by Premailer/Cataract
-        @timings[:cataract_parse] = 0   # No reparsing needed
-        parser # Return the Cataract::Stylesheet directly
-      else
-        # Not using shim - parser is real css_parser, get CSS string and reparse
-        parse_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        css_string = parser.to_s
-        @timings[:premailer_parse] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - parse_start
+      # Parse it with Cataract
+      cataract_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      stylesheet = Cataract.parse_css(css_string)
+      @timings[:cataract_parse] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - cataract_start
 
-        # Parse it with Cataract
-        cataract_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        stylesheet = Cataract.parse_css(css_string)
-        @timings[:cataract_parse] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - cataract_start
-
-        stylesheet
-      end
+      stylesheet
     end
 
     def source_name

data/examples/css_analyzer.rb

@@ -25,19 +25,12 @@ if __FILE__ == $PROGRAM_NAME
       options[:output] = file
     end
 
-    opts.on('--use-shim', 'Use Cataract shim for css_parser (for Premailer)') do
-      options[:use_shim] = true
-    end
-
     opts.on('-h', '--help', 'Show this help message') do
       puts opts
       exit
     end
   end.parse!
 
-  # Check for ENV var to enable shim
-  options[:use_shim] = true if ENV['CATARACT_SHIM']
-
   # Check for required argument
   if ARGV.empty?
     warn 'Error: No URL or file specified'

data/ext/cataract/cataract.c

@@ -228,22 +228,24 @@ static void serialize_at_rule_formatted(VALUE result, VALUE at_rule, const char
                 rb_str_append(result, nested_selector);
                 rb_str_cat2(result, " {\n");
 
-                // Declarations on their own line (4-space indent)
-                rb_str_cat2(result, indent);
-                rb_str_cat2(result, "    ");
-                serialize_declarations(result, nested_declarations);
-                rb_str_cat2(result, "\n");
+                // Declarations (one per line) with 4-space indent
+                VALUE nested_indent = rb_str_new_cstr(indent);
+                rb_str_cat2(nested_indent, "    ");
+                const char *nested_indent_ptr = RSTRING_PTR(nested_indent);
+                serialize_declarations_formatted(result, nested_declarations, nested_indent_ptr);
+                RB_GC_GUARD(nested_indent);
 
                 // Closing brace (2-space indent)
                 rb_str_cat2(result, indent);
                 rb_str_cat2(result, "  }\n");
             }
         } else {
-            // Serialize as declarations (e.g., @font-face)
-            rb_str_cat2(result, indent);
-            rb_str_cat2(result, "  ");
-            serialize_declarations(result, content);
-            rb_str_cat2(result, "\n");
+            // Serialize as declarations (e.g., @font-face, one per line)
+            VALUE content_indent = rb_str_new_cstr(indent);
+            rb_str_cat2(content_indent, "  ");
+            const char *content_indent_ptr = RSTRING_PTR(content_indent);
+            serialize_declarations_formatted(result, content, content_indent_ptr);
+            RB_GC_GUARD(content_indent);
         }
     }
 
@@ -268,11 +270,12 @@ static void serialize_rule_formatted(VALUE result, VALUE rule, const char *inden
     rb_str_append(result, selector);
     rb_str_cat2(result, " {\n");
 
-    // Declarations on their own line with extra indentation
-    rb_str_cat2(result, indent);
-    rb_str_cat2(result, "  ");
-    serialize_declarations(result, declarations);
-    rb_str_cat2(result, "\n");
+    // Declarations (one per line) with extra indentation
+    VALUE decl_indent = rb_str_new_cstr(indent);
+    rb_str_cat2(decl_indent, "  ");
+    const char *decl_indent_ptr = RSTRING_PTR(decl_indent);
+    serialize_declarations_formatted(result, declarations, decl_indent_ptr);
+    RB_GC_GUARD(decl_indent);
 
     // Closing brace
     rb_str_cat2(result, indent);
@@ -987,7 +990,7 @@ static VALUE new_parse_declarations(VALUE self, VALUE declarations_string) {
 // Ruby Module Initialization
 // ============================================================================
 
-void Init_cataract(void) {
+void Init_native_extension(void) {
     // Get Cataract module (should be defined by main extension)
     VALUE mCataract = rb_define_module("Cataract");
 

data/ext/cataract/cataract.h

@@ -110,6 +110,10 @@ static inline VALUE strip_string(const char *str, long len) {
   #define STR_NEW_CSTR(str) rb_str_new_cstr(str)
 #endif
 
+// String comparison macro - check if Ruby string equals C string literal
+#define STR_EQ(val, lit) (RSTRING_LEN(val) == strlen(lit) && \
+                          memcmp(RSTRING_PTR(val), lit, strlen(lit)) == 0)
+
 // Safety limits
 #ifndef MAX_PARSE_DEPTH
   #define MAX_PARSE_DEPTH 10  // Max recursion depth for nested @media/@supports blocks and CSS nesting

data/ext/cataract/extconf.rb

@@ -45,4 +45,4 @@ else
   puts 'String buffer optimization: DISABLED'
 end
 
-create_makefile('cataract/cataract')
+create_makefile('cataract/native_extension')