@voxgig/apidef 8.13.0 → 8.15.0

package/src/resolved.ts

@@ -2,7 +2,22 @@
 
 // See docs/design/resolved-spec-capability.md
 
-import { graphqlInputTypes } from './transform/contract'
+// An operation needs its argument types, including recursive input objects.
+// Output types are represented by the field and generated invocation selection;
+// copying the entire connected output graph per operation is quadratic in API size.
+function graphqlInputTypes(field: any, types: any): any {
+  const out: any = {}
+  function visit(name: string) {
+    if (!types[name] || Object.prototype.hasOwnProperty.call(out, name)) return
+    const type = types[name]
+    out[name] = type
+    if (type.kind === 'INPUT_OBJECT') {
+      for (const child of Object.values(type.fields || {}) as any[]) visit(child.type)
+    }
+  }
+  for (const arg of field.args || []) visit(arg.type)
+  return out
+}
 
 
 const METHODS = [
@@ -16,6 +31,8 @@ type OperationFacts = {
 }
 
 
+type OperationSelector = { entity: string, op: string }
+
 type ResolvedSpec = {
   version: 1
   kind: string
@@ -24,16 +41,14 @@ type ResolvedSpec = {
   // during parse, so a consumer reading the file itself would miss lookups.
   def: any
 
-  operation(method: string, path: string): OperationFacts | undefined
+  operation(method: string, path: string, selector?: OperationSelector): OperationFacts | undefined
 }
 
 
-// The single definition of a resolved operation, shared by contractTransform
-// and by consumers of the capability, so the two cannot disagree.
-function operationFacts(def: any, point: { method: string, orig: string }): OperationFacts | undefined {
-  const path = def?.paths?.[point.orig]
-  const method = path?.[String(point.method).toLowerCase()]
-  const graphql = def?.query?.[point.orig] || def?.mutation?.[point.orig]
+function operationFacts(def: any, point: { m: string, o: string }): OperationFacts | undefined {
+  const path = def?.paths?.[point.o]
+  const method = path?.[String(point.m).toLowerCase()]
+  const graphql = def?.query?.[point.o] || def?.mutation?.[point.o]
 
   if (!method && !graphql) return undefined
 
@@ -67,21 +82,21 @@ function operationFacts(def: any, point: { method: string, orig: string }): Oper
 }
 
 
-// Every described operation, keyed 'METHOD path' as `point.contract.id` is.
+// Every described operation, keyed 'METHOD path' as `point.co.id` is.
 function operationIndex(def: any): { [id: string]: OperationFacts } {
   const out: { [id: string]: OperationFacts } = {}
 
   for (const path of Object.keys(def?.paths || {})) {
     for (const method of METHODS) {
       if (null == def.paths[path]?.[method]) continue
-      const facts = operationFacts(def, { method, orig: path })
+      const facts = operationFacts(def, { m: method, o: path })
       if (facts) out[method.toUpperCase() + ' ' + path] = facts
     }
   }
 
   for (const kind of ['query', 'mutation']) {
     for (const field of Object.keys(def?.[kind] || {})) {
-      const facts = operationFacts(def, { method: 'POST', orig: field })
+      const facts = operationFacts(def, { m: 'POST', o: field })
       if (facts) out['POST ' + field] = facts
     }
   }
@@ -90,20 +105,49 @@ function operationIndex(def: any): { [id: string]: OperationFacts } {
 }
 
 
-function makeResolved(kind: string, def: any): ResolvedSpec {
+function operationGuide(guide: any, method: string, path: string, graphql: boolean,
+  selector?: OperationSelector): any {
+  const matches: any[] = []
+  for (const [entityName, entity] of Object.entries(guide?.entity || {}) as any) {
+    if (selector && selector.entity !== entityName) continue
+    const ops = entity[graphql ? 'field' : 'path']?.[path]?.op || {}
+    for (const [opName, op] of Object.entries(ops) as any) {
+      if (selector && selector.op !== opName) continue
+      if (op.method && op.method.toUpperCase() !== method.toUpperCase()) continue
+      if (op.contract !== undefined || op.live !== undefined) matches.push(op)
+    }
+  }
+  if (matches.length > 1) {
+    throw new Error('Ambiguous operation guide for ' + method + ' ' + path + '; select entity and op')
+  }
+  return matches[0]
+}
+
+function makeResolved(kind: string, def: any, guide: () => any = () => undefined): ResolvedSpec {
   return {
     version: 1,
     kind,
     def,
-    operation: (method: string, path: string) =>
-      operationFacts(def, { method, orig: path }),
+    operation: (method: string, path: string, selector?: OperationSelector) => {
+      const facts = operationFacts(def, { m: method, o: path })
+      if (!facts) return undefined
+      const op = operationGuide(guide(), method, path, facts.protocol === 'graphql', selector)
+      for (const key of ['requestBody', 'responses', 'parameters', 'security']) {
+        if (op?.contract?.[key] !== undefined) {
+          facts[key] = op.contract[key]
+          ;(facts.factSources ??= {})[key] = 'guide'
+        }
+      }
+      if (op?.live !== undefined) facts.live = op.live
+      return facts
+    },
   }
 }
 
 
 // Tolerates a missing context: apidef also runs outside a model build.
-function publishResolved(ctx: any, kind: string, def: any): ResolvedSpec {
-  const resolved = makeResolved(kind, def)
+function publishResolved(ctx: any, kind: string, def: any, guide?: () => any): ResolvedSpec {
+  const resolved = makeResolved(kind, def, guide)
   if (null != ctx && 'object' === typeof ctx) {
     ctx.state = ctx.state || {}
     ctx.state.apidef = { ...(ctx.state.apidef || {}), resolved }
@@ -114,7 +158,7 @@ function publishResolved(ctx: any, kind: string, def: any): ResolvedSpec {
 
 function resolvedSpec(carrier: any): ResolvedSpec | undefined {
   if (null == carrier || 'object' !== typeof carrier) return undefined
-  return carrier.state?.apidef?.resolved ??
+  return carrier.resolved ?? carrier.ctx?.resolved ?? carrier.state?.apidef?.resolved ??
     carrier.ctx?.state?.apidef?.resolved ??
     carrier.apidef?.resolved ??
     undefined
@@ -122,6 +166,7 @@ function resolvedSpec(carrier: any): ResolvedSpec | undefined {
 
 
 export type {
+  OperationSelector,
   OperationFacts,
   ResolvedSpec,
 }

package/src/transform/args.ts

@@ -41,7 +41,7 @@ const argsTransform: Transform = async function(
       each(mop.points, (mpoint: ModelPoint) => {
         const argdefs: ParameterDef[] = []
 
-        if ('graphql' === mpoint.kind) {
+        if ('graphql' === mpoint.k) {
           // 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
@@ -64,10 +64,10 @@ const argsTransform: Transform = async function(
           }
         }
         else {
-          const pathdef: PathDef = def.paths[mpoint.orig]
+          const pathdef: PathDef = def.paths[mpoint.o]
           argdefs.push(...((pathdef as any)?.parameters ?? []))
 
-          const opdef: MethodDef = (pathdef as any)?.[mpoint.method.toLowerCase()]
+          const opdef: MethodDef = (pathdef as any)?.[mpoint.m.toLowerCase()]
           argdefs.push(...(opdef?.parameters ?? []))
         }
 
@@ -85,8 +85,8 @@ 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 ?
+  const field = mpoint.gq?.field ?? mpoint.o
+  return 'mutation' === mpoint.gq?.optype ?
     def.mutation?.[field] : def.query?.[field]
 }
 
@@ -100,7 +100,7 @@ function gqlScalarType(typeName: string): string | undefined {
 }
 
 
-const ARG_KIND: Record<string, ModelArg["kind"]> = {
+const ARG_KIND: Record<string, ModelArg["k"]> = {
   'query': 'query',
   'header': 'header',
   'path': 'param',
@@ -122,11 +122,11 @@ function resolveArgs(
       const ref = (argdef as any)?.$ref
       ctx?.warn?.({
         note: `Parameter with no name on entity=${ment.name} op=${mop.name}` +
-          ` path=${mpoint.orig} is dropped` +
+          ` path=${mpoint.o} is dropped` +
           (null == ref ? '.' : `: \`$ref\` "${ref}" resolves to nothing.`) +
           ' A parameter needs a `name`, or a reference that resolves to one.',
         entity: ment.name,
-        path: mpoint.orig,
+        path: mpoint.o,
         op: mop.name,
       })
       return
@@ -136,35 +136,35 @@ function resolveArgs(
     // Rename map can be keyed by either the spec original (camelCase) or by
     // the snakified form depending on which path went through heuristic01.
     // Try both before falling through to `orig`.
-    const renameMap = mpoint.rename[kind]
+    const renameMap = mpoint.r[kind]
     const name = renameMap?.[specName] ?? renameMap?.[orig] ?? orig
     const marg: ModelArg = {
-      name,
-      orig,
-      type: inferFieldType(name, validator(argdef.schema?.type)),
-      kind,
-      reqd: !!argdef.required
+      n: name,
+      or: orig,
+      t: inferFieldType(name, validator(argdef.schema?.type)),
+      k: kind,
+      r: !!argdef.required
     }
 
     const example = resolveArgExample(argdef)
     if (undefined !== example) {
-      marg.example = example
+      marg.ex = example
     }
 
     if (argdef.nullable) {
-      marg.type = ['`$ONE`', '`$NULL`', marg.type]
+      marg.t = ['`$ONE`', '`$NULL`', marg.t]
     }
 
-    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mpoint.args
-    let kindargs = (mpoint.args[argsKey] = mpoint.args[argsKey] ?? [])
+    const argsKey = (marg.k === 'param' ? 'params' : marg.k) as keyof typeof mpoint.g
+    let kindargs = (mpoint.g[argsKey] = mpoint.g[argsKey] ?? [])
     kindargs.push(marg)
     touchedKeys.add(argsKey)
   })
 
   // Sort once after all args are collected
-  const cmp = (a: ModelArg, b: ModelArg) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  const cmp = (a: ModelArg, b: ModelArg) => a.n < b.n ? -1 : a.n > b.n ? 1 : 0
   for (const key of touchedKeys) {
-    mpoint.args[key as keyof typeof mpoint.args]?.sort(cmp)
+    mpoint.g[key as keyof typeof mpoint.g]?.sort(cmp)
   }
 }
 

package/src/transform/clean.ts

@@ -1,5 +1,6 @@
 
 import type { TransformResult, Transform } from '../transform'
+import { KIT } from '../types'
 
 import { walk, isempty, isnode, ismap, islist } from '@voxgig/struct'
 
@@ -54,6 +55,10 @@ const cleanTransform: Transform = async function(
 
   ctx.apimodel = cur[0]
 
+  for (const entity of Object.values(ctx.apimodel.main?.[KIT]?.entity ?? {}) as any[]) {
+    entity.fields ??= {}
+  }
+
   return { ok: true, msg: 'clean' }
 }
 

package/src/transform/contract.ts

@@ -1,89 +1,24 @@
 // Point contracts. See docs/design/resolved-spec-capability.md
 import type { Transform } from '../transform'
 
-import { operationFacts } from '../resolved'
-
-
-export function contractJSON(value: any): string {
-  function walk(root: any, base: string): any {
-    // One memo per fact, so refs stay local to it.
-    const seen = new Map<any, string>()
-    function copy(v: any, path: string): any {
-      if (v === null || typeof v !== 'object') return v
-      if (seen.has(v)) return { $ref: seen.get(v) }
-      seen.set(v, path)
-      const out: any = Array.isArray(v) ? v.map((item, i) => copy(item, path + '/' + i)) : {}
-      if (!Array.isArray(v)) for (const k of Object.keys(v).sort()) {
-        if (!k.endsWith('$') && !k.startsWith('x-') && undefined !== v[k]) out[k] = copy(v[k], path + '/' + k.replace(/~/g, '~0').replace(/\//g, '~1'))
-      }
-      return out
-    }
-    return copy(root, base)
-  }
-
-  if (null === value || 'object' !== typeof value || Array.isArray(value)) {
-    return JSON.stringify(walk(value, '#'))
-  }
-
-  const out: any = {}
-  for (const k of Object.keys(value).sort()) {
-    if (k.endsWith('$') || k.startsWith('x-') || undefined === value[k]) continue
-    out[k] = walk(value[k], '#/' + k.replace(/~/g, '~0').replace(/\//g, '~1'))
-  }
-  return JSON.stringify(out)
-}
-
-// An operation needs its argument types, including recursive input objects.
-// Output types are represented by the field and generated invocation selection;
-// copying the entire connected output graph per operation is quadratic in API size.
-export function graphqlInputTypes(field: any, types: any): any {
-  const out: any = {}
-  function visit(name: string) {
-    if (!types[name] || Object.prototype.hasOwnProperty.call(out, name)) return
-    const type = types[name]
-    out[name] = type
-    if (type.kind === 'INPUT_OBJECT') {
-      for (const child of Object.values(type.fields || {}) as any[]) visit(child.type)
-    }
-  }
-  for (const arg of field.args || []) visit(arg.type)
-  return out
-}
-
 export const contractTransform: Transform = async (ctx: any) => {
   const def = ctx.def || {}
   for (const entity of Object.values(ctx.apimodel.main.kit.entity || {}) as any[]) {
     for (const op of Object.values(entity.op || {}) as any[]) {
       for (const point of op?.points || []) {
-        const path = def.paths?.[point.orig]
-        const method = path?.[point.method.toLowerCase()]
-        const graphql = def.query?.[point.orig] || def.mutation?.[point.orig]
+        const path = def.paths?.[point.o]
+        const method = path?.[point.m.toLowerCase()]
+        const graphql = def.query?.[point.o] || def.mutation?.[point.o]
         if (!method && !graphql) continue
-        const facts: any = operationFacts(def, point)
-        if (null == facts) continue
-
-        // A property of the point, not of the definition.
-        if (graphql) facts.invocation = point.graphql
-        const guideOp = ctx.guide?.entity?.[entity.name]?.[graphql ? 'field' : 'path']?.[point.orig]?.op?.[op.name]
+        const guideOp = ctx.guide?.entity?.[entity.name]?.[graphql ? 'field' : 'path']?.[point.o]?.op?.[op.name]
         const hint = guideOp?.live
-        for (const key of ['requestBody', 'responses', 'parameters', 'security']) {
-          if (guideOp?.contract?.[key] !== undefined) {
-            facts[key] = guideOp.contract[key]
-            ;(facts.factSources ??= {})[key] = 'guide'
-          }
-        }
         if (hint !== undefined) {
-          facts.live = hint
-          point.live = hint
+          point.li = hint
         }
         // Identity only; facts come from the capability. See
         // docs/design/resolved-spec-capability.md
-        point.contract = { version: 1, id: point.method + ' ' + point.orig,
+        point.co = { version: 2, id: point.m + ' ' + point.o,
           source: graphql ? 'graphql' : def.swagger ? 'swagger2' : 'openapi3' }
-
-        if (ctx.opts?.contractJson) {
-          point.contract.json = contractJSON(facts)
-        }
       }
     }
   }

package/src/transform/entity.ts

@@ -59,7 +59,7 @@ const entityTransform: Transform = async function(
     const modelent: ModelEntity = {
       name: entname,
       op: {},
-      fields: [],
+      fields: {},
       relations,
     }
 
@@ -68,9 +68,20 @@ const entityTransform: Transform = async function(
     msg += guideEntity.name + ' '
   })
 
+  filterEntityAncestors(kit.entity)
   return { ok: true, msg }
 }
 
+function filterEntityAncestors(entities: Record<string, any>) {
+  for (const [name, entity] of Object.entries(entities)) {
+    if (null == entity.relations) continue
+    entity.relations.ancestors = (entity.relations.ancestors ?? [])
+      .map((chain: string[]) => chain.filter(ancestor => ancestor !== name &&
+        Object.prototype.hasOwnProperty.call(entities, ancestor)))
+      .filter((chain: string[]) => 0 < chain.length)
+  }
+}
+
 
 // Move "/X" paths onto the entity that owns "/X/{id}" or "/X/{id}/sub".
 // Only acts when the path "/X" sits on a different entity than the
@@ -301,6 +312,7 @@ function suffix(p: string[], c: string[]): boolean {
 
 
 export {
+  filterEntityAncestors,
   resolvePathList,
   buildRelations,
   entityTransform,