upgrade

type Action string

type ActionTaken struct {
	Action Action

	// Explanation is a human-readable reason why the given Action was chosen
	// for this path.
	Explanation string

	// This is the Path to the single file that this ActionTaken is about. It is
	// always set.
	//
	// This is a relative path, starting from the directory where the template
	// is installed.
	Path string

	// OursPath is only set for certain types of merge conflict. This is the
	// path that the local file was renamed to that needs manual merge
	// resolution.
	//
	// This is a relative path, starting from the directory where the template
	// is installed.
	OursPath string

	// IncomingTemplatePath is only set for certain types of merge conflict.
	// This is the path to the incoming template file that needs merge
	// resolution.
	//
	// This is a relative path, starting from the directory where the template
	// is installed.
	IncomingTemplatePath string
}

type Params struct {
	Clock clock.Clock

	// CWD is the value of os.Getwd(), or in testing, a temp directory.
	CWD string

	// The value of --debug-scratch-contents.
	DebugScratchContents bool

	// The value of --debug-step-diffs.
	DebugStepDiffs bool

	// FS abstracts filesystem operations for error injection testing.
	FS common.FS

	// The value of --git-protocol.
	GitProtocol string

	// The value of --input-file.
	InputFiles []string

	// The value of --input.
	Inputs map[string]string

	// The value of --keep-temp-dirs.
	KeepTempDirs bool

	// The path to the manifest file where the template was previously installed
	// to that will now be upgraded. This is also overwritten with the new
	// manifest after a successful upgrade.
	ManifestPath string // Must be an absolute path.

	// The value of --prompt.
	Prompt   bool
	Prompter input.Prompter

	// Relative paths where patch reversal has already happened. This is a flag
	// supplied by the user. This will be set if there were merge conflicts
	// during patch reversal that were manually resolved by the user.
	// TODO(upgrade): add this as a CLI flag and plumb it through to here.
	ReversalAlreadyDone []string

	// The value of --skip-input-validation.
	SkipInputValidation bool

	// Used in tests to do prompting for inputs even though the input is not a
	// TTY.
	SkipPromptTTYCheck bool

	// The output stream used to print prompts when Prompt==true.
	Stdout io.Writer

	// Empty string, except in tests. Will be used as the parent of temp dirs.
	TempDirBase string
}

type Result struct {
	// If no upgrade was done because this installation of the template is
	// already on the latest version, then this will be true and all other
	// fields in this struct will have zero values.
	Type ResultType

	// The paths to files where abc tried to apply the reversal
	// patches from the manifest to included-from-destination files, and the
	// patches could not be applied cleanly. Manual resolution is needed.
	//
	// This field should only be used when Type==PatchReversalConflict.
	ReversalConflicts []*ReversalConflict

	// Conflicts is the set of files that require manual intervention by the
	// user to resolve a merge conflict. For example, there may be a file that
	// was edited by the user and that edit conflicts with changes to that same
	// file by the upgraded version of the template.
	//
	// This field should only be used when Type==MergeConflict.
	Conflicts []ActionTaken

	// NonConflicts is the set of template output files that do NOT require any
	// action by the user. Callers are free to ignore this.
	//
	// This is mutually exclusive with "Conflicts". Each file is in at most one
	// of the two lists.
	//
	// This field should only be used when Type is Success or MergeConflict.
	NonConflicts []ActionTaken
}

type ResultType string

type ReversalConflict struct {
	// The relative path to the file that needs manual resolution.
	Path string
}