feat(pipe): add version compatibility matrix automation (tracer pilot)

.github/scripts/generate-compatibility/annotation.go

@@ -0,0 +1,122 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/Masterminds/semver/v3"
+	"gopkg.in/yaml.v3"
+)
+
+// compatAnnotationKey is the reverse-DNS annotation carrying compatibility data.
+// It follows the precedent of lerian.studio/chart-type
+// (validate-helm-charts/main.go:21).
+const compatAnnotationKey = "lerian.studio/compatibility"
+
+// chartTypeAnnotationKey is the pre-existing annotation every chart carries.
+// It decides whether a missing cross-compatibility declaration is worth an INFO
+// reminder: single-service charts are standalone and are NOT expected to declare
+// compatibility, so their absence is silent.
+const chartTypeAnnotationKey = "lerian.studio/chart-type"
+
+const (
+	chartTypeSingleService     = "single-service"
+	chartTypeMultiComponent    = "multi-component"
+	chartTypeDependencyWrapper = "dependency-wrapper"
+)
+
+// CompatAnnotation is the parsed representation of the embedded YAML in the
+// lerian.studio/compatibility annotation (data-model §A.1). Both maps are
+// optional in v1; a wholly absent annotation is represented by a nil pointer.
+type CompatAnnotation struct {
+	Requires   map[string]string `yaml:"requires"`
+	TestedWith map[string]string `yaml:"testedWith"`
+}
+
+// parseCompatAnnotation is the SECOND step of the two-step unmarshal: the caller
+// has already pulled the annotation string out of Chart.yaml.annotations; here
+// we unmarshal that embedded YAML document. An empty/whitespace-only string
+// means "no annotation declared" and returns (nil, nil).
+//
+// KnownFields(true) makes unknown/typo top-level keys (e.g. "testedWih",
+// "require") a parse error instead of being silently dropped — otherwise a typo
+// would erase the declaration without warning. The caller surfaces the error as
+// a V1 WARN and continues (never aborts). An empty document yields io.EOF from
+// Decode, which we treat as "nothing declared" (empty ann, no error).
+func parseCompatAnnotation(raw string) (*CompatAnnotation, error) {
+	if strings.TrimSpace(raw) == "" {
+		return nil, nil
+	}
+	var ann CompatAnnotation
+	dec := yaml.NewDecoder(bytes.NewReader([]byte(raw)))
+	dec.KnownFields(true)
+	if err := dec.Decode(&ann); err != nil && err != io.EOF {
+		return nil, err
+	}
+	return &ann, nil
+}
+
+// validateCompat applies rules V3–V6 (api-design §I.3) without ever failing.
+// V1 (valid YAML) and V2 (unknown keys) are handled by parseCompatAnnotation
+// and the typed struct respectively. knownProducts is the set of chart names
+// present in the repo, used for the V3 existence check.
+//
+// chartType (lerian.studio/chart-type) gates the V6 reminder for a MISSING
+// cross-compatibility declaration:
+//   - single-service        → standalone; no reminder (cross-compat N/A).
+//   - multi-component /
+//     dependency-wrapper     → INFO reminder when nothing is declared.
+//   - "" (missing)           → treated as multi-component (conservative) PLUS a
+//     WARN that the chart-type annotation is absent.
+//
+// A DECLARED compatibility is always validated (V3/V4/V5) regardless of type.
+func validateCompat(chart, chartType string, ann *CompatAnnotation, knownProducts map[string]bool) []Warning {
+	var out []Warning
+
+	if chartType == "" {
+		// chart-type should always be present; flag its absence and fall through
+		// as if multi-component (the stricter branch that still reminds on V6).
+		out = append(out, Warning{SevWarn, chart, "CT", "lerian.studio/chart-type annotation is missing; treating as multi-component"})
+		chartType = chartTypeMultiComponent
+	}
+
+	if ann == nil || (len(ann.Requires) == 0 && len(ann.TestedWith) == 0) {
+		// Nothing declared. Single-service charts are standalone and are not
+		// expected to declare cross-compatibility, so stay silent for them.
+		if chartType == chartTypeSingleService {
+			return out
+		}
+		// multi-component / dependency-wrapper: soft, non-blocking reminder.
+		out = append(out, Warning{
+			Severity: SevInfo,
+			Chart:    chart,
+			Rule:     "V6",
+			Detail:   "no compatibility declared (testedWith expected in v1)",
+		})
+		return out
+	}
+
+	// V3 + V4: requires.
+	for product, rng := range ann.Requires {
+		if !knownProducts[product] {
+			out = append(out, Warning{SevWarn, chart, "V3", fmt.Sprintf("requires[%s] — unknown chart", product)})
+		}
+		if _, err := semver.NewConstraint(rng); err != nil {
+			out = append(out, Warning{SevWarn, chart, "V4", fmt.Sprintf("requires[%s] — invalid semver range %q", product, rng)})
+		}
+	}
+
+	// V3 + V5: testedWith.
+	for product, ver := range ann.TestedWith {
+		if !knownProducts[product] {
+			out = append(out, Warning{SevWarn, chart, "V3", fmt.Sprintf("testedWith[%s] — unknown chart", product)})
+		}
+		if _, err := semver.NewVersion(ver); err != nil {
+			out = append(out, Warning{SevWarn, chart, "V5", fmt.Sprintf("testedWith[%s] — not an exact version %q", product, ver)})
+		}
+	}
+
+	return out
+}

