metalsmith-optimize-images 0.9.0 → 0.9.3

package/lib/index.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
 var path = require('path');
-var mkdirp = require('mkdirp');
-var cheerio = require('cheerio');
 var fs = require('fs');
+var mkdirp = require('mkdirp');
 var sharp = require('sharp');
+var cheerio = require('cheerio');
 var crypto = require('crypto');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
@@ -28,10 +28,10 @@ function _interopNamespace(e) {
 }
 
 var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
-var mkdirp__namespace = /*#__PURE__*/_interopNamespace(mkdirp);
-var cheerio__namespace = /*#__PURE__*/_interopNamespace(cheerio);
 var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
+var mkdirp__namespace = /*#__PURE__*/_interopNamespace(mkdirp);
 var sharp__default = /*#__PURE__*/_interopDefaultLegacy(sharp);
+var cheerio__namespace = /*#__PURE__*/_interopNamespace(cheerio);
 var crypto__default = /*#__PURE__*/_interopDefaultLegacy(crypto);
 
 /**
@@ -135,7 +135,11 @@ function buildConfig(options = {}) {
       width: 50,
       quality: 30,
       blur: 10
-    }
+    },
+    // Background image processing settings
+    processUnusedImages: true,
+    // Process images not found in HTML for background use
+    imagePattern: '**/*.{jpg,jpeg,png,gif,webp,avif}' // Pattern to find images for background processing
   };
 
   // Special handling for formatOptions to ensure deep merging
