oxlint-plugin-pngdeer 0.2.0 → 0.3.0

package/README.md

@@ -65,14 +65,16 @@ pngdeer: 4 flagged images could be 718 kB smaller in all (1.0 MB → 310 kB, 70%
   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: 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
 ```
 
-- **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.
+- **Each image warns once per file,** on the line that names it, and says how close to the original it would look. An image named in several files gets the full warning once per run, and a short one after that.
+- **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.
@@ -89,7 +91,7 @@ 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.
+- **Several images run in parallel,** one engine per core, within a quarter of the machine's memory, like the lint's first run.
 - **`--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.
@@ -98,7 +100,7 @@ Already have oxlint 1.90 or later? Install only `oxlint-plugin-pngdeer`. If your
 
 ## Using ESLint
 
-The same rule runs in ESLint 9 and 10, and shares the cache with oxlint:
+The same rule runs in ESLint 9 and 10, and shares the cache with oxlint. With `--concurrency`, ESLint's threads take turns measuring and print one summary:
 
 ```bash
 npm install --save-dev oxlint-plugin-pngdeer
@@ -157,7 +159,15 @@ Measured on a 16-core M-series Mac ([details](https://github.com/lndgalante/oxli
 
 ## In CI
 
-`npm ci` deletes `node_modules`, and the cache with it, so restore the cache after installing, and save it even when the lint fails:
+The simplest way to never start cold: keep the results in a folder you commit, so CI and every clone start with them.
+
+```json
+"settings": { "pngdeer": { "cacheDir": ".pngdeer" } }
+```
+
+Results are small JSON files, one per image version, formatted the way Prettier formats JSON (Biome users: add `!.pngdeer` to `files.includes`). After you add or change images, run `npx oxlint` and commit `.pngdeer` with them. Images pngdeer fails on are remembered on each machine only, never in the committed folder. Upgrading the plugin to a new engine measures everything again; delete the folder first to drop the old results. In a monorepo, packages can share one folder (`"cacheDir": "../../.pngdeer"`).
+
+Or let CI cache it. `npm ci` deletes `node_modules`, and the default cache with it, so restore the cache after installing, and save it even when the lint fails:
 
 ```yaml
 - run: npm ci

package/bin/pngdeer.js

@@ -2,13 +2,11 @@
 // oxlint-plugin-pngdeer: makes the images the lint rule flags smaller, with the engine the rule
 // measures with, so each file it writes is the one the warning promised. Files it writes are marked
 // as pngdeer's (src/marker.js), so the rule never measures them again, on any machine.
-import { chmodSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-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 { readFileSync, realpathSync } from "node:fs";
+import { peakOf, pool } from "../src/batch.js";
+import { plain, shrink } from "../src/shrink.js";
 import { readFlagged } from "../src/summary.js";
-import { count, looks, pathFrom, size, smaller } from "../src/text.js";
+import { count, pathFrom, size } from "../src/text.js";
 
 const HELP = `usage: oxlint-plugin-pngdeer IMAGE... [--target auto|T]
        oxlint-plugin-pngdeer --flagged [--target auto|T]
@@ -27,7 +25,7 @@ pngdeer is lossy: the picture looks the same, the bytes don't, so commit first.
 
 Files it writes are marked as pngdeer's, so the lint rule doesn't flag them again.`;
 
-function main(args) {
+async function main(args) {
   const inputs = [];
   let output;
   let target;
@@ -70,90 +68,80 @@ function main(args) {
     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 }));
+  const jobs = once(
+    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)`);
+  // one image runs here; several run on a pool of engines, one per core, each line printed as it lands
+  if (jobs.length === 1) {
+    const [{ input, target }] = jobs;
+    try {
+      console.log(`${input}: ${shrink(input, output ?? input, target).text}`);
+      return 0;
+    } catch (error) {
+      console.error(`${input}: ${plain(error)}`);
+      return 1;
+    }
+  }
+  console.error(`pngdeer: shrinking ${count(jobs.length, "image")} in place (lossy; commit first so you can undo)`);
   let status = 0;
+  let finished = 0;
   let original = 0;
   let compressed = 0;
   let shrunk = 0;
-  for (const [i, { input, target }] of jobs.entries()) {
-    const step = many ? `[${i + 1}/${jobs.length}] ` : "";
+  const report = (input, result) => {
+    const step = `[${++finished}/${jobs.length}] ${input}`;
+    if (result.error) {
+      console.error(`${step}: ${result.error}`);
+      status = 1;
+      return;
+    }
+    console.log(`${step}: ${result.text}`);
+    if (result.written) {
+      shrunk++;
+      original += result.original;
+      compressed += result.written;
+    }
+  };
+  const work = [];
+  for (const { input, target } of jobs) {
+    let bytes;
     try {
-      const result = shrink(input, output ?? input, target);
-      console.log(`${step}${input}: ${result.text}`);
-      if (result.written) {
-        shrunk++;
-        original += result.original;
-        compressed += result.written;
-      }
+      bytes = readFileSync(input);
     } catch (error) {
-      console.error(`${step}${input}: ${plain(error)}`);
-      status = 1;
+      report(input, { error: plain(error) });
+      continue;
     }
+    work.push({ input, peak: peakOf(bytes), message: { file: input, target, out: input } });
   }
-  if (many && shrunk) {
+  try {
+    await pool(work, { done: (job, result) => report(job.input, result) });
+  } catch (error) {
+    console.error(`oxlint-plugin-pngdeer: ${plain(error)}`);
+    return 1;
+  }
+  if (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`: { 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 { text: `${note}; left as is` };
-  };
-  if (marked(bytes)) return unchanged("already pngdeer's");
-  const why = unsupported(bytes);
-  if (why) throw new Error(why);
-
-  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 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 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. */
-function save(path, bytes) {
-  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.tmp`);
-  try {
-    writeFileSync(tmp, bytes);
+/** Each image once: overlapping globs or ./ forms would shrink it twice, the second time lossily. */
+function once(jobs) {
+  const seen = new Set();
+  return jobs.filter(({ input }) => {
+    let path = input;
     try {
-      chmodSync(tmp, statSync(path).mode & 0o7777);
+      path = realpathSync(input);
     } catch {
-      // a new file keeps the default mode
+      // a missing file is reported when it's read
     }
-    renameSync(tmp, path);
-  } catch (error) {
-    rmSync(tmp, { force: true });
-    if (error.code === "ENOENT") throw new Error(`can't write ${path}: its folder doesn't exist`);
-    throw error;
-  }
-}
-
-/** An error as one line a person can act on. */
-function plain(error) {
-  if (error.code === "ENOENT") return "no such file";
-  if (error.code === "EACCES" || error.code === "EPERM") return "permission denied";
-  if (error.code === "EISDIR") return "a folder, not an image";
-  return error.message;
+    if (seen.has(path)) return false;
+    seen.add(path);
+    return true;
+  });
 }
 
 function fail(message) {
@@ -161,4 +149,4 @@ function fail(message) {
   return 2;
 }
 
-process.exitCode = main(process.argv.slice(2));
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-plugin-pngdeer",
-  "version": "0.2.0",
+  "version": "0.3.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

@@ -1,11 +1,12 @@
 // Fills the cache for a list of images, on a pool of worker threads (one wasm engine each, so all
-// cores work even though the engine itself is single-threaded), within a memory budget.
-import { readFileSync, rmSync } from "node:fs";
+// cores work even though the engine itself is single-threaded), within a memory budget. The command
+// shrinks several images on the same pool.
+import { mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { availableParallelism, totalmem } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Worker } from "node:worker_threads";
-import { cacheDir, key, read, write } from "./cache.js";
+import { key, read, readFirst, write } from "./cache.js";
 import { dimensions, kind, unsupported } from "./images.js";
 import { marked } from "./marker.js";
 
@@ -13,18 +14,32 @@ const MAX_WORKERS = 8;
 // Wasm memory never shrinks, so a worker that measured an image expected to peak above this is
 // replaced rather than kept.
 const BIG = 300e6;
+// A batch holding the lock longer than this died with it (sync.js gives up waiting at 15 minutes too).
+const STALE_MS = 15 * 60 * 1000;
 
 /**
  * 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 = () => {}) {
+export async function fill({ dir, failures = dir, target, files }, progress = () => {}) {
+  // a result in either folder counts: `failures` keeps what pngdeer failed on, on this machine only
+  const cached = (k) => readFirst(k, dir, failures);
   const start = performance.now();
-  const dir = cacheDir(cwd);
   // a cache that can't be written fails here, before any image is compressed for nothing
-  write(dir, "probe", {});
-  rmSync(join(dir, "probe.json"), { force: true });
+  for (const folder of new Set([dir, failures])) {
+    write(folder, "probe", {});
+    rmSync(join(folder, "probe.json"), { force: true });
+  }
+  const release = await lock(failures);
+  try {
+    return await measure({ dir, failures, target, files, cached }, progress, start);
+  } finally {
+    release();
+  }
+}
 
+/** fill() once it holds the lock: what's cached by then is skipped, the rest goes to the pool. */
+async function measure({ dir, failures, target, files, cached }, progress, start) {
   const todo = [];
   const counts = { computed: 0, cached: 0, skipped: 0, failed: 0 };
   for (const file of new Set(files)) {
@@ -35,12 +50,12 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
       continue;
     }
     const k = key(bytes, target);
-    if (read(dir, k)) {
+    if (cached(k)) {
       counts.cached++;
       continue;
     }
+    // pngdeer's own output needs no engine, and no entry: the rule knows it by its mark
     if (marked(bytes)) {
-      write(dir, k, { original: bytes.length, outcome: "output" });
       counts.skipped++;
       continue;
     }
@@ -50,12 +65,8 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
       counts.skipped++;
       continue;
     }
-    const [width, height, frames] = dimensions(bytes, kind(bytes));
-    todo.push({ file, k, peak: peak(width * height * frames) });
+    todo.push({ file, k, peak: peakOf(bytes), message: { file, target } });
   }
-  // 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
@@ -64,7 +75,7 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
       return;
     }
     if (result.error) {
-      write(dir, job.k, { skipped: result.error, failed: true });
+      write(failures, job.k, { skipped: result.error, failed: true });
       counts.failed++;
       return;
     }
@@ -76,6 +87,30 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
     if (output !== input) write(dir, output, { original: entry.compressed, outcome: "output" });
   };
 
+  const total = todo.length;
+  await pool(todo, {
+    // the same bytes may have been marked as pngdeer's output since the batch started
+    skip: (job) => {
+      if (!cached(job.k)) return false;
+      counts.cached++;
+      return true;
+    },
+    done: (job, result) => {
+      record(job, result);
+      progress(counts.computed + counts.failed, total);
+    },
+  });
+  return { ...counts, ms: Math.round(performance.now() - start) };
+}
+
+/**
+ * Runs `jobs` ({ peak, message }) on a pool of engines (worker.js), biggest first, within the memory
+ * budget. `done(job, reply)` gets each reply as it comes; a job `skip(job)` turns down when its turn
+ * comes isn't sent. Rejects, with every engine stopped, if one fails or dies.
+ */
+export async function pool(jobs, { done, skip = () => false }) {
+  // biggest first, so the slowest image doesn't start last
+  const todo = [...jobs].sort((a, b) => b.peak - a.peak);
   const limit = budget();
   const lanes = Array.from({ length: Math.min(todo.length, MAX_WORKERS, Math.max(1, availableParallelism() - 1)) }, () => ({ worker: null, held: 0, busy: false }));
   const waiting = [];
@@ -93,16 +128,12 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
         continue;
       }
       const [job] = todo.splice(index, 1);
-      // the same bytes may have been marked as pngdeer's output since the batch started
-      if (read(dir, job.k)) {
-        counts.cached++;
-        continue;
-      }
+      if (skip(job)) continue;
       self.busy = true;
       self.held = Math.max(self.held, job.peak);
-      self.worker ??= new Worker(new URL("./worker.js", import.meta.url), { workerData: { target } });
+      self.worker ??= new Worker(new URL("./worker.js", import.meta.url));
       try {
-        record(job, await ask(self.worker, { file: job.file }));
+        done(job, await ask(self.worker, job.message));
         if (job.peak > BIG) {
           await self.worker.terminate();
           self.worker = null;
@@ -114,7 +145,6 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
         for (const l of lanes) l.worker?.terminate();
       } finally {
         self.busy = false;
-        progress(counts.computed + counts.failed, total);
         wake();
       }
     }
@@ -125,7 +155,37 @@ export async function fill({ cwd, target, files }, progress = () => {}) {
     await Promise.all(lanes.map((l) => l.worker?.terminate()));
   }
   if (failure) throw failure;
-  return { ...counts, ms: Math.round(performance.now() - start) };
+}
+
+/**
+ * Waits until no other batch measures for this project, then holds that until `release()`: ESLint's
+ * --concurrency lints in several threads, and a command-line lint may start while an editor measures.
+ * Whoever waits then finds most images cached.
+ */
+async function lock(folder) {
+  const path = join(folder, "measuring.lock");
+  for (;;) {
+    try {
+      mkdirSync(path);
+      return () => rmSync(path, { recursive: true, force: true });
+    } catch (error) {
+      // a folder where nothing can be locked: measure anyway
+      if (error.code !== "EEXIST") return () => {};
+    }
+    try {
+      if (Date.now() - statSync(path).mtimeMs > STALE_MS) rmSync(path, { recursive: true, force: true });
+    } catch {
+      // released meanwhile
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+/** An engine's expected peak memory for an image (by its header), for the pool's budget. */
+export function peakOf(bytes) {
+  const type = kind(bytes);
+  const [width, height, frames] = type ? dimensions(bytes, type) : [0, 0, 1];
+  return peak(width * height * frames);
 }
 
 /** An engine's expected peak memory for an image of this many pixels (over all its frames). */
@@ -157,7 +217,7 @@ function ask(worker, message) {
   });
 }
 
-// `node src/batch.js` with { cwd, target, files } as JSON on stdin, for trying it outside a linter
+// `node src/batch.js` with { dir, target, files } as JSON on stdin (dir: the cache folder), for trying it outside a linter
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
   const request = JSON.parse(readFileSync(0, "utf8"));
   process.stdout.write(JSON.stringify(await fill(request)));

package/src/cache.js

@@ -2,10 +2,13 @@
 // 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.
 export const ENGINE = createHash("sha256")
@@ -38,6 +41,15 @@ export function read(dir, k) {
   }
 }
 
+/** The entry for `k` in the first of `dirs` that has one, or null. */
+export function readFirst(k, ...dirs) {
+  for (const dir of new Set(dirs)) {
+    const entry = read(dir, k);
+    if (entry) return entry;
+  }
+  return null;
+}
+
 /** 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;
@@ -45,10 +57,26 @@ export function reportable(entry, { minSavedBytes, minSavedPercent }) {
   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
+  // written whole and renamed, so a reader never sees half an entry; formatted the way Prettier
+  // would, so a committed cache folder passes `prettier --check`
   const tmp = join(dir, `${k}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
-  writeFileSync(tmp, JSON.stringify(entry));
+  writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`);
   renameSync(tmp, join(dir, `${k}.json`));
 }

package/src/index.d.ts

@@ -14,8 +14,10 @@ export interface CompressibleImageOptions {
 export interface PngdeerSettings {
   /** Folders where "/x.png" paths are looked up. Default ["public", "static"]. */
   publicDirs?: string[];
-  /** Path prefixes and the folders they stand for. Default { "@/": "src/", "~/": "src/" }. */
+  /** Path prefixes and the folders they stand for. Default: the project's tsconfig/jsconfig paths, else { "@/": "src/", "~/": "src/" }. */
   aliases?: Record<string, string>;
+  /** Where results are kept, relative to the project root: a folder you can commit. Default node_modules/.cache/pngdeer. */
+  cacheDir?: string;
 }
 
 // Shaped like an ESLint plugin, so `plugins: { pngdeer }` type-checks in eslint.config.ts and

package/src/rule.js

@@ -1,12 +1,12 @@
 // 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 { statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { cacheDir, key, read, reportable } from "./cache.js";
-import { marked } from "./marker.js";
+import { cacheDir, fileKey, readFirst, reportable } from "./cache.js";
 import { projectImages } from "./scan.js";
-import { flag, name, summarize, watch } from "./summary.js";
+import { flag, name, share, summarize, watch } from "./summary.js";
+import { configAliases } from "./tsconfig.js";
 import { fillInBackground, fillSync } from "./sync.js";
 import { count, looks, pathFrom, quote, size, smaller } from "./text.js";
 
@@ -14,23 +14,27 @@ 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" };
+// when neither the settings nor the project's tsconfig/jsconfig define aliases
+const ALIASES = { "@/": "src/", "~/": "src/" };
 
 // Editors lint on every keystroke, so there the rule measures in the background and reports on a
 // later lint. Everywhere else it waits: a one-off run (the oxlint or eslint command, or a tool calling
 // ESLint's Node API, like Nx or xo) would exit before a background batch finished. Neither linter
-// has an API for this: it's how oxlint's language server (--lsp) and ESLint's (the one VS Code, Zed
-// and Neovim use, an Electron child in VS Code) start.
+// has an API for this: it's how oxlint's language server (--lsp), ESLint's (the one VS Code, Zed
+// and Neovim use, an Electron child in VS Code) and the eslint_d daemon that editors call start.
 const EDITOR =
   process.argv.includes("--lsp") ||
-  /eslintServer|language-?server|languageService/i.test(process.argv[1] ?? "") ||
+  /eslintServer|language-?server|languageService|eslint_d/i.test(process.argv[1] ?? "") ||
   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 scanned = new Set(); // `${root}\0${dir}\0${target}` whose project 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
+// outside editors: `${image}\0${target}` -> the linted file that got the image's full warning; other
+// files get a short one. A file linted again (eslint --fix passes, watch modes) keeps its full one.
+const warned = new Map();
 
 export default {
   meta: {
@@ -42,6 +46,8 @@ export default {
     },
     messages: {
       compressible: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}) and look {{looks}} (quality {{quality}}/100). Run: {{command}}",
+      // the same image again, in another file of the same run: its first warning said the rest
+      again: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}), as warned where it's first used. Run: {{command}}",
       lossless: "{{name}} could be {{percent}}% smaller ({{before}} → {{after}}), losslessly. Run: {{command}}",
     },
     schema: [
@@ -64,11 +70,18 @@ export default {
   create(context) {
     const { minSavedBytes, minSavedPercent, target: option, measure } = { ...DEFAULTS, ...context.options[0] };
     const target = option === "auto" ? undefined : option;
-    const { publicDirs = ["public", "static"], aliases = { "@/": "src/", "~/": "src/" } } = context.settings.pngdeer ?? {};
+    const settings = context.settings.pngdeer ?? {};
     const from = context.physicalFilename ?? context.filename;
     // public dirs, aliases and the cache belong to the package, wherever the linter was started
     const root = projectRoot(dirname(from), context.cwd);
-    const dir = cacheDir(root);
+    const { publicDirs = ["public", "static"] } = settings;
+    const aliases = settings.aliases ?? configAliases(root) ?? ALIASES;
+    // a folder the team commits (settings.pngdeer.cacheDir) keeps CI and fresh clones warm
+    const local = cacheDir(root);
+    const dir = settings.cacheDir ? resolve(root, settings.cacheDir) : local;
+    // pngdeer failing on an image is kept in `local` only: the failure may be this machine's alone
+    // (out of memory), and in a committed folder it would stick for the whole team
+    const lookup = (k) => readFirst(k, dir, local);
     const find = (path) => locate(path, from, root, publicDirs, aliases);
     // a path as the person running the linter would type it
     const shown = (file) => pathFrom(context.cwd, file);
@@ -77,7 +90,7 @@ export default {
 
     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 });
+    if (!EDITOR) watch(root, { minSavedBytes, minSavedPercent, target, dir });
 
     function check(node, text) {
       for (const { file, part } of imagesIn(text, find)) {
@@ -102,17 +115,20 @@ export default {
       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);
+      disabled ??= disabledLines(context.sourceCode, context.id ?? RULE);
       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 });
+      if (!EDITOR) flag(file, from, { 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}`}`;
+      const seen = `${file}\0${target}`;
+      if (!EDITOR && !warned.has(seen)) warned.set(seen, from);
+      const repeat = !EDITOR && warned.get(seen) !== from;
       context.report({
         node,
         loc: loc ?? undefined,
-        messageId: result.outcome === "hit" ? "compressible" : "lossless",
+        messageId: repeat ? "again" : result.outcome === "hit" ? "compressible" : "lossless",
         data: {
           name: basename(file),
           percent: smaller(result.original, result.compressed),
@@ -139,37 +155,45 @@ 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);
-          if (!wait) fillInBackground({ cwd: root, target, files });
+        const group = `${root}\0${dir}\0${target}`;
+        const first = measure !== "never" && !scanned.has(group);
+        if (found.length === 0 && !first) {
+          if (!EDITOR) share();
+          return;
+        }
+        scanned.add(group);
+        // what the engine has yet to measure: pngdeer's own output (marked) needs none, and gets no entry,
+        // so the editor and the command line leave the same files in a cache folder someone commits
+        const unmeasured = (file) => {
+          const image = fileKey(file, target);
+          return image && !image.marked && !lookup(image.key);
+        };
+        const named = measure === "never" ? [] : found.map(({ file }) => file);
+        const files = [...new Set(first ? [...named, ...projectImages(root, minSavedBytes)] : named)].filter(unmeasured);
+        if (files.length) {
+          if (!wait) fillInBackground({ dir, failures: local, target, files });
           else if (!failed.has(root)) measureNow(files);
         }
         for (const ref of found) {
-          const result = read(dir, ref.k);
+          const result = lookup(ref.k);
           tell(ref.file, result);
           report(ref, result);
         }
+        if (!EDITOR) share();
       },
     };
 
+    /** Measures `files` (none cached yet) while the lint waits, saying what the wait is for. */
     function measureNow(files) {
-      // how many need the engine, to say what the wait is for (the hashes are kept for later lookups)
-      const fresh = files.filter((file) => {
-        const image = fileKey(file, target);
-        return image && !image.marked && !read(dir, image.key);
-      }).length;
       // 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"}`);
+      const tty = Boolean(process.stderr.isTTY);
+      process.stderr.write(`pngdeer: measuring ${count(files.length, "image")} not in the cache yet...${tty ? "" : "\n"}`);
       try {
-        const { computed, ms } = fillSync({ cwd: root, target, files, progress: tty });
+        const { computed, ms } = fillSync({ dir, failures: local, 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) {
@@ -206,9 +230,10 @@ function imagesIn(text, find) {
 
 /**
  * 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.
+ * `-disable-line` on it, or a `-disable` block around it, for this rule (`id`, as the config names
+ * the plugin) or for all rules.
  */
-function disabledLines(source) {
+function disabledLines(source, id) {
   const lines = new Set();
   const blocks = [];
   let open = null;
@@ -217,7 +242,7 @@ function disabledLines(source) {
     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 (rules.length && !rules.includes(id) && !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;
@@ -252,21 +277,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/shrink.js

@@ -0,0 +1,63 @@
+// Making one image smaller on disk: what the command does to each image it's given, in its own
+// thread for one image or on the pool's engines for several (worker.js).
+import { chmodSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { compress } from "./engine.js";
+import { unsupported } from "./images.js";
+import { mark, marked } from "./marker.js";
+import { looks, size, smaller } from "./text.js";
+
+/**
+ * Writes `input` made smaller to `output`, marked as pngdeer's: { text } saying what happened, plus
+ * { original, written } sizes when it wrote a smaller file. Throws when it can't read or compress.
+ */
+export function shrink(input, output, target) {
+  const bytes = readFileSync(input);
+  const unchanged = (note) => {
+    if (output !== input) save(output, bytes);
+    return { text: `${note}; left as is` };
+  };
+  if (marked(bytes)) return unchanged("already pngdeer's");
+  const why = unsupported(bytes);
+  if (why) throw new Error(why);
+
+  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 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 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 };
+}
+
+/** An error as one line a person can act on. */
+export function plain(error) {
+  if (error?.code === "ENOENT") return "no such file";
+  if (error?.code === "EACCES" || error?.code === "EPERM") return "permission denied";
+  if (error?.code === "EISDIR") return "a folder, not an image";
+  return String(error?.message ?? error);
+}
+
+/** Writes a whole new file or nothing: the image is often written over itself. */
+function save(path, bytes) {
+  // unique per writer: the pool's engines share the process, and one image may come twice
+  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    writeFileSync(tmp, bytes);
+    try {
+      chmodSync(tmp, statSync(path).mode & 0o7777);
+    } catch {
+      // a new file keeps the default mode
+    }
+    renameSync(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    if (error.code === "ENOENT") throw new Error(`can't write ${path}: its folder doesn't exist`);
+    throw error;
+  }
+}

package/src/summary.js

@@ -1,26 +1,35 @@
 // 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";
+// 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, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isMainThread, threadId } from "node:worker_threads";
+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 flagged = new Map(); // image path -> { original, compressed, score, target, files: the linted files warning about it }
 const named = new Set(); // every image linted code names, flagged or not
 const roots = new Map(); // project root -> the rule's options there
+const SHARE_HOURS = 1; // a thread's share older than this was left by a run that died
 
-/** Notes an image a warning was reported for. */
-export function flag(file, entry) {
-  flagged.set(file, entry);
+/** Notes an image a warning in linted file `from` was reported for: one warning per file, however often it's linted. */
+export function flag(file, from, entry) {
+  const files = flagged.get(file)?.files ?? new Set();
+  flagged.set(file, { ...entry, files: files.add(from) });
 }
 
 /** Notes an image linted code names. */
@@ -47,8 +56,58 @@ export function readFlagged(cwd) {
   }
 }
 
-/** Prints the table on stderr and leaves the list in `cwd`; once, as the lint exits. */
+/**
+ * ESLint's --concurrency lints in worker threads, each with its own copy of this module: each leaves
+ * what it saw for the main thread, after every file it lints (a thread may be stopped without warning),
+ * and only the main thread prints. oxlint runs every rule on its main thread.
+ */
+export function share(cwd = process.cwd()) {
+  if (isMainThread || roots.size === 0) return;
+  try {
+    const dir = join(cacheDir(cwd), "threads");
+    mkdirSync(dir, { recursive: true });
+    const state = { flagged: [...flagged].map(([file, entry]) => [file, { ...entry, files: [...entry.files] }]), named: [...named], roots: [...roots] };
+    writeFileSync(join(dir, `${process.pid}-${threadId}.json`), JSON.stringify(state));
+  } catch {
+    // that thread's images go untold
+  }
+}
+
+/** Takes in what this process's lint threads left, and drops shares a dead run left behind. */
+function gather(cwd) {
+  const dir = join(cacheDir(cwd), "threads");
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const path = join(dir, name);
+    try {
+      if (name.startsWith(`${process.pid}-`)) {
+        const state = JSON.parse(readFileSync(path, "utf8"));
+        for (const [file, entry] of state.flagged) {
+          const files = new Set([...(flagged.get(file)?.files ?? []), ...entry.files]);
+          flagged.set(file, { ...entry, files });
+        }
+        for (const file of state.named) named.add(file);
+        for (const [root, options] of state.roots) roots.set(root, options);
+      } else if (Date.now() - statSync(path).mtimeMs < SHARE_HOURS * 3600e3) continue;
+      rmSync(path, { force: true });
+    } catch {
+      // a share half written or already gone
+    }
+  }
+}
+
+/** Prints the table on stderr and leaves the list in `cwd`; once, as the lint exits, on the main thread. */
 export function summarize(cwd = process.cwd()) {
+  if (!isMainThread) return;
+  gather(cwd);
+  // a process that linted nothing (ESLint's main thread, when worker threads did the linting and
+  // left nothing) has nothing to say, and mustn't empty the list the last lint left
+  if (roots.size === 0) return;
   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
@@ -64,11 +123,19 @@ export function summarize(cwd = process.cwd()) {
 
   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 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 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);
@@ -77,14 +144,19 @@ export function summarize(cwd = process.cwd()) {
   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], " "));
+    // an image named in many files warns in each: say so, or the counts look wrong
+    const warnings = images.reduce((sum, [, image]) => sum + image.files.size, 0);
+    const often = warnings > images.length ? ` (${count(warnings, "warning")})` : "";
+    lines.push(`pngdeer: ${count(images.length, "flagged image")}${often} 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);
-    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], " "));
+    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")}`);
   }
@@ -92,28 +164,50 @@ export function summarize(cwd = process.cwd()) {
   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]], biggest saving first. Reads only results already cached.
+ * 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;
-      let entry;
+      const image = fileKey(file, options.target);
+      const entry = image && read(options.dir, 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 {
-        entry = read(cacheDir(root), key(readFileSync(file), options.target));
+        return [{ path, text: readFileSync(path, "utf8") }];
       } catch {
-        continue;
+        return [];
       }
-      if (reportable(entry, options)) found.push([file, entry]);
-    }
+    }));
   }
-  return found.sort(([, a], [, b]) => b.original - b.compressed - (a.original - a.compressed));
+  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`. */

package/src/sync.js

@@ -31,10 +31,10 @@ export function fillSync(request) {
 
 // The editor's background batches: one at a time per process, whatever arrives meanwhile goes in
 // the next one, so fill()'s pool and memory budget hold for the whole language server. Files are
-// keyed by project and target, as a batch has one of each.
-const queued = new Map(); // `${cwd}\0${target}` -> { cwd, target, files: Set }
-const pending = new Set(); // `${cwd}\0${target}\0${file}`, queued or being measured
-const failedAt = new Map(); // `${cwd}\0${target}` -> when its last batch failed
+// keyed by cache folder and target, as a batch has one of each.
+const queued = new Map(); // `${dir}\0${target}` -> { dir, target, files: Set }
+const pending = new Set(); // `${dir}\0${target}\0${file}`, queued or being measured
+const failedAt = new Map(); // `${dir}\0${target}` -> when its last batch failed
 const RETRY_MS = 5 * 60 * 1000;
 let running = false;
 
@@ -57,10 +57,10 @@ function drain() {
 }
 
 /** fill(request) in the background, for the editor: nothing waits, nothing is reported late. */
-export function fillInBackground({ cwd, target, files }) {
-  const group = `${cwd}\0${target}`;
+export function fillInBackground({ dir, failures, target, files }) {
+  const group = `${dir}\0${target}`;
   if (Date.now() - (failedAt.get(group) ?? -Infinity) < RETRY_MS) return;
-  const batch = queued.get(group) ?? { cwd, target, files: new Set() };
+  const batch = queued.get(group) ?? { dir, failures, target, files: new Set() };
   for (const file of files) {
     if (pending.has(`${group}\0${file}`)) continue;
     pending.add(`${group}\0${file}`);

package/src/tsconfig.js

@@ -0,0 +1,132 @@
+// Path aliases a project defines in tsconfig.json or jsconfig.json (compilerOptions.paths), resolved
+// the way TypeScript does, so "@/assets/hero.png" finds the file the build would: `extends` (later
+// entries win, ".json" optional), `paths` and `baseUrl` each from the nearest config that sets them
+// (`null` unsets), targets relative to `baseUrl` or else to the config that set `paths`, and
+// `${configDir}` as the folder of the config being resolved. A config without paths falls back to
+// its `references` (Vite keeps them in tsconfig.app.json). Configs from packages are skipped: they
+// don't point into the project.
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const found = new Map(); // project root -> { aliases, seen: Map(config path -> mtime, or -1 if missing) }
+const told = new Set(); // configs that couldn't be read, already said so
+
+/** { "@/": "src/" }-style aliases from the project's config, as folders relative to `root`; null if none. */
+export function configAliases(root) {
+  const memo = found.get(root);
+  // a config edited since (an editor runs for hours; .svelte-kit and .nuxt regenerate theirs)
+  if (memo && [...memo.seen].every(([file, mtime]) => mtimeOf(file) === mtime)) return memo.aliases;
+  const seen = new Map();
+  let aliases = null;
+  try {
+    aliases = projectAliases(root, seen);
+  } catch {
+    // whatever a config holds, the rule goes on with the default aliases
+  }
+  found.set(root, { aliases, seen });
+  return aliases;
+}
+
+/** The aliases of the project's tsconfig.json (or jsconfig.json, without one), or of its references. */
+function projectAliases(root, seen) {
+  const tsconfig = join(root, "tsconfig.json");
+  const leaf = mtimeOf(tsconfig) >= 0 ? tsconfig : join(root, "jsconfig.json");
+  const options = effective(leaf, dirname(leaf), seen, new Set());
+  if (options?.paths !== undefined) return aliasesOf(options, root, dirname(leaf));
+  for (const reference of load(leaf, seen)?.references ?? []) {
+    if (typeof reference?.path !== "string") continue;
+    const file = configFile(resolve(dirname(leaf), reference.path));
+    if (!file) continue;
+    const referenced = effective(file, dirname(file), seen, new Set());
+    if (referenced?.paths !== undefined) return aliasesOf(referenced, root, dirname(file));
+  }
+  return null;
+}
+
+/**
+ * A config's `paths` (with `pathsDir`, the folder of the config that set them) and `baseUrl` (a
+ * folder), after its `extends`; a key is present only if some config in the chain set it.
+ */
+function effective(file, configDir, seen, chain) {
+  if (chain.has(file)) return {};
+  chain.add(file);
+  const config = load(file, seen);
+  if (!config) return null;
+  let options = {};
+  const extended = typeof config.extends === "string" ? [config.extends] : Array.isArray(config.extends) ? config.extends : [];
+  for (const spec of extended) {
+    const base = typeof spec === "string" && (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("${configDir}")) ? configFile(resolve(dirname(file), expand(spec, configDir))) : null;
+    if (base) options = { ...options, ...effective(base, configDir, seen, chain) };
+  }
+  const own = config.compilerOptions ?? {};
+  if ("baseUrl" in own) options.baseUrl = typeof own.baseUrl === "string" ? resolve(dirname(file), expand(own.baseUrl, configDir)) : undefined;
+  if ("paths" in own) {
+    options.paths = own.paths && typeof own.paths === "object" ? own.paths : null;
+    options.pathsDir = dirname(file);
+  }
+  return options;
+}
+
+/** Folder aliases from effective options; null when none is a folder pattern ("@/*": ["./src/*"]). */
+function aliasesOf({ paths, pathsDir, baseUrl }, root, configDir) {
+  const aliases = {};
+  for (const [pattern, targets] of Object.entries(paths ?? {})) {
+    const target = Array.isArray(targets) ? targets.find((t) => typeof t === "string") : undefined;
+    // a bare "*" would match every path
+    if (pattern === "*" || !pattern.endsWith("*") || !target?.endsWith("*")) continue;
+    const folder = relative(root, resolve(baseUrl ?? pathsDir, expand(target, configDir).slice(0, -1))).split(sep).join("/");
+    aliases[pattern.slice(0, -1)] = folder ? `${folder}/` : "";
+  }
+  return Object.keys(aliases).length ? aliases : null;
+}
+
+/** A config's contents, or null if it doesn't exist; a config that can't be parsed is named on stderr once. */
+function load(file, seen) {
+  seen.set(file, mtimeOf(file));
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return parse(text);
+  } catch (error) {
+    if (!told.has(file)) {
+      told.add(file);
+      process.stderr.write(`pngdeer: couldn't read path aliases from ${file}: ${error.message}\n`);
+    }
+    return null;
+  }
+}
+
+/** The config file a path in `extends` or `references` names: as is, with ".json", or a folder's tsconfig.json. */
+function configFile(path) {
+  for (const file of [path, `${path}.json`, join(path, "tsconfig.json")]) {
+    try {
+      if (statSync(file).isFile()) return file;
+    } catch {
+      // not this one
+    }
+  }
+  return null;
+}
+
+/** JSON with a BOM, comments and trailing commas, as tsconfig files are written. */
+function parse(text) {
+  const bare = text.replace(/^\uFEFF/, "").replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (match) => (match.startsWith('"') ? match : ""));
+  return JSON.parse(bare.replace(/,(\s*[}\]])/g, "$1"));
+}
+
+/** TypeScript 5.5's ${configDir}: the folder of the config being resolved, not of the one that says it. */
+function expand(path, configDir) {
+  return path.replace(/^\$\{configDir\}/, configDir);
+}
+
+function mtimeOf(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return -1;
+  }
+}

