cataract 0.1.0

data/examples/css_analyzer/analyzers/colors.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CSSAnalyzer
+  module Analyzers
+    # Analyzes color usage in CSS
+    class Colors < Base
+      # Color properties to search for
+      COLOR_PROPERTIES = %w[
+        color
+        background-color
+        border-color
+        border-top-color
+        border-right-color
+        border-bottom-color
+        border-left-color
+        outline-color
+        text-decoration-color
+        column-rule-color
+        fill
+        stroke
+      ].freeze
+
+      def analyze
+        color_counts = Hash.new(0)
+        color_examples = Hash.new { |h, k| h[k] = [] }
+
+        # Iterate through all rules
+        stylesheet.rules.each do |rule|
+          # Skip AtRules (like @keyframes) - they don't have declarations
+          next unless rule.is_a?(Cataract::Rule)
+
+          selector = rule.selector
+          media_types = media_queries_for_rule(rule)
+
+          # Check each declaration for color values
+          rule.declarations.each do |decl|
+            property = decl.property
+            value = decl.value
+
+            next unless COLOR_PROPERTIES.include?(property)
+
+            # Extract color values from the declaration
+            colors = extract_colors(value)
+
+            colors.each do |color|
+              normalized = normalize_color(color)
+              color_counts[normalized] += 1
+
+              # Store example (limit to 3 per color)
+              next unless color_examples[normalized].length < 3
+
+              color_examples[normalized] << {
+                property: property,
+                original_value: color,
+                selector: selector,
+                media: media_types
+              }
+            end
+          end
+        end
+
+        # Sort by frequency
+        sorted_colors = color_counts.sort_by { |_color, count| -count }
+
+        {
+          total_colors: color_counts.values.sum,
+          unique_colors: color_counts.size,
+          colors: sorted_colors.map do |color, count|
+            {
+              color: color,
+              count: count,
+              percentage: (count.to_f / color_counts.values.sum * 100).round(1),
+              examples: color_examples[color],
+              hex: color_to_hex(color)
+            }
+          end
+        }
+      end
+
+      private
+
+      # Extract color values from a CSS value string
+      # Handles: hex, rgb(), rgba(), hsl(), hsla(), named colors
+      def extract_colors(value)
+        colors = []
+
+        # Hex colors: #fff, #ffffff, #ffffffff
+        colors += value.scan(/#[0-9a-fA-F]{3,8}\b/)
+
+        # rgb/rgba: rgb(255, 255, 255), rgba(255, 255, 255, 0.5)
+        colors += value.scan(/rgba?\([^)]+\)/)
+
+        # hsl/hsla: hsl(120, 100%, 50%), hsla(120, 100%, 50%, 0.5)
+        colors += value.scan(/hsla?\([^)]+\)/)
+
+        # Named colors (basic set - extend as needed)
+        named_colors = %w[
+          transparent currentcolor inherit
+          black white red green blue yellow orange purple pink
+          gray grey silver maroon olive lime aqua teal navy fuchsia
+        ]
+        named_colors.each do |named|
+          colors << named if value.downcase.include?(named)
+        end
+
+        colors.uniq
+      end
+
+      # Normalize color to lowercase for grouping
+      def normalize_color(color)
+        color.downcase.strip
+      end
+
+      # Convert color to hex for display (best effort)
+      def color_to_hex(color)
+        # If already hex, return as-is
+        return color if color.start_with?('#')
+
+        # For rgb/rgba, try to extract and convert
+        if color.start_with?('rgb')
+          # Simple extraction - just return the color for now
+          # In future, could parse and convert to hex
+          return color
+        end
+
+        # For named colors, return as-is (browser will handle)
+        color
+      end
+    end
+  end
+end

data/examples/css_analyzer/analyzers/important.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CSSAnalyzer
+  module Analyzers
+    # Analyzes !important usage in CSS
+    class Important < Base
+      def analyze
+        total_declarations = 0
+        important_count = 0
+        important_by_property = Hash.new(0)
+        important_by_selector = Hash.new(0)
+        important_examples = []
+
+        # Iterate through all rules
+        stylesheet.rules.each do |rule|
+          # Skip AtRules (like @keyframes) - they don't have declarations
+          next unless rule.is_a?(Cataract::Rule)
+
+          selector = rule.selector
+          media_types = media_queries_for_rule(rule)
+          selector_important_count = 0
+
+          rule.declarations.each do |decl|
+            property = decl.property
+            value = decl.value
+            important = decl.important
+
+            total_declarations += 1
+
+            next unless important
+
+            important_count += 1
+            important_by_property[property] += 1
+            selector_important_count += 1
+
+            important_examples << {
+              selector: selector,
+              property: property,
+              value: value,
+              media: media_types
+            }
+          end
+
+          if selector_important_count.positive?
+            important_by_selector[selector] = selector_important_count
+          end
+        end
+
+        # Sort properties by !important usage
+        top_properties = important_by_property.sort_by { |_prop, count| -count }.first(20)
+
+        # Sort selectors by !important count
+        top_selectors = important_by_selector.sort_by { |_sel, count| -count }.first(20)
+
+        # Calculate percentage
+        important_percentage = if total_declarations.positive?
+                                 (important_count.to_f / total_declarations * 100).round(1)
+                               else
+                                 0.0
+                               end
+
+        {
+          total_declarations: total_declarations,
+          important_count: important_count,
+          important_percentage: important_percentage,
+          properties_using_important: important_by_property.size,
+          selectors_using_important: important_by_selector.size,
+          top_properties: top_properties.map do |prop, count|
+            {
+              property: prop,
+              count: count,
+              percentage: (count.to_f / important_count * 100).round(1)
+            }
+          end,
+          top_selectors: top_selectors.map do |selector, count|
+            {
+              selector: selector,
+              count: count
+            }
+          end,
+          all_important: important_examples
+        }
+      end
+    end
+  end
+end

