config

type BadgeSpec struct {
	Label    string  // left side text (badge name / alt text)
	Value    string  // right side text (supports templates)
	Color    string  // hex color or "auto"
	Output   string  // SVG file output path
	Font     string  // built-in font name override
	FontSize float64 // font size override
	FontFile string  // custom font file override
}

type BuildConfig struct {
	// ID is the unique identifier for this build, referenced by targets.
	ID string `yaml:"id"`

	// Kind is the build type. Determines which fields are valid.
	// Supported: "docker", "binary".
	Kind string `yaml:"kind"`

	// SelectTags enables CLI filtering via --select.
	SelectTags []string `yaml:"select_tags,omitempty"`

	// BuildMode controls the build execution strategy.
	// Supported: "" (standard), "crucible" (self-proving rebuild).
	BuildMode string `yaml:"build_mode,omitempty"`

	// DependsOn references another build ID that must complete before this one.
	// Enables build ordering: binary builds before docker builds that consume them.
	DependsOn string `yaml:"depends_on,omitempty"`

	// Dockerfile is the path to the Dockerfile. Default: auto-detect.
	Dockerfile string `yaml:"dockerfile,omitempty"`

	// Context is the Docker build context path. Default: "." (repo root).
	Context string `yaml:"context,omitempty"`

	// Target is the --target stage name for multi-stage builds.
	Target string `yaml:"target,omitempty"`

	// Platforms lists the target platforms. Default: [linux/{current_arch}].
	Platforms []string `yaml:"platforms,omitempty"`

	// BuildArgs are key-value pairs passed as --build-arg. Supports templates.
	BuildArgs map[string]string `yaml:"build_args,omitempty"`

	// Cache holds build cache settings.
	Cache CacheConfig `yaml:"cache,omitempty"`

	// Builder is the toolchain that interprets the build.
	// Supported: "go". Future: "rust", "zig", "cargo".
	Builder string `yaml:"builder,omitempty"`

	// Command is the builder subcommand. e.g., "build" for "go build".
	// Default: "build".
	Command string `yaml:"command,omitempty"`

	// From is the source/input root or entry point.
	// e.g., "./src/cli" (Go package), "./src/main.rs" (Rust).
	From string `yaml:"from,omitempty"`

	// Output is the artifact name. Windows platforms auto-append ".exe".
	// Default: basename of From.
	Output string `yaml:"output,omitempty"`

	// Args are ordered raw arguments passed directly to the selected builder.
	// For Go: raw args to "go build". For Rust: raw args to "cargo build".
	// Supports template variables: {version}, {sha}, {sha:N}, {date}.
	Args []string `yaml:"args,omitempty"`

	// Env are build environment variables. e.g., {"CGO_ENABLED": "0"}
	Env map[string]string `yaml:"env,omitempty"`

	// Compress enables UPX compression on the output binary. Default: false.
	Compress bool `yaml:"compress,omitempty"`

	// Crucible holds crucible-specific configuration for binary builds.
	Crucible *CrucibleConfig `yaml:"crucible,omitempty"`
}

type CacheConfig struct {
	Watch      []WatchRule `yaml:"watch"`
	AutoDetect *bool       `yaml:"auto_detect"`
}

type CommitConfig struct {
	DefaultType  string       `yaml:"default_type,omitempty"`
	DefaultScope string       `yaml:"default_scope,omitempty"`
	SkipCI       bool         `yaml:"skip_ci,omitempty"`
	Push         bool         `yaml:"push,omitempty"`
	Conventional bool         `yaml:"conventional"`
	Backend      string       `yaml:"backend,omitempty"`
	Types        []CommitType `yaml:"types,omitempty"`
}

type CommitType struct {
	Key       string `yaml:"key"`
	Label     string `yaml:"label"`
	AliasFor  string `yaml:"alias_for,omitempty"`
	ForceBang bool   `yaml:"force_bang,omitempty"`
}

type CompiledPatterns struct {
	Include []*regexp.Regexp
	Exclude []*regexp.Regexp
}

type Condition struct {
	// Tag is a pattern matched against the git tag (CI_COMMIT_TAG).
	// Only evaluated when a tag is present. Prefix with ! to negate.
	Tag string `yaml:"tag,omitempty"`

	// Branch is a pattern matched against the git branch (CI_COMMIT_BRANCH).
	// Prefix with ! to negate.
	Branch string `yaml:"branch,omitempty"`
}

