Add API_HYBRID support to resource ref generator (#67369)

The resource ref generator was not properly handling API_HYBRID protobuf
files. When protoc generates code for API_HYBRID protos (configured in
buf-go.gen.yaml), it creates two versions:

1. Regular .pb.go files with exported struct fields (build tag: !protoopaque)
2. _protoopaque.pb.go files with xxx_hidden_* fields (build tag: protoopaque)

The generator was randomly picking up whichever file it encountered first.
When it selected the protoopaque variant, all struct fields were unexported
(starting with xxx_hidden_), causing them to be filtered out during
documentation generation, resulting in empty or incomplete reference pages.

This change adds a filter to skip _protoopaque.pb.go files during the
source code walk, ensuring the generator only processes regular .pb.go
files that contain properly exported fields with full documentation.

This fix enables proper documentation generation for all API_HYBRID
resources, including bot_instance and other protobuf-based resources.

This is a temporary change, we must convert resource geneneration to use
proto as source instead of go structs otherwise we will never be able to migrate
to proto opaque api.

Signed-off-by: Tiago Silva <tiago.silva@goteleport.com>

.github/workflows/lint.yaml

@@ -79,6 +79,8 @@ jobs:
               - 'docs/pages/reference/infrastructure-as-code/terraform-modules/**'
               - 'examples/chart/teleport-cluster/charts/teleport-operator/operator-crds'
               - 'build.assets/tooling/cmd/resource-ref-generator/**'
+              - 'buf-go.gen.yaml'
+              - 'buf.yaml'
             has_ui:
               - '.github/workflows/lint.yaml'
               - 'web/**'

build.assets/tooling/cmd/resource-ref-generator/resource/resource.go

@@ -109,6 +109,14 @@ func NewSourceData(prefix string, rootPath string) (SourceData, error) {
 			return nil
 		}
 
+		// Skip protoopaque files. For API_HYBRID proto files, two versions are
+		// generated: a regular .pb.go with exported fields and a
+		// _protoopaque.pb.go with hidden fields. We only want to document the
+		// regular version with exported fields.
+		if strings.HasSuffix(info.Name(), "_protoopaque.pb.go") {
+			return nil
+		}
+
 		// Find the Go package path corresponding to the current file.
 		rel, err := filepath.Rel(rootPath, currentPath)
 		if err != nil {