transplant

type Audit struct {
	// AllDepGoFiles holds absolute paths to all files found recursively in all Dep.From.FilePath.
	AllDepGoFiles *cage_strings.Set

	// UsedDepGoFiles holds absolute paths to files directly/transitively depended on by LocalGoFiles
	// by examining the global identifier usage into the latter.
	//
	// All package files will be included even if LocalGoFiles only depends on one file. This excess
	// is currently used to ensure all init functions are included.
	//
	// When a filename is added, its path should be added to UsedDepImportPaths (depDirToImportPath may help).
	UsedDepGoFiles *cage_strings.Set

	// UsedDepImportPaths holds the import paths of packages directly/transitively depended on by LocalGoFiles.
	UsedDepImportPaths *cage_strings.Set

	// LocalGoFiles holds absolute paths of Ops.From.FilePath Go files.
	LocalGoFiles *cage_strings.Set

	// LocalGoTestFiles holds absolute paths of Ops.From.FilePath Go test files.
	LocalGoTestFiles *cage_strings.Set

	// LocalCopyOnlyFiles include all Ops.From.FilePath contents matching Ops.From.CopyOnlyFilePath.
	LocalCopyOnlyFiles *cage_strings.Set

	// LocalGoDescendantFiles include Ops.From.FilePath contents matching Ops.From.GoDescendantFilePath.
	//
	// They are filtered based on having an ancestor Go directory during the copy operation.
	LocalGoDescendantFiles *cage_strings.Set

	// LocalIncludeDirs holds absolute paths of Ops.From.FilePath dirs/files which are/match an
	// Ops.From.* inclusion pattern (that was not invalidated by a related exclusion pattern).
	LocalIncludeDirs *cage_strings.Set

	// AllDepDirs holds absolute paths of directories which match Ops.Dep.From.GoFilePath queries.
	//
	// It differs from the narrower scope of UsedDepGoFiles and covers directories which may include
	// packages which are not dependencies of LocalGoFiles.
	AllDepDirs *cage_strings.Set

	// UnconfiguredDirs holds absolute paths of directories whose packages were imported into Ops.From
	// or Ops.Dep.From packages but were not covered by those configuration.
	//
	// It is indexed by the import path of the packages which perform the imports.
	UnconfiguredDirs map[string]*cage_strings.Set

	// UnconfiguredDirImporters holds the import path keys of UnconfiguredDirs.
	UnconfiguredDirImporters *cage_strings.Set

	// DepCopyOnlyFiles include all Ops.Dep.From.FilePath contents matching Ops.Dep.From.CopyOnlyFilePath.
	DepCopyOnlyFiles *cage_strings.Set

	// DepGoDescendantFiles include Ops.Dep.From.FilePath contents matching Ops.Dep.From.GoDescendantFilePath.
	//
	// They are filtered based on having an ancestor Go directory during the copy operation.
	DepGoDescendantFiles *cage_strings.Set

	// DirectDepImportsIntoLocal enumerates the Ops.Dep.From packages directly imported into Ops.From packages.
	DirectDepImportsIntoLocal *cage_pkgs.ImportList

	// AllDepImportsIntoLocal enumerates the Ops.Dep.From packages directly or transitively imported into
	// Ops.From packages. It includes all elements of DirectDepImportsIntoLocal.
	AllDepImportsIntoLocal *cage_pkgs.ImportList

	// DepGlobalIdUsageDag graphs usage of global identifiers in Ops.Dep packages (except for their
	// init functions) to support pruning the latter during a refactor operation.
	//
	// It graphs connections between LocalGoFiles (as LocalGoFilesDagRoot) and all identifiers observed during
	// a recursive walk of global functions/methods in the Ops.Dep packages.
	DepGlobalIdUsageDag cage_dag.Graph

	// LocalGoFilesDagRoot represents all LocalGoFiles in the DepGlobalIdUsageDag.
	//
	// A Ops.Dep global can be pruned if there is no path from this root to the global in either DAG.
	LocalGoFilesDagRoot cage_pkgs.GlobalId

	// DepGoTestFiles holds absolute paths to files which were found in the same directory as a
	// Ops.Dep package which is directly/transitively used by Ops.Dep packages that are
	// directly/transitively used by LocalGoFiles.
	DepGoTestFiles *cage_strings.Set

	// LocalInspectDirs holds the Ops.From.FilePath directories provided to Inspector for
	// loading by x/tools/go/packages.
	LocalInspectDirs *cage_strings.Set

	// DepInspectDirs holds the Ops.Dep.From.FilePath directories provided to Inspector for
	// loading by x/tools/go/packages.
	DepInspectDirs *cage_strings.Set

	// UsedDepExports indexes used Ops.Dep global identifiers first by import path, then global name.
	UsedDepExports map[string]map[string]cage_pkgs.GlobalId

	// IngressRemovableDirs holds (egress) Ops.From.FilePath dirs which may be removed during ingress because
	// they match config patterns of the egress operation.
	IngressRemovableDirs *cage_strings.Set

	// IngressRemovableFiles holds (egress) Ops.From.FilePath files which may be removed during ingress because
	// they match config patterns of the egress operation.
	IngressRemovableFiles *cage_strings.Set

	// LocalReplaceStringFiles holds Ops.From.ReplaceString matches.
	LocalReplaceStringFiles *ReplaceStringFiles

	// DepReplaceStringFiles holds Ops.Dep.From.ReplaceString matches.
	DepReplaceStringFiles *ReplaceStringFiles

	// Progress receives messages describing analysis steps and runtimes.
	Progress io.Writer

	// WhyLog if non-nil will receive updates which support `{egress,ingress} file` queries.
	WhyLog why.Log

	// AllImportPathReplacer replaces Ops.From.LocalImportPath and all Ops.Dep.From.ImportPath substrings
	// with their To counterparts.
	AllImportPathReplacer *cage_strings.ReplaceSet

	// DepImportPathReplacer replaces Ops.Dep.From.ImportPath substrings with its To counterpart.
	DepImportPathReplacer *cage_strings.ReplaceSet
	// contains filtered or unexported fields
}

