AGENTS.md · graphile/crystal

Sections

1. Repository Overview
2. Guardrails
3. Always Allowed
4. Preferred Style
5. Testing Rules
6. Error pages
7. Glossary
8. Out of date terminology and concepts

First lines (shown under the repo's MIT license)

<!-- prettier-ignore -->
# AGENTS.md

**Audience:** code assistants (Aider, Claude, Codex, Cody, Copilot, etc.)
working on this repository.

## Repository Overview

This is a monorepo with a large number of interdependencies. The repo is split
into 4 main categories based on the root folders, each of which have a
`<category>/website` project for their own website:

- `utils` - lots of helper projects that we use to build the main projects.
  Website: https://star.graphile.org ("star" as in "asterisk" as in "everything
  else")
  - `pg-sql2` - safe (and extremely fast) SQL template strings
  - `graphile-config` - standard utils around creating plugins and presets, used
    throughout Graphile projects.
  - `graphile-export` - can export an in-memory GraphQL schema (with
    resolvers/plans) as an executable JS file - particularly useful for
    serverless.
  - `pg-introspection` - exposes the PostgreSQL system catalog via TypeScript
    interfaces with documentation pulled from postgres.
- `grafast` - a new cutting-edge planning and execution engine for GraphQL. Uses
  GraphQL.js for schema elements (`new GraphQLObjectType`, etc) but completely
  replaces execution and output logic. Website: https://grafast.org
  - `grafserv` - a Grafast-optimized server
  - `@grafserv/persisted` - a plugin for Grafserv for persisted operations /
    trusted documents.
  - `ruru` - a Grafast-optimized GraphiQL distribution
  - `@dataplan/pg` - a collection of Grafast "step classes" for dealing with
    PostgreSQL databases
- `graphile-build` - the Graphile Build project produces a GraphQL schema via a
  set of plugins. Website: https://build.graphile.org
  - `graphile-build-pg` - teaches Graphile Build how to add schema elements from
    PostgreSQL resources (tables, functions)
  - `@graphile/simplify-inflection` - a highly recommended plugin that uses
    simpler names in GraphQL (but increases the chance of collisions, hence not
    included in the default experience)
  - `graphile-utils` - the "bread and butter" plugin factories that help people
    do common manipulations of a PostGraphile schema with minimal effort
- `postgraphile` - autogenerated and highly extensible/customizeable GraphQL API
  server/schema generator built using Graphile Build and executed via Grafast.
  Website: https://postgraphile.org
  - `pgl` - a shortcut to the `postgraphile` binary that also takes care of
    installing all the peerDependencies for you (for compatibility with `npx`

## Guardrails

1. **Never edit versioned docs:** files under `*/website/versioned_docs/**` are
   snapshots taken at release time. Edit the source (unversioned) doc instead.
1. **Keep scope tight.**
   - Prefer many small PRs over one large PR.
   - Avoid large refactors without an issue/plan.
   - Avoid stylistic rewrites without functional gain.
   - Avoid moving/renaming files/pages unless essential.
   - Avoid changing lockfiles or versions unless essential.
1. **Edit in stages** when performing larger edits; for example: when
   refactoring, reorder the code first (without changes), commit, then edit the
   functionality. Many commits are preferred as it allows stepping through the
   work completed in logical chunks.

## Always Allowed

- Read files and make changes to markdown, TypeScript, and `*.test.*` files.
- Write tests; update fixtures and test helpers.
- Improve and update documentation (typically under the `<category>/website`
  folder). Be concise, clear, and accurate. Reflect nuances via admonitions
  where appropriate. Only make essential changes, avoid stylistic changes.
- Spot mistakes in the docs where they do not correctly reflect the code.
- Add or adjust comments, JSDoc/TSDoc, README snippets.
- Fix typos in prose.

## Preferred Style

- Never use `<https://...>`-style links, always use `[text](https://...)`.
- Links do not end in a slash
- Follow current formatting/lint rules; **do not** add style-only churn.
- Do not trim file suffixes from links (e.g. `.md`/`.mdx`) - we use Docusaurus
  to resolve these.
- Keep code samples runnable in principle; **do not** add scripts to run them.
- Wrap prose at 80 characters.
- Always use `Gra*fast*` in Markdown when referring to Gra*fast* - the "fast" is
  stylized in italics. When in MDX use the `<Grafast />` component if available,
  otherwise `Gra*fast*` is fine.
- When discussing steps, say a step **represents** a value at plan-time and
  **yields** values at execution-time. Avoid "evaluates"/"resolves" unless
  quoting legacy APIs.
- Keep Grafast documentation backend-agnostic: do not reference
  PostGraphile-specific helpers (e.g. `@dataplan/pg`) unless the page is
  explicitly about that integration.
- When adding `:::` admonitions, be sure to have a blank line both above and
  below each `:::` line.
- The documentation uses UK English, but the code uses US English. If a spelling
  is valid in both US and UK English, prefer that shared form (e.g. `centralize`
  rather than the UK-only `centralise`, `optimize` rather than `optimise`). Use
  UK spellings such as `behaviour` in prose, but match US spellings in code
  identifiers and when quoting API names (e.g. `BehaviorPlugin`).
- SQL statements should be lowercase throughout the code and documentation,
  however when keywords such as `SELECT` and `DELETE` are presented alone in
  prose they should be upper-cased for clarity.
- Headings in the sidebar and inline in prose are in Sentence case
- Modal verbs: avoid unnecessary language which suggests some is tentative or
  unlikely (eg "may", "might"). Graphile follows RFC 2119 for the use of modal
  verbs.

When writing Grafast plan resolvers in documentation, try and only do one action
per statement; for example instead of:

```ts
const $invoices = loadMany($customer.get("stripeId"), invoicesByStripId);
```

prefer:

```ts
const $stripeId = $customer.get("stripeId");
const $invoices = loadMany($stripeId, invoicesByStripId);
```

This does not apply to literal object or array values passed as the first
argument to `lambda()`, `sideEffect()`, `loadOne()` or `loadMany()` since these
are "multistep" objects provided for user convenience. Similarly `list()` should
always be called as `list([ ... ])` and `object()` as `object({ ... })` without
separate definition of the argument.

When representing the GraphQL context as a step, `const $context = context();`
should always be used since it's always the same GraphQL context object being
represented (even if the contents are mutated).

Exception to the above: `const $foo = context().get("foo");` is fine, and
preferred over the two statement equivalent.

When writing plan resolvers against PostgreSQL resources, prefer the resource
and step helpers before constructing low-level plans by hand. For example, use
argument destructuring such as `(_$root, { $name })`, `users.find()`,
`$users.where(...)`, and `$users.placeholder($name, TYPES.text)` where they fit,
rather than building a custom `pgSelect({ identifiers, args, from })` wrapper.
Reach for low-level constructors only when the resource/step APIs do not express
the query shape.

## Testing Rules

- Prefer **incremental** tests: cover public APIs and critical paths first.
- Use existing test utilities and patterns; mirror nearby tests.
- Keep tests deterministic.

Note: many of the integration tests work by writing `*.test.graphql` files,
which the system will run and capture snapshots of data, plans, errors and
executed SQL. Do not generate these snapshot files, only the `.test.graphql`
files are needed.

Further note: the test suite uses a lot of different schema configurations (see
the `#>` comments at the top of `*.test.graphql` files), so it may be hard to
determine which fields are available. Look for a test in the `schemas` folder
that has a similar configuration, its snapshot can be a guide, or ask.

## Error pages

Graphile owns the domain `err.red` (to be read as "errored"), and automatically