Make cascade front matter order deterministic

Fixes #12594

common/hashing/hashing.go

@@ -123,16 +123,24 @@ func HashUint64(vs ...any) uint64 {
 		o = elements
 	}
 
-	hashOpts := getHashOpts()
-	defer putHashOpts(hashOpts)
-
-	hash, err := hashstructure.Hash(o, hashOpts)
+	hash, err := Hash(o)
 	if err != nil {
 		panic(err)
 	}
 	return hash
 }
 
+// Hash returns a hash from vs.
+func Hash(vs ...any) (uint64, error) {
+	hashOpts := getHashOpts()
+	defer putHashOpts(hashOpts)
+	var v any = vs
+	if len(vs) == 1 {
+		v = vs[0]
+	}
+	return hashstructure.Hash(v, hashOpts)
+}
+
 type keyer interface {
 	Key() string
 }

common/maps/ordered.go

@@ -0,0 +1,117 @@
+// Copyright 2024 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package maps
+
+import (
+	"github.com/gohugoio/hugo/common/hashing"
+)
+
+// Ordered is a map that can be iterated in the order of insertion.
+// Note that insertion order is not affected if a key is re-inserted into the map.
+// This is not thread safe.
+type Ordered[K comparable, T any] struct {
+	// The keys in the order they were added.
+	keys []K
+	// The values.
+	values map[K]T
+}
+
+// NewOrdered creates a new Ordered map.
+func NewOrdered[K comparable, T any]() *Ordered[K, T] {
+	return &Ordered[K, T]{values: make(map[K]T)}
+}
+
+// Set sets the value for the given key.
+// Note that insertion order is not affected if a key is re-inserted into the map.
+func (m *Ordered[K, T]) Set(key K, value T) {
+	// Check if key already exists.
+	if _, found := m.values[key]; !found {
+		m.keys = append(m.keys, key)
+	}
+	m.values[key] = value
+}
+
+// Get gets the value for the given key.
+func (m *Ordered[K, T]) Get(key K) (T, bool) {
+	value, found := m.values[key]
+	return value, found
+}
+
+// Delete deletes the value for the given key.
+func (m *Ordered[K, T]) Delete(key K) {
+	delete(m.values, key)
+	for i, k := range m.keys {
+		if k == key {
+			m.keys = append(m.keys[:i], m.keys[i+1:]...)
+			break
+		}
+	}
+}
+
+// Clone creates a shallow copy of the map.
+// If m is nil, it returns nil.
+func (m *Ordered[K, T]) Clone() *Ordered[K, T] {
+	if m == nil {
+		return nil
+	}
+	clone := NewOrdered[K, T]()
+	for _, k := range m.keys {
+		clone.Set(k, m.values[k])
+	}
+	return clone
+}
+
+// Keys returns the keys in the order they were added.
+func (m *Ordered[K, T]) Keys() []K {
+	if m == nil {
+		return nil
+	}
+	return m.keys
+}
+
+// Values returns the values in the order they were added.
+func (m *Ordered[K, T]) Values() []T {
+	if m == nil {
+		return nil
+	}
+	var values []T
+	for _, k := range m.keys {
+		values = append(values, m.values[k])
+	}
+	return values
+}
+
+// Len returns the number of items in the map.
+func (m *Ordered[K, T]) Len() int {
+	return len(m.keys)
+}
+
+// Range calls f sequentially for each key and value present in the map.
+// If f returns false, range stops the iteration.
+// TODO(bep) replace with iter.Seq2 when we bump go Go 1.24.
+func (m *Ordered[K, T]) Range(f func(key K, value T) bool) {
+	if m == nil {
+		return
+	}
+	for _, k := range m.keys {
+		if !f(k, m.values[k]) {
+			return
+		}
+	}
+}
+
+// Hash calculates a hash from the keys and values.
+func (m *Ordered[K, T]) Hash() (uint64, error) {
+	return hashing.Hash(m.keys, m.values)
+}

common/maps/ordered_test.go

@@ -0,0 +1,74 @@
+// Copyright 2024 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package maps
+
+import (
+	"testing"
+
+	qt "github.com/frankban/quicktest"
+)
+
+func TestOrdered(t *testing.T) {
+	c := qt.New(t)
+
+	m := NewOrdered[string, int]()
+	m.Set("a", 1)
+	m.Set("b", 2)
+	m.Set("c", 3)
+
+	c.Assert(m.Keys(), qt.DeepEquals, []string{"a", "b", "c"})
+	c.Assert(m.Values(), qt.DeepEquals, []int{1, 2, 3})
+
+	v, found := m.Get("b")
+	c.Assert(found, qt.Equals, true)
+	c.Assert(v, qt.Equals, 2)
+
+	m.Set("b", 22)
+	c.Assert(m.Keys(), qt.DeepEquals, []string{"a", "b", "c"})
+	c.Assert(m.Values(), qt.DeepEquals, []int{1, 22, 3})
+
+	m.Delete("b")
+
+	c.Assert(m.Keys(), qt.DeepEquals, []string{"a", "c"})
+	c.Assert(m.Values(), qt.DeepEquals, []int{1, 3})
+}
+
+func TestOrderedHash(t *testing.T) {
+	c := qt.New(t)
+
+	m := NewOrdered[string, int]()
+	m.Set("a", 1)
+	m.Set("b", 2)
+	m.Set("c", 3)
+
+	h1, err := m.Hash()
+	c.Assert(err, qt.IsNil)
+
+	m.Set("d", 4)
+
+	h2, err := m.Hash()
+	c.Assert(err, qt.IsNil)
+
+	c.Assert(h1, qt.Not(qt.Equals), h2)
+
+	m = NewOrdered[string, int]()
+	m.Set("b", 2)
+	m.Set("a", 1)
+	m.Set("c", 3)
+
+	h3, err := m.Hash()
+	c.Assert(err, qt.IsNil)
+	// Order matters.
+	c.Assert(h3, qt.Not(qt.Equals), h1)
+}

