@voxgig/apidef 6.5.1 → 7.0.1

package/src/transform/graphql.ts

@@ -0,0 +1,311 @@
+/* Copyright (c) 2024-2026 Voxgig, MIT License */
+
+// Render the GraphQL wire data onto each point: the complete operation
+// document, its variable bindings, the response unwrap path, and (for list
+// ops) the pagination descriptor.
+//
+// Documents are computed HERE, once, and stored in the model as strings.
+// The alternative — shipping structured selection data and assembling query
+// text inside every generated SDK — would mean one query assembler per
+// language target, all of which must stay semantically identical. One
+// renderer in apidef is the whole reason GraphQL support stays affordable
+// across the target matrix.
+//
+// Documents are rendered SINGLE-LINE with sorted selection fields, so the
+// emitted model is byte-stable and schema drift shows up in model diffs.
+
+import { each } from 'jostraca'
+
+import type { TransformResult, Transform } from '../transform'
+
+import { KIT } from '../types'
+
+import type { KitModel, GuidePath } from '../types'
+
+import type {
+  OpName,
+  ModelOp,
+  ModelEntity,
+  ModelPoint,
+  ModelGraphqlVar,
+} from '../model'
+
+import { deriveRetShape } from '../guide/graphql01'
+
+
+// Fields the default fragment never selects on a to-one relation: the stub
+// carries the id only, so the caller loads the related entity through its
+// own entity op.
+const REL_STUB = '{ id }'
+
+
+function pascal(s: string): string {
+  return s.replace(/(^|[_-])([a-z])/g, (_m, _p, c) => c.toUpperCase())
+}
+
+
+// Build the selection set for an entity type: every non-deprecated scalar,
+// skipping fields that require arguments (they cannot appear in a fixed
+// fragment without binding those arguments), plus an id stub per to-one
+// relation. Sorted — byte-stability.
+function selectionFields(typeName: string, def: any): string[] {
+  const gtype = def.types?.[typeName]
+  if (null == gtype) {
+    return []
+  }
+
+  const out: string[] = []
+
+  for (const fname of Object.keys(gtype.fields)) {
+    const f = gtype.fields[fname]
+
+    if (f.deprecated) {
+      continue
+    }
+    if (f.args.some((a: any) => a.reqd)) {
+      continue
+    }
+
+    const ftype = def.types?.[f.type]
+    const kind = ftype?.kind
+
+    if ('SCALAR' === kind || 'ENUM' === kind) {
+      out.push(fname)
+    }
+    else if (('OBJECT' === kind || 'INTERFACE' === kind) && !f.list) {
+      if (null != ftype.fields?.id) {
+        out.push(fname + ' ' + REL_STUB)
+      }
+    }
+  }
+
+  return out.sort()
+}
+
+
+// Scalar fields of a payload type, for payloads that carry no entity. Used
+// when there is nothing to spread a fragment on, so the operation still has
+// a valid selection set.
+function payloadScalarFields(typeName: string, def: any): string[] {
+  const gtype = def.types?.[typeName]
+  if (null == gtype) {
+    return []
+  }
+
+  const out: string[] = []
+
+  for (const fname of Object.keys(gtype.fields)) {
+    const f = gtype.fields[fname]
+    const kind = def.types?.[f.type]?.kind
+
+    if (!f.deprecated && !f.args.some((a: any) => a.reqd) &&
+      ('SCALAR' === kind || 'ENUM' === kind)) {
+      out.push(fname)
+    }
+  }
+
+  return out.sort()
+}
+
+
+// Variable bindings for a root field: one per argument. `from` is the op
+// argument the value is read from; for the input-object argument that is the
+// request data itself.
+function buildVars(fielddef: any, def: any): ModelGraphqlVar[] {
+  const args = fielddef?.args ?? []
+
+  // The whole-request-body binding is the SINGLE-entity-input convention
+  // (issueCreate(input: IssueCreateInput!)). A field taking several input
+  // objects — items(filter: Filter, orderBy: OrderBy) — must bind each from
+  // its own argument, or they all receive the same value and at least one
+  // fails input validation.
+  const inputs = args.filter((a: any) => {
+    const atype = def.types?.[a.type]
+    return null != atype && 'INPUT_OBJECT' === atype.kind
+  })
+  const soleInput = 1 === inputs.length ? inputs[0].name : undefined
+
+  return args.map((arg: any) => {
+    const v: any = {
+      name: arg.name,
+      from: arg.name === soleInput ? '' : arg.name,
+      gqltype: arg.gqltype,
+    }
+    if (undefined !== arg.deflt) {
+      v.deflt = arg.deflt
+    }
+    return v
+  })
+}
+
+
+// `issue(id: $id, first: $first)` — argument list wired to variables.
+function argList(vars: ModelGraphqlVar[]): string {
+  return 0 === vars.length ? '' :
+    '(' + vars.map((v) => v.name + ': $' + v.name).join(', ') + ')'
+}
+
+
+// `($id: String!, $first: Int = 100)` — the operation's variable
+// declarations. A schema default is carried through: without it a non-null
+// argument that the schema makes omittable (`first: Int! = 100`) would fail
+// variable coercion when the caller leaves it out.
+function varDecl(vars: ModelGraphqlVar[]): string {
+  return 0 === vars.length ? '' :
+    '(' + vars.map((v) => '$' + v.name + ': ' + v.gqltype +
+      (undefined === (v as any).deflt ? '' :
+        ' = ' + JSON.stringify((v as any).deflt))).join(', ') + ')'
+}
+
+
+// Render one operation document, single-line.
+function renderDoc(
+  opname: string,
+  optype: string,
+  field: string,
+  vars: ModelGraphqlVar[],
+  selection: string,
+  fragName: string,
+  fragType: string,
+  fragFields: string[]
+): string {
+  const doc =
+    optype + ' ' + opname + varDecl(vars) +
+    ' { ' + field + argList(vars) + ' ' + selection + ' }' +
+    (0 < fragFields.length ?
+      ' fragment ' + fragName + ' on ' + fragType +
+      ' { ' + fragFields.join(' ') + ' }' : '')
+
+  // Collapse any accidental double spacing so the string is canonical.
+  return doc.replace(/\s+/g, ' ').trim()
+}
+
+
+const graphqlTransform: Transform = async function(
+  ctx: any,
+): Promise<TransformResult> {
+  const { apimodel, def, guide } = ctx
+
+  if (true !== def?.graphql) {
+    return { ok: true, msg: 'graphql (skipped: not a graphql def)' }
+  }
+
+  const kit: KitModel = apimodel.main[KIT]
+
+  let msg = 'graphql '
+
+  each(kit.entity, (ment: ModelEntity, entname: string) => {
+    const gent = guide.entity[entname]
+
+    each(ment.op, (mop: ModelOp, opname: OpName) => {
+      each(mop.points, (mpoint: ModelPoint) => {
+        const rootfield = mpoint.orig
+
+        const gfield: GuidePath | undefined = (gent as any)?.field?.[rootfield]
+        const optype = (gfield?.op?.[opname] as any)?.optype ?? 'query'
+
+        const fielddef = 'mutation' === optype ?
+          def.mutation?.[rootfield] : def.query?.[rootfield]
+
+        if (null == fielddef) {
+          return
+        }
+
+        const ret = deriveRetShape(fielddef, def.types ?? {})
+        const entityType = ret.entity ?? ''
+
+        const fragFields = selectionFields(entityType, def)
+        const fragName = pascal(entname) + 'Fields'
+        const fragSpread = 0 < fragFields.length ? '{ ...' + fragName + ' }' : '{ id }'
+
+        const vars = buildVars(fielddef, def)
+
+        // Selection shape and response unwrap both follow the return kind.
+        let selection = fragSpread
+        let respath = 'body.data.' + rootfield
+
+        if ('connection' === ret.kind) {
+          const nodes = ret.nodes ?? 'nodes'
+          selection = 'nodes' === nodes ?
+            '{ nodes ' + fragSpread + ' pageInfo { endCursor hasNextPage } }' :
+            '{ edges { node ' + fragSpread + ' } pageInfo { endCursor hasNextPage } }'
+          respath = 'body.data.' + rootfield + '.' + nodes
+        }
+        else if ('list' === ret.kind) {
+          selection = fragSpread
+        }
+        else if ('payload' === ret.kind && null == ret.entity) {
+          // Entity-less payload: Linear's DeletePayload is entityId +
+          // success + lastSyncId and nothing else. The classifier admits
+          // these (the entity comes from the field name), so the renderer
+          // must not fall through to the default `{ id }` spread — the
+          // payload HAS no id, and the server rejects the whole document.
+          // Select the payload's own scalars and unwrap to the payload.
+          const own = payloadScalarFields(fielddef.type, def)
+          selection = '{ ' + (0 < own.length ? own.join(' ') : '__typename') + ' }'
+          respath = 'body.data.' + rootfield
+        }
+        else if ('payload' === ret.kind && null != ret.unwrap) {
+          // Mutation payload wrapper: select the entity inside it (plus the
+          // conventional success flag when present) and unwrap on the way
+          // back, so create/update return the entity exactly as REST does.
+          const payloadType = def.types?.[fielddef.type]
+          const hasSuccess = null != payloadType?.fields?.success
+          selection = '{ ' + ret.unwrap + ' ' + fragSpread +
+            (hasSuccess ? ' success' : '') + ' }'
+          respath = 'body.data.' + rootfield + '.' + ret.unwrap
+        }
+
+        // Distinct operation name per point. The action comes from the GUIDE,
+        // not from mpoint.select: selectTransform runs after this stage, so
+        // $action is not set yet, and without the suffix every action point
+        // on an op would ship the same operation name (three PlanetUpdates),
+        // which is what server logs, tracing and APM key on.
+        const actionName = Object.keys((gfield as any)?.action ?? {})[0]
+        const docname = pascal(entname) + pascal(opname) +
+          (null != actionName ? pascal(actionName) : '')
+
+        // GraphQL points ride the HTTP machinery: POST to the single
+        // endpoint, no path parts. The document carries everything else.
+        mpoint.kind = 'graphql'
+        mpoint.method = 'POST'
+        mpoint.parts = []
+
+        mpoint.graphql = {
+          optype: optype as 'query' | 'mutation',
+          field: rootfield,
+          doc: renderDoc(docname, optype, rootfield, vars, selection,
+            fragName, entityType, fragFields),
+          vars,
+        }
+
+        // Carried for the field transform, which derives entity fields from
+        // the same object type. The `$` suffix makes cleanTransform strip it
+        // from the emitted model — it is pipeline state, not wire data.
+        ;(mpoint.graphql as any).entityType$ = entityType
+
+        if ('connection' === ret.kind) {
+          mpoint.graphql.page = {
+            style: 'relay',
+            nodes: ret.nodes ?? 'nodes',
+            cursor: 'pageInfo.endCursor',
+            more: 'pageInfo.hasNextPage',
+          }
+        }
+
+        mpoint.transform.res = '`' + respath + '`'
+      })
+    })
+
+    msg += ment.name + ' '
+  })
+
+  return { ok: true, msg }
+}
+
+
+export {
+  graphqlTransform,
+  selectionFields,
+  renderDoc,
+}

