[cmd/builder] Use relative paths in Go module replacements by default (#15098)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
When users want to track their generated OCB directory in source
control, absolute paths don't work because the `go replace` statements
need to resolve on any machine. This PR adds the
`dist::use_relative_replace_paths` feature so that `path` values in
modules are not forcibly resolved to absolute paths and instead
calculated as relative paths to the output directory.

<!-- Issue number if applicable -->
#### Link to tracking issue
Fixes #15097 

<!--Describe what testing was performed and which tests were added.-->
#### Testing
I installed the tool locally and used it in our setup. When I had this
module:
```yaml
exporters:
- gomod: github.com/GoogleCloudPlatform/opentelemetry-operations-collector/components/google-built-opentelemetry-collector/exporter/googleservicecontrolexporter v0.148.0
  path: ../components/google-built-opentelemetry-collector/exporter/googleservicecontrolexporter
```
I got the following replacement:
```
replace github.com/GoogleCloudPlatform/opentelemetry-operations-collector/components/google-built-opentelemetry-collector/exporter/googleservicecontrolexporter v0.148.0 => ../../components/google-built-opentelemetry-collector/exporter/googleservicecontrolexporter
```
I was able to build successfully.

<!--Describe the documentation added.-->
#### Documentation
Added to the config docs in README.

#### AI Usage Disclosure

The code changes in this PR were created with AI assistance via
Gemini/Antigravity.

<!--Please delete paragraphs that you did not use before submitting.-->

Author: braydonk

.chloggen/ocb_relative_replace_paths.yaml

@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/otlp)
+component: cmd/builder
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: In the generated Collector source, the `replace` statements in the Go module will now use relative paths by default.
+
+# One or more tracking issues or pull requests related to the change
+issues: [15097]
+
+# (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: >
+  We expect that this will not break existing use-cases where the generated collector is only used in an interim manner for builds.
+  It enables the possibility of tracking the generated Collector code as a longer living artifact, allowing it to be run on any
+  machine (whereas absolute paths will be different depending on the machine the Collector source is generated on.)
+  We have added `dist::use_absolute_replace_paths` to go back to the absolute path behaviour in the case where there is an
+  unforeseen use-case that requires absolute paths.
+
+# 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: []

cmd/builder/README.md

@@ -160,6 +160,7 @@ dist:
     version: "1.0.0" # the version for your custom OpenTelemetry Collector. Optional.
     go: "/usr/bin/go" # which Go binary to use to compile the generated sources. Optional.
     debug_compilation: false # enabling this causes the builder to keep the debug symbols in the resulting binary. Optional.
+    use_absolute_replace_paths: false # when using local path overrides, uses absolute paths instead of relative paths. Optional.
 exporters:
   - gomod: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter v0.146.0" # the Go module for the component. Required.
     import: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter" # the import path for the component. Optional.

cmd/builder/internal/builder/config.go

