feat(github): add NewGithubResolvedPackageURL — SHA+originalRef fragment convention helper

[marcellodesales]

Summary

This PR proposes a new helper function NewGithubResolvedPackageURL that implements a convention for representing resolved GitHub action/repo references as a single, unambiguous PURL.

The problem

GitHub Actions (and other tooling) often pin dependencies using a mutable ref such as a tag (v4) or branch (main). Security best practice is to resolve these to an immutable commit SHA for supply-chain integrity. However, a bare SHA PURL like:

pkg:github/actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29

is opaque — a reader cannot tell what human-readable tag or branch it corresponds to without a lookup.

The convention

Encode the original mutable ref as the PURL subpath fragment (#), so both pieces of information travel together in a single PURL:

pkg:github/actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29#v4
pkg:github/org/repo@a5ac7e51b41094c92402da3b24376905380afc29#main
pkg:github/org/repo@a5ac7e51b41094c92402da3b24376905380afc29#feature/my-branch

For reusable workflow references (where the workflow file path also needs to be captured), a path= qualifier is added:

pkg:github/org/repo@<sha>?path=.github%2Fworkflows%2Fci.yml#main

This convention is inspired by purl-spec discussions around canonicalizing resolved VCS references. See the purl-spec issue for the spec proposal (link to be added once a purl-spec issue is opened).

What changed

• packageurl.go: Added NewGithubResolvedPackageURL(owner, repo, resolvedSHA, originalRef, path string) *PackageURL — a thin constructor that wires TypeGithub, sets the SHA as the version, the original mutable ref as the subpath (fragment), and optionally adds a path= qualifier.
• packageurl_test.go: Added TestNewGithubResolvedPackageURL covering: simple tag ref, branch ref, slash-containing branch ref, and reusable workflow with path qualifier.

Backwards compatibility

This is a pure addition — no existing types, constants, or functions are changed.

Test plan

• go test ./... passes (all spec fixture tests + new unit tests)
• NewGithubResolvedPackageURL("actions", "checkout", "<sha>", "v4", "").ToString() returns pkg:github/actions/checkout@<sha>#v4
• With a non-empty path, the path= qualifier appears percent-encoded in the output

🤖 Generated with Claude Code