Add crosslink tidylist command (#642)

* Add `crosslink tidy` command

* Applied suggestions and added test

* Fixed linting and license check

* Enable schedule validation in test

* Renamed "tidy" to "tidylist"

---------

Co-authored-by: Pablo Baeyens <[email protected]>

.chloggen/crosslink-tidy-v1.yaml

@@ -0,0 +1,16 @@
+# 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. crosslink)
+component: crosslink
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adds a 'tidy' subcommand to generate 'go mod tidy' schedules
+
+# One or more tracking issues related to the change
+issues: [642]
+
+# (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:

crosslink/README.md

@@ -162,3 +162,13 @@ for out-dated intra-repository Go modules.
  Go version applied when new `go.work` file is created (default "1.22").
 
     crosslink work --go=1.23
+
+### tidylist
+
+The 'tidylist' command generates a sequence of intra-repository modules, such that
+running 'go mod tidy' on each module in this sequence guarantees that changes
+in the 'go.mod' of one module will be propagated to all of its dependent
+modules. This ensures that no modules are left in a broken 'updates to go.mod
+needed' state at the end. For an acyclic dependency graph, this corresponds to
+topological order. If modules are found to have circular dependencies, they will
+be checked against a provided allowlist.

crosslink/cmd/root.go

@@ -29,12 +29,13 @@ import (
 )
 
 type commandConfig struct {
-	runConfig    cl.RunConfig
-	excludeFlags []string
-	skipFlags    []string
-	rootCommand  cobra.Command
-	pruneCommand cobra.Command
-	workCommand  cobra.Command
+	runConfig       cl.RunConfig
+	excludeFlags    []string
+	skipFlags       []string
+	rootCommand     cobra.Command
+	pruneCommand    cobra.Command
+	workCommand     cobra.Command
+	tidyListCommand cobra.Command
 }
 
 func newCommandConfig() *commandConfig {
@@ -118,6 +119,23 @@ func newCommandConfig() *commandConfig {
 	}
 	c.rootCommand.AddCommand(&c.workCommand)
 
+	c.tidyListCommand = cobra.Command{
+		Use:   "tidylist output_path",
+		Short: "Generate a schedule of modules to tidy that guarantees full propagation of changes",
+		Long: "The 'tidylist' command generates a sequence of intra-repository modules, such that\n" +
+			"running 'go mod tidy' on each module in this sequence guarantees that changes\n" +
+			"in the 'go.mod' of one module will be propagated to all of its dependent\n" +
+			"modules. This ensures that no modules are left in a broken 'updates to go.mod\n" +
+			"needed' state at the end. For an acyclic dependency graph, this corresponds to\n" +
+			"topological order. If modules are found to have circular dependencies, they will\n" +
+			"be checked against a provided allowlist.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			return cl.TidyList(c.runConfig, args[0])
+		},
+	}
+	c.rootCommand.AddCommand(&c.tidyListCommand)
+
 	return c
 }
 
@@ -146,6 +164,8 @@ func init() {
 	comCfg.pruneCommand.Flags().StringSliceVar(&comCfg.excludeFlags, "exclude", []string{}, "list of comma separated go modules that crosslink will ignore in operations."+
 		"multiple calls of --exclude can be made")
 	comCfg.workCommand.Flags().StringVar(&comCfg.runConfig.GoVersion, "go", "1.22", "Go version applied when new go.work file is created")
+	comCfg.tidyListCommand.Flags().StringVar(&comCfg.runConfig.AllowCircular, "allow-circular", "", "path to list of go modules that are allowed to have circular dependencies")
+	comCfg.tidyListCommand.Flags().BoolVar(&comCfg.runConfig.Validate, "validate", false, "enables brute force validation of the tidy schedule")
 }
 
 // transform array slice into map

crosslink/internal/common.go

@@ -76,3 +76,26 @@ func forGoModules(logger *zap.Logger, rootPath string, fn func(path string) erro
 		return fn(path)
 	})
 }
+
+func forGoModFiles(rc RunConfig, fn func(modPath string, modName string, modFile *modfile.File) error) error {
+	return forGoModules(rc.Logger, rc.RootPath, func(path string) error {
+		if _, ok := rc.SkippedPaths[path]; ok {
+			rc.Logger.Debug("skipping", zap.String("path", path))
+			return nil
+		}
+		fullPath := filepath.Join(rc.RootPath, path)
+		modFile, err := os.ReadFile(filepath.Clean(fullPath))
+		if err != nil {
+			return fmt.Errorf("failed to read file: %w", err)
+		}
+
+		modContents, err := modfile.Parse(fullPath, modFile, nil)
+		if err != nil {
+			rc.Logger.Error("Modfile could not be parsed",
+				zap.Error(err),
+				zap.String("file_path", path))
+		}
+
+		return fn(path, modfile.ModulePath(modFile), modContents)
+	})
+}