type Config struct {
	// Ops holds all refactor operation definitions indexed by a user-defined ID.
	Ops map[string]Op

	// Template holds key/value pairs which can be used in some string fields via {{.key_name}} syntax.
	//
	// Key names must use lowercase due to viper(/mapstructure?) limitation. Convention: "some_key_name".
	// https://github.com/spf13/viper/issues/411
	// https://github.com/spf13/viper/pull/635
	Template map[string]string
}

type ConfigMatcher struct {
	// BaseFilePath is the original base path selected when creating the full-path matchers
	BaseFilePath string

	CopyOnlyFilesFull   cage_file.FileMatcher
	CopyOnlyFilesSuffix cage_file.FileMatcher

	GoDescendantFilesFull   cage_file.FileMatcher
	GoDescendantFilesSuffix cage_file.FileMatcher

	InspectDirsFull   cage_file.DirMatcher
	InspectDirsSuffix cage_file.DirMatcher
}

type Copier struct {
	// Audit results inform the copier operation by providing data such as the file lists and globals found in the AST.
	Audit *Audit

	// Ctx is applied to context-aware operations to support externally-defined cancellation.
	Ctx context.Context

	// Op is the configuration data used by both the Audit and copy operation to determine their scope, modes, etc.
	Op Op

	// OverwriteMin is true if the copy should only populate the staging dir, and overwrite files in the
	// destination dir, if the inbound content is different. Files with the same content will be added to
	// CopyPlan.OverwriteSkip.
	OverwriteMin bool

	// ModuleRequire is true if the Go modules step should be performed where the module is initialized
	// and receives requirements from the origin module.
	ModuleRequire bool

	// Plan enumerates the copy actions which would run, to support dry-run mode.
	Plan CopyPlan

	// ProgressCore receives messages describing core copy steps and runtimes.
	ProgressCore io.Writer

	// ProgressModule receives stdout messages from module-related Go commands.
	ProgressModule io.Writer

	// Stderr receives messages about errors which are printed but considered serious enough to be
	// collected and cause the operation to exit early.
	Stderr io.Writer

	// Stage abstracts a temporary directory which is populated fully before the actual copy operation
	// in order to minimize side-effects if an error is encountered.
	Stage *cage_file_stage.Stage

	// WhyLog if non-nil will receive updates which support `{egress,ingress} file` queries.
	WhyLog why.Log
}

type CopyFileError struct {
	// Name is an absolute path.
	Name string

	// Err is an Error() string.
	Err string
}

