oxlint-plugin-pngdeer 0.1.0 → 0.2.1

package/README.md

@@ -9,7 +9,7 @@
 A lint rule for [oxlint](https://oxc.rs/docs/guide/usage/linter) and ESLint. It runs [pngdeer](https://github.com/heydeer/pngdeer), a lossy PNG and JPEG compressor in the spirit of TinyPNG, locally on the images your code imports or points to. When an image could be much smaller at about the same visual quality, the rule warns on that line, with the saving and the command that shrinks the file.
 
 ```
-  ⚠ pngdeer(compressible-image): hero.png could be 70% smaller (509 kB → 151 kB) at about the same visual quality. Run: npx oxlint-plugin-pngdeer public/hero.png
+  ⚠ pngdeer(compressible-image): hero.png could be 70% smaller (509 kB → 151 kB) and look the same side by side (quality 87/100). Run: npx oxlint-plugin-pngdeer public/hero.png
     ╭─[src/App.jsx:10:16]
   9 │     <main>
  10 │       <img src="/hero.png" alt="An arcade stick" />
@@ -53,23 +53,46 @@ Run oxlint:
 ```console
 $ npx oxlint
 pngdeer: measuring 5 images not in the cache yet...
-pngdeer: measured 5 images in 4.5 s; later runs read the cache
-  ⚠ pngdeer(compressible-image): hero.png could be 70% smaller (509 kB → 151 kB) at about the same visual quality. Run: npx oxlint-plugin-pngdeer public/hero.png
+pngdeer: measured 5 images in 4.6 s; later runs read the cache
+
+  ⚠ pngdeer(compressible-image): hero.png could be 70% smaller (509 kB → 151 kB) and look the same side by side (quality 87/100). Run: npx oxlint-plugin-pngdeer public/hero.png
+  ⚠ pngdeer(compressible-image): photo.jpg could be 64% smaller (235 kB → 85 kB) and look close, with differences you might spot side by side (quality 76/100). Run: npx oxlint-plugin-pngdeer public/photo.jpg
   …
-pngdeer: 4 images could be 718 kB smaller in all (70%)
+
+pngdeer: 4 flagged images could be 718 kB smaller in all (1.0 MB → 310 kB, 70% smaller):
+  image                           now    after   saves  quality
+  public/hero.png              509 kB → 151 kB  359 kB       87
+  src/assets/diagram.png       248 kB →  63 kB  185 kB       90
+  public/photo.jpg             235 kB →  85 kB  150 kB       76
+  src/assets/crystal-ball.png   35 kB →  11 kB   24 kB       87
+pngdeer: also 1 image that no linted JS or TS names could be 5.1 kB smaller:
+  public/unused-fire.png        13 kB → 7.5 kB  5.1 kB       90  mentioned in README.md
+pngdeer: quality is SSIMULACRA2, out of 100: 90+ looks identical, 80+ the same side by side, 70+ close, with differences you might spot side by side
+pngdeer: to shrink the 4 flagged images in place (lossy, so commit first), run: npx oxlint-plugin-pngdeer --flagged
+pngdeer: to shrink it too, run: npx oxlint-plugin-pngdeer public/unused-fire.png
 ```
 
-Then shrink what it found. There's no autofix (lint fixes can only edit code), so pass the flagged images to the command, one or several:
+- **Each image warns once per file,** on the line that names it, and says how close to the original it would look.
+- **The table at the end** counts each image once, biggest saving first.
+- **Images no JS or TS names** get their own list, since no warning can point at them. Each row says where the image is used instead: `used in src/App.css`, `mentioned in README.md` (a Markdown file that names it), or `nothing names it`, which may mean the image is unused and could be deleted. These aren't in `--flagged`; the list ends with the command for them.
+- **The table is left out** with `--quiet` and in formats other programs read (`json`, `checkstyle`, `junit`, `sarif`, `gitlab`).
+
+Then shrink what it found. There's no autofix (lint fixes can only edit code), so run the command: `--flagged` takes every image the last lint in that folder warned about, or name images yourself.
 
 ```console
-$ npx oxlint-plugin-pngdeer public/hero.png public/photo.jpg
-public/hero.png: 509 kB → 151 kB (70% smaller, SSIMULACRA2 87.3)
-public/photo.jpg: 235 kB → 85 kB (64% smaller, SSIMULACRA2 75.5)
+$ npx oxlint-plugin-pngdeer --flagged
+pngdeer: shrinking 4 images in place (lossy; commit first so you can undo)
+[1/4] public/hero.png: 509 kB → 151 kB (70% smaller, quality 87/100: looks the same side by side)
+[2/4] src/assets/diagram.png: 248 kB → 63 kB (75% smaller, quality 90/100: looks identical)
+[3/4] public/photo.jpg: 235 kB → 85 kB (64% smaller, quality 76/100: looks close, with differences you might spot side by side)
+[4/4] src/assets/crystal-ball.png: 35 kB → 11 kB (68% smaller, quality 87/100: looks the same side by side)
+pngdeer: 4 images, 1.0 MB → 310 kB (718 kB smaller). Lint again to check.
 ```
 
 - **It's lossy, and it writes over the file.** Commit first so git is your undo, or write a copy to compare with `-o hero.smaller.png`.
+- **A warning you turn off with a comment** stays out of the table and out of `--flagged`.
 - **It takes a few seconds per image,** one at a time.
-- **It doesn't read your lint config.** If you set a `target`, pass it too (`--target 90`); the command in each warning already does. `--help` lists the options.
+- **`--flagged` uses the `target` each image was measured at.** For images you name, pass it yourself (`--target 90`), as the command in each warning does. `--help` lists the options.
 - **JPEGs keep their orientation and color profile;** other camera metadata (EXIF, GPS) is dropped.
 - **It marks each file it writes** with a short text tag (`pngdeer <size>`, in a PNG `tEXt` chunk or a JPEG comment), so the rule doesn't flag it again, on any machine.
 

package/bin/pngdeer.js

@@ -7,14 +7,18 @@ import { basename, dirname, join } from "node:path";
 import { compress } from "../src/engine.js";
 import { unsupported } from "../src/images.js";
 import { mark, marked } from "../src/marker.js";
-import { size } from "../src/text.js";
+import { readFlagged } from "../src/summary.js";
+import { count, looks, pathFrom, size, smaller } from "../src/text.js";
 
 const HELP = `usage: oxlint-plugin-pngdeer IMAGE... [--target auto|T]
+       oxlint-plugin-pngdeer --flagged [--target auto|T]
        oxlint-plugin-pngdeer IMAGE -o OUT [--target auto|T]
 
 Makes PNGs and JPEGs smaller with pngdeer, in place, at about the same visual quality.
 pngdeer is lossy: the picture looks the same, the bytes don't, so commit first.
 
+  --flagged     the images the last lint run from this folder warned about, each at the
+                target it was measured at
   -o OUT        write to OUT instead of in place (one image only)
   --target T    the SSIMULACRA2 score to keep, 0-100 (90 looks identical at 1:1);
                 auto (the default) picks one per image, about TinyPNG's quality
@@ -27,6 +31,8 @@ function main(args) {
   const inputs = [];
   let output;
   let target;
+  let targeted = false;
+  let fromLint = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "-h" || arg === "--help") {
@@ -37,38 +43,74 @@ function main(args) {
       console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
       return 0;
     }
-    if (arg === "-o" || arg === "--target") {
+    if (arg === "--flagged") fromLint = true;
+    else if (arg === "-o" || arg === "--target") {
       const value = args[++i];
       if (value === undefined) return fail(`${arg} needs a value`);
       if (arg === "-o") output = value;
-      else if (value !== "auto") {
-        target = Number(value);
-        if (!(value.trim() !== "" && target >= 0 && target <= 100)) return fail(`--target must be auto or a number from 0 to 100, not ${value}`);
+      else {
+        targeted = true;
+        target = value === "auto" ? undefined : Number(value);
+        if (target !== undefined && !(value.trim() !== "" && target >= 0 && target <= 100)) return fail(`--target must be auto or a number from 0 to 100, not ${value}`);
       }
     } else if (arg.startsWith("-") && arg !== "-") return fail(`unknown option ${arg}`);
     else inputs.push(arg);
   }
-  if (inputs.length === 0) return fail("no image given");
+  if (fromLint && (inputs.length || output !== undefined)) return fail("--flagged takes no images and no -o");
+  if (!fromLint && inputs.length === 0) return fail("no image given");
   if (output !== undefined && inputs.length > 1) return fail("-o takes one image; without it, each image is written in place");
 
+  const flagged = fromLint ? readFlagged(process.cwd()) : null;
+  if (fromLint && !flagged) {
+    console.error("oxlint-plugin-pngdeer: no lint has run in this folder yet: run npx oxlint (or eslint) here first");
+    return 1;
+  }
+  if (fromLint && flagged.length === 0) {
+    console.log("the last lint here flagged nothing");
+    return 0;
+  }
+  // each image, the path to show for it, and its target: a --target given here wins over the lint's
+  const jobs = fromLint
+    ? flagged.map((image) => ({
+        input: pathFrom(process.cwd(), image.file),
+        target: targeted ? target : image.target,
+      }))
+    : inputs.map((input) => ({ input, target }));
+
+  // several images take a while, one after another: say what's coming, count, and add it all up
+  const many = jobs.length > 1;
+  if (many) console.error(`pngdeer: shrinking ${count(jobs.length, "image")} in place (lossy; commit first so you can undo)`);
   let status = 0;
-  for (const input of inputs) {
+  let original = 0;
+  let compressed = 0;
+  let shrunk = 0;
+  for (const [i, { input, target }] of jobs.entries()) {
+    const step = many ? `[${i + 1}/${jobs.length}] ` : "";
     try {
-      console.log(`${input}: ${shrink(input, output ?? input, target)}`);
+      const result = shrink(input, output ?? input, target);
+      console.log(`${step}${input}: ${result.text}`);
+      if (result.written) {
+        shrunk++;
+        original += result.original;
+        compressed += result.written;
+      }
     } catch (error) {
-      console.error(`${input}: ${plain(error)}`);
+      console.error(`${step}${input}: ${plain(error)}`);
       status = 1;
     }
   }
+  if (many && shrunk) {
+    console.error(`pngdeer: ${count(shrunk, "image")}, ${size(original)} → ${size(compressed)} (${size(original - compressed)} smaller). Lint again to check.`);
+  }
   return status;
 }
 
-/** Writes `input` made smaller to `output`, and says what happened. */
+/** Writes `input` made smaller to `output`: { text } saying what happened, and the sizes if it wrote. */
 function shrink(input, output, target) {
   const bytes = readFileSync(input);
   const unchanged = (note) => {
     if (output !== input) save(output, bytes);
-    return `${note}; left as is`;
+    return { text: `${note}; left as is` };
   };
   if (marked(bytes)) return unchanged("already pngdeer's");
   const why = unsupported(bytes);
@@ -77,14 +119,15 @@ function shrink(input, output, target) {
   const { output: compressed, outcome, score } = compress(bytes, target);
   if (outcome === "miss") {
     const wanted = target === undefined ? "the automatic quality" : `--target ${target}`;
-    return unchanged(`no smaller file reaches ${wanted} (the best scores ${score.toFixed(1)})`);
+    return unchanged(`no smaller file reaches ${wanted} (the best reaches quality ${Math.round(score)}/100)`);
   }
   // the mark costs a few dozen bytes, more than pngdeer saves on some tiny files
   const result = outcome === "original" ? null : mark(compressed);
   if (!result || result.length >= bytes.length) return unchanged("pngdeer can't make it smaller");
   save(output, result);
-  const percent = Math.round(100 - (100 * result.length) / bytes.length);
-  return `${size(bytes.length)} → ${size(result.length)} (${percent}% smaller, SSIMULACRA2 ${score.toFixed(1)})`;
+  const quality = outcome === "hit" ? `quality ${Math.round(score)}/100: looks ${looks(score)}` : "lossless: looks identical";
+  const text = `${size(bytes.length)} → ${size(result.length)} (${smaller(bytes.length, result.length)}% smaller, ${quality})`;
+  return { text, original: bytes.length, written: result.length };
 }
 
 /** Writes a whole new file or nothing: the image is often written over itself. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-plugin-pngdeer",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Lint rule for oxlint and ESLint: flags PNGs and JPEGs your code uses that could be much smaller at about the same visual quality, with the command that shrinks them. Local WebAssembly, no upload.",
   "keywords": [
     "oxlint",

package/src/batch.js

@@ -14,8 +14,11 @@ const MAX_WORKERS = 8;
 // replaced rather than kept.
 const BIG = 300e6;
 
-/** Computes every file not cached yet; { computed, cached, skipped, failed, ms }. */
-export async function fill({ cwd, target, files }) {
+/**
+ * Computes every file not cached yet; { computed, cached, skipped, failed, ms }. `progress(done,
+ * total)` hears about each image the engine finishes.
+ */
+export async function fill({ cwd, target, files }, progress = () => {}) {
   const start = performance.now();
   const dir = cacheDir(cwd);
   // a cache that can't be written fails here, before any image is compressed for nothing
@@ -52,6 +55,7 @@ export async function fill({ cwd, target, files }) {
   }
   // biggest first, so the slowest image doesn't start last
   todo.sort((a, b) => b.peak - a.peak);
+  const total = todo.length;
 
   const record = (job, result) => {
     // the file changed or went away after it was queued: cache nothing, the next lint measures it again
@@ -110,6 +114,7 @@ export async function fill({ cwd, target, files }) {
         for (const l of lanes) l.worker?.terminate();
       } finally {
         self.busy = false;
+        progress(counts.computed + counts.failed, total);
         wake();
       }
     }

package/src/cache.js

@@ -2,8 +2,12 @@
 // saving only changes when its bytes, the engine or the target do. One small JSON file per entry,
 // so parallel lint threads and batch workers never write the same file twice over.
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { marked } from "./marker.js";
+import { smaller } from "./text.js";
+
+const keys = new Map(); // image path -> { size, mtimeMs, target, key, marked }, so images aren't re-read on every keystroke
 
 // The engine's identity: the first 16 hex digits of the wasm's SHA-256 (a few ms for 2 MB). A new
 // engine invalidates every entry.
@@ -16,14 +20,18 @@ export function cacheDir(cwd) {
   return join(cwd, "node_modules", ".cache", "pngdeer");
 }
 
+// What an entry holds: a new shape (2 added the score) measures everything again.
+const FORMAT = 2;
+
 /** The cache key of an image's bytes for a given target (undefined: automatic quality). */
 export function key(bytes, target) {
-  return createHash("sha256").update(bytes).update(`\0${ENGINE}\0${target ?? "auto"}`).digest("hex");
+  return createHash("sha256").update(bytes).update(`\0${ENGINE}\0${target ?? "auto"}\0${FORMAT}`).digest("hex");
 }
 
 /**
- * { original, compressed, outcome, ms }; { skipped } (with failed: true if pngdeer itself failed);
- * { outcome: "output" } for bytes pngdeer wrote; or null if not cached yet.
+ * { original, compressed, outcome, score, ms }, compressed counting the mark the command adds;
+ * { skipped } (with failed: true if pngdeer itself failed); { outcome: "output" } for bytes pngdeer
+ * wrote; or null if not cached yet.
  */
 export function read(dir, k) {
   try {
@@ -33,6 +41,28 @@ export function read(dir, k) {
   }
 }
 
+/** Whether an entry is a saving the rule reports: smaller at the target, by both thresholds. */
+export function reportable(entry, { minSavedBytes, minSavedPercent }) {
+  if (!entry || entry.skipped || !["hit", "exact", "lossless"].includes(entry.outcome)) return false;
+  const saved = entry.original - entry.compressed;
+  return saved >= minSavedBytes && smaller(entry.original, entry.compressed) >= minSavedPercent;
+}
+
+/** An image's size, the cache key of its current bytes and whether pngdeer wrote it; null if it can't be read. */
+export function fileKey(file, target) {
+  try {
+    const { size, mtimeMs } = statSync(file);
+    const memo = keys.get(file);
+    if (memo && memo.size === size && memo.mtimeMs === mtimeMs && memo.target === target) return memo;
+    const bytes = readFileSync(file);
+    const image = { size, mtimeMs, target, key: key(bytes, target), marked: marked(bytes) };
+    keys.set(file, image);
+    return image;
+  } catch {
+    return null;
+  }
+}
+
 export function write(dir, k, entry) {
   mkdirSync(dir, { recursive: true });
   // written whole and renamed, so a reader never sees half an entry

package/src/fill-worker.js

@@ -1,11 +1,16 @@
 // Runs one batch (batch.js) off the lint thread; sync.js waits on `signal` when it needs the answer.
+import { writeSync } from "node:fs";
+import { isatty } from "node:tty";
 import { workerData } from "node:worker_threads";
 import { fill } from "./batch.js";
 
 const { request, signal, port } = workerData;
+// A count that rewrites its own line while the lint waits. The lint thread is blocked on `signal`,
+// so it can't print; this writes to the terminal directly, and only to a terminal.
+const progress = request.progress && isatty(2) ? (done, total) => writeSync(2, `\rpngdeer: measuring ${total} images... ${done}/${total}`) : undefined;
 let reply;
 try {
-  reply = { result: await fill(request) };
+  reply = { result: await fill(request, progress) };
 } catch (error) {
   reply = { error: String(error?.message ?? error) };
   // a background batch has no one to tell but its exit code

package/src/rule.js

@@ -1,14 +1,15 @@
 // pngdeer/compressible-image: on each string in the code that names a local PNG or JPEG (imports,
 // require, new URL, JSX src and srcSet, plain strings), says how much smaller pngdeer would make it.
 // oxlint never lints image files themselves, so the reference is where the warning goes.
-import { readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { cacheDir, key, read } from "./cache.js";
-import { marked } from "./marker.js";
+import { statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { cacheDir, fileKey, read, reportable } from "./cache.js";
 import { projectImages } from "./scan.js";
+import { flag, name, summarize, watch } from "./summary.js";
 import { fillInBackground, fillSync } from "./sync.js";
-import { count, quote, size } from "./text.js";
+import { count, looks, pathFrom, quote, size, smaller } from "./text.js";
 
+const RULE = "pngdeer/compressible-image";
 const IMAGE = /\.(png|apng|jpe?g)$/i;
 const REMOTE = /^[a-z][a-z0-9+.-]*:|^\/\//i;
 const DEFAULTS = { minSavedBytes: 4096, minSavedPercent: 10, target: "auto", measure: "auto" };
@@ -24,12 +25,10 @@ const EDITOR =
   process.env.ELECTRON_RUN_AS_NODE === "1";
 
 // Per process (the language server's lasts the whole editor session):
-const keys = new Map(); // image path -> { size, mtimeMs, target, key, marked }, so images aren't re-read on every keystroke
 const roots = new Map(); // directory -> its project root
 const scanned = new Set(); // `${root}\0${target}` whose images were all measured, or queued, once
 const failed = new Set(); // outside editors: roots whose batch failed, not tried again this run
 const told = new Set(); // outside editors: images already named on stderr
-const savings = new Map(); // outside editors: image path -> { original, saved }, for the total at exit
 
 export default {
   meta: {
@@ -40,8 +39,8 @@ export default {
       url: "https://github.com/lndgalante/oxlint-plugin-pngdeer/blob/main/docs/rules/compressible-image.md",
     },
     messages: {
-      compressible: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}) at {{quality}}. Run: {{command}}",
-      lossless: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}) losslessly. Run: {{command}}",
+      compressible: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}) and look {{looks}} (quality {{quality}}/100). Run: {{command}}",
+      lossless: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}), losslessly. Run: {{command}}",
     },
     schema: [
       {
@@ -70,36 +69,55 @@ export default {
     const dir = cacheDir(root);
     const find = (path) => locate(path, from, root, publicDirs, aliases);
     // a path as the person running the linter would type it
-    const shown = (file) => relative(context.cwd, file).split(sep).join("/");
+    const shown = (file) => pathFrom(context.cwd, file);
     const wait = measure === "always" || (measure === "auto" && !EDITOR);
     const found = [];
 
+    const reported = new Set(); // images warned about in this file: once each, at their first mention
+    let disabled; // (line) => whether a comment turns this rule off there, read on first use
+    if (!EDITOR) watch(root, { minSavedBytes, minSavedPercent, target });
+
     function check(node, text) {
-      for (const file of imagesIn(text, find)) {
+      for (const { file, part } of imagesIn(text, find)) {
         const image = fileKey(file, target);
         // a file smaller than minSavedBytes can't save that much: not worth measuring
-        if (image && image.size >= minSavedBytes) found.push({ node, file, k: image.key });
+        if (!EDITOR) name(file);
+        if (image && image.size >= minSavedBytes) found.push({ node, file, k: image.key, loc: part && within(node, part) });
       }
     }
 
-    function report({ node, file }, result) {
-      if (!result || result.skipped || !["hit", "exact", "lossless"].includes(result.outcome)) return;
-      const saved = result.original - result.compressed;
-      const percent = Math.round((100 * saved) / result.original);
-      if (saved < minSavedBytes || percent < minSavedPercent) return;
-      if (!EDITOR) savings.set(file, { original: result.original, saved });
+    // Where `part` sits in a string's source, so a warning for one image of a srcSet underlines that
+    // image alone; null if the source spells it differently (escapes), and the whole string is used.
+    function within(node, part) {
+      const source = context.sourceCode;
+      const at = source.getText(node).indexOf(part);
+      if (at < 0) return null;
+      const start = node.range[0] + at;
+      return { start: source.getLocFromIndex(start), end: source.getLocFromIndex(start + part.length) };
+    }
+
+    function report({ node, file, loc }, result) {
+      if (!reportable(result, { minSavedBytes, minSavedPercent }) || reported.has(file)) return;
+      // The linter hides a warning a comment turns off by itself, but the image mustn't count as
+      // flagged either, or --flagged would rewrite an image someone chose to keep.
+      disabled ??= disabledLines(context.sourceCode);
+      if (disabled((loc?.start ?? node.loc.start).line)) return;
+      reported.add(file);
+      if (!EDITOR) flag(file, { original: result.original, compressed: result.compressed, score: result.score, target });
       // this package's own command (bin/pngdeer.js), at the target measured, so it writes exactly the
       // file this promises; named by the package, so npx can't fetch someone else's
       const command = `npx oxlint-plugin-pngdeer ${quote(shown(file))}${target === undefined ? "" : ` --target ${target}`}`;
       context.report({
         node,
+        loc: loc ?? undefined,
         messageId: result.outcome === "hit" ? "compressible" : "lossless",
         data: {
           name: basename(file),
-          percent,
+          percent: smaller(result.original, result.compressed),
           before: size(result.original),
           after: size(result.compressed),
-          quality: target === undefined ? "about the same visual quality" : `SSIMULACRA2 ${target}`,
+          looks: looks(result.score),
+          quality: Math.round(result.score),
           command,
         },
       });
@@ -119,15 +137,17 @@ export default {
       TemplateLiteral(node) {
         if (node.expressions.length === 0) check(node, node.quasis[0].value.cooked ?? "");
       },
-      // What this file names is measured, then reported. The first time, every image in the
-      // project goes in the same parallel batch, so the files linted next find theirs cached.
+      // What this file names is measured, then reported. The first file of a project in a run also
+      // takes every image in it, named or not, in the same parallel batch: the files linted next find
+      // theirs cached, and the summary can tell about images only CSS or HTML use.
       "Program:exit"() {
-        if (found.length === 0) return;
-        const missing = measure === "never" ? [] : [...new Set(found.filter(({ k }) => !read(dir, k)).map(({ file }) => file))];
-        if (missing.length) {
-          const group = `${root}\0${target}`;
-          const files = scanned.has(group) ? missing : [...new Set([...missing, ...projectImages(root, minSavedBytes)])];
-          scanned.add(group);
+        const group = `${root}\0${target}`;
+        const first = measure !== "never" && !scanned.has(group);
+        if (found.length === 0 && !first) return;
+        scanned.add(group);
+        const missing = measure === "never" ? [] : found.filter(({ k }) => !read(dir, k)).map(({ file }) => file);
+        const files = [...new Set(first ? [...missing, ...projectImages(root, minSavedBytes)] : missing)];
+        if (files.length) {
           if (!wait) fillInBackground({ cwd: root, target, files });
           else if (!failed.has(root)) measureNow(files);
         }
@@ -145,35 +165,32 @@ export default {
         const image = fileKey(file, target);
         return image && !image.marked && !read(dir, image.key);
       }).length;
-      if (fresh) process.stderr.write(`pngdeer: measuring ${count(fresh, "image")} not in the cache yet...\n`);
+      // everything cached (or pngdeer's own output, which needs no engine): nothing to wait for
+      if (!fresh) return;
+      // on a terminal the batch rewrites this line as a count (fill-worker.js), and it's cleared after
+      const tty = Boolean(process.stderr.isTTY);
+      process.stderr.write(`pngdeer: measuring ${count(fresh, "image")} not in the cache yet...${tty ? "" : "\n"}`);
       try {
-        const { computed, ms } = fillSync({ cwd: root, target, files });
+        const { computed, ms } = fillSync({ cwd: root, target, files, progress: tty });
+        if (tty) process.stderr.write("\r\x1b[K");
         if (computed) process.stderr.write(`pngdeer: measured ${count(computed, "image")} in ${(ms / 1000).toFixed(1)} s; later runs read the cache\n`);
       } catch (error) {
         // the images stay unmeasured (and unreported) rather than failing the lint, and the rest
         // of this run doesn't try again
         failed.add(root);
-        process.stderr.write(`${error.message}\n`);
+        process.stderr.write(`${tty ? "\n" : ""}${error.message}\n`);
       }
     }
   },
 };
 
-// A run's last word, outside editors: what all the warnings add up to, each image counted once.
-if (!EDITOR) {
-  process.once("exit", () => {
-    if (savings.size === 0) return;
-    let original = 0;
-    let saved = 0;
-    for (const image of savings.values()) {
-      original += image.original;
-      saved += image.saved;
-    }
-    process.stderr.write(`pngdeer: ${count(savings.size, "image")} could be ${size(saved)} smaller in all (${Math.round((100 * saved) / original)}%)\n`);
-  });
-}
+// A run's last word, outside editors: what all the warnings add up to (summary.js).
+if (!EDITOR) process.once("exit", () => summarize());
 
-/** The image files a string in the code names: itself, or else a srcSet's candidates. */
+/**
+ * The image files a string in the code names, as [{ file, part }]: the string itself (part null), or
+ * else a srcSet's candidates, each with the text that names it.
+ */
 function imagesIn(text, find) {
   // a query or hash ends a path, but a leading # is a subpath import ("#assets/x.png")
   const strip = (path) => path.replace(/(?!^)[?#].*$/, "");
@@ -181,9 +198,38 @@ function imagesIn(text, find) {
   // a whole path first, as file names can hold spaces and commas ("Screenshot … at 10.12.33.png")
   const whole = strip(text.trim());
   const single = usable(whole) && find(whole);
-  if (single) return [single];
-  const candidates = text.split(",").map((part) => strip(part.trim().split(/\s+/)[0]));
-  return candidates.filter(usable).map(find).filter(Boolean);
+  if (single) return [{ file: single, part: null }];
+  const parts = text.split(",").map((part) => part.trim().split(/\s+/)[0]);
+  return parts
+    .filter((part) => usable(strip(part)))
+    .map((part) => ({ file: find(strip(part)), part }))
+    .filter(({ file }) => file);
+}
+
+/**
+ * Whether a comment turns this rule off at a line: `oxlint-` or `eslint-disable-next-line` above it,
+ * `-disable-line` on it, or a `-disable` block around it, for this rule or for all rules.
+ */
+function disabledLines(source) {
+  const lines = new Set();
+  const blocks = [];
+  let open = null;
+  for (const comment of source.getAllComments()) {
+    const directive = /^\s*(?:oxlint|eslint)-(disable-next-line|disable-line|disable|enable)\b(.*)$/s.exec(comment.value);
+    if (!directive) continue;
+    const [, kind, rest] = directive;
+    const rules = rest.split("--")[0].split(",").map((rule) => rule.trim()).filter(Boolean);
+    if (rules.length && !rules.includes(RULE)) continue;
+    if (kind === "disable-next-line") lines.add(comment.loc.end.line + 1);
+    else if (kind === "disable-line") lines.add(comment.loc.start.line);
+    else if (kind === "disable") open ??= comment.loc.start.line;
+    else if (open !== null) {
+      blocks.push([open, comment.loc.start.line]);
+      open = null;
+    }
+  }
+  if (open !== null) blocks.push([open, Infinity]);
+  return (line) => lines.has(line) || blocks.some(([from, to]) => line >= from && line <= to);
 }
 
 /** The file a path in `from` names, or null: relative to the file, or "/x" in a public dir or the root. */
@@ -208,21 +254,6 @@ function projectRoot(dir, fallback) {
   return roots.get(dir);
 }
 
-/** An image's size, the cache key of its current bytes and whether pngdeer wrote it; null if it can't be read. */
-function fileKey(file, target) {
-  try {
-    const { size, mtimeMs } = statSync(file);
-    const memo = keys.get(file);
-    if (memo && memo.size === size && memo.mtimeMs === mtimeMs && memo.target === target) return memo;
-    const bytes = readFileSync(file);
-    const image = { size, mtimeMs, target, key: key(bytes, target), marked: marked(bytes) };
-    keys.set(file, image);
-    return image;
-  } catch {
-    return null;
-  }
-}
-
 function isFile(path) {
   try {
     return statSync(path).isFile();

package/src/scan.js

@@ -1,8 +1,9 @@
-// Every PNG and JPEG in a project, to measure them all in one parallel batch the first time the
-// rule meets an image it hasn't seen (later references then find them cached). Folders are skipped
-// by name, not by reading .gitignore: dot folders, dependencies, build output, and test output such
-// as visual-regression snapshots, which are images too but never shipped. A folder with its own
-// package.json is another project, with its own cache, and is left to it.
+// Every PNG and JPEG in a project, to measure them all in one parallel batch on a run's first file
+// (later references then find them cached), and the other files the summary searches for images no
+// linted code names. Folders are skipped by name, not by reading .gitignore: dot folders,
+// dependencies, build output, and test output such as visual-regression snapshots, which are images
+// too but never shipped. A folder with its own package.json is another project, with its own cache,
+// and is left to it.
 import { readdirSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { EXTENSIONS } from "./images.js";
@@ -15,6 +16,11 @@ const SKIP = new Set([
 
 /** The project's images of at least `minSize` bytes. */
 export function projectImages(root, minSize = 0) {
+  return projectFiles(root, EXTENSIONS, minSize);
+}
+
+/** The project's files with one of `extensions`, from `minSize` to `maxSize` bytes. */
+export function projectFiles(root, extensions, minSize = 0, maxSize = Infinity) {
   const found = [];
   const walk = (dir) => {
     let entries;
@@ -30,8 +36,9 @@ export function projectImages(root, minSize = 0) {
       if (entry.isDirectory()) {
         // Playwright keeps a test's snapshots in "<test file>-snapshots"
         if (!SKIP.has(entry.name) && !entry.name.endsWith("-snapshots")) walk(path);
-      } else if (entry.isFile() && EXTENSIONS.includes(extname(entry.name).toLowerCase()) && size(path) >= minSize) {
-        found.push(path);
+      } else if (entry.isFile() && extensions.includes(extname(entry.name).toLowerCase())) {
+        const bytes = size(path);
+        if (bytes >= minSize && bytes <= maxSize) found.push(path);
       }
     }
   };

package/src/summary.js

@@ -0,0 +1,163 @@
+// What a lint flagged, in all: a table at the end of the run, biggest saving first, and the list that
+// `npx oxlint-plugin-pngdeer --flagged` shrinks, so nobody copies paths from warnings one by one.
+// The table also lists images the run measured that no linted JS or TS names, which no warning can
+// point at, each with where it is used instead (a stylesheet, a page, a template), if anywhere.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { cacheDir, fileKey, read, reportable } from "./cache.js";
+import { projectFiles, projectImages } from "./scan.js";
+import { count, pathFrom, quote, size, smaller } from "./text.js";
+
+// Rows shown per table; the rest are counted, and --flagged still takes them all.
+const ROWS = 10;
+const UNNAMED_ROWS = 5;
+// Formats other programs read: the table on stderr would only get in the way.
+const MACHINE = new Set(["json", "json-with-metadata", "checkstyle", "junit", "sarif", "gitlab"]);
+// Files the linter doesn't read but that use images, most telling first: styles, pages and
+// templates, then content and data. Markdown comes last, and only "mentions" an image: a README
+// that names one may just be describing it.
+const PAGES = [".css", ".scss", ".sass", ".less", ".styl", ".html", ".htm", ".vue", ".svelte", ".astro", ".mdx", ".json", ".yml", ".yaml"];
+const DOCS = [".md"];
+const PAGE_BYTES = 1e6; // bigger ones are build output or lockfiles, not where people name images
+
+const flagged = new Map(); // image path -> { original, compressed, score, target }
+const named = new Set(); // every image linted code names, flagged or not
+const roots = new Map(); // project root -> the rule's options there
+
+/** Notes an image a warning was reported for. */
+export function flag(file, entry) {
+  flagged.set(file, entry);
+}
+
+/** Notes an image linted code names. */
+export function name(file) {
+  named.add(file);
+}
+
+/** Notes a project the lint ran in, and the options it ran with, to find images nothing names. */
+export function watch(root, options) {
+  roots.set(root, options);
+}
+
+/** The list a lint run from `cwd` leaves for --flagged. */
+export function flaggedList(cwd) {
+  return join(cacheDir(cwd), "flagged.json");
+}
+
+/** The images the last lint run from `cwd` flagged, as [{ file, target }]; null if no lint left a list. */
+export function readFlagged(cwd) {
+  try {
+    return JSON.parse(readFileSync(flaggedList(cwd), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Prints the table on stderr and leaves the list in `cwd`; once, as the lint exits. */
+export function summarize(cwd = process.cwd()) {
+  const list = flaggedList(cwd);
+  const images = [...flagged].sort(([, a], [, b]) => b.original - b.compressed - (a.original - a.compressed));
+  // a clean run replaces an older list, but doesn't create one
+  if (images.length || existsSync(list)) {
+    try {
+      mkdirSync(dirname(list), { recursive: true });
+      writeFileSync(list, JSON.stringify(images.map(([file, { target }]) => ({ file, target }))));
+    } catch {
+      // without the list, --flagged has nothing to read; the table still tells
+    }
+  }
+  if (process.argv.includes("--quiet") || MACHINE.has(format())) return;
+
+  const unnamed = unnamedImages();
+  if (images.length === 0 && unnamed.length === 0) return;
+  const shownUnnamed = unnamed.slice(0, UNNAMED_ROWS);
+  const row = ([file, { original, compressed, score }]) => [pathFrom(cwd, file), size(original), size(compressed), size(original - compressed), String(Math.round(score))];
+  const header = ["image", "now", "after", "saves", "quality"];
+  // the unnamed images say where they're named, as no warning can point there
+  const where = ([file, , root]) => {
+    const page = namedIn(root, file);
+    if (!page) return "nothing names it";
+    return `${page.endsWith(".md") ? "mentioned" : "used"} in ${pathFrom(cwd, page)}`;
+  };
+  const rows = [header, ...images.slice(0, ROWS).map(row), ...shownUnnamed.map((image) => [...row(image), where(image)])];
+  const width = (column) => Math.max(...rows.map((cells) => (cells[column] ?? "").length));
+  const line = ([path, before, after, saved, score, place], arrow = "→") =>
+    `  ${path.padEnd(width(0))}  ${before.padStart(width(1))} ${arrow} ${after.padStart(width(2))}  ${saved.padStart(width(3))}  ${score.padStart(width(4))}${place === undefined ? "" : `  ${place}`}`.trimEnd();
+  const total = (list) => {
+    const original = list.reduce((sum, [, image]) => sum + image.original, 0);
+    const compressed = list.reduce((sum, [, image]) => sum + image.compressed, 0);
+    return { saved: size(original - compressed), detail: `${size(original)} → ${size(compressed)}, ${smaller(original, compressed)}% smaller` };
+  };
+  const lines = [];
+  if (images.length) {
+    const { saved, detail } = total(images);
+    lines.push(`pngdeer: ${count(images.length, "flagged image")} could be ${saved} smaller in all (${detail}):`, line(header, " "));
+    lines.push(...rows.slice(1, 1 + Math.min(images.length, ROWS)).map((cells) => line(cells)));
+    if (images.length > ROWS) lines.push(`  …and ${count(images.length - ROWS, "more image")}, ${total(images.slice(ROWS)).saved} in all`);
+  }
+  if (unnamed.length) {
+    // no warning can point at these: their only mention is in CSS, HTML and the like, or nowhere
+    const { saved } = total(unnamed);
+    const lead = images.length ? "also" : "no warnings, but";
+    lines.push(`pngdeer: ${lead} ${count(unnamed.length, "image")} that no linted JS or TS names could be ${saved} smaller:`);
+    if (!images.length) lines.push(line(header, " "));
+    lines.push(...rows.slice(1 + Math.min(images.length, ROWS)).map((cells) => line(cells)));
+    if (unnamed.length > UNNAMED_ROWS) lines.push(`  …and ${count(unnamed.length - UNNAMED_ROWS, "more image")}`);
+  }
+  lines.push("pngdeer: quality is SSIMULACRA2, out of 100: 90+ looks identical, 80+ the same side by side, 70+ close, with differences you might spot side by side");
+  if (images.length) {
+    lines.push(`pngdeer: to shrink the ${images.length === 1 ? "flagged image" : `${images.length} flagged images`} in place (lossy, so commit first), run: npx oxlint-plugin-pngdeer --flagged`);
+  }
+  if (unnamed.length) {
+    const paths = shownUnnamed.map(([file]) => quote(pathFrom(cwd, file))).join(" ");
+    const which = unnamed.length === 1 ? "it" : "them";
+    lines.push(`pngdeer: to shrink ${images.length ? `${which} too` : `${which} in place (lossy, so commit first)`}, run: npx oxlint-plugin-pngdeer ${paths}`);
+    if (shownUnnamed.some((image) => !namedIn(image[2], image[0]))) {
+      lines.push("pngdeer: an image nothing names may be unused (or its path is built at runtime): deleting it saves it all");
+    }
+  }
+  process.stderr.write(`${lines.join("\n")}\n`);
+}
+
+/**
+ * Measured images in the linted projects that no linted code names, and that would clear the rule's
+ * thresholds: [[path, entry, root]], biggest saving first. Reads only results already cached.
+ */
+function unnamedImages() {
+  const found = [];
+  for (const [root, options] of roots) {
+    for (const file of projectImages(root, options.minSavedBytes)) {
+      if (named.has(file) || flagged.has(file)) continue;
+      const image = fileKey(file, options.target);
+      const entry = image && read(cacheDir(root), image.key);
+      if (reportable(entry, options)) found.push([file, entry, root]);
+    }
+  }
+  return found.sort(([, a], [, b]) => b.original - b.compressed - (a.original - a.compressed));
+}
+
+const pages = new Map(); // project root -> [{ path, text }] of its PAGES, then its DOCS, read once
+
+/** The most telling file the linter doesn't read (a stylesheet, a template, a doc) that names `image`; or null. */
+function namedIn(root, image) {
+  if (!pages.has(root)) {
+    const files = [...PAGES, ...DOCS].flatMap((extension) => projectFiles(root, [extension], 0, PAGE_BYTES));
+    pages.set(root, files.flatMap((path) => {
+      try {
+        return [{ path, text: readFileSync(path, "utf8") }];
+      } catch {
+        return [];
+      }
+    }));
+  }
+  const name = basename(image);
+  return pages.get(root).find(({ text }) => text.includes(name))?.path ?? null;
+}
+
+/** The linter's output format, from its command line: `-f x`, `--format x` or `--format=x`. */
+function format() {
+  const args = process.argv;
+  const at = args.findIndex((arg) => arg === "-f" || arg === "--format");
+  if (at >= 0) return args[at + 1];
+  return args.find((arg) => arg.startsWith("--format="))?.slice("--format=".length);
+}

package/src/text.js

@@ -1,3 +1,5 @@
+import { relative, sep } from "node:path";
+
 /** A file size as people read it: decimal kB and MB. */
 export function size(bytes) {
   if (bytes < 1000) return `${bytes} B`;
@@ -5,6 +7,30 @@ export function size(bytes) {
   return `${(bytes / 1e6).toFixed(1)} MB`;
 }
 
+/** How much smaller `after` bytes are than `before`, in whole percent. */
+export function smaller(before, after) {
+  return Math.round(100 - (100 * after) / before);
+}
+
+/** `file` as typed from `cwd`, with forward slashes on every platform. */
+export function pathFrom(cwd, file) {
+  return relative(cwd, file).split(sep).join("/");
+}
+
+/**
+ * How a file at this SSIMULACRA2 score looks next to the original, after "looks", in the metric's
+ * own terms: 90 can't be told apart even flipping between them, 80 not side by side, 70 shows
+ * artifacts that aren't annoying.
+ */
+export function looks(score) {
+  // the whole number people see (89.5 shows as 90), so the words match it
+  const shown = Math.round(score);
+  if (shown >= 90) return "identical";
+  if (shown >= 80) return "the same side by side";
+  if (shown >= 70) return "close, with differences you might spot side by side";
+  return "visibly different";
+}
+
 /** "1 image", "5 images". */
 export function count(n, noun) {
   return `${n} ${noun}${n === 1 ? "" : "s"}`;

package/src/worker.js

@@ -5,6 +5,7 @@ import { readFileSync } from "node:fs";
 import { parentPort, workerData } from "node:worker_threads";
 import { key } from "./cache.js";
 import { compress } from "./engine.js";
+import { mark } from "./marker.js";
 
 const why = (error) => String(error?.message ?? error);
 
@@ -19,9 +20,11 @@ parentPort.on("message", ({ file }) => {
   }
   const input = key(bytes, workerData.target);
   try {
-    const { output, outcome } = compress(bytes, workerData.target);
+    const { output, outcome, score } = compress(bytes, workerData.target);
     const ms = Math.round(performance.now() - start);
-    parentPort.postMessage({ input, original: bytes.length, compressed: output.length, outcome, ms, output: key(output, workerData.target) });
+    // the size the command will write, mark included, so the warning and the command agree
+    const compressed = outcome === "original" ? bytes.length : mark(output).length;
+    parentPort.postMessage({ input, original: bytes.length, compressed, outcome, score, ms, output: key(output, workerData.target) });
   } catch (error) {
     parentPort.postMessage({ input, error: why(error) });
   }