package/src/worker.js

@@ -1,31 +1,41 @@
-// One pngdeer engine per worker thread: compresses the files it's sent and reports sizes, the cache
-// key of the bytes it actually read (the file may have changed since it was queued), and the key of
-// its own output, so that file is recognized later if someone writes it to disk.
+// One pngdeer engine per worker thread, doing what it's sent: { file, target } measures a file and
+// reports sizes, the cache key of the bytes it actually read (the file may have changed since it was
+// queued), and the key of its own output, so that file is recognized later if someone writes it to
+// disk; { file, target, out } makes the file smaller on disk, as the command does (shrink.js).
 import { readFileSync } from "node:fs";
-import { parentPort, workerData } from "node:worker_threads";
+import { parentPort } from "node:worker_threads";
 import { key } from "./cache.js";
 import { compress } from "./engine.js";
 import { mark } from "./marker.js";
+import { plain, shrink } from "./shrink.js";
 
-const why = (error) => String(error?.message ?? error);
-
-parentPort.on("message", ({ file }) => {
+parentPort.on("message", ({ file, target, out }) => {
+  if (out !== undefined) {
+    let reply;
+    try {
+      reply = shrink(file, out, target);
+    } catch (error) {
+      reply = { error: plain(error) };
+    }
+    parentPort.postMessage(reply);
+    return;
+  }
   const start = performance.now();
   let bytes;
   try {
     bytes = readFileSync(file);
   } catch (error) {
-    parentPort.postMessage({ input: null, error: why(error) });
+    parentPort.postMessage({ input: null, error: plain(error) });
     return;
   }
-  const input = key(bytes, workerData.target);
+  const input = key(bytes, target);
   try {
-    const { output, outcome, score } = compress(bytes, workerData.target);
+    const { output, outcome, score } = compress(bytes, target);
     const ms = Math.round(performance.now() - start);
     // 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) });
+    parentPort.postMessage({ input, original: bytes.length, compressed, outcome, score, ms, output: key(output, target) });
   } catch (error) {
-    parentPort.postMessage({ input, error: why(error) });
+    parentPort.postMessage({ input, error: plain(error) });
   }
 });