crosslink/internal/config.go

@@ -41,6 +41,8 @@ type RunConfig struct {
 	Overwrite     bool
 	Prune         bool
 	GoVersion     string
+	AllowCircular string
+	Validate      bool
 	Logger        *zap.Logger
 }
 

crosslink/internal/graph.go

@@ -16,11 +16,8 @@ package crosslink
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 
-	"go.uber.org/zap"
 	"golang.org/x/mod/modfile"
 )
 
@@ -30,25 +27,8 @@ import (
 func buildDepedencyGraph(rc RunConfig, rootModulePath string) (map[string]*moduleInfo, error) {
 	moduleMap := make(map[string]*moduleInfo)
 
-	err := forGoModules(rc.Logger, rc.RootPath, func(path string) error {
-		if _, ok := rc.SkippedPaths[path]; ok {
-			rc.Logger.Debug("skipping", zap.String("path", path))
-			return nil
-		}
-		fullPath := filepath.Join(rc.RootPath, path)
-		modFile, err := os.ReadFile(filepath.Clean(fullPath))
-		if err != nil {
-			return fmt.Errorf("failed to read file: %w", err)
-		}
-
-		modContents, err := modfile.Parse(fullPath, modFile, nil)
-		if err != nil {
-			rc.Logger.Error("Modfile could not be parsed",
-				zap.Error(err),
-				zap.String("file_path", path))
-		}
-
-		moduleMap[modfile.ModulePath(modFile)] = newModuleInfo(*modContents)
+	err := forGoModFiles(rc, func(_ string, modPath string, modContents *modfile.File) error {
+		moduleMap[modPath] = newModuleInfo(*modContents)
 		return nil
 	})
 	if err != nil {

crosslink/internal/mock_test_data/testTidyListAcyclic/gomod

@@ -0,0 +1,3 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot
+
+go 1.20

crosslink/internal/mock_test_data/testTidyListAcyclic/testA/gomod

@@ -0,0 +1,5 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testA
+
+go 1.20
+
+require go.opentelemetry.io/build-tools/crosslink/testroot/testB v1.0.0

crosslink/internal/mock_test_data/testTidyListAcyclic/testB/gomod

@@ -0,0 +1,5 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testB
+
+go 1.20
+
+require go.opentelemetry.io/build-tools/crosslink/testroot/testC v1.0.0

crosslink/internal/mock_test_data/testTidyListAcyclic/testC/gomod

@@ -0,0 +1,3 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testC
+
+go 1.20

crosslink/internal/mock_test_data/testTidyListCyclic/allow-circular-overpermissive.txt

@@ -0,0 +1,5 @@
+# This file lists the modules that are expected to have circular dependencies.
+# If it does not match the actual list, `crosslink tidylist` will return an error.
+testA
+testB
+testC

crosslink/internal/mock_test_data/testTidyListCyclic/allow-circular.txt

@@ -0,0 +1,4 @@
+# This file lists the modules that are expected to have circular dependencies.
+# If it does not match the actual list, `crosslink tidylist` will return an error.
+testA
+testB

crosslink/internal/mock_test_data/testTidyListCyclic/gomod

@@ -0,0 +1,3 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot
+
+go 1.20

crosslink/internal/mock_test_data/testTidyListCyclic/testA/gomod

@@ -0,0 +1,5 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testA
+
+go 1.20
+
+require go.opentelemetry.io/build-tools/crosslink/testroot/testB v1.0.0

crosslink/internal/mock_test_data/testTidyListCyclic/testB/gomod

@@ -0,0 +1,6 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testB
+
+go 1.20
+
+require go.opentelemetry.io/build-tools/crosslink/testroot/testA v1.0.0
+require go.opentelemetry.io/build-tools/crosslink/testroot/testC v1.0.0

crosslink/internal/mock_test_data/testTidyListCyclic/testC/gomod

@@ -0,0 +1,3 @@
+module go.opentelemetry.io/build-tools/crosslink/testroot/testC
+
+go 1.20