package main

Import Path
	go.pact.im/x/goupdate (on go.dev)

Dependency Relation
	imports 16 packages, and imported by 0 packages

Involved Source Files

	      diff.go
	      download.go
	      flags.go
	      htmlgen.go
	#m #d main.go
		Goupdate is a tool for updating Go module dependencies. It is supports Go
		workspaces and is an alternative to running go get -t -u that attempts to
		be less conservative and produces apidiff reports.

		Warning

		Note that goupdate loops until there are no updates available in the build
		graph. This may be inefficient but should be good enough in practice.

		Module dependencies are updated in-place and may leave workspace in broken
		state on failure. Use with extreme caution if there are unsaved changes. It
		is recommended to run goupdate as part of the scheduled CI pipeline instead.

		CI

		Integrating goupdate with GitHub Actions or other CI solutions that support
		scheduled pipelines should be straightforward and only requires Go toolchain
		to be installed. Goupdate can generate HTML reports (that can be embedded in
		Markdown) with overview of updated modules and API changes. It can also run
		tests and includes results in the generated reports. Test failures are
		intended to be reviewed by humans and so do not cause goupdate to exit with
		non-zero status code.

		Motivation

		Goupdate was written after fighting with dependabot storming repositories
		with pull requests per dependency update per module in workspace. In addition
		to that, dependabot does not support updating modules with pseudo-versions
		like golang.org/x/crypto which does not publish semver-tagged releases, see
		https://github.com/dependabot/dependabot-core/issues/3017. It also does not
		support Go workspaces which we use extensively since their introduction in
		Go 1.18.

	      modules.go
	      packages.go
	      report.go
	      tests.go
	      textgen.go
	      upgrade.go
	      workspaces.go
