Coloured output

[EpicWink]

Problem

A little difficult to distinguish between context, added, deleted, and modified properties in monochromatic output.

Proposal

Add option to have coloured output:

• For YAML, JSON and text format, if the output is a TTY, using terminal escapes
• For HTML, using CSS (ideally via classes)

Perhaps on by default (-color auto), with explicit enable/disable (disregard output not being a TTY for -color always).

Blue for context (endpoint method/paths, 'XXX changed'), red for deleted, orange/yellow for modified, and green for added.

Alternatives

Deal with no colours.

[JSSAggie]

Would this add the ability to turn off the colors? If so I am all for it. We are pulling the breaking changes into our API spec pul requests and the color values in the error messages are not helping (:

[EpicWink]

CI usually does not have stdout be a TTY, so my proposal would default to no colours in that case

[reuvenharrison]

@JSSAggie oasdiff automatically disables colored output when it detects piped output so you can easily remove the colors as follows:
oasdiff breaking spec1 spec2 | cat
or
oasdiff changelog spec1 spec2 | cat

[JSSAggie]

I still think the flag is valuable. We can pipe out to a json file in the meantime.

[reuvenharrison]

Hi @JSSAggie,
#386 will remove color codes from json and yaml output.
Does this address your requirement?

[JSSAggie]

Looks like that will do it. Thanks

[ls-jad-elkik]

It's unclear to me if the -color always suggestion was actually implemented in the linked PR.

I would find this helpful since in our CI we'd like to oasdiff breaking ... | tee artifacts/diff.txt to be able to process that txt file later on while still showing colors in the CI step itself. So the auto-detection of a TTY with no override is backfiring in our case.

[reuvenharrison]

Hi @ls-jad-elkik,
We haven't yet implemented -color always.
As of now oasdiff only adds ANSI Color Escape Sequences if the output is not piped.
I would recommend running oasdiff twice as a temporary workaround, once with output to the CI step and once again to store the artifact.

In preparation for a proper solution, could you clarify whether you expect artifacts/diff.txt to contain colors or not?

[ls-jad-elkik]

Hi @reuvenharrison,

We're going to be using the workaround. The idea was to maybe strip the color codes before storing the artifact, because along with colors the indentation is gone when tty detection kicks in. And indentation is also important to make it readable.

I don't think it's a very critical feature, but it's kind of standard to either have that --color=[auto|always|off] flag or COLOR=XXX env var or FORCE_COLOR env var, etc.

Thanks for the quick reply and clarification.

[reuvenharrison]

We will add --color=[auto|always|never]
Thanks for your input!

[reuvenharrison]

The latest release adds support for color=auto|always|never
Your feedback is welcome.

[EpicWink]

Ahh, I didn't specify which commands I would like to see coloured output in the original request. diff I think would also benefit from colours

[reuvenharrison]

Hi @EpicWink,
Which format of the diff report are you using? json, text, html, or yaml?
The json and yaml formats provide a low-level diff report which is not ideal for human-readers.
The diff report in text or html formats is easier to read.
But the best report for humans is the changelog.

It would be useful to understand this and also the general use-case: how you use the diff output?

By the way, you are welcome to join our slack community where we can discuss this privately:
https://join.slack.com/t/oasdiff/shared_invite/zt-1wvo7wois-ttncNBmyjyRXqBzyg~P6oA

Thanks,
Reuven

[EpicWink]

I use the text-format diff, but I hadn't considered using changelog. I think that solves my use-case. I use it as an output in CI Laurie

…

________________________________ From: Reuven Harrison ***@***.***> Sent: Friday, December 1, 2023 7:19:59 PM To: Tufin/oasdiff ***@***.***> Cc: Laurie O ***@***.***>; Mention ***@***.***> Subject: Re: [Tufin/oasdiff] Coloured output (Issue #203) Hi @EpicWink<https://github.com/EpicWink>, Which format of the diff report are you using? json, text, html, or yaml? The json and yaml formats provide a low-level diff report which is not ideal for human-readers. The diff report in text or html formats is easier to read. But the best report for humans is the changelog. It would be useful to understand this and also the general use-case: how you use the diff output? By the way, you are welcome to join our slack community where we can discuss this privately: https://join.slack.com/t/oasdiff/shared_invite/zt-1wvo7wois-ttncNBmyjyRXqBzyg~P6oA Thanks, Reuven — Reply to this email directly, view it on GitHub<#203 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AF72GRNMAFLX5W6R4PJ5EKDYHGOL7AVCNFSM6AAAAAAWETX4T2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMZVG42DMOBWGI>. You are receiving this because you were mentioned.Message ID: ***@***.***>