Add introspection JSON ↔ SDL conversion APIs to apollo-compiler

[smyrick]

Summary

Rover is adding support for GraphQL introspection JSON output ({ "__schema": ... }) on graph introspect, matching the legacy apollo schema:download format. Implementing this surfaced conversion logic that feels like it belongs in apollo-compiler rather than in application code.

Consumer: apollographql/rover#3440

Motivation

In graphql-js, the canonical paths are:

• SDL → introspection JSON: introspectionFromSchema(schema)
• introspection JSON → SDL: buildClientSchema(introspectionResult) + printSchema(schema)

apollo-compiler today validates and manipulates SDL and can execute introspection queries against an existing Schema (apollo_compiler::introspection::partial_execute), but does not expose symmetric ingest/emit APIs for the introspection JSON document shape that tools like the legacy Apollo CLI and Rover migrations expect.

Rover currently implements this in rover-client:

• SDL → JSON: wrap partial_execute + serialize to { "__schema": ... }
• JSON → SDL: deserialize introspection response types, encode to apollo-compiler AST, serialize to SDL, then Schema::parse_and_validate

Proposed APIs (sketch)

1. SDL → introspection JSON

A single entry point, e.g.:

// Returns top-level `{ "__schema": { ... } }` (no GraphQL response envelope)
fn introspection_json_from_schema(schema: &Schema) -> Result<Value, ...>;

Matching graphql-js introspectionFromSchema / legacy apollo schema:download output shape.

2. Introspection JSON → Schema (and SDL)

// Accept `{ "__schema": ... }` and optionally `{ "data": { "__schema": ... } }`
fn schema_from_introspection_json(json: &Value) -> Result<Schema, WithErrors>;
// or
fn schema_from_introspection_json(json: &Value) -> Result<Valid<Schema>, WithErrors>;

Then consumers can call existing serialize() for SDL. This is the Rust equivalent of buildClientSchema.

3. (Optional) test / dev helpers

• Order-independent structural comparison of two introspection JSON documents (type names, fields, nested type refs) for regression tests when byte-for-byte equality is too strict.
• Document recommended validation: introspection JSON → Schema → parse_and_validate / validate.

What Rover could remove once this exists

• sdl_to_introspection_json glue in rover-client
• Most of the custom JSON → SDL encoder in schema.rs
• Local test-only structural parity helpers

References

• Rover PR implementing the feature with local workarounds: Add introspection json to graph introspect rover#3440
• apollo_compiler::introspection::partial_execute (SDL → introspection query result today)
• Schema::parse_and_validate (SDL in only today)