Skip to content

feat(codegen): graphql spec kind — introspection to the api manifest, and a GraphQL fake - #635

Merged
leemour merged 2 commits into
mainfrom
feat/graphql-spec
Nov 17, 2026
Merged

leemour merged 2 commits into
mainfrom
feat/graphql-spec

Conversation

@leemour

@leemour leemour commented Nov 17, 2026

Copy link
Copy Markdown
Member

Task

L1 of the source-manifest plan (cli-private plans/2026-11-16-cli-factory/source-manifest.md, section 6.2): the graphql spec kind the Linear pilot needs. The manifest shape is agreed with the L2 executor in that plan ("Поправка L1", accepted by L2).

Why

Linear has no OpenAPI description, only a GraphQL schema. A WireCat CLI is built from its API manifest, so GraphQL must produce the same manifest the api group, manifestCall and the source interpreters read.

What

  • adaptGraphql(introspection, { url, scalars, exclude }) → ApiModel: one operation per Query/Mutation field with a new graphql binding (operation, field, each argument's GraphQL type in variables, a default selection: scalars and { id } of objects one level deep, a connection's nodes and pageInfo). Arguments are in: "body" flags and the variables object is the request body; the answer is data.<field>, typed by the field's type.
  • Effects: query → read, mutation → write, *Delete/*Archive (not *Unarchive) → destructive, so permissions gives <group>.delete.
  • A Relay connection pages with the existing cursor style (after/first in the variables, pageInfo.endCursor, pageInfo.hasNextPage, nodes), not a new relay style: cli-core's nextPage and crmSourceFromManifest already read it, and a new style would break cli-core's exhaustive switch on the bump.
  • graphqlDocument(binding, selection?) builds the one document a call sends; parseSelection reads a selection.
  • graphqlFake: strict fake in the spirit of fakeApi: only documents graphqlDocument built, selections checked against the types (a union takes only __typename), variables against their schema, answers within the selection, errors[] at HTTP 200.
  • syncGraphql / readGraphql: the introspection snapshot with its provenance and hash. SDL is not read (needs graphql-js; codegen adds no runtime dependency).
  • bindingLabel names any binding. May break callers: Binding has a third member; code that reads binding.name once a binding is not http must narrow to rpc (in cli-core: src/cli/bot/api.ts:45, fixed in L2's bump).

Testing

  • src/codegen/graphql.test.ts over a hand-made, Linear-shaped introspection fixture (test/fixtures/graphql-tracker.ts): connections, an input object, an enum, a custom scalar, a union, wrapped types, a nullable answer, a defaulted non-null argument, Delete/Archive/Unarchive. No call to Linear.
  • pnpm lint, tsc with tsconfig.json and tsconfig.test.json, vitest run src/codegen (141 tests), pnpm docs:check.
  • A fresh-agent review found four bugs (a nullable answer's null dropped, a defaulted non-null argument declared non-null, the fake accepting an object without selection and member fields on a union); all fixed with tests.

🤖 Generated with Claude Code

leemour and others added 2 commits November 17, 2026 22:07
…phqlFake, syncGraphql

An introspection result becomes the ApiModel: one operation per Query and
Mutation field with a graphql binding (field, variables' GraphQL types,
default selection), arguments as body flags and the variables as the
request body, Relay connections paged as the existing cursor style, and
*Delete/*Archive mutations as deletes. graphqlFake is the strict fake for
tests; syncGraphql/readGraphql keep the snapshot with its hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… stricter fake

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 5584e46 into main Nov 17, 2026
10 checks passed
@leemour
leemour deleted the feat/graphql-spec branch November 17, 2026 21:17
@leemour leemour mentioned this pull request Nov 17, 2026
leemour added a commit that referenced this pull request Nov 17, 2026
Dates the release as 0.115.0, carrying #635 (the `graphql` spec kind,
Added → minor) and #634 (`auth` signs in an operation whose spec says
`security: []`). Only package.json and the CHANGELOG change;
`bin/release` publishes it after the merge.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant