🐛 Add support for build metadata precedence in bundle version comparison (#2273)

* Add support for build metadata precedence in bundle version comparison

This change fixes an issue to ensure that operator-controller properly
handles and compares registry+v1 bundle versions that include build
metadata as specified in the semver version.

The intention is that we only treat build metadata as a release value
for registry+v1 bundles, which already have this precedent set. If/when
operator-controller gains support for new bundle types, the intention is
to avoid continuing the practice (and semver violation) of treating
version build metadata as comparable/orderable.

Key changes:
- Introduce VersionRelease type combining semver version with release metadata
- Update bundle comparison logic to consider build metadata when present
- Add exact version matching for pinned versions with build metadata
- Replace GetVersion with GetVersionAndRelease across the codebase
- Ensure successors are determined based on exact version+release matching

This is particularly important for registry+v1 bundles that encode
release information in the build metadata field of their version strings.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Revert semantic changes to ClusterExtension version selection and improve VersionRelease parsing

This commit reverts the user-facing semantic changes to the ClusterExtension
version field that were introduced to support exact version pinning with build
metadata. The version field now ignores build metadata when matching versions,
consistent with semver specification.

Additionally, this commit modifies the VersionRelease parsing logic to be more
tolerant of semver versions whose build metadata is not a valid release. When
build metadata cannot be parsed as a release, the full version (including build
metadata) is preserved in the Version field, with an empty Release field.

Changes include:
- Removed documentation about pinning to exact versions with build metadata
- Removed exactVersionMatcher logic that enforced build metadata equality
- Updated NewLegacyRegistryV1VersionRelease to tolerate non-release build metadata
- Updated test expectations to reflect new behavior

* Address code review feedback for build metadata precedence

- Add documentation for AsLegacyRegistryV1Version method explaining
  the build metadata conversion logic
- Fix AsLegacyRegistryV1Version to preserve original build metadata
  when Release field is not set
- Add comprehensive test coverage for NewLegacyRegistryV1VersionRelease
  including edge cases for build metadata and release parsing
- Add test coverage for AsLegacyRegistryV1Version conversion logic
- Improve compare_test.go test structure with descriptive test names
  and assertion functions for better clarity
- Add test case for non-release build metadata comparison

---------

Co-authored-by: Claude <[email protected]>

Author: joelanford

internal/operator-controller/bundle/versionrelease.go

@@ -0,0 +1,137 @@
+package bundle
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	bsemver "github.com/blang/semver/v4"
+
+	slicesutil "github.com/operator-framework/operator-controller/internal/shared/util/slices"
+)
+
+// NewLegacyRegistryV1VersionRelease parses a registry+v1 bundle version string and returns a
+// VersionRelease. Some registry+v1 bundles utilize the build metadata field of the semver version
+// as release information (a semver spec violation maintained for backward compatibility). When the
+// bundle version includes build metadata that is parsable as a release, the returned
+// VersionRelease has the build metadata extracted into the Release field, and the Version field
+// has its Build metadata cleared. When the bundle version includes build metadata that is NOT
+// parseable as a release, the returned VersionRelease has its Version set to the full semver
+// version (with build metadata) and its Release left empty.
+func NewLegacyRegistryV1VersionRelease(vStr string) (*VersionRelease, error) {
+	vers, err := bsemver.Parse(vStr)
+	if err != nil {
+		return nil, err
+	}
+
+	vr := &VersionRelease{
+		Version: vers,
+	}
+
+	rel, err := NewRelease(strings.Join(vr.Version.Build, "."))
+	if err == nil {
+		// If the version build metadata parses successfully as a release
+		// then use it as a release and drop the build metadata
+		//
+		// If we don't parse the build metadata as a release successfully,
+		// that doesn't mean we have an invalid version. It just means
+		// that we have a valid semver version with valid build metadata,
+		// but no release value. In this case, we return a VersionRelease
+		// with:
+		//   - Version: the full version (with build metadata)
+		//   - Release: <empty>
+		vr.Release = rel
+		vr.Version.Build = nil
+	}
+	return vr, nil
+}
+
+type VersionRelease struct {
+	Version bsemver.Version
+	Release Release
+}
+
+// Compare compares two VersionRelease values. It returns:
+//
+//	-1 if vr < other
+//	 0 if vr == other
+//	+1 if vr > other
+//
+// Comparison is done first by Version, then by Release if versions are equal.
+func (vr *VersionRelease) Compare(other VersionRelease) int {
+	if vCmp := vr.Version.Compare(other.Version); vCmp != 0 {
+		return vCmp
+	}
+	return vr.Release.Compare(other.Release)
+}
+
+// AsLegacyRegistryV1Version converts a VersionRelease into a standard semver version.
+// If the VersionRelease's Release field is set, the returned semver version's build
+// metadata is set to the VersionRelease's Release. Otherwise, the build metadata is
+// set to the VersionRelease's Version field's build metadata.
+func (vr *VersionRelease) AsLegacyRegistryV1Version() bsemver.Version {
+	v := bsemver.Version{
+		Major: vr.Version.Major,
+		Minor: vr.Version.Minor,
+		Patch: vr.Version.Patch,
+		Pre:   vr.Version.Pre,
+		Build: vr.Version.Build,
+	}
+	if len(vr.Release) > 0 {
+		v.Build = slicesutil.Map(vr.Release, func(i bsemver.PRVersion) string { return i.String() })
+	}
+	return v
+}
+
+type Release []bsemver.PRVersion
+
+// Compare compares two Release values. It returns:
+//
+//	-1 if r < other
+//	 0 if r == other
+//	+1 if r > other
+//
+// Comparison is done segment by segment from left to right. Numeric segments are
+// compared numerically, and alphanumeric segments are compared lexically in ASCII
+// sort order. A shorter release is considered less than a longer release if all
+// corresponding segments are equal.
+func (r Release) Compare(other Release) int {
+	if len(r) == 0 && len(other) > 0 {
+		return -1
+	}
+	if len(other) == 0 && len(r) > 0 {
+		return 1
+	}
+	a := bsemver.Version{Pre: r}
+	b := bsemver.Version{Pre: other}
+	return a.Compare(b)
+}
+
+// NewRelease parses a release string into a Release. The release string should be
+// a dot-separated sequence of non-empty identifiers, where each identifier contains
+// only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Numeric identifiers (those
+// containing only digits) must not have leading zeros. An empty string returns a nil
+// Release. Returns an error if any segment is invalid.
+func NewRelease(relStr string) (Release, error) {
+	if relStr == "" {
+		return nil, nil
+	}
+
+	var (
+		segments = strings.Split(relStr, ".")
+		r        = make(Release, 0, len(segments))
+		errs     []error
+	)
+	for i, segment := range segments {
+		prVer, err := bsemver.NewPRVersion(segment)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("segment %d: %v", i, err))
+			continue
+		}
+		r = append(r, prVer)
+	}
+	if err := errors.Join(errs...); err != nil {
+		return nil, fmt.Errorf("invalid release %q: %v", relStr, err)
+	}
+	return r, nil
+}