Backtestshugorun-20261002-200313#15267

Issue #15267 Merged fix PR # Run 2 Oct 2026 · run-20261002-200313 gohugoio/hugo

Bump fileCacheEntryVersion in transform.ToMath

Better

Our patch was judged better than the merged fix.

In this judgment, Patch B = our agent, Patch A = the merged fix.

Both patches make the same core fix: they bump fileCacheEntryVersion from "v1" to "v2" in transform.ToMath. Old cached KaTeX 0.16.21 output then sits under a different key and is no longer reused, which is the root cause in the issue. So both are equally correct.

B adds a comment next to katexVersion in internal/warpc/katex.go telling future upgraders to bump the cache version, and expands the inline comment on the constant. That small craft gain targets exactly how this bug happened (a KaTeX bump without a cache bump).

B also adds an integration test that seeds a stale v1 cache entry and asserts it isn't served. My confidence in this test is limited. Hugo may resolve `caches.misc.dir` as the cache root itself rather than `<dir>/filecache/misc`. If so, the seeded file would never be read, and the test could pass even without the fix. Still, the intent is right, and it adds no risk to production code.

The test's value is uncertain, but B carries the identical fix plus useful guidance to prevent a repeat, so it edges out A.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

27m 13s

Wall-clock time in the container

Full test suite

No new failures

3,754 passed · 99 skipped · 3,855 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

41vs 2 merged

Changed lines, ours vs merged

In ec52e638c we bumped KaTeX from 0.16.21 to 0.18.4. This produces different output.

I ran into this when testing the docs site, specifically the chem example.

The two patches

Our patch+40 −1
internal/warpc/katex.goindex 34fb4edb7..26f7ce068 100644@@ -18,6 +18,7 @@ import ( )  // Keep in sync with js/package.json.+// When upgrading, also bump fileCacheEntryVersion in transform.ToMath if the output changes. const katexVersion = "0.18.4"  //go:embed wasm/renderkatex.wasmtpl/transform/transform.goindex 5c99b322c..9f77c41cc 100644@@ -293,7 +293,7 @@ func (ns *Namespace) ToMath(ctx context.Context, args ...any) (template.HTML, er 		Warnings []string `json:"warnings,omitempty"` 	} -	const fileCacheEntryVersion = "v1" // Increment on incompatible changes.+	const fileCacheEntryVersion = "v2" // Increment on incompatible changes, including KaTeX upgrades that change the output.  	s := hashing.HashString(args...) 	key := "tomath/" + fileCacheEntryVersion + "/" + s[:2] + "/" + s[2:]tpl/transform/transform_integration_test.goindex 9109e6c3e..6d865f1da 100644@@ -15,10 +15,13 @@ package transform_test  import ( 	"fmt"+	"os"+	"path/filepath" 	"strings" 	"testing"  	qt "github.com/frankban/quicktest"+	"github.com/gohugoio/hugo/common/hashing" 	"github.com/gohugoio/hugo/hugolib" ) @@ -171,6 +174,41 @@ disableKinds = ['page','rss','section','sitemap','taxonomy','term'] 	`) } +// Entries in the file cache written by an older KaTeX version must not be reused.+func TestToMathFileCacheVersion(t *testing.T) {+	const expression = "c = \\pm\\sqrt{a^2 + b^2}"++	tempDir := t.TempDir()+	cacheDir := filepath.Join(tempDir, "cache")++	// Seed the file cache with an entry using the key format from before the KaTeX 0.18.4 upgrade.+	s := hashing.HashString(expression)+	staleFilename := filepath.Join(cacheDir, "filecache", "misc", "tomath", "v1", s[:2], s[2:])+	if err := os.MkdirAll(filepath.Dir(staleFilename), 0o777); err != nil {+		t.Fatal(err)+	}+	if err := os.WriteFile(staleFilename, []byte(`{"version":"v1","output":"STALE_KATEX_OUTPUT"}`+"\n"), 0o666); err != nil {+		t.Fatal(err)+	}++	files := `+-- hugo.toml --+disableKinds = ['page','rss','section','sitemap','taxonomy','term']+[caches.misc]+dir = 'CACHE_DIR'+-- layouts/home.html --+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}+  `+	files = strings.ReplaceAll(files, "CACHE_DIR", filepath.ToSlash(cacheDir))++	b := hugolib.Test(t, files, hugolib.TestOptWithConfig(func(cfg *hugolib.IntegrationTestConfig) {+		cfg.NeedsOsFS = true+		cfg.WorkingDir = tempDir+	}))++	b.AssertFileContent("public/index.html", "<span class=\"katex\"><math", "! STALE_KATEX_OUTPUT")+}+ func TestToMathError(t *testing.T) { 	t.Run("Default", func(t *testing.T) { 		files := ` 
Merged fix · PR #+1 −1
tpl/transform/transform.goindex 5c99b322c..f9d0dabb0 100644@@ -293,7 +293,7 @@ func (ns *Namespace) ToMath(ctx context.Context, args ...any) (template.HTML, er 		Warnings []string `json:"warnings,omitempty"` 	} -	const fileCacheEntryVersion = "v1" // Increment on incompatible changes.+	const fileCacheEntryVersion = "v2" // Increment on incompatible changes.  	s := hashing.HashString(args...) 	key := "tomath/" + fileCacheEntryVersion + "/" + s[:2] + "/" + s[2:]