Pass additional information for logger when formatting snippets

[mgroth0]

Description

I generate multiple kotlin files in a large gradle build with custom gradle tasks. The final step of the kotlin code generation uses ktlint to format the code before it is written to a file. As such, the code is passed to ktlint using Code.fromSnippet. This normally works, but occasionally I get log warning messages such as:

Format was not able to resolve all violations which (theoretically) can be autocorrected in file <stdin>

The issue is that I cannot determine which one of the generated files is causing this issue. This PR adds an optional parameter to allow passing more information to this log message.

Checklist

Before submitting the PR, please check following (checks which are not relevant may be ignored):

• Commit message are well written. In addition to a short title, the commit message also explain why a change is made.
• At least one commit message contains a reference Closes #<xxx> or Fixes #<xxx> (replace<xxx> with issue number)
• Tests are added
• KtLint format has been applied on source code itself and violations are fixed
• PR title is short and clear (it is used as description in the release changelog)
• PR description added (background information)

Documentation is updated. See difference between snapshot and release documentation

• Snapshot documentation in case documentation is to be released together with a code change
• Release documentation in case documentation is related to a released version of ktlint and has to be published as soon as the change is merged to master

[mgroth0]

This might be the wrong solution. Its possible there could be multiple generated files with the same name and that the issue of not being able to identify which file has the issue would persist.

Another idea I had originally was to allow passing an optional handler so that the behavior for Format was not able to resolve all violations can be customized. The default would still be to log it at the warning level as it does now, but the api consumer could optionally handle it a different way, even throwing an exception if it choses, by passing a lambda. I decided to try the current solution instead because it seemed like an easier change, but I'm unsure that its sufficient.

[paul-dingemans]

This solution is not acceptable to me for following reasons:

• The fromSnippet method signature is changed. Although the default parameter prevents backward compatibility issue for Kotlin projects, it will still break Java integrations like Spotless.
• Why can you not use fromSnippetWithPath instead?

Note that any of your solution will still be limited by the built-in behavior regarding rerunning ktlint multiple times on the same file. The maximum is limited to three attempts (hard coded). This is a limit that works most of the time. But, for code bases on which ktlint never has run, this might not be enough. The maximum number of runs is limited, as it otherwise can happen that formatting ends in an endless loop when rules are reverting each other changes. I would not be against a Handler that is implemented by the KtLintRuleEngine that gives the API Consumer control about the retry runs. But, the API Consumer should be warned about endless loop behavior when overriding the default behavior.

[mgroth0]

I understand the problem. Certain public APIs need to not change their signature or else it could break java interop.

Why can you not use fromSnippetWithPath instead?

I considered this. Given that I am formatting code snippets before they are written to a file, this felt messy as I would be providing a non-existing or fake file path. This would trigger filesystem IO as it searches for .editorconfig files if I understand correctly. Given this is all running in the gradle configuration phase where filesystem IO is recorded and used for configuration inputs, it felt even more messy. It is maybe a viable workaround but not ideal.

I would not be against a Handler that is implemented by the KtLintRuleEngine that gives the API Consumer control about the retry runs

I can look into this. To be clear, my current priority is just to provide some information so that the warning message identifies which code snippet has the problem, not to change the number of retry runs.