Make launch stage the single preview source of truth in schema codegen

bundle/internal/annotation/descriptor.go

@@ -1,18 +1,19 @@
 package annotation
 
+import "github.com/databricks/cli/internal/clijson"
+
 type Descriptor struct {
-	Description         string            `json:"description,omitempty"`
-	MarkdownDescription string            `json:"markdown_description,omitempty"`
-	Title               string            `json:"title,omitempty"`
-	Default             any               `json:"default,omitempty"`
-	Enum                []any             `json:"enum,omitempty"`
-	MarkdownExamples    string            `json:"markdown_examples,omitempty"`
-	DeprecationMessage  string            `json:"deprecation_message,omitempty"`
-	Preview             string            `json:"x-databricks-preview,omitempty"`
-	LaunchStage         string            `json:"x-databricks-launch-stage,omitempty"`
-	EnumLaunchStages    map[string]string `json:"x-databricks-enum-launch-stages,omitempty"`
-	EnumDescriptions    map[string]string `json:"x-databricks-enum-descriptions,omitempty"`
-	OutputOnly          *bool             `json:"x-databricks-field-behaviors_output_only,omitempty"`
+	Description         string                         `json:"description,omitempty"`
+	MarkdownDescription string                         `json:"markdown_description,omitempty"`
+	Title               string                         `json:"title,omitempty"`
+	Default             any                            `json:"default,omitempty"`
+	Enum                []any                          `json:"enum,omitempty"`
+	MarkdownExamples    string                         `json:"markdown_examples,omitempty"`
+	DeprecationMessage  string                         `json:"deprecation_message,omitempty"`
+	LaunchStage         clijson.LaunchStage            `json:"x-databricks-launch-stage,omitempty"`
+	EnumLaunchStages    map[string]clijson.LaunchStage `json:"x-databricks-enum-launch-stages,omitempty"`
+	EnumDescriptions    map[string]string              `json:"x-databricks-enum-descriptions,omitempty"`
+	OutputOnly          *bool                          `json:"x-databricks-field-behaviors_output_only,omitempty"`
 }
 
 const Placeholder = "PLACEHOLDER"

bundle/internal/annotation/preview.go

@@ -1,15 +1,20 @@
 package annotation
 
+import "github.com/databricks/cli/internal/clijson"
+
+// previewTags maps each launch stage to the human-readable prefix prepended to
+// a field's or enum value's description. clijson owns the closed set of stages;
+// this map must cover every one (asserted by TestPreviewTagCoversAllStages). A
+// stage mapping to "" (GA) renders no prefix.
+var previewTags = map[clijson.LaunchStage]string{
+	clijson.LaunchStageGA:             "",
+	clijson.LaunchStagePublicPreview:  "[Public Preview]",
+	clijson.LaunchStagePublicBeta:     "[Beta]",
+	clijson.LaunchStagePrivatePreview: "[Private Preview]",
+}
+
 // PreviewTag returns the human-readable launch-stage prefix to prepend to a
-// field's or enum value's description. Others are skipped.
-func PreviewTag(launchStage string) string {
-	switch launchStage {
-	case "PRIVATE_PREVIEW":
-		return "[Private Preview]"
-	case "PUBLIC_BETA":
-		return "[Beta]"
-	case "PUBLIC_PREVIEW":
-		return "[Public Preview]"
-	}
-	return ""
+// field's or enum value's description. GA and the empty stage return "".
+func PreviewTag(stage clijson.LaunchStage) string {
+	return previewTags[stage]
 }

bundle/internal/annotation/preview_test.go

@@ -4,22 +4,36 @@ import (
 	"testing"
 
 	"github.com/databricks/cli/bundle/internal/annotation"
+	"github.com/databricks/cli/internal/clijson"
 	"github.com/stretchr/testify/assert"
 )
 
 func TestPreviewTag(t *testing.T) {
 	tests := []struct {
-		launchStage string
+		launchStage clijson.LaunchStage
 		want        string
 	}{
-		{"PUBLIC_PREVIEW", "[Public Preview]"},
-		{"PUBLIC_BETA", "[Beta]"},
-		{"PRIVATE_PREVIEW", "[Private Preview]"},
-		{"GA", ""},
+		{clijson.LaunchStagePublicPreview, "[Public Preview]"},
+		{clijson.LaunchStagePublicBeta, "[Beta]"},
+		{clijson.LaunchStagePrivatePreview, "[Private Preview]"},
+		{clijson.LaunchStageGA, ""},
 		{"", ""},
 		{"SOMETHING_ELSE", ""},
 	}
 	for _, tc := range tests {
 		assert.Equal(t, tc.want, annotation.PreviewTag(tc.launchStage))
 	}
 }
+
+// Every stage in the contract's closed set must have a tag entry, so a stage
+// added to clijson without a tag here is caught rather than rendering blank.
+// GA intentionally maps to the empty prefix; every other stage must be tagged.
+func TestPreviewTagCoversAllStages(t *testing.T) {
+	for _, stage := range clijson.LaunchStages {
+		if stage == clijson.LaunchStageGA {
+			assert.Empty(t, annotation.PreviewTag(stage))
+			continue
+		}
+		assert.NotEmpty(t, annotation.PreviewTag(stage), "stage %q has no preview tag", stage)
+	}
+}

bundle/internal/schema/annotations.go

@@ -13,6 +13,7 @@ import (
 	yaml3 "go.yaml.in/yaml/v3"
 
 	"github.com/databricks/cli/bundle/internal/annotation"
+	"github.com/databricks/cli/internal/clijson"
 	"github.com/databricks/cli/libs/dyn"
 	"github.com/databricks/cli/libs/dyn/convert"
 	"github.com/databricks/cli/libs/dyn/merge"
@@ -134,16 +135,15 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 		s.DeprecationMessage = a.DeprecationMessage
 	}
 
-	// The raw launch stage is intentionally not emitted into the published
-	// schema — nothing consumes it there. It surfaces only as the description
-	// prefix below and the per-value enumDescriptions labels.
-	// x-databricks-preview does stay: the parser derives it from launch_stage
-	// (PRIVATE iff PRIVATE_PREVIEW), and pydabs reads it from jsonschema.json
-	// to mark fields experimental, so this branch also covers hiding
-	// private-preview fields.
-	if a.Preview == "PRIVATE" {
+	// Private-preview fields are hidden from completions and surfaced to
+	// downstream codegen via the launch stage: pydabs reads
+	// x-databricks-launch-stage from jsonschema.json to mark these fields
+	// experimental. Only the private-preview stage is emitted into the published
+	// schema — nothing consumes the others there; they surface only as the
+	// description prefix below and the per-value enumDescriptions labels.
+	if a.LaunchStage == clijson.LaunchStagePrivatePreview {
 		s.DoNotSuggest = true
-		s.Preview = a.Preview
+		s.LaunchStage = string(a.LaunchStage)
 	}
 
 	if a.OutputOnly != nil && *a.OutputOnly {
@@ -167,7 +167,7 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 // and the per-value description text. Returns nil when every entry would be
 // empty so the field is omitted from the schema. The enum slice is the same
 // one assigned to s.Enum, so the arrays stay index-aligned.
-func buildEnumDescriptions(enum []any, launchStages, descriptions map[string]string) []string {
+func buildEnumDescriptions(enum []any, launchStages map[string]clijson.LaunchStage, descriptions map[string]string) []string {
 	if len(enum) == 0 || (len(launchStages) == 0 && len(descriptions) == 0) {
 		return nil
 	}