lockfile

type Artifact struct {
	Name   string `yaml:"name,omitempty" json:"name,omitempty"`
	Kind   string `yaml:"kind" json:"kind"`
	Target string `yaml:"target" json:"target"`
	Source Source `yaml:"source" json:"source"`
	Files  []File `yaml:"files" json:"files"`
	Order  int    `yaml:"order" json:"order"`
	// IncludedPaths/ExcludedPaths are the copy-filter patterns in effect when this artifact was
	// recorded (see RecordOptions.IncludedPaths/ExcludedPaths). Omitted entirely for artifacts
	// recorded with no filtering (mixins, and unfiltered sources), so a committed lock file written
	// before these fields existed loads with both nil -- IsMaterialized treats that identically to
	// an explicit empty list, never spuriously reporting drift on an old receipt.
	IncludedPaths []string `yaml:"included_paths,omitempty" json:"included_paths,omitempty"`
	ExcludedPaths []string `yaml:"excluded_paths,omitempty" json:"excluded_paths,omitempty"`
}

type CleanReport struct {
	Removed   []string
	Conflicts []Drift
}

type Drift struct {
	Artifact string
	Path     string
	Reason   string
}

type File struct {
	Path   string `yaml:"path" json:"path"`
	Type   string `yaml:"type" json:"type"`
	Mode   uint32 `yaml:"mode" json:"mode"`
	SHA256 string `yaml:"sha256" json:"sha256"`
}

type LockFile struct {
	Version   int                 `yaml:"version" json:"version"`
	Artifacts map[string]Artifact `yaml:"artifacts" json:"artifacts"`
}

type MaterializationCheck struct {
	Materialized bool
	// Reason is empty when Materialized is true. Otherwise one of: "no lock entry", "target path
	// changed", "declared source changed", "included/excluded paths changed", or a per-file reason
	// naming the file (e.g. `file "foo.tf" missing`, `file "foo.tf" checksum mismatch`).
	Reason string
}

type MaterializationParams struct {
	// ID is the lock artifact key -- see ArtifactID.
	ID string
	// Declared is the source's currently-declared URI (pre-redaction; IsMaterialized redacts it
	// itself before comparing against the receipt's already-redacted Source.Declared).
	Declared string
	// Target is the source's currently-declared destination path.
	Target string
	// IncludedPaths/ExcludedPaths are the source's currently-declared copy-filter patterns.
	IncludedPaths []string
	ExcludedPaths []string
}

type RecordOptions struct {
	// IncludedPaths/ExcludedPaths select VendorInventoryWithPatterns-style filtered inventory,
	// matching a vendor.yaml or component.yaml source's own copy-filter configuration. Passed
	// through even when both are empty (an unfiltered patterned source still uses this path,
	// matching this package's existing behavior).
	IncludedPaths []string
	ExcludedPaths []string
	// Mixin marks a mixin install: inventoried via plain VendorInventory (no pattern filtering,
	// since mixins install a set of individually-declared files rather than a filtered directory
	// copy), and its filename is appended to ArtifactID's writer list so a component and its
	// mixins never collide on the same lock key.
	Mixin         bool
	MixinFilename string
	// HTTPMetadata is best-effort HTTP cache metadata (ETag/Last-Modified) captured during the
	// fetch that staged tempDir, when it was an HTTP(S) source -- see downloader.FetchMetadata's
	// doc comment. Zero-value for git, OCI, and local sources, whose fetch has no HTTP response to
	// observe. Cache metadata only: never read by IsMaterialized or Verify, both of which continue
	// to rely solely on Digest and the per-file SHA256 values for integrity/drift decisions.
	HTTPMetadata downloader.FetchMetadata
	// VersionConstraint/ResolvedVersion record a range-declared `version:`'s resolution -- see
	// pkg/vendoring/install/version_resolve.go. Both empty for an exact-pinned version: (the common
	// case), matching Source.VersionConstraint/ResolvedVersion's own omitempty fields.
	VersionConstraint string
	ResolvedVersion   string
}

type RecordTarget struct {
	// Kind is the installer's PkgType.String() (e.g. "remote", "oci", "local").
	Kind string
	// Name is the vendor.yaml/component.yaml source's declared name.
	Name string
	// TempDir is the staged fetch content Record inventories.
	TempDir string
	// Path is the materialized destination (a vendor.yaml target or a component's path).
	Path string
	// DeclaredSource is the pre-fetch declared URI (oci:// restored, credentials still present --
	// Record redacts it via lockfile.RedactSource before it reaches the committed lock).
	DeclaredSource string
}

type Source struct {
	Declared     string `yaml:"declared" json:"declared"`
	Resolved     string `yaml:"resolved,omitempty" json:"resolved,omitempty"`
	Digest       string `yaml:"digest,omitempty" json:"digest,omitempty"`
	ETag         string `yaml:"etag,omitempty" json:"etag,omitempty"`
	LastModified string `yaml:"last_modified,omitempty" json:"last_modified,omitempty"`
	// VersionConstraint is the raw semver-range expression declared in a source's `version:` field
	// (e.g. "^1.0.0"), populated only when `version:` was a range rather than an exact pin. Empty
	// for every exact-pinned source -- the overwhelming common case. Distinct from Resolved above:
	// Resolved is the post-fetch resolved identity (e.g. a resolved commit/digest);
	// VersionConstraint/ResolvedVersion are pre-fetch version-range resolution provenance -- see
	// pkg/vendoring/install/version_resolve.go.
	VersionConstraint string `yaml:"version_constraint,omitempty" json:"version_constraint,omitempty"`
	// ResolvedVersion is the concrete version VersionConstraint last resolved to. Empty whenever
	// VersionConstraint is empty.
	ResolvedVersion string `yaml:"resolved_version,omitempty" json:"resolved_version,omitempty"`
}