github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/cmd/go/internal/mvs/mvs.go (about)

     1  // Copyright 2018 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 mvs implements Minimal Version Selection.
     6  // See https://research.swtch.com/vgo-mvs.
     7  package mvs
     8  
     9  import (
    10  	"golang.org/x/mod/module"
    11  )
    12  
    13  // A Reqs is the requirement graph on which Minimal Version Selection (MVS) operates.
    14  //
    15  // The version strings are opaque except for the special version "none"
    16  // (see the documentation for module.Version). In particular, MVS does not
    17  // assume that the version strings are semantic versions; instead, the Max method
    18  // gives access to the comparison operation.
    19  //
    20  // It must be safe to call methods on a Reqs from multiple goroutines simultaneously.
    21  // Because a Reqs may read the underlying graph from the network on demand,
    22  // the MVS algorithms parallelize the traversal to overlap network delays.
    23  type Reqs interface {
    24  	Required(m module.Version) ([]module.Version, error)
    25  
    26  	Max(p, v1, v2 string) string
    27  }
    28  
    29  // An UpgradeReqs is a Reqs that can also identify available upgrades.
    30  type UpgradeReqs interface {
    31  	Reqs
    32  
    33  	Upgrade(m module.Version) (module.Version, error)
    34  }
    35  
    36  // A DowngradeReqs is a Reqs that can also identify available downgrades.
    37  type DowngradeReqs interface {
    38  	Reqs
    39  
    40  	Previous(m module.Version) (module.Version, error)
    41  }
    42  
    43  // BuildList returns the build list for the target module.
    44  //
    45  // target is the root vertex of a module requirement graph. For cmd/go, this is
    46  // typically the main module, but note that this algorithm is not intended to
    47  // be Go-specific: module paths and versions are treated as opaque values.
    48  //
    49  // reqs describes the module requirement graph and provides an opaque method
    50  // for comparing versions.
    51  //
    52  // BuildList traverses the graph and returns a list containing the highest
    53  // version for each visited module. The first element of the returned list is
    54  // target itself; reqs.Max requires target.Version to compare higher than all
    55  // other versions, so no other version can be selected. The remaining elements
    56  // of the list are sorted by path.
    57  //
    58  // See https://research.swtch.com/vgo-mvs for details.
    59  func BuildList(targets []module.Version, reqs Reqs) ([]module.Version, error)
    60  
    61  // Req returns the minimal requirement list for the target module,
    62  // with the constraint that all module paths listed in base must
    63  // appear in the returned list.
    64  func Req(mainModule module.Version, base []string, reqs Reqs) ([]module.Version, error)
    65  
    66  // UpgradeAll returns a build list for the target module
    67  // in which every module is upgraded to its latest version.
    68  func UpgradeAll(target module.Version, reqs UpgradeReqs) ([]module.Version, error)
    69  
    70  // Upgrade returns a build list for the target module
    71  // in which the given additional modules are upgraded.
    72  func Upgrade(target module.Version, reqs UpgradeReqs, upgrade ...module.Version) ([]module.Version, error)
    73  
    74  // Downgrade returns a build list for the target module
    75  // in which the given additional modules are downgraded,
    76  // potentially overriding the requirements of the target.
    77  //
    78  // The versions to be downgraded may be unreachable from reqs.Latest and
    79  // reqs.Previous, but the methods of reqs must otherwise handle such versions
    80  // correctly.
    81  func Downgrade(target module.Version, reqs DowngradeReqs, downgrade ...module.Version) ([]module.Version, error)