image-guard 5.2.5 → 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)
+[![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.)
 
@@ -20,7 +20,7 @@ It’s as safe as possible because compression happens losslessly (near-lossless
 
 You can use Image Guard right away, without installation, by running
 
-```console
+```shell
 npx image-guard
 ```
 
@@ -28,13 +28,13 @@ npx image-guard
 
 Install Image Guard in your project:
 
-```console
+```shell
 npm i -D image-guard
 ```
 
 Run Image Guard by calling
 
-```console
+```shell
 npx image-guard
 ```
 
@@ -44,13 +44,13 @@ To make sure that _all_ images are being compressed, it’s recommended to run I
 
 Install Image Guard in your project:
 
-```console
+```shell
 npm i -D image-guard
 ```
 
 To compress images already in the codebase, run Image Guard once by calling
 
-```console
+```shell
 npx image-guard
 ```
 
@@ -60,7 +60,7 @@ For automated use, Image Guard should be triggered through a [Git hook](https://
 
 Native Git hooks are simpler to set up and don’t require additional dependencies. Run these commands from your project root:
 
-```console
+```shell
 mkdir -p .githooks;\
 cat > .githooks/pre-commit << 'EOF'
 #!/bin/sh
@@ -81,7 +81,7 @@ chmod +x .githooks/pre-commit && git config core.hooksPath .githooks"
 
 If you already use [Husky](https://typicode.github.io/husky/), run the following commands in your project root (you can copy and execute them at once):
 
-```console
+```shell
 grep -qxF "./node_modules/.bin/image-guard --staged" .husky/pre-commit || printf '\n./node_modules/.bin/image-guard --staged' >> .husky/pre-commit;\
 git add .husky/pre-commit;\
 git commit -m "feat: add Husky pre-commit hook for Image Guard";\
@@ -90,7 +90,7 @@ npm pkg set scripts.postprepare="grep -qxF './node_modules/.bin/image-guard --st
 
 If you don’t yet but want to use Husky, run the following commands from your project root:
 
-```console
+```shell
 npm i -D husky;\
 npx husky init;\
 echo "./node_modules/.bin/image-guard --staged" > .husky/pre-commit;\
@@ -101,21 +101,25 @@ 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.)
 
   - `--keep-heic` (used with `--heic-to-avif`) preserves the original HEIC/HEIF files instead of deleting them after conversion.
 
-* `--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.
+* `--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.
 
 ## What Does the Output Look Like?
 
@@ -128,7 +132,7 @@ Roughly like this:
 * White (light gray): The image file has not been changed.
 * 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.
+Tip: Use `--quiet` to suppress these per-file lines and keep only the final summary.
 
 ## How Does Image Guard Work?
 
@@ -165,4 +169,12 @@ Licensed under the Apache License, Version 2.0 (the “License”); you may not
 
     http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+***
+
+You might like some of my other work:
+
+* Optimization tools: [hihtml](https://github.com/j9t/hihtml) · [HTML Minifier Next](https://github.com/j9t/html-minifier-next) · [ObsoHTML](https://github.com/j9t/obsohtml) · [CSS Dedup](https://github.com/j9t/css-dedup) · Image Guard · [Compressor.js Next](https://github.com/j9t/compressorjs-next) · [.htaccess Punk](https://github.com/j9t/htaccess-punk)
+* Defense tools: [IA Defensa](https://iadefensa.com/solutions/)
+* Resources for quality web development: [Articles](https://meiert.com/topics/development/) · [Books](https://meiert.com/topics/books/) (including [_On Web Development_](https://meiert.com/blog/on-web-development-2/)) · [News](https://frontenddogma.com/) · [Terminology](https://webglossary.info/)

package/package.json

@@ -6,16 +6,22 @@
     "imagemin-merlin": "bin/image-guard.sh"
   },
   "dependencies": {
-    "globby": "^16.1.0",
+    "globby": "^16.2.3",
     "heic-decode": "^2.1.0",
-    "sharp": "^0.34.5",
-    "simple-git": "^3.31.1"
+    "sharp": "^0.35.3",
+    "simple-git": "^3.36.0"
   },
   "description": "Near-lossless image compressor that’s easy to use and easy to automate",
   "devDependencies": {
-    "@eslint/js": "^10.0.0",
-    "eslint": "^10.0.0"
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.8.1"
   },
+  "files": [
+    "bin/image-guard.js",
+    "bin/image-guard.sh",
+    "NOTICE.md",
+    "src"
+  ],
   "funding": "https://github.com/j9t/image-guard?sponsor=1",
   "homepage": "https://github.com/j9t/image-guard",
   "keywords": [
@@ -44,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.5"
+  "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) => {

package/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = false
-tab_width = 2
-trim_trailing_whitespace = true
-
-[*.js]
-indent_style = space
-indent_size = 2

package/.github/FUNDING.yml

@@ -1,3 +0,0 @@
-# buy_me_a_coffee: meiert
-github: j9t
-# liberapay: j9t

package/.github/dependabot.yml

@@ -1,12 +0,0 @@
-# https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference
-
-version: 2
-updates:
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "monthly"
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"

package/.github/workflows/npm.yml

@@ -1,21 +0,0 @@
-name: "npm Publishing"
-
-on:
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 'lts/*'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm publish --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/tests.yml

@@ -1,54 +0,0 @@
-name: "Tests"
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        platform: [ubuntu-latest]
-        node: ['lts/*', 'current']
-    name: "Node ${{ matrix.node }} (${{ matrix.platform }})"
-    runs-on: ${{ matrix.platform }}
-    steps:
-      - name: "Check out repository"
-        uses: actions/checkout@v6
-      - name: "Set up Node.js"
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node }}
-          cache: npm
-      - name: "Install dependencies"
-        run: npm ci
-      - name: "Run tests"
-        run: npm test
-
-  test-macos:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    strategy:
-      matrix:
-        node: ['lts/*', 'current']
-    name: "Node ${{ matrix.node }} (macOS)"
-    runs-on: macos-latest
-    steps:
-      - name: "Check out repository"
-        uses: actions/checkout@v6
-      - name: "Set up Node.js"
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node }}
-          cache: npm
-      - name: "Install dependencies"
-        run: npm ci
-      - name: "Run tests"
-        run: npm test

package/CHANGELOG.md

@@ -1,55 +0,0 @@
-# Changelog
-
-Starting with version 5.2.0, all notable changes to Image Guard are documented in this file, which is (mostly) AI-generated and (always) human-edited. Dependency updates may or may not be called out specifically.
-
-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.5] - 2026-03-17
-
-### Changed
-
-* Added recommended ESLint rules to config (and fixed resulting warnings)
-* Promoted `no-unused-vars` and `eqeqeq` from warnings to errors in ESLint config
-
-## [5.2.4] - 2026-03-04
-
-### Fixed
-
-* Changed bin entry from a Node.js script to a shell wrapper that locates node from common version managers (nvm, Volta, asdf, mise) and package managers (Homebrew) before invocation, resolving hook failures in GUI Git clients that don’t inherit the shell’s PATH
-  - **Migration:** If you set up hooks, replace `npx image-guard --staged` with `./node_modules/.bin/image-guard --staged` in your `.githooks/pre-commit` or `.husky/pre-commit`.
-
-## [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
-
-* 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
-
-## [5.2.0] - 2026-02-17
-
-### Added
-
-* Added opt-in HEIC/HEIF-to-AVIF conversion via `--heic-to-avif` (with `--keep-heic` to preserve originals)
-* Introduced changelog

package/SECURITY.md

@@ -1,9 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Only the latest and therefore current version of Image Guard is supported. It’s advised to update older versions to the latest version.
-
-## Reporting a Vulnerability
-
-To report a vulnerability, please [file an issue](https://github.com/j9t/image-guard/issues/new) or email info@meiert.com.

package/bin/image-guard.test.js

@@ -1,553 +0,0 @@
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { execSync } from 'child_process'
-import { fileURLToPath } from 'url'
-import { test, describe, before, after } from 'node:test'
-import assert from 'node:assert'
-import simpleGit from 'simple-git'
-import { fileTypes as allowedFileTypes } from '../src/index.js'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const testFolder = path.join(__dirname, '../media/test')
-const testFolderGit = path.join(__dirname, '../media/test-git')
-const imageGuardScript = path.join(__dirname, '../bin/image-guard.js')
-
-// Function to copy files
-function copyFiles(srcDir, destDir) {
-  if (!fs.existsSync(destDir)) {
-    fs.mkdirSync(destDir, { recursive: true })
-  }
-  fs.readdirSync(srcDir).forEach(file => {
-    const srcFile = path.join(srcDir, file)
-    const destFile = path.join(destDir, file)
-    fs.copyFileSync(srcFile, destFile)
-  })
-}
-
-// Function to check if images are compressed
-const ignoreFiles = ['test#corrupt.gif']
-
-function areImagesCompressed(dir, originalDir = testFolder) {
-  const uncompressedFiles = []
-  const allCompressed = fs.readdirSync(dir).every(file => {
-    if (ignoreFiles.includes(file)) {
-      // console.info(`Ignoring file: ${file}`)
-      return true
-    }
-    const ext = path.extname(file).slice(1).toLowerCase()
-    if (!allowedFileTypes.includes(ext)) return true
-    const filePath = path.join(dir, file)
-    const originalFilePath = path.join(originalDir, file)
-    try {
-      const originalStats = fs.statSync(originalFilePath)
-      const compressedStats = fs.statSync(filePath)
-      const isCompressed = compressedStats.size < originalStats.size
-      if (!isCompressed) {
-        uncompressedFiles.push(file)
-      }
-      return isCompressed
-    } catch (err) {
-      console.warn(`Skipping possibly corrupt file: ${file} (${err.message})`)
-      return true
-    }
-  })
-  return { allCompressed, uncompressedFiles }
-}
-
-// Function to check if images are already compressed
-function areImagesAlreadyCompressed(dir) {
-  return fs.readdirSync(dir).some(file => {
-    const ext = path.extname(file).slice(1).toLowerCase()
-    if (!allowedFileTypes.includes(ext)) return false
-    const filePath = path.join(dir, file)
-    const originalFilePath = path.join(testFolder, file)
-    const originalStats = fs.statSync(originalFilePath)
-    const compressedStats = fs.statSync(filePath)
-    return compressedStats.size >= originalStats.size
-  })
-}
-
-describe('Image Guard', () => {
-  before(() => {
-    // Back up original images
-    copyFiles(testFolder, testFolderGit)
-  })
-
-  after(() => {
-    // Clean up temporary directory
-    if (fs.existsSync(testFolderGit)) {
-      fs.rmSync(testFolderGit, { recursive: true, force: true })
-    }
-  })
-
-  test('Compress images', () => {
-    // Ensure images in temp folder are not already compressed
-    assert.strictEqual(areImagesAlreadyCompressed(testFolderGit), true)
-
-    // Run the script in a completely isolated temporary directory
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-test-'))
-    const tempTestFolder = path.join(tempDir, 'test')
-
-    // Copy test files to isolated temp directory
-    copyFiles(testFolder, tempTestFolder)
-
-    // Run image-guard from temp directory—only files in “tempDir” will be processed
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}"`)
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // Check results from the isolated temp files
-    const { allCompressed, uncompressedFiles } = areImagesCompressed(tempTestFolder, testFolder)
-
-    // Clean up
-    fs.rmSync(tempDir, { recursive: true, force: true })
-
-    if (uncompressedFiles.length > 0) {
-      console.log('The following files were not compressed:', uncompressedFiles.join(', '))
-    }
-    assert.strictEqual(allCompressed, true)
-  })
-
-  test('Compress only staged images', async () => {
-    const git = simpleGit(testFolderGit)
-
-    // Ensure the temp folder exists
-    if (!fs.existsSync(testFolderGit)) {
-      fs.mkdirSync(testFolderGit, { recursive: true })
-    }
-
-    // Initialize a temporary Git repository
-    await git.init()
-    await git.addConfig('user.name', 'Test User')
-    await git.addConfig('user.email', 'test@example.com')
-
-    // Stage files
-    await git.add('.')
-
-    // Run image-guard script with “--staged” option
-    execSync(`node "${imageGuardScript}" --staged`, { cwd: testFolderGit })
-
-    // Verify images are compressed
-    const { allCompressed, uncompressedFiles } = areImagesCompressed(testFolderGit)
-    if (uncompressedFiles.length > 0) {
-      console.log('The following files were not compressed:', uncompressedFiles.join(', '))
-    }
-    assert.strictEqual(allCompressed, true)
-  })
-
-  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) }
-    })
-    execSync(`node "${imageGuardScript}" --dry`, { cwd: testFolderGit, stdio: 'pipe' })
-    const newStats = fs.readdirSync(testFolderGit).sort().map(file => {
-      const filePath = path.join(testFolderGit, file)
-      return { file, stats: fs.statSync(filePath) }
-    })
-    originalStats.forEach((original, index) => {
-      const newFile = newStats[index]
-      assert.strictEqual(newFile.file, original.file)
-      assert.strictEqual(newFile.stats.size, original.stats.size)
-      assert.strictEqual(newFile.stats.mtime.getTime(), original.stats.mtime.getTime())
-    })
-  })
-
-  test('Ignore parity: single file (non-staged vs. staged)', async () => {
-    // Prepare isolated temp directory
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-ignore-one-'))
-    const tempTestFolder = path.join(tempDir, 'test')
-    copyFiles(testFolder, tempTestFolder)
-
-    // Pick a known file from fixture folder
-    const entries = fs.readdirSync(tempTestFolder).filter(n => /\.(png|jpe?g|gif|webp|avif)$/i.test(n))
-    if (entries.length === 0) {
-      fs.rmSync(tempDir, { recursive: true, force: true })
-      return
-    }
-    const target = entries[0]
-    const tempPath = path.join(tempTestFolder, target)
-    // Snapshot the temp copy before running the CLI to ensure equality checks reflect true non-mutation
-    const before = fs.statSync(tempPath)
-
-    // Prepare a pre-run snapshot for non-ignored candidates to verify at least one gets compressed
-    const preSnapshot = new Map()
-    fs.readdirSync(tempTestFolder).sort().forEach(name => {
-      if (name === target) return // excluded: explicitly ignored
-      if (ignoreFiles.includes(name)) return // excluded: known corrupt fixture
-      const ext = path.extname(name).slice(1).toLowerCase()
-      if (!allowedFileTypes.includes(ext)) return
-      const p = path.join(tempTestFolder, name)
-      preSnapshot.set(name, fs.statSync(p))
-    })
-
-    // Non-staged: Run with `--ignore=<file>`
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}" --ignore=${path.posix.join('test', target)}`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // Verify the ignored file was not modified (size and mtime unchanged vs. pre-run snapshot)
-    const tempStats = fs.statSync(tempPath)
-    assert.strictEqual(tempStats.size, before.size)
-    assert.strictEqual(tempStats.mtime.getTime(), before.mtime.getTime())
-
-    // Verify at least one non-ignored candidate was compressed in the non-staged run
-    let shrunkCount = 0
-    for (const [name, statBefore] of preSnapshot) {
-      const statAfter = fs.statSync(path.join(tempTestFolder, name))
-      if (statAfter.size < statBefore.size) shrunkCount++
-    }
-    assert.ok(shrunkCount >= 1, 'Expected at least one non-ignored file to be compressed')
-
-    // Staged: Init repo, stage only target and another file, ensure ignore prevents its processing
-    const git = simpleGit(tempTestFolder)
-    await git.init()
-    await git.addConfig('user.name', 'Test User')
-    await git.addConfig('user.email', 'test@example.com')
-    await git.add('.')
-
-    // Run staged with `ignore`
-    execSync(`node "${imageGuardScript}" --staged --ignore=${path.posix.join('test', target)}`, { cwd: tempTestFolder, stdio: 'pipe' })
-
-    // Check file still not modified compared to its current state (size should not shrink due to ignore)
-    const afterStats = fs.statSync(tempPath)
-    assert.strictEqual(afterStats.size, tempStats.size)
-
-    // Cleanup
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  test('Ignore supports multiple patterns and directories; case-insensitive', () => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-ignore-multi-'))
-    const tempTestFolder = path.join(tempDir, 'test')
-    copyFiles(testFolder, tempTestFolder)
-
-    // Create a subdirectory to simulate directory ignore
-    const subDir = path.join(tempTestFolder, 'Assets')
-    fs.mkdirSync(subDir, { recursive: true })
-    // Copy one file into subdir
-    const oneFile = fs.readdirSync(tempTestFolder).find(n => /\.(png|jpe?g|gif|webp|avif)$/i.test(n))
-    if (oneFile) fs.copyFileSync(path.join(tempTestFolder, oneFile), path.join(subDir, oneFile))
-
-    // Build ignore list: specific file (if available) and directory (case-insensitive path)
-    const ignoreArg = oneFile ? `--ignore=test/${oneFile},test/assets/` : `--ignore=test/assets/`
-    // Snapshot the file placed in ignored directory, before running the CLI
-    let preInside
-    if (oneFile) {
-      preInside = fs.statSync(path.join(subDir, oneFile))
-    }
-
-    // Snapshot before running CLI for file-level ignore check
-    let preIgnored
-    if (oneFile) {
-      preIgnored = fs.statSync(path.join(tempTestFolder, oneFile))
-    }
-
-    // Build a pre-run snapshot of candidates that are not ignored
-    const preSnapshot = new Map()
-    fs.readdirSync(tempTestFolder).sort().forEach(name => {
-      // Exclude the explicitly ignored file (if any) and anything inside the ignored directory
-      if (oneFile && name === oneFile) return
-      if (ignoreFiles.includes(name)) return // exclude corrupt fixture
-      const ext = path.extname(name).slice(1).toLowerCase()
-      if (!allowedFileTypes.includes(ext)) return
-      const p = path.join(tempTestFolder, name)
-      preSnapshot.set(name, fs.statSync(p))
-    })
-
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}" ${ignoreArg}`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // Assert ignored file unchanged (only if there was a file to ignore explicitly)
-    if (oneFile) {
-      const ignoredCopy = fs.statSync(path.join(tempTestFolder, oneFile))
-      assert.strictEqual(ignoredCopy.size, preIgnored.size)
-      assert.strictEqual(ignoredCopy.mtime.getTime(), preIgnored.mtime.getTime())
-    }
-
-    // Assert that at least one non-ignored file in the root `tempTestFolder` was compressed
-    let shrunkCount = 0
-    for (const [name, statBefore] of preSnapshot) {
-      const statAfter = fs.statSync(path.join(tempTestFolder, name))
-      if (statAfter.size < statBefore.size) shrunkCount++
-    }
-    assert.ok(shrunkCount >= 1, 'Expected at least one non-ignored file to be compressed')
-
-    // Assert file inside ignored directory unchanged (if created)
-    if (oneFile) {
-      const inside = fs.statSync(path.join(subDir, oneFile))
-      // Since original may change, assert that the file inside ignored directory remained unchanged, by comparing to its own pre-run snapshot
-      assert.strictEqual(inside.size, preInside.size)
-    }
-
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  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')
-    copyFiles(testFolder, tempTestFolder)
-
-    const originalCwd = process.cwd()
-    let stdout
-    try {
-      process.chdir(tempDir)
-      stdout = execSync(`node "${imageGuardScript}" --quiet`, { encoding: 'utf8' })
-    } finally {
-      process.chdir(originalCwd)
-      fs.rmSync(tempDir, { recursive: true, force: true })
-    }
-
-    // Summary should be present
-    assert.match(stdout, /Defensive base compression completed\./)
-    // Per-file lines like “Compressed <file>” or “Skipped <file>” should be suppressed
-    assert.strictEqual(!(/Compressed|Skipped/.test(stdout)), true)
-  })
-
-  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')
-    copyFiles(testFolder, tempTestFolder)
-
-    // Snapshot sizes/mtimes
-    const before = fs.readdirSync(tempTestFolder).sort().map(file => {
-      const filePath = path.join(tempTestFolder, file)
-      return { file, stats: fs.statSync(filePath) }
-    })
-
-    const originalCwd = process.cwd()
-    let stdout
-    try {
-      process.chdir(tempDir)
-      stdout = execSync(`node "${imageGuardScript}" --dry --quiet`, { encoding: 'utf8' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // Summary present; no per-file lines
-    assert.match(stdout, /There were no images to compress\.|Defensive base compression completed\./)
-    assert.strictEqual(!(/Compressed|Skipped/.test(stdout)), true)
-
-    // Verify no mutations
-    const after = fs.readdirSync(tempTestFolder).sort().map(file => {
-      const filePath = path.join(tempTestFolder, file)
-      return { file, stats: fs.statSync(filePath) }
-    })
-    before.forEach((b, i) => {
-      const a = after[i]
-      assert.strictEqual(a.file, b.file)
-      assert.strictEqual(a.stats.size, b.stats.size)
-      assert.strictEqual(a.stats.mtime.getTime(), b.stats.mtime.getTime())
-    })
-
-    // Ensure no temp or backup artifacts present
-    const entries = fs.readdirSync(tempTestFolder)
-    const hasTemp = entries.some(name => name.startsWith('.image-guard-'))
-    const hasBak = entries.some(name => name.endsWith('.bak'))
-    assert.strictEqual(hasTemp, false)
-    assert.strictEqual(hasBak, false)
-
-    // Cleanup
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  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')
-    copyFiles(testFolder, tempTestFolder)
-
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}"`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    const entries = fs.readdirSync(tempTestFolder)
-    const hasBak = entries.some(name => name.endsWith('.bak'))
-    assert.strictEqual(hasBak, false)
-
-    // Cleanup
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  test('Convert HEIC to AVIF with `--heic-to-avif`', () => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-'))
-    const tempTestFolder = path.join(tempDir, 'test')
-    copyFiles(testFolder, tempTestFolder)
-
-    // Ensure HEIC test fixture exists
-    const heicFile = path.join(tempTestFolder, 'test.heic')
-    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC test fixture must exist')
-
-    // Remove pre-existing AVIF so we can verify the conversion actually creates it
-    const avifFile = path.join(tempTestFolder, 'test.avif')
-    if (fs.existsSync(avifFile)) {
-      fs.unlinkSync(avifFile)
-    }
-
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}" --heic-to-avif`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // AVIF should be created by the conversion
-    assert.strictEqual(fs.existsSync(avifFile), true, 'AVIF file should be created')
-    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')
-
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  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)
-
-    const heicFile = path.join(tempTestFolder, 'test.heic')
-    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC test fixture must exist')
-
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}" --heic-to-avif --keep-heic`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // Both files should exist
-    assert.strictEqual(fs.existsSync(path.join(tempTestFolder, 'test.avif')), true, 'AVIF file should be created')
-    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC file should be preserved with `--keep-heic`')
-
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  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)
-      output = execSync(`node "${imageGuardScript}" --heic-to-avif --dry`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // HEIC should be unchanged
-    const heicAfter = fs.statSync(heicFile)
-    assert.strictEqual(heicAfter.size, heicBefore.size)
-    assert.strictEqual(heicAfter.mtime.getTime(), heicBefore.mtime.getTime())
-
-    // No files should be added or removed
-    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('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)
-
-    const heicFile = path.join(tempTestFolder, 'test.heic')
-    const heicBefore = fs.statSync(heicFile)
-
-    const originalCwd = process.cwd()
-    try {
-      process.chdir(tempDir)
-      execSync(`node "${imageGuardScript}"`, { stdio: 'pipe' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    // HEIC should be untouched
-    const heicAfter = fs.statSync(heicFile)
-    assert.strictEqual(heicAfter.size, heicBefore.size)
-    assert.strictEqual(heicAfter.mtime.getTime(), heicBefore.mtime.getTime())
-
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-
-  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)
-
-    const originalCwd = process.cwd()
-    let output
-    try {
-      process.chdir(tempDir)
-      output = execSync(`node "${imageGuardScript}" --keep-heic 2>&1`, { encoding: 'utf8' })
-    } finally {
-      process.chdir(originalCwd)
-    }
-
-    assert.match(output, /`--keep-heic` has no effect without `--heic-to-avif`/)
-
-    fs.rmSync(tempDir, { recursive: true, force: true })
-  })
-})

package/eslint.config.js

@@ -1,28 +0,0 @@
-import js from '@eslint/js';
-
-export default [
-  {
-    ignores: [
-      'media/',
-      'node_modules/**'
-    ]
-  },
-  js.configs.recommended,
-  {
-    languageOptions: {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-      globals: {
-        console: 'readonly',
-        process: 'readonly',
-        setTimeout: 'readonly'
-      }
-    },
-    rules: {
-      'no-console': 'off', // CLI tool—allow console
-      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-      eqeqeq: ['error', 'smart'],
-      curly: ['warn', 'multi-line']
-    }
-  }
-]