claircore: add Alias type

This provides a standardized way to identify aliases and
cross-references between vulnerabilities.

See-also: https://issues.redhat.com/browse/CLAIRDEV-85
Change-Id: I7255300dddb328dcb5b579523c8efcffe1a560f0
Signed-off-by: Hank Donnay <hdonnay@redhat.com>

Author: hdonnay

alias.go

@@ -0,0 +1,49 @@
+package claircore
+
+import (
+	"strings"
+	"unique"
+)
+
+// Alias is an identifier for the same conceptual vulnerability.
+// An alias has two parts: the namespace and the name.
+//
+// The namespace has no format restrictions, but is almost certainly in one of two
+// formats:
+//   - URI (https://example.com/)
+//   - short prefix (EX)
+//
+// The name has no format restrictions and is only assumed to be unique within
+// the namespace.
+type Alias struct {
+	Space unique.Handle[string]
+	Name  string
+}
+
+// String implements [fmt.Stringer].
+func (a Alias) String() string {
+	space := a.Space.Value()
+
+	var b strings.Builder
+	b.WriteString(space)
+	if strings.Contains(space, "://") { // If URI-ish:
+		b.WriteByte('#')
+	} else {
+		b.WriteByte('-')
+	}
+	b.WriteString(a.Name)
+
+	return b.String()
+}
+
+// Equal reports if two Aliases are the same alias.
+func (a Alias) Equal(b Alias) bool {
+	return a.Space == b.Space && a.Name == b.Name
+}
+
+// Valid reports if the receiver is a valid alias.
+//
+// A invalid alias is one with a missing or empty Space or Name.
+func (a Alias) Valid() bool {
+	return a.Space != unique.Handle[string]{} && a.Space.Value() != "" && a.Name != ""
+}

alias_test.go

@@ -0,0 +1,32 @@
+package claircore
+
+import (
+	"fmt"
+	"unique"
+)
+
+func alias(space, name string) Alias {
+	return Alias{
+		Space: unique.Make(space),
+		Name:  name,
+	}
+}
+
+func ExampleAlias_uri() {
+	fmt.Println(alias("https://example.com/", "CVE-2014-0160"))
+	// Output:
+	// https://example.com/#CVE-2014-0160
+}
+
+func ExampleAlias_cve() {
+	fmt.Println(alias("CVE", "2014-0160"))
+	// Output:
+	// CVE-2014-0160
+}
+
+func ExampleAlias_Equal() {
+	a, b := alias("CVE", "2014-0160"), alias("CVE", "2014-0160")
+	fmt.Println("equal:", a.Equal(b))
+	// Output:
+	// equal: true
+}

vulnerability.go

@@ -38,6 +38,17 @@ type Vulnerability struct {
 	// ArchOperation indicates how the affected Package's "arch" should be
 	// compared.
 	ArchOperation ArchOp `json:"arch_op,omitempty"`
+
+	// Self is an Alias that is the "identity" for this Vulnerability.
+	//
+	// This should be a system-wide, external identifier.
+	Self Alias
+	// Aliases is a set of aliases for the same abstract software flaw.
+	//
+	// For example, GHSA advisories frequently also reference CVE identifiers.
+	//
+	// This may contain the "Self" alias.
+	Aliases []Alias
 }
 
 // CheckVulnernableFunc takes a vulnerability and an indexRecord and checks if the record is