config

type API struct {
	// The path to the API, relative to the root of the API definition repository (e.g., "google/storage/v1").
	Path string `yaml:"path" json:"path"`
	// The name of the service config file, relative to the API `path`.
	ServiceConfig string `yaml:"service_config" json:"service_config"`
	// The status of the API, one of "new" or "existing".
	// This field is ignored when writing to state.yaml.
	Status string `yaml:"-" json:"status,omitempty"`
}

type Commit struct {
	// Type is the type of change (e.g., "feat", "fix", "docs").
	Type string `json:"type"`
	// Subject is the short summary of the change.
	Subject string `json:"subject"`
	// Body is the long-form description of the change.
	Body string `json:"body"`
	// CommitHash is the full commit hash.
	CommitHash string `json:"commit_hash,omitempty"`
	// PiperCLNumber is the Piper CL number associated with the commit.
	PiperCLNumber string `json:"piper_cl_number,omitempty"`
	// A list of library IDs associated with the commit.
	LibraryIDs string `json:"-"`
}

type Config struct {
	// API is the path to the API to be configured or generated,
	// relative to the root of the googleapis repository. It is a directory
	// name as far as (and including) the version (v1, v2, v1alpha etc.). It
	// is expected to contain a service config YAML file.
	// Example: "google/cloud/functions/v2"
	//
	// API is used by generate and configure commands.
	//
	// API Path is specified with the -api flag.
	API string

	// APISource is the path to the root of the googleapis repository.
	// When this is not specified, the googleapis repository is cloned
	// automatically.
	//
	// APISource is used by generate and update-image commands.
	//
	// APISource is specified with the -api-source flag.
	APISource string

	// APISourceDepth controls the depth of the repository closing **IF**
	// APISource is a GitHub repository, and it is cloned.
	APISourceDepth int

	// Branch is the remote branch of the language repository to use.
	// This is the branch which is cloned when Repo is a URL, and also used
	// as the base reference for any pull requests created by the command.
	// By default, the branch "main" is used.
	Branch string

	// Build determines whether to build the generated library, and is only
	// used in the generate command.
	//
	// Build is specified with the -build flag.
	Build bool

	// CheckUnexpectedChanges determines whether to do additional checks for
	// unexpected changes during test-container generate.
	CheckUnexpectedChanges bool

	// CI is the type of Continuous Integration (CI) environment in which
	// the tool is executing.
	CI string

	// CommandName is the name of the command being executed.
	//
	// commandName is populated automatically after flag parsing. No user setup is
	// expected.
	CommandName string

	// Commit determines whether to create a commit for the release but not create
	// a pull request.
	//
	// This flag is ignored if Push is set to true.
	Commit bool

	// GenerateUnchanged determines whether to generate libraries where none of
	// the associated APIs have changed since the commit at which they were last
	// generated. Note that this does not override any configuration indicating
	// that the library should not be automatically generated.
	GenerateUnchanged bool

	// GitHubAPIEndpoint is the GitHub API endpoint to use for all GitHub API
	// operations.
	//
	// This is intended for testing and should not be used in production.
	GitHubAPIEndpoint string

	// GitHubToken is the access token to use for all operations involving
	// GitHub.
	//
	// GitHubToken is used by the generate, update-image, and release
	// init commands when Push is true.
	//
	// GitHubToken is not specified by a flag, as flags are logged and the
	// access token is sensitive information. Instead, it is fetched from the
	// LIBRARIAN_GITHUB_TOKEN environment variable.
	GitHubToken string

	// HostMount is used to remap Docker mount paths when running in environments
	// where Docker containers are siblings (e.g., Kokoro).
	// It specifies a mount point from the Docker host into the Docker container.
	// The format is "{host-dir}:{local-dir}".
	//
	// HostMount is specified with the -host-mount flag.
	HostMount string

	// Image is the language-specific container image to use for language-specific
	// operations. It is primarily used for testing Librarian and/or new images.
	//
	// Image is used by all commands which perform language-specific operations.
	// If this is set via the -image flag, it is expected to be used directly
	// (potentially including a repository and/or tag). If the -image flag is not
	// set, use an image configured in the `config.yaml`.
	//
	// Image is specified with the -image flag.
	Image string

	// Library is the library ID to generate (e.g. secretmanager).
	// This usually corresponds to a releasable language unit -- for Go this would
	// be a Go module or for dotnet the name of a NuGet package. If neither this nor
	// api is specified all currently managed libraries will be regenerated.
	Library string

	// LibraryToTest is the library ID to test (e.g. secretmanager).
	LibraryToTest string

	// LibraryVersion is the library version to release.
	//
	// Overrides the automatic semantic version calculation and forces a specific
	// version for a library.
	// This is intended for exceptional cases, such as applying a backport patch
	// or forcing a major version bump.
	//
	// Requires the --library flag to be specified.
	LibraryVersion string

	// Project is the ID of the Google Cloud project to use.
	Project string

	// PullRequest to target and operate one in the context of a release.
	//
	// The pull request should be in the format `https://github.com/{owner}/{repo}/pull/{number}`.
	// Setting this field for `tag` means librarian will only attempt
	// to process this exact pull request and not search for other pull requests
	// that may be ready for tagging and releasing.
	PullRequest string

	// Push determines whether to push changes to GitHub. It is used in
	// all commands that create commits in a language repository:
	// generate, release init, update-image.
	// These commands all create pull requests if they
	//
	// By default (when Push isn't explicitly specified), commits are created in
	// the language repo (whether a fresh clone or one specified with RepoRoot)
	// but no pull request is created. In this situation, the description of the
	// pull request that would have been created is displayed in the output of
	// the command.
	//
	// When Push is true, GitHubToken must also be specified.
	//
	// Push is specified with the -push flag. No value is required.
	Push bool

	// Repo specifies the language repository to use, as either a local root directory
	// or a URL to clone from. If a local directory is specified, it can
	// be relative to the current working directory. The repository must
	// be in a clean state (i.e. git status should report no changes) to avoid mixing
	// Librarian-created changes with other changes.
	//
	// Repo is used by all commands which operate on a language repository:
	// generate, release init, update-image.
	//
	// When a local directory is specified for the generate command, the repo is checked to
	// determine whether the specified API path is configured as a library. See the generate
	// command documentation for more details.
	// For all commands other than generate, omitting Repo is equivalent to
	// specifying Repo as https://github.com/googleapis/google-cloud-{Language}.
	//
	// Repo is specified with the -repo flag.
	Repo string

	// Test determines whether to run a test after generation.
	Test bool

	// UserGID is the group ID of the current user. It is used to run Docker
	// containers with the same user, so that created files have the correct
	// ownership.
	//
	// This is populated automatically after flag parsing. No user setup is
	// expected.
	UserGID string

	// UserUID is the user ID of the current user. It is used to run Docker
	// containers with the same user, so that created files have the correct
	// ownership.
	//
	// This is populated automatically after flag parsing. No user setup is
	// expected.
	UserUID string

	// WorkRoot is the root directory used for temporary working files, including
	// any repositories that are cloned. By default, this is created in /tmp with
	// a timestamped directory name (e.g. /tmp/librarian-20250617T083548Z) but
	// can be specified with the -output flag.
	//
	// WorkRoot is used by all librarian commands.
	WorkRoot string
}

