image-guard 5.2.0 → 5.2.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.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
+* Removed redundant lossless compression pass after HEIC conversion
+* Documented Display P3 to sRGB color space mapping during HEIC conversion
+
 ## [5.2.0] - 2026-02-17
 
 ### Added

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.
 
@@ -111,7 +111,7 @@ npm pkg set scripts.postprepare="grep -qxF 'npx image-guard --staged' .husky/pre
 
 * `--staged` (recommended with automated use) triggers a mode that watches PNG, JPG, GIF, WebP, and AVIF files (and HEIC/HEIF, when `--heic-to-avif` is used) in `git diff` and only processes those files—that approach makes Image Guard more efficient in operation.
 
-* `--heic-to-avif` converts HEIC/HEIF files to lossless AVIF. The conversion decodes HEIC/HEIF pixel data and re-encodes it as lossless AVIF, then runs the result through Image Guard’s compression pipeline. Original HEIC/HEIF files are deleted after conversion by default.
+* `--heic-to-avif` converts HEIC/HEIF files to AVIF. Because HEIC sources are already lossy-compressed (HEVC), the conversion uses lossy AVIF encoding (quality 80) to produce files smaller than the originals at near-identical visual quality. Original HEIC/HEIF files are deleted after conversion by default. (Note: The conversion maps Display P3 colors—common on iPhones—to sRGB, which may result in slightly less vivid colors.)
 
   - `--keep-heic` (used with `--heic-to-avif`) preserves the original HEIC/HEIF files instead of deleting them after conversion.
 
@@ -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.
 
@@ -148,7 +148,7 @@ Tip: Use `--quiet` to suppress these per‑file lines and keep only the final su
 
 Image Guard is a Node script that uses [sharp](https://www.npmjs.com/package/sharp) under the hood.
 
-Automated compression works by monitoring whether a given [change list](https://webglossary.info/terms/change-list/) includes any PNGs, JPGs, GIFs, WebPs, or AVIFs (and HEIC/HEIF when opted in). It’s initiated by a Git hook. Only those images are compressed where there is an improvement. HEIC conversion uses [heic-decode](https://www.npmjs.com/package/heic-decode) for patent-free decoding and sharp for AVIF encoding. The processed images can then be committed to the underlying repository.
+Automated compression works by monitoring whether a given [change list](https://webglossary.info/terms/change-list/) includes any PNGs, JPGs, GIFs, WebPs, or AVIFs (and HEIC/HEIF when opted in). It’s initiated by a Git hook. Only those images are compressed where there is an improvement. HEIC conversion uses [heic-decode](https://www.npmjs.com/package/heic-decode) for patent-free decoding and sharp for lossy AVIF encoding (quality 80). The processed images can then be committed to the underlying repository.
 
 Through this approach, though glossed over here, Image Guard makes up for what’s missing or complicated in other packages, namely easy, near-riskless, automatable, resource-friendly in-repo optimization.
 

package/bin/image-guard.test.js

@@ -415,7 +415,12 @@ describe('Image Guard', () => {
 
     // AVIF should be created by the conversion
     assert.strictEqual(fs.existsSync(avifFile), true, 'AVIF file should be created')
-    assert.ok(fs.statSync(avifFile).size > 0, 'AVIF file should not be empty')
+    const avifSize = fs.statSync(avifFile).size
+    assert.ok(avifSize > 0, 'AVIF file should not be empty')
+
+    // Lossy AVIF should not be larger than the HEIC source
+    const heicSize = fs.statSync(path.join(testFolder, 'test.heic')).size
+    assert.ok(avifSize <= heicSize, `AVIF (${avifSize}) should not be larger than HEIC (${heicSize})`)
 
     // Original HEIC should be deleted
     assert.strictEqual(fs.existsSync(heicFile), false, 'Original HEIC should be deleted')
@@ -446,19 +451,26 @@ describe('Image Guard', () => {
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
 
-  test('Dry run does not convert HEIC files', () => {
+  test('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)
     }
@@ -472,6 +484,9 @@ 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 })
   })
 

package/package.json

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

package/src/utils.js

@@ -133,7 +133,7 @@ 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)
@@ -227,30 +227,27 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
     const inputBuffer = await fs.promises.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 lossless AVIF (pass the decoded view directly to avoid extra-byte issues)
+    // 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 } })
-      .toFormat('avif', { effort: 5, lossless: true })
+      .toFormat('avif', { quality: 80, effort: 5 })
       .toFile(avifPath)
 
     const fileSizeAfter = await size(avifPath)
 
     logMessage(`Converted ${filename} → ${path.basename(avifPath)} (${sizeReadable(fileSizeBefore)} → ${sizeReadable(fileSizeAfter)})`, dry, 'cyan', quiet)
 
-    // Compress the resulting AVIF through the standard compression pipeline
-    const saved = await compression(avifPath, dry, quiet)
+    if (dry) {
+      await retryFileOperation(() => fs.promises.unlink(avifPath))
+      return 0
+    }
 
-    // Delete original HEIC/HEIF file unless --keep-heic is set (deferred until after compression succeeds)
+    // Delete original HEIC/HEIF file unless `--keep-heic` is set
     if (!keepOriginal) {
       await retryFileOperation(() => fs.promises.unlink(filename))
     }
 
-    // Return compression savings only (conversion size change is informational)
-    return saved
+    return fileSizeAfter < fileSizeBefore ? fileSizeBefore - fileSizeAfter : 0
 
   } catch (err) {
     // Clean up partial AVIF if it was created