upgrade

type Action struct {
	// Description says what Apply does.
	Description string
	// Apply applies the change to the application in workDir.
	Apply func(workDir string) (changed bool, err error)
	// Check reports, reading only, whether the application in workDir,
	// whose baseline is b, needs the change (Apply would change something).
	// Nil means it always does. The upgrade plan counts only the automatic
	// changes an app needs, and must write nothing: TestActionChecksWriteNothing
	// runs every Check against an app and compares its files. Check sees the
	// application as it is before the upgrade (b is that baseline), not as
	// the plan's earlier steps would leave it, and a step's need can change
	// once earlier steps apply: whatever applies a plan must re-check each
	// action right before its Apply, not trust the planned list.
	Check func(workDir string, b Baseline) (needed bool, err error)
}

type Applied struct {
	// Plan is the plan the dependency changes came from. Its automatic and
	// manual changes are not applied: they are still to do.
	Plan Plan `json:"plan"`
	// Commands are the go commands run, in order, with their output.
	Commands []GoCommand `json:"commands"`
	// GoMod and GoSum are the lines the commands removed and added.
	GoMod FileChange `json:"go_mod"`
	GoSum FileChange `json:"go_sum"`
	// FollowUp are steps the dependency change leaves to the developer
	// before the app builds again, such as refreshing a vendor directory.
	FollowUp []string `json:"follow_up"`
	// MigrationRequired is whether the upgrade is not complete until the
	// application migrates its database for the framework-schema changes
	// (Plan.Schema.Steps). ApplyDependencies never runs a migration.
	MigrationRequired bool `json:"migration_required"`
}

type Area string

type Baseline struct {
	// Framework is what go.mod says about the framework module.
	Framework Framework `json:"framework"`
	// Scaffold is the scaffold version the app was generated with: recorded
	// in gombit.yaml, or 0 when no metadata is recorded (Recorded false).
	Scaffold int `json:"scaffold"`
	// Metadata is the format of the recorded block (0 when there is none).
	Metadata int `json:"metadata"`
	// Recorded is whether gombit.yaml carries the metadata block. An app
	// without it was generated before upgrade metadata existed; its
	// baseline is detected (scaffold 0), and can be recorded with
	// RecordBaseline.
	Recorded bool `json:"recorded"`
}

type Bump int

type Change struct {
	// ID names the change, unique across the manifest (kebab-case).
	ID string `yaml:"id" json:"id"`
	// Kind is what moving across it takes.
	Kind Kind `yaml:"kind" json:"kind"`
	// Breaking is whether an app can stop building or behave differently
	// across it without acting.
	Breaking bool `yaml:"breaking" json:"breaking"`
	// Area is the part of an application it touches.
	Area Area `yaml:"area" json:"area"`
	// Summary is one line: what changed.
	Summary string `yaml:"summary" json:"summary"`
	// Details is Markdown: what to do (required for a manual change), and
	// why.
	Details string `yaml:"details,omitempty" json:"details,omitempty"`
	// Action names the automation applying an automatic change.
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
	// Refs are the GitHub issues or pull requests of the change.
	Refs []int `yaml:"refs,omitempty" json:"refs,omitempty"`
	// Config are the configuration variables the change renames, removes,
	// re-defaults, requires or newly refuses values of, and those it adds
	// that another entry needs or that a security change introduces: what
	// the upgrade tooling checks the application's environment files
	// against (AnalyzeConfig). A change in the security area makes each of
	// them, an addition included, a security review.
	Config []ConfigChange `yaml:"config,omitempty" json:"config,omitempty"`
	// Schema are the framework-owned tables the change adds, alters or
	// removes (area schema): the migrations an application generates,
	// reviews and applies for it (AnalyzeSchema). In a manual change they
	// are required; in an informational one, they are for an application
	// that adopts the feature.
	Schema []SchemaChange `yaml:"schema,omitempty" json:"schema,omitempty"`
	// Deprecates are the framework APIs the change deprecates, each named
	// as gombit upgrade check names it (database.KeepStoredZeros). A
	// "Deprecated: since vX.Y.Z" paragraph must name a release with a
	// change declaring its API here, so its window (RemovableFrom) starts
	// where the deprecation was announced.
	Deprecates []string `yaml:"deprecates,omitempty" json:"deprecates,omitempty"`
}

