@voxgig/apidef 5.9.0 → 5.11.0

package/model/apidef.jsonic

@@ -10,8 +10,11 @@ main: kit: entity: &: {
 
   name: key()
   active: *true
-  
-  id: {
+
+  # Present only when the spec models an id for this entity (response /
+  # request schema declares one, or examples imply one). Public APIs that
+  # return payloads without an id leave this undefined.
+  id?: {
     field: string
     name: string
   }
@@ -41,13 +44,46 @@ main: kit: entity: &: {
 
       parts: [ &: string ]
 
+      # Each arg kind (path params, query, header, cookie) has the same
+      # element shape. `kind` is constrained to the kind tag matching the
+      # array it appears in; `example` is optional and captures a spec-
+      # provided example value used by test generators.
       args: {
-        params: [ &: {
+        params?: [ &: {
+          active: *true
+          kind: 'param'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        query?: [ &: {
+          active: *true
+          kind: 'query'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        header?: [ &: {
+          active: *true
+          kind: 'header'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        cookie?: [ &: {
           active: *true
-          kind: string
+          kind: 'cookie'
           name: string
+          orig?: string
           reqd: boolean
           type: top
+          example?: top
         } ]
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/apidef",
-  "version": "5.9.0",
+  "version": "5.11.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",

package/src/apidef.ts

@@ -284,8 +284,21 @@ function ApiDef(opts: ApiDefOptions) {
           warn.history.map(n => formatJSONIC(n)).join('\n\n'))
       }
 
+      // apidef writes model source files (entity, flow, guide jsonics) into
+      // .sdk/model/. Downstream actions (sdkgen, etc.) read those via
+      // sdk.jsonic @-includes, so voxgig-model has to re-resolve the model
+      // before the post-step actions run. Signal reload whenever jostraca
+      // wrote or merged any files; if nothing changed on disk,
+      // voxgig-model's resolveModel cache short-circuits the re-read.
+      const jfiles = jres?.files
+      const reload = !!jfiles && (
+        (jfiles.written?.length ?? 0) > 0 ||
+        (jfiles.merged?.length ?? 0) > 0
+      )
+
       return {
         ok: true,
+        reload,
         err: null,
         start,
         end: Date.now(),
@@ -398,17 +411,22 @@ export type {
 
 export type {
   OpName,
+  ArgKind,
+  NamesCluster,
   ModelEntityRelations,
   ModelOpMap,
   ModelFieldOp,
   ModelField,
   ModelArg,
-  ModelTarget,
+  ModelPoint,
   ModelOp,
   ModelEntity,
   Model,
   ModelEntityFlow,
   ModelEntityFlowStep,
+  ModelEntityFlowStepInput,
+  ModelEntityFlowStepValidator,
+  ModelEntityFlowStepSpec,
 } from './model'
 
 

package/src/builder/flow/flowHeuristic01.ts

@@ -17,7 +17,7 @@ import {
 import type {
   ModelEntity,
   ModelOp,
-  ModelTarget,
+  ModelPoint,
 } from '../../model'
 
 import {
@@ -196,7 +196,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 }
 
 
-function findMainLoadPoint(op: ModelOp): ModelTarget | undefined {
+function findMainLoadPoint(op: ModelOp): ModelPoint | undefined {
   let cands = op.points.filter(a => '{id}' === getelem(a.parts, -1))
   return cands[0]
 }

package/src/model.ts

@@ -9,18 +9,41 @@ import type { MethodName } from './types'
 type OpName = 'load' | 'list' | 'create' | 'update' | 'remove' | 'patch' | 'head' | 'options'
 
 
-type Model = {
+// Argument kinds supported on operation points.
+type ArgKind = 'param' | 'query' | 'header' | 'cookie'
+
+
+// jostraca's `names()` helper sticks several stylised forms of the project
+// name onto an object: `name`, `Name`, `NAME`, plus snake/dash variants.
+// Templates that reach for any of these expect the cluster to be present.
+type NamesCluster = {
   name: string
+  Name: string
+  NAME: string
+}
+
+
+// Top-level unified API model produced by apidef + voxgig-model. Templates
+// access the kit through `model.main.kit.<thing>`. The `info`, `config`,
+// `feature`, and `target` kits remain `any` for now because their shapes are
+// less stable than entity/flow — Phase 2 of the refactor types them.
+type Model = NamesCluster & {
   origin?: string
+  def?: string
 
-  const: {
-    // TODO: remove
-    Name: string
+  const: NamesCluster & {
+    year?: number
   }
 
   main: {
     kit: {
+      info: any
+      config: any
       entity: Record<string, ModelEntity>
+      feature: Record<string, any>
+      flow: Record<string, ModelEntityFlow>
+      target: Record<string, any>
+      option?: Record<string, any>
     }
   }
 }
@@ -52,18 +75,27 @@ type ModelField = {
 }
 
 
-// Operation argument/parameter definition
+// Operation argument/parameter definition.
+// `example` captures a value the spec advertises (parameter `example`,
+// the first entry of `examples`, or `schema.example`/`schema.default`).
+// Test generators use this for required params in live test setup so the
+// generated request actually satisfies the API contract.
 type ModelArg = {
   name: string
   orig: string
   type: any // @voxgig/struct validation schema
-  kind: 'param' | 'query' | 'header' | 'cookie'
+  kind: ArgKind
   reqd: boolean
+  example?: any
 }
 
 
-// Point implementation of an operation
-type ModelTarget = {
+// One concrete HTTP 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
   method: MethodName
   parts: string[]
@@ -93,19 +125,31 @@ type ModelTarget = {
 // Operation definition
 type ModelOp = {
   name: OpName
-  points: ModelTarget[]
+  points: ModelPoint[]
 }
 
 
-// Entity definition - core model entity with operations and fields
+// Entity definition - core model entity with operations and fields.
+// `id` is present only when the OpenAPI response/request schema declares
+// (or examples imply) an `id` field on the entity. Public APIs that return
+// payloads without an id (e.g. read-only feeds) leave it undefined.
+//
+// `Name`, `NAME` etc. are stamped on by jostraca's `names()` helper after
+// apidef hands the model to the generator. They're typed as optional here
+// so apidef's transform code can construct entities without them; template
+// code should reach for them through `nom(entity, 'Name')` rather than
+// direct property access, which both works pre-`names()` and lets us
+// remove the optional later.
 type ModelEntity = {
-  name: string,
-  op: ModelOpMap,
-  fields: ModelField[],
-  id: {
-    name: string,
-    field: string,
-  },
+  name: string
+  Name?: string
+  NAME?: string
+  op: ModelOpMap
+  fields: ModelField[]
+  id?: {
+    name: string
+    field: string
+  }
   relations: ModelEntityRelations
 }
 
@@ -116,36 +160,69 @@ type ModelEntityFlow = {
   kind: string
   // args: Record<string, string>
   step: ModelEntityFlowStep[]
+  active?: boolean
+}
+
+
+// Per-step input cluster. Test-generators name the variables they emit by
+// reading these slots, falling back to derived defaults. All fields are
+// optional — `newFlowStep` in transform/flowstep.ts guarantees the input
+// object itself exists, so consumers don't need to null-check `step.input`.
+type ModelEntityFlowStepInput = {
+  ref?: string
+  entvar?: string
+  matchvar?: string
+  datavar?: string
+  listvar?: string
+  resdatavar?: string
+  markdefvar?: string
+  srcdatavar?: string
+  suffix?: string
+  textfield?: string
+  id?: any
+  [extra: string]: any
+}
+
+
+// Validators and specs are user-supplied callables identified by the
+// `apply` discriminator; `def` is the validator-specific options bag.
+type ModelEntityFlowStepValidator = {
+  apply: string
+  def: Record<string, any>
+}
+
+type ModelEntityFlowStepSpec = {
+  apply: string
+  def: Record<string, any>
 }
 
 
 type ModelEntityFlowStep = {
   op: OpName
-  input: Record<string, any>
+  input: ModelEntityFlowStepInput
   match: Record<string, any>
   data: Record<string, any>
-  spec: {
-    apply: string
-    def: Record<string, any>
-  }[]
-  valid: {
-    apply: string
-    def: Record<string, any>
-  }[]
+  spec: ModelEntityFlowStepSpec[]
+  valid: ModelEntityFlowStepValidator[]
 }
 
 
 export type {
   OpName,
+  ArgKind,
+  NamesCluster,
   Model,
   ModelEntityRelations,
   ModelOpMap,
   ModelFieldOp,
   ModelField,
   ModelArg,
-  ModelTarget,
+  ModelPoint,
   ModelOp,
   ModelEntity,
   ModelEntityFlow,
   ModelEntityFlowStep,
+  ModelEntityFlowStepInput,
+  ModelEntityFlowStepValidator,
+  ModelEntityFlowStepSpec,
 }

package/src/transform/args.ts

@@ -21,7 +21,7 @@ import type {
   OpName,
   ModelOp,
   ModelEntity,
-  ModelTarget,
+  ModelPoint,
   ModelArg,
 } from '../model'
 
@@ -38,16 +38,16 @@ const argsTransform: Transform = async function(
 
   each(kit.entity, (ment: ModelEntity, entname: string) => {
     each(ment.op, (mop: ModelOp, opname: OpName) => {
-      each(mop.points, (mtarget: ModelTarget) => {
+      each(mop.points, (mpoint: ModelPoint) => {
         const argdefs: ParameterDef[] = []
 
-        const pathdef: PathDef = def.paths[mtarget.orig]
+        const pathdef: PathDef = def.paths[mpoint.orig]
         argdefs.push(...(pathdef.parameters ?? []))
 
-        const opdef: MethodDef = (pathdef as any)[mtarget.method.toLowerCase()]
+        const opdef: MethodDef = (pathdef as any)[mpoint.method.toLowerCase()]
         argdefs.push(...(opdef?.parameters ?? []))
 
-        resolveArgs(ment, mop, mtarget, argdefs)
+        resolveArgs(ment, mop, mpoint, argdefs)
       })
 
     })
@@ -67,7 +67,7 @@ const ARG_KIND: Record<string, ModelArg["kind"]> = {
 }
 
 
-function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argdefs: ParameterDef[]) {
+function resolveArgs(ment: ModelEntity, mop: ModelOp, mpoint: ModelPoint, argdefs: ParameterDef[]) {
   const touchedKeys = new Set<string>()
 
   each(argdefs, (argdef: ParameterDef) => {
@@ -79,7 +79,7 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
     // 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 = mtarget.rename[kind]
+    const renameMap = mpoint.rename[kind]
     const name = renameMap?.[specName] ?? renameMap?.[orig] ?? orig
     const marg: ModelArg = {
       name,
@@ -89,12 +89,17 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
       reqd: !!argdef.required
     }
 
+    const example = resolveArgExample(argdef)
+    if (undefined !== example) {
+      marg.example = example
+    }
+
     if (argdef.nullable) {
       marg.type = ['`$ONE`', '`$NULL`', marg.type]
     }
 
-    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mtarget.args
-    let kindargs = (mtarget.args[argsKey] = mtarget.args[argsKey] ?? [])
+    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mpoint.args
+    let kindargs = (mpoint.args[argsKey] = mpoint.args[argsKey] ?? [])
     kindargs.push(marg)
     touchedKeys.add(argsKey)
   })
@@ -102,11 +107,39 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
   // Sort once after all args are collected
   const cmp = (a: ModelArg, b: ModelArg) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
   for (const key of touchedKeys) {
-    mtarget.args[key as keyof typeof mtarget.args]?.sort(cmp)
+    mpoint.args[key as keyof typeof mpoint.args]?.sort(cmp)
   }
 }
 
 
+// OpenAPI lets specs advertise example values four ways:
+//   parameter.example          (single value, OAS 3.0+)
+//   parameter.examples          (named-example object, take first .value)
+//   parameter.schema.example   (single value on the schema)
+//   parameter.schema.default   (default value)
+// Pick the first one we find so test generators can produce valid live
+// requests even when the parameter is required and has no other source.
+function resolveArgExample(argdef: any): any {
+  if (undefined !== argdef?.example) return argdef.example
+
+  const examples = argdef?.examples
+  if (examples && 'object' === typeof examples) {
+    for (const v of Object.values(examples)) {
+      if (v && 'object' === typeof v && undefined !== (v as any).value) {
+        return (v as any).value
+      }
+    }
+  }
+
+  const schema = argdef?.schema
+  if (schema) {
+    if (undefined !== schema.example) return schema.example
+    if (undefined !== schema.default) return schema.default
+  }
+
+  return undefined
+}
+
 
 export {
   argsTransform,

package/src/transform/entity.ts

@@ -41,10 +41,6 @@ const entityTransform: Transform = async function(
       name: entname,
       op: {},
       fields: [],
-      id: {
-        name: 'id',
-        field: 'id',
-      },
       relations,
     }
 

package/src/transform/field.ts

@@ -20,7 +20,7 @@ import type {
   OpName,
   ModelOp,
   ModelEntity,
-  ModelTarget,
+  ModelPoint,
   ModelField,
 } from '../model'
 
@@ -43,10 +43,10 @@ const fieldTransform: Transform = async function(
     for (let opname of opFieldPrecedence) {
       const mop = ment.op[opname]
       if (mop) {
-        const mtargets = mop.points
+        const mpoints = mop.points
 
-        for (let mtarget of mtargets) {
-          const opfields = resolveOpFields(ment, mop, mtarget, def)
+        for (let mpoint of mpoints) {
+          const opfields = resolveOpFields(ment, mop, mpoint, def)
 
           for (let opfield of opfields) {
             if (!seen[opfield.name]) {
@@ -54,7 +54,7 @@ const fieldTransform: Transform = async function(
               seen[opfield.name] = opfield
             }
             else {
-              mergeField(ment, mop, mtarget, def, seen[opfield.name], opfield)
+              mergeField(ment, mop, mpoint, def, seen[opfield.name], opfield)
             }
           }
         }
@@ -65,6 +65,15 @@ const fieldTransform: Transform = async function(
       return a.name < b.name ? -1 : a.name > b.name ? 1 : 0
     })
 
+    // Mark the entity as having an id only when the spec actually declares one.
+    // Downstream (test generators, fixture builders) gate id-specific code on
+    // this presence so that public read-only APIs without ids don't get
+    // bogus id assertions.
+    const idField = fields.find((f: ModelField) => 'id' === f.name)
+    if (idField) {
+      ment.id = { name: 'id', field: 'id' }
+    }
+
     msg += ment.name + ' '
   })
 
@@ -76,11 +85,11 @@ const fieldTransform: Transform = async function(
 function resolveOpFields(
   ment: ModelEntity,
   mop: ModelOp,
-  mtarget: ModelTarget,
+  mpoint: ModelPoint,
   def: any
 ): ModelField[] {
   const mfields: ModelField[] = []
-  const fielddefs = findFieldDefs(ment, mop, mtarget, def)
+  const fielddefs = findFieldDefs(ment, mop, mpoint, def)
 
   for (let fielddef of fielddefs) {
     const fieldname = (fielddef as any).key$ as string
@@ -101,13 +110,13 @@ function resolveOpFields(
 function findFieldDefs(
   _ment: ModelEntity,
   mop: ModelOp,
-  mtarget: ModelTarget,
+  mpoint: ModelPoint,
   def: any
 ): SchemaDef[] {
   const fielddefs: SchemaDef[] = []
-  const pathdef = def.paths[mtarget.orig]
+  const pathdef = def.paths[mpoint.orig]
 
-  const method = mtarget.method.toLowerCase()
+  const method = mpoint.method.toLowerCase()
   const opdef: any = pathdef[method]
 
   if (opdef) {
@@ -303,7 +312,7 @@ function inferTypeFromValue(value: any): string {
 function mergeField(
   ment: ModelEntity,
   mop: ModelOp,
-  mtarget: ModelTarget,
+  mpoint: ModelPoint,
   def: any,
   exisingField: ModelField,
   newField: ModelField

package/src/transform/operation.ts

@@ -19,7 +19,7 @@ import type {
   OpName,
   ModelOpMap,
   ModelOp,
-  ModelTarget,
+  ModelPoint,
 } from '../model'
 
 
@@ -146,7 +146,7 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
         // rewrote the freshly-renamed `{id}` into `{project_id}` again).
         const parts = p.parts
 
-        const mtarget: ModelTarget = {
+        const mpoint: ModelPoint = {
           orig: p.orig,
           parts,
           rename: p.rename,
@@ -158,10 +158,10 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
           }
         }
 
-        mtarget.transform.req = mtarget.transform.req ?? '`reqdata`'
-        mtarget.transform.res = mtarget.transform.res ?? '`body`'
+        mpoint.transform.req = mpoint.transform.req ?? '`reqdata`'
+        mpoint.transform.res = mpoint.transform.res ?? '`body`'
 
-        return mtarget
+        return mpoint
       })
     }
   }

package/src/transform/select.ts

@@ -20,7 +20,7 @@ import type {
   OpName,
   ModelOp,
   ModelEntity,
-  ModelTarget,
+  ModelPoint,
   ModelArg,
 } from '../model'
 
@@ -36,9 +36,9 @@ const selectTransform: Transform = async function(
 
   each(kit.entity, (ment: ModelEntity, _entname: string) => {
     each(ment.op, (mop: ModelOp, _opname: OpName) => {
-      each(mop.points, (mtarget: ModelTarget) => {
-        const pdef: PathDef = def.paths[mtarget.orig]
-        resolveSelect(guide, ment, mop, mtarget, pdef)
+      each(mop.points, (mpoint: ModelPoint) => {
+        const pdef: PathDef = def.paths[mpoint.orig]
+        resolveSelect(guide, ment, mop, mpoint, pdef)
       })
       if (null != mop.points && 0 < mop.points.length) {
         sortPoints(guide, ment, mop)
@@ -56,11 +56,11 @@ function resolveSelect(
   guide: Guide,
   ment: ModelEntity,
   _mop: ModelOp,
-  mtarget: ModelTarget,
+  mpoint: ModelPoint,
   _pdef: PathDef
 ) {
-  const select: any = mtarget.select
-  const margs: any = mtarget.args
+  const select: any = mpoint.select
+  const margs: any = mpoint.args
 
   const argkinds = ['params', 'query', 'header', 'cookie']
 
@@ -75,7 +75,7 @@ function resolveSelect(
   select.exist.sort()
 
   const gent = guide.entity[ment.name]
-  const gpath = gent.path[mtarget.orig]
+  const gpath = gent.path[mpoint.orig]
 
   if (gpath.action) {
     const actname = Object.keys(gpath.action).sort()[0]
@@ -94,12 +94,12 @@ function sortPoints(
   mop: ModelOp,
 ) {
   // Cache joined exist strings to avoid recomputing on every comparison.
-  const existCache = new Map<ModelTarget, string>()
+  const existCache = new Map<ModelPoint, string>()
   for (const pt of mop.points) {
     existCache.set(pt, pt.select.exist.join('\t'))
   }
 
-  mop.points.sort((a: ModelTarget, b: ModelTarget) => {
+  mop.points.sort((a: ModelPoint, b: ModelPoint) => {
     // longest exist len first
     let order = b.select.exist.length - a.select.exist.length
     if (0 === order) {

package/src/transform/top.ts

@@ -41,8 +41,8 @@ const topTransform = async function(
   const { apimodel, def } = ctx
   const kit: KitModel = apimodel.main[KIT]
 
-  kit.info = def.info
-  kit.info.servers = def.servers ?? []
+  kit.info = stringifyInfoScalars(def.info ?? {})
+  kit.info.servers = stringifyInfoScalars(def.servers ?? [])
 
   // Swagger 2.0
   if (def.host) {
@@ -55,6 +55,30 @@ const topTransform = async function(
 }
 
 
+// OpenAPI's `info` object (and the `servers` array) declares every scalar
+// leaf as a string. YAML/JSON parsers don't enforce that — `version: 2`
+// without quotes parses as the number 2, `version: true` as a boolean.
+// Apidef's downstream schema (apidef.jsonic) unifies info fields as
+// `string`, so non-string scalars cause an aontu unify failure during
+// model resolution. Normalise scalar leaves to strings here, at the
+// model-build boundary, rather than relax the schema.
+function stringifyInfoScalars(node: any): any {
+  if (null == node) return node
+  if (Array.isArray(node)) return node.map(stringifyInfoScalars)
+  if ('object' === typeof node) {
+    const out: Record<string, any> = {}
+    for (const [k, v] of Object.entries(node)) {
+      out[k] = stringifyInfoScalars(v)
+    }
+    return out
+  }
+  if ('number' === typeof node || 'boolean' === typeof node) {
+    return String(node)
+  }
+  return node
+}
+
+
 export {
   topTransform
 }