Copilot instructions

1---
2applyTo: "**/*.graphql, **/*.graphqls, **/resolvers/**/*.java, **/resolvers/**/*.ts, **/graphql/**/*.java, **/graphql/**/*.ts"
3---
4 
5## Context
6 
7This instruction file applies to GraphQL schema files and resolver implementations. The project follows a **schema-first** design: the `.graphql` / `.graphqls` schema file is the contract; resolver code is generated or implemented to satisfy it. The server uses Spring for GraphQL (Java) or Apollo Server / GraphQL-Yoga (TypeScript). N+1 query prevention via DataLoader is mandatory. Depth and complexity limiting is required in all production environments.
8 
9---
10 
11## Coding Standards
12 
13- **Schema-first:** Define the schema in `.graphql` files before writing any resolver code
14- **Mutation payload types:** Every mutation returns a dedicated payload type with an `errors` field — never return the entity directly
15- **No `input` reuse across mutations:** Each mutation has its own `input` type — never share `CreateOrderInput` between create and update
16- **DataLoader mandatory:** Any resolver that loads a related entity must use a DataLoader — never call a repository in a loop
17- **Cursor-based pagination:** Use Relay-spec `Connection` / `Edge` / `PageInfo` types — never offset-based `skip`/`limit`
18- **Deprecate, never remove:** Mark unused fields `@deprecated(reason: "...")` and keep for one API lifecycle — never delete a field from a live schema
19- **Depth limit:** Maximum query depth of 7 in production; enforced by `graphql-java-extended-scalars` or `graphql-depth-limit`
20- **Complexity limit:** Maximum complexity of 200 per query; each field contributes 1 by default, connections contribute 10
21 
22---
23 
24## Preferred Patterns
25 
26### Schema Design
27 
28```graphql
29# ✅ CORRECT — mutation payload with errors, dedicated input type
30type Mutation {
31  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
32  cancelOrder(input: CancelOrderInput!): CancelOrderPayload!
33}
34 
35input PlaceOrderInput {
36  customerId: ID!
37  items: [OrderLineItemInput!]!
38  currency: Currency!
39}
40 
41type PlaceOrderPayload {
42  order: Order
43  errors: [UserError!]!
44}
45 
46type UserError {
47  message: String!
48  field: [String!]
49  code: String!
50}
51 
52# ✅ CORRECT — Relay cursor pagination
53type OrderConnection {
54  edges: [OrderEdge!]!
55  pageInfo: PageInfo!
56  totalCount: Int!
57}
58 
59type OrderEdge {
60  node: Order!
61  cursor: String!
62}
63 
64type PageInfo {
65  hasNextPage: Boolean!
66  hasPreviousPage: Boolean!
67  startCursor: String
68  endCursor: String
69}
70 
71# ❌ WRONG — mutation returns entity directly, no error handling
72type Mutation {
73  placeOrder(customerId: ID!, items: [OrderLineItemInput!]!): Order
74}
75 
76# ❌ WRONG — offset-based pagination
77type Query {
78  orders(skip: Int, limit: Int): [Order!]!
79}
80```
81 
82### DataLoader (N+1 Prevention)
83 
84```java
85// ✅ CORRECT — Spring for GraphQL DataLoader registration
86@Component
87public class CustomerDataLoader {
88 
89    @Bean
90    public BatchLoaderRegistry batchLoaderRegistry(CustomerRepository repo) {
91        return BatchLoaderRegistry.builder()
92            .forTypePair(String.class, Customer.class)
93            .registerMappedBatchLoader("customerLoader",
94                (customerIds, env) -> Mono.fromCompletionStage(
95                    repo.findAllByIds(customerIds)
96                        .thenApply(customers -> customers.stream()
97                            .collect(Collectors.toMap(c -> c.getId().toString(), c -> c)))
98                ))
99            .build();
100    }
101}
102 
103// ✅ CORRECT — resolver uses DataLoader, not direct repo call
104@SchemaMapping(typeName = "Order", field = "customer")
105public CompletableFuture<Customer> customer(Order order, DataLoader<String, Customer> customerLoader) {
106    return customerLoader.load(order.getCustomerId().toString());
107}
108 
109// ❌ WRONG — N+1: calls repo once per Order
110@SchemaMapping(typeName = "Order", field = "customer")
111public Customer customer(Order order) {
112    return customerRepository.findById(order.getCustomerId()).orElseThrow();
113}
114```
115 
116### TypeScript Resolver (Apollo Server)
117 
118```typescript
119// ✅ CORRECT — resolver with DataLoader, typed context
120import DataLoader from "dataloader";
121 
122const resolvers = {
123  Order: {
124    customer: async (order: Order, _args: never, ctx: Context): Promise<Customer> => {
125      return ctx.loaders.customer.load(order.customerId);
126    },
127  },
128  Mutation: {
129    placeOrder: async (_root: never, { input }: PlaceOrderArgs, ctx: Context): Promise<PlaceOrderPayload> => {
130      try {
131        const order = await ctx.orderService.place(input);
132        return { order, errors: [] };
133      } catch (err) {
134        return { order: null, errors: [{ message: (err as Error).message, code: "ORDER_FAILED", field: null }] };
135      }
136    },
137  },
138};
139```
140 
141---
142 
143## Anti-Patterns — Do NOT Generate
144 
145```graphql
146# WRONG: mutation returns entity directly — no error handling [BLOCKER]
147type Mutation {
148  placeOrder(customerId: ID!, items: [OrderLineItemInput!]!): Order!
149}
150 
151# WRONG: shared input type across mutations [MAJOR]
152input OrderInput {
153  id: ID
154  customerId: ID
155  items: [OrderLineItemInput!]
156}
157 
158# WRONG: offset pagination — inconsistent on fast-moving datasets [MAJOR]
159type Query {
160  orders(skip: Int!, limit: Int!): [Order!]!
161}
162 
163# WRONG: removing a field without deprecation period [MAJOR]
164# (deleted field that was previously in schema)
165 
166# WRONG: field named with implementation details [MINOR]
167type Order {
168  mysqlId: Int!  # exposes storage detail
169}
170```
171 
172```java
173// WRONG: N+1 — repository call inside a per-entity resolver [BLOCKER]
174@SchemaMapping(typeName = "Order", field = "customer")
175public Customer customer(Order order) {
176    return customerRepository.findById(order.getCustomerId()).orElseThrow();
177}
178```
179 
180---
181 
182## Dependencies & Versions
183 
184| Technology | Version | Notes |
185|-----------|---------|-------|
186| Spring for GraphQL | 1.3+ | `@QueryMapping`, `@SchemaMapping`, `@MutationMapping` |
187| graphql-java | 21+ | `BatchLoaderRegistry` for DataLoader integration |
188| graphql-java-extended-scalars | 22+ | `Date`, `DateTime`, `JSON`, depth/complexity limiting |
189| Apollo Server | 4.x | TypeScript; `ApolloServerPlugin` for complexity limits |
190| DataLoader (npm) | 2.x | Batch + cache loader for N+1 prevention |
191| graphql-depth-limit (npm) | 1.x | `depthLimit(7)` validation rule |
192 
193---
194 
195## Test Conventions
196 
197- Test resolvers with `GraphQlTester` (Spring) or `ApolloServer.executeOperation` (TypeScript) — not raw HTTP
198- Test DataLoader batching: assert the repository `findAllByIds` is called once even when 10 orders are resolved
199- Test mutation error paths: verify `errors` field is populated and `order` is null on failure
200- Test pagination: verify `hasNextPage`, `endCursor`, and correct `edges` count for a given `first` value
201- Test depth limiting: submit a deeply nested query (depth > 7) and assert a validation error is returned
202- Test complexity limiting: submit a query exceeding complexity 200 and assert rejection
203