This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch proposal-280-raw-used-types in repository https://gitbox.apache.org/repos/asf/maven-dependency-analyzer.git
commit 8dee262ac717daf718f871d539a30d23764b9cd1 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Tue Nov 10 18:00:49 2026 +0100 Add proposal for duplicate-class visibility (#280) Propose exposing raw used classes and candidate artifacts alongside current single-artifact mapping, preserving existing analysis behavior. --- docs/PROPOSAL-280-duplicate-class-visibility.md | 78 +++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/PROPOSAL-280-duplicate-class-visibility.md b/docs/PROPOSAL-280-duplicate-class-visibility.md new file mode 100644 index 0000000..6c17c75 --- /dev/null +++ b/docs/PROPOSAL-280-duplicate-class-visibility.md @@ -0,0 +1,78 @@ +# Proposal: expose raw used classes and candidate artifacts for duplicate-class cases (#280) + +## Problem +When multiple resolved artifacts provide the same class, `maven-dependency-analyzer` maps each used class to a single artifact and reports analysis only in terms of that mapping: + +- `DefaultProjectDependencyAnalyzer#buildClassToArtifactMap(...)` retains one provider per class (declared wins over undeclared, else first wins; if two declared artifacts contain the class only the first is credited). +- `ProjectDependencyAnalysis` carries `usedDeclared` / `usedUndeclared` / `unusedDeclared` keyed by `Artifact` (with usages), and discards all non-winning providers and any pre-mapping view. + +Consumers (e.g. `maven-dependency-plugin:analyze*`) therefore suggest/attribute a single dependency even when the reference is ambiguous or when a shaded aggregate wins over the intended API jar. Users cannot see raw referenced types, alternative providers, or whether a suggestion is ambiguous. This is most visible with shaded/uber jars, overlapping APIs, and accidental duplicates. + +**Related:** #313 / PR #315 (1.17.3) fixed the important subcase where a *declared* artifact should be credited over an undeclared duplicate, but the core information loss and ambiguity visibility remain (see #280 discussion). + +## Goals +- Preserve current analysis semantics and public API behavior by default (backward compatible). +- Expose enough information for callers to: (1) inspect used/referenced classes before or alongside artifact attribution, (2) enumerate all candidate artifacts that provide a used class, (3) detect and report ambiguity (and optionally identify the load-order/selected winner). +- Enable richer `dependency:analyze` output (e.g. “class X found in A, B, C — selected A*”) without forcing a UX choice in the analyzer. + +## Non-goals (initially) +- Changing default winner selection policy beyond what #315 already does (can be revisited separately). +- Solving duplicate-class detection/reporting in general (that remains `enforcer:banDuplicateClasses` territory); this proposal focuses on *used* references and their attribution. + +## Proposed API changes + +### `ProjectDependencyAnalysis` (additive) +Keep existing constructors/getters/behavior. Add optional data, defaulting to empty for existing construction paths: + +1. **Raw used classes (pre-mapping / as observed)** + - `Set<String> getUsedClassNames()` — all dependency class names referenced by analyzed bytecode (union of main/test usages considered by analysis), regardless of whether they mapped to an artifact/JDK exclusion. + - Optionally `Set<String> getUnmappedUsedClassNames()` for referenced classes with no providing artifact in `artifactClassMap` (if any reach this layer). + +2. **Candidates per class** + - `Map<String, Set<Artifact>> getCandidateArtifactsByUsedClass()` (or `getProvidingArtifactsByUsedClass()`), containing for each used class the set of resolved artifacts that contain it (from `artifactClassMap`), ordered deterministically where order matters. + - Convenience: `Set<String> getAmbiguousUsedClassNames()` — used classes with `candidates.size() > 1`. + - Convenience: `Set<Artifact> getCandidateArtifacts(String className)`. + +3. **Selected/winner (optional but useful)** + - Expose the chosen artifact per class (current mapping result), e.g. `Map<String, Artifact> getSelectedArtifactByUsedClass()`, so callers can mark the winner among candidates. + +**Construction/back-compat:** add a new constructor/builder or overloads accepting the additional structures; existing constructors delegate with empty maps/sets. `equals/hashCode/toString` should account for new fields only if included (consider compatibility) — prefer additive `toString` sections and document equality semantics. + +### `DefaultProjectDependencyAnalyzer` +- Build and retain a **class -> all candidate artifacts** view from `artifactClassMap` (and declared set if needed for deterministic ordering), not only the collapsed `class -> chosen artifact` map. +- Continue to produce the existing single-artifact `usedDeclared/usedUndeclared/unusedDeclared` results exactly as today (using the same winner policy) so behavior is unchanged. +- Pass raw used class names, candidate map, and selected map into the returned `ProjectDependencyAnalysis`. +- Keep `buildClassToArtifactMap` semantics intact for existing callers; add an internal/helper method (e.g. `buildClassToCandidateArtifactsMap`) for the full view. + +### `DependencyUsage` (optional, lower priority) +If finer-grained reporting is desired, usages could carry ambiguity metadata (e.g. candidate count or ids). This is a larger API ripple; prefer analysis-level maps first. + +## Consumer impact (`maven-dependency-plugin`) +Out of scope for this repo, but enabled by the above: +- `dependency:analyze` / `analyze-only` / `analyze-report` can list all candidate artifacts for an ambiguous used-undeclared class, mark the selected/winner, and/or warn on ambiguity. +- Configuration could gate verbose/ambiguous output to avoid noisy defaults. + +## Example (illustrative) +Referenced class `jakarta.activation.DataHandler` found in `org.glassfish.metro:webservices-api` (shaded, undeclared, selected by current rules*) and `jakarta.activation:jakarta.activation-api` (declared/undeclared depending on POM). Report: +- used class: `jakarta.activation.DataHandler` +- candidates: `[jakarta.activation:jakarta.activation-api, org.glassfish.metro:webservices-api]` +- selected: `org.glassfish.metro:webservices-api` (*subject to winner policy) +- ambiguous: `true` + +## Testing +- Unit tests: mapping produces correct candidate sets and preserves current winner for single- and multi-provider classes (declared-over-undeclared, first-wins fallback, two declared providers). +- IT: duplicate-class scenario (e.g. class present in a declared jar and an undeclared jar; and in two undeclared jars) asserts existing used/unused/undeclared results unchanged and new candidate/raw data present. +- Regression: all existing analyzer/IT expectations remain valid. + +## Open questions +- Should candidate ordering reflect classpath/load order (deterministic) vs grouped (declared first) vs unspecified? (Must be documented; deterministic preferred.) +- Should scope influence “winner” selection or be reported separately? (#315 explicitly did not consider scope except declared-vs-undeclared.) +- `equals/hashCode` compatibility for `ProjectDependencyAnalysis` when new fields are added. +- Naming: `candidate` vs `providing` artifacts; “raw used classes” vs “referenced classes”. +- Whether to surface ambiguity only where `selected` differs from what a human would expect, or for all multi-provider used classes. + +## Implementation plan (incremental) +1. Add analysis-level data structures and accessors with defaults (no behavior change). +2. Compute and populate candidate/selected/raw-used maps in `DefaultProjectDependencyAnalyzer` alongside existing mapping. +3. Add unit/IT coverage for duplicate-class visibility while locking current outcomes. +4. Follow-up in `maven-dependency-plugin` to render ambiguity/candidates (separate change, version alignment).
