Add a new --format tree-full flag for oras discover

[Wwwsylvia]

As per the ORAS diagnose experience proposal, we should add a new --format tree-full flag for oras discover to control the detailed metadata output, such as printing the annotations.
Once we have a way to print the detailed metadata output, we can mark the --verbose flag as deprecated.

oras/docs/proposals/diagnose-experience.md

Lines 72 to 74 in 5280c67

	- Deprecate the `--verbose` flag and keep `--debug` flag to avoid ambiguity. It is reasonable to continue using `--debug` to enable the output of `DEBUG` level logs as it is in ORAS. Meanwhile, this change will make the diagnose experience much more straightforward and less breaking since only ORAS `pull/push/attach/discover` commands have verbose output.
	- Make the verbose output of commands `pull`, `push`, `attach` as the default (status) output. See examples at the bottom.
	- Make the verbose output of command `discover` as a formatted output, controlled by `--format tree-full`.

[Horiodino]

Hi, I’m interested in working on this. If no one else is currently assigned, would it be alright if I take it on?

[Wwwsylvia]

Hi @Horiodino , thank you for volunteering! Sure please feel free to create a PR and let us know if anything is unclear.

Just a note: In #1558 we deprecated the --verbose flag for other commands but oras discover. It's time to apply the same for oras discover as well when we add --format tree-full to it.

[sajayantony]

Really nice to see this coming together. Given that the discover was done before the OCI specification was finalized, it might be good to actually show the annotations in the default output. This aligns well with the API.

Annotations are the main way for a user to consume the output since IMHO the set of digests alone might not usable besides giving an indication.

Basically my vote would be to avoid a tree-full option and just make this the default output as its more usable.
i’m also considering the fact that that we are trying to have lesser options verbose|debug.

[Horiodino]

ok 👍 i will apply the changes

[Wwwsylvia]

When there are multiple referrers with the same artifact type, annotations can be helpful in distinguishing the referrers, however the way we display it does look overwhelming.

Here is an experiment I did:

oras discover output without annotations:

$ oras discover localhost:5000/testdiscover2501101:v1

localhost:5000/testdiscover2501101@sha256:495d9251cdd4ba2a744bcbb960d70ee67ee242e816ff35a451da9981ca4a3ab3
├── test/sbom
│   ├── sha256:600faa0d8129d59d637cac3b83103ead73893c5267020c22e634e68bbbe71e5f
│   │   ├── application/vnd.cncf.notary.signature
│   │   │   └── sha256:e198c5a2b6275b4e06d6efc40ce5c147cdcfc3d1bb6de626abf4d5b1ed2332a7
│   │   └── test/nested
│   │       └── sha256:14f8e26f838b03e7da1ef7512c2f0f0d1f081d9eef2be25652d1706e9c2ca0a5
│   └── sha256:b65067555c873544d4bf35d74fb9c43b3eee0b3875779954efea596e2b1b4600
│       └── application/vnd.cncf.notary.signature
│           └── sha256:90620e18d94f29fd2897fad3cee09f237a5e9c7047eb49c61adf2183f3cd3769
├── application/vnd.cncf.notary.signature
│   └── sha256:6707a13b21ac9a133a25bd65656a809b078d0f961eb3a3a630ad49faf09369be
└── test/discover
    └── sha256:6efa99819a5b3ffc6fb51b8cd48efbc71b5f63e1864bcd1a62485ff8dd8bded4

oras discover output with annotations:

$ oras discover localhost:5000/testdiscover2501101:v1 -v

localhost:5000/testdiscover2501101@sha256:495d9251cdd4ba2a744bcbb960d70ee67ee242e816ff35a451da9981ca4a3ab3
├── test/sbom
│   ├── sha256:600faa0d8129d59d637cac3b83103ead73893c5267020c22e634e68bbbe71e5f
│   │   ├── org.opencontainers.image.created: "2025-01-10T07:32:43Z"
│   │   ├── application/vnd.cncf.notary.signature
│   │   │   └── sha256:e198c5a2b6275b4e06d6efc40ce5c147cdcfc3d1bb6de626abf4d5b1ed2332a7
│   │   │       ├── io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│   │   │       └── org.opencontainers.image.created: "2025-01-10T07:33:53Z"
│   │   └── test/nested
│   │       └── sha256:14f8e26f838b03e7da1ef7512c2f0f0d1f081d9eef2be25652d1706e9c2ca0a5
│   │           └── org.opencontainers.image.created: "2025-01-10T07:36:39Z"
│   └── sha256:b65067555c873544d4bf35d74fb9c43b3eee0b3875779954efea596e2b1b4600
│       ├── org.opencontainers.image.created: "2025-01-10T07:34:18Z"
│       └── application/vnd.cncf.notary.signature
│           └── sha256:90620e18d94f29fd2897fad3cee09f237a5e9c7047eb49c61adf2183f3cd3769
│               ├── io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│               └── org.opencontainers.image.created: "2025-01-10T07:35:02Z"
├── application/vnd.cncf.notary.signature
│   └── sha256:6707a13b21ac9a133a25bd65656a809b078d0f961eb3a3a630ad49faf09369be
│       ├── io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│       └── org.opencontainers.image.created: "2025-01-10T07:35:50Z"
└── test/discover
    └── sha256:6efa99819a5b3ffc6fb51b8cd48efbc71b5f63e1864bcd1a62485ff8dd8bded4
        └── org.opencontainers.image.created: "2025-01-10T07:37:03Z"

