image-guard 5.4.2 → 5.5.0

package/README.md

@@ -121,6 +121,8 @@ Image Guard takes an optional path to the directory to process—`npx image-guar
 
 * `--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) from staged changes (`git diff --cached`) and only processes those files—that approach makes Image Guard more efficient in operation. Because the file set comes from Git, `--staged` can’t be combined with a path.
 
+* `--no-cache` processes all images, including those recorded as already processed (see [“Record of Processed Images”](#record-of-processed-images)).
+
 * `--help`/`-h` lists the arguments and options.
 
 * `--version`/`-V` prints the version number.
@@ -146,11 +148,17 @@ Automated compression works by monitoring whether a given [change list](https://
 
 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.
 
+### Record of Processed Images
+
+To keep repeat runs fast, Image Guard remembers which images it has already processed (compressed, or found not to shrink any further) by their content, and skips them in later runs. This also protects JPG and GIF images from being re-encoded over and over. An image is processed again as soon as its content changes, and all images are when the compression settings or the underlying image libraries change (as through an update).
+
+The record is kept in node_modules/.cache/image-guard of the project being processed, or—where there is no node_modules folder, as is common with `npx`—in the per-user cache folder (~/Library/Caches/image-guard on macOS, %LOCALAPPDATA%\image-guard\Cache on Windows, and ~/.cache/image-guard elsewhere). The `IMAGE_GUARD_CACHE_DIR` environment variable sets a different folder—for example, to persist the record in CI. Deleting the folder, or using `--no-cache`, makes Image Guard process all images again.
+
 ## Why Use Image Guard?
 
 You use Image Guard when you need a simple, automatable, robust solution to compress images in a way that limits unnecessary image payload right from the start, in your repositories, and that reduces the risk that entirely uncompressed images go into production.
 
-As Image Guard compresses near-losslessly, there’s little risk of quality issues from compression. (Lossless compression is not possible for every image format, however, so there’s a risk when excessively iterating over the same images. Doing so may eventually degrade quality.)
+As Image Guard compresses near-losslessly, there’s little risk of quality issues from compression. (Lossless compression is not possible for every image format, however, so there’s a risk when excessively iterating over the same images. Doing so may eventually degrade quality. The [record of processed images](#record-of-processed-images) prevents this, unless it’s bypassed or cleared.)
 
 ## What Does Image Guard _Not_ Do?
 
@@ -168,7 +176,7 @@ To check how a change affects speed, memory, and compression, run the benchmark
 npm run benchmark -- ~/Projects
 ```
 
-The benchmark copies a deterministic sample of the images (honoring .gitignore) to a temporary folder, runs Image Guard on fresh copies of it several times, and reports the median time, peak memory, and bytes saved. Your images are not modified.
+The benchmark copies a deterministic sample of the images (honoring .gitignore) to a temporary folder, runs Image Guard on fresh copies of it several times (each without a record of processed images), and reports the median time, peak memory, and bytes saved. Your images are not modified.
 
 * `--runs <n>` sets the number of runs (default: 3).
 * `--sample <n>` sets the approximate sample size (default: 300). Each format is sampled in proportion to its share, with at least 10 files per format where available.

package/package.json

@@ -60,5 +60,5 @@
     "test": "node --test bin/image-guard.test.js benchmark/benchmark.test.js"
   },
   "type": "module",
-  "version": "5.4.2"
+  "version": "5.5.0"
 }

package/src/cache.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { styleStderr } from './utils.js'
+
+// Records made with other settings or encoder versions are deleted once unused for this long
+const MAX_AGE_STALE = 30 * 24 * 60 * 60 * 1000
+
+// Matches record files only, as the folder may be shared (see `IMAGE_GUARD_CACHE_DIR`)
+const PATTERN_RECORD = /^[0-9a-f]{16}\.txt$/
+
+// The nearest project’s node_modules/.cache, else the per-user cache folder
+export function findDirCache(dirStart) {
+  if (process.env.IMAGE_GUARD_CACHE_DIR) return path.resolve(process.env.IMAGE_GUARD_CACHE_DIR)
+  for (let current = path.resolve(dirStart); ; current = path.dirname(current)) {
+    if (fs.existsSync(path.join(current, 'package.json'))) {
+      const dirModules = path.join(current, 'node_modules')
+      if (fs.existsSync(dirModules)) return path.join(dirModules, '.cache', 'image-guard')
+      break
+    }
+    if (path.dirname(current) === current) break
+  }
+  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Caches', 'image-guard')
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'image-guard', 'Cache')
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'image-guard')
+}
+
+// Remembers images that compression can’t shrink any further (as format and
+// content hash); the fingerprint keeps records apart per compression settings
+// and encoder version, so changing either processes all images again
+export function createCache(dirStart, fingerprint) {
+  const dirCache = findDirCache(dirStart)
+  const fileRecord = path.join(dirCache, `${fingerprint}.txt`)
+  const added = []
+  let entries = new Set()
+  let hits = 0
+
+  try {
+    entries = new Set(fs.readFileSync(fileRecord, 'utf8').split('\n').filter(Boolean))
+  } catch (err) {
+    if (err.code !== 'ENOENT') console.warn(styleStderr('yellow', `Could not read the record of processed images (${err.message})`))
+  }
+
+  return {
+    has(entry) {
+      const found = entries.has(entry)
+      if (found) hits++
+      return found
+    },
+    add(entry) {
+      if (entries.has(entry)) return
+      entries.add(entry)
+      added.push(entry)
+    },
+    get hits() {
+      return hits
+    },
+    save() {
+      if (added.length === 0) {
+        // Keeps runs with other settings from deleting a record that’s still in use
+        if (hits > 0) {
+          try {
+            const now = new Date()
+            fs.utimesSync(fileRecord, now, now)
+          } catch {
+            // Best-effort—at worst, the images are processed once more
+          }
+        }
+        return
+      }
+      try {
+        fs.mkdirSync(dirCache, { recursive: true })
+        // Appending (rather than rewriting) keeps what concurrent runs add
+        fs.appendFileSync(fileRecord, added.map(entry => `${entry}\n`).join(''))
+      } catch (err) {
+        console.warn(styleStderr('yellow', `Could not save the record of processed images (${err.message})`))
+        return
+      }
+      let names = []
+      try {
+        names = fs.readdirSync(dirCache)
+      } catch {
+        // Nothing to clean up if the folder can’t be read
+      }
+      for (const name of names) {
+        const file = path.join(dirCache, name)
+        if (file === fileRecord || !PATTERN_RECORD.test(name)) continue
+        try {
+          if (Date.now() - fs.statSync(file).mtimeMs > MAX_AGE_STALE) fs.rmSync(file)
+        } catch (err) {
+          // Another run may have deleted it already
+          if (err.code !== 'ENOENT') console.warn(styleStderr('yellow', `Could not delete outdated record ${file} (${err.message})`))
+        }
+      }
+    }
+  }
+}

package/src/index.js

@@ -7,6 +7,7 @@ import fsSync from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import sharp from 'sharp'
+import { createCache } from './cache.js'
 import { createGitignoreFilter } from './gitignore.js'
 import { styleStderr, utils } from './utils.js'
 
@@ -31,6 +32,7 @@ export async function runImageGuard() {
     quiet: { type: 'boolean', short: 'q', default: false },
     dry: { type: 'boolean', short: 'd', default: false },
     staged: { type: 'boolean', default: false },
+    'no-cache': { type: 'boolean', default: false },
     help: { type: 'boolean', short: 'h', default: false },
     version: { type: 'boolean', short: 'V', default: false }
   }
@@ -59,6 +61,7 @@ Options:
   -q, --quiet           Print only the final summary
   -d, --dry             Show what would change without writing any files
       --staged          Process only images staged in Git (not combinable with a directory)
+      --no-cache        Process images even if recorded as already processed
   -h, --help            Show this help
   -V, --version         Show the version number`)
     return
@@ -89,11 +92,20 @@ Options:
     throw setupError(`Not a directory: ${dir}`)
   }
 
+  // Remembers images that can’t be compressed further, so later runs can skip them
+  const cache = argv['no-cache'] ? undefined : createCache(argv.staged ? '.' : dir, utils.fingerprint)
+
+  const noteCached = () => {
+    const hits = cache?.hits ?? 0
+    if (hits === 0) return ''
+    return hits === 1 ? ' 1 image was skipped as already processed.' : ` ${hits} images were skipped as already processed.`
+  }
+
   // Share status
   const summary = (run, includesConversion = false) => {
     if (run) {
       const action = includesConversion ? 'compression and conversion' : 'compression'
-      console.info(styleText(['bold'], `\nDefensive base ${action} completed. You saved ${utils.sizeReadable(savedKB)}.`))
+      console.info(styleText(['bold'], `\nDefensive base ${action} completed. You saved ${utils.sizeReadable(savedKB)}.${noteCached()}`))
     } else {
       const what = includesConversion ? 'images to compress or convert' : 'images to compress'
       console.info(styleText(['bold'], `There were no ${what}.`))
@@ -181,7 +193,7 @@ Options:
   const compress = async (files, dry) => {
     if (files.length === 0) return false
 
-    const tasks = files.map(file => limit(() => utils.compression(file, dry, argv.quiet)))
+    const tasks = files.map(file => limit(() => utils.compression(file, dry, argv.quiet, cache)))
     const results = await Promise.allSettled(tasks)
 
     const { hadFailures, addedKB } = processResults(results)
@@ -309,11 +321,13 @@ Options:
     }
   }
 
+  if (!argv.dry) cache?.save()
+
   if (hadFailures) {
     process.exitCode = 1
     if (totalFiles > 0) {
       const action = doConversion ? 'compression and conversion' : 'compression'
-      const savings = savedKB > 0 ? ` You saved ${utils.sizeReadable(savedKB)}.` : ''
+      const savings = `${savedKB > 0 ? ` You saved ${utils.sizeReadable(savedKB)}.` : ''}${noteCached()}`
       console.info(styleText(['bold'], `\nDefensive base ${action} partially completed (some tasks failed).${savings}`))
     } else {
       summary(false, doConversion)

package/src/utils.js

@@ -1,5 +1,6 @@
 // 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 { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import sharp from 'sharp'
@@ -8,6 +9,42 @@ import decode from 'heic-decode'
 
 const MAX_FILE_SIZE = 100 * 1024 * 1024 // 100 MB
 
+// Compression configuration for each format (as sharp names them)
+const formatConfigs = {
+  jpeg: {
+    options: {},
+    settings: { quality: 100 }
+  },
+  png: {
+    options: { pages: -1 },
+    settings: { animated: true, compressionLevel: 9, quality: 100 } // Still waiting for APNG support though (`animated` doesn’t seem to have an effect), https://github.com/lovell/sharp/issues/2375
+  },
+  gif: {
+    options: { pages: -1 },
+    settings: {
+      reuse: true,               // Preserve original palette for lossless quality (default)
+      effort: 10,                // Maximum compression effort
+      dither: 0,                 // No dithering = lossless quality
+      interFrameMaxError: 0,     // No transparency errors = lossless (default)
+      interPaletteMaxError: 0,   // Perfect palette match = lossless
+      colors: 256                // Full palette available (default)
+    }
+  },
+  webp: {
+    options: { pages: -1 },
+    settings: { animated: true, lossless: true }
+  },
+  avif: {
+    options: {},
+    settings: { effort: 5, lossless: true } // Temporarily specifying effort, too, as per https://github.com/lovell/sharp/issues/4370#issuecomment-2798848572
+  }
+}
+
+export const hash = (data) => createHash('sha256').update(data).digest('hex')
+
+// Identifies what compression results depend on, to tell when recorded results no longer apply
+const fingerprint = hash(JSON.stringify({ formatConfigs, versions: sharp.versions })).slice(0, 16)
+
 // `styleText` detects color on `process.stdout` by default, so anything bound
 // for STDERR has to name that stream—otherwise a redirected STDERR collects
 // escape codes whenever STDOUT happens to be a terminal
@@ -34,7 +71,7 @@ const retryFileOperation = async (operation, maxRetries = 5, delayMs = 100) => {
   }
 }
 
-const compression = async (filename, dry, quiet = false) => {
+const compression = async (filename, dry, quiet = false, cache) => {
   const filenameBackup = `${filename}.bak`
   const fileSizeBefore = await size(filename)
   // Track whether original file was successfully replaced
@@ -66,48 +103,28 @@ const compression = async (filename, dry, quiet = false) => {
     }
 
     const outputFormat = ext === 'jpg' ? 'jpeg' : ext // sharp uses “jpeg” instead of “jpg”
-
-    // Compression configuration for each format
-    const formatConfigs = {
-      png: {
-        options: { pages: -1 },
-        settings: { animated: true, compressionLevel: 9, quality: 100 } // Still waiting for APNG support though (`animated` doesn’t seem to have an effect), https://github.com/lovell/sharp/issues/2375
-      },
-      gif: {
-        options: { pages: -1 },
-        settings: {
-          reuse: true,               // Preserve original palette for lossless quality (default)
-          effort: 10,                // Maximum compression effort
-          dither: 0,                 // No dithering = lossless quality
-          interFrameMaxError: 0,     // No transparency errors = lossless (default)
-          interPaletteMaxError: 0,   // Perfect palette match = lossless
-          colors: 256                // Full palette available (default)
-        }
-      },
-      webp: {
-        options: { pages: -1 },
-        settings: { animated: true, lossless: true }
-      },
-      avif: {
-        options: {},
-        settings: { effort: 5, lossless: true } // Temporarily specifying effort, too, as per https://github.com/lovell/sharp/issues/4370#issuecomment-2798848572
-      }
+    const config = formatConfigs[outputFormat]
+    if (!config) {
+      throw new Error(`Unsupported file type for ${filename}`)
     }
 
-    // Apply format-specific compression or use default
-    const config = formatConfigs[outputFormat]
-    if (config) {
-      await sharp(filename, config.options)
-        .toFormat(outputFormat, config.settings)
-        .toFile(tempFilePath)
-    } else {
-      // Fallback for any other supported formats (like JPG)
-      await sharp(filename)
-        .toFormat(outputFormat, { quality: 100 })
-        .toFile(tempFilePath)
+    // The format follows the extension
+    const toEntry = (data) => `${outputFormat}:${hash(data)}`
+
+    const input = await fs.readFile(filename)
+    const entryInput = cache ? toEntry(input) : undefined
+    if (cache?.has(entryInput)) {
+      logMessage(`Skipped ${filename} (already processed)`, dry, 'white', quiet)
+      return 0
     }
 
-    const fileSizeAfter = await size(tempFilePath)
+    const output = await sharp(input, config.options)
+      .toFormat(outputFormat, config.settings)
+      .toBuffer()
+    const fileSizeAfter = output.length
+    if (fileSizeAfter === 0) {
+      throw new Error('Compressed file size is 0')
+    }
 
     let color = 'white'
     let status = 'Skipped'
@@ -120,6 +137,7 @@ const compression = async (filename, dry, quiet = false) => {
       if (!dry) {
         // Only now create a backup and replace the original
         await retryFileOperation(() => fs.copyFile(filename, filenameBackup))
+        await fs.writeFile(tempFilePath, output)
         // Prefer atomic rename when possible
         try {
           await retryFileOperation(() => fs.rename(tempFilePath, filename))
@@ -141,14 +159,15 @@ const compression = async (filename, dry, quiet = false) => {
       details = 'already compressed more effectively'
     }
 
+    // Records the file as it now is, so compressed results aren’t re-encoded again either
+    if (!dry) {
+      cache?.add(fileSizeAfter < fileSizeBefore ? toEntry(output) : entryInput)
+    }
+
     logMessage(`${status} ${filename} (${details})`, dry, color, quiet)
 
     if (dry) {
-      return 0 // Temp file cleaned up in finally
-    }
-
-    if (fileSizeAfter === 0) {
-      console.error(styleStderr('red', `Error compressing ${filename}: Compressed file size is 0`))
+      return 0
     }
 
     return fileSizeAfter < fileSizeBefore ? fileSizeBefore - fileSizeAfter : 0
@@ -174,7 +193,7 @@ 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)
+    // Clean up temp file if it wasn’t consumed (covers error paths)
     if (!tempConsumed) {
       try {
         await retryFileOperation(() => fs.unlink(tempFilePath))
@@ -290,4 +309,4 @@ const size = async (file) => {
 
 const sizeReadable = (size) => `${(size / 1024).toFixed(2)} KB` // eslint-disable-line no-irregular-whitespace
 
-export const utils = { compression, conversion, sizeReadable }
+export const utils = { compression, conversion, sizeReadable, fingerprint }