type Config struct {
	// Version must be 1. The pre-version config was an unversioned alpha
	// that never earned a schema number — this is the first stable schema.
	Version int `yaml:"version"`

	// Vars is a user-defined template variable dictionary.
	// Referenced as {var:name} anywhere templates are resolved.
	Vars map[string]string `yaml:"vars,omitempty"`

	// Defaults is inert YAML anchor storage. StageFreight ignores this
	// section entirely — it exists for users to define &anchors.
	Defaults yaml.Node `yaml:"defaults,omitempty"`

	// Sources defines build source configuration.
	Sources SourcesConfig `yaml:"sources"`

	// Policies defines named regex patterns for git tag and branch matching.
	Policies PoliciesConfig `yaml:"policies"`

	// Builds defines named build artifacts.
	Builds []BuildConfig `yaml:"builds"`

	// Targets defines distribution targets and side-effects.
	Targets []TargetConfig `yaml:"targets"`

	// Narrator defines content composition for file targets.
	Narrator []NarratorFile `yaml:"narrator"`

	// Lint holds lint-specific configuration (unchanged from v1).
	Lint LintConfig `yaml:"lint"`

	// Security holds security scanning configuration (unchanged from v1).
	Security SecurityConfig `yaml:"security"`

	// Commit holds configuration for the commit subsystem.
	Commit CommitConfig `yaml:"commit"`

	// Dependency holds configuration for the dependency update subsystem.
	Dependency DependencyConfig `yaml:"dependency"`

	// Docs holds configuration for the docs generation subsystem.
	Docs DocsConfig `yaml:"docs"`

	// Manifest holds configuration for the manifest subsystem.
	Manifest ManifestConfig `yaml:"manifest"`

	// Release holds configuration for the release subsystem.
	Release ReleaseConfig `yaml:"release"`
}

type CrucibleConfig struct {
	// ToolchainImage is the pinned container image for pass-2 verification.
	// e.g., "docker.io/library/golang:1.24-alpine"
	ToolchainImage string `yaml:"toolchain_image,omitempty"`
}

type DependencyCIConfig struct {
	Handoff DependencyHandoff `yaml:"handoff"` // default: continue
}

type DependencyCommitConfig struct {
	Enabled   bool                      `yaml:"enabled"`
	Type      string                    `yaml:"type"`
	Message   string                    `yaml:"message"`
	Push      bool                      `yaml:"push"`
	SkipCI    bool                      `yaml:"skip_ci"`
	Promotion DependencyCommitPromotion `yaml:"promotion"` // "direct" or "mr"
	MR        DependencyMRConfig        `yaml:"mr"`
}

type DependencyCommitPromotion string

type DependencyConfig struct {
	Enabled bool                   `yaml:"enabled"`
	Output  string                 `yaml:"output"`
	Scope   DependencyScopeConfig  `yaml:"scope"`
	Commit  DependencyCommitConfig `yaml:"commit"`
	CI      DependencyCIConfig     `yaml:"ci"`
}

type DependencyHandoff string

type DependencyMRConfig struct {
	BranchPrefix string `yaml:"branch_prefix"` // default: "stagefreight/deps"
	TargetBranch string `yaml:"target_branch"` // default: "" (CI default branch)
}

type DependencyScopeConfig struct {
	GoModules     bool `yaml:"go_modules"`
	DockerfileEnv bool `yaml:"dockerfile_env"` // umbrella for docker-image + github-release
}

type DetailRule struct {
	Condition `yaml:",inline"`

	// Detail is the detail level to use when this rule matches.
	// Values: "none", "counts", "detailed", "full".
	Detail string `yaml:"detail"`
}

type DocsCommitConfig struct {
	Enabled bool     `yaml:"enabled"`
	Type    string   `yaml:"type"`
	Message string   `yaml:"message"`
	Add     []string `yaml:"add"`
	Push    bool     `yaml:"push"`
	SkipCI  bool     `yaml:"skip_ci"`
}

type DocsConfig struct {
	Enabled    bool                 `yaml:"enabled"`
	Generators DocsGeneratorsConfig `yaml:"generators"`
	Commit     DocsCommitConfig     `yaml:"commit"`
}

type DocsGeneratorsConfig struct {
	Badges        bool `yaml:"badges"`
	ReferenceDocs bool `yaml:"reference_docs"`
	Narrator      bool `yaml:"narrator"`
	DockerReadme  bool `yaml:"docker_readme"`
}

type Level string

