image-guard 5.2.1 → 5.2.3

package/CHANGELOG.md

@@ -4,11 +4,32 @@ Starting with version 5.2.0, all notable changes to Image Guard are documented i
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.3] - 2026-02-21
+
+### Fixed
+
+* Improved corrupt-file error detection to cover WebP and AVIF formats, normalize message casing before matching, and avoid false positives from the overly broad `Invalid` string match
+* Warned when a `.bak` file is left behind after a failed file replacement
+* Removed a dead code branch in result processing
+
+### Changed
+
+* Moved to compression and conversion running in parallel (non-overlapping file sets), reducing wall-clock time when `--heic-to-avif` is active
+* Reduced directory traversals from two to one in non-staged mode when `--heic-to-avif` is active
+* Extracted shared `MAX_FILE_SIZE` constant; aligned `node:fs` and `node:path` import style in `utils.js`
+* Extended test coverage for corrupt file detection and reporting
+
+## [5.2.2] - 2026-02-17
+
+### Fixed
+
+* Updated HEIC dry run to report actual file sizes instead of omitting size data
+
 ## [5.2.1] - 2026-02-17
 
 ### Changed
 
-* HEIC-to-AVIF conversion now uses lossy encoding (quality 80) instead of lossless, producing files smaller than the HEIC originals
+* Adjusted HEIC-to-AVIF conversion to use lossy instead of lossless encoding (quality 80), to produce files smaller than the HEIC originals but still at high quality
 * Removed redundant lossless compression pass after HEIC conversion
 * Documented Display P3 to sRGB color space mapping during HEIC conversion
 

package/README.md