type Classification struct {
	Automatic     []Change `json:"automatic"`
	Manual        []Change `json:"manual"`
	Informational []Change `json:"informational"`
	Breaking      []Change `json:"breaking"`
}

type Codemod struct {
	// ID names it (kebab-case); a manifest change applies it as action
	// "codemod:<ID>".
	ID string
	// Description says what it rewrites, in one line.
	Description string
	// Package is the import path of the framework package declaring the
	// API it rewrites.
	Package string
	// Symbol is that API in Package: Name for a function, type, constant
	// or variable, Type.Name for a method or a struct field that Type's own
	// declaration declares. A member Type only reaches is refused: one
	// promoted from an embedded type or interface, or Base's when Type is
	// defined from it (type Type Base) or an alias of it. It is the
	// declaring type's, and every use of it would be rewritten, however
	// reached.
	Symbol string

	// Rename renames each use to this name. With MoveTo, the empty Rename
	// keeps the name.
	Rename string
	// MoveTo is the import path of the package the replacement of a
	// package-level API lives in: pkg.Name becomes newpkg.Name (or
	// newpkg.Rename), the file importing newpkg if it does not, and no
	// longer importing pkg if nothing else uses it.
	MoveTo string

	// Rewrite rewrites one use, for a change Rename and MoveTo cannot
	// express (reordered arguments, a new parameter): it returns the
	// expression replacing u.Node(), or nil (u.Skip) to leave the use for
	// the developer. It runs bottom-up, so u.Call's arguments are already
	// rewritten; give new nodes the position of what they replace. The
	// replacement must not use the API it replaces, or a second run would
	// rewrite it again: RunCodemods refuses one that does.
	Rewrite func(u *Use) ast.Expr
}

type ConfigCategory string

type ConfigChange struct {
	// Var is the variable, e.g. GOMBIT_HTTP_ADDR.
	Var string `yaml:"var" json:"var"`
	// Change is what the release does to it.
	Change ConfigChangeKind `yaml:"change" json:"change"`
	// To is, for a rename, the new name; for a default change, the new
	// default.
	To string `yaml:"to,omitempty" json:"to,omitempty"`
	// From is, for a default change, the old default.
	From string `yaml:"from,omitempty" json:"from,omitempty"`
	// Environment limits a default change, a requirement or a refusal to
	// one runtime environment (development, test, production); empty is
	// every one.
	Environment string `yaml:"environment,omitempty" json:"environment,omitempty"`
}

type ConfigChangeKind string

type ConfigFile struct {
	// Path is relative to the application directory.
	Path string `json:"path"`
	// Template is whether it is a template (.env.example and the like),
	// which WriteConfigTemplates may upgrade. Any other environment file
	// (.env, .env.production) may hold secrets: only the names it sets are
	// read, and it is never written.
	Template bool `json:"template"`
}

type ConfigFinding struct {
	ConfigChange
	// Release and ChangeID say where the manifest declares it.
	Release  string `json:"release"`
	ChangeID string `json:"change_id"`
	// Category is how it concerns the application.
	Category ConfigCategory `json:"category"`
	// NeedsAction is whether the developer must act (or review): every
	// rename, removal, requirement, refusal and security change, and a
	// default change the application's files do not override.
	NeedsAction bool `json:"needs_action"`
	// SetIn are the environment files (not templates) that set the
	// variable; TemplateSetIn the templates that set it, and DocumentedIn
	// those that mention it commented out: each template as the path's
	// earlier changes leave it (WriteConfigTemplates rewrites it), every
	// other file as it is (see AnalyzeConfig). They are mentions: only
	// .env, for local development runs, is a runtime override gombit loads.
	SetIn         []string `json:"set_in"`
	TemplateSetIn []string `json:"template_set_in"`
	DocumentedIn  []string `json:"documented_in"`
	// SetAs are the files (not templates) that set the variable under an
	// earlier name of a rename on the path, each with that name: renaming
	// A to B, then B to C, a .env setting A is listed for B. It proves
	// nothing about the new name (a default change still needs action),
	// but the file needs the renames.
	SetAs map[string]string `json:"set_as,omitempty"`
	// Fixable is whether WriteConfigTemplates would change a template for
	// it (false once it has).
	Fixable bool `json:"fixable"`
	// Advice says what to do.
	Advice string `json:"advice"`
}