type CopyPlan struct {
	// Add holds the absolute paths of all files to be added to Ops.To.FilePath.
	Add []string `json:",omitempty" toml:",omitempty" yaml:"Add,omitempty" `

	// Overwrite holds the absolute paths of all files to be overwritten in Ops.To.FilePath.
	Overwrite []string `json:",omitempty" toml:",omitempty" yaml:"Overwrite,omitempty"`

	// Remove holds the absolute paths of all files to be removed from Ops.To.FilePath.
	Remove []string `json:",omitempty" toml:",omitempty" yaml:"Remove,omitempty"`

	// PruneGlobalIds describes the global identifiers omitted from Ops.Dep packages because they were not
	// direct/transitive dependencies of packages under Ops.From.FilePath.
	//
	// Global identifier name format: <absolute path to package directory>.<package name>.<identifier name>
	// Files are identified by their absolute paths.
	PruneGlobalIds []string `json:",omitempty" toml:",omitempty" yaml:"PruneGlobalIds,omitempty"`

	// PruneGoFiles holds files which were omitted from the copy because they did not contain a
	// direct/transitive dependency of packages under Ops.From.FilePath.
	PruneGoFiles []string `json:",omitempty" toml:",omitempty" yaml:"PruneGoFiles,omitempty"`

	// GoFormatErr describes Ops.From.CopyOnlyFilePath Go files which could not be automatically
	// formatted by go/format.Source, e.g. due to a syntax error.
	//
	// Those errors are collected here, instead of causing the overall copy operation to fail, to support
	// fixtures with intentional defects. It also supports the general distinction between CopyOnlyFilePath
	// patterns and others like GoFilePath which require error-free parsing.
	GoFormatErr []CopyFileError `json:",omitempty" toml:",omitempty" yaml:"GoFormatErr,omitempty"`

	// RenameNotFound holds absolute paths of RenameFilePath targets which were not found.
	//
	// Paths are collected instead of causing the copy operation to fail to support cases where the
	// target file is not always present.
	RenameNotFound []string `json:",omitempty" toml:",omitempty" yaml:"RenameNotFound,omitempty"`

	// GoModVendor is true if `go mod vendor` is called.
	GoModVendor bool `yaml:"GoModVendor"`

	// Env holds environment details which affect Copier behavior.
	Env map[string]string `yaml:"Env"`

	// StagePath holds the absolute path to the staging file tree where the copy is generated as a whole and then
	// copied at the end of the process.
	StagePath string `yaml:"StagePath"`

	// OverwriteSkip holds the absolute paths of all files not overwritten in Ops.To.FilePath
	// because the destination's content is the same.
	OverwriteSkip []string `json:"-" toml:"-" yaml:"-"`
}

type Dep struct {
	From DepFrom
	To   DepTo
}

type DepFrom struct {
	// FilePath is a path relative to Ops.From.ModuleFilePath.
	//
	// It is used as the base path for all *FilePath patterns.
	FilePath string

	// ImportPath is the prefix of all packages under FilePath.
	//
	// It is computed based on Ops.From.ModuleImportPath and this type's FilePath.
	ImportPath string `mapstructure:"-"`

	// GoFilePath matches directories in which implementation (and optionally test) packages should
	// be copied and analyzed for their dependencies.
	//
	// Implementation packages will only be included if they're direct/transitive dependencies
	// of the target project. Tests will only be included if enabled by the Tests config field
	// and they share a directory with an already included implementation packages.
	//
	// Matching directories will be inspected.
	// If Tests is true, test packages will be auto-discovered.
	// Only Go files will be copied.
	GoFilePath FilePathQuery

	// CopyOnlyFilePath matches files which should be copied but not inspected/refactored.
	//
	// Each pattern is relative to FilePath.
	CopyOnlyFilePath FilePathQuery

	// GoDescendantFilePath first matches files which should be copied but not inspected or refactored
	// (except for basic string replacement of source file/import paths), same as CopyOnlyFilePath.
	// It also requires that each file is a descendant of directory which provides a Go package to the copy
	// (i.e. a dependency of a project matched by GoFilePath).
	//
	// For example, it supports the need to exclude files such as test fixtures whose only dependents are in
	// ancestor directories which will not be part of the copy.
	GoDescendantFilePath FilePathQuery

	// ReplaceString defines the scope of string replacements to perform during copy operations.
	//
	// Replacements occur on the intersection between its matches and those of all other config patterns,
	// such as GoFilePath and CopyOnlyFilePath, which control the scope of the copy operation itself.
	ReplaceString ReplaceStringSpec

	// Tests is true if a GoFilePath-matched test packages and their dependencies should be included.
	Tests bool
}

