Epic: Java config-read edges and the entrypoint report

[rahlk]

Spec

docs/design/specs/2026-09-07-java-config-reads-and-entrypoint-report.md

Summary

codeanalyzer-java projects 9,688 :ConfigKey nodes and 2,604 :JEntrypoint marks, but nothing that says which code reads a key and nothing about how the entrypoint pass behaved. This epic adds application.config_uses[], application.config_reads_unresolved[] and application.entrypoint_report{} to analysis.json, and J_USES_CONFIG, J_READS_CONFIG_UNRESOLVED plus two :JApplication properties to the Neo4j projection.

Contract impact: additive in both projections. No shared field renamed, no shared kind repurposed. The graph contract version does not move — see the release plan.

Affected repos

• codeanalyzer-java — the detection pass, the entrypoint report, both projections. Children 1–3.
• python-sdk — the Java facade has no config accessor and no entrypoint-coverage accessor at all today, so consuming this data is new surface, not a read-the-new-field change. Child 4, deferred to a later cycle.
• docs — contract note, folded into the last analyzer child.

Design decisions

• J_ prefix (J_USES_CONFIG, J_READS_CONFIG_UNRESOLVED), matching codeanalyzer-python's PY_-prefixed pair. The unprefixed spelling was genuinely tempting — :ConfigKey is a cross-language merge target, so one MATCH would answer "who reads this key" across every analyzer — but python has shipped PY_USES_CONFIG, and one concept spelled two ways is the parity failure the clause names. Accepted cost: a cross-language config-read query needs one MATCH per language.
• src widens to the annotated element. Python anchors a config read on a call body node because Python's config reads are calls. Java's dominant idiom is @Value("${db.url}") / @ConfigurationProperties, an annotation with no call site. So J_USES_CONFIG runs from JBodyNode (call-site reads) or JCallable/JField/JType (annotation reads). Rejected: minting a synthetic body node per annotation — it invents a body-node kind with no AST region behind it, a larger addition to the shared vocabulary than widening one endpoint list. Rejected: call sites only — literal parity that reports almost nothing on a Spring app, which is most of the daytrader8 corpus this was measured on.
• Literal tier at L1, dataflow tier at L3/L4. Python gates its literal tier at -a 2; Java's JBodyNode already carries argument_expr/receiver_type/method_name at L1 and annotations are L1 data, so nothing in the tier needs a call graph. Monotonic by construction: config_uses(-a 1) ⊆ config_uses(-a 4), same additive contract as the DDG's ssa → points-to widening. Divergence stated: the same flag gives different availability on the two analyzers.
• Unresolved reads follow python exactly — JApplication → JExternal, props {key, reason, prov, _k}, ghost minted at detection time so a read stays visible at L1 and with --external-calls off. _k = "<key>|<reason>" because one callee (System.getenv) reads many undeclared keys and a plain endpoint-pair MERGE keeps only the last.
• Entrypoint report is python's four keys, honestly populated: rulesets is the five hardcoded finder names (that is Java's ruleset vocabulary), unresolved counts per-finder near-misses, errors records a finder that threw. Always present, even when empty — the pass under-approximates by design, so an absent report and an empty one must not read the same.

Scope guard — explicitly OUT:

