Backtestshugorun-20261005-133023#15267

Issue #15267 Merged fix PR # Run 5 Oct 2026 · run-20261005-133023 gohugoio/hugo

Bump fileCacheEntryVersion in transform.ToMath

Better

Our patch was judged better than the merged fix.

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

Both patches make the same core fix: they bump `fileCacheEntryVersion` from "v1" to "v2" in `transform.ToMath`. This invalidates file cache entries rendered by the older KaTeX, which resolves the issue at its root. On correctness they are equal. The difference is in testing. Patch A adds an integration test that seeds a stale v1 cache entry at the path the old key scheme would use (`filecache/misc/tomath/v1/...`), with sentinel output `STALE_KATEX_OUTPUT`. It then builds a site with a `\ce{...}` chem expression, matching the docs example from the issue, and asserts three things: the stale output is absent, fresh KaTeX MathML is rendered, and a second version directory now sits beside v1. Before the fix, the build would read the stale v1 entry and the test would fail. After the fix, it passes. So the test is a real regression guard, not a tautology. It is somewhat tied to the on-disk cache layout, but it uses the real cache config (`caches.misc dir`) and OS filesystem, so it is reasonable. Patch A also expands the code comment to say KaTeX upgrades count as incompatible changes, a small craft improvement that should help future maintainers remember to bump the version. Patch B is a correct, minimal one-line change with no test. Since the fixes are identical, Patch A wins on tests and slightly on craft.

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

1h 52m

Wall-clock time in the container

Full test suite

No new failures

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

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

47vs 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+46 −1
tpl/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..191055c1f 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" ) @@ -353,6 +356,48 @@ disableKinds = ['page','rss','section','sitemap','taxonomy','term'] 	`) } +// The KaTeX upgrade to 0.18.4 changed the output, so file cache entries+// written by older Hugo versions must not be reused.+func TestToMathStaleFileCacheEntry(t *testing.T) {+	t.Parallel()++	const expression = `\ce{CO2 + C -> 2 CO}`++	cacheDir := t.TempDir()+	toMathDir := filepath.Join(cacheDir, "filecache", "misc", "tomath")++	// Simulate an entry written by a Hugo version bundling an older KaTeX.+	s := hashing.HashString(expression)+	staleFilename := filepath.Join(toMathDir, "v1", s[:2], s[2:])+	qt.Assert(t, os.MkdirAll(filepath.Dir(staleFilename), 0o777), qt.IsNil)+	qt.Assert(t, os.WriteFile(staleFilename, []byte(`{"version":"v1","output":"STALE_KATEX_OUTPUT"}`), 0o666), qt.IsNil)++	files := `+-- hugo.toml --+disableKinds = ['page','rss','section','sitemap','taxonomy','term']+[caches.misc]+dir = 'CACHE_DIR'+-- layouts/home.html --+{{ transform.ToMath "EXPRESSION" }}+`+	files = strings.ReplaceAll(files, "CACHE_DIR", filepath.ToSlash(cacheDir))+	files = strings.ReplaceAll(files, "EXPRESSION", strings.ReplaceAll(expression, `\`, `\\`))++	b := hugolib.Test(t, files, hugolib.TestOptOsFs())++	b.AssertFileContent("public/index.html", "! STALE_KATEX_OUTPUT", `<span class="katex"><math`, `<annotation encoding="application/x-tex">\ce{CO2 + C -&gt; 2 CO}</annotation>`)++	// Make sure the fresh entry was written to the configured cache dir next to the stale one.+	entries, err := os.ReadDir(toMathDir)+	b.Assert(err, qt.IsNil)+	var versions []string+	for _, e := range entries {+		versions = append(versions, e.Name())+	}+	b.Assert(versions, qt.HasLen, 2)+	b.Assert(versions, qt.Contains, "v1")+}+ // Issue #12977 func TestUnmarshalWithIndentedYAML(t *testing.T) { 	t.Parallel() 
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:]