data/examples/css_analyzer/analyzers/properties.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CSSAnalyzer
+  module Analyzers
+    # Analyzes CSS property usage frequency
+    class Properties < Base
+      def analyze
+        property_counts = Hash.new(0)
+        property_examples = Hash.new { |h, k| h[k] = [] }
+
+        # Iterate through all rules
+        stylesheet.rules.each do |rule|
+          # Skip AtRules (like @keyframes) - they don't have declarations
+          next unless rule.is_a?(Cataract::Rule)
+
+          selector = rule.selector
+          media_types = media_queries_for_rule(rule)
+
+          # Iterate through declarations
+          # Each declaration is a struct with property, value, important
+          rule.declarations.each do |decl|
+            property = decl.property
+            value = decl.value
+            important = decl.important
+
+            property_counts[property] += 1
+
+            # Store example (limit to 3 examples per property)
+            next unless property_examples[property].length < 3
+
+            property_examples[property] << {
+              value: value,
+              important: important,
+              selector: selector,
+              media: media_types
+            }
+          end
+        end
+
+        # Sort by frequency and take top N
+        top_n = options[:top] || 20
+        top_properties = property_counts.sort_by { |_prop, count| -count }.first(top_n)
+
+        {
+          total_properties: property_counts.values.sum,
+          unique_properties: property_counts.size,
+          top_properties: top_properties.map do |property, count|
+            {
+              name: property,
+              count: count,
+              percentage: (count.to_f / property_counts.values.sum * 100).round(1),
+              examples: property_examples[property]
+            }
+          end
+        }
+      end
+    end
+  end
+end

data/examples/css_analyzer/analyzers/specificity.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CSSAnalyzer
+  module Analyzers
+    # Analyzes CSS selector specificity
+    class Specificity < Base
+      def analyze
+        specificity_data = []
+        specificity_histogram = Hash.new(0)
+
+        # Iterate through all rules
+        stylesheet.rules.each do |rule|
+          # Skip AtRules (like @keyframes) - they don't have specificity like regular rules
+          next unless rule.is_a?(Cataract::Rule)
+
+          spec = rule.specificity
+          media_types = media_queries_for_rule(rule)
+          specificity_histogram[spec] += 1
+
+          specificity_data << {
+            selector: rule.selector,
+            specificity: spec,
+            media: media_types,
+            declaration_count: rule.declarations.length
+          }
+        end
+
+        # Sort by specificity (highest first)
+        sorted_by_spec = specificity_data.sort_by { |r| -r[:specificity] }
+
+        # Calculate statistics
+        specificities = specificity_data.map { |r| r[:specificity] }
+        avg_specificity = specificities.sum.to_f / specificities.length
+        max_specificity = specificities.max
+        min_specificity = specificities.min
+
+        # Categorize selectors by specificity ranges
+        # Specificity guide:
+        #   0-10: Element selectors (div, p, etc)
+        #   11-100: Class selectors (.class)
+        #   101-1000: ID selectors (#id)
+        #   1000+: Inline styles or many IDs
+        categories = {
+          low: specificity_data.count { |r| r[:specificity] <= 10 },
+          medium: specificity_data.count { |r| r[:specificity] > 10 && r[:specificity] <= 100 },
+          high: specificity_data.count { |r| r[:specificity] > 100 && r[:specificity] <= 1000 },
+          very_high: specificity_data.count { |r| r[:specificity] > 1000 }
+        }
+
+        # Find problematic selectors (high specificity)
+        high_specificity = sorted_by_spec.select { |r| r[:specificity] > 100 }
+
+        {
+          total_selectors: specificity_data.length,
+          average_specificity: avg_specificity.round(1),
+          max_specificity: max_specificity,
+          min_specificity: min_specificity,
+          categories: categories,
+          top_20_highest: sorted_by_spec.first(20),
+          high_specificity_count: high_specificity.length,
+          histogram: specificity_histogram.sort_by { |spec, _count| -spec }.first(20)
+        }
+      end
+    end
+  end
+end