image-guard 5.2.6 → 5.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Image Guard
 
-[![npm version](https://img.shields.io/npm/v/image-guard.svg)](https://www.npmjs.com/package/image-guard) [![Build status](https://github.com/j9t/image-guard/workflows/Tests/badge.svg)](https://github.com/j9t/image-guard/actions) [![Socket](https://badge.socket.dev/npm/package/image-guard)](https://socket.dev/npm/package/image-guard) [![GitHub Sponsors](https://badgen.net/static/Support/Open%20Source/cyan)](https://github.com/j9t/image-guard?sponsor=1)
+[![npm version](https://img.shields.io/npm/v/image-guard.svg)](https://www.npmjs.com/package/image-guard) [![Build status](https://github.com/j9t/image-guard/workflows/Tests/badge.svg)](https://github.com/j9t/image-guard/actions) [![Socket](https://badge.socket.dev/npm/package/image-guard)](https://socket.dev/npm/package/image-guard) [![GitHub Sponsors](https://badgen.net/static/Support/Open%20Source/cyan)](https://github.com/sponsors/j9t)
 
 (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.)
 
@@ -101,15 +101,19 @@ npm pkg set scripts.postprepare="grep -qxF './node_modules/.bin/image-guard --st
 
 (The `postprepare` script ensures that the hook is added to the repository whenever someone installs the package.)
 
+If you give the hook options like `--ignore`, add them to the `postprepare` script as well—the hook command is the only place to configure Image Guard, and the next install rewrites that line.
+
 **Important:** When you commit images that have not yet been compressed, the automated compression process (triggered by the pre-commit hook) will modify those image files to reduce their size. As a result, after your initial commit attempt, you will see these images appear as changed files in Git. To include the optimized images in your repository, you need to stage and commit them again. In rare cases, if further compression is possible, you may need to repeat this process until no further changes are detected. This workflow is intentional and ensures that only optimally compressed images are committed. Many editors can display diffs for images, helping you review these changes.
 
 ### Parameters
 
+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.
 
-* `--ignore` allows you to specify paths to be ignored (as in `--ignore=example,test`). Multiple paths must be separated by commas. The option supports glob patterns (e.g., `assets/**`, `**/*.png`); matching is case-insensitive and honors `.gitignore`.
+* `--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.
 
-* `--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.
+* `--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.
 
 * `--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.)
 

package/package.json

@@ -6,7 +6,7 @@
     "imagemin-merlin": "bin/image-guard.sh"
   },
   "dependencies": {
-    "globby": "^16.2.2",
+    "globby": "^16.2.3",
     "heic-decode": "^2.1.0",
     "sharp": "^0.35.3",
     "simple-git": "^3.36.0"
@@ -14,7 +14,7 @@
   "description": "Near-lossless image compressor that’s easy to use and easy to automate",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.7.0"
+    "eslint": "^10.8.1"
   },
   "files": [
     "bin/image-guard.js",
@@ -50,8 +50,9 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "prepare": "git config core.hooksPath .githooks || true",
     "test": "node --test bin/image-guard.test.js"
   },
   "type": "module",
-  "version": "5.2.6"
+  "version": "5.3.0"
 }

package/src/index.js

@@ -3,6 +3,7 @@
 import { globby, convertPathToPattern } from 'globby'
 import simpleGit from 'simple-git'
 import { parseArgs, styleText } from 'node:util'
+import fsSync from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import sharp from 'sharp'
@@ -23,7 +24,21 @@ export async function runImageGuard() {
     staged: { type: 'boolean', default: false },
     quiet: { type: 'boolean', default: false }
   }
-  const { values: argv } = parseArgs({ options })
+  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(', ')}`)
+  }
+
+  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.')
+  }
+
+  if (!fsSync.existsSync(dir) || !fsSync.statSync(dir).isDirectory()) {
+    throw new Error(`No such directory: ${dir}`)
+  }
 
   // Share status
   const summary = (run, includesConversion = false) => {
@@ -42,7 +57,8 @@ export async function runImageGuard() {
 
   const allTypes = argv['heic-to-avif'] ? [...fileTypes, ...convertTypes] : fileTypes
   if (!argv.quiet) {
-    console.log(`(Search pattern: ${allTypes.join(', ')})\n`)
+    const where = dir === '.' ? '' : `, in ${dir}`
+    console.log(`(Search pattern: ${allTypes.join(', ')}${where})\n`)
   }
 
   let savedKB = 0
@@ -129,12 +145,15 @@ export async function runImageGuard() {
     return hadFailures
   }
 
+  // Plain patterns also get a “/**” variant so directories are excluded with
+  // their contents: “dir/” resolves only where globby can stat it, and a bare
+  // “dir” only covers what the walk descends into
   const getIgnorePatterns = (ignore) => {
     return (ignore || '')
       .split(',')
-      .map(s => s.trim())
+      .map(s => s.trim().replace(/^!/, '').replace(/\/+$/, ''))
       .filter(Boolean)
-      .map(p => (p.startsWith('!') ? p : `!${p}`))
+      .flatMap(p => (/[*?[\]{}]/.test(p) ? [`!${p}`] : [`!${p}`, `!${p}/**`]))
   }
 
   const getFilePattern = (ignore, types = fileTypes) => {
@@ -152,13 +171,18 @@ export async function runImageGuard() {
     return patterns
   }
 
+  // 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 = {}) => {
-    return globby(patterns, {
+    const files = await globby(patterns, {
+      cwd: dir,
       gitignore: true,
       onlyFiles: true,
       caseSensitiveMatch: false,
       ...options
     })
+    return files.map(file => path.join(dir, file))
   }
 
   const filterStagedFiles = async (stagedFiles, types) => {