feat(internal/surfer): improve standard behaviors autogeneration

[quirogas]

Improve dynamic generation of gcloud command collection paths and standard command behaviors. Previously, the generator relied on hardcoded service prefixes and missed critical configurations for standard AIP patterns, leading to incorrect request.collection paths for new services and incomplete command definitions.

This PR addresses these issues by:

1. List Command Output: Automatically generating output.format tables for List commands.
   • Note on differences: The generated table includes all top-level scalar fields and timestamps from the resource message to ensure maximum data visibility by default. This differs from existing manually curated surfaces where columns are often selectively hidden or reordered for specific CLI UX preferences.
2. Custom Method Configuration: deriving the request.method directly from the AIP-136 HTTP custom verb (e.g., :backup) rather than the RPC name. This fixes invocation errors where gcloud would attempt to call a method like backupInstance instead of backup.
3. Async Configuration: Implementing robust defaults for LROs. It dynamically derives the operations collection (AIP-151) from the resource's parent path and toggles extract_resource_result based on whether the operation returns the resource itself (Create/Update) or just metadata.

Changes

internal/surfer/gcloud/builder.go

• Dynamic Collection Paths:

  • Introduced newCollectionPath to dynamically construct request.collection and async.collection by parsing AIP-127 HTTP annotations.
  • Replaced hardcoded service prefixes (e.g., parallelstore.) with dynamic extraction from service.DefaultHost.
  • Implemented logic to strip API versions (v1) and handle complex variables (e.g., {name=projects/*/locations/*/instances/*}) via extractPathFromSegments.
  • Async: Automatically derives async.collection by identifying the resource parent and appending .operations (AIP-151), replacing static defaults.

• Standard Command Behaviors:

  • Output Format: Added newOutputConfig and newFormat to automatically generate table(...) output formats for List commands. It recursively inspects the response message to include all top-level scalar fields and timestamps, ensuring useful default output tables.
  • Custom Request Methods: Refactored newRequest to prioritize the custom HTTP verb (AIP-136, e.g., :backup) over the RPC name. This ensures generated request.method values match the backend expectations (e.g., backup vs backupInstance).
  • Async Extraction: Updated newAsync with a heuristic to set extract_resource_result: true when the LRO's response_type matches the method's resource type, enabling polling behavior for Create/Update operations.

internal/surfer/gcloud/builder_test.go

• Added TestNewCollectionPath to validate path generation across various scenarios:
  • Regional vs. Global resources.
  • Complex path variables ({name=...}).
  • List methods (collection parent logic).
• Added TestNewOutputConfig to verify table format generation from message fields.

internal/surfer/gcloud/command.go

• Removed omitempty tag from ExtractResourceResult to ensure explicit boolean values are generated in the YAML, as expected by the gcloud framework for LROs.

internal/surfer/gcloud/utils/method.go & method_test.go

• Added IsStandardMethod and IsCustomMethod helpers to support cleaner dispatch logic in the builder.
• Added unit tests for method classification.

Fixes #3290, #3649

[gemini-code-assist]

Code Review

This pull request significantly improves the autogeneration of gcloud command configurations by dynamically deriving collection paths, output formats for list commands, and async behavior for LROs, leveraging AIP annotations. A critical security concern, aligning with the rule to sanitize inputs for code generation templates, has been identified: a potential DSL injection vulnerability in the new newFormat and newTable functions due to unsanitized field names from API definitions, which could manipulate CLI output. There are also existing path traversal and code injection points in generate.go that rely on unsanitized strings. It is strongly recommended to sanitize all field names and conduct a comprehensive security audit of the entire generator for safe handling of strings derived from external API definitions. Minor code clarity improvements were also suggested.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.35%. Comparing base (9d04c44) to head (9470406).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3914   +/-   ##
=======================================
  Coverage   83.35%   83.35%           
=======================================
  Files          69       69           
  Lines        6188     6188           
=======================================
  Hits         5158     5158           
  Misses        671      671           
  Partials      359      359           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.