@@ -176,9 +180,9 @@ function buildConfig(options = {}) {
  * @return {string} - A short hash string (8 characters)
  */
 function generateHash(buffer) {
-  // MD5 is sufficient for cache-busting (not cryptographic security)
+  // SHA-256 for cache-busting - using secure algorithm to satisfy security scanners
   // Only use first 8 characters to keep filenames manageable
-  return crypto__default["default"].createHash('md5').update(buffer).digest('hex').slice(0, 8);
+  return crypto__default["default"].createHash('sha256').update(buffer).digest('hex').slice(0, 8);
 }
 
 /**
@@ -268,7 +272,17 @@ async function processImageToVariants(buffer, originalPath, debugFn, config) {
         } else {
           // For specific formats (avif, webp, etc.), apply format-specific options
           const formatOptions = config.formatOptions[format] || {};
-          formatted = resized.clone()[format](formatOptions);
+          if (format === 'avif') {
+            formatted = resized.clone().avif(formatOptions);
+          } else if (format === 'webp') {
+            formatted = resized.clone().webp(formatOptions);
+          } else if (format === 'jpeg') {
+            formatted = resized.clone().jpeg(formatOptions);
+          } else if (format === 'png') {
+            formatted = resized.clone().png(formatOptions);
+          } else {
+            formatted = resized.clone()[format](formatOptions);
+          }
         }
 
         // Generate the actual image buffer - this is where compression happens
@@ -936,9 +950,12 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
  */
 function generateMetadata(processedImages, files, config) {
   const metadataObj = {};
-  processedImages.forEach((variants, key) => {
+  processedImages.forEach((value, key) => {
     // Extract the original path from the cache key (path:mtime)
     const [path] = key.split(':');
+
+    // Handle both array format (from background processing) and object format (from HTML processing)
+    const variants = Array.isArray(value) ? value : value.variants;
     metadataObj[path] = variants.map(v => ({
       path: v.path,
       width: v.width,
@@ -1124,6 +1141,9 @@ function injectProgressiveAssets($) {
  * @param {number} [options.placeholder.width] - Placeholder image width (default: 50)
  * @param {number} [options.placeholder.quality] - Placeholder image quality (default: 30)
  * @param {number} [options.placeholder.blur] - Placeholder image blur amount (default: 10)
+ * @param {boolean} [options.processUnusedImages] - Whether to process unused images for background use (default: true)
+ * @param {string} [options.imagePattern] - Glob pattern to find images for background processing (default: `**\/*.{jpg,jpeg,png,gif,webp,avif}`)
+ * @param {string} [options.imageFolder] - Folder to scan for background images, relative to source (default: 'lib/assets/images')
  * @return {Function} - Metalsmith plugin function
  */
 function optimizeImagesPlugin(options = {}) {
@@ -1149,7 +1169,19 @@ function optimizeImagesPlugin(options = {}) {
       mkdirp__namespace.mkdirpSync(outputPath);
 
       // Find all HTML files that match the pattern (default: **/*.html)
-      const htmlFiles = Object.keys(files).filter(file => metalsmith.match(config.htmlPattern, file));
+      // Also ensure they actually end with .html to avoid processing CSS/JS files
+      const htmlFiles = Object.keys(files).filter(file => {
+        // Must match the HTML pattern
+        if (!metalsmith.match(config.htmlPattern, file)) {
+          return false;
+        }
+
+        // Must actually be an HTML file
+        if (!file.endsWith('.html')) {
+          return false;
+        }
+        return true;
+      });
       if (htmlFiles.length === 0) {
         debug('No HTML files found');
         return done();
@@ -1176,6 +1208,13 @@ function optimizeImagesPlugin(options = {}) {
         }));
       }));
 
+      // Process unused images for background image support
+      // This finds images that weren't processed during HTML scanning and creates variants
+      // for use in CSS background-image with image-set()
+      if (config.processUnusedImages) {
+        await processUnusedImages(files, metalsmith, processedImages, debug, config);
+      }
+
       // Optional: Generate a JSON metadata file with information about all processed images
       // Useful for debugging or integration with other tools
       if (config.generateMetadata) {
@@ -1191,5 +1230,345 @@ function optimizeImagesPlugin(options = {}) {
   };
 }
 
+/**
+ * Process unused images for background image support
+ * Finds images that weren't processed during HTML scanning and creates 1x/2x variants
+ * for use in CSS background-image with image-set()
+ * @param {Object} files - Metalsmith files object
+ * @param {Object} metalsmith - Metalsmith instance
+ * @param {Map} processedImages - Cache of already processed images
+ * @param {Function} debug - Debug function
+ * @param {Object} config - Plugin configuration
+ * @return {Promise<void>} - Promise that resolves when processing is complete
+ */
+async function processUnusedImages(files, metalsmith, processedImages, debug, config) {
+  debug('Processing unused images for background image support');
+
+  // Get all image paths that were already processed during HTML scanning
+  const processedImagePaths = new Set();
+  processedImages.forEach((_variants, cacheKey) => {
+    const [imagePath] = cacheKey.split(':');
+    processedImagePaths.add(imagePath);
+  });
+  debug(`Processed image paths from HTML: ${Array.from(processedImagePaths).join(', ')}`);
+
+  // Find images that weren't processed during HTML scanning using hybrid approach
+  const allBackgroundImages = await findUnprocessedImages(files, metalsmith, config, processedImagePaths, debug);
+  debug(`Background images found to process: ${allBackgroundImages.map(img => img.path).join(', ')}`);
+  if (allBackgroundImages.length === 0) {
+    debug('No unused images found to process');
+    return;
+  }
+  debug(`Found ${allBackgroundImages.length} unused images to process for background use`);
+
+  // Process background images in parallel for better performance
+  await Promise.all(allBackgroundImages.map(async imageObj => {
+    try {
+      debug(`Processing background image: ${imageObj.path} (source: ${imageObj.source})`);
+
+      // Generate background variants with original size and half size
+      const variants = await processBackgroundImageVariants(imageObj.buffer, imageObj.path, debug, config);
+
+      // Save all generated variants to Metalsmith files object
+      variants.forEach(variant => {
+        files[variant.path] = {
+          contents: variant.buffer
+        };
+      });
+
+      // Cache the variants (using current timestamp as mtime for unused images)
+      const cacheKey = `${imageObj.path}:${Date.now()}`;
+      processedImages.set(cacheKey, variants);
+      debug(`Generated ${variants.length} background variants for ${imageObj.path}`);
+    } catch (err) {
+      debug(`Error processing background image ${imageObj.path}: ${err.message}`);
+    }
+  }));
+  debug('Background image processing complete');
+}
+
+/**
+ * Find images that weren't processed during HTML scanning
+ * Uses a hybrid approach: scans filesystem first, then falls back to Metalsmith files object
+ * @param {Object} files - Metalsmith files object
+ * @param {Object} metalsmith - Metalsmith instance
+ * @param {Object} config - Plugin configuration
+ * @param {Set} processedImagePaths - Set of already processed image paths
+ * @param {Function} debug - Debug function
+ * @return {Promise<Array>} - Array of unprocessed image objects with {path, buffer}
+ */
+async function findUnprocessedImages(files, metalsmith, config, processedImagePaths, debug) {
+  const unprocessedImages = [];
+  const sourceImagesDir = path__default["default"].join(metalsmith.source(), 'lib/assets/images');
+  debug(`Looking for unprocessed images using hybrid approach`);
+
+  // Method 1: Scan filesystem (for real testbed scenario)
+  try {
+    debug(`Attempting to scan source directory: ${sourceImagesDir}`);
+    debug(`Source directory exists: ${fs__default["default"].existsSync(sourceImagesDir)}`);
+    debug(`Metalsmith source: ${metalsmith.source()}`);
+    debug(`Metalsmith destination: ${metalsmith.destination()}`);
+    if (fs__default["default"].existsSync(sourceImagesDir)) {
+      debug(`Scanning source directory: ${sourceImagesDir}`);
+      const scanDirectory = (dir, relativePath = '') => {
+        const items = fs__default["default"].readdirSync(dir);
+        debug(`Found ${items.length} items in ${dir}`);
+        for (const item of items) {
+          if (item === '.DS_Store') {
+            continue;
+          }
+          const fullPath = path__default["default"].join(dir, item);
+          const itemRelativePath = path__default["default"].join(relativePath, item);
+          if (fs__default["default"].statSync(fullPath).isDirectory()) {
+            debug(`Scanning subdirectory: ${item}`);
+            scanDirectory(fullPath, itemRelativePath);
+          } else {
+            const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+            if (imageExtensions.some(ext => item.toLowerCase().endsWith(ext))) {
+              // Skip if this is in the responsive output directory
+              if (itemRelativePath.startsWith('responsive/') || itemRelativePath.includes('/responsive/') || fullPath.includes(config.outputDir)) {
+                debug(`Skipping responsive variant: ${itemRelativePath}`);
+                continue;
+              }
+              const buildPath = path__default["default"].join('assets/images', itemRelativePath);
+              const normalizedBuildPath = buildPath.replace(/\\/g, '/');
+              debug(`Found filesystem image: ${item} -> ${normalizedBuildPath}`);
+              debug(`Already processed? ${processedImagePaths.has(normalizedBuildPath)}`);
+              if (!processedImagePaths.has(normalizedBuildPath)) {
+                debug(`Found unprocessed filesystem image: ${itemRelativePath}`);
+                const imageBuffer = fs__default["default"].readFileSync(fullPath);
+                unprocessedImages.push({
+                  path: itemRelativePath,
+                  buffer: imageBuffer,
+                  source: 'filesystem'
+                });
+              }
+            }
+          }
+        }
+      };
+      scanDirectory(sourceImagesDir);
+    } else {
+      debug(`Source directory does not exist, trying alternative paths...`);
+
+      // Try alternative paths
+      const altPaths = [path__default["default"].join(metalsmith.source(), 'assets/images'), path__default["default"].join(metalsmith.source(), 'images'), path__default["default"].join(metalsmith.destination(), 'assets/images'), path__default["default"].join(process.cwd(), 'lib/assets/images'), path__default["default"].join(process.cwd(), 'src/assets/images')];
+      for (const altPath of altPaths) {
+        debug(`Trying alternative path: ${altPath} - exists: ${fs__default["default"].existsSync(altPath)}`);
+        if (fs__default["default"].existsSync(altPath)) {
+          debug(`Found images at alternative path: ${altPath}`);
+
+          // Scan the found alternative path
+          const scanAlternativeDirectory = (dir, relativePath = '') => {
+            const items = fs__default["default"].readdirSync(dir);
+            debug(`Found ${items.length} items in alternative path ${dir}`);
+            for (const item of items) {
+              if (item === '.DS_Store') {
+                continue;
+              }
+              const fullPath = path__default["default"].join(dir, item);
+              const itemRelativePath = path__default["default"].join(relativePath, item);
+              if (fs__default["default"].statSync(fullPath).isDirectory()) {
+                debug(`Scanning alternative subdirectory: ${item}`);
+                scanAlternativeDirectory(fullPath, itemRelativePath);
+              } else {
+                const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+                if (imageExtensions.some(ext => item.toLowerCase().endsWith(ext))) {
+                  // Skip if this is in the responsive output directory
+                  if (itemRelativePath.startsWith('responsive/') || itemRelativePath.includes('/responsive/') || fullPath.includes(config.outputDir)) {
+                    debug(`Skipping responsive variant in alt scan: ${itemRelativePath}`);
+                    continue;
+                  }
+
+                  // For build directory, the path structure is already correct
+                  const buildPath = altPath.includes('build') ? path__default["default"].join('assets/images', itemRelativePath) : path__default["default"].join('assets/images', itemRelativePath);
+                  const normalizedBuildPath = buildPath.replace(/\\/g, '/');
+                  debug(`Found alternative filesystem image: ${item} -> ${normalizedBuildPath}`);
+                  debug(`Already processed? ${processedImagePaths.has(normalizedBuildPath)}`);
+                  if (!processedImagePaths.has(normalizedBuildPath)) {
+                    debug(`Found unprocessed alternative filesystem image: ${itemRelativePath}`);
+                    const imageBuffer = fs__default["default"].readFileSync(fullPath);
+                    unprocessedImages.push({
+                      path: itemRelativePath,
+                      buffer: imageBuffer,
+                      source: 'filesystem-alt'
+                    });
+                  }
+                }
+              }
+            }
+          };
+          scanAlternativeDirectory(altPath);
+          break; // Stop after finding and scanning the first valid path
+        }
+      }
+    }
+  } catch (err) {
+    debug(`Error scanning filesystem: ${err.message}`);
+  }
+
+  // Method 2: Scan Metalsmith files object (for test scenarios and edge cases)
+  debug(`Scanning Metalsmith files object`);
+  const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+  Object.keys(files).forEach(filePath => {
+    // Skip if not an image
+    if (!imageExtensions.some(ext => filePath.toLowerCase().endsWith(ext))) {
+      return;
+    }
+
+    // Skip if it's already a responsive variant (comprehensive checks)
+    if (filePath.startsWith(`${config.outputDir}/`) || filePath.includes('/responsive/') || filePath.includes('responsive-images-manifest.json') || filePath.match(/-\d+w(-[a-f0-9]+)?\.(avif|webp|jpg|jpeg|png)$/i)) {
+      debug(`Skipping responsive variant in files object: ${filePath}`);
+      return;
+    }
+
+    // Skip if already processed during HTML scanning
+    if (processedImagePaths.has(filePath)) {
+      debug(`Skipping already processed files object image: ${filePath}`);
+      return;
+    }
+
+    // Check if we already found this image from filesystem scan
+    const isAlreadyFound = unprocessedImages.some(img => {
+      // For files object images starting with 'images/', check if filesystem found the same file
+      if (filePath.startsWith('images/')) {
+        const relativePath = filePath.replace('images/', '');
+        return img.path === relativePath;
+      }
+      return false;
+    });
+    if (!isAlreadyFound) {
+      debug(`Found unprocessed files object image: ${filePath}`);
+      unprocessedImages.push({
+        path: filePath,
+        buffer: files[filePath].contents,
+        source: 'files'
+      });
+    }
+  });
+  debug(`Found ${unprocessedImages.length} unprocessed images total`);
+  return unprocessedImages;
+}
+
+/**
+ * Process a background image to create 1x (original) and 2x (half-size) variants
+ * for use with CSS image-set() for retina displays
+ * @param {Buffer} buffer - Original image buffer
+ * @param {string} originalPath - Original image path
+ * @param {Function} debugFn - Debug function for logging
+ * @param {Object} config - Plugin configuration
+ * @return {Promise<Array<Object>>} - Array of generated variants
+ */
+async function processBackgroundImageVariants(buffer, originalPath, debugFn, config) {
+  const image = sharp__default["default"](buffer);
+  const metadata = await image.metadata();
+  const variants = [];
+  debugFn(`Processing background image ${originalPath}: ${metadata.width}x${metadata.height}`);
+
+  // Create 1x (original size) and 2x (half size) variants
+  const sizes = [{
+    width: metadata.width,
+    density: '1x'
+  }, {
+    width: Math.round(metadata.width / 2),
+    density: '2x'
+  }];
+
+  // Process both sizes in parallel
+  const sizePromises = sizes.map(async size => {
+    // Create a Sharp instance for this size
+    const resized = image.clone().resize({
+      width: size.width,
+      withoutEnlargement: true // Don't upscale images
+    });
+
+    // Get actual dimensions after resize
+    const resizedMeta = await resized.metadata();
+
+    // Process each format in parallel for this size
+    const formatPromises = config.formats.map(async format => {
+      try {
+        // Skip problematic format combinations
+        if (format === 'original' && metadata.format.toLowerCase() === 'webp') {
+          return null;
+        }
+
+        // Determine output format and Sharp method
+        let outputFormat = format;
+        let sharpMethod = format;
+        if (format === 'original') {
+          outputFormat = metadata.format.toLowerCase();
+          sharpMethod = outputFormat === 'jpeg' ? 'jpeg' : outputFormat;
+        }
+
+        // Apply format-specific processing
+        let processedImage = resized.clone();
+        const formatOptions = config.formatOptions[format === 'original' ? outputFormat : format] || {};
+        if (sharpMethod === 'avif') {
+          processedImage = processedImage.avif(formatOptions);
+        } else if (sharpMethod === 'webp') {
+          processedImage = processedImage.webp(formatOptions);
+        } else if (sharpMethod === 'jpeg') {
+          processedImage = processedImage.jpeg(formatOptions);
+        } else if (sharpMethod === 'png') {
+          processedImage = processedImage.png(formatOptions);
+        }
+
+        // Generate output buffer
+        const outputBuffer = await processedImage.toBuffer();
+
+        // Generate variant path without hash for easier CSS usage
+        const variantPath = generateBackgroundVariantPath(originalPath, size.width, outputFormat, config);
+        debugFn(`Generated background variant: ${variantPath} (${size.density})`);
+        return {
+          path: variantPath,
+          buffer: outputBuffer,
+          width: resizedMeta.width,
+          height: resizedMeta.height,
+          format: outputFormat,
+          density: size.density
+        };
+      } catch (err) {
+        debugFn(`Error processing ${format} format for ${originalPath}: ${err.message}`);
+        return null;
+      }
+    });
+    const formatResults = await Promise.all(formatPromises);
+    return formatResults.filter(result => result !== null);
+  });
+  const sizeResults = await Promise.all(sizePromises);
+
+  // Flatten the results
+  sizeResults.forEach(formatVariants => {
+    variants.push(...formatVariants);
+  });
+  debugFn(`Generated ${variants.length} background variants for ${originalPath}`);
+  return variants;
+}
+
+/**
+ * Generate background image variant path without hash for easier CSS usage
+ * Creates predictable filenames that can be written in CSS without knowing the hash
+ * @param {string} originalPath - Original image path
+ * @param {number} width - Target width
+ * @param {string} format - Target format
+ * @param {Object} config - Plugin configuration
+ * @return {string} - Generated path without hash
+ */
+function generateBackgroundVariantPath(originalPath, width, format, config) {
+  const parsedPath = path__default["default"].parse(originalPath);
+  const originalFormat = parsedPath.ext.slice(1).toLowerCase();
+
+  // If format is 'original', use the source format
+  const outputFormat = format === 'original' ? originalFormat : format;
+
+  // Create background pattern without hash: '[filename]-[width]w.[format]'
+  // Results in: 'header1-1000w.webp' instead of 'header1-1000w-abc12345.webp'
+  const outputName = config.outputPattern.replace('[filename]', parsedPath.name).replace('[width]', width).replace('[format]', outputFormat).replace('-[hash]', '') // Remove hash placeholder and preceding dash
+  .replace('[hash]', ''); // Remove any remaining hash placeholder
+
+  return path__default["default"].join(config.outputDir, outputName);
+}
+
 module.exports = optimizeImagesPlugin;
 //# sourceMappingURL=index.cjs.map