cataract 0.1.0

data/lib/cataract/stylesheet_scope.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Cataract
+  # Chainable query scope for filtering Stylesheet rules.
+  #
+  # Inspired by ActiveRecord's Relation, StylesheetScope provides a fluent
+  # interface for filtering and querying CSS rules. Scopes are lazy - filters
+  # are only applied during iteration.
+  #
+  # @example Chaining filters
+  #   sheet.with_media(:print).with_specificity(10..).select(&:selector?)
+  #
+  # @example Inspect shows results
+  #   scope = sheet.with_media(:screen)
+  #   scope.inspect #=> "#<Cataract::StylesheetScope [...]>"
+  class StylesheetScope
+    include Enumerable
+
+    # @private
+    def initialize(stylesheet, filters = {})
+      @stylesheet = stylesheet
+      @filters = filters
+    end
+
+    # Filter by media query symbol(s).
+    #
+    # @param media [Symbol, Array<Symbol>] Media query symbol(s)
+    # @return [StylesheetScope] New scope with media filter applied
+    #
+    # @example
+    #   sheet.with_media(:print).with_media(:screen) # overwrites to :screen
+    def with_media(media)
+      StylesheetScope.new(@stylesheet, @filters.merge(media: media))
+    end
+
+    # Filter by CSS specificity.
+    #
+    # @param specificity [Integer, Range] Specificity value or range
+    # @return [StylesheetScope] New scope with specificity filter applied
+    #
+    # @example
+    #   sheet.with_specificity(10)      # exactly 10
+    #   sheet.with_specificity(10..)    # 10 or higher
+    #   sheet.with_specificity(5...10)  # between 5 and 9
+    def with_specificity(specificity)
+      StylesheetScope.new(@stylesheet, @filters.merge(specificity: specificity))
+    end
+
+    # Filter by CSS selector.
+    #
+    # @param selector [String, Regexp] CSS selector to match (exact string or pattern)
+    # @return [StylesheetScope] New scope with selector filter applied
+    #
+    # @example Exact string match
+    #   sheet.with_selector('body')
+    #   sheet.with_media(:print).with_selector('.header')
+    #
+    # @example Pattern matching
+    #   sheet.with_selector(/\.btn-/)  # All .btn-* classes
+    #   sheet.with_selector(/^#/)      # All ID selectors
+    def with_selector(selector)
+      StylesheetScope.new(@stylesheet, @filters.merge(selector: selector))
+    end
+
+    # Filter by CSS property name and optional value.
+    #
+    # @param property [String] CSS property name to match
+    # @param value [String, nil] Optional property value to match
+    # @return [StylesheetScope] New scope with property filter applied
+    #
+    # @example Find rules with color property
+    #   sheet.with_property('color')
+    #
+    # @example Find rules with specific property value
+    #   sheet.with_property('position', 'absolute')
+    #   sheet.with_property('color', 'red')
+    def with_property(property, value = nil)
+      StylesheetScope.new(@stylesheet, @filters.merge(property: property, property_value: value))
+    end
+
+    # Filter to only base rules (rules not inside any @media query).
+    #
+    # @return [StylesheetScope] New scope with base_only filter applied
+    #
+    # @example Get base rules only
+    #   sheet.base_only.map(&:selector)
+    #   sheet.base_only.with_property('color').to_a
+    def base_only
+      StylesheetScope.new(@stylesheet, @filters.merge(base_only: true))
+    end
+
+    # Filter by at-rule type.
+    #
+    # @param type [Symbol] At-rule type to match (:keyframes, :font_face, etc.)
+    # @return [StylesheetScope] New scope with at-rule type filter applied
+    #
+    # @example Find all @keyframes
+    #   sheet.with_at_rule_type(:keyframes)
+    #
+    # @example Find all @font-face
+    #   sheet.with_at_rule_type(:font_face)
+    def with_at_rule_type(type)
+      StylesheetScope.new(@stylesheet, @filters.merge(at_rule_type: type))
+    end
+
+    # Filter to rules with !important declarations.
+    #
+    # @param property [String, nil] Optional property name to match
+    # @return [StylesheetScope] New scope with important filter applied
+    #
+    # @example Find all rules with any !important
+    #   sheet.with_important
+    #
+    # @example Find rules with color !important
+    #   sheet.with_important('color')
+    def with_important(property = nil)
+      StylesheetScope.new(@stylesheet, @filters.merge(important: true, important_property: property))
+    end
+
+    # Iterate over filtered rules.
+    #
+    # @yield [rule] Each rule matching the filters
+    # @yieldparam rule [Rule, AtRule] The rule object
+    # @return [Enumerator] Enumerator if no block given
+    def each
+      return enum_for(:each) unless block_given?
+
+      # Get base rules set
+      rules = if @filters[:base_only]
+                # Get rules not in any media query
+                media_index = @stylesheet.instance_variable_get(:@_media_index)
+                media_rule_ids = media_index.values.flatten.uniq
+                @stylesheet.rules.select.with_index { |_rule, idx| !media_rule_ids.include?(idx) }
+              elsif @filters[:media]
+                media_array = Array(@filters[:media])
+
+                # :all is a special case meaning "all rules"
+                if media_array.include?(:all)
+                  @stylesheet.rules
+                else
+                  media_index = @stylesheet.instance_variable_get(:@_media_index)
+                  rule_ids = media_array.flat_map { |m| media_index[m] || [] }.uniq
+                  rule_ids.map { |id| @stylesheet.rules[id] }
+                end
+              else
+                @stylesheet.rules
+              end
+
+      # Apply additional filters during iteration
+      rules.each do |rule|
+        # Specificity filter
+        if @filters[:specificity]
+          next if rule.specificity.nil? # AtRules have nil specificity
+          next unless case @filters[:specificity]
+                      when Range
+                        @filters[:specificity].cover?(rule.specificity)
+                      else
+                        @filters[:specificity] == rule.specificity
+                      end
+        end
+
+        # Selector filter (String or Regexp)
+        if @filters[:selector] && !case @filters[:selector]
+                                   when String
+                                     rule.selector == @filters[:selector]
+                                   when Regexp
+                                     @filters[:selector] =~ rule.selector
+                                   end
+          next
+        end
+
+        # Property filter
+        if @filters[:property] && !rule.has_property?(@filters[:property], @filters[:property_value])
+          next
+        end
+
+        # At-rule type filter
+        if @filters[:at_rule_type] && !rule.at_rule_type?(@filters[:at_rule_type])
+          next
+        end
+
+        # Important filter
+        if @filters[:important] && !rule.has_important?(@filters[:important_property])
+          next
+        end
+
+        yield rule
+      end
+    end
+
+    # Get the number of rules matching the filters.
+    #
+    # Forces evaluation of the scope.
+    #
+    # @return [Integer] Number of matching rules
+    def size
+      to_a.size
+    end
+    alias length size
+
+    # Access a rule by index.
+    #
+    # Forces evaluation of the scope.
+    #
+    # @param index [Integer] Index of the rule to access
+    # @return [Rule, AtRule, nil] Rule at the given index, or nil
+    def [](index)
+      to_a[index]
+    end
+
+    # Check if the scope has no matching rules.
+    #
+    # Forces evaluation of the scope.
+    #
+    # @return [Boolean] true if no rules match the filters
+    def empty?
+      to_a.empty?
+    end
+
+    # Compare the scope to another object.
+    #
+    # Forces evaluation of the scope and compares as an array.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if equal
+    def ==(other)
+      to_a == other
+    end
+
+    # Implicit conversion to Array for Ruby coercion.
+    #
+    # This allows StylesheetScope to be used transparently as an Array
+    # in comparisons and other operations.
+    #
+    # @return [Array] Array of matching rules
+    # @api private
+    def to_ary
+      to_a
+    end
+
+    # Human-readable representation showing filtered results.
+    #
+    # Forces evaluation of the scope and displays results.
+    #
+    # @return [String] Inspection string
+    def inspect
+      rules = to_a
+      if rules.empty?
+        '#<Cataract::StylesheetScope []>'
+      else
+        preview = rules.first(3).map(&:selector).join(', ')
+        more = rules.length > 3 ? ', ...' : ''
+        "#<Cataract::StylesheetScope [#{preview}#{more}] (#{rules.length} rules)>"
+      end
+    end
+  end
+end

