mockql-core
The library behind the mockql binary. It takes a GraphQL operation that may carry
@mock directives, decides what to fetch for real and what to hallucinate, asks an
LLM provider for the mocked parts, and stitches everything back into one GraphQL
response.
If you're new here, this is the layer that does all the actual work — the
mockql-cli crate is just an entry point that wires up arguments and
calls into this crate.
The request lifecycle
Every request flows through the same four stages (the same ones described in the top-level README's How it works):
parse → split (plan) → prompt → merge
MockService (service.rs) is the front door. Give it a validated schema and an HTTP
client, then call execute(MockServiceRequest). Internally it delegates planning to
the MockPlanner (planner.rs) and then acts on the resulting plan.
Glossary
The vocabulary used throughout the codebase:
| Term | What it means |
|---|---|
@mock directive |
The annotation users put on operations/fields to request generated data |
| Scenario | The shape of the request after extraction: NoMocks, Introspection, OperationMocked, AllTopLevelFieldsMocked, PartialMocked |
| Split / Plan | Deciding how to satisfy a request — the bridge from "scenario" to an executable strategy |
| Passthrough / Upstream | Real fields forwarded to the actual GraphQL server |
| Mocked fields | Fields tagged @mock, separated out to be generated |
| Prompt | The structured ask sent to a provider: operation + mocked fields + hints + minimized schema |
| Provider | The LLM backend that generates mock data (CLI or HTTP) |
| Merge | Stitching upstream data and generated mock data into one response |
| Schema filter / Minify | Trimming the schema down to just what the operation touches, then compressing it for the prompt |
| Schema extension | Caller-supplied SDL applied before planning, so you can @mock fields that don't exist upstream yet |
| Serialization format | How generated data is asked for and parsed — JSON or TOON |
The plan is the pivot
MockPlan is the single most important type to understand — it's the decision that
determines everything downstream. MockService::execute is essentially a match over it:
NoMocks→ forward the operation upstream untouched.Introspection→ answer from the local schema, no network, no provider.FullMock→ the whole operation is generated by the provider; no upstream call.PartialMock→ execute the passthrough operation upstream, feed that real data into the prompt as context, generate the mocked fields, then merge.
The planner produces a SplitResult; service.rs converts it 1:1 into a MockPlan.
They're kept as separate types so planning stays free of execution concerns.
Providers
A provider is anything that can turn a prompt into a response. Two families ship in-tree:
- CLI providers shell out to a tool already on your
PATHand authenticated:claude,codex,opencode. - HTTP providers call an API with a credential from the environment:
github-copilot,gemini.
Further reading
The deep documentation lives outside this README so it isn't duplicated: