impl(sidekick): parser for discovery files (#1882)

Author: coryan

internal/sidekick/internal/parser/disco.go

@@ -0,0 +1,41 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 parser
+
+import (
+	"os"
+
+	"github.com/googleapis/librarian/internal/sidekick/internal/api"
+	"github.com/googleapis/librarian/internal/sidekick/internal/parser/discovery"
+	"google.golang.org/genproto/googleapis/api/serviceconfig"
+)
+
+// ParseDisco reads discovery docs specifications and converts them into
+// the `api.API` model.
+func ParseDisco(source, serviceConfigFile string, options map[string]string) (*api.API, error) {
+	contents, err := os.ReadFile(source)
+	if err != nil {
+		return nil, err
+	}
+	var serviceConfig *serviceconfig.Service
+	if serviceConfigFile != "" {
+		cfg, err := readServiceConfig(findServiceConfigPath(serviceConfigFile, options))
+		if err != nil {
+			return nil, err
+		}
+		serviceConfig = cfg
+	}
+	return discovery.NewAPI(serviceConfig, contents)
+}

internal/sidekick/internal/parser/disco_test.go

@@ -0,0 +1,74 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 parser
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestDisco_Parse(t *testing.T) {
+	// Mixing Compute and Secret Manager like this is fine in tests.
+	got, err := ParseDisco(discoSourceFile, secretManagerYamlFullPath, map[string]string{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantName := "secretmanager"
+	wantTitle := "Secret Manager API"
+	wantDescription := "Stores sensitive data such as API keys, passwords, and certificates.\nProvides convenience while improving security."
+	wantPackageName := "google.cloud.secretmanager.v1"
+	if got.Name != wantName {
+		t.Errorf("want = %q; got = %q", wantName, got.Name)
+	}
+	if got.Title != wantTitle {
+		t.Errorf("want = %q; got = %q", wantTitle, got.Title)
+	}
+	if diff := cmp.Diff(got.Description, wantDescription); diff != "" {
+		t.Errorf("description mismatch (-want, +got):\n%s", diff)
+	}
+	if got.PackageName != wantPackageName {
+		t.Errorf("want = %q; got = %q", wantPackageName, got.PackageName)
+	}
+}
+
+func TestDisco_ParseNoServiceConfig(t *testing.T) {
+	got, err := ParseDisco(discoSourceFile, "", map[string]string{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantName := "compute"
+	wantTitle := "Compute Engine API"
+	wantDescription := "Creates and runs virtual machines on Google Cloud Platform. "
+	if got.Name != wantName {
+		t.Errorf("want = %q; got = %q", wantName, got.Name)
+	}
+	if got.Title != wantTitle {
+		t.Errorf("want = %q; got = %q", wantTitle, got.Title)
+	}
+	if diff := cmp.Diff(got.Description, wantDescription); diff != "" {
+		t.Errorf("description mismatch (-want, +got):\n%s", diff)
+	}
+}
+
+func TestDisco_ParseBadFiles(t *testing.T) {
+	if _, err := ParseDisco("-invalid-file-name-", secretManagerYamlFullPath, map[string]string{}); err == nil {
+		t.Fatalf("expected error with invalid source file name")
+	}
+
+	if _, err := ParseDisco(discoSourceFile, "-invalid-file-name-", map[string]string{}); err == nil {
+		t.Fatalf("expected error with invalid service config yaml file name")
+	}
+}

internal/sidekick/internal/parser/parser.go

@@ -28,6 +28,8 @@ func CreateModel(config *config.Config) (*api.API, error) {
 	var err error
 	var model *api.API
 	switch config.General.SpecificationFormat {
+	case "disco":
+		model, err = ParseDisco(config.General.SpecificationSource, config.General.ServiceConfig, config.Source)
 	case "openapi":
 		model, err = ParseOpenAPI(config.General.SpecificationSource, config.General.ServiceConfig, config.Source)
 	case "protobuf":

internal/sidekick/internal/parser/parser_test.go

@@ -19,18 +19,58 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/google/go-cmp/cmp"
 	"github.com/googleapis/librarian/internal/sidekick/internal/config"
 )
 
 var (
-	testdataDir, _ = filepath.Abs("../../testdata")
+	testdataDir, _            = filepath.Abs("../../testdata")
+	discoSourceFile           = path.Join(testdataDir, "disco/compute.v1.json")
+	secretManagerYamlRelative = "google/cloud/secretmanager/v1/secretmanager_v1.yaml"
+	secretManagerYamlFullPath = path.Join(testdataDir, "googleapis", secretManagerYamlRelative)
 )
 
+func TestCreateModelDisco(t *testing.T) {
+	cfg := &config.Config{
+		General: config.GeneralConfig{
+			SpecificationFormat: "disco",
+			ServiceConfig:       secretManagerYamlFullPath,
+			SpecificationSource: discoSourceFile,
+		},
+	}
+	got, err := CreateModel(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantName := "secretmanager"
+	wantTitle := "Secret Manager API"
+	wantDescription := "Stores sensitive data such as API keys, passwords, and certificates.\nProvides convenience while improving security."
+	wantPackageName := "google.cloud.secretmanager.v1"
+	if got.Name != wantName {
+		t.Errorf("want = %q; got = %q", wantName, got.Name)
+	}
+	if got.Title != wantTitle {
+		t.Errorf("want = %q; got = %q", wantTitle, got.Title)
+	}
+	if diff := cmp.Diff(got.Description, wantDescription); diff != "" {
+		t.Errorf("description mismatch (-want, +got):\n%s", diff)
+	}
+	if got.PackageName != wantPackageName {
+		t.Errorf("want = %q; got = %q", wantPackageName, got.PackageName)
+	}
+	// This is strange, but we want to verify the package name override from
+	// the service config YAML applies to the message IDs too.
+	wantMessage := ".google.cloud.secretmanager.v1.ZoneSetPolicyRequest"
+	if _, ok := got.State.MessageByID[wantMessage]; !ok {
+		t.Errorf("missing message %s in MessageByID index", wantMessage)
+	}
+}
+
 func TestCreateModelOpenAPI(t *testing.T) {
 	cfg := &config.Config{
 		General: config.GeneralConfig{
 			SpecificationFormat: "openapi",
-			ServiceConfig:       path.Join(testdataDir, "googleapis/google/cloud/secretmanager/v1/secretmanager_v1.yaml"),
+			ServiceConfig:       secretManagerYamlFullPath,
 			SpecificationSource: path.Join(testdataDir, "openapi/secretmanager_openapi_v1.json"),
 		},
 	}
@@ -50,7 +90,7 @@ func TestCreateModelProtobuf(t *testing.T) {
 	cfg := &config.Config{
 		General: config.GeneralConfig{
 			SpecificationFormat: "protobuf",
-			ServiceConfig:       "google/cloud/secretmanager/v1/secretmanager_v1.yaml",
+			ServiceConfig:       secretManagerYamlRelative,
 			SpecificationSource: "google/cloud/secretmanager/v1",
 		},
 		Source: map[string]string{
@@ -73,7 +113,7 @@ func TestCreateModelOverrides(t *testing.T) {
 	cfg := &config.Config{
 		General: config.GeneralConfig{
 			SpecificationFormat: "protobuf",
-			ServiceConfig:       "google/cloud/secretmanager/v1/secretmanager_v1.yaml",
+			ServiceConfig:       secretManagerYamlRelative,
 			SpecificationSource: "google/cloud/secretmanager/v1",
 		},
 		Source: map[string]string{
@@ -108,7 +148,7 @@ func TestCreateModelNone(t *testing.T) {
 	cfg := &config.Config{
 		General: config.GeneralConfig{
 			SpecificationFormat: "none",
-			ServiceConfig:       "google/cloud/secretmanager/v1/secretmanager_v1.yaml",
+			ServiceConfig:       secretManagerYamlRelative,
 			SpecificationSource: "none",
 		},
 		Source: map[string]string{
@@ -126,3 +166,42 @@ func TestCreateModelNone(t *testing.T) {
 		t.Errorf("expected `nil` model with source format == none")
 	}
 }
+
+func TestCreateModelUnknown(t *testing.T) {
+	cfg := &config.Config{
+		General: config.GeneralConfig{
+			SpecificationFormat: "--unknown--",
+			ServiceConfig:       secretManagerYamlRelative,
+			SpecificationSource: "none",
+		},
+		Source: map[string]string{
+			"googleapis-root":      path.Join(testdataDir, "googleapis"),
+			"name-override":        "Name Override",
+			"title-override":       "Title Override",
+			"description-override": "Description Override",
+		},
+	}
+	if got, err := CreateModel(cfg); err == nil {
+		t.Errorf("expected error with unknown specification format, got=%v", got)
+	}
+}
+
+func TestCreateModelBadParse(t *testing.T) {
+	cfg := &config.Config{
+		General: config.GeneralConfig{
+			SpecificationFormat: "openapi",
+			ServiceConfig:       secretManagerYamlRelative,
+			// Note the mismatch between the format and the file contents.
+			SpecificationSource: discoSourceFile,
+		},
+		Source: map[string]string{
+			"googleapis-root":      path.Join(testdataDir, "googleapis"),
+			"name-override":        "Name Override",
+			"title-override":       "Title Override",
+			"description-override": "Description Override",
+		},
+	}
+	if got, err := CreateModel(cfg); err == nil {
+		t.Errorf("expected error with bad specification, got=%v", got)
+	}
+}