jekyll-imgflow 0.1.9 → 0.2.0

data/lib/jekyll-imgflow/imgflow_tag.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "shellwords"
+
 module Jekyll
   class ImgflowTag < Liquid::Tag
     def initialize(tag_name, markup, tokens)
@@ -36,7 +38,7 @@ module Jekyll
 
     def expand_preset_markup(markup, preset_manager)
       # Parse markup to extract image path, preset name, and user options
-      parts = markup.split
+      parts = Shellwords.split(markup)
       image_path = parts.first
 
       # Extract preset name and user options
@@ -55,8 +57,14 @@ module Jekyll
       # Get preset markup from PresetManager
       preset_markup = preset_manager.build_markup_from_preset(preset_name, user_options)
 
-      # Combine image path with preset markup
-      "#{image_path} #{preset_markup}"
+      # Combine image path with preset markup. Keep the path quoted because
+      # filenames may contain spaces.
+      image_markup = if image_path.include?(" ")
+                       "\"#{image_path.gsub('"', '\\"')}\""
+                     else
+                       image_path
+                     end
+      "#{image_markup} #{preset_markup}"
     end
 
     def process_operations(components, parsed, context)
@@ -82,73 +90,77 @@ module Jekyll
                     "unknown"
                   end
 
-      # Process operations using clean architecture
       operations = parsed[:operations]
+      results = if operations.empty?
+                  [input_path]
+                else
+                  process_variants(components, operations.first, original_name, input_path,
+                                   page_path)
+                end
+
+      relative_results = results.uniq.map { |result| relative_result_path(result, site) }
+      parsed = parsed.merge(markup_format: "picture") if relative_results.length > 1
+      generate_html(relative_results, parsed, context)
+    end
 
