apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-12 01:45:14 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5
omnigraph/og-cheet-sheet.md
Devin AI a3e1b27a63 feat(MR-656): rename read/change to query/mutate with deprecation signals 
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>
2026-05-23 13:34:28 +00:00

1.1 KiB
Raw Blame History

Omnigraph Cheat Sheet

Local Query Validation

Use an explicit schema file:

omnigraph lint  --query ./queries.gq --schema ./schema.pg --json
omnigraph check --query ./queries.gq --schema ./schema.pg

Use a local or s3:// repo target:

omnigraph lint  --query ./queries.gq ./repo.omni --json
omnigraph check --query ./queries.gq s3://bucket/repo

Use omnigraph.yaml target resolution:

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