jekyll-imgflow 0.1.9 → 0.2.0

data/lib/jekyll-imgflow/preset_manager.rb

@@ -1,26 +1,51 @@
 # frozen_string_literal: true
 
+require "shellwords"
 require "yaml"
 
 module JekyllImgFlow
   # PresetManager - translates YAML presets to tags:value format
   # Handles tag overrides (user tags override preset tags)
   # Passes combined markup to Parser for uniform validation flow
+  #
+  # Presets are loaded from two sources (user presets take precedence):
+  # 1. Site presets:  _data/imgflow/presets/*.yml  (user-defined, override built-ins)
+  # 2. Built-in presets: lib/jekyll-imgflow/presets/*.yml (shipped with the gem)
   class PresetManager
+    BUILTIN_PRESETS_DIR = File.expand_path("presets", __dir__).freeze
+
     def initialize(site, config)
       @site = site
       @config = config
       @presets = load_presets
     end
 
-    # Load presets from _data/imgflow/presets/
+    # Load presets from the site's _data/imgflow/presets/ directory,
+    # then merge in built-in presets from the gem. User presets override
+    # built-in presets of the same name.
     def load_presets
-      presets = {}
-      presets_dir = File.join(@site.source, "_data", "imgflow", "presets")
+      presets = load_presets_from_dir(builtin_presets_dir)
+      presets.merge(load_presets_from_dir(site_presets_dir))
+    end
 
-      return presets unless Dir.exist?(presets_dir)
+    # Path to built-in presets shipped with the gem
+    def builtin_presets_dir
+      BUILTIN_PRESETS_DIR
+    end
 
-      Dir.glob(File.join(presets_dir, "*.yml")).each do |preset_file|
+    # Path to user-defined presets in the site
+    def site_presets_dir
+      File.join(@site.source, "_data", "imgflow", "presets")
+    end
+
+    # Load all preset YAML files from a directory
+    # @param dir [String] Directory containing *.yml preset files
+    # @return [Hash<String, Hash>] Preset name => preset data
+    def load_presets_from_dir(dir)
+      presets = {}
+      return presets unless dir && Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.yml")).each do |preset_file|
         preset_name = File.basename(preset_file, ".yml")
         begin
           preset_data = YAML.safe_load_file(preset_file)
@@ -48,12 +73,38 @@ module JekyllImgFlow
       @presets.key?(name.to_s)
     end
 
-    # Get all available preset names
+    # Get all available preset names (user + built-in)
     # @return [Array<String>] Array of preset names
     def available_presets
       @presets.keys
     end
 
+    # Get names of built-in presets shipped with the gem
+    # @return [Array<String>] Array of built-in preset names
+    def builtin_preset_names
+      names = []
+      return names unless Dir.exist?(builtin_presets_dir)
+
+      Dir.glob(File.join(builtin_presets_dir, "*.yml")).each do |file|
+        names << File.basename(file, ".yml")
+      end
+      names
+    end
+
+    # Check if a preset is a built-in (shipped with the gem)
+    # @param name [String] Preset name
+    # @return [Boolean] True if the preset is built-in
+    def builtin_preset?(name)
+      builtin_preset_names.include?(name.to_s)
+    end
+
+    # Check if a preset is user-defined (in the site's _data/)
+    # @param name [String] Preset name
+    # @return [Boolean] True if the preset is user-defined
+    def user_preset?(name)
+      File.exist?(File.join(site_presets_dir, "#{name}.yml"))
+    end
+
     # Build markup from preset (tags:value format)
     # @param preset_name [String] Name of preset
     # @param user_options [Hash] User-provided options that override preset values
@@ -143,7 +194,7 @@ module JekyllImgFlow
     # @param tags [Hash] Tags in key => value format
     # @return [String] Markup string
     def tags_to_markup(tags)
-      tags.map { |key, value| "#{key}:#{value}" }.join(" ")
+      tags.map { |key, value| "#{key}:#{Shellwords.escape(value.to_s)}" }.join(" ")
     end
   end
 end

data/lib/jekyll-imgflow/presets/gallery.yml

@@ -0,0 +1,7 @@
+operations:
+  - resize:
+      width: 400
+  - format:
+      formats: ["avif", "webp", "jpg"]
+  - quality:
+      quality: 80

data/lib/jekyll-imgflow/presets/hero.yml

@@ -0,0 +1,7 @@
+operations:
+  - resize:
+      width: 800
+  - format:
+      formats: ["avif", "webp", "jpg"]
+  - quality:
+      quality: 85

data/lib/jekyll-imgflow/presets/thumbnail.yml

@@ -0,0 +1,7 @@
+operations:
+  - resize:
+      width: 150
+  - format:
+      formats: ["webp", "jpg"]
+  - quality:
+      quality: 75

