CLOUDP-311381: Add a new filter to foascli to support bump.sh fields

tools/cli/internal/apiversion/version.go

@@ -186,6 +186,9 @@ func (v *APIVersion) IsPublicPreview() bool {
 }
 
 func (v *APIVersion) IsUpcoming() bool { return IsUpcomingStabilityLevel(v.stabilityVersion) }
+
+func (v *APIVersion) IsStable() bool { return IsStableStabilityLevel(v.stabilityVersion) }
+
 func FindMatchesFromContentType(contentType string) []string {
 	return contentPattern.FindStringSubmatch(contentType)
 }

tools/cli/internal/openapi/filter/bump.go

@@ -0,0 +1,76 @@
+// Copyright 2025 MongoDB Inc
+//
+// 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 filter
+
+import (
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+// BumpFilter modifies includes the fields "x-state" and "x-beta" to the "preview" and "upcoming" APIs Operations.
+// The "x-state" and "x-beta" fields are bump.sh custom fields to include budges
+// Bump.sh feature: https://docs.bump.sh/help/specification-support/doc-badges/
+type BumpFilter struct {
+	oas      *openapi3.T
+	metadata *Metadata
+}
+
+const (
+	stateFieldName          = "x-state"
+	stateFieldValueUpcoming = "Upcoming"
+	stateFieldValuePreview  = "Preview"
+	betaFieldName           = "x-beta"
+)
+
+func (f *BumpFilter) ValidateMetadata() error {
+	return validateMetadataWithVersion(f.metadata)
+}
+
+func (f *BumpFilter) Apply() error {
+	if f.metadata.targetVersion.IsStable() {
+		return nil
+	}
+
+	if f.metadata.targetVersion.IsUpcoming() {
+		return f.includeBumpFieldForUpcoming()
+	}
+
+	return f.includeBumpFieldForPreview()
+}
+
+func (f *BumpFilter) includeBumpFieldForUpcoming() error {
+	for _, p := range f.oas.Paths.Map() {
+		for _, op := range p.Operations() {
+			if op.Extensions == nil {
+				op.Extensions = map[string]any{}
+			}
+			op.Extensions[stateFieldName] = stateFieldValueUpcoming
+		}
+	}
+
+	return nil
+}
+
+func (f *BumpFilter) includeBumpFieldForPreview() error {
+	for _, p := range f.oas.Paths.Map() {
+		for _, op := range p.Operations() {
+			if op.Extensions == nil {
+				op.Extensions = map[string]any{}
+			}
+			op.Extensions[stateFieldName] = stateFieldValuePreview
+			op.Extensions[betaFieldName] = true
+		}
+	}
+	return nil
+}

tools/cli/internal/openapi/filter/bump_test.go

@@ -0,0 +1,162 @@
+// Copyright 2025 MongoDB Inc
+//
+// 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 filter
+
+import (
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/mongodb/openapi/tools/cli/internal/apiversion"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBumpFilter_Apply_Preview(t *testing.T) {
+	targetVersion, err := apiversion.New(apiversion.WithVersion("preview"))
+	require.NoError(t, err)
+
+	oas := &openapi3.T{
+		OpenAPI: "3.0.0",
+		Info: &openapi3.Info{
+			Version: "1.0",
+		},
+		Paths: openapi3.NewPaths(openapi3.WithPath("test", &openapi3.PathItem{
+			Get: &openapi3.Operation{
+				OperationID: "testOperationID",
+				Summary:     "testSummary",
+				Responses: openapi3.NewResponses(openapi3.WithName("200", &openapi3.Response{
+					Content: openapi3.Content{
+						"application/vnd.atlas.preview+json": {
+							Schema: &openapi3.SchemaRef{
+								Ref: "#/components/schemas/PaginatedAppUserView",
+							},
+							Extensions: map[string]any{
+								"x-gen-version": "preview",
+							},
+						},
+					},
+				})),
+			},
+			Extensions: map[string]any{},
+		})),
+	}
+
+	filter := &BumpFilter{
+		metadata: NewMetadata(targetVersion, "test"),
+		oas:      oas,
+	}
+
+	require.NoError(t, filter.Apply())
+	assert.Len(t, oas.Paths.Map(), 1)
+	assert.Contains(t, oas.Paths.Map(), "test")
+
+	testPath := oas.Paths.Map()["test"]
+	assert.NotNil(t, testPath.Get)
+
+	op := testPath.Get
+	assert.Contains(t, op.Extensions, "x-state")
+	assert.Equal(t, "Preview", op.Extensions["x-state"])
+	assert.Contains(t, op.Extensions, "x-beta")
+	assert.Equal(t, true, op.Extensions["x-beta"])
+}
+
+func TestBumpFilter_Apply_Upcoming(t *testing.T) {
+	targetVersion, err := apiversion.New(apiversion.WithVersion("2024-09-22.upcoming"))
+	require.NoError(t, err)
+
+	oas := &openapi3.T{
+		OpenAPI: "3.0.0",
+		Info: &openapi3.Info{
+			Version: "1.0",
+		},
+		Paths: openapi3.NewPaths(openapi3.WithPath("test", &openapi3.PathItem{
+			Get: &openapi3.Operation{
+				OperationID: "testOperationID",
+				Summary:     "testSummary",
+				Responses: openapi3.NewResponses(openapi3.WithName("200", &openapi3.Response{
+					Content: openapi3.Content{
+						"application/vnd.atlas.2024-09-22.upcoming+json": {
+							Schema: &openapi3.SchemaRef{
+								Ref: "#/components/schemas/PaginatedAppUserView",
+							},
+						},
+					},
+				})),
+			},
+			Extensions: map[string]any{},
+		})),
+	}
+
+	filter := &BumpFilter{
+		metadata: NewMetadata(targetVersion, "test"),
+		oas:      oas,
+	}
+
+	require.NoError(t, filter.Apply())
+	assert.Len(t, oas.Paths.Map(), 1)
+	assert.Contains(t, oas.Paths.Map(), "test")
+
+	testPath := oas.Paths.Map()["test"]
+	assert.NotNil(t, testPath.Get)
+	op := testPath.Get
+
+	assert.Contains(t, op.Extensions, "x-state")
+	assert.Equal(t, "Upcoming", op.Extensions["x-state"])
+	assert.NotContains(t, op.Extensions, "x-beta")
+}
+
+func TestBumpFilter_Apply_Stable(t *testing.T) {
+	targetVersion, err := apiversion.New(apiversion.WithVersion("2024-09-22"))
+	require.NoError(t, err)
+
+	oas := &openapi3.T{
+		OpenAPI: "3.0.0",
+		Info: &openapi3.Info{
+			Version: "1.0",
+		},
+		Paths: openapi3.NewPaths(openapi3.WithPath("test", &openapi3.PathItem{
+			Get: &openapi3.Operation{
+				OperationID: "testOperationID",
+				Summary:     "testSummary",
+				Responses: openapi3.NewResponses(openapi3.WithName("200", &openapi3.Response{
+					Content: openapi3.Content{
+						"application/vnd.atlas.2024-09-22+json": {
+							Schema: &openapi3.SchemaRef{
+								Ref: "#/components/schemas/PaginatedAppUserView",
+							},
+						},
+					},
+				})),
+			},
+			Extensions: map[string]any{},
+		})),
+	}
+
+	filter := &BumpFilter{
+		metadata: NewMetadata(targetVersion, "test"),
+		oas:      oas,
+	}
+
+	require.NoError(t, filter.Apply())
+	assert.Len(t, oas.Paths.Map(), 1)
+	assert.Contains(t, oas.Paths.Map(), "test")
+
+	testPath := oas.Paths.Map()["test"]
+	assert.NotNil(t, testPath.Get)
+	op := testPath.Get
+
+	assert.NotContains(t, op.Extensions, "x-state")
+	assert.NotContains(t, op.Extensions, "x-beta")
+}

tools/cli/internal/openapi/filter/filter.go

@@ -80,6 +80,7 @@ func DefaultFilters(oas *openapi3.T, metadata *Metadata) []Filter {
 		&OperationsFilter{oas: oas},
 		&SunsetFilter{oas: oas},
 		&SchemasFilter{oas: oas},
+		&BumpFilter{oas: oas, metadata: metadata},
 	}
 }
 

tools/cli/internal/openapi/filter/filter_test.go

@@ -112,7 +112,7 @@ func TestDefaultFilters(t *testing.T) {
 	metadata := &Metadata{}
 	filters := DefaultFilters(doc, metadata)
 
-	assert.Len(t, filters, 9)
+	assert.Len(t, filters, 10)
 }
 
 func TestFiltersWithoutVersioning(t *testing.T) {