@voxgig/apidef 6.5.0 → 7.0.0

package/src/model.ts

@@ -90,13 +90,54 @@ type ModelArg = {
 }
 
 
-// One concrete HTTP endpoint that can satisfy an operation. An entity op
+// Transport a point speaks. 'http' is the default and covers every
+// OpenAPI-derived point; 'graphql' points carry a `graphql` block instead
+// of relying on method+path (they synthesize method 'POST' and empty
+// parts so the HTTP-shaped machinery downstream keeps working unchanged).
+type PointKind = 'http' | 'graphql'
+
+
+// Pagination descriptor for a GraphQL list op. `nodes`/`cursor`/`more` are
+// dotted paths relative to the unwrapped connection object.
+type ModelGraphqlPage = {
+  style: string
+  nodes: string
+  cursor: string
+  more: string
+}
+
+
+// One GraphQL variable binding: `name` is the variable as it appears in the
+// operation document, `from` the op argument it is read from, `gqltype` the
+// declared GraphQL type (e.g. 'String!').
+type ModelGraphqlVar = {
+  name: string
+  from: string
+  gqltype: string
+}
+
+
+// GraphQL wire data for a point. `doc` is the complete operation document,
+// rendered single-line with sorted selection fields so output stays
+// byte-stable and schema drift shows up in model diffs.
+type ModelGraphql = {
+  optype: 'query' | 'mutation'
+  field: string
+  doc: string
+  vars: ModelGraphqlVar[]
+  page?: ModelGraphqlPage
+}
+
+
+// One concrete endpoint that can satisfy an operation. An entity op
 // (load/list/create/...) carries an array of these — apidef chooses
 // between them at runtime via `select.exist` matching against reqmatch /
 // reqdata. (Originally named `ModelTarget`; renamed for consistency with
 // the field name `points` and the runtime utility `MakePoint`.)
 type ModelPoint = {
   orig: string
+  kind?: PointKind
+  graphql?: ModelGraphql
   method: MethodName
   parts: string[]
   rename: Partial<{
@@ -210,6 +251,10 @@ type ModelEntityFlowStep = {
 export type {
   OpName,
   ArgKind,
+  PointKind,
+  ModelGraphql,
+  ModelGraphqlVar,
+  ModelGraphqlPage,
   NamesCluster,
   Model,
   ModelEntityRelations,

package/src/parse/graphql.ts

@@ -0,0 +1,302 @@
+/* Copyright (c) 2024-2026 Voxgig, MIT License */
+
+// GraphQL ingestion: normalise an SDL document or an introspection result
+// into the plain `def` structure the guide and transform stages consume.
+//
+// The OpenAPI parser hands downstream stages the spec object itself, with
+// `$ref`s resolved in place. GraphQL has no equivalent literal document, so
+// this builds an explicit graph instead:
+//
+//   def.types    — every named type, keyed by type name
+//   def.query    — root Query fields, keyed by field name
+//   def.mutation — root Mutation fields, keyed by field name
+//   def.servers  — synthesised from the `endpoint` option (a schema carries
+//                  no deployment URL, but transform/top.ts requires one)
+//   def.info     — synthesised; SDL has no info block
+//
+// Type references are held as NAME STRINGS, never object pointers, so the
+// result is acyclic and JSON-serialisable by construction — GraphQL type
+// graphs are freely recursive (Issue.team.issues), and apidef writes
+// `<def>.full.json` under the debug flag.
+
+import { relativizePath } from '../utility'
+
+
+// A single argument on a root field or a type field.
+type GqlArg = {
+  name: string
+  gqltype: string    // rendered GraphQL type, e.g. 'String!' or '[Int!]'
+  type: string       // named (unwrapped) type, e.g. 'String'
+  reqd: boolean
+  deflt?: any
+}
+
+
+// A field on an object/interface type, or a root field.
+type GqlField = {
+  name: string
+  gqltype: string
+  type: string       // named (unwrapped) type
+  reqd: boolean
+  list: boolean
+  args: GqlArg[]
+  deprecated: boolean
+  desc?: string
+}
+
+
+// A named type in the schema. `fields` is present for OBJECT, INTERFACE and
+// INPUT_OBJECT kinds; `values` for ENUM; `possible` for UNION/INTERFACE.
+type GqlType = {
+  name: string
+  kind: string       // OBJECT | INPUT_OBJECT | ENUM | SCALAR | INTERFACE | UNION
+  fields: Record<string, GqlField>
+  values?: string[]
+  possible?: string[]
+  interfaces?: string[]
+  desc?: string
+}
+
+
+type GqlDef = {
+  graphql: true
+  info: Record<string, any>
+  servers: { url: string }[]
+  types: Record<string, GqlType>
+  query: Record<string, GqlField>
+  mutation: Record<string, GqlField>
+  subscription: Record<string, GqlField>
+}
+
+
+// `graphql` is an OPTIONAL peer dependency: REST-only consumers should not
+// have to install it. Resolve it lazily, and fail with an actionable message
+// rather than a bare MODULE_NOT_FOUND.
+function loadGraphQL(meta: { file: string }): any {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('graphql')
+  }
+  catch (err: any) {
+    throw new Error(
+      '@voxgig/apidef: parse: GraphQL: the "graphql" package is required to' +
+      ' parse GraphQL schemas - install it alongside @voxgig/apidef' +
+      ` (${relativizePath(meta.file)})`
+    )
+  }
+}
+
+
+// Introspection JSON arrives either bare (`{__schema:...}`) or wrapped in a
+// GraphQL response envelope (`{data:{__schema:...}}`).
+function asIntrospection(source: string): any {
+  const trimmed = source.trimStart()
+  if (!trimmed.startsWith('{')) {
+    return undefined
+  }
+
+  let parsed: any
+  try {
+    parsed = JSON.parse(source)
+  }
+  catch (err: any) {
+    return undefined
+  }
+
+  if (null != parsed?.__schema) {
+    return parsed
+  }
+  if (null != parsed?.data?.__schema) {
+    return parsed.data
+  }
+
+  return undefined
+}
+
+
+// Render a type reference to its GraphQL source form ('[Issue!]!') and its
+// named form ('Issue'), plus the required/list flags the classifier keys on.
+function describeType(G: any, gtype: any) {
+  const gqltype = String(gtype)
+  const named = G.getNamedType(gtype)
+  return {
+    gqltype,
+    type: named.name,
+    reqd: G.isNonNullType(gtype),
+    list: G.isListType(G.isNonNullType(gtype) ? gtype.ofType : gtype),
+  }
+}
+
+
+function buildArgs(G: any, gargs: any[]): GqlArg[] {
+  return (gargs || []).map((ga: any) => {
+    const d = describeType(G, ga.type)
+    const arg: GqlArg = {
+      name: ga.name,
+      gqltype: d.gqltype,
+      type: d.type,
+      reqd: d.reqd,
+    }
+    if (undefined !== ga.defaultValue && null !== ga.defaultValue) {
+      arg.deflt = ga.defaultValue
+    }
+    return arg
+  })
+}
+
+
+function buildField(G: any, gfield: any): GqlField {
+  const d = describeType(G, gfield.type)
+  const field: GqlField = {
+    name: gfield.name,
+    gqltype: d.gqltype,
+    type: d.type,
+    reqd: d.reqd,
+    list: d.list,
+    args: buildArgs(G, gfield.args),
+    deprecated: null != gfield.deprecationReason,
+  }
+  if (null != gfield.description && '' !== gfield.description) {
+    field.desc = gfield.description
+  }
+  return field
+}
+
+
+function fieldMap(G: any, gtype: any): Record<string, GqlField> {
+  const out: Record<string, GqlField> = {}
+  const gfields = gtype.getFields ? gtype.getFields() : {}
+  // Sorted: downstream output must be byte-stable.
+  for (const name of Object.keys(gfields).sort()) {
+    out[name] = buildField(G, gfields[name])
+  }
+  return out
+}
+
+
+function typeKind(G: any, gtype: any): string {
+  if (G.isObjectType(gtype)) return 'OBJECT'
+  if (G.isInputObjectType(gtype)) return 'INPUT_OBJECT'
+  if (G.isEnumType(gtype)) return 'ENUM'
+  if (G.isInterfaceType(gtype)) return 'INTERFACE'
+  if (G.isUnionType(gtype)) return 'UNION'
+  if (G.isScalarType(gtype)) return 'SCALAR'
+  return 'UNKNOWN'
+}
+
+
+function buildTypes(G: any, schema: any): Record<string, GqlType> {
+  const out: Record<string, GqlType> = {}
+  const typeMap = schema.getTypeMap()
+
+  for (const name of Object.keys(typeMap).sort()) {
+    // Introspection meta types (__Schema, __Type, ...) are not API surface.
+    if (name.startsWith('__')) {
+      continue
+    }
+
+    const gtype = typeMap[name]
+    const kind = typeKind(G, gtype)
+
+    const desc: GqlType = {
+      name,
+      kind,
+      fields: ('OBJECT' === kind || 'INTERFACE' === kind || 'INPUT_OBJECT' === kind) ?
+        fieldMap(G, gtype) : {},
+    }
+
+    if ('ENUM' === kind) {
+      desc.values = gtype.getValues().map((v: any) => v.name).sort()
+    }
+
+    if ('UNION' === kind) {
+      desc.possible = schema.getPossibleTypes(gtype).map((t: any) => t.name).sort()
+    }
+
+    if ('INTERFACE' === kind) {
+      desc.possible = schema.getPossibleTypes(gtype).map((t: any) => t.name).sort()
+    }
+
+    if ('OBJECT' === kind || 'INTERFACE' === kind) {
+      const ifaces = (gtype.getInterfaces ? gtype.getInterfaces() : [])
+        .map((t: any) => t.name).sort()
+      if (0 < ifaces.length) {
+        desc.interfaces = ifaces
+      }
+    }
+
+    if (null != gtype.description && '' !== gtype.description) {
+      desc.desc = gtype.description
+    }
+
+    out[name] = desc
+  }
+
+  return out
+}
+
+
+function rootFields(G: any, gtype: any): Record<string, GqlField> {
+  return null == gtype ? {} : fieldMap(G, gtype)
+}
+
+
+// Parse a GraphQL schema (SDL text or introspection JSON) into `def`.
+//
+// `opts.endpoint` is REQUIRED: a schema declares no deployment URL, but a
+// usable SDK needs a base URL and transform/top.ts fails the build without
+// `servers[0].url`.
+async function parseGraphQL(
+  source: string,
+  meta: { file: string },
+  opts?: { endpoint?: string, title?: string, version?: string }
+): Promise<GqlDef> {
+  const G = loadGraphQL(meta)
+
+  const endpoint = opts?.endpoint
+  if (null == endpoint || '' === String(endpoint).trim()) {
+    throw new Error(
+      '@voxgig/apidef: parse: GraphQL: an endpoint option is required' +
+      ' (a GraphQL schema declares no server URL)' +
+      ` (${relativizePath(meta.file)})`
+    )
+  }
+
+  let schema: any
+  const introspection = asIntrospection(source)
+
+  if (null != introspection) {
+    schema = G.buildClientSchema(introspection)
+  }
+  else {
+    schema = G.buildSchema(source)
+  }
+
+  const def: GqlDef = {
+    graphql: true,
+    info: {
+      title: opts?.title ?? '',
+      version: opts?.version ?? '',
+      description: '',
+    },
+    servers: [{ url: endpoint }],
+    types: buildTypes(G, schema),
+    query: rootFields(G, schema.getQueryType()),
+    mutation: rootFields(G, schema.getMutationType()),
+    subscription: rootFields(G, schema.getSubscriptionType()),
+  }
+
+  return def
+}
+
+
+export {
+  parseGraphQL,
+}
+
+export type {
+  GqlDef,
+  GqlType,
+  GqlField,
+  GqlArg,
+}

package/src/parse.ts

@@ -5,6 +5,8 @@ import { Yaml } from '@tabnas/yaml'
 
 import { relativizePath } from './utility'
 
+import { parseGraphQL } from './parse/graphql'
+
 
 // NOTE: @tabnas/yaml types its Plugin against @tabnas/parser, while
 // Jsonic.use expects @tabnas/jsonic's own (structurally identical) Plugin
@@ -46,6 +48,27 @@ async function parse(kind: string, source: any, meta: { file: string }) {
       throw pe
     }
   }
+  else if ('GraphQL' === kind) {
+
+    validateSource(kind, source, meta)
+
+    try {
+      const def = await parseGraphQL(source, meta, (meta as any).graphql)
+      return def
+    }
+    catch (pe: any) {
+      // Already-decorated errors (missing endpoint, missing package) carry
+      // the package prefix; only raw parser failures need wrapping.
+      if ('string' === typeof pe.message &&
+        !pe.message.startsWith('@voxgig/apidef:')) {
+        pe.message =
+          `@voxgig/apidef: parse: syntax: ${pe.message}` +
+          ` (${relativizePath(meta.file)})`
+      }
+
+      throw pe
+    }
+  }
   else {
     throw new Error(
       `@voxgig/apidef: parse: unknown kind: ${kind}` +

package/src/transform/args.ts

@@ -41,11 +41,35 @@ const argsTransform: Transform = async function(
       each(mop.points, (mpoint: ModelPoint) => {
         const argdefs: ParameterDef[] = []
 
-        const pathdef: PathDef = def.paths[mpoint.orig]
-        argdefs.push(...(pathdef.parameters ?? []))
-
-        const opdef: MethodDef = (pathdef as any)[mpoint.method.toLowerCase()]
-        argdefs.push(...(opdef?.parameters ?? []))
+        if ('graphql' === mpoint.kind) {
+          // GraphQL root-field arguments become 'param' args, so the existing
+          // arg machinery (select.exist matching, request typing, test
+          // generation) works on them unchanged. Input-object arguments are
+          // the request body and are bound as variables by the document
+          // renderer instead, so they are not surfaced as params here.
+          const fielddef: any = graphqlFieldDef(def, mpoint)
+          for (const arg of (fielddef?.args ?? [])) {
+            const argtype = def.types?.[arg.type]
+            if (null != argtype && 'INPUT_OBJECT' === argtype.kind) {
+              continue
+            }
+            argdefs.push({
+              name: arg.name,
+              in: 'path',
+              // A schema default makes a non-null argument omittable by the
+              // caller, so it is not required of the SDK caller either.
+              required: arg.reqd && undefined === arg.deflt,
+              schema: { type: gqlScalarType(arg.type) },
+            } as any)
+          }
+        }
+        else {
+          const pathdef: PathDef = def.paths[mpoint.orig]
+          argdefs.push(...(pathdef.parameters ?? []))
+
+          const opdef: MethodDef = (pathdef as any)[mpoint.method.toLowerCase()]
+          argdefs.push(...(opdef?.parameters ?? []))
+        }
 
         resolveArgs(ment, mop, mpoint, argdefs)
       })
@@ -59,6 +83,31 @@ const argsTransform: Transform = async function(
 }
 
 
+// Locate the normalised root-field descriptor a GraphQL point came from.
+function graphqlFieldDef(def: any, mpoint: ModelPoint): any {
+  const field = mpoint.graphql?.field ?? mpoint.orig
+  return 'mutation' === mpoint.graphql?.optype ?
+    def.mutation?.[field] : def.query?.[field]
+}
+
+
+// Map a GraphQL named type onto the JSON-schema-ish scalar names the
+// existing arg/field typing understands.
+//
+// Only the built-in scalars have a known JSON shape. A custom scalar can be
+// anything — JSON/JSONObject accept objects and arrays, DateTime is a
+// string, Upload is a file handle — so anything unrecognised stays
+// unconstrained rather than being wrongly advertised (and validated) as a
+// string. ID and String are the two custom-free string cases.
+function gqlScalarType(typeName: string): string | undefined {
+  return 'Int' === typeName ? 'integer' :
+    'Float' === typeName ? 'number' :
+      'Boolean' === typeName ? 'boolean' :
+        ('String' === typeName || 'ID' === typeName) ? 'string' :
+          undefined
+}
+
+
 const ARG_KIND: Record<string, ModelArg["kind"]> = {
   'query': 'query',
   'header': 'header',

package/src/transform/entity.ts

@@ -42,7 +42,10 @@ const entityTransform: Transform = async function(
   // ID. Move "/people" onto person here; this also clears the way for
   // sensible flow generation (one entity, one collection, multiple
   // sub-resources).
-  mergeCollectionPaths(guide, ctx.log)
+  // Path-shaped collection merging is meaningless for root-field guides.
+  if (true !== ctx.def?.graphql) {
+    mergeCollectionPaths(guide, ctx.log)
+  }
 
   each(guide.entity, (guideEntity: GuideEntity, entname: string) => {
     // `active: false` in guide.aontu drops the entity. The guide model has
@@ -58,8 +61,18 @@ const entityTransform: Transform = async function(
 
     ctx.log.debug({ point: 'guide-entity', note: entname })
 
-    const paths$ = resolvePathList(guideEntity, ctx.def)
-    const relations = buildRelations(guideEntity, paths$)
+    const graphql = true === ctx.def?.graphql
+
+    const paths$ = graphql ?
+      resolveFieldList(guideEntity, ctx.def) :
+      resolvePathList(guideEntity, ctx.def)
+
+    // Ancestry is inferred from literal/{param} path pairs, which root
+    // fields do not have; GraphQL relations come from the schema instead
+    // (see transform/graphql.ts).
+    const relations = graphql ?
+      { ancestors: [] } :
+      buildRelations(guideEntity, paths$)
 
     const modelent: ModelEntity = {
       name: entname,
@@ -214,6 +227,53 @@ function resolvePathList(guideEntity: GuideEntity, def: { paths: Record<string,
 }
 
 
+// Root-field equivalent of resolvePathList for GraphQL guides. A root field
+// has no path to split, so `parts` stays empty (GraphQL points address the
+// single endpoint and carry their operation document instead) and `def` is
+// the normalised root-field descriptor rather than a path item.
+function resolveFieldList(guideEntity: GuideEntity, def: any) {
+  const paths$: PathDesc[] = []
+
+  each((guideEntity as any).field, (guideField: GuidePath, orig: string) => {
+    if (!guideActive(guideField)) {
+      return
+    }
+
+    // The root field lives under query or mutation depending on the op type
+    // the guide recorded.
+    const optype = Object.values(guideField.op ?? {})
+      .map((o: any) => o.optype)
+      .find((t: any) => null != t) ?? 'query'
+
+    const fielddef = 'mutation' === optype ?
+      def.mutation?.[orig] : def.query?.[orig]
+
+    // The guide expresses GraphQL renames as `rename: arg:` (root fields
+    // have arguments, not path params), while the model's arg machinery
+    // reads `rename.param`. Translate so a user override actually applies.
+    const grename: any = guideField.rename ?? {}
+    const rename: any = null != grename.arg ?
+      { ...grename, param: { ...(grename.param ?? {}), ...grename.arg } } :
+      grename
+
+    const pathdesc: PathDesc = {
+      orig,
+      parts: [],
+      rename,
+      method: '', // operation collectOps will copy and assign per op
+      op: guideField.op,
+      def: fielddef,
+    }
+
+    paths$.push(pathdesc)
+  })
+
+    ; (guideEntity as any).paths$ = paths$
+
+  return paths$
+}
+
+
 
 function buildRelations(guideEntity: any, paths$: PathDesc[]) {
   // An ancestor is a literal collection segment (e.g. "rems") followed by

package/src/transform/field.ts

@@ -4,7 +4,7 @@ import { each, getx } from 'jostraca'
 
 import type { TransformResult, Transform } from '../transform'
 
-import { validator, canonize, inferFieldType, normalizeFieldName, envelopeProp } from '../utility'
+import { validator, canonizeField, inferFieldType, normalizeFieldName, envelopeProp } from '../utility'
 
 import { KIT } from '../types'
 
@@ -93,7 +93,10 @@ function resolveOpFields(
 
   for (let fielddef of fielddefs) {
     const fieldname = (fielddef as any).key$ as string
-    const name = canonize(normalizeFieldName(fieldname))
+    // Field names are WIRE identifiers — see canonizeField. Using the
+    // entity-name canonizer here renamed modelType -> model_type and
+    // items -> item, so the SDK read keys the server never sends.
+    const name = canonizeField(normalizeFieldName(fieldname))
     const mfield: ModelField = {
       name,
       type: inferFieldType(name, validator(fielddef.type)),
@@ -107,12 +110,96 @@ function resolveOpFields(
 }
 
 
+// GraphQL entity fields come straight from the object type: every
+// non-deprecated scalar field, minus any that require arguments (selecting
+// `download(format: Format!)` without binding its argument makes every
+// operation using the fragment fail GraphQL validation), plus one id-stub
+// reference per to-one relation.
+function findGraphqlFieldDefs(
+  ment: ModelEntity,
+  mpoint: ModelPoint,
+  def: any
+): SchemaDef[] {
+  const typeName = (mpoint.graphql as any)?.entityType$ ??
+    (ment as any).orig$ ?? ''
+  const gtype = def.types?.[typeName]
+
+  if (null == gtype) {
+    return []
+  }
+
+  const out: SchemaDef[] = []
+
+  // Sorted by construction in parse/graphql.ts, so output stays byte-stable.
+  for (const fname of Object.keys(gtype.fields)) {
+    const f = gtype.fields[fname]
+
+    if (f.deprecated) {
+      continue
+    }
+
+    // A field taking required arguments cannot appear in a fixed fragment.
+    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({
+        key$: fname,
+        // Enum values are always strings; scalars map by name, with unknown
+        // custom scalars left unconstrained.
+        type: 'ENUM' === kind ? 'string' : gqlFieldType(f.type),
+        required: f.reqd,
+      } as any)
+    }
+    else if (('OBJECT' === kind || 'INTERFACE' === kind) && !f.list) {
+      // To-one relation. The default fragment selects `team { id }`, so the
+      // response carries a nested stub object — declare it as such. Naming a
+      // flat `team_id` here would advertise a field the wire never returns,
+      // since nothing flattens the response.
+      const idField = ftype.fields?.id
+      if (null != idField) {
+        out.push({
+          key$: fname,
+          type: 'object',
+          required: false,
+        } as any)
+      }
+    }
+  }
+
+  return out
+}
+
+
+// GraphQL named type -> the type names the field typing understands.
+//
+// Built-ins only: a custom scalar (JSON, JSONObject, Upload, ...) can hold
+// any JSON value, so advertising it as a string would misdescribe the data
+// and make generated validation reject values the schema accepts. Enums are
+// mapped by the caller, which knows they are strings.
+function gqlFieldType(typeName: string): string | undefined {
+  return 'Int' === typeName ? 'integer' :
+    'Float' === typeName ? 'number' :
+      'Boolean' === typeName ? 'boolean' :
+        ('String' === typeName || 'ID' === typeName) ? 'string' :
+          undefined
+}
+
+
 function findFieldDefs(
   _ment: ModelEntity,
   mop: ModelOp,
   mpoint: ModelPoint,
   def: any
 ): SchemaDef[] {
+  if ('graphql' === mpoint.kind) {
+    return findGraphqlFieldDefs(_ment, mpoint, def)
+  }
+
   const fielddefs: SchemaDef[] = []
   const pathdef = def.paths[mpoint.orig]