@voxgig/apidef 2.0.2 → 2.1.0

package/src/guide.ts

@@ -3,38 +3,65 @@ import Path from 'node:path'
 
 import { File, Content, each } from 'jostraca'
 
+import { merge } from '@voxgig/struct'
+
 
 import { heuristic01 } from './guide/heuristic01'
 
+import {
+  getdlog,
+} from './utility'
+
+
+// Log non-fatal wierdness.
+const dlog = getdlog('apidef', __filename)
 
 async function resolveGuide(ctx: any) {
-  let guide: Record<string, any> = ctx.model.main.api.guide
+  let baseguide: Record<string, any> = {}
+  let override: Record<string, any> = ctx.model.main.api.guide
 
   if ('heuristic01' === ctx.opts.strategy) {
-    guide = await heuristic01(ctx)
+    baseguide = await heuristic01(ctx)
   }
   else {
     throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
   }
 
+  // Override generated base guide with custom hints 
+  let guide = merge([{}, baseguide, override])
+
+  // TODO: this is a hack!!!
+  // Instead, update @voxgig/model, so that builders can request a reload of the entire
+  // model. This allows builders to modify the model for later buidlers
+  // during a single generation pass.
+
+
   guide = cleanGuide(guide)
 
-  ctx.model.main.api.guide = guide
+
+  // TODO: FIX: sdk.jsonic should have final version of guide
+  if (ctx.model.main?.api) {
+    ctx.model.main.api.guide = guide
+  }
+  else {
+    dlog('missing', 'ctx.model.main.api')
+  }
 
   const guideFile =
     Path.join(ctx.opts.folder,
-      (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'guide.jsonic')
+      (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'base-guide.jsonic')
 
   const guideBlocks = [
     '# Guide',
     '',
     'main: api: guide: { ',
-    '',
+
   ]
 
 
-  guideBlocks.push(...each(guide.entity, (entity, entityname) => {
-    guideBlocks.push(`\nentity: ${entityname}: {`)
+  guideBlocks.push(...each(baseguide.entity, (entity, entityname) => {
+    guideBlocks.push(`
+entity: ${entityname}: {`)
 
     each(entity.path, (path, pathname) => {
       guideBlocks.push(`  path: '${pathname}': op: {`)
@@ -58,8 +85,8 @@ async function resolveGuide(ctx: any) {
   const guideSrc = guideBlocks.join('\n')
 
   return () => {
-    File({ name: Path.basename(guideFile) }, () => Content(guideSrc))
-
+    // Save base guide for reference
+    File({ name: '../def/' + Path.basename(guideFile) }, () => Content(guideSrc))
   }
 }
 
@@ -70,7 +97,19 @@ function cleanGuide(guide: Record<string, any>): Record<string, any> {
     entity: {}
   }
 
+  const exclude_entity = guide.exclude?.entity?.split(',') || []
+  const include_entity = guide.include?.entity?.split(',') || []
+
   each(guide.entity, (entity: any, name: string) => {
+    if (exclude_entity.includes(name)) {
+      return
+    }
+    if (exclude_entity.includes('*')) {
+      if (!include_entity.includes(name)) {
+        return
+      }
+    }
+
     let ent: any = clean.entity[name] = clean.entity[name] = { name, path: {} }
 
     each(entity.path, (path: any, pathname: string) => {

package/src/parse.ts

@@ -2,6 +2,10 @@
 
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
 
+import { each, snakify } from 'jostraca'
+
+
+import { depluralize } from './utility'
 
 
 // Parse an API definition source into a JSON sructure.
@@ -16,12 +20,51 @@ async function parse(kind: string, source: any, meta?: any) {
 
 
 async function parseOpenAPI(source: any, meta?: any) {
-  const config = await createConfig(meta?.config || {})
-  let bundle
+  const base = meta?.config || {}
+  const config: any = await createConfig(base)
 
-  bundle = await bundleFromString({
+  // First pass: parse without dereferencing to preserve $refs
+  const bundleWithRefs = await bundleFromString({
     source,
     config,
+    dereference: false,
+  })
+
+  // Walk the tree and add x-ref properties
+  const seen = new WeakSet()
+  let refCount = 0
+
+  function addXRefs(obj: any, path: string = '') {
+    if (!obj || typeof obj !== 'object' || seen.has(obj)) return
+    seen.add(obj)
+
+    if (Array.isArray(obj)) {
+      obj.forEach((item, index) => addXRefs(item, `${path}[${index}]`))
+    } else {
+      // Check for $ref property
+      if (obj.$ref && typeof obj.$ref === 'string') {
+        obj['x-ref'] = obj.$ref
+        refCount++
+      }
+
+      // Recursively process all properties
+      for (const [key, value] of Object.entries(obj)) {
+        if (value && typeof value === 'object') {
+          addXRefs(value, path ? `${path}.${key}` : key)
+        }
+      }
+    }
+  }
+
+  addXRefs(bundleWithRefs.bundle.parsed)
+
+  // Serialize back to string with x-refs preserved
+  const sourceWithXRefs = JSON.stringify(bundleWithRefs.bundle.parsed)
+
+  // Second pass: parse with dereferencing
+  const bundle = await bundleFromString({
+    source: sourceWithXRefs,
+    config,
     dereference: true,
   })
 
@@ -31,6 +74,65 @@ async function parseOpenAPI(source: any, meta?: any) {
 }
 
 
+
+
+
+
+
+// Make consistent changes to support semantic entities.
+function rewrite(def: any) {
+  const paths = def.paths
+  each(paths, (path) => {
+    each(path.parameters, (param: any) => {
+
+      let new_param = param.name
+      let new_path = path.key$
+
+      // Rename param if nane is "id", and not the final param.
+      // Rewrite /foo/{id}/bar as /foo/{foo_id}/bar.
+      // Avoids ambiguity with bar id.
+      if (param.name.match(/^id$/i)) {
+        let m = path.key$.match(/\/([^\/]+)\/{id\}\/[^\/]/)
+
+        if (m) {
+          const parent = depluralize(snakify(m[1]))
+          new_param = `${parent}_id`
+          new_path = path.key$.replace('{id}', '{' + new_param + '}')
+        }
+      }
+      else {
+        new_param = depluralize(snakify(param.name))
+        new_path = path.key$.replace('{' + param.name + '}', '{' + new_param + '}')
+      }
+
+      let pathdef = paths[path.key$]
+      delete paths[path.key$]
+
+      paths[new_path] = pathdef
+      path.key$ = new_path
+
+      param.name = new_param
+    })
+  })
+
+
+  sortkeys(def, 'paths')
+  sortkeys(def, 'components')
+
+  return def
+}
+
+
+function sortkeys(obj: any, prop: string) {
+  const sorted: any = {}
+  const sorted_keys = Object.keys(obj[prop]).sort()
+  for (let sk of sorted_keys) {
+    sorted[sk] = obj[prop][sk]
+  }
+  obj[prop] = sorted
+}
+
 export {
-  parse
+  parse,
+  rewrite,
 }

package/src/transform/clean.ts

@@ -0,0 +1,28 @@
+
+import { each, getx } from 'jostraca'
+
+import type { TransformResult } from '../transform'
+
+import { walk } from '@voxgig/struct'
+
+
+
+const cleanTransform = async function(
+  ctx: any,
+): Promise<TransformResult> {
+  const { apimodel } = ctx
+
+  walk(apimodel, (k: any, v: any) => {
+    if ('string' === typeof k && k.includes('$')) {
+      return undefined
+    }
+    return v
+  })
+
+  return { ok: true, msg: 'clean' }
+}
+
+
+export {
+  cleanTransform
+}

package/src/transform/field.ts

@@ -69,7 +69,8 @@ function fieldbuild(
       field.name = property.key$
       fixName(field, field.name)
 
-      field.type = property.type
+      // field.type = property.type
+      resolveFieldType(entityModel, field, property)
       fixName(field, field.type, 'type')
 
       field.short = property.description
@@ -93,6 +94,31 @@ function fieldbuild(
 }
 
 
+// Resovles a heuristic "primary" type which subsumes the more detailed type.
+// The primary type is only: string, number, boolean, null, object, array
+function resolveFieldType(entity: any, field: any, property: any) {
+  const ptt = typeof property.type
+
+  if ('string' === ptt) {
+    field.type = property.type
+  }
+  else if (Array.isArray(property.type)) {
+    field.type =
+      (property.type.filter((t: string) => 'null' != t).sort()[0]) ||
+      property.type[0] ||
+      'string'
+    field.typelist = property.type
+  }
+  else if ('undefined' === ptt && null != property.enum) {
+    field.type = 'string'
+    field.enum = property.enum
+  }
+  else {
+    throw new Error(
+      `APIDEF: Unsupported property type: ${property.type} (${entity.name}.${field.name})`)
+  }
+}
+
 
 export {
   fieldTransform

package/src/transform/operation.ts

@@ -1,11 +1,14 @@
 
 
-import { each, getx } from 'jostraca'
+import { each, getx, snakify } from 'jostraca'
+
+import { transform, setprop, getprop } from '@voxgig/struct'
 
 import type { TransformResult } from '../transform'
 
 import { fixName, OPKIND } from '../transform'
 
+import { depluralize } from '../utility'
 
 
 const operationTransform = async function(
@@ -31,7 +34,6 @@ const operationTransform = async function(
     entity: any,
     model: any
   ) => {
-
     const paramSpec: any = paramMap[paramDef.name] = {
       required: paramDef.required
     }
@@ -143,12 +145,13 @@ const operationTransform = async function(
     content: any,
     schema: any,
     propkeys: any
-  ) => {
+  ): [any, string] => {
     let why = 'default'
     let transform: any = '`body`'
+    const properties = schema?.properties
 
-    if (null == content || null == schema || null == propkeys) {
-      return transform
+    if (null == content || null == schema || null == propkeys || null == properties) {
+      return [transform, why]
     }
 
     const opname = op.key$
@@ -162,9 +165,12 @@ const operationTransform = async function(
         else {
           // Use sub property that is an array
           for (let pk of propkeys) {
-            if ('array' === schema.properties[pk]?.type) {
+            if ('array' === properties[pk]?.type) {
               why = 'list-single-array:' + pk
               transform = '`body.' + pk + '`'
+
+              // TODO: if each item has prop === name of entity, use that, get with $EACH
+
               break
             }
           }
@@ -173,14 +179,14 @@ const operationTransform = async function(
     }
     else {
       if ('object' === schema.type) {
-        if (null == schema.properties.id) {
+        if (null == properties.id) {
           if (1 === propkeys.length) {
             why = 'map-single-prop:' + propkeys[0]
             transform = '`body.' + propkeys[0] + '`'
           }
           else {
             for (let pk of propkeys) {
-              if (schema.properties[pk].properties?.id) {
+              if (properties[pk]?.properties?.id) {
                 why = 'map-sub-prop:' + pk
                 transform = '`body.' + pk + '`'
                 break
@@ -205,12 +211,13 @@ const operationTransform = async function(
     content: any,
     schema: any,
     propkeys: any
-  ) => {
-    let transform: any = '`data`'
+  ): [any, string] => {
+    let transform: any = '`reqdata`'
     let why = 'default'
+    const properties = schema?.properties
 
-    if (null == content || null == schema || null == propkeys) {
-      return transform
+    if (null == content || null == schema || null == propkeys || null == properties) {
+      return [transform, why]
     }
 
     const opname = op.key$
@@ -219,14 +226,14 @@ const operationTransform = async function(
       if ('array' !== schema.type) {
         if (1 === propkeys.length) {
           why = 'list-single-prop:' + propkeys[0]
-          transform = { [propkeys[0]]: '`data`' }
+          transform = { [propkeys[0]]: '`reqdata`' }
         }
         else {
           // Use sub property that is an array
           for (let pk of propkeys) {
-            if ('array' === schema.properties[pk]?.type) {
+            if ('array' === properties[pk]?.type) {
               why = 'list-single-array:' + pk
-              transform = { [pk]: '`data`' }
+              transform = { [pk]: '`reqdata`' }
               break
             }
           }
@@ -235,16 +242,16 @@ const operationTransform = async function(
     }
     else {
       if ('object' === schema.type) {
-        if (null == schema.properties.id) {
+        if (null == properties.id) {
           if (1 === propkeys.length) {
             why = 'map-single-prop:' + propkeys[0]
-            transform = { [propkeys[0]]: '`data`' }
+            transform = { [propkeys[0]]: '`reqdata`' }
           }
           else {
             for (let pk of propkeys) {
-              if (schema.properties[pk].properties?.id) {
+              if (properties[pk]?.properties?.id) {
                 why = 'map-sub-prop:' + pk
-                transform = { [pk]: '`data`' }
+                transform = { [pk]: '`reqdata`' }
                 break
               }
             }
@@ -269,8 +276,10 @@ const operationTransform = async function(
       const [reqform, reqform_COMMENT] =
         resolveTransform(entityModel, op, kind, 'reqform', pathdef)
 
-      const opModel = entityModel.op[opname] = {
+      const opModel = {
         path: path.key$,
+        pathalt: ([] as any[]),
+
         method,
         kind,
         param: {},
@@ -289,24 +298,64 @@ const operationTransform = async function(
 
       fixName(opModel, op.key$)
 
+      let params: any[] = []
+
       // Params are in the path
       if (0 < path.params$.length) {
-        let params = getx(pathdef[method], 'parameters?in=path') || []
-        if (Array.isArray(params)) {
-          params.reduce((a: any, p: any) =>
-          (paramBuilder(a, p, opModel, entityModel,
-            pathdef, op, path, entity, model), a), opModel.param)
-        }
+        let sharedparams = getx(pathdef, 'parameters?in=path') || []
+        params = sharedparams.concat(
+          getx(pathdef[method], 'parameters?in=path') || []
+        )
+
+        // if (Array.isArray(params)) {
+        params.reduce((a: any, p: any) =>
+        (paramBuilder(a, p, opModel, entityModel,
+          pathdef, op, path, entity, model), a), opModel.param)
+        //}
       }
 
       // Queries are after the ?
-      let queries = getx(pathdef[op.val$], 'parameters?in!=path') || []
-      if (Array.isArray(queries)) {
-        queries.reduce((a: any, p: any) =>
-        (queryBuilder(a, p, opModel, entityModel,
-          pathdef, op, path, entity, model), a), opModel.query)
+      let sharedqueries = getx(pathdef, 'parameters?in!=path') || []
+      let queries = sharedqueries.concat(getx(pathdef[method], 'parameters?in!=path') || [])
+      queries.reduce((a: any, p: any) =>
+      (queryBuilder(a, p, opModel, entityModel,
+        pathdef, op, path, entity, model), a), opModel.query)
+
+      let pathalt: any[] = []
+      const pathselector = makePathSelector(path.key$) // , params)
+      let before = false
+
+      if (null != entityModel.op[opname]) {
+        pathalt = entityModel.op[opname].pathalt
+
+        // Ordering for pathalts: most to least paramrs, then alphanumberic
+        for (let i = 0; i < pathalt.length; i++) {
+          let current = pathalt[i]
+          before =
+            pathselector.pn$ > current.pn$ ||
+            (pathselector.pn$ === current.pn$ &&
+              pathselector.path <= current.path)
+
+          if (before) {
+            pathalt = [
+              ...pathalt.slice(0, i),
+              pathselector,
+              ...pathalt.slice(i),
+            ]
+            break
+          }
+        }
+      }
+
+      if (!before) {
+        pathalt.push(pathselector)
       }
 
+      opModel.path = pathalt[pathalt.length - 1].path
+      opModel.pathalt = pathalt
+
+      entityModel.op[opname] = opModel
+
       return opModel
     },
 
@@ -333,6 +382,22 @@ const operationTransform = async function(
 
   }
 
+  /*
+    console.dir(
+      transform({ guide }, {
+        entity: {
+          '`$PACK`': ['guide.entity', {
+            '`$KEY`': 'name',
+            op: {
+              // load: ['`$IF`', ['`$SELECT`',{path:{'`$ANY`':{op:{load:'`$EXISTS`'}}}}], {
+              load: ['`$IF`', 'path.*.op.load', {
+                path: () => 'foo'
+              }]
+            }
+          }]
+        }
+      }), { depth: null })
+  */
 
   each(guide.entity, (guideEntity: any) => {
     let opcount = 0
@@ -348,6 +413,8 @@ const operationTransform = async function(
           opcount++
         }
       })
+
+
     })
 
     msg += guideEntity.name + '=' + opcount + ' '
@@ -357,6 +424,26 @@ const operationTransform = async function(
 }
 
 
+function makePathSelector(path: string) { // , params: any[]) {
+  let out: any = { path }
+
+  let pn$ = 0
+  for (const m of path.matchAll(/\/[^\/]+\/{([^}]+)\}/g)) {
+    const paramName = depluralize(snakify(m[1]))
+    out[paramName] = true
+    pn$++
+  }
+  out.pn$ = pn$
+
+  // for (let p of params) {
+  //   setprop(out, p.name, getprop(out, p.name, false))
+  //   console.log('SP', p.name, out[p.name])
+  // }
+
+  return out
+}
+
+
 export {
   operationTransform
 }

package/src/transform.ts

@@ -79,6 +79,7 @@ const GuideShape = Gubu({
 type Guide = ReturnType<typeof GuideShape>
 
 
+/*
 async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
   const { log, model: { main: { api: { guide } } } } = ctx
 
@@ -89,27 +90,27 @@ async function resolveTransforms(ctx: TransformCtx): Promise<TransformSpec> {
   // TODO: parameterize
   const defkind = 'openapi'
   const transformNames = guide.control.transform[defkind].order
-    .split(/\s*,\s*/)
+    .split(/\s*,\s* /)
     .map((t: string) => t.trim())
-    .filter((t: string) => '' != t)
+  .filter((t: string) => '' != t)
 
-  log.info({
-    point: 'transform', note: 'order: ' + transformNames.join(';'),
-    order: transformNames
-  })
+log.info({
+  point: 'transform', note: 'order: ' + transformNames.join(';'),
+  order: transformNames
+})
 
-  try {
-    for (const tn of transformNames) {
-      log.debug({ what: 'transform', transform: tn, note: tn })
-      const transform = await resolveTransform(tn, ctx)
-      tspec.transform.push(transform)
-    }
-  }
-  catch (err: any) {
-    throw err
+try {
+  for (const tn of transformNames) {
+    log.debug({ what: 'transform', transform: tn, note: tn })
+    const transform = await resolveTransform(tn, ctx)
+    tspec.transform.push(transform)
   }
+}
+catch (err: any) {
+  throw err
+}
 
-  return tspec
+return tspec
 }
 
 
@@ -195,13 +196,19 @@ async function processTransforms(
 
   return pres
 }
+*/
 
 
 
 function fixName(base: any, name: string, prop = 'name') {
-  base[prop.toLowerCase()] = name.toLowerCase()
-  base[camelify(prop)] = camelify(name)
-  base[prop.toUpperCase()] = name.toUpperCase()
+  if (null != base && 'object' === typeof base && 'string' === typeof name) {
+    base[prop.toLowerCase()] = name.toLowerCase()
+    base[camelify(prop)] = camelify(name)
+    base[prop.toUpperCase()] = name.toUpperCase()
+  }
+  else {
+    // record to a "wierds" log
+  }
 }
 
 
@@ -221,6 +228,6 @@ export {
   fixName,
   OPKIND,
   GuideShape,
-  resolveTransforms,
-  processTransforms,
+  // resolveTransforms,
+  // processTransforms,
 }