feat(charts): add content digest for the embedded talm library

Expose the binary's built-in talm library chart as a normalized
path->content map (TalmLibraryFiles) plus a deterministic, order-
independent digest over a chart tree (HashChartFiles). Chart.yaml
name/version lines are folded to %s placeholders through a shared
NormalizeChartMeta helper — also adopted by PresetFiles — so a version
stamp is not counted as content.

This is the comparison primitive for detecting when a project's vendored
charts/talm/ has drifted from the binary that renders it: equal digests
mean identical library bytes, independent of the stamped version.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>

Author: lexfrei

charts/charts.go

@@ -1,25 +1,56 @@
 package charts
 
 import (
+	"crypto/sha256"
 	"embed"
+	"encoding/hex"
+	"fmt"
 	"io/fs"
 	"path"
 	"regexp"
+	"sort"
 	"strings"
 
 	"github.com/cockroachdb/errors"
 )
 
 const presetGenericName = "generic"
 
+// talmLibraryName is the directory of the talm library chart inside the
+// embedded tree (and the name it is vendored under at charts/talm/ in a
+// project). It is talm-owned — unlike the preset templates, which the
+// operator edits — so it is the only tree the drift check compares.
+const talmLibraryName = "talm"
+
+// chartYamlName is the conventional Helm chart metadata filename.
+const chartYamlName = "Chart.yaml"
+
 //go:embed all:cozystack all:generic all:talm
 var embeddedCharts embed.FS
 
