mockql-core 0.0.7

Core library for GenAI-powered GraphQL response mocking via @mock
Documentation

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 PATH and 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: