cataract 0.1.0

data/lib/cataract/at_rule.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Cataract
+  # Represents a CSS at-rule like @keyframes, @font-face, @supports, etc.
+  #
+  # AtRule is a C struct defined as: `Struct.new(:id, :selector, :content, :specificity)`
+  #
+  # At-rules define CSS resources or control structures rather than selecting elements.
+  # Unlike regular rules, they don't have CSS specificity and are filtered out when
+  # using `select(&:selector?)`.
+  #
+  # The content field varies by at-rule type:
+  # - `@keyframes`: Array of Rule (keyframe percentage blocks like "0%", "100%")
+  # - `@font-face`: Array of Declaration (font property declarations)
+  # - `@supports`: Array of Rule (conditional rules)
+  #
+  # @example Parse @keyframes
+  #   css = "@keyframes fade { 0% { opacity: 0; } 100% { opacity: 1; } }"
+  #   sheet = Cataract.parse_css(css)
+  #   at_rule = sheet.rules.first
+  #   at_rule.selector #=> "@keyframes fade"
+  #   at_rule.content #=> [Rule, Rule] (two keyframe blocks)
+  #
+  # @example Parse @font-face
+  #   css = "@font-face { font-family: 'MyFont'; src: url('font.woff'); }"
+  #   sheet = Cataract.parse_css(css)
+  #   at_rule = sheet.rules.first
+  #   at_rule.selector #=> "@font-face"
+  #   at_rule.content #=> [Declaration, Declaration]
+  #
+  # @attr [Integer] id The at-rule's position in the stylesheet (0-indexed)
+  # @attr [String] selector The at-rule identifier (e.g., "@keyframes fade", "@font-face")
+  # @attr [Array<Rule>, Array<Declaration>] content Nested rules or declarations
+  # @attr [nil] specificity Always nil for at-rules (they don't have CSS specificity)
+  class AtRule
+    # Check if this is a selector-based rule (vs an at-rule like @keyframes).
+    #
+    # @return [Boolean] Always returns false for AtRule objects
+    def selector?
+      false
+    end
+
+    # Check if this is an at-rule.
+    #
+    # @return [Boolean] Always returns true for AtRule objects
+    def at_rule?
+      true
+    end
+
+    # Check if this is a specific at-rule type.
+    #
+    # @param type [Symbol] At-rule type (e.g., :keyframes, :font_face)
+    # @return [Boolean] true if at-rule matches the type
+    #
+    # @example Check for @keyframes
+    #   at_rule.at_rule_type?(:keyframes) #=> true if selector is "@keyframes ..."
+    #
+    # @example Check for @font-face
+    #   at_rule.at_rule_type?(:font_face) #=> true if selector is "@font-face"
+    def at_rule_type?(type)
+      type_str = "@#{type.to_s.tr('_', '-')}"
+      selector.start_with?(type_str)
+    end
+
+    # Check if this at-rule has a declaration with the specified property.
+    #
+    # @param _property [String] CSS property name
+    # @param _value [String, nil] Optional value to match
+    # @return [Boolean] Always returns false for AtRule objects
+    def has_property?(_property, _value = nil)
+      false
+    end
+
+    # Check if this at-rule has any !important declarations.
+    #
+    # @param _property [String, nil] Optional property name
+    # @return [Boolean] Always returns false for AtRule objects
+    def has_important?(_property = nil)
+      false
+    end
+
+    # Compare at-rules by their attributes rather than object identity.
+    #
+    # Two at-rules are equal if they have the same id, selector, and content.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if at-rules have same attributes
+    def ==(other)
+      return false unless other.is_a?(AtRule)
+
+      id == other.id &&
+        selector == other.selector &&
+        content == other.content
+    end
+    alias eql? ==
+  end
+end

data/lib/cataract/color_conversion.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Color conversion utilities for Cataract
+#
+# This is an optional extension that adds color conversion capabilities to Cataract::Stylesheet.
+# Load it explicitly to add the convert_colors! method:
+#
+#   require 'cataract/color_conversion'
+#
+# Usage:
+#   sheet = Cataract.parse_css('.button { color: #ff0000; }')
+#   sheet.convert_colors!(to: :rgb)
+#   sheet.to_css  # => ".button { color: rgb(255 0 0); }"
+#
+# This extension is loaded on-demand to reduce memory footprint for users who
+# don't need color conversion functionality.
+
+require 'cataract/cataract_color'