@@ -67,15 +67,16 @@ type ConfResolver struct {
 
 // Distribution holds the parameters for the final binary
 type Distribution struct {
-	Module           string `mapstructure:"module,omitempty"`
-	Name             string `mapstructure:"name"`
-	Go               string `mapstructure:"go,omitempty"`
-	Description      string `mapstructure:"description"`
-	OutputPath       string `mapstructure:"output_path"`
-	Version          string `mapstructure:"version,omitempty"`
-	BuildTags        string `mapstructure:"build_tags,omitempty"`
-	DebugCompilation bool   `mapstructure:"debug_compilation,omitempty"`
-	CGoEnabled       bool   `mapstructure:"cgo_enabled,omitempty"`
+	Module                  string `mapstructure:"module,omitempty"`
+	Name                    string `mapstructure:"name"`
+	Go                      string `mapstructure:"go,omitempty"`
+	Description             string `mapstructure:"description"`
+	OutputPath              string `mapstructure:"output_path"`
+	Version                 string `mapstructure:"version,omitempty"`
+	BuildTags               string `mapstructure:"build_tags,omitempty"`
+	DebugCompilation        bool   `mapstructure:"debug_compilation,omitempty"`
+	CGoEnabled              bool   `mapstructure:"cgo_enabled,omitempty"`
+	UseAbsoluteReplacePaths bool   `mapstructure:"use_absolute_replace_paths,omitempty"`
 }
 
 // Module represents a receiver, exporter, processor or extension for the distribution
@@ -171,42 +172,42 @@ func (c *Config) ParseModules() error {
 	var err error
 	usedNames := make(map[string]int)
 
-	c.Extensions, err = parseModules(c.Extensions, usedNames)
+	c.Extensions, err = c.parseModules(c.Extensions, usedNames)
 	if err != nil {
 		return err
 	}
 
-	c.Receivers, err = parseModules(c.Receivers, usedNames)
+	c.Receivers, err = c.parseModules(c.Receivers, usedNames)
 	if err != nil {
 		return err
 	}
 
-	c.Exporters, err = parseModules(c.Exporters, usedNames)
+	c.Exporters, err = c.parseModules(c.Exporters, usedNames)
 	if err != nil {
 		return err
 	}
 
-	c.Processors, err = parseModules(c.Processors, usedNames)
+	c.Processors, err = c.parseModules(c.Processors, usedNames)
 	if err != nil {
 		return err
 	}
 
-	c.Connectors, err = parseModules(c.Connectors, usedNames)
+	c.Connectors, err = c.parseModules(c.Connectors, usedNames)
 	if err != nil {
 		return err
 	}
 
-	telemetry, err := parseModules([]Module{c.Telemetry}, usedNames)
+	telemetry, err := c.parseModules([]Module{c.Telemetry}, usedNames)
 	if err != nil {
 		return err
 	}
 	c.Telemetry = telemetry[0]
 
-	c.ConfmapProviders, err = parseModules(c.ConfmapProviders, usedNames)
+	c.ConfmapProviders, err = c.parseModules(c.ConfmapProviders, usedNames)
 	if err != nil {
 		return err
 	}
-	c.ConfmapConverters, err = parseModules(c.ConfmapConverters, usedNames)
+	c.ConfmapConverters, err = c.parseModules(c.ConfmapConverters, usedNames)
 	if err != nil {
 		return err
 	}
@@ -245,7 +246,7 @@ func validateTelemetry(c *Config) error {
 	return nil
 }
 
-func parseModules(mods []Module, usedNames map[string]int) ([]Module, error) {
+func (c *Config) parseModules(mods []Module, usedNames map[string]int) ([]Module, error) {
 	var parsedModules []Module
 	for _, mod := range mods {
 		if mod.Import == "" {
@@ -275,13 +276,28 @@ func parseModules(mods []Module, usedNames map[string]int) ([]Module, error) {
 		// Check if path is empty, otherwise filepath.Abs replaces it with current path ".".
 		if mod.Path != "" {
 			var err error
-			mod.Path, err = filepath.Abs(mod.Path)
+			absPath, err := filepath.Abs(mod.Path)
 			if err != nil {
-				return mods, fmt.Errorf("module has a relative \"path\" element, but we couldn't resolve the current working dir: %w", err)
+				return mods, fmt.Errorf("failed to resolve absolute path for %s: %w", mod.Path, err)
 			}
-			// Check if the path exists
-			if _, err := os.Stat(mod.Path); os.IsNotExist(err) {
-				return mods, fmt.Errorf("filepath does not exist: %s", mod.Path)
+
+			if c.Distribution.UseAbsoluteReplacePaths {
+				mod.Path = absPath
+			} else {
+				absOutputPath, err := filepath.Abs(c.Distribution.OutputPath)
+				if err != nil {
+					return mods, fmt.Errorf("failed to resolve absolute path for output dir %s: %w", c.Distribution.OutputPath, err)
+				}
+				mod.Path, err = filepath.Rel(absOutputPath, absPath)
+				if err != nil {
+					return mods, fmt.Errorf("failed to make path relative to output dir: %w", err)
+				}
+			}
+			mod.Path = filepath.ToSlash(mod.Path)
+
+			// Check if the path exists using the absolute path
+			if _, err := os.Stat(absPath); os.IsNotExist(err) {
+				return mods, fmt.Errorf("filepath does not exist: %s", absPath)
 			}
 		}
 

cmd/builder/internal/builder/config_test.go

@@ -5,6 +5,7 @@ package builder
 
 import (
 	"os"
+	"path/filepath"
 	"reflect"
 	"strings"
 	"testing"
@@ -171,9 +172,12 @@ func TestInvalidConverter(t *testing.T) {
 	require.Error(t, err, "expected an error when parsing invalid modules")
 }
 
-func TestRelativePath(t *testing.T) {
+func TestAbsoluteReplacePaths(t *testing.T) {
 	// prepare
 	cfg := Config{
+		Distribution: Distribution{
+			UseAbsoluteReplacePaths: true,
+		},
 		Extensions: []Module{{
 			GoMod: "some-module",
 			Path:  "./templates",
@@ -187,7 +191,8 @@ func TestRelativePath(t *testing.T) {
 	// verify
 	cwd, err := os.Getwd()
 	require.NoError(t, err)
-	assert.True(t, strings.HasPrefix(cfg.Extensions[0].Path, cwd))
+	normalizedCwd := filepath.ToSlash(cwd)
+	assert.True(t, strings.HasPrefix(cfg.Extensions[0].Path, normalizedCwd), "expected path %q to have prefix %q", cfg.Extensions[0].Path, normalizedCwd)
 }
 
 func TestModuleFromCore(t *testing.T) {
@@ -397,6 +402,44 @@ func TestSkipsNilFieldValidation(t *testing.T) {
 	assert.NoError(t, cfg.Validate())
 }
 
+func TestParseModulesDefaultRelativePath(t *testing.T) {
+	cfg := Config{
+		Distribution: Distribution{
+			OutputPath: "./output",
+		},
+		Extensions: []Module{{
+			GoMod: "some-module",
+			Path:  "./templates",
+		}},
+	}
+
+	err := cfg.ParseModules()
+	require.NoError(t, err)
+
+	assert.Equal(t, "../templates", cfg.Extensions[0].Path)
+}
+
+func TestParseModulesAbsoluteReplacePathsFlag(t *testing.T) {
+	cfg := Config{
+		Distribution: Distribution{
+			OutputPath:              "./output",
+			UseAbsoluteReplacePaths: true,
+		},
+		Extensions: []Module{{
+			GoMod: "some-module",
+			Path:  "./templates",
+		}},
+	}
+
+	err := cfg.ParseModules()
+	require.NoError(t, err)
+
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	expectedPath := filepath.ToSlash(filepath.Join(cwd, "templates"))
+	assert.Equal(t, expectedPath, cfg.Extensions[0].Path)
+}
+
 func TestIsEmpty(t *testing.T) {
 	for _, tt := range []struct {
 		name  string

cmd/builder/internal/builder/main_test.go

@@ -418,7 +418,7 @@ func TestReplaceStatementsAreComplete(t *testing.T) {
 	// This ensures the resulting go.mod file has maximum coverage of modules
 	// that exist in the Core repository.
 	usedNames := make(map[string]int)
-	cfg.Exporters, err = parseModules([]Module{
+	cfg.Exporters, err = cfg.parseModules([]Module{
 		{
 			GoMod: "go.opentelemetry.io/collector/exporter/debugexporter v1.9999.9999",
 		},
@@ -433,7 +433,7 @@ func TestReplaceStatementsAreComplete(t *testing.T) {
 		},
 	}, usedNames)
 	require.NoError(t, err)
-	cfg.Receivers, err = parseModules([]Module{
+	cfg.Receivers, err = cfg.parseModules([]Module{
 		{
 			GoMod: "go.opentelemetry.io/collector/receiver/nopreceiver v1.9999.9999",
 		},
@@ -442,13 +442,13 @@ func TestReplaceStatementsAreComplete(t *testing.T) {
 		},
 	}, usedNames)
 	require.NoError(t, err)
-	cfg.Extensions, err = parseModules([]Module{
+	cfg.Extensions, err = cfg.parseModules([]Module{
 		{
 			GoMod: "go.opentelemetry.io/collector/extension/zpagesextension v1.9999.9999",
 		},
 	}, usedNames)
 	require.NoError(t, err)
-	cfg.Processors, err = parseModules([]Module{
+	cfg.Processors, err = cfg.parseModules([]Module{
 		{
 			GoMod: "go.opentelemetry.io/collector/processor/batchprocessor v1.9999.9999",
 		},