image-guard 5.3.1 → 5.4.0

package/README.md

@@ -109,17 +109,21 @@ If you give the hook options like `--ignore`, add them to the `postprepare` scri
 
 Image Guard takes an optional path to the directory to process—`npx image-guard assets`—and works on the current directory when that path is omitted.
 
-* `--dry` allows you to run Image Guard in “dry mode.” All changes are shown in the terminal.
+* `--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.)
 
-* `--ignore` allows you to specify paths to be ignored (as in `--ignore=example,test`). Multiple paths must be separated by commas. Naming a directory excludes everything inside it. The option supports glob patterns (e.g., `assets/**`, `**/*.png`); matching is case-insensitive and honors `.gitignore`. Patterns are relative to the directory being processed—with `--staged`, to the repository root.
+  - `--keep-heic` (used with `--heic-to-avif`) preserves the original HEIC/HEIF files instead of deleting them after conversion.
 
-* `--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.
+* `--ignore`/`-i` allows you to specify paths to be ignored (as in `--ignore=example,test`). Multiple paths must be separated by commas. Naming a directory excludes everything inside it. The option supports glob patterns (e.g., `assets/**`, `**/*.png`); matching is case-insensitive and honors .gitignore. Patterns are relative to the directory being processed—with `--staged`, to the repository root.
 
-* `--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.)
+* `--quiet`/`-q` suppresses per-file logs and prints only the final summary (plus errors). This reduces console noise and speeds up runs in CI and Git hooks.
 
-  - `--keep-heic` (used with `--heic-to-avif`) preserves the original HEIC/HEIF files instead of deleting them after conversion.
+* `--dry`/`-d` allows you to run Image Guard in “dry mode.” All changes are shown in the terminal (unless combined with `--quiet`, which leaves just the summary).
+
+* `--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.
+
+* `--help`/`-h` lists the arguments and options.
 
-* `--quiet` suppresses per-file logs and prints only the final summary (plus errors). This reduces console noise and speeds up runs in CI and Git hooks.
+* `--version`/`-V` prints the version number.
 
 ## What Does the Output Look Like?
 

package/bin/image-guard.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
 
 import { runImageGuard } from '../src/index.js'
+import { styleStderr } from '../src/utils.js'
 
 try {
   await runImageGuard()
 } catch (err) {
-  console.error('Error running Image Guard:', err.message)
+  if (err.setupFailed) {
+    console.error(styleStderr('red', err.message))
+  } else {
+    console.error('Error running Image Guard:', err)
+  }
   process.exit(1)
 }

package/package.json

@@ -14,7 +14,8 @@
   "description": "Near-lossless image compressor that’s easy to use and easy to automate",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.8.1"
+    "eslint": "^10.8.1",
+    "globals": "^17.11.0"
   },
   "files": [
     "bin/image-guard.js",
@@ -54,5 +55,5 @@
     "test": "node --test bin/image-guard.test.js"
   },
   "type": "module",
-  "version": "5.3.1"
-}
+  "version": "5.4.0"
+}

package/src/index.js

@@ -7,7 +7,7 @@ import fsSync from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import sharp from 'sharp'
-import { utils } from './utils.js'
+import { styleStderr, utils } from './utils.js'
 
 // Files to be compressed
 export const fileTypes = ['avif', 'gif', 'jpg', 'jpeg', 'png', 'webp'];
@@ -15,34 +15,77 @@ export const fileTypes = ['avif', 'gif', 'jpg', 'jpeg', 'png', 'webp'];
 // Files to be converted (require explicit opt-in)
 export const convertTypes = ['heic', 'heif'];
 
