GH-944: Support root path exclusion for QDox scanning to avoid existing blocking issues

[ascopes]

This enables users to work around issues such as paul-hammant/qdox#219, paul-hammant/qdox#1, paul-hammant/qdox#292, etc that result in issues such as #944 being raised.

This is a strategic change operating on the appreciation that the author of QDox and Apache Maven maintainers are very busy and may be unable to produce an immediate fix for the aforementioned issues, with the knowledge that these issues can still pose a solid blocker for development by consumers of these libraries for significant periods of time.

With this change, users can specify a set of excluded scan directories that source trees reside within to prevent maven-plugin-plugin from feeding them into the Java source analysis tooling, which allows unblocking builds that are completely blocked until such a time that issues such as paul-hammant/qdox#287 are addressed. Given the long release span between releases of dependent libraries, developers will otherwise be blocked for long periods of time with unbuildable projects using the current tooling.

Following this checklist to help us incorporate your
contribution quickly and easily:

• Your pull request should address just one issue, without pulling in other changes.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body.
  Note that commits might be squashed by a maintainer on merge.
• Run mvn verify to make sure basic checks pass.
  A more thorough check will be performed on your pull request automatically.
• You have run the integration tests successfully (mvn -Prun-its verify).

CLA has been signed for previous changes.

To make clear that you license your contribution under
the Apache License Version 2.0, January 2004
you have to acknowledge this by using the following check-box.

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

Fixes GH-944.

[ascopes]

Squashed fixes for tests, documentation, and spotless into the original commit. Please can the workflow be run again. Thanks!

[Copilot]

Pull request overview

This PR adds the ability to exclude specific source root directories from being scanned during Maven plugin descriptor generation. This allows users to work around parsing issues in QDox (such as unsupported syntax in generated sources) that can block builds.

Key Changes:

• Added excludedScanDirectories parameter to the PluginToolsRequest interface and implementation
• Modified both Java extractors (Javadoc and Annotations) to skip excluded directories during source scanning
• Added integration test demonstrating the exclusion of annotation processor-generated sources

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/PluginToolsRequest.java	Added interface methods for getting/setting excluded scan directories
maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/DefaultPluginToolsRequest.java	Implemented excluded scan directories with lazy initialization to empty HashSet
maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java	Added exclusion check when processing compile source roots and isExcludedDirectory helper method
maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java	Added exclusion check when processing compile source roots and isExcludedDirectory helper method
maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/DescriptorGeneratorMojo.java	Added excludedScanDirectories Mojo parameter with comprehensive documentation
maven-plugin-plugin/src/it/gh-944-exclude-source-directory/pom.xml	Integration test POM demonstrating exclusion of generated-sources/annotations
maven-plugin-plugin/src/it/gh-944-exclude-source-directory/src/main/java/org/apache/maven/plugin/coreit/SomeGeneratedModel.java	Test model that triggers QDox parsing issue when generated
maven-plugin-plugin/src/it/gh-944-exclude-source-directory/src/main/java/org/apache/maven/plugin/coreit/FirstMojo.java	Test Mojo that uses the generated model
maven-plugin-plugin/src/it/gh-944-exclude-source-directory/invoker.properties	Invoker configuration for integration test

Comments suppressed due to low confidence (1)

maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java:564

• The generatedPlugin directory at line 561-563 is not checked against the excluded directories, while the compile source roots are. This creates an inconsistency where users cannot exclude the generated-sources/plugin directory even if it causes parsing issues. Consider applying the same exclusion logic to this path for consistency.

        // TODO be more dynamic
        File generatedPlugin = new File(project.getBasedir(), "target/generated-sources/plugin");
        if (!project.getCompileSourceRoots().contains(generatedPlugin.getAbsolutePath())) {
            builder.addSourceTree(generatedPlugin);
        }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ascopes]

Ready for review. Thanks!