fix(neo4j): carry body_span, type parameters, leaf spans and call-site facts (#258)

The sweep that followed #255 walked every analysis.json `$def` against
V2GraphProjector and found nine more fields the payload emits and the graph
declares nowhere. This is the mechanical half: additive properties, no new node
family, no comment model, no schema_version move.

- `:JCallable` gains the body block's own offsets under a `body_` prefix
  (`body_start_line` … `body_end_byte`). `span` covers the whole declaration, so
  before this the graph could not tell a signature from the body it encloses, and
  a body-less declaration read the same as one whose body was not recorded. A
  prefix rather than a second node: a body block has no identity, it is a second
  pair of offsets into the same file. Absent, not zeroed, when there is no body.
- `:JType` and `:JCallable` gain `type_parameters_json`. A type parameter carries
  a name, resolved bounds, a span and its own annotations, so it does not flatten
  to a scalar — same treatment as `parameters_json`, which is the precedent for
  exactly this shape.
- The enum-constant and record-component blocks now call `putLines` and
  `annotate`, as `projectField` already did. Both leaf labels join the
  `J_ANNOTATED_BY` sources.
- `J_ANNOTATED_BY` carries the application site's span, on a keyed edge. Java
  annotations are repeatable, so one (owner, annotation) endpoint pair
  legitimately occurs twice on one declaration; a plain MERGE collapsed the two
  applications onto one relationship and kept only the last span and argument
  list. `_k` is the span key.
- `:JBodyNode` gains `callee_signature` (the erased signature of the resolved
  callee, which is what distinguishes overloads at a call site) and `arguments`.

`arguments` stays body-local rather than being mapped through `globalOrdinal` the
way `call_node` is, which is what #256 specified. The conformance assertion for
that mapping failed on the first run: an argument id names an argument
*expression*, and an expression is a body node only when it is itself a call site.
On daytrader8, 537 of 3666 argument ids name a body node, so the mapping would
have handed out 3129 `:JBodyNode` ids resolving to nothing. Carrying the
canonical local ids verbatim keeps the fact exact and positionally aligned with
`argument_expr` and `argument_types`; a consumer that wants the node for a nested
call composes it the same way this projection does.

Every field is asserted against the analysis.json value per node, not by
presence, and the body offsets are asserted to slice `:JModule.source` to text
that starts with `{` and ends with `}`. The enum, record, annotation and generics
assertions run over `enum-record-bodies-test` and
`generics-varargs-duplicate-signature-test`: the L4 fixture declares no enum, no
record, no annotation and no generic, which is how these drops survived every
existing assertion.

Closes #256

Author: rahlk

schema.neo4j.json

@@ -44,6 +44,7 @@
         "base_types": "string[]",
         "interfaces": "string[]",
         "docstring": "string",
+        "type_parameters_json": "string",
         "is_entrypoint": "boolean",
         "entrypoint_frameworks": "string[]",
         "start_line": "integer",
@@ -76,12 +77,19 @@
         "is_implicit": "boolean",
         "is_entrypoint": "boolean",
         "entrypoint_frameworks": "string[]",
+        "type_parameters_json": "string",
         "start_line": "integer",
         "start_column": "integer",
         "end_line": "integer",
         "end_column": "integer",
         "start_byte": "integer",
-        "end_byte": "integer"
+        "end_byte": "integer",
+        "body_start_line": "integer",
+        "body_start_column": "integer",
+        "body_end_line": "integer",
+        "body_end_column": "integer",
+        "body_start_byte": "integer",
+        "body_end_byte": "integer"
       }
     },
     {
@@ -139,7 +147,13 @@
         "id": "string",
         "name": "string",
         "arguments": "string[]",
-        "docstring": "string"
+        "docstring": "string",
+        "start_line": "integer",
+        "start_column": "integer",
+        "end_line": "integer",
+        "end_column": "integer",
+        "start_byte": "integer",
+        "end_byte": "integer"
       }
     },
     {
@@ -152,7 +166,13 @@
         "type": "string",
         "modifiers": "string[]",
         "is_variadic": "boolean",
-        "docstring": "string"
+        "docstring": "string",
+        "start_line": "integer",
+        "start_column": "integer",
+        "end_line": "integer",
+        "end_column": "integer",
+        "start_byte": "integer",
+        "end_byte": "integer"
       }
     },
     {
@@ -171,6 +191,8 @@
         "is_static_call": "boolean",
         "argument_types": "string[]",
         "argument_expr": "string[]",
+        "callee_signature": "string",
+        "arguments": "string[]",
         "var": "string",
         "call_node": "string",
         "start_line": "integer",
@@ -392,13 +414,22 @@
       "from": [
         "JType",
         "JCallable",
-        "JField"
+        "JField",
+        "JEnumConstant",
+        "JRecordComponent"
       ],
       "to": [
         "JAnnotation"
       ],
       "properties": {
-        "arguments": "string[]"
+        "arguments": "string[]",
+        "_k": "string",
+        "start_line": "integer",
+        "start_column": "integer",
+        "end_line": "integer",
+        "end_column": "integer",
+        "start_byte": "integer",
+        "end_byte": "integer"
       }
     },
     {

src/main/java/com/ibm/cldk/neo4j/V2GraphProjector.java

@@ -38,6 +38,7 @@
 import com.ibm.cldk.schema.JModule;
 import com.ibm.cldk.schema.JRecordComponent;
 import com.ibm.cldk.schema.JType;
+import com.ibm.cldk.schema.JTypeParameter;
 import com.ibm.cldk.schema.JVariableDeclaration;
 import com.ibm.cldk.schema.Span;
 import com.ibm.cldk.schema.V2Json;
@@ -218,6 +219,7 @@ private static void projectType(RowBuilder b, NodeRef parent, String containment
         p.put("base_types", type.getBaseTypes());
         p.put("interfaces", type.getInterfaces());
         p.put("docstring", docstringOf(type.getComments()));
+        putTypeParameters(p, type.getTypeParameters());
         putLines(p, type.getSpan());
         if (type.isEntrypointClass()) {
             p.put("is_entrypoint", true);
@@ -252,9 +254,11 @@ private static void projectType(RowBuilder b, NodeRef parent, String containment
             ep.put("name", ec.getName());
             ep.put("arguments", ec.getArguments());
             ep.put("docstring", docstringOf(ec.getComments()));
+            putLines(ep, ec.getSpan());
             ep.put("_module", fileKey);
             NodeRef er = b.node(Arrays.asList("JEnumConstant"), "id", id, RowBuilder.prune(ep));
             b.edge("J_HAS_ENUM_CONSTANT", ref, er);
+            annotate(b, er, ec.getDecorators());
         }
         for (JRecordComponent rc : type.getRecordComponents()) {
             Map<String, Object> rp = RowBuilder.props();
@@ -267,9 +271,11 @@ private static void projectType(RowBuilder b, NodeRef parent, String containment
                 rp.put("is_variadic", true);
             }
             rp.put("docstring", docstringOf(rc.getComments()));
+            putLines(rp, rc.getSpan());
             rp.put("_module", fileKey);
             NodeRef rr = b.node(Arrays.asList("JRecordComponent"), "id", id, RowBuilder.prune(rp));
             b.edge("J_HAS_RECORD_COMPONENT", ref, rr);
+            annotate(b, rr, rc.getDecorators());
         }
         for (Map.Entry<String, JCallable> c : type.getCallables().entrySet()) {
             projectCallable(b, ref, c.getKey(), c.getValue(), module, fileKey, typeIdByFqn);
@@ -332,7 +338,13 @@ private static void projectCallable(RowBuilder b, NodeRef owner, String signatur
             p.put("is_entrypoint", true);
             p.put("entrypoint_frameworks", c.getEntrypointFrameworks());
         }
+        putTypeParameters(p, c.getTypeParameters());
         putLines(p, c.getSpan());
+        // The body block's own offsets, under a `body_` prefix. `span` covers the whole declaration,
+        // so without this the graph cannot tell the signature from the body it encloses -- and an
+        // abstract or interface method, which has no body at all, reads the same as one whose body
+        // was simply not recorded. Absent (not zeroed) when there is no body.
+        putLines(p, c.getBodySpan(), "body_");
         p.put("_module", fileKey);
         NodeRef ref = b.node(labels, "id", c.getId(), RowBuilder.prune(p));
         b.edge("J_HAS_METHOD", owner, ref);
@@ -369,6 +381,15 @@ private static void projectCallable(RowBuilder b, NodeRef owner, String signatur
             np.put("is_static_call", n.getIsStaticCall());
             np.put("argument_types", n.getArgumentTypes());
             np.put("argument_expr", n.getArgumentExpr());
+            np.put("callee_signature", n.getCalleeSignature());
+            // The canonical `arguments`: one body-local `line:col` id per argument, positionally
+            // aligned with `argument_expr` and `argument_types`. Kept local, NOT mapped to global
+            // body-node ids the way `call_node` below is: an argument is a body node only when it is
+            // itself a call site (`f(g(x))`), so qualifying every entry with the owning callable
+            // would hand out `:JBodyNode` ids that mostly resolve to nothing. A consumer that wants
+            // the node for a nested call builds it the same way this projection does -- the owner id,
+            // an `@`, then the local id.
+            np.put("arguments", n.getArguments());
             putLines(np, n.getSpan());
             np.put("_module", fileKey);
             // L4 SDG synthetic-vertex payload: absent on every non-synthetic node (prune drops nulls).
@@ -429,6 +450,36 @@ private static String globalOrdinal(String callableId, String localKey) {
         return localKey.startsWith("@") ? callableId + localKey : callableId + "@" + localKey;
     }
 
+    /**
+     * A span as a MERGE discriminant. Byte offsets when the span has them, the line/column pair
+     * otherwise, and {@code ""} for no span -- two annotations without spans collapse, which is the
+     * pre-existing behaviour and no worse than it.
+     */
+    private static String spanKey(Span span) {
+        if (span == null) {
+            return "";
+        }
+        if (span.getBytes() != null && span.getBytes().length > 1) {
+            return span.getBytes()[0] + ":" + span.getBytes()[1];
+        }
+        if (span.getStart() != null && span.getStart().length > 1) {
+            return "L" + span.getStart()[0] + ":" + span.getStart()[1];
+        }
+        return "";
+    }
+
+    /**
+     * The declared type parameters, serialized whole. Each carries a name, its resolved bounds, its
+     * own span and its own annotations, so it does not flatten to a scalar -- same call as
+     * {@code parameters_json}, and for the same reason. Absent when the declaration is not generic.
+     */
+    private static void putTypeParameters(Map<String, Object> p, List<JTypeParameter> params) {
+        if (params == null || params.isEmpty()) {
+            return;
+        }
+        p.put("type_parameters_json", V2Json.compact().toJson(params));
+    }
+
     // ------------------------------------------------------------------------------------------
     // Repository-artifact layer: build manifests, config files, declared dependencies.
     // ------------------------------------------------------------------------------------------
@@ -601,7 +652,12 @@ private static void annotate(RowBuilder b, NodeRef owner, List<JDecorator> decor
                     RowBuilder.prune(mapOf("name", d.getName())));
             Map<String, Object> p = RowBuilder.props();
             p.put("arguments", d.getArgs());
-            b.edge("J_ANNOTATED_BY", owner, ann, RowBuilder.prune(p));
+            putLines(p, d.getSpan());
+            // `_k` = the application site. Annotations are repeatable in Java (`@Foo @Foo`), so the
+            // same (owner, annotation) endpoint pair can occur more than once on one declaration;
+            // without the discriminant a plain MERGE collapses them onto one relationship and keeps
+            // only the last span and argument list SET.
+            b.keyedEdge("J_ANNOTATED_BY", owner, ann, RowBuilder.prune(p), spanKey(d.getSpan()));
         }
     }
 
@@ -733,24 +789,34 @@ private static String slice(String source, Span span) {
      * position (two nodes on one line) unrepresentable.
      */
     private static void putLines(Map<String, Object> p, Span span) {
+        putLines(p, span, "");
+    }
+
+    /**
+     * As above, under a property-name prefix, for a node carrying a second span beside its own —
+     * {@code JCallable} carries the declaration's span unprefixed and the body block's under
+     * {@code body_}. A prefix rather than a second node because a body block is not a thing with an
+     * identity; it is a second pair of offsets into the same file.
+     */
+    private static void putLines(Map<String, Object> p, Span span, String prefix) {
         if (span == null) {
             return;
         }
         if (span.getStart() != null && span.getStart().length > 0) {
-            p.put("start_line", span.getStart()[0]);
+            p.put(prefix + "start_line", span.getStart()[0]);
             if (span.getStart().length > 1) {
-                p.put("start_column", span.getStart()[1]);
+                p.put(prefix + "start_column", span.getStart()[1]);
             }
         }
         if (span.getEnd() != null && span.getEnd().length > 0) {
-            p.put("end_line", span.getEnd()[0]);
+            p.put(prefix + "end_line", span.getEnd()[0]);
             if (span.getEnd().length > 1) {
-                p.put("end_column", span.getEnd()[1]);
+                p.put(prefix + "end_column", span.getEnd()[1]);
             }
         }
         if (span.getBytes() != null && span.getBytes().length > 1) {
-            p.put("start_byte", span.getBytes()[0]);
-            p.put("end_byte", span.getBytes()[1]);
+            p.put(prefix + "start_byte", span.getBytes()[0]);
+            p.put(prefix + "end_byte", span.getBytes()[1]);
         }
     }
 

src/main/java/com/ibm/cldk/neo4j/V2SchemaCatalog.java

@@ -98,9 +98,19 @@ Map<String, String> done() {
      * are the ones they must adopt.
      */
     private static Map<String, String> lines(P p) {
-        return p.put("start_line", "integer").put("start_column", "integer")
-                .put("end_line", "integer").put("end_column", "integer")
-                .put("start_byte", "integer").put("end_byte", "integer").done();
+        return span(p, "").done();
+    }
+
+    /**
+     * The same six properties under a name prefix, for a node carrying a second span beside its own.
+     * {@code JCallable} is the only one: {@code body_*} is the body block, where the unprefixed span
+     * is the whole declaration. Absent entirely on an abstract or interface method, which has no
+     * body -- distinguishable from a body that was not recorded, which the line pair alone was not.
+     */
+    private static P span(P p, String prefix) {
+        return p.put(prefix + "start_line", "integer").put(prefix + "start_column", "integer")
+                .put(prefix + "end_line", "integer").put(prefix + "end_column", "integer")
+                .put(prefix + "start_byte", "integer").put(prefix + "end_byte", "integer");
     }
 
     public static final List<NodeLabel> NODE_LABELS = buildNodeLabels();
@@ -136,18 +146,19 @@ private static List<NodeLabel> buildNodeLabels() {
                 lines(new P().put("id", "string").put("name", "string").put("kind", "string")
                         .put("modifiers", "string[]").put("base_types", "string[]")
                         .put("interfaces", "string[]").put("docstring", "string")
+                        .put("type_parameters_json", "string")
                         .put("is_entrypoint", "boolean").put("entrypoint_frameworks", "string[]"))));
 
         n.add(node("JCallable", "JSymbol", "id",
-                lines(new P().put("id", "string").put("name", "string").put("signature", "string")
+                span(span(new P().put("id", "string").put("name", "string").put("signature", "string")
                         .put("kind", "string").put("declaration", "string").put("return_type", "string")
                         .put("parameters_json", "string").put("modifiers", "string[]")
                         .put("error_channel", "string[]").put("code", "string").put("docstring", "string")
                         .put("cyclomatic_complexity", "integer")
                         .put("referenced_types", "string[]").put("accessed_fields", "string[]")
                         .put("is_implicit", "boolean").put("is_entrypoint", "boolean")
                         .put("entrypoint_frameworks", "string[]")
-                        )));
+                        .put("type_parameters_json", "string"), ""), "body_").done()));
 
         n.add(node("JExternal", "JSymbol", "id",
                 new P().put("id", "string").put("kind", "string").put("signature", "string")
@@ -163,20 +174,21 @@ private static List<NodeLabel> buildNodeLabels() {
                         .put("initializer", "string"))));
 
         n.add(node("JEnumConstant", "JEnumConstant", "id",
-                new P().put("id", "string").put("name", "string").put("arguments", "string[]")
-                        .put("docstring", "string").done()));
+                lines(new P().put("id", "string").put("name", "string").put("arguments", "string[]")
+                        .put("docstring", "string"))));
 
         n.add(node("JRecordComponent", "JRecordComponent", "id",
-                new P().put("id", "string").put("name", "string").put("type", "string")
+                lines(new P().put("id", "string").put("name", "string").put("type", "string")
                         .put("modifiers", "string[]").put("is_variadic", "boolean")
-                        .put("docstring", "string").done()));
+                        .put("docstring", "string"))));
 
         n.add(node("JBodyNode", "JBodyNode", "id",
                 lines(new P().put("id", "string").put("kind", "string").put("method_name", "string")
                         .put("receiver_expr", "string").put("receiver_type", "string")
                         .put("return_type", "string").put("accessibility", "string")
                         .put("is_constructor_call", "boolean").put("is_static_call", "boolean")
                         .put("argument_types", "string[]").put("argument_expr", "string[]")
+                        .put("callee_signature", "string").put("arguments", "string[]")
                         // L4 SDG synthetic-vertex payload.
                         .put("var", "string").put("call_node", "string"))));
 
