build

type ArgDecl struct {
	Name    string
	Default string
	Line    string // original instruction text
}

type AttestationRecord struct {
	Type           AttestationType `json:"type,omitempty"`
	SignatureRef   string          `json:"signature_ref,omitempty"`   // cosign signature digest ref
	AttestationRef string          `json:"attestation_ref,omitempty"` // DSSE provenance digest ref
	SignerIdentity string          `json:"signer_identity,omitempty"` // workload identity / key fingerprint
	VerifiedDigest string          `json:"verified_digest,omitempty"` // digest the signature covers
}

type AttestationType string

type BuildInstance struct {
	Commit     string `json:"commit,omitempty"`
	PipelineID string `json:"pipeline_id,omitempty"`
	JobID      string `json:"job_id,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
}

type BuildPlan struct {
	Steps []BuildStep
}

type BuildResult struct {
	Steps    []StepResult
	Duration time.Duration
}

type BuildStep struct {
	Name         string
	Dockerfile   string
	Context      string
	Target       string
	Platforms    []string
	BuildArgs    map[string]string
	Labels       map[string]string // OCI labels injected via --label
	Tags         []string
	Output       OutputMode
	Extract      []ExtractRule    // artifact mode only
	Registries   []RegistryTarget // image mode only
	Load         bool             // --load into daemon
	Push         bool             // --push to registries
	SavePath     string           // save image tarball here after build (for security scanning)
	MetadataFile string           // temp file for buildx --metadata-file (digest capture)
}

type Buildx struct {
	Verbose bool
	Stdout  io.Writer
	Stderr  io.Writer
}

type CrucibleCheck struct {
	Name   string // e.g. "binary hash", "version", "image digest"
	Status string // "match", "differs", "unavailable"
	Detail string // e.g. "sha256:abc123..."
}

type CrucibleOpts struct {
	Image      string   // pass-1 candidate image ref
	FinalTag   string   // tag for the verification artifact
	RepoDir    string   // absolute path to repo root (mounted into container)
	ExtraFlags []string // original user flags minus --build-mode
	EnvVars    []string // credential and CI env vars to forward (KEY=VALUE)
	RunID      string   // correlates passes in logs
	Verbose    bool
}

type CrucibleResult struct {
	Passed        bool
	ExitCode      int
	FinalImageRef string
}

type CrucibleVerification struct {
	ArtifactChecks  []CrucibleCheck
	ExecutionChecks []CrucibleCheck
	TrustLevel      string
}

type DSSEEnvelope struct {
	PayloadType string          `json:"payloadType"`
	Payload     string          `json:"payload"` // base64-encoded ProvenanceStatement
	Signatures  []DSSESignature `json:"signatures"`
}

type DSSESignature struct {
	KeyID string `json:"keyid,omitempty"`
	Sig   string `json:"sig"`
}

type Detection struct {
	RootDir     string // absolute path to repo root
	Dockerfiles []DockerfileInfo
	Language    string   // "go", "rust", "node", "python", ""
	Lockfiles   []string // relative paths: go.mod, Cargo.toml, etc.
	GitInfo     *GitInfo
}

type DockerfileInfo struct {
	Path        string  // relative path from repo root
	Stages      []Stage // parsed multistage stages
	Args        []string
	Expose      []string
	Healthcheck *string
}

type Engine interface {
	Name() string
	Detect(ctx context.Context, rootDir string) (*Detection, error)
	Plan(ctx context.Context, cfg interface{}, det *Detection) (*BuildPlan, error)
	Execute(ctx context.Context, plan *BuildPlan) (*BuildResult, error)
}

type ExtractRule struct {
	From string // path inside the container
	To   string // local destination path
}

type GitInfo struct {
	Remote    string // origin URL
	Branch    string // current branch
	LatestTag string
	SHA       string
}

type InventoryResult struct {
	BaseImages []PackageInfo // normalized primary base image versions from FROM refs
	Lineage    []PackageInfo // inferred distro lineage from tag suffixes
	Packages   []PackageInfo // all discovered packages
	Args       []ArgDecl     // ARG declarations with defaults
}

type LayerEvent struct {
	Stage       string        // "builder", "stage-1", "" (for internal steps)
	StageStep   string        // "1/7", "2/7", etc.
	Instruction string        // "FROM", "COPY", "RUN", "WORKDIR", "ENV", "ARG", "EXPOSE", "ADD"
	Detail      string        // instruction arguments (truncated)
	Cached      bool          // true if layer was a cache hit
	Duration    time.Duration // layer execution time (0 for cached layers)
	Image       string        // for FROM: the base image name (without digest)
}

type OutputMode string

type PackageInfo struct {
	Name       string // package name
	Version    string // version if known, empty otherwise
	Pinned     bool   // true if version is explicitly pinned
	Source     string // broad category: "dockerfile", "dockerfile_arg", "base_image"
	SourceRef  string // narrow origin: the actual instruction or ARG declaration
	Manager    string // package manager name: "apk", "pip", "npm", "go", "galaxy", "binary", "base", "apt"
	Confidence string // "inferred" for heuristic-derived items, empty for authoritative
	URL        string // download URL for binary installs
	Stage      string // stage name from "AS <name>", empty for unnamed stages
	Final      bool   // true if this is from the last FROM stage (the shipped image)
}

type ProvenanceBuilder struct {
	ID string `json:"id"`
}

type ProvenanceInvocation struct {
	ConfigSource map[string]any `json:"configSource,omitempty"`
	Parameters   map[string]any `json:"parameters,omitempty"`
	Environment  map[string]any `json:"environment,omitempty"`
}

type ProvenanceMaterial struct {
	URI    string            `json:"uri"`
	Digest map[string]string `json:"digest,omitempty"`
}

type ProvenanceMetadata struct {
	BuildStartedOn  string          `json:"buildStartedOn,omitempty"`
	BuildFinishedOn string          `json:"buildFinishedOn,omitempty"`
	Completeness    map[string]bool `json:"completeness,omitempty"`
	Reproducible    bool            `json:"reproducible"`
}

type ProvenancePredicate struct {
	BuildType    string               `json:"buildType"`
	Builder      ProvenanceBuilder    `json:"builder"`
	Invocation   ProvenanceInvocation `json:"invocation"`
	Metadata     ProvenanceMetadata   `json:"metadata"`
	Materials    []ProvenanceMaterial `json:"materials,omitempty"`
	StageFreight map[string]any       `json:"stagefreight,omitempty"`
}

type ProvenanceStatement struct {
	Type          string              `json:"_type"`
	PredicateType string              `json:"predicateType"`
	Subject       []ProvenanceSubject `json:"subject"`
	Predicate     ProvenancePredicate `json:"predicate"`
}

type ProvenanceSubject struct {
	Name   string            `json:"name"`
	Digest map[string]string `json:"digest,omitempty"`
}

type PublishManifest struct {
	Published []PublishedImage `json:"published"`
	Timestamp string           `json:"timestamp"` // RFC3339
}

type PublishedImage struct {
	Host              string             `json:"host"`                          // normalized registry host
	Path              string             `json:"path"`                          // image path
	Tag               string             `json:"tag"`                           // resolved tag
	Provider          string             `json:"provider"`                      // canonical provider name
	Ref               string             `json:"ref"`                           // full image ref (host/path:tag)
	Digest            string             `json:"digest,omitempty"`              // image digest (immutable truth)
	CredentialRef     string             `json:"credential_ref,omitempty"`      // non-secret env var prefix for OCI auth resolution
	BuildInstance     BuildInstance      `json:"build_instance,omitempty"`      // CI/build metadata
	Registry          string             `json:"registry,omitempty"`            // registry hostname
	ObservedDigest    string             `json:"observed_digest,omitempty"`     // what the registry returned post-push
	ObservedDigestAlt string             `json:"observed_digest_alt,omitempty"` // second observation via registry API
	ObservedBy        string             `json:"observed_by,omitempty"`         // primary observation method (e.g., "buildx")
	ObservedByAlt     string             `json:"observed_by_alt,omitempty"`     // alternate observation method (e.g., "registry_api")
	ExpectedTags      []string           `json:"expected_tags,omitempty"`       // all tags this digest was published under
	ExpectedCommit    string             `json:"expected_commit,omitempty"`     // commit this digest was built from
	Attestation       *AttestationRecord `json:"attestation,omitempty"`         // signing/attestation record (nil = absent)
	SigningAttempted  bool               `json:"signing_attempted,omitempty"`   // true if signing was attempted but failed
}

type RegistryTarget struct {
	URL         string
	Path        string
	Tags        []string
	Credentials string                 // env var prefix for auth (e.g., "DOCKERHUB" → DOCKERHUB_USER/DOCKERHUB_PASS)
	Provider    string                 // registry vendor: dockerhub, ghcr, gitlab, jfrog, harbor, quay, gitea, generic
	Retention   config.RetentionPolicy // restic-style retention policy
	TagPatterns []string               // original unresolved tag templates for pattern matching during retention
}

type Stage struct {
	Name      string // alias from "AS name", empty if unnamed
	BaseImage string // the FROM image reference
	Line      int    // line number of the FROM instruction
}

type StepResult struct {
	Name      string
	Status    string       // "success", "failed", "cached"
	Images    []string     // pushed image references
	Artifacts []string     // extracted file paths
	Layers    []LayerEvent // parsed build layer events (from --progress=plain)
	Duration  time.Duration
	Error     error
}

type VerificationArtifact struct {
	Tag string // e.g. "stagefreight/crucible-verify:<run-id>"
}

type VersionInfo = gitver.VersionInfo