feat(AIP-123): lint for pattern segments matching the singular.

[toumorokoshi]

From @noahdietz (https://github.com/googleapis/api-linter/pull/1143#discussion_r1187922720)

I think another idea for these annotations, singular and plural is to ensure that they appear in the pattern(s) as the resource_id segment and collectionId segment respectively.

[noahdietz]

@andrei-scripniciuc this would be a good starter rule to work on if you are interested. I'll detail the requirements a bit more in this issue in a bit.

[noahdietz]

Guidance from AIP-123 is as follows:

• Singular must be the lower camel case of the type.
  • Pattern variables must be the singular form of the resource type e.g. a pattern variable representing a Topic resource ID is named {topic}.
• Plural must be the lower camel case plural of the singular.
  • Pattern collection identifier segments must match the plural of the resources...

Given a message with a google.api.resource annotation, ensure the following:

• the plural form is present in all pattern entries as the Collection Identifier
• the singular is present in snake_case form in all pattern entries as the Resource ID variable segment

Example:

message FooBar {
  option (google.api.resource) = {
    type: "foo.googleapis.com/FooBar"
    singular: "fooBar"
    plural: "fooBars"

    // Valid because it contains `fooBars` as the collection ID
    // and {foo_bar} (singular: fooBar -> foo_bar) as the resource ID variable segment
    pattern: "projects/{project}/fooBars/{foo_bar}"

    // Invalid because it doesn't contain `fooBars` and doesn't contain `{foo_bar}`
    pattern: "organizations/{organization}/foobars/{foo_bar_id}"
  }
}

These should be separate rules (this issue I guess was opened for singular), one for each field, and should only be executed if:

• the message is a resource (i.e. has google.api.resource)
• the resource has singular OR plural, respectively

[noahdietz]

@andrei-scripniciuc just remove yourself if you don't have time :)

[noahdietz]

Oh, here is a "demo" PR for adding a new rule: https://github.com/googleapis/api-linter/pull/968/files

Notice that there are markdown files required for documentation.