type LintConfig struct {
	Level        Level                   `yaml:"level"`
	CacheDir     string                  `yaml:"cache_dir"`
	TargetBranch string                  `yaml:"target_branch"`
	Exclude      []string                `yaml:"exclude"`
	Modules      map[string]ModuleConfig `yaml:"modules"`
}

type ManifestConfig struct {
	// Enabled controls whether manifest generation is active (default: false).
	Enabled bool `yaml:"enabled"`

	// Mode controls where the manifest is stored.
	// ephemeral: temp location, use during run, discard after.
	// workspace: generate to .stagefreight/manifests/, don't auto-commit.
	// commit: generate and include in docs commit.
	// publish: generate and export as release asset / CI artifact.
	Mode string `yaml:"mode,omitempty"`

	// OutputDir is the output directory for manifest files.
	// Default: .stagefreight/manifests
	OutputDir string `yaml:"output_dir,omitempty"`
}

type ModuleConfig struct {
	Enabled *bool          `yaml:"enabled,omitempty"`
	Exclude []string       `yaml:"exclude,omitempty"`
	Options map[string]any `yaml:"options,omitempty"`
}

type NarratorFile struct {
	// File is the path to the target file (required).
	File string `yaml:"file"`

	// LinkBase is the base URL for relative link rewriting.
	LinkBase string `yaml:"link_base,omitempty"`

	// Items are the composable content items for this file.
	Items []NarratorItem `yaml:"items"`
}

type NarratorItem struct {
	// ID is the item identifier (unique within file).
	ID string `yaml:"id"`

	// Kind is the item type: badge, shield, text, component, break, include.
	Kind string `yaml:"kind"`

	// Placement declares where this item goes in the target file.
	Placement NarratorPlacement `yaml:"placement"`

	// Text is the badge label (left side text).
	Text string `yaml:"text,omitempty"`

	// Value is the badge value (right side text, supports templates).
	Value string `yaml:"value,omitempty"`

	// Color is the badge color (hex or "auto").
	Color string `yaml:"color,omitempty"`

	// Font is the badge font name override.
	Font string `yaml:"font,omitempty"`

	// FontSize is the badge font size override.
	FontSize int `yaml:"font_size,omitempty"`

	// Output is the SVG output path for badge generation.
	Output string `yaml:"output,omitempty"`

	// Link is the clickable URL (kind: badge, shield).
	Link string `yaml:"link,omitempty"`

	// Shield is the shields.io path (kind: shield).
	Shield string `yaml:"shield,omitempty"`

	// Content is raw text/markdown content (kind: text).
	Content string `yaml:"content,omitempty"`

	// Spec is the component spec file path (kind: component).
	Spec string `yaml:"spec,omitempty"`

	// Path is the file path to include verbatim (kind: include).
	Path string `yaml:"path,omitempty"`

	// Source is an optional path to a manifest JSON file (kind: build-contents).
	// If omitted, uses the current scope manifest.
	Source string `yaml:"source,omitempty"`

	// Section is the dot-path into the manifest (kind: build-contents).
	// e.g., "inventories.pip", "build.args", "security.sbom"
	Section string `yaml:"section,omitempty"`

	// Renderer is the rendering format (kind: build-contents).
	// Supported: "table", "list", "kv".
	Renderer string `yaml:"renderer,omitempty"`

	// Columns selects which columns to render (kind: build-contents, renderer: table).
	Columns []string `yaml:"columns,omitempty"`

	// OutputFile is an optional standalone file output path (kind: build-contents).
	// When set, the rendered content is written as a standalone file.
	// Can be used alongside placement (section embedding) or alone.
	OutputFile string `yaml:"output_file,omitempty"`

	// Type is the props resolver type ID (kind: props).
	Type string `yaml:"type,omitempty"`

	// Params are provider-semantic inputs for the props resolver.
	Params map[string]string `yaml:"params,omitempty"`

	// Label overrides the auto-derived alt text for props.
	Label string `yaml:"label,omitempty"`

	// Style is a presentation override for shields.io badge style.
	Style string `yaml:"style,omitempty"`

	// Logo is a presentation override for shields.io logo name.
	Logo string `yaml:"logo,omitempty"`
}

type NarratorPlacement struct {
	// Between is a two-element array: [start_marker, end_marker].
	// Content is placed relative to these markers.
	Between [2]string `yaml:"between,omitempty"`

	// After is a regex/literal line match (reserved for future use).
	After string `yaml:"after,omitempty"`

	// Before is a regex/literal line match (reserved for future use).
	Before string `yaml:"before,omitempty"`

	// Heading is a markdown heading match (reserved for future use).
	Heading string `yaml:"heading,omitempty"`

	// Mode controls how content is placed:
	// replace (default), append, prepend, above, below.
	Mode string `yaml:"mode,omitempty"`

	// Inline renders items side-by-side when true (default: false).
	Inline bool `yaml:"inline,omitempty"`
}