+// chartMetaRegex matches the `name:`/`version:` metadata lines of a
+// Chart.yaml. Both are rewritten to a %s placeholder so the init flow can
+// substitute the real project name/version, and so the drift check can
+// compare two chart trees without a version stamp counting as content.
+var chartMetaRegex = regexp.MustCompile(`(name|version): \S+`)
+
+// NormalizeChartMeta rewrites the name/version lines of a Chart.yaml to %s
+// placeholders. Files other than Chart.yaml pass through unchanged. base is
+// the file's base name (e.g. path.Base(p)). Keeping a single normalizer
+// means the init-time substitution and the content-drift comparison treat
+// chart metadata identically.
+func NormalizeChartMeta(base, content string) string {
+	if base != chartYamlName {
+		return content
+	}
+
+	return chartMetaRegex.ReplaceAllString(content, "$1: %s")
+}
+
 // PresetFiles returns a map of file paths to their contents.
 // For Chart.yaml files, name and version are replaced with %s placeholders.
 func PresetFiles() (map[string]string, error) {
 	filesMap := make(map[string]string)
-	regex := regexp.MustCompile(`(name|version): \S+`)
 
 	err := fs.WalkDir(embeddedCharts, ".", func(filePath string, entry fs.DirEntry, err error) error {
 		if err != nil {
@@ -47,12 +78,8 @@ func PresetFiles() (map[string]string, error) {
 			return errors.Wrapf(err, "reading embedded chart file %q", filePath)
 		}
 
-		content := string(data)
-
-		// For Chart.yaml files, replace name and version with %s
-		if path.Base(filePath) == "Chart.yaml" {
-			content = regex.ReplaceAllString(content, "$1: %s")
-		}
+		// For Chart.yaml files, replace name and version with %s.
+		content := NormalizeChartMeta(path.Base(filePath), string(data))
 
 		// Use the file path as-is (relative to charts directory)
 		filesMap[filePath] = content
@@ -66,6 +93,67 @@ func PresetFiles() (map[string]string, error) {
 	return filesMap, nil
 }
 
+// TalmLibraryFiles returns the embedded talm library chart keyed by path
+// relative to the talm/ root (e.g. "Chart.yaml", "templates/_helpers.tpl"),
+// so the keys line up with a project's vendored charts/talm/ tree. Chart.yaml
+// metadata is normalized via NormalizeChartMeta, so a version stamp is not
+// treated as content. It is the embedded counterpart compared against the
+// vendored copy to surface chart drift after a binary upgrade.
+func TalmLibraryFiles() (map[string]string, error) {
+	filesMap := make(map[string]string)
+
+	err := fs.WalkDir(embeddedCharts, talmLibraryName, func(filePath string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return errors.Wrapf(err, "walking embedded talm library at %q", filePath)
+		}
+
+		if entry.IsDir() {
+			return nil
+		}
+
+		data, err := embeddedCharts.ReadFile(filePath)
+		if err != nil {
+			return errors.Wrapf(err, "reading embedded talm file %q", filePath)
+		}
+
+		// Strip the talm/ prefix so keys match a vendored charts/talm/ tree.
+		rel := strings.TrimPrefix(filePath, talmLibraryName+"/")
+		filesMap[rel] = NormalizeChartMeta(path.Base(filePath), string(data))
+
+		return nil
+	})
+	if err != nil {
+		return nil, errors.Wrap(err, "collecting embedded talm library")
+	}
+
+	return filesMap, nil
+}
+
+// HashChartFiles returns a deterministic digest of a chart tree described as
+// a path→content map. The digest folds in the sorted set of (path, content)
+// pairs and is independent of map iteration order. Each path and content is
+// length-prefixed so distinct trees cannot collide by a fortunate alignment
+// of concatenated bytes. Two trees hash equal iff they carry the same files
+// with the same bytes — the signal the drift check relies on.
+func HashChartFiles(files map[string]string) string {
+	paths := make([]string, 0, len(files))
+	for p := range files {
+		paths = append(paths, p)
+	}
+
+	sort.Strings(paths)
+
+	hasher := sha256.New()
+	for _, p := range paths {
+		// Length-prefix both the path and its content so the boundary
+		// between them (and between successive entries) is unambiguous.
+		fmt.Fprintf(hasher, "%d:%s%d:", len(p), p, len(files[p]))
+		hasher.Write([]byte(files[p]))
+	}
+
+	return hex.EncodeToString(hasher.Sum(nil))
+}
+
 // AvailablePresets returns a list of available preset chart names.
 // The presetGenericName preset is always first if it exists.
 func AvailablePresets() ([]string, error) {

charts/library_test.go

@@ -0,0 +1,140 @@
+package charts
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestTalmLibraryFiles_NormalizesAndStripsPrefix pins the embedded talm
+// library collector. Keys must be relative to the talm/ root (so they
+// line up with a project's vendored charts/talm/ tree), the library
+// Chart.yaml must come back with its name/version normalized to %s (so a
+// version stamp never counts as content), and the helpers template must
+// be present verbatim.
+func TestTalmLibraryFiles_NormalizesAndStripsPrefix(t *testing.T) {
+	files, err := TalmLibraryFiles()
+	if err != nil {
+		t.Fatalf("TalmLibraryFiles: %v", err)
+	}
+
+	if len(files) == 0 {
+		t.Fatal("TalmLibraryFiles returned empty map; embedded talm library is missing")
+	}
+
+	for path := range files {
+		if strings.HasPrefix(path, "talm/") {
+			t.Errorf("key %q still carries the talm/ prefix; it would not match a vendored charts/talm/ relative path", path)
+		}
+	}
+
+	chart, ok := files["Chart.yaml"]
+	if !ok {
+		t.Fatal("expected Chart.yaml entry keyed relative to the talm/ root")
+	}
+	if !strings.Contains(chart, "version: %s") {
+		t.Errorf("library Chart.yaml not normalized; a version stamp would be treated as content drift:\n%s", chart)
+	}
+
+	if _, ok := files["templates/_helpers.tpl"]; !ok {
+		t.Error("expected templates/_helpers.tpl in the embedded talm library")
+	}
+}
+
+// TestHashChartFiles_OrderIndependent pins that the digest depends on the
+// set of (path, content) pairs, not on map iteration order. Go map order
+// is randomized, so a digest that folded order in would be non-
+// deterministic across runs and falsely report drift.
+func TestHashChartFiles_OrderIndependent(t *testing.T) {
+	a := map[string]string{
+		"Chart.yaml":             "name: %s\nversion: %s\n",
+		"templates/_helpers.tpl": "{{- define \"x\" -}}{{- end -}}",
+	}
+	b := map[string]string{
+		"templates/_helpers.tpl": "{{- define \"x\" -}}{{- end -}}",
+		"Chart.yaml":             "name: %s\nversion: %s\n",
+	}
+
+	if HashChartFiles(a) != HashChartFiles(b) {
+		t.Error("digest depends on map order; it must be deterministic over the (path, content) set")
+	}
+}
+
+// TestHashChartFiles_ContentSensitive pins that any change to a file's
+// content changes the digest. This is the signal the drift check relies
+// on: a stale helpers template must hash differently from a fresh one.
+func TestHashChartFiles_ContentSensitive(t *testing.T) {
+	base := map[string]string{"templates/_helpers.tpl": "old"}
+	changed := map[string]string{"templates/_helpers.tpl": "new"}
+
+	if HashChartFiles(base) == HashChartFiles(changed) {
+		t.Error("digest is insensitive to content; real chart drift would go undetected")
+	}
+}
+
+// TestHashChartFiles_PathBoundaryUnambiguous guards the length-prefixed
+// framing: two different file trees must not collide just because their
+// concatenated path+content bytes happen to line up. Without framing,
+// {"ab": "c"} and {"a": "bc"} would hash identically.
+func TestHashChartFiles_PathBoundaryUnambiguous(t *testing.T) {
+	left := map[string]string{"ab": "c"}
+	right := map[string]string{"a": "bc"}
+
+	if HashChartFiles(left) == HashChartFiles(right) {
+		t.Error("path/content boundary is ambiguous; distinct trees collide to the same digest")
+	}
+}
+
+// TestNormalizeChartMeta_VersionStampDoesNotAffectHash is the core
+// correctness guard for the whole drift feature: two library trees that
+// differ ONLY in the Chart.yaml version stamp must hash identically once
+// normalized. A binary version bump that left charts/talm/ byte-identical
+// must not be reported as drift — that false positive is exactly what the
+// version-number comparison approach got wrong.
+func TestNormalizeChartMeta_VersionStampDoesNotAffectHash(t *testing.T) {
+	old := map[string]string{
+		"Chart.yaml":             NormalizeChartMeta("Chart.yaml", "name: talm\nversion: 0.27.0\ntype: library\n"),
+		"templates/_helpers.tpl": "{{- define \"x\" -}}{{- end -}}",
+	}
+	fresh := map[string]string{
+		"Chart.yaml":             NormalizeChartMeta("Chart.yaml", "name: talm\nversion: 0.30.0\ntype: library\n"),
+		"templates/_helpers.tpl": "{{- define \"x\" -}}{{- end -}}",
+	}
+
+	if HashChartFiles(old) != HashChartFiles(fresh) {
+		t.Error("version-only difference changed the digest; a pure version bump would raise a false drift warning")
+	}
+}
+
+// TestNormalizeChartMeta_LeavesNonChartYamlUntouched pins that the
+// normalizer only rewrites Chart.yaml. A helpers template that happens to
+// contain a `version:` line (e.g. inside a rendered manifest snippet) must
+// pass through unchanged, or genuine drift in that template would be
+// masked.
+func TestNormalizeChartMeta_LeavesNonChartYamlUntouched(t *testing.T) {
+	const tpl = "version: 1.2.3 # part of a rendered example, not chart metadata"
+	if got := NormalizeChartMeta("_helpers.tpl", tpl); got != tpl {
+		t.Errorf("NormalizeChartMeta rewrote a non-Chart.yaml file: %q", got)
+	}
+}
+
+// TestNormalizeChartMeta_PreservesApiAndAppVersion pins that only the
+// `name`/`version` metadata is folded to a placeholder. The camelCase
+// `apiVersion`/`appVersion` keys must survive verbatim — otherwise a real
+// change to those fields would be normalized away and hidden from the drift
+// comparison. Guards against a future regex tweak (e.g. adding `(?i)`) that
+// would start eating them.
+func TestNormalizeChartMeta_PreservesApiAndAppVersion(t *testing.T) {
+	const chart = "apiVersion: v2\nname: talm\nversion: 0.1.0\nappVersion: 1.30.0\ntype: library\n"
+
+	got := NormalizeChartMeta("Chart.yaml", chart)
+
+	if !strings.Contains(got, "apiVersion: v2") {
+		t.Errorf("apiVersion was rewritten:\n%s", got)
+	}
+	if !strings.Contains(got, "appVersion: 1.30.0") {
+		t.Errorf("appVersion was rewritten:\n%s", got)
+	}
+	if !strings.Contains(got, "name: %s") || !strings.Contains(got, "version: %s") {
+		t.Errorf("name/version not normalized:\n%s", got)
+	}
+}