package/src/transform/select.ts

@@ -37,7 +37,9 @@ const selectTransform: Transform = async function(
   each(kit.entity, (ment: ModelEntity, _entname: string) => {
     each(ment.op, (mop: ModelOp, _opname: OpName) => {
       each(mop.points, (mpoint: ModelPoint) => {
-        const pdef: PathDef = def.paths[mpoint.orig]
+        // GraphQL defs have no `paths`; the lookup is only passed through to
+        // an unused parameter, so skip it rather than dereference undefined.
+        const pdef: PathDef = def.paths?.[mpoint.orig]
         resolveSelect(guide, ment, mop, mpoint, pdef)
       })
       if (null != mop.points && 0 < mop.points.length) {
@@ -64,8 +66,18 @@ function resolveSelect(
 
   const argkinds = ['params', 'query', 'header', 'cookie']
 
+  // `exist` names values that must be PRESENT for this point to be chosen.
+  // A GraphQL root field exposes its optional arguments (relay's first /
+  // after, filters) as params, and requiring those for selection would make
+  // list() unusable without supplying every pagination argument. Only
+  // required arguments identify a point.
+  const reqdonly = 'graphql' === (mpoint as any).kind
+
   argkinds.map((kind: string) => {
     each(margs[kind], (marg: ModelArg) => {
+      if (reqdonly && !marg.reqd) {
+        return
+      }
       if (!select.exist.includes(marg.name)) {
         select.exist.push(marg.name)
       }
@@ -75,7 +87,12 @@ function resolveSelect(
   select.exist.sort()
 
   const gent = guide.entity[ment.name]
-  const gpath = gent.path[mpoint.orig]
+  // REST guides key entries by path, GraphQL guides by root field.
+  const gpath = gent.path?.[mpoint.orig] ?? (gent as any).field?.[mpoint.orig]
+
+  if (null == gpath) {
+    return
+  }
 
   if (gpath.action) {
     const actname = Object.keys(gpath.action).sort()[0]

package/src/transform/top.ts

@@ -59,7 +59,31 @@ const topTransform = async function(
   // spec DOES declare auth we leave `auth` unset so the SDK's own config
   // (main.kit.config.auth) governs. Set AFTER stringifyInfoScalars so the
   // value stays a real boolean rather than the string "false".
-  if (!specDeclaresAuth(def)) {
+  if (true === def.graphql) {
+    // A GraphQL schema NEVER declares HTTP auth, so specDeclaresAuth would
+    // report every secured GraphQL API (Linear included) as public and
+    // suppress all generated auth code. Take the explicit build option
+    // instead: only an option that actively says "public" emits the no-auth
+    // signal; silence leaves auth unset so the SDK's own config governs.
+    const authopt = ctx.opts?.auth
+    if (null != authopt) {
+      if (false === authopt.active) {
+        kit.info.auth = false
+      }
+      else {
+        kit.info.security = {
+          scheme: authopt.scheme ?? 'apikey',
+          type: authopt.type ?? 'apiKey',
+          in: authopt.in ?? 'header',
+          name: authopt.name ?? 'Authorization',
+          // '' means a raw credential with no prefix (Linear's style);
+          // prepareAuth in generated SDKs already honours that.
+          prefix: authopt.prefix ?? '',
+        }
+      }
+    }
+  }
+  else if (!specDeclaresAuth(def)) {
     kit.info.auth = false
   }
   else {
@@ -105,10 +129,15 @@ const topTransform = async function(
   // Swagger 2 derives it from `host` + `basePath`. If neither yields a
   // non-empty url, the generated SDK has no way to issue requests, so fail
   // the apidef model build rather than emit broken code.
+  // (For GraphQL the parser already synthesised servers[0] from the required
+  // `endpoint` build option, so this check passes on the same terms.)
   const firstServerUrl: any = kit.info.servers?.[0]?.url
   if (null == firstServerUrl || '' === String(firstServerUrl).trim()) {
     throw new Error(
-      'apidef: no server URL found in API definition (servers[0].url is required).'
+      true === def.graphql ?
+        'apidef: no endpoint given for GraphQL schema' +
+        ' (the endpoint build option is required).' :
+        'apidef: no server URL found in API definition (servers[0].url is required).'
     )
   }
 

package/src/types.ts

@@ -33,11 +33,41 @@ type ApiDefOptions = {
   meta?: Record<string, any>
   outprefix?: string
   strategy?: string
+
+  // Input format. Defaults to 'OpenAPI'; sniffed from the def file name
+  // when not given (see resolveKind in apidef.ts).
+  kind?: DefKind
+
+  // GraphQL-only build inputs. A GraphQL schema carries neither a
+  // deployment URL nor an HTTP auth declaration, so both must be supplied
+  // out of band (see docs/design/graphql-ingestion.md).
+  endpoint?: string
+  auth?: ApiDefAuthOption
+
   why?: {
     show?: boolean
   }
 }
 
+
+// Input definition format.
+type DefKind = 'OpenAPI' | 'GraphQL'
+
+
+// Auth descriptor for schema formats that cannot declare their own. When
+// omitted for a GraphQL build, no auth signal is emitted either way, so the
+// SDK's own config governs; set `active: false` to state a public API
+// explicitly (which suppresses generated auth code, as an OpenAPI spec with
+// no security schemes does).
+type ApiDefAuthOption = {
+  active?: boolean
+  scheme?: string
+  type?: string
+  in?: string
+  name?: string
+  prefix?: string
+}
+
 const ControlShape = Shape({
   step: {
     parse: true,
@@ -207,6 +237,8 @@ type GuideControl = {}
 type GuideMetrics = {
   count: {
     path: number
+    // Schema root fields classified (GraphQL guides; 0 for OpenAPI).
+    field: number
     method: number
     entity: number
     tag: number
@@ -223,6 +255,9 @@ type GuideMetrics = {
 type GuideEntity = {
   name: string
   orig: string
+  // GraphQL guides key operations by schema root field instead of path;
+  // the two branches are mutually exclusive per guide.
+  field?: Record<string, GuidePath>
   path: Record<string, GuidePath>
 }
 
@@ -247,6 +282,9 @@ type GuideRenameParam = {
 
 type GuidePathOp = {
   method: string
+  // GraphQL root-field ops carry the operation type instead of relying on
+  // an HTTP verb (points still synthesize method 'POST').
+  optype?: string
   why_op: string[]
   transform: {
     req: any
@@ -280,6 +318,8 @@ export type {
   Log,
   FsUtil,
   ApiDefOptions,
+  DefKind,
+  ApiDefAuthOption,
   ApiDefResult,
   Control,
   Model,

package/src/utility.ts

@@ -1012,6 +1012,36 @@ function canonize(s: string) {
 }
 
 
+// Canonicalise a FIELD name — which is a WIRE identifier, not a type name.
+//
+// `canonize` is right for entity/type names: it snakifies and depluralizes so
+// `Users` and `user-items` converge on `user` / `user_item`. Applied to a
+// field it is actively WRONG, because the name has to match the JSON the
+// server actually sends:
+//
+//   modelType   -> canonize -> model_type    (server sends modelType)
+//   items       -> canonize -> item          (server sends items)
+//
+// Nothing maps back: the model's `alias.field` map is emitted empty and no
+// generator consumes it, so the wire name is simply lost. Across the fleet's
+// specs that renamed 23% of all fields (146 repos) and depluralized another
+// 13% — every one of those SDKs reading a key the server never sends.
+//
+// So: keep the transliteration and identifier sanitisation that stop a name
+// being unusable in a target language, and drop the snakify/depluralize that
+// change what the name MEANS. Case and plurality are preserved verbatim.
+const CANONIZE_FIELD_CACHE = new Map<string, string>()
+
+function canonizeField(s: string) {
+  if (null == s || '' === s) return ''
+  const cached = CANONIZE_FIELD_CACHE.get(s)
+  if (undefined !== cached) return cached
+  const out = transliterate(s).replace(/[^a-zA-Z_0-9]/g, '')
+  CANONIZE_FIELD_CACHE.set(s, out)
+  return out
+}
+
+
 // Namespace-qualified schema names (ASP.NET / Java style:
 // "NoFrixion.MoneyMoov.Models.PaymentRequests.MerchantPayment",
 // "com.example.api.Payment") describe the type by their LAST dotted
@@ -1551,16 +1581,35 @@ function isEntityWrapperProp(propSchema: any): boolean {
 // signal, and is still checked first.
 function envelopeProp(resprops: any, opname: string): string | null {
   const keys = keysof(resprops)
-  if (1 !== keys.length) {
+  if (0 === keys.length) {
     return null
   }
 
-  const key = keys[0]
-  const prop = resprops[key]
-  if (!isEntityWrapperProp(prop)) {
+  // Exactly one STRUCTURED property, with any siblings being scalars.
+  //
+  // The original rule demanded exactly one property full stop, which missed
+  // the single most common envelope shape in the wild:
+  //
+  //   { "success": true, "data": [ ... ] }
+  //   { "status": "ok",  "result": { ... } }
+  //
+  // A boolean/string status flag beside the payload is metadata, not a
+  // sibling of equal standing, so the body is still an envelope. UniVec's
+  // /v1/models returns exactly this and every generated SDK — TypeScript, Go,
+  // Python alike — returned an empty list against an API plainly serving
+  // data.
+  //
+  // Scalar-only siblings keep the guard meaningful: `{ok, id}` from a delete
+  // has no structured member and is still handed over whole, and a body with
+  // TWO structured members is a composite we must not guess at.
+  const structured = keys.filter((k: string) => isEntityWrapperProp(resprops[k]))
+  if (1 !== structured.length) {
     return null
   }
 
+  const key = structured[0]
+  const prop = resprops[key]
+
   const islist = propIsList(prop)
   if (null == islist || islist !== ('list' === opname)) {
     return null
@@ -1666,6 +1715,7 @@ export {
   VALID_CANON,
   CANON_ONE,
   canonize,
+  canonizeField,
   canonizeCmpName,
   stripSchemaNamespace,
   sanitizeSlug,