Add crosslink tidylist command

.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
+
+### tidy
+
+The 'tidy' 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

@@ -35,6 +35,7 @@
 	rootCommand  cobra.Command
 	pruneCommand cobra.Command
 	workCommand  cobra.Command
+	tidyCommand  cobra.Command
 }
 
 func newCommandConfig() *commandConfig {
@@ -118,6 +119,23 @@
 	}
 	c.rootCommand.AddCommand(&c.workCommand)
 
+	c.tidyCommand = cobra.Command{
+		Use:   "tidy output_path",
+		Short: "Generate a schedule of modules to tidy that guarantees full propagation of changes",
+		Long: "The 'tidy' 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.Tidy(c.runConfig, args[0])
+		},
+	}
+	c.rootCommand.AddCommand(&c.tidyCommand)
+
 	return c
 }
 
@@ -146,6 +164,8 @@
 	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.tidyCommand.Flags().StringVar(&comCfg.runConfig.AllowCircular, "allow-circular", "", "path to list of go modules that are allowed to have circular dependencies")
+	comCfg.tidyCommand.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 @@
 		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/tidy.go

@@ -0,0 +1,204 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package crosslink
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+
+	"go.uber.org/zap"
+	"golang.org/x/mod/modfile"
+)
+
+type graphNode struct {
+	file    *modfile.File
+	path    string
+	name    string
+	deps    []string
+	index   int
+	sccRoot int
+	onStack bool
+}
+
+func Tidy(rc RunConfig, outputPath string) error {
+	rc.Logger.Debug("crosslink run config", zap.Any("run_config", rc))
+
+	rootModule, err := identifyRootModule(rc.RootPath)
+	if err != nil {
+		return fmt.Errorf("failed to identify root module: %w", err)
+	}
+
+	// Read circular dependency allowlist
+
+	var allowCircular []string
+	if rc.AllowCircular != "" {
+		var file *os.File
+		file, err = os.Open(rc.AllowCircular)
+		if err != nil {
+			return fmt.Errorf("failed to open cicular dependency allowlist: %w", err)
+		}
+		defer file.Close()
+		scanner := bufio.NewScanner(file)
+		for scanner.Scan() {
+			line := scanner.Text()
+			if line != "" {
+				allowCircular = append(allowCircular, line)
+			}
+		}
+		if err = scanner.Err(); err != nil {
+			return fmt.Errorf("failed to read cicular dependency allowlist: %w", err)
+		}
+	}
+
+	// Read intra-repository dependency graph
+
+	graph := make(map[string]*graphNode)
+	var modsAlpha []string
+	err = forGoModFiles(rc, func(filePath string, name string, file *modfile.File) error {
+		if !strings.HasPrefix(name, rootModule) {
+			rc.Logger.Debug("ignoring module outside root module namespace", zap.String("mod_name", name))
+			return nil
+		}
+		modsAlpha = append(modsAlpha, name)
+		modPath, _ := strings.CutSuffix(filePath, "/go.mod")
+		graph[name] = &graphNode{
+			file:    file,
+			path:    modPath,
+			name:    name,
+			deps:    nil,
+			index:   -1,
+			sccRoot: -1,
+			onStack: false,
+		}
+		return nil
+	})
+	if err != nil {
+		return fmt.Errorf("failed during file walk: %w", err)
+	}
+
+	for _, deps := range graph {
+		for _, req := range deps.file.Require {
+			if _, ok := graph[req.Mod.Path]; ok {
+				deps.deps = append(deps.deps, req.Mod.Path)
+			}
+		}
+	}
+
+	rc.Logger.Debug("read module graph", zap.Int("mod_cnt", len(graph)))
+
+	// Compute tidying schedule
+	// We use Tarjan's algorithm to identify the topological order of strongly-
+	// connected components of the graph, then apply a naive solution to each.
+
+	var modsTopo []string
+	nextIdx := 0
+	unauthorizedRec := false
+	var stack []*graphNode
+
+	var visit func(mod *graphNode)
+	visit = func(mod *graphNode) {
+		mod.index = nextIdx
+		mod.sccRoot = nextIdx
+		nextIdx++
+		stack = append(stack, mod)
+		mod.onStack = true
+
+		for _, mod2Name := range mod.deps {
+			mod2 := graph[mod2Name]
+			if mod2.index == -1 {
+				visit(mod2)
+			} else if !mod2.onStack {
+				continue
+			}
+			mod.sccRoot = min(mod.sccRoot, mod2.sccRoot)
+		}
+
+		if mod.index == mod.sccRoot {
+			var scc []string
+			for {
+				mod2 := stack[len(stack)-1]
+				stack = stack[:len(stack)-1]
+				mod2.onStack = false
+				scc = append(scc, mod2.path)
+				if mod2 == mod {
+					break
+				}
+			}
+			if len(scc) > 1 { // circular dependencies
+				rc.Logger.Debug("found SCC in module graph", zap.Any("scc", scc))
+				for _, mod2 := range scc {
+					if !slices.Contains(allowCircular, mod2) {
+						fmt.Printf("module depends on itself: %s\n", mod2)
+						unauthorizedRec = true
+					}
+				}
+			}
+
+			// Apply a naive solution for each SCC
+			// (quadratic in the number of modules, but optimal for 1 or 2)
+			for i := 0; i < len(scc)-1; i++ {
+				modsTopo = append(modsTopo, scc...)
+			}
+			modsTopo = append(modsTopo, scc[0])
+		}
+	}
+	for _, modName := range modsAlpha {
+		visit(graph[modName])
+	}
+
+	rc.Logger.Debug("computed tidy schedule", zap.Int("schedule_len", len(modsTopo)))
+
+	if unauthorizedRec {
+		return fmt.Errorf("circular dependencies were found that are not allowlisted")
+	}
+
+	// Writing out schedule
+	err = os.WriteFile(outputPath, []byte(strings.Join(modsTopo, "\n")), 0600)
+	if err != nil {
+		return fmt.Errorf("failed to write tidy schedule file: %w", err)
+	}
+
+	if rc.Validate {
+		// Check validity of solution
+		// (iterate over possible paths and check they are all subsequences of modsTopo)
+
+		var queue [][]string
+		for _, modName := range modsAlpha {
+			queue = append(queue, []string{modName})
+		}
+		for len(queue) > 0 {
+			path := queue[0]
+			queue = queue[1:]
+			i := 0
+			for _, modName := range path {
+				i = slices.Index(path[i:], modName)
+				if i == -1 {
+					return fmt.Errorf("tidy schedule is invalid; changes may not be propagated along path: %v", path)
+				}
+			}
+			for _, dep := range graph[path[0]].deps {
+				if !slices.Contains(path, dep) {
+					path2 := slices.Clone(path)
+					queue = append(queue, slices.Insert(path2, 0, dep))
+				}
+			}
+		}
+	}
+
+	return nil
+}