type DepTo struct {
	// FilePath is a path relative to Ops.To.ModuleFilePath.
	FilePath string

	// ImportPath is the prefix of all packages under FilePath.
	//
	// It is computed based on Ops.To.ModuleImportPath and this type's FilePath.
	ImportPath string `mapstructure:"-"`
}

type File struct {
	// AbsPath is the absolute path to the file being copied.
	AbsPath string

	// Dir is the parent directory of the file.
	Dir string

	// Go is true of the file is a Go file.
	Go bool

	// Node is the inspection data about the associated ast.File.
	Node cage_pkgs.Node

	// FileSet contains the subject file if it is of Go type.
	FileSet *token.FileSet

	// Pkg is the inspection data about the file's package.
	Pkg *cage_pkgs.Package

	// Mode represents the file's mode/permission bits.
	Mode os.FileMode
}

type FileConfig struct {
	Audit            *Audit
	ToFilePathPrefix string
}

type FilePathQuery struct {
	// Include holds github.com/bmatcuk/doublestar glob patterns which validate a candidate path.
	//
	// If any matches, the candidate path is accepted.
	Include []string

	// Exclude holds github.com/bmatcuk/doublestar glob patterns which invalidate a candidate path.
	//
	// If any matches, the candidate path is rejected.
	Exclude []string
}

type FromFinderInput struct {
	// BaseFilePath is the base path of Include/Exclude suffix-targeting matchers.
	BaseFilePath string

	// Include holds the file/dir matchers computed from Ops.From or Ops.Dep.From config.
	Include *ConfigMatcher

	// Exclude allows the search to avoid overlapping result sets.
	// When Include defines an Ops.From search, Exclude holds Ops.Dep.From matchers.
	// When Include defines an Ops.Dep.From search, it holds a Ops.From matcher.
	Exclude []*ConfigMatcher

	// ReplaceString specs match subsets of Include matches which are targeted for string replacements.
	ReplaceString ReplaceStringSpec
}

type FromFinderOutput struct {
	AllFiles cage_file.DirToFinderMatchFiles

	CopyOnlyFiles     *cage_strings.Set
	GoDescendantFiles *cage_strings.Set

	InspectDirs       *cage_strings.Set
	InspectIgnoreDirs *cage_strings.Set

	ReplaceStringFiles *ReplaceStringFiles
}

type Op struct {
	// Id is a copy of the Config.Ops key selected by the user in the config file.
	//
	// It supports cases such as error messages in parts of the code that only receive the Op
	// and not the whole Config from which it belongs.
	Id string

	// From describes the origin module location.
	From RootFrom

	// To describes the standalone-repo location.
	To RootTo

	// Dep describes dependencies of code in From that exists elsewhere in the origin module and is not vendored,
	// e.g. first-party packages/modules centrally shared in the repo.
	Dep []Dep

	// DryRun is true if the operation should perform all steps except creating/modifying Ops.To.FilePath.
	DryRun bool `mapstructure:"-"`

	// Ingress is true if the copy mode/direction is from a standalone module to the origin source tree.
	Ingress bool `mapstructure:"-"`
}

type PrunableFile struct {
	*File

	// DecoratedFile is a converted ast.File that contains additional information which supports
	// such things as AST editing w/ comment position retention.
	DecoratedFile *dst.File

	// Decorator converts the ast.File to Decorated file, maps dst.Node values to ast.Node values, etc.
	Decorator *decorator.Decorator
}

type RenameSpec struct {
	// Old is a relative path.
	//
	// It is a source path during egress and destination path during ingress.
	//
	// It must identify a file already selected in the operation, e.g. via CopyOnlyFilePath
	// or other *FilePath query.
	Old string

	// New is a relative path.
	//
	// It is a destination path during egress and source path during ingress.
	//
	// It must identify a file already selected in the operation, e.g. via CopyOnlyFilePath
	// or other *FilePath query.
	New string
}

