feat: add CoreEx.Data.GraphQL (GraphQL-lite) query bridge

[chullybun]

Summary

Adds CoreEx.Data.GraphQL — a transport-agnostic bridge that lets a native GraphQL query drive an entity's existing QueryArgsConfig-based QueryAsync/GetAsync pipeline, with no parallel query engine and no new authorization surface. GraphQL where/orderBy syntax is rewritten 1:1 onto the OData-esque QueryArgs/PagingArgs strings already understood by QueryFilterParser/QueryOrderByParser, so field/operator legality continues to be enforced by the same battle-tested parser used by REST $query.

Key capabilities

• Native GraphQL where/orderBy translated syntactically to the OData-esque equivalent, then parsed by the existing, unmodified QueryFilterParser/QueryOrderByParser — exact operator/field parity with $query, including whatever QueryArgsConfig exposes (startswith(), ge, etc.).
• Relay Cursor Connections paging (edges, pageInfo, totalCount) bridged onto PagingArgs, including a totalCount-only fast path that avoids over-fetching rows.
• Field-selection projection via JsonFilter, honoring aliases and __typename at every depth; fragments are rejected loudly rather than silently ignored. The resolved selection is also fed into QueryArgs.IncludeFields for list roots, so the underlying QueryArgsConfig-driven data layer can project only what was actually selected.
• includeText/includeInactive ref-data options, supported (and schema-advertised) on both list (AddQuery) and single-item (AddGet) roots — an item-root product(id: "...", includeText: true) { category categoryText } works the same way a list root does.
• Spec-compliant introspection: __schema/__type(name:)/__typename are real and built once from the registered roots. Each query root's where/orderBy are described as fully-typed <Item>WhereInput/<Item>OrderByInput INPUT_OBJECT graphs (derived automatically from QueryArgsConfig.ToJsonSchema()), so schema-aware tooling (Postman, Nitro, Apollo Sandbox, GraphiQL) gets full autocomplete with no extra configuration.
• Injection-safe: string operands are quote-escaped, and field names originate from the GraphQL Name grammar, so the constructed OData string can't be broken out of.
• GraphQL-shaped error mapping: ArgumentException, KeyNotFoundException, GraphQLArgumentTranslationException, QueryFilterParserException, QueryOrderByParserException, ValidationException, NotFoundException, and unknown-field/unknown-root errors all map to distinct { message, path, extensions.code } shapes instead of a generic, unhelpful EXECUTION_ERROR.
• Endpoint customization hook: MapCoreExGraphQLLite accepts an optional configure callback for further endpoint customisation (auth, rate limiting, etc.), and tags the endpoint for discoverability.
• Layering: transport-agnostic contract (IGraphQLEngine, GraphQLEngineResult, GraphQLEngineError) lives in core CoreEx; the implementation lives in CoreEx.Data.GraphQL; the minimal-API HTTP bridge (MapCoreExGraphQLLite) lives in CoreEx.AspNetCore. Dependencies point the right way.

Hardening found via iterative review

Across several rounds of independent/automated review, the following were found and fixed with regression tests: culture-sensitive float literal parsing; unprojected object-typed leaf fields silently returning the whole DTO; undefined GraphQL variable references silently resolving to null; silent long→int overflow in argument conversion; last-wins duplicate response-key aliases; totalCount-only over-fetching; a type-shape cache key that ignored JsonSerializerOptions; OperationCanceledException being swallowed into a field error instead of propagating; reserved/duplicate root-name registration; malformed numeric literal handling; a hasNextPage edge case; and the final response JSON silently falling back to default (rather than the configured) JsonSerializerOptions.

While hardening this feature, a genuine pre-existing, unrelated CoreEx.Json.JsonFilter bug was also found and fixed: sibling scalar fields where one name is a raw string prefix of another (e.g. the common ref-data category/categoryText Code/Text pair) were incorrectly treated as a nested-path relationship and the shorter field silently dropped from Include-filtered output — this affected REST $fields projection too, not just GraphQL-lite.

Docs

• New src/CoreEx.Data.GraphQL/README.md and AGENTS.md, kept current with every capability above (introspection, includeText on item roots, etc.).
• docs/capabilities.md, samples/docs/hosts-layer.md, samples/docs/patterns.md, .github/instructions/coreex-host-setup.instructions.md, .github/instructions/coreex-api-controllers.instructions.md, and .github/agents/coreex-expert.agent.md updated with the registration API and the CoreEx.ExecutionContext.GetRequiredService<T>() scoped-resolution pattern.
• .github/instructions/coreex-repositories.instructions.md codifies the QueryArgsConfig visibility exception and folder-placement convention established while building this feature.

Testing

