Add mergeAST utility for merging multiple AST documents

[veeceey]

Summary

• Adds a new mergeAST utility function that merges multiple DocumentNodes into a single document by combining their selection sets
• Fields with the same response name (alias or field name) and identical arguments are recursively merged; fields with different arguments are kept separate
• Operations are matched by name and type (query/mutation/subscription); fragment definitions are deduplicated by name
• Variable definitions and directives are also merged with deduplication
• Includes 20 test cases covering: simple merging, deduplication, nested selections, arguments, aliases, named operations, variables, fragments, inline fragments, and the motivating use case from the issue

Closes #1428

Motivation

As discussed in #1428, there are many use cases where dynamically merging GraphQL AST trees is needed, particularly:

• Resolvers that need to ensure additional fields are present in requests forwarded to backend services
• Libraries that compose queries from multiple sources
• React Server Components combining multiple GraphQL queries into a single request

The implementation follows the suggestion from @benjie to migrate/adapt the approach from GraphiQL's merge-ast utility, while providing a simpler, focused API that fits naturally alongside the existing concatAST utility.

API

import { mergeAST } from 'graphql';

const merged = mergeAST([documentA, documentB]);

Test plan

• 20 unit tests covering all merging scenarios
• Existing concatAST tests still pass
• Verify CI passes

[vercel]

Someone is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: veeceey / name: Varun Chawla (866226a, a29673b)

[yaacovCR]

There is some feedback by @benjie on this idea from PR #4359

[veeceey]

Thanks for the pointer @yaacovCR. I went through benjie's feedback on #4359 -- the DOS concern with mergeAST on unvalidated input is a fair point. I'll look into adding depth/complexity guards so it's safer to use on arbitrary documents. If the preference is still to keep this as a separate package first, I'm open to that too. Let me know how you'd like to proceed.

[veeceey]

Went through benjie's feedback on #4359 about the DOS concern -- totally valid point. I've added a depth guard to the recursive merge path:

• New maxDepth option on mergeAST (defaults to 20)
• Depth is tracked through mergeSelectionSets -> mergeFieldNodes / mergeInlineFragments recursion
• Throws a clear error if the limit is hit, with a message suggesting the option if the depth is intentional
• Added tests covering the depth limit for both field merging and inline fragment merging

Default of 20 should be more than enough for any real-world query while still catching adversarial nesting. The option is there if someone has a legitimate deep schema and wants to raise it.

Also exported the MergeASTOptions type from the public API so consumers can use it.