data/lib/cataract/declarations.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Cataract
+  # Container for CSS property declarations with merge and cascade support.
+  #
+  # The Declarations class provides a convenient Ruby interface for working with
+  # CSS property-value pairs. It wraps an array of Declaration structs (defined in C)
+  # and provides hash-like access, iteration, and merging capabilities.
+  #
+  # @example Create from hash
+  #   decls = Cataract::Declarations.new('color' => 'red', 'margin' => '10px')
+  #   decls['color'] #=> "red"
+  #
+  # @example Create from Declaration array
+  #   rule = Cataract.parse_css("body { color: red; }").rules.first
+  #   decls = Cataract::Declarations.new(rule.declarations)
+  #   decls['color'] #=> "red"
+  #
+  # @example Create from CSS string
+  #   decls = Cataract::Declarations.new("color: red; margin: 10px")
+  #   decls.size #=> 2
+  #
+  # @example Work with !important
+  #   decls = Cataract::Declarations.new('color' => 'red !important')
+  #   decls.important?('color') #=> true
+  #   decls['color'] #=> "red !important"
+  class Declarations
+    include Enumerable
+
+    # Create a new Declarations container.
+    #
+    # @param properties [Hash, Array<Declaration>, String] Initial declarations
+    #   - Hash: Property name => value pairs
+    #   - Array: Array of Declaration structs from parser
+    #   - String: CSS declaration block (e.g., "color: red; margin: 10px")
+    # @return [Declarations] New Declarations instance
+    def initialize(properties = {})
+      case properties
+      when Array
+        # Array of Declaration structs from C parser - store directly
+        @values = properties
+      when Hash
+        # Hash from user - convert to internal storage
+        @values = []
+        properties.each { |prop, value| self[prop] = value }
+      when String
+        # String "color: red; background: blue" - parse it
+        @values = parse_declaration_string(properties)
+      else
+        @values = []
+      end
+    end
+
+    # Get the value of a CSS property.
+    #
+    # Returns the property value with !important suffix if present.
+    # Property names are case-insensitive.
+    #
+    # @param property [String, Symbol] The CSS property name
+    # @return [String, nil] The property value with !important suffix, or nil if not found
+    #
+    # @example
+    #   decls['color'] #=> "red"
+    #   decls['Color'] #=> "red" (case-insensitive)
+    #   decls['font-weight'] #=> "bold !important"
+    def get_property(property)
+      prop = normalize_property(property)
+      val = find_value(prop)
+      return nil if val.nil?
+
+      suffix = val.important ? ' !important' : ''
+      "#{val.value}#{suffix}"
+    end
+    alias [] get_property
+
+    # Set the value of a CSS property.
+    #
+    # Property names are normalized to lowercase. Trailing semicolons are stripped.
+    # The !important flag can be included in the value string.
+    #
+    # @param property [String, Symbol] The CSS property name
+    # @param value [String] The property value (may include !important)
+    # @return [void]
+    #
+    # @example
+    #   decls['color'] = 'red'
+    #   decls['margin'] = '10px !important'
+    #   decls['Color'] = 'blue' # Overwrites 'color' (case-insensitive)
+    def set_property(property, value)
+      prop = normalize_property(property)
+
+      # Parse !important and strip trailing semicolons (css_parser compatibility)
+      clean_value = value.to_s.strip
+      # Remove trailing semicolons (guard to avoid allocation when no semicolon present)
+      # value_str = value_str.sub(/;+$/, '') if value_str.end_with?(';')
+      clean_value.sub!(/;+$/, '') if clean_value.end_with?(';')
+
+      is_important = clean_value.end_with?('!important')
+      if is_important
+        clean_value.sub!(/\s*!important\s*$/, '').strip!
+      else
+        clean_value.strip!
+      end
+
+      # Reject malformed declarations with no value (e.g., "color: !important")
+      # css_parser silently ignores these
+      return if clean_value.empty?
+
+      # Find existing value or create new one
+      # Properties from C parser are already normalized, so direct comparison
+      existing_index = @values.find_index { |v| v.property == prop }
+
+      # Create a new Declaration struct
+      new_val = Cataract::Declaration.new(prop, clean_value, is_important)
+
+      if existing_index
+        @values[existing_index] = new_val
+      else
+        @values << new_val
+      end
+    end
+    alias []= set_property
+
+    # Check if a property is defined in this declaration block.
+    #
+    # @param property [String, Symbol] The CSS property name
+    # @return [Boolean] true if the property exists
+    #
+    # @example
+    #   decls.key?('color') #=> true
+    #   decls.has_property?('font-size') #=> false
+    def key?(property)
+      !find_value(normalize_property(property)).nil?
+    end
+    alias has_property? key?
+
+    # Check if a property has the !important flag.
+    #
+    # @param property [String, Symbol] The CSS property name
+    # @return [Boolean] true if the property has !important, false otherwise
+    #
+    # @example
+    #   decls['color'] = 'red !important'
+    #   decls.important?('color') #=> true
+    #   decls['margin'] = '10px'
+    #   decls.important?('margin') #=> false
+    def important?(property)
+      val = find_value(normalize_property(property))
+      val ? val.important : false
+    end
+
+    # Delete a property from the declaration block.
+    #
+    # @param property [String, Symbol] The CSS property name to delete
+    # @return [Array<Declaration>] The modified declarations array
+    #
+    # @example
+    #   decls.delete('color')
+    #   decls.key?('color') #=> false
+    def delete(property)
+      prop = normalize_property(property)
+      @values.delete_if { |v| v.property == prop }
+    end
+
+    # Iterate through each property-value pair.
+    #
+    # @yieldparam property [String] The property name
+    # @yieldparam value [String] The property value (without !important)
+    # @yieldparam important [Boolean] Whether the property has !important flag
+    # @return [Enumerator, nil] Returns enumerator if no block given
+    #
+    # @example
+    #   decls.each do |property, value, important|
+    #     puts "#{property}: #{value}#{important ? ' !important' : ''}"
+    #   end
+    def each
+      return enum_for(:each) unless block_given?
+
+      @values.each do |val|
+        yield val.property, val.value, val.important
+      end
+    end
+
+    # Get the number of declarations.
+    #
+    # @return [Integer] Number of properties in the declaration block
+    def size
+      @values.size
+    end
+    alias length size
+
+    # Check if the declaration block is empty.
+    #
+    # @return [Boolean] true if no properties are defined
+    def empty?
+      @values.empty?
+    end
+
+    # Convert declarations to CSS string.
+    #
+    # Implemented in C for performance (see ext/cataract/cataract.c).
+    # The C implementation is defined via rb_define_method and overrides this stub.
+    #
+    # @return [String] CSS declaration block string
+    #
+    # @example
+    #   decls.to_s #=> "color: red; margin: 10px !important;"
+
+    # Enable implicit string conversion for comparisons
+    alias to_str to_s
+
+    # Convert to a hash of property => value pairs.
+    #
+    # Values include !important suffix if present.
+    #
+    # @return [Hash<String, String>] Hash of property names to values
+    #
+    # @example
+    #   decls.to_h #=> {"color" => "red", "margin" => "10px !important"}
+    def to_h
+      result = {}
+      each do |property, value, is_important|
+        suffix = is_important ? ' !important' : ''
+        result[property] = "#{value}#{suffix}"
+      end
+      result
+    end
+
+    # Convert to an array of Declaration structs.
+    #
+    # Returns the internal array of Declaration structs, which is useful
+    # for creating Rule objects or passing to C functions.
+    #
+    # @return [Array<Declaration>] Array of Declaration structs
+    def to_a
+      @values
+    end
+
+    # Merge another set of declarations into this one (mutating).
+    #
+    # Properties from the other declarations will overwrite properties in this one.
+    # The !important flag is preserved during merge.
+    #
+    # @param other [Declarations, Hash] Declarations to merge in
+    # @return [self] Returns self for method chaining
+    # @raise [ArgumentError] If other is not Declarations or Hash
+    #
+    # @example
+    #   decls1 = Cataract::Declarations.new('color' => 'red')
+    #   decls2 = Cataract::Declarations.new('margin' => '10px')
+    #   decls1.merge!(decls2)
+    #   decls1.to_h #=> {"color" => "red", "margin" => "10px"}
+    def merge!(other)
+      case other
+      when Declarations
+        other.each { |prop, value, important| self[prop] = important ? "#{value} !important" : value }
+      when Hash
+        other.each { |prop, value| self[prop] = value }
+      else
+        raise ArgumentError, 'Can only merge Declarations or Hash objects'
+      end
+      self
+    end
+
+    # Merge another set of declarations (non-mutating).
+    #
+    # Creates a copy of this Declarations object and merges the other into it.
+    #
+    # @param other [Declarations, Hash] Declarations to merge
+    # @return [Declarations] New Declarations with merged properties
+    #
+    # @example
+    #   decls1 = Cataract::Declarations.new('color' => 'red')
+    #   decls2 = Cataract::Declarations.new('margin' => '10px')
+    #   merged = decls1.merge(decls2)
+    #   merged.to_h #=> {"color" => "red", "margin" => "10px"}
+    #   decls1.to_h #=> {"color" => "red"} (unchanged)
+    def merge(other)
+      dup.merge!(other)
+    end
+
+    # Create a shallow copy of this Declarations object.
+    #
+    # @return [Declarations] New Declarations with copied properties
+    def dup
+      new_decl = self.class.new
+      each { |prop, value, important| new_decl[prop] = important ? "#{value} !important" : value }
+      new_decl
+    end
+
+    # Compare this Declarations with another object.
+    #
+    # @param other [Declarations, String] Object to compare with
+    # @return [Boolean] true if equal
+    #
+    # @example
+    #   decls1 = Cataract::Declarations.new('color' => 'red')
+    #   decls2 = Cataract::Declarations.new('color' => 'red')
+    #   decls1 == decls2 #=> true
+    #   decls1 == "color: red;" #=> true (string comparison)
+    def ==(other)
+      case other
+      when Declarations
+        # Compare arrays of Declaration structs
+        to_a == other.to_a
+      when String
+        # Allow string comparison for convenience
+        to_s == other
+      else
+        false
+      end
+    end
+
+    private
+
+    # Normalize user-provided property names for case-insensitive lookup
+    # Note: Properties from C parser are already normalized
+    def normalize_property(property)
+      property.to_s.strip.downcase
+    end
+
+    # Find a Value struct by normalized property name
+    def find_value(normalized_property)
+      @values.find { |v| v.property == normalized_property }
+    end
+
+    # Parse "color: red; background: blue" string into array of Declaration structs
+    def parse_declaration_string(str)
+      Cataract.parse_declarations(str)
+    end
+  end
+end