type ReplaceStringFiles struct {
	// ImportPath holds Ops.From.ReplaceString.ImportPath/Ops.Dep.From.ReplaceString.ImportPath matches.
	ImportPath *cage_strings.Set
}

type ReplaceStringSpec struct {
	// ImportPath matches files which should have Ops.From/Ops.To import paths converted
	// when found outside import statements of parsed files identified via GoFilePath:
	// e.g. CopyOnlyFilePath and GoDescendantFilePath matches
	//
	// Each pattern is relative to the FilePath field in the parent RootFrom/DepFrom.
	ImportPath FilePathQuery
}

type RootFrom struct {
	// ModuleFilePath is the absolute path to the root of the origin module where the go.mod can be found.
	//
	// It is the base directory for all *FilePath patterns.
	//
	// If it contains a go.sum, and `go mod tidy` execution in the destination during egress also
	// creates one, the destination's hashes will be verified against the origin's.
	//
	// If it contains a vendor/modules.txt file, `go mod vendor` will be used to create one in the destination.
	ModuleFilePath string

	// ModuleImportPath is the import path of the module rooted in ModuleFilePath.
	//
	// It is a copy of Module.Path and present for consistency with RootTo.ModuleImportPath.
	ModuleImportPath string `mapstructure:"-"`

	// LocalFilePath is a path relative to ModuleFilePath which declares the root of all project-local files.
	//
	// It is read from the config file, resolved to an absolute path, and then used as the base path for
	// all Ops.From.*FilePath patterns.
	LocalFilePath string

	// LocalImportPath is the prefix of all packages under LocalFilePath.
	//
	// It is computed based on ModuleImportPath and LocalFilePath.
	LocalImportPath string `mapstructure:"-"`

	// GoFilePath matches directories in which implementation (and optionally test) packages should
	// be copied and analyzed for their dependencies.
	//
	// Matching directories will be inspected.
	// If Tests is true, test packages will be auto-discovered.
	// Only Go files will be copied.
	GoFilePath FilePathQuery

	// CopyOnlyFilePath matches files which should be copied but not inspected or refactored
	// (except for basic string replacement of source file/import paths).
	//
	// Each pattern is relative to FilePath.
	CopyOnlyFilePath FilePathQuery

	// GoDescendantFilePath first matches files which should be copied but not inspected or refactored
	// (except for basic string replacement of source file/import paths), same as CopyOnlyFilePath.
	// It also requires that each file is a descendant of directory which provides a Go package to the copy
	// (i.e. a dependency of a project matched by GoFilePath).
	//
	// For example, it supports the need to exclude files such as test fixtures whose only dependents are in
	// ancestor directories which will not be part of the copy.
	GoDescendantFilePath FilePathQuery

	// Rename defines file/directory path changes to perform during the copy operation.
	RenameFilePath []RenameSpec

	// ReplaceString defines the scope of string replacements to perform during copy operations.
	//
	// Replacements occur on the intersection between its matches and those of all other config patterns,
	// such as GoFilePath and CopyOnlyFilePath, which control the scope of the copy operation itself.
	ReplaceString ReplaceStringSpec

	// ModuleSum is true if <ModuleFilePath>/go.sum was found during config validation/finalization.
	ModuleSum bool `mapstructure:"-"`

	// Tests is true if GoFilePath-matched test packages and their dependencies should be included.
	Tests bool

	// Vendor is true if GOFLAGS contains "-mod=vendor" and <ModuleFilePath>/{go.sum,vendor/modules.txt} exists
	// (as indication that the origin is using the same vendoring tool as we are).
	//
	// go.sum is required because a prior `go mod vendor` run should have created one.
	Vendor bool `mapstructure:"-"`
}

type RootTo struct {
	// ModuleFilePath is the absolute path to the root of the copy's tree.
	ModuleFilePath string

	// ModuleImportPath is the import path of the module copied to ModuleFilePath.
	ModuleImportPath string

	// LocalFilePath is a path relative to ModuleFilePath which declares the root of all copied project-local files.
	LocalFilePath string

	// LocalImportPath is the prefix of all packages under LocalFilePath.
	//
	// It is computed based on ModuleImportPath and LocalFilePath.
	LocalImportPath string `mapstructure:"-"`
}