@@ -238,8 +250,14 @@ private static List<RelType> buildRelTypes() {
         r.add(rel("J_IMPORTS", Arrays.asList("JModule"), Arrays.asList("JModule", "JPackage"),
                 new P().put("spellings", "string[]").put("is_static", "boolean")
                         .put("is_wildcard", "boolean").done()));
-        r.add(rel("J_ANNOTATED_BY", Arrays.asList("JType", "JCallable", "JField"),
-                Arrays.asList("JAnnotation"), new P().put("arguments", "string[]").done()));
+        // `_k` = the application site's span. Java annotations are repeatable (`@Foo @Foo`), so one
+        // (owner, annotation) endpoint pair legitimately occurs twice on one declaration; without the
+        // discriminant a plain MERGE collapses the two applications onto one relationship and keeps
+        // only the last span and argument list SET.
+        r.add(rel("J_ANNOTATED_BY",
+                Arrays.asList("JType", "JCallable", "JField", "JEnumConstant", "JRecordComponent"),
+                Arrays.asList("JAnnotation"),
+                lines(new P().put("arguments", "string[]").put("_k", "string"))));
         // L3 CPG overlay. `_k` is the MERGE discriminant (internal, underscore-prefixed): J_CFG_NEXT
         // merges per `kind` (a conditional's true/false pair), J_DDG per `(var, prov)`.
         r.add(rel("J_CFG_NEXT", body, body, new P().put("kind", "string").put("_k", "string").done()));