type ConfigReport struct {
	// Files are the environment files read.
	Files []ConfigFile `json:"files"`
	// Unreadable are the environment files that could not be read (no
	// permission, not a regular file): what they set is unknown, so check
	// them by hand.
	Unreadable []string `json:"unreadable"`
	// Findings are the upgrade's configuration changes, in release order.
	Findings []ConfigFinding `json:"findings"`
}

type DependencyChange struct {
	Module string `json:"module"`
	// Directive is the directive that changes: "require" or "replace".
	Directive string `json:"directive"`
	// ForVersion is, for a replace, the version it replaces (its left
	// side); empty for a replace of every version.
	ForVersion string `json:"for_version,omitempty"`
	// From is the directive's right side now: the required version, or the
	// replacement as go.mod writes it ("path version", or a directory).
	From string `json:"from"`
	// To is the version it moves to; empty for a replace that must be
	// dropped instead.
	To string `json:"to,omitempty"`
	// Note says why the directive must change, when the reason is not
	// plain.
	Note string `json:"note,omitempty"`
}

type DeprecatedUse struct {
	// File is the using file, relative to the application directory when
	// it is inside it.
	File string `json:"file"`
	// Line and Column are where the use is.
	Line   int `json:"line"`
	Column int `json:"column"`
	// Symbol is the API used: an import path (a deprecated package),
	// pkg.Name, pkg.Type.Field, or (*pkg.Type).Method.
	Symbol string `json:"symbol"`
	// Package is the import path of the package that declares it.
	Package string `json:"package"`
	// Deprecation is the declaration's "Deprecated:" paragraph, which names
	// what to use instead.
	Deprecation string `json:"deprecation"`
	// Since is the release that deprecated it, as the paragraph says
	// ("Deprecated: since vX.Y.Z, ..."), and RemovableFrom the first
	// release of its line the compatibility policy lets remove it;
	// RemovableFromMajor is the major release that may remove it if it
	// comes first (v1.0.0, for a pre-1.0 deprecation). All empty when the
	// paragraph names no release.
	Since              string `json:"since,omitempty"`
	RemovableFrom      string `json:"removable_from,omitempty"`
	RemovableFromMajor string `json:"removable_from_major,omitempty"`
}

type FileChange struct {
	Removed []string `json:"removed"`
	Added   []string `json:"added"`
}

type FileFix struct {
	// Path is the file, relative to the application directory, with
	// forward slashes.
	Path string `json:"path"`
	// Before and After are its content before and after the rewrite.
	Before []byte `json:"-"`
	After  []byte `json:"-"`
	// contains filtered or unexported fields
}

type Fix struct {
	// Files are the files it changes, by path.
	Files []FileFix `json:"files"`
	// Left are the uses no codemod could rewrite: the developer changes
	// them.
	Left []LeftUse `json:"left"`
	// Unchecked are the application's Go files the build configuration
	// excludes (build constraints) that may use a codemod's API (they
	// mention its name): they are not type-checked, so not rewritten. They
	// are found by walking the tree as ./... does, so a directory whose
	// every file is excluded is covered too. Rerun with their GOOS, GOARCH
	// or -tags (GOFLAGS) to cover them.
	Unchecked []string `json:"unchecked"`
}

