🌟 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-line: 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-line=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