feat(sidekick): parse discovery doc path templates

internal/sidekick/internal/parser/discovery/uritemplate.go

@@ -0,0 +1,126 @@
+// 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 discovery
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/googleapis/librarian/internal/sidekick/internal/api"
+)
+
+const (
+	beginExpression = '{'
+	endExpression   = '}'
+	slash           = '/'
+)
+
+var (
+	identifierRe = regexp.MustCompile("[A-Za-z][A-Za-z0-9_]*")
+)
+
+// ParseUriTemplate parses a [RFC 6570] URI template as an `api.PathTemplate`.
+//
+// In sidekick we need to capture the structure of the URI template for the
+// codec(s) to emit good templates with them.
+func ParseUriTemplate(uriTemplate string) (*api.PathTemplate, error) {
+	template := &api.PathTemplate{}
+	var pos int
+	for {
+		var err error
+		var segment *api.PathSegment
+		var width int
+
+		if pos == len(uriTemplate) {
+			return nil, fmt.Errorf("expected a segment, found eof: %s", uriTemplate)
+		}
+		if uriTemplate[pos] == beginExpression {
+			segment, width, err = parseExpression(uriTemplate[pos:])
+		} else {
+			segment, width, err = parseLiteral(uriTemplate[pos:])
+		}
+		if err != nil {
+			return nil, err
+		}
+		template.Segments = append(template.Segments, *segment)
+		pos += width
+		if pos == len(uriTemplate) || uriTemplate[pos] != slash {
+			break
+		}
+		pos++ // Skip slash
+	}
+	if pos != len(uriTemplate) {
+		return nil, fmt.Errorf("trailing data (%q) cannot be parsed as a URI template", uriTemplate[pos:])
+	}
+	return template, nil
+}
+
+func parseExpression(input string) (*api.PathSegment, int, error) {
+	if input == "" || input[0] != beginExpression {
+		return nil, 0, fmt.Errorf("missing `{` character in expression %q", input)
+	}
+	tail := input[1:]
+	if strings.IndexAny(tail, "+#") == 0 {
+		return nil, 0, fmt.Errorf("level 2 expressions unsupported input=%q", input)
+	}
+	if strings.IndexAny(tail, "./?&") == 0 {
+		return nil, 0, fmt.Errorf("level 3 expressions unsupported input=%q", input)
+	}
+	if strings.IndexAny(tail, "=,!@|") == 0 {
+		return nil, 0, fmt.Errorf("reserved character on expression %q", input)
+	}
+	match := identifierRe.FindStringIndex(tail)
+	if match[0] != 0 {
+		return nil, 0, fmt.Errorf("no identifier found on expression %q", input)
+	}
+	id := tail[0:match[1]]
+	tail = tail[match[1]:]
+	if tail == "" || tail[0] != endExpression {
+		return nil, 0, fmt.Errorf("missing `}` character at the end of the expression %q", input)
+	}
+	return &api.PathSegment{Variable: api.NewPathVariable(id)}, match[1] + 2, nil
+}
+
+// parseLiteral() extracts a literal value from `input`.
+//
+// The format for literals is defined in:
+//
+//	https://www.rfc-editor.org/rfc/rfc6570.html#section-2.1
+//
+// We simplify the parsing a bit assuming most discovery docs contain valid
+// URI templates.
+func parseLiteral(input string) (*api.PathSegment, int, error) {
+	index := strings.IndexAny(input, " \"'<>\\^`{|}/")
+	var literal string
+	var tail string
+	var width int
+	if index == -1 {
+		literal = input
+		tail = ""
+		width = len(input)
+	} else {
+		literal = input[:index]
+		tail = input[index:]
+		width = index
+	}
+	if literal == "" {
+		return nil, 0, fmt.Errorf("invalid empty literal with input=%q", input)
+	}
+	if tail != "" && tail[0] != slash {
+		return nil, index, fmt.Errorf("found unexpected character %v in literal %q, stopped at position %v", tail[0], input, index)
+	}
+	return &api.PathSegment{Literal: &literal}, width, nil
+}

internal/sidekick/internal/parser/discovery/uritemplate_test.go

