Allow users and rule authors to specify a reason per configured value

[marschwar]

What does this PR address?
A few times there was the request to be able to specify a custom error message or a reason for certain setting. See #3501 for example. This will allow rule authors to enable this features for all rules that have configurable list of string values such as

  ForbiddenImport:
    active: true
    imports:
      - value: 'org.junit.Test'
        reason: 'Do not use JUnit4. Replace with org.junit.jupiter.api.Test.'

This is only providing the option to do so and does not change any rules.

Thanks to @BraisGabin for collaborating on this.

[BraisGabin]

* I do not really like the nameof the `ExplainedValues` type and `explainedValues` config delegate. Any idea what we could call the combination of a configured value and the reasoning why the value is configured?

ValueWithReason? I don't think it's better... it's the only other option that I find.

* Do you agree on the representation in the `config.yml` (see `detekt-core/src/test/resources/explained-values.yml`)?

I like it.

* Should the reason be shown in the documentation? If so, any ideas on how to do that? (This would be a separate PR)

I don't think so. I don't think that it could provide any value for the reader.

[marschwar]

I think I also prefer ValueWithReason but before changing everything multiple times I would like to wait on some more opinions.

[cortinico]

I haven't looked into the code, but if I understand correctly it relies on a separate explained-values.yml file right?

I would rather move this file inside the config on a top level explanation: key or even move it closer to the rule config as a metadata addition

[marschwar]

if I understand correctly it relies on a separate explained-values.yml file right?

No, that is not correct the explained-values.yml is only used in the tests to verify that the config parser can read those formats correctly. The idea is, that rule authors may decide that their rule supports values with reasons instead of values only. So instead of

  ForbiddenImport:
    active: true
    imports:
      - 'org.assertj.core.api.Assertions'

it could become

  ForbiddenImport:
    active: true
    imports:
      - value: 'org.assertj.core.api.Assertions'
        reason: 'import Assertions.assertThat directly'

[codecov]

Codecov Report

Merging #4611 (b27a563) into main (a8cde4f) will decrease coverage by 0.07%.
The diff coverage is 77.06%.

@@             Coverage Diff              @@
##               main    #4611      +/-   ##
============================================
- Coverage     84.80%   84.73%   -0.08%     
  Complexity     3453     3453              
============================================
  Files           492      493       +1     
  Lines         11328    11397      +69     
  Branches       2086     2103      +17     
============================================
+ Hits           9607     9657      +50     
- Misses          673      682       +9     
- Partials       1048     1058      +10     

Impacted Files	Coverage Δ
...bosch/detekt/generator/collection/Configuration.kt	100.00% <ø> (ø)
...ekt/generator/collection/ConfigurationCollector.kt	62.38% <41.93%> (-7.62%)	⬇️
...rbosch/detekt/generator/collection/DefaultValue.kt	88.23% <83.33%> (-2.68%)	⬇️
.../io/gitlab/arturbosch/detekt/api/ConfigProperty.kt	96.77% <91.66%> (-3.23%)	⬇️
.../io/gitlab/arturbosch/detekt/generator/out/Yaml.kt	79.36% <95.65%> (+6.63%)	⬆️
...o/gitlab/arturbosch/detekt/api/ValuesWithReason.kt	100.00% <100.00%> (ø)
...tekt/generator/printer/RuleConfigurationPrinter.kt	100.00% <100.00%> (ø)
...ator/printer/defaultconfig/RuleSetConfigPrinter.kt	88.00% <100.00%> (-0.89%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a8cde4f...b27a563. Read the comment docs.

[cortinico]

The idea is, that rule authors may decide that their rule supports values with reasons instead of values only. So instead of

Gotcha 👍 Looks great then.

[marschwar]

Could we add this feature with 1.21?

[BraisGabin]

Sorry for the late review! I missed the notification about this.

[BraisGabin]

@marschwar I think that we can merge this. Could you fix the conflicts?

[marschwar]

I have yet to figure out how to format the RuleCollectorSpec

[marschwar]

Ready to be merged from my point of view unless you would like me to add more tests?

[schalkms]

Good to go
Thank you!