@voxgig/apidef 5.7.0 → 5.8.2

package/src/transform/args.ts

@@ -71,9 +71,16 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
   const touchedKeys = new Set<string>()
 
   each(argdefs, (argdef: ParameterDef) => {
-    const orig = depluralize(snakify(normalizeFieldName(argdef.name)))
+    // Spec name as written (e.g. `dataType`) is what the rename map is keyed
+    // by; the snakified form is the user-friendly runtime identifier.
+    const specName = normalizeFieldName(argdef.name)
+    const orig = depluralize(snakify(specName))
     const kind = ARG_KIND[argdef.in] ?? 'query'
-    const name = mtarget.rename[kind]?.[orig] ?? orig
+    // 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 name = renameMap?.[specName] ?? renameMap?.[orig] ?? orig
     const marg: ModelArg = {
       name,
       orig,

package/src/transform/entity.ts

@@ -1,6 +1,6 @@
 
 
-import { each } from 'jostraca'
+import { each, snakify } from 'jostraca'
 
 import type { TransformResult, Transform } from '../transform'
 
@@ -21,6 +21,11 @@ import type {
   ModelEntity,
 } from '../model'
 
+import {
+  depluralize,
+  normalizeFieldName,
+} from '../utility'
+
 
 
 const entityTransform: Transform = async function(
@@ -67,7 +72,24 @@ function resolvePathList(guideEntity: GuideEntity, def: { paths: Record<string,
 
     each(rename.param, (param: any) => {
       const pI = parts.indexOf('{' + param.key$ + '}')
-      parts[pI] = '{' + param.val$ + '}'
+      if (pI >= 0) parts[pI] = '{' + param.val$ + '}'
+    })
+
+    // Implicit snake_case normalization for any path placeholder that wasn't
+    // explicitly renamed. apidef's args transform snake-cases param names
+    // (e.g. spec `platformKey` → param.name `platform_key`); without
+    // normalizing the placeholder to match, runtime URL substitution by
+    // param.name fails to fill `{platformKey}`.
+    rename.param = (rename.param as any) ?? {}
+    parts.forEach((part: string, i: number) => {
+      const m = part.match(/^\{(.+)\}$/)
+      if (!m) return
+      const placeholder = m[1]
+      const snake = depluralize(snakify(normalizeFieldName(placeholder)))
+      if (snake !== placeholder && (rename.param as any)[placeholder] === undefined) {
+        ; (rename.param as any)[placeholder] = snake
+        parts[i] = '{' + snake + '}'
+      }
     })
 
     const pathdesc: PathDesc = {

package/src/transform/field.ts

@@ -119,9 +119,23 @@ function findFieldDefs(
     if (responses) {
       fieldSets = getx(responses, '200 content "application/json" schema') ??
         getx(responses, '200 schema')
-      if ('get' === method && 'list' == mop.name) {
-        fieldSets = getx(responses, '201 content "application/json" schema items') ??
-          getx(responses, '201 schema items')
+      if ('list' == mop.name) {
+        // List responses commonly come in three shapes:
+        //   1. direct array — { type: array, items: { ...item } }
+        //   2. wrapper object — { properties: { items: [Item], page, ... } }
+        //      (a single array-of-object property inside an object schema)
+        //   3. legacy "list of created items" under 201
+        // Resolve to the inner item schema when we can identify one
+        // unambiguously; otherwise fall through to the 200 schema as-is.
+        const unwrapped = unwrapArrayWrapper(fieldSets)
+        if (unwrapped) {
+          fieldSets = unwrapped
+        }
+        else {
+          const fromCreated = getx(responses, '201 content "application/json" schema items') ??
+            getx(responses, '201 schema items')
+          if (fromCreated) fieldSets = fromCreated
+        }
       }
       else if ('put' === method && null == fieldSets) {
         fieldSets = getx(responses, '201 content "application/json" schema') ??
@@ -178,7 +192,7 @@ function inferFieldsFromExamples(opdef: any): SchemaDef[] {
   }
 
   const fielddefs: SchemaDef[] = []
-  for (const [key, value] of Object.entries(example)) {
+  for (const [key, value] of Object.entries(example).sort(([a],[b]) => a < b ? -1 : a > b ? 1 : 0)) {
     const fielddef: any = {
       key$: key,
       type: inferTypeFromValue(value),
@@ -237,6 +251,42 @@ function unwrapExample(example: any): any {
 }
 
 
+// unwrapArrayWrapper inspects a list-response schema and, when it is an
+// object with a single array-of-object-schema property (e.g.
+// { boards: [Board] }, { items: [Foo], page, total, ... }), returns the
+// inner item schema so that field resolution sees the actual entity
+// properties rather than the wrapper's bookkeeping.
+//
+// Returns null if the input is not unambiguously such a wrapper:
+//   - schema is already an array → return null (let caller use it directly)
+//   - no array-of-object-schema property → return null
+//   - more than one array-of-object-schema property → ambiguous, return null
+function unwrapArrayWrapper(schema: any): any {
+  if (null == schema || 'object' !== typeof schema) return null
+  // Direct list shape — caller can resolve from items directly.
+  if (schema.type === 'array' && schema.items) {
+    const items = schema.items
+    if (items && (items.properties || Array.isArray(items.allOf))) {
+      return items
+    }
+    return null
+  }
+  if (null == schema.properties || 'object' !== typeof schema.properties) return null
+  let resolved: any = null
+  for (const key of Object.keys(schema.properties)) {
+    const prop = schema.properties[key]
+    if (null == prop || 'object' !== typeof prop) continue
+    if (prop.type !== 'array' || null == prop.items) continue
+    const items = prop.items
+    if (null == items || 'object' !== typeof items) continue
+    if (!items.properties && !Array.isArray(items.allOf)) continue
+    if (resolved != null) return null // ambiguous: multiple array-of-object props
+    resolved = items
+  }
+  return resolved
+}
+
+
 function inferTypeFromValue(value: any): string {
   if (null == value) return 'string'
   if ('boolean' === typeof value) return 'boolean'

package/src/transform/flowstep.ts

@@ -1,6 +1,6 @@
 
 
-import { each } from 'jostraca'
+import { each, camelify, lcf } from 'jostraca'
 
 import type { TransformResult, Transform } from '../transform'
 
@@ -10,6 +10,43 @@ import {
   nom,
 } from '../utility'
 
+
+// Detect a path-parameter that is in fact the entity's own id, after URL
+// renaming. Three ways an identity can show up:
+//   1. The param literally has name 'id' (the common case for e.g. /things/{id}).
+//   2. The param's lower-camelCase name appears in `point.rename.param` mapping
+//      to 'id' — e.g. `{connectionId: 'id'}` for `/companies/{company_id}/connections/{id}`.
+//      In this case the param's own name is `connection_id` (apidef snake-cased
+//      it), which doesn't equal 'id' but the placeholder in `parts` is `{id}`.
+//   3. Positional convention: for singleton ops (load/update/remove), the
+//      LAST `{X}` placeholder in the path is the entity's own id. Catches
+//      cases where the entity name and path placeholder differ in spelling
+//      (e.g. entity `enviroment` vs path `/environments/{environment_id}`)
+//      and apidef therefore didn't synthesize a rename-to-id.
+//
+// Without this helper, the flow generator double-counts the entity's id —
+// emitting it as both `srcdatavar.id` AND a separate body field — which the
+// in-memory test mock then requires to match a non-existent field on the
+// stored entity.
+function isEntityIdParam(point: any, param: any, opname?: string): boolean {
+  if ('id' === param?.name) return true
+  const renameMap = point?.rename?.param
+  if (renameMap && param?.name) {
+    const camel = lcf(camelify(param.name))
+    if ('id' === renameMap[camel]) return true
+  }
+  if ('update' === opname || 'load' === opname || 'remove' === opname) {
+    const parts: any[] = point?.parts || []
+    let last: string | null = null
+    for (const p of parts) {
+      const m = String(p).match(/^\{(.+)\}$/)
+      if (m) last = m[1]
+    }
+    if (last && last === param?.name) return true
+  }
+  return false
+}
+
 import { KIT } from '../types'
 
 import type { KitModel } from '../types'
@@ -116,6 +153,24 @@ function newFlowStep(opname: OpName, args: Record<string, any>): ModelEntityFlow
 }
 
 
+// Reverse-lookup: given a point with rename.param like {spaceId: 'id'} or
+// {space_id: 'id'}, return the snake_case ORIGINAL name (e.g. 'space_id') of
+// any param whose URL placeholder is now `{id}`. Returns null when no
+// rename-to-id is recorded — the literal `id` then represents the entity's
+// own id and createStep should skip it.
+function originalSnakeNameOfRenamedId(point: any): string | null {
+  const renameMap = point?.rename?.param || {}
+  for (const [src, dst] of Object.entries(renameMap)) {
+    if ('id' === dst) {
+      const srcStr = String(src)
+      // Already snake_case? Use as-is. Otherwise convert to snake form.
+      return srcStr.includes('_') ? srcStr : (srcStr.replace(/[A-Z]/g, m => '_' + m.toLowerCase()).replace(/^_/, ''))
+    }
+  }
+  return null
+}
+
+
 const createStep: MakeFlowStep = (
   opmap: any,
   flow: ModelEntityFlow,
@@ -128,17 +183,59 @@ const createStep: MakeFlowStep = (
     const step = newFlowStep('create', args)
 
     each(point.args.params, (param: any) => {
-      // id should not be here in the first place
-      if ('id' !== param.name) {
-        step.match[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
+      if ('id' === param.name) {
+        // For CREATE, `id` in the path is NOT the entity's own id (entity is
+        // being created here — its id doesn't exist yet). It's some parent's
+        // id renamed by apidef's path normalization (e.g. `space_id` → `id`
+        // in `/spaces/{id}/space_memberships` for SpaceMembership). Recover
+        // the original snake_case name so the test seeds the parent's id
+        // into both the created entity's data AND the URL.
+        const origName = originalSnakeNameOfRenamedId(point)
+        if (origName) {
+          step.match[origName] = args.input?.[origName] ?? origName.replace(/_id/, '') + '01'
+        }
+        // If there's no rename-from, this is genuinely the entity's id — skip
+        // (the create call generates it).
+        return
       }
+      step.match[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
     })
 
+    // Also seed any path-param fields required by other ops (typically LIST
+    // through a sibling parent path), so the in-memory test mock can find
+    // the just-created entity when a later step queries by those fields.
+    // Without this, a metric created at /pages/{page_id}/metrics/data lacks
+    // the page_access_user_id field required by
+    // /pages/{page_id}/page_access_users/{page_access_user_id}/metrics LIST.
+    seedRelatedOpParams(opmap, point, step)
+
     flow.step.push(step)
   }
 }
 
 
+function seedRelatedOpParams(opmap: any, createPoint: any, step: ModelEntityFlowStep) {
+  const otherOps = ['list', 'load', 'update', 'remove']
+  for (const opname of otherOps) {
+    const op = opmap[opname]
+    if (!op?.points) continue
+    for (const point of op.points) {
+      const params: any[] = point?.args?.params || []
+      for (const param of params) {
+        if (!param?.name) continue
+        if (isEntityIdParam(point, param, opname as any)) continue
+        if (step.match[param.name] !== undefined) continue
+        // For renamed-from-id params on CREATE's chosen point we'd already
+        // have set the snake-case origin; don't double-write.
+        if ('id' === param.name) continue
+        step.match[param.name] =
+          param.name.replace(/_id/, '') + '01'
+      }
+    }
+  }
+}
+
+
 const listStep: MakeFlowStep = (
   opmap: any,
   flow: ModelEntityFlow,
@@ -151,6 +248,17 @@ const listStep: MakeFlowStep = (
     const step = newFlowStep('list', args)
 
     each(point.args.params, (param: any) => {
+      if ('id' === param.name) {
+        // For LIST, `id` in the path is a parent's id renamed by apidef
+        // (LIST doesn't address a single entity by id). Recover the original
+        // snake_case name so test code references a real idmap entry rather
+        // than landing on the bogus `id01` default.
+        const origName = originalSnakeNameOfRenamedId(point)
+        if (origName) {
+          step.match[origName] = args.input?.[origName] ?? origName.replace(/_id/, '') + '01'
+        }
+        return
+      }
       step.match[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
     })
 
@@ -171,12 +279,12 @@ const updateStep: MakeFlowStep = (
     const step = newFlowStep('update', args)
 
     each(point.args.params, (param: any) => {
-      if ('id' === param.name) {
-        step.data.id = args.input?.id ?? ent.name + '01'
-      }
-      else {
-        step.data[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
+      if (isEntityIdParam(point, param, 'update')) {
+        // Entity's own id — supplied at test time via the loaded/created
+        // entity's id field, not as a separate body parameter. Skip.
+        return
       }
+      step.data[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
     })
 
     flow.step.push(step)
@@ -196,7 +304,7 @@ const loadStep: MakeFlowStep = (
     const step = newFlowStep('load', args)
 
     each(point.args.params, (param: any) => {
-      if ('id' === param.name) {
+      if (isEntityIdParam(point, param, 'load')) {
         step.match.id = args.input?.id ?? ent.name + '01'
       }
       else {
@@ -221,7 +329,7 @@ const removeStep: MakeFlowStep = (
     const step = newFlowStep('remove', args)
 
     each(point.args.params, (param: any) => {
-      if ('id' === param.name) {
+      if (isEntityIdParam(point, param, 'remove')) {
         step.match.id = args.input?.id ?? ent.name + '01'
       }
       else {

package/src/transform/operation.ts

@@ -137,7 +137,14 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
     mop = {
       name: opname,
       points: opdesc.paths.map((p: PathDesc) => {
-        const parts = applyRename(p)
+        // Renames already applied by entity.ts resolvePathList — re-applying
+        // here corrupted paths for any spec where rename map maps an old
+        // name to a value that another rename maps to a different new name
+        // (e.g. gitlab `/groups/{id}/badges/{badge_id}` with rename
+        // `{badge_id: 'id', id: 'project_id'}` ended up as
+        // `/groups/{project_id}/badges/{project_id}` — the second pass
+        // rewrote the freshly-renamed `{id}` into `{project_id}` again).
+        const parts = p.parts
 
         const mtarget: ModelTarget = {
           orig: p.orig,
@@ -162,12 +169,6 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
 }
 
 
-function applyRename(pathdesc: PathDesc): string[] {
-  const prn: Record<string, string> = pathdesc.rename?.param ?? {}
-  return pathdesc.parts.map(p => '{' === p[0] ? (prn[p.substring(1, p.length - 1)] ?? p) : p)
-}
-
-
 
 
 export {

package/src/transform/select.ts

@@ -78,7 +78,7 @@ function resolveSelect(
   const gpath = gent.path[mtarget.orig]
 
   if (gpath.action) {
-    const actname = Object.keys(gpath.action)[0]
+    const actname = Object.keys(gpath.action).sort()[0]
 
     if (null != actname) {
       select.$action = actname

package/src/utility.ts

@@ -24,6 +24,11 @@ import type {
 
 const KONSOLE_LOG = console['log']
 
+// Sorted iteration helpers — ensures deterministic key order matching Go.
+const sortedKeys = (obj: any): string[] => Object.keys(obj ?? {}).sort()
+const sortedEntries = (obj: any): [string, any][] =>
+  Object.entries(obj ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+
 // Pre-compiled regex patterns for formatJsonSrc to avoid recompilation per call.
 const RE_JSON_KEY = /"([a-zA-Z_][a-zA-Z_0-9]*)": /g
 const RE_JSON_TRAILING_BRACE = /},/g
@@ -1163,5 +1168,7 @@ export {
   warnOnError,
   relativizePath,
   getModelPath,
+  sortedKeys,
+  sortedEntries,
 
 }