• 118/118 CoreEx.Data.GraphQL.Test.Unit tests passing across net8/9/10.
• 7/7 sample Contoso.Products.Test.Api GraphQLLite_* integration tests passing across net8/9/10, including a spec-compliant introspection test driven by a standard client-tooling introspection query (embedded resource).
• 705/705 CoreEx.Test.Unit passing across net8/9/10 (includes the JsonFilter regression coverage above).
• Full CoreEx.sln build clean (0 warnings, 0 errors).

[Copilot]

Pull request overview

This PR introduces CoreEx.Data.GraphQL, a transport-agnostic “GraphQL-lite” query bridge that translates GraphQL where/orderBy and Relay-style paging onto the existing QueryArgsConfig + QueryArgs/PagingArgs pipeline, plus a minimal-API hosting bridge in CoreEx.AspNetCore and sample usage/tests/docs.

Changes:

• Add new CoreEx.Data.GraphQL package (engine, translators, selection/projection, schema discovery) and new CoreEx-level contracts/result envelope types.
• Add ASP.NET Core minimal-API bridge (MapCoreExGraphQLLite) and wire it into the Contoso Products sample with matching integration tests.
• Update solution/test filters, dependency versions, and documentation/instructions to reflect the new capability and registration pattern.

Reviewed changes

