feat(maven-plugin): add depclean:report goal for the Maven Site (#478)

[patbaumgartner]

Closes #478.

What

Adds a depclean:report goal built on the Maven Reporting API (maven-reporting-impl 4.0.0 / Doxia 2) that renders the DepClean analysis as target/site/depclean.html, listed in the site's Project Reports section.

The page contains:

• the settings the analysis ran with (ignoreTests, ignoreScopes, ignoreDependencies) and whether the result was reused or freshly computed;
• a Summary table (count + total size per category) linking to each section;
• one table per category — used / potentially unused × direct / transitive / inherited direct / inherited transitive, plus the dependencies ignored by configuration — with group id, artifact id, version, scope, size and used / total classes;
• a Used classes per dependency section listing the classes the project actually references from each used dependency.

How

• DepCleanReportMojo extends AbstractMavenReport, @Execute(phase = TEST_COMPILE), so a bare mvn site works without a prior build. It is read-only: never writes pom-debloated.xml, never applies failIfUnused*; skips cleanly for skipDepClean and pom packaging.
• Reuse instead of analysing twice: depclean:depclean now always writes a small gson snapshot to target/depclean-analysis.json. The report reuses it only when the settings match and the file is newer than pom.xml and every compiled class under target/classes / target/test-classes; otherwise it analyses itself and writes the snapshot. A file handoff was chosen over MavenProject context values because maven-site-plugin loads report plugins in their own ClassRealm, so in-memory ProjectDependencyAnalysis instances would not be type-compatible across goals.
• DepCleanReportRenderer extends AbstractMavenReportRenderer (Doxia sink, no HTML templates).
• ignoreDependencies / ignoreScopes / ignoreTests / skipDepClean are shared with the depclean goal under the same property names.

Compatibility

• Runtime floor stays Java 8: the reporting/Doxia jars pass the existing enforceBytecodeVersion rule, and runtime-smoke now also runs depclean:report on JDK 8/17/21/25 (verified locally with a real JDK 8 runtime).
• Requires maven-site-plugin >= 3.20.0 (Doxia 2). Maven 3.9 still defaults to 3.12.1, so users must pin a recent version — documented in the README. Maven 4 (default site plugin 4.0.0-M16) works out of the box; the site IT passes on both 3.9.16 and 4.0.0-rc-6.

Usage

<reporting>
  <plugins>
    <plugin>
      <groupId>se.kth.castor</groupId>
      <artifactId>depclean-maven-plugin</artifactId>
      <version>${depclean.version}</version>
      <reportSets>
        <reportSet>
          <reports>
            <report>report</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>

mvn site -> target/site/depclean.html; standalone mvn se.kth.castor:depclean-maven-plugin:<v>:report -> target/reports/depclean.html.

Tests

• Unit: AnalysisSnapshotFileTest (round trip; freshness: missing / newer pom / newer class / different settings / corrupt file), DepCleanReportRendererTest (renders through Xhtml5Sink, asserts structure, anchors, - for a null scope, empty analysis).
• IT (DepCleanReportMojoIT): report_via_site (mvn site, page listed in project-reports.html, no pom-debloated.xml), report_reuses_analysis (package depclean:report reuses the snapshot, banner printed once), report_recomputes_when_stale (standalone report analyses itself).
• ./mvnw -ntp clean verify --errors green; scripts/set-version.sh --check green (the script now also tracks the :report command line in the README).

---

Supersedes #540, which GitHub auto-closed when the fork was re-created (same commits, same branch).

[Copilot]

🟡 Changes recommended

The snapshot reuse fingerprint currently includes test output even when ignoreTests=true, unnecessarily invalidating reuse and undermining the PR’s “avoid analyzing twice” behavior for that configuration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a new Maven Site reporting goal (depclean:report) to the depclean-maven-plugin, generating an HTML report integrated into Maven Site’s “Project Reports” section and reusing prior DepClean analysis results via a snapshot file to avoid duplicate analysis runs.

Changes:

• Introduces depclean:report built on the Maven Reporting API / Doxia 2, rendering a DepClean report page via a Doxia sink renderer.
• Adds snapshot + input fingerprinting (target/depclean-analysis.json) so depclean:depclean and depclean:report can share analysis results safely.
• Adds unit + integration tests and updates docs/CI/scripts to cover the new goal and its usage.

File summaries

File	Description
scripts/set-version.sh	Updates README version syncing to handle both :depclean and :report CLI examples.
README.md	Documents the new Maven Site report goal, usage, and site plugin version requirement.
depclean-maven-plugin/src/main/java/se/kth/depclean/DepCleanReportMojo.java	Implements the report goal as a Maven report, including snapshot reuse + fallback analysis.
depclean-maven-plugin/src/main/java/se/kth/depclean/report/DepCleanReportRenderer.java	Renders the report content using Doxia sinks (tables, sections, anchors, details).
depclean-maven-plugin/src/main/java/se/kth/depclean/report/AnalysisSnapshot.java	Defines the serializable snapshot model handed off between goals.
depclean-maven-plugin/src/main/java/se/kth/depclean/report/AnalysisSnapshotFile.java	Reads/writes the JSON snapshot and validates reuse conditions.
depclean-maven-plugin/src/main/java/se/kth/depclean/report/AnalysisInputs.java	Computes an inputs fingerprint from POM + compiled class files to detect staleness.
depclean-maven-plugin/src/main/java/se/kth/depclean/DepCleanMojo.java	Persists a snapshot after depclean:depclean so depclean:report can reuse it.
depclean-maven-plugin/pom.xml	Adds Maven reporting/Doxia dependencies required for the report implementation/tests.
depclean-maven-plugin/src/test/java/se/kth/depclean/report/DepCleanReportRendererTest.java	Unit-tests renderer output structure/content via an XHTML sink.
depclean-maven-plugin/src/test/java/se/kth/depclean/report/AnalysisSnapshotFileTest.java	Unit-tests snapshot JSON roundtrip and reuse gating.
depclean-maven-plugin/src/test/java/se/kth/depclean/report/AnalysisInputsTest.java	Unit-tests fingerprint stability and change detection semantics.
depclean-maven-plugin/src/test/java/se/kth/depclean/DepCleanReportMojoIT.java	Integration-tests report generation via mvn site and snapshot reuse/recompute scenarios.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_via_site/pom.xml	IT fixture for site generation and “Project Reports” listing verification.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_via_site/src/main/java/Greeter.java	IT fixture source to ensure one dependency is used and another remains unused.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_reuses_analysis/pom.xml	IT fixture for package + depclean:report reuse behavior.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_reuses_analysis/src/main/java/Greeter.java	IT fixture source for reuse test case.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_recomputes_when_stale/pom.xml	IT fixture for standalone report recomputation when no prior snapshot exists.
depclean-maven-plugin/src/test/resources-its/se/kth/depclean/DepCleanReportMojoIT/report_recomputes_when_stale/src/main/java/Greeter.java	IT fixture source for stale/recompute test case.
.github/workflows/build.yml	Extends runtime smoke to also run :report and validate it reuses analysis + renders output.

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
15 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 91.58576% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.46%. Comparing base (ae128ce) to head (a04c828).

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #546      +/-   ##
============================================
+ Coverage     53.76%   57.46%   +3.70%     
  Complexity      337      337              
============================================
  Files            52       57       +5     
  Lines          2814     3120     +306     
  Branches        361      395      +34     
============================================
+ Hits           1513     1793     +280     
- Misses         1203     1218      +15     
- Partials         98      109      +11     

Flag	Coverage Δ
gradleplugin	37.84% <87.70%> (+9.59%)	⬆️
integration	78.86% <91.58%> (+2.04%)	⬆️
unittests	78.86% <91.58%> (+2.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
depclean-core	74.59% <ø> (ø)
depclean-maven-plugin	84.28% <91.58%> (+3.34%)	⬆️
depclean-gradle-plugin	6.70% <ø> (ø)

---

Continue to review full report in Codecov by Harness.

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

🚀 New features to boost your workflow:

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