Baseline mechanism that counts violations per file rather than rely on line number

[steve-the-edwards]

Expected Behavior

When using baseline files, it would be great to be able to record the count of violations per file rather than the line number of each violation in the baseline. Or to record both the original line number and the counts and use the counts in the mechanism to check against baseline.

Current Behavior

Currently the baseline files specify the violations with a line number. This means that if an unrelated change is made to the file, all the baselines must be re-generated, and that creates a lot of unwanted friction.

Additional information

• Current version of ktlint: 1.6.0

[steve-the-edwards]

@paul-dingemans I would be happy to help PR this change but I have not looked at the code for the baselines much. Do you have a sense of how much work this would be?

For more context we are attempting to begin to adopt some much more strict rules, e.g., with Compose lints - which will have a number of violations. These are more helpfully baselined (rather than @Suppress) in order to turn the rule on going forward and then work back on the tech debt. Having too many @Suppress throughout files is way too noisy. We do not want to use file level @Suppress if possible, because then new violations are not detected.

However, with the baselines as they are currently reported, if someone makes an unrelated change to files then they need to regenerate baselines for something that had nothing to do with their current work. This is an unacceptable friction for us. Using a baseline with violation count per file would eliminate this extra friction when making unrelated change while still allowing us to lint new instances and baseline extensive old tech debt without creating too much noise in the file.

[ConstantinCezarBegu]

@paul-dingemans I would love to offer for something like this!

In ktlint-cli-reporter-baseline/src/main/kotlin/com/pinterest/ktlint/cli/reporter/baseline/Baseline.kt we can just add a function that takes the cli errors and creates a count output.

The code is pretty simple and I honestly don't think it's that much work to add a count implementation since the summery count is already done for the cli:
Summary error count (descending) by rule:
standard:comment-wrapping: 14
standard:op-spacing: 2

We would mostly have to modify public fun List.containsLintError( to basically do a count check instead (that could allow us to also keep the same baselines) which I think is a good idea so that we know for what line it was originally created (in case they turn stale).

This behaviour would need to be changed based on a flag of course.

We could make it so that the baseline returns numbers similar to cli summary but that might require more refactoring and not sure if we actually want a baseline like that.

Open to any ideas.

[paul-dingemans]

I doubt this will work. But I am happy that you are willing to contribute ;-)

The baseline functionality is somewhat helpful, but in combination with auto-formatting it has limitations as you already experienced.

The structure of the baseline results in a breaking change of Ktlint, and that is not something that I consider in short term. Some API consumers of ktlint process the baseline file as well. I think it is used by detekt, but maybe also by other integrators.

As alternative you can consider to migrate your code base per package. You can disable the entire rule in the root directory of your project, and enable it for one or more (sub)packages. Or the other way around (enable in root, and disable for some packages).

[steve-the-edwards]

The per package enabling is a good idea!

Another alternative that we are considering: could we have a gradle task within ktlint that would be equivalent to generating a baseline but instead it would inline all the expression level @Suppressions for a particular snapshot of the code?

This was we see all the @Suppress that are active, and they are stable across unrelated code changes.

[paul-dingemans]

The per package enabling is a good idea!

See https://pinterest.github.io/ktlint/latest/faq/#how-do-i-disable-ktlint-for-generated-code for how to disable/enable per package.

Another alternative that we are considering: could we have a gradle task within ktlint that would be equivalent to generating a baseline but instead it would inline all the expression level @SUPPRESSiONs for a particular snapshot of the code?

Ktlint does not provide any gradle task. You might be confused with one of the gradle plugins that integrate with ktlint. But those plugin would not be able to provide such a task without it being supported by ktlint. Automatically adding @Suppress annotations instead of generating a baseline is technically possible, but there are challenges to overcome (see #2588 for an example). But it would violate the idea for which the baseline was introduced. Introducing Ktlint on a project would in that case leading to modify a lot of source files to add the @Suppress, for no other reasons than linting/formatting. In some projects this is not acceptible. With the baseline file this was prevented, as only one file was added containing all lint violations. So if this functionality would be added, it would only make sense to do this for violations which can not be autocorrected. Adding a @Suppress violation in a file, for a violation which can be autocorrected would be strange.

When starting with KtLint is always to take the one-time pain to fix all violations. I would suggest following approach:

1. Run ktlint format multiple times until all violations that can be autocorrected are fixed.
2. Disable all rules that emit violations that can not be autocorrect.
3. Enable the rules from the previous step on a one by one basis, and resolve the errors. When handling errors on only one rule at a time, you quickly get the gist of it, and you will be able to process them at a higher speed.