type PoliciesConfig struct {
	// GitTags maps policy names to regex patterns for git tag matching.
	// e.g., "stable": "^\\d+\\.\\d+\\.\\d+$"
	// Named "git_tags" (not "tags") to avoid collision with Docker image tags.
	GitTags map[string]string `yaml:"git_tags"`

	// Branches maps policy names to regex patterns for branch matching.
	// e.g., "main": "^main$"
	Branches map[string]string `yaml:"branches"`
}

type ReleaseConfig struct {
	Enabled         bool   `yaml:"enabled"`
	SecuritySummary string `yaml:"security_summary"`
	RegistryLinks   bool   `yaml:"registry_links"`
	CatalogLinks    bool   `yaml:"catalog_links"`
}

type RetentionPolicy struct {
	KeepLast    int      `yaml:"keep_last"`    // keep the N most recent tags
	KeepDaily   int      `yaml:"keep_daily"`   // keep one per day for the last N days
	KeepWeekly  int      `yaml:"keep_weekly"`  // keep one per week for the last N weeks
	KeepMonthly int      `yaml:"keep_monthly"` // keep one per month for the last N months
	KeepYearly  int      `yaml:"keep_yearly"`  // keep one per year for the last N years
	Protect     []string `yaml:"protect"`      // tag patterns that are never deleted (v2)
}

type ScannersConfig struct {
	Trivy *bool `yaml:"trivy,omitempty"` // run Trivy image scan (default: true)
	Grype *bool `yaml:"grype,omitempty"` // run Grype image scan (default: true)
}

type SecurityConfig struct {
	Enabled        bool           `yaml:"enabled"`          // run vulnerability scanning (default: true)
	Scanners       ScannersConfig `yaml:"scanners"`         // per-scanner toggles
	SBOMEnabled    bool           `yaml:"sbom"`             // generate SBOM artifacts (default: true)
	FailOnCritical bool           `yaml:"fail_on_critical"` // fail the pipeline if critical vulns found
	OutputDir      string         `yaml:"output"`           // directory for scan artifacts (default: .stagefreight/security)

	// ReleaseDetail is the default detail level for security info in release notes.
	// Values: "none", "counts", "detailed", "full" (default: "counts").
	ReleaseDetail string `yaml:"release_detail"`

	// ReleaseDetailRules are conditional overrides evaluated top-down (first match wins).
	// Uses the standard Condition primitive for tag/branch matching with ! negation.
	ReleaseDetailRules []DetailRule `yaml:"release_detail_rules"`

	// OverwhelmMessage is the message lines shown when >1000 vulns are found.
	// Defaults to ["…maybe start here:"] with the OverwhelmLink below.
	OverwhelmMessage []string `yaml:"overwhelm_message"`

	// OverwhelmLink is an optional URL appended after OverwhelmMessage.
	// Defaults to a Psychology Today anxiety page. Empty string disables.
	OverwhelmLink string `yaml:"overwhelm_link"`
}

type SourceConfig struct {
	Kind          string `yaml:"kind"`           // source type (default: "git")
	Worktree      string `yaml:"worktree"`       // path to working tree (default: ".")
	URL           string `yaml:"url"`            // optional: enables deterministic link_base/raw_base derivation
	DefaultBranch string `yaml:"default_branch"` // optional: used with URL for raw_base derivation
}

type SourcesConfig struct {
	Primary SourceConfig `yaml:"primary"`
}

type TargetCondition struct {
	// Branches lists branch filters. Each entry is a policy name or "re:<regex>".
	// Empty = no branch filtering.
	Branches []string `yaml:"branches,omitempty"`

	// GitTags lists git tag filters. Each entry is a policy name or "re:<regex>".
	// Empty = no tag filtering.
	GitTags []string `yaml:"git_tags,omitempty"`

	// Events lists CI event type filters.
	// Supported: push, tag, release, schedule, manual, pull_request, merge_request.
	// Empty = no event filtering.
	Events []string `yaml:"events,omitempty"`
}

