gudusoft.gsqlparser.ir.semantic.export

Class SemanticIRJsonExporter

Object

gudusoft.gsqlparser.ir.semantic.export.SemanticIRJsonExporter

public final class SemanticIRJsonExporter
extends Object

Deterministic JSON exporter for SemanticProgram. Hand-rolled — no reflection, no map ordering surprises, no third-party dependency — so golden files stay byte-stable across JVMs and refactors.

Format is pretty-printed with two-space indent and a trailing newline. Field order within an object is fixed by the writer methods, not by any map iteration order.

API status: advanced/preview. Supported consumers obtain JSON and its schema discriminator from AnalysisResult. They should branch on the schema version rather than depend on this exporter implementation.

Field Summary

Fields

Modifier and Type	Field and Description
static String	SCHEMA_VERSION Baseline JSON schema version emitted at the top of every exported program when the program contains no structured-data paths.
static String	SCHEMA_VERSION_DEGRADED Schema version emitted when the program contains at least one StatementGraph.KIND_UNANALYZED block — a new kind value plus the unanalyzedReason object, neither of which is part of the frozen v1 / v2 / v3 shapes.
static String	SCHEMA_VERSION_JOIN_ANALYSIS Schema version emitted when any statement carries join-analysis facts (a structured join graph or WHERE filter predicates — slice 172, GAPs 1/2/4).
static String	SCHEMA_VERSION_STRUCTURED Schema version emitted when any reference in the program carries a StructuredColumnPath.

Method Summary

Modifier and Type	Method and Description
static String	schemaVersionFor(SemanticProgram program) Return the schema version selected for program.
static String	toJson(SemanticProgram program)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCHEMA_VERSION

public static final String SCHEMA_VERSION

Baseline JSON schema version emitted at the top of every exported program when the program contains no structured-data paths. Slice 75 froze this at "1"; structured-dataflow support adds "2" which carries optional path fields on ColumnRef and LineageRef. Consumers can branch on the value to handle either shape.

Initialised in a static block (rather than as a literal compile-time constant) so binary consumers compiled against one version of this library don't silently see the old value after a drop-in JAR upgrade. The trade-off is a slightly verbose declaration; the upside is a durable version contract (codex diff-review round-1 Q3).

SCHEMA_VERSION_STRUCTURED

public static final String SCHEMA_VERSION_STRUCTURED

Schema version emitted when any reference in the program carries a StructuredColumnPath. Strictly additive over v1: every v1 field is still present, v2 only adds optional path objects on column / lineage references.

SCHEMA_VERSION_JOIN_ANALYSIS

public static final String SCHEMA_VERSION_JOIN_ANALYSIS

Schema version emitted when any statement carries join-analysis facts (a structured join graph or WHERE filter predicates — slice 172, GAPs 1/2/4). Strictly additive over v1/v2: it only adds an optional joinAnalysis object per statement; every other field is unchanged, so v1/v2 payloads are byte-identical when no statement has joins or filter predicates.

SCHEMA_VERSION_DEGRADED

public static final String SCHEMA_VERSION_DEGRADED

Schema version emitted when the program contains at least one StatementGraph.KIND_UNANALYZED block — a new kind value plus the unanalyzedReason object, neither of which is part of the frozen v1 / v2 / v3 shapes. Version 5 extends the original v4 diagnostic object with category, related locations, and exact vendor enrichment. Selected per-payload, so a program with nothing skipped still exports under its historical version, byte for byte.

Method Detail

schemaVersionFor

public static String schemaVersionFor(SemanticProgram program)

Return the schema version selected for program.

The exporter uses payload-sensitive versions: ordinary programs use v1, structured-column paths use v2, join-analysis facts use v3, and a recovered program containing an unanalyzed block uses v5. This method is the single selector shared by the JSON writer and SqlSemanticAnalyzer, so an AnalysisResult cannot report a version different from its JSON payload.

Parameters:

program - non-null Semantic IR program

Returns:

schema version that toJson(SemanticProgram) will emit

toJson

public static String toJson(SemanticProgram program)