data/lib/cataract/import_resolver.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'open-uri'
+require 'set'
+
+module Cataract
+  # Error raised during import resolution
+  class ImportError < Error; end
+
+  # Resolves @import statements in CSS
+  # Handles fetching imported files and inlining them with proper security controls
+  module ImportResolver
+    # Default options for safe import resolution
+    SAFE_DEFAULTS = {
+      max_depth: 5,                      # Prevent infinite recursion
+      allowed_schemes: ['https'],        # Only HTTPS by default
+      extensions: ['css'],               # Only .css files
+      timeout: 10,                       # 10 second timeout for fetches
+      follow_redirects: true,            # Follow redirects
+      base_path: nil                     # Base path for resolving relative imports
+    }.freeze
+
+    # Resolve @import statements in CSS
+    #
+    # @param css [String] CSS content with @import statements
+    # @param options [Hash] Import resolution options
+    # @param depth [Integer] Current recursion depth (internal)
+    # @param imported_urls [Set] Set of already imported URLs to prevent circular references
+    # @return [String] CSS with imports inlined
+    def self.resolve(css, options = {}, depth: 0, imported_urls: Set.new)
+      # Normalize options
+      opts = normalize_options(options)
+
+      # Check recursion depth
+      # depth starts at 0, max_depth is count of imports allowed
+      # depth 0: parsing main file (counts as import 1)
+      # depth 1: parsing first @import  (counts as import 2)
+      # depth 2: parsing nested @import (counts as import 3)
+      if depth > opts[:max_depth]
+        raise ImportError, "Import nesting too deep: exceeded maximum depth of #{opts[:max_depth]}"
+      end
+
+      # Find all @import statements at the top of the file
+      # Per CSS spec, @import must come before all rules except @charset
+      imports = extract_imports(css)
+
+      return css if imports.empty?
+
+      # Process each import
+      resolved_css = +'' # Mutable string
+      remaining_css = css
+
+      imports.each do |import_data|
+        url = import_data[:url]
+        media = import_data[:media]
+
+        # Validate URL
+        validate_url(url, opts)
+
+        # Check for circular references
+        raise ImportError, "Circular import detected: #{url}" if imported_urls.include?(url)
+
+        # Fetch imported CSS
+        imported_css = fetch_url(url, opts)
+
+        # Recursively resolve imports in the imported CSS
+        imported_urls_copy = imported_urls.dup
+        imported_urls_copy.add(url)
+        imported_css = resolve(imported_css, opts, depth: depth + 1, imported_urls: imported_urls_copy)
+
+        # Wrap in @media if import had media query
+        imported_css = "@media #{media} {\n#{imported_css}\n}" if media
+
+        resolved_css << imported_css << "\n"
+
+        # Remove this import from remaining CSS
+        remaining_css = remaining_css.sub(import_data[:full_match], '')
+      end
+
+      # Return resolved imports + remaining CSS
+      resolved_css + remaining_css
+    end
+
+    # Normalize options with safe defaults
+    def self.normalize_options(options)
+      if options == true
+        # imports: true -> use safe defaults
+        SAFE_DEFAULTS.dup
+      elsif options.is_a?(Hash)
+        # imports: { ... } -> merge with safe defaults
+        SAFE_DEFAULTS.merge(options)
+      else
+        raise ArgumentError, 'imports option must be true or a Hash'
+      end
+    end
+
+    # Extract @import statements from CSS
+    # Returns array of hashes: { url: "...", media: "...", full_match: "..." }
+    # Delegates to C implementation for performance
+    def self.extract_imports(css)
+      Cataract.extract_imports(css)
+    end
+
+    # Normalize URL - handle relative paths and missing schemes
+    # Returns a URI object
+    def self.normalize_url(url, base_path = nil)
+      # Try to parse as-is first
+      uri = URI.parse(url)
+
+      # If no scheme, treat as relative file path
+      if uri.scheme.nil?
+        # Convert to file:// URL
+        # Relative paths stay relative, absolute paths stay absolute
+        if url.start_with?('/')
+          uri = URI.parse("file://#{url}")
+        else
+          # Relative path - make it absolute relative to base_path or current directory
+          absolute_path = if base_path
+                            File.expand_path(url, base_path)
+                          else
+                            File.expand_path(url)
+                          end
+          uri = URI.parse("file://#{absolute_path}")
+        end
+      end
+
+      uri
+    rescue URI::InvalidURIError => e
+      raise ImportError, "Invalid import URL: #{url} (#{e.message})"
+    end
+
+    # Validate URL against security options
+    def self.validate_url(url, options)
+      uri = normalize_url(url, options[:base_path])
+
+      # Check scheme
+      unless options[:allowed_schemes].include?(uri.scheme)
+        raise ImportError,
+              "Import scheme '#{uri.scheme}' not allowed. Allowed schemes: #{options[:allowed_schemes].join(', ')}"
+      end
+
+      # Check extension
+      path = uri.path || ''
+      ext = File.extname(path).delete_prefix('.')
+
+      unless ext.empty? || options[:extensions].include?(ext)
+        raise ImportError,
+              "Import extension '.#{ext}' not allowed. Allowed extensions: #{options[:extensions].join(', ')}"
+      end
+
+      # Additional security checks for file:// scheme
+      if uri.scheme == 'file'
+        # Resolve to absolute path to prevent directory traversal
+        file_path = uri.path
+
+        # Check file exists and is readable
+        unless File.exist?(file_path) && File.readable?(file_path)
+          raise ImportError, "Import file not found or not readable: #{file_path}"
+        end
+
+        # Prevent reading sensitive files (basic check)
+        dangerous_paths = ['/etc/', '/proc/', '/sys/', '/dev/']
+        if dangerous_paths.any? { |prefix| file_path.start_with?(prefix) }
+          raise ImportError, "Import of sensitive system files not allowed: #{file_path}"
+        end
+      end
+
+      true
+    rescue URI::InvalidURIError => e
+      raise ImportError, "Invalid import URL: #{url} (#{e.message})"
+    end
+
+    # Fetch content from URL
+    def self.fetch_url(url, options)
+      uri = normalize_url(url, options[:base_path])
+
+      case uri.scheme
+      when 'file'
+        # Read from local filesystem
+        File.read(uri.path)
+      when 'http', 'https'
+        # Fetch from network
+        fetch_http(uri, options)
+      else
+        raise ImportError, "Unsupported scheme: #{uri.scheme}"
+      end
+    rescue Errno::ENOENT
+      raise ImportError, "Import file not found: #{url}"
+    rescue OpenURI::HTTPError => e
+      raise ImportError, "HTTP error fetching import: #{url} (#{e.message})"
+    rescue SocketError => e
+      raise ImportError, "Network error fetching import: #{url} (#{e.message})"
+    rescue StandardError => e
+      raise ImportError, "Error fetching import: #{url} (#{e.class}: #{e.message})"
+    end
+
+    # Fetch content via HTTP/HTTPS
+    def self.fetch_http(uri, options)
+      # Use open-uri with timeout
+      open_uri_options = {
+        read_timeout: options[:timeout],
+        redirect: options[:follow_redirects]
+      }
+
+      # Use uri.open instead of URI.open to avoid shell command injection
+      uri.open(open_uri_options, &:read)
+    end
+  end
+end