Add dependency resources reference that includes resolved artifact files (#373)

[elharo]

Fixes #373

Summary

The aggregate maven.project.dependencies reference was a FileSet rooted at the local repository, using localRepository.pathOf(artifact) for its include patterns. Artifacts that are not physically in the local repository (notably reactor inter-module dependencies, resolved to a sibling module's output) silently matched nothing, so the aggregate was incomplete in reactor builds.

Approach

This PR keeps the legacy behavior intact and adds a new reference:

• maven.project.dependencies remains the legacy FileSet rooted at the local repository. Existing builds keep working unchanged.
• A new maven.project.dependencies.resources reference is added: a resource collection (Union) of per-artifact FileSets, each rooted at the actual resolved artifact file (artifact.getFile()). This includes artifacts from any location, including reactor inter-module dependencies.

Changes

• DependencyFilesetsTask.java: keep the local-repository-based FileSet (including the empty-artifacts special case) and add the Union of per-artifact FileSets from artifact.getFile(), registered under maven.project.dependencies.resources.
• antrun.mdo: new projectDependenciesResourcesId configuration attribute (default maven.project.dependencies.resources).
• Unit tests DependencyFilesetsTaskAggregateTest: the legacy fileset reference remains rooted at the local repository, and the resources reference includes artifacts outside the local repository.
• New IT dependency-filesets-resources-test and updated dependencyFilesets.apt.vm docs to cover the new resources reference. The existing filesets-test IT is unchanged.

Verification

• The new test fails on master (no maven.project.dependencies.resources reference) and passes with the fix; the legacy-reference test passes both before and after.
• mvn verify (rat, checkstyle, spotless, unit tests, javadoc) passes.
• mvn verify -Prun-its passes: all 30 integration tests succeed, including the new dependency-filesets-resources-test; the unchanged filesets-test IT still passes.

[elharo]

This change breaks existing projects that rely on the aggregate dependencies reference.

• The DependencyFilesetsTask previously exported the aggregate project dependencies (using the default ID maven.project.dependencies or a custom prefix) as an Ant FileSet.

• The provided patch changes the underlying Java object of this reference from org.apache.tools.ant.types.FileSet to org.apache.tools.ant.types.resources.Union, which is a ResourceCollection.

• Existing Ant build XML configurations that reference this collection using the <fileset refid="maven.project.dependencies"/> syntax will fail because the referenced object is no longer a valid FileSet.

• To resolve this break, users must update their Ant scripts to use the <resources refid="maven.project.dependencies"/> element instead of <fileset>.

• This required syntax modification is explicitly demonstrated in the patch's updates to both the integration test (src/it/filesets-test/pom.xml) and the documentation (src/site/apt/tasks/dependencyFilesets.apt.vm).

The architectural purpose of this change is to alter how the dependency paths are resolved. By assembling the Union resource collection from the actual resolved artifact files, the plugin can now successfully include artifacts located outside the local Maven repository, such as reactor inter-module dependencies.

[elharo]

It is not possible to achieve this specific fix while maintaining a single Ant FileSet reference.

An Ant FileSet is strictly constrained to a single base directory (defined by the dir attribute). Because reactor dependencies (located in the project's target directories) and resolved dependencies (located in the local Maven repository) exist in disparate directory trees, a single FileSet cannot encapsulate both.

However, backward compatibility for users relying on the <fileset> syntax can be maintained by altering the plugin's approach rather than modifying the data type of the existing reference. There are two primary technical solutions:

1. Dual References (Deprecation Approach)

The plugin can maintain the existing maven.project.dependencies reference as a FileSet restricted only to the local repository, preserving legacy behavior (and its existing bug regarding reactor dependencies).

A new reference (e.g., maven.project.dependencies.resources) can be introduced as a Union (ResourceCollection) that correctly resolves all artifacts regardless of their location. Users who require reactor module support can migrate to the new reference using <resources>, while existing builds remain unbroken.

2. Staging Directory (File I/O Approach)

The plugin can resolve all dependencies (both reactor and local repository), and copy or hardlink them into a temporary staging directory within the build's target directory.

The plugin can then return a standard FileSet with its dir attribute pointing to this staging directory. This maintains full backward compatibility with the <fileset> tag and includes all artifacts, but introduces disk I/O overhead and increases build time.

[elharo]

Only the first approach preserves existing behavior for existing pom.xml files. Let's do that.