cataract 0.1.0

data/examples/color_conversion_visual_test/generate.rb

@@ -0,0 +1,202 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Visual test generator for Cataract color conversions
+# Generates an HTML file showing color conversions across all supported formats
+
+require 'erb'
+require 'fileutils'
+
+# Add lib to load path
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'cataract'
+
+# Sample of named colors to test (diverse hues, saturations, lightness)
+SAMPLE_COLORS = %w[
+  red
+  green
+  blue
+  yellow
+  cyan
+  magenta
+  white
+  black
+  gray
+  silver
+  maroon
+  olive
+  lime
+  aqua
+  teal
+  navy
+  fuchsia
+  purple
+  orange
+  pink
+  coral
+  tomato
+  gold
+  indigo
+  violet
+  brown
+  tan
+  khaki
+  salmon
+  crimson
+  chocolate
+  peru
+  sienna
+  steelblue
+  skyblue
+  turquoise
+  orchid
+  plum
+  lavender
+].freeze
+
+def convert_color(color_str, from_format, to_format)
+  css = ".test { color: #{color_str}; }"
+  sheet = Cataract.parse_css(css)
+  sheet.convert_colors!(from: from_format, to: to_format)
+  decls = Cataract::Declarations.new(sheet.declarations)
+  decls['color']
+end
+
+def auto_detect_convert(color_str, to_format)
+  css = ".test { color: #{color_str}; }"
+  sheet = Cataract.parse_css(css)
+  sheet.convert_colors!(to: to_format)
+  decls = Cataract::Declarations.new(sheet.declarations)
+  decls['color']
+end
+
+def hex_difference(hex1, hex2)
+  # Parse hex colors and calculate RGB distance
+  r1, g1, b1 = hex1.scan(/[0-9a-f]{2}/i).map { |h| h.to_i(16) }
+  r2, g2, b2 = hex2.scan(/[0-9a-f]{2}/i).map { |h| h.to_i(16) }
+
+  Math.sqrt(((r1 - r2)**2) + ((g1 - g2)**2) + ((b1 - b2)**2))
+end
+
+# Generate forward conversion tests (named → rgb → hwb → hsl → oklab → lab → lch)
+def generate_forward_tests(colors)
+  colors.map do |color_name|
+    # Start with named color
+    named = color_name
+
+    # Convert through each format in sequence
+    rgb = convert_color(named, :named, :rgb)
+    hwb = convert_color(rgb, :rgb, :hwb)
+    hsl = convert_color(hwb, :hwb, :hsl)
+    oklab = convert_color(hsl, :hsl, :oklab)
+    lab = convert_color(oklab, :oklab, :lab)
+    lch = convert_color(lab, :lab, :lch)
+
+    {
+      name: color_name,
+      named: named,
+      rgb: rgb,
+      hwb: hwb,
+      hsl: hsl,
+      oklab: oklab,
+      lab: lab,
+      lch: lch
+    }
+  end
+end
+
+# Generate reverse conversion tests (lch → lab → oklab → hsl → hwb → rgb → hex)
+def generate_reverse_tests(colors)
+  colors.map do |color_name|
+    # Get original hex value
+    original_hex = convert_color(color_name, :named, :hex)
+
+    # Convert to LCH first
+    lch = convert_color(color_name, :named, :lch)
+
+    # Convert back through the chain
+    lab = convert_color(lch, :lch, :lab)
+    oklab = convert_color(lab, :lab, :oklab)
+    hsl = convert_color(oklab, :oklab, :hsl)
+    hwb = convert_color(hsl, :hsl, :hwb)
+    rgb = convert_color(hwb, :hwb, :rgb)
+    hex = convert_color(rgb, :rgb, :hex)
+
+    # Calculate match quality
+    diff = hex_difference(original_hex, hex)
+    match_class = if diff.zero?
+                    'perfect'
+                  elsif diff < 2
+                    'close'
+                  else
+                    'off'
+                  end
+
+    match_symbol = case match_class
+                   when 'perfect' then '✓'
+                   when 'close' then '≈'
+                   else '✗'
+                   end
+
+    {
+      name: color_name,
+      original_hex: original_hex,
+      lch: lch,
+      lab: lab,
+      oklab: oklab,
+      hsl: hsl,
+      hwb: hwb,
+      rgb: rgb,
+      hex: hex,
+      match_class: match_class,
+      match_symbol: match_symbol,
+      diff: diff
+    }
+  end
+end
+
+# Calculate statistics
+def calculate_stats(forward_tests, reverse_tests)
+  perfect = reverse_tests.count { |t| t[:match_class] == 'perfect' }
+  close = reverse_tests.count { |t| t[:match_class] == 'close' }
+
+  {
+    total_tests: forward_tests.length,
+    perfect_matches: perfect,
+    close_matches: close,
+    formats_tested: 7 # hex, rgb, hwb, hsl, oklab, lab, lch
+  }
+end
+
+# Main execution
+puts 'Generating color conversion visual test...'
+puts "Testing #{SAMPLE_COLORS.length} colors..."
+
+# Generate test data
+forward_tests = generate_forward_tests(SAMPLE_COLORS)
+puts '✓ Generated forward conversion tests'
+
+reverse_tests = generate_reverse_tests(SAMPLE_COLORS)
+puts '✓ Generated reverse conversion tests'
+
+stats = calculate_stats(forward_tests, reverse_tests)
+puts '✓ Calculated statistics'
+
+# Load ERB template
+template_path = File.join(__dir__, 'template.html.erb')
+template = ERB.new(File.read(template_path), trim_mode: '-')
+
+# Render HTML
+html = template.result(binding)
+
+# Write output
+output_path = File.join(__dir__, 'color_conversion_test.html')
+File.write(output_path, html)
+
+puts "\n✓ Generated: #{output_path}"
+puts "\nStatistics:"
+puts "  Total colors tested: #{stats[:total_tests]}"
+puts "  Perfect round-trips: #{stats[:perfect_matches]}"
+puts "  Close matches: #{stats[:close_matches]}"
+puts "  Formats: #{stats[:formats_tested]}"
+puts "\nOpen #{output_path} in a browser to view the results."

