Repository-artifact layer for java — artifact / dependency / config_key nodes

[georgesafta]

Summary

Implement the repository-artifact layer in codeanalyzer-java — the producer-side evidence a cross-service / whole-application analysis needs but no analyzer emits today. Contract of record: docs/design/specs/repository-artifact-layer.md (committed in codellm-devkit/.github), tracked by epic codellm-devkit/.github#45.

This is the first PR for the Java train, the application-anchored slice, into the canonical schema v2 model (--schema v2, package com.ibm.cldk.schema.*):

• artifact nodes (JArtifact) — a non-source file inventory with raw-text capture
• dependency nodes (JDependency) — normalized deps parsed from pom.xml / Gradle coordinates (net-new — today deps are only downloaded as jars, never modeled)
• config_key nodes (JConfigKey) — normalized keys from structured config files

All three anchor on the application node (stable, no body-node risk). The shared vocabulary (scope enum, artifact_kind enum, @artifact/ id grammar) is coined verbatim per the spec's parity clause, identical to the python/typescript trains.

Two Java-specific divergences (found by inspecting the code, not just the spec)

1. Neo4j is now available for this layer — the premise this issue was written on is obsolete. When this issue was filed, analyzeV2() rejected --emit neo4j and the Neo4j projector ran entirely off the legacy v1 IR, so a v2 addition could reach analysis.json but never the graph. That is no longer true: PR feat(l4): interprocedural SDG — param_in/param_out, semantic DDG, summary edges, graph 2.1.0 #203 shipped the canonical v2 graph projection (V2GraphProjector, V2SchemaCatalog, graph contract 2.0.0, since bumped to 2.1.0 by the L4 overlay), removed the guard, and made --schema v2 the default. "Roadmap candidate 9", the v1→v2 Neo4j migration this issue deferred to, is done. Whoever picks this up should decide afresh whether to project the artifact layer into the graph in the same PR — the epic's J_USES_CONFIG-only deferral and this issue's broader whole-layer deferral were both consequences of a blocker that no longer exists. Note that V2SchemaCatalog already reserves un-prefixed Artifact and Package labels as cross-language merge targets, declared but not emitted, so the graph vocabulary is partly staked out already.

2. Artifact discovery needs a new repo-wide walk. The v2 walk (L1Extractor.extractAll) is source-root scoped — it only enumerates .java files under JavaParser source roots and never sees a repo-root pom.xml / application.yml / Dockerfile. The inventory needs its own Files.walk of the project root, homed alongside utils/ProjectDirectoryScanner.java, not hooked into L1Extractor.

Scope

In (this PR):

• JArtifact / JDependency / JConfigKey Lombok @Data POJOs + JApplication.artifacts map (com.ibm.cldk.schema.*)
• CanId.artifactId / dependencyId / configKeyId helpers (@artifact/ marker keeps them out of the signatureOf id space)
• Repo-wide inventory + classification walk (new com.ibm.cldk.artifacts package); other catch-all — a file is never dropped
• Raw-text capture (utf-8 / binary / over-cap truncation), --artifact-text / --no-artifact-text (default on) + --artifact-text-max-bytes (default 262144); parsing reads a decode buffer independent of capture so the flag drops only the raw-text payload
• Dependency parse: pom.xml (JDK DOM, on the classpath) with groupId:artifactId identity, version_spec, <scope>/<optional> → shared scope; build.gradle/.kts shallow regex reader; gradle.lockfile → resolved_version; ecosystem="maven"
• Config parse (overlay — failure never drops the artifact): .properties (java.util.Properties), application.yml/.yaml (needs a new YAML dep — see open decision), Jakarta EE .xml descriptors; dotted keys, value, references[] (${VAR} → env:VAR)
• Extend the local conformance schema src/test/resources/schema/analysis.v2.schema.json ($defs + enum constraints + application.artifacts) — the L1 conformance gate validates against it with additionalProperties:false
• Decision-log entry

Out (follow-ups / other trains):

• config_use / J_USES_CONFIG edge (follow-up PR; Java is well-positioned — JBodyNode already carries receiverExpr/argumentExpr at L1, so System.getenv reads are visible without a PyCallArgument.value-style extension; @Value/@ConfigurationProperties reads anchor on JDecorator)
• All Neo4j projection of the artifact layer — rides candidate 9 — obsolete: candidate 9 landed in PR feat(l4): interprocedural SDG — param_in/param_out, semantic DDG, summary edges, graph 2.1.0 #203. Re-scope when picked up.
• python / typescript analyzers; python-sdk mirror

Open decisions (resolve before/at review)

1. YAML dependency: add SnakeYAML to build.gradle now (enables application.yml config-key extraction; needs a reflect-config.json entry for native-image), or ship .yml inventoried-but-unparsed this PR. Recommendation: add now — application.yml is the dominant Spring Boot config surface.
2. Gradle depth: shallow regex reader misses version-catalog (libs.*) / dynamic deps. Accept as a documented, logged limitation for PR 1 (Maven pom.xml is the complete path), or scope Gradle out of PR 1.

Acceptance

