Create an interface for Kover tasks

[mgroth0]

I am new to this plugin and I wanted to make certain tasks depend on Kover tasks. However, KoverHtmlTask and such are internal. This would be fine as long a superclass or interface were made public. But even AbstractKoverReportTask is internal. There is no straightforward way to do task.dependsOn(tasks.withType<KoverHtmlTask>()).

There are a couple of simple solutions. One is that you can make these tasks public and make the constructor internal. Another is that you can create a public interface that they extend from.

[shanshin]

Hi,
it is not worth using task types for dependencies, because for example, in Android, several tasks with the same type can be created (in the future this may be added to regular JVM projects).

You may add a dependency to a Kover task by its name, for example
tasks.myTask { dependsOn(tasks.named("koverHtmlReport")) }

Names koverXmlReport, koverHtmlReport, koverVerify are stable for Kotlin/JVM or Kotlin/MPP, сonstants for the names of these tasks will be introduced in 0.7.0.

[mgroth0]

Hey @shanshin. Thanks for the info. I disagree with your opinion on this.

Making task types public API is the norm. I've never encountered a gradle plugin before this that doesn't have public task classes, regardless how many tasks are created per project.

Depending on tasks using withType is more typesafe and preferred.

Configuring tasks using tasks.withType<X>.configureEach is also idiomatic.

It seems to me making task types public API has great benefit, no cost, and aligns better with idiomatic gradle usage.

[shanshin]

The described problem is solved by searching for a task by name (tasks.named("someName")), while it is also safe because if there is no task with that name, an error will be thrown.

The use of tasks.withType<X>.configureEach in the case of Kover tasks in most cases is not assumed, because all the configuration of the plug-in takes place in a single place - extensions of the project.

For rare cases, a search by name can be used, which is generally preferable, because in Android projects most often work will be carried out with a specific build variant and the corresponding task.

I've never encountered a gradle plugin before this that doesn't have public task classes, regardless how many tasks are created per project.

In fact, there are quite a lot of such tasks, for example, the most frequently used such task is check from the base plugin.

[shanshin]

In the future, some public classes may be added, however, it is necessary to understand what problem they will solve.

At the moment, the only known problem is defining dependencies between tasks, but it is easily solved with the names. For kts build scripts, we will add type-safe accessors for default reports so that users can write tasks.koverHtmlReport.

[mgroth0]

tasks.named("someName") is less safe because it only throws an error at runtime, not compilation time. Compilation-time type safety is cleaner and more robust. Type safety is also reinenforced by IDE syntax highlighting, but finding by names is not.

If I want to reference "koverHtmlReport" in multiple places, I will likely want to define const val KOVER_HTML_REPORT_TASK_NAME = "koverHtmlReport" somewhere. But that's just extra clutter in my code where tasks.withType<KoverHTMLReport> would be more elegant and simple.

Checking if a task is a kover task based soley on the name will not work in when statements:

when (task) {
	is KotlinCompile, is Jar -> {
         ...
    }
    is JavaExec -> {
         ...
    }
    .name == KOVER_HTML_REPORT_TASK_NAME -> { // compilation error
         ...
    }
}

(at least for now, until one day KT-21661 is hopefully implemented )

Finding objects by type rather than name is also useful because if the hierarchical structure. If all kover tasks can implement an empty interface interface KoverTask: Task, then its easy to gather all kover tasks with tasks.withType<KoverTask>. KoverHtmlTask and KoverXmlTask can both implement a KoverReport interface (that is not implemented by KoverVerifyTask) if a user only wants to gather the tasks that's main purpose is to generate a report.

The kotlin-gradle-dsl is not available in all places. For example, it is not included by default in the gradle API when writing gradle plugins (and it can be challenging to include the kotlin-gradle-dsl as a dependency for gradle plugins.) So type-safe accessors won't solve this issue as broadly as public classes would.

Allowing users to use tasks.withType does not prevent the from using tasks.named. tasks.named, kotlin-gradle-dsl accessors, or other techniques can still be used to find tasks for a particular android build varient or similar.

check is a lifecycle task. AFAIK it does not do anything, it only depends on other tasks. I'd be curious if there are any tasks that actually do actions that don't have some public type it can be referenced, or at least narrowed down by.

I don't think new classes or code needs to be written (though creating a simple hierarchy with interfaces would be excellent). What issues would be introduced by simply removing the internal keyword for the existing task classes? The internal keyword could be added to the constructor and/or to any properties to protect the integrity of the classes if needed. As far as I can see, this change would have no effect on the rest of the plugin

Given how small of a change this is that there are identifiable benefits, I'm curious why there is such a need for justification. What costs are there to simply removing the internal keyword?

[qwwdfsad]

Given how small of a change this is that there are identifiable benefits, I'm curious why there is such a need for justification. What costs are there to simply removing the internal keyword?

It immediately becomes a part of public API which imposes quite a lot of restrictions:

• API members should be properly documented
• The API itself should be named properly, be consistent, and hack-free. E.g. now we can get away with val someTrickFlagAsWorkaround, but with public API we can't
• It's part of API, thus extra care is required regarding API evolution.

Note that all these problems are solvable and are not arguments against your proposal, but rather an answer to "why it's not public by default" question.

To the original report -- thanks for the effort and for going the extra mile in explaining to us why this is a problem for Kover's users!
We'll discuss it internally and see what we can do to both solve your issue and keep our public API minimal

[shanshin]

tasks.named("someName") is less safe because it only throws an error at runtime, not compilation time.

This problem is solved by using constants with the task names: e.g. kotlinx.kover.api.KoverNames.HTML_REPORT_TASK_NAME for 0.6.1

What issues would be introduced by simply removing the internal keyword for the existing task classes?

Unfortunately in this case AbstractKoverReportTask becomes public, however these are implementation details. This class does not fit the hierarchy of reports described above (verify is also inherited from it), however, by making it public, we will need to maintain exactly such a hierarchy in the future for compatibility, which makes refactoring difficult.

Finding objects by type rather than name is also useful because if the hierarchical structure.

At this point, there may be discrepancies in the understanding of the correct hierarchy. After the implementation of #229, new tasks for printing "reports to logs" will appear, and verification will start working in a similar way after #339.

Allowing users to use tasks.withType does not prevent the from using tasks.named. tasks.named, kotlin-gradle-dsl accessors, or other techniques can still be used to find tasks for a particular android build varient or similar.

in this case, Android users can find an example of a solution with withType on the Internet and use configureEach to configure several tasks at once without realizing it.

If the concepts of default reports (always existing tasks with names koverHtmlReport, koverXmlReport etc) remain in the stable version , then it will be possible to add the interfaces like KoverDefaultHtmlReport. However, this requires additional design in the future.