data/examples/color_conversion_visual_test/template.html.erb

@@ -0,0 +1,259 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Cataract Color Conversion Visual Test</title>
+
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
+
+    <style>
+        body {
+            background: #f8f9fa;
+        }
+        .color-cell {
+            width: 80px;
+            height: 40px;
+            border: 1px solid #dee2e6;
+            border-radius: 4px;
+            display: inline-block;
+            box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+            cursor: help;
+        }
+        .match-indicator {
+            font-size: 1.5em;
+        }
+        .match-indicator.perfect { color: #198754; }
+        .match-indicator.close { color: #ffc107; }
+        .match-indicator.off { color: #dc3545; }
+        .stat-value {
+            font-size: 2.5em;
+            font-weight: bold;
+            color: #0d6efd;
+        }
+    </style>
+</head>
+<body>
+    <div class="container-fluid py-5">
+        <h1 class="mb-4">🎨 Cataract Color Conversion Visual Test</h1>
+
+        <div class="card mb-4">
+            <div class="card-body">
+                <p><strong>Purpose:</strong> This page visually validates color conversions across different CSS color formats.</p>
+                <p>If conversions are correct, all color swatches in each row should appear identical.</p>
+                <p><strong>Tip:</strong> Hover over any color swatch to see the CSS color value.</p>
+                <p class="mb-0"><strong>Generated:</strong> <%= Time.now.strftime('%Y-%m-%d %H:%M:%S') %></p>
+            </div>
+        </div>
+
+        <!-- Tabs for Forward/Reverse Conversion -->
+        <ul class="nav nav-tabs mb-3" id="conversionTabs" role="tablist">
+            <li class="nav-item" role="presentation">
+                <button class="nav-link active" id="forward-tab" data-bs-toggle="tab" data-bs-target="#forward" type="button" role="tab" aria-controls="forward" aria-selected="true">
+                    Forward: Named → RGB → HWB → HSL → Oklab → Lab → LCH
+                </button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="reverse-tab" data-bs-toggle="tab" data-bs-target="#reverse" type="button" role="tab" aria-controls="reverse" aria-selected="false">
+                    Reverse: LCH → Lab → Oklab → HSL → HWB → RGB → Hex
+                </button>
+            </li>
+        </ul>
+
+        <div class="tab-content mb-5" id="conversionTabContent">
+            <!-- Forward conversion tab -->
+            <div class="tab-pane fade show active" id="forward" role="tabpanel" aria-labelledby="forward-tab">
+                <p class="text-muted mb-3">Starting from named colors, converting through each format. All swatches should match.</p>
+
+                <div class="table-responsive">
+                    <table class="table table-striped table-hover">
+                        <thead class="table-light">
+                            <tr>
+                                <th>Color Name</th>
+                                <th>Named</th>
+                                <th>RGB</th>
+                                <th>HWB</th>
+                                <th>HSL</th>
+                                <th>Oklab</th>
+                                <th>Lab</th>
+                                <th>LCH</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <% forward_tests.each do |test| %>
+                            <tr>
+                                <td class="fw-bold"><%= test[:name] %></td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:named] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:named] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:rgb] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:rgb] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:hwb] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:hwb] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:hsl] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:hsl] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:oklab] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:oklab] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:lab] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:lab] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:lch] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:lch] %>"></div>
+                                </td>
+                            </tr>
+                            <% end %>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            <!-- Reverse conversion tab -->
+            <div class="tab-pane fade" id="reverse" role="tabpanel" aria-labelledby="reverse-tab">
+                <p class="text-muted mb-3">Starting from LCH, converting back through each format. Some precision loss expected but should be visually close.</p>
+
+                <div class="table-responsive">
+                    <table class="table table-striped table-hover">
+                        <thead class="table-light">
+                            <tr>
+                                <th>Original</th>
+                                <th>LCH</th>
+                                <th>Lab</th>
+                                <th>Oklab</th>
+                                <th>HSL</th>
+                                <th>HWB</th>
+                                <th>RGB</th>
+                                <th>Hex</th>
+                                <th>Match</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <% reverse_tests.each do |test| %>
+                            <tr>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:original_hex] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:original_hex] %>"></div>
+                                    <div class="small fw-bold mt-1"><%= test[:name] %></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:lch] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:lch] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:lab] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:lab] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:oklab] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:oklab] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:hsl] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:hsl] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:hwb] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:hwb] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:rgb] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:rgb] %>"></div>
+                                </td>
+                                <td>
+                                    <div class="color-cell" style="background-color: <%= test[:hex] %>;"
+                                         data-bs-toggle="tooltip" data-bs-placement="top"
+                                         title="<%= test[:hex] %>"></div>
+                                </td>
+                                <td class="match-indicator <%= test[:match_class] %>"
+                                    data-bs-toggle="tooltip" data-bs-placement="top"
+                                    title="RGB distance: <%= '%.2f' % test[:diff] %>">
+                                    <%= test[:match_symbol] %>
+                                </td>
+                            </tr>
+                            <% end %>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+
+        <!-- Statistics -->
+        <div class="mb-5">
+            <h2 class="mb-3">Conversion Statistics</h2>
+            <div class="row g-4">
+                <div class="col-md-3">
+                    <div class="card text-center">
+                        <div class="card-body">
+                            <div class="stat-value"><%= stats[:total_tests] %></div>
+                            <div class="text-muted">Total Tests</div>
+                        </div>
+                    </div>
+                </div>
+                <div class="col-md-3">
+                    <div class="card text-center">
+                        <div class="card-body">
+                            <div class="stat-value"><%= stats[:perfect_matches] %></div>
+                            <div class="text-muted">Perfect Round-trips</div>
+                        </div>
+                    </div>
+                </div>
+                <div class="col-md-3">
+                    <div class="card text-center">
+                        <div class="card-body">
+                            <div class="stat-value"><%= stats[:close_matches] %></div>
+                            <div class="text-muted">Close Matches</div>
+                        </div>
+                    </div>
+                </div>
+                <div class="col-md-3">
+                    <div class="card text-center">
+                        <div class="card-body">
+                            <div class="stat-value"><%= stats[:formats_tested] %></div>
+                            <div class="text-muted">Formats Tested</div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <footer class="text-center text-muted mt-5">
+            Generated by Cataract Color Conversion Test Suite
+        </footer>
+    </div>
+
+    <!-- Bootstrap Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script>
+
+    <!-- Initialize tooltips -->
+    <script>
+        // Enable all tooltips
+        const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
+        const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl));
+    </script>
+</body>
+</html>