+// Marks a failure as the user’s to fix rather than a bug
+function setupError(message) {
+  const err = new Error(message)
+  err.setupFailed = true
+  return err
+}
+
 export async function runImageGuard() {
   const options = {
-    dry: { type: 'boolean', default: false },
     'heic-to-avif': { type: 'boolean', default: false },
-    ignore: { type: 'string', multiple: false, default: '' },
     'keep-heic': { type: 'boolean', default: false },
+    ignore: { type: 'string', short: 'i', multiple: false, default: '' },
+    quiet: { type: 'boolean', short: 'q', default: false },
+    dry: { type: 'boolean', short: 'd', default: false },
     staged: { type: 'boolean', default: false },
-    quiet: { type: 'boolean', default: false }
+    help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'V', default: false }
+  }
+
+  let argv, positionals
+  try {
+    ({ values: argv, positionals } = parseArgs({ options, allowPositionals: true }))
+  } catch (err) {
+    // `parseArgs` appends guidance about `--` that only muddies a plain typo
+    const [summary] = err.message.split('. ')
+    throw setupError(`${summary}—run \`image-guard --help\` for the available options.`)
+  }
+
+  if (argv.help) {
+    console.log(`Usage: image-guard [options] [directory]
+
+Compress images in place, and optionally convert HEIC/HEIF files to AVIF.
+
+Arguments:
+  directory  Directory to process (default: current directory)
+
+Options:
+      --heic-to-avif    Also convert HEIC/HEIF files to AVIF
+      --keep-heic       Keep the original HEIC/HEIF files (only with \`--heic-to-avif\`)
+  -i, --ignore <paths>  Comma-separated paths or glob patterns to exclude
+  -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)
+  -h, --help            Show this help
+  -V, --version         Show the version number`)
+    return
+  }
+
+  if (argv.version) {
+    const pkg = JSON.parse(fsSync.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    console.log(pkg.version)
+    return
   }
-  const { values: argv, positionals } = parseArgs({ options, allowPositionals: true })
 
   if (positionals.length > 1) {
-    throw new Error(`Expected at most one path, got ${positionals.length}: ${positionals.join(', ')}`)
+    throw setupError(`Expected at most one path, got ${positionals.length}: ${positionals.join(', ')}`)
   }
 
   const dir = positionals[0] || '.'
 
   if (positionals.length && argv.staged) {
-    throw new Error('`--staged` takes its files from Git, not from a path—pass one or the other.')
+    throw setupError('`--staged` takes its files from Git, not from a path—pass one or the other.')
   }
 
   if (!fsSync.existsSync(dir)) {
-    throw new Error(`No such directory: ${dir}`)
+    throw setupError(`No such directory: ${dir}`)
   }
 
   // A path that is there but isn’t a directory gets its own message
   if (!fsSync.statSync(dir).isDirectory()) {
-    throw new Error(`Not a directory: ${dir}`)
+    throw setupError(`Not a directory: ${dir}`)
   }
 
   // Share status
@@ -57,7 +100,7 @@ export async function runImageGuard() {
   }
 
   if (argv['keep-heic'] && !argv['heic-to-avif']) {
-    console.warn(styleText('yellow', '`--keep-heic` has no effect without `--heic-to-avif`'))
+    console.warn(styleStderr('yellow', '`--keep-heic` has no effect without `--heic-to-avif`'))
   }
 
   const allTypes = argv['heic-to-avif'] ? [...fileTypes, ...convertTypes] : fileTypes
@@ -122,7 +165,7 @@ export async function runImageGuard() {
       } else {
         hadFailures = true
         const reason = r.reason && r.reason.message ? r.reason.message : String(r.reason)
-        console.error(styleText('red', 'Task failed:'), reason)
+        console.error(styleStderr('red', 'Task failed:'), reason)
       }
     }
     return { hadFailures, addedKB }
@@ -176,7 +219,7 @@ export async function runImageGuard() {
     return patterns
   }
 
-  // Globbing runs with `dir` as its base—so ignore patterns and `.gitignore`
+  // Globbing runs with `dir` as its base—so ignore patterns and .gitignore
   // lookup are relative to the searched directory, not to the shell’s—and the
   // results are rejoined for display and file access
   const findFiles = async (patterns, options = {}) => {

package/src/utils.js

@@ -8,6 +8,11 @@ import decode from 'heic-decode'
 
 const MAX_FILE_SIZE = 100 * 1024 * 1024 // 100 MB
 
+// `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
+export const styleStderr = (format, text) => styleText(format, text, { stream: process.stderr })
+
 const logMessage = (message, dry, color = 'yellow', quiet = false) => {
   if (quiet) return
   const prefix = dry ? 'Dry run: ' : ''
@@ -143,7 +148,7 @@ const compression = async (filename, dry, quiet = false) => {
     }
 
     if (fileSizeAfter === 0) {
-      console.error(styleText('red', `Error compressing ${filename}: Compressed file size is 0`))
+      console.error(styleStderr('red', `Error compressing ${filename}: Compressed file size is 0`))
     }
 
     return fileSizeAfter < fileSizeBefore ? fileSizeBefore - fileSizeAfter : 0
@@ -163,7 +168,7 @@ const compression = async (filename, dry, quiet = false) => {
     ) {
       logMessage(`Skipped ${filename} (corrupt file)`, dry, 'yellow', quiet)
     } else {
-      console.error(styleText('red', `Error compressing ${filename}:`), err)
+      console.error(styleStderr('red', `Error compressing ${filename}:`), err)
     }
     return 0
 
@@ -184,14 +189,14 @@ const compression = async (filename, dry, quiet = false) => {
         await retryFileOperation(() => fs.unlink(filenameBackup))
       } catch (err) {
         if (err.code !== 'ENOENT') {
-          console.warn(styleText('yellow', `Failed to delete backup file ${filenameBackup}:`), err)
+          console.warn(styleStderr('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}`))
+        console.warn(styleStderr('yellow', `Replacement failed for ${filename}; backup preserved at ${filenameBackup}`))
       } catch {
         // No backup exists—nothing to warn about
       }
@@ -262,7 +267,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
       await retryFileOperation(() => fs.unlink(avifPath))
     } catch (cleanupErr) {
       if (cleanupErr.code !== 'ENOENT') {
-        console.warn(styleText('yellow', `Failed to clean up ${avifPath}:`), cleanupErr)
+        console.warn(styleStderr('yellow', `Failed to clean up ${avifPath}:`), cleanupErr)
       }
     }
 
@@ -272,7 +277,7 @@ const conversion = async (filename, dry, keepOriginal, quiet = false) => {
     )) {
       logMessage(`Skipped ${filename} (corrupt or unsupported HEIC/HEIF file)`, dry, 'yellow', quiet)
     } else {
-      console.error(styleText('red', `Error converting ${filename}:`), err)
+      console.error(styleStderr('red', `Error converting ${filename}:`), err)
     }
     return 0
   }