github.com/go-asm/go@v1.21.1-0.20240213172139-40c5ead50c48/cmd/go/modload/edit.go (about)

     1  // Copyright 2021 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package modload
     6  
     7  import (
     8  	"context"
     9  	"errors"
    10  	"fmt"
    11  	"maps"
    12  	"os"
    13  	"slices"
    14  
    15  	"github.com/go-asm/go/cmd/go/cfg"
    16  	"github.com/go-asm/go/cmd/go/gover"
    17  	"github.com/go-asm/go/cmd/go/mvs"
    18  	"github.com/go-asm/go/cmd/go/par"
    19  
    20  	"golang.org/x/mod/module"
    21  )
    22  
    23  // editRequirements returns an edited version of rs such that:
    24  //
    25  //  1. Each module version in mustSelect is selected.
    26  //
    27  //  2. Each module version in tryUpgrade is upgraded toward the indicated
    28  //     version as far as can be done without violating (1).
    29  //     (Other upgrades are also allowed if they are caused by
    30  //     transitive requirements of versions in mustSelect or
    31  //     tryUpgrade.)
    32  //
    33  //  3. Each module version in rs.rootModules (or rs.graph, if rs is unpruned)
    34  //     is downgraded or upgraded from its original version only to the extent
    35  //     needed to satisfy (1) and (2).
    36  //
    37  // Generally, the module versions in mustSelect are due to the module or a
    38  // package within the module matching an explicit command line argument to 'go
    39  // get', and the versions in tryUpgrade are transitive dependencies that are
    40  // either being upgraded by 'go get -u' or being added to satisfy some
    41  // otherwise-missing package import.
    42  //
    43  // If pruning is enabled, the roots of the edited requirements include an
    44  // explicit entry for each module path in tryUpgrade, mustSelect, and the roots
    45  // of rs, unless the selected version for the module path is "none".
    46  func editRequirements(ctx context.Context, rs *Requirements, tryUpgrade, mustSelect []module.Version) (edited *Requirements, changed bool, err error) {
    47  	if rs.pruning == workspace {
    48  		panic("editRequirements cannot edit workspace requirements")
    49  	}
    50  
    51  	orig := rs
    52  	// If we already know what go version we will end up on after the edit, and
    53  	// the pruning for that version is different, go ahead and apply it now.
    54  	//
    55  	// If we are changing from pruned to unpruned, then we MUST check the unpruned
    56  	// graph for conflicts from the start. (Checking only for pruned conflicts
    57  	// would miss some that would be introduced later.)
    58  	//
    59  	// If we are changing from unpruned to pruned, then we would like to avoid
    60  	// unnecessary downgrades due to conflicts that would be pruned out of the
    61  	// final graph anyway.
    62  	//
    63  	// Note that even if we don't find a go version in mustSelect, it is possible
    64  	// that we will switch from unpruned to pruned (but not the other way around!)
    65  	// after applying the edits if we find a dependency that requires a high
    66  	// enough go version to trigger an upgrade.
    67  	rootPruning := orig.pruning
    68  	for _, m := range mustSelect {
    69  		if m.Path == "go" {
    70  			rootPruning = pruningForGoVersion(m.Version)
    71  			break
    72  		} else if m.Path == "toolchain" && pruningForGoVersion(gover.FromToolchain(m.Version)) == unpruned {
    73  			// We don't know exactly what go version we will end up at, but we know
    74  			// that it must be a version supported by the requested toolchain, and
    75  			// that toolchain does not support pruning.
    76  			//
    77  			// TODO(bcmills): 'go get' ought to reject explicit toolchain versions
    78  			// older than gover.GoStrictVersion. Once that is fixed, is this still
    79  			// needed?
    80  			rootPruning = unpruned
    81  			break
    82  		}
    83  	}
    84  
    85  	if rootPruning != rs.pruning {
    86  		rs, err = convertPruning(ctx, rs, rootPruning)
    87  		if err != nil {
    88  			return orig, false, err
    89  		}
    90  	}
    91  
    92  	// selectedRoot records the edited version (possibly "none") for each module
    93  	// path that would be a root in the edited requirements.
    94  	var selectedRoot map[string]string // module path → edited version
    95  	if rootPruning == pruned {
    96  		selectedRoot = maps.Clone(rs.maxRootVersion)
    97  	} else {
    98  		// In a module without graph pruning, modules that provide packages imported
    99  		// by the main module may either be explicit roots or implicit transitive
   100  		// dependencies. To the extent possible, we want to preserve those implicit
   101  		// dependencies, so we need to treat everything in the build list as
   102  		// potentially relevant — that is, as what would be a “root” in a module
   103  		// with graph pruning enabled.
   104  		mg, err := rs.Graph(ctx)
   105  		if err != nil {
   106  			// If we couldn't load the graph, we don't know what its requirements were
   107  			// to begin with, so we can't edit those requirements in a coherent way.
   108  			return orig, false, err
   109  		}
   110  		bl := mg.BuildList()[MainModules.Len():]
   111  		selectedRoot = make(map[string]string, len(bl))
   112  		for _, m := range bl {
   113  			selectedRoot[m.Path] = m.Version
   114  		}
   115  	}
   116  
   117  	for _, r := range tryUpgrade {
   118  		if v, ok := selectedRoot[r.Path]; ok && gover.ModCompare(r.Path, v, r.Version) >= 0 {
   119  			continue
   120  		}
   121  		if cfg.BuildV {
   122  			fmt.Fprintf(os.Stderr, "go: trying upgrade to %v\n", r)
   123  		}
   124  		selectedRoot[r.Path] = r.Version
   125  	}
   126  
   127  	// conflicts is a list of conflicts that we cannot resolve without violating
   128  	// some version in mustSelect. It may be incomplete, but we want to report
   129  	// as many conflicts as we can so that the user can solve more of them at once.
   130  	var conflicts []Conflict
   131  
   132  	// mustSelectVersion is an index of the versions in mustSelect.
   133  	mustSelectVersion := make(map[string]string, len(mustSelect))
   134  	for _, r := range mustSelect {
   135  		if v, ok := mustSelectVersion[r.Path]; ok && v != r.Version {
   136  			prev := module.Version{Path: r.Path, Version: v}
   137  			if gover.ModCompare(r.Path, v, r.Version) > 0 {
   138  				conflicts = append(conflicts, Conflict{Path: []module.Version{prev}, Constraint: r})
   139  			} else {
   140  				conflicts = append(conflicts, Conflict{Path: []module.Version{r}, Constraint: prev})
   141  			}
   142  			continue
   143  		}
   144  
   145  		mustSelectVersion[r.Path] = r.Version
   146  		selectedRoot[r.Path] = r.Version
   147  	}
   148  
   149  	// We've indexed all of the data we need and we've computed the initial
   150  	// versions of the roots. Now we need to load the actual module graph and
   151  	// restore the invariant that every root is the selected version of its path.
   152  	//
   153  	// For 'go mod tidy' we would do that using expandGraph, which upgrades the
   154  	// roots until their requirements are internally consistent and then drops out
   155  	// the old roots. However, here we need to do more: we also need to make sure
   156  	// the modules in mustSelect don't get upgraded above their intended versions.
   157  	// To do that, we repeatedly walk the module graph, identify paths of
   158  	// requirements that result in versions that are too high, and downgrade the
   159  	// roots that lead to those paths. When no conflicts remain, we're done.
   160  	//
   161  	// Since we want to report accurate paths to each conflict, we don't drop out
   162  	// older-than-selected roots until the process completes. That might mean that
   163  	// we do some extra downgrades when they could be skipped, but for the benefit
   164  	// of being able to explain the reason for every downgrade that seems
   165  	// worthwhile.
   166  	//
   167  	// Graph pruning adds an extra wrinkle: a given node in the module graph
   168  	// may be reached from a root whose dependencies are pruned, and from a root
   169  	// whose dependencies are not pruned. It may be the case that the path from
   170  	// the unpruned root leads to a conflict, while the path from the pruned root
   171  	// prunes out the requirements that would lead to that conflict.
   172  	// So we need to track the two kinds of paths independently.
   173  	// They join back together at the roots of the graph: if a root r1 with pruned
   174  	// requirements depends on a root r2 with unpruned requirements, then
   175  	// selecting r1 would cause r2 to become a root and pull in all of its
   176  	// unpruned dependencies.
   177  	//
   178  	// The dqTracker type implements the logic for propagating conflict paths
   179  	// through the pruned and unpruned parts of the module graph.
   180  	//
   181  	// We make a best effort to fix incompatibilities, subject to two properties:
   182  	//
   183  	// 	1. If the user runs 'go get' with a set of mutually-compatible module
   184  	// 	versions, we should accept those versions.
   185  	//
   186  	// 	2. If we end up upgrading or downgrading a module, it should be
   187  	// 	clear why we did so.
   188  	//
   189  	// We don't try to find an optimal SAT solution,
   190  	// especially given the complex interactions with graph pruning.
   191  
   192  	var (
   193  		roots      []module.Version // the current versions in selectedRoot, in sorted order
   194  		rootsDirty = true           // true if roots does not match selectedRoot
   195  	)
   196  
   197  	// rejectedRoot records the set of module versions that have been disqualified
   198  	// as roots of the module graph. When downgrading due to a conflict or error,
   199  	// we skip any version that has already been rejected.
   200  	//
   201  	// NOTE(bcmills): I am not sure that the rejectedRoot map is really necessary,
   202  	// since we normally only downgrade roots or accept indirect upgrades to
   203  	// known-good versions. However, I am having trouble proving that accepting an
   204  	// indirect upgrade never introduces a conflict that leads to further
   205  	// downgrades. I really want to be able to prove that editRequirements
   206  	// terminates, and the easiest way to prove it is to add this map.
   207  	//
   208  	// Then the proof of termination is this:
   209  	// On every iteration where we mark the roots as dirty, we add some new module
   210  	// version to the map. The universe of module versions is finite, so we must
   211  	// eventually reach a state in which we do not add any version to the map.
   212  	// In that state, we either report a conflict or succeed in the edit.
   213  	rejectedRoot := map[module.Version]bool{}
   214  
   215  	for rootsDirty && len(conflicts) == 0 {
   216  		roots = roots[:0]
   217  		for p, v := range selectedRoot {
   218  			if v != "none" {
   219  				roots = append(roots, module.Version{Path: p, Version: v})
   220  			}
   221  		}
   222  		gover.ModSort(roots)
   223  
   224  		// First, we extend the graph so that it includes the selected version
   225  		// of every root. The upgraded roots are in addition to the original
   226  		// roots, so we will have enough information to trace a path to each
   227  		// conflict we discover from one or more of the original roots.
   228  		mg, upgradedRoots, err := extendGraph(ctx, rootPruning, roots, selectedRoot)
   229  		if err != nil {
   230  			var tooNew *gover.TooNewError
   231  			if mg == nil || errors.As(err, &tooNew) {
   232  				return orig, false, err
   233  			}
   234  			// We're about to walk the entire extended module graph, so we will find
   235  			// any error then — and we will either try to resolve it by downgrading
   236  			// something or report it as a conflict with more detail.
   237  		}
   238  
   239  		// extendedRootPruning is an index of the pruning used to load each root in
   240  		// the extended module graph.
   241  		extendedRootPruning := make(map[module.Version]modPruning, len(roots)+len(upgradedRoots))
   242  		findPruning := func(m module.Version) modPruning {
   243  			if rootPruning == pruned {
   244  				summary, _ := mg.loadCache.Get(m)
   245  				if summary != nil && summary.pruning == unpruned {
   246  					return unpruned
   247  				}
   248  			}
   249  			return rootPruning
   250  		}
   251  		for _, m := range roots {
   252  			extendedRootPruning[m] = findPruning(m)
   253  		}
   254  		for m := range upgradedRoots {
   255  			extendedRootPruning[m] = findPruning(m)
   256  		}
   257  
   258  		// Now check the resulting extended graph for errors and incompatibilities.
   259  		t := dqTracker{extendedRootPruning: extendedRootPruning}
   260  		mg.g.WalkBreadthFirst(func(m module.Version) {
   261  			if max, ok := mustSelectVersion[m.Path]; ok && gover.ModCompare(m.Path, m.Version, max) > 0 {
   262  				// m itself violates mustSelect, so it cannot appear in the module graph
   263  				// even if its transitive dependencies would be pruned out.
   264  				t.disqualify(m, pruned, dqState{dep: m})
   265  				return
   266  			}
   267  
   268  			summary, err := mg.loadCache.Get(m)
   269  			if err != nil && err != par.ErrCacheEntryNotFound {
   270  				// We can't determine the requirements of m, so we don't know whether
   271  				// they would be allowed. This may be a transient error reaching the
   272  				// repository, rather than a permanent error with the retrieved version.
   273  				//
   274  				// TODO(golang.org/issue/31730, golang.org/issue/30134):
   275  				// decide what to do based on the actual error.
   276  				t.disqualify(m, pruned, dqState{err: err})
   277  				return
   278  			}
   279  
   280  			reqs, ok := mg.RequiredBy(m)
   281  			if !ok {
   282  				// The dependencies of m do not appear in the module graph, so they
   283  				// can't be causing any problems this time.
   284  				return
   285  			}
   286  
   287  			if summary == nil {
   288  				if m.Version != "" {
   289  					panic(fmt.Sprintf("internal error: %d reqs present for %v, but summary is nil", len(reqs), m))
   290  				}
   291  				// m is the main module: we are editing its dependencies, so it cannot
   292  				// become disqualified.
   293  				return
   294  			}
   295  
   296  			// Before we check for problems due to transitive dependencies, first
   297  			// check m's direct requirements. A requirement on a version r that
   298  			// violates mustSelect disqualifies m, even if the requirements of r are
   299  			// themselves pruned out.
   300  			for _, r := range reqs {
   301  				if max, ok := mustSelectVersion[r.Path]; ok && gover.ModCompare(r.Path, r.Version, max) > 0 {
   302  					t.disqualify(m, pruned, dqState{dep: r})
   303  					return
   304  				}
   305  			}
   306  			for _, r := range reqs {
   307  				if !t.require(m, r) {
   308  					break
   309  				}
   310  			}
   311  		})
   312  
   313  		// We have now marked all of the versions in the graph that have conflicts,
   314  		// with a path to each conflict from one or more roots that introduce it.
   315  		// Now we need to identify those roots and change their versions
   316  		// (if possible) in order to resolve the conflicts.
   317  		rootsDirty = false
   318  		for _, m := range roots {
   319  			path, err := t.path(m, extendedRootPruning[m])
   320  			if len(path) == 0 && err == nil {
   321  				continue // Nothing wrong with m; we can keep it.
   322  			}
   323  
   324  			// path leads to a module with a problem: either it violates a constraint,
   325  			// or some error prevents us from determining whether it violates a
   326  			// constraint. We might end up logging or returning the conflict
   327  			// information, so go ahead and fill in the details about it.
   328  			conflict := Conflict{
   329  				Path: path,
   330  				Err:  err,
   331  			}
   332  			if err == nil {
   333  				var last module.Version = path[len(path)-1]
   334  				mustV, ok := mustSelectVersion[last.Path]
   335  				if !ok {
   336  					fmt.Fprintf(os.Stderr, "go: %v\n", conflict)
   337  					panic("internal error: found a version conflict, but no constraint it violates")
   338  				}
   339  				conflict.Constraint = module.Version{
   340  					Path:    last.Path,
   341  					Version: mustV,
   342  				}
   343  			}
   344  
   345  			if v, ok := mustSelectVersion[m.Path]; ok && v == m.Version {
   346  				// m is in mustSelect, but is marked as disqualified due to a transitive
   347  				// dependency.
   348  				//
   349  				// In theory we could try removing module paths that don't appear in
   350  				// mustSelect (added by tryUpgrade or already present in rs) in order to
   351  				// get graph pruning to take effect, but (a) it is likely that 'go mod
   352  				// tidy' would re-add those roots and reintroduce unwanted upgrades,
   353  				// causing confusion, and (b) deciding which roots to try to eliminate
   354  				// would add a lot of complexity.
   355  				//
   356  				// Instead, we report the path to the conflict as an error.
   357  				// If users want to explicitly prune out nodes from the dependency
   358  				// graph, they can always add an explicit 'exclude' directive.
   359  				conflicts = append(conflicts, conflict)
   360  				continue
   361  			}
   362  
   363  			// If m is not the selected version of its path, we have two options: we
   364  			// can either upgrade to the version that actually is selected (dropping m
   365  			// itself out of the bottom of the module graph), or we can try
   366  			// downgrading it.
   367  			//
   368  			// If the version we would be upgrading to is ok to use, we will just plan
   369  			// to do that and avoid the overhead of trying to find some lower version
   370  			// to downgrade to.
   371  			//
   372  			// However, it is possible that m depends on something that leads to its
   373  			// own upgrade, so if the upgrade isn't viable we should go ahead and try
   374  			// to downgrade (like with any other root).
   375  			if v := mg.Selected(m.Path); v != m.Version {
   376  				u := module.Version{Path: m.Path, Version: v}
   377  				uPruning, ok := t.extendedRootPruning[m]
   378  				if !ok {
   379  					fmt.Fprintf(os.Stderr, "go: %v\n", conflict)
   380  					panic(fmt.Sprintf("internal error: selected version of root %v is %v, but it was not expanded as a new root", m, u))
   381  				}
   382  				if !t.check(u, uPruning).isDisqualified() && !rejectedRoot[u] {
   383  					// Applying the upgrade from m to u will resolve the conflict,
   384  					// so plan to do that if there are no other conflicts to resolve.
   385  					continue
   386  				}
   387  			}
   388  
   389  			// Figure out what version of m's path was present before we started
   390  			// the edit. We want to make sure we consider keeping it as-is,
   391  			// even if it wouldn't normally be included. (For example, it might
   392  			// be a pseudo-version or pre-release.)
   393  			origMG, _ := orig.Graph(ctx)
   394  			origV := origMG.Selected(m.Path)
   395  
   396  			if conflict.Err != nil && origV == m.Version {
   397  				// This version of m.Path was already in the module graph before we
   398  				// started editing, and the problem with it is that we can't load its
   399  				// (transitive) requirements.
   400  				//
   401  				// If this conflict was just one step in a longer chain of downgrades,
   402  				// then we would want to keep going past it until we find a version
   403  				// that doesn't have that problem. However, we only want to downgrade
   404  				// away from an *existing* requirement if we can confirm that it actually
   405  				// conflicts with mustSelect. (For example, we don't want
   406  				// 'go get -u ./...' to incidentally downgrade some dependency whose
   407  				// go.mod file is unavailable or has a bad checksum.)
   408  				conflicts = append(conflicts, conflict)
   409  				continue
   410  			}
   411  
   412  			// We need to downgrade m's path to some lower version to try to resolve
   413  			// the conflict. Find the next-lowest candidate and apply it.
   414  			rejectedRoot[m] = true
   415  			prev := m
   416  			for {
   417  				prev, err = previousVersion(ctx, prev)
   418  				if gover.ModCompare(m.Path, m.Version, origV) > 0 && (gover.ModCompare(m.Path, prev.Version, origV) < 0 || err != nil) {
   419  					// previousVersion skipped over origV. Insert it into the order.
   420  					prev.Version = origV
   421  				} else if err != nil {
   422  					// We don't know the next downgrade to try. Give up.
   423  					return orig, false, err
   424  				}
   425  				if rejectedRoot[prev] {
   426  					// We already rejected prev in a previous round.
   427  					// To ensure that this algorithm terminates, don't try it again.
   428  					continue
   429  				}
   430  				pruning := rootPruning
   431  				if pruning == pruned {
   432  					if summary, err := mg.loadCache.Get(m); err == nil {
   433  						pruning = summary.pruning
   434  					}
   435  				}
   436  				if t.check(prev, pruning).isDisqualified() {
   437  					// We found a problem with prev this round that would also disqualify
   438  					// it as a root. Don't bother trying it next round.
   439  					rejectedRoot[prev] = true
   440  					continue
   441  				}
   442  				break
   443  			}
   444  			selectedRoot[m.Path] = prev.Version
   445  			rootsDirty = true
   446  
   447  			// If this downgrade is potentially interesting, log the reason for it.
   448  			if conflict.Err != nil || cfg.BuildV {
   449  				var action string
   450  				if prev.Version == "none" {
   451  					action = fmt.Sprintf("removing %s", m)
   452  				} else if prev.Version == origV {
   453  					action = fmt.Sprintf("restoring %s", prev)
   454  				} else {
   455  					action = fmt.Sprintf("trying %s", prev)
   456  				}
   457  				fmt.Fprintf(os.Stderr, "go: %s\n\t%s\n", conflict.Summary(), action)
   458  			}
   459  		}
   460  		if rootsDirty {
   461  			continue
   462  		}
   463  
   464  		// We didn't resolve any issues by downgrading, but we may still need to
   465  		// resolve some conflicts by locking in upgrades. Do that now.
   466  		//
   467  		// We don't do these upgrades until we're done downgrading because the
   468  		// downgrade process might reveal or remove conflicts (by changing which
   469  		// requirement edges are pruned out).
   470  		var upgradedFrom []module.Version // for logging only
   471  		for p, v := range selectedRoot {
   472  			if _, ok := mustSelectVersion[p]; !ok {
   473  				if actual := mg.Selected(p); actual != v {
   474  					if cfg.BuildV {
   475  						upgradedFrom = append(upgradedFrom, module.Version{Path: p, Version: v})
   476  					}
   477  					selectedRoot[p] = actual
   478  					// Accepting the upgrade to m.Path might cause the selected versions
   479  					// of other modules to fall, because they were being increased by
   480  					// dependencies of m that are no longer present in the graph.
   481  					//
   482  					// TODO(bcmills): Can removing m as a root also cause the selected
   483  					// versions of other modules to rise? I think not: we're strictly
   484  					// removing non-root nodes from the module graph, which can't cause
   485  					// any root to decrease (because they're roots), and the dependencies
   486  					// of non-roots don't matter because they're either always unpruned or
   487  					// always pruned out.
   488  					//
   489  					// At any rate, it shouldn't cost much to reload the module graph one
   490  					// last time and confirm that it is stable.
   491  					rootsDirty = true
   492  				}
   493  			}
   494  		}
   495  		if rootsDirty {
   496  			if cfg.BuildV {
   497  				gover.ModSort(upgradedFrom) // Make logging deterministic.
   498  				for _, m := range upgradedFrom {
   499  					fmt.Fprintf(os.Stderr, "go: accepting indirect upgrade from %v to %s\n", m, selectedRoot[m.Path])
   500  				}
   501  			}
   502  			continue
   503  		}
   504  		break
   505  	}
   506  	if len(conflicts) > 0 {
   507  		return orig, false, &ConstraintError{Conflicts: conflicts}
   508  	}
   509  
   510  	if rootPruning == unpruned {
   511  		// An unpruned go.mod file lists only a subset of the requirements needed
   512  		// for building packages. Figure out which requirements need to be explicit.
   513  		var rootPaths []string
   514  
   515  		// The modules in mustSelect are always promoted to be explicit.
   516  		for _, m := range mustSelect {
   517  			if m.Version != "none" && !MainModules.Contains(m.Path) {
   518  				rootPaths = append(rootPaths, m.Path)
   519  			}
   520  		}
   521  
   522  		for _, m := range roots {
   523  			if v, ok := rs.rootSelected(m.Path); ok && (v == m.Version || rs.direct[m.Path]) {
   524  				// m.Path was formerly a root, and either its version hasn't changed or
   525  				// we believe that it provides a package directly imported by a package
   526  				// or test in the main module. For now we'll assume that it is still
   527  				// relevant enough to remain a root. If we actually load all of the
   528  				// packages and tests in the main module (which we are not doing here),
   529  				// we can revise the explicit roots at that point.
   530  				rootPaths = append(rootPaths, m.Path)
   531  			}
   532  		}
   533  
   534  		roots, err = mvs.Req(MainModules.mustGetSingleMainModule(), rootPaths, &mvsReqs{roots: roots})
   535  		if err != nil {
   536  			return nil, false, err
   537  		}
   538  	}
   539  
   540  	changed = rootPruning != orig.pruning || !slices.Equal(roots, orig.rootModules)
   541  	if !changed {
   542  		// Because the roots we just computed are unchanged, the entire graph must
   543  		// be the same as it was before. Save the original rs, since we have
   544  		// probably already loaded its requirement graph.
   545  		return orig, false, nil
   546  	}
   547  
   548  	// A module that is not even in the build list necessarily cannot provide
   549  	// any imported packages. Mark as direct only the direct modules that are
   550  	// still in the build list. (We assume that any module path that provided a
   551  	// direct import before the edit continues to do so after. There are a few
   552  	// edge cases where that can change, such as if a package moves into or out of
   553  	// a nested module or disappears entirely. If that happens, the user can run
   554  	// 'go mod tidy' to clean up the direct/indirect annotations.)
   555  	//
   556  	// TODO(bcmills): Would it make more sense to leave the direct map as-is
   557  	// but allow it to refer to modules that are no longer in the build list?
   558  	// That might complicate updateRoots, but it may be cleaner in other ways.
   559  	direct := make(map[string]bool, len(rs.direct))
   560  	for _, m := range roots {
   561  		if rs.direct[m.Path] {
   562  			direct[m.Path] = true
   563  		}
   564  	}
   565  	edited = newRequirements(rootPruning, roots, direct)
   566  
   567  	// If we ended up adding a dependency that upgrades our go version far enough
   568  	// to activate pruning, we must convert the edited Requirements in order to
   569  	// avoid dropping transitive dependencies from the build list the next time
   570  	// someone uses the updated go.mod file.
   571  	//
   572  	// Note that it isn't possible to go in the other direction (from pruned to
   573  	// unpruned) unless the "go" or "toolchain" module is explicitly listed in
   574  	// mustSelect, which we already handled at the very beginning of the edit.
   575  	// That is because the virtual "go" module only requires a "toolchain",
   576  	// and the "toolchain" module never requires anything else, which means that
   577  	// those two modules will never be downgraded due to a conflict with any other
   578  	// constraint.
   579  	if rootPruning == unpruned {
   580  		if v, ok := edited.rootSelected("go"); ok && pruningForGoVersion(v) == pruned {
   581  			// Since we computed the edit with the unpruned graph, and the pruned
   582  			// graph is a strict subset of the unpruned graph, this conversion
   583  			// preserves the exact (edited) build list that we already computed.
   584  			//
   585  			// However, it does that by shoving the whole build list into the roots of
   586  			// the graph. 'go get' will check for that sort of transition and log a
   587  			// message reminding the user how to clean up this mess we're about to
   588  			// make. 😅
   589  			edited, err = convertPruning(ctx, edited, pruned)
   590  			if err != nil {
   591  				return orig, false, err
   592  			}
   593  		}
   594  	}
   595  	return edited, true, nil
   596  }
   597  
   598  // extendGraph loads the module graph from roots, and iteratively extends it by
   599  // unpruning the selected version of each module path that is a root in rs or in
   600  // the roots slice until the graph reaches a fixed point.
   601  //
   602  // The graph is guaranteed to converge to a fixed point because unpruning a
   603  // module version can only increase (never decrease) the selected versions,
   604  // and the set of versions for each module is finite.
   605  //
   606  // The extended graph is useful for diagnosing version conflicts: for each
   607  // selected module version, it can provide a complete path of requirements from
   608  // some root to that version.
   609  func extendGraph(ctx context.Context, rootPruning modPruning, roots []module.Version, selectedRoot map[string]string) (mg *ModuleGraph, upgradedRoot map[module.Version]bool, err error) {
   610  	for {
   611  		mg, err = readModGraph(ctx, rootPruning, roots, upgradedRoot)
   612  		// We keep on going even if err is non-nil until we reach a steady state.
   613  		// (Note that readModGraph returns a non-nil *ModuleGraph even in case of
   614  		// errors.) The caller may be able to fix the errors by adjusting versions,
   615  		// so we really want to return as complete a result as we can.
   616  
   617  		if rootPruning == unpruned {
   618  			// Everything is already unpruned, so there isn't anything we can do to
   619  			// extend it further.
   620  			break
   621  		}
   622  
   623  		nPrevRoots := len(upgradedRoot)
   624  		for p := range selectedRoot {
   625  			// Since p is a root path, when we fix up the module graph to be
   626  			// consistent with the selected versions, p will be promoted to a root,
   627  			// which will pull in its dependencies. Ensure that its dependencies are
   628  			// included in the module graph.
   629  			v := mg.g.Selected(p)
   630  			if v == "none" {
   631  				// Version “none” always has no requirements, so it doesn't need
   632  				// an explicit node in the module graph.
   633  				continue
   634  			}
   635  			m := module.Version{Path: p, Version: v}
   636  			if _, ok := mg.g.RequiredBy(m); !ok && !upgradedRoot[m] {
   637  				// The dependencies of the selected version of p were not loaded.
   638  				// Mark it as an upgrade so that we will load its dependencies
   639  				// in the next iteration.
   640  				//
   641  				// Note that we don't remove any of the existing roots, even if they are
   642  				// no longer the selected version: with graph pruning in effect this may
   643  				// leave some spurious dependencies in the graph, but it at least
   644  				// preserves enough of the graph to explain why each upgrade occurred:
   645  				// this way, we can report a complete path from the passed-in roots
   646  				// to every node in the module graph.
   647  				//
   648  				// This process is guaranteed to reach a fixed point: since we are only
   649  				// adding roots (never removing them), the selected version of each module
   650  				// can only increase, never decrease, and the set of module versions in the
   651  				// universe is finite.
   652  				if upgradedRoot == nil {
   653  					upgradedRoot = make(map[module.Version]bool)
   654  				}
   655  				upgradedRoot[m] = true
   656  			}
   657  		}
   658  		if len(upgradedRoot) == nPrevRoots {
   659  			break
   660  		}
   661  	}
   662  
   663  	return mg, upgradedRoot, err
   664  }
   665  
   666  type perPruning[T any] struct {
   667  	pruned   T
   668  	unpruned T
   669  }
   670  
   671  func (pp perPruning[T]) from(p modPruning) T {
   672  	if p == unpruned {
   673  		return pp.unpruned
   674  	}
   675  	return pp.pruned
   676  }
   677  
   678  // A dqTracker tracks and propagates the reason that each module version
   679  // cannot be included in the module graph.
   680  type dqTracker struct {
   681  	// extendedRootPruning is the modPruning given the go.mod file for each root
   682  	// in the extended module graph.
   683  	extendedRootPruning map[module.Version]modPruning
   684  
   685  	// dqReason records whether and why each each encountered version is
   686  	// disqualified in a pruned or unpruned context.
   687  	dqReason map[module.Version]perPruning[dqState]
   688  
   689  	// requiring maps each not-yet-disqualified module version to the versions
   690  	// that would cause that module's requirements to be included in a pruned or
   691  	// unpruned context. If that version becomes disqualified, the
   692  	// disqualification will be propagated to all of the versions in the
   693  	// corresponding list.
   694  	//
   695  	// This map is similar to the module requirement graph, but includes more
   696  	// detail about whether a given dependency edge appears in a pruned or
   697  	// unpruned context. (Other commands do not need this level of detail.)
   698  	requiring map[module.Version][]module.Version
   699  }
   700  
   701  // A dqState indicates whether and why a module version is “disqualified” from
   702  // being used in a way that would incorporate its requirements.
   703  //
   704  // The zero dqState indicates that the module version is not known to be
   705  // disqualified, either because it is ok or because we are currently traversing
   706  // a cycle that includes it.
   707  type dqState struct {
   708  	err error          // if non-nil, disqualified because the requirements of the module could not be read
   709  	dep module.Version // disqualified because the module is or requires dep
   710  }
   711  
   712  func (dq dqState) isDisqualified() bool {
   713  	return dq != dqState{}
   714  }
   715  
   716  func (dq dqState) String() string {
   717  	if dq.err != nil {
   718  		return dq.err.Error()
   719  	}
   720  	if dq.dep != (module.Version{}) {
   721  		return dq.dep.String()
   722  	}
   723  	return "(no conflict)"
   724  }
   725  
   726  // require records that m directly requires r, in case r becomes disqualified.
   727  // (These edges are in the opposite direction from the edges in an mvs.Graph.)
   728  //
   729  // If r is already disqualified, require propagates the disqualification to m
   730  // and returns the reason for the disqualification.
   731  func (t *dqTracker) require(m, r module.Version) (ok bool) {
   732  	rdq := t.dqReason[r]
   733  	rootPruning, isRoot := t.extendedRootPruning[r]
   734  	if isRoot && rdq.from(rootPruning).isDisqualified() {
   735  		// When we pull in m's dependencies, we will have an edge from m to r, and r
   736  		// is disqualified (it is a root, which causes its problematic dependencies
   737  		// to always be included). So we cannot pull in m's dependencies at all:
   738  		// m is completely disqualified.
   739  		t.disqualify(m, pruned, dqState{dep: r})
   740  		return false
   741  	}
   742  
   743  	if dq := rdq.from(unpruned); dq.isDisqualified() {
   744  		t.disqualify(m, unpruned, dqState{dep: r})
   745  		if _, ok := t.extendedRootPruning[m]; !ok {
   746  			// Since m is not a root, its dependencies can't be included in the pruned
   747  			// part of the module graph, and will never be disqualified from a pruned
   748  			// reason. We've already disqualified everything that matters.
   749  			return false
   750  		}
   751  	}
   752  
   753  	// Record that m is a dependant of r, so that if r is later disqualified
   754  	// m will be disqualified as well.
   755  	if t.requiring == nil {
   756  		t.requiring = make(map[module.Version][]module.Version)
   757  	}
   758  	t.requiring[r] = append(t.requiring[r], m)
   759  	return true
   760  }
   761  
   762  // disqualify records why the dependencies of m cannot be included in the module
   763  // graph if reached from a part of the graph with the given pruning.
   764  //
   765  // Since the pruned graph is a subgraph of the unpruned graph, disqualifying a
   766  // module from a pruned part of the graph also disqualifies it in the unpruned
   767  // parts.
   768  func (t *dqTracker) disqualify(m module.Version, fromPruning modPruning, reason dqState) {
   769  	if !reason.isDisqualified() {
   770  		panic("internal error: disqualify called with a non-disqualifying dqState")
   771  	}
   772  
   773  	dq := t.dqReason[m]
   774  	if dq.from(fromPruning).isDisqualified() {
   775  		return // Already disqualified for some other reason; don't overwrite it.
   776  	}
   777  	rootPruning, isRoot := t.extendedRootPruning[m]
   778  	if fromPruning == pruned {
   779  		dq.pruned = reason
   780  		if !dq.unpruned.isDisqualified() {
   781  			// Since the pruned graph of m is a subgraph of the unpruned graph, if it
   782  			// is disqualified due to something in the pruned graph, it is certainly
   783  			// disqualified in the unpruned graph from the same reason.
   784  			dq.unpruned = reason
   785  		}
   786  	} else {
   787  		dq.unpruned = reason
   788  		if dq.pruned.isDisqualified() {
   789  			panic(fmt.Sprintf("internal error: %v is marked as disqualified when pruned, but not when unpruned", m))
   790  		}
   791  		if isRoot && rootPruning == unpruned {
   792  			// Since m is a root that is always unpruned, any other roots — even
   793  			// pruned ones! — that cause it to be selected would also cause the reason
   794  			// for is disqualification to be included in the module graph.
   795  			dq.pruned = reason
   796  		}
   797  	}
   798  	if t.dqReason == nil {
   799  		t.dqReason = make(map[module.Version]perPruning[dqState])
   800  	}
   801  	t.dqReason[m] = dq
   802  
   803  	if isRoot && (fromPruning == pruned || rootPruning == unpruned) {
   804  		// Either m is disqualified even when its dependencies are pruned,
   805  		// or m's go.mod file causes its dependencies to *always* be unpruned.
   806  		// Everything that depends on it must be disqualified.
   807  		for _, p := range t.requiring[m] {
   808  			t.disqualify(p, pruned, dqState{dep: m})
   809  			// Note that since the pruned graph is a subset of the unpruned graph,
   810  			// disqualifying p in the pruned graph also disqualifies it in the
   811  			// unpruned graph.
   812  		}
   813  		// Everything in t.requiring[m] is now fully disqualified.
   814  		// We won't need to use it again.
   815  		delete(t.requiring, m)
   816  		return
   817  	}
   818  
   819  	// Either m is not a root, or it is a pruned root but only being disqualified
   820  	// when reached from the unpruned parts of the module graph.
   821  	// Either way, the reason for this disqualification is only visible to the
   822  	// unpruned parts of the module graph.
   823  	for _, p := range t.requiring[m] {
   824  		t.disqualify(p, unpruned, dqState{dep: m})
   825  	}
   826  	if !isRoot {
   827  		// Since m is not a root, its dependencies can't be included in the pruned
   828  		// part of the module graph, and will never be disqualified from a pruned
   829  		// reason. We've already disqualified everything that matters.
   830  		delete(t.requiring, m)
   831  	}
   832  }
   833  
   834  // check reports whether m is disqualified in the given pruning context.
   835  func (t *dqTracker) check(m module.Version, pruning modPruning) dqState {
   836  	return t.dqReason[m].from(pruning)
   837  }
   838  
   839  // path returns the path from m to the reason it is disqualified, which may be
   840  // either a module that violates constraints or an error in loading
   841  // requirements.
   842  //
   843  // If m is not disqualified, path returns (nil, nil).
   844  func (t *dqTracker) path(m module.Version, pruning modPruning) (path []module.Version, err error) {
   845  	for {
   846  		dq := t.dqReason[m].from(pruning)
   847  		if !dq.isDisqualified() {
   848  			return path, nil
   849  		}
   850  		path = append(path, m)
   851  		if dq.err != nil || dq.dep == m {
   852  			return path, dq.err // m itself is the conflict.
   853  		}
   854  		m = dq.dep
   855  	}
   856  }