// Ref represents the parsed structure of an OCM component reference.
// A component reference is a string that uniquely identifies a component in a repository.
//
// The format of a component reference is:
//
//	[<type>::]<repository>/[<valid-prefix>]/<component>[:<version>][@<digest>]
//
// For valid prefixes, see ValidPrefixes.
// For valid components, see ComponentRegex.
// For valid versions, see VersionRegex.
// For valid digests, see DigestRegex.
type Ref struct {
	// Type represents the repository type (e.g., "oci", "ctf")
	Type string

	// Repository is the location of the component repository
	Repository runtime.Typed

	// Prefix is an optional path element that helps structure components within a repository
	// It can only be one of ValidPrefixes.
	Prefix string

	// Component is the name of the component.
	// Validated as per ComponentRegex.
	Component string

	// Version is the semantic version of the component. It can be specified without Digest,
	// in which case it is a "soft" version pinning in that the content behind the version
	// can change without the specification becoming invalid.
	// Validated as per VersionRegex.
	Version string

	// Digest is an optional content-addressable identifier for a pinned component version (e.g., sha256:abcd...)
	// if present, it indicates a specific version of the component MUST be present with this digest.
	// Thus, the Digest is more authoritative than the Version.
	// Validates as per DigestRegex.
	Digest string
}

// Parse parses an input string into a Ref.
// Accepted inputs are of the forms
//
//   - [ctf::][<file path>/[<DefaultPrefix>]/<component id>[:<version>][@<digest>]
//   - [oci::][<registry>/<repository>/[<DefaultPrefix>]/<component id>[:<version>][@<digest>]
//   - localhost[:<port>]/[<DefaultPrefix>]/<component id>[:<version>] - localhost special cases
//
// Not accepted cases that were valid in old OCM:
//
//   - [type::][<repositorySpecJSON>/[<DefaultPrefix>]/<component id>[:<version>] - arbitrary repository definitions
//   - <repositoryAlias>//[<DefaultPrefix>]/<component id>[:<version>] - repository aliases for the ocm configuration
//
// All non-supported special cases are currently under review of being accepted forms.
func Parse(input string) (*Ref, error) { ... }