jekyll-imgflow 0.1.10 → 0.3.0

data/lib/jekyll-imgflow/operation_processor.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
 require_relative "filename_generator"
+require "benchmark"
 
 module JekyllImgFlow
   # OperationProcessor - processes image operations using providers
   # Handles both single operations and batch operations
   class OperationProcessor
+    attr_accessor :stats
+
     def initialize(provider, path_resolver, manifest = nil, config = nil)
       @provider = provider
       @path_resolver = path_resolver
       @filename_generator = FilenameGenerator.new
       @manifest = manifest
       @config = config
+      @stats = ProcessingStats.new
     end
 
     # Process a single operation on an image
@@ -41,6 +45,7 @@ module JekyllImgFlow
     def process_operation(original_name, operation, input_path, page_path = nil)
       type = operation[:type]
       params = operation[:params]
+      file_digest = operation[:file_digest] || @filename_generator.file_digest(input_path)
 
       # Determine version type
       version_type = determine_version_type(params)
@@ -58,17 +63,37 @@ module JekyllImgFlow
       # Ensure output directory exists before processing
       FileUtils.mkdir_p(File.dirname(actual_output_path))
 
-      # Animated GIFs must not be resized or converted — the operation
-      # would destroy the animation. Copy the original file as-is so the
-      # manifest can track it and HTML references stay valid.
-      if AnimatedGifDetector.animated?(input_path)
+      # Skip processing if the output file already exists and is up-to-date.
+      # This handles legacy manifests, corrupted manifests, and any case where
+      # optimized files exist on disk but the manifest is out of sync — the
+      # version is registered in the manifest without re-running the provider.
+      if !operation[:force_processing] && output_up_to_date?(input_path, actual_output_path)
+        Jekyll.logger.debug "⏭️  ImgFlow: Output exists and up-to-date, " \
+                            "skipping provider call for #{original_name}"
+        @stats.record_cache_hit
+      elsif AnimatedGifDetector.animated?(input_path)
+        # Animated GIFs must not be resized or converted — the operation
+        # would destroy the animation. Copy the original file as-is so the
+        # manifest can track it and HTML references stay valid.
         Jekyll.logger.warn "🖼️  ImgFlow: Skipping resize for animated GIF " \
                            "'#{original_name}' — copying original as-is to " \
                            "preserve animation."
         FileUtils.cp(input_path, actual_output_path)
+        @stats.record_cache_miss
       else
         # Process the operation (create the image)
-        process_single_operation(type, input_path, actual_output_path, params)
+        elapsed = Benchmark.measure do
+          process_single_operation(type, input_path, actual_output_path, params)
+        end
+        @stats.record_operation_time(type, elapsed.real)
+        @stats.record_cache_miss
+
+        # Record compression ratio if we have the original size
+        if File.file?(input_path) && File.file?(actual_output_path)
+          format = params[:format] || File.extname(input_path).delete(".")
+          @stats.record_compression_ratio(format.to_s, File.size(input_path),
+                                          File.size(actual_output_path))
+        end
       end
 
       # Register in manifest
@@ -76,14 +101,14 @@ module JekyllImgFlow
         # Store relative path (with leading /) for manifest storage
         relative_path = "/#{@path_resolver.resolve_relative_output_path(filename, subdir)}"
 
-        provider_name = @provider.class.provider_name
+        provider_name = @provider&.class&.provider_name || "unknown"
         @manifest.register_version(
           original_name,
           relative_path,
           params,
           version_type,
           page_path,
-          nil, # file_digest
+          file_digest,
           provider_name
         )
       end
@@ -170,26 +195,22 @@ module JekyllImgFlow
     # @param output_path [String] Path to output image
     # @param operations [Hash] Operations to apply
     # @return [Boolean] True if processing needed
-    def needs_processing?(input_path, output_path, operations)
+    def needs_processing?(input_path, output_path, _operations = nil)
       # If output doesn't exist, needs processing
       return true unless File.exist?(output_path)
 
       # If input is newer than output, needs processing
-      return true if File.mtime(input_path) > File.mtime(output_path)
-
-      # Check if operations changed by comparing cache key
-      # stored alongside the output file
-      cache_key = @filename_generator.generate_cache_key(operations)
-      cache_file = "#{output_path}.cache_key"
-
-      return true unless File.exist?(cache_file)
-
-      stored_key = File.read(cache_file).strip
-      return true if stored_key != cache_key
-
-      # No cache key file - needs processing to create it
+      File.mtime(input_path) > File.mtime(output_path)
+    end
 
-      false
+    # Check if the output file exists and the input is not newer than the
+    # output. Used to skip provider calls when the optimized file is already
+    # on disk (e.g. legacy manifest, manifest out of sync).
+    # @param input_path [String] Path to input image
+    # @param output_path [String] Path to output image
+    # @return [Boolean] True if output exists and is up-to-date
+    def output_up_to_date?(input_path, output_path)
+      File.file?(output_path) && File.mtime(input_path) <= File.mtime(output_path)
     end
 
     # Build operation structure from params hash

data/lib/jekyll-imgflow/parser.rb

@@ -9,7 +9,7 @@ module JekyllImgFlow
     # Define valid operation parameters and attribute types
     OPERATION_PARAMS = %i[width height ratio aspect_ratio quality format formats
                           optimize level watermark opacity position keep preset].freeze
-    HTML_ATTRIBUTES = %i[alt class title loading].freeze
+    HTML_ATTRIBUTES = %i[alt class title loading link modal].freeze
 
     # Simple operation mappings for single-parameter operations
     SIMPLE_OPERATIONS = {

data/lib/jekyll-imgflow/picture_tag_adaptor.rb

@@ -43,7 +43,7 @@ module JekyllImgFlow
     # @return [Hash] Translation result with markup and attributes
     def translate_to_imgflow(picture_markup)
       # Extract content between {% picture ... %}
-      match = picture_markup.match(/\{%\s*picture\s+(.+?)\s*%}/)
+      match = picture_markup.match(/\{%\s*picture\s+(.+?)%\}/)
       return { markup: "", attributes: {} } unless match
 
       content = match[1].strip

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)