feat(sidekick): Support QuickStart sample generation (#4257)

Add support for QuickStart sample generation in sidekick both
at the service client level and the package level. It does so by
selecting a significant method per client and a significant client per
package.

Generate Rust QuickStart samples for both the service
client and the package.

Author: amanda-tarafa

internal/sidekick/api/model.go

@@ -165,6 +165,9 @@ type API struct {
 	State *APIState
 	// ResourceDefinitions contains the data from the `google.api.resource_definition` annotation.
 	ResourceDefinitions []*Resource
+	// QuickstartService is the service that will be used to generate the quickstart sample
+	// at the package level.
+	QuickstartService *Service
 	// Language specific annotations.
 	Codec any
 }
@@ -230,6 +233,9 @@ type Service struct {
 	// The model this service belongs to, mustache templates use this field to
 	// navigate the data structure.
 	Model *API
+	// QuickstartMethod is the method that will be used to generate the quickstart sample
+	// for this service.
+	QuickstartMethod *Method
 	// Language specific annotations.
 	Codec any
 }

internal/sidekick/api/skip_test.go

@@ -372,7 +372,7 @@ func TestIncludeMethods(t *testing.T) {
 	})
 
 	wantServices := []*Service{s1}
-	if diff := cmp.Diff(wantServices, model.Services, cmpopts.IgnoreFields(Method{}, "Model"), cmpopts.IgnoreFields(Service{}, "Model")); diff != "" {
+	if diff := cmp.Diff(wantServices, model.Services, cmpopts.IgnoreFields(Method{}, methodIgnoreFields...), cmpopts.IgnoreFields(Service{}, "Model", "QuickstartMethod")); diff != "" {
 		t.Errorf("mismatch in services (-want, +got)\n:%s", diff)
 	}
 

internal/sidekick/api/xref.go

@@ -111,6 +111,141 @@ func enrichSamples(model *API) {
 	for _, m := range model.State.MethodByID {
 		enrichMethodSamples(m)
 	}
+
+	for _, s := range model.Services {
+		s.QuickstartMethod = findQuickstartMethod(s)
+	}
+	model.QuickstartService = findQuickstartService(model)
+}
+
+func findQuickstartMethod(s *Service) *Method {
+	// Priority: List > Get > Create > Delete > Update
+	priorities := []func(m *Method) bool{
+		func(m *Method) bool { return m.IsAIPStandardList },
+		func(m *Method) bool { return m.IsAIPStandardGet },
+		func(m *Method) bool { return m.IsAIPStandardCreate },
+		func(m *Method) bool { return m.IsAIPStandardDelete },
+		func(m *Method) bool { return m.IsAIPStandardUpdate },
+		// Fallback for when no standard AIP method is available: any method that is not streaming.
+		func(m *Method) bool { return !m.ClientSideStreaming && !m.ServerSideStreaming },
+	}
+
+	strippedServiceName := strings.TrimSuffix(s.Name, "Service")
+	lowerStripped := strings.ToLower(strippedServiceName)
+
+	for _, isType := range priorities {
+		var nonDeprecated []*Method
+		var deprecated []*Method
+
+		for _, m := range s.Methods {
+			if isType(m) {
+				if m.Deprecated {
+					deprecated = append(deprecated, m)
+				} else {
+					nonDeprecated = append(nonDeprecated, m)
+				}
+			}
+		}
+
+		searchList := nonDeprecated
+		if len(searchList) == 0 {
+			searchList = deprecated
+		}
+
+		if len(searchList) == 0 {
+			continue
+		}
+
+		if len(searchList) == 1 {
+			return searchList[0]
+		}
+
+		// Tie-breaking: Substring match on method name
+		for _, m := range searchList {
+			if strings.Contains(strings.ToLower(m.Name), lowerStripped) {
+				return m
+			}
+		}
+
+		// Tie-breaking: Resource singular/plural match
+		for _, m := range searchList {
+			res := standardMethodOutputResource(m)
+			if res != nil {
+				if strings.ToLower(res.Singular) == lowerStripped || strings.ToLower(res.Plural) == lowerStripped {
+					return m
+				}
+			}
+		}
+
+		// Default to first candidate if no tie-breaker matches
+		return searchList[0]
+	}
+	return nil
+}
+
+func findQuickstartService(api *API) *Service {
+	if len(api.Services) == 0 {
+		return nil
+	}
+
+	var nonDeprecated []*Service
+	var deprecated []*Service
+
+	for _, s := range api.Services {
+		if len(s.Methods) > 0 {
+			if s.Deprecated {
+				deprecated = append(deprecated, s)
+			} else {
+				nonDeprecated = append(nonDeprecated, s)
+			}
+		}
+	}
+
+	searchList := nonDeprecated
+	if len(searchList) == 0 {
+		searchList = deprecated
+	}
+
+	if len(searchList) == 0 {
+		return api.Services[0]
+	}
+
+	if len(searchList) == 1 {
+		return searchList[0]
+	}
+
+	// Prefer services with a QuickstartMethod that is an AIP standard method
+	var servicesWithStandardQuickstart []*Service
+	// Fallback to services with ANY QuickstartMethod
+	var servicesWithAnyQuickstart []*Service
+
+	for _, s := range searchList {
+		if s.QuickstartMethod != nil {
+			servicesWithAnyQuickstart = append(servicesWithAnyQuickstart, s)
+			if s.QuickstartMethod.IsAIPStandardList ||
+				s.QuickstartMethod.IsAIPStandardGet ||
+				s.QuickstartMethod.IsAIPStandardCreate ||
+				s.QuickstartMethod.IsAIPStandardDelete ||
+				s.QuickstartMethod.IsAIPStandardUpdate {
+				servicesWithStandardQuickstart = append(servicesWithStandardQuickstart, s)
+			}
+		}
+	}
+
+	if len(servicesWithStandardQuickstart) > 0 {
+		searchList = servicesWithStandardQuickstart
+	} else if len(servicesWithAnyQuickstart) > 0 {
+		searchList = servicesWithAnyQuickstart
+	}
+
+	lowerApiName := strings.ToLower(api.Name)
+	for _, s := range searchList {
+		if strings.Contains(strings.ToLower(s.Name), lowerApiName) {
+			return s
+		}
+	}
+
+	return searchList[0]
 }
 
 func enrichEnumSamples(e *Enum) {

internal/sidekick/api/xref_test.go

@@ -1946,3 +1946,122 @@ func TestFindResourceIDField(t *testing.T) {
 		})
 	}
 }
