feat!: refine oras discover JSON format #1649

wangxiaoxuan273 · 2025-03-10T03:04:51Z

What this PR does / why we need it:

This Pull Request:

adds the information for the subject manifest to the output of oras discover when using the --format json option.
changes the output field name of manifests to referrers.

Current display:

$ oras discover mcr.microsoft.com/oss/kubernetes/kubectl:v1.29.1 --format json
{
  "reference": "mcr.microsoft.com/oss/kubernetes/kubectl@sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:bece4f4746a39cb39e38451c70fa5a1e5ea4fa20d4cca40136b51d9557918b01",
  "size": 1788,
  "referrers": [
    {
      "reference": "mcr.microsoft.com/oss/kubernetes/kubectl@sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:325129be79f416fe11a9ec44233cfa57f5d89434e6d37170f97e48f7904983e3",
      "size": 788,
      "annotations": {
        "org.opencontainers.image.created": "2024-03-15T22:49:10Z",
        "vnd.microsoft.artifact.lifecycle.end-of-life.date": "2024-03-15"
      },
      "artifactType": "application/vnd.microsoft.artifact.lifecycle"
    },
.....

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Part of #1403

Please check the following list:

Does the affected code have corresponding tests, e.g. unit test, E2E test?
Does this change require a documentation update?
Does this introduce breaking changes that would require an announcement or bumping the major version?
Do all new files have an appropriate license header?

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

codecov · 2025-03-10T06:52:33Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.53%. Comparing base (a3f3230) to head (1f10d83).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1649   +/-   ##
=======================================
  Coverage   84.52%   84.53%           
=======================================
  Files         126      126           
  Lines        5681     5682    +1     
=======================================
+ Hits         4802     4803    +1     
  Misses        625      625           
  Partials      254      254

☔ View full report in Codecov by Sentry.
📢 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.

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

cmd/oras/internal/display/metadata/model/discover.go

Copilot

PR Overview

This PR updates the output of the oras discover command when using JSON and go-template formats by including a dedicated subject field and renaming the existing manifests field to referrers. The changes affect tests, command help text, metadata models, and related helper functions to support the new structure.

Updated test expectations to unmarshal into a new structure with Subject and Referrers.
Modified CLI examples and internal model functions to align with the new JSON format.
Adjusted multiple e2e tests to validate the updated discover output across different outputs (json, tree, table, etc).

Reviewed Changes

File	Description
test/e2e/suite/command/discover.go	Replaced references to "manifests" with a new "discover" struct containing Subject and Referrers.
test/e2e/internal/testdata/foobar/const.go	Added new descriptor constants (FooBar, FooBarOCI) for subject manifest support.
cmd/oras/root/discover.go	Updated CLI help examples to use the new referrers field in go-template output.
cmd/oras/internal/display/metadata/model/discover.go	Changed model structure and NewDiscover signature to include subject and referrers instead of manifests.
test/e2e/suite/command/resolve_host.go, cp.go, attach.go, oci_artifact.go	Adjusted tests to reference the new referrers field consistently across JSON and go-template outputs.
cmd/oras/internal/display/metadata/template/discover.go and json/discover.go	Updated construction of discover models to pass subject information appropriately.

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (2)

test/e2e/suite/command/discover.go:110

[nitpick] The struct name 'discover' is very generic and is repeatedly defined across multiple test files. Consider renaming it or extracting it into a common helper to improve maintainability.

type discover struct {

test/e2e/suite/command/discover.go:131

[nitpick] While JSON output tests validate the subject field, consider adding tests for non-JSON outputs (e.g., tree and table) to ensure that the subject information is consistently conveyed.

It("should include information of subject and referrers manifests", func() {

cmd/oras/internal/display/metadata/model/discover.go

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

Copilot

Pull Request Overview

This PR updates the output of the oras discover command to include the subject manifest and renames the output field from "manifests" to "referrers" when using the JSON format. Key changes include:

Updating tests and examples to expect a subject descriptor and referrers field.
Changing the underlying model and template implementations to replace "manifests" with "referrers".
Adjusting go-template examples and related E2E tests to reflect the renamed field.

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/e2e/suite/command/discover.go	Updated JSON parsing in tests to check "referrers" instead of "manifests" and include subject validation.
test/e2e/internal/testdata/foobar/const.go	Added new descriptor constants for subject manifests.
cmd/oras/root/discover.go	Updated go-template example to output "referrers".
cmd/oras/internal/display/metadata/model/discover.go	Updated model to accept a subject and referrers, and renamed JSON key.
test/e2e/suite/command/cp.go	Updated tests to verify output based on "referrers" field.
test/e2e/suite/command/resolve_host.go	Updated tests to check the new JSON field "referrers".
test/e2e/suite/command/attach.go	Adjusted attachment tests to output and verify using "referrers".
test/e2e/suite/scenario/oci_artifact.go	Updated artifact tests to use "referrers" in go-template output.
cmd/oras/internal/display/metadata/json/discover.go	Updated JSON discover handler to pass the subject manifest.
cmd/oras/internal/display/metadata/template/discover.go	Updated template discover handler accordingly.

Comments suppressed due to low confidence (1)

test/e2e/suite/command/discover.go:110

[nitpick] Consider extracting the repeated inline 'discover' struct definition into a shared test helper to improve maintainability and consistency across tests.

type discover struct {

Wwwsylvia

LGTM

TerryHowe

/lgtm

wangxiaoxuan273 · 2025-03-13T02:16:11Z

Spec related: #1625

shizhMSFT

LGTM but this PR depends on #1625

FeynmanZhou · 2025-03-14T05:52:29Z

@shizhMSFT @wangxiaoxuan273 @oras-project/oras-cli You can review this PR now #1625

shizhMSFT

LGTM

feat: oras discover json format should include the subject manifest

69aa690

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

wangxiaoxuan273 requested review from sajayantony, shizhMSFT, SteveLasker, qweeah, Wwwsylvia and TerryHowe as code owners March 10, 2025 03:04

Xiaoxuan Wang added 6 commits March 10, 2025 11:17

fix failed e2e tests

7df8894

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

fix one test

95d2e8a

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

fix error

31f3682

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

fix typo

0917cea

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

update e2e tests

e1d1921

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

update e2e tests

42d1a62

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

Xiaoxuan Wang added 3 commits March 10, 2025 15:50

added new e2e test

f57cd7c

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

fix failed test

6ca4d01

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

add more tests

6f1b895

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

wangxiaoxuan273 mentioned this pull request Mar 10, 2025

docs: improve formatted output for oras discover #1625

Merged

4 tasks

update OCI e2e test

b3afe16

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

wangxiaoxuan273 commented Mar 10, 2025

View reviewed changes

cmd/oras/internal/display/metadata/model/discover.go Outdated Show resolved Hide resolved

Merge branch 'main' into discover-json-show-image

43c8c71

Wwwsylvia requested a review from Copilot March 10, 2025 08:44

Copilot AI reviewed Mar 10, 2025

View reviewed changes

shizhMSFT changed the title ~~feat: oras discover json format should include the subject manifest~~ feat!: oras discover json format should include the subject manifest Mar 10, 2025

shizhMSFT requested a review from FeynmanZhou March 10, 2025 14:16

Wwwsylvia reviewed Mar 11, 2025

View reviewed changes

cmd/oras/internal/display/metadata/model/discover.go Outdated Show resolved Hide resolved

cmd/oras/internal/display/metadata/model/discover.go Outdated Show resolved Hide resolved

Xiaoxuan Wang added 2 commits March 12, 2025 11:00

update UX

8e907d4

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

Merge branch 'main' into discover-json-show-image

2c6676b

wangxiaoxuan273 force-pushed the discover-json-show-image branch from aad8926 to 2c6676b Compare March 12, 2025 05:35

update test

169bc35

Signed-off-by: Xiaoxuan Wang <xiaoxuanwang@microsoft.com>

wangxiaoxuan273 force-pushed the discover-json-show-image branch from d5c8168 to 169bc35 Compare March 12, 2025 05:42

wangxiaoxuan273 requested review from Copilot and Wwwsylvia March 12, 2025 05:44

Copilot AI reviewed Mar 12, 2025

View reviewed changes

Wwwsylvia approved these changes Mar 12, 2025

View reviewed changes

TerryHowe approved these changes Mar 12, 2025

View reviewed changes

shizhMSFT changed the title ~~feat!: oras discover json format should include the subject manifest~~ feat!: refine oras discover JSON format Mar 14, 2025

shizhMSFT requested changes Mar 14, 2025

View reviewed changes

shizhMSFT mentioned this pull request Mar 14, 2025

feat!: support showing indirect referrers for all formats of oras discover #1653

Merged

4 tasks

Merge branch 'main' into discover-json-show-image

1f10d83

shizhMSFT approved these changes Mar 25, 2025

View reviewed changes

Wwwsylvia merged commit eccaaa9 into oras-project:main Mar 25, 2025
8 checks passed

Wwwsylvia mentioned this pull request Apr 24, 2025

bump: tag and release ORAS CLI v1.3.0-beta.3 #1705

Merged

6 tasks

wangxiaoxuan273 deleted the discover-json-show-image branch August 25, 2025 02:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat!: refine oras discover JSON format #1649

feat!: refine oras discover JSON format #1649

Uh oh!

wangxiaoxuan273 commented Mar 10, 2025 •

edited

Loading

Uh oh!

codecov bot commented Mar 10, 2025 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Wwwsylvia left a comment

Uh oh!

TerryHowe left a comment

Uh oh!

wangxiaoxuan273 commented Mar 13, 2025

Uh oh!

shizhMSFT left a comment

Uh oh!

FeynmanZhou commented Mar 14, 2025 •

edited

Loading

Uh oh!

shizhMSFT left a comment

Uh oh!

Uh oh!

Uh oh!

feat!: refine oras discover JSON format #1649

feat!: refine oras discover JSON format #1649

Uh oh!

Conversation

wangxiaoxuan273 commented Mar 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

PR Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Wwwsylvia left a comment

Choose a reason for hiding this comment

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

wangxiaoxuan273 commented Mar 13, 2025

Uh oh!

shizhMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

FeynmanZhou commented Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shizhMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

wangxiaoxuan273 commented Mar 10, 2025 •

edited

Loading

codecov bot commented Mar 10, 2025 •

edited

Loading

FeynmanZhou commented Mar 14, 2025 •

edited

Loading