[cmd/mdatagen]: Improve loading errors for clarity (open-telemetry#13206)

#### Description
Expose `go list -f` stderr if the command fails.

<!-- Issue number if applicable -->
#### Link to tracking issue
Fixes open-telemetry#13205

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Manual, unit tests

<!--Describe the documentation added.-->
#### Documentation
No new docs required

Author: jeffalder

.chloggen/alder_improve-mdatagen-errors.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'enhancement'
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Taught mdatagen to print the `go list` stderr output on failures, and to run `go list` where the metadata file is."
+
+# One or more tracking issues or pull requests related to the change
+issues: [13205]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

cmd/mdatagen/internal/command_test.go

@@ -199,6 +199,8 @@ func TestRunContents(t *testing.T) {
 			require.NoError(t, err)
 			metadataFile := filepath.Join(tmpdir, "metadata.yaml")
 			require.NoError(t, os.WriteFile(metadataFile, ymlContent, 0o600))
+			require.NoError(t, os.WriteFile(filepath.Join(tmpdir, "empty.go"), []byte("package shortname"), 0o600))
+			require.NoError(t, os.WriteFile(filepath.Join(tmpdir, "go.mod"), []byte("module shortname"), 0o600))
 			require.NoError(t, os.WriteFile(filepath.Join(tmpdir, "README.md"), []byte(`
 <!-- status autogenerated section -->
 foo

cmd/mdatagen/internal/loader.go

@@ -5,6 +5,8 @@ package internal // import "go.opentelemetry.io/collector/cmd/mdatagen/internal"
 
 import (
 	"context"
+	"errors"
+	"fmt"
 	"os/exec"
 	"path/filepath"
 	"strings"
@@ -42,7 +44,7 @@ func LoadMetadata(filePath string) (Metadata, error) {
 		return md, err
 	}
 	if md.ScopeName == "" {
-		md.ScopeName, err = packageName()
+		md.ScopeName, err = packageName(filepath.Dir(filePath))
 		if err != nil {
 			return md, err
 		}
@@ -80,11 +82,17 @@ func shortFolderName(filePath string) string {
 	return parentFolder
 }
 
-func packageName() (string, error) {
+func packageName(filePath string) (string, error) {
 	cmd := exec.Command("go", "list", "-f", "{{.ImportPath}}")
+	cmd.Dir = filePath
 	output, err := cmd.Output()
 	if err != nil {
-		return "", err
+		var ee *exec.ExitError
+		if errors.As(err, &ee) {
+			return "", fmt.Errorf("unable to determine package name: %v failed: (stderr) %v", cmd.Args, string(ee.Stderr))
+		}
+
+		return "", fmt.Errorf("unable to determine package name: %v failed: %v %w", cmd.Args, string(output), err)
 	}
 	return strings.TrimSpace(string(output)), nil
 }

cmd/mdatagen/internal/loader_test.go

@@ -4,6 +4,8 @@
 package internal
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -13,6 +15,22 @@ import (
 	"go.opentelemetry.io/collector/pdata/pmetric"
 )
 
+func TestTwoPackagesInDirectory(t *testing.T) {
+	contents, err := os.ReadFile("testdata/twopackages.yaml")
+	require.NoError(t, err)
+	tempDir := t.TempDir()
+	metadataPath := filepath.Join(tempDir, "metadata.yaml")
+	// we create a trivial module and packages to avoid having invalid go checked into our test directory.
+	require.NoError(t, os.WriteFile(filepath.Join(tempDir, "go.mod"), []byte("module twopackages"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(tempDir, "package1.go"), []byte("package package1"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(tempDir, "package2.go"), []byte("package package2"), 0o600))
+	require.NoError(t, os.WriteFile(metadataPath, contents, 0o600))
+
+	_, err = LoadMetadata(metadataPath)
+	require.Error(t, err)
+	require.ErrorContains(t, err, "unable to determine package name: [go list -f {{.ImportPath}}] failed: (stderr) found packages package1 (package1.go) and package2 (package2.go)")
+}
+
 func TestLoadMetadata(t *testing.T) {
 	tests := []struct {
 		name    string
@@ -348,7 +366,7 @@ func TestLoadMetadata(t *testing.T) {
 				Type:                 "subcomponent",
 				Parent:               "parentComponent",
 				GeneratedPackageName: "metadata",
-				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal",
+				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata",
 				ShortFolderName:      "testdata",
 				Tests:                Tests{Host: "componenttest.NewNopHost()"},
 			},
@@ -358,7 +376,7 @@ func TestLoadMetadata(t *testing.T) {
 			want: Metadata{
 				Type:                 "custom",
 				GeneratedPackageName: "customname",
-				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal",
+				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata",
 				ShortFolderName:      "testdata",
 				Tests:                Tests{Host: "componenttest.NewNopHost()"},
 				Status: &Status{
@@ -376,7 +394,7 @@ func TestLoadMetadata(t *testing.T) {
 			want: Metadata{
 				Type:                 "test",
 				GeneratedPackageName: "metadata",
-				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal",
+				ScopeName:            "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata",
 				ShortFolderName:      "testdata",
 				Tests:                Tests{Host: "componenttest.NewNopHost()"},
 				Status: &Status{
@@ -422,13 +440,17 @@ func TestLoadMetadata(t *testing.T) {
 			want:    Metadata{},
 			wantErr: "decoding failed due to the following error(s):\n\nerror decoding 'attributes[used_attr].type': invalid type: \"invalidtype\"",
 		},
+		{
+			name:    "testdata/~~this file doesn't exist~~.yaml",
+			wantErr: "unable to read the file file:testdata/~~this file doesn't exist~~.yaml",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got, err := LoadMetadata(tt.name)
 			if tt.wantErr != "" {
 				require.Error(t, err)
-				require.EqualError(t, err, tt.wantErr)
+				require.ErrorContains(t, err, tt.wantErr)
 			} else {
 				require.NoError(t, err)
 				require.Equal(t, tt.want, got)

cmd/mdatagen/internal/testdata/empty.go

@@ -0,0 +1,6 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package testdata
+
+// this file allows `go list -f` to run in tests and get the scope name.

cmd/mdatagen/internal/testdata/events/empty.go

@@ -0,0 +1,6 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package events
+
+// this file allows `go list -f` to run in tests and get the scope name.

cmd/mdatagen/internal/testdata/twopackages.yaml

@@ -0,0 +1,7 @@
+type: sample
+github_project: open-telemetry/opentelemetry-collector
+
+status:
+  class: receiver
+  stability:
+    beta: [traces]