mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-18 02:24:27 +02:00
a3e1b27a63
HTTP server:
- Add POST /mutate as canonical write endpoint (pairs with POST /query).
- Mark POST /read and POST /change as deprecated. Three-channel signal:
* OpenAPI: `deprecated: true` on the operation (every codegen flags
the generated SDK method).
* RFC 9745: response `Deprecation: true` header on every response.
* RFC 8288: response `Link: </successor>; rel="successor-version"`
pointing at /query and /mutate respectively.
- Share business logic across /mutate and /change via run_mutate(); the
/change wrapper is the only place that adds the deprecation headers.
- ChangeRequest field aliases (query_source/query_name) preserved.
- AliasCommand serde now accepts `query`/`mutate` alongside `read`/`change`.
CLI:
- Promote `omnigraph query` / `omnigraph mutate` to top-level canonical
subcommands (clap visible_alias keeps `omnigraph read` / `omnigraph
change` working forever).
- Promote `omnigraph lint` / `omnigraph check` to top-level (was nested
under `omnigraph query lint`, which is now a deprecated argv shim that
rewrites to the canonical form).
- Argv-level preprocessing prints a one-line deprecation warning to
stderr when any legacy spelling is used. Canonical names are silent.
Tests:
- Server: /mutate works, /change emits Deprecation+Link headers, /read
emits Deprecation+Link headers, /query carries no deprecation signal.
- OpenAPI: /read and /change flagged deprecated; /query and /mutate not.
- CLI: canonical `lint` matches deprecated `query lint` / `query check`
output; `read` / `change` print deprecation warnings.
Docs:
- cli.md: new canonical examples; "Deprecated names" migration table.
- cli-reference.md: top-level table updated; aliases.<name>.command
accepts both legacy and canonical spellings.
- server.md: endpoint inventory shows /query and /mutate as canonical
and /read and /change as deprecated; dedicated section explains the
three-channel deprecation signal.
- og-cheet-sheet.md: use new `omnigraph lint` / `omnigraph check`.
- openapi.json regenerated.
Migration is purely cosmetic — every deprecated form continues to work
indefinitely; only the spelling changes.
Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>
40 lines
1.1 KiB
Markdown
40 lines
1.1 KiB
Markdown
# Omnigraph Cheat Sheet
|
|
|
|
## Local Query Validation
|
|
|
|
Use an explicit schema file:
|
|
|
|
```bash
|
|
omnigraph lint --query ./queries.gq --schema ./schema.pg --json
|
|
omnigraph check --query ./queries.gq --schema ./schema.pg
|
|
```
|
|
|
|
Use a local or `s3://` repo target:
|
|
|
|
```bash
|
|
omnigraph lint --query ./queries.gq ./repo.omni --json
|
|
omnigraph check --query ./queries.gq s3://bucket/repo
|
|
```
|
|
|
|
Use `omnigraph.yaml` target resolution:
|
|
|
|
```bash
|
|
omnigraph lint --query ./queries.gq --target local --config ./omnigraph.yaml
|
|
```
|
|
|
|
> The previous `omnigraph query lint` / `omnigraph query check` spellings
|
|
> are kept as deprecated argv shims that print a one-line warning to
|
|
> stderr and rewrite to the canonical `omnigraph lint` / `omnigraph check`.
|
|
|
|
## What It Checks
|
|
|
|
- parses every query in the file
|
|
- typechecks each query against the resolved schema
|
|
- warns on hardcoded mutation queries with no params
|
|
- warns when nullable node fields have no update-query coverage
|
|
|
|
## Current Limits
|
|
|
|
- repo-backed lint is local/S3-only in v1
|
|
- HTTP targets need `--schema`
|
|
- exit code is nonzero only when there are strict validation errors
|