data/examples/css_analyzer/analyzer.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'uri'
+require_relative '../../lib/cataract'
+require_relative 'analyzers/properties'
+require_relative 'analyzers/colors'
+require_relative 'analyzers/specificity'
+require_relative 'analyzers/important'
+
+module CSSAnalyzer
+  # Main analyzer orchestrator that coordinates all analysis modules
+  class Analyzer
+    attr_reader :stylesheet, :source, :options, :timings
+
+    def initialize(source, options = {})
+      @source = source
+      @options = {
+        top: 20,
+        use_shim: false
+      }.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
+
+    # Run all analyses and collect results
+    def analyze_all
+      {
+        summary: analyze_summary,
+        properties: Analyzers::Properties.new(stylesheet, options).analyze,
+        colors: Analyzers::Colors.new(stylesheet, options).analyze,
+        specificity: Analyzers::Specificity.new(stylesheet, options).analyze,
+        important: Analyzers::Important.new(stylesheet, options).analyze
+      }
+    end
+
+    # Generate summary statistics
+    def analyze_summary
+      {
+        total_rules: stylesheet.rules_count,
+        file_name: source_name,
+        file_path: source,
+        generated_at: Time.now
+      }
+    end
+
+    # Generate HTML report
+    def generate_report
+      analysis = analyze_all
+      template = ERB.new(template_content, trim_mode: '-')
+      template.result(binding)
+    end
+
+    # Save report to file or stdout
+    def save_report
+      report = generate_report
+
+      if options[:output]
+        File.write(options[:output], report)
+        puts "Report saved to #{options[:output]}"
+      else
+        puts report
+      end
+
+      # Also save the parsed CSS for debugging
+      save_parsed_css
+    end
+
+    # Save parsed CSS to a file for debugging/comparison
+    def save_parsed_css
+      # Generate a unique filename based on source and shim usage
+      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"
+
+      # Serialize stylesheet to CSS
+      css_output = @stylesheet.to_s
+
+      File.write(filename, css_output)
+      warn "Parsed CSS saved to #{filename} (#{@stylesheet.size} rules, #{css_output.length} bytes)"
+    end
+
+    private
+
+    def load_css(source)
+      # Check if it's a URL
+      if /\A#{URI::DEFAULT_PARSER.make_regexp(%w[http https])}\z/.match?(source)
+        load_from_url(source)
+      elsif File.exist?(source)
+        # Local file
+        Cataract::Stylesheet.load_file(source)
+      else
+        raise ArgumentError, "Invalid source: #{source} (not a valid URL or file path)"
+      end
+    end
+
+    def load_from_url(url)
+      # Check if it's a direct CSS file
+      if url.end_with?('.css')
+        Cataract::Stylesheet.load_uri(url)
+      else
+        # It's a webpage - use Premailer to fetch and combine all CSS
+        load_from_webpage(url)
+      end
+    end
+
+    def load_from_webpage(url)
+      require 'premailer'
+
+      # Fetch webpage and extract CSS
+      fetch_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      premailer = Premailer.new(url, with_html_string: false)
+      @timings[:fetch] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - fetch_start
+
+      # Get CSS parser from Premailer
+      parser = premailer.instance_variable_get(:@css_parser)
+
+      # 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
+
+        stylesheet
+      end
+    end
+
+    def source_name
+      if /\A#{URI::DEFAULT_PARSER.make_regexp(%w[http https])}\z/.match?(source)
+        uri = URI.parse(source)
+        if source.end_with?('.css')
+          File.basename(uri.path)
+        else
+          uri.host
+        end
+      else
+        File.basename(source)
+      end
+    end
+
+    def template_content
+      template_path = File.join(__dir__, 'templates', 'report.html.erb')
+      File.read(template_path)
+    end
+  end
+end

data/examples/css_analyzer/analyzers/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CSSAnalyzer
+  module Analyzers
+    # Base class for all analyzers
+    # Each analyzer should implement #analyze method that returns a hash of results
+    class Base
+      attr_reader :stylesheet, :options
+
+      def initialize(stylesheet, options = {})
+        @stylesheet = stylesheet
+        @options = options
+      end
+
+      # Override in subclasses
+      def analyze
+        raise NotImplementedError, "#{self.class} must implement #analyze"
+      end
+
+      # Helper to get the tab name for this analyzer
+      def tab_name
+        self.class.name.split('::').last.downcase
+      end
+
+      # Helper to get media queries for a specific rule
+      # @param rule [Cataract::Rule] The rule to check
+      # @return [Array<Symbol>] Array of media query symbols this rule appears in
+      def media_queries_for_rule(rule)
+        stylesheet.instance_variable_get(:@_media_index).select { |_media, ids| ids.include?(rule.id) }.keys
+      end
+    end
+  end
+end