hugo/hugolib/sitesmatrix/dimensions.go

// Copyright 2025 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 sitesmatrix

import (
	"fmt"
)

const (
	// Dimensions in the Hugo build matrix.
	// These can be used as indices into the Vector type.
	Language int = iota
	Version
	Role
)

// Vector represents a site vector in the Hugo sites matrix from the three dimensions:
// Language, Version and Role.
// This is a fixed-size array for performance reasons (for one, it can be used as map key).
type Vector [3]int

// Compare returns -1 if v1 is less than v2, 0 if they are equal, and 1 if v1 is greater than v2.
// This adds a implicit weighting to the dimensions, where the first dimension is the most important,
// but this is just used for sorting to get stable output.
func (v1 Vector) Compare(v2 Vector) int {
	// note that a and b will never be equal.
	minusOneOrOne := func(a, b int) int {
		if a < b {
			return -1
		}
		return 1
	}
	if v1[0] != v2[0] {
		return minusOneOrOne(v1[0], v2[0])
	}
	if v1[1] != v2[1] {
		return minusOneOrOne(v1[1], v2[1])
	}
	if v1[2] != v2[2] {
		return minusOneOrOne(v1[2], v2[2])
	}
	// They are equal.
	return 0
}

// Distance returns the distance between v1 and v2
// using the first dimension that is different.
func (v1 Vector) Distance(v2 Vector) int {
	if v1[0] != v2[0] {
		return v1[0] - v2[0]
	}
	if v1[1] != v2[1] {
		return v1[1] - v2[1]
	}
	if v1[2] != v2[2] {
		return v1[2] - v2[2]
	}
	return 0
}

// EuclideanDistanceSquared returns the Euclidean distance between two vectors as the sum of the squared differences.

func (v1 Vector) HasVector(v2 Vector) bool {
	return v1 == v2
}

func (v1 Vector) HasAnyVector(vp VectorProvider) bool {
	n := vp.LenVectors()
	if n == 0 {
		return false
	}
	if n == 1 {
		return v1 == vp.VectorSample()
	}

	return !vp.ForEachVector(func(v2 Vector) bool {
		if v1 == v2 {
			return false // stop iteration
		}
		return true // continue iteration
	})
}

func (v1 Vector) LenVectors() int {
	return 1
}

func (v1 Vector) VectorSample() Vector {
	return v1
}

func (v1 Vector) EqualsVector(other VectorProvider) bool {
	if other.LenVectors() != 1 {
		return false
	}
	return other.VectorSample() == v1
}

func (v1 Vector) ForEachVector(yield func(v Vector) bool) bool {
	return yield(v1)
}

// Language returns the language dimension.
func (v1 Vector) Language() int {
	return v1[Language]
}

// Version returns the version dimension.
func (v1 Vector) Version() int {
	return v1[Version]
}

// IsFirst returns true if this is the first vector in the matrix, i.e. all dimensions are 0.
func (v1 Vector) IsFirst() bool {
	return v1[Language] == 0 && v1[Version] == 0 && v1[Role] == 0
}

// Role returns the role dimension.
func (v1 Vector) Role() int {
	return v1[Role]
}

func (v1 Vector) Weight() int {
	return 0
}

var _ ToVectorStoreProvider = Vectors{}

type Vectors map[Vector]struct{}

func (vs Vectors) ForEachVector(yield func(v Vector) bool) bool {
	for v := range vs {
		if !yield(v) {
			return false
		}
	}
	return true
}

func (vs Vectors) LenVectors() int {
	return len(vs)
}

func (vs Vectors) ToVectorStore() VectorStore {
	return newVectorStoreMapFromVectors(vs)
}

// VectorSample returns one of the vectors in the set.
func (vs Vectors) VectorSample() Vector {
	for v := range vs {
		return v
	}
	panic("no vectors")
}

type (
	VectorIterator interface {
		// ForEachVector iterates over all vectors in the provider.
		// It returns false if the iteration was stopped early.
		ForEachVector(func(v Vector) bool) bool

		// LenVectors returns the number of vectors in the provider.
		LenVectors() int

		// VectorSample returns one of the vectors in the provider, usually the first or the only one.
		// This will panic if the provider is empty.
		VectorSample() Vector
	}
)

// Bools holds boolean values for each dimension in the Hugo build matrix.
type Bools [3]bool

func (d Bools) Language() bool {
	return d[Language]
}

func (d Bools) Version() bool {
	return d[Version]
}

func (d Bools) Role() bool {
	return d[Role]
}

func (d Bools) IsZero() bool {
	return !d[0] && !d[1] && !d[2]
}

type VectorProvider interface {
	VectorIterator
	// HasVector returns true if the given vector is contained in the provider.
	// Used for membership testing of files, resources and pages.
	HasVector(HasAnyVectorv Vector) bool

	// HasAnyVector returns true if any of the vectors in the provider matches any of the vectors in v.
	HasAnyVector(v VectorProvider) bool

	// Equals returns true if this provider is equal to the other provider.
	EqualsVector(other VectorProvider) bool
}

type VectorStore interface {
	VectorProvider
	Complement(...VectorProvider) VectorStore
	WithLanguageIndices(i ...int) VectorStore
	WithVersionIndices(i ...int) VectorStore
	WithRoleIndices(i ...int) VectorStore
	HasLanguage(lang int) bool
	HasVersion(version int) bool
	HasRole(role int) bool
	MustHash() uint64

	// Used in tests.
	KeysSorted() ([]int, []int, []int)
	Vectors() []Vector
}

type ToVectorStoreProvider interface {
	ToVectorStore() VectorStore
}

// CoarseSiteVectorMatcher is implemented by types that can match a site vector in a coarse way, i.e. it first checks for a
// sites matrix match and then falls back to checking the sites complements.
type CoarseSiteVectorMatcher interface {
	MatchSiteVectorCoarse(Vector) bool
	MatchSiteVectorCoarseExcludeLanguage(Vector) bool
}

func VectorIteratorToStore(vi VectorIterator) VectorStore {
	switch v := vi.(type) {
	case VectorStore:
		return v
	case ToVectorStoreProvider:
		return v.ToVectorStore()
	}

	vectors := make(Vectors)
	vi.ForEachVector(func(v Vector) bool {
		vectors[v] = struct{}{}
		return true
	})
	return vectors.ToVectorStore()
}

type weightedVectorStore struct {
	VectorStore
	weight int
}

func (w weightedVectorStore) Weight() int {
	return w.weight
}

func NewWeightedVectorStore(vs VectorStore, weight int) VectorStore {
	if vs == nil {
		return nil
	}
	return weightedVectorStore{VectorStore: vs, weight: weight}
}

// Dimension is a dimension in the Hugo build matrix.
type Dimension int8

func ParseDimension(s string) (int, error) {
	switch s {
	case "language":
		return Language, nil
	case "version":
		return Version, nil
	case "role":
		return Role, nil
	default:
		return 0, fmt.Errorf("unknown dimension %q", s)
	}
}

func DimensionName(d int) string {
	switch d {
	case Language:
		return "language"
	case Version:
		return "version"
	case Role:
		return "role"
	default:
		panic("unknown dimension")
	}
}

// Common information provided by all of language, version and role.
type DimensionInfo interface {
	// The name. This corresponds to the key in the config, e.g. "en", "v1.2.3", "guest".
	Name() string

	// Whether this is the default value for this dimension.
	IsDefault() bool
}