• Comment nodes. codeanalyzer-java#231 listed this as a third goal on the stated grounds that codeanalyzer-python projects comment nodes. It does not: there is no :PyComment node type in codeanalyzer/neo4j/schema.py, and project.py:843 collapses comments to a docstring property exactly as V2GraphProjector.docstringOf does. python-sdk documents it as a deliberate ceiling (neo4j_backend.py:73). No parity gap, no term to match — closed by fact. Projecting comments remains available later as a new capability, not as this parity fix.
• CRUD (codeanalyzer-java#187).
• The can:// id missing from the :JApplication root (codeanalyzer-schema#5).
• codeanalyzer-typescript's identical config gap.

Release plan

• codeanalyzer-java 3.0.3 → 3.1.0 (MINOR — additive JSON fields, additive graph relationships) carries children 1–3. Nothing gates the analyzer.
• The graph contract version stays 2.0.0. V2SchemaCatalog.SCHEMA_VERSION is deliberately held there; the class javadoc's "2.2.0" is stale text. This analyzer already drifted to 2.1.0/2.2.0/3.0.0 alone while codeanalyzer-python stayed at 2.0.0, and that drift was undone. Moving it is a coordinated re-baseline across all three analyzers — Epic: scope every destructive Neo4j statement on the can:// id prefix; retire _module #50, not this epic. Recorded consequence: a consumer cannot detect J_USES_CONFIG or the entrypoint properties from schema_version alone. Detection is by presence until Epic: scope every destructive Neo4j statement on the can:// id prefix; retire _module #50 lands, the same gap the _module removal already lives with.
• python-sdk is deferred, by decision. Stated plainly: the analyzer will emit data nothing consumes, and codeanalyzer-java#231's actual complaint — get_config_readers() returning an unconditional [], get_entrypoint_coverage() reporting entrypoint_report_unavailable — stays unfixed until child 4 ships in a later cycle.

Planned children, filed just-in-time as each is picked up:

1. codeanalyzer-java — literal tier: detectors, resolver, both new JSON lists, both new relationship types.
2. codeanalyzer-java — dataflow tier over the L3/L4 DDG, prov: ["dataflow"].
3. codeanalyzer-java — entrypoint report: model, finder plumbing, both projections, docs.
4. python-sdk — Java facade accessors. Deferred.

Definition of done (epic-level)

• Every sub-issue closed with its gate green.
• On a daytrader8 projection: J_USES_CONFIG is non-empty, every dst resolves to a projected :ConfigKey, and every src resolves to a projected :JBodyNode/:JCallable/:JField/:JType. No dangling endpoints.
• MATCH (a:JApplication) RETURN any(k IN keys(a) WHERE k CONTAINS 'entrypoint') returns TRUE.
• Monotonicity holds on a fixture carrying both a literal and a dataflow-only read: config_uses(-a 1) ⊆ config_uses(-a 3) ⊆ config_uses(-a 4).
• analysis.v2.schema.json admits the three new application-level members; the L1 conformance gate stays green.
• entrypoint_report_json parses with the same model shape as codeanalyzer-python's, and is present on every projection including one with zero entrypoints.
• CHANGELOG updated; codeanalyzer-java 3.1.0 released.

[rahlk]

Shipped in codeanalyzer-java 3.1.0

All three analyzer children are closed and released. The spec is merged to main at docs/design/specs/2026-09-07-java-config-reads-and-entrypoint-report.md, so the link above resolves.

Child	PR	On main
#232 config-read literal tier	#233	79d201c
#234 entrypoint report + node attribution	#235	52212d2
#236 dataflow tiers (L3 intra, L4 interprocedural)	#237	b010151
— stale contract-version prose	#238	5b40540
— release	#239	21cc730, tag v3.1.0

MINOR, not PATCH. The release was initially asked for as 3.0.4; it went out as 3.1.0 because the change adds public surface — config_uses[], config_reads_unresolved[], entrypoint_report{} and entrypoint_frameworks in analysis.json, plus two Neo4j relationship types and three node properties. A patch tag would have told a consumer on a ~3.0 pin there was nothing new to read.

The graph contract version did not move. V2SchemaCatalog.SCHEMA_VERSION is still 2.0.0, so these relationships are detectable by presence, not by version, until #50 re-baselines all three analyzers. #238 records that on the constant itself, with an explicit "do not bump this to advertise them".

Published: PyPI codeanalyzer-java==3.1.0, GitHub Release v3.1.0 (jar + installer + schema.neo4j.json, byte-identical to the repo copy).

Gates, run on the tagged commit

Gate	Result
Fixture suite	546 tests; the one failure is CodeAnalyzerIntegrationTest, which needs a Docker daemon and fails identically on pre-existing commits
Schema conformance	-a 1/2/3/4 on daytrader8: 0 errors each
Monotonicity	full-tree facts 6226 → 6226 → 11095 → 15725, 0 lost at any step
Determinism	two runs byte-identical
Cross-projection	J_USES_CONFIG cypher 15 = json 15; J_READS_CONFIG_UNRESOLVED cypher 6 = the 6 distinct (key, reason) pairs _k collapses 12 json records into

What is knowingly unproven

• The dataflow tiers are fixture-proven only. daytrader8's config reads are all literals or undeclared keys — it has no non-literal read to widen — and the other checked-in fixtures have no config reads or no checked-out sources. The corpus runs prove monotonicity and the absence of false positives, not the closures.
• --l3-engine wala was never exercised, since it needs a built project. That is exactly the configuration where the intra tier's ssa filter earns its keep (spec §4 D3, refusal 2). Worth one run against a real build.
• unresolved/errors in the entrypoint report will usually be empty. They capture a finder that throws, and the finders swallow their own resolution failures internally (StrutsEntrypointFinder.java:41). Recorded in the spec, out of scope for #234.

Remaining

Child 4, the python-sdk Java facade accessors, stays unfiled and deferred by the release-plan decision. It is now unblocked — 3.1.0 is published — and until it ships, #231's original complaint stands: cldk/analysis/java/ has no config accessor and no entrypoint-coverage accessor, so the analyzer emits this data and nothing consumes it. This epic stays open on that child.