Package-Level Type Names (total 13, none are exported)

	/* sort exporteds by: alphabet | popularity */
	/* 13 unexporteds ... *//* 13 unexporteds: */
	 type downloadedModule (struct)

		Fields (total 9, all are exported)
			Dir string
				// absolute path to cached source root directory

			Error string
				// error loading module

			GoMod string
				// absolute path to cached .mod file

			GoModSum string
				// checksum for go.mod (as in go.sum)

			Info string
				// absolute path to cached .info file

			Path string
				// module path

			Sum string
				// checksum for path, version (as in go.sum)

			Version string
				// module version

			Zip string
				// absolute path to cached .zip file

		As Outputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func queryUpgrades(workspaceDir string, modulePaths []string) ([]downloadedModule, error)
			func queryUpgradesCached(workspaceDir string, deps []string, cache map[string]downloadedModule) ([]downloadedModule, error)
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func queryUpgradesCached(workspaceDir string, deps []string, cache map[string]downloadedModule) ([]downloadedModule, error)

	 type flags (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			goVersion string
			outFormat string
			outPath string
			runTests string
			testShort bool
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func parseFlags(args []string) (*flags, error)
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func generateReport(f *flags, r *report) error
			func runTests(f *flags, w *workspace) (*testReport, error)

	 type htmlGenerator (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			docsURL string
			w io.Writer
		Methods (total 39, none are exported)
			/* 39 unexporteds ... *//* 39 unexporteds: */
			(*htmlGenerator) emptyModuleDetails(m packages.Module, prefix string) error
			(*htmlGenerator) html(tag string, attrNames []string, attrValues map[string]string, body func() error, closeTag bool) error
			(*htmlGenerator) htmlAnchor(href string, body func() error) error
			(*htmlGenerator) htmlAnchorText(href, s string) error
			(*htmlGenerator) htmlCodeText(s string) error
			(*htmlGenerator) htmlDetails(body func() error) error
			(*htmlGenerator) htmlHeaderText(s string) error
			(*htmlGenerator) htmlHorizontalRule() error
			(*htmlGenerator) htmlListItem(body func() error) error
			(*htmlGenerator) htmlPreSamp(body func() error) error
			(*htmlGenerator) htmlPreSampText(s string) error
			(*htmlGenerator) htmlSummary(body func() error) error
			(*htmlGenerator) htmlSummaryText(s string) error
			(*htmlGenerator) htmlUnorderedList(body func() error) error
			(*htmlGenerator) listItemPackageWithErrors(pkg *packages.Package) error
			(*htmlGenerator) listModules(prefix string, modules []packages.Module) error
			(*htmlGenerator) listPackageDiffs(changes []packageDiff) error
			(*htmlGenerator) listPackages(header string, pkgs []*packages.Package) error
			(*htmlGenerator) moduleUpgradeSummary(modulePath, oldVersion, newVersion string, unchanged bool) error
			(*htmlGenerator) visitModuleDiff(d moduleDiff) error
			(*htmlGenerator) visitModuleDiffAdded(pkgs []*packages.Package) error
			(*htmlGenerator) visitModuleDiffChanged(changes []packageDiff) error
			(*htmlGenerator) visitModuleDiffNewBroken(pkgs []*packages.Package) error
			(*htmlGenerator) visitModuleDiffOldBroken(pkgs []*packages.Package) error
			(*htmlGenerator) visitModuleDiffRemoved(pkgs []*packages.Package) error
			(*htmlGenerator) visitPackageDiff(d packageDiff) error
			(*htmlGenerator) visitReport(r *report) error
			(*htmlGenerator) visitStateDiff(s stateDiff) error
			(*htmlGenerator) visitStateDiffAdded(modules []packages.Module) error
			(*htmlGenerator) visitStateDiffRemoved(modules []packages.Module) error
			(*htmlGenerator) visitStateDiffUpdated(updated []moduleDiff) error
			(*htmlGenerator) visitTestReport(t *testReport) error
			(*htmlGenerator) visitTestReportDecode(decodeError error, buffer []byte) error
			(*htmlGenerator) visitTestReportEvents(events []testEvent) error
			(*htmlGenerator) visitTestReportFailed(failed, decodeError bool) error
			(*htmlGenerator) visitTestReportStderr(stderr []byte) error
			(*htmlGenerator) writeBytes(s []byte) error
			(*htmlGenerator) writeRawString(s string) error
			(*htmlGenerator) writeString(s string) error

	 type moduleDiff (struct)

		Fields (total 8, all are exported)
			Added []*packages.Package
				Added is a list of added packages.

			Changed []packageDiff
				Changed is a list of changed packages.

			New packages.Module
				New is the new module.

			NewBroken []*packages.Package
				OldBroken is a list of broken packages in the new version.

			Old packages.Module
				Old is the old module.

			OldBroken []*packages.Package
				OldBroken is a list of broken packages in the old version.

			Path string
				Path is the module path of the updated module.

			Removed []*packages.Package
				Added is a list of removed packages.

		Methods (only one, which is exported)
			(*moduleDiff) Unchanged() bool
				Unchanged returns true if there are no changes except for the version bump.


	 type packageDiff (struct)

		Fields (total 4, all are exported)
			Diff apidiff.Report
				Diff contains API changes report.

			New *packages.Package
				New is the old package.

			Old *packages.Package
				Old is the old package.

			Path string
				Path is the package import path from the updated module.

		Methods (total 3, in which 2 are exported)
			(*packageDiff) Compatible() []apidiff.Change
			(*packageDiff) Incompatible() []apidiff.Change
			/* one unexported ... *//* one unexported: */
			(*packageDiff) changes(compat bool) []apidiff.Change

	 type report (struct)

		Fields (total 2, both are exported)
			State stateDiff
			Tests *testReport
		As Inputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func generateHTML(w io.Writer, r *report) error
			func generateReport(f *flags, r *report) error
			func generateText(w io.Writer, r *report) error

	 type sectionIndentWriter (struct)

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			indent io.Writer
			pre []byte
			wr io.Writer
		Methods (total 3, in which 2 are exported)
			(*sectionIndentWriter) Section(f func() error) error
			(*sectionIndentWriter) Write(p []byte) (int, error)
			/* one unexported ... *//* one unexported: */
			(*sectionIndentWriter) writer() io.Writer
		Implements (at least one exported)
			*sectionIndentWriter : io.Writer
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newSectionIndentWriter(wr io.Writer, pre string) *sectionIndentWriter

	 type state (struct)

		Fields (total 3, all are exported)
			ByModule map[string][]*packages.Package
			ModuleByPath map[string]packages.Module
			Modules []packages.Module
		As Outputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func loadState(workspaceDir string, patterns ...string) (*state, error)
			func stateFromPacakges(pkgs []*packages.Package) *state
			func upgradeModules(w *workspace, s *state) (*state, error)
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func diffState(prev, final *state) stateDiff
			func upgradeModules(w *workspace, s *state) (*state, error)

	 type stateDiff (struct)

		Fields (total 3, all are exported)
			Added []packages.Module
				Added is a list of added module dependencies.

			Removed []packages.Module
				Removed is a list of removed module dependencies.

			Updated []moduleDiff
				Updated is a list of updated module dependencies.

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func diffState(prev, final *state) stateDiff

	 type testEvent (struct)

		Fields (total 6, all are exported)
			Action string
			Elapsed float64
				// seconds

			Output *string
				// optional

			Package string
			Test string
			Time time.Time
				// encodes as an RFC3339-format string


	 type testReport (struct)

		Fields (total 5, all are exported)
			Buffer []byte
				// remaining stdout buffer if Decode != nil

			Decode error
				// stdout decoding error

			Events []testEvent
			Failed bool
				// test failed (non-zero exit code)

			Stderr []byte
				// test stderr output

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func runTests(f *flags, w *workspace) (*testReport, error)

	 type textGenerator (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			w *sectionIndentWriter
		Methods (total 29, none are exported)
			/* 29 unexporteds ... *//* 29 unexporteds: */
			(*textGenerator) section(title string, f func() error) error
			(*textGenerator) sectionBrokenPackages(title string, pkgs []*packages.Package) error
			(*textGenerator) sectionModuleDiffPackages(title string, pkgs []*packages.Package) error
			(*textGenerator) sectionPackageDiffChanges(title string, changes []apidiff.Change) error
			(*textGenerator) sectionPackageErrors(title string, errs []packages.Error) error
			(*textGenerator) sectionStateDiffModules(title string, modules []packages.Module) error
			(*textGenerator) visitModuleDiff(d moduleDiff) error
			(*textGenerator) visitModuleDiffAdded(pkgs []*packages.Package) error
			(*textGenerator) visitModuleDiffChanged(changes []packageDiff) error
			(*textGenerator) visitModuleDiffNewBroken(pkgs []*packages.Package) error
			(*textGenerator) visitModuleDiffOldBroken(pkgs []*packages.Package) error
			(*textGenerator) visitModuleDiffRemoved(pkgs []*packages.Package) error
			(*textGenerator) visitPacakgeDiffCompatible(changes []apidiff.Change) error
			(*textGenerator) visitPacakgeDiffIncompatible(changes []apidiff.Change) error
			(*textGenerator) visitPackageDiff(d packageDiff) error
			(*textGenerator) visitReport(r *report) error
			(*textGenerator) visitStateDiff(s stateDiff) error
			(*textGenerator) visitStateDiffAdded(modules []packages.Module) error
			(*textGenerator) visitStateDiffRemoved(modules []packages.Module) error
			(*textGenerator) visitStateDiffUpdated(updates []moduleDiff) error
			(*textGenerator) visitTestReport(t *testReport) error
			(*textGenerator) visitTestReportBuffer(buf []byte) error
			(*textGenerator) visitTestReportDecodeError(decodeError error) error
			(*textGenerator) visitTestReportEvents(events []testEvent, failed bool) error
			(*textGenerator) visitTestReportStderr(buf []byte) error
			(*textGenerator) writeBytes(s []byte) error
			(*textGenerator) writeRawBytes(s []byte) error
			(*textGenerator) writeRawString(s string) error
			(*textGenerator) writeString(s string) error

	 type workspace (struct)

		Fields (total 2, both are exported)
			Dir string
				Dir, if non-empty, is a directory of the Go workspace.

			Paths []string
				Paths is a list of modules in the current workspace. If Dir is empty,
				it contains a single directory for the main module.

		Methods (only one, which is exported)
			(*workspace) Root() string
				Root returns workspace root directory.

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func loadWorkspace() (*workspace, error)
		As Inputs Of (at least 4, none are exported)
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func goworksync(w *workspace) error
			func runTests(f *flags, w *workspace) (*testReport, error)
			func syncWorkspace(w *workspace) error
			func upgradeModules(w *workspace, s *state) (*state, error)


Package-Level Functions (total 32, none are exported)

	/* 32 unexporteds ... *//* 32 unexporteds: */
	 func addGoModRequires(moduleDir string, requires []string) error
	 func collectPackages(pkgs []*packages.Package) []*packages.Package
		collectPackages visits all packages and returns flattened list.

	 func diffState(prev, final *state) stateDiff
		diffState returns the difference in the API between the two workspace states.

	 func generateHTML(w io.Writer, r *report) error
	 func generateReport(f *flags, r *report) error
		generateReport generates the report for the requested flags.

	 func generateText(w io.Writer, r *report) error
	 func goenv(vars ...string) (map[string]string, error)
		goenv returns the given Go environment variables.

	 func goworksync(w *workspace) error
		goworksync removes current go.work.sum file and runs go work sync.

	 func intersectModuleSets(moduleByPath, otherModuleByPath map[string]packages.Module) []string
		intersectModuleSets returns a list of modules that are present in both sets.

	 func intersectPackageSets(pkgByImportPath, otherPkgByImportPath map[string]*packages.Package) []string
		intersectPackageSets returns a list of import paths that are present in both
		sets.

	 func loadGoModVersion(moduleDir string) (string, error)
		loadGoModVersion returns the value of the go directive in go.mod file.

	 func loadPackages(workspaceDir string, patterns ...string) ([]*packages.Package, error)
		loadPackages loads packages from the workspace that match the given pattern.

	 func loadState(workspaceDir string, patterns ...string) (*state, error)
	 func loadWorkspace() (*workspace, error)
	 func log(s string)
	 func main()
	 func modulesNotInSet(modules []packages.Module, moduleByPath map[string]packages.Module) []packages.Module
		modulesNotInSet returns a list of module versions that are not present
		in the moduleByPath set.

	 func must(err error)
	 func newSectionIndentWriter(wr io.Writer, pre string) *sectionIndentWriter
	 func packagesByImportPath(pkgs []*packages.Package) map[string]*packages.Package
		packagesByImportPath groups packages by their import path.

	 func packagesByModule(pkgs []*packages.Package) (map[string][]*packages.Package, map[string]packages.Module)
		packagesByModule groups packages by their containing Go module. It skips
		packages that do not have modules (i.e. stdlib).

	 func packagesNotInSet(pkgs []*packages.Package, pkgByImportPath map[string]*packages.Package) []*packages.Package
		packagesNotInSet returns packages that are not present in the given set.

	 func parseFlags(args []string) (*flags, error)
	 func queryUpgrades(workspaceDir string, modulePaths []string) ([]downloadedModule, error)
	 func queryUpgradesCached(workspaceDir string, deps []string, cache map[string]downloadedModule) ([]downloadedModule, error)
	 func runTests(f *flags, w *workspace) (*testReport, error)
	 func sortedModules(moduleByPath map[string]packages.Module) []packages.Module
		sortedModules returns modules sorted by their module path.

	 func splitBrokenPackages(pkgs []*packages.Package) (good, broken []*packages.Package)
		splitBrokenPackages splits packages into good and broken.

	 func stateFromPacakges(pkgs []*packages.Package) *state
	 func syncWorkspace(w *workspace) error
		syncWorkspace runs go mod tidy and go work sync for the given workspace.

	 func updateGoModVersion(moduleDir, goVersion string) (string, error)
		updateGoModVersion updates go directive in go.mod file.

	 func upgradeModules(w *workspace, s *state) (*state, error)
		upgradeModules recursively updates dependencies in the workspace.


Package-Level Variables (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var errParse error
		errParse was copied from flag package. It is used for Func flags to indicate
		parse error.

	  var htmlEscaper *strings.Replacer
Package-Level Constants (total 7, none are exported)

	/* 7 unexporteds ... *//* 7 unexporteds: */
	const formatHTML = "html"
	const formatJSON = "json"
	const formatText = "text"
	const runTestsAll = "all"
	const runTestsNone = "none"
	const runTestsWork = "work"
	const usage = "goupdate [flags]\n  -go string\n        If non-empty, sets go direct...

The pages are generated with Golds v0.4.9. (GOOS=linux GOARCH=amd64)