data/lib/cataract/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cataract
+  VERSION = '0.1.0'
+end

data/lib/cataract.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative 'cataract/version'
+require_relative 'cataract/cataract' # Load C extension (defines Rule, Declaration, AtRule structs)
+require_relative 'cataract/rule' # Add Ruby methods to Rule
+require_relative 'cataract/at_rule' # Add Ruby methods to AtRule
+require_relative 'cataract/stylesheet_scope'
+require_relative 'cataract/stylesheet'
+require_relative 'cataract/declarations'
+require_relative 'cataract/import_resolver'
+
+# Cataract is a high-performance CSS parser written in C with a Ruby interface.
+#
+# It provides fast CSS parsing, rule querying, cascade merging, and serialization.
+# Designed for performance-critical applications that need to process large amounts of CSS.
+#
+# @example Basic usage
+#   require 'cataract'
+#
+#   # Parse CSS
+#   sheet = Cataract.parse_css("body { color: red; } h1 { color: blue; }")
+#
+#   # Query rules
+#   sheet.select(&:selector?).each { |rule| puts "#{rule.selector}: #{rule.declarations}" }
+#
+#   # Merge with cascade rules
+#   merged = sheet.merge
+#
+# @see Stylesheet Main class for working with parsed CSS
+# @see Rule Represents individual CSS rules
+module Cataract
+  class << self
+    # Parse a CSS string into a Stylesheet object.
+    #
+    # This is the main entry point for parsing CSS. It returns a Stylesheet
+    # object that can be queried, modified, and serialized.
+    #
+    # @param css [String] The CSS string to parse
+    # @param imports [Boolean, Hash] Whether to resolve @import statements.
+    #   Pass true to enable with defaults, or a hash with options:
+    #   - allowed_schemes: Array of allowed URI schemes (default: ['https'])
+    #   - extensions: Array of allowed file extensions (default: ['css'])
+    #   - max_depth: Maximum import nesting depth (default: 5)
+    #   - base_path: Base directory for resolving relative imports
+    # @return [Stylesheet] A new Stylesheet containing the parsed CSS rules
+    # @raise [IOError] If import resolution fails and io_exceptions option is enabled
+    #
+    # @example Parse simple CSS
+    #   sheet = Cataract.parse_css("body { color: red; }")
+    #   sheet.size #=> 1
+    #
+    # @example Parse with imports
+    #   sheet = Cataract.parse_css("@import 'style.css';", imports: true)
+    #
+    # @example Parse with import options
+    #   sheet = Cataract.parse_css(css, imports: {
+    #     allowed_schemes: ['https', 'file'],
+    #     base_path: '/path/to/css'
+    #   })
+    #
+    # @see Stylesheet#parse
+    # @see Stylesheet.parse
+    def parse_css(css, imports: false)
+      # Resolve @import statements if requested
+      css = ImportResolver.resolve(css, imports) if imports
+
+      Stylesheet.parse(css)
+    end
+
+    # Merge CSS rules according to CSS cascade rules.
+    #
+    # Takes a Stylesheet or CSS string and merges all rules according to CSS cascade
+    # precedence rules. Returns a new Stylesheet with a single merged rule containing
+    # the final computed declarations.
+    #
+    # @param stylesheet_or_css [Stylesheet, String] The stylesheet to merge, or a CSS string to parse and merge
+    # @return [Stylesheet] A new Stylesheet with merged rules
+    #
+    # Merge rules (in order of precedence):
+    # 1. !important declarations win over non-important
+    # 2. Higher specificity wins
+    # 3. Later declarations with same specificity and importance win
+    # 4. Shorthand properties are created from longhand when possible (e.g., margin-* -> margin)
+    #
+    # @example Merge a stylesheet
+    #   sheet = Cataract.parse_css(".test { color: red; } #test { color: blue; }")
+    #   merged = Cataract.merge(sheet)
+    #   merged.rules.first.declarations #=> [#<Declaration property="color" value="blue" important=false>]
+    #
+    # @example Merge with !important
+    #   sheet = Cataract.parse_css(".test { color: red !important; } #test { color: blue; }")
+    #   merged = Cataract.merge(sheet)
+    #   merged.rules.first.declarations #=> [#<Declaration property="color" value="red" important=true>]
+    #
+    # @example Shorthand creation
+    #   css = ".test { margin-top: 10px; margin-right: 10px; margin-bottom: 10px; margin-left: 10px; }"
+    #   merged = Cataract.merge(Cataract.parse_css(css))
+    #   # merged contains single "margin: 10px" declaration instead of four longhand properties
+    #
+    # @note This is a module-level convenience method. The same functionality is available
+    #   as an instance method: `stylesheet.merge`
+    # @note Implemented in C (see ext/cataract/merge.c)
+    #
+    # @see Stylesheet#merge
+    # Cataract.merge is defined in C via rb_define_module_function
+  end
+end