oras discover output in table format:

$ oras discover localhost:5000/testdiscover2501101:v1 --format table

Discovered 4 artifacts referencing localhost:5000/testdiscover2501101:v1
Digest: sha256:495d9251cdd4ba2a744bcbb960d70ee67ee242e816ff35a451da9981ca4a3ab3

Artifact Type                           Digest
test/sbom                               sha256:600faa0d8129d59d637cac3b83103ead73893c5267020c22e634e68bbbe71e5f
test/sbom                               sha256:b65067555c873544d4bf35d74fb9c43b3eee0b3875779954efea596e2b1b4600
application/vnd.cncf.notary.signature   sha256:6707a13b21ac9a133a25bd65656a809b078d0f961eb3a3a630ad49faf09369be
test/discover                           sha256:6efa99819a5b3ffc6fb51b8cd48efbc71b5f63e1864bcd1a62485ff8dd8bded4

[FeynmanZhou]

Really nice to see this coming together. Given that the discover was done before the OCI specification was finalized, it might be good to actually show the annotations in the default output. This aligns well with the API.

Annotations are the main way for a user to consume the output since IMHO the set of digests alone might not usable besides giving an indication.

Basically my vote would be to avoid a tree-full option and just make this the default output as its more usable. i’m also considering the fact that that we are trying to have lesser options verbose|debug.

@sajayantony

The referrers' annotations are useful metadata for users. However, I have concerns on showing referrers' annotations recursively in the default output may complicate the tree hierarchy, especially when there are multiple referrers and each has a bunch of annotations. The reference graph relationship between the root image and referrers will be hard to recognized. Just as the example output shared by @Wwwsylvia above.

From the user's point of view, the purpose of querying a tree view is to list a tree of the referrers and show their dependency hierarchy. Annotations are supposed to be printed only when users want to dig into the detailed metadata of each referrer.

Considering annotation is a key-value format, I would suggest showing annotations metadata in a JSON or table format. This will provide a better user experience to the formatted output.

[shizhMSFT]

I would suggest refine the output of --format tree by merging --format tree-full into --format tree.

The problem of the --format tree-full is that the annotations are mixed with the artifact type of the referrers. Those annotations should share the same root node under the subject node.

[Wwwsylvia]

I would suggest refine the output of --format tree by merging --format tree-full into --format tree.

The problem of the --format tree-full is that the annotations are mixed with the artifact type of the referrers. Those annotations should share the same root node under the subject node

@shizhMSFT @FeynmanZhou

Just brainstorming - How about formatting the tree view to something like this:

localhost:5000/testdiscover2501101@sha256:495d9251cdd4ba2a744bcbb960d70ee67ee242e816ff35a451da9981ca4a3ab3
├── <test/sbom>
│   ├── sha256:600faa0d8129d59d637cac3b83103ead73893c5267020c22e634e68bbbe71e5f
│   │   ├── annotations:
│   │   │       * org.opencontainers.image.created: "2025-01-10T07:32:43Z"
│   │   ├── <application/vnd.cncf.notary.signature>
│   │   │   └── sha256:e198c5a2b6275b4e06d6efc40ce5c147cdcfc3d1bb6de626abf4d5b1ed2332a7
│   │   │       └── annotations:
│   │   │               * io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│   │   │               * org.opencontainers.image.created: "2025-01-10T07:33:53Z"
│   │   └── <test/nested>
│   │       └── sha256:14f8e26f838b03e7da1ef7512c2f0f0d1f081d9eef2be25652d1706e9c2ca0a5
│   │           └── annotations:
│   │                   * org.opencontainers.image.created: "2025-01-10T07:36:39Z"
│   ├── sha256:b65067555c873544d4bf35d74fb9c43b3eee0b3875779954efea596e2b1b4600
│   │   ├── annotations:
│   │   │       * org.opencontainers.image.created: "2025-01-10T07:34:18Z"
│   │   └── <application/vnd.cncf.notary.signature>
│   │       └── sha256:90620e18d94f29fd2897fad3cee09f237a5e9c7047eb49c61adf2183f3cd3769
│   │           └── annotations:
│   │                   * io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│   │                   * org.opencontainers.image.created: "2025-01-10T07:35:02Z"
├── <application/vnd.cncf.notary.signature>
│   └── sha256:6707a13b21ac9a133a25bd65656a809b078d0f961eb3a3a630ad49faf09369be
│       └── annotations:
│               * io.cncf.notary.x509chain.thumbprint#S256: '["37fca476dc777649d80b5337bfbc79aa2d083454918cf0658a9956c8054a8b77"]'
│               * org.opencontainers.image.created: "2025-01-10T07:35:50Z"
└── <test/discover>
    └── sha256:6efa99819a5b3ffc6fb51b8cd48efbc71b5f63e1864bcd1a62485ff8dd8bded4
        └── annotations:
                * org.opencontainers.image.created: "2025-01-10T07:37:03Z"

The idea is to:

1. Putting <> around the artifact type of the referrer
2. Making annotations a separate node
3. Use * mark to list the annotations

[shizhMSFT]

@Wwwsylvia Instead of putting special marks, I'm thinking about using different colors via TTY.

[Horiodino]

Could someone please give a final review so we can make the necessary changes? Everyone seems to have different opinions.