surfer: Support multiple resource patterns and multitype resources

[quirogas]

The generator currently only considers the first pattern (Patterns[0]) defined for a resource. Many Google Cloud APIs, such as Cloud Logging, define multiple patterns for a single resource to support different parent hierarchies (e.g., Project, Folder, Organization).

Context & Rationale

• Proto Definition: google.api.resource allows multiple pattern strings.

  option (google.api.resource) = {
    type: "logging.googleapis.com/LogSink"
    pattern: "projects/{project}/sinks/{sink}"
    pattern: "organizations/{organization}/sinks/{sink}"
    // ...
  };

• gcloud Schema: The multitype_resource_spec definition allows an argument to resolve against multiple resource collections, generating mutually exclusive parent flags (e.g., --project vs --organization).
• Current Limitation: builder.go hardcodes the selection of the first pattern, making it impossible to generate commands that support the full flexibility of the API.
• AIP-123 & AIP-124 Provide guidance for pattern uniqueness and conventions.

Implementation Considerations

• Detection: Check if len(resource.Patterns) > 1.
• Mapping: Iterate through all patterns. Each pattern corresponds to a distinct gcloud collection path (e.g., logging.projects.sinks, logging.organizations.sinks).
• Generation:
  • If multiple patterns exist, construct a multitype_resource_spec.
  • Populate its resources list with a resource_spec for each pattern.
  • Ensure attributes (like project, organization) are correctly derived for each sub-spec.
• Dispatch Pattern Alignment:: Issue refactor(internal/python): replace command mocks and add GitHub action #3365 should be taken into consideration when designing a pattern for this feature.

Relevant files

• internal/surfer/gcloud/builder.go
• gcloud_command_schema.yaml