diff --git a/CHANGELOG.md b/CHANGELOG.md index 1cc8b2b..efebd61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,16 @@ Every entry says what changed as a caller sees it, why, and what to watch for ## Unreleased +### Added + +- **A GraphQL API generates its `api` group too.** `adaptGraphql` reads an introspection result into the model: one + operation per `Query` and `Mutation` field, with a new `graphql` binding (the field, its variables' GraphQL types and + a default selection), its arguments as body flags, a Relay connection paged as `cursor`, and `*Delete`/`*Archive` + mutations as deletes. `syncGraphql` and `readGraphql` keep the snapshot with its hash, `graphqlDocument` builds the + request, and `graphqlFake` is a strict fake for tests. Watch for: `Binding` has a third member, so code that reads + `binding.name` once a binding is not `http` must narrow to `rpc`; `bindingLabel` names any binding. See the + [reference](docs/REFERENCE.md). For the Linear pilot. + ### Fixed - **`generate` with `auth` signs in an operation whose spec says `security: []`**, the same as one with no diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 9c5f4ee..8fc8be6 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -213,8 +213,8 @@ system keychain, `resolvePaths` without `env` reads `process.env`. Passing them timeout test finish instantly and a keyring test incapable of reaching a real keychain. **Generating an API catalog is `@wirecat/cli-base/codegen`**, a build-time tool. It reads a -format-neutral `ApiModel` — operations with a transport binding (`http` method and path, or `rpc` -name), an `effect` (`read`, `write`, `destructive`) and how far the source can be trusted +format-neutral `ApiModel` — operations with a transport binding (`http` method and path, `rpc` +name, or a `graphql` field), an `effect` (`read`, `write`, `destructive`) and how far the source can be trusted (`contract`, `example`, `inferred`, `override`) — and writes committed files. It parses no file format and adds no runtime dependency: `adaptOpenApi` reads a parsed OpenAPI document, `adaptDiscovery` parsed Google Discovery documents, and an adapter from Postman or anything else lives in the CLI that has that @@ -253,6 +253,25 @@ generate(model, generators, { }) ``` +**A GraphQL API comes from its introspection result.** `syncGraphql({ url, dir })` sends the standard introspection +query (`INTROSPECTION_QUERY`) and writes `schema.json`, its types sorted by name, with a `provenance.json`; +`readGraphql(dir)` loads it back and stops on a changed hash. `adaptGraphql(schema, { url, scalars, exclude })` makes one +operation of each `Query` and `Mutation` field, with a `graphql` binding: the field, each argument's GraphQL type +(`variables`) and a default selection — scalars and `{ id }` of each object, one level deep; a Relay connection's `nodes` +and `pageInfo`. `graphqlDocument(binding, selection?)` builds the one document a call sends, with every variable +declared and passed; a caller that needs more (`state { type }`) passes its own selection. Each argument is a body flag, +the variables are the request body, and the answer is `data.`, typed by the field's type; the fields of an +answer type are all optional, since a selection asks for some. A query reads; a mutation writes; one whose name ends in +`Delete` or `Archive` (not `Unarchive`) deletes, so `permissions` gives it `.delete`. A connection with an `after` +argument pages as `cursor`: `after` and `first` in the variables, `pageInfo.endCursor` and `pageInfo.hasNextPage` in the +answer, rows under `nodes`. Each scalar the schema defines beyond GraphQL's five is mapped in `scalars` +(`{ DateTime: { type: "string" } }`), else generation stops; SDL is not read, since that needs graphql-js. `exclude` names a field, or +`query.` / `mutation.` when both roots have it. Sign-in is +not in a GraphQL schema: `generate`'s `auth` gives it. `graphqlFake({ operations, definitions, url, auth, answers })` +is the GraphQL counterpart of `fakeApi`: it takes only a document `graphqlDocument` built, refuses a selected field the +type lacks, an object selected without fields and variables that break their schema, and answers `{ data: { } }` +within the selection, or a scenario's `errors` with HTTP 200. + The generated schemas import `@wirecat/cli-base/codegen/runtime` at run time — a few number helpers, not the generator. Numbers are expected from a lossless JSON parser (`lossless-json`): a 64-bit integer comes out as its exact decimal string, and any other integer that does not fit a JS diff --git a/docs/standards/kit-surface.md b/docs/standards/kit-surface.md index 1878e96..1748abc 100644 --- a/docs/standards/kit-surface.md +++ b/docs/standards/kit-surface.md @@ -47,6 +47,7 @@ what it cannot do yet. | Swagger 2.0 | `adaptOpenApi(await upgradeToOpenApi3(document))` | | Swagger 1.2 (Yandex Disk) | `upgradeToOpenApi3(listing, declarations)`: the resource listing, and each API declaration keyed by its `apis[].path`, fetched from the listing's `basePath` followed by that path | | Google Discovery | `adaptDiscovery(readDiscovery(dir))`, snapshots written by `syncDiscovery` | +| GraphQL (Linear) | `adaptGraphql(readGraphql(dir), { url, scalars })`, the introspection result written by `syncGraphql` | `upgradeToOpenApi3` converts with [swagger-converter](https://github.com/apigee-127/swagger-converter) (1.2 → 2.0) and [@scalar/openapi-upgrader](https://github.com/scalar/scalar/tree/main/packages/openapi-upgrader) (2.0 → 3.0). They are diff --git a/src/codegen/graphql-fake.ts b/src/codegen/graphql-fake.ts new file mode 100644 index 0000000..6205441 --- /dev/null +++ b/src/codegen/graphql-fake.ts @@ -0,0 +1,235 @@ +/** + * A strict fake of a GraphQL service, built from the files `generate` wrote, in the spirit of `fakeApi`: a `fetch` that + * takes only a POST of a document `graphqlDocument` builds for an operation the manifest has, refuses a selection + * field the type lacks, variables that break their schema and a missing sign-in, and answers `data.` within + * the selection. A test writes only its scenarios; one that answers outside the schema or the selection throws. + */ + +import { sampleOf, schemaProblems } from "./fake.js" +import { graphqlDocument, parseSelection, type Selection } from "./graphql.js" +import type { ManifestOperation } from "./manifest.js" +import type { GraphqlBinding, SchemaNode } from "./model.js" +import { identifier } from "./names.js" + +type Definitions = Readonly> + +export interface GraphqlFakeCall { + /** The matched operation's id; absent when the request matched none. */ + operation?: string + query: string + selection?: Selection + variables: Readonly> + headers: Headers +} + +/** `data` is the field's answer; `errors` are sent as GraphQL's, with HTTP 200 unless `status` says otherwise. */ +export interface GraphqlFakeAnswer { + status?: number + data?: unknown + errors?: readonly { message: string; extensions?: Readonly> }[] + headers?: Readonly> +} + +type Answering = (call: GraphqlFakeCall) => GraphqlFakeAnswer | Promise + +export interface GraphqlFakeOptions { + operations: readonly ManifestOperation[] + definitions: Definitions + /** The endpoint: `https://api.linear.app/graphql`. */ + url: string + /** The header and value every call must carry: `{ header: "Authorization", value: "" }`. */ + auth?: { header: string; value: string } + /** Answers by operation id; one without an answer gets a sample of its selection. */ + answers?: Readonly> +} + +export interface GraphqlFake { + fetch: (input: string | URL | Request, init?: RequestInit) => Promise + calls: GraphqlFakeCall[] + /** Why each refused call was refused; a test that expects none asserts this is empty. */ + refusals: string[] +} + +const isObject = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Array.isArray(value) + +type ObjectNode = Extract +type Shape = { kind: "leaf" } | { kind: "union" } | { kind: "object"; objects: ObjectNode[] } + +/** What a selection walks into, through references, lists and a nullable wrapper: an object, a union or a leaf. */ +const shapeOf = (node: SchemaNode, definitions: Definitions, depth = 0): Shape => { + if (depth > 20) return { kind: "leaf" } + switch (node.type) { + case "ref": { + const target = definitions[identifier(node.ref)] + return target ? shapeOf(target, definitions, depth + 1) : { kind: "leaf" } + } + case "array": + return shapeOf(node.items, definitions, depth + 1) + case "allOf": { + const objects = node.of.flatMap((one) => { + const inner = shapeOf(one, definitions, depth + 1) + return inner.kind === "object" ? inner.objects : [] + }) + return objects.length > 0 ? { kind: "object", objects } : { kind: "leaf" } + } + case "union": + return { kind: "union" } + case "object": + return { kind: "object", objects: [node] } + default: + return { kind: "leaf" } + } +} + +/** + * Every field the selection names that the type lacks, a leaf asked without a selection, or an object asked with one. + * On a union only `__typename` is selectable: its members' fields need fragments, which a selection here never has. + */ +export const selectionProblems = ( + selection: Selection, + node: SchemaNode, + definitions: Definitions, + where = "selection", +): string[] => { + const shape = shapeOf(node, definitions) + if (shape.kind === "leaf") return [`${where}: a scalar has no fields to select`] + return Object.entries(selection).flatMap(([name, inner]) => { + if (name === "__typename") return inner === true ? [] : [`${where}.__typename: a scalar has no fields to select`] + if (shape.kind === "union") return [`${where}.${name}: a union takes only __typename`] + const property = shape.objects.map((one) => one.properties[name]).find(Boolean) + if (!property) return [`${where}.${name}: no such field`] + const leaf = shapeOf(property, definitions).kind === "leaf" + if (inner === true) return leaf ? [] : [`${where}.${name}: an object needs a selection`] + return selectionProblems(inner, property, definitions, `${where}.${name}`) + }) +} + +/** Every field of the answer outside the selection. */ +const outside = (value: unknown, selection: Selection, where: string): string[] => { + if (Array.isArray(value)) return value.flatMap((one, index) => outside(one, selection, `${where}[${index}]`)) + if (!isObject(value)) return [] + return Object.entries(value).flatMap(([name, inner]) => { + const asked = selection[name] + if (asked === undefined) return [`${where}.${name}: not selected`] + return asked === true ? [] : outside(inner, asked, `${where}.${name}`) + }) +} + +/** A value of the type with only the selected fields. */ +const sampleWithin = (node: SchemaNode, selection: Selection | true, definitions: Definitions): unknown => { + if (selection === true) return sampleOf(node, definitions) + if (node.type === "ref") { + const target = definitions[identifier(node.ref)] + return target ? sampleWithin(target, selection, definitions) : null + } + if (node.type === "array") return [sampleWithin(node.items, selection, definitions)] + const shape = shapeOf(node, definitions) + const objects = shape.kind === "object" ? shape.objects : [] + return Object.fromEntries( + Object.entries(selection).map(([name, inner]) => [ + name, + name === "__typename" + ? "Object" + : sampleWithin( + objects.map((one) => one.properties[name]).find(Boolean) ?? { type: "unknown" }, + inner, + definitions, + ), + ]), + ) +} + +const json = (status: number, body: unknown, headers: Readonly> = {}) => + new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...headers } }) + +/** The selection inside a document built for `binding`, or `undefined` when it was not built so. */ +const selectionIn = (binding: GraphqlBinding, query: string): string | undefined => { + const marker = "\u0000" + const [head = "", tail = ""] = graphqlDocument(binding, marker).split(marker) + if (query === graphqlDocument(binding, "")) return "" + if (!query.startsWith(head) || !query.endsWith(tail) || query.length < head.length + tail.length) return undefined + return query.slice(head.length, query.length - tail.length) +} + +export const graphqlFake = (options: GraphqlFakeOptions): GraphqlFake => { + const calls: GraphqlFakeCall[] = [] + const refusals: string[] = [] + const { definitions } = options + const endpoint = new URL(options.url).href + const refuse = (status: number, problems: readonly string[]) => { + for (const problem of problems) refusals.push(problem) + return json(status, { errors: problems.map((message) => ({ message, extensions: { code: "FAKE_REFUSED" } })) }) + } + const graphql = options.operations.filter( + (one): one is ManifestOperation & { binding: GraphqlBinding } => one.binding.kind === "graphql", + ) + + const fetch = async (input: string | URL | Request, init?: RequestInit): Promise => { + const request = new Request(input, init) + let body: unknown + try { + body = JSON.parse(await request.text()) + } catch { + body = undefined + } + const query = isObject(body) && typeof body.query === "string" ? body.query : "" + const variables = isObject(body) && isObject(body.variables) ? body.variables : {} + const call: GraphqlFakeCall = { query, variables, headers: request.headers } + calls.push(call) + if (request.url !== endpoint) return refuse(404, [`${request.url} is not ${endpoint}`]) + if (request.method !== "POST") return refuse(405, [`a GraphQL call is a POST, not ${request.method}`]) + if (!query) return refuse(400, ["the body is not JSON with a query"]) + if (options.auth && request.headers.get(options.auth.header) !== options.auth.value) + return refuse(401, [`no ${options.auth.header} header with the expected sign-in`]) + const found = graphql + .map((operation) => ({ operation, text: selectionIn(operation.binding, query) })) + .find((one) => one.text !== undefined) + if (!found) return refuse(400, [`no operation of the manifest builds the document: ${query.slice(0, 120)}`]) + const { operation } = found + call.operation = operation.id + const response = operation.response?.schema ? definitions[operation.response.schema] : undefined + let selection: Selection = {} + const parseProblems: string[] = [] + try { + selection = parseSelection(found.text ?? "") + call.selection = selection + } catch (error) { + parseProblems.push(`${operation.id}: ${(error as Error).message}`) + } + const variablesSchema = operation.request?.schema ? definitions[operation.request.schema] : undefined + const problems = [ + ...parseProblems, + ...(response && found.text ? selectionProblems(selection, response, definitions, operation.id) : []), + ...(response && !found.text && shapeOf(response, definitions).kind !== "leaf" + ? [`${operation.id}: an object needs a selection`] + : []), + ...(variablesSchema + ? schemaProblems(variables, variablesSchema, definitions, "variables") + : Object.keys(variables).map((name) => `${operation.id}: takes no argument "${name}"`)), + ] + if (problems.length > 0) return refuse(400, problems) + + const answering = options.answers?.[operation.id] + if (!answering) { + const data = response + ? found.text + ? sampleWithin(response, selection, definitions) + : sampleOf(response, definitions) + : null + return json(200, { data: { [operation.binding.field]: data } }) + } + const { status = 200, data, errors, headers } = await answering(call) + if (errors?.length) return json(status, { data: null, errors }, headers) + if (status >= 200 && status < 300 && response && data !== undefined) { + const wrong = [ + ...schemaProblems(data, response, definitions, "answer"), + ...(found.text ? outside(data, selection, "answer") : []), + ] + if (wrong.length > 0) + throw new Error(`the answer for ${operation.id} breaks its schema or selection: ${wrong.join("; ")}`) + } + return json(status, { data: { [operation.binding.field]: data ?? null } }, headers) + } + return { fetch, calls, refusals } +} diff --git a/src/codegen/graphql.test.ts b/src/codegen/graphql.test.ts new file mode 100644 index 0000000..423b1fc --- /dev/null +++ b/src/codegen/graphql.test.ts @@ -0,0 +1,343 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { afterAll, describe, expect, it } from "vitest" +import { trackerIntrospection } from "../../test/fixtures/graphql-tracker.js" +import { + adaptGraphql, + CodegenError, + coverageGenerator, + definitionsGenerator, + type GraphqlBinding, + generate, + graphqlDocument, + graphqlFake, + INTROSPECTION_QUERY, + type ManifestOperation, + manifestGenerator, + parseSelection, + readGraphql, + type SchemaNode, + syncGraphql, + typesGenerator, + valibotGenerator, +} from "./index.js" + +const URL_ = "https://api.tracker.example/graphql" +const scalars = { DateTime: { type: "string" } } as const +const model = () => adaptGraphql(trackerIntrospection(), { url: URL_, scalars }) +const operation = (id: string) => { + const found = model().operations.find((one) => one.id === id) + if (!found) throw new Error(`no ${id}`) + return found +} + +/** What a CLI's pnpm generate writes, read back as the manifest and definitions a fake takes. */ +const generated = () => { + const artifacts = generate( + model(), + [manifestGenerator({ path: "manifest.ts" }), definitionsGenerator({ path: "definitions.ts" })], + { banner: [], permissions: { group: "issues" } }, + ) + const constant = (path: string, name: string) => { + const content = artifacts.find((one) => one.path === path)?.content ?? "" + const start = content.indexOf("=", content.indexOf(`export const ${name}`)) + 1 + const end = content.indexOf("\n\nexport const", start) + return JSON.parse(content.slice(start, end < 0 ? undefined : end)) + } + return { + operations: constant("manifest.ts", "operations") as ManifestOperation[], + definitions: constant("definitions.ts", "definitions") as Record, + } +} + +describe("adaptGraphql", () => { + it("makes one operation of each Query and Mutation field, with the effect its kind and name say", () => { + const effects = Object.fromEntries(model().operations.map((one) => [one.id, one.effect])) + expect(effects).toEqual({ + issue: "read", + issueArchive: "destructive", + issueCreate: "write", + issueDelete: "destructive", + issueUnarchive: "write", + issues: "read", + maybeIssue: "read", + recentIssues: "read", + search: "read", + teams: "read", + users: "read", + viewer: "read", + workflowStates: "read", + }) + }) + + it("binds a field with its variables' GraphQL types and a default selection one level deep", () => { + const issues = operation("issues") + expect(issues.binding).toEqual({ + kind: "graphql", + operation: "query", + field: "issues", + variables: { + first: "Int", + after: "String", + filter: "IssueFilter", + includeArchived: "Boolean", + orderBy: "PaginationOrderBy", + }, + selection: + "nodes { id identifier title description priority createdAt updatedAt archivedAt state { id } team { id } assignee { id } } pageInfo { hasNextPage endCursor }", + }) + expect(operation("issue").binding).toMatchObject({ + variables: { id: "String!" }, + selection: + "id identifier title description priority createdAt updatedAt archivedAt state { id } team { id } assignee { id }", + }) + expect(operation("issueDelete").binding).toMatchObject({ operation: "mutation", selection: "success" }) + }) + + it("makes each argument a body flag and the variables the request body", () => { + const issue = operation("issue") + expect(issue.parameters).toEqual([{ name: "id", in: "body", required: true, schema: { type: "string" } }]) + expect(issue.requestBody).toMatchObject({ required: true, schema: { type: "object", required: ["id"] } }) + expect(operation("viewer").requestBody).toBeUndefined() + const create = model().schemas.find((one) => one.id === "IssueCreateInput")?.schema + // A non-null field with a default may be left out. + expect(create).toMatchObject({ type: "object", required: ["title", "teamId"] }) + }) + + it("declares a non-null argument with a default as a nullable variable, which may then be left out", () => { + expect(operation("recentIssues").binding).toMatchObject({ variables: { limit: "Int" } }) + expect(operation("recentIssues").parameters[0]).toMatchObject({ name: "limit", required: false }) + }) + + it("keeps a nullable answer's null, and leaves deprecated fields out of the default selection", () => { + const [types] = generate(model(), [typesGenerator({ path: "types.ts" })], { banner: [] }) + expect(types?.content).toMatch(/export type MaybeIssueResponse = Issue \| null/) + expect(operation("issue").binding).not.toMatchObject({ selection: expect.stringContaining("legacyKey") }) + }) + + it("selects only __typename of a union", () => { + expect(operation("search").binding).toMatchObject({ selection: "__typename" }) + }) + + it("leaves out one root's field when both roots have its name", () => { + const both = trackerIntrospection() + const mutation = both.data.__schema.types.find((one) => one.name === "Mutation") as unknown as { fields: unknown[] } + const query = both.data.__schema.types.find((one) => one.name === "Query") as unknown as { + fields: { name: string }[] + } + mutation.fields.push({ ...query.fields.find((one) => one.name === "viewer") }) + expect(() => generate(adaptGraphql(both, { url: URL_, scalars }), [], { banner: [] })).toThrow( + /two operations share the id "viewer"/, + ) + const kept = adaptGraphql(both, { url: URL_, scalars, exclude: { "mutation.viewer": "a test clash" } }) + expect(kept.operations.find((one) => one.id === "viewer")?.binding).toMatchObject({ operation: "query" }) + }) + + it("pages a Relay connection as a cursor in the variables", () => { + expect(operation("issues").pagination).toEqual({ + style: "cursor", + cursor: { in: "body", name: "after" }, + next: "pageInfo.endCursor", + items: "nodes", + hasMore: "pageInfo.hasNextPage", + limit: { in: "body", name: "first" }, + }) + expect(operation("viewer").pagination).toBeUndefined() + expect(operation("issue").pagination).toBeUndefined() + }) + + it("stops on a scalar it was not told the shape of", () => { + expect(() => adaptGraphql(trackerIntrospection(), { url: URL_ })).toThrow(/scalar DateTime: map it in scalars/) + }) + + it("leaves out an excluded field, and stops on an exclusion that matches none", () => { + const left = adaptGraphql(trackerIntrospection(), { url: URL_, scalars, exclude: { viewer: "not needed" } }) + expect(left.operations.map((one) => one.id)).not.toContain("viewer") + expect(() => adaptGraphql(trackerIntrospection(), { url: URL_, scalars, exclude: { nope: "x" } })).toThrow( + CodegenError, + ) + }) + + it("goes through generate: types, schemas, manifest, coverage and the delete keys", () => { + const artifacts = generate( + model(), + [ + typesGenerator({ path: "types.ts" }), + valibotGenerator({ path: "schemas.ts", typesImport: "./types.js" }), + manifestGenerator({ path: "manifest.ts" }), + coverageGenerator({ path: "API.md", title: "API", command: (one) => `tracker api ${one.command}` }), + ], + { banner: [], permissions: { group: "issues" } }, + ) + const text = (path: string) => artifacts.find((one) => one.path === path)?.content ?? "" + expect(text("types.ts")).toContain("issues: IssueConnection") + expect(text("API.md")).toContain( + "| `issueDelete` | `mutation issueDelete` | `tracker api issue-delete` | destructive", + ) + const { operations } = generated() + const keys = Object.fromEntries(operations.map((one) => [one.id, one.permissions?.map((p) => p.key)])) + expect(keys.issueDelete).toEqual(["issues.delete"]) + expect(keys.issueArchive).toEqual(["issues.delete"]) + expect(keys.issueUnarchive).toBeUndefined() + }) +}) + +describe("graphqlDocument and parseSelection", () => { + const binding: GraphqlBinding = { + kind: "graphql", + operation: "query", + field: "issue", + variables: { id: "String!" }, + selection: "id", + } + + it("declares and passes every variable around the selection", () => { + expect(graphqlDocument(binding)).toBe("query Issue($id: String!) { issue(id: $id) { id } }") + expect(graphqlDocument({ ...binding, variables: {} }, "")).toBe("query Issue { issue }") + }) + + it("reads names and braces, and refuses what it cannot check", () => { + expect(parseSelection("id state { id type } ")).toEqual({ id: true, state: { id: true, type: true } }) + expect(() => parseSelection("id(first: 1)")).toThrow(/only field names/) + expect(() => parseSelection("state { id")).toThrow(/not closed/) + expect(() => parseSelection("state { }")).toThrow(/selects nothing/) + }) +}) + +describe("graphqlFake", () => { + const KEY = "lin_api_fake" + const post = (fake: ReturnType, query: string, variables: unknown = {}, key = KEY) => + fake + .fetch(URL_, { + method: "POST", + headers: { authorization: key, "content-type": "application/json" }, + body: JSON.stringify({ query, variables }), + }) + .then(async (response) => ({ status: response.status, body: (await response.json()) as Record })) + const bindingOf = (operations: readonly ManifestOperation[], id: string) => + operations.find((one) => one.id === id)?.binding as GraphqlBinding + const make = (answers = {}) => { + const { operations, definitions } = generated() + const fake = graphqlFake({ + operations, + definitions, + url: URL_, + auth: { header: "Authorization", value: KEY }, + answers, + }) + return { fake, operations } + } + + it("answers a default selection with a sample within it", async () => { + const { fake, operations } = make() + const answer = await post(fake, graphqlDocument(bindingOf(operations, "issue")), { id: "a" }) + expect(answer.status).toBe(200) + const issue = (answer.body.data as { issue: Record }).issue + expect(Object.keys(issue)).toContain("state") + expect(issue.state).toEqual({ id: "xxxxxx" }) + expect(fake.refusals).toEqual([]) + }) + + it("takes a deeper selection the types have, and refuses a field they lack", async () => { + const { fake, operations } = make() + const issues = bindingOf(operations, "issues") + const deep = "nodes { id state { type } assignee { email } } pageInfo { hasNextPage endCursor }" + expect((await post(fake, graphqlDocument(issues, deep))).status).toBe(200) + const typo = await post(fake, graphqlDocument(issues, "nodes { id stat { type } } pageInfo { endCursor }")) + expect(typo.status).toBe(400) + expect(fake.refusals).toEqual(["issues.nodes.stat: no such field"]) + }) + + it("refuses an object without a selection, wrong or unknown variables, a hand-typed document and no sign-in", async () => { + const { fake, operations } = make() + const issue = bindingOf(operations, "issue") + await post(fake, graphqlDocument(issue, "id state"), { id: "a" }) + await post(fake, graphqlDocument(issue), { id: 7 }) + await post(fake, graphqlDocument(issue), { id: "a", extra: 1 }) + await post(fake, 'query { issue(id: "a") { id } }') + await post(fake, graphqlDocument(issue), { id: "a" }, "wrong") + expect(fake.refusals).toEqual([ + "issue.state: an object needs a selection", + "variables.id: expected a string", + "variables.extra: no such field", + 'no operation of the manifest builds the document: query { issue(id: "a") { id } }', + "no Authorization header with the expected sign-in", + ]) + }) + + it("pages through a scenario with state, and sends errors[] with HTTP 200", async () => { + const pages = [ + { nodes: [{ id: "1" }], pageInfo: { hasNextPage: true, endCursor: "c1" } }, + { nodes: [{ id: "2" }], pageInfo: { hasNextPage: false, endCursor: null } }, + ] + const { fake, operations } = make({ + issues: ({ variables }: { variables: { after?: string } }) => ({ data: pages[variables.after === "c1" ? 1 : 0] }), + issue: () => ({ errors: [{ message: "Entity not found", extensions: { code: "INVALID_INPUT" } }] }), + }) + const issues = graphqlDocument(bindingOf(operations, "issues"), "nodes { id } pageInfo { hasNextPage endCursor }") + const first = await post(fake, issues, { first: 1 }) + const second = await post(fake, issues, { first: 1, after: "c1" }) + expect([first.body.data, second.body.data]).toEqual([{ issues: pages[0] }, { issues: pages[1] }]) + const missing = await post(fake, graphqlDocument(bindingOf(operations, "issue")), { id: "x" }) + expect(missing).toEqual({ + status: 200, + body: { data: null, errors: [{ message: "Entity not found", extensions: { code: "INVALID_INPUT" } }] }, + }) + }) + + it("refuses an object asked with no selection and a member's field asked on a union", async () => { + const { fake, operations } = make() + await post(fake, graphqlDocument(bindingOf(operations, "issue"), ""), { id: "a" }) + await post(fake, graphqlDocument(bindingOf(operations, "search"), "id"), { term: "a" }) + expect(fake.refusals).toEqual(["issue: an object needs a selection", "search.id: a union takes only __typename"]) + }) + + it("answers null for a nullable answer, and a URL without a path matches", async () => { + const { operations, definitions } = generated() + const fake = graphqlFake({ + operations, + definitions, + url: "https://api.tracker.example", + answers: { maybeIssue: () => ({ data: null }) }, + }) + const answer = await fake.fetch("https://api.tracker.example/", { + method: "POST", + body: JSON.stringify({ query: graphqlDocument(bindingOf(operations, "maybeIssue")), variables: { id: "a" } }), + }) + expect(await answer.json()).toEqual({ data: { maybeIssue: null } }) + }) + + it("throws on a scenario that answers outside its selection", async () => { + const { fake, operations } = make({ issue: () => ({ data: { id: "1", title: "x" } }) }) + await expect(post(fake, graphqlDocument(bindingOf(operations, "issue"), "id"), { id: "1" })).rejects.toThrow( + /answer.title: not selected/, + ) + }) +}) + +describe("syncGraphql and readGraphql", () => { + const dir = mkdtempSync(join(tmpdir(), "graphql-sync-")) + afterAll(() => rmSync(dir, { recursive: true, force: true })) + + it("writes the schema with its provenance, reads it back, and refuses a changed file", async () => { + let asked: unknown + const fetch = (async (_url: string, init: RequestInit) => { + asked = JSON.parse(String(init.body)) + return new Response(JSON.stringify(trackerIntrospection()), { status: 200 }) + }) as unknown as typeof globalThis.fetch + const provenance = await syncGraphql({ url: URL_, dir, fetch, now: new Date("2026-11-17T00:00:00Z") }) + expect(asked).toEqual({ query: INTROSPECTION_QUERY }) + expect(provenance).toMatchObject({ source: URL_, retrieved_at: "2026-11-17T00:00:00.000Z" }) + const read = readGraphql(dir) + expect(adaptGraphql(read, { url: URL_, scalars }).operations).toHaveLength(13) + writeFileSync(join(dir, "schema.json"), "{}") + expect(() => readGraphql(dir)).toThrow(/hash mismatch/) + }) + + it("refuses an answer of errors, which a service sends when introspection needs a sign-in", async () => { + const fetch = (async () => + new Response(JSON.stringify({ errors: [{ message: "auth" }] }))) as unknown as typeof globalThis.fetch + await expect(syncGraphql({ url: URL_, dir, fetch })).rejects.toThrow(/may need a sign-in/) + }) +}) diff --git a/src/codegen/graphql.ts b/src/codegen/graphql.ts new file mode 100644 index 0000000..c04502e --- /dev/null +++ b/src/codegen/graphql.ts @@ -0,0 +1,471 @@ +/** + * A GraphQL schema's introspection result, already parsed → the format-neutral `ApiModel`, plus the offline snapshot + * it comes from: `syncGraphql` asks the endpoint for its schema with the standard introspection query and records + * where it came from, and `readGraphql` loads it back only while its hash still matches. + * + * One field of `Query` or `Mutation` is one operation. Its arguments are the request body (the variables), each also a + * flag; its answer is `data.`, typed by the field's type. A query reads; a mutation writes, and one whose name + * ends in `Delete` or `Archive` deletes. A Relay connection pages as a `cursor`: `after`, `pageInfo.endCursor`. + * SDL is not read: that needs graphql-js, and codegen adds no runtime dependency. + */ +import { createHash } from "node:crypto" +import { mkdirSync, readFileSync, writeFileSync } from "node:fs" +import { join } from "node:path" +import type { ApiModel, ApiOperation, ApiSchema, GraphqlBinding, Pagination, SchemaNode } from "./model.js" +import { CodegenError } from "./pipeline.js" + +type Json = Record + +interface TypeRef { + kind: string + name?: string | null + ofType?: TypeRef | null +} + +interface InputValue { + name: string + description?: string | null + type: TypeRef + defaultValue?: string | null +} + +interface Field { + name: string + description?: string | null + args: InputValue[] + type: TypeRef + isDeprecated?: boolean +} + +interface FullType { + kind: string + name: string + description?: string | null + fields?: Field[] | null + inputFields?: InputValue[] | null + enumValues?: { name: string }[] | null + possibleTypes?: { name: string }[] | null +} + +const object = (value: unknown): value is Json => !!value && typeof value === "object" && !Array.isArray(value) + +const BUILT_IN: Readonly> = { + String: { type: "string" }, + ID: { type: "string" }, + Int: { type: "integer", format: "int32" }, + Float: { type: "number" }, + Boolean: { type: "boolean" }, +} + +export interface GraphqlOptions { + /** The endpoint every operation is sent to: `https://api.linear.app/graphql`. */ + url: string + /** + * The schema's own scalars, each as the JSON value it travels as: `{ DateTime: { type: "string" }, JSON: { type: + * "unknown" } }`. A scalar the schema uses that is not here stops generation: its shape is never guessed. + */ + scalars?: Readonly> + /** + * Fields of `Query` or `Mutation` left out, each with the reason: by name, or as `query.` or `mutation.` + * when both roots have one of that name. One that matches no field stops generation. + */ + exclude?: Readonly> + sourceUrl?: string + sourceRevision?: string +} + +const DELETES = /(Delete|Archive)$/ +const UNDOES = /Unarchive$/ +export const GRAPHQL_DELETE_REASON = "a mutation whose name ends in Delete or Archive deletes" + +/** `[ID!]!` from its introspection reference. */ +const typeText = (ref: TypeRef): string => + ref.kind === "NON_NULL" && ref.ofType + ? `${typeText(ref.ofType)}!` + : ref.kind === "LIST" && ref.ofType + ? `[${typeText(ref.ofType)}]` + : String(ref.name) + +const named = (ref: TypeRef): string => (ref.ofType ? named(ref.ofType) : String(ref.name)) + +/** Builds the one document an operation sends: every variable declared and passed, the selection inside. */ +export const graphqlDocument = (binding: GraphqlBinding, selection: string = binding.selection): string => { + const variables = Object.entries(binding.variables) + const declared = variables.length ? `(${variables.map(([name, type]) => `$${name}: ${type}`).join(", ")})` : "" + const passed = variables.length ? `(${variables.map(([name]) => `${name}: $${name}`).join(", ")})` : "" + const inner = selection.trim() ? ` { ${selection.trim()} }` : "" + return `${binding.operation} ${binding.field[0]?.toUpperCase()}${binding.field.slice(1)}${declared} { ${binding.field}${passed}${inner} }` +} + +/** A selection as a tree: a field's name → its own selection, or `true` for a leaf. */ +export interface Selection { + readonly [field: string]: Selection | true +} + +/** + * `id title state { id type }` → its tree. Only names and braces: an argument, an alias, a fragment or a directive + * throws, since nothing here can check one. + */ +export const parseSelection = (text: string): Selection => { + const tokens = text.match(/[_A-Za-z][_0-9A-Za-z]*|[{}]|\S/g) ?? [] + let at = 0 + const level = (nested: boolean): Selection => { + const fields: Record = {} + while (at < tokens.length) { + const token = tokens[at] as string + if (token === "}") { + if (!nested) throw new Error(`selection "${text}": an unmatched }`) + at += 1 + return fields + } + if (!/^[_A-Za-z]/.test(token)) + throw new Error(`selection "${text}": "${token}" — only field names and braces are supported`) + at += 1 + if (tokens[at] === "{") { + at += 1 + const inner = level(true) + if (Object.keys(inner).length === 0) throw new Error(`selection "${text}": ${token} selects nothing`) + fields[token] = inner + } else fields[token] = true + } + if (nested) throw new Error(`selection "${text}": a { is not closed`) + return fields + } + return level(false) +} + +const schemaOf = (raw: unknown): Json => { + const root = object(raw) && object(raw.data) ? raw.data : raw + if (!object(root) || !object(root.__schema)) + throw new CodegenError(["not a GraphQL introspection result: no __schema"]) + return root.__schema +} + +export const adaptGraphql = (introspection: unknown, options: GraphqlOptions): ApiModel => { + const schema = schemaOf(introspection) + const types = new Map() + for (const type of Array.isArray(schema.types) ? (schema.types as FullType[]) : []) + if (object(type) && typeof type.name === "string" && !type.name.startsWith("__")) types.set(type.name, type) + const rootName = (key: string) => { + const root = schema[key] + return object(root) && typeof root.name === "string" ? root.name : undefined + } + const scalars = { ...BUILT_IN, ...options.scalars } + const unknownScalars = [...types.values()] + .filter((type) => type.kind === "SCALAR" && !scalars[type.name]) + .map((type) => `scalar ${type.name}: map it in scalars, as the JSON value it travels as`) + if (unknownScalars.length > 0) throw new CodegenError(unknownScalars) + + const described = (text: string | null | undefined) => (text ? { description: text } : {}) + const reference = (ref: TypeRef, where: string): SchemaNode => { + if (ref.kind === "NON_NULL" && ref.ofType) { + const { nullable: _, ...inner } = reference(ref.ofType, where) as SchemaNode & { nullable?: boolean } + return inner as SchemaNode + } + if (ref.kind === "LIST" && ref.ofType) return { type: "array", items: reference(ref.ofType, where), nullable: true } + const name = String(ref.name) + const type = types.get(name) + if (!type) throw new CodegenError([`${where}: the schema has no type ${name}`]) + if (type.kind === "SCALAR") return { ...(scalars[name] as SchemaNode), nullable: true } + return { type: "ref", ref: name, nullable: true } + } + + const schemas: ApiSchema[] = [] + for (const type of types.values()) { + const where = `type ${type.name}` + const common = described(type.description) + switch (type.kind) { + case "SCALAR": + break + case "ENUM": + schemas.push({ + id: type.name, + schema: { ...common, type: "string", enum: (type.enumValues ?? []).map((one) => one.name) }, + }) + break + case "OBJECT": + case "INTERFACE": + // A selection asks for some of the fields, so none is required in an answer. + schemas.push({ + id: type.name, + schema: { + ...common, + type: "object", + properties: Object.fromEntries( + (type.fields ?? []).map((field) => [ + field.name, + { ...reference(field.type, `${where}.${field.name}`), ...described(field.description) }, + ]), + ), + required: [], + }, + }) + break + case "UNION": + schemas.push({ + id: type.name, + schema: { + ...common, + type: "union", + of: (type.possibleTypes ?? []).map((one) => ({ type: "ref", ref: one.name })), + }, + }) + break + case "INPUT_OBJECT": + schemas.push({ id: type.name, schema: { ...common, ...inputObject(type.inputFields ?? [], where) } }) + break + default: + throw new CodegenError([`${where}: unsupported kind ${type.kind}`]) + } + } + + function inputObject(values: readonly InputValue[], where: string): SchemaNode { + return { + type: "object", + properties: Object.fromEntries( + values.map((one) => [ + one.name, + { ...reference(one.type, `${where}.${one.name}`), ...described(one.description) }, + ]), + ), + required: values.filter((one) => one.type.kind === "NON_NULL" && one.defaultValue == null).map((one) => one.name), + } + } + + const fieldsOf = (name: string) => { + const type = types.get(name) + return type && (type.kind === "OBJECT" || type.kind === "INTERFACE") ? (type.fields ?? []) : undefined + } + const selectable = (field: Field) => + !field.isDeprecated && !field.args.some((one) => one.type.kind === "NON_NULL" && one.defaultValue == null) + const isLeaf = (name: string) => { + const kind = types.get(name)?.kind + return kind === "SCALAR" || kind === "ENUM" + } + /** Scalars, and `{ id }` of each object that has one; a type with neither gives `__typename`. */ + const oneLevel = (name: string): string => { + const parts = (fieldsOf(name) ?? []).filter(selectable).flatMap((field) => { + const inner = named(field.type) + if (isLeaf(inner)) return [field.name] + return fieldsOf(inner)?.some((one) => one.name === "id") ? [`${field.name} { id }`] : [] + }) + return parts.length > 0 ? parts.join(" ") : "__typename" + } + /** A Relay connection: `nodes` of one type, and a `pageInfo` with `hasNextPage` and `endCursor`. */ + const connectionOf = (name: string): string | undefined => { + const fields = fieldsOf(name) + const nodes = fields?.find((one) => one.name === "nodes") + const pageInfo = fields?.find((one) => one.name === "pageInfo") + const info = pageInfo && fieldsOf(named(pageInfo.type)) + if (!nodes || !info || !["hasNextPage", "endCursor"].every((key) => info.some((one) => one.name === key))) + return undefined + return named(nodes.type) + } + const selectionOf = (name: string): string => { + if (isLeaf(name)) return "" + if (types.get(name)?.kind === "UNION") return "__typename" + const node = connectionOf(name) + return node ? `nodes { ${oneLevel(node)} } pageInfo { hasNextPage endCursor }` : oneLevel(name) + } + + // An answer that is only a reference is named after its type, which would drop a nullable field's null: such an + // answer is wrapped, so it gets a name of its own that keeps it. + const answerOf = (node: SchemaNode): SchemaNode => + node.type === "ref" && node.nullable + ? { type: "allOf", of: [{ type: "ref", ref: node.ref }], nullable: true } + : node + + const exclude = options.exclude ?? {} + const excluded = new Set() + const operations: ApiOperation[] = [] + for (const [key, operation] of [ + ["queryType", "query"], + ["mutationType", "mutation"], + ] as const) { + const root = rootName(key) + if (!root) continue + for (const field of fieldsOf(root) ?? []) { + const scoped = `${operation}.${field.name}` + const left = [scoped, field.name].find((name) => exclude[name] !== undefined) + if (left !== undefined) { + excluded.add(left) + continue + } + const where = `${root}.${field.name}` + const argument = (one: InputValue) => ({ + ...reference(one.type, `${where}(${one.name})`), + ...described(one.description), + }) + const required = field.args.filter((one) => one.type.kind === "NON_NULL" && one.defaultValue == null) + const answer = named(field.type) + const binding: GraphqlBinding = { + kind: "graphql", + operation, + field: field.name, + // A non-null argument with a default may be left out; declared non-null, its variable could not be. + variables: Object.fromEntries( + field.args.map((one) => [ + one.name, + one.defaultValue != null && one.type.kind === "NON_NULL" && one.type.ofType + ? typeText(one.type.ofType) + : typeText(one.type), + ]), + ), + selection: selectionOf(answer), + } + const deletes = operation === "mutation" && DELETES.test(field.name) && !UNDOES.test(field.name) + const has = (name: string, type: string) => + field.args.some((one) => one.name === name && one.type.kind !== "NON_NULL" && named(one.type) === type) + const pages = + operation === "query" && field.type.kind !== "LIST" && connectionOf(answer) && has("after", "String") + const pagination: Pagination | undefined = pages + ? { + style: "cursor", + cursor: { in: "body", name: "after" }, + next: "pageInfo.endCursor", + items: "nodes", + hasMore: "pageInfo.hasNextPage", + ...(has("first", "Int") ? { limit: { in: "body" as const, name: "first" } } : {}), + } + : undefined + const summary = field.description?.split("\n")[0] + operations.push({ + id: field.name, + binding, + ...(summary ? { summary } : {}), + ...described(field.description), + tags: [operation], + parameters: field.args.map((one) => ({ + name: one.name, + in: "body" as const, + required: required.includes(one), + ...described(one.description), + schema: argument(one), + })), + ...(field.args.length > 0 + ? { + requestBody: { + confidence: "contract" as const, + required: required.length > 0, + schema: inputObject(field.args, where), + }, + } + : {}), + response: { confidence: "contract", required: false, schema: answerOf(reference(field.type, where)) }, + effect: operation === "query" ? "read" : deletes ? "destructive" : "write", + ...(deletes ? { effectReason: GRAPHQL_DELETE_REASON } : {}), + ...(pagination ? { pagination, paginationSource: "detected" } : {}), + ...(field.isDeprecated ? { deprecated: true } : {}), + source: { location: where }, + }) + } + } + const stale = Object.keys(exclude).filter((name) => !excluded.has(name)) + if (stale.length > 0) + throw new CodegenError(stale.map((name) => `exclusion "${name}" matches no field of Query or Mutation`)) + + return { + source: { + kind: "other", + sourceUrl: options.sourceUrl ?? options.url, + ...(options.sourceRevision !== undefined ? { sourceRevision: options.sourceRevision } : {}), + }, + operations: operations.sort((a, b) => a.id.localeCompare(b.id)), + schemas, + servers: [{ url: options.url }], + } +} + +/** The standard introspection query, deep enough for `[[Type!]!]!`. */ +export const INTROSPECTION_QUERY = `query IntrospectionQuery { + __schema { + queryType { name } + mutationType { name } + types { + kind name description + fields(includeDeprecated: true) { name description isDeprecated args { ...InputValue } type { ...TypeRef } } + inputFields { ...InputValue } + enumValues(includeDeprecated: true) { name } + possibleTypes { name } + } + } +} +fragment InputValue on __InputValue { name description defaultValue type { ...TypeRef } } +fragment TypeRef on __Type { + kind name + ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } +}` + +const FILE = "schema.json" + +export interface GraphqlProvenance { + source: string + /** Of the committed file; `readGraphql` refuses a snapshot that no longer matches it. */ + sha256: string + retrieved_at: string + normalization: string +} + +const sha256 = (bytes: string | Buffer): string => createHash("sha256").update(bytes).digest("hex") + +const sortKeys = (value: unknown): unknown => + Array.isArray(value) + ? value.map(sortKeys) + : object(value) + ? Object.fromEntries( + Object.keys(value) + .sort() + .map((key) => [key, sortKeys(value[key])]), + ) + : value + +const byName = (list: unknown): unknown => + Array.isArray(list) + ? [...list].sort((a, b) => String((a as Json)?.name).localeCompare(String((b as Json)?.name))) + : list + +/** + * Asks `url` for its schema and writes `schema.json` and `provenance.json` to `dir`. Run by hand, then review the diff: + * the build never fetches. Types are sorted by name so a reordered answer is no diff. `headers` is for a service that + * answers introspection only when signed in; nothing of them is written. + */ +export const syncGraphql = async (options: { + url: string + dir: string + fetch?: typeof globalThis.fetch + headers?: Readonly> + now?: Date +}): Promise => { + const fetch = options.fetch ?? globalThis.fetch + const response = await fetch(options.url, { + method: "POST", + headers: { "content-type": "application/json", ...options.headers }, + body: JSON.stringify({ query: INTROSPECTION_QUERY }), + signal: AbortSignal.timeout(30_000), + redirect: "error", + }) + if (!response.ok) throw new Error(`GraphQL introspection failed: HTTP ${response.status}`) + const answer: unknown = await response.json() + if (object(answer) && Array.isArray(answer.errors) && answer.errors.length > 0) + throw new Error("GraphQL introspection failed: the service answered errors[]; it may need a sign-in") + const schema = schemaOf(answer) + const written = `${JSON.stringify(sortKeys({ __schema: { ...schema, types: byName(schema.types) } }), null, 2)}\n` + const provenance: GraphqlProvenance = { + source: options.url, + sha256: sha256(written), + retrieved_at: (options.now ?? new Date()).toISOString(), + normalization: "types sorted by name, object keys sorted, 2-space JSON", + } + mkdirSync(options.dir, { recursive: true }) + writeFileSync(join(options.dir, FILE), written) + writeFileSync(join(options.dir, "provenance.json"), `${JSON.stringify(provenance, null, 2)}\n`) + return provenance +} + +/** The snapshot `syncGraphql` wrote, parsed. Throws if its hash changed. */ +export const readGraphql = (dir: string): unknown => { + const provenance = JSON.parse(readFileSync(join(dir, "provenance.json"), "utf8")) as { sha256?: string } + const raw = readFileSync(join(dir, FILE)) + if (sha256(raw) !== provenance.sha256) throw new CodegenError([`GraphQL schema hash mismatch: ${join(dir, FILE)}`]) + return JSON.parse(raw.toString("utf8")) +} diff --git a/src/codegen/index.ts b/src/codegen/index.ts index 1c35b27..7d90c5c 100644 --- a/src/codegen/index.ts +++ b/src/codegen/index.ts @@ -3,7 +3,7 @@ * manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated * files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and * adds no runtime dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery - * documents the consumer has parsed; `upgradeToOpenApi3` brings Swagger 1.2 and 2.0 to OpenAPI 3 through two optional + * documents the consumer has parsed, and `adaptGraphql` a GraphQL introspection result; `upgradeToOpenApi3` brings Swagger 1.2 and 2.0 to OpenAPI 3 through two optional * peer dependencies. `fakeApi` serves the generated manifest as a strict fake for a CLI's tests, and `signInRequirements` with * `signInPlace` say which sign-in a call needs and where its token goes. An adapter from * Postman or anything else lives in the consumer. @@ -28,6 +28,26 @@ export { sampleOf, schemaProblems, } from "./fake.js" +export { + adaptGraphql, + GRAPHQL_DELETE_REASON, + type GraphqlOptions, + type GraphqlProvenance, + graphqlDocument, + INTROSPECTION_QUERY, + parseSelection, + readGraphql, + type Selection, + syncGraphql, +} from "./graphql.js" +export { + type GraphqlFake, + type GraphqlFakeAnswer, + type GraphqlFakeCall, + type GraphqlFakeOptions, + graphqlFake, + selectionProblems, +} from "./graphql-fake.js" export { requestSchema } from "./json-schema.js" export { type CoverageOptions, @@ -51,6 +71,7 @@ export type { Discriminator, Effect, GeneratedArtifact, + GraphqlBinding, HttpBinding, HttpMethod, OAuthFlow, @@ -65,7 +86,7 @@ export type { SourceInfo, SourceReference, } from "./model.js" -export { identifier, kebab } from "./names.js" +export { bindingLabel, identifier, kebab } from "./names.js" export { adaptOpenApi, OpenApiError } from "./openapi.js" export { detectPagination } from "./pagination.js" export { type PatchedSpec, type PatchSpecOptions, patchSpec, type SpecPatch } from "./patch.js" diff --git a/src/codegen/manifest.ts b/src/codegen/manifest.ts index 509a574..41c5e6a 100644 --- a/src/codegen/manifest.ts +++ b/src/codegen/manifest.ts @@ -10,7 +10,7 @@ import type { SchemaNode, SecurityRequirement, } from "./model.js" -import { kebab } from "./names.js" +import { bindingLabel, kebab } from "./names.js" import { isLossless } from "./runtime.js" import { SchemaTree } from "./tree.js" @@ -185,8 +185,7 @@ export const coverageGenerator = const tree = new SchemaTree(model) const rows = model.operations.map((operation) => { const entry = toManifest(operation, tree) - const binding = - entry.binding.kind === "http" ? `${entry.binding.method} ${entry.binding.path}` : entry.binding.name + const binding = bindingLabel(entry.binding) const status = entry.deprecated ? "deprecated" : "generated" return `| \`${entry.id}\` | \`${binding}\` | \`${options.command(entry)}\` | ${entry.effect} | ${ entry.request?.confidence ?? "—" diff --git a/src/codegen/model.ts b/src/codegen/model.ts index b48333b..24b2e9a 100644 --- a/src/codegen/model.ts +++ b/src/codegen/model.ts @@ -28,7 +28,21 @@ export interface RpcBinding { name: string } -export type Binding = HttpBinding | RpcBinding +/** + * One field of a GraphQL schema's `Query` or `Mutation`. The request is one document, built by `graphqlDocument` from + * the field, its variables' GraphQL types and a selection; the answer is `data.`. + */ +export interface GraphqlBinding { + kind: "graphql" + operation: "query" | "mutation" + field: string + /** Each argument's GraphQL type as written in the schema: `{ id: "String!", filter: "IssueFilter" }`. */ + variables: Readonly> + /** The default selection: scalars, and `{ id }` of each object, one level deep; a connection's `nodes` and `pageInfo`. */ + selection: string +} + +export type Binding = HttpBinding | RpcBinding | GraphqlBinding interface SchemaCommon { sensitive?: boolean diff --git a/src/codegen/names.ts b/src/codegen/names.ts index 0cd8f5f..b1f894b 100644 --- a/src/codegen/names.ts +++ b/src/codegen/names.ts @@ -1,3 +1,5 @@ +import type { Binding } from "./model.js" + const pascal = (text: string): string => text .split(/[^A-Za-z0-9]+/) @@ -47,3 +49,11 @@ export const kebab = (id: string): string => .replace(/[^A-Za-z0-9]+/g, "-") .replace(/^-|-$/g, "") .toLowerCase() + +/** How a reader names the call: `GET /pages/{id}`, `sendMessage`, `query issues`. */ +export const bindingLabel = (binding: Binding): string => + binding.kind === "http" + ? `${binding.method} ${binding.path}` + : binding.kind === "rpc" + ? binding.name + : `${binding.operation} ${binding.field}` diff --git a/src/codegen/pipeline.ts b/src/codegen/pipeline.ts index 9c1dc99..0a2c20b 100644 --- a/src/codegen/pipeline.ts +++ b/src/codegen/pipeline.ts @@ -14,7 +14,7 @@ import type { SecurityRequirement, SecurityScheme, } from "./model.js" -import { identifier, kebab } from "./names.js" +import { bindingLabel, identifier, kebab } from "./names.js" import { answerPaths, detectPagination, requestParameters } from "./pagination.js" import { signInRequirements } from "./sign-in.js" @@ -296,9 +296,7 @@ const applyAuth = (model: ApiModel, auth: AuthOverride): ApiModel => { } const bindingKey = (operation: ApiOperation): string => - operation.binding.kind === "http" - ? `${operation.binding.method} ${operation.binding.path}` - : `rpc ${operation.binding.name}` + operation.binding.kind === "rpc" ? `rpc ${operation.binding.name}` : bindingLabel(operation.binding) const duplicates = (values: readonly string[]): string[] => [...new Set(values.filter((value, index) => values.indexOf(value) !== index))].sort() diff --git a/src/codegen/skill.ts b/src/codegen/skill.ts index 85a5808..a62c097 100644 --- a/src/codegen/skill.ts +++ b/src/codegen/skill.ts @@ -8,7 +8,7 @@ import type { CommandInfo, OptionInfo } from "../commands/registry.js" import { flatten } from "../commands/registry.js" import type { ManifestOperation } from "./manifest.js" import type { GeneratedArtifact, Pagination } from "./model.js" -import { kebab } from "./names.js" +import { bindingLabel, kebab } from "./names.js" import { CodegenError } from "./pipeline.js" export interface ApiSkillOptions { @@ -76,8 +76,7 @@ const flagRow = (option: OptionInfo) => `| ${code(option.flags, true)} | ${option.mandatory ? "yes" : "no"} | ${text(option.description)} |` const section = (operation: ManifestOperation, command: CommandInfo): string[] => { - const call = - operation.binding.kind === "http" ? `${operation.binding.method} ${operation.binding.path}` : operation.binding.name + const call = bindingLabel(operation.binding) const scopes = (operation.security ?? []).map((requirement) => Object.entries(requirement) .map(([scheme, list]) => (list.length > 0 ? `${scheme} (${list.join(", ")})` : scheme)) diff --git a/test/fixtures/graphql-tracker.ts b/test/fixtures/graphql-tracker.ts new file mode 100644 index 0000000..39d715d --- /dev/null +++ b/test/fixtures/graphql-tracker.ts @@ -0,0 +1,165 @@ +// A hand-made introspection result shaped like Linear's: Relay connections, an input object, an enum, a custom +// scalar, wrapped types, and Delete, Archive and Unarchive mutations. Not Linear's real schema. +type Ref = { kind: string; name: string | null; ofType: Ref | null } + +const named = (kind: string, name: string): Ref => ({ kind, name, ofType: null }) +const scalar = (name: string) => named("SCALAR", name) +const object = (name: string) => named("OBJECT", name) +const input = (name: string) => named("INPUT_OBJECT", name) +const nonNull = (of: Ref): Ref => ({ kind: "NON_NULL", name: null, ofType: of }) +const list = (of: Ref): Ref => ({ kind: "LIST", name: null, ofType: of }) + +const arg = (name: string, type: Ref, defaultValue: string | null = null) => ({ + name, + description: null, + type, + defaultValue, +}) +const field = (name: string, type: Ref, args: ReturnType[] = [], description: string | null = null) => ({ + name, + description, + args, + type, + isDeprecated: false, +}) +const type = (kind: string, name: string, rest: Record = {}) => ({ + kind, + name, + description: null, + fields: null, + inputFields: null, + enumValues: null, + possibleTypes: null, + ...rest, +}) +const page = [arg("first", scalar("Int"), "50"), arg("after", scalar("String"))] +const connection = (name: string, node: string) => + type("OBJECT", `${name}Connection`, { + fields: [field("nodes", nonNull(list(nonNull(object(node))))), field("pageInfo", nonNull(object("PageInfo")))], + }) + +export const trackerIntrospection = () => ({ + data: { + __schema: { + queryType: { name: "Query" }, + mutationType: { name: "Mutation" }, + types: [ + type("SCALAR", "String"), + type("SCALAR", "ID"), + type("SCALAR", "Int"), + type("SCALAR", "Float"), + type("SCALAR", "Boolean"), + type("SCALAR", "DateTime"), + type("OBJECT", "Query", { + fields: [ + field( + "issues", + nonNull(object("IssueConnection")), + [ + ...page, + arg("filter", input("IssueFilter")), + arg("includeArchived", scalar("Boolean")), + arg("orderBy", named("ENUM", "PaginationOrderBy")), + ], + "All issues.\nPaged.", + ), + field("issue", nonNull(object("Issue")), [arg("id", nonNull(scalar("String")))], "One issue by its id."), + field("teams", nonNull(object("TeamConnection")), page), + field("users", nonNull(object("UserConnection")), [...page, arg("includeArchived", scalar("Boolean"))]), + field("workflowStates", nonNull(object("WorkflowStateConnection")), page), + field("viewer", nonNull(object("User"))), + field("maybeIssue", object("Issue"), [arg("id", nonNull(scalar("String")))]), + field("recentIssues", nonNull(list(nonNull(object("Issue")))), [ + arg("limit", nonNull(scalar("Int")), "10"), + ]), + field("search", nonNull(list(nonNull(named("UNION", "SearchResult")))), [ + arg("term", nonNull(scalar("String"))), + ]), + ], + }), + type("OBJECT", "Mutation", { + fields: [ + field("issueCreate", nonNull(object("IssuePayload")), [arg("input", nonNull(input("IssueCreateInput")))]), + field("issueDelete", nonNull(object("DeletePayload")), [arg("id", nonNull(scalar("String")))]), + field("issueArchive", nonNull(object("ArchivePayload")), [arg("id", nonNull(scalar("String")))]), + field("issueUnarchive", nonNull(object("ArchivePayload")), [arg("id", nonNull(scalar("String")))]), + ], + }), + type("OBJECT", "Issue", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("identifier", nonNull(scalar("String"))), + field("title", nonNull(scalar("String"))), + field("description", scalar("String")), + field("priority", nonNull(scalar("Float"))), + field("createdAt", nonNull(scalar("DateTime"))), + field("updatedAt", nonNull(scalar("DateTime"))), + field("archivedAt", scalar("DateTime")), + field("state", nonNull(object("WorkflowState"))), + field("team", nonNull(object("Team"))), + field("assignee", object("User")), + field("labels", nonNull(object("IssueLabelConnection")), page), + field("history", nonNull(object("IssueLabelConnection")), [arg("since", nonNull(scalar("DateTime")))]), + { ...field("legacyKey", scalar("String")), isDeprecated: true }, + ], + }), + type("OBJECT", "WorkflowState", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("name", nonNull(scalar("String"))), + field("type", nonNull(scalar("String"))), + field("team", nonNull(object("Team"))), + ], + }), + type("OBJECT", "Team", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("key", nonNull(scalar("String"))), + field("name", nonNull(scalar("String"))), + ], + }), + type("OBJECT", "User", { + fields: [ + field("id", nonNull(scalar("ID"))), + field("name", nonNull(scalar("String"))), + field("email", nonNull(scalar("String"))), + field("active", nonNull(scalar("Boolean"))), + ], + }), + type("OBJECT", "IssueLabel", { + fields: [field("id", nonNull(scalar("ID"))), field("name", nonNull(scalar("String")))], + }), + type("OBJECT", "PageInfo", { + fields: [field("hasNextPage", nonNull(scalar("Boolean"))), field("endCursor", scalar("String"))], + }), + connection("Issue", "Issue"), + connection("Team", "Team"), + connection("User", "User"), + connection("WorkflowState", "WorkflowState"), + connection("IssueLabel", "IssueLabel"), + type("OBJECT", "IssuePayload", { + fields: [field("success", nonNull(scalar("Boolean"))), field("issue", object("Issue"))], + }), + type("OBJECT", "DeletePayload", { fields: [field("success", nonNull(scalar("Boolean")))] }), + type("OBJECT", "ArchivePayload", { fields: [field("success", nonNull(scalar("Boolean")))] }), + type("UNION", "SearchResult", { possibleTypes: [{ name: "Issue" }, { name: "Team" }] }), + type("ENUM", "PaginationOrderBy", { enumValues: [{ name: "createdAt" }, { name: "updatedAt" }] }), + type("INPUT_OBJECT", "IssueFilter", { + inputFields: [arg("updatedAt", input("DateComparator"))], + }), + type("INPUT_OBJECT", "DateComparator", { + inputFields: [arg("gt", scalar("DateTime")), arg("gte", scalar("DateTime"))], + }), + type("INPUT_OBJECT", "IssueCreateInput", { + inputFields: [ + arg("title", nonNull(scalar("String"))), + arg("teamId", nonNull(scalar("String"))), + arg("description", scalar("String")), + arg("priority", nonNull(scalar("Int")), "0"), + ], + }), + type("OBJECT", "__Schema", { fields: [] }), + ], + }, + }, +})