language

type BaseLang struct{}

type BaseLifecycleManager struct{}

type FinishableLanguage interface {
	// DoneGeneratingRules is called when all calls to GenerateRules have been
	// completed.
	// This allows for hooks to be called, for instance to release resources
	// such as shutting down a background server.
	// No further calls will be made to GenerateRules on this Language instance
	// after this method has been called.
	DoneGeneratingRules()
}

type GenerateArgs struct {
	// Config is the configuration for the directory where rules are being
	// generated.
	Config *config.Config

	// Dir is the canonical absolute path to the directory.
	Dir string

	// Rel is the slash-separated path to the directory, relative to the
	// repository root ("" for the root directory itself). This may be used
	// as the package name in labels.
	Rel string

	// File is the build file for the directory. File is nil if there is
	// no existing build file.
	File *rule.File

	// Subdirs is a list of subdirectories in the directory, including
	// symbolic links to directories that Gazelle will follow.
	// RegularFiles is a list of regular files including other symbolic
	// links.
	// GeneratedFiles is a list of generated files in the directory
	// (usually these are mentioned as "out" or "outs" attributes in rules).
	Subdirs, RegularFiles, GenFiles []string

	// OtherEmpty is a list of empty rules generated by other languages.
	// OtherGen is a list of generated rules generated by other languages.
	OtherEmpty, OtherGen []*rule.Rule
}

type GenerateResult struct {
	// Gen is a list of rules generated from files found in the directory
	// GenerateRules was asked to process. These will be merged with existing
	// rules or added to the build file.
	Gen []*rule.Rule

	// Empty is a list of rules that cannot be built with the files found in the
	// directory GenerateRules was asked to process. These will be merged with
	// existing rules. If the merged rules are empty, they will be deleted.
	Empty []*rule.Rule

	// Imports contains information about the imported libraries for each
	// rule in Gen. Gen and Imports must have the same length, since they
	// correspond. These values are passed to Resolve after merge. The type
	// is opaque since different languages may use different representations.
	Imports []interface{}
}

type ImportReposArgs struct {
	// Config is the configuration for the main workspace.
	Config *config.Config

	// Path is the name of the configuration file to import.
	Path string

	// Prune indicates whether repository rules that are no longer needed
	// should be deleted. This means the Empty list in the result should be
	// filled in.
	Prune bool

	// Cache stores information fetched from the network and ensures that
	// the same request isn't made multiple times.
	Cache *repo.RemoteCache
}

type ImportReposResult struct {
	// Gen is a list of imported repository rules.
	Gen []*rule.Rule

	// Empty is a list of repository rules that may be deleted. This should only
	// be set if ImportReposArgs.Prune is true.
	Empty []*rule.Rule

	// Error is any fatal error that occurred. Non-fatal errors should be logged.
	Error error
}

type Language interface {
	// TODO(jayconrod): is embedding Configurer strictly necessary?
	config.Configurer
	resolve.Resolver

	// Kinds returns a map of maps rule names (kinds) and information on how to
	// match and merge attributes that may be found in rules of those kinds. All
	// kinds of rules generated for this language may be found here.
	Kinds() map[string]rule.KindInfo

	// GenerateRules extracts build metadata from source files in a directory.
	// GenerateRules is called in each directory where an update is requested
	// in depth-first post-order.
	//
	// args contains the arguments for GenerateRules. This is passed as a
	// struct to avoid breaking implementations in the future when new
	// fields are added.
	//
	// A GenerateResult struct is returned. Optional fields may be added to this
	// type in the future.
	//
	// Any non-fatal errors this function encounters should be logged using
	// log.Print.
	GenerateRules(args GenerateArgs) GenerateResult

	// Loads returns .bzl files and symbols they define. Every rule generated by
	// GenerateRules, now or in the past, should be loadable from one of these
	// files.
	//
	// Deprecated: Implement ModuleAwareLanguage's ApparentLoads.
	Loads() []rule.LoadInfo

	// Fix repairs deprecated usage of language-specific rules in f. This is
	// called before the file is indexed. Unless c.ShouldFix is true, fixes
	// that delete or rename rules should not be performed.
	Fix(c *config.Config, f *rule.File)
}

type LifecycleManager interface {
	FinishableLanguage
	Before(ctx context.Context)
	AfterResolvingDeps(ctx context.Context)
}

type ModuleAwareLanguage interface {
	// ApparentLoads returns .bzl files and symbols they define. Every rule
	// generated by GenerateRules, now or in the past, should be loadable from
	// one of these files.
	//
	// The moduleToApparentName argument is a function that resolves a given
	// Bazel module name to the apparent repository name configured for this
	// module in the MODULE.bazel file, or the empty string if there is no such
	// module or the MODULE.bazel file doesn't exist. Languages should use the
	// non-empty value returned by this function to form the repository part of
	// the load statements they return and fall back to using the legacy
	// WORKSPACE name otherwise.
	//
	// See https://bazel.build/external/overview#concepts for more information
	// on repository names.
	//
	// Example: For a project with these lines in its MODULE.bazel file:
	//
	//   bazel_dep(name = "rules_go", version = "0.38.1", repo_name = "my_rules_go")
	//   bazel_dep(name = "gazelle", version = "0.27.0")
	//
	// moduleToApparentName["rules_go"] == "my_rules_go"
	// moduleToApparentName["gazelle"] == "gazelle"
	// moduleToApparentName["foobar"] == ""
	ApparentLoads(moduleToApparentName func(string) string) []rule.LoadInfo
}

type RepoImporter interface {
	// CanImport returns whether a given configuration file may be imported
	// with this extension. Only one extension may import any given file.
	// ImportRepos will not be called unless this returns true.
	CanImport(path string) bool

	// ImportRepos generates a list of repository rules by reading a
	// configuration file from another build system.
	ImportRepos(args ImportReposArgs) ImportReposResult
}

type RepoUpdater interface {
	UpdateRepos(args UpdateReposArgs) UpdateReposResult
}

type UpdateReposArgs struct {
	// Config is the configuration for the main workspace.
	Config *config.Config

	// Imports is a list of libraries to update. UpdateRepos should return
	// repository rules that provide these libraries. It may also return
	// repository rules providing transitive dependencies.
	Imports []string

	// Cache stores information fetched from the network and ensures that
	// the same request isn't made multiple times.
	Cache *repo.RemoteCache
}

type UpdateReposResult struct {
	// Gen is a list of repository rules that provide libraries named by
	// UpdateImportArgs.Imports. These will be merged with existing rules or
	// added to WORKSPACE. This list may be shorter or longer than the list
	// of imports, since a single repository may provide multiple imports,
	// and additional repositories may be needed for transitive dependencies.
	Gen []*rule.Rule

	// Error is any fatal error that occurred. Non-fatal errors should be logged.
	Error error
}