data/lib/jekyll-imgflow/processing_stats.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module JekyllImgFlow
+  # ProcessingStats — collects cache hit/miss, per-operation timing, and
+  # compression ratio metrics during a Jekyll build. Accessed by the
+  # performance benchmark to report beyond wall-clock time.
+  class ProcessingStats
+    attr_reader :cache_hits, :cache_misses, :operation_timings, :compression_ratios
+
+    def initialize
+      @cache_hits = 0
+      @cache_misses = 0
+      @operation_timings = Hash.new { |h, k| h[k] = 0.0 }
+      @compression_ratios = {}
+      @mutex = Mutex.new
+    end
+
+    def record_cache_hit
+      @mutex.synchronize { @cache_hits += 1 }
+    end
+
+    def record_cache_miss
+      @mutex.synchronize { @cache_misses += 1 }
+    end
+
+    # Record wall-clock time for a specific operation type (:resize, :format, etc.)
+    def record_operation_time(type, seconds)
+      @mutex.synchronize { @operation_timings[type] += seconds }
+    end
+
+    # Record compression ratio for a format (e.g. "webp" => 78.5 percent saved)
+    def record_compression_ratio(format, original_size, output_size)
+      return if original_size.zero?
+
+      ratio = ((original_size - output_size).to_f / original_size * 100).round(1)
+      @mutex.synchronize do
+        @compression_ratios[format] ||= { ratios: [], count: 0 }
+        @compression_ratios[format][:ratios] << ratio
+        @compression_ratios[format][:count] += 1
+      end
+    end
+
+    # Average compression ratio per format
+    def average_compression_ratios
+      @compression_ratios.transform_values do |data|
+        (data[:ratios].sum / data[:count]).round(1) if data[:count].positive?
+      end
+    end
+
+    def total_processed
+      @cache_hits + @cache_misses
+    end
+
+    def cache_hit_rate
+      return 0.0 if total_processed.zero?
+
+      (@cache_hits.to_f / total_processed * 100).round(1)
+    end
+
+    def to_h
+      {
+        cache_hits: @cache_hits,
+        cache_misses: @cache_misses,
+        cache_hit_rate: cache_hit_rate,
+        total_processed: total_processed,
+        operation_timings: @operation_timings.transform_values { |v| v.round(3) },
+        compression_ratios: average_compression_ratios
+      }
+    end
+
+    def reset
+      @mutex.synchronize do
+        @cache_hits = 0
+        @cache_misses = 0
+        @operation_timings.clear
+        @compression_ratios.clear
+      end
+    end
+  end
+end

data/lib/jekyll-imgflow/provider_registry.rb

@@ -12,6 +12,9 @@ module JekyllImgFlow
       self.class.discover_providers unless self.class.providers_discovered?
     end
 
+    # Files in providers/ that are not provider classes (modules, helpers)
+    NON_PROVIDER_FILES = %w[base_provider.rb].freeze
+
     # Dynamic provider discovery
     def self.discover_providers
       return if @providers_discovered
@@ -20,7 +23,8 @@ module JekyllImgFlow
       providers_dir = File.join(File.dirname(__FILE__), "providers")
 
       Dir.glob(File.join(providers_dir, "*.rb")).each do |file|
-        next if File.basename(file) == "base_provider.rb"
+        basename = File.basename(file)
+        next if NON_PROVIDER_FILES.include?(basename)
 
         provider_name = File.basename(file, ".rb")
         register_provider(provider_name)
@@ -72,9 +76,20 @@ module JekyllImgFlow
       end
     end
 
-    # Get current provider (first available from priority list)
+    # Get current provider (first available from priority list).
+    # If no provider is available, logs a warning and returns nil.
+    # The caller should check for nil and handle gracefully.
     def current_provider
-      providers.find(&:available?)
+      provider = providers.find(&:available?)
+      return provider if provider
+
+      configured = @config.backend_priority.join(", ")
+      Jekyll.logger.warn "ImgFlow:",
+                         "No available image provider found. " \
+                         "Configured backends: #{configured}. " \
+                         "Install one of: sharp, libvips, imagemagick, " \
+                         "or start the Docker HTTP providers."
+      nil
     end
 
     # Get list of available provider names

data/lib/jekyll-imgflow/providers/base_provider.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "English"
 require "open3"
 require "pathname"
 
@@ -158,6 +157,13 @@ module JekyllImgFlow
       # Helper methods
       protected
 
+      # Check if the input file is an SVG (vector format).
+      # SVGs require special handling: they have no fixed pixel dimensions,
+      # so providers must choose a rasterization size.
+      def svg?(input_path)
+        File.extname(input_path).downcase == ".svg"
+      end
+
       def execute_command(command)
         stdout, stderr, status = Open3.capture3(command)
         raise "Command failed: #{command}\nError: #{stderr.strip}" unless status.success?
@@ -185,11 +191,16 @@ module JekyllImgFlow
         end
 
         # Provider capability methods
+        KNOWN_OPERATIONS = %i[crop format opacity optimize quality resize
+                              watermark alpha_opacity].freeze
+
         def unsupported_operations
           [] # Default: no unsupported operations
         end
 
         def supports_operation?(operation)
+          return false unless KNOWN_OPERATIONS.include?(operation)
+
           !unsupported_operations.include?(operation)
         end
       end

data/lib/jekyll-imgflow/providers/flyimg.rb