• application.artifacts emitted as a contained named map of artifact nodes with stable can://…/@artifact/… ids; unrecognized files artifact_kind:"other", never dropped
• pom.xml (and best-effort Gradle) parsed into dependency nodes with groupId:artifactId identity and correct scope; gradle.lockfile pins resolved_version
• Structured config exposes config_key nodes with dotted keys and recognized references[]
• Text-decodable artifacts carry verbatim text + text_encoding/text_truncated; binary/over-cap remain inventoried with path + content_hash
• --no-artifact-text drops only the text payload; inventory + deps + config overlay unchanged
• artifacts section byte-identical across -a 1|2|3 (ungated / all-levels)
• L1ConformanceGateTest green (local v2 schema extended); no null leaves
• Neo4j untouched: Neo4jSchemaConformanceTest green, schema_version 1.0.0 unchanged, --schema v2 --emit neo4j still errors, no artifact labels in the graph catalog — obsolete. The v1 catalog is no longer what --emit schema emits (it now always emits the v2 catalog, currently 2.1.0), and --schema v2 --emit neo4j is the supported default path. Replace with whatever the re-scoping decides.
• Existing v2 symbol_table/call_graph output byte-identical

Part of epic codellm-devkit/.github#45. Sibling: codeanalyzer-python#152.

---

Update (2026-08-29): the Neo4j premise above was invalidated by PR #203 (v2 graph projection) and PR #205 (@entry defines the formals). Struck text is left visible rather than deleted so the original reasoning stays auditable. The rest of the scope — application-anchored JArtifact/JDependency/JConfigKey, pom.xml/Gradle coordinate parsing, config-key extraction, and the repo-wide walk L1Extractor cannot do — is unaffected and still accurate.

[rahlk]

The python train is complete and released (codeanalyzer-python 1.3.0, 2026-08-29): artifacts + dependencies (#157/#160), ConfigKey family (#152/#163), the level-graded config_use edge (#162/#164), and deployment-env namespaces (#165/#168). The epic (codellm-devkit/.github#45) now carries a "Contract as shipped" section — where this issue's original text follows the epic's older sketch, the shipped contract supersedes it. The load-bearing deltas:

• No language-prefixed nouns: graph labels are neutral Artifact / Package / ConfigKey (shared MERGE targets across analyzers) — not JArtifact/TSArtifact-style triplets. Language-specific edges keep the prefix: your *_PROVIDES, *_UNRESOLVED_IMPORT, *_USES_CONFIG.
• Ids: can://artifact/<app>/<path> (neutral namespace); packages by purl (pkg:maven/… / pkg:npm/…); config keys <artifact-id>@key/<dotted.key>. --app-name agreement is the join precondition.
• Placement: application.artifacts sibling map, config keys nested per artifact; the code tree stays code-only.
• Classification: open roles: string[] (never-drop inventory: unmatched decodable → unknown, binaries hash-only), not a closed artifact_kind enum.
• Dependency record: kind {runtime, dev, optional, build}, prov {declared, lockfile, installed-metadata, heuristic}, direct: false for lockfile-only transitives, locked_version.
• Text policy: capture-on default, 256 KiB cap, --artifact-text/--no-artifact-text, --artifact-text-max-bytes; extraction parses full on-disk text, never the stored copy.
• config_use: literal tier at the call-graph level, dataflow tiers over your own def-use substrate, unresolved reads first-class with reasons; deployment-env sources (Dockerfile ENV, compose/k8s env) mint bindable env keys, Dockerfile ARG a non-bindable dockerfile namespace.
• Neo4j SCHEMA_VERSION stays 2.0.0 until the layer settles across all analyzers.

Copy-from reference: the three specs in codeanalyzer-python docs/design/specs/ (2026-08-27 artifacts, 2026-08-28 config-key family, 2026-08-28 config-use edge) and the v1.3.0 release assets — schema.json + schema.cypher are the machine-readable contract; analyzing-canpy-graphs-skill.tar.gz documents the query surface the layer should support.

Java-specific notes: pom.xml/Gradle parsing maps onto the same record shape (purl pkg:maven/<group>/<artifact>; Maven scopes → the shared kind values per the epic's mapping duty, now expressed against kind not scope). The J_USES_CONFIG-deferred-to-candidate-9 boundary is unchanged — analysis.json carries config_uses facts; the Neo4j edge rides the v2 migration.

[rahlk]

Implementation plan committed: docs/design/plans/2026-08-29-repository-artifact-layer.md (5ef4ad4 on main), seven tasks.

It emulates codeanalyzer-python v1.3.0 rather than the spec, on explicit instruction. Read codellm-devkit/.github#48 alongside it: the spec mandates an artifact_kind enum, a scope enum, and an ecosystem mapping table that the reference implementation never built — the whole python package contains exactly one Enum, and it is unrelated. So this issue's line about coining that vocabulary "verbatim per the spec's parity clause, identical to the python/typescript trains" cannot be satisfied as written; the two clauses contradict each other. The plan follows the trains.

What that means concretely: bare format (one value) plus many-valued roles[] instead of artifact_kind; kind with python's four values instead of the spec's six; ecosystem as a hardcoded "maven" literal; artifacts as sibling maps on the application with symbol_table left strictly code-keyed; and lockfile-only transitive dependencies emitted with direct=false, which the spec scopes out but python ships.

Four places the plan decides rather than transcribes, because Java's ecosystem differs: Maven provided/system scope has no slot in python's four-value kind (mapped to build, documented); purl becomes two-segment pkg:maven/<group>/<artifact>, so JDependency carries group additively; PEP 503 normalization is not ported; and provides_imports/unresolved_imports are not implemented at all — they exist in python because a PyPI distribution name is not its import name, which is not a Java problem, and doing it properly means reading package indexes out of resolved jars.

Task 7 is the Neo4j projection that this issue originally deferred, now unblocked. One new dependency: org.yaml:snakeyaml, needed for application.yml; it is currently only transitively present.

Out of scope and worth their own issues: config_use/J_USES_CONFIG (python's detector-rule mechanism is call-shaped and has no purchase on Spring's @Value annotation injection), POM parent and BOM-import inheritance, and transitive Maven resolution beyond what a lockfile states.