oxlint-plugin-pngdeer 0.2.0 → 0.2.1

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.
+- **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.

package/package.json

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

package/src/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")
@@ -45,6 +48,21 @@ 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

package/src/rule.js

@@ -1,10 +1,9 @@
 // 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, read, reportable } from "./cache.js";
 import { projectImages } from "./scan.js";
 import { flag, name, summarize, watch } from "./summary.js";
 import { fillInBackground, fillSync } from "./sync.js";
@@ -26,7 +25,6 @@ const EDITOR =
   process.env.ELECTRON_RUN_AS_NODE === "1";
 
 // Per process (the language server's lasts the whole editor session):
-const keys = new Map(); // image path -> { size, mtimeMs, target, key, marked }, so images aren't re-read on every keystroke
 const roots = new Map(); // directory -> its project root
 const scanned = new Set(); // `${root}\0${target}` whose images were all measured, or queued, once
 const failed = new Set(); // outside editors: roots whose batch failed, not tried again this run
@@ -139,15 +137,17 @@ export default {
       TemplateLiteral(node) {
         if (node.expressions.length === 0) check(node, node.quasis[0].value.cooked ?? "");
       },
-      // What this file names is measured, then reported. The first time, every image in the
-      // project goes in the same parallel batch, so the files linted next find theirs cached.
+      // What this file names is measured, then reported. The first file of a project in a run also
+      // takes every image in it, named or not, in the same parallel batch: the files linted next find
+      // theirs cached, and the summary can tell about images only CSS or HTML use.
       "Program:exit"() {
-        if (found.length === 0) return;
-        const missing = measure === "never" ? [] : [...new Set(found.filter(({ k }) => !read(dir, k)).map(({ file }) => file))];
-        if (missing.length) {
-          const group = `${root}\0${target}`;
-          const files = scanned.has(group) ? missing : [...new Set([...missing, ...projectImages(root, minSavedBytes)])];
-          scanned.add(group);
+        const group = `${root}\0${target}`;
+        const first = measure !== "never" && !scanned.has(group);
+        if (found.length === 0 && !first) return;
+        scanned.add(group);
+        const missing = measure === "never" ? [] : found.filter(({ k }) => !read(dir, k)).map(({ file }) => file);
+        const files = [...new Set(first ? [...missing, ...projectImages(root, minSavedBytes)] : missing)];
+        if (files.length) {
           if (!wait) fillInBackground({ cwd: root, target, files });
           else if (!failed.has(root)) measureNow(files);
         }
@@ -165,9 +165,11 @@ export default {
         const image = fileKey(file, target);
         return image && !image.marked && !read(dir, image.key);
       }).length;
+      // everything cached (or pngdeer's own output, which needs no engine): nothing to wait for
+      if (!fresh) return;
       // on a terminal the batch rewrites this line as a count (fill-worker.js), and it's cleared after
-      const tty = Boolean(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(fresh, "image")} not in the cache yet...${tty ? "" : "\n"}`);
       try {
         const { computed, ms } = fillSync({ cwd: root, target, files, progress: tty });
         if (tty) process.stderr.write("\r\x1b[K");
@@ -252,21 +254,6 @@ function projectRoot(dir, fallback) {
   return roots.get(dir);
 }
 
-/** An image's size, the cache key of its current bytes and whether pngdeer wrote it; null if it can't be read. */
-function fileKey(file, target) {
-  try {
-    const { size, mtimeMs } = statSync(file);
-    const memo = keys.get(file);
-    if (memo && memo.size === size && memo.mtimeMs === mtimeMs && memo.target === target) return memo;
-    const bytes = readFileSync(file);
-    const image = { size, mtimeMs, target, key: key(bytes, target), marked: marked(bytes) };
-    keys.set(file, image);
-    return image;
-  } catch {
-    return null;
-  }
-}
-
 function isFile(path) {
   try {
     return statSync(path).isFile();

package/src/scan.js

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

package/src/summary.js

@@ -1,18 +1,24 @@
 // 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.
+// The table also lists images the run measured that no linted JS or TS names, which no warning can
+// point at, each with where it is used instead (a stylesheet, a page, a template), if anywhere.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { 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";
+import { basename, dirname, join } from "node:path";
+import { cacheDir, fileKey, read, reportable } from "./cache.js";
+import { projectFiles, projectImages } from "./scan.js";
+import { count, pathFrom, quote, size, smaller } from "./text.js";
 
 // Rows shown per table; the rest are counted, and --flagged still takes them all.
 const ROWS = 10;
 const UNNAMED_ROWS = 5;
 // Formats other programs read: the table on stderr would only get in the way.
 const MACHINE = new Set(["json", "json-with-metadata", "checkstyle", "junit", "sarif", "gitlab"]);
+// Files the linter doesn't read but that use images, most telling first: styles, pages and
+// templates, then content and data. Markdown comes last, and only "mentions" an image: a README
+// that names one may just be describing it.
+const PAGES = [".css", ".scss", ".sass", ".less", ".styl", ".html", ".htm", ".vue", ".svelte", ".astro", ".mdx", ".json", ".yml", ".yaml"];
+const DOCS = [".md"];
+const PAGE_BYTES = 1e6; // bigger ones are build output or lockfiles, not where people name images
 
 const flagged = new Map(); // image path -> { original, compressed, score, target }
 const named = new Set(); // every image linted code names, flagged or not
@@ -64,11 +70,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 +91,16 @@ 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], " "));
+    lines.push(`pngdeer: ${count(images.length, "flagged image")} could be ${saved} smaller in all (${detail}):`, line(header, " "));
     lines.push(...rows.slice(1, 1 + Math.min(images.length, ROWS)).map((cells) => line(cells)));
     if (images.length > ROWS) lines.push(`  …and ${count(images.length - ROWS, "more image")}, ${total(images.slice(ROWS)).saved} in all`);
   }
   if (unnamed.length) {
+    // no warning can point at these: their only mention is in CSS, HTML and the like, or nowhere
     const { saved } = total(unnamed);
-    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 +108,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(cacheDir(root), image.key);
+      if (reportable(entry, options)) found.push([file, entry, root]);
+    }
+  }
+  return found.sort(([, a], [, b]) => b.original - b.compressed - (a.original - a.compressed));
+}
+
+const pages = new Map(); // project root -> [{ path, text }] of its PAGES, then its DOCS, read once
+
+/** The most telling file the linter doesn't read (a stylesheet, a template, a doc) that names `image`; or null. */
+function namedIn(root, image) {
+  if (!pages.has(root)) {
+    const files = [...PAGES, ...DOCS].flatMap((extension) => projectFiles(root, [extension], 0, PAGE_BYTES));
+    pages.set(root, files.flatMap((path) => {
       try {
-        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`. */