Copilot reviewed 54 out of 54 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/CoreEx.Data.GraphQL.Test.Unit/Model/PersonQueryArgsConfig.cs	Minimal QueryArgsConfig used by unit tests to exercise end-to-end translation/parsing.
tests/CoreEx.Data.GraphQL.Test.Unit/Model/Person.cs	Test DTO shape for nested selection/projection tests.
tests/CoreEx.Data.GraphQL.Test.Unit/Internal/GraphQLValueConverterTests.cs	Unit coverage for argument conversion (literals, variables, culture, overflow).
tests/CoreEx.Data.GraphQL.Test.Unit/Internal/GraphQLOrderByTranslatorTests.cs	Unit coverage for orderBy translation and validation errors.
tests/CoreEx.Data.GraphQL.Test.Unit/Internal/GraphQLFilterTranslatorTests.cs	Unit coverage for where translation and operand escaping/validation errors.
tests/CoreEx.Data.GraphQL.Test.Unit/Internal/GraphQLCursorTests.cs	Unit coverage for cursor encoding/decoding behavior.
tests/CoreEx.Data.GraphQL.Test.Unit/Internal/GraphQLArgsMapperTests.cs	Unit coverage for mapping GraphQL args to QueryArgs/PagingArgs (incl. count-only path).
tests/CoreEx.Data.GraphQL.Test.Unit/GraphQLEngineTests.cs	End-to-end engine tests (projection, paging, schema, errors, cancellation).
tests/CoreEx.Data.GraphQL.Test.Unit/CoreEx.Data.GraphQL.Test.Unit.csproj	New multi-targeted unit test project for GraphQL-lite engine.
src/CoreEx/Data/GraphQL/IGraphQLEngine.cs	New transport-agnostic engine contract in CoreEx.
src/CoreEx/Data/GraphQL/GraphQLEngineResult.cs	CoreEx-level result envelope for GraphQL-over-HTTP-style responses.
src/CoreEx/Data/GraphQL/GraphQLEngineError.cs	CoreEx-level error envelope (message/path/extensions).
src/CoreEx.Data.GraphQL/README.md	Package documentation (capabilities, usage, non-goals).
src/CoreEx.Data.GraphQL/Internal/GraphQLValueConverter.cs	AST + variables → CLR argument conversion and typed accessors.
src/CoreEx.Data.GraphQL/Internal/GraphQLTypeShape.cs	Reflected DTO field shape caching keyed by serializer options.
src/CoreEx.Data.GraphQL/Internal/GraphQLSelectionResolver.cs	Selection-set validation + JsonFilter include-path flattening.
src/CoreEx.Data.GraphQL/Internal/GraphQLSchemaBuilder.cs	Discovery document builder composing QueryArgsConfig schema + DTO field shape.
src/CoreEx.Data.GraphQL/Internal/GraphQLResponseShaper.cs	Alias-aware reshaping plus __typename injection post-JsonFilter.
src/CoreEx.Data.GraphQL/Internal/GraphQLOrderByTranslator.cs	GraphQL orderBy list-of-objects → OData-esque order-by string.
src/CoreEx.Data.GraphQL/Internal/GraphQLFilterTranslator.cs	GraphQL where input object → OData-esque filter string.
src/CoreEx.Data.GraphQL/Internal/GraphQLCursor.cs	Offset-based cursor codec for Relay forward pagination.
src/CoreEx.Data.GraphQL/Internal/GraphQLConnectionResolver.cs	Validates/records fixed Connection/Edge/PageInfo selection shapes.
src/CoreEx.Data.GraphQL/Internal/GraphQLArgumentTranslationException.cs	Dedicated exception type for GraphQL arg-shape translation failures.
src/CoreEx.Data.GraphQL/Internal/GraphQLArgsMapper.cs	Maps resolved args into QueryArgs + paging semantics (incl. count-only optimization).
src/CoreEx.Data.GraphQL/GraphQLServiceCollectionExtensions.cs	DI registration extension for singleton IGraphQLEngine.
src/CoreEx.Data.GraphQL/GraphQLQueryRoot.cs	Query-root descriptor binding root name + config + resolver.
src/CoreEx.Data.GraphQL/GraphQLLiteOptions.cs	Options container for explicit root registration (AddQuery/AddGet).
src/CoreEx.Data.GraphQL/GraphQLItemRoot.cs	Single-item root descriptor binding root name + resolver.
src/CoreEx.Data.GraphQL/GraphQLEngine.cs	Concrete engine implementation (parse, execute roots, apply projection, map errors).
src/CoreEx.Data.GraphQL/GlobalUsing.cs	Global usings for the new package.
src/CoreEx.Data.GraphQL/CoreEx.Data.GraphQL.csproj	New package project definition and dependencies.
src/CoreEx.Data.GraphQL/AGENTS.md	AI usage guide for the new package (registration and do-not rules).
src/CoreEx.AspNetCore/GlobalUsing.cs	Adds global using for GraphQL-lite engine contract types.
src/CoreEx.AspNetCore/CoreExAspNetCoreExtensions.GraphQLLite.cs	Minimal-API bridge endpoint mapping GraphQL-over-HTTP envelope to IGraphQLEngine.
samples/tests/Contoso.Products.Test.Api/ReadTests.ProductGraphQLLite.cs	Sample integration tests proving parity with REST query behavior.
samples/src/Contoso.Products.Infrastructure/Repositories/ProductQueryArgsConfig.cs	Makes config public for host-level GraphQL-lite root registration.
samples/src/Contoso.Products.Api/Program.cs	Registers engine roots and maps /api/products/query endpoint.
samples/src/Contoso.Products.Api/GlobalUsing.cs	Adds global usings for GraphQL-lite registration and config access.
samples/src/Contoso.Products.Api/Contoso.Products.Api.csproj	Adds project reference to CoreEx.Data.GraphQL.
samples/docs/patterns.md	Documents GraphQL-lite query bridge as an API pattern.
samples/docs/hosts-layer.md	Documents host wiring and usage constraints for the /query bridge.
README.md	Adds the new package to the repo/package catalog.
docs/capabilities.md	Adds “GraphQL-lite Query Bridge” capability documentation.
Directory.Packages.props	Adds GraphQL-Parser dependency version.
CoreEx.slnx	Adds new project + tests to solution index.
CoreEx.sln	Adds new projects to the Visual Studio solution.
CoreEx.Core.Test.Parallel.slnf	Includes new unit test project in the parallel test filter.
CoreEx.Core.slnf	Includes new project + tests in core solution filter.
AGENTS.md	Updates agent entry-point doc to include new data/query packages.
.github/instructions/coreex-repositories.instructions.md	Documents QueryArgsConfig visibility exception for GraphQL-lite host registration.
.github/instructions/coreex-host-setup.instructions.md	Documents GraphQL-lite registration and mapping APIs for hosts.
.github/instructions/coreex-conventions.instructions.md	Updates documentation conventions guidance (incl. private methods, test exceptions).
.github/instructions/coreex-api-controllers.instructions.md	Notes optional GraphQL-lite surface alongside REST query endpoints.
.github/agents/coreex-expert.agent.md	Adds new package guide link for the expert agent references.

Comments suppressed due to low confidence (1)

src/CoreEx.Data.GraphQL/Internal/GraphQLValueConverter.cs:94

• GetBool returns null for unsupported types, which can silently ignore invalid inputs (especially via variables) rather than returning an ARGUMENT_ERROR. Consider throwing GraphQLArgumentTranslationException for any non-null, non-boolean value.

[Copilot]

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

src/CoreEx/Data/GraphQL/GraphQLEngineResult.cs:36

• GraphQLEngineResult.Failure is declared as params IEnumerable<GraphQLEngineError> but call sites pass a single GraphQLEngineError (e.g. Failure(NewError(...))), which won’t compile. Use params GraphQLEngineError[] (or a non-params IEnumerable<...> parameter) so the call sites are valid.
  src/CoreEx.Data.GraphQL/GraphQLEngine.cs:138
