@voxgig/apidef 5.10.0 → 6.0.0

package/src/transform/entity.ts

@@ -31,6 +31,17 @@ const entityTransform: Transform = async function(
 
   let msg = ''
 
+  // Pre-pass: merge collection paths into the entity that owns the
+  // per-instance paths. Heuristic01 sometimes assigns "/people" to a
+  // separate "*_search" entity (because the response wraps Person in
+  // a search/pagination component) while "/people/{id}" and
+  // "/people/{id}/anime" land on "person". Result: the person entity has
+  // no primary list endpoint, so direct-load tests can't bootstrap an
+  // 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)
+
   each(guide.entity, (guideEntity: GuideEntity, entname: string) => {
     ctx.log.debug({ point: 'guide-entity', note: entname })
 
@@ -41,10 +52,6 @@ const entityTransform: Transform = async function(
       name: entname,
       op: {},
       fields: [],
-      id: {
-        name: 'id',
-        field: 'id',
-      },
       relations,
     }
 
@@ -57,6 +64,81 @@ const entityTransform: Transform = async function(
 }
 
 
+// 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
+// per-instance paths — leaves correctly-classified APIs alone.
+function mergeCollectionPaths(guide: any, log?: any) {
+  const entities = guide.entity as Record<string, any>
+
+  // First pass: build collectionRoot -> owner-entity-name map.
+  // owner is the entity whose name contains "/X/{...}" paths; we prefer
+  // the owner whose direct-load path is "/X/{id}" (no further segments)
+  // so that nested-resource entities don't claim the root.
+  const rootOwners: Record<string, { ename: string, depth: number }> = {}
+
+  for (const [ename, entity] of Object.entries(entities)) {
+    for (const pathStr of Object.keys(entity.path ?? {})) {
+      // Match /A/{...} or /A/{...}/...
+      const m = pathStr.match(/^\/([^\/{}]+)\/\{[^}]+\}(\/.*)?$/)
+      if (!m) continue
+      const root = m[1]
+      const trailing = m[2] ?? ''
+      // Depth = number of segments after the {id} placeholder. Lower
+      // depth wins (e.g. "/people/{id}" beats "/people/{id}/anime").
+      const depth = trailing === '' ? 0 : trailing.split('/').filter(Boolean).length
+
+      const cur = rootOwners[root]
+      if (!cur || depth < cur.depth) {
+        rootOwners[root] = { ename, depth }
+      }
+    }
+  }
+
+  // Second pass: for each entity with a "/X" path, if X has an owner
+  // elsewhere, move the path there.
+  for (const [ename, entity] of Object.entries(entities)) {
+    if (entity.path == null) continue
+    const pathsToMove: string[] = []
+
+    for (const pathStr of Object.keys(entity.path)) {
+      // Match exactly /X (one literal segment, no params).
+      const m = pathStr.match(/^\/([^\/{}]+)$/)
+      if (!m) continue
+      const root = m[1]
+      const owner = rootOwners[root]
+      if (owner && owner.ename !== ename) {
+        pathsToMove.push(pathStr)
+      }
+    }
+
+    for (const pathStr of pathsToMove) {
+      const owner = rootOwners[pathStr.slice(1)]
+      const targetEntity = entities[owner.ename]
+      if (targetEntity == null) continue
+      targetEntity.path = targetEntity.path ?? {}
+      // If the target already has this path (unlikely), leave it alone.
+      if (targetEntity.path[pathStr] == null) {
+        targetEntity.path[pathStr] = entity.path[pathStr]
+      }
+      delete entity.path[pathStr]
+      log?.debug?.({
+        point: 'merge-collection-path',
+        path: pathStr,
+        from: ename,
+        to: owner.ename,
+      })
+    }
+  }
+
+  // Drop entities that are now empty after the merge.
+  for (const ename of Object.keys(entities)) {
+    if (entities[ename].path == null || Object.keys(entities[ename].path).length === 0) {
+      delete entities[ename]
+    }
+  }
+}
+
+
 
 function resolvePathList(guideEntity: GuideEntity, def: { paths: Record<string, any> }) {
   const paths$: PathDesc[] = []
@@ -90,10 +172,18 @@ function resolvePathList(guideEntity: GuideEntity, def: { paths: Record<string,
 
 
 function buildRelations(guideEntity: any, paths$: PathDesc[]) {
+  // An ancestor is a literal collection segment (e.g. "rems") followed by
+  // a path-param placeholder that names an instance ID. We only collect
+  // the literal parts — placeholder parts like "{año}" must be excluded
+  // even when they're themselves followed by another placeholder, otherwise
+  // downstream code treats `{año}` as an ancestor name and emits broken
+  // idmap entries / match keys.
   let ancestors: any[] = paths$
     .map(pli => pli.parts
       .map((p, i) =>
-        (pli.parts[i + 1]?.[0] === '{' && pli.parts[i + 1] !== '{id}') ? p : null)
+        ('{' !== p[0] &&
+          pli.parts[i + 1]?.[0] === '{' &&
+          pli.parts[i + 1] !== '{id}') ? p : null)
       .filter(p => null != p))
     .filter(n => 0 < n.length)
     .sort((a, b) => a.length - b.length)

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) {
@@ -51,10 +51,45 @@ const topTransform = async function(
     })
   }
 
+  // A usable SDK requires a base URL. OpenAPI 3 puts it in `servers[].url`;
+  // 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.
+  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).'
+    )
+  }
+
   return { ok: true, msg: 'top' }
 }
 
 
+// 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
 }

package/src/types.ts

@@ -117,6 +117,10 @@ type KitModel = {
 
 type ApiDefResult = {
   ok: boolean
+  // True when apidef wrote model source files (e.g. entity / flow jsonics).
+  // Producer host (voxgig-model) uses this to re-resolve the unified model
+  // before downstream actions run, so they see the freshly written sources.
+  reload?: boolean
   start: number
   end: number
   steps: string[]
@@ -291,7 +295,7 @@ export type {
   ModelFieldOp,
   ModelField,
   ModelArg,
-  ModelTarget,
+  ModelPoint,
   ModelOp,
   ModelEntity,
 } from './model'