🌟 Let's talk about output formats options

[ldez]

Important

This is a proposal: I don't know if it is possible and what the impact could be inside the code.
The proposal may evolve.

---

The current configuration

# colored-line-number
# line-number
# json
# colored-tab
# tab
# html
# checkstyle
# code-climate
# junit-xml
# junit-xml-extended
# github-actions
# teamcity
# sarif

output:
  print-issued-lines: false
  print-linter-name: false
  formats:
    - format: json
      path: stderr
    - format: checkstyle
      path: report.xml
    - format: colored-line-number

--out-format=checkstyle:report.xml,json:stdout,line-number-colored
--print-issued-lines=false
--print-linter-name=false

---

⛑️ The Problems

Global Options but Only For Some Formats

output:
  print-issued-lines: false
  print-linter-name: false
  formats:
    - format: json
      path: stderr
    - format: checkstyle
      path: report.xml
    - format: colored-line-number

• The option output.print-issued-lines is for line-number, colored-line-number formats.
• The option output.print-linter-name is for line-number, colored-line-number, tab, colored-tab formats.

Format Names

The names of the colored variants have an unexpected style:

• line-number, colored-line-number
• tab, colored-tab

I think tab, tab-colored are more natural.

Slice of Formats

output:
  formats:
    - format: json
      path: stderr
    - format: checkstyle
      path: report.xml
    - format: colored-line-number

Currently, the formats are represented into a slice, this type has been introduced mainly for compatibility reasons with the initial format option (a simple string)

A side effect of a slice is the possibility of defining the same format several times but with different output paths.
But I think this is not a real use case.

Another side effect is the flag parsing complexity because the flag --out-format value is a simple string.

Non-User friendly CLI flag

The current syntax can be used only if you know the syntax and there is no suggestion/completion.

--out-format=checkstyle:report.xml,json:stdout,line-number-colored

💭 Proposal

Configuration

output:
  formats:
    text: # (line-number)
      path: stdout
      print-linter-name: true
      print-issued-lines: true
      colors: true
    json:
      path: ./path/to/output.json
    tab:
      path: stdout
      print-linter-name: true
      colors: true
    html:
      path: ./path/to/output.html
    checkstyle:
      path: ./path/to/output.xml
    code-climate:
      path: ./path/to/output.json
    junit-xml:
      path: ./path/to/output.xml
      extended: true
    teamcity:
      path: ./path/to/output.txt
    sarif:
      path: ./path/to/output.json

CLI flags

--output.text.path=stdout
--output.text.print-linter-name=false
--output.text.print-issued-lines=false
--output.text.colors=false
--output.json.path=./path/to/output.json
--output.tab.path=stdout
--output.tab.print-linter-name=false
--output.tab.colors=false
--output.html.path=./path/to/output.html
--output.checkstyle.path=./path/to/output.xml
--output.code-climate.path=./path/to/output.json
--output.junit-xml.path=./path/to/output.xml
--output.junit-xml.extended=true
--output.teamcity.path=./path/to/output.txt
--output.sarif.path=./path/to/output.json

example

Before:

--out-format=checkstyle:report.xml,json:stdout,line-number-colored

After:

--output.checkstyle.path=report.xml
--output.json.path=stdout
--output.text.path=stdout

[ldez]

I created a working implementation.

As the main key output.formats is the same as the existing one, and the current implementation uses a hack to handle multiple types (string, slice), I didn't find a way to create a compatibility layer.

I wonder if the flag prefix --output. is right or not, I mean --output.text.path vs --text.path.

[ldez]

Maybe the new main key can be output.styles 🤔

With the new fmt command it can be better to avoid the word format about elements related to linters 🤔

[bombsimon]

I wonder if the flag prefix --output. is right or not, I mean --output.text.path vs --text.path.

Maybe the new main key can be output.styles 🤔

With the new fmt command it can be better to avoid the word format about elements related to linters 🤔

I think the proposal looks good and would be an improvement from the current --out-format. By supporting multiple output formats at the same time it can become complex and messy with the flags rather than just having the user pipe to a file and us printing to stdout. And as long as we want to support all configs from a config file as CLI flags it will look something like your suggestion.

I think it's fine to (re)use format if you want to, don't see it as risk of ambiguity with the fmt "format". I'd prefer it over styles at least.

But I also pondering if it would be possible to keep using out-format but improve the usage? Right now we don't have anything other than format at the second level in the config and it's completely omitted in the CLI flags so it's not a 1:1 map.

Thinking

---
out-format:
  json:
    path: /tmp/out.json
  tab:
    colors: true

--out-format.json.path=/tmp.out.json
--out-format.tab.colors=true

In your example in the original post it seems like line-number-colored got dropped, where would that go? Something like --output.line-number-colored?

[ldez]

line-number/line-number-colored -> text

line-number-colored (the default):

--output.text.path=stdout
--output.text.colors=true

line-number:

--output.text.path=stdout
--output.text.colors=false

[ldez]

But I also pondering if it would be possible to keep using out-format but improve the usage?

I'm not a fan of out-format: this is weird to use out instead of output.

I'd prefer it over styles at least.

Ok so I cannot create a compatibility layer, the PR will be open after the next minor release.

[ldez]

Note: I trimmed the configuration to only focus on formats but there are more fields.

output:
  path-prefix: ""
  sort-results: true
  sort-order:
    - linter
    - severity
    - file
  show-stats: true
  # ...

[bombsimon]

I'm not a fan of out-format: this is weird to use out instead of output.

Yeah, I agree. Not sure why I wrote like formats was the only section, given the current config structure output seems like the best name and format or formats as the second level.

[ldez]

FYI output.format is already used, it was the previous name of output.formats, and this is still used for compatibility.

This is why I said I cannot create a compatibility layer without a new name.