cmd/cue: "help flags" documents unverifiable behaviour with --list and --merge

[jpluscplusm]

What version of CUE are you using (cue version)?

$ cue version
cue version v0.9.2

go version go1.22.4
      -buildmode exe
       -compiler gc
       -trimpath true
     CGO_ENABLED 0
          GOARCH amd64
            GOOS linux
         GOAMD64 v1
cue.lang.version v0.9.2

Does this issue reproduce with the latest stable release?

0.9.2 is latest.

What did you do?

I read https://cuelang.org/docs/reference/command/cue-help-flags/ (text updated here to reflect the correction anticipated in https://cuelang.org/cl/1199496):

Handling multiple documents or streams

To handle multi-document files, such as JSON Lines or YAML files with document separators (---), the user must specify the --merge, --list, or --files flag. The --merge flag merges each element into a single package as if each element was defined in a separate file. The --list flag concatenates each entry in a file into a list. Using --list flag in combination with the --merge flag concatenates entries with the same path into a list, instead of unifying them.

I then tried to use the information in the final sentence, combining --merge and --list in a single cue export command:

# Default behaviour is "--merge".
exec cue export data.yml
cmp stdout out.merge
exec cue export data.yml --merge
cmp stdout out.merge

# "--list" does something different".
exec cue export data.yml --list
cmp stdout out.list

# "--list --merge" behaves identically to "--list".
exec cue export data.yml --list --merge
cmp stdout out.list

-- data.yml --
---
A: 10
a:
  b: 1
doc0: true
---
A: 10
a:
  c: 2
doc1: true
---
A: 10
a:
  d: 3
doc2: true
-- out.merge --
{
    "A": 10,
    "a": {
        "b": 1,
        "c": 2,
        "d": 3
    },
    "doc0": true,
    "doc1": true,
    "doc2": true
}
-- out.list --
[
    {
        "A": 10,
        "a": {
            "b": 1
        },
        "doc0": true
    },
    {
        "A": 10,
        "a": {
            "c": 2
        },
        "doc1": true
    },
    {
        "A": 10,
        "a": {
            "d": 3
        },
        "doc2": true
    }
]

What did you expect to see?

I expected to see cue export --merge --list behaving differently from cue export --list, when given "entries with the same path" - resulting in a failing test.

What did you see instead?

A passing test. I can't provide a failing test, as I don't understand what effect the help text is documenting.

[myitcv]

cc @mvdan because this could be related to recent JSONL issues.

[mvdan]

Per my last review of https://review.gerrithub.io/c/cue-lang/cue/+/1199496 I actually think the help text was right in the original version; combining --list and --path is a supported behavior.

From my reading of the flags, combining --list and --merge shouldn't be useful, as they do opposite things, and perhaps we should treat that as an error for the sake of UX.

[myitcv]

text updated here to reflect the correction anticipated in https://cuelang.org/cl/1199496

I'm not clear that CL is correct FWIW, so I don't think we can rely on the expectations that follow.

I suggest we pick things up in https://github.com/cue-lang/cue/issues/3385 first.