@@ -26,8 +26,9 @@ module JekyllImgFlow
 
         # Fetch the result in one request
         fetch_and_save(url, output_path)
-        reset_operations
         output_path
+      ensure
+        reset_operations
       end
 
       def build_combined_flyimg_url(input_path)

data/lib/jekyll-imgflow/providers/imagemagick.rb

@@ -8,6 +8,10 @@ module JekyllImgFlow
   module Providers
     # ImageMagick provider implementation using the standardized tag interface
     class Imagemagick < BaseProvider
+      # Cache rsvg delegate check across all instances (checked once per build)
+      @rsvg_available = nil
+      @svg_warning_shown = false
+
       def available?
         # Check if magick or convert CLI is available
         _, _, status1 = Open3.capture3("which", "magick")
@@ -18,17 +22,30 @@ module JekyllImgFlow
       def execute(input_path, output_path)
         return if @operations.empty?
 
+        # Warn once per build about SVG performance with ImageMagick
+        warn_svg_performance if svg?(input_path) && !self.class.instance_variable_get(:@svg_warning_shown)
+
         # Build single ImageMagick command with all operations combined
         command = build_combined_imagemagick_command(input_path, output_path)
         execute_command(command)
 
-        reset_operations
         output_path
+      ensure
+        reset_operations
       end
 
       def build_combined_imagemagick_command(input_path, output_path)
-        # Start with base command
-        command_parts = ["magick", input_path.shellescape]
+        # Start with base command.
+        # For SVGs, set -density before the input so ImageMagick rasterizes
+        # at a reasonable resolution instead of the full viewBox (which can
+        # be 10000x8500 = 85M pixels, making each conversion take 10+ seconds).
+        # With the rsvg delegate installed, -density controls the render DPI.
+        # Without rsvg, ImageMagick uses its slow internal MSVG parser.
+        command_parts = if svg?(input_path)
+                          ["magick", "-density", svg_density.to_s, input_path.shellescape]
+                        else
+                          ["magick", input_path.shellescape]
+                        end
 
         # Add all operations
         @operations.each do |operation|
@@ -133,6 +150,58 @@ module JekyllImgFlow
         # ImageMagick uses 1-100 directly, no translation needed
         quality
       end
+
+      # Choose a rasterization density (DPI) for SVG input.
+      # ImageMagick's internal SVG parser renders at the full viewBox size
+      # (e.g. 10000x8500 = 85M pixels) before applying -resize, which is
+      # extremely slow. Setting -density before the input tells the rsvg
+      # delegate to render at a lower resolution.
+      # We target ~2x the largest resize dimension for good quality,
+      # assuming a ~10 inch viewBox (common for SVGs). This avoids the
+      # massive internal canvas while preserving output quality.
+      # For a 400px output: density = 80px/in / 10in = 8 DPI → renders at
+      # ~800px instead of 10000px, giving ~10x speedup.
+      def svg_density
+        max_width = @operations.filter_map { |op| op[:type] == :resize && op[:width] }.max
+        # Default to 36 DPI if no resize (e.g. format-only conversion)
+        return 36 unless max_width
+
+        # Target 2x output width for quality. Assume ~10 inch viewBox.
+        # No upper cap — even 2000px output only needs 40 DPI.
+        (max_width * 2 / 10).to_i
+      end
+
+      # Check if ImageMagick has the rsvg delegate installed.
+      # Without it, ImageMagick uses its slow internal MSVG parser.
+      # Install with: macOS: `brew install librsvg`, Ubuntu: `apt install librsvg2-bin`
+      def rsvg_available?
+        return self.class.instance_variable_get(:@rsvg_available) unless self.class.instance_variable_get(:@rsvg_available).nil?
+
+        stdout, _, status = Open3.capture3("magick", "-list", "delegate")
+        result = status.success? && stdout.include?("rsvg-convert")
+        self.class.instance_variable_set(:@rsvg_available, result)
+        result
+      end
+
+      # Warn once per build about SVG performance with ImageMagick.
+      # Suggests installing rsvg-convert or using a different provider.
+      def warn_svg_performance
+        return if self.class.instance_variable_get(:@svg_warning_shown)
+
+        self.class.instance_variable_set(:@svg_warning_shown, true)
+        if rsvg_available?
+          Jekyll.logger.info "ImgFlow:",
+                             "ImageMagick processing SVG with rsvg delegate " \
+                             "(density=#{svg_density})."
+        else
+          Jekyll.logger.warn "ImgFlow:",
+                             "ImageMagick is processing SVGs without the rsvg " \
+                             "delegate — this is VERY slow. Install librsvg " \
+                             "(macOS: `brew install librsvg`, " \
+                             "Ubuntu: `apt install librsvg2-bin`) or use a " \
+                             "different provider (sharp/libvips) for SVGs."
+        end
+      end
     end
   end
 end

data/lib/jekyll-imgflow/providers/imgproxy.rb

@@ -26,8 +26,9 @@ module JekyllImgFlow
 
         # Fetch the result in one request
         fetch_and_save(url, output_path)
-        reset_operations
         output_path
+      ensure
+        reset_operations
       end
 
       def build_combined_imgproxy_url(input_path)