config/allconfig/allconfig.go

@@ -143,7 +143,7 @@ type Config struct {
 
 	// The cascade configuration section contains the top level front matter cascade configuration options,
 	// a slice of page matcher and params to apply to those pages.
-	Cascade *config.ConfigNamespace[[]page.PageMatcherParamsConfig, map[page.PageMatcher]maps.Params] `mapstructure:"-"`
+	Cascade *config.ConfigNamespace[[]page.PageMatcherParamsConfig, *maps.Ordered[page.PageMatcher, maps.Params]] `mapstructure:"-"`
 
 	// The segments defines segments for the site. Used for partial/segmented builds.
 	Segments *config.ConfigNamespace[map[string]segments.SegmentConfig, segments.Segments] `mapstructure:"-"`
@@ -766,9 +766,10 @@ type Configs struct {
 }
 
 func (c *Configs) Validate(logger loggers.Logger) error {
-	for p := range c.Base.Cascade.Config {
+	c.Base.Cascade.Config.Range(func(p page.PageMatcher, params maps.Params) bool {
 		page.CheckCascadePattern(logger, p)
-	}
+		return true
+	})
 	return nil
 }
 

hugolib/cascade_test.go

@@ -841,3 +841,38 @@ title: p1
 	b.AssertFileExists("public/s1/index.html", false)
 	b.AssertFileExists("public/s1/p1/index.html", false)
 }
+
+// Issue 12594.
+func TestCascadeOrder(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableKinds = ['rss','sitemap','taxonomy','term', 'home']
+-- content/_index.md --
+---
+title: Home
+cascade:
+- _target:
+    path: "**"
+  params:
+    background: yosemite.jpg
+- _target:
+  params:
+    background: goldenbridge.jpg
+---
+-- content/p1.md --
+---
+title: p1
+---
+-- layouts/_default/single.html --
+Background: {{ .Params.background }}|
+-- layouts/_default/list.html --
+{{ .Title }}|
+  `
+
+	for i := 0; i < 10; i++ {
+		b := Test(t, files)
+		b.AssertFileContent("public/p1/index.html", "Background: yosemite.jpg")
+	}
+}

hugolib/content_map_page.go

@@ -1387,7 +1387,7 @@ func (sa *sitePagesAssembler) applyAggregates() error {
 		}
 
 		// Handle cascades first to get any default dates set.
-		var cascade map[page.PageMatcher]maps.Params
+		var cascade *maps.Ordered[page.PageMatcher, maps.Params]
 		if keyPage == "" {
 			// Home page gets it's cascade from the site config.
 			cascade = sa.conf.Cascade.Config
@@ -1399,7 +1399,7 @@ func (sa *sitePagesAssembler) applyAggregates() error {
 		} else {
 			_, data := pw.WalkContext.Data().LongestPrefix(keyPage)
 			if data != nil {
-				cascade = data.(map[page.PageMatcher]maps.Params)
+				cascade = data.(*maps.Ordered[page.PageMatcher, maps.Params])
 			}
 		}
 
@@ -1481,11 +1481,11 @@ func (sa *sitePagesAssembler) applyAggregates() error {
 				pageResource := rs.r.(*pageState)
 				relPath := pageResource.m.pathInfo.BaseRel(pageBundle.m.pathInfo)
 				pageResource.m.resourcePath = relPath
-				var cascade map[page.PageMatcher]maps.Params
+				var cascade *maps.Ordered[page.PageMatcher, maps.Params]
 				// Apply cascade (if set) to the page.
 				_, data := pw.WalkContext.Data().LongestPrefix(resourceKey)
 				if data != nil {
-					cascade = data.(map[page.PageMatcher]maps.Params)
+					cascade = data.(*maps.Ordered[page.PageMatcher, maps.Params])
 				}
 				if err := pageResource.setMetaPost(cascade); err != nil {
 					return false, err
@@ -1549,10 +1549,10 @@ func (sa *sitePagesAssembler) applyAggregatesToTaxonomiesAndTerms() error {
 				const eventName = "dates"
 
 				if p.Kind() == kinds.KindTerm {
-					var cascade map[page.PageMatcher]maps.Params
+					var cascade *maps.Ordered[page.PageMatcher, maps.Params]
 					_, data := pw.WalkContext.Data().LongestPrefix(s)
 					if data != nil {
-						cascade = data.(map[page.PageMatcher]maps.Params)
+						cascade = data.(*maps.Ordered[page.PageMatcher, maps.Params])
 					}
 					if err := p.setMetaPost(cascade); err != nil {
 						return false, err