Clean the Compiler output directories only when the task executes (#21)

[alexander-yevsyukov]

What & why

Resolves #21 — LaunchSpineCompiler should clean the output dir only when needed.

LaunchSpineCompiler registered an unconditional doFirst action that wiped its target directories on every invocation. Together with the historic lack of declared inputs/outputs, this forced users to run ./gradlew clean build. The task is now @CacheableTask with declared inputs and outputs, so the eager wipe is unnecessary and actively hostile to incremental builds.

Changes

LaunchSpineCompiler — cleanup simplified

• Cleanup moved into an exec() override, so it runs only when the task actually executes. Up-to-date and cache-restored runs leave the generated code intact — incremental builds no longer need clean.
• Deletes only this task's own output directories, preserving any directory that coincides with a source directory (the deprecated in-place protoc overwrite mode). This removes the old sources/targets zip + Files.isSameFile "gymnastics" noted in the issue.
• Drops the early return on empty sources, so descriptor-only mode (protoc built-ins off) no longer leaves stale files behind.
• Deletes via an injected FileSystemOperations instead of Task.project at execution time (configuration-cache friendly).

Functional tests — four new PluginSpec cases for the no-clean flows:

• a proto message rename drops the stale generated file and recompiles;
• a deleted generated/ directory is restored while generateProto stays UP_TO_DATE;
• an unrelated regular-source change keeps the launch task UP_TO_DATE;
• settings rewritten with identical content on every build keep the launch task UP_TO_DATE.

Dokka aggregation fix — build.gradle.kts

• test-env calls disableDocumentationTasks(), so it never produces the module-descriptor.json the multi-module Dokka publication consolidates. It was still in the root dokka(...) aggregation, so :dokkaGeneratePublicationHtml failed on the missing descriptor whenever dokkaGenerate ran. Now excluded, so repo-wide dokkaGenerate passes. This was a pre-existing failure (unrelated to LaunchSpineCompiler should clean the output dir only when needed #21) surfaced while running the pre-PR checks.

Verification

• ./gradlew build (CI parity): BUILD SUCCESSFUL, no failed tasks.
• :gradle-plugin:check: 15 functional tests, 0 failures (1 pre-existing @Disabled skip); detekt clean.
• ./gradlew dokkaGenerate (both changes present): BUILD SUCCESSFUL — root aggregation now green.
• Reviewers: spine-code-review, kotlin-engineer, review-docs — all APPROVE; actionable findings applied.

Notes for the reviewer

• Behavior change worth a look: with empty/absent sources, the task now cleans its declared output dirs instead of skipping cleanup. Targets are this task's own @OutputDirectories, so deleting them before regeneration is the intended contract (documented in the class KDoc).
• The two commits are independent concerns and can be reviewed separately.

[Copilot]

Pull request overview

This PR improves incremental build behavior for the Spine Compiler Gradle integration by ensuring LaunchSpineCompiler cleans its outputs only when the task actually executes (not on up-to-date / cache-restored runs), and adds functional test coverage for the no-clean workflows. It also includes a small fix for root Dokka aggregation and updates versions/reports.

Changes:

• Update LaunchSpineCompiler to delete its target output directories inside exec() using injected FileSystemOperations, preserving any target directory that matches a source directory.
• Add functional tests covering incremental proto changes, deleted generated/ restoration, unrelated source changes, and stable settings rewrites.
• Fix Dokka aggregation by excluding test-env, and bump/update versions and generated dependency reports.

Reviewed changes

Copilot reviewed 19 out of 22 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
version.gradle.kts	Bump compiler version to 2.0.0-SNAPSHOT.052.
protoc-plugin/src/main/kotlin/io/spine/tools/compiler/protoc/Plugin.kt	Switch CodeGeneratorRequestWriter import to the io.spine.tools.code.proto package.
protoc-plugin/build.gradle.kts	Add tool-base dependency to supply CodeGeneratorRequestWriter.
gradle.properties	Enable Gradle build caching. (Config-managed in many Spine repos; not reviewed in depth here.)
gradle-plugin/src/main/kotlin/io/spine/tools/compiler/gradle/plugin/LaunchSpineCompiler.kt	Move cleanup to exec() and use injected FileSystemOperations so cleanup runs only on actual task execution.
gradle-plugin/src/functionalTest/kotlin/io/spine/tools/compiler/gradle/plugin/PluginSpec.kt	Add functional tests for incremental/no-clean scenarios and refactor test setup helper.
docs/dependencies/pom.xml	Update published-docs dependency versions to match the new snapshot set.
docs/dependencies/dependencies.md	Refresh generated dependency/license report content for the new version set.
buildSrc/src/test/kotlin/io/spine/gradle/publish/IncrementGuardTest.kt	Add tests for increment-guard branch/event logic. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/gradle/report/coverage/SiblingCoverage.kt	Add helper for cross-module Kover crediting. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/gradle/report/coverage/KoverConfig.kt	Rename/refactor helper method for class name discovery. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/gradle/publish/IncrementGuard.kt	Change guard logic to PR-base-branch based decision. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/dependency/local/ToolBase.kt	Bump tool-base version constants. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt	Bump core-jvm-plugins version constants. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt	Bump compiler fallback versions. (Config-managed; skipped.)
buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt	Bump spine-base version constants. (Config-managed; skipped.)
build.gradle.kts	Exclude test-env from Dokka aggregation to prevent missing module-descriptor.json failures.
.github/workflows/increment-guard.yml	Update version-guard workflow trigger/conditions. (Config-managed; skipped.)
.github/workflows/ensure-reports-updated.yml	Update license-reports workflow trigger/conditions. (Config-managed; skipped.)
.github/workflows/build-on-windows.yml	Simplify Windows workflow steps/Gradle invocation. (Config-managed; skipped.)
.agents/tasks/clean-output-only-when-needed.md	Task log/plan file. (Config-managed; skipped.)

[codecov]

Codecov Report

❌ Patch coverage is 78.00000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.34%. Comparing base (f15c9ca) to head (d9b6fe4).
⚠️ Report is 6 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #70      +/-   ##
============================================
+ Coverage     75.09%   75.34%   +0.25%     
- Complexity      668      672       +4     
============================================
  Files           202      202              
  Lines          3915     3947      +32     
  Branches        395      393       -2     
============================================
+ Hits           2940     2974      +34     
+ Misses          857      855       -2     
  Partials        118      118              

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.