fix(AIP-140): restrict uri naming suggestions to fields with URI in comments (#1541)

* fix(AIP-140): restrict `uri` naming suggestions to fields with URI in comments

AIP-140 was recently updated to clarify that field names may use `url`
when the field can only represent a URL. The current URI lint rule for
AIP-140 will unconditionally discourage using `url` in field names.
This change updates the URI lint rule to be more conservative by only
suggesting renaming the field to use `uri` when the field's comments
use the term URI.

Related update to AIP-140:
aip-dev/google.aip.dev#1551

* Add a test case for a `uri` field with a comment mentioning "URI".

* Add a test case for a `url` field where comment has intra-word "uri" substring

---------

Co-authored-by: Santiago Quiroga <22756465+quirogas@users.noreply.github.com>

Author: stephanemoore

rules/aip0140/uri.go

@@ -15,6 +15,7 @@
 package aip0140
 
 import (
+	"regexp"
 	"strings"
 
 	"bitbucket.org/creachadair/stringset"
@@ -23,18 +24,26 @@ import (
 	"github.com/jhump/protoreflect/desc"
 )
 
+var uriInCommentRegexp = regexp.MustCompile(`\b(uri|URI)\b`)
+
 var uri = &lint.FieldRule{
 	Name: lint.NewRuleName(140, "uri"),
 	LintField: func(f *desc.FieldDescriptor) []lint.Problem {
 		nameSegments := stringset.New(strings.Split(f.GetName(), "_")...)
-		if nameSegments.Contains("url") {
-			return []lint.Problem{{
-				Message:    "Use `uri` instead of `url` in field names.",
-				Descriptor: f,
-				Location:   locations.DescriptorName(f),
-				Suggestion: strings.ReplaceAll(f.GetName(), "url", "uri"),
-			}}
+		if !nameSegments.Contains("url") {
+			return nil
+		}
+
+		comment := f.GetSourceInfo().GetLeadingComments()
+		if !uriInCommentRegexp.MatchString(comment) {
+			return nil
 		}
-		return nil
+
+		return []lint.Problem{{
+			Message:    "Field uses `url` in field name but comment refers to URIs. Use `uri` instead of `url` in field name if field represents a URI.",
+			Descriptor: f,
+			Location:   locations.DescriptorName(f),
+			Suggestion: strings.ReplaceAll(f.GetName(), "url", "uri"),
+		}}
 	},
 }

rules/aip0140/uri_test.go

@@ -23,21 +23,29 @@ import (
 func TestURI(t *testing.T) {
 	for _, test := range []struct {
 		name     string
+		Comment  string
 		Field    string
 		problems testutils.Problems
 	}{
-		{"Valid", "uri", nil},
-		{"ValidPrefix", "uri_foo", nil},
-		{"ValidSuffix", "foo_uri", nil},
-		{"ValidIntermixed", "foo_uri_bar", nil},
-		{"Invalid", "url", testutils.Problems{{Message: "uri", Suggestion: "uri"}}},
-		{"InvalidPrefix", "url_foo", testutils.Problems{{Message: "uri", Suggestion: "uri_foo"}}},
-		{"InvalidSuffix", "foo_url", testutils.Problems{{Message: "uri", Suggestion: "foo_uri"}}},
-		{"InvalidIntermixed", "foo_url_bar", testutils.Problems{{Message: "uri", Suggestion: "foo_uri_bar"}}},
+		{"Valid", "", "uri", nil},
+		{"ValidPrefix", "", "uri_foo", nil},
+		{"ValidSuffix", "", "foo_uri", nil},
+		{"ValidIntermixed", "", "foo_uri_bar", nil},
+		{"ValidWithURIComment", "// A URI.", "uri", nil},
+		{"ValidURL", "", "url", nil},
+		{"ValidURLPrefix", "", "url_foo", nil},
+		{"ValidURLSuffix", "", "foo_url", nil},
+		{"ValidURLIntermixed", "", "foo_url_bar", nil},
+		{"ValidIntraWordURIComment", "// A URL to a curio.", "url", nil},
+		{"Invalid", "// A URI.", "url", testutils.Problems{{Message: "uri", Suggestion: "uri"}}},
+		{"InvalidPrefix", "// A uri.", "url_foo", testutils.Problems{{Message: "uri", Suggestion: "uri_foo"}}},
+		{"InvalidSuffix", "// A URI.", "foo_url", testutils.Problems{{Message: "uri", Suggestion: "foo_uri"}}},
+		{"InvalidIntermixed", "// A uri.", "foo_url_bar", testutils.Problems{{Message: "uri", Suggestion: "foo_uri_bar"}}},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			f := testutils.ParseProto3Tmpl(t, `
 				message Foo {
+				  {{.Comment}}
 					string {{.Field}} = 1;
 				}
 			`, test)