-      result = if operations.empty?
-                 # No operations - use original image
-                 input_path
-               else
-                 # Generate filename early to check existence
-                 operation = operations.first
-                 params = operation[:params]
-
-                 # For default versions, include default format and quality for proper identification
-                 if determine_version_type(params, components[:config]) == :default
-                   params = params.dup
-                   params[:format] ||= components[:config].formats.first  # Use default format
-                   params[:quality] ||= components[:config].quality       # Use default quality
-                 end
-
-                 # Preserve original directory structure under output
-                 subdir = File.dirname(original_name)
-                 subdir = nil if subdir == "."
-
-                 filename = components[:filename_generator].generate_filename(input_path, params)
-                 output_path = components[:path_resolver].resolve_source_output_path(filename, subdir)
-
-                 # Determine version type
-                 version_type = determine_version_type(params, components[:config])
-
-                 # Check if version exists in manifest
-                 Jekyll.logger.debug "🔍 ImgflowTag: Checking existence - original_name: #{original_name}, version_type: #{version_type}, page_path: #{page_path}"
-                 Jekyll.logger.debug "🔍 ImgflowTag: Params being checked: #{params.inspect}"
-
-                 if components[:manifest].version_exists?(original_name, params, version_type)
-                   # Version exists - update page usage and return path
-                   Jekyll.logger.debug "✅ ImgflowTag: Version exists! Updating page usage"
-                   components[:manifest].update_page_usage(original_name, params, version_type,
-                                                           page_path)
-                   output_path
-                 else
-                   # Version doesn't exist - create it
-                   Jekyll.logger.debug "❌ ImgflowTag: Version doesn't exist - creating"
-                   versions = components[:manifest].get_versions(original_name)
-                   Jekyll.logger.debug "🔍 ImgflowTag: Manifest has - default: #{versions['default']&.length || 0}, specialized: #{versions['specialized']&.length || 0}"
-
-                   components[:operation_processor].process_operation(
-                     original_name,
-                     operation,
-                     input_path,
-                     page_path
-                   )
-                 end
-               end
-
-      # Convert absolute paths to relative for HTML generation
-      relative_result = if result.start_with?(site.dest)
-                          # Processed images - remove site.dest and leading /
-                          result.sub(%r{^#{Regexp.escape(site.dest)}/}, "")
-                        elsif result.start_with?(site.source)
-                          # Original images - convert from source to relative and remove leading /
-                          result.sub(%r{^#{Regexp.escape(site.source)}/}, "")
-                        else
-                          # Already relative or other format - remove leading / if present
-                          result.start_with?("/") ? result[1..] : result
-                        end
+    def process_variants(components, operation, original_name, input_path, page_path)
+      params = operation[:params].dup
+      formats = Array(params.delete(:formats) || params[:format])
+      # When no format is explicitly specified, generate all configured formats
+      # (avif, webp, png, jpg) so browsers get a <picture> with <source> tags for
+      # modern formats and an <img> fallback. This applies to both default-width
+      # versions (which find pre-generated files in the manifest cache) and
+      # specialized versions (which are generated on-demand).
+      formats = components[:config].formats if formats.empty?
+
+      formats.map do |format|
+        variant_params = params.dup
+        variant_params[:format] = format
+        process_variant(components, operation, variant_params, original_name, input_path, page_path)
+      end
+    end
+
+    def process_variant(components, operation, params, original_name, input_path, page_path)
+      config = components[:config]
+      if determine_version_type(params, config) == :default
+        params[:format] ||= config.formats.first
+        params[:quality] ||= config.quality
+      end
 
-      # Generate HTML for the result
-      generate_html([relative_result], parsed, context)
+      digest = components[:filename_generator].file_digest(input_path)
+      variant = operation.merge(params: params, file_digest: digest)
+      subdir = File.dirname(original_name)
+      subdir = nil if subdir == "."
+      filename = components[:filename_generator].generate_filename(input_path, params)
+      output_path = components[:path_resolver].resolve_source_output_path(filename, subdir)
+      version_type = determine_version_type(params, config)
+
+      if components[:manifest].version_exists?(original_name, params, version_type, digest) &&
+         File.file?(output_path)
+        components[:stats]&.record_cache_hit
+        components[:manifest].update_page_usage(original_name, params, version_type, page_path)
+        return output_path
+      end
+
+      unless components[:operation_processor]
+        Jekyll.logger.warn "ImgFlow:", "No image provider available — " \
+                                       "rendering original without optimization."
+        return input_path
+      end
+
+      components[:operation_processor].process_operation(
+        original_name, variant.merge(force_processing: true), input_path, page_path
+      )
+    end
+
+    def relative_result_path(result, site)
+      if result.start_with?(site.dest)
+        result.sub(%r{^#{Regexp.escape(site.dest)}/}, "")
+      elsif result.start_with?(site.source)
+        result.sub(%r{^#{Regexp.escape(site.source)}/}, "")
+      else
+        result.delete_prefix("/")
+      end
     end
 
     def generate_html(results, parsed, context)
@@ -232,8 +244,10 @@ module Jekyll
         filename_generator = JekyllImgFlow::FilenameGenerator.new
         registry = JekyllImgFlow::ProviderRegistry.new(config)
         provider = registry.current_provider
-        operation_processor = JekyllImgFlow::OperationProcessor.new(provider, path_resolver,
-                                                                    manifest, config)
+        if provider
+          operation_processor = JekyllImgFlow::OperationProcessor.new(provider, path_resolver,
+                                                                      manifest, config)
+        end
         preset_manager = JekyllImgFlow::PresetManager.new(site, config)
 
         site.imgflow_components = {
@@ -244,6 +258,7 @@ module Jekyll
           registry: registry,
           provider: provider,
           operation_processor: operation_processor,
+          stats: operation_processor&.stats,
           preset_manager: preset_manager
         }
       end

data/lib/jekyll-imgflow/manifest_manager.rb

@@ -2,7 +2,6 @@
 
 require "json"
 require "fileutils"
-require "digest"
 
 module JekyllImgFlow
   # Manages the manifest of generated images
@@ -13,9 +12,11 @@ module JekyllImgFlow
 
     def initialize(site)
       @site = site
-      # Place manifest in _site - rebuilt on each Jekyll build
-      @manifest_path = File.join(@site.dest, "assets", "images", "imgflow-manifest.json")
-      @manifest = load_manifest
+      @config = JekyllImgFlow::Config.new(site)
+      @file_cleaner = GeneratedFileCleaner.new(site, @config)
+      @manifest_path = File.join(@site.source, @config.cache_dir, "imgflow-manifest.json")
+      @legacy_manifest_paths = legacy_manifest_paths
+      @manifest = load_manifest(manifest_load_path)
       @current_provider = current_provider
 
       # Check if provider changed and invalidate cache if needed
@@ -23,20 +24,22 @@ module JekyllImgFlow
     end
 
     # Load existing manifest or create new one
-    def load_manifest
-      if File.exist?(@manifest_path)
+    def load_manifest(path = @manifest_path)
+      if path && File.exist?(path)
         begin
-          data = JSON.parse(File.read(@manifest_path))
+          data = JSON.parse(File.read(path))
 
           # Handle new format with provider at top level
           if data.is_a?(Hash) && data.key?("images")
             @cached_provider = data["provider"]
-            data["images"] || {}
+            images = data["images"] || {}
           else
             # Old format - just image data
             @cached_provider = nil
-            data
+            images = data
           end
+
+          migrate_legacy_manifest(images)
         rescue JSON::ParserError => e
           Jekyll.logger.warn "ImgFlow: Corrupt manifest file, starting fresh: #{e.message}"
           @cached_provider = nil
@@ -48,6 +51,23 @@ module JekyllImgFlow
       end
     end
 
+    # Detect and migrate legacy manifest entries (pre-0.1.11 format).
+    # Old entries have operations like {"width": 400} without format/quality
+    # and no file_digest. Clearing them lets the build re-register existing
+    # output files without reprocessing (output_up_to_date? check handles this).
+    def migrate_legacy_manifest(images)
+      legacy = images.any? do |_name, data|
+        versions = data.dig("versions", "default") || []
+        versions.any? { |v| v["file_digest"].nil? || !v["operations"].key?("format") }
+      end
+      if legacy
+        Jekyll.logger.info "ImgFlow: Detected legacy manifest format, " \
+                           "clearing entries for re-registration."
+        images.clear
+      end
+      images
+    end
+
     # Save manifest to disk
     def save
       # Store current provider at top level of manifest
@@ -55,44 +75,98 @@ module JekyllImgFlow
         "provider" => @current_provider,
         "images" => @manifest
       }
+      content = JSON.pretty_generate(manifest_data)
+      if File.exist?(@manifest_path) && File.binread(@manifest_path) == content
+        cleanup_legacy_manifests
+        return
+      end
 
-      FileUtils.mkdir_p(File.dirname(@manifest_path))
-      File.write(@manifest_path, JSON.pretty_generate(manifest_data))
+      directory = File.dirname(@manifest_path)
+      temporary_path = "#{@manifest_path}.tmp-#{Process.pid}-#{Thread.current.object_id}"
+      FileUtils.mkdir_p(directory)
+      File.open(temporary_path, "wb") do |file|
+        file.write(content)
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary_path, @manifest_path)
+      cleanup_legacy_manifests
+    ensure
+      FileUtils.rm_f(temporary_path) if temporary_path
     end
 
     # Get current provider from site config
-    def current_provider
-      config = JekyllImgFlow::Config.new(@site)
-      # Get first available provider from backend_priority
-      config.backend_priority&.first || "unknown"
-    end
+    def current_provider = @config.backend_priority&.first || "unknown"
 
     # Clean up manifest entries for deleted original images
-    # @param current_originals [Array<String>] Array of current original image basenames
+    # @param current_originals [Array<String>] Paths relative to the originals directory
     def cleanup_deleted_originals(current_originals)
       current_set = current_originals.to_set
 
       @manifest.each_key do |original_name|
-        # Extract basename without extension
-        basename = File.basename(original_name, ".*")
+        next if current_set.include?(original_name)
+
+        data = @manifest.delete(original_name)
+        VERSION_TYPES.each do |type|
+          (data.dig("versions", type) || []).each do |version|
+            @file_cleaner.delete(version["output"])
+          end
+        end
+        Jekyll.logger.debug "🗑️  Removed manifest entry for deleted original: #{original_name}"
+      end
+    end
+
+    def cleanup_obsolete_defaults(expected_operations)
+      @manifest.each_value do |data|
+        versions = data.dig("versions", "default") || []
+        versions.reject! do |version|
+          obsolete = expected_operations.none? do |operations|
+            same_operations?(version["operations"], operations)
+          end
+          @file_cleaner.delete(version["output"]) if obsolete
+          obsolete
+        end
+      end
+    end
+
+    def reset_page_usage
+      @manifest.each_value do |data|
+        (data.dig("versions", "specialized") || []).each do |version|
+          version["used_on"] = []
+        end
+      end
+    end
 
-        # If original no longer exists, remove from manifest
-        unless current_set.include?(basename)
-          @manifest.delete(original_name)
-          Jekyll.logger.debug "🗑️  Removed manifest entry for deleted original: #{original_name}"
+    # Normalize operations for consistent comparison after JSON persistence.
+    def normalize_operations(operations)
+      case operations
+      when Hash
+        operations.to_h do |key, value|
+          [key.to_s, normalize_operations(value)]
         end
+      when Array
+        operations.map { |value| normalize_operations(value) }
+      when Symbol
+        operations.to_s
+      else
+        operations
       end
     end
 
+    def same_operations?(left, right) = normalize_operations(left) == normalize_operations(right)
+
     # Check if a specific image version exists and is up-to-date
-    def version_exists?(original_name, operations, type = :specialized)
+    def version_exists?(original_name, operations, type = :specialized, file_digest = nil)
       return false unless @manifest[original_name]
 
       # Provider change is already handled in initialize, so just check operations
       versions = @manifest.dig(original_name, "versions", type.to_s) || []
       Jekyll.logger.debug "🔍 ManifestManager: Looking for operations: #{operations.inspect} in #{versions.length} #{type} versions"
 
-      result = versions.any? { |v| v["operations"] == operations }
+      result = versions.any? do |version|
+        same_operations?(version["operations"], operations) &&
+          (!file_digest || version["file_digest"] == file_digest)
+      end
       Jekyll.logger.debug "🔍 ManifestManager: Final result: #{result}"
       result
     end
@@ -112,25 +186,9 @@ module JekyllImgFlow
                          "Provider changed from '#{@cached_provider}' to '#{@current_provider}'"
       Jekyll.logger.warn "ImgFlow:", "Invalidating cache and cleaning optimized directory..."
 
-      # Get optimized directory path
-      config = JekyllImgFlow::Config.new(@site)
-      optimized_dir = File.join(@site.source, config.output)
-
-      # Safety guard: prevent deletion of _site itself
-      raise "Refusing to delete optimized directory: path resolves to site dest or is empty" if optimized_dir == @site.dest || optimized_dir.empty?
-
-      # Delete all files in optimized directory
-      if Dir.exist?(optimized_dir)
-        deleted_count = 0
-        Dir.glob(File.join(optimized_dir, "**", "*")).each do |file|
-          if File.file?(file)
-            File.delete(file)
-            deleted_count += 1
-          end
-        end
-        Jekyll.logger.warn "ImgFlow:",
-                           "Deleted #{deleted_count} cached images from optimized directory"
-      end
+      deleted_count = @file_cleaner.clear
+      Jekyll.logger.warn "ImgFlow:",
+                         "Deleted #{deleted_count} cached images from optimized directory"
 
       # Clear manifest cache
       @manifest.clear
@@ -146,7 +204,7 @@ module JekyllImgFlow
       return unless @manifest[original_name]
 
       versions = @manifest.dig(original_name, "versions", type.to_s) || []
-      version = versions.find { |v| v["operations"] == operations }
+      version = versions.find { |v| same_operations?(v["operations"], operations) }
       version&.dig("output")
     end
 
@@ -162,7 +220,7 @@ module JekyllImgFlow
 
       # Get the existing version to preserve provider
       versions = @manifest.dig(original_name, "versions", type.to_s) || []
-      version = versions.find { |v| v["operations"] == operations }
+      version = versions.find { |v| same_operations?(v["operations"], operations) }
       provider = version&.dig("provider")
       Jekyll.logger.debug "🔍 update_page_usage: provider=#{provider}, current used_on=#{version&.dig('used_on')&.inspect}"
 
@@ -183,9 +241,10 @@ module JekyllImgFlow
       @manifest[original_name]["file_digest"] = file_digest if file_digest
 
       versions = @manifest[original_name]["versions"][type.to_s] ||= []
+      normalized_operations = normalize_operations(operations)
 
       # Find or create version entry
-      version = versions.find { |v| v["operations"] == operations }
+      version = versions.find { |v| same_operations?(v["operations"], normalized_operations) }
 
       # Normalize page_path to array
       page_paths = if page_path.is_a?(Array)
@@ -200,16 +259,19 @@ module JekyllImgFlow
         page_paths.each do |path|
           version["used_on"] << path if path && !version["used_on"].include?(path)
         end
+        version["output"] = output_path
+        version["file_digest"] = file_digest if file_digest
         # Update provider if provided
         version["provider"] = provider if provider
       else
         # Create new version entry
         versions << {
           "output" => output_path,
-          "operations" => operations,
+          "operations" => normalized_operations,
           "type" => type.to_s,
           "used_on" => page_paths,
           "created_at" => Time.now.to_i,
+          "file_digest" => file_digest,
           "provider" => provider
         }
       end
@@ -220,7 +282,7 @@ module JekyllImgFlow
       return false unless @manifest[original_name]
 
       versions = @manifest.dig(original_name, "versions", "default") || []
-      versions.any? { |v| v["operations"] == operations }
+      versions.any? { |v| same_operations?(v["operations"], operations) }
     end
 
     # Find orphaned specialized images (not used on any page)
@@ -261,16 +323,14 @@ module JekyllImgFlow
       cleaned = []
 
       orphans.each do |orphan|
-        output_file = File.join(@site.source, orphan["output"])
-        if File.exist?(output_file)
-          File.delete(output_file)
+        if @file_cleaner.delete(orphan["output"])
           cleaned << orphan["output"]
           Jekyll.logger.info "🗑️  Cleaned orphaned image: #{orphan['output']}"
         end
 
         # Remove from manifest
         versions = @manifest.dig(orphan["original"], "versions", "specialized") || []
-        versions.reject! { |v| v["operations"] == orphan["operations"] }
+        versions.reject! { |v| same_operations?(v["operations"], orphan["operations"]) }
       end
 
       cleaned
@@ -288,5 +348,24 @@ module JekyllImgFlow
       versions = @manifest[original_name]["versions"]
       (versions["default"]&.any? || false) || (versions["specialized"]&.any? || false)
     end
+
+    private
+
+    def legacy_manifest_paths
+      [
+        File.join(@site.source, "assets", "images", "imgflow-manifest.json"),
+        File.join(@site.dest, "assets", "images", "imgflow-manifest.json")
+      ].reject { |path| path == @manifest_path }
+    end
+
+    def manifest_load_path
+      return @manifest_path if File.exist?(@manifest_path)
+
+      @legacy_manifest_paths.find { |path| File.exist?(path) }
+    end
+
+    def cleanup_legacy_manifests
+      @legacy_manifest_paths.each { |path| FileUtils.rm_f(path) }
+    end
   end
 end

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/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