fix: probe images with a real decode before optimizing (#394)

The header-sniffing guard from #393 was not enough: the same garden
failed again on a *truncated AVIF* renamed to .jpg. Its ftypavif header
passes the magic-byte check, but sharp fails mid-decode ("bad seek"),
and eleventy-img leaves internal per-format promise rejections
permanently unhandled on decode failure — Eleventy's unhandledRejection
handler then fails the build, regardless of the .catch we attach to the
returned promise (verified empirically with the reporting garden's
actual file).

A valid header can never prove a decodable bitstream, so the picture
transform now awaits isDecodableImage: header sniff as a cheap first
filter, then an actual sharp decode (stats()), memoized per file
mtime+size so each unique image is probed once per build. The probe
resolves sharp through eleventy-img's own module resolution, so the
answer always agrees with what the pipeline can do. Undecodable files
keep their original <img> tag and log a warning naming the file.

Fixture: a tiny AVIF truncated to 60%, which reproduces the exact
"bad seek" failure in tests.


Claude-Session: https://claude.ai/code/session_01TFUucReuWzHi8VCKMovneB

Co-authored-by: Ole Eskild Steensen <6201338+oleeskild@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: oleeskild

.eleventy.js

@@ -34,7 +34,7 @@ const {
 const { basesPlugin } = require("./src/helpers/basesPlugin");
 
 const Image = require("@11ty/eleventy-img");
-const { isTransformableImage } = require("./src/helpers/imageFormat.js");
+const { isDecodableImage } = require("./src/helpers/imageFormat.js");
 function transformImage(src, cls, alt, sizes, widths = ["500", "700", "auto"]) {
   let options = {
     widths: widths,
@@ -552,7 +552,7 @@ module.exports = function(eleventyConfig) {
   }
 
 
-  eleventyConfig.addTransform("picture", function(str) {
+  eleventyConfig.addTransform("picture", async function(str) {
     if (!isMarkdownPage(this.page.inputPath)) {
       return str;
     }
@@ -563,10 +563,13 @@ module.exports = function(eleventyConfig) {
     for (const imageTag of parsed.querySelectorAll(".cm-s-obsidian img")) {
       const src = imageTag.getAttribute("src");
       if (src && src.startsWith("/") && !src.endsWith(".svg")) {
-        // Files whose content sharp can't decode (e.g. HEIC renamed to
-        // .jpg) keep their original <img> tag instead of a <picture>
-        // pointing at optimized files that will never exist.
-        if (!isTransformableImage("./src/site" + decodeURI(src))) {
+        // Files sharp can't decode (e.g. HEIC or a truncated AVIF renamed
+        // to .jpg) keep their original <img> tag instead of a <picture>
+        // pointing at optimized files that will never exist. This must be
+        // a real decode probe, not just a header check: feeding an
+        // undecodable file to eleventy-img fails the whole build via
+        // unhandled promise rejections in its internals.
+        if (!(await isDecodableImage("./src/site" + decodeURI(src)))) {
           continue;
         }
         const cls = imageTag.classList.value;

src/helpers/__fixtures__/truncated.avif.jpg

@@ -1,4 +1,14 @@
 const fs = require("fs");
+const { createRequire } = require("module");
+
+// Use the exact sharp instance eleventy-img uses, so "can we decode this?"
+// always agrees with what the optimization pipeline can actually do.
+let sharp;
+try {
+	sharp = createRequire(require.resolve("@11ty/eleventy-img"))("sharp");
+} catch {
+	sharp = require("sharp");
+}
 
 /**
  * Check whether a file's actual content is an image format the sharp-based
@@ -55,4 +65,54 @@ function isTransformableImage(filePath) {
 	return false;
 }
 
-module.exports = { isTransformableImage };
+// Probe results memoized per file version — decoding is the expensive part
+// and the same image is typically referenced from many pages.
+const decodableCache = new Map();
+
+/**
+ * Check whether sharp can actually decode a file, by decoding it.
+ *
+ * Header sniffing (isTransformableImage) is a fast first filter, but a
+ * valid header proves nothing about the bitstream: a truncated AVIF still
+ * says "ftypavif" yet fails mid-decode, and eleventy-img leaves internal
+ * promise rejections unhandled on decode failure, which kills the whole
+ * Eleventy build. Only files that pass a real decode may enter the
+ * optimization pipeline.
+ */
+async function isDecodableImage(filePath) {
+	if (!isTransformableImage(filePath)) {
+		return false;
+	}
+
+	let cacheKey;
+
+	try {
+		const stat = fs.statSync(filePath);
+		cacheKey = `${filePath}:${stat.mtimeMs}:${stat.size}`;
+	} catch {
+		return false;
+	}
+
+	if (decodableCache.has(cacheKey)) {
+		return decodableCache.get(cacheKey);
+	}
+
+	const probe = sharp(filePath)
+		.stats()
+		.then(
+			() => true,
+			(err) => {
+				console.warn(
+					`[image] ${filePath} cannot be decoded and will not be optimized: ${err.message.split("\n")[0]}`,
+				);
+
+				return false;
+			},
+		);
+
+	decodableCache.set(cacheKey, probe);
+
+	return probe;
+}
+
+module.exports = { isTransformableImage, isDecodableImage };

src/helpers/imageFormat.js

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest";
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { isTransformableImage } from "./imageFormat.js";
+import { isTransformableImage, isDecodableImage } from "./imageFormat.js";
 
 const writeTemp = (name, bytes) => {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "img-format-"));
@@ -57,3 +57,38 @@ describe("isTransformableImage", () => {
 		expect(isTransformableImage("/nonexistent/img.jpg")).toBe(false);
 	});
 });
+
+describe("isDecodableImage", () => {
+	it("rejects a truncated AVIF that passes header sniffing", async () => {
+		// Real-world case: a truncated AVIF renamed to .jpg has a valid
+		// ftypavif header but cannot be decoded ("bad seek to ...").
+		await expect(
+			isDecodableImage(
+				path.join(__dirname, "__fixtures__", "truncated.avif.jpg"),
+			),
+		).resolves.toBe(false);
+	});
+
+	it("accepts a real decodable image", async () => {
+		await expect(
+			isDecodableImage("src/site/img/tree-1.svg").then(Boolean),
+		).resolves.toBe(false); // svg is not in scope for the optimizer
+
+		await expect(
+			isDecodableImage("src/site/img/user/A Assets/travolta.png"),
+		).resolves.toBe(true);
+	});
+
+	it("rejects HEIC content without invoking a decode", async () => {
+		const heic = [0, 0, 0, 24, ...Buffer.from("ftypheic"), 0, 0, 0, 0];
+		await expect(
+			isDecodableImage(writeTemp("photo.jpg", heic)),
+		).resolves.toBe(false);
+	});
+
+	it("rejects a missing file", async () => {
+		await expect(isDecodableImage("/nonexistent/img.jpg")).resolves.toBe(
+			false,
+		);
+	});
+});