fix(java): a contested name fails its own query, not the whole application

[rahlk]

Closes #420. Related: codellm-devkit/codeanalyzer-java#269 (where the duplicates originate).

The defect

JCodeanalyzer._add_type raised while flattening the containment tree, and self._index() is the last line of __init__ — so an application carrying duplicate qualified names could not be loaded, and every query became unavailable, including the overwhelming majority naming no duplicated type. The realistic input is a monorepo whose services vendor a shared internal library, putting several copies of one package into one analysis.

Surfacing the ambiguity was right. Refusing the whole application for it was not.

The change

Both backends record the competing files while indexing and refuse at the name-addressed query, through one shared guard on JavaAnalysisBackend:

def _refuse_if_contested(self, qualified_class_name: str) -> None:
    paths = getattr(self, "_contested", {}).get(qualified_class_name)
    if paths:
        raise CodeanalyzerExecutionException(duplicate_type_name(qualified_class_name, paths))

That also settles an inconsistency: the in-memory backend raised at construction while JNeo4jBackend._idx is a @cached_property and raised lazily, despite a docstring saying it "Mirrors JCodeanalyzer._index". They now fail at the same point on the same input, which the new test asserts directly.

Nothing is dropped. Callables stay keyed by their own can:// id, distinct per copy, so every copy remains addressable even while its name is not.

The message no longer blames the analyzer — it emitted both declarations correctly, with distinct ids; the duplication is a property of the source tree — and now names the colliding files so the reader can act on it:

type qualified name 'com.ibm...MarketSummaryDataBean' is declared in 2 files
(src/main/java/.../MarketSummaryDataBean.java, vendored/src/main/java/.../MarketSummaryDataBean.java):
several declarations spell one name, so a query naming it cannot be answered —
analyse the copies separately, or deduplicate them in source

Why not "return all candidates"

Considered and rejected; reasoning recorded on #420. The name-addressed methods are on the shared cross-language ABC (cldk/analysis/commons/backend.py:119-136), so widening their return types touches 44 definitions across 10 files — the ABC plus an in-memory backend, a Neo4j backend and a facade for each of Java, Python and TypeScript — and charges Python and TypeScript for a Java monorepo's vendored copies. A well-formed single-service analysis has exactly one class per FQN. If enumerating copies becomes a real need, the additive move is a parallel get_classes(name) -> List[T], which breaks nothing.

Public signatures are untouched — get_class still returns JType | None. The 113 public-surface tests pass unchanged, which is the evidence for that claim rather than an assertion of it.

Tests

tests/analysis/java/test_java_duplicate_fqn.py, 5 cases written failing-first. The fixture copies one module of the real daytrader8 analysis to a second path, rewriting only its can:// ids — exactly what a vendored copy looks like to the analyzer.

• an application carrying duplicate qualified names still loads
• a name declared once answers as it always did
• the contested name raises at the query and names the competing files
• every copy stays addressable by its own can:// id
• the Neo4j backend agrees with the in-memory one

Verification

1795 passed, 4 failed, 404 skipped. All four failures are in test_java_e2e.py and environmental — the locally installed codeanalyzer-java is 3.1.1 against a 3.3.3 pin, and two of them state outright that they are "Measured off the 3.3.3 jar". Confirmed pre-existing by re-running on a stashed tree.

Sequencing

Worth landing with or behind codellm-devkit/codeanalyzer-java#269. The index-time raise was the only mechanism telling a caller the input was unsafe; bundled analyses now load, and until #269 lands they will load with the wrong-copy call edges the analyzer emits. This PR makes the ambiguity precise, not the resolution correct.

Base branch

Opened against release/2.0, which is the checked-out line; retarget to main if that is wrong.