oxlint-plugin-pngdeer 0.1.0 → 0.2.0

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,44 @@ 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: 1 more image could be 5.1 kB smaller, but no linted code names it (used from CSS or HTML, or not at all):
+  public/unused-fire.png        13 kB → 7.5 kB  5.1 kB       90
+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
 ```
 
-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. It also lists images the run measured that no linted code names, like a CSS background, which no warning can point at.
+- **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.0",
   "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

@@ -4,6 +4,7 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { smaller } from "./text.js";
 
 // 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 +17,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 +38,13 @@ 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;
+}
+
 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

@@ -2,13 +2,15 @@
 // 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 { basename, dirname, join, resolve } from "node:path";
+import { cacheDir, key, read, reportable } from "./cache.js";
 import { marked } from "./marker.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" };
@@ -29,7 +31,6 @@ 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 +41,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 +71,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,
         },
       });
@@ -145,35 +165,30 @@ 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`);
+      // on a terminal the batch rewrites this line as a count (fill-worker.js), and it's cleared after
+      const tty = Boolean(fresh && process.stderr.isTTY);
+      if (fresh) 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 +196,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. */

package/src/summary.js

@@ -0,0 +1,125 @@
+// 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 names images the run measured but no linted code names (used from CSS or HTML, or
+// not at all), which no warning can point at.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { cacheDir, key, read, reportable } from "./cache.js";
+import { projectImages } from "./scan.js";
+import { count, pathFrom, 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"]);
+
+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 row = ([file, { original, compressed, score }]) => [pathFrom(cwd, file), size(original), size(compressed), size(original - compressed), String(Math.round(score))];
+  const rows = [["image", "now", "after", "saves", "quality"], ...images.slice(0, ROWS).map(row), ...unnamed.slice(0, UNNAMED_ROWS).map(row)];
+  const width = (column) => Math.max(...rows.map((cells) => cells[column].length));
+  const line = ([path, before, after, saved, score], arrow = "→") =>
+    `  ${path.padEnd(width(0))}  ${before.padStart(width(1))} ${arrow} ${after.padStart(width(2))}  ${saved.padStart(width(3))}  ${score.padStart(width(4))}`;
+  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(rows[0], " "));
+    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) {
+    const { saved } = total(unnamed);
+    lines.push(`pngdeer: ${count(unnamed.length, "more image")} could be ${saved} smaller, but no linted code names ${unnamed.length === 1 ? "it" : "them"} (used from CSS or HTML, or not at all):`);
+    if (!images.length) lines.push(line(rows[0], " "));
+    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`);
+  }
+  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]], 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;
+      let entry;
+      try {
+        entry = read(cacheDir(root), key(readFileSync(file), options.target));
+      } catch {
+        continue;
+      }
+      if (reportable(entry, options)) found.push([file, entry]);
+    }
+  }
+  return found.sort(([, a], [, b]) => b.original - b.compressed - (a.original - a.compressed));
+}
+
+/** 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) });
   }