feat(gqlize): @deprecated, build-time schema validation, Relay-compliant connections

[Azerothian]

Three GraphQL features the generator was leaving on the table, from the audit of graphql 17 and the Relay spec against packages/gqlize/src/graphql/**. The artifact IR was already ahead of the generator — snapshot/ir.ts round-trips deprecationReason and nothing produced it — so half the work was done and tested.

Each item is independently reviewable; they are separate concerns that happen to share a branch.

1. @deprecated, end to end

There was previously no way to deprecate anything. grep found zero deprecationReason outside the snapshot IR, so renaming a column was a hard breaking change with no warning path — the one problem @deprecated exists to solve.

A reason can be written two ways:

{
  name: "Post",
  define: { subtitle: { type: Sequelize.STRING, deprecated: "use `title`" } },
  deprecations: {
    fields:          { comments: "use `Comment(where: { postId: ... })`" },  // relationships have no slot of their own
    classMethods:    { legacySearch: "use `Post(where:)`" },
    instanceMethods: { trimTitle: "the server trims on write now" },         // the `apply` transform inputs
  },
}

deprecationFor (packages/utilize/src/utils/deprecation.ts) is the single point that decides precedence: the central map wins, which is the same precedence comments.fields already has over a field's own description, and for the same reason — the map is the only way a definition can deprecate a declaration it did not author.

Where a reason lands: output fields (including global-id and override fields), mutation inputs, both halves of the orderBy enum pair (a deprecated column should not stay silently sortable), class-method query fields, apply transform inputs, and for a model-level deprecated, QueryModels.X and MutationModels.X — GraphQL has no way to deprecate an object type.

One asymmetry is the spec's, not ours: graphql rejects @deprecated on a required input field, since a client cannot stop sending a value it is obliged to send. A deprecated NOT NULL column therefore shows the reason on {Def}OptionalInput (update) and not on {Def}RequiredInput (create). Asserted as a test rather than left as a surprise.

Two cache-sharing hazards worth flagging for review: schemaCache.lists memoises connection field configs across parents, so every mark on a list field copies ({...many, deprecationReason}) rather than mutating — otherwise deprecating one parent's relationship would deprecate every other use of the same connection.

2. Build-time schema validation

validateSchema / assertValidSchema were never called anywhere in packages/*/src. Issue #54 is why that matters: graphql validates lazily — once per execution, cached on the schema — and returns the same error list for every operation. So one malformed field in options.root did not fail only the query that selected it, it failed every query, at request time, naming the coordinate but not the code that produced it.

Now:

Error: gqlize: the generated schema is not a valid GraphQL schema:
  - Subscription.subjectChanged field type must be Output Type but got: undefined.
Most often this is a type written into `options.root`, `options.extend` or a definition's
`override` / `expose` block. Pass `validate: false` to skip this check.

materializeSchema runs the same gate, where it matters more — an artifact is loaded at boot, so an invalid one would otherwise reach production traffic before the first query reported it. options.validate: false opts out for a host building many permission profiles per process. graphql's own error objects stay on error.errors.

No existing suite turned out to be building a deliberately invalid schema.

3. Relay connection nullability ⚠️ breaking

 type PostList {
-  pageInfo: PageInfo          +  pageInfo: PageInfo!
-  edges: [PostEdge]           +  edges: [PostEdge!]!
   total: Int                  # unchanged — a separate COUNT the include builder may skip
 }
 type PostEdge {
   node: Post                  # unchanged — the row can go away between the page query and the node resolve
-  cursor: String              +  cursor: String!
 }
 type PageInfo {
-  hasNextPage: Boolean        +  hasNextPage: Boolean!
-  hasPreviousPage: Boolean    +  hasPreviousPage: Boolean!
   startCursor: String         # unchanged — an empty page has no edge to name
 }

The first three are what the Relay Connections spec requires. The other two are the same argument applied consistently: resolvers/connection.ts has always returned an edges array and minted every edge's cursor itself, so the nullable spelling only ever bought clients a null check they could not trigger — while Relay, graphql-codegen and Apollo's relayStylePagination all generated boolean | null from it.

Consumer impact: artifacts must be rebuilt (gqlize check reports them stale) and client codegen re-run. Nothing breaks at runtime — the server never sent null for these — but null checks become dead code. No resolver, hook or permission behaviour changed. Documented as a new section in docs/migration-6-to-7.md, since 7.0 is still unreleased.

4. Documentation

docs/specifications.md §3, §4, §5 (a new Deprecation section), §6, §11, §13; docs/guide.md §3 (Deprecating fields), §4 (Build-time validation), §6; a migration section; and packages/gqlize/README.md.

The README ## Features and ## TODO were stale in ways the spec inherited, since §13 claims to quote the README: the typed where/filter object for the Sequelize adapter, cross-adapter relationships, before/after hooks and CI/CD were all listed as pending and all ship today. Each was checked against the code before being pruned. §13 now also records the deferred findings (schema directives, user-declared interfaces/unions, @oneOf, the missing subscription artifact half) and a Deliberately out of scope section for @defer/@stream, cost/depth limiting, federation and DataLoader — with the caveat that a @streamed field still goes through build-include-from-selection.ts and so over-fetches rather than breaks.

Every SDL block in the docs was diffed against real printSchema output rather than hand-written; that caught one wrong connection type name.

Verification

• Root pnpm test: 9/9 packages green, gqlize 76 suites / 801 tests (from 73/788). nestize and temporalize both build through createSchema, so item 2's assert covers them.
• pnpm typecheck 9/9; pnpm lint clean against the zero-warning ratchet.
• npx jest --ci sits at the pre-existing 13-suite/26-test baseline (jest ESM transform on relay.test.ts, plus postgres unavailable locally) — unchanged by this branch.
• The two SDL goldens moved for item 3 only, and every one of the 32 diff lines was read by hand; items 1 and 2 moved no golden, confirming they leaked no schema-shape change.
• examples/gqlize-basic regenerated, and the artifact verified to boot through loadSchema and serve a connection query with the new shape.

Closes the build-time half of #54 — the subscription root itself is still unimplemented and stays on the roadmap, with the artifact gap now recorded alongside it.

🤖 Generated with Claude Code

https://claude.ai/code/session_012xoQguMMNiv844ST3LvBMm