Document tag and digest reference semantics

[Haihan-Jiang]

Fixes #2287

This clarifies how pkg/name handles references such as repo:tag@sha256:.... These are accepted as digest references: the digest is the identifier used by the parsed reference, while the original string still preserves the tag.

Changes:

• update package docs to mention references with both tag and digest
• note that ParseReference returns a Digest for that form
• add a focused test for Identifier(), Name(), and String() behavior

Tested:

• go test ./pkg/name
• go test ./...

[Haihan-Jiang]

This is ready for review. The tag and digest reference semantics are now documented, and the visible checks are green.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.91%. Comparing base (31df54c) to head (1649ed1).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2325   +/-   ##
=======================================
  Coverage   56.91%   56.91%           
=======================================
  Files         165      165           
  Lines       11362    11362           
=======================================
  Hits         6467     6467           
  Misses       4134     4134           
  Partials      761      761           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.