[GH-ISSUE #8702] [Feature] Reconstruct GraphQL schemas and operation contracts from retained artifacts #7517

New issue

Open

opened 2026-11-03 00:30:29 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 00:30:29 +00:00

Owner

Originally created by @jayykernel on GitHub (Nov 2, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/8702

Problem

A GraphQL client/server surface is more than a list of HTTP endpoints. The schema defines object and input types, fields, arguments, enums, interfaces, unions and directives; client operations select only parts of that contract. Existing endpoint discovery can identify GraphQL request destinations, but does not provide a structured, provenance-aware schema model for understanding the API surface or comparing versions.

Proposed outcome

Add an offline GraphQL schema and operation analyzer that accepts caller-selected SDL files, introspection JSON responses, and retained client operation documents.

Parse schema definitions and extensions into a normalized type graph, preserving descriptions, deprecations, directives, defaults and source locations when available.
Parse query, mutation and subscription documents; resolve referenced fields, arguments, variables, fragments and operation names against the supplied schema.
Report unresolved types/fields, validation failures and incomplete schema coverage explicitly rather than guessing missing definitions.
Compare two supplied schemas and report added, removed and changed types, fields, arguments, enum values and nullability.
Link client operations to schema fields with source/artifact provenance; keep observed operations distinct from schema-derived possibilities.
Support bounded inputs and deterministic output through CLI and MCP.

Safety and scope

Operate only on caller-supplied local artifacts or already-retained Evidence. Do not contact GraphQL endpoints, run introspection queries, replay operations, submit mutations or infer authorization/accessibility from schema visibility. Treat introspection data as an incomplete view unless completeness is established by its provenance.

Acceptance criteria

Owned fixtures cover SDL, introspection JSON, schema extensions, fragments, aliases, directives, custom scalars and invalid operations.
Schema diff correctly distinguishes nullable/non-null changes, list wrappers, argument defaults and enum changes.
Partial introspection and missing referenced types produce explicit coverage diagnostics.
CLI/MCP workflows preserve input digest, provenance and source locations where available.
Documentation explains offline-only inputs, introspection completeness and unsupported federation features.

Scope

A focused schema-analysis capability complementary to endpoint/API-surface work (#3591) and the website reverse-engineering roadmap (#774). Federation composition, live introspection and authorization testing are intentionally out of scope.

Originally created by @jayykernel on GitHub (Nov 2, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/8702 ## Problem A GraphQL client/server surface is more than a list of HTTP endpoints. The schema defines object and input types, fields, arguments, enums, interfaces, unions and directives; client operations select only parts of that contract. Existing endpoint discovery can identify GraphQL request destinations, but does not provide a structured, provenance-aware schema model for understanding the API surface or comparing versions. ## Proposed outcome Add an offline GraphQL schema and operation analyzer that accepts caller-selected SDL files, introspection JSON responses, and retained client operation documents. - Parse schema definitions and extensions into a normalized type graph, preserving descriptions, deprecations, directives, defaults and source locations when available. - Parse query, mutation and subscription documents; resolve referenced fields, arguments, variables, fragments and operation names against the supplied schema. - Report unresolved types/fields, validation failures and incomplete schema coverage explicitly rather than guessing missing definitions. - Compare two supplied schemas and report added, removed and changed types, fields, arguments, enum values and nullability. - Link client operations to schema fields with source/artifact provenance; keep observed operations distinct from schema-derived possibilities. - Support bounded inputs and deterministic output through CLI and MCP. ## Safety and scope Operate only on caller-supplied local artifacts or already-retained Evidence. Do not contact GraphQL endpoints, run introspection queries, replay operations, submit mutations or infer authorization/accessibility from schema visibility. Treat introspection data as an incomplete view unless completeness is established by its provenance. ## Acceptance criteria - [ ] Owned fixtures cover SDL, introspection JSON, schema extensions, fragments, aliases, directives, custom scalars and invalid operations. - [ ] Schema diff correctly distinguishes nullable/non-null changes, list wrappers, argument defaults and enum changes. - [ ] Partial introspection and missing referenced types produce explicit coverage diagnostics. - [ ] CLI/MCP workflows preserve input digest, provenance and source locations where available. - [ ] Documentation explains offline-only inputs, introspection completeness and unsupported federation features. ## Scope A focused schema-analysis capability complementary to endpoint/API-surface work (#3591) and the website reverse-engineering roadmap (#774). Federation composition, live introspection and authorization testing are intentionally out of scope.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7517

No description provided.

Rows
Columns