• When edges/node are aliased (supported by GraphQLConnectionResolver), the error Path currently uses the literal field names ("edges", "node") rather than the response keys (aliases). This makes errors point at the wrong JSON path for clients using aliases; use the resolved aliases in the errorPath passed to GraphQLSelectionResolver.Resolve.
  src/CoreEx.Data.GraphQL/Internal/GraphQLValueConverter.cs:79
• GetInt returns null for unsupported value types, which can silently turn an invalid argument (e.g. first: "abc" or a wrong-typed variable) into “not specified”, falling back to defaults or even a NOT_FOUND. For GraphQL arguments this should be an ARGUMENT_ERROR so callers get deterministic feedback.

[Copilot]

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

src/CoreEx/Data/GraphQL/GraphQLEngineResult.cs:36

• GraphQLEngineResult.Failure is declared as params IEnumerable<GraphQLEngineError> but all call sites pass a single GraphQLEngineError (e.g. GraphQLEngine.ExecuteAsync), which will not compile. The params type should be GraphQLEngineError[] (or accept a single IEnumerable<GraphQLEngineError> without params).
  src/CoreEx.Data.GraphQL/README.md:70
• The Key types table says IGraphQLEngine, GraphQLEngineResult, and GraphQLEngineError are in the CoreEx.Data namespace, but the types added in this PR are in CoreEx.Data.GraphQL. This should be corrected so consumers can locate the API quickly.

[Copilot]

Pull request overview

Copilot reviewed 62 out of 62 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

src/CoreEx/Data/GraphQL/GraphQLEngineResult.cs:36

• GraphQLEngineResult.Failure currently takes params IEnumerable<GraphQLEngineError> which makes call sites like GraphQLEngineResult.Failure(NewError(...)) a compile error (a single GraphQLEngineError is not an IEnumerable<GraphQLEngineError>). Change this overload to accept params GraphQLEngineError[] (or a single IEnumerable<GraphQLEngineError> without params).
  src/CoreEx.Data.GraphQL/README.md:20
• README describes the IGraphQLEngine contract as being in the CoreEx.Data namespace, but the actual contract is CoreEx.Data.GraphQL (in the CoreEx project). This is likely to mislead consumers and should be corrected.
  src/CoreEx.Data.GraphQL/README.md:65
• The Key types table lists the wrong AddCoreExGraphQLLite signature; the extension takes Action<GraphQLLiteOptions, IServiceProvider> (as shown in the usage snippet), not Action<GraphQLLiteOptions>.
  src/CoreEx.Data.GraphQL/README.md:70
• The Key types table says IGraphQLEngine / GraphQLEngineResult / GraphQLEngineError are in the CoreEx.Data namespace, but they are defined in CoreEx.Data.GraphQL. Aligning this avoids confusion when searching/importing types.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/CoreEx.Data.GraphQL/Internal/GraphQLOrderByTranslator.cs:37

• orderBy list items are documented as "each object should specify a single field" because input-object field order is not spec-guaranteed; however the current implementation allows multi-key objects and relies on dictionary enumeration order, which can produce nondeterministic precedence. Consider rejecting multi-key objects with a clear translation error so precedence is always well-defined.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 75 out of 75 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/CoreEx.Data.GraphQL/Internal/GraphQLOrderByTranslator.cs:37

• orderBy items are documented as “each object should specify a single field” because GraphQL input-object field order is not spec-guaranteed, but the implementation currently accepts multi-key objects and will translate them in whatever enumeration order the dictionary yields. This makes sort precedence ambiguous/non-portable for orderBy: [{ a: ASC, b: DESC }]. Consider rejecting multi-key objects with an ARGUMENT_ERROR so precedence is always expressed via list order ([{a: ASC}, {b: DESC}]).

[Copilot]

Pull request overview

Copilot reviewed 77 out of 77 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/CoreEx.Data.GraphQL/GraphQLLiteArgs.cs:34

• GetIdentifier<TId> documentation says it "converts"/is "convertible", but the implementation only accepts values that are already of type TId (e.g., a numeric ID supplied as a string via variables would be rejected). This is both misleading for consumers and unnecessarily strict for the GraphQL ID scalar (commonly string-or-int). Consider adding common coercions (string↔numeric, string→Guid, etc.) or, at minimum, rewording the docs to match the current behavior.
  src/CoreEx.AspNetCore/CoreExAspNetCoreExtensions.GraphQLLite.cs:45
• Typo in comment: "Self -deserializing" should be hyphenated as "Self-deserializing".

            // Self -deserializing the request body to the standard GraphQL-over-HTTP request envelope and self-handling any deserialization errors to return a GraphQL-lite error response.