type Framework struct {
	// Module is the framework's module path.
	Module string `json:"module"`
	// Version is the framework release the app builds against: the require
	// directive's version, or the version of a replace by the framework
	// module itself. It is empty when there is no framework release to
	// name: the framework is replaced by a local directory (Local) or by
	// another module (a fork: see Replace), or a go.work decides the build
	// (Workspace). Upgrade planning starts from Version, so it never names
	// what is not a release of the framework.
	Version string `json:"version,omitempty"`
	// Required is the require directive's version.
	Required string `json:"required"`
	// Replace is the replace directive in go.mod that applies to Required,
	// as the go command picks it, if any. Nil when a go.work applies
	// (Workspace): the workspace's replaces count then, and are not read.
	Replace *Replacement `json:"replace,omitempty"`
	// Local is true when go.mod replaces the framework by a local directory
	// (a framework checkout): there is no published version to upgrade
	// from. False when a go.work applies (Workspace), which decides instead.
	Local bool `json:"local,omitempty"`
	// Workspace is the go.work the go command uses for the app (its own
	// answer, `go env GOWORK`), if any. The workspace then decides the
	// framework the app builds against: its other modules' requirements and
	// replaces count too. This package does not resolve that, so only
	// Required (go.mod's) is set, and Version, Replace and Local are empty;
	// with GOWORK=off the app builds from its go.mod alone.
	Workspace string `json:"workspace,omitempty"`
}

type GoCommand struct {
	// Args are its arguments, after "go".
	Args []string `json:"args"`
	// Output is what it printed (stdout and stderr).
	Output string `json:"output,omitempty"`
}

type GoCommandError struct {
	Args   []string
	Output string
	Err    error
}

type Kind string

type LeftUse struct {
	File    string `json:"file"`
	Line    int    `json:"line"`
	Column  int    `json:"column"`
	Codemod string `json:"codemod"`
	Symbol  string `json:"symbol"`
	Reason  string `json:"reason"`
}

type Manifest struct {
	// Format is the manifest's format (ManifestFormat).
	Format int `yaml:"format" json:"format"`
	// Releases are in ascending version order. The first is the baseline:
	// the first release the manifest covers, which upgrades start from, so
	// it declares no changes. Unreleased, if present, is last.
	Releases []Release `yaml:"releases" json:"releases"`
}

type Plan struct {
	// Baseline is where the application stands (Detect).
	Baseline Baseline `json:"baseline"`
	// Current is the framework release the application builds against.
	Current string `json:"current"`
	// Target is the framework release the plan moves it to.
	Target string `json:"target"`
	// Dependencies are the go.mod directives about the framework module the
	// upgrade changes: its require, and a replace of it by the framework
	// module itself, which decides the build too. None when the application
	// already builds against Target.
	Dependencies []DependencyChange `json:"dependencies"`
	// Releases are the releases the upgrade moves across, in order.
	Releases []Release `json:"releases"`
	// Automatic are the automatic changes the application needs, each with
	// the action that applies it. An automatic change whose action reports
	// the application does not need it is left out.
	Automatic []PlannedAction `json:"automatic"`
	// Manual are the changes the developer must act on: every one the
	// manifest declares between Current and Target, with what to do.
	Manual []Change `json:"manual"`
	// Breaking are the breaking changes this application faces: every
	// breaking manual and informational change, and the breaking automatic
	// changes it needs. An automatic change its action reports the app does
	// not need is left out here too, as in Automatic, so the plan never
	// counts a change the app has already absorbed.
	Breaking []Change `json:"breaking"`
	// Informational are the changes worth knowing, with nothing to do.
	Informational []Change `json:"informational"`
	// Config is what the upgrade's configuration changes mean for the
	// application's environment files (AnalyzeConfig): names only, never
	// a value.
	Config ConfigReport `json:"config"`
	// Schema is what the upgrade's framework-schema changes (auth tables,
	// storage claims) mean for the application's migrations
	// (AnalyzeSchema, from its model registry in database/migrations): the
	// migration steps the upgrade is not complete without. The upgrade
	// tooling never generates or applies a migration.
	Schema SchemaReport `json:"schema"`
	// Contract are the changes on the path to the generated contract (the
	// OpenAPI document and TypeScript client: area client). Whatever they
	// are, the framework renders the generated artifacts, so after the
	// dependency change gombit upgrade contract checks them.
	Contract []Change `json:"contract"`
}

