heaputil: add package with helper functions for working with heaps

This patch adds a new `heaputil` containing helper functions for
working with heaps. As of now, it only contains a single `Valid`
function which returns whether a heap is a valid heap based on
the min-heap invariant defined by `heap.Interface`.

The reasoning for creating a new package instead of reusing the
existing `heap` package is that that package is intended to be
a type-safe copy of the standard library package with the same name.

Release note: None

Author: andyyang890

pkg/BUILD.bazel

@@ -727,6 +727,7 @@ ALL_TESTS = [
     "//pkg/util/cloudinfo:cloudinfo_test",
     "//pkg/util/collatedstring:collatedstring_test",
     "//pkg/util/container/heap:heap_test",
+    "//pkg/util/container/heaputil:heaputil_test",
     "//pkg/util/container/list:list_test",
     "//pkg/util/container/ring:ring_test",
     "//pkg/util/ctxgroup:ctxgroup_test",
@@ -2570,6 +2571,8 @@ GO_TARGETS = [
     "//pkg/util/collatedstring:collatedstring_test",
     "//pkg/util/container/heap:heap",
     "//pkg/util/container/heap:heap_test",
+    "//pkg/util/container/heaputil:heaputil",
+    "//pkg/util/container/heaputil:heaputil_test",
     "//pkg/util/container/list:list",
     "//pkg/util/container/list:list_test",
     "//pkg/util/container/ring:ring",

pkg/util/container/heaputil/BUILD.bazel

@@ -0,0 +1,19 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "heaputil",
+    srcs = ["heaputil.go"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/util/container/heaputil",
+    visibility = ["//visibility:public"],
+    deps = ["//pkg/util/container/heap"],
+)
+
+go_test(
+    name = "heaputil_test",
+    srcs = ["heaputil_test.go"],
+    deps = [
+        ":heaputil",
+        "//pkg/util/container/heap",
+        "@com_github_stretchr_testify//require",
+    ],
+)

pkg/util/container/heaputil/heaputil.go

@@ -0,0 +1,25 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+// Package heaputil provides helper functions for working with heaps.
+package heaputil
+
+import "github.com/cockroachdb/cockroach/pkg/util/container/heap"
+
+// Valid returns whether a heap is a valid heap based on the min-heap
+// invariant defined by heap.Interface.
+func Valid[T any](h heap.Interface[T]) bool {
+	n := h.Len()
+	for i := 0; i < n; i++ {
+		left, right := 2*i+1, 2*i+2
+		if left < n && h.Less(left, i) {
+			return false
+		}
+		if right < n && h.Less(right, i) {
+			return false
+		}
+	}
+	return true
+}

pkg/util/container/heaputil/heaputil_test.go

@@ -0,0 +1,71 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package heaputil_test
+
+import (
+	"testing"
+
+	"github.com/cockroachdb/cockroach/pkg/util/container/heap"
+	"github.com/cockroachdb/cockroach/pkg/util/container/heaputil"
+	"github.com/stretchr/testify/require"
+)
+
+func TestValid(t *testing.T) {
+	for name, tc := range map[string]struct {
+		h     intHeap
+		valid bool
+	}{
+		"nil heap": {
+			h:     nil,
+			valid: true,
+		},
+		"empty heap": {
+			h:     []int{},
+			valid: true,
+		},
+		"sorted heap": {
+			h:     []int{1, 2, 3, 4, 5, 6},
+			valid: true,
+		},
+		"valid heap": {
+			h:     []int{2, 4, 6, 5, 9, 7},
+			valid: true,
+		},
+		"invalid heap due to left child": {
+			h:     []int{5, 1, 7},
+			valid: false,
+		},
+		"invalid heap due to right child": {
+			h:     []int{4, 6, 1},
+			valid: false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			actual := heaputil.Valid(&tc.h)
+			require.Equal(t, tc.valid, actual)
+		})
+	}
+}
+
+type intHeap []int
+
+var _ heap.Interface[int] = (*intHeap)(nil)
+
+func (h intHeap) Len() int           { return len(h) }
+func (h intHeap) Less(i, j int) bool { return h[i] < h[j] }
+func (h intHeap) Swap(i, j int)      { h[i], h[j] = h[j], h[i] }
+
+func (h *intHeap) Push(x int) {
+	*h = append(*h, x)
+}
+
+func (h *intHeap) Pop() int {
+	old := *h
+	n := len(old)
+	x := old[n-1]
+	*h = old[:n-1]
+	return x
+}