data/lib/tasks/gem.rake

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Gem release tasks
+namespace :gem do
+  desc 'Prepare gem for release (compile, test, lint)'
+  task prep: %i[compile test lint] do
+    puts "\n#{'=' * 80}"
+    puts '✓ Gem preparation complete!'
+    puts '  - Code compiled successfully'
+    puts '  - All tests passed'
+    puts '  - Linting passed'
+    puts '=' * 80
+    puts "\nReady for release! Next steps:"
+    puts '  1. Update version in lib/cataract/version.rb'
+    puts '  2. Update CHANGELOG.md'
+    puts '  3. Commit changes: git commit -am "Release vX.Y.Z"'
+    puts '  4. Run: rake release (creates tag, builds gem, pushes to rubygems)'
+    puts '=' * 80
+  end
+
+  desc 'Build and test gem locally (sanity check before release)'
+  task build_test: :build do
+    require_relative '../cataract/version'
+    version = Cataract::VERSION
+    gem_file = "pkg/cataract-#{version}.gem"
+
+    puts "\nTesting gem installation locally..."
+    sh "gem install #{gem_file} --local"
+
+    puts "\nRunning smoke test..."
+    ruby_code = <<~RUBY
+      require 'cataract'
+      sheet = Cataract::Stylesheet.parse('body { color: red; }')
+      raise 'Smoke test failed!' unless sheet.rules_count == 1
+      puts '✓ Smoke test passed'
+    RUBY
+    sh "ruby -e \"#{ruby_code}\""
+
+    puts "\n✓ Local gem test successful: #{gem_file}"
+    puts "\nTo release, run: rake release"
+  end
+
+  desc 'Bump version (usage: rake gem:bump[major|minor|patch])'
+  task :bump, [:type] do |_t, args|
+    type = args[:type] || 'patch'
+    unless %w[major minor patch].include?(type)
+      abort "Invalid version bump type: #{type}. Use: major, minor, or patch"
+    end
+
+    version_file = 'lib/cataract/version.rb'
+    content = File.read(version_file)
+
+    # Extract current version
+    current_version = content[/VERSION = ['"](.+?)['"]/, 1]
+    major, minor, patch = current_version.split('.').map(&:to_i)
+
+    # Bump version
+    case type
+    when 'major'
+      major += 1
+      minor = 0
+      patch = 0
+    when 'minor'
+      minor += 1
+      patch = 0
+    when 'patch'
+      patch += 1
+    end
+
+    new_version = "#{major}.#{minor}.#{patch}"
+
+    # Update file
+    new_content = content.gsub(/VERSION = ['"]#{Regexp.escape(current_version)}['"]/, "VERSION = '#{new_version}'")
+    File.write(version_file, new_content)
+
+    puts "Version bumped: #{current_version} → #{new_version}"
+    puts "\nNext steps:"
+    puts "  1. Review changes: git diff #{version_file}"
+    puts '  2. Update CHANGELOG.md'
+    puts "  3. Commit: git commit -am 'Bump version to #{new_version}'"
+  end
+
+  desc 'Prepare release commit (prep, bump version, commit)'
+  task :release_commit, [:type] => :prep do |_t, args|
+    type = args[:type] || 'patch'
+
+    # Check for uncommitted changes (ignore untracked files)
+    modified_files = `git status --porcelain`.lines.reject { |line| line.start_with?('??') }
+    unless modified_files.empty?
+      abort 'ERROR: Working directory has uncommitted changes. Commit or stash them first.'
+    end
+
+    # Check we're on main branch
+    current_branch = `git rev-parse --abbrev-ref HEAD`.strip
+    unless current_branch == 'main'
+      puts "WARNING: You're on branch '#{current_branch}', not 'main'"
+      print 'Continue anyway? (y/N): '
+      response = $stdin.gets.chomp
+      abort 'Aborted.' unless response.downcase == 'y'
+    end
+
+    # Bump version
+    Rake::Task['gem:bump'].invoke(type)
+
+    # Reload version
+    load 'lib/cataract/version.rb'
+    new_version = Cataract::VERSION
+
+    # Auto-generate CHANGELOG with git-cliff
+    puts "\n#{'=' * 80}"
+    puts 'Generating CHANGELOG.md with git-cliff...'
+    puts '=' * 80
+
+    if system('which git-cliff > /dev/null 2>&1')
+      sh "git-cliff --tag v#{new_version} --output CHANGELOG.md"
+      puts '✓ CHANGELOG.md generated'
+
+      # Show the changelog for review
+      puts "\nGenerated CHANGELOG (preview):"
+      puts '-' * 80
+      system('head -n 50 CHANGELOG.md')
+      puts '-' * 80
+
+      print "\nAccept this CHANGELOG? (Y/n): "
+      response = $stdin.gets.chomp
+      abort 'Aborted. Edit CHANGELOG.md manually if needed.' if response.downcase == 'n'
+    else
+      puts 'WARNING: git-cliff not found. Please update CHANGELOG.md manually.'
+      puts 'Install: cargo install git-cliff'
+      puts "\nPress Enter when ready to commit..."
+      $stdin.gets
+
+      # Check if CHANGELOG was actually updated
+      changelog_diff = `git diff CHANGELOG.md`
+      if changelog_diff.strip.empty?
+        puts 'WARNING: CHANGELOG.md was not modified'
+        print 'Continue anyway? (y/N): '
+        response = $stdin.gets.chomp
+        abort 'Aborted. Please update CHANGELOG.md first.' unless response.downcase == 'y'
+      end
+    end
+
+    # Commit changes with Release Bot as author
+    commit_message = "Release v#{new_version}"
+    git_email = `git config user.email`.strip
+    sh 'git add lib/cataract/version.rb CHANGELOG.md'
+    sh "git commit --author 'Release Bot <#{git_email}>' -m '#{commit_message}'"
+
+    puts "\n#{'=' * 80}"
+    puts "✓ Release commit created: #{commit_message}"
+    puts '=' * 80
+    puts "\nNext steps:"
+    puts '  1. Review commit: git show'
+    puts '  2. Push to GitHub: git push'
+    puts '  3. Create release: rake release (builds gem, creates tag, pushes to rubygems)'
+    puts '=' * 80
+  end
+end