From ce31d8551f2047c14eaccbd4264b2920c4c1a3be Mon Sep 17 00:00:00 2001 From: Rahul Krishna Date: Wed, 2 Sep 2026 13:02:18 -0400 Subject: [PATCH] fix(neo4j): hold the graph contract at the shared 2.0.0 baseline SCHEMA_VERSION on the graph is a shared cross-analyzer number, not this analyzer's own. codeanalyzer-typescript states the rule on its own catalog -- "SCHEMA_VERSION moves only when every analyzer re-baselines together" -- and codeanalyzer-python has stayed at 2.0.0 throughout. This analyzer had drifted off it: 2.1.0 for the L4 SDG overlay, 2.2.0 for the repository-artifact layer, then 3.0.0 when `_module` was removed. The first two were additive over labels that 2.0.0 had already reserved, and the third claimed a MAJOR re-baseline no sibling had agreed to. None was anyone else's to undo, so the number goes back to 2.0.0 and the javadoc now says the rule out loud, so the next change here is recognizable as a cross-repo decision rather than a local one. The uncomfortable half is recorded in the code rather than papered over: removing `_module` IS breaking, and while this number stays put a consumer cannot detect that removal from the version alone. The answer is a coordinated re-baseline across all three analyzers, which is what the epic exists for -- not a unilateral bump here, which is exactly how the drift started. This also stops the graph reporting 3.0.0 while analysis.json reports 2.0.0 for the same analysis, from two fields that share the name `schema_version` and version different things. All three now read 2.0.0. No behaviour change: `_module` is still absent, :JCanNode still present, the prefix-scoped purge untouched. --- schema.neo4j.json | 2 +- .../com/ibm/cldk/neo4j/V2SchemaCatalog.java | 27 ++++++++++++------- .../com/ibm/cldk/CodeAnalyzerV2CliTest.java | 4 +-- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/schema.neo4j.json b/schema.neo4j.json index 6148f9d3..13de0684 100644 --- a/schema.neo4j.json +++ b/schema.neo4j.json @@ -1,5 +1,5 @@ { - "schema_version": "3.0.0", + "schema_version": "2.0.0", "generator": "codeanalyzer-java", "marker_labels": [ "JEntrypoint", diff --git a/src/main/java/com/ibm/cldk/neo4j/V2SchemaCatalog.java b/src/main/java/com/ibm/cldk/neo4j/V2SchemaCatalog.java index c3ace8d3..04d6a1d7 100644 --- a/src/main/java/com/ibm/cldk/neo4j/V2SchemaCatalog.java +++ b/src/main/java/com/ibm/cldk/neo4j/V2SchemaCatalog.java @@ -32,20 +32,29 @@ * are {@code :JBodyNode} rows with {@code kind == "call"}, parameters flatten to * {@code JCallable.parameters_json}, and javadoc collapses to a {@code docstring} property. * - *

{@code SCHEMA_VERSION} bump policy: MAJOR on a breaking change (renamed/removed label, - * relationship or key), MINOR on an additive one. Stamped onto {@code :JApplication} so consumers - * detect producer/consumer mismatch at runtime. + *

{@code SCHEMA_VERSION} is the SHARED graph contract version, not this analyzer's own. It moves + * only when every analyzer re-baselines together — codeanalyzer-typescript states the same rule on + * its own catalog — so a change here is a cross-repo decision, not a local one. Stamped onto + * {@code :JApplication} so consumers detect producer/consumer mismatch at runtime. + * + *

Bump policy once such a re-baseline happens: MAJOR on a breaking change (renamed/removed + * label, relationship or key), MINOR on an additive one. */ public final class V2SchemaCatalog { private V2SchemaCatalog() {} - // 2.1.0: additive MINOR — L4 SDG overlay (JBodyNode.var/call_node; J_PARAM_IN/J_PARAM_OUT/ - // J_SUMMARY, reserved at 2.0.0, now actually emitted). - // 2.2.0: additive MINOR — the repository-artifact layer (#197): Artifact/Package/ConfigKey - // reserved at 2.0.0, now actually emitted, plus HAS_ARTIFACT/DEFINES_CONFIG/ - // DECLARES_DEPENDENCY/LOCKS. - public static final String SCHEMA_VERSION = "3.0.0"; + // Held at the shared 2.0.0 baseline. This analyzer previously moved it alone — 2.1.0 for the L4 + // SDG overlay, 2.2.0 for the repository-artifact layer, then 3.0.0 when `_module` was removed — + // while codeanalyzer-python stayed at 2.0.0. Both of those layers were additive over labels + // 2.0.0 already reserved, and none of them was a re-baseline anyone else agreed to, so the + // drift was this analyzer's alone to undo. + // + // Consequence, recorded rather than papered over: removing `_module` IS breaking, and while this + // number stays put a consumer cannot detect that removal from the version alone. The fix is a + // coordinated re-baseline across all three analyzers, not a unilateral bump here — see + // codellm-devkit/.github#50. + public static final String SCHEMA_VERSION = "2.0.0"; /** Labels layered onto a node in addition to its merge + specific labels. */ /** diff --git a/src/test/java/com/ibm/cldk/CodeAnalyzerV2CliTest.java b/src/test/java/com/ibm/cldk/CodeAnalyzerV2CliTest.java index 5321bae9..007333eb 100644 --- a/src/test/java/com/ibm/cldk/CodeAnalyzerV2CliTest.java +++ b/src/test/java/com/ibm/cldk/CodeAnalyzerV2CliTest.java @@ -184,10 +184,10 @@ void emitSchemaAlwaysEmitsTheV2Catalog(@TempDir Path tmp) throws IOException { assertEquals(0, run("--emit", "schema", "-o", out.toString())); JsonObject doc = JsonParser.parseString(Files.readString(out.resolve("schema.neo4j.json"))) .getAsJsonObject(); - assertEquals("3.0.0", doc.get("schema_version").getAsString()); + assertEquals("2.0.0", doc.get("schema_version").getAsString()); assertEquals(0, run("--emit", "schema", "-o", out.toString(), "--schema", "v1"), "--emit schema ignores --schema"); - assertEquals("3.0.0", JsonParser.parseString(Files.readString(out.resolve("schema.neo4j.json"))) + assertEquals("2.0.0", JsonParser.parseString(Files.readString(out.resolve("schema.neo4j.json"))) .getAsJsonObject().get("schema_version").getAsString()); }