@@ -0,0 +1,131 @@
+// 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 discovery
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"github.com/googleapis/librarian/internal/sidekick/internal/api"
+)
+
+func TestParseUriTemplateSuccess(t *testing.T) {
+	for _, test := range []struct {
+		input string
+		want  *api.PathTemplate
+	}{
+		{"locations/global/firewallPolicies", api.NewPathTemplate().WithLiteral("locations").WithLiteral("global").WithLiteral("firewallPolicies")},
+		{"locations/global/operations/{operation}", api.NewPathTemplate().WithLiteral("locations").WithLiteral("global").WithLiteral("operations").WithVariable(api.NewPathVariable("operation"))},
+		{"projects/{project}/zones/{zone}/{parentName}/reservationSubBlocks", api.NewPathTemplate().WithLiteral("projects").WithVariable(api.NewPathVariable("project")).WithLiteral("zones").WithVariable(api.NewPathVariable("zone")).WithVariable(api.NewPathVariable("parentName")).WithLiteral("reservationSubBlocks")},
+	} {
+		got, err := ParseUriTemplate(test.input)
+		if err != nil {
+			t.Errorf("expected a successful parse with input=%s, err=%v", test.input, err)
+			continue
+		}
+		if diff := cmp.Diff(test.want, got, cmpopts.EquateEmpty()); diff != "" {
+			t.Errorf("mismatch [%s] (-want, +got):\n%s", test.input, diff)
+		}
+	}
+}
+
+func TestParseUriTemplateError(t *testing.T) {
+	for _, test := range []struct {
+		input string
+	}{
+		{"v1/{+parent}/externalAccountKeys"},
+		{"a/b/c/"},
+		{"a/b/c|"},
+		{"a/b/{c}|"},
+		{"a/b/{c}}/d"},
+		{"a/b/{c}}"},
+		{"a/b/{c}/"},
+		{"{foo}}bar"},
+	} {
+		if got, err := ParseUriTemplate(test.input); err == nil {
+			t.Errorf("expected a parsing error with input=%s, got=%v", test.input, got)
+		}
+	}
+}
+
+func TestParseExpression(t *testing.T) {
+	for _, test := range []struct {
+		input string
+		want  string
+	}{
+		{"{abc}", "abc"},
+		{"{Abc}", "Abc"},
+		{"{abc012}", "abc012"},
+		{"{abc_012}", "abc_012"},
+		{"{abc_012}/foo/{bar}", "abc_012"},
+	} {
+		gotSegment, gotWidth, err := parseExpression(test.input)
+		if err != nil {
+			t.Errorf("expected a successful parse with input=%s, err=%v", test.input, err)
+			continue
+		}
+		if diff := cmp.Diff(&api.PathSegment{Variable: api.NewPathVariable(test.want)}, gotSegment); diff != "" {
+			t.Errorf("mismatch [%s] (-want, +got):\n%s", test.input, diff)
+		}
+		if len(test.want)+2 != gotWidth {
+			t.Errorf("mismatch want=%d, got=%d", len(test.want), gotWidth)
+		}
+	}
+}
+
+func TestParseExpressionError(t *testing.T) {
+	for _, input := range []string{
+		"", "(a)",
+		"{+a}", "{#a}",
+		"{.a}", "{/a}", "{?a}", "{&a}",
+		"{=a}", "{,a}", "{!a}", "{@a}", "{|a}",
+		"{a,b}", "{_abc}", "{0abc}", "{ab"} {
+		if gotSegment, gotWidth, err := parseExpression(input); err == nil {
+			t.Errorf("expected a parsing error with input=%s, gotSegment=%v, gotWidth=%v", input, gotSegment, gotWidth)
+		}
+	}
+}
+
+func TestParseLiteral(t *testing.T) {
+	for _, test := range []struct {
+		input string
+		want  string
+	}{
+		{"abc/def", "abc"},
+		{"abcde/f", "abcde"},
+		{"abcdef", "abcdef"},
+	} {
+		gotSegment, gotWidth, err := parseLiteral(test.input)
+		if err != nil {
+			t.Errorf("expected a successful parse with input=%s, err=%v", test.input, err)
+			continue
+		}
+		if diff := cmp.Diff(&api.PathSegment{Literal: &test.want}, gotSegment); diff != "" {
+			t.Errorf("mismatch [%s] (-want, +got):\n%s", test.input, diff)
+		}
+		if len(test.want) != gotWidth {
+			t.Errorf("mismatch want=%d, got=%d", len(test.want), gotWidth)
+		}
+	}
+}
+
+func TestParseLiteralError(t *testing.T) {
+	for _, input := range []string{"", "^", "'", "/", "abc^"} {
+		if gotSegment, gotWidth, err := parseLiteral(input); err == nil {
+			t.Errorf("expected a parsing error with input=%s, gotSegment=%v, gotWidth=%v", input, gotSegment, gotWidth)
+		}
+	}
+}