type TargetConfig struct {
	// ID is the unique identifier for this target (logging, status, enable/disable).
	ID string `yaml:"id"`

	// Kind is the target type. Determines which fields are valid.
	Kind string `yaml:"kind"`

	// Build references a BuildConfig.ID. Required for kind: registry.
	Build string `yaml:"build,omitempty"`

	// When specifies routing conditions for this target.
	When TargetCondition `yaml:"when,omitempty"`

	// SelectTags enables CLI filtering via --select.
	SelectTags []string `yaml:"select_tags,omitempty"`

	// URL is the registry/forge hostname (kind: registry, docker-readme, release).
	URL string `yaml:"url,omitempty"`

	// Provider is the vendor type for auth and API behavior.
	// Registry: docker, ghcr, gitlab, jfrog, harbor, quay, gitea, generic.
	// Release: github, gitlab, gitea.
	// If omitted on registry/docker-readme, inferred from URL.
	Provider string `yaml:"provider,omitempty"`

	// Path is the image path within the registry (kind: registry, docker-readme).
	Path string `yaml:"path,omitempty"`

	// Credentials is the env var prefix for authentication.
	// Resolution: try {PREFIX}_TOKEN first, else {PREFIX}_USER + {PREFIX}_PASS.
	Credentials string `yaml:"credentials,omitempty"`

	// Description is a short description override (kind: registry, docker-readme).
	Description string `yaml:"description,omitempty"`

	// Retention controls cleanup of old tags/releases.
	// Structured only in v2 (no scalar shorthand).
	Retention *RetentionPolicy `yaml:"retention,omitempty"`

	// Tags are tag templates resolved against version info (kind: registry).
	// e.g., ["{version}", "{major}.{minor}", "latest"]
	Tags []string `yaml:"tags,omitempty"`

	// NativeScan enables post-push vulnerability scanning via the registry's own built-in scanner.
	// Distinct from StageFreight's own scan pipeline (Trivy/Grype run by StageFreight itself).
	// Currently supported: Harbor (triggers Harbor's built-in Trivy after each push).
	// No-op for Docker Hub, GHCR, Quay, JFrog, and other providers.
	// Best-effort — scan failures warn but do not fail the build.
	// Push success does not imply scan success; results appear in the registry UI only.
	NativeScan bool `yaml:"native_scan,omitempty"`

	// File is the path to the README file (kind: docker-readme).
	File string `yaml:"file,omitempty"`

	// LinkBase is the base URL for relative link rewriting (kind: docker-readme).
	LinkBase string `yaml:"link_base,omitempty"`

	// SpecFiles lists component spec file paths (kind: gitlab-component).
	SpecFiles []string `yaml:"spec_files,omitempty"`

	// Catalog enables GitLab Catalog registration (kind: gitlab-component).
	Catalog bool `yaml:"catalog,omitempty"`

	// Aliases are rolling git tag aliases (kind: release).
	// e.g., ["{version}", "{major}.{minor}", "latest"]
	// Named "aliases" to avoid collision with Tags (image tags) and git_tags (policy filters).
	Aliases []string `yaml:"aliases,omitempty"`

	// ProjectID is the "owner/repo" or numeric ID for remote forge targets (kind: release).
	ProjectID string `yaml:"project_id,omitempty"`

	// SyncRelease syncs release notes + tags to a remote forge (kind: release, remote only).
	SyncRelease bool `yaml:"sync_release,omitempty"`

	// SyncAssets syncs scan artifacts to a remote forge (kind: release, remote only).
	SyncAssets bool `yaml:"sync_assets,omitempty"`

	// Archives references a binary-archive target ID (kind: release only).
	Archives string `yaml:"archives,omitempty"`

	// BinaryName overrides the binary name inside the archive (kind: binary-archive).
	// Auto-detected from referenced build if omitted.
	BinaryName string `yaml:"binary_name,omitempty"`

	// Format is the archive format: "tar.gz", "zip", or "auto" (kind: binary-archive).
	// "auto" picks zip for windows, tar.gz for everything else. Default: "auto".
	Format string `yaml:"format,omitempty"`

	// Name is the archive filename template (kind: binary-archive).
	// Supports: {id}, {version}, {os}, {arch}. e.g., "{id}-{version}-{os}-{arch}".
	Name string `yaml:"name,omitempty"`

	// Include lists extra files to bundle into the archive (kind: binary-archive).
	// e.g., ["README.md", "LICENSE"]
	Include []string `yaml:"include,omitempty"`

	// Checksums generates a SHA256SUMS file alongside archives (kind: binary-archive).
	Checksums bool `yaml:"checksums,omitempty"`
}

type WatchRule struct {
	Paths       []string `yaml:"paths"`
	Invalidates []string `yaml:"invalidates"`
}