GraphQL contract
@lol/search-schema declares fields. The GraphQL API is built from those declarations at boot by buildGraphQLSchema, so the surface consumers use comes out of a generator this repository does not own.
The test suite covers those declarations: their names, paths, roles and derive functions. Nothing in it builds the GraphQL schema, so nothing observes what the generator turns them into. When @lde/search 0.18 added or and and to every Where input, every test passed.
packages/search-schema/schema.graphql is that surface, committed. The graphql-contract job regenerates it on every pull request that could move it, and commits the difference to the branch.
What that gives you
- a diff in Files changed, where a reviewer already looks, rather than a line in a CI log;
- a history of the published API, so “what changed between these releases” is a diff between two tags: the answer to give a presentation-layer developer;
- a
graphql-schema-changelabel, so it is visible in a listing without opening the pull request.
The label answers does this pull request change the API, not was the file out of date: an author who regenerated it themselves leaves nothing to commit, so a real API change would go unlabelled. It diffs the branch’s surface against the base’s, once the branch’s is current.
Nothing to accept and nothing to run: merging the pull request is what adopts the change.
Not a check
It is a maintenance job. By the time it finishes the file always matches, so a comparison could never fail – there is no red mark to chase, and it never blocks a merge. It fails only if it cannot do its work, such as a rejected push.
One consequence: pushing to a Renovate branch marks that pull request as edited, and Renovate then stops keeping it current with main. Merge those rather than letting them sit.
Reading the diff
The diff states the API change: a field or type that disappears, or is renamed, is breaking, and the commit that lands it needs a !.
Regenerate locally with npx nx run @lol/search-schema:sdl; never edit the file by hand. It is generated from module.ts – the file the images mount – and not from the schema export, so it cannot describe a different API from the one served.
The target runs search-print-sdl, the writer @lde/search-api-graphql ships, which loads module.ts through the same loader the indexer and the served API use and forwards its schemaOptions. It writes the file formatted with this repository’s own Prettier configuration, so the pre-commit hook has nothing left to reformat – were the two to disagree, each would undo the other and the job would commit a difference on every run. The formatting also keeps a surface move readable: one field argument per line, so adding an argument is one added line.
Editors
graphql.config.yml points editors at the committed file rather than a running endpoint, so validation works offline. It covers docs/**/*.md, where the guide's ```graphql examples live; without it an editor has no schema to resolve those fields against and reports every one as unknown.
Limits
This reports the API's surface, not its behaviour. A change that alters neither a type nor a field is invisible here by design: adding a locale changes what is indexed and stemmed, but localized text is [LanguageString!]! either way. The guide's examples are executed against a running API, and the indexer-image job boots the proposed LDE indexer against the bundled schema.