+
+func TestFindQuickstartMethod(t *testing.T) {
+	fooMethod := &Method{Name: "FooMethod"}
+	listPolicies := &Method{Name: "ListAccessPolicies", IsAIPStandardList: true, OutputType: &Message{Resource: &Resource{Singular: "accesspolicy"}}}
+	getPolicy := &Method{Name: "GetAccessPolicy", IsAIPStandardGet: true}
+	createPolicy := &Method{Name: "CreateAccessPolicy", IsAIPStandardCreate: true}
+	deletePolicy := &Method{Name: "DeleteAccessPolicy", IsAIPStandardDelete: true}
+	updatePolicy := &Method{Name: "UpdateAccessPolicy", IsAIPStandardUpdate: true}
+	listOther := &Method{Name: "ListOtherThings", IsAIPStandardList: true, OutputType: &Message{Resource: &Resource{Singular: "otherthing"}}}
+
+	testCases := []struct {
+		name    string
+		service *Service
+		want    *Method
+	}{
+		{
+			name:    "empty service",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{}},
+			want:    nil,
+		},
+		{
+			name:    "fallback to simple method when no standard methods exist",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{fooMethod}},
+			want:    fooMethod,
+		},
+		{
+			name:    "prefer non-deprecated simple method",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{{Name: "DeprecatedList", Deprecated: true}, fooMethod}},
+			want:    fooMethod,
+		},
+		{
+			name:    "only get method",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{getPolicy}},
+			want:    getPolicy,
+		},
+		{
+			name:    "prioritizes list over get",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{getPolicy, listOther}},
+			want:    listOther,
+		},
+		{
+			name:    "prioritizes create over delete",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{deletePolicy, createPolicy}},
+			want:    createPolicy,
+		},
+		{
+			name:    "prioritizes delete over update",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{updatePolicy, deletePolicy}},
+			want:    deletePolicy,
+		},
+		{
+			name:    "tie-breaking on name matching (ListAccessPolicies vs ListOtherThings for AccessPolicyService)",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{listOther, listPolicies}},
+			want:    listPolicies,
+		},
+		{
+			name:    "tie-breaking fallback to resource singular/plural",
+			service: &Service{Name: "AccessPolicyService", Methods: []*Method{listOther, {Name: "ListPolicies", IsAIPStandardList: true, OutputType: &Message{Resource: &Resource{Singular: "accesspolicy"}}}}},
+			want:    &Method{Name: "ListPolicies", IsAIPStandardList: true, OutputType: &Message{Resource: &Resource{Singular: "accesspolicy"}}}, // matches singular 'accesspolicy'
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findQuickstartMethod(tc.service)
+			if diff := cmp.Diff(tc.want, got, cmpopts.IgnoreFields(Method{}, "Service", "Model")); diff != "" {
+				t.Errorf("findQuickstartMethod() mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
+func TestFindQuickstartService(t *testing.T) {
+	fooMethod := &Method{Name: "FooMethod"}
+	serviceA := &Service{Name: "ServiceA", Methods: []*Method{fooMethod}}
+	serviceB := &Service{Name: "SecretManagerService", Methods: []*Method{fooMethod}}
+	deprecatedService := &Service{Name: "SecretManagerService", Deprecated: true, Methods: []*Method{fooMethod}}
+
+	testCases := []struct {
+		name string
+		api  *API
+		want *Service
+	}{
+		{
+			name: "no services",
+			api:  &API{Name: "secretmanager", Services: nil},
+			want: nil,
+		},
+		{
+			name: "one service",
+			api:  &API{Name: "secretmanager", Services: []*Service{serviceA}},
+			want: serviceA,
+		},
+		{
+			name: "match service name to api name",
+			api:  &API{Name: "secretmanager", Services: []*Service{serviceA, serviceB}},
+			want: serviceB,
+		},
+		{
+			name: "no match defaults to first",
+			api:  &API{Name: "otherapi", Services: []*Service{serviceA, serviceB}},
+			want: serviceA,
+		},
+		{
+			name: "prefer non-deprecated service",
+			api:  &API{Name: "secretmanager", Services: []*Service{deprecatedService, serviceA}},
+			want: serviceA,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findQuickstartService(tc.api)
+			if diff := cmp.Diff(tc.want, got); diff != "" {
+				t.Errorf("findQuickstartService() mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}

internal/sidekick/rust/annotate.go

@@ -80,6 +80,12 @@ type modelAnnotations struct {
 	DetailedTracingAttributes bool
 	// If true, the generated builders's visibility should be restricted to the crate.
 	InternalBuilders bool
+	// The service to use for the package-level quickstart sample.
+	// Rust generation may decide not to generate some services,
+	// e.g. if the methods have no bindings. On occasion the service
+	// selected at the model level will be skipped for Rust generation
+	// so we need to choose a different one.
+	QuickstartService *api.Service
 }
 
 // IsWktCrate returns true when bootstrapping the well-known types crate the templates add some
@@ -681,6 +687,17 @@ func annotateModel(model *api.API, codec *codec) (*modelAnnotations, error) {
 		}
 		return defaultHost[:idx]
 	}()
+
+	var quickstartService *api.Service
+	if model.QuickstartService != nil {
+		if slices.ContainsFunc(servicesSubset, func(s *api.Service) bool { return s == model.QuickstartService }) {
+			quickstartService = model.QuickstartService
+		}
+	}
+	if quickstartService == nil && len(servicesSubset) > 0 {
+		quickstartService = servicesSubset[0]
+	}
+
 	ann := &modelAnnotations{
 		PackageName:      codec.packageName(model),
 		PackageNamespace: codec.rootModuleName(model),
@@ -709,6 +726,7 @@ func annotateModel(model *api.API, codec *codec) (*modelAnnotations, error) {
 		GenerateRpcSamples:        codec.generateRpcSamples,
 		DetailedTracingAttributes: codec.detailedTracingAttributes,
 		InternalBuilders:          codec.internalBuilders,
+		QuickstartService:         quickstartService,
 	}
 
 	codec.addFeatureAnnotations(model, ann)

internal/sidekick/rust/annotate_model_test.go

@@ -185,6 +185,66 @@ func TestInternalBuildersAnnotation(t *testing.T) {
 	}
 }
 
+func TestQuickstartServiceAnnotation(t *testing.T) {
+	t.Run("survives filtering", func(t *testing.T) {
+		model := newTestAnnotateModelAPI()
+		// model.Services[0] is Service0, model.Services[1] is Service1
+		model.QuickstartService = model.Services[1]
+
+		codec := newTestCodec(t, libconfig.SpecProtobuf, "", nil)
+		got, err := annotateModel(model, codec)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if got.QuickstartService == nil {
+			t.Fatal("QuickstartService should not be nil")
+		}
+		if got.QuickstartService != model.Services[1] {
+			t.Errorf("expected QuickstartService to be Service1, got %v", got.QuickstartService.Name)
+		}
+	})
+
+	t.Run("filtered out fallback", func(t *testing.T) {
+		model := newTestAnnotateModelAPI()
+
+		// Create a service that has no methods with bindings, so it will be filtered out.
+		filteredService := &api.Service{
+			Name:    "FilteredService",
+			ID:      "..FilteredService",
+			Package: "test.v1",
+			Methods: []*api.Method{
+				{
+					Name: "noBindings",
+					ID:   "..FilteredService.noBindings",
+				},
+			},
+		}
+		model.Services = append(model.Services, filteredService)
+		for _, s := range model.Services {
+			s.Model = model
+		}
+		api.CrossReference(model)
+
+		// Set the filtered service as the global quickstart.
+		model.QuickstartService = filteredService
+
+		codec := newTestCodec(t, libconfig.SpecProtobuf, "", nil)
+		got, err := annotateModel(model, codec)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if got.QuickstartService == nil {
+			t.Fatal("QuickstartService should not be nil")
+		}
+		// It should have fallen back to the first non-filtered service (Service0).
+		if got.QuickstartService != model.Services[0] {
+			t.Errorf("expected QuickstartService to fall back to Service0, got %v", got.QuickstartService.Name)
+		}
+	})
+}
+
 func newTestAnnotateModelAPI() *api.API {
 	service0 := &api.Service{
 		Name: "Service0",