type GlobalFile struct {
	Path        string `yaml:"path"`
	Permissions string `yaml:"permissions"`
}

type LibrarianConfig struct {
	GlobalFilesAllowlist []*GlobalFile    `yaml:"global_files_allowlist"`
	Libraries            []*LibraryConfig `yaml:"libraries"`
	TagFormat            string           `yaml:"tag_format"`
}

type LibrarianState struct {
	// The name and tag of the generator image to use. tag is required.
	Image string `yaml:"image" json:"image"`
	// A list of library configurations.
	Libraries []*LibraryState `yaml:"libraries" json:"libraries"`
}

type LibraryConfig struct {
	GenerateBlocked bool   `yaml:"generate_blocked"`
	LibraryID       string `yaml:"id"`
	NextVersion     string `yaml:"next_version"`
	ReleaseBlocked  bool   `yaml:"release_blocked"`
	TagFormat       string `yaml:"tag_format"`
	// Whether to create a GitHub release for this library.
	SkipGitHubReleaseCreation bool `yaml:"skip_github_release_creation"`
}

type LibraryState struct {
	// A unique identifier for the library, in a language-specific format.
	// A valid ID should not be empty and only contains alphanumeric characters, slashes, periods, underscores, and hyphens.
	ID string `yaml:"id" json:"id"`
	// The last released version of the library, following SemVer.
	Version string `yaml:"version" json:"version"`
	// The commit hash from the API definition repository at which the library was last generated.
	LastGeneratedCommit string `yaml:"last_generated_commit" json:"-"`
	// The changes from the language repository since the library was last released.
	// This field is ignored when writing to state.yaml.
	Changes []*Commit `yaml:"-" json:"changes,omitempty"`
	// A list of APIs that are part of this library.
	APIs []*API `yaml:"apis" json:"apis"`
	// A list of directories in the language repository where Librarian contributes code.
	SourceRoots []string `yaml:"source_roots" json:"source_roots"`
	// The previous release version, this field is only for bookkeeping.
	PreviousVersion string `yaml:"-" json:"-"`
	// A list of regular expressions for files and directories to preserve during the copy and remove process.
	PreserveRegex []string `yaml:"preserve_regex" json:"preserve_regex"`
	// A list of regular expressions for files and directories to remove before copying generated code.
	// If not set, this defaults to the `source_roots`.
	// A more specific `preserve_regex` takes precedence.
	RemoveRegex []string `yaml:"remove_regex" json:"remove_regex"`
	// A list of paths to exclude from the release.
	// Files matching these paths will not be considered part of a commit for this library.
	ReleaseExcludePaths []string `yaml:"release_exclude_paths,omitempty" json:"release_exclude_paths,omitempty"`
	// Specifying a tag format allows librarian to honor this format when creating
	// a tag for the release of the library. The replacement values of {id} and {version}
	// permitted to reference the values configured in the library. If not specified
	// the assumed format is {id}-{version}. e.g., {id}/v{version}.
	TagFormat string `yaml:"tag_format,omitempty" json:"tag_format,omitempty"`
	// Whether including this library in a release.
	// This field is ignored when writing to state.yaml.
	ReleaseTriggered bool `yaml:"-" json:"release_triggered,omitempty"`
	// An error message from the docker response.
	// This field is ignored when writing to state.yaml.
	ErrorMessage string `yaml:"-" json:"error,omitempty"`
}