migrator

type API interface {
	// FindProblems allows you to report problems about a Project, or about
	// certain configuration files within the project.
	//
	// If the method finds issues which warrant followup, it should use
	// proj.Report and/or proj.ConfigFiles()["filename"].Report. Reporting one or
	// more problems will cause the migrator tool to set up a checkout for this
	// project.
	//
	// Logging is set up for this context, and will be diverted to a per-project
	// logfile.
	//
	// `proj` is implemented with LUCI Config API calls; it reflects the state of
	// the project as currently known by the luci-config service.
	//
	// This function should panic on error.
	FindProblems(ctx context.Context, proj Project)

	// ApplyFix allows you to attempt to automatically fix problems within a repo.
	//
	// Note that for real implementations you may want to keep details on the
	// `impl` struct; this will let you carry over information from
	// FindProblems.
	//
	// Logging is set up for this context, and will be diverted to a per-project
	// logfile.
	//
	// `repo.Project()` is implemented with local filesystem interactions on the
	// checked-out repo. This may differ from the current state of the luci-config
	// service.
	//
	// This function should panic on error.
	ApplyFix(ctx context.Context, repo Repo)
}

type ConfigFile interface {
	Reportable

	// Path returns the path relative to the repo's generated configuration
	// directory.
	Path() string

	// RawData returns the data of this configuration file as a string.
	//
	// May do a (cached) network operation to retrieve the raw data.
	RawData() string

	// TextPb parses the raw data as a text proto with "heredoc" processing into
	// `out`.
	//
	// May do a (cached) network operation to retrieve the raw data.
	//
	// If there are errors during parsing, this panics.
	TextPb(out proto.Message)
}

type InstantiateAPI func() API

type Project interface {
	Reportable

	ID() string

	// ConfigFiles returns a mapping of path to config file.
	//
	// May do a (cached) network operation to retrieve the data.
	ConfigFiles() map[string]ConfigFile
}

type Repo interface {
	// ConfigRoot returns the path to the config file 'root'.
	//
	// This would be the directory containing `main.star`, if the repo has one,
	// otherwise is identical to GeneratedConfigRoot.
	//
	// TODO: Have a less-heuristic way to find this path in the repo.
	//
	// This an 'absolute-style' path (see Shell).
	ConfigRoot() string

	// GeneratedConfigRoot returns the path to the generated config files (i.e.
	// the ones seen by the luci-config service).
	//
	// This an 'absolute-style' path (see Shell).
	GeneratedConfigRoot() string

	// Project returns the LUCI Project associated with this repo.
	//
	// Files retrieved with ConfigFiles() will be based on the checked-out data.
	Project() Project

	// Shell returns a new shell object for this repo with its current working
	// directory set to ConfigRoot().
	Shell() Shell
}

type Report struct {
	ReportID

	Tag     string
	Problem string

	// If true, indicates that this report can be fixed by ApplyFix.
	Actionable bool

	Metadata map[string]stringset.Set
}

type ReportDump struct {
	// contains filtered or unexported fields
}

type ReportID struct {
	Project    string
	ConfigFile string
}

type ReportOption func(*Report)

type Reportable interface {
	// Report logs a problem about this object.
	//
	// `tag` should be a CAPS_STRING which makes sense to your particular
	// application.
	//
	// `description` should be a human readable explanation of the problem.
	//
	// Example:
	//    tag: MISSING_BLARF
	//    description: "blarf.cfg file is missing"
	Report(tag, description string, opts ...ReportOption)
}

type Shell interface {
	// Cd changes the current directory.
	//
	// Absolute paths (i.e. beginning with '/') are interpreted as relative to the
	// repo root.
	//
	// Attempting to Cd out of the top of the repo is an error.
	Cd(path string)

	// ModifyFile allows trivial modification of a file.
	//
	// This will call `modify` with the contents of the old file ("" if the file
	// didn't exist), and will write the returned string back to `path`, if the
	// returned string is different. This will create missing intermediate
	// directories.
	//
	// Allows supplying FileMode. If omitted, defaults to 0666 (i.e. a+rw) for new
	// files, and otherwise will keep the mode of the existing file.
	ModifyFile(path string, modify func(oldContents string) string, mode ...os.FileMode)

	// Stat returns the FileInfo for the entity at `path`, or nil if no such
	// entity exists.
	Stat(path string) os.FileInfo

	// Run executes a command `name` with arguments `args`.
	//
	// `name` may be relative to the Shell's cwd (e.g. `./main.star`), or to $PATH
	// (e.g. `git`).
	//
	// The command is expected to return exitcode 0.
	//
	// The command runs with the cwd of the Shell.
	//
	// Stdout+Stderr are redirected to logging (with Stdout logged at 'Info' level
	// and Stderr logged at 'Error' level).
	//
	// If the very last item in `args` is the TieStderr constant, both will be
	// tied together and all output will be logged at 'Info' level.
	Run(name string, args ...string)

	// Same as `Run`, but returns the exitcode of the process (instead of
	// asserting an exit code of 0).
	Retval(name string, args ...string) int

	// Same as `Run`, but returns the stdout of the process. If TieStderr is the
	// last argument, then this captures Stderr, too.
	Stdout(name string, args ...string) string
}