.github/scripts/generate-compatibility/annotation_test.go

@@ -0,0 +1,72 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestParseCompatAnnotation(t *testing.T) {
+	tests := []struct {
+		name      string
+		raw       string
+		want      *CompatAnnotation
+		wantError bool
+	}{
+		{
+			name: "complete requires + testedWith",
+			raw: `requires:
+  midaz-helm: ">=8.4.0 <9.0.0"
+testedWith:
+  midaz-helm: "8.6.0"
+`,
+			want: &CompatAnnotation{
+				Requires:   map[string]string{"midaz-helm": ">=8.4.0 <9.0.0"},
+				TestedWith: map[string]string{"midaz-helm": "8.6.0"},
+			},
+		},
+		{
+			name: "only testedWith (typical v1 post-backfill)",
+			raw: `testedWith:
+  midaz-helm: "8.6.0"
+`,
+			want: &CompatAnnotation{
+				TestedWith: map[string]string{"midaz-helm": "8.6.0"},
+			},
+		},
+		{
+			name: "empty string => nil (absent)",
+			raw:  "",
+			want: nil,
+		},
+		{
+			name:      "broken embedded YAML => error (V1)",
+			raw:       "requires:\n  midaz-helm \">=8.4.0\"\n", // missing colon
+			wantError: true,
+		},
+		{
+			name:      "unknown top-level field (typo 'testedWih') => error, not silent",
+			raw:       "testedWih:\n  midaz-helm: \"8.6.0\"\n",
+			wantError: true,
+		},
+		{
+			name:      "unknown top-level field (typo 'require') => error, not silent",
+			raw:       "require:\n  midaz-helm: \">=8.4.0\"\n",
+			wantError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseCompatAnnotation(tt.raw)
+			if (err != nil) != tt.wantError {
+				t.Fatalf("err = %v, wantError = %v", err, tt.wantError)
+			}
+			if tt.wantError {
+				return
+			}
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("got %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}

.github/scripts/generate-compatibility/builddoc_test.go

@@ -0,0 +1,93 @@
+package main
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// fakeTagLister returns canned tags (and optional dates) per dir.
+type fakeTagLister struct {
+	tags  map[string][]string
+	dates map[string]map[string]string // dir -> (tag -> YYYY-MM-DD)
+}
+
+func (f fakeTagLister) listTags(dir string) ([]string, error) {
+	return f.tags[dir], nil
+}
+
+func (f fakeTagLister) listTagDates(dir string) (map[string]string, error) {
+	if f.dates == nil {
+		return map[string]string{}, nil
+	}
+	return f.dates[dir], nil
+}
+
+func TestBuildDoc_Golden(t *testing.T) {
+	root := t.TempDir()
+
+	// midaz: N=8.6.0, tags cover 8.6..8.2.
+	writeChart(t, root, "midaz", `apiVersion: v2
+name: midaz-helm
+type: application
+version: 8.6.0
+appVersion: "3.7.8"
+`)
+	// plugin-fees: N=7.2.0, only its own tag; declares requires+testedWith.
+	writeChart(t, root, "plugin-fees", `apiVersion: v2
+name: plugin-fees-helm
+type: application
+version: 7.2.0
+appVersion: "3.3.0"
+annotations:
+  lerian.studio/compatibility: |
+    requires:
+      midaz-helm: ">=8.4.0 <9.0.0"
+    testedWith:
+      midaz-helm: "8.6.0"
+`)
+
+	lister := fakeTagLister{
+		tags: map[string][]string{
+			"midaz": {
+				"midaz-v8.6.0", "midaz-v8.5.0", "midaz-v8.4.0",
+				"midaz-v8.3.0", "midaz-v8.2.0", "midaz-v8.6.0-beta.11",
+			},
+			"plugin-fees": {"plugin-fees-v7.2.0"},
+		},
+		dates: map[string]map[string]string{
+			"midaz": {
+				"midaz-v8.6.0": "2026-06-01", "midaz-v8.5.0": "2026-05-01",
+				"midaz-v8.4.0": "2026-04-01", "midaz-v8.3.0": "2026-03-01",
+				"midaz-v8.2.0": "2026-02-01",
+			},
+			"plugin-fees": {"plugin-fees-v7.2.0": "2026-06-15"},
+		},
+	}
+
+	doc, err := buildDoc(root, lister, io.Discard)
+	if err != nil {
+		t.Fatalf("buildDoc: %v", err)
+	}
+	doc.GeneratedFrom = "test" // pin the provenance field for a stable golden
+
+	got, err := renderJSON(doc)
+	if err != nil {
+		t.Fatalf("renderJSON: %v", err)
+	}
+
+	goldenPath := filepath.Join("testdata", "golden_two_products.json")
+	if os.Getenv("UPDATE_GOLDEN") == "1" {
+		if err := os.WriteFile(goldenPath, got, 0o644); err != nil {
+			t.Fatalf("update golden: %v", err)
+		}
+	}
+	want, err := os.ReadFile(goldenPath)
+	if err != nil {
+		t.Fatalf("read golden (run with UPDATE_GOLDEN=1 first): %v", err)
+	}
+	if string(got) != string(want) {
+		t.Fatalf("JSON mismatch.\n--- got ---\n%s\n--- want ---\n%s", got, want)
+	}
+}

.github/scripts/generate-compatibility/chart.go

@@ -0,0 +1,36 @@
+// Command generate-compatibility produces the per-product support-window matrix
+// (README blocks + docs/compatibility.json) for the charts in this repo.
+//
+// It mirrors the sibling tools in .github/scripts (generate-values-schemas,
+// update-readme-matrix): invoked with --root ../.., reads the repo state, and
+// writes deterministic artifacts. No network access beyond the git tags already
+// present in the checkout.
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// chartDirectories returns the names (not full paths) of the immediate
+// subdirectories of <root>/charts, sorted ascending. Loose files under charts/
+// are ignored. Mirrors validate-helm-charts/main.go:292-307 but returns bare
+// names (the caller joins paths), copied here because Go forbids importing one
+// package main from another.
+func chartDirectories(root string) ([]string, error) {
+	chartsRoot := filepath.Join(root, "charts")
+	entries, err := os.ReadDir(chartsRoot)
+	if err != nil {
+		return nil, err
+	}
+
+	dirs := []string{}
+	for _, entry := range entries {
+		if entry.IsDir() {
+			dirs = append(dirs, entry.Name())
+		}
+	}
+	sort.Strings(dirs)
+	return dirs, nil
+}