@@ -4,7 +4,7 @@
 
 (This project was based on [sum.cumo’s imagemin-merlin](https://github.com/sumcumo/imagemin-merlin). [Changes are documented](https://github.com/sumcumo/imagemin-merlin/compare/master...j9t:master), and include this README. Image Guard supports additional file formats—WebP, AVIF, and HEIC/HEIF—, comes with improved code and documentation, and is being maintained. For this reason, it’s [not based on any Imagemin packages](https://meiert.com/blog/image-guard-4/) anymore.)
 
-Image Guard takes care of near-lossless compression of your images, to help you avoid bloat in your repositories. It makes it convenient and as safe as possible to automatically compress PNG, JPG, GIF, WebP, and AVIF images. It can also convert HEIC/HEIF files to AVIF (opt-in via `--heic-to-avif`).
+Image Guard takes care of near-lossless compression of your images, to help you avoid bloat in your repositories. It makes it convenient and as safe as possible to automatically compress PNG, JPG, GIF, WebP, and AVIF images. It can also convert HEIC/HEIF files to AVIF.
 
 It’s convenient because setup is simple. Run it right away—done. Or install, run, add hook—done.
 
@@ -140,7 +140,7 @@ Roughly like this:
 * Green: The image file has been compressed.
 * Cyan: The image file has been converted (HEIC/HEIF to AVIF).
 * White (light gray): The image file has not been changed.
-* Blue: The image file had already been compressed more aggressively than the new result, and was therefore skipped, too.
+* Blue: The image file had already been compressed more effectively than the new result, and was therefore skipped, too.
 
 Tip: Use `--quiet` to suppress these per‑file lines and keep only the final summary.
 

package/bin/image-guard.test.js

@@ -141,7 +141,7 @@ describe('Image Guard', () => {
     assert.strictEqual(allCompressed, true)
   })
 
-  test('Do not modify files in dry run', () => {
+  test('Ensure files are not modified in dry run', () => {
     const originalStats = fs.readdirSync(testFolderGit).sort().map(file => {
       const filePath = path.join(testFolderGit, file)
       return { file, stats: fs.statSync(filePath) }
@@ -298,7 +298,7 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('Quiet mode suppresses per-file logs but keeps summary', () => {
+  test('Ensure quiet mode suppresses per-file logs but keeps summary', () => {
     // Prepare isolated temp directory with test images
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-quiet-'))
     const tempTestFolder = path.join(tempDir, 'test')
@@ -320,7 +320,7 @@ describe('Image Guard', () => {
     assert.strictEqual(!(/Compressed|Skipped/.test(stdout)), true)
   })
 
-  test('Dry and quiet runs leave no artifacts and do not mutate files', () => {
+  test('Ensure dry and quiet runs leave no artifacts and do not mutate files', () => {
     // Use isolated temp directory
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-dry-quiet-'))
     const tempTestFolder = path.join(tempDir, 'test')
@@ -368,7 +368,7 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('No .bak files remain after normal compression', () => {
+  test('Ensure no .bak files remain after normal compression', () => {
     // Prepare isolated temp directory with test images
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-bak-'))
     const tempTestFolder = path.join(tempDir, 'test')
@@ -428,7 +428,7 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('`--keep-heic` preserves original HEIC file', () => {
+  test('Ensure `--keep-heic` preserves original HEIC file', () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-keep-heic-'))
     const tempTestFolder = path.join(tempDir, 'test')
     copyFiles(testFolder, tempTestFolder)
@@ -451,19 +451,26 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('Dry run does not convert HEIC files', () => {
+  test('Ensure dry run does not convert HEIC files but reports sizes', () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-dry-'))
     const tempTestFolder = path.join(tempDir, 'test')
     copyFiles(testFolder, tempTestFolder)
 
+    // Remove pre-existing AVIF so the conversion path is exercised
+    const avifFile = path.join(tempTestFolder, 'test.avif')
+    if (fs.existsSync(avifFile)) {
+      fs.unlinkSync(avifFile)
+    }
+
     const heicFile = path.join(tempTestFolder, 'test.heic')
     const heicBefore = fs.statSync(heicFile)
     const filesBefore = fs.readdirSync(tempTestFolder).sort()
 
     const originalCwd = process.cwd()
+    let output = ''
     try {
       process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}" --heic-to-avif --dry`, { stdio: 'pipe' })
+      output = execSync(`node "${imageGuardScript}" --heic-to-avif --dry`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
     } finally {
       process.chdir(originalCwd)
     }
@@ -477,10 +484,13 @@ describe('Image Guard', () => {
     const filesAfter = fs.readdirSync(tempTestFolder).sort()
     assert.deepStrictEqual(filesAfter, filesBefore)
 
+    // Dry run should report size data for HEIC conversion
+    assert.match(output, /Converted.*test\.heic.*KB.*→.*KB/i, 'Dry run should report HEIC conversion sizes')
+
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('HEIC files are ignored without `--heic-to-avif` flag', () => {
+  test('Ensure HEIC files are ignored without `--heic-to-avif` flag', () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-noflag-'))
     const tempTestFolder = path.join(tempDir, 'test')
     copyFiles(testFolder, tempTestFolder)
@@ -504,7 +514,25 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('`--keep-heic` without `--heic-to-avif` warns', () => {
+  test('Skip and report corrupt files', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-corrupt-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    const originalCwd = process.cwd()
+    let output = ''
+    try {
+      process.chdir(tempDir)
+      output = execSync(`node "${imageGuardScript}"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+    } finally {
+      process.chdir(originalCwd)
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+
+    assert.match(output, /Skipped.*test#corrupt\.gif.*corrupt file/i)
+  })
+
+  test('Ensure `--keep-heic` without `--heic-to-avif` issues warning', () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-keep-warn-'))
     const tempTestFolder = path.join(tempDir, 'test')
     copyFiles(testFolder, tempTestFolder)

package/package.json

@@ -46,5 +46,5 @@
     "test": "node --test bin/image-guard.test.js"
   },
   "type": "module",
-  "version": "5.2.1"
+  "version": "5.2.3"
 }

package/src/index.js

@@ -97,11 +97,7 @@ export async function runImageGuard() {
     let addedKB = 0
     for (const r of results) {
       if (r.status === 'fulfilled') {
-        if (typeof r.value === 'number') {
-          addedKB += r.value
-        } else {
-          hadFailures = true
-        }
+        addedKB += r.value
       } else {
         hadFailures = true
         const reason = r.reason && r.reason.message ? r.reason.message : String(r.reason)
@@ -192,32 +188,44 @@ export async function runImageGuard() {
       const diffOutput = await git.raw(['diff', '--name-only', '--cached', '--diff-filter=ACMRT'])
       const stagedFiles = diffOutput.split('\n').map(s => s.trim()).filter(Boolean)
 
-      const compressionFiles = await filterStagedFiles(stagedFiles, fileTypes)
-      totalFiles += compressionFiles.length
-      hadFailures = await compress(compressionFiles, argv.dry)
-
-      if (doConversion) {
-        const conversionFiles = await filterStagedFiles(stagedFiles, convertTypes)
-        totalFiles += conversionFiles.length
-        const convFailed = await convert(conversionFiles, argv.dry, argv['keep-heic'])
-        hadFailures = hadFailures || convFailed
-      }
+      // Collect compression and conversion candidates in parallel
+      const [compressionFiles, conversionFiles] = await Promise.all([
+        filterStagedFiles(stagedFiles, fileTypes),
+        doConversion ? filterStagedFiles(stagedFiles, convertTypes) : Promise.resolve([])
+      ])
+      totalFiles += compressionFiles.length + conversionFiles.length
+
+      // Run compression and conversion in parallel (non-overlapping file sets)
+      const [compFailed, convFailed] = await Promise.all([
+        compress(compressionFiles, argv.dry),
+        convert(conversionFiles, argv.dry, argv['keep-heic'])
+      ])
+      hadFailures = compFailed || convFailed
     } catch (err) {
       console.error(err)
       hadFailures = true
     }
   } else {
-    const patterns = getFilePattern(argv.ignore)
-    const compressionFiles = await findFiles(patterns)
+    // Single directory traversal for all relevant types
+    const allFiles = await findFiles(getFilePattern(argv.ignore, allTypes))
+
+    const compExts = new Set(fileTypes)
+    const compressionFiles = allFiles.filter(f => compExts.has(path.extname(f).slice(1).toLowerCase()))
     totalFiles += compressionFiles.length
-    hadFailures = await compress(compressionFiles, argv.dry)
 
     if (doConversion) {
-      const convPatterns = getFilePattern(argv.ignore, convertTypes)
-      const conversionFiles = await findFiles(convPatterns)
+      const convExts = new Set(convertTypes)
+      const conversionFiles = allFiles.filter(f => convExts.has(path.extname(f).slice(1).toLowerCase()))
       totalFiles += conversionFiles.length
-      const convFailed = await convert(conversionFiles, argv.dry, argv['keep-heic'])
-      hadFailures = hadFailures || convFailed
+
+      // Run compression and conversion in parallel (non-overlapping file sets)
+      const [compFailed, convFailed] = await Promise.all([
+        compress(compressionFiles, argv.dry),
+        convert(conversionFiles, argv.dry, argv['keep-heic'])
+      ])
+      hadFailures = compFailed || convFailed
+    } else {
+      hadFailures = await compress(compressionFiles, argv.dry)
     }
   }
 

package/src/utils.js

@@ -1,11 +1,13 @@
 // This file, which had been forked from imagemin-merlin, was modified for image-guard: https://github.com/sumcumo/imagemin-merlin/compare/master...j9t:master
 
-import fs from 'fs'
-import path from 'path'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
 import sharp from 'sharp'
 import { styleText } from 'node:util'
 import decode from 'heic-decode'
 
+const MAX_FILE_SIZE = 100 * 1024 * 1024 // 100 MB
+
 const logMessage = (message, dry, color = 'yellow', quiet = false) => {
   if (quiet) return
   const prefix = dry ? 'Dry run: ' : ''
@@ -38,9 +40,7 @@ const compression = async (filename, dry, quiet = false) => {
     return 0
   }
 
-  const maxFileSize = 100 * 1024 * 1024 // 100 MB
-
-  if (fileSizeBefore > maxFileSize) {
+  if (fileSizeBefore > MAX_FILE_SIZE) {
     logMessage(`Skipped ${filename} (file too large: ${sizeReadable(fileSizeBefore)})`, dry, 'yellow', quiet)
     return 0
   }
@@ -114,17 +114,17 @@ const compression = async (filename, dry, quiet = false) => {
       details = `${sizeReadable(fileSizeBefore)} → ${sizeReadable(fileSizeAfter)}`
       if (!dry) {
         // Only now create a backup and replace the original
-        await retryFileOperation(() => fs.promises.copyFile(filename, filenameBackup))
+        await retryFileOperation(() => fs.copyFile(filename, filenameBackup))
         // Prefer atomic rename when possible
         try {
-          await retryFileOperation(() => fs.promises.rename(tempFilePath, filename))
+          await retryFileOperation(() => fs.rename(tempFilePath, filename))
           // Temp file was renamed (consumed)
           tempConsumed = true
           replacementSucceeded = true
         } catch {
           // Fallback to copy when rename across devices isn’t possible
-          await retryFileOperation(() => fs.promises.copyFile(tempFilePath, filename))
-          await retryFileOperation(() => fs.promises.unlink(tempFilePath))
+          await retryFileOperation(() => fs.copyFile(tempFilePath, filename))
+          await retryFileOperation(() => fs.unlink(tempFilePath))
           // Temp file explicitly removed after copy
           tempConsumed = true
           replacementSucceeded = true
@@ -133,23 +133,13 @@ const compression = async (filename, dry, quiet = false) => {
     } else if (fileSizeAfter > fileSizeBefore) {
       color = 'blue'
       status = 'Skipped'
-      details = 'already compressed more aggressively'
+      details = 'already compressed more effectively'
     }
 
     logMessage(`${status} ${filename} (${details})`, dry, color, quiet)
 
     if (dry) {
-      await retryFileOperation(() => fs.promises.unlink(tempFilePath))
-      return 0
-    }
-
-    // Clean up temp file only when it wasn’t consumed
-    if (!tempConsumed) {
-      try {
-        await retryFileOperation(() => fs.promises.unlink(tempFilePath))
-      } catch (err) {
-        if (err.code !== 'ENOENT') throw err
-      }
+      return 0 // Temp file cleaned up in finally
     }
 
     if (fileSizeAfter === 0) {
@@ -160,15 +150,17 @@ const compression = async (filename, dry, quiet = false) => {
 
   } catch (err) {
 
-    // Check if this is a file corruption error
-    if (err.message && (
-      err.message.includes('corrupt header') ||
-      err.message.includes('Unexpected end of') ||
-      err.message.includes('Invalid') ||
-      err.message.includes('gifload:') ||
-      err.message.includes('pngload:') ||
-      err.message.includes('jpegload:')
-    )) {
+    // Check if this is a file corruption error (sharp/libvips error messages)
+    const msg = err.message ? err.message.toLowerCase() : ''
+    if (msg.includes('corrupt header') ||
+      msg.includes('unexpected end of') ||
+      msg.includes('invalid image') ||
+      msg.includes('gifload:') ||
+      msg.includes('pngload:') ||
+      msg.includes('jpegload:') ||
+      msg.includes('webpload:') ||
+      msg.includes('avifload:')
+    ) {
       logMessage(`Skipped ${filename} (corrupt file)`, dry, 'yellow', quiet)
     } else {
       console.error(styleText('red', `Error compressing ${filename}:`), err)
@@ -177,15 +169,32 @@ const compression = async (filename, dry, quiet = false) => {
 
   } finally {
 
+    // Clean up temp file if it wasn’t consumed (covers dry-run, error, and no-improvement paths)
+    if (!tempConsumed) {
+      try {
+        await retryFileOperation(() => fs.unlink(tempFilePath))
+      } catch {
+        // Best-effort cleanup—ignore all errors to avoid masking the original error
+      }
+    }
+
     // If backup created (i.e., only in improvement path), try to remove it
     if (!dry && replacementSucceeded) {
       try {
-        await retryFileOperation(() => fs.promises.unlink(filenameBackup))
+        await retryFileOperation(() => fs.unlink(filenameBackup))
       } catch (err) {
         if (err.code !== 'ENOENT') {
           console.warn(styleText('yellow', `Failed to delete backup file ${filenameBackup}:`), err)
         }
       }
+    } else if (!dry && !replacementSucceeded) {
+      // If a backup was created but replacement failed, warn so the user can recover it
+      try {
+        await fs.access(filenameBackup)
+        console.warn(styleText('yellow', `Replacement failed for ${filename}; backup preserved at ${filenameBackup}`))
+      } catch {
+        // No backup exists—nothing to warn about
+      }
     }
 
   }
@@ -199,9 +208,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
     return 0
   }
 
-  const maxFileSize = 100 * 1024 * 1024 // 100 MB
-
-  if (fileSizeBefore > maxFileSize) {
+  if (fileSizeBefore > MAX_FILE_SIZE) {
     logMessage(`Skipped ${filename} (file too large: ${sizeReadable(fileSizeBefore)})`, dry, 'yellow', quiet)
     return 0
   }
@@ -215,7 +222,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
 
   // Avoid overwriting an existing AVIF file
   try {
-    await fs.promises.access(avifPath)
+    await fs.access(avifPath)
     logMessage(`Skipped ${filename} (${path.basename(avifPath)} already exists)`, dry, 'yellow', quiet)
     return 0
   } catch {
@@ -224,14 +231,9 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
 
   try {
     // Decode HEIC/HEIF to raw pixel data
-    const inputBuffer = await fs.promises.readFile(filename)
+    const inputBuffer = await fs.readFile(filename)
     const { width, height, data } = await decode({ buffer: inputBuffer })
 
-    if (dry) {
-      logMessage(`Converted ${filename} → ${path.basename(avifPath)}`, dry, 'cyan', quiet)
-      return 0
-    }
-
     // Encode as lossy AVIF—HEIC sources are already lossy (HEVC), so lossless
     // re-encoding would inflate file sizes without any quality benefit
     await sharp(data, { raw: { width, height, channels: 4 } })
@@ -242,9 +244,14 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
 
     logMessage(`Converted ${filename} → ${path.basename(avifPath)} (${sizeReadable(fileSizeBefore)} → ${sizeReadable(fileSizeAfter)})`, dry, 'cyan', quiet)
 
+    if (dry) {
+      await retryFileOperation(() => fs.unlink(avifPath))
+      return 0
+    }
+
     // Delete original HEIC/HEIF file unless `--keep-heic` is set
     if (!keepOriginal) {
-      await retryFileOperation(() => fs.promises.unlink(filename))
+      await retryFileOperation(() => fs.unlink(filename))
     }
 
     return fileSizeAfter < fileSizeBefore ? fileSizeBefore - fileSizeAfter : 0
@@ -252,7 +259,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
   } catch (err) {
     // Clean up partial AVIF if it was created
     try {
-      await fs.promises.unlink(avifPath)
+      await retryFileOperation(() => fs.unlink(avifPath))
     } catch (cleanupErr) {
       if (cleanupErr.code !== 'ENOENT') {
         console.warn(styleText('yellow', `Failed to clean up ${avifPath}:`), cleanupErr)
@@ -272,7 +279,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
 }
 
 const size = async (file) => {
-  const stats = await fs.promises.stat(file)
+  const stats = await fs.stat(file)
   return stats.size
 }