type PlanOptions struct {
	// MigrationDir is the application's migration directory, which holds
	// its model registry, relative to its directory unless absolute (as
	// gombit db --dir; default database/migrations). The framework-schema
	// section is judged against it, and its steps act on it.
	MigrationDir string
}

type PlannedAction struct {
	Change Change `json:"change"`
	// Description says what the action does.
	Description string `json:"description"`
}

type Release struct {
	// Version is the release's version (canonical semver), or Unreleased.
	Version string `yaml:"version" json:"version"`
	// Changes are its upgrade-relevant changes; none for a release with
	// nothing to declare.
	Changes []Change `yaml:"changes,omitempty" json:"changes"`
}

type Replacement = frameworkmod.Replacement

type SchemaChange struct {
	// Model is the framework model, by its package within the framework
	// module and its type: auth.RefreshToken, storage/claims.Claim.
	Model string `yaml:"model" json:"model"`
	// Table is the table: the model's own, or a many-to-many join table
	// the model declares (Join).
	Table string `yaml:"table" json:"table"`
	// Join: Table is a join table Model declares (auth_user_groups for
	// auth.User). Its change alters Model; it never adds or removes it. A
	// table that is not the own table of a model this gombit has is read
	// as a join table even without the flag.
	Join bool `yaml:"join,omitempty" json:"join,omitempty"`
	// Change is what happens to it.
	Change SchemaChangeKind `yaml:"change" json:"change"`
	// Destructive: the change drops or narrows something, so the migration
	// loses data unless the application acts first (gombit db plan then
	// asks for --allow).
	Destructive bool `yaml:"destructive,omitempty" json:"destructive,omitempty"`
}

type SchemaChangeKind string

type SchemaFinding struct {
	SchemaChange
	// Release and ChangeID say where the manifest declares it.
	Release  string `json:"release"`
	ChangeID string `json:"change_id"`
	// Required is whether the application must migrate for it: the change
	// is manual, and its model is one the application has (or, added, one
	// every application needs). An informational change's table is for an
	// application that adopts the feature it belongs to.
	Required bool `json:"required"`
	// Registered is whether the application's model registry lists the
	// model, so its migrations carry the table.
	Registered bool `json:"registered"`
	// Advice says what to do.
	Advice string `json:"advice"`
}

type SchemaReport struct {
	// Registry is the application's model registry file, relative to the
	// application directory, and RegistryFound whether it exists: without
	// one the application has generated no migration yet.
	Registry      string `json:"registry"`
	RegistryFound bool   `json:"registry_found"`
	// Findings are the framework-schema changes on the path, in order.
	Findings []SchemaFinding `json:"findings"`
	// Steps are the migration steps the upgrade needs, in order: the
	// upgrade is not complete until they are done. Empty when no change
	// requires one. They are for the developer: gombit upgrade never
	// generates or applies a migration.
	Steps []string `json:"steps"`
}

type Use struct {
	// Ident is the identifier denoting the API.
	Ident *ast.Ident
	// Expr is the use: pkg.Name; x.Name (a method, a field, a method
	// expression); or a bare Name (a dot import, a composite literal key).
	Expr ast.Expr
	// Call is the call, or conversion, whose function Expr is, possibly
	// parenthesized and instantiated ((f)(x), f[T](x)); nil when Expr is
	// not called. CallFun builds a new call's Fun keeping those wrappers.
	Call *ast.CallExpr
	// Path is the enclosing nodes, Ident first and the file last.
	Path []ast.Node
	// Info is the type information of the use's package, for the source
	// as it was before any rewrite (new nodes have none).
	Info *types.Info
	// contains filtered or unexported fields
}